[ { "path": ".bandit", "content": "# Exclude test directories and virtual environment from Bandit scans\n# B101 (assert_used) only appears in test code; excluding test dirs resolves it\n# For pyproject.toml config (used by pre-commit), see [tool.bandit] in pyproject.toml\n# NOTE: cli/ and scripts/ are NOT excluded - they contain operational code that should be scanned\n\nexclude_dirs:\n - ./tests\n - ./agents/a2a/test\n - ./metrics-service/tests\n - ./.venv\n" }, { "path": ".claudeignore", "content": "cat .claudeignore\n```\n\nShould look like this:\n```\n# Dependencies\n**/node_modules/\nnode_modules/\n\n# Python\n**/.venv/\n**/__pycache__/\n*.pyc\n\n# Terraform\n**/.terraform/\n*.tfstate\n*.tfstate.*\n*.log\ntfplan\n\n# Test/Build outputs\nhtmlcov/\nsite/\n.coverage\n*.egg-info/\n\n# Caches\n.hypothesis/\n.ruff_cache/\n.pytest_cache/\n.scratchpad/\n.tmp/\n.oauth-tokens/\n\n# Log files\n*.log\n**/*.log\n" }, { "path": ".dockerignore", "content": "# Virtual environments\n**/.venv\n.venv/\n.venv\nregistry/.venv/\nservers/*/.venv/\nvenv/\n\n# Node.js\nnode_modules/\nfrontend/node_modules/\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# Python build artifacts \n__pycache__/\n*.pyc\n*.pyo\n*.pyd\n*.egg-info/\n**/*.egg-info/\ndist/\nbuild/\n\n# Logs\nlogs/\n*.log\noauth_cognito.log\nregistry.log\n*_tests*.log\nfull-test-run.log\n\n# Git\n.git/\n.gitignore\n\n# Documentation\ndocs/\n*.md\nREADME*\n\n# Tests \ntests/\ntest/\n**/tests/\n**/*test*\n\n# IDE/Editor files\n.vscode/\n.idea/\n*.swp\n*.swo\n\n# OS files\n.DS_Store\nThumbs.db\n\n# Temporary files\ntmp/\ntemp/\n*.tmp\n\n# Large binaries\n*.bin\n*.model\n*.pkl\n*.h5\n\n# Specific large directories\nmcp-atlassian/\nterraform/\nhtmlcov/\nsite/\ncli/*\n!cli/examples/\nsecurity_scans/\nagent_security_scans/\nskill_security_scans/\ncredentials-provider/\n.oauth-tokens/\n.scratchpad/\n# frontend/build/ - KEEP THIS, needed by registry service" }, { "path": ".env.example", "content": "# =============================================================================\n# MCP Gateway Registry - Environment Configuration Sample \n# =============================================================================\n# Copy this file to .env and update with your actual values\n# Never commit real credentials to version control\n\n# =============================================================================\n# REGISTRY CONFIGURATION\n# =============================================================================\n\n# Public URL where the MCP Gateway Registry is accessible\n# For custom HTTPS domain: https://mcpgateway.mycorp.com\nREGISTRY_URL=http://localhost\n\n# =============================================================================\n# REGISTRY CARD CONFIGURATION\n# =============================================================================\n\n# Registry identity and metadata for federation and discovery\n# These values populate the registry card shown in federated environments\n\n# Human-readable registry name (display name for your registry)\n# If not set, a random Docker-style name will be generated (e.g., \"brave-falcon-registry\")\n# Displayed in federated registry listings and UI headers\nREGISTRY_NAME=\"AI Gateway Registry\"\n\n# Organization that operates this registry\n# If not set, defaults to \"ACME Inc.\"\n# Used to identify the organization operating this registry instance\nREGISTRY_ORGANIZATION_NAME=\"ACME Inc.\"\n\n# Registry description for federation\n# Describes the purpose and scope of this registry\nREGISTRY_DESCRIPTION=\"Central registry for all your AI assets\"\n\n# Contact email for registry administrators\n# Leave empty if not publicly shared\nREGISTRY_CONTACT_EMAIL=\n\n# Documentation or support URL for this registry\n# Leave empty if not available\nREGISTRY_CONTACT_URL=\n\n# =============================================================================\n# Deployment Mode Configuration\n# =============================================================================\n\n# DEPLOYMENT_MODE controls how the registry integrates with the gateway/nginx\n# Options:\n# - with-gateway (default): Full integration with nginx reverse proxy\n# - Nginx config is regenerated when servers are registered/deleted\n# - Frontend shows gateway authentication instructions\n# - registry-only: Registry operates as catalog/discovery service only\n# - Nginx config is NOT updated on server changes\n# - Frontend shows direct connection mode (proxy_pass_url)\n# - Use when registry is separate from gateway infrastructure\n# Default: with-gateway (uncomment to change)\n# DEPLOYMENT_MODE=with-gateway\n\n# REGISTRY_MODE controls which features are enabled (informational - for UI feature flags)\n# This setting affects the /api/config response which the frontend can use\n# to show/hide navigation elements. Currently informational only - all APIs remain active.\n# Options:\n# - full (default): All features enabled (mcp_servers, agents, skills, federation)\n# - skills-only: Only skills feature flag enabled\n# - mcp-servers-only: Only MCP server feature flag enabled\n# - agents-only: Only A2A agent feature flag enabled\n# Note: with-gateway + skills-only is invalid and auto-corrects to registry-only + skills-only\n# Default: full (uncomment to change)\n# REGISTRY_MODE=full\n\n# Tab visibility overrides (AND-ed with REGISTRY_MODE feature flags)\n# These control which tabs are shown in the UI without affecting backend APIs.\n# REGISTRY_MODE is the master control — SHOW_*_TAB can only further restrict, never expand.\n# Formula: tab_visible = REGISTRY_MODE_enables_feature AND SHOW_*_TAB\n# All default to true (backward compatible). Set to false to hide a tab.\n# SHOW_SERVERS_TAB=true\n# SHOW_VIRTUAL_SERVERS_TAB=true\n# SHOW_SKILLS_TAB=true\n# SHOW_AGENTS_TAB=true\n\n# =============================================================================\n# AUTH SERVER CONFIGURATION\n# =============================================================================\n\n# Internal auth server URL (for Docker network communication)\nAUTH_SERVER_URL=http://auth-server:8888\n\n# External auth server URL (public-facing, for browser redirects)\n# For local development: http://localhost:8888\n# For custom HTTPS domain: https://mcpgateway.mycorp.com\nAUTH_SERVER_EXTERNAL_URL=http://localhost:8888\n\n# =============================================================================\n# NETWORK-TRUSTED API ACCESS (Enterprise Perimeter Security)\n# =============================================================================\n#\n# Allow Registry API access without full token validation.\n#\n# Use case: Enterprise deployments where the MCP Gateway Registry operates\n# within a secure network perimeter (VPC, private subnet, VPN, etc.)\n#\n# When enabled (true):\n# - Registry API endpoints (/api/*, /v0.1/*) use static token auth\n# instead of IdP-based JWT validation\n# - Clients must send: Authorization: Bearer \n# - Useful for trusted networks, CI/CD pipelines, and internal automation\n# - MCP Gateway server access STILL requires full IdP authentication\n#\n# When disabled (false, default):\n# - All endpoints require valid JWT tokens from the configured IdP\n# - Standard security posture\n#\n# Security considerations:\n# - Always set REGISTRY_API_TOKEN when enabling this feature\n# - Network-level security (firewalls, security groups) should be in place\n# - Audit logs will show \"network-trusted\" as auth method\n# - MCP server tool invocations remain fully protected by the IdP\n#\n# Default: false\nREGISTRY_STATIC_TOKEN_AUTH_ENABLED=false\n\n# Static API key for Registry API when REGISTRY_STATIC_TOKEN_AUTH_ENABLED=true.\n# Clients must send this value as: Authorization: Bearer \n# This single key gets full admin access (legacy mode). For per-key scoping\n# see REGISTRY_API_KEYS below.\n# Generate with: python3 -c \"import secrets; print(secrets.token_urlsafe(32))\"\nREGISTRY_API_TOKEN=\n\n# Multiple static API keys with per-key group assignments (Issue #779).\n# JSON map: name -> {key, groups}. Each key gets only the scopes that its\n# groups resolve to via group_mappings in scopes.yml / mcp_scope_default.\n#\n# When set, these keys are merged with REGISTRY_API_TOKEN (which becomes a\n# legacy entry with admin groups). On parse error the feature is disabled\n# entirely (fail-closed).\n#\n# Format (must be valid JSON on a single line, wrap in single quotes in shell):\n# REGISTRY_API_KEYS='{\"monitoring\":{\"key\":\"\",\"groups\":[\"mcp-readonly\"]},\"deploy\":{\"key\":\"\",\"groups\":[\"mcp-registry-admin\"]}}'\n#\n# Rules:\n# - name: ^[a-z0-9][a-z0-9_-]{0,63}$ (log-safe identifier)\n# - key: minimum 32 characters\n# - groups: non-empty list of group names from your scopes.yml group_mappings\n# - Names \"legacy\", \"network-user\", \"network-trusted\" are reserved\n# - Key values must be unique across entries\n#\n# Generate a key: python3 -c \"import secrets; print(secrets.token_urlsafe(32))\"\n#\n# See docs/registry-api-auth.md and docs/faq/registry-api-auth-faq.md for details.\nREGISTRY_API_KEYS=\n\n# =============================================================================\n# REGISTRATION WEBHOOK (Issue #742)\n# =============================================================================\n#\n# Fire an async POST to a URL when a server, agent, or skill is registered\n# (added) or deleted (removed). The call is fire-and-forget: failures are\n# logged but never propagated to the caller.\n#\n# REGISTRATION_WEBHOOK_URL: Full URL to POST to. Disabled when empty.\n# Only http:// and https:// schemes are accepted. A warning is logged\n# when HTTP (not HTTPS) is used.\n#\n# REGISTRATION_WEBHOOK_AUTH_HEADER: Name of the header used for auth.\n# Default: \"Authorization\". If set to \"Authorization\", the token is\n# auto-prefixed with \"Bearer \". For any other header (e.g. X-API-Key)\n# the token is sent as-is.\n#\n# REGISTRATION_WEBHOOK_AUTH_TOKEN: Auth token value. Leave empty for\n# unauthenticated webhooks.\n#\n# REGISTRATION_WEBHOOK_TIMEOUT_SECONDS: HTTP timeout in seconds.\n# Default: 10\n#\nREGISTRATION_WEBHOOK_URL=\nREGISTRATION_WEBHOOK_AUTH_HEADER=Authorization\nREGISTRATION_WEBHOOK_AUTH_TOKEN=\nREGISTRATION_WEBHOOK_TIMEOUT_SECONDS=10\n\n# =============================================================================\n# REGISTRATION GATE / ADMISSION CONTROL (Issue #809)\n# =============================================================================\n#\n# Call an external endpoint to approve or deny registration and update\n# requests BEFORE they are persisted. The gate is fail-closed: if the\n# endpoint is unreachable after retries, the registration is blocked.\n#\n# REGISTRATION_GATE_ENABLED: Master switch. Default: false\n#\n# REGISTRATION_GATE_URL: Full URL to POST to. Must be set when enabled.\n# Only http:// and https:// schemes are accepted. HTTPS is strongly\n# recommended for production.\n#\n# REGISTRATION_GATE_AUTH_TYPE: How to authenticate with the gate endpoint.\n# Options: none, api_key, bearer. Default: none\n#\n# REGISTRATION_GATE_AUTH_CREDENTIAL: Credential value for api_key or bearer.\n# For bearer: sent as \"Authorization: Bearer \".\n# For api_key: sent as \": \".\n#\n# REGISTRATION_GATE_AUTH_HEADER_NAME: Header name when auth_type=api_key.\n# Default: X-Api-Key\n#\n# REGISTRATION_GATE_TIMEOUT_SECONDS: HTTP timeout per attempt. Default: 5\n#\n# REGISTRATION_GATE_MAX_RETRIES: Number of retries after the first attempt.\n# Uses exponential backoff (0.5s, 1s, 2s, ...). Default: 2\n#\nREGISTRATION_GATE_ENABLED=false\nREGISTRATION_GATE_URL=\nREGISTRATION_GATE_AUTH_TYPE=none\nREGISTRATION_GATE_AUTH_CREDENTIAL=\nREGISTRATION_GATE_AUTH_HEADER_NAME=X-Api-Key\nREGISTRATION_GATE_TIMEOUT_SECONDS=5\nREGISTRATION_GATE_MAX_RETRIES=2\n\n# =============================================================================\n# FEDERATION STATIC TOKEN AUTH (Scoped Access for Peer Registries)\n# =============================================================================\n#\n# Allow peer registries to access federation and peer management endpoints\n# using a static Bearer token instead of OAuth2 JWT.\n#\n# IMPORTANT: This token only grants access to:\n# - /api/federation/* (federation export endpoints)\n# - /api/peers/* (peer management endpoints)\n# It does NOT grant access to other registry APIs.\n#\n# When enabled (true):\n# - Federation/peer endpoints accept: Authorization: Bearer \n# - Used for quick setup of peer-to-peer federation without OAuth2 infrastructure\n# - Audit logs will show \"federation-static\" as auth method\n#\n# When disabled (false, default):\n# - Federation endpoints require OAuth2 JWT with federation-service scope\n#\n# Default: false\nFEDERATION_STATIC_TOKEN_AUTH_ENABLED=false\n\n# Static token for federation API access.\n# Generate with: python3 -c \"import secrets; print(secrets.token_urlsafe(32))\"\nFEDERATION_STATIC_TOKEN=\n\n# Encryption key for storing federation tokens in MongoDB (required on importing registry).\n# When peer configs contain federation_token, it is encrypted before storage using this key.\n# Generate with: python3 -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"\nFEDERATION_ENCRYPTION_KEY=\n\n# =============================================================================\n# M2M DIRECT CLIENT REGISTRATION (Issue #851)\n# =============================================================================\n#\n# Enables the admin API at /api/iam/m2m-clients that lets operators register\n# M2M client_ids and their group mappings by writing directly to the\n# idp_m2m_clients MongoDB collection, WITHOUT requiring an IdP Admin API\n# token (e.g. OKTA_API_TOKEN). Useful when IdP Admin API access is gated.\n#\n# Records created via this API are tagged provider=\"manual\" and cannot be\n# modified or deleted by this API if they were written by IdP sync.\n#\n# Endpoints gated by this flag:\n# POST /api/iam/m2m-clients (admin)\n# GET /api/iam/m2m-clients (any authenticated user)\n# GET /api/iam/m2m-clients/{id} (any authenticated user)\n# PATCH /api/iam/m2m-clients/{id} (admin)\n# DELETE /api/iam/m2m-clients/{id} (admin)\n#\n# Default: true (feature is on; set to false to disable the router entirely)\nM2M_DIRECT_REGISTRATION_ENABLED=true\n\n# =============================================================================\n# AUTHENTICATION PROVIDER CONFIGURATION\n# =============================================================================\n# Choose authentication provider: 'cognito', 'keycloak', 'entra', 'okta', or 'auth0'\nAUTH_PROVIDER=keycloak\n\n# =============================================================================\n# KEYCLOAK CONFIGURATION (if AUTH_PROVIDER=keycloak)\n# =============================================================================\n\n# Keycloak server URL (internal URL for server-to-server communication)\n# DO NOT CHANGE: This should always be http://keycloak:8080 for Docker network communication\nKEYCLOAK_URL=http://keycloak:8080\n\n# Keycloak external URL (for browser redirects)\n# For local development: http://localhost:8080\n# For custom HTTPS domain: https://mcpgateway.mycorp.com\nKEYCLOAK_EXTERNAL_URL=http://localhost:8080\n\n# Keycloak admin URL (for setup scripts - internal access)\n# Typically http://localhost:8080 for local access to Keycloak admin\n# For custom HTTPS domain: https://mcpgateway.mycorp.com\nKEYCLOAK_ADMIN_URL=http://localhost:8080\n\n# Keycloak realm name\nKEYCLOAK_REALM=mcp-gateway\n\n# Keycloak admin credentials (for initial setup)\nKEYCLOAK_ADMIN=admin\nKEYCLOAK_ADMIN_PASSWORD=your-secure-keycloak-admin-password\n\n# Keycloak database password\nKEYCLOAK_DB_PASSWORD=your-secure-db-password\n\n# Keycloak client credentials for web authentication\n# These are auto-generated when you run keycloak/setup/init-keycloak.sh\n# To retrieve: Check script output or Keycloak Admin Console → Clients → Credentials tab\nKEYCLOAK_CLIENT_ID=mcp-gateway-web\nKEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret-here\n\n# Keycloak M2M client credentials for machine-to-machine authentication\n# These are auto-generated when you run keycloak/setup/init-keycloak.sh\n# To retrieve: Check script output or Keycloak Admin Console → Clients → Credentials tab\nKEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_M2M_CLIENT_SECRET=your-keycloak-m2m-secret-here\n\n# Enable Keycloak in OAuth2 providers\nKEYCLOAK_ENABLED=true\n\n# Initial admin and test user passwords for Keycloak setup\nINITIAL_ADMIN_PASSWORD=your-secure-keycloak-admin-password\nINITIAL_USER_PASSWORD=your-secure-keycloak-user-password\n\n# =============================================================================\n# MCPGW (MCP GATEWAY SERVER) CONFIGURATION\n# =============================================================================\n# These settings configure the MCPGW MCP server that provides tool access\n# to the registry. Required only when running the MCPGW server component.\n\n# **WARNING**: Before enabling OIDC, review the security gaps documented in\n# GitHub issue #895. The M2M token flow does NOT propagate user identity to\n# the registry, which bypasses per-user authorization and audit logging.\n# Do NOT set OIDC_ENABLED=true in any environment until issue #895 is resolved.\n\n# Enable OIDC/OAuth2 authentication for the MCPGW server\n# When true, MCPGW uses Keycloak OAuthProxy for client authentication\n# When false (default), MCPGW uses bearer-token passthrough\n# OIDC_ENABLED=false\n\n# OIDC client credentials (used when OIDC_ENABLED=true)\n# These should match a Keycloak client configured for the MCPGW server\n# OIDC_CLIENT_ID=mcp-gateway-web\n# OIDC_CLIENT_SECRET=your-oidc-client-secret-here\n\n# Keycloak internal URL for server-to-server OIDC communication\n# Used by MCPGW to reach Keycloak within the Docker network\n# KEYCLOAK_INTERNAL_URL=http://keycloak:8080\n\n# M2M (machine-to-machine) client credentials for MCPGW to call registry APIs\n# MCPGW uses these to obtain tokens for authenticated registry API calls\n# M2M_CLIENT_ID=mcp-gateway-m2m\n# M2M_CLIENT_SECRET=your-m2m-client-secret-here\n\n# Base URL where the MCPGW server is reachable (for OAuth redirect URIs)\n# MCPGW_BASE_URL=http://localhost:18003\n\n# Bind host for the MCPGW server\n# Use 127.0.0.1 for local-only access (default), 0.0.0.0 for containers\n# HOST=127.0.0.1\n\n# =============================================================================\n# GATEWAY HOST CONFIGURATION\n# =============================================================================\n\n# Optional: Additional server names for nginx reverse proxy gateway access\n# Use this to add custom domain names, public IPs, or private IPs to the nginx server_name directive\n# Supports multiple names separated by spaces\n#\n# Examples:\n# - Custom domain: mcpgateway.example.com\n# - Public IP: 54.123.45.67\n# - Private IP: 10.0.1.42\n# - Multiple: mcpgateway.example.com 54.123.45.67\n# - Custom domain: mcpgateway.ddns.net\n#\n# Default: Empty (will auto-detect private IP if available)\n# WARNING: HTTP access is not recommended for production. Use HTTPS with valid SSL certificates.\nGATEWAY_ADDITIONAL_SERVER_NAMES=\n\n# =============================================================================\n# AMAZON COGNITO OAUTH2 CONFIGURATION (if AUTH_PROVIDER=cognito)\n# =============================================================================\n\n# AWS Configuration\nAWS_REGION=us-east-1\n\n# Amazon Cognito User Pool ID\n# Format: {region}_{random_string}\nCOGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX\n\n# Cognito App Client ID\n# Get this from Amazon Cognito console > User Pools > App Integration > App clients\nCOGNITO_CLIENT_ID=your_cognito_client_id_here\n\n# Cognito App Client Secret\n# Get this from Amazon Cognito console > User Pools > App Integration > App clients\nCOGNITO_CLIENT_SECRET=your_cognito_client_secret_here\n\n# Enable Cognito in OAuth2 providers\nCOGNITO_ENABLED=false\n\n# =============================================================================\n# MICROSOFT ENTRA ID CONFIGURATION (if AUTH_PROVIDER=entra)\n# =============================================================================\n\n# Azure AD Tenant ID (Directory/tenant ID from Azure Portal)\n# Format: GUID (e.g., 12345678-1234-1234-1234-123456789012)\n# Get from: Azure Portal → Azure Active Directory → Overview → Tenant ID\nENTRA_TENANT_ID=your-tenant-id-here\n\n# Entra ID Application (client) ID\n# Format: GUID (e.g., 87654321-4321-4321-4321-210987654321)\n# Get from: Azure Portal → App registrations → Your App → Application (client) ID\nENTRA_CLIENT_ID=your-client-id-here\n\n# Entra ID Client Secret (Application secret value)\n# Get from: Azure Portal → App registrations → Your App → Certificates & secrets\n# NOTE: Copy the secret VALUE immediately after creation (not the secret ID)\nENTRA_CLIENT_SECRET=your-client-secret-here\n\n# Enable Entra ID in OAuth2 providers (set to true when using Entra ID)\nENTRA_ENABLED=false\n\n# Entra ID Login Base URL (optional - defaults to https://login.microsoftonline.com)\n# Change this only if using a sovereign cloud (e.g., Azure Government, Azure China)\n# Examples:\n# - Azure Public Cloud (default): https://login.microsoftonline.com\n# - Azure Government: https://login.microsoftonline.us\n# - Azure China: https://login.chinacloudapi.cn\n# - Azure Germany: https://login.microsoftonline.de\n# ENTRA_LOGIN_BASE_URL=https://login.microsoftonline.com\n\n# Azure AD Group Object IDs for authorization (configured in scopes.yml)\n# Admin Group Example\nENTRA_GROUP_ADMIN_ID=your-admin-group-object-id-here\n# Users Group Example\nENTRA_GROUP_USERS_ID=your-users-group-object-id-here\n\n# IdP Group Filtering (optional, applies to all identity providers)\n# Comma-separated list of prefixes. Only groups whose name starts with\n# any of these prefixes are shown in IAM > Groups page.\n# For Entra ID, uses Microsoft Graph $filter for server-side filtering.\n# For Keycloak, Okta, Auth0, filtering is applied client-side.\n# Leave empty to show all groups (default).\n# Examples:\n# IDP_GROUP_FILTER_PREFIX=mcp-\n# IDP_GROUP_FILTER_PREFIX=mcp-,registry-,ai-\nIDP_GROUP_FILTER_PREFIX=\n\n# =============================================================================\n# OKTA CONFIGURATION (if AUTH_PROVIDER=okta)\n# =============================================================================\n\n# Okta org domain (without https://)\n# Format: dev-123456.okta.com\n# Get from: Okta Admin Console URL (remove -admin suffix)\nOKTA_DOMAIN=dev-123456.okta.com\n\n# Okta OAuth2 Application Client ID\n# Get from: Okta Admin Console → Applications → Your App → General tab\nOKTA_CLIENT_ID=your_okta_client_id_here\n\n# Okta OAuth2 Application Client Secret\n# Get from: Okta Admin Console → Applications → Your App → General tab\nOKTA_CLIENT_SECRET=your_okta_client_secret_here\n\n# Optional: Separate M2M client credentials (defaults to above if not set)\n# OKTA_M2M_CLIENT_ID=your_okta_m2m_client_id_here\n# OKTA_M2M_CLIENT_SECRET=your_okta_m2m_client_secret_here\n\n# Optional: Okta Admin API token for IAM operations (user/group management)\n# Get from: Okta Admin Console → Security → API → Tokens\n# OKTA_API_TOKEN=your_okta_api_token_here\n\n# Optional: Okta Custom Authorization Server ID (for M2M tokens)\n# Get from: Okta Admin Console → Security → API → Authorization Servers\n# If using custom authorization server for M2M, specify the ID here (e.g., aus1108sx6pwGzb8T698)\n# If not set, uses the default Org Authorization Server\n# OKTA_AUTH_SERVER_ID=your_auth_server_id_here\n\n# =============================================================================\n# GITHUB OAUTH2 CONFIGURATION\n# =============================================================================\n\n# GitHub OAuth App Client ID\n# Get this from GitHub > Settings > Developer settings > OAuth Apps\nGITHUB_CLIENT_ID=your_github_client_id_here\n\n# GitHub OAuth App Client Secret\nGITHUB_CLIENT_SECRET=your_github_client_secret_here\n\n# Enable GitHub in OAuth2 providers\nGITHUB_ENABLED=false\n\n# =============================================================================\n# GITHUB PRIVATE REPOSITORY ACCESS (SKILL.md fetching)\n# =============================================================================\n# Enable authenticated access to SKILL.md files in private GitHub repositories.\n# Two options: Personal Access Token (simple) or GitHub App (enterprise).\n# If both are configured, GitHub App takes priority.\n\n# Option 1: Personal Access Token\n# Generate at https://github.com/settings/tokens with 'repo' scope\n# Fine-grained PATs: scope to 'contents: read' on specific repos\n# GITHUB_PAT=ghp_your_token_here\n\n# Option 2: GitHub App (recommended for organizations)\n# Create at https://github.com/settings/apps\n# Required permissions: Contents (read-only)\n# GITHUB_APP_ID=123456\n# GITHUB_APP_INSTALLATION_ID=78901234\n# GITHUB_APP_PRIVATE_KEY=\"-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\"\n\n# Extra GitHub hosts for enterprise instances (comma-separated)\n# Auth headers are sent ONLY to github.com, raw.githubusercontent.com, and hosts listed here\n# GITHUB_EXTRA_HOSTS=github.mycompany.com,raw.github.mycompany.com\n\n# GitHub API base URL (default: https://api.github.com)\n# For GitHub Enterprise Server, use: https://github.mycompany.com/api/v3\n# GITHUB_API_BASE_URL=https://api.github.com\n\n# =============================================================================\n# GOOGLE OAUTH2 CONFIGURATION\n# =============================================================================\n\n# Google OAuth2 Client ID\n# Get this from Google Cloud Console > APIs & Services > Credentials\nGOOGLE_CLIENT_ID=your_google_client_id_here\n\n# Google OAuth2 Client Secret\nGOOGLE_CLIENT_SECRET=your_google_client_secret_here\n\n# Enable Google in OAuth2 providers\nGOOGLE_ENABLED=false\n\n# =============================================================================\n# AUTH0 OAUTH2 CONFIGURATION\n# =============================================================================\n\n# Auth0 Domain (your Auth0 tenant domain)\n# Get this from Auth0 Dashboard > Applications > Your App > Settings\n# Example: your-tenant.auth0.com\nAUTH0_DOMAIN=your-tenant.auth0.com\n\n# Auth0 Client ID\nAUTH0_CLIENT_ID=your_auth0_client_id_here\n\n# Auth0 Client Secret\nAUTH0_CLIENT_SECRET=your_auth0_client_secret_here\n\n# Auth0 API Audience (required for M2M token validation)\n# This is the API Identifier from Auth0 Dashboard > APIs\n# Use the Management API audience: https://.auth0.com/api/v2/\n# Or a custom API audience you created in Auth0\n# AUTH0_AUDIENCE=https://dev-example.us.auth0.com/api/v2/\n\n# Auth0 Groups Claim (custom claim for group memberships)\n# Auth0 requires a custom Action/Rule to add groups to tokens.\n# The claim must be a namespaced URI to avoid conflicts.\n# Default: https://mcp-gateway/groups\nAUTH0_GROUPS_CLAIM=https://mcp-gateway/groups\n\n# Enable Auth0 in OAuth2 providers\nAUTH0_ENABLED=false\n\n# Auth0 M2M Client ID (REQUIRED for IAM Management - user/role administration)\n# Create an M2M application in Auth0 with Auth0 Management API permissions\n# See docs/auth0.md for setup instructions\n# AUTH0_M2M_CLIENT_ID=your_m2m_client_id\n\n# Auth0 M2M Client Secret (REQUIRED for IAM Management)\n# AUTH0_M2M_CLIENT_SECRET=your_m2m_client_secret\n\n# Auth0 Management API Token (alternative to M2M credentials)\n# You can use a static Management API token instead of M2M client credentials\n# Generate in Auth0 Dashboard > Applications > APIs > Auth0 Management API > API Explorer\n# WARNING: Static tokens expire after 24 hours - M2M credentials recommended for production\n# AUTH0_MANAGEMENT_API_TOKEN=your_management_api_token\n\n# =============================================================================\n# APPLICATION SECURITY\n# =============================================================================\n\n# CRITICAL: CHANGE THIS SECRET KEY IMMEDIATELY!\n# This is used for:\n# - JWT token signing and session security\n# - Backend MCP server credential encryption (Bearer tokens, API keys)\n# Generate a strong, random 64-character string in production\n# WARNING: Using the default value is a security risk!\n# WARNING: Changing this key will invalidate all encrypted credentials!\nSECRET_KEY=CHANGE-THIS-IMMEDIATELY-use-a-strong-random-key-in-production\n\n# =============================================================================\n# SESSION COOKIE CONFIGURATION\n# =============================================================================\n\n# Session cookie secure flag (HTTPS-only transmission)\n# IMPORTANT: Set based on your environment:\n# - Local development (localhost via HTTP): Set to false\n# - Production with HTTPS: Set to true\n#\n# If set to true, cookies will ONLY be sent over HTTPS connections.\n# Setting this to true on localhost (HTTP) will cause login to fail!\n#\n# Default: false (safe for local development)\n# Production: MUST be true\nSESSION_COOKIE_SECURE=false\n\n# Session cookie domain (for cross-subdomain authentication)\n# Leave unset or empty for single-domain deployments (RECOMMENDED for most cases)\n# Set to domain with leading dot for cross-subdomain sharing\n#\n# Examples:\n# Single domain (mcpgateway.ddns.net): Leave unset or set to empty string\n# SESSION_COOKIE_DOMAIN=\n#\n# Cross-subdomain (auth.example.com + registry.example.com): Set to .example.com\n# SESSION_COOKIE_DOMAIN=.example.com\n#\n# Multi-level domains (registry.region-1.corp.company.internal): Set to your org domain\n# SESSION_COOKIE_DOMAIN=.corp.company.internal\n#\n# Default: Empty (cookie scoped to exact host only - safest option)\nSESSION_COOKIE_DOMAIN=\n\n# =============================================================================\n# OAUTH TOKEN STORAGE CONFIGURATION\n# =============================================================================\n\n# Control whether OAuth provider tokens are stored in session cookies\n# When enabled (true, default):\n# - OAuth access_token, refresh_token, and expiration stored in session\n# - May cause cookie size issues with large tokens (e.g., Microsoft Entra ID)\n#\n# When disabled (false):\n# - OAuth tokens NOT stored in session cookies\n# - Reduces cookie size significantly\n# - Recommended for Entra ID deployments experiencing cookie size errors\n#\n# Default: false (tokens are not used functionally, reduces cookie size)\nOAUTH_STORE_TOKENS_IN_SESSION=false\n\n# =============================================================================\n# EXTERNAL MCP SERVER AUTH TOKENS (Auto-generated from OAuth flows)\n# =============================================================================\n# These tokens are automatically populated by the OAuth credential scripts\n# Do not set these manually - they are managed by credentials-provider/\n\n# ATLASSIAN_AUTH_TOKEN=\"auto_generated_by_oauth_flow\"\n# SRE_GATEWAY_AUTH_TOKEN=\"auto_generated_by_oauth_flow\"\n\n# Smithery API Key for accessing Smithery-hosted MCP servers\n# Get this from https://smithery.ai/\nSMITHERY_API_KEY=your_smithery_api_key_here\n\n# =============================================================================\n# AI/LLM CONFIGURATION\n# =============================================================================\n\n# Anthropic API Key for Claude models (required for agent functionality)\n# Get this from https://console.anthropic.com/\nANTHROPIC_API_KEY=your_anthropic_api_key_here\n\n# =============================================================================\n# SECURITY SCANNING CONFIGURATION (Cisco AI Defense Integration)\n# =============================================================================\n\n# Enable/disable security scanning for MCP servers\n# When enabled, servers are scanned during registration for security threats\nSECURITY_SCAN_ENABLED=true\n\n# Automatically scan servers when they are registered\n# Set to false to disable automatic scanning on registration\nSECURITY_SCAN_ON_REGISTRATION=true\n\n# Block (disable) servers that fail security scans\n# When true, unsafe servers are automatically disabled\n# When false, unsafe servers remain enabled but tagged\nSECURITY_BLOCK_UNSAFE_SERVERS=true\n\n# Analyzers to use for security scanning (comma-separated)\n# Available: yara, llm, api\n# - yara: Pattern matching with YARA rules (no API key required)\n# - llm: LLM-as-a-judge evaluation (requires MCP_SCANNER_LLM_API_KEY)\n# - api: Cisco AI Defense inspect API (requires Cisco credentials)\nSECURITY_ANALYZERS=yara\n\n# Security scan timeout in seconds (default: 300 = 5 minutes)\nSECURITY_SCAN_TIMEOUT=60\n\n# Add 'security-pending' tag to servers that fail security scan\n# This helps identify servers awaiting security review\nSECURITY_ADD_PENDING_TAG=true\n\n# MCP Security Scanner LLM API Key (optional - only needed for LLM-based security analysis)\n# Default analyzer is YARA (no API key required)\n# To use LLM analyzer: ./cli/service_mgmt.sh add config.json yara,llm\n# Get OpenAI API key from https://platform.openai.com/api-keys\nMCP_SCANNER_LLM_API_KEY=your_openai_api_key_here\n\n# =============================================================================\n# EMBEDDINGS CONFIGURATION\n# =============================================================================\n\n# Embeddings provider: 'sentence-transformers' (local) or 'litellm' (cloud-based)\n# Default: sentence-transformers (no API key required)\nEMBEDDINGS_PROVIDER=litellm\n\n# Model name for embeddings generation\n# For sentence-transformers: model name from Hugging Face (e.g., all-MiniLM-L6-v2)\n# For litellm: provider-prefixed model (e.g., bedrock/amazon.titan-embed-text-v1,\n# openai/text-embedding-3-small, cohere/embed-english-v3.0)\nEMBEDDINGS_MODEL_NAME=bedrock/amazon.titan-embed-text-v2:0\n\n# Embedding dimension (must match the model's output dimension)\n# all-MiniLM-L6-v2: 384\n# text-embedding-3-small: 1536\n# amazon.titan-embed-text-v1: 1536\n# cohere/embed-english-v3.0: 1024\nEMBEDDINGS_MODEL_DIMENSIONS=1024\n\n# LiteLLM-specific settings (only used when EMBEDDINGS_PROVIDER=litellm)\n# API key for cloud embeddings provider (provider-specific)\n# For OpenAI: Get from https://platform.openai.com/api-keys\n# For Cohere: Get from https://dashboard.cohere.com/api-keys\n# For Bedrock: Not used - configure AWS credentials via standard methods (see below)\n# EMBEDDINGS_API_KEY=your_api_key_here\n\n# Optional: Custom API base URL for embeddings provider\n# EMBEDDINGS_API_BASE=https://api.custom-endpoint.com\n\n# AWS region for Amazon Bedrock embeddings (only needed for Bedrock)\n# Note: For Bedrock authentication, use standard AWS credential chain:\n# - IAM roles (recommended for EC2/EKS)\n# - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)\n# - AWS credentials file (~/.aws/credentials)\n# EMBEDDINGS_AWS_REGION=us-east-1\n\n# =============================================================================\n# ANS (AGENT NAMING SERVICE) CONFIGURATION\n# =============================================================================\n\n# Enable ANS integration for agent identity verification\n# When enabled, agents can be linked to ANS records for verified identity\nANS_INTEGRATION_ENABLED=false\n\n# ANS API endpoint URL\nANS_API_ENDPOINT=https://api.godaddy.com\n\n# ANS API credentials (required when ANS_INTEGRATION_ENABLED=true)\n# Get these from your ANS provider account\nANS_API_KEY=\nANS_API_SECRET=\n\n# ANS API request timeout in seconds\nANS_API_TIMEOUT_SECONDS=30\n\n# How often to re-sync ANS verification status (in hours)\nANS_SYNC_INTERVAL_HOURS=6\n\n# Cache TTL for ANS verification results (in seconds)\nANS_VERIFICATION_CACHE_TTL_SECONDS=3600\n\n# =============================================================================\n# A2A AGENT SECURITY SCANNING CONFIGURATION\n# =============================================================================\n\n# Enable/disable security scanning for A2A agents\n# When enabled, agents are scanned during registration for security threats\nAGENT_SECURITY_SCAN_ENABLED=true\n\n# Automatically scan agents when they are registered\n# Set to false to disable automatic scanning on registration\nAGENT_SECURITY_SCAN_ON_REGISTRATION=true\n\n# Block (disable) agents that fail security scans\n# When true, unsafe agents are automatically disabled\n# When false, unsafe agents remain enabled but tagged\nAGENT_SECURITY_BLOCK_UNSAFE_AGENTS=true\n\n# Analyzers to use for agent security scanning (comma-separated)\n# Available: yara, spec, heuristic, llm, endpoint\n# - yara: Pattern matching with YARA rules (no API key required)\n# - spec: A2A protocol specification validation (no API key required)\n# - heuristic: Logic-based threat detection (no API key required)\n# - llm: LLM-as-a-judge evaluation (requires A2A_SCANNER_LLM_API_KEY)\n# - endpoint: Dynamic endpoint security testing (requires live agent)\nAGENT_SECURITY_ANALYZERS=yara,spec\n\n# Agent security scan timeout in seconds (default: 60 = 1 minute)\nAGENT_SECURITY_SCAN_TIMEOUT=60\n\n# Add 'security-pending' tag to agents that fail security scan\n# This helps identify agents awaiting security review\nAGENT_SECURITY_ADD_PENDING_TAG=true\n\n# A2A Security Scanner LLM API Key (optional - only needed for LLM-based agent analysis)\n# Default analyzers are YARA and Spec (no API key required)\n# Get Azure OpenAI API key from https://portal.azure.com/\nA2A_SCANNER_LLM_API_KEY=your_azure_openai_api_key_here\n\n# =============================================================================\n# CONTAINER REGISTRY CREDENTIALS (for CI/CD and local builds)\n# =============================================================================\n\n# Docker Hub credentials for publishing container images\n# Get these from https://hub.docker.com/settings/security\nDOCKERHUB_USERNAME=your_dockerhub_username\nDOCKERHUB_TOKEN=your_dockerhub_access_token\n\n# GitHub Container Registry credentials (optional - for publishing to ghcr.io)\n# The GITHUB_TOKEN is automatically provided in GitHub Actions\n# For local builds, generate a Personal Access Token with packages:write scope\n# Get this from https://github.com/settings/tokens\n# GITHUB_USERNAME=your_github_username\n# GITHUB_TOKEN=your_github_personal_access_token\n\n# # Container registry organization names\n# DOCKERHUB_ORG=mcpgateway\n# GITHUB_ORG=agentic-community\n\n# =============================================================================\n# EXTERNAL REGISTRY CONFIGURATION\n# =============================================================================\n\n# Comma-separated list of tags that identify external registry servers\n# These tags are used by the frontend to separate internal MCP servers from\n# external registry integrations (e.g., Anthropic, Workday, AWS Agent Registry)\n# Servers tagged with these values will appear in the \"External Registries\" tab\n# Default: anthropic-registry,workday-asor,agentcore\nEXTERNAL_REGISTRY_TAGS=anthropic-registry,workday-asor,agentcore\n\n# =============================================================================\n# AWS REGISTRY FEDERATION (optional)\n# =============================================================================\n# Overrides the aws_registry.enabled flag in the federation config (MongoDB).\n# Registry IDs, region, sync settings are managed via /api/federation/config API.\n#\n# Required IAM permissions on the ECS task role:\n# - bedrock-agentcore:ListRegistries\n# - bedrock-agentcore:ListRegistryRecords\n# - bedrock-agentcore:GetRegistryRecord\n#\n# Enable AWS Agent Registry federation (default: false)\nAWS_REGISTRY_FEDERATION_ENABLED=false\n\n# =============================================================================\n# STORAGE BACKEND CONFIGURATION\n# =============================================================================\n\n# Storage Backend Selection\n# Options:\n# \"file\" - Uses JSON files (simple, local development)\n# \"documentdb\" - Uses Amazon DocumentDB or MongoDB (production, with native vector search)\n# \"mongodb-ce\" - Uses MongoDB Community Edition 8.2 (local dev, application-level vector search)\n# For production deployments, DocumentDB is recommended for scalability and concurrent access\n# Options: file, mongodb-ce, documentdb\nSTORAGE_BACKEND=mongodb-ce\n\n# DocumentDB Configuration (used when STORAGE_BACKEND=documentdb or mongodb-ce)\n# Amazon DocumentDB (MongoDB-compatible) or MongoDB connection settings\n\n# For local MongoDB CE (mongodb-ce backend):\n# Authentication with SCRAM-SHA-256 (stronger than SCRAM-SHA-1)\nDOCUMENTDB_HOST=mongodb\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_USERNAME=admin\nDOCUMENTDB_PASSWORD=admin\nDOCUMENTDB_USE_TLS=false\nDOCUMENTDB_NAMESPACE=default\n\n# For AWS DocumentDB (documentdb backend):\n# Uses SCRAM-SHA-1 (AWS DocumentDB v5.0 limitation)\n# DOCUMENTDB_HOST=your-documentdb-cluster.cluster-xxxxx.us-east-1.docdb.amazonaws.com\n# DOCUMENTDB_PORT=27017\n# DOCUMENTDB_DATABASE=mcp_registry\n# DOCUMENTDB_USERNAME=your_username\n# DOCUMENTDB_PASSWORD=your_password\n# DOCUMENTDB_USE_TLS=true\n# DOCUMENTDB_TLS_CA_FILE=global-bundle.pem\n# DOCUMENTDB_USE_IAM=false\n# DOCUMENTDB_REPLICA_SET=rs0\n# DOCUMENTDB_READ_PREFERENCE=secondaryPreferred\n# DOCUMENTDB_NAMESPACE=default\n\n# =============================================================================\n# GRAFANA CONFIGURATION\n# =============================================================================\n\n# Grafana admin password for the local metrics dashboard\n# IMPORTANT: You must set a strong, random password before starting Grafana\n# Generate with: python3 -c \"import secrets; print(secrets.token_urlsafe(24))\"\nGRAFANA_ADMIN_PASSWORD=CHANGE-ME-SET-STRONG-PASSWORD\n\n# =============================================================================\n# OTLP PUSH EXPORT CONFIGURATION\n# =============================================================================\n# Push OpenTelemetry metrics to an external observability platform via OTLP/HTTP.\n# When OTEL_OTLP_ENDPOINT is set, the metrics service pushes all 9 OTel metrics\n# to the configured endpoint in parallel with the existing Prometheus exporter.\n# When unset, only the Prometheus exporter is active (default behavior).\n\n# OTLP endpoint URL (leave empty to disable OTLP export)\n# OTEL_OTLP_ENDPOINT=\n\n# Datadog (US1):\n# OTEL_OTLP_ENDPOINT=https://otlp.datadoghq.com\n# OTEL_EXPORTER_OTLP_HEADERS=dd-api-key=YOUR_DATADOG_API_KEY\n\n# Datadog (EU1):\n# OTEL_OTLP_ENDPOINT=https://otlp.datadoghq.eu\n# OTEL_EXPORTER_OTLP_HEADERS=dd-api-key=YOUR_DATADOG_API_KEY\n\n# New Relic:\n# OTEL_OTLP_ENDPOINT=https://otlp.nr-data.net\n# OTEL_EXPORTER_OTLP_HEADERS=api-key=YOUR_NEW_RELIC_LICENSE_KEY\n\n# Export interval in milliseconds (default: 30000 = 30 seconds)\n# OTEL_OTLP_EXPORT_INTERVAL_MS=30000\n\n# Metric temporality preference (default: cumulative)\n# Datadog requires \"delta\" — set this when using Datadog as the OTLP endpoint\n# Other platforms (New Relic, Honeycomb, Grafana Cloud) work with the default \"cumulative\"\n# OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative\n\n# =============================================================================\n# AGENTCORE TOKEN REFRESHER - CLIENT SECRETS\n# =============================================================================\n# Used by: uv run python -m cli.agentcore.token_refresher\n#\n# The token refresher resolves OAuth client secrets in this order:\n# 1. Per-client env var: OAUTH_CLIENT_SECRET_\n# 2. Cognito auto-retrieval via AWS describe_user_pool_client API\n# 3. Vendor-level env var (AUTH0_CLIENT_SECRET, OKTA_CLIENT_SECRET, etc.)\n#\n# For Cognito gateways, no env var is needed -- secrets are auto-retrieved\n# from AWS if the IAM role has cognito-idp:DescribeUserPoolClient permission.\n# Set per-client env vars below to override auto-retrieval or for non-Cognito IdPs.\n#\n# The client_id values come from the allowed_clients field in\n# token_refresh_manifest.json (generated by cli.agentcore sync).\n\n# --- Cognito per-client secrets (override auto-retrieval) ---\n# OAUTH_CLIENT_SECRET_49ujl0b9ser72gnp6q1ph9v6vs=your_cognito_client_secret\n# OAUTH_CLIENT_SECRET_5m3bmqg5jjdadkqrecibp5t03j=your_cognito_client_secret\n\n# --- Auth0 (vendor-level, shared across all Auth0 gateways) ---\n# Falls back to AUTH0_CLIENT_SECRET defined above if per-client var not set\n# OAUTH_CLIENT_SECRET_your_auth0_client_id=your_auth0_client_secret\n\n# --- Okta (vendor-level, shared across all Okta gateways) ---\n# Falls back to OKTA_CLIENT_SECRET defined above if per-client var not set\n# OAUTH_CLIENT_SECRET_your_okta_client_id=your_okta_client_secret\n\n# --- Entra ID (vendor-level, shared across all Entra gateways) ---\n# Falls back to ENTRA_CLIENT_SECRET defined above if per-client var not set\n# OAUTH_CLIENT_SECRET_your_entra_client_id=your_entra_client_secret\n\n# --- Keycloak (vendor-level, shared across all Keycloak gateways) ---\n# Falls back to KEYCLOAK_CLIENT_SECRET defined above if per-client var not set\n# OAUTH_CLIENT_SECRET_your_keycloak_client_id=your_keycloak_client_secret\n\n# =============================================================================\n# ADDITIONAL CONFIGURATION\n# =============================================================================\n\n# Optional: Set specific Cognito domain if using custom domain\n# COGNITO_DOMAIN=your-custom-domain.auth.{region}.amazoncognito.com\n\n# Optional: Additional service-specific environment variables\n# Add any additional configuration variables your deployment requires\n\n# =============================================================================\n# AUDIT LOGGING CONFIGURATION\n# =============================================================================\n\n# Enable/disable audit logging\n# When enabled, all API and MCP requests are logged to MongoDB for compliance\n# Default: true\nAUDIT_LOG_ENABLED=true\n\n# Audit log retention period in days\n# Logs older than this are automatically deleted via MongoDB TTL index\n# Common values: 7 (dev), 30 (standard), 90 (compliance)\n# Default: 7\nAUDIT_LOG_MONGODB_TTL_DAYS=7\n\n# =============================================================================\n# APPLICATION LOG CONFIGURATION (Issue #886)\n# =============================================================================\n# Controls RotatingFileHandler and optional MongoDB log storage for\n# centralized log retrieval across pods.\n\n# Max size per log file in bytes before rotation (default: 50 MB)\n# APP_LOG_MAX_BYTES=52428800\n\n# Number of rotated backup files to keep (default: 5)\n# APP_LOG_BACKUP_COUNT=5\n\n# Write application logs to centralized storage (default: true)\n# When enabled, log entries are written to the application_logs collection\n# with TTL auto-expiry. Requires MongoDB/DocumentDB backend.\nAPP_LOG_CENTRALIZED_ENABLED=true\n\n# Days to retain application logs in centralized storage (default: 1)\n# APP_LOG_CENTRALIZED_TTL_DAYS=1\n\n# Number of log records to buffer before flushing to MongoDB (default: 50)\n# APP_LOG_MONGODB_BUFFER_SIZE=50\n\n# Seconds between periodic flushes to MongoDB (default: 5.0)\n# APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=5.0\n\n# Application log level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)\n# APP_LOG_LEVEL=INFO\n\n# Comma-separated logger names to exclude from MongoDB log writes (default: uvicorn.access,httpx,pymongo,motor)\n# APP_LOG_EXCLUDED_LOGGERS=uvicorn.access,httpx,pymongo,motor\n\n# =============================================================================\n# FEDERATION PEER SYNC CONFIGURATION\n# =============================================================================\n# OAuth2 client credentials for peer-to-peer registry federation\n# Run keycloak/setup/setup-federation-service-account.sh to create the client\n# FEDERATION_TOKEN_ENDPOINT=http://keycloak:8080/realms/mcp-gateway/protocol/openid-connect/token\n# FEDERATION_CLIENT_ID=federation-peer-m2m\n# FEDERATION_CLIENT_SECRET=your-federation-client-secret\n\n# =============================================================================\n# WORKDAY ASOR FEDERATION CONFIGURATION (optional)\n# =============================================================================\n# Required only if using Workday ASOR federation\n# Replace 'your-tenant' and 'your_instance' with your actual Workday tenant identifiers\n# Example: https://services.wd101.myworkday.com/ccx/oauth2/production_instance/token\n# IMPORTANT: Must use HTTPS in production environments\n# If not configured with a valid URL, ASOR federation will be automatically disabled with a warning logged\nWORKDAY_TOKEN_URL=https://your-tenant.workday.com/ccx/oauth2/your_instance/token\n\n# =============================================================================\n# TELEMETRY CONFIGURATION\n# =============================================================================\n# Anonymous usage telemetry for tracking registry adoption\n# Privacy-first: no PII, no IP addresses, no hostnames\n\n# Disable telemetry entirely (default: not set, telemetry is ON)\n# MCP_TELEMETRY_DISABLED=1\n\n# Disable daily heartbeat telemetry only (default: not set, heartbeat ON)\n# Startup ping is still sent. Set to 1 to opt out of heartbeat only.\n# MCP_TELEMETRY_OPT_OUT=1\n\n# Heartbeat telemetry interval in minutes (default: 1440 = 24 hours)\nMCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=1440\n\n# Telemetry collector endpoint (default: central collector)\n# Override to use a self-hosted collector\n# MCP_TELEMETRY_ENDPOINT=https://m3ijrhd020.execute-api.us-east-1.amazonaws.com/v1/collect\n\n# Debug mode: log telemetry payloads instead of sending (default: false)\n# TELEMETRY_DEBUG=true\n\n# Disable built-in airegistry-tools server auto-registration\n# Set to true for production/GitOps deployments that manage their own server registrations\n# DISABLE_AI_REGISTRY_TOOLS_SERVER=false\n" }, { "path": ".github/workflows/auth-server-test.yml", "content": "name: Auth Server Test Suite\n\non:\n push:\n branches: [main, develop]\n paths:\n - 'auth_server/**'\n - 'tests/auth_server/**'\n - '.github/workflows/auth-server-test.yml'\n pull_request:\n branches: [main, develop]\n paths:\n - 'auth_server/**'\n - 'tests/auth_server/**'\n - '.github/workflows/auth-server-test.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n name: \"Auth Server Tests (Python ${{ matrix.python-version }})\"\n runs-on: ubuntu-latest\n timeout-minutes: 20\n strategy:\n matrix:\n python-version: [\"3.14\"]\n fail-fast: false\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v5\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n\n - name: Cache dependencies\n uses: actions/cache@v4\n with:\n path: ~/.cache/uv\n key: ${{ runner.os }}-uv-authserver-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}\n restore-keys: |\n ${{ runner.os }}-uv-authserver-${{ matrix.python-version }}-\n ${{ runner.os }}-uv-authserver-\n\n - name: Install dependencies\n run: uv sync --extra dev\n\n - name: Run auth server tests\n run: |\n uv run pytest tests/auth_server/ -v -o \"addopts=\" --cov=auth_server --cov-report=xml --cov-report=html --cov-report=term\n\n - name: Upload coverage to Codecov\n uses: codecov/codecov-action@v5\n with:\n file: ./coverage.xml\n flags: auth-server\n name: codecov-auth-server-${{ matrix.python-version }}\n fail_ci_if_error: false\n\n - name: Upload coverage HTML report\n uses: actions/upload-artifact@v4\n if: always()\n with:\n name: auth-server-coverage-${{ matrix.python-version }}\n path: htmlcov/\n retention-days: 14\n\n lint:\n name: \"Auth Server Code Quality\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.14\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n\n - name: Install linting tools\n run: uv pip install --system ruff\n\n - name: Run ruff check\n run: ruff check auth_server/\n continue-on-error: true\n\n - name: Run ruff format check\n run: ruff format --check auth_server/\n continue-on-error: true\n" }, { "path": ".github/workflows/build-auth-server.yml", "content": "name: Build Auth Server Image\n\non:\n push:\n branches: [main]\n paths:\n - 'auth_server/**'\n - 'registry/**'\n - 'docker/Dockerfile.auth'\n - 'docker/auth-entrypoint.sh'\n - '.github/workflows/build-auth-server.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n packages: write\n attestations: write\n id-token: write\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\nenv:\n REGISTRY: public.ecr.aws\n IMAGE_NAME: p3v1o3c6/auth-server\n\njobs:\n build-and-push:\n if: github.repository == 'agentic-community/mcp-gateway-registry'\n name: Build and Push\n runs-on: ubuntu-latest\n timeout-minutes: 30\n\n steps:\n - name: Checkout code\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n\n - name: Set up QEMU\n uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0\n\n - name: Configure Role to Acquire Credentials\n uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7 # v6.0.0\n with:\n aws-region: us-east-1\n role-session-name: auth-server-build\n role-to-assume: ${{ secrets.ECR_ROLE }}\n\n - name: Login to Amazon ECR Public\n id: login-ecr-public\n uses: aws-actions/amazon-ecr-login@062b18b96a7aff071d4dc91bc00c4c1a7945b076 # v2.0.1\n with:\n registry-type: public\n\n - name: Extract metadata\n id: meta\n uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0\n with:\n images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}\n tags: |\n type=raw,value=latest,enable={{is_default_branch}}\n type=sha,prefix=,format=long\n\n - name: Build and push\n id: push\n uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0\n with:\n context: .\n file: docker/Dockerfile.auth\n push: true\n platforms: linux/amd64,linux/arm64\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n build-args: |\n BUILD_VERSION=${{ github.sha }}\n cache-from: type=gha\n cache-to: type=gha,mode=max\n\n - name: Generate attestation\n uses: actions/attest-build-provenance@96278af6caaf10aea03fd8d33a09a777ca52d62f # v3.2.0\n with:\n subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}\n subject-digest: ${{ steps.push.outputs.digest }}\n push-to-registry: true\n\n - name: Image Summary\n run: |\n echo \"## Auth Server Image Published\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"**Tags:**\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n echo \"${{ steps.meta.outputs.tags }}\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n" }, { "path": ".github/workflows/build-mcpgw.yml", "content": "name: Build MCPGW Image\n\non:\n push:\n branches: [main]\n paths:\n - 'servers/mcpgw/**'\n - 'registry/**'\n - 'docker/Dockerfile.mcp-server'\n - '.github/workflows/build-mcpgw.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n packages: write\n attestations: write\n id-token: write\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\nenv:\n REGISTRY: public.ecr.aws\n IMAGE_NAME: p3v1o3c6/mcpgw\n\njobs:\n build-and-push:\n if: github.repository == 'agentic-community/mcp-gateway-registry'\n name: Build and Push\n runs-on: ubuntu-latest\n timeout-minutes: 45\n\n steps:\n - name: Checkout code\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n\n - name: Set up QEMU\n uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0\n\n - name: Configure Role to Acquire Credentials\n uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7 # v6.0.0\n with:\n aws-region: us-east-1\n role-session-name: mcpgw-build\n role-to-assume: ${{ secrets.ECR_ROLE }}\n\n - name: Login to Amazon ECR Public\n id: login-ecr-public\n uses: aws-actions/amazon-ecr-login@062b18b96a7aff071d4dc91bc00c4c1a7945b076 # v2.0.1\n with:\n registry-type: public\n\n - name: Extract metadata\n id: meta\n uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0\n with:\n images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}\n tags: |\n type=raw,value=latest,enable={{is_default_branch}}\n type=sha,prefix=,format=long\n\n - name: Build and push\n id: push\n uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0\n with:\n context: .\n file: docker/Dockerfile.mcp-server\n push: true\n platforms: linux/amd64,linux/arm64\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n build-args: |\n BUILD_VERSION=${{ github.sha }}\n SERVER_DIR=servers/mcpgw\n cache-from: type=gha\n cache-to: type=gha,mode=max\n\n - name: Generate attestation\n uses: actions/attest-build-provenance@96278af6caaf10aea03fd8d33a09a777ca52d62f # v3.2.0\n with:\n subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}\n subject-digest: ${{ steps.push.outputs.digest }}\n push-to-registry: true\n\n - name: Image Summary\n run: |\n echo \"## MCPGW Image Published\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"**Tags:**\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n echo \"${{ steps.meta.outputs.tags }}\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n" }, { "path": ".github/workflows/build-registry.yml", "content": "name: Build Registry Image\n\non:\n push:\n branches: [main]\n paths:\n - 'registry/**'\n - 'auth_server/**'\n - 'api/**'\n - 'frontend/**'\n - 'scripts/**'\n - 'docker/Dockerfile.registry'\n - 'docker/registry-entrypoint.sh'\n - 'pyproject.toml'\n - '.github/workflows/build-registry.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n packages: write\n attestations: write\n id-token: write\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\nenv:\n REGISTRY: public.ecr.aws\n IMAGE_NAME: p3v1o3c6/registry\n\njobs:\n build-and-push:\n if: github.repository == 'agentic-community/mcp-gateway-registry'\n name: Build and Push\n runs-on: ubuntu-latest\n timeout-minutes: 45\n\n steps:\n - name: Checkout code\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n\n - name: Set up QEMU\n uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0\n\n - name: Configure Role to Acquire Credentials\n uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7 # v6.0.0\n with:\n aws-region: us-east-1\n role-session-name: registry-build\n role-to-assume: ${{ secrets.ECR_ROLE }}\n\n - name: Login to Amazon ECR Public\n id: login-ecr-public\n uses: aws-actions/amazon-ecr-login@062b18b96a7aff071d4dc91bc00c4c1a7945b076 # v2.0.1\n with:\n registry-type: public\n\n - name: Extract metadata\n id: meta\n uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0\n with:\n images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}\n tags: |\n type=raw,value=latest,enable={{is_default_branch}}\n type=sha,prefix=,format=long\n\n - name: Build and push\n id: push\n uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0\n with:\n context: .\n file: docker/Dockerfile.registry\n push: true\n platforms: linux/amd64,linux/arm64\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n build-args: |\n BUILD_VERSION=${{ github.sha }}\n cache-from: type=gha\n cache-to: type=gha,mode=max\n\n - name: Generate attestation\n uses: actions/attest-build-provenance@96278af6caaf10aea03fd8d33a09a777ca52d62f # v3.2.0\n with:\n subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}\n subject-digest: ${{ steps.push.outputs.digest }}\n push-to-registry: true\n\n - name: Image Summary\n run: |\n echo \"## Registry Image Published\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"**Tags:**\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n echo \"${{ steps.meta.outputs.tags }}\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n" }, { "path": ".github/workflows/docs.yml", "content": "name: Build and Deploy Documentation\n\non:\n push:\n branches: [main]\n paths:\n - 'docs/**'\n - 'mkdocs.yml'\n - 'README.md'\n - '.github/workflows/docs.yml'\n pull_request:\n branches: [main]\n paths:\n - 'docs/**'\n - 'mkdocs.yml'\n - 'README.md'\n workflow_dispatch:\n\npermissions:\n contents: read\n pages: write\n id-token: write\n\nconcurrency:\n group: pages-${{ github.ref }}\n cancel-in-progress: false\n\njobs:\n build:\n name: \"Build Documentation\"\n runs-on: ubuntu-latest\n timeout-minutes: 15\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n fetch-depth: 0 # Fetch all history for git plugins\n \n - name: Setup Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.14'\n \n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n \n - name: Cache dependencies\n uses: actions/cache@v4\n with:\n path: ~/.cache/uv\n key: ${{ runner.os }}-uv-${{ hashFiles('pyproject.toml') }}\n restore-keys: |\n ${{ runner.os }}-uv-\n \n - name: Install dependencies\n run: |\n uv pip install --system -e \".[docs]\"\n \n - name: Setup Pages\n id: pages\n uses: actions/configure-pages@v4\n \n - name: Build documentation\n run: |\n mkdocs build --clean\n \n - name: Upload artifact\n uses: actions/upload-pages-artifact@v3\n with:\n path: ./site\n\n deploy:\n name: \"Deploy to GitHub Pages\"\n if: github.ref == 'refs/heads/main'\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n runs-on: ubuntu-latest\n timeout-minutes: 10\n needs: build\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions/deploy-pages@v4" }, { "path": ".github/workflows/helm-chart-update.yml", "content": "name: Update Helm Charts on Release\n\non:\n workflow_run:\n workflows: [\"Release Docker Images\"]\n types: [completed]\n\npermissions:\n contents: write\n pull-requests: write\n\njobs:\n update-helm-charts:\n name: Update Helm Chart Image Tags\n runs-on: ubuntu-latest\n if: >-\n github.event.workflow_run.conclusion == 'success' &&\n github.repository == 'agentic-community/mcp-gateway-registry'\n\n steps:\n - name: Checkout code\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 0\n persist-credentials: false\n\n - name: Extract version from tag\n id: version\n env:\n HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}\n run: |\n TAG=\"$HEAD_BRANCH\"\n VERSION=\"${TAG#v}\"\n echo \"version=$VERSION\" >> \"$GITHUB_OUTPUT\"\n echo \"tag=$TAG\" >> \"$GITHUB_OUTPUT\"\n echo \"Extracted version: $VERSION from tag: $TAG\"\n\n - name: Update image tags in Helm charts\n id: update\n run: |\n VERSION=\"${{ steps.version.outputs.version }}\"\n for VALUES_FILE in \\\n charts/mcp-gateway-registry-stack/values.yaml \\\n charts/auth-server/values.yaml \\\n charts/registry/values.yaml \\\n charts/mcpgw/values.yaml; do\n sed -i \"s/^\\(\\s*tag:\\s*\\).*/\\1${VERSION}/\" \"$VALUES_FILE\"\n echo \"Updated $VALUES_FILE\"\n done\n\n if git diff --quiet; then\n echo \"Charts already at version $VERSION, skipping PR creation\"\n echo \"changed=false\" >> \"$GITHUB_OUTPUT\"\n else\n echo \"changed=true\" >> \"$GITHUB_OUTPUT\"\n fi\n\n - name: Check for new environment variables\n id: envcheck\n env:\n TAG: ${{ steps.version.outputs.tag }}\n run: |\n TAG=\"$TAG\"\n\n # Find the previous release tag\n PREV_TAG=$(git tag --list 'v*.*.*' --sort=-v:refname | grep -v \"^${TAG}$\" | head -n 1)\n if [ -z \"$PREV_TAG\" ]; then\n echo \"No previous tag found, skipping env var check\"\n echo \"comment=\" >> \"$GITHUB_OUTPUT\"\n exit 0\n fi\n echo \"Comparing env vars between $PREV_TAG and $TAG\"\n\n # Extract env var names from app code at each tag\n extract_env_vars() {\n local ref=\"$1\"\n git show \"${ref}:registry/core/config.py\" 2>/dev/null | \\\n grep -oP '(?:env=\")[A-Z_][A-Z0-9_]*(?:\")' | sed 's/env=\"//;s/\"//' || true\n for f in auth_server/server.py servers/mcpgw/server.py; do\n git show \"${ref}:${f}\" 2>/dev/null | \\\n grep -oP '(?:os\\.environ\\.get|os\\.getenv|os\\.environ\\[)\\s*\\(?\\s*[\"\\x27]([A-Z_][A-Z0-9_]*)[\"\\x27]' | \\\n grep -oP '[A-Z_][A-Z0-9_]+' || true\n done\n }\n\n extract_env_vars \"$PREV_TAG\" | sort -u > /tmp/env_old.txt\n extract_env_vars \"$TAG\" | sort -u > /tmp/env_new.txt\n\n # Find newly added env vars\n NEW_VARS=$(comm -13 /tmp/env_old.txt /tmp/env_new.txt)\n if [ -z \"$NEW_VARS\" ]; then\n echo \"No new environment variables detected\"\n echo \"comment=\" >> \"$GITHUB_OUTPUT\"\n exit 0\n fi\n\n # Check which new vars are missing from helm templates\n MISSING=\"\"\n for VAR in $NEW_VARS; do\n if ! grep -rq \"$VAR\" charts/*/templates/; then\n MISSING=\"${MISSING}\\n- \\`${VAR}\\`\"\n fi\n done\n\n if [ -z \"$MISSING\" ]; then\n echo \"All new env vars are already in helm templates\"\n echo \"comment=\" >> \"$GITHUB_OUTPUT\"\n else\n COMMENT=$(cat <> \"$GITHUB_OUTPUT\"\n fi\n\n - name: Create Pull Request\n id: create-pr\n if: steps.update.outputs.changed == 'true'\n uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8\n with:\n branch: helm-update-${{ steps.version.outputs.version }}\n commit-message: \"chore: update Helm chart image tags to ${{ steps.version.outputs.version }}\"\n title: \"chore: update Helm chart image tags to ${{ steps.version.outputs.version }}\"\n body: |\n Automated update of Helm chart image tags to `${{ steps.version.outputs.version }}` following release `${{ steps.version.outputs.tag }}`.\n\n Updated files:\n - `charts/mcp-gateway-registry-stack/values.yaml`\n - `charts/auth-server/values.yaml`\n - `charts/registry/values.yaml`\n - `charts/mcpgw/values.yaml`\n labels: helm\n\n - name: Comment on PR with missing env vars\n if: steps.update.outputs.changed == 'true' && steps.envcheck.outputs.comment != ''\n uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0\n with:\n issue-number: ${{ steps.create-pr.outputs.pull-request-number }}\n body: ${{ steps.envcheck.outputs.comment }}\n" }, { "path": ".github/workflows/helm-release-retag.yml", "content": "name: Move Release Tag After Helm Chart Update\n\non:\n pull_request:\n types: [closed]\n branches: [main]\n\npermissions:\n contents: write\n\njobs:\n retag-release:\n name: Move Release Tag to Main\n runs-on: ubuntu-latest\n if: >-\n github.event.pull_request.merged == true &&\n startsWith(github.event.pull_request.head.ref, 'helm-update-') &&\n github.repository == 'agentic-community/mcp-gateway-registry'\n\n steps:\n - name: Checkout code\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 0\n\n - name: Extract version and move tag\n run: |\n BRANCH=\"${{ github.event.pull_request.head.ref }}\"\n VERSION=\"${BRANCH#helm-update-}\"\n TAG=\"v${VERSION}\"\n\n echo \"Moving tag $TAG to current main HEAD\"\n\n git tag -f \"$TAG\"\n git push origin \"$TAG\" --force\n" }, { "path": ".github/workflows/helm-test.yml", "content": "name: Helm Chart Tests\n\non:\n push:\n branches: [main, develop]\n paths:\n - 'charts/**'\n - '.github/workflows/helm-test.yml'\n pull_request:\n paths:\n - 'charts/**'\n - '.github/workflows/helm-test.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n lint:\n name: \"Helm Lint\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Helm\n uses: azure/setup-helm@v4\n with:\n version: '3.14.0'\n\n - name: Add Helm repositories\n run: |\n helm repo add bitnami https://charts.bitnami.com/bitnami || true\n helm repo update\n\n - name: Build chart dependencies\n run: |\n for chart in charts/*/; do\n if [ -f \"${chart}Chart.yaml\" ]; then\n echo \"Building dependencies for ${chart}...\"\n helm dependency build \"$chart\" || true\n fi\n done\n\n - name: Lint all charts\n run: |\n echo \"## Helm Lint Results\" >> $GITHUB_STEP_SUMMARY\n failed=0\n for chart in charts/*/; do\n if [ -f \"${chart}Chart.yaml\" ]; then\n echo \"Linting ${chart}...\"\n if helm lint \"$chart\" 2>&1; then\n echo \"- ${chart}: PASSED\" >> $GITHUB_STEP_SUMMARY\n else\n echo \"- ${chart}: WARNING (lint issues found)\" >> $GITHUB_STEP_SUMMARY\n # Don't fail on lint warnings, only errors\n fi\n fi\n done\n\n template:\n name: \"Helm Template Validation\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Helm\n uses: azure/setup-helm@v4\n with:\n version: '3.14.0'\n\n - name: Template validation\n run: |\n echo \"## Helm Template Results\" >> $GITHUB_STEP_SUMMARY\n for chart in charts/*/; do\n if [ -f \"${chart}Chart.yaml\" ]; then\n echo \"Validating template for ${chart}...\"\n if helm template test \"$chart\" --debug > /dev/null 2>&1; then\n echo \"- ${chart}: PASSED\" >> $GITHUB_STEP_SUMMARY\n else\n echo \"- ${chart}: FAILED\" >> $GITHUB_STEP_SUMMARY\n helm template test \"$chart\" --debug || true\n fi\n fi\n done\n\n kubeconform:\n name: \"Kubernetes Manifest Validation\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Helm\n uses: azure/setup-helm@v4\n with:\n version: '3.14.0'\n\n - name: Install kubeconform\n run: |\n curl -sL https://github.com/yannh/kubeconform/releases/download/v0.6.4/kubeconform-linux-amd64.tar.gz | tar xz\n sudo mv kubeconform /usr/local/bin/\n\n - name: Validate Kubernetes manifests\n run: |\n echo \"## Kubeconform Results\" >> $GITHUB_STEP_SUMMARY\n for chart in charts/*/; do\n if [ -f \"${chart}Chart.yaml\" ]; then\n echo \"Validating ${chart}...\"\n helm template test \"$chart\" 2>/dev/null | kubeconform -strict -summary -ignore-missing-schemas || true\n fi\n done\n\n dependency-check:\n name: \"Helm Dependency Check\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Helm\n uses: azure/setup-helm@v4\n with:\n version: '3.14.0'\n\n - name: Add Helm repositories\n run: |\n helm repo add bitnami https://charts.bitnami.com/bitnami || true\n helm repo update\n\n - name: Build dependencies for umbrella chart\n run: |\n if [ -f \"charts/mcp-gateway-registry-stack/Chart.yaml\" ]; then\n echo \"Building dependencies for umbrella chart...\"\n helm dependency build charts/mcp-gateway-registry-stack || true\n fi\n\n summary:\n name: \"Helm Test Summary\"\n runs-on: ubuntu-latest\n timeout-minutes: 5\n needs: [lint, template, kubeconform, dependency-check]\n if: always()\n\n steps:\n - name: Results Summary\n run: |\n echo \"## Helm Chart Test Summary\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"| Job | Status |\" >> $GITHUB_STEP_SUMMARY\n echo \"|-----|--------|\" >> $GITHUB_STEP_SUMMARY\n echo \"| Lint | ${{ needs.lint.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Template | ${{ needs.template.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Kubeconform | ${{ needs.kubeconform.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Dependencies | ${{ needs.dependency-check.result }} |\" >> $GITHUB_STEP_SUMMARY\n" }, { "path": ".github/workflows/metrics-service-test.yml", "content": "name: Metrics Service Test Suite\n\non:\n push:\n branches: [main, develop]\n paths:\n - 'metrics-service/**'\n - '.github/workflows/metrics-service-test.yml'\n pull_request:\n branches: [main, develop]\n paths:\n - 'metrics-service/**'\n - '.github/workflows/metrics-service-test.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n name: \"Metrics Service Tests (Python ${{ matrix.python-version }})\"\n runs-on: ubuntu-latest\n timeout-minutes: 20\n strategy:\n matrix:\n python-version: [\"3.14\"]\n fail-fast: false\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v5\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n\n - name: Cache dependencies\n uses: actions/cache@v4\n with:\n path: ~/.cache/uv\n key: ${{ runner.os }}-uv-metrics-${{ matrix.python-version }}-${{ hashFiles('metrics-service/pyproject.toml') }}\n restore-keys: |\n ${{ runner.os }}-uv-metrics-${{ matrix.python-version }}-\n ${{ runner.os }}-uv-metrics-\n\n - name: Install dependencies\n working-directory: metrics-service\n run: uv sync --extra dev\n\n - name: Run metrics service tests\n working-directory: metrics-service\n run: |\n uv run pytest tests/ -v --cov=. --cov-report=xml --cov-report=html --cov-report=term\n\n - name: Upload coverage to Codecov\n uses: codecov/codecov-action@v5\n with:\n file: ./metrics-service/coverage.xml\n flags: metrics-service\n name: codecov-metrics-service-${{ matrix.python-version }}\n fail_ci_if_error: false\n\n - name: Upload coverage HTML report\n uses: actions/upload-artifact@v4\n if: always()\n with:\n name: metrics-service-coverage-${{ matrix.python-version }}\n path: metrics-service/htmlcov/\n retention-days: 14\n\n lint:\n name: \"Metrics Service Code Quality\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.14\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n\n - name: Install linting tools\n run: uv pip install --system ruff\n\n - name: Run ruff check\n working-directory: metrics-service\n run: ruff check .\n\n - name: Run ruff format check\n working-directory: metrics-service\n run: ruff format --check .\n continue-on-error: true\n" }, { "path": ".github/workflows/registry-test.yml", "content": "name: Registry Test Suite\n\non:\n push:\n branches: [main, develop]\n # No path filters - run on every merge to main/develop\n pull_request:\n branches: [main, develop]\n paths:\n - 'registry/**'\n - 'tests/**'\n - 'pyproject.toml'\n - 'scripts/test.py'\n - '.github/workflows/registry-test.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n name: \"Test (Python ${{ matrix.python-version }})\"\n runs-on: ubuntu-latest\n timeout-minutes: 30\n strategy:\n matrix:\n python-version: [\"3.14\"]\n fail-fast: false\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v5\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n\n - name: Cache dependencies\n uses: actions/cache@v4\n with:\n path: ~/.cache/uv\n key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}\n restore-keys: |\n ${{ runner.os }}-uv-${{ matrix.python-version }}-\n ${{ runner.os }}-uv-\n\n - name: Install dependencies\n run: |\n uv sync --extra dev\n\n - name: Check dependencies\n run: |\n uv run python scripts/test.py check\n\n - name: Run all tests with coverage\n run: |\n uv run python scripts/test.py coverage -n 8\n\n - name: Upload coverage to Codecov\n uses: codecov/codecov-action@v5\n with:\n file: ./coverage.xml\n flags: unittests\n name: codecov-python-${{ matrix.python-version }}\n fail_ci_if_error: false\n\n - name: Upload coverage HTML report\n uses: actions/upload-artifact@v4\n if: always()\n with:\n name: coverage-report-${{ matrix.python-version }}\n path: htmlcov/\n retention-days: 14\n\n - name: Upload test reports\n uses: actions/upload-artifact@v4\n if: always()\n with:\n name: test-reports-${{ matrix.python-version }}\n path: tests/reports/\n retention-days: 14\n\n lint:\n name: \"Code Quality\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.14\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n\n - name: Cache dependencies\n uses: actions/cache@v4\n with:\n path: ~/.cache/uv\n key: ${{ runner.os }}-uv-lint-${{ hashFiles('pyproject.toml') }}\n restore-keys: |\n ${{ runner.os }}-uv-lint-\n\n - name: Install dependencies\n run: |\n uv pip install --system ruff\n\n - name: Run ruff check\n run: |\n ruff check registry/ tests/\n continue-on-error: true\n\n - name: Run ruff format check\n run: |\n ruff format --check registry/ tests/\n continue-on-error: true\n\n security:\n name: \"Security Check\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.14\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v4\n with:\n version: \"latest\"\n\n - name: Install bandit\n run: |\n uv pip install --system bandit\n\n - name: Run bandit security scan\n run: |\n bandit -r registry/ -f json -o bandit-report.json || true\n\n - name: Upload security report\n uses: actions/upload-artifact@v4\n if: always()\n with:\n name: security-report\n path: bandit-report.json\n retention-days: 14\n\n summary:\n name: \"Test Summary\"\n runs-on: ubuntu-latest\n timeout-minutes: 5\n needs: [test, lint, security]\n if: always()\n\n steps:\n - name: Test Results Summary\n run: |\n echo \"## Test Results Summary\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"| Job | Status |\" >> $GITHUB_STEP_SUMMARY\n echo \"|-----|--------|\" >> $GITHUB_STEP_SUMMARY\n echo \"| Tests | ${{ needs.test.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Code Quality | ${{ needs.lint.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Security | ${{ needs.security.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n\n if [[ \"${{ needs.test.result }}\" == \"success\" && \"${{ needs.lint.result }}\" == \"success\" && \"${{ needs.security.result }}\" == \"success\" ]]; then\n echo \"All checks passed!\" >> $GITHUB_STEP_SUMMARY\n else\n echo \"Some checks failed. Please review the logs.\" >> $GITHUB_STEP_SUMMARY\n fi\n" }, { "path": ".github/workflows/release-images.yml", "content": "name: Release Docker Images\n\non:\n push:\n tags:\n - 'v*.*.*'\n workflow_dispatch:\n inputs:\n tag:\n description: 'Release tag (e.g., v1.0.0)'\n required: true\n type: string\n\npermissions:\n contents: read\n packages: write\n attestations: write\n id-token: write\n\nenv:\n REGISTRY: public.ecr.aws\n NAMESPACE: p3v1o3c6\n\njobs:\n build-release-images:\n name: Build ${{ matrix.service }} Release\n runs-on: ubuntu-latest\n timeout-minutes: 45\n if: github.repository == 'agentic-community/mcp-gateway-registry'\n \n strategy:\n matrix:\n include:\n - service: auth-server\n dockerfile: docker/Dockerfile.auth\n - service: registry\n dockerfile: docker/Dockerfile.registry\n - service: mcpgw\n dockerfile: docker/Dockerfile.mcp-server\n extra_build_args: |-\n SERVER_DIR=servers/mcpgw\n\n steps:\n - name: Checkout code\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n\n - name: Set up QEMU\n uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0\n\n - name: Configure AWS Credentials\n uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7 # v6.0.0\n with:\n aws-region: us-east-1\n role-session-name: ${{ matrix.service }}-release\n role-to-assume: ${{ secrets.ECR_ROLE }}\n\n - name: Login to Amazon ECR Public\n uses: aws-actions/amazon-ecr-login@062b18b96a7aff071d4dc91bc00c4c1a7945b076 # v2.0.1\n with:\n registry-type: public\n\n - name: Extract metadata\n id: meta\n uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0\n with:\n images: ${{ env.REGISTRY }}/${{ env.NAMESPACE }}/${{ matrix.service }}\n tags: |\n type=semver,pattern={{version}}\n type=semver,pattern={{major}}.{{minor}}\n type=semver,pattern={{major}}\n type=raw,value=latest\n\n - name: Build and push\n id: push\n uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0\n with:\n context: .\n file: ${{ matrix.dockerfile }}\n push: true\n platforms: linux/amd64,linux/arm64\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n build-args: |\n BUILD_VERSION=${{ github.ref_name }}\n ${{ matrix.extra_build_args }}\n cache-from: type=gha\n cache-to: type=gha,mode=max\n\n - name: Generate attestation\n uses: actions/attest-build-provenance@96278af6caaf10aea03fd8d33a09a777ca52d62f # v3.2.0\n with:\n subject-name: ${{ env.REGISTRY }}/${{ env.NAMESPACE }}/${{ matrix.service }}\n subject-digest: ${{ steps.push.outputs.digest }}\n push-to-registry: true\n\n - name: Image Summary\n run: |\n echo \"## ${{ matrix.service }} Release Image Published\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"**Tags:**\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n echo \"${{ steps.meta.outputs.tags }}\" >> $GITHUB_STEP_SUMMARY\n echo '```' >> $GITHUB_STEP_SUMMARY\n" }, { "path": ".github/workflows/terraform-test.yml", "content": "name: Terraform Tests\n\non:\n push:\n branches: [main, develop]\n paths:\n - 'terraform/**'\n - '.github/workflows/terraform-test.yml'\n pull_request:\n paths:\n - 'terraform/**'\n - '.github/workflows/terraform-test.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n security-events: write\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n validate:\n name: \"Terraform Validate\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n defaults:\n run:\n working-directory: terraform/aws-ecs\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Setup Terraform\n uses: hashicorp/setup-terraform@v3\n with:\n terraform_version: \"1.12.0\"\n\n - name: Terraform fmt check\n id: fmt\n run: terraform fmt -check -recursive\n continue-on-error: true\n\n - name: Terraform init\n id: init\n run: terraform init -backend=false\n\n - name: Terraform validate\n id: validate\n run: terraform validate\n continue-on-error: true\n\n - name: Post validation results\n run: |\n echo \"## Terraform Validation Results\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"| Check | Status |\" >> $GITHUB_STEP_SUMMARY\n echo \"|-------|--------|\" >> $GITHUB_STEP_SUMMARY\n echo \"| Format | ${{ steps.fmt.outcome }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Init | ${{ steps.init.outcome }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Validate | ${{ steps.validate.outcome }} |\" >> $GITHUB_STEP_SUMMARY\n\n tflint:\n name: \"TFLint\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n defaults:\n run:\n working-directory: terraform/aws-ecs\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Setup TFLint\n uses: terraform-linters/setup-tflint@v4\n with:\n tflint_version: v0.50.0\n\n - name: Init TFLint\n run: tflint --init\n continue-on-error: true\n\n - name: Run TFLint\n run: tflint --recursive --format compact\n continue-on-error: true\n\n tfsec:\n name: \"TFSec Security Scan\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Run tfsec\n uses: aquasecurity/tfsec-action@v1.0.3\n with:\n working_directory: terraform/aws-ecs\n soft_fail: true\n format: sarif\n out: tfsec-results.sarif\n continue-on-error: true\n\n - name: Upload SARIF file\n uses: github/codeql-action/upload-sarif@v3\n if: always()\n with:\n sarif_file: tfsec-results.sarif\n continue-on-error: true\n\n checkov:\n name: \"Checkov Security Scan\"\n runs-on: ubuntu-latest\n timeout-minutes: 15\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Run Checkov\n uses: bridgecrewio/checkov-action@v12\n with:\n directory: terraform/aws-ecs\n framework: terraform\n soft_fail: true\n output_format: cli,sarif\n output_file_path: console,checkov-results.sarif\n download_external_modules: true\n\n - name: Upload SARIF file\n uses: github/codeql-action/upload-sarif@v3\n if: always()\n with:\n sarif_file: checkov-results.sarif\n continue-on-error: true\n\n summary:\n name: \"Terraform Test Summary\"\n runs-on: ubuntu-latest\n timeout-minutes: 5\n needs: [validate, tflint, tfsec, checkov]\n if: always()\n\n steps:\n - name: Results Summary\n run: |\n echo \"## Terraform Test Summary\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"| Job | Status |\" >> $GITHUB_STEP_SUMMARY\n echo \"|-----|--------|\" >> $GITHUB_STEP_SUMMARY\n echo \"| Validate | ${{ needs.validate.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| TFLint | ${{ needs.tflint.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| TFSec | ${{ needs.tfsec.result }} |\" >> $GITHUB_STEP_SUMMARY\n echo \"| Checkov | ${{ needs.checkov.result }} |\" >> $GITHUB_STEP_SUMMARY\n" }, { "path": ".gitignore", "content": "# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n\n# Models\n.models/\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py,cover\n.hypothesis/\n.pytest_cache/\ncover/\ntests/reports/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\ndb.sqlite3-journal\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\n.pybuilder/\ntarget/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# IPython\nprofile_default/\nipython_config.py\n\n# pyenv\n# For a library or package, you might want to ignore these files since the code is\n# intended to run in multiple environments; otherwise, check them in:\n# .python-version\n\n# pipenv\n# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.\n# However, in case of collaboration, if having platform-specific dependencies or dependencies\n# having no cross-platform support, pipenv may install dependencies that don't work, or not\n# install all needed dependencies.\n#Pipfile.lock\n\n# UV\n# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.\n# This is especially recommended for binary packages to ensure reproducibility, and is more\n# commonly ignored for libraries.\n#uv.lock\n\n# poetry\n# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.\n# This is especially recommended for binary packages to ensure reproducibility, and is more\n# commonly ignored for libraries.\n# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control\n#poetry.lock\n\n# pdm\n# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.\n#pdm.lock\n# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it\n# in version control.\n# https://pdm.fming.dev/latest/usage/project/#working-with-version-control\n.pdm.toml\n.pdm-python\n.pdm-build/\n\n# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm\n__pypackages__/\n\n# Celery stuff\ncelerybeat-schedule\ncelerybeat.pid\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.env.*\n!.env.example\n.env.backup\n.env.user\n.env.docker\n\n# Configuration files with sensitive data\ncredentials-provider/agentcore-auth/config.yaml\ncredentials-provider/oauth/config.yaml\ncli/examples/peer-registry-lob-1.json\ncli/examples/peer-sales-registry.json\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\n\n# PyCharm\n# JetBrains specific template is maintained in a separate JetBrains.gitignore that can\n# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore\n# and can be added to the global gitignore or merged into this file. For a more nuclear\n# option (not recommended) you can uncomment the following to ignore the entire idea folder.\n.idea/\n\n# Ruff stuff:\n.ruff_cache/\n.cache/\n\n# PyPI configuration file\n.pypirc\ncookies.txt\n.cookies\n\n# Scratchpad for temporary notes and planning\n.scratchpad/\n\n# MongoDB keyfile for replica set authentication\n.mongodb-keyfile\n\n# Roo IDE files\n.roo/\n\n# VS Code / IDE files\n.vscode/\n\n# Kiro files\n.kiro\n.kiro/\n\n# Agent config\nagents/agent_config.json\n\n# Jules files\n.Jules/\n\n# OAuth tokens and credentials - never commit these!\n.oauth-tokens/\n.agentcore-params\n.cognito_access_token\n.network-trusted-token\n.token*\napi/.token\napi/.mcp-session\n\n# Keycloak client secrets (generated by init-keycloak.sh)\nkeycloak/setup/keycloak-client-secrets.txt\nkeycloak/setup/retrieved-keycloak-secrets.txt\n\n# MCP Gateway specific\nregistry/server_state.json\nregistry/nginx_mcp_revproxy.conf\nregistry/agents/\nregistry/data/\nlogs/\ntoken_refresher.pid\ntoken_refresher.log\ntoken_refresh_manifest.json\n.mcp.json\n\n# Secrets and API keys - never commit these!\n.keys.yml\n.keys.yml.encrypted\n*.keys.yml\n*.keys.yml.encrypted\n\n# SSL certificates and keys - never commit these!\n*.pem\n*.key\n*.crt\n*.csr\n*.p12\n*.pfx\n/etc/ssl/\n\n# Agent testing\nagents/test_results/\nagents/.env.user\nssl_data/\nagents/.env.agent\n\n# Frontend / Node.js / React / TypeScript\nfrontend/node_modules/\nfrontend/build/\nfrontend/dist/\nfrontend/.env\nfrontend/.env.local\nfrontend/.env.development.local\nfrontend/.env.test.local\nfrontend/.env.production.local\nfrontend/npm-debug.log*\nfrontend/yarn-debug.log*\nfrontend/yarn-error.log*\nfrontend/.pnpm-debug.log*\nfrontend/lerna-debug.log*\nfrontend/.DS_Store\nfrontend/.vscode/\nfrontend/.idea/\nfrontend/*.tsbuildinfo\nfrontend/.nyc_output\nfrontend/coverage/\nfrontend/.cache/\nfrontend/.parcel-cache/\nfrontend/.next/\nfrontend/out/\nfrontend/.nuxt/\nfrontend/.vuepress/dist\nfrontend/.serverless/\nfrontend/.fusebox/\nfrontend/.dynamodb/\nfrontend/.tern-port\nfrontend/storybook-static/\n\n# Node.js (global patterns)\nnode_modules/\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n.pnpm-debug.log*\nlerna-debug.log*\n.DS_Store\n*.tsbuildinfo\n.nyc_output\ncoverage/\n.cache/\n.parcel-cache/\n.scratchpad/\n\n#MCP Json\n.tmp/anthropic-import\n\n# Anthropic registry temporary files\nanthropic_servers_*.json\ncurated_import_list.txt\n\n#Security scans\nsecurity_scans/\n\n#Temporary directories\n.tmp\n\n#AgentCore CLI generated files\n.bedrock_agentcore\n.bedrock_agentcore.yaml\n\n# Terraform user-specific configuration (NEVER COMMIT!)\n# Users should copy terraform.tfvars.example to terraform.tfvars and edit it\nterraform.tfvars\nterraform.tfvars.json\noverride.tf\noverride.tf.json\n*_override.tf\n*_override.tf.json\n.terraform/\n.terraform.lock.hcl\ncrash.log\ncrash.*.log\ntfplan*\nterraform.tfstate*\nterraform-outputs.json.backup*\n\n# Terraform outputs and region-specific configs (environment-specific, do not commit)\nterraform-outputs.json\nterraform-outputs.txt\nterraform/aws-ecs/scripts/terraform-outputs.json\nterraform/aws-ecs/terraform-outputs.txt\nterraform.tfvars.*\n!terraform.tfvars.example\nterraform/aws-ecs/terraform.tfvars.*\n!terraform/aws-ecs/terraform.tfvars.example\n\n# Generated image manifest for container builds (generated by Makefile)\nimage-manifest.json# Admin password files\n*.admin_password\nterraform/.admin_password\nimage-manifest.json\nagent_security_scans/\nskill_security_scans/\n\n# Helm dependency charts and lock files (fetched via helm dependency build)\ncharts/*/charts/\ncharts/*/Chart.lock\n\n# Shell config artifacts\n.ash/\n\n# Claude\n.claude/*\n!.claude/skills/\n.claude/skills/search-registry/\n.token?\n\n# Telemetry collector build artifacts and state\nterraform/telemetry-collector/terraform.tfstate\nterraform/telemetry-collector/terraform.tfstate.backup\nterraform/telemetry-collector/tfplan\nterraform/telemetry-collector/terraform-apply.log\nterraform/telemetry-collector/deployment-info-testing.txt\nterraform/telemetry-collector/lambda_function.zip\nterraform/telemetry-collector/lambda/collector/lambda_function_linux.zip\nterraform/telemetry-collector/lambda/index-setup/index_setup.zip\nterraform/telemetry-collector/lambda/lambda_function.zip\nterraform/telemetry-collector/global-bundle.pem\nterraform/telemetry-collector/terraform.tfvars\nterraform/telemetry-collector/DEPLOYMENT-SUMMARY.md\nterraform/telemetry-collector/INTEGRATION-TEST-SUMMARY.md\nterraform/telemetry-collector/MONITORING-GUIDE.md\nterraform/telemetry-collector/PROGRESS.md\nterraform/telemetry-collector/lambda/collector/package/\nterraform/telemetry-collector/lambda/index-setup/package/\nterraform/telemetry-collector/.terraform/\nterraform/telemetry-collector/.terraform.lock.hcl\n\n# Vendored Python packages in Lambda directories (build artifacts)\nterraform/telemetry-collector/lambda/collector/*.dist-info/\nterraform/telemetry-collector/lambda/collector/bson/\nterraform/telemetry-collector/lambda/collector/dns/\nterraform/telemetry-collector/lambda/collector/gridfs/\nterraform/telemetry-collector/lambda/collector/motor/\nterraform/telemetry-collector/lambda/collector/pymongo/\nterraform/telemetry-collector/lambda/collector/pydantic/\nterraform/telemetry-collector/lambda/collector/pydantic_core/\nterraform/telemetry-collector/lambda/collector/annotated_types/\nterraform/telemetry-collector/lambda/collector/typing_inspection/\nterraform/telemetry-collector/lambda/collector/typing_extensions.py\nterraform/telemetry-collector/lambda/collector/boto3/\nterraform/telemetry-collector/lambda/collector/botocore/\nterraform/telemetry-collector/lambda/collector/dateutil/\nterraform/telemetry-collector/lambda/collector/jmespath/\nterraform/telemetry-collector/lambda/collector/s3transfer/\nterraform/telemetry-collector/lambda/collector/urllib3/\nterraform/telemetry-collector/lambda/collector/bin/\nterraform/telemetry-collector/lambda/collector/six.py\nterraform/telemetry-collector/lambda/collector/*.dist-info/\nterraform/telemetry-collector/lambda/index-setup/*.dist-info/\nterraform/telemetry-collector/lambda/index-setup/bson/\nterraform/telemetry-collector/lambda/index-setup/pymongo/\n\n# Root-level telemetry test scripts (not part of the project)\ntest-telemetry-*.sh\ntest-telemetry-*.py\nverify-telemetry-test.sh\nwatch-collector-logs.sh\nNEXT-STEPS-TELEMETRY.md\n.env.telemetry-test\nregistry_metrics.csv\n.claude/skills/usage-report/known-internal-instances.md\n" }, { "path": ".pre-commit-config.yaml", "content": "# Pre-commit hooks for MCP Gateway Registry\n# Install with: pre-commit install\n# Run manually: pre-commit run --all-files\n\nrepos:\n # Ruff - Fast Python linter and formatter\n - repo: https://github.com/astral-sh/ruff-pre-commit\n rev: v0.8.2\n hooks:\n # Run the linter with auto-fixes\n - id: ruff\n args: [--fix]\n name: Ruff linter\n description: Run ruff linter with auto-fixes\n\n # Run the formatter\n - id: ruff-format\n name: Ruff formatter\n description: Run ruff formatter\n\n # Pre-commit hooks for file quality\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v5.0.0\n hooks:\n # Remove trailing whitespace\n - id: trailing-whitespace\n name: Trim trailing whitespace\n description: Remove trailing whitespace\n\n # Ensure files end with newline\n - id: end-of-file-fixer\n name: Fix end of files\n description: Ensure files end with a newline\n\n # Check YAML syntax\n - id: check-yaml\n name: Check YAML\n description: Validate YAML file syntax\n exclude: ^(docker/|\\.github/)\n\n # Check JSON syntax\n - id: check-json\n name: Check JSON\n description: Validate JSON file syntax\n\n # Prevent large files from being committed\n - id: check-added-large-files\n name: Check for large files\n description: Prevent files larger than 500KB\n args: ['--maxkb=500']\n\n # Check for merge conflict markers\n - id: check-merge-conflict\n name: Check for merge conflicts\n description: Check for merge conflict markers\n\n # Detect private keys\n - id: detect-private-key\n name: Detect private keys\n description: Check for private SSH keys\n\n # Check for case conflicts in filenames\n - id: check-case-conflict\n name: Check filename case conflicts\n description: Check for case conflicts in filenames\n\n # Check Python docstrings\n - id: check-docstring-first\n name: Check docstring is first\n description: Ensure docstring comes first in Python files\n\n # Check for debugger imports\n - id: debug-statements\n name: Check for debugger statements\n description: Check for pdb and ipdb debugger statements\n\n # Detect-secrets - Prevent secrets from being committed\n - repo: https://github.com/Yelp/detect-secrets\n rev: v1.5.0\n hooks:\n - id: detect-secrets\n name: Detect secrets\n description: Prevent hardcoded secrets from being committed\n args: ['--baseline', '.secrets.baseline']\n exclude: ^(tests/|docs/|cli/examples/)\n\n # Bandit - Security vulnerability scanner\n - repo: https://github.com/PyCQA/bandit\n rev: '1.8.3'\n hooks:\n - id: bandit\n name: Bandit security scan\n description: Scan for security vulnerabilities\n args: ['-c', 'pyproject.toml']\n additional_dependencies: ['bandit[toml]']\n exclude: ^tests/\n\n # MyPy - Static type checker\n - repo: https://github.com/pre-commit/mirrors-mypy\n rev: v1.11.2\n hooks:\n - id: mypy\n name: MyPy type checking\n description: Static type checking\n additional_dependencies:\n - types-requests\n - types-PyYAML\n - pydantic\n args: [--ignore-missing-imports, --no-strict-optional]\n exclude: ^(tests/|scripts/)\n\n # Local hooks for project-specific checks\n - repo: local\n hooks:\n # Run fast unit tests\n - id: pytest-fast\n name: Run fast tests\n entry: uv run pytest -m \"not slow\" --tb=short\n language: system\n pass_filenames: false\n always_run: true\n stages: [commit]\n\n # Python syntax check\n - id: python-syntax\n name: Check Python syntax\n entry: python -m py_compile\n language: system\n types: [python]\n\n # Shell script syntax check\n - id: shell-syntax\n name: Check shell script syntax\n entry: bash -n\n language: system\n types: [shell]\n exclude: ^(docker/|scripts/setup/)\n\n# Default stages\ndefault_stages: [commit]\n\n# Default language version\ndefault_language_version:\n python: python3.14\n\n# Fail fast - stop on first error\nfail_fast: false\n\n# Minimum pre-commit version\nminimum_pre_commit_version: '2.20.0'\n" }, { "path": ".secrets.baseline", "content": "{\n \"version\": \"1.5.0\",\n \"plugins_used\": [\n {\n \"name\": \"ArtifactoryDetector\"\n },\n {\n \"name\": \"AWSKeyDetector\"\n },\n {\n \"name\": \"AzureStorageKeyDetector\"\n },\n {\n \"name\": \"Base64HighEntropyString\",\n \"limit\": 4.5\n },\n {\n \"name\": \"BasicAuthDetector\"\n },\n {\n \"name\": \"CloudantDetector\"\n },\n {\n \"name\": \"DiscordBotTokenDetector\"\n },\n {\n \"name\": \"GitHubTokenDetector\"\n },\n {\n \"name\": \"GitLabTokenDetector\"\n },\n {\n \"name\": \"HexHighEntropyString\",\n \"limit\": 3.0\n },\n {\n \"name\": \"IbmCloudIamDetector\"\n },\n {\n \"name\": \"IbmCosHmacDetector\"\n },\n {\n \"name\": \"IPPublicDetector\"\n },\n {\n \"name\": \"JwtTokenDetector\"\n },\n {\n \"name\": \"KeywordDetector\",\n \"keyword_exclude\": \"\"\n },\n {\n \"name\": \"MailchimpDetector\"\n },\n {\n \"name\": \"NpmDetector\"\n },\n {\n \"name\": \"OpenAIDetector\"\n },\n {\n \"name\": \"PrivateKeyDetector\"\n },\n {\n \"name\": \"PypiTokenDetector\"\n },\n {\n \"name\": \"SendGridDetector\"\n },\n {\n \"name\": \"SlackDetector\"\n },\n {\n \"name\": \"SoftlayerDetector\"\n },\n {\n \"name\": \"SquareOAuthDetector\"\n },\n {\n \"name\": \"StripeDetector\"\n },\n {\n \"name\": \"TelegramBotTokenDetector\"\n },\n {\n \"name\": \"TwilioKeyDetector\"\n }\n ],\n \"filters_used\": [\n {\n \"path\": \"detect_secrets.filters.allowlist.is_line_allowlisted\"\n },\n {\n \"path\": \"detect_secrets.filters.common.is_ignored_due_to_verification_policies\",\n \"min_level\": 2\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_indirect_reference\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_likely_id_string\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_lock_file\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_not_alphanumeric_string\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_potential_uuid\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_sequential_string\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_swagger_file\"\n },\n {\n \"path\": \"detect_secrets.filters.heuristic.is_templated_secret\"\n },\n {\n \"path\": \"detect_secrets.filters.regex.should_exclude_file\",\n \"pattern\": [\n \"^(tests/|docs/|cli/examples/|\\\\.git/)\"\n ]\n }\n ],\n \"results\": {\n \"api/get-m2m-token.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"api/get-m2m-token.sh\",\n \"hashed_secret\": \"2be88ca4242c76e8253ac62474851065032d6833\",\n \"is_verified\": false,\n \"line_number\": 211\n }\n ],\n \"api/registry_client.py\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"api/registry_client.py\",\n \"hashed_secret\": \"fca71afec681b7c2932610046e8e524820317e47\",\n \"is_verified\": false,\n \"line_number\": 268\n }\n ],\n \"api/registry_management.py\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"api/registry_management.py\",\n \"hashed_secret\": \"fca71afec681b7c2932610046e8e524820317e47\",\n \"is_verified\": false,\n \"line_number\": 1519\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"api/registry_management.py\",\n \"hashed_secret\": \"665b1e3851eefefa3fb878654292f16597d25155\",\n \"is_verified\": false,\n \"line_number\": 1733\n }\n ],\n \"api/test-management-api-e2e.md\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"api/test-management-api-e2e.md\",\n \"hashed_secret\": \"b60c1b0150f701d3ea5375a34a43e3e9b63ada2c\",\n \"is_verified\": false,\n \"line_number\": 65\n }\n ],\n \"auth_server/.env.template\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"auth_server/.env.template\",\n \"hashed_secret\": \"1bb9fef4dcaec0c4c0ba677e927f904500ab6c4b\",\n \"is_verified\": false,\n \"line_number\": 11\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"auth_server/.env.template\",\n \"hashed_secret\": \"29b8dca3de5ff27bcf8bd3b622adf9970f29381c\",\n \"is_verified\": false,\n \"line_number\": 23\n }\n ],\n \"build_and_run.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"build_and_run.sh\",\n \"hashed_secret\": \"c35bdb821a941808a150db95d0f934f449bbff17\",\n \"is_verified\": false,\n \"line_number\": 433\n }\n ],\n \"charts/auth-server/values.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/auth-server/values.yaml\",\n \"hashed_secret\": \"8d44de1035672968b3e922b3d15e08c1dce4f9b6\",\n \"is_verified\": false,\n \"line_number\": 12\n }\n ],\n \"charts/keycloak-configure/templates/configmap.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/keycloak-configure/templates/configmap.yaml\",\n \"hashed_secret\": \"5ffe533b830f08a0326348a9160afafc8ada44db\",\n \"is_verified\": false,\n \"line_number\": 95\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/keycloak-configure/templates/configmap.yaml\",\n \"hashed_secret\": \"9723444fb302ebd3cac2b5e5f0a1ade0d40c03c7\",\n \"is_verified\": false,\n \"line_number\": 724\n }\n ],\n \"charts/mcp-gateway-registry-stack/README.md\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/README.md\",\n \"hashed_secret\": \"2d5978d21d2072d7922a49935dcb363378eab0bc\",\n \"is_verified\": false,\n \"line_number\": 118\n }\n ],\n \"charts/mcp-gateway-registry-stack/templates/mongodb-cluster.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/templates/mongodb-cluster.yaml\",\n \"hashed_secret\": \"7d4295ea62a0fb8fb7f8f5707db8cd4db689d9c2\",\n \"is_verified\": false,\n \"line_number\": 26\n }\n ],\n \"charts/mcp-gateway-registry-stack/templates/oauth-provider-secret.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/templates/oauth-provider-secret.yaml\",\n \"hashed_secret\": \"e3568c17ddb547dd50c4b4990152e9ad46ac29ea\",\n \"is_verified\": false,\n \"line_number\": 42\n }\n ],\n \"charts/mcp-gateway-registry-stack/templates/shared-secret.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/templates/shared-secret.yaml\",\n \"hashed_secret\": \"e3568c17ddb547dd50c4b4990152e9ad46ac29ea\",\n \"is_verified\": false,\n \"line_number\": 12\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/templates/shared-secret.yaml\",\n \"hashed_secret\": \"94c6c8fdccfc8f4fe660af892feaabdc8d8d2201\",\n \"is_verified\": false,\n \"line_number\": 14\n }\n ],\n \"charts/mcp-gateway-registry-stack/values.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/values.yaml\",\n \"hashed_secret\": \"76ed0a056aa77060de25754586440cff390791d0\",\n \"is_verified\": false,\n \"line_number\": 18\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/values.yaml\",\n \"hashed_secret\": \"f880fa90169f5214a7e9c6a817b3f31aeb71f5c7\",\n \"is_verified\": false,\n \"line_number\": 22\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcp-gateway-registry-stack/values.yaml\",\n \"hashed_secret\": \"54053db99b49b4cc046f7b4854a80de3d6dfae71\",\n \"is_verified\": false,\n \"line_number\": 70\n }\n ],\n \"charts/mcpgw/values.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mcpgw/values.yaml\",\n \"hashed_secret\": \"aa90ae690498f4d84834974d12a9990b594e338e\",\n \"is_verified\": false,\n \"line_number\": 12\n }\n ],\n \"charts/mongodb-configure/templates/configmap.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mongodb-configure/templates/configmap.yaml\",\n \"hashed_secret\": \"3442496b96dd01591a8cd44b1eec1368ab728aba\",\n \"is_verified\": false,\n \"line_number\": 226\n }\n ],\n \"charts/mongodb-configure/values.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/mongodb-configure/values.yaml\",\n \"hashed_secret\": \"54053db99b49b4cc046f7b4854a80de3d6dfae71\",\n \"is_verified\": false,\n \"line_number\": 15\n }\n ],\n \"charts/registry/values.yaml\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"charts/registry/values.yaml\",\n \"hashed_secret\": \"c83acc39662eea92bcfbd9dc69d4dbe5fc0f2951\",\n \"is_verified\": false,\n \"line_number\": 12\n }\n ],\n \"cli/mcp_security_scanner.py\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"cli/mcp_security_scanner.py\",\n \"hashed_secret\": \"80bcbe9821472b00da2dcece9bf1f7ee27acf22c\",\n \"is_verified\": false,\n \"line_number\": 31\n }\n ],\n \"cli/src/utils/cost.json\": [\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"cli/src/utils/cost.json\",\n \"hashed_secret\": \"0e58cba3de592ca22002e9b5a355102bfc738f05\",\n \"is_verified\": false,\n \"line_number\": 3142\n },\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"cli/src/utils/cost.json\",\n \"hashed_secret\": \"9b45b018ce366a8d8b440df12fadc183406c92d6\",\n \"is_verified\": false,\n \"line_number\": 7148\n },\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"cli/src/utils/cost.json\",\n \"hashed_secret\": \"4ad9c5ebcdbd110afa5ca680854dd5bd72314bb8\",\n \"is_verified\": false,\n \"line_number\": 7453\n },\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"cli/src/utils/cost.json\",\n \"hashed_secret\": \"8927d5a0b386ac18deffa37f02fd808f3fb8bcbd\",\n \"is_verified\": false,\n \"line_number\": 8488\n },\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"cli/src/utils/cost.json\",\n \"hashed_secret\": \"c8883fc592bf698b29fd2304fa1ad570df1f9abf\",\n \"is_verified\": false,\n \"line_number\": 14119\n },\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"cli/src/utils/cost.json\",\n \"hashed_secret\": \"61da47b9d42215793e5604b478982f4cb21fdee1\",\n \"is_verified\": false,\n \"line_number\": 20303\n },\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"cli/src/utils/cost.json\",\n \"hashed_secret\": \"aa684a0841bf2d1fd7e9b774262fcddc9920ffc6\",\n \"is_verified\": false,\n \"line_number\": 20388\n }\n ],\n \"cli/user_mgmt.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"cli/user_mgmt.sh\",\n \"hashed_secret\": \"2be88ca4242c76e8253ac62474851065032d6833\",\n \"is_verified\": false,\n \"line_number\": 244\n }\n ],\n \"credentials-provider/entra/generate_tokens.py\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"credentials-provider/entra/generate_tokens.py\",\n \"hashed_secret\": \"c303df00cd0a72b21c62900b758b06fc541664ce\",\n \"is_verified\": false,\n \"line_number\": 327\n }\n ],\n \"frontend/e2e/helpers/auth.ts\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"frontend/e2e/helpers/auth.ts\",\n \"hashed_secret\": \"d033e22ae348aeb5660fc2140aec35850c4da997\",\n \"is_verified\": false,\n \"line_number\": 7\n }\n ],\n \"frontend/src/components/IAMUsers.tsx\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"frontend/src/components/IAMUsers.tsx\",\n \"hashed_secret\": \"6c56a9249cba324d029f725f1f7c0e47184e2dcf\",\n \"is_verified\": false,\n \"line_number\": 111\n }\n ],\n \"frontend/src/pages/Login.tsx\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"frontend/src/pages/Login.tsx\",\n \"hashed_secret\": \"6c56a9249cba324d029f725f1f7c0e47184e2dcf\",\n \"is_verified\": false,\n \"line_number\": 93\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"frontend/src/pages/Login.tsx\",\n \"hashed_secret\": \"73e350f9131d07e887b1e22e114101a90d44ebb0\",\n \"is_verified\": false,\n \"line_number\": 95\n }\n ],\n \"keycloak/README.md\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/README.md\",\n \"hashed_secret\": \"534c57bf48f9277e7ee50c5febcdb3dab99f0051\",\n \"is_verified\": false,\n \"line_number\": 12\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/README.md\",\n \"hashed_secret\": \"001c1654cb8dff7c4ddb1ae6d2203d0dd15a6096\",\n \"is_verified\": false,\n \"line_number\": 13\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/README.md\",\n \"hashed_secret\": \"354b3a4b7715d3694c88a4fa7db49e41de86568e\",\n \"is_verified\": false,\n \"line_number\": 82\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/README.md\",\n \"hashed_secret\": \"7b0e6379ca79d9a02abc556232d503a86c37012e\",\n \"is_verified\": false,\n \"line_number\": 83\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/README.md\",\n \"hashed_secret\": \"45d676e7c6ab44cf4b8fa366ef2d8fccd3e6d6e6\",\n \"is_verified\": false,\n \"line_number\": 165\n }\n ],\n \"keycloak/setup/disable-ssl.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/setup/disable-ssl.sh\",\n \"hashed_secret\": \"6eef6648406c333a4035cd5e60d0bf2ecf2606d7\",\n \"is_verified\": false,\n \"line_number\": 80\n }\n ],\n \"keycloak/setup/get-all-client-credentials.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/setup/get-all-client-credentials.sh\",\n \"hashed_secret\": \"08d2e98e6754af941484848930ccbaddfefe13d6\",\n \"is_verified\": false,\n \"line_number\": 104\n }\n ],\n \"keycloak/setup/setup-federation-service-account.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/setup/setup-federation-service-account.sh\",\n \"hashed_secret\": \"45d676e7c6ab44cf4b8fa366ef2d8fccd3e6d6e6\",\n \"is_verified\": false,\n \"line_number\": 17\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"keycloak/setup/setup-federation-service-account.sh\",\n \"hashed_secret\": \"2be88ca4242c76e8253ac62474851065032d6833\",\n \"is_verified\": false,\n \"line_number\": 156\n }\n ],\n \"metrics-service/add_test_key.py\": [\n {\n \"type\": \"Hex High Entropy String\",\n \"filename\": \"metrics-service/add_test_key.py\",\n \"hashed_secret\": \"41bc5baca453bd6dc49f421ece29f5d57bb581bb\",\n \"is_verified\": false,\n \"line_number\": 13\n }\n ],\n \"metrics-service/docs/README.md\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"metrics-service/docs/README.md\",\n \"hashed_secret\": \"b310da45b1ebf444106a41b7832ab2fbe25dab41\",\n \"is_verified\": false,\n \"line_number\": 446\n }\n ],\n \"metrics-service/tests/conftest.py\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"metrics-service/tests/conftest.py\",\n \"hashed_secret\": \"bd33830043487aed705b9aff291a77d69f27adb3\",\n \"is_verified\": false,\n \"line_number\": 98\n }\n ],\n \"metrics-service/tests/test_auth.py\": [\n {\n \"type\": \"Hex High Entropy String\",\n \"filename\": \"metrics-service/tests/test_auth.py\",\n \"hashed_secret\": \"244f421f896bdcdd2784dccf4eaf7c8dfd5189b5\",\n \"is_verified\": false,\n \"line_number\": 151\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"metrics-service/tests/test_auth.py\",\n \"hashed_secret\": \"52adafa10bb9e78a57950036e8b266c51ef8ef88\",\n \"is_verified\": false,\n \"line_number\": 243\n }\n ],\n \"registry/constants.py\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"registry/constants.py\",\n \"hashed_secret\": \"665b1e3851eefefa3fb878654292f16597d25155\",\n \"is_verified\": false,\n \"line_number\": 46\n }\n ],\n \"registry/embeddings/README.md\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"registry/embeddings/README.md\",\n \"hashed_secret\": \"235ca8ecd22dbaae08d2971367bebdc1d1bd0224\",\n \"is_verified\": false,\n \"line_number\": 65\n }\n ],\n \"registry/utils/credential_encryption.py\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"registry/utils/credential_encryption.py\",\n \"hashed_secret\": \"665b1e3851eefefa3fb878654292f16597d25155\",\n \"is_verified\": false,\n \"line_number\": 211\n }\n ],\n \"release-notes/v1.0.9.md\": [\n {\n \"type\": \"Basic Auth Credentials\",\n \"filename\": \"release-notes/v1.0.9.md\",\n \"hashed_secret\": \"5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8\",\n \"is_verified\": false,\n \"line_number\": 104\n }\n ],\n \"scripts/init-mongodb.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"scripts/init-mongodb.sh\",\n \"hashed_secret\": \"d033e22ae348aeb5660fc2140aec35850c4da997\",\n \"is_verified\": false,\n \"line_number\": 27\n }\n ],\n \"scripts/refresh_m2m_token.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"scripts/refresh_m2m_token.sh\",\n \"hashed_secret\": \"2be88ca4242c76e8253ac62474851065032d6833\",\n \"is_verified\": false,\n \"line_number\": 49\n }\n ],\n \"servers/fininfo/README.md\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"servers/fininfo/README.md\",\n \"hashed_secret\": \"af2fdf068ba0c919287d6931c8dc993edaf01f3b\",\n \"is_verified\": false,\n \"line_number\": 24\n }\n ],\n \"terraform/aws-ecs/README.md\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/README.md\",\n \"hashed_secret\": \"4d0d3c53f51abc7660789000a958332860aa8280\",\n \"is_verified\": false,\n \"line_number\": 335\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/README.md\",\n \"hashed_secret\": \"145f85ed29830a933e12fb56dcfb94ce29172f65\",\n \"is_verified\": false,\n \"line_number\": 336\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/README.md\",\n \"hashed_secret\": \"19a4df734b1b7b83858d6002352ba67c91f1f4b5\",\n \"is_verified\": false,\n \"line_number\": 359\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/README.md\",\n \"hashed_secret\": \"8b603b119fa2980e0e6d3b186fe5e7c02d9d9bd1\",\n \"is_verified\": false,\n \"line_number\": 429\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/README.md\",\n \"hashed_secret\": \"c303df00cd0a72b21c62900b758b06fc541664ce\",\n \"is_verified\": false,\n \"line_number\": 803\n }\n ],\n \"terraform/aws-ecs/documentdb-elastic.tf.disabled\": [\n {\n \"type\": \"Basic Auth Credentials\",\n \"filename\": \"terraform/aws-ecs/documentdb-elastic.tf.disabled\",\n \"hashed_secret\": \"347cd9c53ff77d41a7b22aa56c7b4efaf54658e3\",\n \"is_verified\": false,\n \"line_number\": 226\n }\n ],\n \"terraform/aws-ecs/documentdb.tf\": [\n {\n \"type\": \"Basic Auth Credentials\",\n \"filename\": \"terraform/aws-ecs/documentdb.tf\",\n \"hashed_secret\": \"347cd9c53ff77d41a7b22aa56c7b4efaf54658e3\",\n \"is_verified\": false,\n \"line_number\": 356\n }\n ],\n \"terraform/aws-ecs/keycloak-database.tf\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/keycloak-database.tf\",\n \"hashed_secret\": \"f8be3d043f32db05fe41961eb713644aa21b6222\",\n \"is_verified\": false,\n \"line_number\": 13\n }\n ],\n \"terraform/aws-ecs/modules/mcp-gateway/secrets.tf\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/modules/mcp-gateway/secrets.tf\",\n \"hashed_secret\": \"be4c27293b0757101cbef01b36ac78028aefc399\",\n \"is_verified\": false,\n \"line_number\": 56\n }\n ],\n \"terraform/aws-ecs/scripts/init-keycloak.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/scripts/init-keycloak.sh\",\n \"hashed_secret\": \"2be88ca4242c76e8253ac62474851065032d6833\",\n \"is_verified\": false,\n \"line_number\": 1103\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/scripts/init-keycloak.sh\",\n \"hashed_secret\": \"e3eba309413812b94096a6477501e13853a616b4\",\n \"is_verified\": false,\n \"line_number\": 1124\n }\n ],\n \"terraform/aws-ecs/scripts/post-deployment-setup.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/scripts/post-deployment-setup.sh\",\n \"hashed_secret\": \"6eef6648406c333a4035cd5e60d0bf2ecf2606d7\",\n \"is_verified\": false,\n \"line_number\": 469\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/scripts/post-deployment-setup.sh\",\n \"hashed_secret\": \"e3eba309413812b94096a6477501e13853a616b4\",\n \"is_verified\": false,\n \"line_number\": 487\n }\n ],\n \"terraform/aws-ecs/scripts/run-documentdb-cli.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/scripts/run-documentdb-cli.sh\",\n \"hashed_secret\": \"6eef6648406c333a4035cd5e60d0bf2ecf2606d7\",\n \"is_verified\": false,\n \"line_number\": 178\n }\n ],\n \"terraform/aws-ecs/scripts/run-documentdb-init.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/scripts/run-documentdb-init.sh\",\n \"hashed_secret\": \"6eef6648406c333a4035cd5e60d0bf2ecf2606d7\",\n \"is_verified\": false,\n \"line_number\": 179\n }\n ],\n \"terraform/aws-ecs/scripts/user_mgmt.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/scripts/user_mgmt.sh\",\n \"hashed_secret\": \"2be88ca4242c76e8253ac62474851065032d6833\",\n \"is_verified\": false,\n \"line_number\": 261\n }\n ],\n \"terraform/aws-ecs/setup-documentdb-env.sh\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/setup-documentdb-env.sh\",\n \"hashed_secret\": \"d4758e20bc459a501939d69dd4bfa383debac93a\",\n \"is_verified\": false,\n \"line_number\": 20\n }\n ],\n \"terraform/aws-ecs/terraform.tfvars.example\": [\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"b81a4503bd668cde97ef070bfe9cf2baca9872e0\",\n \"is_verified\": false,\n \"line_number\": 53\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"f60d623e416a938ffa3a98bba1d5cdcd38eba18a\",\n \"is_verified\": false,\n \"line_number\": 57\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"01b1a021a74c4b51fe616e4c1487962a96ccaa78\",\n \"is_verified\": false,\n \"line_number\": 184\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"4d0d3c53f51abc7660789000a958332860aa8280\",\n \"is_verified\": false,\n \"line_number\": 201\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"5fe9c3b9f7d89f322a2b0749e74652ec152c05c3\",\n \"is_verified\": false,\n \"line_number\": 205\n },\n {\n \"type\": \"Base64 High Entropy String\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"e5575d5cd84e9e2f6620e721e2b71b88cdb47bba\",\n \"is_verified\": false,\n \"line_number\": 234\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"c303df00cd0a72b21c62900b758b06fc541664ce\",\n \"is_verified\": false,\n \"line_number\": 299\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"a6778f1880744bd1a342a8e3789135412d8f9da2\",\n \"is_verified\": false,\n \"line_number\": 354\n },\n {\n \"type\": \"Secret Keyword\",\n \"filename\": \"terraform/aws-ecs/terraform.tfvars.example\",\n \"hashed_secret\": \"788b6b2bfd50bb3353254fb8a62d7388cf6f7aa6\",\n \"is_verified\": false,\n \"line_number\": 355\n }\n ]\n },\n \"generated_at\": \"2026-03-10T06:00:15Z\"\n}\n" }, { "path": ".semgrepignore", "content": "# Documentation - contains example credentials and test data\ndocs/\n*.md\n\n# Test files - contains test credentials and mock data\n**/test/**\n**/tests/**\n*test*.py\n*test*.sh\n*test*.ts\n*test*.js\ncli/test_*.py\ncli/test_*.sh\nagents/*/test/\n\n# Test configurations\ndocker-compose.federation-test.yml\n\n# Reports and build artifacts - not source code\n*.json\n**/semgrep_report.json\n**/bandit_report.json\nbuild/\ndist/\n.pytest_cache/\n*.log\n\n# Node modules and dependencies\nnode_modules/\n.venv/\nvenv/\nENV/\n\n# CI/CD and generated files\n.github/workflows/\n*.pyc\n__pycache__/\n" }, { "path": "CLAUDE.md", "content": "# Claude Coding Rules\n\n## Overview\nThis document contains coding standards and best practices that must be followed for all code development. These rules prioritize maintainability, simplicity, and modern Python development practices.\n\n## Core Principles\n- Write code with minimal complexity for maximum maintainability and clarity\n- Choose simple, readable solutions over clever or complex implementations\n- Prioritize code that any team member can confidently understand, modify, and debug\n\n## Pull Request Evaluation\n\nWhen evaluating pull requests for merge, adopt the **Merge Specialist** persona defined in [TEAM.md](TEAM.md). This persona provides comprehensive guidelines for:\n\n- Running and verifying tests\n- Assessing code quality against these standards\n- Reviewing architecture and design decisions\n- Checking for breaking changes\n- Evaluating performance impact\n- Ensuring documentation is complete\n\n**IMPORTANT**: Before approving any PR for merge, the Merge Specialist must verify that all tests pass and no existing functionality is broken. A PR with failing tests should NEVER be approved for merge.\n\n## Technology Stack\n\n### Package Management\n- Always use `uv` and `pyproject.toml` for package management\n- Never use `pip` directly\n\n### Modern Python Libraries\n- **Data Processing**: Use `polars` instead of `pandas`\n- **Web APIs**: Use `fastapi` instead of `flask`\n- **Code Formatting/Linting**: Use `ruff` for both linting and formatting\n- **Type Checking**: Use `mypy` - type checks have become actually useful and should be part of CI/CD\n- **Performance**: Leverage modern CPython improvements - CPython is now much faster\n\n## Code Style Guidelines\n\n### Function Structure\n- All internal/private functions must start with an underscore (`_`)\n- Private functions should be placed at the top of the file, followed by public functions\n- Functions should be modular, containing no more than 30-50 lines\n- Use two blank lines between function definitions\n- One function parameter per line for better readability\n\n### Type Annotations\n- Use clear type annotations for all function parameters\n- One function parameter per line for better readability\n- Use modern Python 3.10+ type hint syntax (PEP 604/585)\n- Example:\n ```python\n def process_data(\n input_file: str,\n output_format: str,\n validate: bool = True\n ) -> dict[str, Any]:\n pass\n ```\n\n### Modern Type Hint Standards (Python 3.10+)\n\n**IMPORTANT**: This codebase uses modern Python 3.10+ type hint syntax (PEP 604 and PEP 585). Always use built-in types instead of importing from `typing` module.\n\n#### PEP 604: Union Types with `|`\nUse `X | None` instead of `Optional[X]`:\n\n```python\n# Good - Modern syntax (Python 3.10+)\ndef process_data(\n sample_size: int | None = None,\n language: str | None = None\n) -> list[dict[str, Any]]:\n pass\n\n# Avoid - Legacy syntax\nfrom typing import Optional, List, Dict, Any\n\ndef process_data(\n sample_size: Optional[int] = None,\n language: Optional[str] = None\n) -> List[Dict[str, Any]]:\n pass\n```\n\n#### PEP 585: Built-in Generic Types\nUse `list`, `dict`, `tuple`, `set` directly instead of importing from `typing`:\n\n```python\n# Good - Built-in generic types\ndef process_items(\n data: list[dict[str, Any]],\n filters: set[str],\n metadata: tuple[str, int]\n) -> dict[str, list[Any]]:\n pass\n\n# Avoid - typing module imports\nfrom typing import List, Dict, Set, Tuple, Any\n\ndef process_items(\n data: List[Dict[str, Any]],\n filters: Set[str],\n metadata: Tuple[str, int]\n) -> Dict[str, List[Any]]:\n pass\n```\n\n#### Type Hint Migration Examples\n\n**Example 1: Optional Parameters**\n```python\n# Old style\nfrom typing import Optional\n\ndef get_user(user_id: int, token: Optional[str] = None) -> Optional[dict]:\n pass\n\n# New style - no imports needed\ndef get_user(user_id: int, token: str | None = None) -> dict | None:\n pass\n```\n\n**Example 2: Complex Types**\n```python\n# Old style\nfrom typing import List, Dict, Optional, Tuple\n\ndef process_samples(\n sample_size: Optional[int] = None,\n language: Optional[str] = None\n) -> List[dict]:\n \"\"\"Process dataset samples.\n\n Args:\n sample_size: Number of samples. None uses default, 0 means all.\n language: Language filter. None means all languages.\n \"\"\"\n if sample_size == 0:\n return process_all()\n elif sample_size is None:\n sample_size = DEFAULT_SAMPLE_SIZE\n\n return process_with_size(sample_size)\n\n# New style - cleaner and more Pythonic\ndef process_samples(\n sample_size: int | None = None,\n language: str | None = None\n) -> list[dict[str, Any]]:\n \"\"\"Process dataset samples.\n\n Args:\n sample_size: Number of samples. None uses default, 0 means all.\n language: Language filter. None means all languages.\n \"\"\"\n if sample_size == 0:\n return process_all()\n elif sample_size is None:\n sample_size = DEFAULT_SAMPLE_SIZE\n\n return process_with_size(sample_size)\n```\n\n**Example 3: Nested Generic Types**\n```python\n# Old style\nfrom typing import Dict, List, Tuple, Optional\n\ndef get_user_data(\n user_id: int\n) -> Optional[Dict[str, List[Tuple[str, int]]]]:\n pass\n\n# New style - much cleaner\ndef get_user_data(\n user_id: int\n) -> dict[str, list[tuple[str, int]]] | None:\n pass\n```\n\n#### Benefits of Modern Type Hints\n1. **Fewer imports**: No need to import from `typing` for basic types\n2. **More readable**: `X | None` is clearer than `Optional[X]`\n3. **Consistent with Python evolution**: PEP 585 and PEP 604 are the future\n4. **Better IDE support**: Native type inference without imports\n5. **Simpler syntax**: Less typing, easier to understand\n\n### Class Definitions with Pydantic\n- Consider using Pydantic BaseModel for all class definitions to leverage validation, serialization, and other powerful features\n- Pydantic provides automatic validation, type coercion, and serialization capabilities\n- Use modern type hints (PEP 604/585) in Pydantic models\n- Example:\n ```python\n from pydantic import BaseModel, Field, validator\n\n class UserConfig(BaseModel):\n \"\"\"User configuration settings.\"\"\"\n\n username: str = Field(..., min_length=3, max_length=50)\n email: str = Field(..., regex=r'^[\\w\\.-]+@[\\w\\.-]+\\.\\w+$')\n timeout_seconds: int = Field(default=30, ge=1, le=300)\n debug_enabled: bool = False\n tags: list[str] = Field(default_factory=list)\n metadata: dict[str, str] | None = None\n\n @validator('username')\n def username_alphanumeric(cls, v: str) -> str:\n if not v.replace('_', '').isalnum():\n raise ValueError('Username must be alphanumeric')\n return v.lower()\n ```\n\n### Main Function Pattern\n- The main function should act as a control flow orchestrator\n- Parse command line arguments and delegate to other functions\n- Avoid implementing business logic directly in main()\n\n### Command-Line Interface Design\nWhen creating CLI applications:\n\n1. **Use argparse with comprehensive help**:\n ```python\n parser = argparse.ArgumentParser(\n description=\"Clear description of what the tool does\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\n Example usage:\n # Basic usage\n uv run python -m module --param value\n \n # With environment variable\n export PARAM=value\n uv run python -m module\n \"\"\"\n )\n ```\n\n2. **Support both CLI args and environment variables**:\n ```python\n def _get_config_value(cli_value: Optional[str] = None) -> str:\n if cli_value:\n return cli_value\n \n env_value = os.getenv(\"CONFIG_VAR\")\n if env_value:\n return env_value\n \n raise ValueError(\"Value must be provided via --param or CONFIG_VAR env var\")\n ```\n\n3. **Provide sensible defaults**:\n ```python\n parser.add_argument(\n \"--sample-size\",\n type=int,\n help=f\"Number of samples (default: {DEFAULT_SIZE}). Use 0 for all\",\n )\n ```\n\n4. **Use special values for \"all\" options**:\n ```python\n if sample_size == 0 or sample_size is None:\n # Process entire dataset\n else:\n # Process sample\n ```\n\n### Imports\n- Write imports as multi-line imports for better readability\n- Example:\n ```python\n from .services.output_formatter import (\n _display_evaluation_results,\n _print_results_summary,\n _check_mcp_generation_criteria\n )\n ```\n\n### Constants\n- Don't hard code constants within functions\n- For trivial constants, declare them at the top of the file:\n ```python\n STARTUP_DELAY: int = 10\n MAX_RETRIES: int = 3\n ```\n- For many constants, create a separate `constants.py` file with a class structure\n\n### Logging Configuration\n- Always use the following logging configuration:\n ```python\n import logging\n \n # Configure logging with basicConfig\n logging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n )\n ```\n\n### Logging Best Practices\n- Add sufficient log messages throughout the code to aid in debugging and monitoring\n- Don't shy away from adding debug logs using `logging.debug()` for detailed tracing\n- When printing a dictionary as part of a trace message, always pretty print it:\n ```python\n logger.info(f\"Processing data:\\n{json.dumps(data_dict, indent=2, default=str)}\")\n ```\n- Consider adding a `--debug` flag to the application that sets the logging level to DEBUG:\n ```python\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n ```\n\n### Performance Feedback\nProvide users with feedback on long-running operations:\n\n1. **Display elapsed time after completion**:\n ```python\n start_time = time.time()\n # ... perform operation ...\n elapsed_time = time.time() - start_time\n minutes = int(elapsed_time // 60)\n seconds = elapsed_time % 60\n \n if minutes > 0:\n logger.info(f\"Completed in {minutes} minutes and {seconds:.1f} seconds\")\n else:\n logger.info(f\"Completed in {seconds:.1f} seconds\")\n ```\n\n2. **Warn about potentially long operations**:\n ```python\n if processing_full_dataset:\n logger.warning(\"Processing FULL dataset. This may take a long time.\")\n else:\n logger.info(f\"Processing {sample_size} samples.\")\n ```\n\n3. **Show configuration at startup**:\n ```python\n logger.info(f\"Configuration: {config.model_dump()}\")\n ```\n\n### Performance Optimization\n- Use `@lru_cache` decorator where appropriate for expensive computations\n\n### External Resource Management\nWhen working with external data sources (APIs, datasets, databases):\n\n1. **Version/pin external dependencies**:\n ```python\n # Specify exact versions or commits for reproducibility\n API_VERSION = \"v2\"\n SCHEMA_VERSION = \"2024-01-15\"\n ```\n\n2. **Document external resources in code**:\n ```python\n # Constants file with clear documentation\n DATA_SOURCE: str = \"source-name\" # Documentation URL: https://...\n API_ENDPOINT: str = \"https://api.example.com/v1\" # API docs: https://...\n ```\n\n3. **Handle data filtering and edge cases gracefully**:\n ```python\n def load_filtered_data(\n filters: Dict[str, Any],\n limit: Optional[int] = None\n ) -> List[dict]:\n data = fetch_from_source()\n \n # Apply filters with clear feedback\n for key, value in filters.items():\n filtered = [item for item in data if item.get(key) == value]\n logger.info(f\"Filter '{key}={value}': {len(data)} -> {len(filtered)} items\")\n data = filtered\n \n if not data:\n raise ValueError(f\"No data found matching filters: {filters}\")\n \n # Handle size limits\n if limit and len(data) < limit:\n logger.warning(f\"Only {len(data)} items available (requested: {limit})\")\n \n return data[:limit] if limit else data\n ```\n\n4. **Provide actionable error messages**:\n ```python\n if not data:\n raise ValueError(\n f\"No data retrieved from {DATA_SOURCE}. \"\n f\"Check connection and credentials. \"\n f\"Documentation: {DOCS_URL}\"\n )\n ```\n\n### Decorators and Functional Patterns\n\n#### Guidelines for Using Decorators and Functional Patterns Appropriately\n\n**Use Decorators When:**\n- They're built-in or widely known (`@property`, `@staticmethod`, `@dataclass`)\n- They have a single, clear purpose (`@login_required`, `@cache`)\n- They don't change function behavior dramatically\n\nExample - Good use of decorators:\n```python\n# Good - clear, single purpose\n@dataclass\nclass User:\n name: str\n email: str\n\n@lru_cache(maxsize=128)\ndef expensive_calculation(n: int) -> int:\n return sum(i**2 for i in range(n))\n```\n\n**Use Functional Patterns When:**\n- Simple transformations are clearer than loops\n- You need pure functions for testing\n- The functional approach is more readable\n\nExample - Good use of functional patterns:\n```python\n# Good - simple and clear\nnumbers = [1, 2, 3, 4, 5]\nsquared = [n**2 for n in numbers]\nevens = [n for n in numbers if n % 2 == 0]\n\n# Good - simple map operation\nnames = [\"alice\", \"bob\", \"charlie\"]\ncapitalized = list(map(str.capitalize, names))\n```\n\n**Avoid When:**\n- You're chaining multiple complex operations\n- The code requires explaining how it works\n- An entry-level developer would struggle to modify it\n- You're using advanced functional programming concepts\n\nExample - Avoid complex patterns:\n```python\n# Bad - too complex, hard to understand\nresult = reduce(lambda x, y: x + y, \n filter(lambda x: x % 2 == 0,\n map(lambda x: x**2, range(10))))\n\n# Good - clear and simple\ntotal = 0\nfor i in range(10):\n squared = i ** 2\n if squared % 2 == 0:\n total += squared\n```\n\n#### Avoid Deep Nesting\n- Limit nesting to 2-3 levels maximum\n- Extract nested logic into well-named functions\n- Use early returns to reduce nesting\n\nExample - Reducing nesting:\n```python\n# Bad - too much nesting\ndef process_data(data):\n if data:\n if data.get(\"users\"):\n for user in data[\"users\"]:\n if user.get(\"active\"):\n if user.get(\"email\"):\n send_email(user[\"email\"])\n\n# Good - reduced nesting with early returns\ndef process_data(data):\n if not data:\n return\n \n users = data.get(\"users\", [])\n if not users:\n return\n \n for user in users:\n _process_active_user(user)\n\ndef _process_active_user(user):\n if not user.get(\"active\"):\n return\n \n email = user.get(\"email\")\n if email:\n send_email(email)\n```\n\n### Code Validation\n- Always run `uv run python -m py_compile ` after making changes to Python files\n- Always run `bash -n ` after making changes to bash/shell scripts to check syntax\n\n## Error Handling and Exceptions\n\n### Exception Handling Principles\n- Use specific exception types, avoid bare `except:` clauses\n- Always log exceptions with proper context\n- Fail fast and fail clearly - don't suppress errors silently\n- Use custom exceptions for domain-specific errors\n\n### Exception Pattern\n```python\nimport logging\n\nlogger = logging.getLogger(__name__)\n\nclass DomainSpecificError(Exception):\n \"\"\"Base exception for our application\"\"\"\n pass\n\ndef process_data(data: dict) -> dict:\n try:\n # Process data\n result = _validate_and_transform(data)\n return result\n except ValidationError as e:\n logger.error(f\"Validation failed for data: {e}\")\n raise DomainSpecificError(f\"Invalid input data: {e}\") from e\n except Exception as e:\n logger.exception(\"Unexpected error in process_data\")\n raise\n```\n\n### Error Messages\n- Write clear, actionable error messages\n- Include context about what was being attempted\n- Suggest possible solutions when appropriate\n\n## Testing Standards\n\n### Testing Framework\n- Use `pytest` as the primary testing framework\n- Maintain minimum 80% code coverage\n- Use `pytest-cov` for coverage reporting\n\n### Test Structure\n```python\nimport pytest\nfrom unittest.mock import Mock, patch\n\nclass TestFeatureName:\n \"\"\"Tests for feature_name module\"\"\"\n \n def test_happy_path(self):\n \"\"\"Test normal operation with valid inputs\"\"\"\n # Arrange\n input_data = {\"key\": \"value\"}\n \n # Act\n result = function_under_test(input_data)\n \n # Assert\n assert result[\"status\"] == \"success\"\n \n def test_edge_case(self):\n \"\"\"Test boundary conditions\"\"\"\n pass\n \n def test_error_handling(self):\n \"\"\"Test error scenarios\"\"\"\n with pytest.raises(ValueError, match=\"Invalid input\"):\n function_under_test(None)\n```\n\n### Testing Best Practices\n- Follow AAA pattern: Arrange, Act, Assert\n- One assertion per test when possible\n- Use descriptive test names that explain what is being tested\n- Mock external dependencies\n- Use fixtures for common test data\n- Test both happy paths and error cases\n\n### Running Tests Before Pull Requests\n\n**CRITICAL**: Always run the full test suite before submitting a pull request or after completing a major feature.\n\n#### When to Run Tests\n1. **Before submitting a pull request**: All tests must pass before creating a PR\n2. **After completing a major feature**: Verify no regressions were introduced\n3. **After making significant refactoring changes**: Ensure existing functionality still works\n4. **After updating dependencies**: Verify compatibility with new versions\n\n#### How to Run Tests\nRun the complete test suite with parallel execution:\n\n```bash\n# Run all tests in parallel (using 8 workers)\nuv run pytest tests/ -n 8\n\n# Expected output (as of 2026-01-06):\n# - 701 passed\n# - 57 skipped\n# - Coverage: ~39.50%\n# - Execution time: ~30 seconds\n```\n\n#### Test Execution Options\n```bash\n# Run tests serially (slower, but uses less memory)\nuv run pytest tests/\n\n# Run only unit tests\nuv run pytest tests/unit/\n\n# Run only integration tests\nuv run pytest tests/integration/\n\n# Run with verbose output\nuv run pytest tests/ -n 8 -v\n\n# Run and stop at first failure\nuv run pytest tests/ -n 8 -x\n\n# Run with coverage report\nuv run pytest tests/ -n 8 --cov=registry --cov-report=term-missing\n```\n\n#### Test Prerequisites\nBefore running tests, ensure:\n\n1. **MongoDB is running** (for integration tests):\n ```bash\n docker ps | grep mongo\n # Should show: mcp-mongodb running on 0.0.0.0:27017\n ```\n\n2. **Test environment is configured**:\n - Tests automatically set `DOCUMENTDB_HOST=localhost`\n - Tests use `mongodb-ce` storage backend\n - Tests use `directConnection=true` for single-node MongoDB\n\n#### Continuous Integration\nTests run automatically via GitHub Actions when:\n- Pull requests are created targeting `main` or `develop` branches\n- Code is pushed to `main` or `develop` branches\n\nSee [.github/workflows/registry-test.yml](.github/workflows/registry-test.yml:7-8) for CI configuration.\n\n#### Acceptable Test Results\n- **All unit tests must pass** (no failures allowed in unit tests)\n- **Integration tests**: Some tests may be skipped due to known issues\n- **Coverage**: Minimum 35% coverage required (configured in pyproject.toml:87)\n- **Warnings**: Minor warnings are acceptable, but investigate new warnings\n\n#### What to Do If Tests Fail\n1. Review the test failure output carefully\n2. Fix the failing test(s) before submitting PR\n3. Re-run tests to verify the fix\n4. Never submit a PR with failing tests\n5. If a test failure is unrelated to your changes, investigate and fix it or document why it should be skipped\n\n## Async/Await Best Practices\n\n### Async Code Structure\n```python\nimport asyncio\nfrom typing import List\n\nasync def fetch_data(url: str) -> dict:\n \"\"\"Fetch data from URL asynchronously\"\"\"\n async with aiohttp.ClientSession() as session:\n async with session.get(url) as response:\n return await response.json()\n\nasync def process_urls(urls: List[str]) -> List[dict]:\n \"\"\"Process multiple URLs concurrently\"\"\"\n tasks = [fetch_data(url) for url in urls]\n return await asyncio.gather(*tasks, return_exceptions=True)\n```\n\n### Async Guidelines\n- Use `async with` for async context managers\n- Use `asyncio.gather()` for concurrent operations\n- Handle exceptions in async code properly\n- Don't mix blocking and async code\n- Use `asyncio.run()` to run async functions from sync code\n\n## Documentation Standards\n\n### Docstring Format\nUse Google-style docstrings:\n```python\ndef calculate_metrics(\n data: List[float],\n threshold: float = 0.5\n) -> Dict[str, float]:\n \"\"\"Calculate statistical metrics for the given data.\n \n Args:\n data: List of numerical values to analyze\n threshold: Minimum value to include in calculations\n \n Returns:\n Dictionary containing calculated metrics:\n - mean: Average value\n - std: Standard deviation\n - count: Number of values above threshold\n \n Raises:\n ValueError: If data is empty or contains non-numeric values\n \n Example:\n >>> metrics = calculate_metrics([1.0, 2.0, 3.0])\n >>> print(metrics['mean'])\n 2.0\n \"\"\"\n pass\n```\n\n### Documentation Requirements\n- All public functions must have docstrings\n- Include type hints in function signatures\n- Document exceptions that can be raised\n- Provide usage examples for complex functions\n- Keep docstrings up-to-date with code changes\n\n## Security Guidelines\n\n### Input Validation\n- Always validate and sanitize user inputs\n- Use Pydantic models for request/response validation\n- Never trust external data\n\n### Secrets Management\n```python\nimport os\nfrom typing import Optional\n\ndef get_secret(key: str, default: Optional[str] = None) -> str:\n \"\"\"Retrieve secret from environment variable.\n \n Never hardcode secrets in source code.\n \"\"\"\n value = os.environ.get(key, default)\n if value is None:\n raise ValueError(f\"Required secret '{key}' not found in environment\")\n return value\n```\n\n### Security Best Practices\n- Never log sensitive information (passwords, tokens, PII)\n- Use environment variables for configuration\n- Validate all inputs, especially from external sources\n- Use parameterized queries for database operations\n- Keep dependencies updated for security patches\n\n### Security Scanning with Bandit\n- Run Bandit regularly as part of the development workflow\n- Handle false positives with `# nosec` comments and clear justification\n- Common patterns to handle:\n ```python\n # When using random for ML reproducibility (not cryptography)\n # This is not for security/cryptographic purposes - nosec B311\n random.seed(random_seed)\n samples = random.sample(dataset, size) # nosec B311\n \n # When loading from trusted sources with version pinning\n # This is acceptable for evaluation tools using well-known datasets - nosec B615\n ds = load_dataset(DATASET_NAME, revision=\"main\") # nosec B615\n ```\n- Run security scans with: `uv run bandit -r src/`\n\n### Server Binding Security\n- When starting a server, never bind it to `0.0.0.0` unless absolutely necessary\n- Prefer binding to `127.0.0.1` for local-only access\n- If external access is needed, bind to the specific private IP address:\n ```python\n # Bad - exposes to all interfaces\n app.run(host=\"0.0.0.0\", port=8000)\n \n # Good - local only\n app.run(host=\"127.0.0.1\", port=8000)\n \n # Good - specific private IP\n import socket\n private_ip = socket.gethostbyname(socket.gethostname())\n app.run(host=private_ip, port=8000)\n ```\n\n### Subprocess Security Guidelines\n\nWhen using the `subprocess` module, follow these security patterns to prevent Bandit B603/B607 findings and avoid shell injection vulnerabilities.\n\n#### ✅ ALWAYS Use List Form (Not String Commands)\n\n```python\n# Good - list form prevents shell injection\nresult = subprocess.run(\n [\"nginx\", \"-s\", \"reload\"],\n capture_output=True,\n text=True,\n timeout=5,\n)\n\n# Bad - string form with shell=True is vulnerable to injection\nresult = subprocess.run(\"nginx -s reload\", shell=True) # NEVER DO THIS\n```\n\n#### ✅ ALWAYS Add Timeout\n\n```python\n# Good - prevents DoS from hanging processes\nresult = subprocess.run(cmd, timeout=30, capture_output=True)\n\n# Bad - no timeout can cause infinite hangs\nresult = subprocess.run(cmd, capture_output=True) # Missing timeout!\n```\n\n#### ✅ ALWAYS Handle Errors\n\n```python\n# Good - proper error handling\ntry:\n result = subprocess.run(\n cmd,\n capture_output=True,\n text=True,\n check=True, # Raises CalledProcessError on non-zero exit\n timeout=30,\n )\nexcept subprocess.TimeoutExpired:\n logger.error(\"Command timed out\")\n return False\nexcept subprocess.CalledProcessError as e:\n logger.error(f\"Command failed: {e.stderr}\")\n return False\n```\n\n#### ✅ Approved Subprocess Patterns\n\n**Pattern 1: System Utilities (hardcoded commands)**\n```python\n# System commands with hardcoded paths and flags\nresult = subprocess.run(\n [\"nginx\", \"-t\"], # nosec B603 B607 - hardcoded command\n capture_output=True,\n text=True,\n timeout=5,\n)\n\nresult = subprocess.run(\n [\"hostname\", \"-I\"], # nosec B603 B607 - hardcoded command\n capture_output=True,\n text=True,\n timeout=2,\n)\n```\n\n**Pattern 2: Internal Scripts (controlled paths)**\n```python\n# Internal scripts with validated arguments\nscript_path = os.path.join(project_root, \"scripts/generate_token.sh\")\nresult = subprocess.run(\n [script_path, validated_arg], # nosec B603 - hardcoded internal script path\n capture_output=True,\n text=True,\n timeout=30,\n cwd=working_directory,\n)\n```\n\n**Pattern 3: External Tools (hardcoded flags, data as arguments)**\n```python\n# External tools with hardcoded flags - user data passed as arguments, not commands\ncmd = [\"mcp-scanner\", \"--format\", \"json\", \"--url\", user_provided_url]\nresult = subprocess.run( # nosec B603 - args are hardcoded flags passed to mcp-scanner tool\n cmd,\n capture_output=True,\n text=True,\n check=True,\n timeout=60,\n)\n```\n\n#### ✅ Security Comment Standards for Subprocess\n\nWhen suppressing Bandit warnings for subprocess calls, **always include a clear justification**:\n\n```python\n# Good - explains why it's safe\nsubprocess.run(\n [\"nginx\", \"-s\", \"reload\"],\n ...\n) # nosec B603 B607 - hardcoded command\n\n# Good - explains the security model\nsubprocess.run(\n [script_path, arg],\n ...\n) # nosec B603 - hardcoded internal script path\n\n# Good - explains what's hardcoded\nsubprocess.run(\n cmd,\n ...\n) # nosec B603 - args are hardcoded flags passed to tool\n\n# Bad - no justification\nsubprocess.run(cmd, ...) # nosec B603\n```\n\n**Valid Justification Templates:**\n- `# nosec B603 B607 - hardcoded command` - for system utilities (nginx, hostname, etc.)\n- `# nosec B603 - hardcoded internal script path` - for internal project scripts\n- `# nosec B603 - hardcoded internal script path and flags` - when both path and flags are hardcoded\n- `# nosec B603 - args are hardcoded flags passed to [tool-name]` - for external tools\n\n#### ❌ NEVER Do These With Subprocess\n\n```python\n# NEVER use shell=True with any user input\nuser_cmd = f\"tool --arg {user_input}\"\nsubprocess.run(user_cmd, shell=True) # VULNERABLE TO INJECTION\n\n# NEVER construct commands from user input\ncmd = f\"grep {user_search_term} file.txt\" # VULNERABLE\nsubprocess.run(cmd, shell=True)\n\n# NEVER skip timeout - can hang forever\nsubprocess.run([\"long-running-command\"]) # NO TIMEOUT\n\n# NEVER ignore errors without logging\nresult = subprocess.run(cmd, capture_output=True)\n# No error handling - failures go unnoticed\n```\n\n### SQL Security Guidelines\n\nWhen working with databases, follow these patterns to prevent SQL injection vulnerabilities (Bandit B608).\n\n#### ✅ ALWAYS Use Parameterized Queries\n\n```python\n# Good - parameterized query with placeholders\ncutoff = datetime.now().isoformat()\nquery = \"DELETE FROM table_name WHERE created_at < ?\"\ncursor.execute(query, (cutoff,))\n\n# Bad - string formatting is vulnerable to SQL injection\ncutoff_str = f\"'{datetime.now().isoformat()}'\"\nquery = f\"DELETE FROM table_name WHERE created_at < {cutoff_str}\" # VULNERABLE\ncursor.execute(query)\n```\n\n#### ✅ Validate Identifiers Against Allowlists\n\nFor table names and column names that cannot be parameterized, use allowlist validation:\n\n```python\n# Define allowlists for table and column names\nALLOWED_TABLES = {\"users\", \"metrics\", \"auth_logs\"}\nALLOWED_COLUMNS = {\"created_at\", \"updated_at\", \"timestamp\"}\n\ndef validate_table_name(table: str) -> str:\n \"\"\"Validate table name against allowlist.\"\"\"\n if table not in ALLOWED_TABLES:\n raise ValueError(f\"Invalid table: {table}\")\n return table\n\ndef validate_column_name(column: str) -> str:\n \"\"\"Validate column name against allowlist.\"\"\"\n if column not in ALLOWED_COLUMNS:\n raise ValueError(f\"Invalid column: {column}\")\n return column\n\n# Use validated identifiers with nosec comment\ntable = validate_table_name(user_provided_table)\ncolumn = validate_column_name(user_provided_column)\nquery = f\"SELECT * FROM {table} WHERE {column} = ?\" # nosec B608 - table and column validated against allowlists\ncursor.execute(query, (value,))\n```\n\n#### ✅ Return Query and Parameters as Tuple\n\nFor query-building methods, return both query string and parameters:\n\n```python\ndef get_cleanup_query(\n table_name: str,\n days: int\n) -> tuple[str, tuple]:\n \"\"\"Get cleanup query and parameters.\n\n Returns:\n Tuple of (query_string, parameters)\n \"\"\"\n # Validate table name against allowlist\n table_name = validate_table_name(table_name)\n\n # Calculate cutoff date\n cutoff = (datetime.now() - timedelta(days=days)).isoformat()\n\n # Build parameterized query\n query = f\"DELETE FROM {table_name} WHERE created_at < ?\" # nosec B608 - table_name validated against allowlist\n\n return query, (cutoff,)\n\n# Use the query and parameters\nquery, params = get_cleanup_query(\"metrics\", 90)\ncursor.execute(query, params)\n```\n\n#### ✅ Security Comment Standards for SQL\n\nWhen suppressing B608 warnings, **always document the validation**:\n\n```python\n# Good - documents allowlist validation\nquery = f\"SELECT * FROM {table}\" # nosec B608 - table name validated against allowlist\ncursor.execute(query, params)\n\n# Good - references validation function\nquery = f\"DELETE FROM {table}\" # nosec B608 - table validated by validate_table_name()\ncursor.execute(query, params)\n\n# Good - explains multiple validations\nquery = f\"SELECT {column} FROM {table}\" # nosec B608 - table and column validated against allowlists\ncursor.execute(query, params)\n\n# Bad - no justification\nquery = f\"SELECT * FROM {table}\" # nosec B608\ncursor.execute(query)\n```\n\n**Valid Justification Templates:**\n- `# nosec B608 - table name validated against allowlist`\n- `# nosec B608 - column name validated against allowlist`\n- `# nosec B608 - table and column validated against allowlists`\n- `# nosec B608 - identifier validated by _validate_identifier()`\n\n#### ❌ NEVER Do These With SQL\n\n```python\n# NEVER use string formatting for values\nvalue = user_input\nquery = f\"SELECT * FROM users WHERE name = '{value}'\" # VULNERABLE TO SQL INJECTION\ncursor.execute(query)\n\n# NEVER concatenate user input into queries\nquery = \"SELECT * FROM \" + user_table + \" WHERE id = \" + user_id # VULNERABLE\ncursor.execute(query)\n\n# NEVER skip validation for identifiers\ntable = request.args.get('table') # No validation!\nquery = f\"SELECT * FROM {table}\" # VULNERABLE\ncursor.execute(query)\n\n# NEVER use datetime() SQL functions with interpolated values\ndays = user_input\nquery = f\"DELETE FROM t WHERE created_at < datetime('now', '-{days} days')\" # VULNERABLE\ncursor.execute(query)\n```\n\n### Security Checklist for Code Review\n\nWhen reviewing code with subprocess or SQL operations, verify:\n\n**Subprocess Checklist:**\n- [ ] Using list form (not string commands)\n- [ ] No `shell=True` anywhere\n- [ ] Timeout specified\n- [ ] Error handling includes `TimeoutExpired` and `CalledProcessError`\n- [ ] Commands are hardcoded (no dynamic construction from user input)\n- [ ] `# nosec` comments include clear justifications\n- [ ] Arguments passed as list elements (not interpolated into commands)\n\n**SQL Checklist:**\n- [ ] Using parameterized queries for all values\n- [ ] Table and column names validated against allowlists\n- [ ] No string formatting or concatenation for SQL values\n- [ ] Query methods return `tuple[str, tuple]`\n- [ ] `# nosec` comments document validation method\n- [ ] No datetime() SQL functions with interpolated parameters\n\n## Development Workflow\n\n### Recommended Development Tools\n- **Ruff**: For linting and formatting (replaces multiple tools like isort and many flake8 plugins)\n- **Bandit**: For security vulnerability scanning\n- **MyPy**: For type checking\n- **Pytest**: For testing\n\n### Pre-commit Workflow\n\n#### Option 1: Automated Pre-commit Hooks (Recommended)\n\nInstall pre-commit hooks to automatically run checks before each commit:\n\n```bash\n# Install pre-commit (one-time setup)\nuv pip install pre-commit\n\n# Install the git hooks (one-time per repo clone)\npre-commit install\n\n# Now all checks run automatically on git commit\ngit add file.py\ngit commit -m \"Your message\" # Hooks run automatically\n\n# Run hooks manually on all files\npre-commit run --all-files\n```\n\n**What runs automatically:**\n- ✅ Ruff linter with auto-fixes\n- ✅ Ruff formatter (PEP 604/585 modernization)\n- ✅ Trailing whitespace removal\n- ✅ End-of-file fixes\n- ✅ YAML/JSON validation\n- ✅ Bandit security scan\n- ✅ MyPy type checking\n- ✅ Fast unit tests\n- ✅ Python/shell syntax checks\n\n#### Option 2: Manual Workflow\n\nBefore committing code, run these checks in order:\n\n```bash\n# 1. Format and lint with auto-fixes\nuv run ruff check --fix . && uv run ruff format .\n\n# 2. Security scanning\nuv run bandit -r src/\n\n# 3. Type checking\nuv run mypy src/\n\n# 4. Run tests\nuv run pytest\n\n# Or run all checks in one command:\nuv run ruff check --fix . && uv run ruff format . && uv run bandit -r src/ && uv run mypy src/ && uv run pytest\n```\n\n### Code Formatting Standards\n\n**Ruff Configuration**: This project uses ruff for formatting with the following key settings (see `pyproject.toml`):\n\n- **Target Python**: 3.10+ (enables PEP 604/585)\n- **Line Length**: 100 characters\n- **Type Hint Modernization**: Automatic via ruff rules:\n - `UP006`: Use PEP 585 built-in generics (`list`, `dict`, `tuple`)\n - `UP007`: Use PEP 604 union syntax (`X | Y` instead of `Union[X, Y]`)\n - `UP037`: Remove quotes from type annotations\n - `I001`: Auto-sort imports (isort compatible)\n\n**Formatting automatically handles:**\n- Type hint modernization (PEP 604/585)\n- Import organization (stdlib, third-party, local)\n- Trailing whitespace removal\n- Consistent indentation (4 spaces)\n- Line length enforcement\n- Docstring formatting\n\n**Example ruff modernizations:**\n```python\n# Before ruff format\nfrom typing import Optional, List, Dict\ndef func(x: Optional[List[Dict]]) -> Optional[str]: pass\n\n# After ruff format (automatic)\ndef func(x: list[dict] | None) -> str | None: pass\n```\n\n### Adding Development Dependencies\n```bash\n# Add development dependencies\nuv add --dev ruff mypy bandit pytest pytest-cov pre-commit\n```\n\n## Dependency Management\n\n### Project Configuration\nAlways specify Python version in `pyproject.toml` to avoid warnings:\n```toml\n[project]\nname = \"project-name\"\nversion = \"0.1.0\"\ndescription = \"Project description\"\nrequires-python = \">=3.14\" # Always specify this!\ndependencies = [\n # ... dependencies\n]\n```\n\n### Version Pinning\nIn `pyproject.toml`:\n```toml\n[project]\ndependencies = [\n \"fastapi>=0.100.0,<0.200.0\", # Minor version flexibility\n \"pydantic==2.5.0\", # Exact version for critical dependencies\n \"polars>=0.19.0\", # Minimum version only\n]\n\n[tool.uv]\ndev-dependencies = [\n \"pytest>=7.0.0\",\n \"ruff>=0.1.0\",\n \"mypy>=1.0.0\",\n \"bandit>=1.7.0\",\n]\n```\n\n### Dependency Guidelines\n- Pin exact versions for critical dependencies\n- Use version ranges for stable libraries\n- Separate dev dependencies from runtime dependencies\n- Regularly update dependencies for security patches\n- Document why specific versions are pinned\n\n## Project Structure\n\n### Standard Layout\n```\nproject_name/\n├── src/\n│ └── project_name/\n│ ├── __init__.py\n│ ├── main.py\n│ ├── models/\n│ │ ├── __init__.py\n│ │ └── domain.py\n│ ├── services/\n│ │ ├── __init__.py\n│ │ └── business_logic.py\n│ ├── api/\n│ │ ├── __init__.py\n│ │ └── endpoints.py\n│ └── utils/\n│ ├── __init__.py\n│ └── helpers.py\n├── tests/\n│ ├── __init__.py\n│ ├── conftest.py\n│ ├── unit/\n│ └── integration/\n├── scripts/\n│ └── deploy.sh\n├── docs/\n├── pyproject.toml\n├── README.md\n└── .env.example\n```\n\n### Module Organization\n- Keep related functionality together\n- Use clear, descriptive module names\n- Avoid circular imports\n- Keep modules focused on a single responsibility\n\n### Comprehensive .gitignore\nEnsure your `.gitignore` includes all necessary entries:\n\n```gitignore\n# Python\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n.Python\nbuild/\ndist/\n*.egg-info/\n*.egg\n\n# Virtual environments\n.env\n.venv\nenv/\nvenv/\nENV/\n\n# Testing and linting caches\n.ruff_cache/\n.mypy_cache/\n.pytest_cache/\n.coverage\nhtmlcov/\n\n# Security reports\nbandit_report.json\n\n# IDE\n.vscode/\n.idea/\n*.swp\n*.swo\n\n# OS\n.DS_Store\nThumbs.db\n\n# Project specific\n*.csv # Or specific output files\n.scratchpad/\nlogs/\noutput/\n\n# AWS\n.aws/\n```\n\n## Scratchpad for Planning & Design\n\nThe `.scratchpad/` folder contains intermediate and temporary documents used during development that are not meant for long-term storage or committed to the repository.\n\n**Contents:**\n- Design discussions and architecture sketches\n- Todo lists and task planning documents\n- GitHub issue creation planning\n- LinkedIn posts and social media drafts\n- Session notes and decision logs\n- Meeting minutes and action items\n- Prototype diagrams and brainstorming documents\n- Any other context-specific content created during active work\n\n**Important:**\n- `.scratchpad/` is in `.gitignore` and will NOT be committed\n- These files are temporary and may be deleted at any time\n- Only relevant within the context of current work sessions\n- Not suitable for documentation or long-term reference\n- Use for active planning, not for finalized documentation\n\n**Naming Convention:**\n- Design files: `design-feature-name.md` or `design-YYYY-MM-DD.md`\n- Planning files: `plan-feature-name.md` or `task-status.md`\n- Drafts: `draft-linkedin-post.md`, `draft-github-issue.md`\n- Notes: `session-notes-YYYY-MM-DD.md`, `meeting-minutes.md`\n- Sub-tasks: `sub-tasks-issue-NUMBER-feature-name.md`\n\n## Environment Configuration\n\n### Environment Variables\n```python\nfrom pydantic import BaseSettings\nfrom typing import Optional\n\nclass Settings(BaseSettings):\n \"\"\"Application settings from environment variables.\"\"\"\n \n app_name: str = \"MyApp\"\n debug: bool = False\n database_url: str\n api_key: str\n redis_url: Optional[str] = None\n \n class Config:\n env_file = \".env\"\n env_file_encoding = \"utf-8\"\n case_sensitive = False\n\n# Global settings instance\nsettings = Settings()\n```\n\n### Configuration Best Practices\n- Use Pydantic Settings for type-safe configuration\n- Provide `.env.example` with all required variables\n- Never commit `.env` files to version control\n- Document all environment variables\n- Use sensible defaults where appropriate\n\n## Data Validation with Pydantic\n\n### Model Definition\n```python\nfrom pydantic import BaseModel, Field, validator\nfrom typing import Optional\nfrom datetime import datetime\n\nclass UserRequest(BaseModel):\n \"\"\"User creation request model.\"\"\"\n \n username: str = Field(..., min_length=3, max_length=50)\n email: str = Field(..., regex=r'^[\\w\\.-]+@[\\w\\.-]+\\.\\w+$')\n age: Optional[int] = Field(None, ge=0, le=150)\n created_at: datetime = Field(default_factory=datetime.utcnow)\n \n @validator('username')\n def username_alphanumeric(cls, v: str) -> str:\n if not v.replace('_', '').isalnum():\n raise ValueError('Username must be alphanumeric')\n return v.lower()\n \n class Config:\n json_schema_extra = {\n \"example\": {\n \"username\": \"john_doe\",\n \"email\": \"john@example.com\",\n \"age\": 25\n }\n }\n```\n\n### Validation Guidelines\n- Use Pydantic for all API request/response models\n- Define clear validation rules with Field()\n- Use custom validators for complex logic\n- Provide examples in model configuration\n- Return validation errors with clear messages\n\n## Platform Naming\n- Always refer to the service as \"Amazon Bedrock\" (never \"AWS Bedrock\")\n\n## GitHub Commit and Pull Request Guidelines\n- Never include auto-generated messages like \"🤖 Generated with [Claude Code]\"\n- Never include \"Co-Authored-By: Claude \"\n- Keep commit messages clean and professional\n- When creating pull requests, do not include Claude Code attribution or generation messages\n- Pull request descriptions should be professional and focus on the technical changes\n\n## Documentation Guidelines\n- Never add emojis to README.md files in repositories\n- Keep README files professional and emoji-free\n\n### Emoji Usage Guidelines\n- **Code**: Absolutely no emojis in source code, comments, or docstrings\n- **Documentation**: Avoid emojis in all documentation files (.md, .rst, etc.)\n- **Log Messages**: Use plain text only for log messages - no emojis\n- **Shell Scripts**: Avoid emojis in shell scripts - prefer plain text status messages\n- **Comments**: Use clear, descriptive text instead of emojis in code comments\n\n**Rationale**: Emojis can cause encoding issues, reduce accessibility, appear unprofessional in enterprise environments, and may not render consistently across different systems and terminals.\n\n### README Best Practices\nA well-structured README should include:\n\n1. **Prerequisites Section**: List external dependencies and setup requirements\n ```markdown\n ## Prerequisites\n - Python 3.14+\n - AWS credentials configured\n - Amazon Bedrock Guardrail with sensitive information filters\n ```\n\n2. **Links to External Resources**: Provide links to datasets, documentation, and services\n ```markdown\n - Evaluate performance on the [dataset-name](https://link-to-dataset)\n - See [AWS documentation](https://docs.aws.amazon.com/...) for setup\n ```\n\n3. **Clear Command Examples**: Show all command-line options with examples\n ```markdown\n ## Usage\n # Basic usage\n uv run python -m module_name --required-param value\n \n # With all options\n uv run python -m module_name --param1 value1 --param2 value2\n \n # Using environment variables\n export CONFIG_VAR=value\n uv run python -m module_name\n ```\n\n4. **Development Workflow**: Include a section on development practices\n ```markdown\n ## Development Workflow\n # Run all checks before committing\n uv run ruff check --fix . && uv run ruff format . && uv run bandit -r src/\n ```\n\n5. **Performance Warnings**: Alert users about time-intensive operations\n ```markdown\n # Evaluate full dataset (warning: this may take a long time)\n uv run python -m module_name --sample-size 0\n ```\n\n## Project Notes and Planning Guidelines\n\n### Scratchpad Usage\n- Always create and maintain a `.scratchpad/` folder in each project root for temporary markdown files, task status, and planning documents\n- Add `.scratchpad/` to the project's `.gitignore` file to keep notes local\n- Use this folder to store:\n - Technical analysis and findings (`analysis-YYYY-MM-DD.md`)\n - Implementation plans and strategies (`plan-feature-name.md`)\n - Code refactoring ideas (`refactor-component-name.md`)\n - Architecture decisions and considerations (`architecture-decisions.md`)\n - Development progress and next steps (`progress-notes.md`)\n - Task status and temporary working documents\n\n### Plan Documentation Process\n1. **Default Behavior**: When asked to create plans, create individual markdown files in `.scratchpad/` folder\n2. **File Naming**: Use descriptive names with dates when relevant:\n - `plan-agent-refactoring-2024-07-31.md`\n - `analysis-memory-system.md`\n - `task-status-current.md`\n3. **Organization**: Each file should have clear headings, timestamps, and be self-contained\n\n### Scratchpad Folder Structure Example\n```\nproject_root/\n├── .scratchpad/\n│ ├── plan-agent-refactoring-2024-07-31.md\n│ ├── analysis-hardcoded-names.md\n│ ├── task-status-current.md\n│ ├── architecture-decisions.md\n│ └── progress-notes.md\n├── .gitignore # Contains .scratchpad/\n└── ... other project files\n```\n\n### Individual File Structure Example\n```markdown\n# Agent Name Refactoring Plan\n*Created: 2024-07-31*\n\n## Investigation Summary\n- Found hardcoded constants in multiple files\n- Plan to centralize in constants.py\n\n## Implementation Strategy\n- Phase 1: Extend constants\n- Phase 2: Update core infrastructure\n- [Detailed steps follow...]\n\n## Next Steps\n- [ ] Implement constants centralization\n- [ ] Create utility methods\n```\n\n## Docker Build and Deployment\n\nWhen building and pushing Docker containers, create a shell script following this pattern:\n\n```bash\n#!/bin/bash\n\n# Exit on error\nset -e\n\n# Get the directory where this script is located\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nPARENT_DIR=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Configuration\nAWS_REGION=\"${AWS_REGION:-us-east-1}\"\nECR_REPO_NAME=\"your_app_name\"\nAWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)\nECR_REPO_URI=\"$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$ECR_REPO_NAME\"\n\n# Login to Amazon ECR\necho \"Logging in to Amazon ECR...\"\naws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin \"$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com\"\n\n# Create repository if it doesn't exist\necho \"Creating ECR repository if it doesn't exist...\"\naws ecr describe-repositories --repository-names \"$ECR_REPO_NAME\" --region \"$AWS_REGION\" || \\\n aws ecr create-repository --repository-name \"$ECR_REPO_NAME\" --region \"$AWS_REGION\"\n\n# Build the Docker image\necho \"Building Docker image...\"\ndocker build -f \"$PARENT_DIR/Dockerfile\" -t \"$ECR_REPO_NAME\" \"$PARENT_DIR\"\n\n# Tag the image\necho \"Tagging image...\"\ndocker tag \"$ECR_REPO_NAME\":latest \"$ECR_REPO_URI\":latest\n\n# Push the image to ECR\necho \"Pushing image to ECR...\"\ndocker push \"$ECR_REPO_URI\":latest\n\necho \"Successfully built and pushed image to:\"\necho \"$ECR_REPO_URI:latest\"\n\n# Save the container URI to a file for reference\necho \"$ECR_REPO_URI:latest\" > \"$SCRIPT_DIR/.container_uri\"\n```\n\n### Docker Script Best Practices\n- Always use `set -e` to exit on error\n- Use environment variables for configuration with sensible defaults\n- Login to ECR before pushing\n- Create ECR repository if it doesn't exist\n- Use clear echo statements to show progress (avoid emojis for compatibility)\n- Save container URI to a file for reference by other scripts\n\n### ARM64 Support\nFor ARM64 builds, add QEMU setup:\n```bash\ndocker run --rm --privileged multiarch/qemu-user-static --reset -p yes\nDOCKER_BUILDKIT=0 docker build -f \"$PARENT_DIR/Dockerfile\" -t \"$ECR_REPO_NAME\" \"$PARENT_DIR\"\n```\n\n## GitHub Issue Management\n\n### Label Management Best Practices\nWhen creating GitHub issues:\n\n1. **Check Available Labels First**: Always get a list of available labels for the repository before creating issues\n ```bash\n gh label list\n ```\n\n2. **Use Only Existing Labels**: Only apply labels that already exist in the repository to avoid errors during issue creation\n\n3. **Suggest New Labels**: If you believe a new label would be beneficial, make a suggestion in the issue description or as a separate comment, but don't attempt to add non-existent labels during issue creation\n\n4. **Label Application**: Apply labels that are available and relevant to the issue type and scope\n\n**Example Workflow**:\n```bash\n# First check available labels\ngh label list\n\n# Create issue with only existing labels\ngh issue create --title \"...\" --body-file \"...\" --label \"enhancement,bug\"\n\n# If new labels are needed, suggest them in issue comments\ngh issue comment 123 --body \"Suggest adding 'agentcore' label for AgentCore-related issues\"\n```\n\n## Summary\n\nThese guidelines ensure consistent, maintainable, and modern Python code. Key principles:\n\n- **Simplicity First**: Write code maintainable by entry-level developers\n- **Modern Python**: Use Python 3.10+ features (PEP 604/585 type hints)\n- **Automated Quality**: Use pre-commit hooks for consistent formatting\n- **Security**: Follow subprocess and SQL security patterns\n- **Type Safety**: Clear type annotations with modern syntax\n\nAlways prioritize simplicity and clarity over cleverness.\n## Federated Registry Implementation Workflow\n\nWhen implementing the federated registry feature, follow this 3-agent workflow for each sub-feature:\n\n### Agent Roles\n1. **Writer Agent** - Implement code following CLAUDE.md standards\n2. **Reviewer Agent** - Analyze time/space complexity, evaluate trade-offs, check production readiness\n3. **Tester Agent** - Write property-based tests, integration tests, validate acceptance criteria\n\n### Workflow Per Sub-Feature\n1. Writer Agent implements all tasks\n2. Reviewer Agent analyzes and suggests improvements\n3. Writer Agent addresses reviewer suggestions\n4. Tester Agent writes tests and validates\n5. Update plan if new scope discovered\n6. Final validation before marking complete\n\n### Quality Gates\n- All acceptance criteria verified with tests\n- Reviewer approved production readiness\n- Property-based tests cover invariants\n- No TODO or FIXME left unaddressed\n- Code compiles without warnings\n- Existing tests still pass\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "## Code of Conduct\nThis project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).\nFor more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact\nopensource-codeofconduct@amazon.com with any additional questions or comments.\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing Guidelines\n\nThank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional\ndocumentation, we greatly value feedback and contributions from our community.\n\nPlease read through this document before submitting any issues or pull requests to ensure we have all the necessary\ninformation to effectively respond to your bug report or contribution.\n\n\n## Reporting Bugs/Feature Requests\n\nWe welcome you to use the GitHub issue tracker to report bugs or suggest features.\n\nWhen filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already\nreported the issue. Please try to include as much information as you can. Details like these are incredibly useful:\n\n* A reproducible test case or series of steps\n* The version of our code being used\n* Any modifications you've made relevant to the bug\n* Anything unusual about your environment or deployment\n\n\n## Contributing via Pull Requests\nContributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:\n\n1. You are working against the latest source on the *main* branch.\n2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.\n3. You open an issue to discuss any significant work - we would hate for your time to be wasted.\n\nTo send us a pull request, please:\n\n1. Fork the repository.\n2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.\n3. Ensure local tests pass.\n4. Commit to your fork using clear commit messages.\n5. Send us a pull request, answering any default questions in the pull request interface.\n6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.\n\nGitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and\n[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).\n\n\n## Finding contributions to work on\nLooking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.\n\n\n## Code of Conduct\nThis project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).\nFor more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact\nopensource-codeofconduct@amazon.com with any additional questions or comments.\n\n\n## Security issue notifications\nIf you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.\n\n\n## Licensing\n\nSee the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.\n" }, { "path": "DEV_INSTRUCTIONS.md", "content": "# Getting Started\n\n## Prerequisite Reading\n**READ THIS FIRST:** [CONTRIBUTING.md](CONTRIBUTING.md)\n\nBefore you start contributing, please review the project's contribution guidelines.\n\n## Setup Instructions for Contributors\n\n### Step 1: Choose Your Development Environment\nWe recommend the fastest option to get started:\n\n#### Option A: macOS Setup (Fastest ⚡)\nComplete this setup guide first:\n\n- [macOS Setup Guide](macos-setup-guide.md)\n- Time to first run: ~30 minutes\n\n#### Option B: EC2 Complete Configuration (Preferred for Server Setup)\nIf working on EC2 or a Linux server, complete this guide first:\n\n- [Complete Configuration Guide](complete-configuration-guide.md)\n- Time to first run: ~60 minutes\n\n## Before You Start Coding\n\n### 1. Ask Your Coding Assistant to Read Documentation\nBefore making any code changes, ask your AI coding assistant to read:\n\n**LLM/AI Documentation (Critical for understanding the project):**\n- [docs/llms.txt](docs/llms.txt)\n\n**Coding Standards and Guidelines:**\n- [CLAUDE.md](CLAUDE.md) - Project-specific coding standards\n\n### 2. Review the CLAUDE.md File\nThis project uses [CLAUDE.md](CLAUDE.md) for coding standards. The file is already included in the repository root - make sure to review it before contributing.\n\n## Testing Your Changes\n\nBefore submitting a pull request, you must run and pass the test suite:\n\n### Quick Start Testing\n```bash\n# Generate fresh credentials (tokens expire in 5 minutes)\n./credentials-provider/generate_creds.sh\n\n# Run tests locally (skip production for fast iteration)\n./tests/run_all_tests.sh --skip-production\n```\n\n### For PR Merge (REQUIRED)\n```bash\n# Full test suite including production tests\n./tests/run_all_tests.sh\n\n# All tests must pass (0 failures) before merging\n```\n\n### Understanding the Tests\nSee the comprehensive testing documentation:\n\n- **[tests/README.md](tests/README.md)** - Start here! Navigation guide with access control overview\n- **[tests/TEST_QUICK_REFERENCE.md](tests/TEST_QUICK_REFERENCE.md)** - Quick reference for how-to guides\n- **[tests/lob-bot-access-control-testing.md](tests/lob-bot-access-control-testing.md)** - Access control test details\n- **[auth_server/scopes.yml](auth_server/scopes.yml)** - Permission definitions (admin, LOB1, LOB2)\n\n### Common Testing Workflows\n\n**Agent CRUD Testing:**\n```bash\n./credentials-provider/generate_creds.sh\nbash tests/agent_crud_test.sh\n```\n\n**Access Control Testing (LOB Bots):**\n```bash\n./keycloak/setup/generate-agent-token.sh admin-bot\n./keycloak/setup/generate-agent-token.sh lob1-bot\n./keycloak/setup/generate-agent-token.sh lob2-bot\nbash tests/run-lob-bot-tests.sh\n```\n\n**Check Test Logs:**\n```bash\nls -lh /tmp/*_*.log\ngrep -i \"error\\|fail\" /tmp/*.log\n```\n\n## Fork and Contribute\n\n### Repository Access\n**Important:** There is no direct access to this repository. To contribute:\n\n1. **Fork the repository on GitHub**\n ```\n https://github.com/agentic-community/mcp-gateway-registry\n ```\n\n2. **Clone your fork locally**\n ```bash\n git clone https://github.com/YOUR-USERNAME/mcp-gateway-registry.git\n cd mcp-gateway-registry\n ```\n\n3. **Create a feature branch**\n ```bash\n git checkout -b feat/your-feature-name\n ```\n\n4. **Make your changes** following the coding standards in CLAUDE.md\n\n5. **Commit and push to your fork**\n ```bash\n git push origin feat/your-feature-name\n ```\n\n6. **Create a Pull Request** to the main repository\n - Use a clear, descriptive PR title\n - Reference any related issues\n - Include test results and screenshots if applicable\n\n## Development Checklist\nBefore submitting a pull request:\n\n- [ ] Completed one of the setup guides (macOS or EC2)\n- [ ] Read docs/llms.txt\n- [ ] Read CLAUDE.md (coding standards)\n- [ ] Code follows project conventions (use ruff, mypy, pytest)\n- [ ] Generated fresh credentials: `./credentials-provider/generate_creds.sh`\n- [ ] Local tests pass: `./tests/run_all_tests.sh --skip-production`\n- [ ] PR merge tests pass: `./tests/run_all_tests.sh` (all tests must pass)\n- [ ] Reviewed test documentation: [tests/README.md](tests/README.md)\n- [ ] Changes are pushed to a fork, not directly to this repo\n- [ ] Pull request is created with clear description\n\n## Questions?\n- Check the [CONTRIBUTING.md](CONTRIBUTING.md) file for more details\n- Review existing PRs to see contribution patterns\n- Ask your coding assistant to review the documentation with you\n\nHappy coding! 🚀\n" }, { "path": "Dockerfile", "content": "# Use an official Python runtime as a parent image\nFROM python:3.14-slim\n\n# Set environment variables to prevent interactive prompts during installation\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1 \\\n DEBIAN_FRONTEND=noninteractive\n\n# Install system dependencies including nginx with lua module\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n nginx \\\n nginx-extras \\\n lua-cjson \\\n curl \\\n procps \\\n openssl \\\n git \\\n build-essential \\\n && apt-get clean \\\n && rm -rf /var/lib/apt/lists/*\n\n# Set the working directory in the container\nWORKDIR /app\n\n# Copy the application code\nCOPY . /app/\n\n# Copy nginx configurations (both HTTP-only and HTTP+HTTPS versions)\nCOPY docker/nginx_rev_proxy_http_only.conf /app/docker/nginx_rev_proxy_http_only.conf\nCOPY docker/nginx_rev_proxy_http_and_https.conf /app/docker/nginx_rev_proxy_http_and_https.conf\n\n# Copy custom error pages for nginx\nCOPY docker/502.html /usr/share/nginx/html/502.html\n\n# Make the entrypoint script executable\nCOPY docker/entrypoint.sh /app/docker/entrypoint.sh\nRUN chmod +x /app/docker/entrypoint.sh\n\n# Create nginx lua directories and remove default sites (needed by entrypoint script)\nRUN mkdir -p /etc/nginx/lua/virtual_mappings && \\\n rm -f /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default && \\\n mkdir -p /var/lib/nginx/body /var/lib/nginx/proxy /var/lib/nginx/fastcgi /var/lib/nginx/uwsgi /var/lib/nginx/scgi && \\\n mkdir -p /var/log/nginx && \\\n mkdir -p /run/nginx\n\n# Expose ports for Nginx (HTTP/HTTPS on high ports for non-root) and the Registry\nEXPOSE 8080 8443 7860\n\n# Define environment variables for registry/server configuration (can be overridden at runtime)\n# Provide sensible defaults or leave empty if they should be explicitly set\nARG BUILD_VERSION=\"1.0.0\"\nARG SECRET_KEY=\"\"\nARG POLYGON_API_KEY=\"\"\n\nENV BUILD_VERSION=$BUILD_VERSION\nENV SECRET_KEY=$SECRET_KEY\nENV POLYGON_API_KEY=$POLYGON_API_KEY\n\n# Add health check using the new HTTP endpoint\nHEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \\\n CMD curl -f http://localhost:7860/health || exit 1\n\n# Create non-root user for security (CIS Docker Benchmark 4.1)\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\n# Create security scan directories and certs directory with proper permissions\nRUN mkdir -p /app/security_scans /app/skill_security_scans /app/agent_security_scans /app/certs && \\\n chown -R appuser:appuser /app/security_scans /app/skill_security_scans /app/agent_security_scans /app/certs\n\n# Set ownership of application files, nginx configs, and entrypoint\nRUN chown -R appuser:appuser /app /etc/nginx /var/log/nginx /var/lib/nginx /run/nginx /app/docker/entrypoint.sh\n\n# Switch to non-root user\nUSER appuser\n\n# Run the entrypoint script when the container launches\nENTRYPOINT [\"/app/docker/entrypoint.sh\"]" }, { "path": "LICENSE", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n" }, { "path": "Makefile", "content": ".PHONY: help test test-unit test-integration test-e2e test-fast test-coverage test-auth test-servers test-search test-health test-core install-dev lint format check-deps clean build-keycloak push-keycloak build-and-push-keycloak deploy-keycloak update-keycloak save-outputs view-logs view-logs-keycloak view-logs-registry view-logs-auth view-logs-follow list-images build push build-push generate-manifest validate-config publish-dockerhub publish-dockerhub-component publish-dockerhub-version publish-dockerhub-no-mirror publish-local compose-up-agents compose-down-agents compose-logs-agents build-agents push-agents\n\n# Default target\nhelp:\n\t@echo \"🧪 MCP Registry Testing Commands\"\n\t@echo \"\"\n\t@echo \"Setup:\"\n\t@echo \" install-dev Install development dependencies\"\n\t@echo \" check-deps Check if test dependencies are installed\"\n\t@echo \"\"\n\t@echo \"Testing:\"\n\t@echo \" test Run full test suite with coverage\"\n\t@echo \" test-unit Run unit tests only\"\n\t@echo \" test-integration Run integration tests only\" \n\t@echo \" test-e2e Run end-to-end tests only\"\n\t@echo \" test-fast Run fast tests (exclude slow tests)\"\n\t@echo \" test-coverage Generate coverage reports\"\n\t@echo \"\"\n\t@echo \"Domain Testing:\"\n\t@echo \" test-auth Run authentication domain tests\"\n\t@echo \" test-servers Run server management domain tests\"\n\t@echo \" test-search Run search domain tests\"\n\t@echo \" test-health Run health monitoring domain tests\"\n\t@echo \" test-core Run core infrastructure tests\"\n\t@echo \"\"\n\t@echo \"Code Quality:\"\n\t@echo \" lint Run linting checks\"\n\t@echo \" format Format code\"\n\t@echo \" clean Clean up test artifacts\"\n\t@echo \"\"\n\t@echo \"Keycloak Build & Deploy:\"\n\t@echo \" build-keycloak Build Keycloak Docker image locally\"\n\t@echo \" build-and-push-keycloak Build and push to ECR\"\n\t@echo \" deploy-keycloak Update ECS service (after push)\"\n\t@echo \" update-keycloak Build, push, and deploy in one command\"\n\t@echo \"\"\n\t@echo \"Infrastructure Documentation:\"\n\t@echo \" save-outputs Save Terraform outputs as JSON\"\n\t@echo \"\"\n\t@echo \"CloudWatch Logs Viewing:\"\n\t@echo \" view-logs View logs from all components (last 30 min)\"\n\t@echo \" view-logs-keycloak View Keycloak logs (last 30 min)\"\n\t@echo \" view-logs-registry View Registry logs (last 30 min)\"\n\t@echo \" view-logs-auth View Auth Server logs (last 30 min)\"\n\t@echo \" view-logs-follow Follow logs in real-time for all components\"\n\t@echo \"\"\n\t@echo \"Container Build & Registry:\"\n\t@echo \" list-images List all configured container images\"\n\t@echo \" build Build all images locally\"\n\t@echo \" build IMAGE=name Build specific image (e.g., IMAGE=registry)\"\n\t@echo \" push Push all images to ECR\"\n\t@echo \" push IMAGE=name Push specific image to ECR\"\n\t@echo \" build-push Build and push all images\"\n\t@echo \" build-push IMAGE=name Build and push specific image\"\n\t@echo \" build-push-deploy Build, push, and deploy (default: both services)\"\n\t@echo \" build-push-deploy IMAGE=x Build, push, deploy specific (registry or auth_server)\"\n\t@echo \" generate-manifest Generate image-manifest.json for Terraform\"\n\t@echo \" validate-config Validate build-config.yaml syntax\"\n\t@echo \"\"\n\t@echo \"DockerHub Publishing:\"\n\t@echo \" publish-dockerhub Publish all images to DockerHub\"\n\t@echo \" publish-dockerhub-component Publish specific component (COMPONENT=name)\"\n\t@echo \" publish-dockerhub-version Publish with version tag (VERSION=v1.0.0)\"\n\t@echo \" publish-dockerhub-no-mirror Publish without external images\"\n\t@echo \" publish-local Build locally without pushing\"\n\t@echo \"\"\n\t@echo \"Local A2A Agent Development:\"\n\t@echo \" compose-up-agents Start A2A agents with docker-compose\"\n\t@echo \" compose-down-agents Stop A2A agents\"\n\t@echo \" compose-logs-agents Follow A2A agent logs in real-time\"\n\t@echo \" build-agents Build both A2A agent images locally\"\n\t@echo \" push-agents Push both A2A agent images to ECR\"\n\n# Installation\ninstall-dev:\n\t@echo \"📦 Installing development dependencies...\"\n\tpip install -e .[dev]\n\ncheck-deps:\n\t@python scripts/test.py check\n\n# Full test suite\ntest:\n\t@python scripts/test.py full\n\n# Test types\ntest-unit:\n\t@python scripts/test.py unit\n\ntest-integration:\n\t@python scripts/test.py integration\n\ntest-e2e:\n\t@python scripts/test.py e2e\n\ntest-fast:\n\t@python scripts/test.py fast\n\ntest-coverage:\n\t@python scripts/test.py coverage\n\n# Domain-specific tests\ntest-auth:\n\t@python scripts/test.py auth\n\ntest-servers:\n\t@python scripts/test.py servers\n\ntest-search:\n\t@python scripts/test.py search\n\ntest-health:\n\t@python scripts/test.py health\n\ntest-core:\n\t@python scripts/test.py core\n\n# Code quality\nlint:\n\t@echo \"🔍 Running linting checks...\"\n\t@python -m bandit -r registry/ -f json || true\n\t@echo \"✅ Linting complete\"\n\nformat:\n\t@echo \"🎨 Formatting code...\"\n\t@python -m black registry/ tests/ --diff --color\n\t@echo \"✅ Code formatting complete\"\n\n# Cleanup\nclean:\n\t@echo \"🧹 Cleaning up test artifacts...\"\n\t@rm -rf htmlcov/\n\t@rm -rf tests/reports/\n\t@rm -rf .coverage\n\t@rm -rf coverage.xml\n\t@rm -rf .pytest_cache/\n\t@find . -type d -name \"__pycache__\" -exec rm -rf {} + 2>/dev/null || true\n\t@find . -type f -name \"*.pyc\" -delete 2>/dev/null || true\n\t@echo \"✅ Cleanup complete\"\n\n# Development workflow\ndev-test: clean install-dev test-fast\n\t@echo \"🚀 Development test cycle complete!\"\n\n# CI/CD workflow\nci-test: clean check-deps test test-coverage\n\t@echo \"🏗️ CI/CD test cycle complete!\"\n\n# Keycloak Build & Deployment\n# Variables\nAWS_REGION ?= us-west-2\nAWS_PROFILE ?= default\nIMAGE_TAG ?= latest\n\nbuild-keycloak:\n\t@echo \"🐋 Building Keycloak Docker image...\"\n\t@$(MAKE) build IMAGE=keycloak\n\t@echo \"✅ Image built: keycloak:$(IMAGE_TAG)\"\n\nbuild-and-push-keycloak:\n\t@echo \"📦 Building and pushing Keycloak to ECR...\"\n\t@$(MAKE) build-push IMAGE=keycloak\n\t@echo \"✅ Keycloak image built and pushed successfully\"\n\ndeploy-keycloak:\n\t@echo \"🚀 Deploying Keycloak ECS service...\"\n\taws ecs update-service \\\n\t\t--cluster keycloak \\\n\t\t--service keycloak \\\n\t\t--force-new-deployment \\\n\t\t--region $(AWS_REGION) \\\n\t\t--profile $(AWS_PROFILE) \\\n\t\t--output table\n\t@echo \"✅ ECS service update initiated\"\n\nupdate-keycloak: build-and-push-keycloak deploy-keycloak\n\t@echo \"\"\n\t@echo \"✅ Keycloak update complete!\"\n\t@echo \"\"\n\t@echo \"Service URLs:\"\n\t@echo \" Admin Console: https://kc.mycorp.click/admin\"\n\t@echo \" Service URL: https://kc.mycorp.click\"\n\t@echo \"\"\n\t@echo \"Monitor deployment:\"\n\t@echo \" aws ecs describe-services --cluster keycloak --services keycloak --region $(AWS_REGION) --query 'services[0].[serviceName,status,runningCount,desiredCount]' --output table\"\n\nsave-outputs:\n\t@echo \"💾 Saving Terraform outputs as JSON...\"\n\t./terraform/aws-ecs/scripts/save-terraform-outputs.sh\n\t@echo \"\"\n\t@echo \"✅ Outputs saved to terraform/aws-ecs/terraform-outputs.json\"\n\nview-logs:\n\t@echo \"📋 Viewing CloudWatch logs from last 30 minutes for all components...\"\n\t./terraform/aws-ecs/scripts/view-cloudwatch-logs.sh\n\nview-logs-keycloak:\n\t@echo \"📋 Viewing Keycloak CloudWatch logs from last 30 minutes...\"\n\t./terraform/aws-ecs/scripts/view-cloudwatch-logs.sh --component keycloak --minutes 30\n\nview-logs-registry:\n\t@echo \"📋 Viewing Registry CloudWatch logs from last 30 minutes...\"\n\t./terraform/aws-ecs/scripts/view-cloudwatch-logs.sh --component registry --minutes 30\n\nview-logs-auth:\n\t@echo \"📋 Viewing Auth Server CloudWatch logs from last 30 minutes...\"\n\t./terraform/aws-ecs/scripts/view-cloudwatch-logs.sh --component auth-server --minutes 30\n\nview-logs-follow:\n\t@echo \"📋 Following CloudWatch logs in real-time for all components...\"\n\t./terraform/aws-ecs/scripts/view-cloudwatch-logs.sh --follow\n\n# ========================================\n# Unified Container Build System\n# ========================================\n\nlist-images:\n\t@./scripts/generate-image-manifest.sh --list\n\ngenerate-manifest:\n\t@./scripts/generate-image-manifest.sh\n\nvalidate-config:\n\t@python3 -c \"import yaml; yaml.safe_load(open('build-config.yaml'))\" && echo \"Config is valid!\"\n\nbuild:\n\t@$(if $(IMAGE),IMAGE=$(IMAGE),) ./scripts/build-images.sh build\n\npush:\n\t@$(if $(IMAGE),IMAGE=$(IMAGE),) ./scripts/build-images.sh push\n\nbuild-push:\n\t@$(if $(NO_CACHE),NO_CACHE=$(NO_CACHE),) $(if $(IMAGE),IMAGE=$(IMAGE),) ./scripts/build-images.sh build-push\n\nbuild-push-deploy:\n\t@./scripts/deploy.sh $(if $(IMAGE),--service $(IMAGE),) $(if $(NO_CACHE),--no-cache,) --skip-monitor\n\n# ========================================\n# DockerHub Publishing\n# ========================================\n\npublish-dockerhub:\n\t@echo \"Publishing all images to DockerHub...\"\n\t./scripts/publish_containers.sh --dockerhub\n\npublish-dockerhub-component:\n\t@echo \"Publishing $(COMPONENT) to DockerHub...\"\n\t./scripts/publish_containers.sh --dockerhub --component $(COMPONENT)\n\npublish-dockerhub-version:\n\t@echo \"Publishing all images to DockerHub with version $(VERSION)...\"\n\t./scripts/publish_containers.sh --dockerhub --version $(VERSION)\n\npublish-dockerhub-no-mirror:\n\t@echo \"Publishing all images to DockerHub (skipping external images)...\"\n\t./scripts/publish_containers.sh --dockerhub --skip-mirror\n\npublish-local:\n\t@echo \"Building all images locally (no push)...\"\n\t./scripts/publish_containers.sh --local\n\n# ========================================\n# Local A2A Agent Development\n# ========================================\n\ncompose-up-agents:\n\t@echo \"Starting A2A agents with docker-compose...\"\n\tcd agents/a2a && docker-compose -f docker-compose.local.yml up -d\n\t@echo \"Agents started:\"\n\t@echo \" Flight Booking Agent: http://localhost:9002/ping\"\n\t@echo \" Travel Assistant Agent: http://localhost:9001/ping\"\n\ncompose-down-agents:\n\t@echo \"Stopping A2A agents...\"\n\tcd agents/a2a && docker-compose -f docker-compose.local.yml down\n\ncompose-logs-agents:\n\t@echo \"Following A2A agent logs...\"\n\tcd agents/a2a && docker-compose -f docker-compose.local.yml logs -f\n\nbuild-agents:\n\t@echo \"Building A2A agent images locally...\"\n\t@$(MAKE) build IMAGE=flight_booking_agent\n\t@$(MAKE) build IMAGE=travel_assistant_agent\n\t@echo \"Both agents built successfully\"\n\npush-agents:\n\t@echo \"Pushing A2A agent images to ECR...\"\n\t@$(MAKE) push IMAGE=flight_booking_agent\n\t@$(MAKE) push IMAGE=travel_assistant_agent\n\t@echo \"Both agents pushed to ECR\"\n" }, { "path": "NOTICE", "content": "Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\nQ2 2025 Contributions Copyright Dheeraj Oruganty under MIT License.\n" }, { "path": "README.md", "content": "
\n\"MCP\n\n**Unified Agent & MCP Server Registry – Gateway for AI Development Tools**\n\n[![GitHub stars](https://img.shields.io/github/stars/agentic-community/mcp-gateway-registry?style=flat&logo=github)](https://github.com/agentic-community/mcp-gateway-registry/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/agentic-community/mcp-gateway-registry?style=flat&logo=github)](https://github.com/agentic-community/mcp-gateway-registry/network)\n[![GitHub issues](https://img.shields.io/github/issues/agentic-community/mcp-gateway-registry?style=flat&logo=github)](https://github.com/agentic-community/mcp-gateway-registry/issues)\n[![License](https://img.shields.io/github/license/agentic-community/mcp-gateway-registry?style=flat)](https://github.com/agentic-community/mcp-gateway-registry/blob/main/LICENSE)\n[![GitHub release](https://img.shields.io/github/v/release/agentic-community/mcp-gateway-registry?style=flat&logo=github)](https://github.com/agentic-community/mcp-gateway-registry/releases)\n\n[🚀 Get Running Now](#option-a-pre-built-images-instant-setup) | [macOS Setup Skill](.claude/skills/macos-setup/SKILL.md) | [AWS Workshop Studio](https://catalog.us-east-1.prod.workshops.aws/workshops/0c3265a6-1a4a-467b-ae56-e4d019184b0e/en-US) | [AWS Deployment](terraform/aws-ecs/README.md) | [Quick Start](#quick-start) | [Documentation](docs/) | [Community](#community)\n\n**Demo Videos:** 🎥 [AWS Show & Tell](https://www.youtube.com/watch?v=dk0qVukHLGU) | ⭐ [MCP Registry CLI Demo](https://github.com/user-attachments/assets/98200866-e8bd-4ac3-bad6-c6d42b261dbe) | [Full End-to-End Functionality](https://github.com/user-attachments/assets/5ffd8e81-8885-4412-a4d4-3339bbdba4fb) | [OAuth 3-Legged Authentication](https://github.com/user-attachments/assets/3c3a570b-29e6-4dd3-b213-4175884396cc) | [Dynamic Tool Discovery](https://github.com/user-attachments/assets/cee25b31-61e4-4089-918c-c3757f84518c) | [Agent Skills](https://github.com/user-attachments/assets/5d1f227a-25f8-480d-9ff9-acba2498844b) | [Virtual MCP Servers](https://app.vidcast.io/share/954e6296-f217-4559-8d86-88cec25af763) | [Slide Deck](docs/slides/mcp-gateway-registry-presentation.pdf)\n\n
\n\n---\n\n## What is MCP Gateway & Registry?\n\nThe **MCP Gateway & Registry** is a unified platform designed for centralizing access to both MCP Servers and AI Agents using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). It serves three core functions:\n\n1. **Unified MCP Server Gateway** – Centralized access point for multiple MCP servers\n2. **MCP Servers Registry** – Register, discover, and manage access to MCP servers with unified governance\n3. **Agent Registry & A2A Communication Hub** – Agent registration, discovery, governance, and direct agent-to-agent communication through the [A2A (Agent-to-Agent) Protocol](https://a2a-protocol.org/latest/specification/)\n\nThe platform integrates with external registries such as Anthropic's MCP Registry (and more to come), providing a single control plane for both tool access, agent orchestration, and agent-to-agent communication patterns.\n\n**Why unified?** Instead of managing hundreds of individual MCP server configurations, agent connections, and separate governance systems across your development teams, this platform provides secure, governed access to curated MCP servers and registered agents through a single, unified control plane.\n\n**Transform this chaos:**\n```\n❌ AI agents require separate connections to each MCP server\n❌ Each developer configures VS Code, Cursor, Claude Code individually\n❌ Developers must install and manage MCP servers locally\n❌ No standard authentication flow for enterprise tools\n❌ Scattered API keys and credentials across tools\n❌ No visibility into what tools teams are using\n❌ Security risks from unmanaged tool sprawl\n❌ No dynamic tool discovery for autonomous agents\n❌ No curated tool catalog for multi-tenant environments\n❌ A2A provides agent cards but no way for agents to discover other agents\n❌ Maintaining separate MCP server and agent registries is a non-starter for governance\n❌ Impossible to maintain unified policies across server and agent access\n```\n\n**Into this organized approach:**\n```\n✅ AI agents connect to one gateway, access multiple MCP servers\n✅ Single configuration point for VS Code, Cursor, Claude Code\n✅ Central IT manages cloud-hosted MCP infrastructure via streamable HTTP\n✅ Developers use standard OAuth 2LO/3LO flows for enterprise MCP servers\n✅ Centralized credential management with secure vault integration\n✅ Complete visibility and audit trail for all tool usage\n✅ Security features with governed tool access\n✅ Dynamic tool discovery and invocation for autonomous workflows\n✅ Registry provides discoverable, curated MCP servers for multi-tenant use\n✅ Agents can discover and communicate with other agents through unified Agent Registry\n✅ Single control plane for both MCP servers and agent governance\n✅ Unified policies and audit trails for both server and agent access\n```\n\n```\n┌─────────────────────────────────────┐ ┌──────────────────────────────────────────────────────┐\n│ BEFORE: Chaos │ │ AFTER: MCP Gateway & Registry │\n├─────────────────────────────────────┤ ├──────────────────────────────────────────────────────┤\n│ │ │ │\n│ Developer 1 ──┬──► MCP Server A │ │ Developer 1 ──┐ ┌─ MCP Server A │\n│ ├──► MCP Server B │ │ │ ├─ MCP Server B │\n│ └──► MCP Server C │ │ Developer 2 ──┼──► MCP Gateway │ │\n│ │ │ │ & Registry ───┼─ MCP Server C │\n│ Developer 2 ──┬──► MCP Server A │ ──► │ AI Agent 1 ───┘ │ │ │\n│ ├──► MCP Server D │ │ │ ├─ AI Agent 1 │\n│ └──► MCP Server E │ │ AI Agent 2 ──────────────┤ ├─ AI Agent 2 │\n│ │ │ │ │ │\n│ AI Agent 1 ───┬──► MCP Server B │ │ AI Agent 3 ──────────────┘ └─ AI Agent 3 │\n│ ├──► MCP Server C │ │ │\n│ └──► MCP Server F │ │ Single Connection Point │\n│ │ │ │\n│ ❌ Multiple connections per user │ │ ✅ One gateway for all │\n│ ❌ No centralized control │ │ ✅ Unified server & agent access │\n│ ❌ Credential sprawl │ │ ✅ Unified governance & audit trails │\n└─────────────────────────────────────┘ └──────────────────────────────────────────────────────┘\n```\n\n> **Note on Agent-to-Agent Communication:** AI Agents discover other AI Agents through the unified Agent Registry and communicate with them **directly** (peer-to-peer) without routing through the MCP Gateway. The Registry handles discovery, authentication, and access control, while agents maintain direct connections for efficient, low-latency communication.\n\n## Unified Agent & Server Registry\n\nThis platform serves as a comprehensive, unified registry supporting:\n\n- ✅ **MCP Server Registration & Discovery** – Register, discover, and manage access to MCP servers\n- ✅ **AI Agent Registration & Discovery** – Register agents and enable them to discover other agents\n- ✅ **Agent-to-Agent (A2A) Communication** – Direct agent-to-agent communication patterns using the A2A protocol\n- ✅ **Multi-Protocol Support** – Support for various agent communication protocols and patterns\n- ✅ **Unified Governance** – Single policy and access control system for both agents and servers\n- ✅ **Cross-Protocol Agent Discovery** – Agents can discover each other regardless of implementation\n- ✅ **Integrated External Registries** – Connect with Anthropic's MCP Registry and other external sources\n- ✅ **Agent Cards & Metadata** – Rich metadata for agent capabilities, skills, and authentication schemes\n\nKey distinction: **Unlike separate point solutions, this unified registry eliminates the need to maintain separate MCP server and agent systems**, providing a single control plane for agent orchestration, MCP server access, and agent-to-agent communication.\n\n## MCP Servers, Agents and Skills Registry\n\nWatch how MCP Servers, A2A Agents, and External Registries work together for dynamic tool discovery:\n\nhttps://github.com/user-attachments/assets/97c640db-f78b-4a6c-9662-894f975f66e2\n\n---\n\n## MCP Tools in Action\n\n[View MCP Tools Demo](docs/img/MCP_tools.gif)\n\n---\n\n## MCP Registry CLI\n\nInteractive terminal interface for chatting with AI models and discovering MCP tools in natural language. Talk to the registry using a Claude Code-like conversational interface with real-time token status, cost tracking, and AI model selection.\n\n
\n\"MCP\n
\n\n**Quick Start:** `registry --url https://mcpgateway.ddns.net` | [Full Guide](docs/mcp-registry-cli.md)\n\n---\n\n## What's New\n\n- **Group-Restricted Agent Visibility** - Agent publishers can now restrict which IdP groups can see their agent by setting `visibility: \"group-restricted\"` and specifying `allowedGroups` at registration time, without needing an admin to change IAM scopes. Works as a second filter on top of the existing IAM group scope layer: users must pass both the IAM scope check and the allowed_groups check. Nginx forwards JWT group claims via X-Groups header, the list endpoint enforces group filtering for all non-admin users, and the CLI supports `--allowed-groups` for both registration and filtering. Frontend registration and edit forms include a Visibility dropdown and Allowed Groups input. Compatible with all supported IdPs (Keycloak, Entra ID, Cognito, Okta, Auth0). ([#883](https://github.com/agentic-community/mcp-gateway-registry/issues/883), [#922](https://github.com/agentic-community/mcp-gateway-registry/issues/922)) [Full Guide](docs/agent-visibility-and-group-access.md) | [FAQ](docs/faq/group-restricted-agent-visibility.md)\n\n- **Admin Data Export** - Download registry data as JSON files for debugging, auditing, and backup. A new Data Export section in the admin Settings page supports 11 collections: Servers, Agents, Skills, Virtual Servers, Federation Peers, Federation Configs, Registry Card, IAM Users, IAM Groups, IAM M2M Clients, and Scopes. Download individual collections or use the Download All as ZIP button (powered by JSZip) with per-collection progress indicators. Includes a sensitive data warning banner and a dedicated scopes export endpoint that dumps full server_access rules. Admin-only access, not visible to non-admin users.\n\n- **Centralized Log Rotation, Storage, and Retrieval** - Production-grade application logging with RotatingFileHandler (50 MB, 5 backups) for both the registry and auth-server. Optional MongoDB storage via a non-blocking MongoDBLogHandler with buffered background writes and TTL-based auto-expiry. Admin REST API endpoints (`GET /api/admin/logs` for querying with filters, `GET /api/admin/logs/export` for JSONL download, `GET /api/admin/logs/metadata` for available services and levels) and a Settings UI Log Viewer with filtering by service, level, hostname, search text, and time range. Security includes MongoDB regex injection prevention via `re.escape()`, rate limiting (10 requests per 60 seconds per user), and max search length validation. MongoDB logging is OFF by default; enable with `APP_LOG_MONGODB_ENABLED=true`. File-based rotation is always active.\n\n- **Registration Webhooks and Gate** - Two external integration points for registration lifecycle events. **Registration Gate (Admission Control)**: call an external endpoint to approve or deny registration and update requests before they are persisted. Supports all asset types (servers, agents, skills) for both register and update operations. Fail-closed design: if the gate endpoint is unreachable after configurable retries with exponential backoff, the registration is blocked. Sensitive fields (credentials, tokens, passwords) are automatically stripped from the payload sent to the gate. Supports Bearer token, API key, or unauthenticated access. Gate returns 200 to allow, 403 to deny with a custom error message. **Registration Webhooks**: send HTTP POST notifications to an external URL when servers, agents, or skills are registered or deleted. Enables real-time integration with CMDBs, CI/CD pipelines, Slack, or any external system. Fire-and-forget delivery (failures are logged, never block the caller). Supports Bearer token and custom API key authentication with configurable headers and timeouts. Both are configured across Docker Compose, Terraform/ECS, and Helm/EKS. ([#809](https://github.com/agentic-community/mcp-gateway-registry/issues/809), [#742](https://github.com/agentic-community/mcp-gateway-registry/issues/742)) [Webhooks and Gate Guide](docs/registration-webhooks.md)\n\n- **Multi-Key Static Tokens with Per-Key Groups** - Replace the single `REGISTRY_API_TOKEN` with a `REGISTRY_API_KEYS` JSON object where each key carries its own name, secret, and group list. Groups resolve to scopes through the standard `group_mappings` pipeline, so each key gets exactly the privileges its groups grant. Supports zero-downtime rotation (add new key, migrate clients, remove old key), timing-safe comparison via `hmac.compare_digest`, and full coexistence with the legacy single token. The legacy token is auto-promoted to a `\"legacy\"` entry in the internal token map with `mcp-registry-admin` scopes for backward compatibility. Key names appear in audit logs as the username for traceability. Scope changes propagate to static tokens via the auth server reload mechanism without requiring a restart. ([#779](https://github.com/agentic-community/mcp-gateway-registry/issues/779)) [Registry API Authentication Guide](docs/registry-api-auth.md) | [FAQ](docs/faq/registry-api-auth-faq.md)\n\n- **Registry API Authentication: Unified Model** - The Registry API (`/api/*`, `/v0.1/*`) accepts four credential types **concurrently**: session cookies (browser UI), IdP-issued JWTs (Okta/Entra/Cognito/Keycloak) and UI-issued self-signed JWTs, a static `REGISTRY_API_TOKEN` for trusted service-to-service callers, and a separate `FEDERATION_STATIC_TOKEN` scoped to federation/peer endpoints only. Previously, enabling static-token mode silently blocked JWT callers on `/api/*` ([#871](https://github.com/agentic-community/mcp-gateway-registry/issues/871)). One improvement remains on the roadmap: external user access tokens that let a frontend app call the registry on behalf of its logged-in users without sharing a registry credential ([#826](https://github.com/agentic-community/mcp-gateway-registry/issues/826)). [Registry API Authentication Guide](docs/registry-api-auth.md) | [FAQ](docs/faq/registry-api-auth-faq.md)\n\n- **GitHub Private Repository Auth for Agent Skills** - Fetch SKILL.md files from private GitHub repositories using Personal Access Tokens (PAT) or GitHub App authentication (recommended for organizations). Supports GitHub Enterprise Server with configurable API base URLs and extra host matching. Auth headers are only sent to github.com, raw.githubusercontent.com, and explicitly listed hosts. Helm deployments support Kubernetes secrets for credential injection. Configured across Docker Compose, Helm, and Terraform/ECS. See [`.env.example`](.env.example) for all parameters. [Configuration Guide](docs/configuration.md#github-private-repository-access)\n\n- **Configurable Tab Visibility, Pagination, and Lifecycle Filtering** - Four new `SHOW_*_TAB` environment variables control which dashboard tabs are visible independently of `REGISTRY_MODE` (formula: `tab_visible = mode enables feature AND SHOW_*_TAB`). All APIs (`GET /api/servers`, `/api/agents`, `/api/skills`) now support `limit`/`offset` pagination. New lifecycle status filtering in the sidebar lets you filter by active, deprecated, or experimental assets. Also adds `GET /api/servers/{path}` for single server retrieval, improved semantic search ranking (global ranking replaces the old 3-per-type cap), network-trusted JWT token generation, and heartbeat telemetry opt-out. See [`.env.example`](.env.example) for all new configuration parameters. [Tab Visibility Configuration](docs/configuration.md#tab-visibility-overrides)\n\n- **AWS Agent Registry Federation** - Federate MCP servers, A2A agents, and agent skills from [AWS Agent Registry](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry.html) into MCP Gateway Registry. Add multiple AgentCore registries (same or different AWS accounts/regions), select which descriptor types to sync (MCP, A2A, CUSTOM, AGENT_SKILLS), and manage everything from the External Registries settings page. Supports cross-account access via IAM role assumption, cascade cleanup on registry removal, and automatic sync on startup. Enable with a single environment variable (`AWS_REGISTRY_FEDERATION_ENABLED=true`) for ECS/Terraform or Helm deployments. [Operations Guide](docs/aws-agent-registry-federation.md) | [Design Document](docs/design/aws-agent-registry-federation.md)\n\n- **Register Any Agent (A2A and Non-A2A)** - The Agent Registry now supports registering any agent, not just A2A protocol agents. A new `supported_protocol` field (`a2a` or `other`) distinguishes agent types. Register through the UI (checkbox for A2A agents, dropdown for protocol selection on edit), the API (`supportedProtocol` field in registration payload), or the CLI (`--supported-protocol` flag). Default `trust_level` updated to `community` and `visibility` to `public` for consistency. A one-time [backfill script](scripts/backfill_agent_fields.py) normalizes existing agents in MongoDB. Two new Claude Code skills -- [generate-agent-card](.claude/skills/generate-agent-card/SKILL.md) and [generate-server-card](.claude/skills/generate-server-card/SKILL.md) -- analyze source code and generate registration-ready agent or server card JSON files. [Documentation](docs/supported-protocol-and-trust-fields.md)\n\n- **Amazon Bedrock AgentCore Bulk Import** - Auto-discover and register all AgentCore Gateways and Agent Runtimes from your AWS account in a single command. The CLI scans for READY resources, registers gateways as MCP Servers and runtimes as MCP Servers or A2A Agents based on protocol, and writes a token refresh manifest for automated credential rotation. Supports multi-account scanning, OIDC-compliant identity providers (Cognito, Auth0, Okta, Entra ID, Keycloak), and overwrite mode for updating existing registrations. [AgentCore Operations Guide](docs/agentcore.md) | [Design Document](docs/design/agentcore-scanner-design.md)\n\n- **Anonymous Usage Telemetry** - Privacy-first telemetry to track registry adoption patterns. Sends only non-sensitive deployment metadata (version, OS, storage backend, auth provider) -- no PII, no hostnames, no user data. Opt-out by default (startup ping is ON, set `MCP_TELEMETRY_DISABLED=1` to disable). Opt-in daily heartbeat with aggregate counts (server/agent/skill totals). HMAC-signed requests, IP-hashed rate limiting, strict schema validation, and fail-silent design ensure zero impact on registry operation. Admin API to force heartbeat/startup events on demand. [Telemetry Documentation](docs/TELEMETRY.md)\n\n- **Agent Name Service (ANS) Integration** - Adds PKI-based trust verification for registered agents and MCP servers through GoDaddy's [Agent Name Service](https://www.godaddy.com/ans). Agent owners link their ANS Agent ID to their registry entry, and the registry verifies the identity via the ANS API, displaying a clickable trust badge on agent cards and semantic search results. A background scheduler re-verifies all linked identities every 6 hours with circuit breaker protection. Supports verified, expired, and revoked status tracking with admin endpoints for manual sync, metrics, and health checks. [Design and Operations Guide](docs/design/ans-integration.md) | [Demo Video](https://app.vidcast.io/share/c2240a78-8899-46ad-9375-6fb0cc1345f3?playerMode=vidcast)\n\n- **Registry Card for Federation Discovery** - As registries increasingly need to discover and communicate with each other, we've implemented the Registry Card specification—a standardized discovery document accessible via `/.well-known/registry-card`. This provides essential metadata including authentication endpoints, capabilities, and contact information for any registry instance. Enhanced server, agent, and skills cards with richer metadata enable better federation workflows. [Registry Card Configuration Guide](docs/federation-operational-guide.md#registry-card-configuration)\n\n- 🔑 **Auth0 Identity Provider Support** - Full enterprise SSO integration with Auth0 as an identity provider. The harmonized IAM API now supports Auth0 alongside Keycloak, Microsoft Entra ID, and Okta, providing a unified interface to create users, groups, and M2M service accounts regardless of your IdP choice. Features include Auth0 Actions for group claims injection, M2M client sync with database-driven groups enrichment for OAuth2 Client Credentials tokens, and complete Docker Compose and Terraform/ECS deployment support. Switch identity providers with a single environment variable while using the same management APIs and UI. [Auth0 Setup Guide](docs/auth0.md)\n\n- 🔑 **Okta Identity Provider Support** - Full enterprise SSO integration with Okta as an identity provider. The existing harmonized IAM API now supports Okta alongside Keycloak and Microsoft Entra ID, providing a unified interface to create users, groups, and M2M service accounts regardless of your IdP choice. Features include custom authorization server support for scalable M2M authentication, database-driven groups enrichment for OAuth2 Client Credentials tokens, and complete Docker Compose and Terraform/ECS deployment support. Switch identity providers with a single environment variable while using the same management APIs and UI. [Okta Setup Guide](docs/okta-setup.md)\n\n- 🔐 **Enterprise Security Posture Documentation** - Comprehensive security architecture documentation covering defense-in-depth across all deployment platforms (ECS, EKS, Docker Compose). Details infrastructure security, encryption at rest/in-transit with KMS, secrets management with automated rotation, container hardening following CIS benchmarks, application security with automated scanning (Semgrep, Bandit), supply chain security for MCP servers, and compliance with SOC 2/GDPR standards. [Security Posture Guide](docs/security-posture.md)\n\n- **📊 Direct OTLP Push Export for Metrics** - Push metrics directly to any OTLP-compatible observability platform (Datadog, New Relic, Honeycomb, Grafana Cloud) without requiring an intermediate OTEL Collector. Configure via environment variables (`OTEL_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`) for instant integration with commercial observability platforms. Supports both Docker Compose and Terraform/ECS deployments with secure credential handling via AWS Secrets Manager. Works alongside existing Prometheus/Grafana setup for hybrid monitoring. [Metrics Architecture Guide - Direct OTLP Push](docs/metrics-architecture.md#direct-otlp-push-export-simplified-setup)\n\n- ⭐ **AWS Workshop Studio: Securing AI Agent Ecosystems with MCP Gateway and Registry** - Hands-on workshop covering deployment, authentication, governance, and security best practices for production AI agent ecosystems. Learn to deploy the MCP Gateway & Registry on AWS, configure enterprise authentication, implement fine-grained access control, and secure AI agent communications. [Start Workshop](https://catalog.us-east-1.prod.workshops.aws/workshops/0c3265a6-1a4a-467b-ae56-e4d019184b0e/en-US)\n\n- 💻 **One-Command macOS Setup** - The quickest way to get started and experiment with the solution on your MacBook. Simply ask Claude Code or your favorite AI coding assistant to use the [macOS Setup Skill](.claude/skills/macos-setup/SKILL.md) and it will automatically clone the repository, install all dependencies, configure services (MongoDB, Keycloak, registry), register sample servers, and verify the complete stack is running. Perfect for single-developer environments and hands-on exploration. Supports both full setup and complete teardown with a single command. *ECS/EKS deployment skill coming very soon.*\n\n- **AI Registry MCP Server (airegistry-tools)** - Enables AI coding assistants (Claude Code, Roo Code, Cursor, etc.) to discover and query MCP servers, agents, and skills directly from the registry. Provides 5 tools: `list_services`, `list_agents`, `list_skills`, `intelligent_tool_finder` (semantic search), and `healthcheck`. Auto-registered on registry startup with no manual setup required. See [AI Registry Tools documentation](docs/ai-registry-tools.md) for details.\n\n- **Governance & Security Enhancements** - Enhanced audit logging with searchable filters (username, MCP server) and statistics dashboard showing top users, operations, timeline charts, and per-user activity breakdowns. System uptime and health stats now visible in the header with deployment info, registry statistics, and database status. Comprehensive security hardening via Bandit scanning addressed subprocess security (B603/B607), SQL injection prevention (B608), hardcoded credentials detection (B105), and other vulnerability patterns across the codebase. All security findings documented and resolved with proper justifications for necessary exceptions.\n\n- **IAM Settings UI** - Visual interface for managing users, groups, and M2M service accounts directly from the web UI. Create and configure access control groups with fine-grained permissions for servers, tools, agents, and UI features. Manage human users with group assignments, and create M2M service accounts for AI agents with OAuth2 client credentials. Features include searchable server/agent/tool selectors, JSON import/export for scope configurations, and support for both MCP servers and virtual servers in access rules. Works with both Keycloak and Microsoft Entra ID identity providers. [IAM Settings Guide](docs/iam-settings-ui.md)\n\n- **System Configuration Viewer** - View and export all registry configuration parameters through the Settings UI. Admin-only panel displays 11 configuration groups (Deployment, Storage, Auth, Embeddings, Health, WebSocket, Security Scanning, Audit, Federation, Discovery) with sensitive value masking. Export configuration in ENV, JSON, TFVARS, or YAML formats for deployment automation. API endpoints provide programmatic access at `/api/config/full` and `/api/config/export`. [Configuration Guide](docs/configuration.md#viewing-configuration-via-ui)\n\n- **Virtual MCP Server Support** - Aggregate tools, resources, and prompts from multiple backend MCP servers into a single unified endpoint. Clients connect to one virtual server that presents a curated, access-controlled view of capabilities from any combination of registered backends. Features include tool aliasing (resolve naming conflicts), version pinning (lock to specific backend versions), per-tool scope-based access control, session multiplexing (one client session maps to N backend sessions transparently), and 60-second cached aggregation for `tools/list`, `resources/list`, and `prompts/list`. Supports all MCP JSON-RPC methods including `initialize`, `ping`, `tools/call`, `resources/read`, and `prompts/get`. [Design Document](docs/design/virtual-mcp-server.md) | [Operations Guide](docs/virtual-server-operations.md)\n\n- **Registry-Only Deployment Mode** - Run the registry as a standalone catalog/discovery service without nginx gateway integration. In `registry-only` mode, nginx configuration is not updated when servers are registered, and MCP proxy requests return 503 with instructions to use direct connection. The frontend adapts to show `proxy_pass_url` instead of gateway URLs. Combined with `REGISTRY_MODE` settings (`full`, `skills-only`, `mcp-servers-only`, `agents-only`), you can configure the registry for specific use cases. For example, set `REGISTRY_MODE=skills-only` to run a dedicated Skills Registry that only manages Agent Skills (SKILL.md files) without MCP servers or A2A agents - ideal for teams that want a lightweight skill library. The UI automatically adapts to show only relevant features, and API endpoints for disabled features return 503. Invalid combinations like `with-gateway + skills-only` are auto-corrected with warnings. [Registry Deployment Modes Guide](docs/registry-deployment-modes.md)\n\n- **Agent Skills Registry** - Register, discover, and manage reusable instruction sets (SKILL.md files) that enhance AI coding assistants with specialized workflows. Skills are hosted on GitHub, GitLab, or Bitbucket and registered in the MCP Gateway Registry for discovery and access control. Features include YAML frontmatter parsing for metadata extraction, health monitoring with URL accessibility checks, visibility controls (public/private/group), star ratings, semantic search integration, tool dependency validation, and a rich UI with SKILL.md content modals. Security includes automatic security scanning during registration using [Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/cisco-ai-skill-scanner) with YARA pattern matching, LLM analysis, and static code inspection. SSRF protection with redirect validation ensures safe URL handling. [Agent Skills Guide](docs/agent-skills-operational-guide.md) | [Architecture](docs/design/agent-skills-architecture.md) | [Security Scanning](docs/security-scanner.md#agent-skills-security-scanning)\n\n- **📋 Compliance Audit Logging** - Comprehensive audit logging for security monitoring and compliance. Captures all Registry API and MCP Gateway access events with user identity, operation details, and timing. Features include automatic credential masking (tokens, cookies, passwords are never logged), TTL-based log retention (default 7 days, configurable), admin-only audit viewer UI with filtering and export (JSONL/CSV), and non-blocking async design. Supports SOC 2 and GDPR requirements with who/what/when/where/outcome tracking. [Audit Logging Guide](docs/audit-logging.md)\n\n- **🌐 Peer-to-Peer Registry Federation** - Connect multiple MCP Gateway Registry instances for bidirectional server and agent synchronization. Central IT teams can aggregate visibility across Line of Business registries, or LOBs can inherit shared tools from a central hub. Features include configurable sync modes (all, whitelist, tag filter), scheduled and on-demand sync, static token authentication for IdP-agnostic deployments, Fernet-encrypted credential storage, generation-based orphan detection, and path namespacing to prevent collisions. Synced items are read-only and display their source registry. A VS Code-style Settings UI provides peer management, sync triggering, and status monitoring. [Architecture Design](docs/design/federation-architecture.md) | [Operational Guide](docs/federation-operational-guide.md)\n\n- **🔑 Static Token Auth for Registry API** - Access Registry API endpoints (`/api/*`, `/v0.1/*`) using a static API key instead of IdP-based JWT validation. Designed for trusted network environments, CI/CD pipelines, and CLI tooling where configuring a full identity provider may not be practical. MCP Gateway endpoints continue to require full IdP authentication. Includes startup validation that disables the feature if no token is configured. [Registry API Authentication Guide](docs/registry-api-auth.md)\n\n- **🔀 MCP Server Version Routing** - Run multiple versions of the same MCP server simultaneously behind a single gateway endpoint. Register new versions as inactive, test them with the `X-MCP-Server-Version` header, then promote to active with a single API call or UI click. Features include instant rollback, version pinning for clients, deprecation lifecycle with sunset dates, automatic nginx map-based O(1) routing, cascade deletion of all versions, and post-swap health checks. The dashboard displays both the admin-controlled routing version and the MCP server-reported software version independently. Only the active version appears in search results and health checks. [Design Document](docs/design/server-versioning.md) | [Operations Guide](docs/server-versioning-operations.md)\n- **👥 Multi-Provider IAM with Harmonized API** - Full Identity and Access Management support for Keycloak, Microsoft Entra ID, Okta, and Auth0. The registry API provides a unified experience for user and group management regardless of which IdP you use. Human users can log in via the UI and generate self-signed JWT tokens (with the same permissions as their session) for CLI tools and AI coding assistants. Service accounts (M2M) enable AI agent identity with OAuth2 Client Credentials flow. Fine-grained access control through scopes defines exactly which MCP servers, methods, tools, and agents each user can access. [Authentication Design](docs/design/authentication-design.md) | [IdP Provider Architecture](docs/design/idp-provider-support.md) | [Scopes Management](docs/scopes-mgmt.md) | [Entra ID Setup](docs/entra-id-setup.md) | [Okta Setup](docs/okta-setup.md) | [Auth0 Setup](docs/auth0.md)\n- **🏷️ Custom Metadata for Servers & Agents** - Add rich custom metadata to MCP servers and agents for organization, compliance, and integration tracking. Metadata is fully searchable via semantic search, enabling queries like \"team:data-platform\", \"PCI-DSS compliant\", or \"owner:alice@example.com\". Use cases include team ownership, compliance tracking (PCI-DSS, HIPAA), cost center allocation, deployment regions, JIRA tickets, and custom tags. Backward compatible with existing registrations. [Metadata Usage Guide](docs/custom-metadata.md)\n- **🔎 Enhanced Hybrid Search** - Improved semantic search combining vector similarity with tokenized keyword matching for servers, tools, and agents. Explicit name references now boost relevance scores, ensuring exact matches appear first. [Hybrid Search Architecture](docs/design/hybrid-search-architecture.md)\n- **🛡️ Security Scan Results in UI** - Security scan results are now displayed directly on Server and Agent cards with color-coded shield icons (gray/green/red). Click the shield icon to view detailed scan results and trigger rescans from the UI. [Security Scanner Documentation](docs/security-scanner.md)\n- **🧪 Comprehensive Test Suite & Updated LLM Documentation** - Full pytest test suite with 701+ passing tests (unit, integration, E2E) running automatically on all PRs via GitHub Actions. 35% minimum coverage (targeting 80%), ~30 second execution with 8 parallel workers. Updated llms.txt provides comprehensive documentation for LLM coding assistants covering storage backend migration (file → DocumentDB/MongoDB), repository patterns, AWS ECS deployment, Microsoft Entra ID integration, dual security scanning, federation architecture, rating system, testing standards, and critical code organization antipatterns. [Testing Guide](docs/testing/README.md) | [docs/llms.txt](docs/llms.txt)\n- **📊 DocumentDB & MongoDB CE Storage Backend** - Distributed storage with MongoDB-compatible backends. DocumentDB provides native HNSW vector search for sub-100ms semantic queries in production deployments, while MongoDB Community Edition 8.2 enables full-featured local development with replica sets. Both backends use the same repository abstraction layer with automatic collection management, optimized indexes, and application-level vector search for MongoDB CE. Switch between MongoDB CE (local testing) and DocumentDB (production) with a single environment variable. Note: File-based storage is deprecated and will be removed in a future release. MongoDB CE is recommended for local development. [Configuration Guide](docs/configuration.md#storage-backend-configuration) | [Storage Architecture](docs/design/storage-architecture-mongodb-documentdb.md)\n- **🔒 A2A Agent Security Scanning** - Integrated security scanning for A2A agents using [Cisco AI Defense A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner). Automatic security scans during agent registration with YARA pattern matching, A2A specification validation, and heuristic threat detection. Features include automatic tagging of unsafe agents, configurable blocking policies, and detailed scan reports with API endpoints for viewing results and triggering rescans.\n- **🔧 Registry Management API** - New programmatic API for managing servers, groups, and users. Python client (`api/registry_client.py`) with type-safe interfaces, RESTful HTTP endpoints (`/api/management/*`), and comprehensive error handling. Replaces shell scripts with modern API approach while maintaining backward compatibility. [API Documentation](api/README.md) | [Service Management Guide](docs/service-management.md)\n- **⭐ Server & Agent Rating System** - Rate and review agents with an interactive 5-star rating widget. Users can submit ratings via the UI or CLI, view aggregate ratings with individual rating details, and update their existing ratings. Features include a rotating buffer (max 100 ratings per agent), one rating per user, float average calculations, and full OpenAPI documentation. Enables community-driven agent quality assessment and discovery.\n- **🧠 Flexible Embeddings Support** - Choose from three embedding provider options for semantic search: local sentence-transformers, OpenAI, or any LiteLLM-supported provider including Amazon Bedrock Titan, Cohere, and 100+ other models. Switch providers with simple configuration changes. [Embeddings Guide](docs/embeddings.md)\n- **☁️ AWS ECS Deployment** - Deployment configuration on Amazon ECS Fargate with multi-AZ architecture, Application Load Balancer with HTTPS, auto-scaling, CloudWatch monitoring, and NAT Gateway redundancy. Complete Terraform configuration for deploying the entire stack. [ECS Deployment Guide](terraform/aws-ecs/README.md)\n- **📦 Flexible Deployment Modes** - Three deployment options to match your requirements: (1) CloudFront Only for quick setup without custom domains, (2) Custom Domain with Route53/ACM for branded URLs, or (3) CloudFront + Custom Domain for production with CDN benefits. [Deployment Modes Guide](docs/deployment-modes.md)\n- **🔗 Federated Registry** - MCP Gateway registry now supports federation of servers and agents from other registries. [Federation Guide](docs/federation.md)\n- **🔗 Agent-to-Agent (A2A) Protocol Support** - Agents can now register, discover, and communicate with other agents through a secure, centralized registry. Enable autonomous agent ecosystems with Keycloak-based access control and fine-grained permissions. [A2A Guide](docs/a2a.md)\n- **🏢 Microsoft Entra ID Integration** - Enterprise SSO with Microsoft Entra ID (Azure AD) authentication. Group-based access control, conditional access policies, and seamless integration with existing Microsoft 365 environments. [Entra ID Setup Guide](docs/entra-id-setup.md)\n- **🤖 Agentic CLI for MCP Registry** - Talk to the Registry in natural language using a Claude Code-like interface. Discover tools, ask questions, and execute MCP commands conversationally. [Learn more](docs/mcp-registry-cli.md)\n- **🔒 MCP Server Security Scanning** - Integrated vulnerability scanning with [Cisco AI Defense MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner). Automatic security scans during server registration, periodic registry-wide scans with detailed markdown reports, and automatic disabling of servers with security issues.\n- **📥 Import Servers from Anthropic MCP Registry** - Import curated MCP servers from Anthropic's registry with a single command. [Import Guide](docs/anthropic-registry-import.md)\n- **🔌 Anthropic MCP Registry REST API Compatibility** - Full compatibility with Anthropic's MCP Registry REST API specification. [API Documentation](docs/anthropic_registry_api.md)\n- **🔎 Unified Semantic Search for Servers, Tools & Agents** - Natural-language search across every MCP server, its tools, and registered A2A agents using `POST /api/search/semantic`. Works from the dashboard UI (session cookie auth) or programmatically with JWT Bearer tokens, returning relevance-scored matches per entity type in a single response.\n- **🚀 Pre-built Images** - Deploy instantly with pre-built Docker images. [Get Started](#option-a-pre-built-images-instant-setup) | [macOS Guide](docs/macos-setup-guide.md)\n- **🔐 Keycloak Integration** - Enterprise authentication with AI agent audit trails and group-based authorization. [Learn more](docs/keycloak-integration.md)\n- **⚡ Amazon Bedrock AgentCore Integration** - AgentCore Gateway support with dual authentication. [Integration Guide](docs/agentcore.md)\n\n\n---\n\n## A2A Agents - Example Implementations\n\nThe registry includes two example A2A agents that demonstrate how both human developers and autonomous AI agents can discover, register, and use agents through the unified Agent Registry. Agents can programmatically discover other agents via semantic search and use them through the A2A protocol, enabling dynamic agent composition and autonomous agent orchestration.\n\n### Example Agents\n\n| Agent | Path | Skills |\n|-------|------|--------|\n| **Travel Assistant Agent** | `/travel-assistant-agent` | Flight search, pricing checks, recommendations, trip planning |\n| **Flight Booking Agent** | `/flight-booking-agent` | Availability checks, flight reservations, payments, reservation management |\n\n### Agent Discovery\n\n**View in Registry UI:**\nOpen the registry and navigate to the **A2A Agents** tab to browse registered agents with their full metadata, capabilities, and skills.\n\n**Search via CLI:**\nDevelopers can search for agents by natural language description:\n\n```bash\n# Search for agents that can help book a trip\ncli/agent_mgmt.sh search \"need an agent to book a trip\"\n```\n\n**Example Output:**\n```\nFound 4 agent(s) matching 'need an agent to book a trip':\n--------------------------------------------------------------------------------------------------------------\nAgent Name | Path | Score\n--------------------------------------------------------------------------------------------------------------\nTravel Assistant Agent | /travel-assistant-agent | 0.8610\nFlight Booking Agent | /flight-booking-agent | 1.2134\n--------------------------------------------------------------------------------------------------------------\n```\n\n### Agent-to-Agent Discovery API\n\nThe registry provides a **semantic search API** that agents can use as a tool to discover other A2A agents at runtime. This API enables dynamic agent composition where agents find collaborators based on capabilities rather than hardcoded references.\n\n**Discovery API Endpoint:**\n```\nPOST /api/agents/discover/semantic?query=&max_results=5\nAuthorization: Bearer \n```\n\n**Response includes:**\n- Agent name, description, and endpoint URL\n- Agent card metadata with skills and capabilities\n- Relevance score for ranking matches\n- Trust level and visibility settings\n\n**How agents use it:**\n1. An agent calls the registry's semantic search API with a natural language query (e.g., \"agent that can book flights\")\n2. The registry returns matching agents with their endpoint URLs and full agent card metadata\n3. The agent uses the agent card to understand capabilities and invokes the discovered agent via A2A protocol\n\n**Example - Travel Assistant discovering and invoking Flight Booking Agent:**\n```\nUser: \"I need to book a flight from NYC to LA\"\n\nTravel Assistant:\n 1. Calls registry API: POST /api/agents/discover/semantic?query=\"book flights\"\n 2. Registry returns Flight Booking Agent with endpoint URL and agent card\n 3. Uses agent card to understand capabilities, then sends A2A message to Flight Booking Agent\n 4. Returns booking confirmation to user\n```\n\nThis pattern enables agents to dynamically extend their capabilities by discovering specialized agents for tasks they cannot handle directly.\n\n**Agent Cards:** View the agent card metadata at [agents/a2a/test/](agents/a2a/test/) to see the complete agent definitions including skills, protocols, and capabilities.\n\nFor complete agent deployment and testing documentation, see [agents/a2a/README.md](agents/a2a/README.md).\n\n---\n\n## Core Use Cases\n\n### AI Agent & Coding Assistant Governance\nProvide both autonomous AI agents and human developers with secure access to approved tools through AI coding assistants (VS Code, Cursor, Claude Code) while maintaining IT oversight and compliance.\n\n### Enterprise Security & Compliance \nCentralized authentication, fine-grained permissions, and comprehensive audit trails for SOX/GDPR compliance pathways across both human and AI agent access patterns.\n\n### Dynamic Tool Discovery\nAI agents can autonomously discover and execute specialized tools beyond their initial capabilities using intelligent semantic search, while developers get guided tool discovery through their coding assistants.\n\n### Unified Access Gateway\nSingle gateway supporting both autonomous AI agents (machine-to-machine) and AI coding assistants (human-guided) with consistent authentication and tool access patterns.\n\n---\n\n## Architecture\n\nThe MCP Gateway & Registry provides a unified platform for both autonomous AI agents and AI coding assistants to access enterprise-curated tools through a centralized gateway with comprehensive authentication and governance.\n\n```mermaid\nflowchart TB\n subgraph Human_Users[\"Human Users\"]\n User1[\"Human User 1\"]\n User2[\"Human User 2\"]\n UserN[\"Human User N\"]\n end\n\n subgraph AI_Agents[\"AI Agents\"]\n Agent1[\"AI Agent 1\"]\n Agent2[\"AI Agent 2\"]\n Agent3[\"AI Agent 3\"]\n AgentN[\"AI Agent N\"]\n end\n\n subgraph EC2_Gateway[\"MCP Gateway & Registry (Amazon EC2 Instance)\"]\n subgraph NGINX[\"NGINX Reverse Proxy\"]\n RP[\"Reverse Proxy Router\"]\n end\n \n subgraph AuthRegistry[\"Authentication & Registry Services\"]\n AuthServer[\"Auth Server
(Dual Auth)\"]\n Registry[\"Registry
Web UI\"]\n RegistryMCP[\"Registry
MCP Server\"]\n end\n \n subgraph LocalMCPServers[\"Local MCP Servers\"]\n MCP_Local1[\"MCP Server 1\"]\n MCP_Local2[\"MCP Server 2\"]\n end\n end\n \n %% Identity Provider\n IdP[Identity Provider
Keycloak/Cognito]\n \n subgraph EKS_Cluster[\"Amazon EKS/EC2 Cluster\"]\n MCP_EKS1[\"MCP Server 3\"]\n MCP_EKS2[\"MCP Server 4\"]\n end\n \n subgraph APIGW_Lambda[\"Amazon API Gateway + AWS Lambda\"]\n API_GW[\"Amazon API Gateway\"]\n Lambda1[\"AWS Lambda Function 1\"]\n Lambda2[\"AWS Lambda Function 2\"]\n end\n \n subgraph External_Systems[\"External Data Sources & APIs\"]\n DB1[(Database 1)]\n DB2[(Database 2)]\n API1[\"External API 1\"]\n API2[\"External API 2\"]\n API3[\"External API 3\"]\n end\n \n %% Connections from Human Users\n User1 -->|Web Browser
Authentication| IdP\n User2 -->|Web Browser
Authentication| IdP\n UserN -->|Web Browser
Authentication| IdP\n User1 -->|Web Browser
HTTPS| Registry\n User2 -->|Web Browser
HTTPS| Registry\n UserN -->|Web Browser
HTTPS| Registry\n \n %% Connections from Agents to Gateway\n Agent1 -->|MCP Protocol
SSE with Auth| RP\n Agent2 -->|MCP Protocol
SSE with Auth| RP\n Agent3 -->|MCP Protocol
Streamable HTTP with Auth| RP\n AgentN -->|MCP Protocol
Streamable HTTP with Auth| RP\n \n %% Auth flow connections\n RP -->|Auth validation| AuthServer\n AuthServer -.->|Validate credentials| IdP\n Registry -.->|User authentication| IdP\n RP -->|Tool discovery| RegistryMCP\n RP -->|Web UI access| Registry\n \n %% Connections from Gateway to MCP Servers\n RP -->|SSE| MCP_Local1\n RP -->|SSE| MCP_Local2\n RP -->|SSE| MCP_EKS1\n RP -->|SSE| MCP_EKS2\n RP -->|Streamable HTTP| API_GW\n \n %% Connections within API GW + Lambda\n API_GW --> Lambda1\n API_GW --> Lambda2\n \n %% Connections to External Systems\n MCP_Local1 -->|Tool Connection| DB1\n MCP_Local2 -->|Tool Connection| DB2\n MCP_EKS1 -->|Tool Connection| API1\n MCP_EKS2 -->|Tool Connection| API2\n Lambda1 -->|Tool Connection| API3\n\n %% Style definitions\n classDef user fill:#fff9c4,stroke:#f57f17,stroke-width:2px\n classDef agent fill:#e1f5fe,stroke:#29b6f6,stroke-width:2px\n classDef gateway fill:#e8f5e9,stroke:#66bb6a,stroke-width:2px\n classDef nginx fill:#f3e5f5,stroke:#ab47bc,stroke-width:2px\n classDef mcpServer fill:#fff3e0,stroke:#ffa726,stroke-width:2px\n classDef eks fill:#ede7f6,stroke:#7e57c2,stroke-width:2px\n classDef apiGw fill:#fce4ec,stroke:#ec407a,stroke-width:2px\n classDef lambda fill:#ffebee,stroke:#ef5350,stroke-width:2px\n classDef dataSource fill:#e3f2fd,stroke:#2196f3,stroke-width:2px\n \n %% Apply styles\n class User1,User2,UserN user\n class Agent1,Agent2,Agent3,AgentN agent\n class EC2_Gateway,NGINX gateway\n class RP nginx\n class AuthServer,Registry,RegistryMCP gateway\n class IdP apiGw\n class MCP_Local1,MCP_Local2 mcpServer\n class EKS_Cluster,MCP_EKS1,MCP_EKS2 eks\n class API_GW apiGw\n class Lambda1,Lambda2 lambda\n class DB1,DB2,API1,API2,API3 dataSource\n```\n\n**Key Architectural Benefits:**\n- **Unified Gateway**: Single point of access for both AI agents and human developers through coding assistants\n- **Dual Authentication**: Supports both human user authentication and machine-to-machine agent authentication\n- **Scalable Infrastructure**: Nginx reverse proxy with horizontal scaling capabilities\n- **Multiple Transports**: SSE and Streamable HTTP support for different client requirements\n\n---\n\n## Key Advantages\n\n### **Security Features**\n- OAuth 2.0/3.0 compliance with IdP integration\n- Fine-grained access control at tool and method level\n- Zero-trust network architecture\n- Complete audit trails and comprehensive analytics for compliance\n\n### **AI Agent & Developer Experience**\n- Single configuration works across autonomous AI agents and AI coding assistants (VS Code, Cursor, Claude Code, Cline)\n- Dynamic tool discovery with natural language queries for both agents and humans\n- Instant onboarding for new team members and AI agent deployments\n- Unified governance for both AI agents and human developers\n\n### **Deployment Features**\n- Container-native (Docker/Kubernetes)\n- Real-time health monitoring and alerting\n- Dual authentication supporting both human and machine authentication\n\n---\n## Quick Start\n\nThere are 4 options for setting up the MCP Gateway & Registry:\n\n- **Option A: AI-Assisted macOS Setup** — The absolute fastest way to get started on macOS. Ask your AI coding assistant to use the [macOS Setup Skill](.claude/skills/macos-setup/SKILL.md) for fully automated one-command setup. Perfect for experimentation.\n- **Option B: Pre-built Images** — Fast setup using pre-built Docker or Podman containers. Recommended for most users.\n- **Option C: Podman (Rootless)** — Detailed Podman-specific instructions for macOS and rootless Linux environments.\n- **Option D: Build from Source** — Full source build for customization or development.\n\n### Option A: AI-Assisted macOS Setup (Fastest)\n\n**The easiest way to get started on macOS.** Simply ask Claude Code or your AI coding assistant:\n\n> \"Use the macOS setup skill to install and configure the MCP Gateway & Registry\"\n\nThe [macOS Setup Skill](.claude/skills/macos-setup/SKILL.md) will automatically:\n- ✅ Clone the repository and install all dependencies (Homebrew, Python, UV, Docker, Node.js)\n- ✅ Configure and start MongoDB with replica set\n- ✅ Set up and initialize Keycloak with admin user\n- ✅ Start the registry and auth server\n- ✅ Register the Cloudflare MCP docs server\n- ✅ Verify the complete stack is operational\n\n**Perfect for:** Single-developer experimentation, quick demos, hands-on exploration\n\n**What you need:** macOS with an AI coding assistant (Claude Code, Cursor, etc.)\n\n**Clean up:** When done, ask your AI assistant to \"teardown the MCP Gateway setup\" for complete removal.\n\n*Note: ECS/EKS deployment skill coming very soon for production deployments.*\n\n---\n\n### Option B: Pre-built Images (Instant Setup)\n\nGet running with pre-built Docker containers in minutes. This is the recommended approach for most users.\n\n```bash\n# Clone and configure\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\ncp .env.example .env\n\n# Edit .env with your passwords (KEYCLOAK_ADMIN_PASSWORD, etc.)\nnano .env\n\n# Deploy with pre-built images\nexport DOCKERHUB_ORG=mcpgateway\n./build_and_run.sh --prebuilt\n\n# Access the Registry UI\nopen http://localhost:7860 # macOS\n# xdg-open http://localhost:7860 # Linux\n```\n\n**[Complete Quick Start Guide](docs/quickstart.md)** - Full step-by-step instructions including:\n- Prerequisites installation (Docker, Python, UV)\n- Environment configuration\n- MongoDB and Keycloak initialization\n- User and service account setup\n- Server and agent registration\n- Testing the gateway functionality\n\n**Benefits:** No build time | No Node.js required | No frontend compilation | Consistent tested images\n\n---\n\n### Option C: Podman (Rootless Container Deployment)\n\n**Perfect for macOS and rootless Linux environments**\n\nPodman provides rootless container execution without requiring privileged ports, making it ideal for:\n- **macOS** users with Podman Desktop\n- **Linux** users preferring rootless containers\n- **Development** environments where Docker daemon isn't available\n\n**Quick Podman Setup (macOS non-Apple Silicon):**\n\n```bash\n# Install Podman Desktop\nbrew install podman-desktop\n# OR download from: https://podman-desktop.io/\n```\n\nInside Podman Desktop, go to Preferences > Podman Machine and create a new machine with at least 4 CPUs and 8GB RAM. Alternatively, see more detailed [Podman installation guide](docs/installation.md#podman-installation) for instructions on setting this up on CLI.\n\n```bash\n# Initialize Podman machine\npodman machine init\npodman machine start\n\n# Verify installation\npodman --version\npodman compose version\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your credentials\n```\n\n**Deploy with Podman** see full Podman setup instructions (downloading, installing, and initializing a first Podman container, as well as troubleshooting) in our [Installation Guide](docs/installation.md#podman-installation).\n\n**Build with Podman:**\n\n```bash\n# Auto-detect (will use Podman if Docker not available)\n./build_and_run.sh --prebuilt\n\n# Explicit Podman mode (only non-Apple Silicon)\n./build_and_run.sh --prebuilt --podman\n\n# Access registry at non-privileged ports\n# On macOS:\nopen http://localhost:8080\n# On Linux: xdg-open http://localhost:8080\n```\n\n> Note: **Apple Silicon (M1/M2/M3)?** Don't use `--prebuilt` with Podman on ARM64. This will cause a \"proxy already running\" error. See [Podman on Apple Silicon Guide](docs/podman-apple-silicon.md).\n\n```bash\n# To run on Apple Silicon Macs:\n./build_and_run.sh --podman\n```\n\n**Key Differences vs. Docker:**\n- No root/sudo required\n- Works on macOS without privileged port access\n- HTTP port: `8080` (instead of `80`)\n- HTTPS port: `8443` (instead of `443`)\n- All other service ports unchanged\n\nFor detailed Podman setup instructions, see [Installation Guide](docs/installation.md#podman-installation) and [macOS Setup Guide](docs/macos-setup-guide.md#podman-deployment).\n\n### Option D: Build from Source\n\n**New to MCP Gateway?** Start with our [Complete Setup Guide](docs/complete-setup-guide.md) for detailed step-by-step instructions from scratch on AWS EC2.\n\n**Running on macOS?** See our [macOS Setup Guide](docs/macos-setup-guide.md) for platform-specific instructions and optimizations.\n\n### Testing & Integration Options\n\n**Test Suite:**\nThe project includes comprehensive automated testing with pytest:\n\n```bash\n# Run all tests\nmake test\n\n# Run only unit tests (fast)\nmake test-unit\n\n# Run with coverage report\nmake test-coverage\n\n# Run specific test categories\nuv run pytest -m unit # Unit tests only\nuv run pytest -m integration # Integration tests\nuv run pytest -m \"not slow\" # Skip slow tests\n```\n\n**Test Structure:**\n- **Unit Tests** (`tests/unit/`) - Fast, isolated component tests\n- **Integration Tests** (`tests/integration/`) - Component interaction tests\n- **E2E Tests** (`tests/integration/test_e2e_workflows.py`) - Complete workflow tests\n\n**Python Agent:**\n- `agents/agent.py` - Full-featured Python agent with advanced AI capabilities\n\n**Testing Documentation:**\n- [Testing Guide](docs/testing/README.md) - Comprehensive testing documentation\n- [Writing Tests](docs/testing/WRITING_TESTS.md) - How to write effective tests\n- [Test Maintenance](docs/testing/MAINTENANCE.md) - Maintaining test suite health\n\n**Pre-commit Hooks:**\n```bash\n# Install pre-commit hooks\npip install pre-commit\npre-commit install\n\n# Run hooks manually\npre-commit run --all-files\n```\n\n**Next Steps:** [Complete Installation Guide](docs/installation.md) | [Authentication Setup](docs/auth.md) | [AI Assistant Integration](docs/ai-coding-assistants-setup.md)\n\n---\n\n## Enterprise Features\n\n### AI Agents & Coding Assistants Integration\n\nTransform how both autonomous AI agents and development teams access enterprise tools with centralized governance:\n\n\n\n\n\n\n\n\n\n
\n\"Roo\n

Enterprise-curated MCP servers accessible through unified gateway

\n		\n\"Roo\n

AI assistants executing approved enterprise tools with governance

\n
\n\n### Observability\n\nComprehensive real-time metrics and monitoring through Grafana dashboards with dual-path storage: SQLite for detailed historical analysis and OpenTelemetry (OTEL) export for integration with Prometheus, CloudWatch, Datadog, and other monitoring platforms. Track authentication events, tool executions, discovery queries, and system performance metrics. [Learn more](docs/OBSERVABILITY.md)\n\n\"Grafana\n

Real-time metrics and observability dashboard tracking server health, tool usage, and authentication events

\n
\n\n### Anthropic MCP Registry Integration\n\nSeamlessly integrate with Anthropic's official MCP Registry to import and access curated MCP servers through your gateway:\n\n- **Import Servers**: Select and import desired servers from Anthropic's registry with a single command\n- **Unified Access**: Access imported servers through your gateway with centralized authentication and governance\n- **API Compatibility**: Full support for Anthropic's Registry REST API specification - point your Anthropic API clients to this registry to discover available servers\n\n\"Anthropic\n

Import and access curated MCP servers from Anthropic's official registry

\n\n[Import Guide](docs/anthropic-registry-import.md) | [Registry API Documentation](docs/anthropic_registry_api.md)\n\n### Federation - External Registry Integration\n\n**Unified Multi-Registry Access:**\n- **Anthropic MCP Registry** - Import curated MCP servers with purple `ANTHROPIC` visual tags\n- **Workday ASOR** - Import AI agents from Agent System of Record with orange `ASOR` visual tags \n- **Automatic Sync** - Scheduled synchronization with external registries\n- **Visual Identification** - Clear visual tags distinguish federation sources in the UI\n- **Centralized Management** - Single control plane for all federated servers and agents\n\n**Quick Setup:**\n```bash\n# Configure federation sources\necho 'ASOR_ACCESS_TOKEN=your_token' >> .env\n\n# Update federation.json with your sources\n# Restart services\n./build_and_run.sh\n```\n\n[**📖 Complete Federation Guide**](docs/federation.md) - Environment setup, authentication, configuration, and troubleshooting\n\n### Security Scanning\n\n**Integrated Vulnerability Detection:**\n- **Automated Security Scanning** - Integrated vulnerability scanning for MCP servers using [Cisco AI Defence MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner), with automatic scans during registration and support for periodic registry-wide scans\n- **Detailed Security Reports** - Comprehensive markdown reports with vulnerability details, severity assessments, and remediation recommendations\n- **Automatic Protection** - Servers with security issues are automatically disabled with security-pending status to protect your infrastructure\n- **Compliance Ready** - Security audit trails and vulnerability tracking for enterprise compliance requirements\n\n### Authentication & Authorization\n\n**Multiple Identity Modes:**\n- **Machine-to-Machine (M2M)** - For autonomous AI agents and automated systems\n- **Three-Legged OAuth (3LO)** - For external service integration (Atlassian, Google, GitHub)\n- **Session-Based** - For human developers using AI coding assistants and web interface\n\n**Supported Identity Providers:** Keycloak, Microsoft Entra ID, Okta, Auth0, Amazon Cognito, and any OAuth 2.0 compatible provider. [Learn more](docs/auth.md)\n\n**Fine-Grained Permissions:** Tool-level, method-level, team-based, and temporary access controls. [Learn more](docs/scopes.md)\n\n### Deployment Options\n\n**Cloud Platforms:** Amazon EC2, Amazon EKS\n\n---\n\n## Telemetry\n\nThe registry collects **anonymous, non-sensitive** usage telemetry to help us understand adoption patterns and improve the product. Both tiers are **opt-out** and **on by default**.\n\n**What is sent (Tier 1 -- startup ping):** Registry version, Python version, OS, CPU architecture, cloud provider, storage backend, auth provider, and deployment mode. No IP addresses, hostnames, file paths, user data, or any PII.\n\n**Also sent by default (Tier 2 -- daily heartbeat):** Aggregate counts (number of servers, agents, skills, peers), search backend, embeddings provider, and uptime. Same privacy guarantees as Tier 1. Disable heartbeat only: `MCP_TELEMETRY_OPT_OUT=1`.\n\n> **Behavior change (post v1.0.18):** The daily heartbeat was previously opt-in (`MCP_TELEMETRY_OPT_IN=1`). It is now opt-out and sent by default. Since the heartbeat contains only aggregate counts (no PII), this aligns it with the startup ping behavior.\n\n**To opt out completely:**\n\n```bash\nexport MCP_TELEMETRY_DISABLED=1 # Disables both startup ping and heartbeat\n```\n\n**To disable heartbeat only (startup ping still sent):**\n\n```bash\nexport MCP_TELEMETRY_OPT_OUT=1\n```\n\nAll requests are HMAC-signed, rate-limited, and schema-validated. Telemetry is fail-silent and never impacts registry operation. Full details in the [Telemetry Documentation](docs/TELEMETRY.md).\n\n---\n\n## Deployments\n\n### AWS Elastic Container Service (ECS)\n\n
\n\"MCP\n
\n\n**Deployment configuration** on Amazon ECS Fargate with comprehensive enterprise features:\n\n- **Multi-AZ Architecture** - Redundancy across multiple availability zones\n- **Application Load Balancer** - HTTPS/SSL termination with automatic certificate management via ACM\n- **Auto-scaling** - Dynamic scaling based on CPU and memory utilization\n- **CloudWatch Integration** - Comprehensive monitoring, logging, and alerting\n- **NAT Gateway HA** - Redundant NAT gateway configuration for secure outbound connectivity\n- **Keycloak Integration** - Enterprise authentication with RDS Aurora PostgreSQL backend\n- **EFS Shared Storage** - Persistent storage for models, logs, and configuration\n- **Service Discovery** - AWS Cloud Map for service-to-service communication\n\n**[Complete ECS Deployment Guide](terraform/aws-ecs/README.md)** - Step-by-step instructions for deploying the entire stack with Terraform.\n\n### Amazon EKS (Kubernetes)\n\n**Coming Soon** - Kubernetes deployment on Amazon EKS with Helm charts for container orchestration at scale.\n\n---\n\n## Documentation\n\n| Getting Started | Enterprise Setup | Developer & Operations |\n|------------------|-------------------|------------------------|\n| [Complete Setup Guide](docs/complete-setup-guide.md)
**NEW!** Step-by-step from scratch on AWS EC2 | [Authentication Guide](docs/auth.md)
OAuth and identity provider integration | [AI Coding Assistants Setup](docs/ai-coding-assistants-setup.md)
VS Code, Cursor, Claude Code integration |\n| [Installation Guide](docs/installation.md)
Complete setup instructions for EC2 and EKS | [AWS ECS Deployment](terraform/aws-ecs/README.md)
Deployment guide for AWS ECS Fargate | [API Reference](docs/registry_api.md)
Programmatic registry management |\n| [Keycloak Integration](docs/keycloak-integration.md)
Enterprise identity with agent audit trails | [Token Refresh Service](docs/token-refresh-service.md)
Automated token refresh and lifecycle management | [MCP Registry CLI](docs/mcp-registry-cli.md)
Command-line client for registry management |\n| [Configuration Reference](docs/configuration.md)
Environment variables and settings | [Amazon Cognito Setup](docs/cognito.md)
Step-by-step IdP configuration | [Observability Guide](docs/OBSERVABILITY.md)
**NEW!** Metrics, monitoring, and OpenTelemetry setup |\n| [Auth0 Integration](docs/auth0.md)
Auth0 SSO with M2M support | [Okta Setup](docs/okta-setup.md)
Okta IdP configuration | [Entra ID Setup](docs/entra-id-setup.md)
Microsoft Entra ID integration |\n| | [Anthropic Registry Import](docs/anthropic-registry-import.md)
**NEW!** Import servers from Anthropic MCP Registry | [Federation Guide](docs/federation.md)
External registry integration (Anthropic, ASOR) |\n| | | [P2P Federation Guide](docs/federation-operational-guide.md)
**NEW!** Peer-to-peer registry federation |\n| | [Service Management](docs/service-management.md)
Server lifecycle and operations | [Anthropic Registry API](docs/anthropic_registry_api.md)
**NEW!** REST API compatibility |\n| | | [Fine-Grained Access Control](docs/scopes.md)
Permission management and security |\n| | | [Dynamic Tool Discovery](docs/dynamic-tool-discovery.md)
Autonomous agent capabilities |\n| | | [Deployment Guide](docs/installation.md)
Complete setup for deployment environments |\n| | | [Troubleshooting Guide](docs/faq/index.md)
Common issues and solutions |\n\n---\n\n## Community\n\n### Get Involved\n\n**Join the Discussion**\n- [GitHub Discussions](https://github.com/agentic-community/mcp-gateway-registry/discussions) - Feature requests and general discussion\n- [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues) - Bug reports and feature requests\n\n**Contributing**\n- [Contributing Guide](CONTRIBUTING.md) - How to contribute code and documentation\n- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines\n- [Security Policy](SECURITY.md) - Responsible disclosure process\n\n### Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=agentic-community/mcp-gateway-registry&type=Date)](https://star-history.com/#agentic-community/mcp-gateway-registry&Date)\n\n### Roadmap\n\nOur development roadmap is organized into release milestones with clear deliverables and progress tracking:\n\n| Milestone | Progress | Status | Key Issues |\n|-----------|----------|--------|------------|\n| **v1.0.20** | 100% (11/11) | Complete | [#871 - Unified Auth](https://github.com/agentic-community/mcp-gateway-registry/issues/871), [#851 - M2M Registration](https://github.com/agentic-community/mcp-gateway-registry/issues/851), [#824 - Python 3.14](https://github.com/agentic-community/mcp-gateway-registry/issues/824), [#809 - Registration Gate](https://github.com/agentic-community/mcp-gateway-registry/issues/809), [#779 - Multi API Keys](https://github.com/agentic-community/mcp-gateway-registry/issues/779), [#742 - Webhooks](https://github.com/agentic-community/mcp-gateway-registry/issues/742) and 5 more |\n| **v1.0.21** | 100% (5/5) | Complete | [#906 - Admin Data Export](https://github.com/agentic-community/mcp-gateway-registry/issues/906), [#897 - Per-skill Auth Credentials UI](https://github.com/agentic-community/mcp-gateway-registry/issues/897), [#891 - CSRF Toggle Fix](https://github.com/agentic-community/mcp-gateway-registry/issues/891), [#886 - Centralized Log Rotation](https://github.com/agentic-community/mcp-gateway-registry/issues/886), [#856 - ARM64 Images](https://github.com/agentic-community/mcp-gateway-registry/issues/856) |\n| **v1.0.22** | 0% (0/5) | Planned | [#867 - Prometheus Metrics Endpoint](https://github.com/agentic-community/mcp-gateway-registry/issues/867), [#847 - A2A Reverse Proxy Gateway](https://github.com/agentic-community/mcp-gateway-registry/issues/847), [#844 - Dependency Management](https://github.com/agentic-community/mcp-gateway-registry/issues/844), [#744 - AI Chat Assistant](https://github.com/agentic-community/mcp-gateway-registry/issues/744), [#500 - Logout Routing Fix](https://github.com/agentic-community/mcp-gateway-registry/issues/500) |\n| **Parking Lot** | Backlog | Backlog | 23 open issues awaiting prioritization |\n\n**Status Legend:** Complete, Planned, Backlog\n\n---\n\n#### Major Features\n\nThe following major features span multiple milestones and represent significant architectural improvements:\n\n- **[#867 - Prometheus Metrics Endpoint](https://github.com/agentic-community/mcp-gateway-registry/issues/867)** **PLANNED** (v1.0.22)\n Expose a `/metrics` endpoint on the registry for in-process Prometheus counters.\n\n- **[#847 - A2A Reverse Proxy Gateway](https://github.com/agentic-community/mcp-gateway-registry/issues/847)** **PLANNED** (v1.0.22)\n Add reverse proxy gateway support for A2A agents.\n\n- **[#744 - AI Chat Assistant](https://github.com/agentic-community/mcp-gateway-registry/issues/744)** **PLANNED** (v1.0.22)\n Embedded AI chat assistant for registry operations, discovery, and agent design.\n\n- **[#665 - Agent-to-Agent Knowledge Sharing](https://github.com/agentic-community/mcp-gateway-registry/issues/665)** **BACKLOG**\n Enable agents to share and discover knowledge through the AI Registry, forming a collaborative knowledge network.\n\n- **[#666 - Context Hub MVP](https://github.com/agentic-community/mcp-gateway-registry/issues/666)** **BACKLOG**\n Implement Context Hub with card creation, search, and auto-discovery for agent knowledge management.\n\n- **[#614 - MCP OAuth 2.1 Authorization Spec](https://github.com/agentic-community/mcp-gateway-registry/issues/614)** **BACKLOG**\n Implement RFC 9728 Protected Resource Metadata with native IDE support for MCP OAuth 2.1 authorization.\n\n- **[#556 - AI Gateway & Registry Rebrand](https://github.com/agentic-community/mcp-gateway-registry/issues/556)** **BACKLOG**\n Rename \"MCP Gateway Registry\" to \"AI Gateway & Registry\" to reflect expanded support for agents and tools beyond MCP.\n\n- **[#605 - AgentCore Auto-Registration](https://github.com/agentic-community/mcp-gateway-registry/issues/605)** **COMPLETED** (April 2026)\n Automated discovery and registration of Bedrock AgentCore gateways with credential management integration. Full `cli/agentcore/` module with boto3 discovery, registration, token refresh, and security scheme support.\n\n- **[#641 - Okta Identity Provider](https://github.com/agentic-community/mcp-gateway-registry/issues/641)** **COMPLETED**\n Added Okta as an identity provider option alongside Keycloak, Entra ID, Auth0, GitHub, and Google OAuth2.\n\n- **[#557-559 - Observability & Telemetry Suite](https://github.com/agentic-community/mcp-gateway-registry/issues/557)** **COMPLETED**\n Comprehensive telemetry infrastructure with server-side collector, client-side instrumentation, and end-to-end enhancements. [Telemetry docs](docs/TELEMETRY.md).\n\n- **[#129 - Virtual MCP Server Support](https://github.com/agentic-community/mcp-gateway-registry/issues/129)** **COMPLETED**\n Dynamic tool aggregation and intelligent routing using Lua scripting. Enables logical grouping of tools from multiple backend servers into a single virtual endpoint.\n\n- **[#232 - A2A Curated Registry Discovery](https://github.com/agentic-community/mcp-gateway-registry/issues/232)** **COMPLETED**\n Enable agent-to-agent discovery and tool invocation through curated registry patterns.\n\n- **[#260 - Federation Between MCP Registry Instances](https://github.com/agentic-community/mcp-gateway-registry/issues/260)** **COMPLETED**\n Federated registry with bi-directional sync, peer management, chain prevention, orphan detection, and security scan propagation across registries.\n\n- **[#297 - Unified UI Registration Flow](https://github.com/agentic-community/mcp-gateway-registry/issues/297)** **COMPLETED**\n Streamlined registration experience for both MCP servers and A2A agents through a unified interface.\n\n- **[#295 - Multi-Level Tool Usage Rate Limiting](https://github.com/agentic-community/mcp-gateway-registry/issues/295)** **BACKLOG**\n Comprehensive rate limiting architecture with detailed implementation guide for tool usage control.\n\n---\n\n#### Recently Completed (April 2026)\n\n- **[#906 - Admin Data Export](https://github.com/agentic-community/mcp-gateway-registry/issues/906)** - Admin-only Data Export page for downloading registry collections as JSON.\n- **[#897 - Per-skill Auth Credentials UI](https://github.com/agentic-community/mcp-gateway-registry/issues/897)** - Frontend UI for managing per-skill authentication credentials.\n- **[#886 - Centralized Log Rotation](https://github.com/agentic-community/mcp-gateway-registry/issues/886)** - Centralized log rotation, auth-server file logging, and log retrieval via MongoDB storage.\n- **[#871 - Unified JWT and Static Token Auth](https://github.com/agentic-community/mcp-gateway-registry/issues/871)** - JWT/session auth coexists with static token auth, supporting four credential types concurrently.\n- **[#856 - ARM64 Docker Images](https://github.com/agentic-community/mcp-gateway-registry/issues/856)** - Multi-architecture Docker images with ARM64 support.\n- **[#851 - Direct M2M Client Registration](https://github.com/agentic-community/mcp-gateway-registry/issues/851)** - Direct machine-to-machine client registration API that bypasses IdP sync.\n- **[#824 - Python 3.14 Runtime Upgrade](https://github.com/agentic-community/mcp-gateway-registry/issues/824)** - Upgraded Python runtime from 3.12 to 3.14 to resolve CVE-2025-13836.\n- **[#809 - Registration Gate Admission Control](https://github.com/agentic-community/mcp-gateway-registry/issues/809)** - Admission control webhook for agent, server, and skill registration.\n- **[#779 - Multiple Static API Keys](https://github.com/agentic-community/mcp-gateway-registry/issues/779)** - Multiple static API keys with per-key group and scope assignments.\n- **[#742 - Webhook Notifications](https://github.com/agentic-community/mcp-gateway-registry/issues/742)** - Configurable webhook notification on server, agent, and skill registration events.\n\nFor the complete list of all issues, feature requests, and detailed release history, visit:\n- [All GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues)\n- [All GitHub Milestones](https://github.com/agentic-community/mcp-gateway-registry/milestones)\n- [Release Notes](release-notes/)\n\n---\n\n## License\n\nThis project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n
\n\n**⭐ Star this repository if it helps your organization!**\n\n[Get Started](docs/installation.md) | [Documentation](docs/) | [Contribute](CONTRIBUTING.md)\n\n
" }, { "path": "SECURITY.md", "content": "# Reporting Security Issues\n\nWe take all security reports seriously.\nWhen we receive such reports,\nwe will investigate and subsequently address\nany potential vulnerabilities as quickly as possible.\nIf you discover a potential security issue in this project,\nplease notify AWS/Amazon Security via our\n[vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/)\nor directly via email to [AWS Security](mailto:aws-security@amazon.com).\nPlease do *not* create a public GitHub issue in this project." }, { "path": "agents/a2a/.dockerignore", "content": "# Python\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\n*.egg-info/\n.installed.cfg\n*.egg\n\n# Virtual environments\n.env\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# IDE\n.vscode/\n.idea/\n*.swp\n*.swo\n\n# OS\n.DS_Store\nThumbs.db\n\n# Git\n.git/\n.gitignore\n\n# Documentation\n*.md\ndocs/\n\n# Tests\ntests/\n*_test.py\ntest_*.py\n\n# Agent-specific exclusions\nagent-langgraph/\n*/data/\n*/__pycache__/" }, { "path": "agents/a2a/.env.example", "content": "# MCP Registry URL (use Docker service name when running in Docker network)\nMCP_REGISTRY_URL=http://registry\n\n# JWT Token for registry authentication\n# Get a valid token from the registry UI or API, then paste it here.\n# The agent uses this token to call the registry's semantic search API.\nREGISTRY_JWT_TOKEN=\n" }, { "path": "agents/a2a/.gitignore", "content": "# Environment variables with secrets\n.env\n\n# Python\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n.Python\n\n# Virtual environments\nvenv/\nenv/\n.venv/\n\n# Docker\n.tmp/\n\n# IDE\n.vscode/\n.idea/\n*.swp\n*.swo\n*~\n\n# OS\n.DS_Store\nThumbs.db\n" }, { "path": "agents/a2a/README.md", "content": "# Travel Booking Agents\n\nTwo AI agents built with AWS Bedrock AgentCore and the Strands framework for flight search and booking.\n\n## Agents\n\n**Travel Assistant Agent** (`travel_assistant_agent`)\n- Searches for available flights between cities\n- Provides flight recommendations based on price and preferences\n- Returns detailed flight information (times, prices, airlines)\n- **Discovers other agents** through the MCP Gateway Registry and dynamically adds them as tools\n- [Full specification](https://github.com/agentic-community/mcp-gateway-registry/issues/196)\n\n**Flight Booking Agent** (`flight_booking_agent`)\n- Checks flight availability and seat counts\n- Creates flight reservations\n- Manages booking database\n- [Full specification](https://github.com/agentic-community/mcp-gateway-registry/issues/197)\n\n## Deployment Options\n\n### Local Docker Container\n\nRun agents locally with full FastAPI server including custom API endpoints.\n\n**Prerequisites:**\n- Docker and Docker Compose\n- AWS credentials configured (via AWS_PROFILE, EC2 IAM role, or ~/.aws/credentials)\n- `uv sync --extra dev` to install main dependencies and development ones\n\n**Deploy:**\n```bash\n# 1. Get AWS credentials (for Isengard users)\nisengard credentials --account YOUR_ACCOUNT --role YOUR_ROLE --export\n\n# This exports: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN\n# Docker will automatically pick these up from your environment\n\n# 2. Deploy (auto-detects your system architecture)\n# From repo root:\nagents/a2a/deploy_local.sh\n\n# Or from agents/a2a directory:\n./deploy_local.sh\n```\n\n**Architecture Support:**\nThe script automatically detects your system architecture:\n- **Intel/AMD Macs and Linux:** Uses `docker-compose.local.yml` (x86_64)\n- **Apple Silicon Macs:** Uses `docker-compose.arm.yml` (ARM64)\n\nTo override auto-detection:\n```bash\n# Force ARM64 (Apple Silicon) - from repo root\nagents/a2a/deploy_local.sh --arm64\n\n# Force x86_64 (Intel/AMD) - from repo root\nagents/a2a/deploy_local.sh --x86_64\n\n# Show help - from repo root\nagents/a2a/deploy_local.sh --help\n\n# Or from agents/a2a directory:\n./deploy_local.sh --arm64\n./deploy_local.sh --x86_64\n./deploy_local.sh --help\n```\n\n**Endpoints:**\n- Travel Assistant: `http://localhost:9001`\n- Flight Booking: `http://localhost:9002`\n- Custom APIs: `/api/search-flights`, `/api/recommendations`, `/api/check-availability`\n- Health check: `/ping`\n\n### AgentCore Runtime (AWS)\n\nDeploy agents to AWS managed infrastructure with automatic scaling.\n\n**Prerequisites:**\n- AWS credentials configured (via AWS_PROFILE, EC2 IAM role, or ~/.aws/credentials)\n- AgentCore CLI: `pip install bedrock-agentcore-starter-toolkit`\n\n**Deploy:**\n```bash\n# Configure AWS credentials (one of these methods)\nexport AWS_PROFILE=your_profile_name\n\n# Or use EC2 IAM role (no export needed)\n\n# Then deploy\n./deploy_live.sh\n```\n\n**Note:** The deployment script automatically builds ARM64 images for AgentCore Runtime compatibility. The `docker-compose.arm.yml` file defines the ARM64 build targets used during deployment.\n\n**Access:**\n- Agents accessible via A2A protocol only\n- ARNs shown in deployment output\n- CloudWatch logs for monitoring\n\n## Testing\n\n### Agent Card Endpoint (Local)\n\nTest the agent card endpoint locally to verify agent metadata. The script retrieves and displays agent card information, and saves JSON files locally for reference.\n\n**Run the check:**\n\n```bash\n# From repo root\nagents/a2a/test/check_agent_cards.sh\n\n# Or from agents/a2a directory\ncd agents/a2a\n./test/check_agent_cards.sh\n```\n\n**Output Files:**\n\nAgent cards are saved to the `agents/a2a/test/` directory:\n- `travel_assistant_agent_card.json` - Travel Assistant agent metadata\n- `flight_booking_agent_card.json` - Flight Booking agent metadata\n\nThese files contain:\n- Agent name and description\n- Available tools and capabilities\n- API endpoints and methods\n- Input/output schemas\n\n> **Next Steps:** For remote testing of deployed agents, consider using the [A2A Inspector](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore-testing.html) to interact with and debug your AgentCore Runtime deployments.\n\n### Agent and API Tests\n\nRun comprehensive tests against local or live deployments to verify agent functionality:\n\n**Test Coverage:**\n- **Health Checks:** Verify agents are responsive via `/ping` endpoint\n- **Agent Communication (A2A Protocol):** Send natural language requests to agents and verify responses\n - Travel Assistant: Flight search queries\n - Flight Booking: Availability checks and reservations\n- **Direct API Endpoints:** Test custom FastAPI endpoints (local only)\n - `/api/search-flights` - Flight search with parameters\n - `/api/recommendations` - Price-based recommendations\n - `/api/check-availability` - Seat availability checks\n- **Response Validation:** Verify response structure and content accuracy\n\n**Run Tests:**\n\n```bash\n# Test local Docker containers (from repo root)\nuv run python agents/a2a/test/simple_agents_test.py --endpoint local\n\n# Test local Docker containers (from agents/a2a directory)\ncd agents/a2a\nuv run python test/simple_agents_test.py --endpoint local\n\n# Test AgentCore Runtime (from repo root)\nuv run python agents/a2a/test/simple_agents_test.py --endpoint live\n```\n\n**Debug Mode:**\n\nFor detailed request/response tracing, use the `--debug` flag:\n\n```bash\n# View full JSON-RPC payloads, response bodies, and timing (from repo root)\nuv run python agents/a2a/test/simple_agents_test.py --endpoint local --debug\n\n# Or from agents/a2a directory:\nuv run python test/simple_agents_test.py --endpoint local --debug\n```\n\nThis displays:\n- Complete JSON-RPC request payloads\n- Full agent response bodies with artifacts\n- Response timing and HTTP status codes\n- Streaming data for agent reasoning\n\n## Deployment Scripts\n\n### deploy_local.sh\nDeploys and starts the agents locally in Docker containers.\n\n**Features:**\n- Auto-detects your system architecture (x86_64 or ARM64)\n- Validates AWS credentials using the credential chain\n- Removes and recreates containers and volumes for a clean deployment\n- Builds Docker images locally before starting\n\n**Usage (from repo root):**\n```bash\nagents/a2a/deploy_local.sh # Auto-detect architecture\nagents/a2a/deploy_local.sh --arm64 # Force ARM64 (Apple Silicon)\nagents/a2a/deploy_local.sh --x86_64 # Force x86_64 (Intel/AMD)\nagents/a2a/deploy_local.sh --help # Show usage options\n```\n\n**Usage (from agents/a2a directory):**\n```bash\n./deploy_local.sh # Auto-detect architecture\n./deploy_local.sh --arm64 # Force ARM64 (Apple Silicon)\n./deploy_local.sh --x86_64 # Force x86_64 (Intel/AMD)\n./deploy_local.sh --help # Show usage options\n```\n\n### shutdown_local.sh\nStops and removes all containers, networks, and volumes.\n\n**Usage (from repo root):**\n```bash\nagents/a2a/shutdown_local.sh\n```\n\n**Usage (from agents/a2a directory):**\n```bash\n./shutdown_local.sh\n```\n\nThis is useful when you want to completely clean up before redeploying or when done testing locally.\n\n## Agent-to-Agent Discovery\n\nThe Travel Assistant Agent can discover and invoke other agents at runtime using the MCP Gateway Registry's semantic search API. This enables dynamic agent composition where agents find collaborators based on capabilities.\n\n### Configuration\n\n1. Copy the example environment file:\n```bash\ncp agents/a2a/.env.example agents/a2a/.env\n```\n\n2. Edit `agents/a2a/.env` and set your JWT token:\n```bash\n# Registry URL (default works for Docker network)\nMCP_REGISTRY_URL=http://registry\n\n# Paste a valid JWT token from the registry UI or API\nREGISTRY_JWT_TOKEN=\n```\n\nThe agent uses this token to authenticate with the registry's semantic search API. The `deploy_local.sh` script automatically loads `.env` before starting containers.\n\n### Prerequisites\n\n- MCP Gateway Registry running (`docker-compose up -d`)\n- Flight Booking Agent registered in the registry (via UI or CLI)\n- Valid JWT token configured in `agents/a2a/.env`\n\n### Discovery Tools\n\nThe Travel Assistant Agent provides three tools for agent discovery:\n\n| Tool | Description |\n|------|-------------|\n| `discover_remote_agents` | Search registry for agents by natural language query |\n| `view_cached_remote_agents` | List all discovered agents in cache |\n| `invoke_remote_agent` | Send a message to a cached agent via A2A protocol |\n\n### Testing Discovery\n\n1. Start the MCP Gateway Registry and register the Flight Booking Agent\n\n2. Deploy agents locally:\n```bash\nagents/a2a/deploy_local.sh\n```\n\n3. Run the test suite (includes discovery test):\n```bash\nuv run python agents/a2a/test/simple_agents_test.py --endpoint local --debug\n```\n\n4. View agent logs to see discovery in action:\n```bash\ndocker logs -f travel-assistant-agent\n```\n\nYou should see logs like:\n```\nRegistryDiscoveryClient initialized with direct JWT token for http://registry\nTool called: discover_remote_agents(query='book flights', max_results=5)\nFound 1 agents\nCached agent: Flight Booking Agent (ID: /flight-booking-agent)\n```\n\n### Example Flow\n\n```\nUser: \"I need to book a flight from NYC to LA\"\n\nTravel Assistant Agent:\n 1. discover_remote_agents(\"agent that can book flights\")\n -> Returns: Flight Booking Agent (score: 0.85)\n\n 2. invoke_remote_agent(\"/flight-booking-agent\", \"Book flight NYC to LA\")\n -> Flight Booking Agent processes request\n -> Returns booking confirmation\n\n 3. Returns combined response to user\n```\n\n---\n\n## Key Differences\n\n| Feature | Local Docker | AgentCore Runtime |\n|---------|-------------|-------------------|\n| A2A Protocol | ✅ | ✅ |\n| Custom API Endpoints | ✅ | ❌ |\n| Health Check `/ping` | ✅ | ❌ |\n| Agent Discovery | ✅ | ✅ |\n| Deployment | Docker Compose | AgentCore CLI |\n\n**Note:** Custom FastAPI endpoints (like `/api/search-flights`) are only available in local Docker deployments. **AgentCore Runtime only wraps the container and exposes the standard A2A conversational interface.**\n" }, { "path": "agents/a2a/deploy_live.sh", "content": "#!/bin/bash\n\n# AgentCore Live Deployment Script\n#\n# Deploys A2A agents to AWS using AgentCore CLI with custom Dockerfiles.\n# - Builds locally with Docker, pushes to ECR, deploys to AgentCore Runtime\n# - Uses container mode with custom Dockerfiles for full control\n# - Targets ARM64 platform for AWS AgentCore Runtime (which runs on ARM64)\n#\n# For local testing before live deployment:\n# - Use docker-compose.local.yml for x86_64 testing on local machines\n# - Use docker-compose.arm.yml with docker buildx if testing ARM64 locally\n#\n# File Management:\n# During deployment, the following files are copied from agents-strands root into each agent directory:\n# - pyproject.toml, uv.lock -> src//.tmp/ (for dependency installation in Docker)\n# - .dockerignore -> src// (to optimize Docker build context)\n# These files are automatically cleaned up after deployment completes.\n\n\nset -e\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\necho -e \"${BLUE}AgentCore Live Deployment Script${NC}\"\necho \"======================================\"\n\n# Check if AWS credentials are set\necho -e \"\\nValidating AWS credentials...\"\n\nIDENTITY_OUTPUT=$(aws sts get-caller-identity 2>&1)\nEXIT_CODE=$?\n\nif [ $EXIT_CODE -ne 0 ]; then\n echo -e \"${RED}❌ Error: Unable to retrieve AWS credentials${NC}\"\n echo \"\"\n echo \"AWS credentials not found. Please provide credentials using one of these methods:\"\n echo \"\"\n echo \"1. AWS Profile (recommended):\"\n echo \" export AWS_PROFILE=your_profile_name\"\n echo \"\"\n echo \"2. EC2 IAM Role (automatic when running on EC2 instance)\"\n echo \"\"\n echo \"Debug info:\"\n echo \"$IDENTITY_OUTPUT\"\n exit 1\nfi\n\nACCOUNT_ID=$(echo \"$IDENTITY_OUTPUT\" | grep -o '\"Account\": \"[^\"]*\"' | cut -d'\"' -f4)\nREGION=${AWS_REGION:-us-east-1}\n\necho -e \"${GREEN}✅ AWS credentials validated${NC}\"\necho -e \" Account: ${ACCOUNT_ID}\"\necho -e \" Region: ${REGION}\"\n\n# Check if agentcore CLI is installed\necho -e \"\\nChecking AgentCore CLI...\"\nif ! command -v agentcore &> /dev/null; then\n echo -e \"${RED}❌ Error: agentcore CLI not found${NC}\"\n echo \"Please install it with: pip install bedrock-agentcore-starter-toolkit\"\n exit 1\nfi\necho -e \"${GREEN}✅ AgentCore CLI found${NC}\"\n\n# Agent configurations\nFLIGHT_AGENT_NAME=\"flight_booking_agent\"\nFLIGHT_AGENT_ENTRYPOINT=\"src/flight-booking-agent/agent.py\"\n\nTRAVEL_AGENT_NAME=\"travel_assistant_agent\"\nTRAVEL_AGENT_ENTRYPOINT=\"src/travel-assistant-agent/agent.py\"\n\n# Function to configure and deploy an agent\ndeploy_agent() {\n local agent_name=$1\n local entrypoint=$2\n\n echo -e \"\\nDeploying ${agent_name}...\"\n echo \" Entrypoint: ${entrypoint}\"\n echo \" Protocol: A2A\"\n echo \" Deployment: container (custom Dockerfile in agent directory)\"\n echo \" Database: /app/data/bookings.db\"\n echo \" Build: Local Docker build, then push to ECR\"\n\n # Get the entrypoint directory where our Dockerfile lives\n local entrypoint_dir=$(dirname \"${entrypoint}\")\n\n # Check if agent is already configured\n if agentcore configure list 2>/dev/null | grep -q \"${agent_name}\"; then\n echo \"Agent ${agent_name} already configured, will update\"\n else\n echo \"Configuring ${agent_name}...\"\n agentcore configure \\\n --entrypoint \"${entrypoint}\" \\\n --name \"${agent_name}\" \\\n --region \"${REGION}\" \\\n --protocol A2A \\\n --deployment-type container \\\n --non-interactive \\\n --disable-memory\n fi\n\n # Copy files from agents-strands root into agent directory for Docker build\n # Files copied:\n # - pyproject.toml, uv.lock -> ${entrypoint_dir}/.tmp/ (for dependency installation)\n # - .dockerignore -> ${entrypoint_dir}/ (to optimize Docker build context)\n # These files are cleaned up after deployment completes\n echo \" Copying dependency files to .tmp directory\"\n mkdir -p \"${entrypoint_dir}/.tmp\"\n cp pyproject.toml uv.lock \"${entrypoint_dir}/.tmp/\"\n\n # Copy .dockerignore to agent directory if it doesn't exist\n if [ ! -f \"${entrypoint_dir}/.dockerignore\" ] && [ -f \".dockerignore\" ]; then\n echo \" Copying .dockerignore to agent directory\"\n cp .dockerignore \"${entrypoint_dir}/.dockerignore\"\n fi\n\n # Replace AgentCore's generated Dockerfile with our custom one\n local agentcore_dockerfile=\".bedrock_agentcore/${agent_name}/Dockerfile\"\n if [ -f \"${entrypoint_dir}/Dockerfile\" ]; then\n echo \" Replacing generated Dockerfile with custom one\"\n cp \"${entrypoint_dir}/Dockerfile\" \"${agentcore_dockerfile}\"\n fi\n\n # Create a docker-compose override for ARM64 build if it exists\n # This ensures the agentcore CLI builds for ARM64 (the target platform for AgentCore Runtime)\n local docker_compose_override=\".bedrock_agentcore/${agent_name}/docker-compose.override.yml\"\n if [ -f \"docker-compose.arm.yml\" ]; then\n echo \" Creating ARM64 docker-compose override for AgentCore Runtime target\"\n mkdir -p \".bedrock_agentcore/${agent_name}\"\n # Extract the service definition for this agent from docker-compose.arm.yml\n # The agentcore CLI will use this for building\n cat > \"${docker_compose_override}\" <\"\necho \" • View logs: Check CloudWatch logs (shown in status above)\"\necho \" • Update agents: Run this script again to deploy changes\"\necho \" • Destroy agents: agentcore destroy --agent \"\n" }, { "path": "agents/a2a/deploy_local.sh", "content": "#!/bin/bash\n\nset -e\n\n# Find the agents/a2a directory\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nA2A_DIR=\"$SCRIPT_DIR\"\n\n# If running from repo root, adjust the path\nif [ ! -f \"$A2A_DIR/docker-compose.local.yml\" ]; then\n A2A_DIR=\"$SCRIPT_DIR/agents/a2a\"\nfi\n\n# Verify we found the agents/a2a directory\nif [ ! -f \"$A2A_DIR/docker-compose.local.yml\" ]; then\n echo \"❌ Error: docker-compose.local.yml not found\"\n echo \"\"\n echo \"This script must be run from either:\"\n echo \" - The agents/a2a directory: ./deploy_local.sh\"\n echo \" - The repository root: agents/a2a/deploy_local.sh\"\n exit 1\nfi\n\n# Change to agents/a2a directory for the deployment\ncd \"$A2A_DIR\"\n\n# Load environment variables from .env file if it exists\nif [ -f \".env\" ]; then\n echo \"Loading configuration from .env file...\"\n set -a\n source .env\n set +a\nelse\n echo \"Warning: No .env file found in $A2A_DIR\"\n echo \"Copy .env.example to .env and configure REGISTRY_JWT_TOKEN for agent discovery.\"\nfi\n\n# Parse command line arguments\nCOMPOSE_FILE=\"docker-compose.local.yml\"\nARCHITECTURE=\"\"\nTARGETPLATFORM=\"\"\n\nfor arg in \"$@\"; do\n case \"$arg\" in\n --arm64)\n COMPOSE_FILE=\"docker-compose.arm.yml\"\n ARCHITECTURE=\"ARM64\"\n TARGETPLATFORM=\"linux/arm64\"\n ;;\n --x86_64)\n COMPOSE_FILE=\"docker-compose.local.yml\"\n ARCHITECTURE=\"x86_64\"\n TARGETPLATFORM=\"linux/amd64\"\n ;;\n --help)\n echo \"Usage: ./deploy_local.sh [OPTIONS]\"\n echo \"\"\n echo \"Options:\"\n echo \" --arm64 Use ARM64 docker-compose file (for Apple Silicon Macs)\"\n echo \" --x86_64 Use x86_64 docker-compose file (default for Intel/AMD)\"\n echo \" --help Show this help message\"\n echo \"\"\n echo \"Examples:\"\n echo \" ./deploy_local.sh # Auto-detect architecture\"\n echo \" ./deploy_local.sh --arm64 # Force ARM64 (Apple Silicon)\"\n echo \" ./deploy_local.sh --x86_64 # Force x86_64 (Intel/AMD)\"\n exit 0\n ;;\n *)\n echo \"Unknown option: $arg\"\n echo \"Use --help for usage information\"\n exit 1\n ;;\n esac\ndone\n\n# Auto-detect architecture if not specified\nif [ -z \"$ARCHITECTURE\" ]; then\n SYSTEM_ARCH=$(uname -m)\n if [ \"$SYSTEM_ARCH\" = \"arm64\" ] || [ \"$SYSTEM_ARCH\" = \"aarch64\" ]; then\n COMPOSE_FILE=\"docker-compose.arm.yml\"\n ARCHITECTURE=\"ARM64 (auto-detected)\"\n TARGETPLATFORM=\"linux/arm64\"\n else\n COMPOSE_FILE=\"docker-compose.local.yml\"\n ARCHITECTURE=\"x86_64 (auto-detected)\"\n TARGETPLATFORM=\"linux/amd64\"\n fi\nfi\n\n# Export TARGETPLATFORM for docker-compose to use\nexport TARGETPLATFORM\n\necho \"Deploying agents for: $ARCHITECTURE\"\necho \"\"\n\necho \"Validating AWS credentials...\"\n\n# Check if AWS credentials are available through the credential chain\n# This checks: explicit env vars, AWS_PROFILE, EC2 IAM role, ~/.aws/credentials, etc.\nIDENTITY_OUTPUT=$(aws sts get-caller-identity 2>&1)\nEXIT_CODE=$?\n\nif [ $EXIT_CODE -ne 0 ]; then\n echo \"❌ Error: Unable to retrieve AWS credentials\"\n echo \"\"\n echo \"AWS credentials not found. Please provide credentials using one of these methods:\"\n echo \"\"\n echo \"1. AWS Profile (recommended):\"\n echo \" export AWS_PROFILE=your_profile_name\"\n echo \"\"\n echo \"2. EC2 IAM Role (automatic when running on EC2 instance)\"\n echo \"\"\n echo \"Debug info:\"\n echo \"$IDENTITY_OUTPUT\"\n exit 1\nfi\n\n# Extract and display credential information\nACCOUNT_ID=$(echo \"$IDENTITY_OUTPUT\" | grep -o '\"Account\": \"[^\"]*\"' | cut -d'\"' -f4)\nARN=$(echo \"$IDENTITY_OUTPUT\" | grep -o '\"Arn\": \"[^\"]*\"' | cut -d'\"' -f4)\n\necho \"✅ AWS credentials validated\"\necho \" Account ID: $ACCOUNT_ID\"\necho \" Principal: $ARN\"\n\necho \"Stopping existing containers and removing volumes...\"\ndocker compose -f \"$COMPOSE_FILE\" down -v\n\necho \"Building images...\"\n\n# Copy dependency files to .tmp directories for build\necho \"Copying dependency files to .tmp directories...\"\nmkdir -p src/flight-booking-agent/.tmp src/travel-assistant-agent/.tmp\ncp pyproject.toml uv.lock src/flight-booking-agent/.tmp/\ncp pyproject.toml uv.lock src/travel-assistant-agent/.tmp/\n\n# Build images\ndocker compose -f \"$COMPOSE_FILE\" build --no-cache\n\n# Clean up .tmp directories\necho \"Cleaning up .tmp directories...\"\nrm -rf src/flight-booking-agent/.tmp\nrm -rf src/travel-assistant-agent/.tmp\n\necho \"Starting containers...\"\ndocker compose -f \"$COMPOSE_FILE\" up -d\n\necho \"✅ Deployment complete!\"\necho \"\"\necho \"Waiting for containers to be ready and starting to display live logs...\"\necho \"Press Ctrl+C to stop viewing logs (containers will continue running)\"\necho \"\"\n\n# Wait a moment for containers to start\nsleep 2\n\n# Display live logs\ndocker compose -f \"$COMPOSE_FILE\" logs -f\n" }, { "path": "agents/a2a/docker-compose.arm.yml", "content": "services:\n travel-assistant-agent:\n image: travel-assistant-agent:latest\n build:\n context: ./src/travel-assistant-agent\n dockerfile: Dockerfile\n args:\n TARGETPLATFORM: linux/arm64\n container_name: travel-assistant-agent\n ports:\n - \"9001:9000\" # Map host port 9001 to associated container port 9000 for local testing\n environment:\n - DB_PATH=/app/data/flights.db\n - AWS_REGION=us-east-1\n - AWS_DEFAULT_REGION=us-east-1\n - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}\n - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}\n - AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN:-}\n - AGENT_NAME=travel-assistant\n - AGENTCORE_RUNTIME_URL=http://travel-assistant-agent:9000/\n - KEYCLOAK_URL=${KEYCLOAK_URL:-}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-}\n - MCP_REGISTRY_URL=${MCP_REGISTRY_URL:-http://registry}\n - REGISTRY_JWT_TOKEN=${REGISTRY_JWT_TOKEN:-}\n - M2M_CLIENT_ID=${TRAVEL_AGENT_M2M_CLIENT_ID:-}\n - M2M_CLIENT_SECRET=${TRAVEL_AGENT_M2M_CLIENT_SECRET:-}\n volumes:\n - travel_assistant_data:/app/data\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:9000/ping\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n\n flight-booking-agent:\n image: flight-booking-agent:latest\n build:\n context: ./src/flight-booking-agent\n dockerfile: Dockerfile\n args:\n TARGETPLATFORM: linux/arm64\n container_name: flight-booking-agent\n ports:\n - \"9002:9000\" # Map host port 9002 to associated container port 9000 for local testing\n environment:\n - DB_PATH=/app/data/bookings.db\n - AWS_REGION=us-east-1\n - AWS_DEFAULT_REGION=us-east-1\n - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}\n - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}\n - AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN:-}\n - AGENT_NAME=flight-booking\n - AGENTCORE_RUNTIME_URL=http://flight-booking-agent:9000/\n - KEYCLOAK_URL=${KEYCLOAK_URL:-}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-}\n - MCP_REGISTRY_URL=${MCP_REGISTRY_URL:-http://registry}\n - REGISTRY_JWT_TOKEN=${REGISTRY_JWT_TOKEN:-}\n - M2M_CLIENT_ID=${FLIGHT_BOOKING_M2M_CLIENT_ID:-}\n - M2M_CLIENT_SECRET=${FLIGHT_BOOKING_M2M_CLIENT_SECRET:-}\n volumes:\n - flight_booking_data:/app/data\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:9000/ping\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n\nvolumes:\n travel_assistant_data:\n driver: local\n flight_booking_data:\n driver: local\n\nnetworks:\n default:\n # Use the external network created by the main mcp-gateway-registry docker-compose\n # \"default\" is the logical network name used within this compose file \n # \"external: true\" means this network already exists and should not be created\n # This allows agents to communicate with gateway/registry services on the same network\n name: mcp-gateway-registry_default\n external: true\n" }, { "path": "agents/a2a/docker-compose.local.yml", "content": "services:\n travel-assistant-agent:\n image: travel-assistant-agent:latest\n build:\n context: ./src/travel-assistant-agent\n dockerfile: Dockerfile\n args:\n TARGETPLATFORM: ${TARGETPLATFORM:-linux/amd64}\n container_name: travel-assistant-agent\n ports:\n - \"9001:9000\" # Map host port 9001 to associated container port 9000 for local testing\n environment:\n - DB_PATH=/app/data/flights.db\n - AWS_REGION=us-east-1\n - AWS_DEFAULT_REGION=us-east-1\n - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}\n - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}\n - AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN:-}\n - AGENT_NAME=travel-assistant\n - AGENTCORE_RUNTIME_URL=http://travel-assistant-agent:9000/\n - KEYCLOAK_URL=${KEYCLOAK_URL:-}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-}\n - MCP_REGISTRY_URL=${MCP_REGISTRY_URL:-http://registry}\n - REGISTRY_JWT_TOKEN=${REGISTRY_JWT_TOKEN:-}\n - M2M_CLIENT_ID=${TRAVEL_AGENT_M2M_CLIENT_ID:-}\n - M2M_CLIENT_SECRET=${TRAVEL_AGENT_M2M_CLIENT_SECRET:-}\n volumes:\n - travel_assistant_data:/app/data\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:9000/ping\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n\n flight-booking-agent:\n image: flight-booking-agent:latest\n build:\n context: ./src/flight-booking-agent\n dockerfile: Dockerfile\n args:\n TARGETPLATFORM: ${TARGETPLATFORM:-linux/amd64}\n container_name: flight-booking-agent\n ports:\n - \"9002:9000\" # Map host port 9002 to associated container port 9000 for local testing\n environment:\n - DB_PATH=/app/data/bookings.db\n - AWS_REGION=us-east-1\n - AWS_DEFAULT_REGION=us-east-1\n - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}\n - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}\n - AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN:-}\n - AGENT_NAME=flight-booking\n - AGENTCORE_RUNTIME_URL=http://flight-booking-agent:9000/\n - KEYCLOAK_URL=${KEYCLOAK_URL:-}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-}\n - MCP_REGISTRY_URL=${MCP_REGISTRY_URL:-http://registry}\n - REGISTRY_JWT_TOKEN=${REGISTRY_JWT_TOKEN:-}\n - M2M_CLIENT_ID=${FLIGHT_BOOKING_M2M_CLIENT_ID:-}\n - M2M_CLIENT_SECRET=${FLIGHT_BOOKING_M2M_CLIENT_SECRET:-}\n volumes:\n - flight_booking_data:/app/data\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:9000/ping\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n\nvolumes:\n travel_assistant_data:\n driver: local\n flight_booking_data:\n driver: local\n \nnetworks:\n default:\n # Use the external network created by the main mcp-gateway-registry docker-compose\n # \"default\" is the logical network name used within this compose file\n # \"name\" overrides the actual Docker network name (prevents creating a2a_default)\n # \"external: true\" means this network already exists and should not be created\n # This allows agents to communicate with gateway/registry services on the same network\n name: mcp-gateway-registry_default\n external: true\n" }, { "path": "agents/a2a/pyproject.toml", "content": "[project]\nname = \"a2a\"\nversion = \"0.1.0\"\ndescription = \"Travel and Flight Booking Agents\"\nrequires-python = \">=3.14\"\ndependencies = [\n \"fastapi>=0.115.12\",\n \"uvicorn[standard]>=0.34.2\",\n \"strands-agents[a2a]>=0.1.6\",\n \"pydantic>=2.11.3\",\n \"python-dotenv>=1.2.2\",\n \"aiohttp>=3.8.0\",\n]\n\n[project.optional-dependencies]\ndev = [\n \"bedrock-agentcore-starter-toolkit>=0.1.0\",\n]\n\n[build-system]\nrequires = [\"setuptools>=61.0\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[tool.uv]\n# Local-only project - never resolve from PyPI\npackage = false" }, { "path": "agents/a2a/shutdown_local.sh", "content": "#!/bin/bash\n\nset -e\n\n# Find the agents/a2a directory\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nA2A_DIR=\"$SCRIPT_DIR\"\n\n# If running from repo root, adjust the path\nif [ ! -f \"$A2A_DIR/docker-compose.local.yml\" ]; then\n A2A_DIR=\"$SCRIPT_DIR/agents/a2a\"\nfi\n\n# Verify we found the agents/a2a directory\nif [ ! -f \"$A2A_DIR/docker-compose.local.yml\" ]; then\n echo \"❌ Error: docker-compose.local.yml not found\"\n echo \"\"\n echo \"This script must be run from either:\"\n echo \" - The agents/a2a directory: ./shutdown_local.sh\"\n echo \" - The repository root: agents/a2a/shutdown_local.sh\"\n exit 1\nfi\n\n# Change to agents/a2a directory for the shutdown\ncd \"$A2A_DIR\"\n\necho \"Stopping and removing local agents...\"\necho \"\"\n\n# Determine which compose file to use based on architecture (same logic as deploy_local.sh)\nCOMPOSE_FILE=\"docker-compose.local.yml\"\nSYSTEM_ARCH=$(uname -m)\n\nif [ \"$SYSTEM_ARCH\" = \"arm64\" ] || [ \"$SYSTEM_ARCH\" = \"aarch64\" ]; then\n COMPOSE_FILE=\"docker-compose.arm.yml\"\n echo \"Detected ARM64 architecture\"\nelse\n echo \"Detected x86_64 architecture\"\nfi\n\necho \"\"\necho \"Using docker-compose file: $COMPOSE_FILE\"\necho \"\"\n\n# Stop and remove containers, networks, and volumes\ndocker compose -f \"$COMPOSE_FILE\" down -v\n\necho \"\"\necho \"✅ Shutdown complete!\"\necho \"All containers, networks, and volumes have been removed.\"\necho \"\"\necho \"To restart the agents, run: ./deploy_local.sh\"\n" }, { "path": "agents/a2a/src/flight-booking-agent/Dockerfile", "content": "ARG TARGETPLATFORM\nFROM --platform=${TARGETPLATFORM} public.ecr.aws/docker/library/python:3.14-slim\n\nWORKDIR /app\n\n# Install system dependencies and uv\n# build-essential is required to compile asyncpg from source (no py3.14 wheel yet)\n# apt-get upgrade ensures latest security patches (e.g. openssl ~deb13u2)\nRUN apt-get update && apt-get upgrade -y && apt-get install -y \\\n sqlite3 \\\n curl \\\n build-essential \\\n && rm -rf /var/lib/apt/lists/* \\\n && pip install uv\n\n# Copy dependency files (build-images.sh copies these to .tmp/ directory before build)\nCOPY .tmp/pyproject.toml .tmp/uv.lock ./\n\n# Install Python dependencies using uv (as root, before switching users)\nRUN uv sync --frozen --no-dev\n\n# Copy agent code (all files from the context directory)\nCOPY . ./\n\n# Create non-root user\nRUN useradd -m -u 1000 bedrock_agentcore\n\n# Create data directory for SQLite database with proper ownership\n# Also fix ownership of installed packages\nRUN mkdir -p /app/data && \\\n chown -R bedrock_agentcore:bedrock_agentcore /app\n\nUSER bedrock_agentcore\n\n# Set environment variables\nENV PYTHONPATH=/app\nENV AWS_REGION=us-east-1\nENV AWS_DEFAULT_REGION=us-east-1\n\n# Expose port for A2A communication (port 9000 for A2A protocol)\nEXPOSE 9000\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\\n CMD curl -f http://localhost:9000/ping || exit 1\n\n# Run the agent with uv (uses the virtual environment created by uv sync)\nCMD [\"uv\", \"run\", \"--no-sync\", \"agent.py\"]\n" }, { "path": "agents/a2a/src/flight-booking-agent/__init__.py", "content": "\"\"\"Flight Booking Agent Package.\"\"\"\n\nimport logging\n\nfrom .agent import (\n agent,\n app,\n)\nfrom .database import BookingDatabaseManager\nfrom .env_settings import env_settings\nfrom .tools import FLIGHT_BOOKING_TOOLS\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n__all__ = [\"app\", \"agent\", \"env_settings\", \"BookingDatabaseManager\", \"FLIGHT_BOOKING_TOOLS\"]\n" }, { "path": "agents/a2a/src/flight-booking-agent/agent.py", "content": "\"\"\"Flight Booking Agent - Main application module.\"\"\"\n\nimport logging\nfrom contextlib import asynccontextmanager\n\nimport uvicorn\nfrom dependencies import (\n get_db_manager,\n get_env,\n)\nfrom fastapi import FastAPI\nfrom strands import Agent\nfrom strands.multiagent.a2a import A2AServer\nfrom tools import (\n FLIGHT_BOOKING_TOOLS,\n check_availability,\n confirm_booking,\n manage_reservation,\n process_payment,\n reserve_flight,\n)\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nstrands_agent = Agent(\n name=\"Flight Booking Agent\",\n description=\"Flight booking and reservation management agent\",\n tools=FLIGHT_BOOKING_TOOLS,\n callback_handler=None,\n model=\"global.anthropic.claude-sonnet-4-5-20250929-v1:0\",\n)\n\nenv_settings = get_env()\na2a_server = A2AServer(agent=strands_agent, http_url=env_settings.agent_url, serve_at_root=True)\n\n\n@asynccontextmanager\nasync def lifespan(\n app: FastAPI,\n):\n \"\"\"Application lifespan manager.\"\"\"\n # Setups before server startup\n get_db_manager()\n logger.info(\"Flight Booking Agent starting up\")\n logger.info(f\"Agent URL: {env_settings.agent_url}\")\n logger.info(f\"Listening on {env_settings.host}:{env_settings.port}\")\n\n # TODO: register agent with MCP Gateway Registry when path available\n\n yield\n # Triggered after server shutdown\n logger.info(\"Flight Booking Agent shutting down\")\n\n\napp = FastAPI(title=\"Flight Booking Agent\", lifespan=lifespan)\n\n\n@app.get(\"/ping\")\ndef ping():\n \"\"\"Health check endpoint.\"\"\"\n logger.debug(\"Ping endpoint called\")\n return {\"status\": \"healthy\"}\n\n\n@app.get(\"/api/health\")\ndef health():\n \"\"\"Health status endpoint.\"\"\"\n logger.debug(\"Health endpoint called\")\n return {\"status\": \"healthy\", \"agent\": \"flight_booking\"}\n\n\n@app.post(\"/api/check-availability\")\ndef api_check_availability(\n flight_id: int,\n):\n \"\"\"Check flight availability API endpoint.\"\"\"\n logger.info(f\"Checking availability for flight_id: {flight_id}\")\n result = check_availability(flight_id)\n logger.debug(f\"Availability check result: {result}\")\n return {\"result\": result}\n\n\n@app.post(\"/api/reserve-flight\")\ndef api_reserve_flight(\n flight_id: int,\n passengers: list,\n requested_seats: list | None = None,\n):\n \"\"\"Reserve flight API endpoint.\"\"\"\n logger.info(f\"Reserving flight_id: {flight_id} for {len(passengers)} passengers\")\n logger.debug(f\"Passengers: {passengers}\")\n logger.debug(f\"Requested seats: {requested_seats}\")\n result = reserve_flight(flight_id, passengers, requested_seats)\n logger.debug(f\"Reservation result: {result}\")\n return {\"result\": result}\n\n\n@app.post(\"/api/confirm-booking\")\ndef api_confirm_booking(\n booking_number: str,\n):\n \"\"\"Confirm booking API endpoint.\"\"\"\n logger.info(f\"Confirming booking: {booking_number}\")\n result = confirm_booking(booking_number)\n logger.debug(f\"Booking confirmation result: {result}\")\n return {\"result\": result}\n\n\n@app.post(\"/api/process-payment\")\ndef api_process_payment(\n booking_number: str,\n payment_method: str,\n amount: float | None = None,\n):\n \"\"\"Process payment API endpoint.\"\"\"\n logger.info(f\"Processing payment for booking: {booking_number}\")\n logger.debug(f\"Payment method: {payment_method}, Amount: {amount}\")\n result = process_payment(booking_number, payment_method, amount)\n logger.debug(f\"Payment processing result: {result}\")\n return {\"result\": result}\n\n\n@app.get(\"/api/reservation/{booking_number}\")\ndef api_get_reservation(\n booking_number: str,\n):\n \"\"\"Get reservation details API endpoint.\"\"\"\n logger.info(f\"Retrieving reservation: {booking_number}\")\n result = manage_reservation(booking_number, \"view\")\n logger.debug(f\"Reservation details: {result}\")\n return {\"result\": result}\n\n\n@app.delete(\"/api/reservation/{booking_number}\")\ndef api_cancel_reservation(\n booking_number: str,\n reason: str = \"User requested cancellation\",\n):\n \"\"\"Cancel reservation API endpoint.\"\"\"\n logger.info(f\"Canceling reservation: {booking_number}\")\n logger.debug(f\"Cancellation reason: {reason}\")\n result = manage_reservation(booking_number, \"cancel\", reason)\n logger.debug(f\"Cancellation result: {result}\")\n return {\"result\": result}\n\n\napp.mount(\"/\", a2a_server.to_fastapi_app())\n\n\ndef main() -> None:\n \"\"\"Main entry point for the application.\"\"\"\n logger.info(\"Starting Flight Booking Agent server\")\n uvicorn.run(app, host=env_settings.host, port=env_settings.port)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "agents/a2a/src/flight-booking-agent/database.py", "content": "\"\"\"Database management module for Flight Booking Agent.\"\"\"\n\nimport logging\nimport os\nimport sqlite3\nimport uuid\nfrom datetime import datetime\nfrom typing import (\n Any,\n)\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _create_tables(\n conn: sqlite3.Connection,\n) -> None:\n \"\"\"Create database tables if they don't exist.\"\"\"\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS flights (\n id INTEGER PRIMARY KEY,\n flight_number TEXT UNIQUE NOT NULL,\n airline TEXT NOT NULL,\n departure_city TEXT NOT NULL,\n arrival_city TEXT NOT NULL,\n departure_time DATETIME NOT NULL,\n arrival_time DATETIME NOT NULL,\n duration_minutes INTEGER,\n price DECIMAL(10,2),\n available_seats INTEGER DEFAULT 100,\n aircraft_type TEXT,\n created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n )\n \"\"\")\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS bookings (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n booking_number TEXT UNIQUE NOT NULL,\n flight_id INTEGER NOT NULL,\n total_price DECIMAL(10,2),\n status TEXT CHECK(status IN ('pending', 'confirmed', 'paid', 'cancelled')) DEFAULT 'pending',\n created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n confirmed_at DATETIME,\n FOREIGN KEY (flight_id) REFERENCES flights(id)\n )\n \"\"\")\n\n # Booking passengers table\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS booking_passengers (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n booking_id INTEGER NOT NULL,\n passenger_name TEXT NOT NULL,\n email TEXT,\n seat_number TEXT,\n FOREIGN KEY (booking_id) REFERENCES bookings(id)\n )\n \"\"\")\n\n # Payments table\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS payments (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n booking_id INTEGER NOT NULL,\n amount DECIMAL(10,2),\n status TEXT CHECK(status IN ('pending', 'completed', 'failed')) DEFAULT 'pending',\n payment_method TEXT,\n transaction_id TEXT,\n processed_at DATETIME,\n FOREIGN KEY (booking_id) REFERENCES bookings(id)\n )\n \"\"\")\n\n # Seat inventory table\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS seat_inventory (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n flight_id INTEGER NOT NULL,\n seat_row TEXT,\n seat_column TEXT,\n status TEXT CHECK(status IN ('available', 'reserved', 'booked')) DEFAULT 'available',\n FOREIGN KEY (flight_id) REFERENCES flights(id)\n )\n \"\"\")\n\n # Cancellations table\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS cancellations (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n booking_id INTEGER NOT NULL,\n reason TEXT,\n refund_amount DECIMAL(10,2),\n cancelled_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n FOREIGN KEY (booking_id) REFERENCES bookings(id)\n )\n \"\"\")\n\n\ndef _insert_seed_data(\n conn: sqlite3.Connection,\n) -> None:\n \"\"\"Insert seed data into the database if empty.\"\"\"\n cursor = conn.execute(\"SELECT COUNT(*) FROM flights\")\n if cursor.fetchone()[0] == 0:\n flight_data = [\n (\n 1,\n \"UA101\",\n \"United\",\n \"SF\",\n \"NY\",\n \"2025-11-15 08:00\",\n \"2025-11-15 16:30\",\n 330,\n 250.00,\n 85,\n \"B737\",\n ),\n (\n 2,\n \"AA202\",\n \"American\",\n \"SF\",\n \"NY\",\n \"2025-11-15 10:15\",\n \"2025-11-15 18:45\",\n 330,\n 280.00,\n 45,\n \"A320\",\n ),\n (\n 3,\n \"DL303\",\n \"Delta\",\n \"SF\",\n \"NY\",\n \"2025-11-15 14:30\",\n \"2025-11-15 23:00\",\n 330,\n 220.00,\n 120,\n \"B757\",\n ),\n (\n 4,\n \"UA104\",\n \"United\",\n \"SF\",\n \"LA\",\n \"2025-11-16 07:00\",\n \"2025-11-16 08:30\",\n 90,\n 120.00,\n 95,\n \"B737\",\n ),\n ]\n\n conn.executemany(\n \"\"\"\n INSERT OR IGNORE INTO flights\n (id, flight_number, airline, departure_city, arrival_city,\n departure_time, arrival_time, duration_minutes, price,\n available_seats, aircraft_type)\n VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n \"\"\",\n flight_data,\n )\n\n cursor = conn.execute(\"SELECT COUNT(*) FROM bookings\")\n if cursor.fetchone()[0] == 0:\n booking_data = [\n (\"BK001\", 1, 500.00, \"confirmed\", \"2025-11-01 10:00:00\", \"2025-11-01 10:15:00\"),\n (\"BK002\", 1, 250.00, \"pending\", \"2025-11-01 11:00:00\", None),\n (\"BK003\", 2, 560.00, \"confirmed\", \"2025-11-01 12:00:00\", \"2025-11-01 12:10:00\"),\n (\"BK004\", 3, 440.00, \"confirmed\", \"2025-11-01 13:00:00\", \"2025-11-01 13:05:00\"),\n ]\n\n conn.executemany(\n \"\"\"\n INSERT INTO bookings (booking_number, flight_id, total_price, status, created_at, confirmed_at)\n VALUES (?, ?, ?, ?, ?, ?)\n \"\"\",\n booking_data,\n )\n\n passenger_data = [\n (1, \"John Smith\", \"john@example.com\", \"12A\"),\n (1, \"Jane Smith\", \"jane@example.com\", \"12B\"),\n (2, \"Bob Johnson\", \"bob@example.com\", \"14C\"),\n (3, \"Alice Williams\", \"alice@example.com\", \"1A\"),\n (4, \"Charlie Brown\", \"charlie@example.com\", \"5B\"),\n ]\n\n conn.executemany(\n \"\"\"\n INSERT INTO booking_passengers (booking_id, passenger_name, email, seat_number)\n VALUES (?, ?, ?, ?)\n \"\"\",\n passenger_data,\n )\n\n payment_data = [\n (1, 500.00, \"completed\", \"credit_card\", \"TXN001\", \"2025-11-01 10:15:00\"),\n (2, 250.00, \"pending\", \"credit_card\", None, None),\n (3, 560.00, \"completed\", \"credit_card\", \"TXN003\", \"2025-11-01 12:10:00\"),\n (4, 440.00, \"completed\", \"paypal\", \"TXN004\", \"2025-11-01 13:05:00\"),\n ]\n\n conn.executemany(\n \"\"\"\n INSERT INTO payments (booking_id, amount, status, payment_method, transaction_id, processed_at)\n VALUES (?, ?, ?, ?, ?, ?)\n \"\"\",\n payment_data,\n )\n\n seat_data = [\n (1, \"1\", \"A\", \"booked\"),\n (1, \"1\", \"B\", \"booked\"),\n (1, \"1\", \"C\", \"available\"),\n (1, \"1\", \"D\", \"available\"),\n (1, \"12\", \"A\", \"booked\"),\n (1, \"12\", \"B\", \"booked\"),\n (1, \"12\", \"C\", \"available\"),\n (1, \"12\", \"D\", \"available\"),\n (1, \"14\", \"C\", \"booked\"),\n (1, \"14\", \"D\", \"available\"),\n ]\n\n conn.executemany(\n \"\"\"\n INSERT INTO seat_inventory (flight_id, seat_row, seat_column, status)\n VALUES (?, ?, ?, ?)\n \"\"\",\n seat_data,\n )\n\n conn.commit()\n\n\nclass BookingDatabaseManager:\n \"\"\"Database manager for flight bookings.\"\"\"\n\n def __init__(\n self,\n db_path: str,\n ) -> None:\n \"\"\"Initialize the database manager.\"\"\"\n self.db_path = db_path\n logger.info(f\"Initializing BookingDatabaseManager with db_path: {db_path}\")\n self.init_database()\n\n def init_database(self) -> None:\n \"\"\"Initialize the database with tables and seed data.\"\"\"\n os.makedirs(os.path.dirname(self.db_path), exist_ok=True)\n\n with sqlite3.connect(self.db_path) as conn:\n _create_tables(conn)\n _insert_seed_data(conn)\n\n def get_connection(self) -> sqlite3.Connection:\n \"\"\"Get a database connection.\"\"\"\n return sqlite3.connect(self.db_path)\n\n def get_flight_availability(\n self,\n flight_id: int,\n ) -> dict[str, Any] | None:\n \"\"\"Get availability information for a specific flight.\"\"\"\n logger.info(f\"Checking availability for flight_id: {flight_id}\")\n with self.get_connection() as conn:\n cursor = conn.execute(\n \"\"\"\n SELECT f.flight_number, f.airline, f.departure_city, f.arrival_city,\n f.departure_time, f.available_seats, f.price\n FROM flights f\n WHERE f.id = ?\n \"\"\",\n (flight_id,),\n )\n\n row = cursor.fetchone()\n if not row:\n logger.warning(f\"Flight not found: flight_id={flight_id}\")\n return None\n\n logger.info(f\"Flight availability retrieved: {row[0]}, available_seats={row[5]}\")\n\n return {\n \"flight_id\": flight_id,\n \"flight_number\": row[0],\n \"airline\": row[1],\n \"route\": f\"{row[2]} → {row[3]}\",\n \"departure_time\": row[4],\n \"available_seats\": row[5],\n \"price_per_seat\": float(row[6]),\n \"availability_status\": \"Available\" if row[5] > 0 else \"Sold Out\",\n }\n\n def create_reservation(\n self,\n flight_id: int,\n passengers: list[dict[str, str]],\n requested_seats: list[str] | None = None,\n ) -> dict[str, Any]:\n \"\"\"Create a new flight reservation.\"\"\"\n logger.info(\n f\"Creating reservation for flight_id: {flight_id}, passengers: {len(passengers)}\"\n )\n with self.get_connection() as conn:\n cursor = conn.execute(\n \"SELECT price, available_seats FROM flights WHERE id = ?\", (flight_id,)\n )\n flight_row = cursor.fetchone()\n\n if not flight_row:\n logger.error(f\"Flight not found: flight_id={flight_id}\")\n raise ValueError(f\"Flight with ID {flight_id} not found\")\n\n price_per_seat, available_seats = flight_row\n num_passengers = len(passengers)\n\n if available_seats < num_passengers:\n logger.warning(\n f\"Insufficient seats: requested={num_passengers}, available={available_seats}\"\n )\n raise ValueError(\n f\"Not enough seats available. Requested: {num_passengers}, Available: {available_seats}\"\n )\n\n booking_number = f\"BK{uuid.uuid4().hex[:6].upper()}\"\n total_price = float(price_per_seat) * num_passengers\n logger.info(f\"Generated booking_number: {booking_number}, total_price: {total_price}\")\n\n cursor = conn.execute(\n \"\"\"\n INSERT INTO bookings (booking_number, flight_id, total_price, status)\n VALUES (?, ?, ?, 'pending')\n \"\"\",\n (booking_number, flight_id, total_price),\n )\n\n booking_id = cursor.lastrowid\n\n assigned_seats = []\n for i, passenger in enumerate(passengers):\n seat_number = (\n requested_seats[i]\n if requested_seats and i < len(requested_seats)\n else f\"AUTO{i + 1}\"\n )\n\n conn.execute(\n \"\"\"\n INSERT INTO booking_passengers (booking_id, passenger_name, email, seat_number)\n VALUES (?, ?, ?, ?)\n \"\"\",\n (booking_id, passenger[\"name\"], passenger.get(\"email\", \"\"), seat_number),\n )\n\n assigned_seats.append(seat_number)\n\n conn.execute(\n \"\"\"\n UPDATE flights\n SET available_seats = available_seats - ?\n WHERE id = ?\n \"\"\",\n (num_passengers, flight_id),\n )\n\n conn.commit()\n logger.info(\n f\"Reservation created successfully: booking_number={booking_number}, booking_id={booking_id}\"\n )\n\n return {\n \"booking_number\": booking_number,\n \"booking_id\": booking_id,\n \"flight_id\": flight_id,\n \"status\": \"reserved\",\n \"total_price\": total_price,\n \"passengers\": passengers,\n \"assigned_seats\": assigned_seats,\n \"reservation_expires\": \"24 hours from creation\",\n \"next_steps\": [\"Confirm booking\", \"Process payment\"],\n }\n\n def confirm_booking(\n self,\n booking_number: str,\n ) -> dict[str, Any]:\n \"\"\"Confirm a pending booking.\"\"\"\n logger.info(f\"Confirming booking: {booking_number}\")\n with self.get_connection() as conn:\n # Get booking details\n cursor = conn.execute(\n \"\"\"\n SELECT id, flight_id, status, total_price\n FROM bookings\n WHERE booking_number = ?\n \"\"\",\n (booking_number,),\n )\n\n booking_row = cursor.fetchone()\n if not booking_row:\n logger.error(f\"Booking not found: {booking_number}\")\n raise ValueError(f\"Booking {booking_number} not found\")\n\n booking_id, flight_id, current_status, total_price = booking_row\n\n if current_status != \"pending\":\n logger.warning(f\"Cannot confirm booking {booking_number}, status: {current_status}\")\n raise ValueError(\n f\"Booking {booking_number} cannot be confirmed. Current status: {current_status}\"\n )\n\n # Update booking status\n confirmation_time = datetime.now().isoformat()\n conn.execute(\n \"\"\"\n UPDATE bookings\n SET status = 'confirmed', confirmed_at = ?\n WHERE booking_number = ?\n \"\"\",\n (confirmation_time, booking_number),\n )\n\n conn.commit()\n\n # Generate confirmation code\n confirmation_code = f\"CONF{uuid.uuid4().hex[:8].upper()}\"\n logger.info(\n f\"Booking confirmed: {booking_number}, confirmation_code: {confirmation_code}\"\n )\n\n return {\n \"booking_number\": booking_number,\n \"confirmation_code\": confirmation_code,\n \"status\": \"confirmed\",\n \"confirmed_at\": confirmation_time,\n \"total_price\": float(total_price),\n \"next_steps\": [\"Process payment to complete booking\"],\n }\n\n def process_payment(\n self,\n booking_number: str,\n payment_method: str,\n amount: float | None = None,\n ) -> dict[str, Any]:\n \"\"\"Process payment for a booking.\"\"\"\n logger.info(f\"Processing payment for booking: {booking_number}, method: {payment_method}\")\n with self.get_connection() as conn:\n # Get booking details\n cursor = conn.execute(\n \"\"\"\n SELECT id, total_price, status\n FROM bookings\n WHERE booking_number = ?\n \"\"\",\n (booking_number,),\n )\n\n booking_row = cursor.fetchone()\n if not booking_row:\n logger.error(f\"Booking not found: {booking_number}\")\n raise ValueError(f\"Booking {booking_number} not found\")\n\n booking_id, total_price, booking_status = booking_row\n payment_amount = amount if amount is not None else float(total_price)\n\n # Generate transaction ID\n transaction_id = f\"TXN{uuid.uuid4().hex[:8].upper()}\"\n processed_time = datetime.now().isoformat()\n logger.info(f\"Payment transaction created: {transaction_id}, amount: {payment_amount}\")\n\n # Insert payment record\n conn.execute(\n \"\"\"\n INSERT INTO payments (booking_id, amount, status, payment_method, transaction_id, processed_at)\n VALUES (?, ?, 'completed', ?, ?, ?)\n \"\"\",\n (booking_id, payment_amount, payment_method, transaction_id, processed_time),\n )\n\n # Update booking status to paid\n conn.execute(\n \"\"\"\n UPDATE bookings\n SET status = 'paid'\n WHERE booking_number = ?\n \"\"\",\n (booking_number,),\n )\n\n conn.commit()\n logger.info(\n f\"Payment completed: booking={booking_number}, transaction={transaction_id}\"\n )\n\n return {\n \"booking_number\": booking_number,\n \"transaction_id\": transaction_id,\n \"payment_status\": \"completed\",\n \"amount_paid\": payment_amount,\n \"payment_method\": payment_method,\n \"processed_at\": processed_time,\n \"booking_status\": \"paid\",\n \"message\": \"Payment processed successfully. Booking is now complete.\",\n }\n\n def get_booking_details(\n self,\n booking_number: str,\n ) -> dict[str, Any]:\n \"\"\"Get detailed information about a booking.\"\"\"\n with self.get_connection() as conn:\n # Get complete booking details\n cursor = conn.execute(\n \"\"\"\n SELECT b.id, b.booking_number, b.flight_id, b.total_price, b.status,\n b.created_at, b.confirmed_at, f.flight_number, f.airline,\n f.departure_city, f.arrival_city, f.departure_time\n FROM bookings b\n JOIN flights f ON b.flight_id = f.id\n WHERE b.booking_number = ?\n \"\"\",\n (booking_number,),\n )\n\n booking_row = cursor.fetchone()\n if not booking_row:\n raise ValueError(f\"Booking {booking_number} not found\")\n\n # Get passengers\n passenger_cursor = conn.execute(\n \"\"\"\n SELECT passenger_name, email, seat_number\n FROM booking_passengers\n WHERE booking_id = ?\n \"\"\",\n (booking_row[0],),\n )\n\n passengers = []\n for p_row in passenger_cursor.fetchall():\n passengers.append({\"name\": p_row[0], \"email\": p_row[1], \"seat\": p_row[2]})\n\n return {\n \"booking_number\": booking_number,\n \"flight\": {\n \"flight_number\": booking_row[7],\n \"airline\": booking_row[8],\n \"route\": f\"{booking_row[9]} → {booking_row[10]}\",\n \"departure_time\": booking_row[11],\n },\n \"booking_details\": {\n \"status\": booking_row[4],\n \"total_price\": float(booking_row[3]),\n \"created_at\": booking_row[5],\n \"confirmed_at\": booking_row[6],\n },\n \"passengers\": passengers,\n }\n\n def cancel_booking(\n self,\n booking_number: str,\n reason: str,\n ) -> dict[str, Any]:\n \"\"\"Cancel an existing booking.\"\"\"\n logger.info(f\"Cancelling booking: {booking_number}, reason: {reason}\")\n with self.get_connection() as conn:\n # Get booking details\n cursor = conn.execute(\n \"\"\"\n SELECT id, flight_id, status, total_price\n FROM bookings\n WHERE booking_number = ?\n \"\"\",\n (booking_number,),\n )\n\n booking_row = cursor.fetchone()\n if not booking_row:\n logger.error(f\"Booking not found: {booking_number}\")\n raise ValueError(f\"Booking {booking_number} not found\")\n\n booking_id, flight_id, current_status, total_price = booking_row\n\n if current_status == \"cancelled\":\n logger.warning(f\"Booking already cancelled: {booking_number}\")\n raise ValueError(f\"Booking {booking_number} is already cancelled\")\n\n # Calculate refund amount (simplified logic)\n refund_amount = float(total_price) * 0.8 # 80% refund\n\n # Insert cancellation record\n conn.execute(\n \"\"\"\n INSERT INTO cancellations (booking_id, reason, refund_amount)\n VALUES (?, ?, ?)\n \"\"\",\n (booking_id, reason, refund_amount),\n )\n\n # Update booking status\n conn.execute(\n \"\"\"\n UPDATE bookings\n SET status = 'cancelled'\n WHERE booking_number = ?\n \"\"\",\n (booking_number,),\n )\n\n # Get passenger count to free up seats\n cursor = conn.execute(\n \"\"\"\n SELECT COUNT(*) FROM booking_passengers WHERE booking_id = ?\n \"\"\",\n (booking_id,),\n )\n num_seats = cursor.fetchone()[0]\n\n # Update available seats count\n conn.execute(\n \"\"\"\n UPDATE flights\n SET available_seats = available_seats + ?\n WHERE id = ?\n \"\"\",\n (num_seats, flight_id),\n )\n\n conn.commit()\n logger.info(\n f\"Booking cancelled: {booking_number}, refund_amount: {refund_amount}, seats_freed: {num_seats}\"\n )\n\n return {\n \"booking_number\": booking_number,\n \"status\": \"cancelled\",\n \"cancellation_reason\": reason,\n \"refund_amount\": refund_amount,\n \"cancelled_at\": datetime.now().isoformat(),\n \"message\": \"Booking cancelled successfully. Refund will be processed within 5-7 business days.\",\n }\n" }, { "path": "agents/a2a/src/flight-booking-agent/dependencies.py", "content": "\"\"\"Dependency injection module for Flight Booking Agent.\"\"\"\n\nimport logging\nfrom functools import lru_cache\n\nfrom database import BookingDatabaseManager\nfrom env_settings import EnvSettings\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Simple singleton providers\n@lru_cache\ndef get_env() -> EnvSettings:\n \"\"\"Get environment settings singleton.\"\"\"\n logger.debug(\"Getting environment settings\")\n return EnvSettings()\n\n\n@lru_cache\ndef get_db_manager() -> BookingDatabaseManager:\n \"\"\"Get database manager singleton.\"\"\"\n env = get_env()\n logger.debug(f\"Getting database manager with db_path: {env.db_path}\")\n return BookingDatabaseManager(env.db_path)\n" }, { "path": "agents/a2a/src/flight-booking-agent/env_settings.py", "content": "\"\"\"Environment settings for Flight Booking Agent.\"\"\"\n\nimport logging\nimport os\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass EnvSettings:\n \"\"\"Environment settings configuration.\"\"\"\n\n def __init__(self) -> None:\n \"\"\"Initialize environment settings.\"\"\"\n self.db_path: str = os.getenv(\"DB_PATH\", \"/app/data/bookings.db\")\n self.aws_region: str = os.getenv(\"AWS_REGION\") or os.getenv(\n \"AWS_DEFAULT_REGION\", \"us-east-1\"\n )\n self.agent_name: str = os.getenv(\"AGENT_NAME\", \"flight-booking\")\n self.agent_version: str = os.getenv(\"AGENT_VERSION\", \"1.0.0\")\n\n # MCP Gateway Registry URL (TODO: replace later)\n self.mcp_registry_url: str = os.getenv(\"MCP_REGISTRY_URL\", \"http://localhost:7860\")\n\n # Agent's public URL (AgentCore Runtime injects automatically)\n self.agent_url: str = os.getenv(\"AGENTCORE_RUNTIME_URL\", \"http://127.0.0.1:9000/\")\n\n # Server configuration (fixed for A2A protocol)\n # Agent binds to 0.0.0.0 for container/K8s deployment where network isolation\n # is provided by container runtime. In production, use firewall rules.\n self.host: str = os.getenv(\"AGENT_HOST\", \"0.0.0.0\") # nosec B104 - intentional for containerized agent deployment\n self.port: int = 9000\n\n logger.info(\n f\"EnvSettings initialized: agent_name={self.agent_name}, version={self.agent_version}\"\n )\n logger.debug(f\"Database path: {self.db_path}\")\n logger.debug(f\"Agent URL: {self.agent_url}\")\n" }, { "path": "agents/a2a/src/flight-booking-agent/tools.py", "content": "\"\"\"Tools for Flight Booking Agent - Direct SQLite operations for booking management.\"\"\"\n\nimport json\nimport logging\n\nfrom dependencies import get_db_manager\nfrom strands import tool\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n@tool\ndef check_availability(\n flight_id: int,\n) -> str:\n \"\"\"Check seat availability for a specific flight.\"\"\"\n logger.info(f\"Tool called: check_availability(flight_id={flight_id})\")\n try:\n availability = get_db_manager().get_flight_availability(flight_id)\n\n if not availability:\n error_msg = f\"Flight with ID {flight_id} not found\"\n logger.warning(error_msg)\n return json.dumps({\"error\": error_msg})\n\n logger.debug(f\"Availability result:\\n{json.dumps(availability, indent=2)}\")\n return json.dumps(availability, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in check_availability: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef reserve_flight(\n flight_id: int,\n passengers: list[dict[str, str]],\n requested_seats: list[str] | None = None,\n) -> str:\n \"\"\"Reserve seats on a flight for passengers.\"\"\"\n logger.info(f\"Tool called: reserve_flight(flight_id={flight_id}, passengers={len(passengers)})\")\n logger.debug(f\"Passengers: {passengers}, Requested seats: {requested_seats}\")\n try:\n reservation = get_db_manager().create_reservation(flight_id, passengers, requested_seats)\n logger.debug(f\"Reservation result:\\n{json.dumps(reservation, indent=2)}\")\n return json.dumps(reservation, indent=2)\n\n except ValueError as e:\n logger.warning(f\"Validation error in reserve_flight: {e}\")\n return json.dumps({\"error\": \"Invalid reservation parameters\"})\n except Exception as e:\n logger.exception(f\"Database error in reserve_flight: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef confirm_booking(\n booking_number: str,\n) -> str:\n \"\"\"Confirm and finalize a flight booking.\"\"\"\n logger.info(f\"Tool called: confirm_booking(booking_number={booking_number})\")\n try:\n confirmation = get_db_manager().confirm_booking(booking_number)\n logger.debug(f\"Confirmation result:\\n{json.dumps(confirmation, indent=2)}\")\n return json.dumps(confirmation, indent=2)\n\n except ValueError as e:\n logger.warning(f\"Validation error in confirm_booking: {e}\")\n return json.dumps({\"error\": \"Invalid booking confirmation parameters\"})\n except Exception as e:\n logger.exception(f\"Database error in confirm_booking: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef process_payment(\n booking_number: str,\n payment_method: str,\n amount: float | None = None,\n) -> str:\n \"\"\"Process payment for a booking (simulated).\"\"\"\n logger.info(\n f\"Tool called: process_payment(booking_number={booking_number}, payment_method={payment_method})\"\n )\n logger.debug(f\"Payment amount: {amount}\")\n try:\n payment_result = get_db_manager().process_payment(booking_number, payment_method, amount)\n logger.debug(f\"Payment result:\\n{json.dumps(payment_result, indent=2)}\")\n return json.dumps(payment_result, indent=2)\n\n except ValueError as e:\n logger.warning(f\"Validation error in process_payment: {e}\")\n return json.dumps({\"error\": \"Invalid payment parameters\"})\n except Exception as e:\n logger.exception(f\"Database error in process_payment: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef manage_reservation(\n booking_number: str,\n action: str,\n reason: str | None = None,\n) -> str:\n \"\"\"Update, view, or cancel existing reservations.\"\"\"\n logger.info(\n f\"Tool called: manage_reservation(booking_number={booking_number}, action={action})\"\n )\n logger.debug(f\"Reason: {reason}\")\n try:\n db_manager = get_db_manager()\n if action == \"view\":\n booking_details = db_manager.get_booking_details(booking_number)\n logger.debug(f\"Booking details:\\n{json.dumps(booking_details, indent=2)}\")\n return json.dumps(booking_details, indent=2)\n\n elif action == \"cancel\":\n if not reason:\n error_msg = \"Cancellation reason is required\"\n logger.warning(error_msg)\n return json.dumps({\"error\": error_msg})\n\n cancellation_result = db_manager.cancel_booking(booking_number, reason)\n logger.debug(f\"Cancellation result:\\n{json.dumps(cancellation_result, indent=2)}\")\n return json.dumps(cancellation_result, indent=2)\n\n else:\n error_msg = f\"Unknown action: {action}. Supported actions: view, cancel\"\n logger.warning(error_msg)\n return json.dumps({\"error\": error_msg})\n\n except ValueError as e:\n logger.warning(f\"Validation error in manage_reservation: {e}\")\n return json.dumps({\"error\": \"Invalid reservation parameters\"})\n except Exception as e:\n logger.exception(f\"Database error in manage_reservation: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n# TODO: Create tool that's able to dynamically search agents from MCP Registry\n# example:\n# @tool\n# def delegate_to_agent(agent_capability: str, action: str, params: Dict) -> str:\n\nFLIGHT_BOOKING_TOOLS = [\n check_availability,\n reserve_flight,\n confirm_booking,\n process_payment,\n manage_reservation,\n]\n" }, { "path": "agents/a2a/src/travel-assistant-agent/Dockerfile", "content": "ARG TARGETPLATFORM\nFROM --platform=${TARGETPLATFORM} public.ecr.aws/docker/library/python:3.14-slim\n\nWORKDIR /app\n\n# Install system dependencies and uv\n# build-essential is required to compile asyncpg from source (no py3.14 wheel yet)\n# apt-get upgrade ensures latest security patches (e.g. openssl ~deb13u2)\nRUN apt-get update && apt-get upgrade -y && apt-get install -y \\\n sqlite3 \\\n curl \\\n build-essential \\\n && rm -rf /var/lib/apt/lists/* \\\n && pip install uv\n\n# Copy dependency files (build-images.sh copies these to .tmp/ directory before build)\nCOPY .tmp/pyproject.toml .tmp/uv.lock ./\n\n# Install Python dependencies using uv (as root, before switching users)\nRUN uv sync --frozen --no-dev\n\n# Copy agent code (all files from the context directory)\nCOPY . ./\n\n# Create non-root user\nRUN useradd -m -u 1000 bedrock_agentcore\n\n# Create data directory for SQLite database with proper ownership\n# Also fix ownership of installed packages\nRUN mkdir -p /app/data && \\\n chown -R bedrock_agentcore:bedrock_agentcore /app\n\nUSER bedrock_agentcore\n\n# Set environment variables\nENV PYTHONPATH=/app\nENV AWS_REGION=us-east-1\nENV AWS_DEFAULT_REGION=us-east-1\n\n# Expose port for A2A communication (port 9000 for A2A protocol)\nEXPOSE 9000\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\\n CMD curl -f http://localhost:9000/ping || exit 1\n\n# Run the agent with uv (uses the virtual environment created by uv sync)\nCMD [\"uv\", \"run\", \"--no-sync\", \"server.py\"]\n" }, { "path": "agents/a2a/src/travel-assistant-agent/__init__.py", "content": "\"\"\"Travel Assistant Agent Package.\"\"\"\n\nimport logging\n\nfrom .agent import (\n agent,\n app,\n)\nfrom .database import FlightDatabaseManager\nfrom .env_settings import env_settings\nfrom .tools import TRAVEL_ASSISTANT_TOOLS\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n__all__ = [\"app\", \"agent\", \"env_settings\", \"FlightDatabaseManager\", \"TRAVEL_ASSISTANT_TOOLS\"]\n" }, { "path": "agents/a2a/src/travel-assistant-agent/agent.py", "content": "\"\"\"Tools for Travel Assistant Agent - Flight search and trip planning utilities.\"\"\"\n\nimport json\nimport logging\n\nfrom dependencies import get_db_manager, get_registry_client, get_remote_agent_cache\nfrom strands import Agent, tool\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n@tool\ndef search_flights(\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n) -> str:\n \"\"\"Search for available flights between cities on a specific date.\"\"\"\n logger.info(\n f\"Tool called: search_flights(departure_city={departure_city}, arrival_city={arrival_city}, departure_date={departure_date})\"\n )\n try:\n flights = get_db_manager().search_flights(departure_city, arrival_city, departure_date)\n\n result = {\n \"query\": {\n \"departure_city\": departure_city,\n \"arrival_city\": arrival_city,\n \"departure_date\": departure_date,\n },\n \"flights\": flights,\n \"count\": len(flights),\n }\n\n logger.debug(f\"Flight search result:\\n{json.dumps(result, indent=2)}\")\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in search_flights: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef check_prices(\n flight_id: int,\n) -> str:\n \"\"\"Get pricing and seat availability for a specific flight.\"\"\"\n logger.info(f\"Tool called: check_prices(flight_id={flight_id})\")\n try:\n flight_details = get_db_manager().get_flight_details(flight_id)\n\n if not flight_details:\n error_msg = f\"Flight with ID {flight_id} not found\"\n logger.warning(error_msg)\n return json.dumps({\"error\": error_msg})\n\n logger.debug(f\"Flight details result:\\n{json.dumps(flight_details, indent=2)}\")\n return json.dumps(flight_details, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in check_prices: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef get_recommendations(\n max_price: float,\n preferred_airlines: list[str] | None = None,\n) -> str:\n \"\"\"Get flight recommendations based on customer preferences.\"\"\"\n logger.info(\n f\"Tool called: get_recommendations(max_price={max_price}, preferred_airlines={preferred_airlines})\"\n )\n try:\n recommendations = get_db_manager().get_recommendations(max_price, preferred_airlines)\n\n result = {\n \"criteria\": {\"max_price\": max_price, \"preferred_airlines\": preferred_airlines or \"Any\"},\n \"recommendations\": recommendations,\n \"count\": len(recommendations),\n }\n\n logger.debug(f\"Recommendations result:\\n{json.dumps(result, indent=2)}\")\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in get_recommendations: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef create_trip_plan(\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n return_date: str | None = None,\n budget: float | None = None,\n) -> str:\n \"\"\"Create and save a trip planning record.\"\"\"\n logger.info(\n f\"Tool called: create_trip_plan(departure_city={departure_city}, arrival_city={arrival_city}, departure_date={departure_date})\"\n )\n logger.debug(f\"Return date: {return_date}, Budget: {budget}\")\n try:\n db_manager = get_db_manager()\n trip_plan_id = db_manager.create_trip_plan(\n departure_city, arrival_city, departure_date, return_date, budget\n )\n\n # Get available flights for the trip\n outbound_flights = db_manager.search_flights(departure_city, arrival_city, departure_date)\n return_flights = []\n\n if return_date:\n return_flights = db_manager.search_flights(arrival_city, departure_city, return_date)\n\n result = {\n \"trip_plan_id\": trip_plan_id,\n \"trip_details\": {\n \"departure_city\": departure_city.upper(),\n \"arrival_city\": arrival_city.upper(),\n \"departure_date\": departure_date,\n \"return_date\": return_date,\n \"budget\": budget,\n \"status\": \"planning\",\n },\n \"outbound_flights\": outbound_flights,\n \"return_flights\": return_flights,\n \"next_steps\": [\n \"Review available flights\",\n \"Select preferred flights\",\n \"Contact Flight Booking Agent for reservation\",\n ],\n }\n\n logger.debug(f\"Trip plan result:\\n{json.dumps(result, indent=2)}\")\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in create_trip_plan: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\nasync def discover_remote_agents(query: str, max_results: int = 5) -> str:\n \"\"\"\n Discover remote agents from the mcp-registry with natural language query.\n Cache them for visibility and invocation for later tool calls from LLM\n \"\"\"\n logger.info(f\"Tool called: discover_remote_agents(query='{query}', max_results={max_results})\")\n\n try:\n registry_client = get_registry_client()\n if not registry_client:\n return json.dumps(\n {\n \"error\": \"Registry discovery not configured\",\n \"message\": \"Set M2M_CLIENT_ID and M2M_CLIENT_SECRET environment variables\",\n }\n )\n\n # Search registry\n discovered = await registry_client.discover_by_semantic_search(\n query=query,\n max_results=max_results,\n )\n\n if not discovered:\n return json.dumps(\n {\n \"query\": query,\n \"agents_found\": 0,\n \"message\": \"No agents found matching your query\",\n }\n )\n\n # Get auth token and cache the agents\n auth_token = await registry_client._get_token()\n cache = get_remote_agent_cache()\n newly_cached = cache.cache_discovered_agents(discovered, auth_token)\n\n result = {\n \"query\": query,\n \"agents_found\": len(discovered),\n \"newly_cached\": len(newly_cached),\n \"total_cached\": len(cache),\n \"agents\": [\n {\n \"id\": agent.path,\n \"name\": agent.name,\n \"description\": agent.description,\n \"url\": agent.url,\n \"skills\": agent.skill_names,\n \"tags\": agent.tags,\n \"relevance_score\": agent.relevance_score,\n \"trust_level\": agent.trust_level,\n }\n for agent in discovered\n ],\n \"next_steps\": [\n \"Use view_cached_remote_agents() to see all cached agents\",\n \"Use invoke_remote_agent(agent_id, message) to call a specific agent\",\n ],\n }\n\n logger.info(\n f\"Discovery successful: found {len(discovered)} agents, cached {len(newly_cached)} new\"\n )\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.error(f\"Discovery error in discover_remote_agents: {e}\", exc_info=True)\n return json.dumps(\n {\n \"error\": \"Discovery failed\",\n \"message\": \"An internal error occurred during agent discovery\",\n }\n )\n\n\n@tool\nasync def view_cached_remote_agents() -> str:\n \"\"\"View all cached remote agents available for invocation.\"\"\"\n logger.info(\"Tool called: view_cached_remote_agents()\")\n\n try:\n cache = get_remote_agent_cache()\n\n if len(cache) == 0:\n return json.dumps(\n {\n \"total\": 0,\n \"message\": \"No agents cached. Use discover_remote_agents() to find and cache agents.\",\n }\n )\n\n all_agents = cache.get_all()\n result = {\n \"total\": len(cache),\n \"agents\": [\n {\n \"id\": agent_id,\n \"name\": agent_client.agent_name,\n \"url\": agent_client.agent_url,\n \"skills\": agent_client.skills,\n }\n for agent_id, agent_client in all_agents.items()\n ],\n \"usage\": \"Use invoke_remote_agent(agent_id, message) to call any of these agents\",\n }\n\n logger.info(f\"Returning {len(cache)} cached agents\")\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.error(f\"Error in view_cached_remote_agents: {e}\", exc_info=True)\n return json.dumps(\n {\n \"error\": \"Failed to view cached agents\",\n \"message\": \"An internal error occurred while viewing cached agents\",\n }\n )\n\n\n@tool\nasync def invoke_remote_agent(agent_id: str, message: str) -> str:\n \"\"\"Invoke a cached remote agent by ID with a natural language message.\"\"\"\n logger.info(\n f\"Tool called: invoke_remote_agent(agent_id='{agent_id}', message='{message[:100]}...')\"\n )\n\n try:\n cache = get_remote_agent_cache()\n\n if agent_id not in cache:\n all_agents = cache.get_all()\n available_ids = list(all_agents.keys())\n return json.dumps(\n {\n \"error\": f\"Agent '{agent_id}' not found in cache\",\n \"available_agents\": available_ids,\n \"hint\": \"Use discover_remote_agents() to find and cache agents, or view_cached_remote_agents() to see what's available\",\n }\n )\n\n # Get the cached agent client and invoke it\n agent_client = cache.get(agent_id)\n logger.info(f\"Invoking agent: {agent_client.agent_name}\")\n\n response = await agent_client.send_message(message)\n\n logger.info(f\"Successfully invoked {agent_client.agent_name}\")\n return response\n\n except Exception as e:\n logger.error(f\"Error in invoke_remote_agent: {e}\", exc_info=True)\n return json.dumps(\n {\n \"error\": \"Failed to invoke remote agent\",\n \"agent_id\": agent_id,\n \"message\": \"An internal error occurred while invoking the remote agent\",\n }\n )\n\n\nTRAVEL_ASSISTANT_TOOLS = [\n search_flights,\n check_prices,\n get_recommendations,\n create_trip_plan,\n discover_remote_agents,\n view_cached_remote_agents,\n invoke_remote_agent,\n]\n\nstrands_agent = Agent(\n name=\"Travel Assistant Agent\",\n description=\"Flight search and trip planning agent with dynamic agent discovery\",\n tools=TRAVEL_ASSISTANT_TOOLS,\n callback_handler=None,\n model=\"global.anthropic.claude-sonnet-4-5-20250929-v1:0\",\n)\n\n\ndef get_agent_instance():\n return strands_agent\n" }, { "path": "agents/a2a/src/travel-assistant-agent/database.py", "content": "\"\"\"Database management module for Travel Assistant Agent.\"\"\"\n\nimport logging\nimport os\nimport sqlite3\nfrom typing import (\n Any,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _insert_seed_data(\n conn: sqlite3.Connection,\n) -> None:\n \"\"\"Insert seed data into the database.\"\"\"\n seed_data = [\n (\n 1,\n \"UA101\",\n \"United\",\n \"SF\",\n \"NY\",\n \"2025-11-15 08:00\",\n \"2025-11-15 16:30\",\n 330,\n 250.00,\n 85,\n \"B737\",\n ),\n (\n 2,\n \"AA202\",\n \"American\",\n \"SF\",\n \"NY\",\n \"2025-11-15 10:15\",\n \"2025-11-15 18:45\",\n 330,\n 280.00,\n 45,\n \"A320\",\n ),\n (\n 3,\n \"DL303\",\n \"Delta\",\n \"SF\",\n \"NY\",\n \"2025-11-15 14:30\",\n \"2025-11-15 23:00\",\n 330,\n 220.00,\n 120,\n \"B757\",\n ),\n (\n 4,\n \"UA104\",\n \"United\",\n \"SF\",\n \"LA\",\n \"2025-11-16 07:00\",\n \"2025-11-16 08:30\",\n 90,\n 120.00,\n 95,\n \"B737\",\n ),\n (\n 5,\n \"AA205\",\n \"American\",\n \"NY\",\n \"SF\",\n \"2025-11-17 09:00\",\n \"2025-11-17 12:30\",\n 330,\n 260.00,\n 78,\n \"A321\",\n ),\n (\n 6,\n \"DL306\",\n \"Delta\",\n \"LA\",\n \"NY\",\n \"2025-11-18 11:00\",\n \"2025-11-18 19:30\",\n 330,\n 240.00,\n 92,\n \"B757\",\n ),\n ]\n\n conn.executemany(\n \"\"\"\n INSERT OR IGNORE INTO flights\n (id, flight_number, airline, departure_city, arrival_city,\n departure_time, arrival_time, duration_minutes, price,\n available_seats, aircraft_type)\n VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n \"\"\",\n seed_data,\n )\n\n conn.commit()\n\n\nclass FlightDatabaseManager:\n \"\"\"Database manager for flight searches and trip planning.\"\"\"\n\n def __init__(\n self,\n db_path: str,\n ) -> None:\n \"\"\"Initialize the database manager.\"\"\"\n self.db_path = db_path\n logger.info(f\"Initializing FlightDatabaseManager with db_path: {db_path}\")\n self.init_database()\n\n def init_database(self) -> None:\n \"\"\"Initialize the database with tables and seed data.\"\"\"\n os.makedirs(os.path.dirname(self.db_path), exist_ok=True)\n\n with sqlite3.connect(self.db_path) as conn:\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS flights (\n id INTEGER PRIMARY KEY,\n flight_number TEXT UNIQUE NOT NULL,\n airline TEXT NOT NULL,\n departure_city TEXT NOT NULL,\n arrival_city TEXT NOT NULL,\n departure_time DATETIME NOT NULL,\n arrival_time DATETIME NOT NULL,\n duration_minutes INTEGER,\n price DECIMAL(10,2),\n available_seats INTEGER DEFAULT 100,\n aircraft_type TEXT,\n created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n )\n \"\"\")\n\n conn.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS trip_plans (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n departure_city TEXT NOT NULL,\n arrival_city TEXT NOT NULL,\n departure_date TEXT NOT NULL,\n return_date TEXT,\n budget DECIMAL(10,2),\n status TEXT DEFAULT 'planning',\n created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n )\n \"\"\")\n\n cursor = conn.execute(\"SELECT COUNT(*) FROM flights\")\n if cursor.fetchone()[0] == 0:\n _insert_seed_data(conn)\n\n def get_connection(self) -> sqlite3.Connection:\n \"\"\"Get a database connection.\"\"\"\n return sqlite3.connect(self.db_path)\n\n def search_flights(\n self,\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Search for available flights between cities on a specific date.\"\"\"\n logger.info(\n f\"Searching flights: {departure_city} -> {arrival_city}, date: {departure_date}\"\n )\n with self.get_connection() as conn:\n cursor = conn.execute(\n \"\"\"\n SELECT id, flight_number, airline, departure_city, arrival_city,\n departure_time, arrival_time, duration_minutes, price,\n available_seats, aircraft_type\n FROM flights\n WHERE departure_city = ? AND arrival_city = ?\n AND DATE(departure_time) = ?\n ORDER BY price ASC\n \"\"\",\n (departure_city.upper(), arrival_city.upper(), departure_date),\n )\n\n flights = []\n for row in cursor.fetchall():\n flights.append(\n {\n \"id\": row[0],\n \"flight_number\": row[1],\n \"airline\": row[2],\n \"departure_city\": row[3],\n \"arrival_city\": row[4],\n \"departure_time\": row[5],\n \"arrival_time\": row[6],\n \"duration_minutes\": row[7],\n \"price\": float(row[8]),\n \"available_seats\": row[9],\n \"aircraft_type\": row[10],\n }\n )\n\n logger.info(f\"Found {len(flights)} flights\")\n return flights\n\n def get_flight_details(\n self,\n flight_id: int,\n ) -> dict[str, Any] | None:\n \"\"\"Get detailed information about a specific flight.\"\"\"\n logger.info(f\"Getting flight details for flight_id: {flight_id}\")\n with self.get_connection() as conn:\n cursor = conn.execute(\n \"\"\"\n SELECT flight_number, airline, departure_city, arrival_city,\n departure_time, arrival_time, price, available_seats\n FROM flights\n WHERE id = ?\n \"\"\",\n (flight_id,),\n )\n\n row = cursor.fetchone()\n if not row:\n logger.warning(f\"Flight not found: flight_id={flight_id}\")\n return None\n\n logger.info(f\"Flight details retrieved: {row[0]}\")\n\n return {\n \"flight_id\": flight_id,\n \"flight_number\": row[0],\n \"airline\": row[1],\n \"route\": f\"{row[2]} → {row[3]}\",\n \"departure_time\": row[4],\n \"arrival_time\": row[5],\n \"price\": float(row[6]),\n \"available_seats\": row[7],\n \"availability_status\": \"Available\" if row[7] > 0 else \"Sold Out\",\n }\n\n def get_recommendations(\n self,\n max_price: float,\n preferred_airlines: list[str] | None = None,\n ) -> list[dict[str, Any]]:\n \"\"\"Get flight recommendations based on price and airline preferences.\"\"\"\n logger.info(\n f\"Getting recommendations: max_price={max_price}, airlines={preferred_airlines}\"\n )\n with self.get_connection() as conn:\n query = \"SELECT * FROM flights WHERE price <= ? AND available_seats > 0\"\n params: list[Any] = [max_price]\n\n if preferred_airlines:\n placeholders = \",\".join([\"?\" for _ in preferred_airlines])\n query += f\" AND airline IN ({placeholders})\"\n params.extend(preferred_airlines)\n\n query += \" ORDER BY price ASC, available_seats DESC\"\n\n cursor = conn.execute(query, params)\n\n recommendations = []\n for row in cursor.fetchall():\n recommendations.append(\n {\n \"id\": row[0],\n \"flight_number\": row[1],\n \"airline\": row[2],\n \"route\": f\"{row[3]} → {row[4]}\",\n \"departure_time\": row[5],\n \"arrival_time\": row[6],\n \"duration_minutes\": row[7],\n \"price\": float(row[8]),\n \"available_seats\": row[9],\n \"aircraft_type\": row[10],\n \"recommendation_score\": min(\n 100, int((max_price - float(row[8])) / max_price * 100)\n ),\n }\n )\n\n logger.info(f\"Found {len(recommendations)} recommendations\")\n return recommendations\n\n def create_trip_plan(\n self,\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n return_date: str | None = None,\n budget: float | None = None,\n ) -> int:\n \"\"\"Create a new trip plan.\"\"\"\n logger.info(\n f\"Creating trip plan: {departure_city} -> {arrival_city}, date: {departure_date}, budget: {budget}\"\n )\n with self.get_connection() as conn:\n cursor = conn.execute(\n \"\"\"\n INSERT INTO trip_plans\n (departure_city, arrival_city, departure_date, return_date, budget)\n VALUES (?, ?, ?, ?, ?)\n \"\"\",\n (departure_city.upper(), arrival_city.upper(), departure_date, return_date, budget),\n )\n\n trip_plan_id = cursor.lastrowid\n conn.commit()\n logger.info(f\"Trip plan created: trip_plan_id={trip_plan_id}\")\n return trip_plan_id\n" }, { "path": "agents/a2a/src/travel-assistant-agent/dependencies.py", "content": "\"\"\"Dependency injection module for Travel Assistant Agent.\"\"\"\n\nimport logging\nfrom functools import lru_cache\n\nfrom database import FlightDatabaseManager\nfrom env_settings import EnvSettings\nfrom registry_discovery_client import RegistryDiscoveryClient\nfrom remote_agent_client import RemoteAgentCache\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n@lru_cache\ndef get_env() -> EnvSettings:\n \"\"\"Get environment settings singleton.\"\"\"\n logger.debug(\"Getting environment settings\")\n return EnvSettings()\n\n\n@lru_cache\ndef get_db_manager() -> FlightDatabaseManager:\n \"\"\"Get database manager singleton.\"\"\"\n env = get_env()\n logger.debug(f\"Getting database manager with db_path: {env.db_path}\")\n return FlightDatabaseManager(env.db_path)\n\n\n@lru_cache\ndef get_registry_client() -> RegistryDiscoveryClient | None:\n \"\"\"Get registry discovery client singleton.\n\n Returns:\n RegistryDiscoveryClient if configured, None otherwise\n \"\"\"\n env = get_env()\n\n # Option 1: Use direct JWT token if provided\n if env.registry_jwt_token:\n logger.info(\"Creating RegistryDiscoveryClient with direct JWT token\")\n return RegistryDiscoveryClient(\n registry_url=env.mcp_registry_url,\n jwt_token=env.registry_jwt_token,\n )\n\n # Option 2: Use M2M client credentials\n if not env.m2m_client_secret:\n logger.warning(\"M2M_CLIENT_SECRET not configured, discovery will not work\")\n return None\n\n if not env.m2m_client_id:\n logger.warning(\"M2M_CLIENT_ID not configured, discovery will not work\")\n return None\n\n logger.info(\"Creating RegistryDiscoveryClient with M2M credentials\")\n return RegistryDiscoveryClient(\n registry_url=env.mcp_registry_url,\n keycloak_url=env.keycloak_url,\n client_id=env.m2m_client_id,\n client_secret=env.m2m_client_secret,\n realm=env.keycloak_realm,\n )\n\n\n@lru_cache\ndef get_remote_agent_cache() -> RemoteAgentCache:\n \"\"\"Get the remote agent cache singleton.\n\n Returns:\n RemoteAgentCache instance\n \"\"\"\n logger.debug(\"Getting remote agent cache\")\n return RemoteAgentCache()\n" }, { "path": "agents/a2a/src/travel-assistant-agent/env_settings.py", "content": "\"\"\"Environment settings for Travel Assistant Agent.\"\"\"\n\nimport logging\nimport os\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass EnvSettings:\n \"\"\"Environment settings configuration.\"\"\"\n\n def __init__(self) -> None:\n \"\"\"Initialize environment settings.\"\"\"\n self.db_path: str = os.getenv(\"DB_PATH\", \"/app/data/flights.db\")\n self.aws_region: str = os.getenv(\"AWS_REGION\") or os.getenv(\n \"AWS_DEFAULT_REGION\", \"us-east-1\"\n )\n self.agent_name: str = os.getenv(\"AGENT_NAME\", \"travel-assistant\")\n self.agent_version: str = os.getenv(\"AGENT_VERSION\", \"1.0.0\")\n\n # MCP Gateway Registry URL\n self.mcp_registry_url: str = os.getenv(\"MCP_REGISTRY_URL\", \"http://localhost:7860\")\n\n # Agent's public URL (AgentCore Runtime injects automatically)\n self.agent_url: str = os.getenv(\"AGENTCORE_RUNTIME_URL\", \"http://127.0.0.1:9000/\")\n\n # Server configuration (fixed for A2A protocol)\n # Agent binds to 0.0.0.0 for container/K8s deployment where network isolation\n # is provided by container runtime. In production, use firewall rules.\n self.host: str = os.getenv(\"AGENT_HOST\", \"0.0.0.0\") # nosec B104 - intentional for containerized agent deployment\n self.port: int = 9000\n\n # Keycloak configuration for M2M authentication\n self.keycloak_url: str = os.getenv(\"KEYCLOAK_URL\", \"http://localhost:8080\")\n self.keycloak_realm: str = os.getenv(\"KEYCLOAK_REALM\", \"mcp-gateway\")\n self.m2m_client_id: str = os.getenv(\"M2M_CLIENT_ID\", \"\")\n self.m2m_client_secret: str = os.getenv(\"M2M_CLIENT_SECRET\", \"\")\n\n # Optional: Direct JWT token (bypasses M2M authentication)\n # If set, this token is used directly instead of fetching from Keycloak\n self.registry_jwt_token: str = os.getenv(\"REGISTRY_JWT_TOKEN\", \"\")\n\n logger.info(\n f\"EnvSettings initialized: agent_name={self.agent_name}, version={self.agent_version}\"\n )\n if self.registry_jwt_token:\n logger.info(\"Using direct JWT token for registry authentication\")\n elif self.m2m_client_id and self.m2m_client_secret:\n logger.info(\"Using M2M client credentials for registry authentication\")\n logger.debug(f\"Database path: {self.db_path}\")\n logger.debug(f\"Agent URL: {self.agent_url}\")\n" }, { "path": "agents/a2a/src/travel-assistant-agent/models.py", "content": "\"\"\"Data models for Travel Assistant Agent.\"\"\"\n\nfrom typing import Any\n\nfrom pydantic import BaseModel, Field\n\n\nclass AgentSkill(BaseModel):\n \"\"\"Skill/capability of an agent.\"\"\"\n\n id: str = Field(..., description=\"Skill identifier\")\n name: str = Field(..., description=\"Skill name\")\n description: str | None = Field(None, description=\"Skill description\")\n tags: list[str] = Field(default_factory=list, description=\"Skill tags\")\n examples: list[str] | None = Field(None, description=\"Usage examples\")\n input_modes: list[str] | None = Field(None, description=\"Supported input modes\")\n output_modes: list[str] | None = Field(None, description=\"Supported output modes\")\n security: dict[str, Any] | None = Field(None, description=\"Security requirements\")\n\n\nclass DiscoveredAgent(BaseModel):\n \"\"\"Agent discovered from registry.\"\"\"\n\n model_config = {\"populate_by_name\": True, \"extra\": \"ignore\"}\n\n name: str = Field(..., description=\"Agent name\")\n description: str = Field(default=\"\", description=\"Agent description\")\n path: str = Field(..., description=\"Registry path\")\n url: str | None = Field(None, description=\"Agent endpoint URL for invocation\")\n tags: list[str] = Field(default_factory=list, description=\"Categorization tags\")\n skills: list[AgentSkill] = Field(default_factory=list, description=\"Agent skills\")\n is_enabled: bool = Field(False, description=\"Whether agent is enabled\")\n trust_level: str = Field(\"unverified\", description=\"Trust level\")\n visibility: str = Field(\"public\", description=\"Agent visibility\")\n relevance_score: float | None = Field(None, description=\"Relevance score from search\")\n\n @property\n def agent_name(self) -> str:\n \"\"\"Alias for name for backward compatibility.\"\"\"\n return self.name\n\n @property\n def skill_names(self) -> list[str]:\n \"\"\"Get list of skill names.\"\"\"\n return [skill.name for skill in self.skills]\n" }, { "path": "agents/a2a/src/travel-assistant-agent/registry_discovery_client.py", "content": "\"\"\"Client for agent discovery through MCP Gateway Registry.\"\"\"\n\nimport logging\nimport time\n\nimport aiohttp\nfrom models import DiscoveredAgent\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass RegistryDiscoveryClient:\n \"\"\"Client for agent discovery through MCP Gateway Registry.\"\"\"\n\n def __init__(\n self,\n registry_url: str,\n keycloak_url: str | None = None,\n client_id: str | None = None,\n client_secret: str | None = None,\n realm: str = \"mcp-gateway\",\n jwt_token: str | None = None,\n ) -> None:\n self.registry_url = registry_url.rstrip(\"/\")\n self.keycloak_url = keycloak_url.rstrip(\"/\") if keycloak_url else None\n self.client_id = client_id\n self.client_secret = client_secret\n self.realm = realm\n self.token: str | None = None\n self.token_expires_at: float = 0\n\n # Direct JWT token (bypasses M2M authentication)\n self.direct_jwt_token = jwt_token\n\n if jwt_token:\n logger.info(\n f\"RegistryDiscoveryClient initialized with direct JWT token for {registry_url}\"\n )\n else:\n logger.info(\n f\"RegistryDiscoveryClient initialized with M2M credentials for {registry_url}\"\n )\n\n async def _get_token(self) -> str:\n \"\"\"Get or refresh JWT token from Keycloak using client credentials flow.\n\n Returns:\n JWT access token\n\n Raises:\n Exception: If token acquisition fails\n \"\"\"\n # If direct JWT token is provided, use it directly\n if self.direct_jwt_token:\n logger.debug(\"Using direct JWT token\")\n return self.direct_jwt_token\n\n current_time = time.time()\n if self.token and current_time < self.token_expires_at - 60:\n logger.debug(\"Using cached token\")\n return self.token\n\n token_url = f\"{self.keycloak_url}/realms/{self.realm}/protocol/openid-connect/token\"\n logger.debug(f\"Requesting new token from {token_url}\")\n\n async with aiohttp.ClientSession() as session:\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n\n try:\n async with session.post(token_url, data=data) as response:\n if response.status != 200:\n error_text = await response.text()\n logger.error(f\"Token request failed: {response.status} - {error_text}\")\n raise Exception(f\"Failed to get token: {response.status}\")\n\n token_data = await response.json()\n self.token = token_data[\"access_token\"]\n expires_in = token_data.get(\"expires_in\", 300)\n self.token_expires_at = current_time + expires_in\n\n logger.info(f\"Token acquired, expires in {expires_in}s\")\n return self.token\n\n except aiohttp.ClientError as e:\n logger.error(f\"Network error getting token: {e}\")\n raise Exception(f\"Network error: {e}\")\n\n async def discover_by_semantic_search(\n self,\n query: str,\n max_results: int = 5,\n ) -> list[DiscoveredAgent]:\n \"\"\"Discover agents using semantic search (natural language query).\n\n Args:\n query: Natural language search query\n max_results: Maximum number of results to return\n\n Returns:\n List of discovered agents with relevance scores\n\n Raises:\n Exception: If discovery fails\n \"\"\"\n logger.info(f\"Semantic search: '{query}' (max_results={max_results})\")\n\n token = await self._get_token()\n discovery_url = f\"{self.registry_url}/api/agents/discover/semantic\"\n headers = {\"Authorization\": f\"Bearer {token}\", \"Host\": \"localhost\"}\n # This endpoint uses query parameters, not JSON body\n params = {\"query\": query, \"max_results\": max_results}\n\n async with aiohttp.ClientSession() as session:\n try:\n async with session.post(\n discovery_url,\n headers=headers,\n params=params,\n ) as response:\n if response.status != 200:\n error_text = await response.text()\n logger.error(f\"Discovery failed: {response.status} - {error_text}\")\n raise Exception(f\"Discovery failed: {response.status}\")\n\n result = await response.json()\n agents_data = result.get(\"agents\", [])\n\n agents = [DiscoveredAgent(**agent) for agent in agents_data]\n logger.info(f\"Found {len(agents)} agents\")\n\n return agents\n\n except aiohttp.ClientError as e:\n logger.error(f\"Network error during discovery: {e}\")\n raise Exception(f\"Network error: {e}\")\n\n except aiohttp.ClientError as e:\n logger.error(f\"Network error during discovery: {e}\")\n raise Exception(f\"Network error: {e}\")\n\n async def discover_by_skills(\n self,\n skills: list[str],\n tags: list[str] | None = None,\n max_results: int = 5,\n ) -> list[DiscoveredAgent]:\n \"\"\"Discover agents by required skills and tags.\n\n Args:\n skills: Required skill names or IDs\n tags: Optional tag filters\n max_results: Maximum number of results to return\n\n Returns:\n List of discovered agents with relevance scores\n\n Raises:\n Exception: If discovery fails\n \"\"\"\n logger.info(f\"Skill-based search: skills={skills}, tags={tags}\")\n\n token = await self._get_token()\n discovery_url = f\"{self.registry_url}/api/agents/discover\"\n headers = {\n \"Authorization\": f\"Bearer {token}\",\n \"Content-Type\": \"application/json\",\n }\n body = {\n \"skills\": skills,\n \"tags\": tags or [],\n \"max_results\": max_results,\n }\n\n async with aiohttp.ClientSession() as session:\n try:\n async with session.post(\n discovery_url,\n headers=headers,\n json=body,\n ) as response:\n if response.status != 200:\n error_text = await response.text()\n logger.error(f\"Discovery failed: {response.status} - {error_text}\")\n raise Exception(f\"Discovery failed: {response.status}\")\n\n result = await response.json()\n agents_data = result.get(\"agents\", [])\n\n agents = [DiscoveredAgent(**agent) for agent in agents_data]\n logger.info(f\"Found {len(agents)} agents\")\n\n return agents\n\n except aiohttp.ClientError as e:\n logger.error(f\"Network error during discovery: {e}\")\n raise Exception(f\"Network error: {e}\")\n" }, { "path": "agents/a2a/src/travel-assistant-agent/remote_agent_client.py", "content": "\"\"\"Client for communicating with remote A2A agents.\"\"\"\n\nimport logging\nfrom uuid import uuid4\n\nimport httpx\nfrom a2a.client import A2ACardResolver, ClientConfig, ClientFactory\nfrom a2a.types import Message, Part, Role, TextPart\nfrom models import DiscoveredAgent\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass RemoteAgentClient:\n \"\"\"\n Client for communicating with a remote A2A agent.\n This class wraps an A2A agent discovered from the registry, providing\n lazy initialization and reusable client connections.\n\n Reference: https://strandsagents.com/latest/documentation/docs/user-guide/concepts/multi-agent/agent-to-agent/\n \"\"\"\n\n def __init__(\n self,\n agent_url: str,\n agent_name: str,\n agent_id: str,\n skills: list[str] | None = None,\n auth_token: str | None = None,\n ):\n self.agent_url = agent_url\n self.agent_name = agent_name\n self.agent_id = agent_id\n self.skills = skills or []\n self.auth_token = auth_token\n self.agent_card = None\n self.client = None\n self.httpx_client = None\n self._initialized = False\n logger.info(\n f\"Created RemoteAgentClient for: {agent_name} (ID: {agent_id}, Skills: {len(self.skills)})\"\n )\n\n async def _ensure_initialized(self):\n if self._initialized:\n return\n\n logger.info(f\"Initializing A2A client for {self.agent_name} at {self.agent_url}\")\n\n headers = {}\n if self.auth_token:\n headers[\"Authorization\"] = f\"Bearer {self.auth_token}\"\n\n # Create persistent httpx client (not using context manager)\n self.httpx_client = httpx.AsyncClient(timeout=300, headers=headers)\n\n # Get agent card\n resolver = A2ACardResolver(httpx_client=self.httpx_client, base_url=self.agent_url)\n self.agent_card = await resolver.get_agent_card()\n\n # Create client with persistent httpx_client\n config = ClientConfig(httpx_client=self.httpx_client, streaming=False)\n factory = ClientFactory(config)\n self.client = factory.create(self.agent_card)\n\n self._initialized = True\n logger.info(f\"A2A client initialized for {self.agent_name}\")\n\n async def send_message(self, message: str) -> str:\n # Send a natural language message to the remote agent.\n await self._ensure_initialized()\n\n logger.info(f\"Sending message to {self.agent_name}: {message[:100]}...\")\n\n try:\n # Create A2A message\n msg = Message(\n kind=\"message\",\n role=Role.user,\n parts=[Part(TextPart(kind=\"text\", text=message))],\n message_id=uuid4().hex,\n )\n\n # Send message and get response\n async for event in self.client.send_message(msg):\n if isinstance(event, Message):\n response_text = \"\"\n for part in event.parts:\n if hasattr(part, \"text\"):\n response_text += part.text\n logger.info(f\"Message sent successfully to {self.agent_name}\")\n return response_text\n\n return f\"No response received from {self.agent_name}\"\n\n except Exception as e:\n logger.error(f\"Message failed: {e}\", exc_info=True)\n return f\"Error communicating with {self.agent_name}: an internal error occurred\"\n\n async def close(self):\n # Close the httpx client and cleanup resources\n if self.httpx_client:\n await self.httpx_client.aclose()\n logger.info(f\"Closed httpx client for {self.agent_name}\")\n\n\nclass RemoteAgentCache:\n def __init__(self):\n self._cache: dict[str, RemoteAgentClient] = {}\n logger.info(\"RemoteAgentCache initialized\")\n\n def get(self, agent_id: str) -> RemoteAgentClient | None:\n return self._cache.get(agent_id)\n\n def get_all(self) -> dict[str, RemoteAgentClient]:\n return self._cache.copy()\n\n def add(self, agent_id: str, agent_client: RemoteAgentClient):\n self._cache[agent_id] = agent_client\n logger.info(f\"Added agent to cache: {agent_id}\")\n\n def cache_discovered_agents(\n self, agents: list[DiscoveredAgent], auth_token: str | None = None\n ) -> dict[str, RemoteAgentClient]:\n newly_cached = {}\n\n for agent in agents:\n agent_id = agent.path\n\n # Skip if already cached\n if agent_id in self._cache:\n logger.info(f\"Agent {agent_id} already cached, skipping\")\n continue\n\n # Create and cache the remote agent client\n agent_client = RemoteAgentClient(\n agent_url=agent.url,\n agent_name=agent.name,\n agent_id=agent_id,\n skills=agent.skill_names,\n auth_token=auth_token,\n )\n\n self._cache[agent_id] = agent_client\n newly_cached[agent_id] = agent_client\n logger.info(f\"Cached agent: {agent.name} (ID: {agent_id})\")\n\n logger.info(f\"Cached {len(newly_cached)} new agents. Total in cache: {len(self._cache)}\")\n return newly_cached\n\n async def clear(self):\n count = len(self._cache)\n for agent_client in self._cache.values():\n await agent_client.close()\n\n self._cache.clear()\n logger.info(f\"Cleared {count} agents from cache\")\n\n def __len__(self) -> int:\n return len(self._cache)\n\n def __contains__(self, agent_id: str) -> bool:\n return agent_id in self._cache\n" }, { "path": "agents/a2a/src/travel-assistant-agent/server.py", "content": "\"\"\"Travel Assistant Agent - Main application module.\"\"\"\n\nimport logging\nfrom contextlib import asynccontextmanager\n\nimport uvicorn\nfrom agent import (\n check_prices,\n create_trip_plan,\n get_recommendations,\n search_flights,\n strands_agent,\n)\nfrom dependencies import (\n get_db_manager,\n get_env,\n)\nfrom fastapi import FastAPI\nfrom strands.multiagent.a2a import A2AServer\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nenv_settings = get_env()\n\n# Use agent instance from tools module\na2a_server = A2AServer(agent=strands_agent, http_url=env_settings.agent_url, serve_at_root=True)\n\n\n@asynccontextmanager\nasync def lifespan(\n app: FastAPI,\n):\n \"\"\"Application lifespan manager.\"\"\"\n # Setups before server startup\n get_db_manager()\n logger.info(\"Travel Assistant Agent starting up\")\n logger.info(f\"Agent URL: {env_settings.agent_url}\")\n logger.info(f\"Listening on {env_settings.host}:{env_settings.port}\")\n\n yield\n # Triggered after server shutdown\n logger.info(\"Travel Assistant Agent shutting down\")\n\n\napp = FastAPI(title=\"Travel Assistant Agent\", lifespan=lifespan)\n\n\n@app.get(\"/ping\")\ndef ping():\n \"\"\"Health check endpoint.\"\"\"\n logger.debug(\"Ping endpoint called\")\n return {\"status\": \"healthy\"}\n\n\n@app.get(\"/api/health\")\ndef health():\n \"\"\"Health status endpoint.\"\"\"\n logger.debug(\"Health endpoint called\")\n return {\"status\": \"healthy\", \"agent\": \"travel_assistant\"}\n\n\n@app.post(\"/api/search-flights\")\ndef api_search_flights(\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n):\n \"\"\"Search flights API endpoint.\"\"\"\n logger.info(f\"Searching flights: {departure_city} to {arrival_city} on {departure_date}\")\n result = search_flights(departure_city, arrival_city, departure_date)\n logger.debug(f\"Flight search result: {result}\")\n return {\"result\": result}\n\n\n@app.post(\"/api/check-prices\")\ndef api_check_prices(\n flight_id: int,\n):\n \"\"\"Check prices API endpoint.\"\"\"\n logger.info(f\"Checking prices for flight_id: {flight_id}\")\n result = check_prices(flight_id)\n logger.debug(f\"Price check result: {result}\")\n return {\"result\": result}\n\n\n@app.get(\"/api/recommendations\")\ndef api_recommendations(\n max_price: float,\n preferred_airlines: str | None = None,\n):\n \"\"\"Get recommendations API endpoint.\"\"\"\n logger.info(\n f\"Getting recommendations: max_price={max_price}, preferred_airlines={preferred_airlines}\"\n )\n airlines = preferred_airlines.split(\",\") if preferred_airlines else None\n result = get_recommendations(max_price, airlines)\n logger.debug(f\"Recommendations result: {result}\")\n return {\"result\": result}\n\n\n@app.post(\"/api/create-trip-plan\")\ndef api_create_trip_plan(\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n return_date: str | None = None,\n budget: float | None = None,\n):\n \"\"\"Create trip plan API endpoint.\"\"\"\n logger.info(\n f\"Creating trip plan: {departure_city} to {arrival_city}, dates: {departure_date} - {return_date}\"\n )\n logger.debug(f\"Budget: {budget}\")\n result = create_trip_plan(departure_city, arrival_city, departure_date, return_date, budget)\n logger.debug(f\"Trip plan result: {result}\")\n return {\"result\": result}\n\n\n@app.post(\"/api/discover-agents\")\nasync def api_discover_agents(query: str):\n \"\"\"Discover agents through registry using semantic search.\"\"\"\n logger.info(f\"Agent discovery request: query='{query}'\")\n\n from dependencies import get_registry_client\n\n registry_client = get_registry_client()\n if not registry_client:\n return {\"error\": \"Discovery not configured\"}\n\n try:\n agents = await registry_client.discover_by_semantic_search(\n query=query,\n max_results=5,\n )\n return {\n \"query\": query,\n \"agents_found\": len(agents),\n \"agents\": [agent.model_dump() for agent in agents],\n }\n except Exception as e:\n logger.error(f\"Discovery failed: {e}\", exc_info=True)\n return {\"error\": \"An internal error occurred during agent discovery\"}\n\n\napp.mount(\"/\", a2a_server.to_fastapi_app())\n\n\ndef main() -> None:\n \"\"\"Main entry point for the application.\"\"\"\n logger.info(\"Starting Travel Assistant Agent server\")\n uvicorn.run(app, host=env_settings.host, port=env_settings.port)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "agents/a2a/src/travel-assistant-agent/tools.py", "content": "\"\"\"Tools for Travel Assistant Agent - Flight search and trip planning utilities.\"\"\"\n\nimport json\nimport logging\n\nfrom dependencies import get_db_manager\nfrom strands import tool\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n@tool\ndef search_flights(\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n) -> str:\n \"\"\"Search for available flights between cities on a specific date.\"\"\"\n logger.info(\n f\"Tool called: search_flights(departure_city={departure_city}, arrival_city={arrival_city}, departure_date={departure_date})\"\n )\n try:\n flights = get_db_manager().search_flights(departure_city, arrival_city, departure_date)\n\n result = {\n \"query\": {\n \"departure_city\": departure_city,\n \"arrival_city\": arrival_city,\n \"departure_date\": departure_date,\n },\n \"flights\": flights,\n \"count\": len(flights),\n }\n\n logger.debug(f\"Flight search result:\\n{json.dumps(result, indent=2)}\")\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in search_flights: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef check_prices(\n flight_id: int,\n) -> str:\n \"\"\"Get pricing and seat availability for a specific flight.\"\"\"\n logger.info(f\"Tool called: check_prices(flight_id={flight_id})\")\n try:\n flight_details = get_db_manager().get_flight_details(flight_id)\n\n if not flight_details:\n error_msg = f\"Flight with ID {flight_id} not found\"\n logger.warning(error_msg)\n return json.dumps({\"error\": error_msg})\n\n logger.debug(f\"Flight details result:\\n{json.dumps(flight_details, indent=2)}\")\n return json.dumps(flight_details, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in check_prices: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef get_recommendations(\n max_price: float,\n preferred_airlines: list[str] | None = None,\n) -> str:\n \"\"\"Get flight recommendations based on customer preferences.\"\"\"\n logger.info(\n f\"Tool called: get_recommendations(max_price={max_price}, preferred_airlines={preferred_airlines})\"\n )\n try:\n recommendations = get_db_manager().get_recommendations(max_price, preferred_airlines)\n\n result = {\n \"criteria\": {\"max_price\": max_price, \"preferred_airlines\": preferred_airlines or \"Any\"},\n \"recommendations\": recommendations,\n \"count\": len(recommendations),\n }\n\n logger.debug(f\"Recommendations result:\\n{json.dumps(result, indent=2)}\")\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in get_recommendations: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n@tool\ndef create_trip_plan(\n departure_city: str,\n arrival_city: str,\n departure_date: str,\n return_date: str | None = None,\n budget: float | None = None,\n) -> str:\n \"\"\"Create and save a trip planning record.\"\"\"\n logger.info(\n f\"Tool called: create_trip_plan(departure_city={departure_city}, arrival_city={arrival_city}, departure_date={departure_date})\"\n )\n logger.debug(f\"Return date: {return_date}, Budget: {budget}\")\n try:\n db_manager = get_db_manager()\n trip_plan_id = db_manager.create_trip_plan(\n departure_city, arrival_city, departure_date, return_date, budget\n )\n\n # Get available flights for the trip\n outbound_flights = db_manager.search_flights(departure_city, arrival_city, departure_date)\n return_flights = []\n\n if return_date:\n return_flights = db_manager.search_flights(arrival_city, departure_city, return_date)\n\n result = {\n \"trip_plan_id\": trip_plan_id,\n \"trip_details\": {\n \"departure_city\": departure_city.upper(),\n \"arrival_city\": arrival_city.upper(),\n \"departure_date\": departure_date,\n \"return_date\": return_date,\n \"budget\": budget,\n \"status\": \"planning\",\n },\n \"outbound_flights\": outbound_flights,\n \"return_flights\": return_flights,\n \"next_steps\": [\n \"Review available flights\",\n \"Select preferred flights\",\n \"Contact Flight Booking Agent for reservation\",\n ],\n }\n\n logger.debug(f\"Trip plan result:\\n{json.dumps(result, indent=2)}\")\n return json.dumps(result, indent=2)\n\n except Exception as e:\n logger.exception(f\"Database error in create_trip_plan: {e}\")\n return json.dumps({\"error\": \"An internal database error occurred\"})\n\n\n# TODO: Create tool that's able to dynamically search agents from MCP Registry\n# example:\n# @tool\n# def delegate_to_agent(agent_capability: str, action: str, params: Dict) -> str:\n\n\nTRAVEL_ASSISTANT_TOOLS = [search_flights, check_prices, get_recommendations, create_trip_plan]\n" }, { "path": "agents/a2a/test/agent_discovery_test.py", "content": "#!/usr/bin/env python3\n\"\"\"\nTest script for agent discovery and booking workflow.\n\nTest 1: Travel agent searches for flights using its own tools\nTest 2: Travel agent discovers booking agent, checks availability, reserves seats, and completes booking\n\nUsage: python agent_discovery_test_v2.py [--endpoint local|live]\n\"\"\"\n\nimport argparse\nimport logging\nimport sys\n\nimport requests\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nLOCAL_ENDPOINTS = {\n \"travel_assistant\": \"http://localhost:9001\",\n}\n\n\nclass AgentTester:\n \"\"\"Agent testing class.\"\"\"\n\n def __init__(self, endpoints, is_live=False):\n self.endpoints = endpoints\n self.is_live = is_live\n\n def send_agent_message(self, agent_type, message):\n \"\"\"Send message to agent using A2A protocol.\"\"\"\n endpoint = self.endpoints[agent_type]\n\n payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": f\"test-{message[:10]}\",\n \"method\": \"message/send\",\n \"params\": {\n \"message\": {\n \"role\": \"user\",\n \"parts\": [{\"kind\": \"text\", \"text\": message}],\n \"messageId\": f\"msg-{message[:10]}\",\n }\n },\n }\n\n response = requests.post(\n endpoint, json=payload, headers={\"Content-Type\": \"application/json\"}, timeout=60\n )\n return response.json()\n\n def extract_response_text(self, response):\n \"\"\"Extract text from A2A response.\"\"\"\n if \"result\" not in response:\n return \"\"\n\n artifacts = response[\"result\"].get(\"artifacts\", [])\n response_text = \"\"\n for artifact in artifacts:\n if \"parts\" in artifact:\n for part in artifact[\"parts\"]:\n if \"text\" in part:\n response_text += part[\"text\"]\n return response_text\n\n\nclass AgentDiscoveryTests:\n \"\"\"Test suite for agent discovery and booking workflow.\"\"\"\n\n def __init__(self, tester):\n self.tester = tester\n self.agent_type = \"travel_assistant\"\n\n def test_search_flight_solo(self):\n \"\"\"Test 1: Travel agent searches for flights using its own tools.\"\"\"\n print(\"\\n1. Testing flight search (travel agent solo)...\")\n message = \"Search for flights from New York to Los Angeles on 2025-12-20\"\n response = self.tester.send_agent_message(self.agent_type, message)\n\n assert \"result\" in response, f\"No result in response: {response}\"\n response_text = self.tester.extract_response_text(response)\n\n # Check if flight search happened\n assert any(\n keyword in response_text.lower()\n for keyword in [\"flight\", \"new york\", \"los angeles\", \"nyc\", \"lax\"]\n ), f\"Response doesn't mention flight search. Got: {response_text[:300]}\"\n\n print(\" ✓ Travel agent searched for flights using its own tools\")\n print(f\" Response preview: {response_text[:200]}...\")\n return response_text\n\n def test_book_flight_with_discovery(self):\n \"\"\"Test 2: Travel agent discovers booking agent and delegates booking tasks.\"\"\"\n print(\"\\n2. Testing flight booking with agent discovery and invocation...\")\n message = (\n \"I want to book flight ID 1. I need you to reserve 2 seats, confirm the reservation, \"\n \"and process the payment. You don't have these booking capabilities yourself, so you'll \"\n \"need to find and use an agent that can handle flight reservations and confirmations.\"\n )\n response = self.tester.send_agent_message(self.agent_type, message)\n response_text = self.tester.extract_response_text(response)\n\n # Check if agent discovery and delegation happened\n assert any(\n keyword in response_text.lower()\n for keyword in [\"reserve\", \"book\", \"confirm\", \"agent\", \"discover\"]\n ), f\"Booking workflow failed. Got: {response_text[:300]}\"\n print(\" ✓ Booking agent discovered and invoked\")\n print(f\" Response preview: {response_text[:200]}...\")\n\n print(\" ✓ Complete booking workflow succeeded\")\n return response_text\n\n\ndef run_tests(endpoint_type):\n \"\"\"Run all discovery tests.\"\"\"\n print(\n f\"Running agent discovery and booking workflow tests against {endpoint_type} endpoints...\"\n )\n print(\"=\" * 70)\n print(\"Test 1: Travel agent searches for flights (solo)\")\n print(\"Test 2: Travel agent discovers booking agent and completes booking\")\n print(\"=\" * 70)\n\n endpoints = LOCAL_ENDPOINTS\n is_live = endpoint_type == \"live\"\n tester = AgentTester(endpoints, is_live=is_live)\n\n try:\n discovery_tests = AgentDiscoveryTests(tester)\n\n # Run tests in sequence\n discovery_tests.test_search_flight_solo()\n discovery_tests.test_book_flight_with_discovery()\n\n print(\"\\n\" + \"=\" * 70)\n print(\"✅ All tests passed!\")\n print(\"=\" * 70)\n return True\n\n except AssertionError as e:\n logger.error(f\"Test assertion failed: {e}\")\n print(f\"\\n❌ Test failed: {e}\")\n return False\n except Exception as e:\n logger.exception(\"Test failed with exception\")\n print(f\"\\n❌ Test failed with exception: {e}\")\n return False\n\n\ndef main():\n \"\"\"Main entry point for test script.\"\"\"\n parser = argparse.ArgumentParser(description=\"Test agent discovery and booking workflow\")\n parser.add_argument(\n \"--endpoint\",\n choices=[\"local\", \"live\"],\n default=\"local\",\n help=\"Test against local or live endpoints (default: local)\",\n )\n\n args = parser.parse_args()\n success = run_tests(args.endpoint)\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "agents/a2a/test/agent_simple_test.py", "content": "#!/usr/bin/env python3\n\"\"\"\nTest script for Travel Assistant and Flight Booking agents\nUsage: python simple_agents_test.py --endpoint local|live [--debug]\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport sys\nimport time\nimport uuid\nfrom typing import (\n Any,\n)\n\nimport boto3\nimport requests\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n# Endpoint configurations\nLOCAL_ENDPOINTS = {\n \"travel_assistant\": \"http://localhost:9001\",\n \"flight_booking\": \"http://localhost:9002\",\n}\n\nLIVE_ENDPOINTS = {\n \"travel_assistant\": \"travel_assistant_agent ARN\",\n \"flight_booking\": \"flight_booking_agent ARN\",\n}\n\nAWS_REGION = \"us-east-1\"\n\n\nclass AgentTester:\n \"\"\"Agent testing class for both local and live endpoints.\"\"\"\n\n def __init__(\n self,\n endpoints: dict[str, str],\n is_live: bool = False,\n ) -> None:\n self.endpoints = endpoints\n self.is_live = is_live\n if is_live:\n self.bedrock_client = boto3.client(\"bedrock-agentcore\", region_name=AWS_REGION)\n\n def send_agent_message(\n self,\n agent_type: str,\n message: str,\n ) -> dict[str, Any]:\n \"\"\"Send message to agent using A2A protocol (local) or boto3 (live).\"\"\"\n endpoint = self.endpoints[agent_type]\n if not endpoint:\n raise ValueError(f\"No endpoint configured for {agent_type}\")\n\n request_id = f\"test-{uuid.uuid4().hex[:8]}\"\n message_id = f\"test-msg-{uuid.uuid4().hex[:8]}\"\n timestamp = time.time()\n\n if self.is_live:\n # Use boto3 for AgentCore Runtime\n return self._invoke_agentcore_runtime(\n endpoint, message, request_id, message_id, timestamp\n )\n else:\n # Use HTTP for local A2A\n payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": request_id,\n \"method\": \"message/send\",\n \"params\": {\n \"message\": {\n \"role\": \"user\",\n \"parts\": [{\"kind\": \"text\", \"text\": message}],\n \"messageId\": message_id,\n }\n },\n }\n\n logger.debug(f\"[REQUEST] Agent: {agent_type}, Endpoint: {endpoint}\")\n logger.debug(f\"[REQUEST] ID: {request_id}, Message ID: {message_id}\")\n logger.debug(f\"[REQUEST] Payload:\\n{json.dumps(payload, indent=2)}\")\n\n start_time = time.time()\n response = requests.post(\n endpoint, json=payload, headers={\"Content-Type\": \"application/json\"}, timeout=60\n )\n response_time = time.time() - start_time\n\n response_json = response.json()\n logger.debug(f\"[RESPONSE] Time: {response_time:.3f}s, Status: {response.status_code}\")\n logger.debug(f\"[RESPONSE] Body:\\n{json.dumps(response_json, indent=2, default=str)}\")\n\n return response_json\n\n def _invoke_agentcore_runtime(\n self,\n runtime_arn: str,\n message: str,\n request_id: str,\n message_id: str,\n timestamp: float,\n ) -> dict[str, Any]:\n \"\"\"Invoke AgentCore Runtime using boto3.\"\"\"\n # A2A protocol requires JSON-RPC format\n payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": request_id,\n \"method\": \"message/send\",\n \"params\": {\n \"message\": {\n \"role\": \"user\",\n \"parts\": [{\"kind\": \"text\", \"text\": message}],\n \"messageId\": message_id,\n }\n },\n }\n payload_json = json.dumps(payload)\n\n logger.debug(f\"[AGENTCORE REQUEST] ARN: {runtime_arn}\")\n logger.debug(f\"[AGENTCORE REQUEST] ID: {request_id}, Message ID: {message_id}\")\n logger.debug(f\"[AGENTCORE REQUEST] Payload:\\n{json.dumps(payload, indent=2)}\")\n\n # Generate session ID (must be 33+ characters)\n session_id = f\"test-session-{uuid.uuid4().hex}\"\n logger.debug(f\"[AGENTCORE REQUEST] Session ID: {session_id}\")\n\n try:\n start_time = time.time()\n response = self.bedrock_client.invoke_agent_runtime(\n agentRuntimeArn=runtime_arn,\n runtimeSessionId=session_id,\n qualifier=\"DEFAULT\",\n payload=payload_json,\n )\n response_time = time.time() - start_time\n\n # Read streaming response\n if \"response\" in response:\n streaming_body = response[\"response\"]\n all_lines = []\n\n for line in streaming_body.iter_lines():\n line_str = line.decode(\"utf-8\")\n all_lines.append(line_str)\n logger.debug(f\"[AGENTCORE STREAM] Line: {line_str}\")\n\n # The response is a single JSON-RPC response line\n if all_lines:\n try:\n json_response = json.loads(all_lines[0])\n\n logger.debug(f\"[AGENTCORE RESPONSE] Time: {response_time:.3f}s\")\n logger.debug(\n f\"[AGENTCORE RESPONSE] Body:\\n{json.dumps(json_response, indent=2, default=str)}\"\n )\n\n # Check for JSON-RPC error\n if \"error\" in json_response:\n return {\"error\": json_response[\"error\"]}\n\n # Return the JSON-RPC result directly\n return json_response\n\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to parse response: {e}\")\n return {\"error\": f\"Failed to parse response: {e}\"}\n\n return {\"error\": \"Empty response\"}\n\n return {\"error\": \"No response content\"}\n\n except Exception as e:\n logger.error(f\"AgentCore invocation failed: {e}\")\n return {\"error\": str(e)}\n\n def call_api_endpoint(\n self,\n agent_type: str,\n endpoint: str,\n method: str = \"POST\",\n **params,\n ) -> dict[str, Any]:\n \"\"\"Call direct API endpoint (only works for local).\"\"\"\n if self.is_live:\n raise NotImplementedError(\n \"Direct API endpoints not available for live AgentCore Runtime\"\n )\n\n url = f\"{self.endpoints[agent_type]}{endpoint}\"\n if not self.endpoints[agent_type]:\n raise ValueError(f\"No endpoint configured for {agent_type}\")\n\n logger.debug(f\"[API REQUEST] Agent: {agent_type}, URL: {url}\")\n logger.debug(f\"[API REQUEST] Method: {method}, Params: {params}\")\n\n start_time = time.time()\n if method.upper() == \"GET\":\n response = requests.get(url, params=params, timeout=60)\n else:\n response = requests.post(url, params=params, timeout=60)\n response_time = time.time() - start_time\n\n response_json = response.json()\n logger.debug(f\"[API RESPONSE] Time: {response_time:.3f}s, Status: {response.status_code}\")\n logger.debug(f\"[API RESPONSE] Body:\\n{json.dumps(response_json, indent=2, default=str)}\")\n\n return response_json\n\n def ping_agent(\n self,\n agent_type: str,\n ) -> bool:\n \"\"\"Check if agent is healthy (only works for local).\"\"\"\n if self.is_live:\n # For live, we can't ping directly, assume healthy if ARN is configured\n return bool(self.endpoints.get(agent_type))\n\n try:\n url = f\"{self.endpoints[agent_type]}/ping\"\n logger.debug(f\"[PING] Agent: {agent_type}, URL: {url}\")\n\n start_time = time.time()\n response = requests.get(url, timeout=5)\n response_time = time.time() - start_time\n\n is_healthy = response.status_code == 200 and response.json().get(\"status\") == \"healthy\"\n logger.debug(f\"[PING RESPONSE] Time: {response_time:.3f}s, Healthy: {is_healthy}\")\n\n return is_healthy\n except Exception as e:\n logger.debug(f\"[PING ERROR] Agent: {agent_type}, Error: {e}\")\n return False\n\n\nclass TravelAssistantTests:\n \"\"\"Test suite for Travel Assistant agent.\"\"\"\n\n def __init__(\n self,\n tester: AgentTester,\n ) -> None:\n self.tester = tester\n self.agent_type = \"travel_assistant\"\n\n def test_ping(self) -> None:\n \"\"\"Test agent health check.\"\"\"\n print(\"Testing Travel Assistant ping...\")\n result = self.tester.ping_agent(self.agent_type)\n assert result, \"Travel Assistant ping failed\"\n print(\"✓ Travel Assistant is healthy\")\n\n def test_agent_flight_search(self) -> None:\n \"\"\"Test agent flight search via A2A.\"\"\"\n print(\"Testing Travel Assistant flight search...\")\n message = \"Search for flights from SF to NY on 2025-11-15\"\n response = self.tester.send_agent_message(self.agent_type, message)\n\n assert \"result\" in response, f\"No result in response: {response}\"\n assert \"artifacts\" in response[\"result\"], \"No artifacts in response\"\n\n # Check if agent found flights\n artifacts = response[\"result\"][\"artifacts\"]\n assert len(artifacts) > 0, \"No artifacts returned\"\n\n # Extract text from artifact parts\n response_text = \"\"\n for artifact in artifacts:\n if \"parts\" in artifact:\n for part in artifact[\"parts\"]:\n if \"text\" in part:\n response_text += part[\"text\"]\n\n assert \"flight\" in response_text.lower(), (\n f\"Response doesn't mention flights. Got: {response_text[:100]}\"\n )\n print(\"✓ Travel Assistant flight search working\")\n\n def test_api_search_flights(self) -> None:\n \"\"\"Test direct API endpoint (local only).\"\"\"\n if self.tester.is_live:\n print(\n \"Skipping /api/search-flights endpoint (only available in local Docker container)\"\n )\n return\n\n print(\"Testing Travel Assistant API endpoint...\")\n response = self.tester.call_api_endpoint(\n self.agent_type,\n \"/api/search-flights\",\n departure_city=\"SF\",\n arrival_city=\"NY\",\n departure_date=\"2025-11-15\",\n )\n\n assert \"result\" in response, f\"No result in API response: {response}\"\n result_data = json.loads(response[\"result\"])\n assert \"flights\" in result_data, \"No flights in API response\"\n assert len(result_data[\"flights\"]) > 0, \"No flights found\"\n print(\"✓ Travel Assistant API endpoint working\")\n\n def test_api_recommendations(self) -> None:\n \"\"\"Test recommendations API (local only).\"\"\"\n if self.tester.is_live:\n print(\n \"Skipping /api/recommendations endpoint (only available in local Docker container)\"\n )\n return\n\n print(\"Testing Travel Assistant recommendations...\")\n response = self.tester.call_api_endpoint(\n self.agent_type,\n \"/api/recommendations\",\n method=\"GET\",\n max_price=300,\n preferred_airlines=\"United,Delta\",\n )\n\n assert \"result\" in response, \"No result in recommendations response\"\n result_data = json.loads(response[\"result\"])\n assert \"recommendations\" in result_data, \"No recommendations in response\"\n print(\"✓ Travel Assistant recommendations working\")\n\n\nclass FlightBookingTests:\n \"\"\"Test suite for Flight Booking agent.\"\"\"\n\n def __init__(\n self,\n tester: AgentTester,\n ) -> None:\n self.tester = tester\n self.agent_type = \"flight_booking\"\n\n def test_ping(self) -> None:\n \"\"\"Test agent health check.\"\"\"\n print(\"Testing Flight Booking ping...\")\n result = self.tester.ping_agent(self.agent_type)\n assert result, \"Flight Booking ping failed\"\n print(\"✓ Flight Booking is healthy\")\n\n def test_agent_availability_check(self) -> None:\n \"\"\"Test agent availability check via A2A.\"\"\"\n print(\"Testing Flight Booking availability check...\")\n message = \"Check availability for flight ID 1\"\n response = self.tester.send_agent_message(self.agent_type, message)\n\n assert \"result\" in response, f\"No result in response: {response}\"\n assert \"artifacts\" in response[\"result\"], \"No artifacts in response\"\n\n artifacts = response[\"result\"][\"artifacts\"]\n assert len(artifacts) > 0, \"No artifacts returned\"\n\n response_text = artifacts[0][\"parts\"][0][\"text\"]\n assert \"available\" in response_text.lower(), \"Response doesn't mention availability\"\n print(\"✓ Flight Booking availability check working\")\n\n def test_agent_booking(self) -> None:\n \"\"\"Test agent booking via A2A.\"\"\"\n print(\"Testing Flight Booking reservation...\")\n message = \"Book flight ID 1 for Jane Smith, email jane@test.com\"\n response = self.tester.send_agent_message(self.agent_type, message)\n\n assert \"result\" in response, f\"No result in response: {response}\"\n artifacts = response[\"result\"][\"artifacts\"]\n response_text = artifacts[0][\"parts\"][0][\"text\"]\n\n assert \"booking\" in response_text.lower() or \"reserved\" in response_text.lower(), (\n \"Response doesn't mention booking/reservation\"\n )\n print(\"✓ Flight Booking reservation working\")\n\n def test_api_check_availability(self) -> None:\n \"\"\"Test direct API endpoint (local only).\"\"\"\n if self.tester.is_live:\n print(\n \"Skipping /api/check-availability endpoint (only available in local Docker container)\"\n )\n return\n\n print(\"Testing Flight Booking API endpoint...\")\n response = self.tester.call_api_endpoint(\n self.agent_type, \"/api/check-availability\", flight_id=1\n )\n\n assert \"result\" in response, f\"No result in API response: {response}\"\n result_data = json.loads(response[\"result\"])\n assert \"flight_id\" in result_data, \"No flight_id in API response\"\n assert \"available_seats\" in result_data, \"No available_seats in response\"\n print(\"✓ Flight Booking API endpoint working\")\n\n\ndef run_tests(\n endpoint_type: str,\n) -> bool:\n \"\"\"Run all tests for specified endpoint type.\"\"\"\n print(f\"Running tests against {endpoint_type} endpoints...\")\n print(\"=\" * 50)\n\n # Select endpoints\n endpoints = LOCAL_ENDPOINTS if endpoint_type == \"local\" else LIVE_ENDPOINTS\n\n # Check if endpoints are configured\n for agent, url in endpoints.items():\n if not url:\n print(f\"❌ No {endpoint_type} endpoint configured for {agent}\")\n return False\n\n is_live = endpoint_type == \"live\"\n tester = AgentTester(endpoints, is_live=is_live)\n\n try:\n # Test Travel Assistant\n print(\"\\nTesting Travel Assistant Agent\")\n print(\"-\" * 30)\n travel_tests = TravelAssistantTests(tester)\n travel_tests.test_ping()\n travel_tests.test_agent_flight_search()\n travel_tests.test_api_search_flights()\n travel_tests.test_api_recommendations()\n\n # Test Flight Booking\n print(\"\\nTesting Flight Booking Agent\")\n print(\"-\" * 30)\n booking_tests = FlightBookingTests(tester)\n booking_tests.test_ping()\n booking_tests.test_agent_availability_check()\n booking_tests.test_agent_booking()\n booking_tests.test_api_check_availability()\n\n print(\"\\n\" + \"=\" * 50)\n print(\"✅ All tests passed!\")\n return True\n\n except Exception as e:\n logger.exception(\"Test failed with exception\")\n print(f\"\\n❌ Test failed: {e}\")\n return False\n\n\ndef main() -> None:\n \"\"\"Main entry point for test script.\"\"\"\n parser = argparse.ArgumentParser(description=\"Test Travel Assistant and Flight Booking agents\")\n parser.add_argument(\n \"--endpoint\",\n choices=[\"local\", \"live\"],\n required=True,\n help=\"Test against local or live endpoints\",\n )\n parser.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable debug logging to see detailed request/response traces\",\n )\n parser.add_argument(\n \"--verbose\",\n action=\"store_true\",\n help=\"Alias for --debug, enables debug logging\",\n )\n\n args = parser.parse_args()\n\n # Enable debug logging if requested\n if args.debug or args.verbose:\n logging.getLogger().setLevel(logging.DEBUG)\n logger.info(\"Debug logging enabled - detailed traces will be shown\")\n\n success = run_tests(args.endpoint)\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "agents/a2a/test/check_agent_cards.sh", "content": "#!/bin/bash\n\n# Check agent cards for local deployments and save to local files\n\nset -e\n\n# Get script directory\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\n\necho \"Checking Agent Cards...\"\necho \"================================\"\n\n# Check if jq is installed\nif ! command -v jq &> /dev/null; then\n echo \"Warning: jq not installed. Output will not be formatted.\"\n JQ_CMD=\"cat\"\nelse\n JQ_CMD=\"jq .\"\nfi\n\necho \"\"\necho \"Travel Assistant Agent Card:\"\necho \"--------------------------------\"\nTRAVEL_CARD_FILE=\"$SCRIPT_DIR/travel_assistant_agent_card.json\"\nTRAVEL_CARD_RESPONSE=$(curl -s http://localhost:9001/.well-known/agent-card.json)\n\nif [ -n \"$TRAVEL_CARD_RESPONSE\" ]; then\n echo \"$TRAVEL_CARD_RESPONSE\" | $JQ_CMD\n if command -v jq &> /dev/null; then\n echo \"$TRAVEL_CARD_RESPONSE\" | jq . > \"$TRAVEL_CARD_FILE\"\n else\n echo \"$TRAVEL_CARD_RESPONSE\" > \"$TRAVEL_CARD_FILE\"\n fi\n echo \"✅ Travel Assistant agent card retrieved\"\n echo \" Saved to: $TRAVEL_CARD_FILE\"\nelse\n echo \"❌ Failed to retrieve Travel Assistant agent card\"\n echo \" Is the agent running on port 9001?\"\nfi\n\necho \"\"\necho \"Flight Booking Agent Card:\"\necho \"--------------------------------\"\nBOOKING_CARD_FILE=\"$SCRIPT_DIR/flight_booking_agent_card.json\"\nBOOKING_CARD_RESPONSE=$(curl -s http://localhost:9002/.well-known/agent-card.json)\n\nif [ -n \"$BOOKING_CARD_RESPONSE\" ]; then\n echo \"$BOOKING_CARD_RESPONSE\" | $JQ_CMD\n if command -v jq &> /dev/null; then\n echo \"$BOOKING_CARD_RESPONSE\" | jq . > \"$BOOKING_CARD_FILE\"\n else\n echo \"$BOOKING_CARD_RESPONSE\" > \"$BOOKING_CARD_FILE\"\n fi\n echo \"✅ Flight Booking agent card retrieved\"\n echo \" Saved to: $BOOKING_CARD_FILE\"\nelse\n echo \"❌ Failed to retrieve Flight Booking agent card\"\n echo \" Is the agent running on port 9002?\"\nfi\n\necho \"\"\necho \"================================\"\necho \"Summary:\"\nif [ -f \"$TRAVEL_CARD_FILE\" ]; then\n echo \"✅ Travel Assistant agent card saved\"\nfi\nif [ -f \"$BOOKING_CARD_FILE\" ]; then\n echo \"✅ Flight Booking agent card saved\"\nfi\necho \"================================\"\n" }, { "path": "agents/a2a/test/flight_booking_agent_card.json", "content": "{\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\n \"text\"\n ],\n \"defaultOutputModes\": [\n \"text\"\n ],\n \"description\": \"Flight booking and reservation management agent\",\n \"name\": \"Flight Booking Agent\",\n \"preferredTransport\": \"JSONRPC\",\n \"protocolVersion\": \"0.3.0\",\n \"skills\": [\n {\n \"description\": \"Check seat availability for a specific flight.\",\n \"id\": \"check_availability\",\n \"name\": \"check_availability\",\n \"tags\": []\n },\n {\n \"description\": \"Reserve seats on a flight for passengers.\",\n \"id\": \"reserve_flight\",\n \"name\": \"reserve_flight\",\n \"tags\": []\n },\n {\n \"description\": \"Confirm and finalize a flight booking.\",\n \"id\": \"confirm_booking\",\n \"name\": \"confirm_booking\",\n \"tags\": []\n },\n {\n \"description\": \"Process payment for a booking (simulated).\",\n \"id\": \"process_payment\",\n \"name\": \"process_payment\",\n \"tags\": []\n },\n {\n \"description\": \"Update, view, or cancel existing reservations.\",\n \"id\": \"manage_reservation\",\n \"name\": \"manage_reservation\",\n \"tags\": []\n }\n ],\n \"url\": \"http://flight-booking-agent:9000/\",\n \"version\": \"0.0.1\"\n}\n" }, { "path": "agents/a2a/test/simple_agents_test.py", "content": "#!/usr/bin/env python3\n\"\"\"\nTest script for Travel Assistant and Flight Booking agents\nUsage: python simple_agents_test.py --endpoint local|live [--debug]\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport sys\nimport time\nimport uuid\nfrom typing import (\n Any,\n)\n\nimport boto3\nimport requests\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n# Endpoint configurations\nLOCAL_ENDPOINTS = {\n \"travel_assistant\": \"http://localhost:9001\",\n \"flight_booking\": \"http://localhost:9002\",\n}\n\nLIVE_ENDPOINTS = {\n \"travel_assistant\": \"travel_assistant_agent ARN\",\n \"flight_booking\": \"flight_booking_agent ARN\",\n}\n\nAWS_REGION = \"us-east-1\"\n\n\nclass AgentTester:\n \"\"\"Agent testing class for both local and live endpoints.\"\"\"\n\n def __init__(\n self,\n endpoints: dict[str, str],\n is_live: bool = False,\n ) -> None:\n self.endpoints = endpoints\n self.is_live = is_live\n if is_live:\n self.bedrock_client = boto3.client(\"bedrock-agentcore\", region_name=AWS_REGION)\n\n def send_agent_message(\n self,\n agent_type: str,\n message: str,\n ) -> dict[str, Any]:\n \"\"\"Send message to agent using A2A protocol (local) or boto3 (live).\"\"\"\n endpoint = self.endpoints[agent_type]\n if not endpoint:\n raise ValueError(f\"No endpoint configured for {agent_type}\")\n\n request_id = f\"test-{uuid.uuid4().hex[:8]}\"\n message_id = f\"test-msg-{uuid.uuid4().hex[:8]}\"\n timestamp = time.time()\n\n if self.is_live:\n # Use boto3 for AgentCore Runtime\n return self._invoke_agentcore_runtime(\n endpoint, message, request_id, message_id, timestamp\n )\n else:\n # Use HTTP for local A2A\n payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": request_id,\n \"method\": \"message/send\",\n \"params\": {\n \"message\": {\n \"role\": \"user\",\n \"parts\": [{\"kind\": \"text\", \"text\": message}],\n \"messageId\": message_id,\n }\n },\n }\n\n logger.debug(f\"[REQUEST] Agent: {agent_type}, Endpoint: {endpoint}\")\n logger.debug(f\"[REQUEST] ID: {request_id}, Message ID: {message_id}\")\n logger.debug(f\"[REQUEST] Payload:\\n{json.dumps(payload, indent=2)}\")\n\n start_time = time.time()\n response = requests.post(\n endpoint, json=payload, headers={\"Content-Type\": \"application/json\"}, timeout=60\n )\n response_time = time.time() - start_time\n\n response_json = response.json()\n logger.debug(f\"[RESPONSE] Time: {response_time:.3f}s, Status: {response.status_code}\")\n logger.debug(f\"[RESPONSE] Body:\\n{json.dumps(response_json, indent=2, default=str)}\")\n\n return response_json\n\n def _invoke_agentcore_runtime(\n self,\n runtime_arn: str,\n message: str,\n request_id: str,\n message_id: str,\n timestamp: float,\n ) -> dict[str, Any]:\n \"\"\"Invoke AgentCore Runtime using boto3.\"\"\"\n # A2A protocol requires JSON-RPC format\n payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": request_id,\n \"method\": \"message/send\",\n \"params\": {\n \"message\": {\n \"role\": \"user\",\n \"parts\": [{\"kind\": \"text\", \"text\": message}],\n \"messageId\": message_id,\n }\n },\n }\n payload_json = json.dumps(payload)\n\n logger.debug(f\"[AGENTCORE REQUEST] ARN: {runtime_arn}\")\n logger.debug(f\"[AGENTCORE REQUEST] ID: {request_id}, Message ID: {message_id}\")\n logger.debug(f\"[AGENTCORE REQUEST] Payload:\\n{json.dumps(payload, indent=2)}\")\n\n # Generate session ID (must be 33+ characters)\n session_id = f\"test-session-{uuid.uuid4().hex}\"\n logger.debug(f\"[AGENTCORE REQUEST] Session ID: {session_id}\")\n\n try:\n start_time = time.time()\n response = self.bedrock_client.invoke_agent_runtime(\n agentRuntimeArn=runtime_arn,\n runtimeSessionId=session_id,\n qualifier=\"DEFAULT\",\n payload=payload_json,\n )\n response_time = time.time() - start_time\n\n # Read streaming response\n if \"response\" in response:\n streaming_body = response[\"response\"]\n all_lines = []\n\n for line in streaming_body.iter_lines():\n line_str = line.decode(\"utf-8\")\n all_lines.append(line_str)\n logger.debug(f\"[AGENTCORE STREAM] Line: {line_str}\")\n\n # The response is a single JSON-RPC response line\n if all_lines:\n try:\n json_response = json.loads(all_lines[0])\n\n logger.debug(f\"[AGENTCORE RESPONSE] Time: {response_time:.3f}s\")\n logger.debug(\n f\"[AGENTCORE RESPONSE] Body:\\n{json.dumps(json_response, indent=2, default=str)}\"\n )\n\n # Check for JSON-RPC error\n if \"error\" in json_response:\n return {\"error\": json_response[\"error\"]}\n\n # Return the JSON-RPC result directly\n return json_response\n\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to parse response: {e}\")\n return {\"error\": f\"Failed to parse response: {e}\"}\n\n return {\"error\": \"Empty response\"}\n\n return {\"error\": \"No response content\"}\n\n except Exception as e:\n logger.error(f\"AgentCore invocation failed: {e}\")\n return {\"error\": str(e)}\n\n def call_api_endpoint(\n self,\n agent_type: str,\n endpoint: str,\n method: str = \"POST\",\n **params,\n ) -> dict[str, Any]:\n \"\"\"Call direct API endpoint (only works for local).\"\"\"\n if self.is_live:\n raise NotImplementedError(\n \"Direct API endpoints not available for live AgentCore Runtime\"\n )\n\n url = f\"{self.endpoints[agent_type]}{endpoint}\"\n if not self.endpoints[agent_type]:\n raise ValueError(f\"No endpoint configured for {agent_type}\")\n\n logger.debug(f\"[API REQUEST] Agent: {agent_type}, URL: {url}\")\n logger.debug(f\"[API REQUEST] Method: {method}, Params: {params}\")\n\n start_time = time.time()\n if method.upper() == \"GET\":\n response = requests.get(url, params=params, timeout=60)\n else:\n response = requests.post(url, params=params, timeout=60)\n response_time = time.time() - start_time\n\n response_json = response.json()\n logger.debug(f\"[API RESPONSE] Time: {response_time:.3f}s, Status: {response.status_code}\")\n logger.debug(f\"[API RESPONSE] Body:\\n{json.dumps(response_json, indent=2, default=str)}\")\n\n return response_json\n\n def ping_agent(\n self,\n agent_type: str,\n ) -> bool:\n \"\"\"Check if agent is healthy (only works for local).\"\"\"\n if self.is_live:\n # For live, we can't ping directly, assume healthy if ARN is configured\n return bool(self.endpoints.get(agent_type))\n\n try:\n url = f\"{self.endpoints[agent_type]}/ping\"\n logger.debug(f\"[PING] Agent: {agent_type}, URL: {url}\")\n\n start_time = time.time()\n response = requests.get(url, timeout=5)\n response_time = time.time() - start_time\n\n is_healthy = response.status_code == 200 and response.json().get(\"status\") == \"healthy\"\n logger.debug(f\"[PING RESPONSE] Time: {response_time:.3f}s, Healthy: {is_healthy}\")\n\n return is_healthy\n except Exception as e:\n logger.debug(f\"[PING ERROR] Agent: {agent_type}, Error: {e}\")\n return False\n\n\nclass TravelAssistantTests:\n \"\"\"Test suite for Travel Assistant agent.\"\"\"\n\n def __init__(\n self,\n tester: AgentTester,\n ) -> None:\n self.tester = tester\n self.agent_type = \"travel_assistant\"\n\n def test_ping(self) -> None:\n \"\"\"Test agent health check.\"\"\"\n print(\"Testing Travel Assistant ping...\")\n result = self.tester.ping_agent(self.agent_type)\n assert result, \"Travel Assistant ping failed\"\n print(\"✓ Travel Assistant is healthy\")\n\n def test_agent_flight_search(self) -> None:\n \"\"\"Test agent flight search via A2A.\"\"\"\n print(\"Testing Travel Assistant flight search...\")\n message = \"Search for flights from SF to NY on 2025-11-15\"\n response = self.tester.send_agent_message(self.agent_type, message)\n\n assert \"result\" in response, f\"No result in response: {response}\"\n assert \"artifacts\" in response[\"result\"], \"No artifacts in response\"\n\n # Check if agent found flights\n artifacts = response[\"result\"][\"artifacts\"]\n assert len(artifacts) > 0, \"No artifacts returned\"\n\n # Extract text from artifact parts\n response_text = \"\"\n for artifact in artifacts:\n if \"parts\" in artifact:\n for part in artifact[\"parts\"]:\n if \"text\" in part:\n response_text += part[\"text\"]\n\n assert \"flight\" in response_text.lower(), (\n f\"Response doesn't mention flights. Got: {response_text[:100]}\"\n )\n print(\"✓ Travel Assistant flight search working\")\n\n def test_api_search_flights(self) -> None:\n \"\"\"Test direct API endpoint (local only).\"\"\"\n if self.tester.is_live:\n print(\n \"Skipping /api/search-flights endpoint (only available in local Docker container)\"\n )\n return\n\n print(\"Testing Travel Assistant API endpoint...\")\n response = self.tester.call_api_endpoint(\n self.agent_type,\n \"/api/search-flights\",\n departure_city=\"SF\",\n arrival_city=\"NY\",\n departure_date=\"2025-11-15\",\n )\n\n assert \"result\" in response, f\"No result in API response: {response}\"\n result_data = json.loads(response[\"result\"])\n assert \"flights\" in result_data, \"No flights in API response\"\n assert len(result_data[\"flights\"]) > 0, \"No flights found\"\n print(\"✓ Travel Assistant API endpoint working\")\n\n def test_api_recommendations(self) -> None:\n \"\"\"Test recommendations API (local only).\"\"\"\n if self.tester.is_live:\n print(\n \"Skipping /api/recommendations endpoint (only available in local Docker container)\"\n )\n return\n\n print(\"Testing Travel Assistant recommendations...\")\n response = self.tester.call_api_endpoint(\n self.agent_type,\n \"/api/recommendations\",\n method=\"GET\",\n max_price=300,\n preferred_airlines=\"United,Delta\",\n )\n\n assert \"result\" in response, \"No result in recommendations response\"\n result_data = json.loads(response[\"result\"])\n assert \"recommendations\" in result_data, \"No recommendations in response\"\n print(\"✓ Travel Assistant recommendations working\")\n\n\nclass FlightBookingTests:\n \"\"\"Test suite for Flight Booking agent.\"\"\"\n\n def __init__(\n self,\n tester: AgentTester,\n ) -> None:\n self.tester = tester\n self.agent_type = \"flight_booking\"\n\n def test_ping(self) -> None:\n \"\"\"Test agent health check.\"\"\"\n print(\"Testing Flight Booking ping...\")\n result = self.tester.ping_agent(self.agent_type)\n assert result, \"Flight Booking ping failed\"\n print(\"✓ Flight Booking is healthy\")\n\n def test_agent_availability_check(self) -> None:\n \"\"\"Test agent availability check via A2A.\"\"\"\n print(\"Testing Flight Booking availability check...\")\n message = \"Check availability for flight ID 1\"\n response = self.tester.send_agent_message(self.agent_type, message)\n\n assert \"result\" in response, f\"No result in response: {response}\"\n assert \"artifacts\" in response[\"result\"], \"No artifacts in response\"\n\n artifacts = response[\"result\"][\"artifacts\"]\n assert len(artifacts) > 0, \"No artifacts returned\"\n\n response_text = artifacts[0][\"parts\"][0][\"text\"]\n assert \"available\" in response_text.lower(), \"Response doesn't mention availability\"\n print(\"✓ Flight Booking availability check working\")\n\n def test_agent_booking(self) -> None:\n \"\"\"Test agent booking via A2A.\"\"\"\n print(\"Testing Flight Booking reservation...\")\n message = \"Book flight ID 1 for Jane Smith, email jane@test.com\"\n response = self.tester.send_agent_message(self.agent_type, message)\n\n assert \"result\" in response, f\"No result in response: {response}\"\n artifacts = response[\"result\"][\"artifacts\"]\n response_text = artifacts[0][\"parts\"][0][\"text\"]\n\n assert \"booking\" in response_text.lower() or \"reserved\" in response_text.lower(), (\n \"Response doesn't mention booking/reservation\"\n )\n print(\"✓ Flight Booking reservation working\")\n\n def test_api_check_availability(self) -> None:\n \"\"\"Test direct API endpoint (local only).\"\"\"\n if self.tester.is_live:\n print(\n \"Skipping /api/check-availability endpoint (only available in local Docker container)\"\n )\n return\n\n print(\"Testing Flight Booking API endpoint...\")\n response = self.tester.call_api_endpoint(\n self.agent_type, \"/api/check-availability\", flight_id=1\n )\n\n assert \"result\" in response, f\"No result in API response: {response}\"\n result_data = json.loads(response[\"result\"])\n assert \"flight_id\" in result_data, \"No flight_id in API response\"\n assert \"available_seats\" in result_data, \"No available_seats in response\"\n print(\"✓ Flight Booking API endpoint working\")\n\n\nclass AgentDiscoveryTests:\n \"\"\"Test suite for cross-agent discovery via the MCP Gateway Registry.\n\n Tests the full flow: Travel Assistant discovers Flight Booking agent\n through the registry's semantic search API and delegates a booking task.\n Requires the MCP Gateway Registry to be running and the Flight Booking\n agent to be registered in it.\n \"\"\"\n\n def __init__(\n self,\n tester: AgentTester,\n registry_url: str = \"http://localhost\",\n ) -> None:\n self.tester = tester\n self.registry_url = registry_url\n\n def _is_registry_available(self) -> bool:\n \"\"\"Check if the MCP Gateway Registry is reachable.\"\"\"\n try:\n response = requests.get(f\"{self.registry_url}/health\", timeout=5)\n return response.status_code == 200\n except Exception:\n return False\n\n def test_discover_and_delegate_booking(self) -> None:\n \"\"\"Test Travel Assistant discovering Flight Booking agent and delegating a booking.\n\n Flow:\n 1. Send booking request to Travel Assistant\n 2. Travel Assistant calls discover_remote_agents() to find booking agents\n 3. Travel Assistant calls invoke_remote_agent() to delegate to Flight Booking\n 4. Flight Booking processes the request and returns confirmation\n 5. Travel Assistant returns combined response\n \"\"\"\n if not self._is_registry_available():\n print(\n f\" Skipping: registry not available at {self.registry_url}. \"\n \"Start the registry and register the Flight Booking agent to run this test.\"\n )\n return\n\n print(\"Testing cross-agent discovery and delegation flow...\")\n\n # This message explicitly instructs the LLM to use discovery tools\n message = (\n \"I need to book a flight. Please use the discover_remote_agents tool to find \"\n \"agents that can handle flight bookings, then use invoke_remote_agent to ask \"\n \"that agent to book flight ID 1 for John Smith with email john@test.com\"\n )\n\n logger.debug(\"[DISCOVERY TEST] Sending booking request to Travel Assistant...\")\n response = self.tester.send_agent_message(\"travel_assistant\", message)\n\n assert \"result\" in response, f\"No result in discovery response: {response}\"\n assert \"artifacts\" in response[\"result\"], \"No artifacts in discovery response\"\n\n # Extract text from all artifact parts\n artifacts = response[\"result\"][\"artifacts\"]\n assert len(artifacts) > 0, \"No artifacts returned from discovery flow\"\n\n response_text = \"\"\n for artifact in artifacts:\n if \"parts\" in artifact:\n for part in artifact[\"parts\"]:\n if \"text\" in part:\n response_text += part[\"text\"]\n\n logger.debug(f\"[DISCOVERY TEST] Full response text:\\n{response_text}\")\n\n response_lower = response_text.lower()\n\n # Verify the response indicates discovery happened\n discovery_keywords = [\"discover\", \"found\", \"flight booking\", \"remote agent\", \"cached\"]\n has_discovery = any(keyword in response_lower for keyword in discovery_keywords)\n\n # Verify the response indicates a booking was attempted or completed\n booking_keywords = [\"book\", \"reserv\", \"confirm\", \"john smith\"]\n has_booking = any(keyword in response_lower for keyword in booking_keywords)\n\n assert has_discovery or has_booking, (\n f\"Response doesn't indicate discovery or booking happened. Got: {response_text[:300]}\"\n )\n\n if has_discovery:\n print(\" [OK] Discovery indicators found in response\")\n if has_booking:\n print(\" [OK] Booking indicators found in response\")\n\n print(\"[PASS] Cross-agent discovery and delegation flow working\")\n\n\ndef run_tests(\n endpoint_type: str,\n skip_discovery: bool = False,\n registry_url: str = \"http://localhost\",\n) -> bool:\n \"\"\"Run all tests for specified endpoint type.\"\"\"\n print(f\"Running tests against {endpoint_type} endpoints...\")\n print(\"=\" * 50)\n\n # Select endpoints\n endpoints = LOCAL_ENDPOINTS if endpoint_type == \"local\" else LIVE_ENDPOINTS\n\n # Check if endpoints are configured\n for agent, url in endpoints.items():\n if not url:\n print(f\"❌ No {endpoint_type} endpoint configured for {agent}\")\n return False\n\n is_live = endpoint_type == \"live\"\n tester = AgentTester(endpoints, is_live=is_live)\n\n try:\n # Test Travel Assistant\n print(\"\\nTesting Travel Assistant Agent\")\n print(\"-\" * 30)\n travel_tests = TravelAssistantTests(tester)\n travel_tests.test_ping()\n travel_tests.test_agent_flight_search()\n travel_tests.test_api_search_flights()\n travel_tests.test_api_recommendations()\n\n # Test Flight Booking\n print(\"\\nTesting Flight Booking Agent\")\n print(\"-\" * 30)\n booking_tests = FlightBookingTests(tester)\n booking_tests.test_ping()\n booking_tests.test_agent_availability_check()\n booking_tests.test_agent_booking()\n booking_tests.test_api_check_availability()\n\n # Test Agent-to-Agent Discovery\n if not skip_discovery:\n print(\"\\nTesting Agent-to-Agent Discovery\")\n print(\"-\" * 30)\n discovery_tests = AgentDiscoveryTests(tester, registry_url=registry_url)\n discovery_tests.test_discover_and_delegate_booking()\n else:\n print(\"\\nSkipping Agent-to-Agent Discovery tests (--skip-discovery flag set)\")\n\n print(\"\\n\" + \"=\" * 50)\n print(\"All tests passed!\")\n return True\n\n except Exception as e:\n logger.exception(\"Test failed with exception\")\n print(f\"\\n❌ Test failed: {e}\")\n return False\n\n\ndef main() -> None:\n \"\"\"Main entry point for test script.\"\"\"\n parser = argparse.ArgumentParser(description=\"Test Travel Assistant and Flight Booking agents\")\n parser.add_argument(\n \"--endpoint\",\n choices=[\"local\", \"live\"],\n required=True,\n help=\"Test against local or live endpoints\",\n )\n parser.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable debug logging to see detailed request/response traces\",\n )\n parser.add_argument(\n \"--verbose\",\n action=\"store_true\",\n help=\"Alias for --debug, enables debug logging\",\n )\n parser.add_argument(\n \"--skip-discovery\",\n action=\"store_true\",\n help=\"Skip agent-to-agent discovery tests (requires registry running)\",\n )\n parser.add_argument(\n \"--registry-url\",\n default=\"http://localhost\",\n help=\"MCP Gateway Registry URL for discovery tests (default: http://localhost)\",\n )\n\n args = parser.parse_args()\n\n # Enable debug logging if requested\n if args.debug or args.verbose:\n logging.getLogger().setLevel(logging.DEBUG)\n logger.info(\"Debug logging enabled - detailed traces will be shown\")\n\n success = run_tests(\n endpoint_type=args.endpoint,\n skip_discovery=args.skip_discovery,\n registry_url=args.registry_url,\n )\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "agents/a2a/test/travel_assistant_agent_card.json", "content": "{\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\n \"text\"\n ],\n \"defaultOutputModes\": [\n \"text\"\n ],\n \"description\": \"Flight search and trip planning agent with dynamic agent discovery\",\n \"name\": \"Travel Assistant Agent\",\n \"preferredTransport\": \"JSONRPC\",\n \"protocolVersion\": \"0.3.0\",\n \"skills\": [\n {\n \"description\": \"Search for available flights between cities on a specific date.\",\n \"id\": \"search_flights\",\n \"name\": \"search_flights\",\n \"tags\": []\n },\n {\n \"description\": \"Get pricing and seat availability for a specific flight.\",\n \"id\": \"check_prices\",\n \"name\": \"check_prices\",\n \"tags\": []\n },\n {\n \"description\": \"Get flight recommendations based on customer preferences.\",\n \"id\": \"get_recommendations\",\n \"name\": \"get_recommendations\",\n \"tags\": []\n },\n {\n \"description\": \"Create and save a trip planning record.\",\n \"id\": \"create_trip_plan\",\n \"name\": \"create_trip_plan\",\n \"tags\": []\n },\n {\n \"description\": \"Discover remote agents from the mcp-registry with natural language query.\\nCache them for visibility and invocation for later tool calls from LLM\",\n \"id\": \"discover_remote_agents\",\n \"name\": \"discover_remote_agents\",\n \"tags\": []\n },\n {\n \"description\": \"View all cached remote agents available for invocation.\",\n \"id\": \"view_cached_remote_agents\",\n \"name\": \"view_cached_remote_agents\",\n \"tags\": []\n },\n {\n \"description\": \"Invoke a cached remote agent by ID with a natural language message.\",\n \"id\": \"invoke_remote_agent\",\n \"name\": \"invoke_remote_agent\",\n \"tags\": []\n }\n ],\n \"url\": \"http://travel-assistant-agent:9000/\",\n \"version\": \"0.0.1\"\n}\n" }, { "path": "agents/agent.py", "content": "#!/usr/bin/env python3\n\"\"\"\nInteractive LangGraph Agent with Registry Tool Discovery\n\nThis agent discovers and invokes MCP tools using semantic search on the registry.\nIt supports multi-turn conversation and maintains conversation history.\n\nAuthentication:\n The agent requires a JWT token for authenticating with the MCP Registry.\n The token can be obtained from different sources depending on your setup.\n\nUsage Examples:\n # Using token from api/.token file (simple cat):\n python agents/agent.py \\\n --mcp-registry-url https://mcpgateway.ddns.net/mcpgw/mcp \\\n --jwt-token \"$(cat api/.token)\" \\\n --provider bedrock \\\n --prompt \"What time is it in New York?\"\n\n # Using token from .oauth-tokens/ingress.json (requires jq):\n python agents/agent.py \\\n --mcp-registry-url https://mcpgateway.ddns.net/mcpgw/mcp \\\n --jwt-token \"$(jq -r '.access_token' .oauth-tokens/ingress.json)\" \\\n --provider bedrock \\\n --prompt \"What time is it in New York?\"\n\n # Interactive mode for multi-turn conversations:\n python agents/agent.py \\\n --mcp-registry-url https://mcpgateway.ddns.net/mcpgw/mcp \\\n --jwt-token \"$(cat api/.token)\" \\\n --provider bedrock \\\n --interactive\n\n # With verbose logging for debugging:\n python agents/agent.py \\\n --mcp-registry-url https://mcpgateway.ddns.net/mcpgw/mcp \\\n --jwt-token \"$(cat api/.token)\" \\\n --provider bedrock \\\n --prompt \"What time is it in New York?\" \\\n --verbose\n\nAvailable Tools:\n - calculator: For mathematical calculations\n - search_registry_tools: Discover MCP tools via semantic search\n - invoke_mcp_tool: Invoke discovered tools on MCP servers\n\nEnvironment Variables:\n - ANTHROPIC_API_KEY: Required when using --provider anthropic\n\"\"\"\n\nimport argparse\nimport ast\nimport asyncio\nimport json\nimport logging\nimport operator as _operator\nimport os\nimport re\nimport sys\nimport threading\nimport time\nfrom datetime import (\n UTC,\n datetime,\n)\nfrom typing import (\n Any,\n)\nfrom urllib.parse import (\n urljoin,\n urlparse,\n)\n\nimport httpx\nimport mcp\nimport yaml\nfrom langchain_anthropic import ChatAnthropic\nfrom langchain_aws import ChatBedrock\nfrom langchain_core.tools import tool\nfrom langgraph.prebuilt import create_react_agent\nfrom mcp.client.sse import sse_client\nfrom mcp.client.streamable_http import streamable_http_client\nfrom registry_client import (\n RegistryClient,\n _format_tool_result,\n)\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\n# Get logger\nlogger = logging.getLogger(__name__)\n\n# Global registry client instance (initialized in main)\nregistry_client: RegistryClient | None = None\n\n\nclass ProgressSpinner:\n \"\"\"Simple progress spinner for showing activity during operations.\"\"\"\n\n SPINNER_CHARS = [\"⠋\", \"⠙\", \"⠹\", \"⠸\", \"⠼\", \"⠴\", \"⠦\", \"⠧\", \"⠇\", \"⠏\"]\n\n def __init__(self):\n self._stop_event = threading.Event()\n self._thread: threading.Thread | None = None\n\n def _spin(self) -> None:\n idx = 0\n while not self._stop_event.is_set():\n char = self.SPINNER_CHARS[idx % len(self.SPINNER_CHARS)]\n sys.stdout.write(f\"\\r{char}\")\n sys.stdout.flush()\n idx += 1\n time.sleep(0.1)\n\n def start(self) -> \"ProgressSpinner\":\n self._stop_event.clear()\n self._thread = threading.Thread(target=self._spin, daemon=True)\n self._thread.start()\n return self\n\n def stop(\n self,\n final_message: str = None,\n ) -> None:\n self._stop_event.set()\n if self._thread:\n self._thread.join(timeout=0.5)\n # Clear the spinner character\n sys.stdout.write(\"\\r \\r\")\n sys.stdout.flush()\n if final_message:\n print(f\" {final_message}\")\n\n\ndef print_step(\n step: str,\n icon: str = \"->\",\n) -> None:\n \"\"\"Print a step indicator.\"\"\"\n print(f\" {icon} {step}\")\n\n\ndef load_server_config(config_file: str = \"server_config.yml\") -> dict[str, Any]:\n \"\"\"\n Load server configuration from YAML file.\n\n Args:\n config_file: Path to the configuration file\n\n Returns:\n Dict containing server configurations\n \"\"\"\n try:\n # Try to find config file in the same directory as this script\n config_path = os.path.join(os.path.dirname(__file__), config_file)\n if not os.path.exists(config_path):\n # Try current working directory\n config_path = config_file\n if not os.path.exists(config_path):\n logger.warning(\n f\"Server config file not found: {config_file}. Using default configuration.\"\n )\n return {\"servers\": {}}\n\n with open(config_path) as f:\n config = yaml.safe_load(f)\n logger.info(f\"Loaded server config from: {config_path}\")\n return config or {\"servers\": {}}\n except Exception as e:\n logger.warning(f\"Failed to load server config: {e}. Using default configuration.\")\n return {\"servers\": {}}\n\n\ndef resolve_env_vars(value: str, server_name: str = None) -> str:\n \"\"\"\n Resolve environment variable references in a string.\n Supports ${VAR_NAME} syntax.\n\n Args:\n value: String that may contain environment variable references\n server_name: Name of the server (for error context)\n\n Returns:\n String with environment variables resolved\n\n Raises:\n ValueError: If a required environment variable is not found\n \"\"\"\n import re\n\n missing_vars = []\n\n def replace_env_var(match):\n var_name = match.group(1)\n env_value = os.environ.get(var_name)\n if env_value is None:\n missing_vars.append(var_name)\n return match.group(0) # Return original if not found\n return env_value\n\n # Find all ${VAR_NAME} patterns and replace them\n pattern = r\"\\$\\{([^}]+)\\}\"\n resolved_value = re.sub(pattern, replace_env_var, value)\n\n # If any environment variables were missing, raise an error\n if missing_vars:\n server_context = f\" for server '{server_name}'\" if server_name else \"\"\n missing_list = \"', '\".join(missing_vars)\n raise ValueError(\n f\"Missing required environment variable(s): '{missing_list}'{server_context}. \"\n f\"Please set these environment variables and try again.\"\n )\n\n return resolved_value\n\n\ndef get_server_headers(server_name: str, config: dict[str, Any]) -> dict[str, str]:\n \"\"\"\n Get server-specific headers from configuration with environment variable resolution.\n\n Args:\n server_name: Name of the server (e.g., 'sre-gateway', 'atlassian')\n config: Loaded server configuration\n\n Returns:\n Dictionary of headers for the server\n\n Raises:\n ValueError: If required environment variables for the server are missing\n \"\"\"\n servers = config.get(\"servers\", {})\n server_config = servers.get(server_name, {})\n raw_headers = server_config.get(\"headers\", {})\n\n if not raw_headers:\n logger.debug(f\"No custom headers configured for server '{server_name}'\")\n return {}\n\n # Resolve environment variables in header values\n resolved_headers = {}\n try:\n for header_name, header_value in raw_headers.items():\n resolved_value = resolve_env_vars(header_value, server_name)\n if resolved_value != header_value:\n logger.debug(f\"Resolved header {header_name} for server {server_name}\")\n resolved_headers[header_name] = resolved_value\n\n logger.info(f\"Applied {len(resolved_headers)} custom headers for server '{server_name}'\")\n return resolved_headers\n\n except ValueError as e:\n # Re-raise with additional context about which server failed\n logger.error(f\"Failed to configure headers for server '{server_name}': {e}\")\n raise\n\n\ndef enable_verbose_logging():\n \"\"\"Enable verbose debug logging for HTTP libraries and main logger.\"\"\"\n # Set main logger to DEBUG level\n logger.setLevel(logging.DEBUG)\n\n # Enable debug logging for httpx to see request/response details\n httpx_logger = logging.getLogger(\"httpx\")\n httpx_logger.setLevel(logging.DEBUG)\n httpx_logger.propagate = True\n\n # Enable debug logging for httpcore (underlying HTTP library)\n httpcore_logger = logging.getLogger(\"httpcore\")\n httpcore_logger.setLevel(logging.DEBUG)\n httpcore_logger.propagate = True\n\n # Enable debug logging for mcp client libraries\n mcp_logger = logging.getLogger(\"mcp\")\n mcp_logger.setLevel(logging.DEBUG)\n mcp_logger.propagate = True\n\n logger.info(\"Verbose logging enabled for httpx, httpcore, mcp libraries, and main logger\")\n\n\ndef parse_arguments() -> argparse.Namespace:\n \"\"\"\n Parse command line arguments for the Interactive LangGraph Agent.\n\n Returns:\n argparse.Namespace: The parsed command line arguments\n \"\"\"\n parser = argparse.ArgumentParser(\n description=\"Interactive LangGraph Agent with Registry Tool Discovery\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Using token from api/.token file:\n python agents/agent.py --jwt-token \"$(cat api/.token)\" --prompt \"What time is it?\"\n\n # Using token from .oauth-tokens/ingress.json:\n python agents/agent.py --jwt-token \"$(jq -r '.access_token' .oauth-tokens/ingress.json)\" --prompt \"What time is it?\"\n\n # Interactive mode:\n python agents/agent.py --jwt-token \"$(cat api/.token)\" --interactive\n\"\"\",\n )\n\n # Server connection arguments\n parser.add_argument(\n \"--mcp-registry-url\",\n type=str,\n default=\"https://mcpgateway.ddns.net/mcpgw/mcp\",\n help=\"URL of the MCP Registry (default: https://mcpgateway.ddns.net/mcpgw/mcp)\",\n )\n\n # Authentication - JWT token required\n parser.add_argument(\n \"--jwt-token\",\n type=str,\n required=True,\n help=\"JWT token for authentication (required)\",\n )\n\n # Model and provider arguments\n parser.add_argument(\n \"--provider\",\n type=str,\n choices=[\"anthropic\", \"bedrock\"],\n default=\"bedrock\",\n help=\"Model provider to use (default: bedrock)\",\n )\n parser.add_argument(\n \"--model\",\n type=str,\n default=\"us.anthropic.claude-3-7-sonnet-20250219-v1:0\",\n help=\"Model ID to use\",\n )\n\n # Prompt arguments\n parser.add_argument(\n \"--prompt\",\n type=str,\n default=None,\n help=\"Initial prompt to send to the agent\",\n )\n\n # Interactive mode argument\n parser.add_argument(\n \"--interactive\",\n \"-i\",\n action=\"store_true\",\n help=\"Enable interactive mode for multi-turn conversations\",\n )\n\n # Verbose logging argument\n parser.add_argument(\n \"--verbose\",\n \"-v\",\n action=\"store_true\",\n help=\"Enable verbose HTTP debugging output\",\n )\n\n args = parser.parse_args()\n\n # Enable verbose logging if requested\n if args.verbose:\n enable_verbose_logging()\n\n return args\n\n\n_SAFE_OPERATORS: dict = {\n ast.Add: _operator.add,\n ast.Sub: _operator.sub,\n ast.Mult: _operator.mul,\n ast.Div: _operator.truediv,\n ast.Pow: _operator.pow,\n ast.FloorDiv: _operator.floordiv,\n ast.Mod: _operator.mod,\n}\n\n_SAFE_UNARY_OPERATORS: dict = {\n ast.UAdd: _operator.pos,\n ast.USub: _operator.neg,\n}\n\n\ndef _safe_eval_arithmetic(expression: str) -> int | float:\n \"\"\"Safely evaluate an arithmetic expression using AST node whitelisting.\n\n Only numeric literals and basic arithmetic operators are permitted.\n Function calls, attribute access, names, and all other non-arithmetic\n constructs raise ValueError immediately.\n\n Args:\n expression: A pre-validated arithmetic expression string.\n\n Returns:\n The numeric result of the expression.\n\n Raises:\n ValueError: If the expression contains unsupported operations.\n ZeroDivisionError: If the expression divides by zero.\n \"\"\"\n\n def _eval_node(node: ast.AST) -> int | float:\n if isinstance(node, ast.Expression):\n return _eval_node(node.body)\n if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):\n return node.value\n if isinstance(node, ast.BinOp):\n op_func = _SAFE_OPERATORS.get(type(node.op))\n if op_func is None:\n raise ValueError(f\"Unsupported operator: {type(node.op).__name__}\")\n\n # Special handling for exponentiation to prevent DoS\n if isinstance(node.op, ast.Pow):\n left_val = _eval_node(node.left)\n right_val = _eval_node(node.right)\n if abs(right_val) > 100:\n raise ValueError(\"Exponent too large (max 100)\")\n return op_func(left_val, right_val)\n\n return op_func(_eval_node(node.left), _eval_node(node.right))\n if isinstance(node, ast.UnaryOp):\n op_func = _SAFE_UNARY_OPERATORS.get(type(node.op))\n if op_func is None:\n raise ValueError(f\"Unsupported unary operator: {type(node.op).__name__}\")\n return op_func(_eval_node(node.operand))\n raise ValueError(f\"Unsupported expression type: {type(node).__name__}\")\n\n tree = ast.parse(expression, mode=\"eval\")\n return _eval_node(tree)\n\n\n@tool\ndef calculator(expression: str) -> str:\n \"\"\"\n Evaluate a mathematical expression and return the result.\n\n This tool can perform basic arithmetic operations like addition, subtraction,\n multiplication, division, and exponentiation.\n\n Args:\n expression (str): The mathematical expression to evaluate (e.g., \"2 + 2\", \"5 * 10\", \"(3 + 4) / 2\")\n\n Returns:\n str: The result of the evaluation as a string\n\n Example:\n calculator(\"2 + 2\") -> \"4\"\n calculator(\"5 * 10\") -> \"50\"\n calculator(\"(3 + 4) / 2\") -> \"3.5\"\n \"\"\"\n # Security check: only allow basic arithmetic operations and numbers\n # Remove all whitespace\n expression = expression.replace(\" \", \"\")\n\n # Guard against excessively long expressions (DoS via large exponents)\n if len(expression) > 200:\n return \"Error: Expression too long (max 200 characters).\"\n\n # Check if the expression contains only allowed characters\n if not re.match(r\"^[0-9+\\-*/().^ ]+$\", expression):\n return \"Error: Only basic arithmetic operations (+, -, *, /, ^, (), .) are allowed.\"\n\n try:\n # Replace ^ with ** for exponentiation\n expression = expression.replace(\"^\", \"**\")\n\n # Safely evaluate using AST node whitelisting (no arbitrary code execution)\n result = _safe_eval_arithmetic(expression)\n return str(result)\n except Exception as e:\n return f\"Error evaluating expression: {str(e)}\"\n\n\n@tool\nasync def search_registry_tools(\n query: str,\n max_results: int = 10,\n) -> str:\n \"\"\"\n Search for MCP tools using semantic search on the registry.\n\n Use this tool to discover available MCP tools that can help accomplish a task.\n The search uses natural language understanding to find the most relevant tools.\n\n Args:\n query (str): Natural language description of the capability you need\n (e.g., \"get current time\", \"search jira issues\", \"manage files\")\n max_results (int): Maximum number of results to return (default: 10)\n\n Returns:\n str: JSON string containing matching tools with their details including:\n - tool_name: Name of the tool\n - server_path: Path to invoke the tool on\n - server_name: Human-readable server name\n - description: What the tool does\n - relevance_score: How well it matches your query (0-1)\n - supported_transports: Transport protocols supported\n - auth_provider: Authentication provider if needed\n - tool_schema: Input parameters for the tool\n\n Example:\n search_registry_tools(\"get the current time in different timezones\")\n search_registry_tools(\"search for jira issues\", max_results=5)\n \"\"\"\n global registry_client\n\n if registry_client is None:\n return json.dumps(\n {\"error\": \"Registry client not initialized. Check authentication configuration.\"}\n )\n\n try:\n logger.info(f\"Searching registry for tools: '{query}' (max_results={max_results})\")\n\n # Search for tools using semantic search\n search_response = await registry_client.search_tools(\n query=query,\n max_results=max_results,\n entity_types=[\"mcp_server\", \"tool\"],\n )\n\n results = []\n\n # Process tool results first (most specific)\n # The search API now returns inputSchema directly, no need for get_server_info\n for tool_result in search_response.tools:\n formatted = _format_tool_result(tool_result)\n results.append(formatted)\n\n # Also include matching tools from server results\n for server_result in search_response.servers:\n for matching_tool in server_result.matching_tools:\n # Check if this tool is already in results\n existing = [\n r\n for r in results\n if r[\"tool_name\"] == matching_tool.tool_name\n and r[\"server_path\"] == server_result.path\n ]\n if existing:\n continue\n\n tool_data = {\n \"tool_name\": matching_tool.tool_name,\n \"server_path\": server_result.path,\n \"server_name\": server_result.server_name,\n \"description\": matching_tool.description or \"No description available\",\n \"relevance_score\": matching_tool.relevance_score,\n \"supported_transports\": [\"streamable_http\"],\n }\n # Note: inputSchema is available in the tools[] array, not matching_tools\n\n results.append(tool_data)\n\n # Sort by relevance score\n results.sort(key=lambda x: x.get(\"relevance_score\", 0), reverse=True)\n\n # Limit to max_results\n results = results[:max_results]\n\n logger.info(f\"Found {len(results)} matching tools for query: '{query}'\")\n\n return json.dumps(\n {\n \"query\": query,\n \"tools\": results,\n \"total_found\": len(results),\n },\n indent=2,\n )\n\n except Exception as e:\n logger.error(f\"Error searching registry: {e}\", exc_info=True)\n return json.dumps({\"error\": f\"Search failed: {str(e)}\"})\n\n\n@tool\nasync def invoke_mcp_tool(\n mcp_registry_url: str,\n server_name: str,\n tool_name: str,\n arguments: dict[str, Any],\n supported_transports: list[str] = None,\n auth_provider: str = None,\n) -> str:\n \"\"\"\n Invoke a tool on an MCP server using the MCP Registry URL and server name.\n\n Args:\n mcp_registry_url: The URL of the MCP Registry\n server_name: The name of the MCP server to connect to\n tool_name: The name of the tool to invoke\n arguments: Dictionary containing the arguments for the tool\n supported_transports: Transport protocols ([\"streamable_http\"] or [\"sse\"])\n auth_provider: Authentication provider (e.g., \"atlassian\")\n\n Returns:\n The result of the tool invocation as a string\n \"\"\"\n # Build server URL from registry URL and server name\n parsed_url = urlparse(mcp_registry_url)\n base_url = f\"{parsed_url.scheme}://{parsed_url.netloc}\"\n\n # Remove leading slash from server_name if present\n server_name_clean = server_name.lstrip(\"/\")\n server_url = urljoin(base_url + \"/\", server_name_clean)\n\n # Build headers with authentication\n auth_token = agent_settings.auth_token\n region = agent_settings.region\n\n headers = {\n \"X-Authorization\": f\"Bearer {auth_token}\",\n \"X-Region\": region,\n \"Authorization\": f\"Bearer {auth_token}\",\n }\n\n # Get server-specific headers from configuration\n server_headers = get_server_headers(server_name_clean, server_config)\n headers.update(server_headers)\n\n # Handle egress authentication if auth_provider is specified\n if auth_provider:\n headers = _add_egress_auth(headers, auth_provider, server_name_clean)\n\n # Determine transport (default to streamable_http)\n use_sse = (\n supported_transports\n and \"sse\" in supported_transports\n and \"streamable_http\" not in supported_transports\n )\n\n if use_sse:\n server_url = server_url.rstrip(\"/\") + \"/sse\"\n\n logger.info(f\"Invoking {tool_name} on {server_name_clean}\")\n\n # Try invocation, retry with /mcp suffix on failure\n try:\n if use_sse:\n return await _invoke_via_sse(server_url, headers, tool_name, arguments)\n else:\n return await _invoke_via_http(server_url, headers, tool_name, arguments)\n except Exception as e:\n # Always retry with /mcp suffix on first failure\n mcp_url = server_url.rstrip(\"/\") + \"/mcp\"\n logger.info(f\"First attempt failed, retrying with /mcp suffix: {mcp_url}\")\n try:\n if use_sse:\n return await _invoke_via_sse(mcp_url, headers, tool_name, arguments)\n else:\n return await _invoke_via_http(mcp_url, headers, tool_name, arguments)\n except Exception as retry_e:\n logger.error(f\"Error invoking MCP tool (retry): {retry_e}\")\n return f\"Error invoking MCP tool: {str(retry_e)}\"\n\n\ndef _add_egress_auth(\n headers: dict[str, str],\n auth_provider: str,\n server_name: str,\n) -> dict[str, str]:\n \"\"\"Add egress authentication headers if available.\"\"\"\n oauth_tokens_dir = os.path.join(\n os.path.dirname(os.path.dirname(os.path.abspath(__file__))), \".oauth-tokens\"\n )\n server_lower = server_name.lower()\n provider_lower = auth_provider.lower()\n\n # Try provider-server specific file, then provider-only file\n egress_files = [\n os.path.join(oauth_tokens_dir, f\"{provider_lower}-{server_lower}-egress.json\"),\n os.path.join(oauth_tokens_dir, f\"{provider_lower}-egress.json\"),\n ]\n\n for egress_file in egress_files:\n if os.path.exists(egress_file):\n with open(egress_file) as f:\n egress_data = json.load(f)\n\n egress_token = egress_data.get(\"access_token\")\n if egress_token:\n headers[\"Authorization\"] = f\"Bearer {egress_token}\"\n logger.info(f\"Using egress auth for {auth_provider}\")\n\n # Provider-specific headers\n if provider_lower == \"atlassian\":\n cloud_id = egress_data.get(\"cloud_id\")\n if cloud_id:\n headers[\"X-Atlassian-Cloud-Id\"] = cloud_id\n\n break\n\n return headers\n\n\nasync def _invoke_via_sse(\n server_url: str,\n headers: dict[str, str],\n tool_name: str,\n arguments: dict[str, Any],\n) -> str:\n \"\"\"Invoke tool via SSE transport.\"\"\"\n async with sse_client(server_url, headers=headers) as (read, write):\n async with mcp.ClientSession(read, write) as session:\n await session.initialize()\n result = await session.call_tool(tool_name, arguments=arguments)\n return _format_tool_response(result)\n\n\nasync def _invoke_via_http(\n server_url: str,\n headers: dict[str, str],\n tool_name: str,\n arguments: dict[str, Any],\n) -> str:\n \"\"\"Invoke tool via streamable HTTP transport.\"\"\"\n async with httpx.AsyncClient(headers=headers) as http_client:\n async with streamable_http_client(\n url=server_url,\n http_client=http_client,\n ) as (read, write, _):\n async with mcp.ClientSession(read, write) as session:\n await session.initialize()\n result = await session.call_tool(tool_name, arguments=arguments)\n return _format_tool_response(result)\n\n\ndef _format_tool_response(result: Any) -> str:\n \"\"\"Format MCP tool result as string.\"\"\"\n response_parts = []\n for r in result.content:\n if hasattr(r, \"text\"):\n response_parts.append(r.text)\n return \"\\n\".join(response_parts).strip()\n\n\n# Get current UTC time (using timezone.utc to avoid deprecation warning)\ncurrent_utc_time = str(datetime.now(UTC))\n\n\n# Global agent settings to store authentication details\nclass AgentSettings:\n \"\"\"Stores authentication details for MCP tool invocation.\"\"\"\n\n def __init__(self):\n self.auth_token: str | None = None\n self.region: str = \"us-east-1\"\n\n\nagent_settings = AgentSettings()\n\n# Global server configuration\nserver_config = {}\n\n\ndef load_system_prompt():\n \"\"\"\n Load the system prompt template from the system_prompt.txt file.\n\n Returns:\n str: The system prompt template\n \"\"\"\n import os\n\n try:\n # Get the directory where this Python file is located\n current_dir = os.path.dirname(__file__)\n system_prompt_path = os.path.join(current_dir, \"system_prompt.txt\")\n with open(system_prompt_path) as f:\n return f.read()\n except Exception as e:\n print(f\"Error loading system prompt: {e}\")\n # Provide a minimal fallback prompt in case the file can't be loaded\n return \"\"\"\n \n You are a highly capable AI assistant designed to solve problems for users.\n Current UTC time: {current_utc_time}\n MCP Registry URL: {mcp_registry_url}\n \n \"\"\"\n\n\ndef print_agent_response(\n response_dict: dict[str, Any],\n verbose: bool = False,\n) -> None:\n \"\"\"\n Print the agent's final response.\n\n Args:\n response_dict: Dictionary containing the agent response with 'messages' key\n verbose: Whether to show detailed message flow\n \"\"\"\n if not response_dict or \"messages\" not in response_dict:\n return\n\n messages = response_dict[\"messages\"]\n\n # In verbose mode, show the message flow\n if verbose:\n _print_verbose_messages(messages)\n\n # Find and print the final AI response\n for message in reversed(messages):\n message_type = type(message).__name__\n\n if \"AIMessage\" in message_type:\n content = getattr(message, \"content\", None)\n if content:\n print(\"\\n\" + str(content), flush=True)\n break\n\n\ndef _print_verbose_messages(messages: list[Any]) -> None:\n \"\"\"Print detailed message flow for debugging.\"\"\"\n colors = {\n \"SYSTEM\": \"\\033[1;33m\",\n \"HUMAN\": \"\\033[1;32m\",\n \"AI\": \"\\033[1;36m\",\n \"TOOL\": \"\\033[1;35m\",\n \"RESET\": \"\\033[0m\",\n }\n\n print(f\"\\n{colors['AI']}=== Message Flow ({len(messages)} messages) ==={colors['RESET']}\\n\")\n\n for i, message in enumerate(messages, 1):\n msg_type = type(message).__name__\n color = colors.get(\n \"AI\" if \"AI\" in msg_type else \"TOOL\" if \"Tool\" in msg_type else \"HUMAN\", colors[\"RESET\"]\n )\n\n content = getattr(message, \"content\", str(message))\n preview = content[:100] + \"...\" if len(str(content)) > 100 else content\n\n print(f\"{color}[{i}] {msg_type}: {preview}{colors['RESET']}\")\n\n # Show tool calls if present\n if hasattr(message, \"tool_calls\") and message.tool_calls:\n for tc in message.tool_calls:\n print(f\" -> Tool: {tc.get('name', 'unknown')}\")\n\n\nclass InteractiveAgent:\n \"\"\"Interactive agent that maintains conversation history.\"\"\"\n\n def __init__(\n self,\n agent,\n system_prompt: str,\n verbose: bool = False,\n ):\n self.agent = agent\n self.system_prompt = system_prompt\n self.verbose = verbose\n self.conversation_history: list[dict[str, str]] = []\n\n async def process_message(\n self,\n user_input: str,\n show_progress: bool = True,\n ) -> dict[str, Any]:\n \"\"\"Process a user message and return the agent's response.\"\"\"\n messages = [{\"role\": \"system\", \"content\": self.system_prompt}]\n messages.extend(self.conversation_history)\n messages.append({\"role\": \"user\", \"content\": user_input})\n\n spinner = None\n if show_progress:\n spinner = ProgressSpinner().start()\n\n try:\n response = await self.agent.ainvoke({\"messages\": messages})\n finally:\n if spinner:\n spinner.stop()\n\n # Update history\n self.conversation_history.append({\"role\": \"user\", \"content\": user_input})\n\n if response and \"messages\" in response:\n for message in reversed(response[\"messages\"]):\n if \"AIMessage\" in type(message).__name__:\n ai_content = getattr(message, \"content\", str(message))\n self.conversation_history.append({\"role\": \"assistant\", \"content\": ai_content})\n break\n\n return response\n\n async def run_interactive_session(self) -> None:\n \"\"\"Run an interactive conversation session.\"\"\"\n print(\"\\n\" + \"=\" * 60)\n print(\"Interactive Agent Session\")\n print(\"=\" * 60)\n print(\"Commands: 'exit' to quit, 'clear' to reset, 'history' to view\")\n print(\"=\" * 60 + \"\\n\")\n\n while True:\n try:\n user_input = input(\"\\nYou: \").strip()\n\n if user_input.lower() in [\"exit\", \"quit\", \"bye\"]:\n print(\"\\nGoodbye!\")\n break\n\n if user_input.lower() in [\"clear\", \"reset\"]:\n self.conversation_history = []\n print(\"History cleared.\")\n continue\n\n if user_input.lower() == \"history\":\n self._print_history()\n continue\n\n if not user_input:\n continue\n\n response = await self.process_message(user_input)\n print(\"\\nAgent:\", end=\"\")\n print_agent_response(response, self.verbose)\n\n except KeyboardInterrupt:\n print(\"\\n\\nInterrupted. Type 'exit' to quit.\")\n except Exception as e:\n print(f\"\\nError: {str(e)}\")\n if self.verbose:\n import traceback\n\n traceback.print_exc()\n\n def _print_history(self) -> None:\n \"\"\"Print conversation history.\"\"\"\n if not self.conversation_history:\n print(\"No history yet.\")\n return\n\n print(\"\\nConversation History:\")\n print(\"-\" * 40)\n for i, msg in enumerate(self.conversation_history, 1):\n role = \"You\" if msg[\"role\"] == \"user\" else \"Agent\"\n preview = msg[\"content\"][:80] + \"...\" if len(msg[\"content\"]) > 80 else msg[\"content\"]\n print(f\"{i}. {role}: {preview}\")\n\n\nasync def main():\n \"\"\"Main function - parses args, sets up model, and runs agent.\"\"\"\n args = parse_arguments()\n\n # Set up authentication\n agent_settings.auth_token = args.jwt_token\n\n # Load server configuration\n global server_config\n server_config = load_server_config()\n\n # Show startup info\n print_step(f\"Registry: {args.mcp_registry_url}\")\n print_step(f\"Provider: {args.provider}\")\n print_step(f\"Model: {args.model}\")\n\n # Initialize model\n model = _create_model(args.provider, args.model)\n if not model:\n return\n\n try:\n # Initialize registry client\n global registry_client\n parsed_url = urlparse(args.mcp_registry_url)\n registry_base_url = f\"{parsed_url.scheme}://{parsed_url.netloc}\"\n\n registry_client = RegistryClient(\n registry_url=registry_base_url,\n jwt_token=args.jwt_token,\n )\n\n # Create the agent\n all_tools = [calculator, search_registry_tools, invoke_mcp_tool]\n agent = create_react_agent(model, all_tools)\n\n # Load system prompt\n system_prompt = load_system_prompt().format(\n current_utc_time=current_utc_time,\n mcp_registry_url=args.mcp_registry_url,\n )\n\n interactive_agent = InteractiveAgent(agent, system_prompt, args.verbose)\n\n # Process initial prompt if provided\n if args.prompt:\n print_step(\"Processing prompt...\")\n response = await interactive_agent.process_message(args.prompt)\n\n if not args.interactive:\n print_agent_response(response, args.verbose)\n return\n else:\n print(\"\\nAgent:\", end=\"\")\n print_agent_response(response, args.verbose)\n\n # Run interactive session or show usage\n if args.interactive:\n await interactive_agent.run_interactive_session()\n elif not args.prompt:\n print(\"\\nNo prompt provided. Use --prompt or --interactive\")\n print(\"\\nExamples:\")\n print(' python agent.py --prompt \"What time is it?\"')\n print(\" python agent.py --interactive\")\n\n except Exception as e:\n print(f\"Error: {str(e)}\")\n import traceback\n\n traceback.print_exc()\n\n\ndef _create_model(\n provider: str,\n model_id: str,\n):\n \"\"\"Create the LLM model based on provider.\"\"\"\n if provider == \"anthropic\":\n api_key = os.getenv(\"ANTHROPIC_API_KEY\")\n if not api_key:\n print(\"Error: ANTHROPIC_API_KEY not found\")\n return None\n\n return ChatAnthropic(\n model=model_id,\n api_key=api_key,\n temperature=0,\n max_tokens=8192,\n )\n\n # Default to Bedrock\n aws_region = os.getenv(\"AWS_DEFAULT_REGION\", os.getenv(\"AWS_REGION\", \"us-east-1\"))\n return ChatBedrock(\n model_id=model_id,\n region_name=aws_region,\n temperature=0,\n max_tokens=8192,\n )\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "agents/cli_user_auth.py", "content": "#!/usr/bin/env python3\n\"\"\"\nCLI tool for MCP Gateway user authentication via Cognito OAuth.\nCaptures session cookie and saves to local file for agent use.\n\nUsage:\n python cli_auth.py [--cookie-file PATH]\n\nEnvironment variables required:\n COGNITO_DOMAIN: Cognito domain (e.g., 'mcp-gateway' or full URL)\n COGNITO_CLIENT_ID: OAuth client ID\n SECRET_KEY: Must match the registry SECRET_KEY for cookie compatibility\n AWS_REGION: AWS region (optional, defaults to us-east-1)\n\"\"\"\n\nimport argparse\nimport base64\nimport hashlib\nimport json\nimport logging\nimport os\nimport secrets\nimport sys\nimport threading\nimport webbrowser\nfrom http.server import BaseHTTPRequestHandler, HTTPServer\nfrom pathlib import Path\nfrom urllib.parse import parse_qs, urlencode\n\nimport requests\nfrom dotenv import load_dotenv\nfrom itsdangerous import URLSafeTimedSerializer\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO, format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n)\nlogger = logging.getLogger(__name__)\n\n# Load environment variables from .env file\n# Look for .env file in the same directory as this script\nscript_dir = Path(__file__).parent\nenv_file = script_dir / \".env.user\"\nif env_file.exists():\n load_dotenv(env_file, override=True)\n logger.info(f\"Loaded environment variables from {env_file}\")\nelse:\n logger.warning(f\"No .env file found at {env_file}\")\n\n# Configuration from environment\nCOGNITO_USER_POOL_ID = os.environ.get(\"COGNITO_USER_POOL_ID\")\nCOGNITO_DOMAIN = os.environ.get(\"COGNITO_DOMAIN\")\nCOGNITO_CLIENT_ID = os.environ.get(\"COGNITO_CLIENT_ID\")\nCOGNITO_CLIENT_SECRET = os.environ.get(\"COGNITO_CLIENT_SECRET\")\nSECRET_KEY = os.environ.get(\"SECRET_KEY\")\n\n# Make redirect URI configurable based on environment\nREGISTRY_URL = os.environ.get(\"REGISTRY_URL\", \"http://localhost\")\nUSE_DIRECT_CALLBACK = os.environ.get(\"USE_DIRECT_CALLBACK\", \"true\").lower() == \"true\"\n\nif USE_DIRECT_CALLBACK:\n logger.info(\"Using direct callback\")\n # Direct callback to local server (original behavior)\n COGNITO_REDIRECT_URI = \"http://localhost:9090/callback\"\n CALLBACK_PORT = 9090\n CALLBACK_PATH = \"/callback\"\nelse:\n # Use nginx proxy callback (for Docker environments)\n COGNITO_REDIRECT_URI = f\"{REGISTRY_URL}/oauth2/callback/cognito\"\n CALLBACK_PORT = 8080 # Different port to avoid conflicts\n CALLBACK_PATH = \"/auth_complete\"\n\nAWS_REGION = os.environ.get(\"AWS_REGION\", \"us-east-1\")\n\n# Validate required environment variables\nif not all([COGNITO_USER_POOL_ID, COGNITO_CLIENT_ID, SECRET_KEY]):\n logger.error(\"Missing required environment variables\")\n logger.error(\"Required: COGNITO_USER_POOL_ID, COGNITO_CLIENT_ID, SECRET_KEY\")\n sys.exit(1)\n\n# Construct the Cognito domain\nif COGNITO_DOMAIN:\n # Use custom domain if provided\n COGNITO_DOMAIN_URL = f\"https://{COGNITO_DOMAIN}.auth.{AWS_REGION}.amazoncognito.com\"\nelse:\n # Otherwise use user pool ID without underscores (standard format)\n user_pool_id_wo_underscore = COGNITO_USER_POOL_ID.replace(\"_\", \"\")\n COGNITO_DOMAIN_URL = f\"https://{user_pool_id_wo_underscore}.auth.{AWS_REGION}.amazoncognito.com\"\n\nlogger.info(f\"Using Cognito domain: {COGNITO_DOMAIN_URL}\")\nlogger.info(\n f\"Redirect URI configured: {COGNITO_REDIRECT_URI if 'COGNITO_REDIRECT_URI' in globals() else 'Not yet configured'}\"\n)\n\n# OAuth endpoints\nAUTHORIZE_URL = f\"{COGNITO_DOMAIN_URL}/oauth2/authorize\"\nTOKEN_URL = f\"{COGNITO_DOMAIN_URL}/oauth2/token\"\n\n# Global variables for OAuth flow\nauth_result = None\nauth_complete = threading.Event()\npkce_verifier = None\n\n\nclass OAuthCallbackHandler(BaseHTTPRequestHandler):\n \"\"\"HTTP request handler for OAuth callback\"\"\"\n\n def log_message(self, format, *args):\n \"\"\"Override to use logger instead of stderr\"\"\"\n logger.debug(f\"Callback server: {format}\", *args)\n\n def do_GET(self):\n \"\"\"Handle OAuth callback\"\"\"\n global auth_result\n\n if self.path.startswith(CALLBACK_PATH):\n # Parse query parameters\n query_string = self.path.split(\"?\", 1)[1] if \"?\" in self.path else \"\"\n params = parse_qs(query_string)\n\n # Check for authorization code\n if \"code\" in params:\n auth_code = params[\"code\"][0]\n logger.info(\"Authorization code received\")\n\n # Exchange code for tokens\n token_result = self.exchange_code_for_tokens(auth_code)\n\n if token_result:\n # Create session cookie\n cookie_value = self.create_session_cookie(token_result)\n if cookie_value:\n auth_result = {\n \"success\": True,\n \"cookie\": cookie_value,\n \"user_info\": token_result,\n }\n self.send_success_response()\n else:\n self.send_error_response(\"Failed to create session cookie\")\n else:\n self.send_error_response(\"Failed to exchange authorization code\")\n\n elif \"error\" in params:\n error = params.get(\"error\", [\"Unknown error\"])[0]\n error_description = params.get(\"error_description\", [\"\"])[0]\n logger.error(f\"OAuth error: {error} - {error_description}\")\n self.send_error_response(f\"Authentication failed: {error}\")\n\n else:\n self.send_error_response(\"Invalid callback parameters\")\n\n # Signal completion\n auth_complete.set()\n else:\n self.send_404()\n\n def exchange_code_for_tokens(self, auth_code):\n \"\"\"Exchange authorization code for tokens\"\"\"\n global pkce_verifier\n\n try:\n # Basic auth with client credentials\n auth_string = f\"{COGNITO_CLIENT_ID}:{COGNITO_CLIENT_SECRET}\"\n auth_bytes = auth_string.encode(\"utf-8\")\n auth_b64 = base64.b64encode(auth_bytes).decode(\"utf-8\")\n\n headers = {\n \"Authorization\": f\"Basic {auth_b64}\",\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n }\n\n data = {\n \"grant_type\": \"authorization_code\",\n \"client_id\": COGNITO_CLIENT_ID,\n \"code\": auth_code,\n \"redirect_uri\": COGNITO_REDIRECT_URI,\n \"code_verifier\": pkce_verifier,\n }\n\n response = requests.post(TOKEN_URL, headers=headers, data=data, timeout=30)\n response.raise_for_status()\n\n token_data = response.json()\n logger.info(\"Successfully exchanged code for tokens\")\n\n # Decode ID token to get user info\n id_token = token_data.get(\"id_token\")\n if id_token:\n # Simple JWT decode without verification (Cognito already verified)\n # In production, should verify with Cognito JWKS\n payload = id_token.split(\".\")[1]\n # Add padding if needed\n payload += \"=\" * (4 - len(payload) % 4)\n user_info = json.loads(base64.urlsafe_b64decode(payload))\n\n return {\n \"username\": user_info.get(\"cognito:username\", user_info.get(\"email\")),\n \"groups\": user_info.get(\"cognito:groups\", []),\n \"email\": user_info.get(\"email\"),\n \"sub\": user_info.get(\"sub\"),\n }\n\n return None\n\n except Exception as e:\n logger.error(f\"Token exchange failed: {e}\")\n return None\n\n def create_session_cookie(self, user_info):\n \"\"\"Create session cookie matching registry format\"\"\"\n try:\n signer = URLSafeTimedSerializer(SECRET_KEY)\n\n # Create session data matching old implementation format\n session_data = {\n \"username\": user_info[\"username\"],\n \"groups\": user_info.get(\"groups\", []),\n \"provider_type\": \"cognito\",\n \"is_oauth\": True,\n \"session_id\": secrets.token_urlsafe(16),\n \"login_time\": None, # Will be set by registry if needed\n }\n\n # Serialize the session data\n cookie_value = signer.dumps(session_data)\n logger.info(f\"Session cookie created for user: {user_info['username']}\")\n\n return cookie_value\n\n except Exception as e:\n logger.error(f\"Failed to create session cookie: {e}\")\n return None\n\n def send_success_response(self):\n \"\"\"Send success response to browser\"\"\"\n self.send_response(200)\n self.send_header(\"Content-type\", \"text/html\")\n self.end_headers()\n\n html = \"\"\"\n \n \n Authentication Successful\n \n \n \n

✓ Authentication Successful!

\n
\n

Your session cookie has been saved.

\n

You can now close this window and return to the terminal.

\n
\n \n \n \n \"\"\"\n self.wfile.write(html.encode())\n\n def send_error_response(self, error_message):\n \"\"\"Send error response to browser\"\"\"\n self.send_response(400)\n self.send_header(\"Content-type\", \"text/html\")\n self.end_headers()\n\n html = f\"\"\"\n \n \n Authentication Failed\n \n \n \n

✗ Authentication Failed

\n

{error_message}

\n

Please close this window and try again.

\n \n \n \"\"\"\n self.wfile.write(html.encode())\n\n def send_404(self):\n \"\"\"Send 404 response\"\"\"\n self.send_response(404)\n self.end_headers()\n\n\ndef generate_pkce_challenge():\n \"\"\"Generate PKCE code verifier and challenge\"\"\"\n # Generate code verifier (43-128 characters)\n code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode(\"utf-8\").rstrip(\"=\")\n\n # Generate code challenge (SHA256 of verifier)\n challenge_bytes = hashlib.sha256(code_verifier.encode(\"utf-8\")).digest()\n code_challenge = base64.urlsafe_b64encode(challenge_bytes).decode(\"utf-8\").rstrip(\"=\")\n\n return code_verifier, code_challenge\n\n\ndef start_callback_server():\n \"\"\"Start the OAuth callback server\"\"\"\n server = HTTPServer((\"localhost\", CALLBACK_PORT), OAuthCallbackHandler)\n server_thread = threading.Thread(target=server.serve_forever)\n server_thread.daemon = True\n server_thread.start()\n\n logger.info(f\"Callback server started on http://localhost:{CALLBACK_PORT}\")\n return server\n\n\ndef save_cookie_to_file(cookie_value, file_path):\n \"\"\"Save cookie to file with secure permissions\"\"\"\n try:\n # Expand user path and create directory if needed\n cookie_path = Path(file_path).expanduser()\n cookie_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)\n\n # Write cookie to file\n cookie_path.write_text(cookie_value)\n\n # Set secure permissions (owner read/write only)\n cookie_path.chmod(0o600)\n\n logger.info(f\"Session cookie saved to: {cookie_path}\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to save cookie: {e}\")\n return False\n\n\ndef main():\n \"\"\"Main authentication flow\"\"\"\n global pkce_verifier\n\n parser = argparse.ArgumentParser(description=\"MCP Gateway CLI Authentication\")\n parser.add_argument(\n \"--cookie-file\",\n default=\"~/.mcp/session_cookie\",\n help=\"Path to save session cookie (default: ~/.mcp/session_cookie)\",\n )\n parser.add_argument(\n \"--use-proxy\",\n action=\"store_true\",\n help=\"Use nginx proxy callback instead of direct callback (for Docker environments)\",\n )\n parser.add_argument(\n \"--registry-url\",\n default=\"http://localhost\",\n help=\"Registry URL for proxy-based auth (default: http://localhost)\",\n )\n args = parser.parse_args()\n\n # Override environment variables with CLI arguments\n if args.use_proxy:\n global USE_DIRECT_CALLBACK, COGNITO_REDIRECT_URI, CALLBACK_PORT, CALLBACK_PATH, REGISTRY_URL\n USE_DIRECT_CALLBACK = False\n REGISTRY_URL = args.registry_url\n COGNITO_REDIRECT_URI = f\"{REGISTRY_URL}/oauth2/callback/cognito\"\n CALLBACK_PORT = 8081\n CALLBACK_PATH = \"/auth_complete\"\n\n try:\n # Generate PKCE challenge\n pkce_verifier, pkce_challenge = generate_pkce_challenge()\n\n # Start callback server\n server = start_callback_server()\n\n # Build authorization URL\n auth_params = {\n \"response_type\": \"code\",\n \"client_id\": COGNITO_CLIENT_ID,\n \"redirect_uri\": COGNITO_REDIRECT_URI,\n \"scope\": \"openid email profile\",\n \"code_challenge\": pkce_challenge,\n \"code_challenge_method\": \"S256\",\n }\n auth_url = f\"{AUTHORIZE_URL}?{urlencode(auth_params)}\"\n\n # Open browser for authentication\n logger.info(\"Opening browser for Cognito login...\")\n print(\"\\n\" + \"=\" * 50)\n print(\"Opening your browser for authentication...\")\n print(\"Please complete the login process.\")\n print(f\"Redirect URI: {COGNITO_REDIRECT_URI}\")\n print(f\"Callback server: http://localhost:{CALLBACK_PORT}\")\n print(\"=\" * 50 + \"\\n\")\n\n logger.info(f\"Authorization URL: {auth_url}\")\n webbrowser.open(auth_url)\n\n # Wait for callback\n logger.info(\"Waiting for authentication callback...\")\n auth_complete.wait(timeout=300) # 5 minute timeout\n\n # Shutdown callback server\n server.shutdown()\n\n # Check results\n if auth_result and auth_result.get(\"success\"):\n cookie_value = auth_result[\"cookie\"]\n\n if save_cookie_to_file(cookie_value, args.cookie_file):\n print(\"\\n\" + \"=\" * 50)\n print(\"✓ Authentication successful!\")\n print(f\"✓ Session cookie saved to: {Path(args.cookie_file).expanduser()}\")\n print(\"\\nYou can now use this cookie with agents:\")\n print(\" python agents/agent.py --use-session-cookie\")\n print(\"=\" * 50 + \"\\n\")\n return 0\n else:\n print(\"\\n✗ Failed to save session cookie\")\n return 1\n else:\n print(\"\\n✗ Authentication failed\")\n return 1\n\n except KeyboardInterrupt:\n print(\"\\n\\nAuthentication cancelled by user\")\n return 1\n except Exception as e:\n logger.error(f\"Unexpected error: {e}\")\n print(f\"\\n✗ Error: {e}\")\n return 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "agents/client.py", "content": "\"\"\"\nClient for the Auth Server REST API.\n\nThis script demonstrates connecting to the Auth Server with Cognito authentication.\n\nConfiguration can be provided via command line arguments or environment variables.\nCommand line arguments take precedence over environment variables.\n\nEnvironment Variables:\n- AUTH_SERVER_URL: URL of the Auth server\n- COGNITO_CLIENT_ID: Cognito App Client ID\n- COGNITO_CLIENT_SECRET: Cognito App Client Secret\n- COGNITO_USER_POOL_ID: Cognito User Pool ID\n- AWS_REGION: AWS region for Cognito\n\nUsage:\n python client.py --generate-token --scopes \"read write\"\n\nExample with command line arguments:\n python client.py --server-url http://localhost:8888 \\\n --client-id [CLIENT_ID] --client-secret [CLIENT_SECRET] \\\n --user-pool-id [USER_POOL_ID] --region us-east-1 \\\n --generate-token --scopes \"read write\"\n\nExample with environment variables (create a .env file):\n AUTH_SERVER_URL=http://localhost:8888\n COGNITO_CLIENT_ID=your_client_id\n COGNITO_CLIENT_SECRET=your_client_secret\n COGNITO_USER_POOL_ID=your_user_pool_id\n AWS_REGION=us-east-1\n \n python client.py --generate-token --scopes \"read write\"\n\"\"\"\n\nimport argparse\nimport logging\nimport os\n\nimport requests\nfrom cognito_utils import generate_token\n\n# Import dotenv for loading environment variables\ntry:\n from dotenv import load_dotenv\n\n DOTENV_AVAILABLE = True\nexcept ImportError:\n DOTENV_AVAILABLE = False\n print(\"Warning: python-dotenv not installed. Environment file loading disabled.\")\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s|p%(process)d|%(pathname)s:%(lineno)d|%(levelname)s|%(message)s\",\n)\n\n\n# Create a custom formatter that extracts folder and filename\nclass CustomFormatter(logging.Formatter):\n def format(self, record):\n # Get the full path and extract just the folder and filename\n pathname = record.pathname\n parts = pathname.split(\"/\")\n if len(parts) >= 2:\n folder_and_file = \"/\".join(parts[-2:]) # Get last two parts (folder/file)\n else:\n folder_and_file = parts[-1] # Just filename if no folder\n\n # Replace the pathname with our custom format\n record.pathname = folder_and_file\n return super().format(record)\n\n\n# Get the root logger and set our custom formatter\nroot_logger = logging.getLogger()\nfor handler in root_logger.handlers:\n handler.setFormatter(\n CustomFormatter(\n \"%(asctime)s|p%(process)d|%(pathname)s:%(lineno)d|%(levelname)s|%(message)s\"\n )\n )\n\nlogger = logging.getLogger(__name__)\n\n\ndef load_env_config() -> dict[str, str | None]:\n \"\"\"\n Load configuration from .env file if available.\n\n Returns:\n Dict[str, Optional[str]]: Dictionary containing environment variables\n \"\"\"\n env_config = {\n \"client_id\": None,\n \"client_secret\": None,\n \"region\": None,\n \"user_pool_id\": None,\n \"server_url\": None,\n }\n\n if DOTENV_AVAILABLE:\n # Try to load from .env file in the current directory\n env_file = os.path.join(os.path.dirname(__file__), \".env\")\n if os.path.exists(env_file):\n load_dotenv(env_file)\n logger.info(f\"Loading environment variables from {env_file}\")\n else:\n # Try to load from .env file in the parent directory\n env_file = os.path.join(os.path.dirname(__file__), \"..\", \".env\")\n if os.path.exists(env_file):\n load_dotenv(env_file)\n logger.info(f\"Loading environment variables from {env_file}\")\n else:\n # Try to load from current working directory\n load_dotenv()\n logger.info(\"Loading environment variables from current directory\")\n\n # Get values from environment\n env_config[\"client_id\"] = os.getenv(\"COGNITO_CLIENT_ID\")\n env_config[\"client_secret\"] = os.getenv(\"COGNITO_CLIENT_SECRET\")\n env_config[\"region\"] = os.getenv(\"AWS_REGION\")\n env_config[\"user_pool_id\"] = os.getenv(\"COGNITO_USER_POOL_ID\")\n env_config[\"server_url\"] = os.getenv(\"AUTH_SERVER_URL\")\n\n return env_config\n\n\ndef parse_arguments():\n \"\"\"\n Parse command line arguments for the Auth Server REST Client.\n Command line arguments take precedence over environment variables.\n\n Returns:\n argparse.Namespace: The parsed command line arguments\n \"\"\"\n # Load environment configuration first\n env_config = load_env_config()\n\n parser = argparse.ArgumentParser(description=\"Auth Server REST Client\")\n\n parser.add_argument(\n \"--server-url\",\n type=str,\n default=env_config[\"server_url\"] or \"http://localhost:8888\",\n help=\"URL of the Auth server (can be set via AUTH_SERVER_URL env var, default: http://localhost:8888)\",\n )\n\n parser.add_argument(\n \"--client-id\",\n type=str,\n default=env_config[\"client_id\"],\n help=\"Cognito App Client ID (can be set via COGNITO_CLIENT_ID env var)\",\n )\n\n parser.add_argument(\n \"--client-secret\",\n type=str,\n default=env_config[\"client_secret\"],\n help=\"Cognito App Client Secret (can be set via COGNITO_CLIENT_SECRET env var, required for token generation)\",\n )\n\n parser.add_argument(\n \"--user-pool-id\",\n type=str,\n default=env_config[\"user_pool_id\"],\n help=\"Cognito User Pool ID (can be set via COGNITO_USER_POOL_ID env var)\",\n )\n\n parser.add_argument(\n \"--region\",\n type=str,\n default=env_config[\"region\"] or \"us-east-1\",\n help=\"AWS Region (can be set via AWS_REGION env var, default: us-east-1)\",\n )\n\n parser.add_argument(\n \"--token\",\n type=str,\n help=\"Provide a token directly\",\n )\n\n parser.add_argument(\n \"--generate-token\",\n action=\"store_true\",\n help=\"Generate a valid token using client credentials flow\",\n )\n\n parser.add_argument(\n \"--scopes\",\n type=str,\n help=\"Space-separated list of scopes for token generation (e.g., 'read write')\",\n )\n\n args = parser.parse_args()\n\n # Validate that required Cognito parameters are available (either from command line or environment)\n missing_params = []\n if not args.client_id:\n missing_params.append(\"--client-id (or COGNITO_CLIENT_ID env var)\")\n if not args.client_secret:\n missing_params.append(\"--client-secret (or COGNITO_CLIENT_SECRET env var)\")\n if not args.user_pool_id:\n missing_params.append(\"--user-pool-id (or COGNITO_USER_POOL_ID env var)\")\n if not args.region:\n missing_params.append(\"--region (or AWS_REGION env var)\")\n\n if missing_params:\n parser.error(f\"Missing required parameters: {', '.join(missing_params)}\")\n\n return args\n\n\ndef main():\n \"\"\"Main function to demonstrate client usage.\"\"\"\n args = parse_arguments()\n\n # Example: Check server health\n try:\n health_response = requests.get(f\"{args.server_url}/health\", timeout=30)\n health_response.raise_for_status()\n logger.info(f\"Server health: {health_response.json()}\")\n except Exception as e:\n logger.error(f\"Error checking server health: {e}\")\n return\n\n # Determine which token to use\n access_token = None\n\n # Option 1: Generate a token if requested\n if args.generate_token:\n if not args.client_secret:\n logger.error(\"Client secret is required for token generation\")\n return\n\n try:\n scopes = args.scopes.split() if args.scopes else None\n token_response = generate_token(\n client_id=args.client_id,\n client_secret=args.client_secret,\n user_pool_id=args.user_pool_id,\n region=args.region,\n scopes=scopes,\n )\n access_token = token_response[\"access_token\"]\n logger.info(f\"Generated token: {access_token[:20]}...\")\n\n # Print token details\n logger.info(f\"Token type: {token_response.get('token_type', 'N/A')}\")\n logger.info(f\"Expires in: {token_response.get('expires_in', 'N/A')} seconds\")\n if \"scope\" in token_response:\n logger.info(f\"Scopes: {token_response['scope']}\")\n\n except Exception as e:\n logger.error(f\"Failed to generate token: {e}\")\n return\n\n # Option 2: Use provided token\n elif args.token:\n access_token = args.token\n logger.info(f\"Using provided token: {access_token[:20]}...\")\n\n # No token available\n else:\n logger.error(\"No token available. Use --generate-token or --token to provide a token.\")\n return\n\n # Include the new required headers\n headers = {\n \"Authorization\": f\"Bearer {access_token}\",\n \"X-Client-Id\": args.client_id,\n \"X-User-Pool-Id\": args.user_pool_id,\n \"X-Region\": args.region,\n }\n\n logger.info(\"Sending validation request with headers:\")\n logger.info(f\" Authorization: Bearer {access_token[:10]}...\")\n logger.info(f\" X-Client-Id: {args.client_id}\")\n logger.info(f\" X-User-Pool-Id: {args.user_pool_id}\")\n logger.info(f\" X-Region: {args.region}\")\n\n try:\n # Call the validate endpoint\n validate_response = requests.post(\n f\"{args.server_url}/validate\", headers=headers, timeout=30\n )\n validate_response.raise_for_status()\n result = validate_response.json()\n\n # Print the result\n logger.info(\"Token validation result:\")\n logger.info(f\"Valid: {result['valid']}\")\n logger.info(f\"Scopes: {', '.join(result['scopes'])}\")\n logger.info(f\"Method: {result.get('method', 'N/A')}\")\n logger.info(f\"Client ID: {result.get('client_id', 'N/A')}\")\n if result.get(\"error\"):\n logger.info(f\"Error: {result['error']}\")\n except requests.exceptions.HTTPError as e:\n if e.response.status_code == 401:\n logger.error(\n f\"Authentication error: {e.response.json().get('detail', 'Unknown error')}\"\n )\n else:\n logger.error(f\"HTTP error: {e}\")\n except Exception as e:\n logger.error(f\"Error validating token: {e}\")\n\n # Example: Get auth configuration\n try:\n config_response = requests.get(f\"{args.server_url}/config\", timeout=30)\n config_response.raise_for_status()\n auth_config = config_response.json()\n\n logger.info(\"Server auth configuration:\")\n for key, value in auth_config.items():\n logger.info(f\"{key}: {value}\")\n\n logger.info(\"\\nClient configuration:\")\n logger.info(f\"Client ID: {args.client_id}\")\n logger.info(f\"User Pool ID: {args.user_pool_id}\")\n logger.info(f\"Region: {args.region}\")\n except Exception as e:\n logger.error(f\"Error accessing auth configuration: {e}\")\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "agents/registry_client.py", "content": "\"\"\"Client for MCP Registry API - tool discovery and search.\"\"\"\n\nimport json\nimport logging\nimport time\nfrom typing import (\n Any,\n)\n\nimport aiohttp\nfrom pydantic import (\n BaseModel,\n Field,\n)\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass MatchingTool(BaseModel):\n \"\"\"Tool matching result from semantic search.\n\n Note: inputSchema is NOT included here to avoid duplication.\n Full tool details including inputSchema are in the tools[] array.\n \"\"\"\n\n tool_name: str = Field(..., description=\"Name of the matching tool\")\n description: str | None = Field(None, description=\"Tool description\")\n relevance_score: float = Field(0.0, ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Match context\")\n\n\nclass ServerSearchResult(BaseModel):\n \"\"\"MCP Server search result from semantic search.\"\"\"\n\n path: str = Field(..., description=\"Server path in registry\")\n server_name: str = Field(..., description=\"Server name\")\n description: str | None = Field(None, description=\"Server description\")\n tags: list[str] = Field(default_factory=list, description=\"Server tags\")\n num_tools: int = Field(0, description=\"Number of tools\")\n is_enabled: bool = Field(False, description=\"Whether server is enabled\")\n relevance_score: float = Field(0.0, ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Match context\")\n matching_tools: list[MatchingTool] = Field(\n default_factory=list, description=\"Tools matching the query\"\n )\n\n\nclass ToolSearchResult(BaseModel):\n \"\"\"Tool search result from semantic search.\"\"\"\n\n server_path: str = Field(..., description=\"Server path in registry\")\n server_name: str = Field(..., description=\"Server name\")\n tool_name: str = Field(..., description=\"Tool name\")\n description: str | None = Field(None, description=\"Tool description\")\n inputSchema: dict[str, Any] | None = Field(None, description=\"JSON Schema for tool input\")\n relevance_score: float = Field(0.0, ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Match context\")\n\n\nclass SearchResponse(BaseModel):\n \"\"\"Response from semantic search API.\"\"\"\n\n query: str = Field(..., description=\"Original query\")\n servers: list[ServerSearchResult] = Field(default_factory=list, description=\"Matching servers\")\n tools: list[ToolSearchResult] = Field(default_factory=list, description=\"Matching tools\")\n total_servers: int = Field(0, description=\"Total matching servers\")\n total_tools: int = Field(0, description=\"Total matching tools\")\n\n\nclass RegistryClient:\n \"\"\"Client for MCP Registry API operations.\"\"\"\n\n def __init__(\n self,\n registry_url: str,\n jwt_token: str | None = None,\n keycloak_url: str | None = None,\n client_id: str | None = None,\n client_secret: str | None = None,\n realm: str = \"mcp-gateway\",\n ) -> None:\n \"\"\"\n Initialize the Registry Client.\n\n Args:\n registry_url: Base URL of the MCP Registry (e.g., https://mcpgateway.ddns.net)\n jwt_token: Pre-generated JWT token (bypasses M2M auth)\n keycloak_url: Keycloak URL for M2M token generation\n client_id: OAuth client ID\n client_secret: OAuth client secret\n realm: Keycloak realm name\n \"\"\"\n self.registry_url = registry_url.rstrip(\"/\")\n self.jwt_token = jwt_token\n self.keycloak_url = keycloak_url.rstrip(\"/\") if keycloak_url else None\n self.client_id = client_id\n self.client_secret = client_secret\n self.realm = realm\n\n # Token caching\n self._cached_token: str | None = None\n self._token_expires_at: float = 0\n\n if jwt_token:\n logger.info(f\"RegistryClient initialized with JWT token for {registry_url}\")\n elif keycloak_url:\n logger.info(f\"RegistryClient initialized with M2M credentials for {registry_url}\")\n else:\n logger.warning(\"RegistryClient initialized without authentication\")\n\n async def _get_token(self) -> str:\n \"\"\"\n Get or refresh the authentication token.\n\n Returns:\n JWT access token\n\n Raises:\n Exception: If token acquisition fails\n \"\"\"\n # Use direct JWT token if provided\n if self.jwt_token:\n logger.debug(\"Using direct JWT token\")\n return self.jwt_token\n\n # Check cached token validity (with 60s safety margin)\n current_time = time.time()\n if self._cached_token and current_time < self._token_expires_at - 60:\n logger.debug(\"Using cached token\")\n return self._cached_token\n\n # Need to fetch new token from Keycloak\n if not self.keycloak_url or not self.client_id or not self.client_secret:\n raise ValueError(\"M2M credentials required but not provided\")\n\n token_url = f\"{self.keycloak_url}/realms/{self.realm}/protocol/openid-connect/token\"\n logger.debug(f\"Requesting new token from {token_url}\")\n\n async with aiohttp.ClientSession() as session:\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n\n try:\n async with session.post(token_url, data=data) as response:\n if response.status != 200:\n error_text = await response.text()\n logger.error(f\"Token request failed: {response.status} - {error_text}\")\n raise Exception(f\"Failed to get token: {response.status}\")\n\n token_data = await response.json()\n self._cached_token = token_data[\"access_token\"]\n expires_in = token_data.get(\"expires_in\", 300)\n self._token_expires_at = current_time + expires_in\n\n logger.info(f\"Token acquired, expires in {expires_in}s\")\n return self._cached_token\n\n except aiohttp.ClientError as e:\n logger.error(f\"Network error getting token: {e}\")\n raise Exception(f\"Network error: {e}\")\n\n async def search_tools(\n self,\n query: str,\n max_results: int = 10,\n entity_types: list[str] | None = None,\n ) -> SearchResponse:\n \"\"\"\n Search for MCP tools using semantic search.\n\n Args:\n query: Natural language search query\n max_results: Maximum number of results to return\n entity_types: Entity types to search (mcp_server, tool, a2a_agent)\n\n Returns:\n SearchResponse with matching servers and tools\n\n Raises:\n Exception: If search fails\n \"\"\"\n logger.info(f\"Semantic search: '{query}' (max_results={max_results})\")\n\n token = await self._get_token()\n search_url = f\"{self.registry_url}/api/search/semantic\"\n\n headers = {\n \"Authorization\": f\"Bearer {token}\",\n \"Content-Type\": \"application/json\",\n }\n\n body = {\n \"query\": query,\n \"max_results\": max_results,\n }\n\n if entity_types:\n body[\"entity_types\"] = entity_types\n\n async with aiohttp.ClientSession() as session:\n try:\n async with session.post(\n search_url,\n headers=headers,\n json=body,\n ) as response:\n if response.status != 200:\n error_text = await response.text()\n logger.error(f\"Search failed: {response.status} - {error_text}\")\n raise Exception(f\"Search failed: {response.status} - {error_text}\")\n\n result = await response.json()\n logger.info(\n f\"Search returned {result.get('total_servers', 0)} servers, \"\n f\"{result.get('total_tools', 0)} tools\"\n )\n\n # Log full response for debugging\n logger.info(\n f\"Full search API response:\\n{json.dumps(result, indent=2, default=str)}\"\n )\n\n return SearchResponse(**result)\n\n except aiohttp.ClientError as e:\n logger.error(f\"Network error during search: {e}\")\n raise Exception(f\"Network error: {e}\")\n\n async def get_server_info(\n self,\n server_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"\n Get detailed information about a specific MCP server.\n\n Uses the /api/servers endpoint with query parameter to find the server.\n\n Args:\n server_path: Path of the server in the registry\n\n Returns:\n Server information dict or None if not found\n \"\"\"\n logger.info(f\"Getting server info for: {server_path}\")\n\n token = await self._get_token()\n # Normalize path - remove leading/trailing slashes\n clean_path = server_path.strip(\"/\")\n\n # Use the servers list endpoint with query to find the specific server\n server_url = f\"{self.registry_url}/api/servers\"\n\n headers = {\n \"Authorization\": f\"Bearer {token}\",\n }\n\n params = {\n \"query\": clean_path,\n }\n\n async with aiohttp.ClientSession() as session:\n try:\n async with session.get(\n server_url,\n headers=headers,\n params=params,\n ) as response:\n if response.status != 200:\n error_text = await response.text()\n logger.error(f\"Get servers failed: {response.status} - {error_text}\")\n return None\n\n result = await response.json()\n\n # Find the matching server in the results\n servers = result if isinstance(result, list) else result.get(\"servers\", [])\n for server in servers:\n srv_path = server.get(\"path\", \"\").strip(\"/\")\n if srv_path == clean_path:\n logger.info(f\"Got server info for {server_path}\")\n return server\n\n logger.warning(f\"Server not found in results: {server_path}\")\n return None\n\n except aiohttp.ClientError as e:\n logger.error(f\"Network error getting server info: {e}\")\n return None\n\n\ndef _format_tool_result(\n tool: ToolSearchResult,\n) -> dict[str, Any]:\n \"\"\"\n Format a tool search result for display to the agent.\n\n The search API returns inputSchema directly, so no additional server lookup is needed.\n\n Args:\n tool: Tool search result\n\n Returns:\n Formatted tool information dict\n \"\"\"\n result = {\n \"tool_name\": tool.tool_name,\n \"server_path\": tool.server_path,\n \"server_name\": tool.server_name,\n \"description\": tool.description or \"No description available\",\n \"relevance_score\": tool.relevance_score,\n \"supported_transports\": [\"streamable_http\"],\n }\n\n # Use inputSchema from search result if available\n if tool.inputSchema:\n result[\"tool_schema\"] = tool.inputSchema\n\n return result\n\n\ndef _format_server_result(\n server: ServerSearchResult,\n) -> dict[str, Any]:\n \"\"\"\n Format a server search result for display to the agent.\n\n Args:\n server: Server search result\n\n Returns:\n Formatted server information dict\n \"\"\"\n matching_tools = []\n for t in server.matching_tools:\n tool_info = {\n \"tool_name\": t.tool_name,\n \"description\": t.description,\n \"relevance_score\": t.relevance_score,\n }\n # Note: inputSchema is available in the tools[] array, not matching_tools\n matching_tools.append(tool_info)\n\n return {\n \"server_path\": server.path,\n \"server_name\": server.server_name,\n \"description\": server.description or \"No description available\",\n \"tags\": server.tags,\n \"num_tools\": server.num_tools,\n \"is_enabled\": server.is_enabled,\n \"relevance_score\": server.relevance_score,\n \"matching_tools\": matching_tools,\n }\n" }, { "path": "agents/system_prompt.txt", "content": "\nYou are a highly capable AI assistant designed to solve a wide range of problems for users. You have access to built-in tools and can discover additional specialized tools as needed.\n\nIf there is a user question that requires understanding of the current time to answer it, for example\nit needs to determine a date range then remember that you know the current UTC datetime is {current_utc_time}\nand determine the date range based on that.\n\nMCP Registry URL: {mcp_registry_url}\n\n\n\nYou have direct access to these built-in tools:\n- calculator: For performing mathematical calculations and arithmetic operations\n- search_registry_tools: For discovering MCP tools using semantic search on the registry\n- invoke_mcp_tool: For invoking tools on MCP servers (authentication handled automatically)\n\nTool Discovery and Invocation Workflow:\n1. Use search_registry_tools to find tools that match your needs:\n search_registry_tools(\"description of needed capability\", max_results=10)\n\n2. The search returns tools with these important fields:\n - tool_name: Name of the tool to invoke\n - server_path: Path to use as server_name in invoke_mcp_tool\n - description: What the tool does\n - tool_schema: Input parameters required\n - supported_transports: Transport protocol to use\n - auth_provider: Authentication provider if needed (IMPORTANT!)\n\n3. Use invoke_mcp_tool with the discovered information:\n\nExample workflow:\n# Step 1: Search for tools\nsearch_registry_tools(\"get the current time\")\n\n# Step 2: Invoke the discovered tool\ninvoke_mcp_tool(\n mcp_registry_url=\"{mcp_registry_url}\",\n server_name=\"/currenttime\",\n tool_name=\"current_time_by_timezone\",\n arguments={{\"tz_name\": \"America/New_York\"}},\n supported_transports=[\"streamable_http\"],\n auth_provider=\"bedrock-agentcore\"\n)\n\nFor Atlassian services (Jira, Confluence):\ninvoke_mcp_tool(\n mcp_registry_url=\"{mcp_registry_url}\",\n server_name=\"/atlassian\",\n tool_name=\"jira_get_issue\",\n arguments={{\"issue_key\": \"PROJ-123\"}},\n supported_transports=[\"streamable_http\"],\n auth_provider=\"atlassian\"\n)\n\n\n\n1. Understand the user's request completely\n2. **First, check if you can handle the request with your existing available tools**\n3. **If you need specialized capabilities, use search_registry_tools to discover MCP tools**\n4. For calculations, use the calculator tool\n5. For discovered tools, use invoke_mcp_tool to call them (authentication is handled automatically)\n6. Execute the appropriate tools with proper arguments\n7. Present results clearly to the user\n\n\n\nAlways be transparent about what tools you're using.\nWhen using MCP tools, explain which tool you're calling.\nFor complex tasks, break them down into steps using different tools as needed.\n\n**CRITICAL: When calling invoke_mcp_tool, always check the search_registry_tools results for:**\n- **server_path**: Use this as the server_name parameter\n- **auth_provider**: Include this parameter if present - essential for external services like Atlassian, AWS services, etc.\n- **tool_schema**: Review this to understand required arguments\n\nPrioritize security and privacy. Never use tools to access, generate, or share harmful, illegal, or unethical content.\n" }, { "path": "api/.gitignore", "content": "# Temporary JSON files created during testing\n*.json\n\n# Token files\n.token\n" }, { "path": "api/README.md", "content": "# MCP Gateway Registry Management API\n\nCommand-line tools for managing users, groups, servers, and agents in the MCP Gateway Registry.\n\n## API Specification\n\n**Live OpenAPI Specification** (Always Up-to-Date):\n\nAccess the OpenAPI specification directly from your running registry instance:\n\n- **Localhost**: `http://localhost/openapi.json`\n- **Production**: `https://registry.us-east-1.example.com/openapi.json` (replace with your actual registry endpoint)\n\nThe live OpenAPI spec is auto-generated and always reflects the current API implementation.\n\n**Reference OpenAPI Specification** (May Not Be Latest):\n\nA reference copy is available at [openapi.json](openapi.json) for offline reference. However, this may not reflect the latest changes. Always use the live endpoint from your running registry for the most current API specification.\n\n## Quick Start\n\n### Local Development Testing\n\n```bash\n# 1. Start local services\ndocker-compose up -d\n\n# 2. Generate credentials for localhost\ncd credentials-provider\n./generate_creds.sh\ncd ..\n\n# 3. Run management commands\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \n\n# Example: Create a user\nuv run python api/registry_management.py \\\n --token-file .oauth-tokens/ingress.json \\\n user-create-human \\\n --username johndoe \\\n --email john@example.com \\\n --first-name John \\\n --last-name Doe \\\n --groups mcp-registry-user \\\n --password MySecurePass123\n```\n\n### Production (AWS ECS Deployment)\n\n```bash\n# 1. Get M2M token from Keycloak (requires AWS credentials)\n./api/get-m2m-token.sh \\\n --aws-region us-east-1 \\\n --keycloak-url https://keycloak.us-east-1.example.com \\\n --output-file api/.token \\\n registry-admin-bot\n\n# 2. Run management commands against production\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n --aws-region us-east-1 \\\n --keycloak-url https://keycloak.us-east-1.example.com \\\n \n\n# Example: List all users in production\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n --aws-region us-east-1 \\\n --keycloak-url https://keycloak.us-east-1.example.com \\\n user-list\n```\n\n## Token Generation\n\n### For Localhost\nUse `credentials-provider/generate_creds.sh` which creates tokens for local Keycloak instance:\n\n**Using generate_creds.sh (all services):**\n```bash\ncd credentials-provider && ./generate_creds.sh && cd ..\n```\nToken saved to: `.oauth-tokens/ingress.json`\n\n**Using generate-agent-token.sh (specific M2M bot):**\n```bash\n# Generate token for default bot (mcp-gateway-m2m)\n./keycloak/setup/generate-agent-token.sh\n\n# Generate token for custom M2M bot\n./keycloak/setup/generate-agent-token.sh lob1-bot\n```\nTokens saved to: `.oauth-tokens/{agent-name}.json`\n\n### For Production (AWS)\nUse `api/get-m2m-token.sh` which retrieves tokens from AWS-deployed Keycloak:\n\n**Default admin bot:**\n```bash\n./api/get-m2m-token.sh \\\n --aws-region us-east-1 \\\n --keycloak-url https://keycloak.us-east-1.example.com \\\n --output-file api/.token \\\n registry-admin-bot\n```\n\n**Custom M2M bot account:**\n```bash\n./api/get-m2m-token.sh \\\n --aws-region us-east-1 \\\n --keycloak-url https://keycloak.us-east-1.example.com \\\n --output-file api/.token \\\n lob1-bot\n```\n\nToken saved to: `api/.token`\n\n**Notes:**\n- `get-m2m-token.sh` is for AWS deployments only and requires AWS credentials\n- It retrieves secrets from SSM Parameter Store\n- You can specify any M2M service account name as the last argument\n- The script automatically handles both `client-name` and `service-account-client-name` formats\n\n## End-to-End Testing\n\n### Test Localhost\n```bash\n./api/test-management-api-e2e.sh --token-file .oauth-tokens/ingress.json\n```\n\n### Test Production\n```bash\n./api/test-management-api-e2e.sh \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n --aws-region us-east-1 \\\n --keycloak-url https://keycloak.us-east-1.example.com\n```\n\n## Common Management Operations\n\n### User Management\n\n```bash\n# Create human user\nuv run python api/registry_management.py --token-file \\\n user-create-human \\\n --username alice \\\n --email alice@example.com \\\n --first-name Alice \\\n --last-name Smith \\\n --groups engineering \\\n --password SecurePass123\n\n# Create M2M service account\nuv run python api/registry_management.py --token-file \\\n user-create-m2m \\\n --name service-bot \\\n --groups engineering \\\n --description \"Automated service account\"\n\n# List users\nuv run python api/registry_management.py --token-file user-list\n\n# Delete user\nuv run python api/registry_management.py --token-file \\\n user-delete --username alice --force\n```\n\n### Group Management\n\n```bash\n# Create group\nuv run python api/registry_management.py --token-file \\\n group-create \\\n --name engineering \\\n --description \"Engineering team\"\n\n# List groups\nuv run python api/registry_management.py --token-file group-list\n\n# Delete group\nuv run python api/registry_management.py --token-file \\\n group-delete --name engineering --force\n```\n\n### Server Registration\n\n```bash\n# Register server from JSON config\nuv run python api/registry_management.py --token-file \\\n register --config server-config.json\n\n# List servers\nuv run python api/registry_management.py --token-file list\n\n# Remove server\nuv run python api/registry_management.py --token-file \\\n remove --path /my-server --force\n```\n\n### Agent Registration\n\n```bash\n# Register agent from JSON config\nuv run python api/registry_management.py --token-file \\\n agent-register --config agent-config.json\n\n# List agents\nuv run python api/registry_management.py --token-file agent-list\n\n# Delete agent\nuv run python api/registry_management.py --token-file \\\n agent-delete --path /my-agent --force\n```\n\n## Environment Summary\n\n| Environment | Token Script | Registry URL | Keycloak URL |\n|-------------|--------------|--------------|--------------|\n| **Localhost** | `credentials-provider/generate_creds.sh` or `keycloak/setup/generate-agent-token.sh` | `http://localhost` (default) | `http://localhost:8080` (default) |\n| **Production** | `api/get-m2m-token.sh --aws-region ... --keycloak-url ...` | `https://registry.us-east-1.example.com` | `https://keycloak.us-east-1.example.com` |\n\n## Files\n\n- `registry_management.py` - Main CLI for user/group/server/agent management\n- `registry_client.py` - Python client library for Registry API\n- `get-m2m-token.sh` - Get M2M tokens from AWS Keycloak (production only)\n- `test-management-api-e2e.sh` - End-to-end test suite\n- `.gitignore` - Excludes token files and temporary JSON files\n\n## Requirements\n\n- Python 3.14+ with `uv` package manager\n- For production: AWS credentials with access to SSM Parameter Store\n- For localhost: Running `docker-compose` stack with Keycloak\n\n## Authentication\n\nAll commands require a valid JWT token:\n- **Localhost**: Session-based tokens from `generate_creds.sh`\n- **Production**: M2M client credentials from `get-m2m-token.sh`\n\nTokens are passed via `--token-file` parameter and must have appropriate scopes for the operations being performed.\n" }, { "path": "api/USER-GROUP-MANAGEMENT.md", "content": "# User and Group Management Guide\n\nThis guide provides the correct sequence of operations for managing users, groups, and scopes in the MCP Gateway Registry.\n\n## Prerequisites\n\nSet up environment variables for easier command execution:\n\n```bash\nexport REGISTRY_URL=\"https://registry.us-east-1.aroraai.people.aws.dev\"\nexport AWS_REGION=\"us-east-1\"\nexport KEYCLOAK_URL=\"https://kc.us-east-1.aroraai.people.aws.dev\"\n```\n\n## Architecture Overview\n\nThe system has two layers of configuration:\n\n1. **Keycloak IAM Groups**: User membership and authentication (who belongs to which group)\n2. **DocumentDB Scopes**: Authorization rules (what each group can access)\n\nBoth must be configured for users to have proper access.\n\n## Complete Workflow\n\n### Step 1: Import Group Scope Configuration\n\nImport the group's authorization rules (scopes) into DocumentDB. This defines what servers/tools the group can access.\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n import-group \\\n --file cli/examples/currenttime-users.json\n```\n\n**What this does:**\n- Creates scope configuration in DocumentDB\n- If `\"create_in_idp\": true` is in the JSON, it also creates the IdP group (Keycloak/Entra)\n- Defines server access rules, UI permissions, and group mappings\n\n**Example JSON structure** (cli/examples/currenttime-users.json):\n```json\n{\n \"scope_name\": \"currenttime-users\",\n \"description\": \"Users with access to currenttime server\",\n \"server_access\": [\n {\n \"server\": \"currenttime\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"current_time_by_timezone\"]\n }\n ],\n \"group_mappings\": [\"currenttime-users\"],\n \"ui_permissions\": {\n \"list_service\": [\"currenttime\"],\n \"health_check_service\": [\"currenttime\"]\n },\n \"create_in_idp\": true\n}\n```\n\n### Step 2: Create IAM Group (if not auto-created)\n\nIf the group wasn't auto-created in Step 1 (no `\"create_in_idp\": true`), create it manually:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n group-create \\\n --name currenttime-users \\\n --description \"Users with access to currenttime server\"\n```\n\n**Note:** If the group already exists, this will fail with \"Group already exists\" error. You can verify with:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n group-list\n```\n\n### Step 3: Create Human User Account\n\nCreate a human user and assign them to the group:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-create-human \\\n --username ctuser \\\n --email ctuser@example.com \\\n --first-name Current \\\n --last-name Time \\\n --password riv2025 \\\n --groups currenttime-users\n```\n\n**Important:**\n- Password is only set during creation\n- If user already exists, this fails with \"User already exists\"\n- Users can be assigned to multiple groups by comma-separating them: `--groups group1,group2`\n\n### Step 4: Create M2M Service Account\n\nCreate a machine-to-machine service account for programmatic access:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-create-m2m \\\n --name currenttime-service-bot \\\n --groups currenttime-users \\\n --description \"Service account for currenttime server automation\"\n```\n\n**Important:**\n- Save the client_id and client_secret immediately - the secret is only shown once\n- Service accounts use OAuth2 client credentials flow\n\n## Verification Commands\n\n### List All Users\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-list\n```\n\n### List All Groups\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n group-list\n```\n\n### List Scope Groups (DocumentDB)\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n list-groups\n```\n\n### Describe Specific Group\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n describe-group \\\n --group-name currenttime-users\n```\n\n## Troubleshooting\n\n### User Already Exists\n\nIf you get \"User already exists\" error:\n\n1. Check if user exists:\n ```bash\n uv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-list | grep username\n ```\n\n2. Either use the existing user or delete and recreate:\n ```bash\n # Delete existing user\n uv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-delete \\\n --username ctuser\n\n # Then recreate\n uv run python api/registry_management.py ... user-create-human ...\n ```\n\n### Group Already Exists\n\nIf you get \"Group already exists\" error, the group is already configured. Verify with:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n group-list | grep currenttime-users\n```\n\n### Password Reset\n\nCurrently, password reset must be done through Keycloak admin UI or by deleting and recreating the user with a new password.\n\n**Note:** For the existing user `ctuser`, if the password is unknown, you'll need to either:\n- Delete and recreate the user with a known password\n- Use Keycloak admin UI to reset the password\n- Contact an administrator\n\n## Current Status for ctuser\n\nThe user `ctuser` currently exists with:\n- **Username:** ctuser\n- **Email:** ctuser@example.com\n- **Name:** CT User\n- **Groups:** currenttime-users\n- **Status:** Enabled\n- **Password:** Unknown (was set during initial creation)\n\nIf you need to use this account and don't know the password, delete and recreate it:\n\n```bash\n# Delete existing user\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-delete \\\n --username ctuser\n\n# Recreate with known password\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-create-human \\\n --username ctuser \\\n --email ctuser@example.com \\\n --first-name Current \\\n --last-name Time \\\n --password riv2025 \\\n --groups currenttime-users\n```\n\n## Quick Reference\n\n### Create Everything from Scratch\n\n```bash\n# 1. Import group scope configuration (creates IdP group if create_in_idp=true)\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n import-group --file cli/examples/currenttime-users.json\n\n# 2. Create human user (if group doesn't auto-create users)\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-create-human \\\n --username ctuser \\\n --email ctuser@example.com \\\n --first-name Current \\\n --last-name Time \\\n --password riv2025 \\\n --groups currenttime-users\n\n# 3. Create M2M service account\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n user-create-m2m \\\n --name currenttime-service-bot \\\n --groups currenttime-users \\\n --description \"Service account for currenttime automation\"\n```\n\n## Federation Management\n\nFor importing servers from Anthropic's registry:\n\n```bash\n# Save federation configuration\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n federation-save \\\n --config cli/examples/federation-config-example.json\n\n# Sync federated servers\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --aws-region $AWS_REGION \\\n --keycloak-url $KEYCLOAK_URL \\\n federation-sync\n```\n" }, { "path": "api/get-m2m-token.sh", "content": "#!/bin/bash\n\n# Script to get M2M JWT token for a Keycloak client with smart caching\n# Usage: ./get-m2m-token.sh [OPTIONS] [client-name]\n#\n# Options:\n# --aws-region REGION AWS region (overrides AWS_REGION env var)\n# --keycloak-url URL Keycloak base URL (overrides KEYCLOAK_URL env var)\n# --output-file FILE Save token to file instead of printing to stdout\n# --help Show this help message\n#\n# Environment variables (used if command-line options not provided):\n# AWS_REGION - AWS region where Keycloak and SSM are deployed (e.g., us-east-1)\n# KEYCLOAK_URL - Keycloak base URL (e.g., https://kc.us-east-1.mycorp.click)\n#\n# This script implements smart token management:\n# 1. First checks SSM Parameter Store for cached token\n# 2. Validates token expiration (with 60 second buffer)\n# 3. Only fetches new token from Keycloak if needed\n# 4. Stores new tokens in SSM (but NOT in local files by default)\n# 5. Outputs the token to stdout (or saves to file if --output-file is specified)\n\nset -e\n\n# Get script directory\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nTERRAFORM_OUTPUTS=\"$SCRIPT_DIR/terraform-outputs.json\"\nPARENT_DIR=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Colors\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nRED='\\033[0;31m'\nNC='\\033[0m'\n\n# Parse command-line arguments\nCLIENT_NAME=\"\"\nCLI_AWS_REGION=\"\"\nCLI_KEYCLOAK_URL=\"\"\nOUTPUT_FILE=\"\"\n\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --aws-region)\n CLI_AWS_REGION=\"$2\"\n shift 2\n ;;\n --keycloak-url)\n CLI_KEYCLOAK_URL=\"$2\"\n shift 2\n ;;\n --output-file)\n OUTPUT_FILE=\"$2\"\n shift 2\n ;;\n --help)\n echo \"Usage: $0 [OPTIONS] [client-name]\"\n echo \"\"\n echo \"Options:\"\n echo \" --aws-region REGION AWS region (overrides AWS_REGION env var)\"\n echo \" --keycloak-url URL Keycloak base URL (overrides KEYCLOAK_URL env var)\"\n echo \" --output-file FILE Save token to file instead of printing to stdout\"\n echo \" --help Show this help message\"\n echo \"\"\n echo \"Environment variables:\"\n echo \" AWS_REGION - AWS region where Keycloak and SSM are deployed\"\n echo \" KEYCLOAK_URL - Keycloak base URL\"\n exit 0\n ;;\n -*)\n echo -e \"${RED}Error: Unknown option: $1${NC}\" >&2\n exit 1\n ;;\n *)\n CLIENT_NAME=\"$1\"\n shift\n ;;\n esac\ndone\n\n# Command-line args override environment variables\nAWS_REGION=\"${CLI_AWS_REGION:-$AWS_REGION}\"\nKEYCLOAK_URL=\"${CLI_KEYCLOAK_URL:-$KEYCLOAK_URL}\"\n\n# Configuration - require mandatory parameters\nif [ -z \"$AWS_REGION\" ]; then\n echo -e \"${RED}Error: AWS_REGION is required${NC}\" >&2\n echo -e \"${RED}Set via environment variable or --aws-region option:${NC}\" >&2\n echo -e \"${RED} export AWS_REGION=us-east-1${NC}\" >&2\n echo -e \"${RED} OR${NC}\" >&2\n echo -e \"${RED} $0 --aws-region us-east-1 ${NC}\" >&2\n exit 1\nfi\n\nif [ -z \"$KEYCLOAK_URL\" ]; then\n echo -e \"${RED}Error: KEYCLOAK_URL is required${NC}\" >&2\n echo -e \"${RED}Set via environment variable or --keycloak-url option:${NC}\" >&2\n echo -e \"${RED} export KEYCLOAK_URL=https://kc.us-east-1.mycorp.click${NC}\" >&2\n echo -e \"${RED} OR${NC}\" >&2\n echo -e \"${RED} $0 --keycloak-url https://kc.us-east-1.mycorp.click ${NC}\" >&2\n exit 1\nfi\n\nREALM=\"mcp-gateway\"\nCLIENT_NAME=\"${CLIENT_NAME:-registry-admin-bot}\"\nORIGINAL_CLIENT_NAME=\"${CLIENT_NAME}\"\nSSM_TOKEN_PARAM=\"/keycloak/clients/${CLIENT_NAME}/jwt_token\"\nEXPIRATION_BUFFER=60 # Refresh token if expires within 60 seconds\n\necho -e \"${YELLOW}Getting JWT token for client: $CLIENT_NAME${NC}\" >&2\necho -e \"${YELLOW}Using AWS region: $AWS_REGION${NC}\" >&2\necho -e \"${YELLOW}Using Keycloak URL: $KEYCLOAK_URL${NC}\" >&2\necho \"\" >&2\n\n# Function to check if token is expired\nis_token_expired() {\n local expires_at=$1\n local current_time=$(date +%s)\n local time_until_expiry=$((expires_at - current_time))\n\n if [ $time_until_expiry -le $EXPIRATION_BUFFER ]; then\n return 0 # Token is expired or will expire soon\n else\n return 1 # Token is still valid\n fi\n}\n\n# Step 1: Try to get cached token from SSM Parameter Store (skip for local mode)\nif [ \"$AWS_REGION\" != \"local\" ]; then\n echo -e \"${YELLOW}Step 1: Checking SSM Parameter Store for cached token...${NC}\" >&2\n\n # Get the SSM parameter value (which is a JSON string)\n # Try the original client name first\n SSM_PARAM_VALUE=$(aws ssm get-parameter \\\n --name \"$SSM_TOKEN_PARAM\" \\\n --with-decryption \\\n --region \"$AWS_REGION\" 2>/dev/null | jq -r '.Parameter.Value // empty' 2>/dev/null || echo \"\")\nelse\n echo -e \"${YELLOW}Step 1: Skipping SSM cache check (local mode)${NC}\" >&2\n SSM_PARAM_VALUE=\"\"\nfi\n\n# If not found, try with service-account- prefix\nif [ -z \"$SSM_PARAM_VALUE\" ] || [ \"$SSM_PARAM_VALUE\" = \"null\" ]; then\n SSM_TOKEN_PARAM_ALT=\"/keycloak/clients/service-account-${ORIGINAL_CLIENT_NAME}/jwt_token\"\n SSM_PARAM_VALUE=$(aws ssm get-parameter \\\n --name \"$SSM_TOKEN_PARAM_ALT\" \\\n --with-decryption \\\n --region \"$AWS_REGION\" 2>/dev/null | jq -r '.Parameter.Value // empty' 2>/dev/null || echo \"\")\n if [ -n \"$SSM_PARAM_VALUE\" ] && [ \"$SSM_PARAM_VALUE\" != \"null\" ]; then\n # Use the alternate parameter name for storing the token later\n SSM_TOKEN_PARAM=\"$SSM_TOKEN_PARAM_ALT\"\n fi\nfi\n\nif [ -n \"$SSM_PARAM_VALUE\" ] && [ \"$SSM_PARAM_VALUE\" != \"null\" ]; then\n echo -e \"${GREEN}Found cached token in SSM at $SSM_TOKEN_PARAM${NC}\" >&2\n\n # Parse the JSON value (Parameter.Value is itself a JSON string)\n CACHED_ACCESS_TOKEN=$(echo \"$SSM_PARAM_VALUE\" | jq -r '.access_token // empty' 2>/dev/null)\n CACHED_EXPIRES_AT=$(echo \"$SSM_PARAM_VALUE\" | jq -r '.expires_at // empty' 2>/dev/null)\n CACHED_EXPIRES_IN=$(echo \"$SSM_PARAM_VALUE\" | jq -r '.expires_in // 300' 2>/dev/null)\n\n if [ -n \"$CACHED_ACCESS_TOKEN\" ] && [ -n \"$CACHED_EXPIRES_AT\" ]; then\n # Check if token is still valid\n if ! is_token_expired \"$CACHED_EXPIRES_AT\"; then\n CURRENT_TIME=$(date +%s)\n TIME_UNTIL_EXPIRY=$((CACHED_EXPIRES_AT - CURRENT_TIME))\n\n echo -e \"${GREEN}Cached token is still valid (expires in ${TIME_UNTIL_EXPIRY} seconds)${NC}\" >&2\n echo -e \"${GREEN}Using cached token from SSM${NC}\" >&2\n echo \"\" >&2\n echo -e \"${GREEN}Successfully retrieved cached token!${NC}\" >&2\n\n # Output token to file or stdout\n if [ -n \"$OUTPUT_FILE\" ]; then\n echo \"$CACHED_ACCESS_TOKEN\" > \"$OUTPUT_FILE\"\n echo \" Token saved to: $OUTPUT_FILE\" >&2\n else\n echo \"$CACHED_ACCESS_TOKEN\"\n fi\n exit 0\n else\n echo -e \"${YELLOW}Cached token is expired or will expire soon${NC}\" >&2\n echo -e \"${YELLOW}Will fetch new token from Keycloak...${NC}\" >&2\n fi\n else\n echo -e \"${YELLOW}Invalid cached token format${NC}\" >&2\n echo -e \"${YELLOW}Will fetch new token from Keycloak...${NC}\" >&2\n fi\nelse\n echo -e \"${YELLOW}No cached token found in SSM${NC}\" >&2\n echo -e \"${YELLOW}Will fetch new token from Keycloak...${NC}\" >&2\nfi\n\necho \"\" >&2\n\n# Step 2: Get new token from Keycloak\necho -e \"${YELLOW}Step 2: Fetching new token from Keycloak...${NC}\" >&2\necho \"Keycloak URL: $KEYCLOAK_URL\" >&2\n\n# Get Keycloak admin password from environment variable first, then SSM\nif [ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ]; then\n echo \"Attempting to retrieve Keycloak admin password from SSM...\" >&2\n KEYCLOAK_ADMIN_PASSWORD=$(aws ssm get-parameter \\\n --name \"/keycloak/admin_password\" \\\n --with-decryption \\\n --region \"$AWS_REGION\" 2>/dev/null | jq -r '.Parameter.Value // empty' 2>/dev/null)\nfi\n\nif [ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ] || [ \"$KEYCLOAK_ADMIN_PASSWORD\" = \"null\" ]; then\n echo -e \"${RED}Error: Could not retrieve Keycloak admin password${NC}\" >&2\n echo -e \"${RED}Set KEYCLOAK_ADMIN_PASSWORD environment variable or ensure SSM parameter exists${NC}\" >&2\n exit 1\nfi\n\n# Get admin token\necho \"Getting admin token...\" >&2\nADMIN_TOKEN=$(curl -s -X POST \"${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=admin\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" 2>/dev/null | jq -r '.access_token // empty' 2>/dev/null)\n\nif [ -z \"$ADMIN_TOKEN\" ] || [ \"$ADMIN_TOKEN\" = \"null\" ]; then\n echo -e \"${RED}Error: Failed to get admin token${NC}\" >&2\n exit 1\nfi\n\necho -e \"${GREEN}Admin token obtained${NC}\" >&2\n\n# Get client UUID\n# Try with the provided name first, then try with service-account- prefix\necho \"Looking up client UUID...\" >&2\nCLIENT_UUID=$(curl -s -H \"Authorization: Bearer ${ADMIN_TOKEN}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=${CLIENT_NAME}\" 2>/dev/null | \\\n jq -r 'if type == \"array\" then (.[0].id // empty) else empty end' 2>/dev/null)\n\n# If not found, try with service-account- prefix (Keycloak's naming convention for service accounts)\nif [ -z \"$CLIENT_UUID\" ]; then\n echo \"Client '${CLIENT_NAME}' not found, trying 'service-account-${CLIENT_NAME}'...\" >&2\n CLIENT_NAME=\"service-account-${CLIENT_NAME}\"\n # Update SSM parameter path to match the actual client name\n SSM_TOKEN_PARAM=\"/keycloak/clients/${CLIENT_NAME}/jwt_token\"\n CLIENT_UUID=$(curl -s -H \"Authorization: Bearer ${ADMIN_TOKEN}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=${CLIENT_NAME}\" 2>/dev/null | \\\n jq -r 'if type == \"array\" then (.[0].id // empty) else empty end' 2>/dev/null)\nfi\n\nif [ -z \"$CLIENT_UUID\" ]; then\n echo -e \"${RED}Error: Client '${CLIENT_NAME}' not found${NC}\" >&2\n exit 1\nfi\n\necho -e \"${GREEN}Client UUID: ${CLIENT_UUID}${NC}\" >&2\n\n# Get client secret\necho \"Retrieving client secret...\" >&2\nCLIENT_SECRET=$(curl -s -H \"Authorization: Bearer ${ADMIN_TOKEN}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${CLIENT_UUID}/client-secret\" 2>/dev/null | \\\n jq -r '.value // empty' 2>/dev/null)\n\nif [ -z \"$CLIENT_SECRET\" ]; then\n echo -e \"${RED}Error: Could not retrieve client secret${NC}\" >&2\n exit 1\nfi\n\necho -e \"${GREEN}Client secret retrieved${NC}\" >&2\n\n# Get M2M token using client credentials\necho \"Requesting M2M access token...\" >&2\n\nTOKEN_RESPONSE=$(curl -s -X POST \"${KEYCLOAK_URL}/realms/${REALM}/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id=${CLIENT_NAME}\" \\\n -d \"client_secret=${CLIENT_SECRET}\" \\\n -d \"grant_type=client_credentials\" 2>/dev/null)\n\nACCESS_TOKEN=$(echo \"$TOKEN_RESPONSE\" | jq -r '.access_token // empty' 2>/dev/null)\n\nif [ -z \"$ACCESS_TOKEN\" ]; then\n echo -e \"${RED}Error: Failed to get access token${NC}\" >&2\n ERROR_MSG=$(echo \"$TOKEN_RESPONSE\" | jq -r '.error_description // .error // \"Unknown error\"' 2>/dev/null)\n echo -e \"${RED}Error details: $ERROR_MSG${NC}\" >&2\n exit 1\nfi\n\n# Calculate expiration time\nEXPIRES_IN=$(echo \"$TOKEN_RESPONSE\" | jq -r '.expires_in // 300' 2>/dev/null)\nCURRENT_TIME=$(date +%s)\nEXPIRES_AT=$((CURRENT_TIME + EXPIRES_IN))\n\necho -e \"${GREEN}Successfully obtained new access token!${NC}\" >&2\necho \"Expires in: ${EXPIRES_IN} seconds\" >&2\n\n# Step 3: Store token in SSM Parameter Store (skip for local mode)\nif [ \"$AWS_REGION\" != \"local\" ]; then\n echo \"\" >&2\n echo -e \"${YELLOW}Step 3: Storing token in SSM Parameter Store...${NC}\" >&2\n\n TOKEN_JSON=$(cat </dev/null 2>&1\n\n if [ $? -eq 0 ]; then\n echo -e \"${GREEN}Token stored in SSM: $SSM_TOKEN_PARAM${NC}\" >&2\n else\n echo -e \"${YELLOW}Warning: Failed to store token in SSM (continuing anyway)${NC}\" >&2\n fi\nelse\n echo \"\" >&2\n echo -e \"${YELLOW}Step 3: Skipping SSM token storage (local mode)${NC}\" >&2\nfi\n\necho \"\" >&2\necho -e \"${GREEN}=== Token Management Complete ===${NC}\" >&2\necho \"\" >&2\necho \"Token details:\" >&2\necho \" Client: $CLIENT_NAME\" >&2\necho \" Expires in: ${EXPIRES_IN} seconds\" >&2\necho \" Expires at: $(date -d @${EXPIRES_AT} 2>/dev/null || date -r ${EXPIRES_AT} 2>/dev/null || echo $EXPIRES_AT)\" >&2\necho \" SSM location: $SSM_TOKEN_PARAM\" >&2\n\n# Output the token to stdout or save to file\nif [ -n \"$OUTPUT_FILE\" ]; then\n echo \"$ACCESS_TOKEN\" > \"$OUTPUT_FILE\"\n echo \" Token saved to: $OUTPUT_FILE\" >&2\n echo \"\" >&2\nelse\n echo \"\" >&2\n # Output the token to stdout for consumption by other scripts\n echo \"$ACCESS_TOKEN\"\nfi\n\n# Also save to .token file in the script directory for local convenience\nif [ \"$AWS_REGION\" = \"local\" ]; then\n TOKEN_FILE=\"${SCRIPT_DIR}/.token\"\n echo \"$ACCESS_TOKEN\" > \"$TOKEN_FILE\"\n echo \" Token also saved to: $TOKEN_FILE\" >&2\nfi\n" }, { "path": "api/populate-registry.sh", "content": "#!/bin/bash\n# Populate MCP Gateway Registry with example servers and agents\n# This script registers all example MCP servers, A2A agents, and configures federation\nset -e\n\n# Colors\nGREEN='\\033[0;32m'\nBLUE='\\033[0;34m'\nYELLOW='\\033[1;33m'\nRED='\\033[0;31m'\nNC='\\033[0m'\n\n# Get script directory\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nREPO_ROOT=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Function to show usage\nshow_usage() {\n echo \"Usage: $0 [OPTIONS]\"\n echo \"\"\n echo \"Options:\"\n echo \" --registry-url Registry URL (required if REGISTRY_URL env var not set)\"\n echo \" --keycloak-url Keycloak URL (required if KEYCLOAK_URL env var not set)\"\n echo \" --aws-region AWS region (default: us-east-1)\"\n echo \" --token-file Path to existing token file (optional - will generate if not provided)\"\n echo \" --help Show this help message\"\n echo \"\"\n echo \"Examples:\"\n echo \" # Using command-line arguments\"\n echo \" $0 \\\\\"\n echo \" --registry-url https://registry.us-east-1.example.com \\\\\"\n echo \" --keycloak-url https://kc.us-east-1.example.com \\\\\"\n echo \" --aws-region us-east-1\"\n echo \"\"\n echo \" # Using environment variables\"\n echo \" export REGISTRY_URL=https://registry.us-east-1.example.com\"\n echo \" export KEYCLOAK_URL=https://kc.us-east-1.example.com\"\n echo \" export AWS_REGION=us-east-1\"\n echo \" $0\"\n echo \"\"\n echo \" # Using existing token file\"\n echo \" $0 \\\\\"\n echo \" --registry-url https://registry.us-east-1.example.com \\\\\"\n echo \" --keycloak-url https://kc.us-east-1.example.com \\\\\"\n echo \" --token-file /path/to/token.json\"\n echo \"\"\n}\n\n# Parse command-line arguments\nREGISTRY_URL_ARG=\"\"\nKEYCLOAK_URL_ARG=\"\"\nAWS_REGION_ARG=\"\"\nTOKEN_FILE_ARG=\"\"\n\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --registry-url)\n REGISTRY_URL_ARG=\"$2\"\n shift 2\n ;;\n --keycloak-url)\n KEYCLOAK_URL_ARG=\"$2\"\n shift 2\n ;;\n --aws-region)\n AWS_REGION_ARG=\"$2\"\n shift 2\n ;;\n --token-file)\n TOKEN_FILE_ARG=\"$2\"\n shift 2\n ;;\n --help)\n show_usage\n exit 0\n ;;\n *)\n echo -e \"${RED}Error: Unknown option: $1${NC}\"\n echo \"\"\n show_usage\n exit 1\n ;;\n esac\ndone\n\necho -e \"${BLUE}========================================${NC}\"\necho -e \"${BLUE}MCP Gateway Registry Population Script${NC}\"\necho -e \"${BLUE}========================================${NC}\"\necho \"\"\n\n# Resolve configuration from arguments or environment variables\nREGISTRY_URL=\"${REGISTRY_URL_ARG:-${REGISTRY_URL:-}}\"\nKEYCLOAK_URL=\"${KEYCLOAK_URL_ARG:-${KEYCLOAK_URL:-}}\"\nAWS_REGION=\"${AWS_REGION_ARG:-${AWS_REGION:-us-east-1}}\"\nTOKEN_FILE=\"${TOKEN_FILE_ARG:-${SCRIPT_DIR}/.token}\"\n\n# Validate required parameters\nif [[ -z \"$REGISTRY_URL\" ]]; then\n echo -e \"${RED}Error: REGISTRY_URL is required${NC}\"\n echo \"\"\n show_usage\n exit 1\nfi\n\nif [[ -z \"$KEYCLOAK_URL\" ]]; then\n echo -e \"${RED}Error: KEYCLOAK_URL is required${NC}\"\n echo \"\"\n show_usage\n exit 1\nfi\n\necho -e \"${BLUE}Configuration:${NC}\"\necho \" Registry URL: $REGISTRY_URL\"\necho \" Keycloak URL: $KEYCLOAK_URL\"\necho \" AWS Region: $AWS_REGION\"\necho \" Token File: $TOKEN_FILE\"\necho \"\"\n\n# Get M2M token if not provided\nif [[ -n \"$TOKEN_FILE_ARG\" && -f \"$TOKEN_FILE\" ]]; then\n echo -e \"${YELLOW}Step 1: Using provided token file...${NC}\"\n echo -e \"${GREEN}✓ Token file found: $TOKEN_FILE${NC}\"\nelse\n echo -e \"${YELLOW}Step 1: Getting M2M authentication token...${NC}\"\n \"${SCRIPT_DIR}/get-m2m-token.sh\" \\\n --aws-region \"$AWS_REGION\" \\\n --keycloak-url \"$KEYCLOAK_URL\" \\\n --output-file \"$TOKEN_FILE\" \\\n registry-admin-bot\n\n if [[ ! -f \"$TOKEN_FILE\" ]]; then\n echo -e \"${RED}Error: Failed to get M2M token${NC}\"\n exit 1\n fi\n echo -e \"${GREEN}✓ Token acquired${NC}\"\nfi\necho \"\"\n\n# MCP Server configs\nSERVERS=(\n \"cli/examples/cloudflare-docs-server-config.json\"\n \"cli/examples/context7-server-config.json\"\n \"cli/examples/currenttime.json\"\n \"cli/examples/mcpgw.json\"\n \"cli/examples/realserverfaketools.json\"\n)\n\n# A2A Agent configs\nAGENTS=(\n \"cli/examples/flight_booking_agent_card.json\"\n \"cli/examples/travel_assistant_agent_card.json\"\n)\n\n# Register servers\necho -e \"${YELLOW}Step 2: Registering MCP Servers...${NC}\"\nSUCCESS_COUNT=0\nFAIL_COUNT=0\n\nfor config in \"${SERVERS[@]}\"; do\n config_path=\"${REPO_ROOT}/${config}\"\n if [[ ! -f \"$config_path\" ]]; then\n echo -e \"${RED} ✗ Config not found: $config${NC}\"\n ((FAIL_COUNT++))\n continue\n fi\n\n echo -e \"${BLUE} → Registering: $(basename $config)${NC}\"\n set +e # Temporarily disable exit on error\n uv run python \"${SCRIPT_DIR}/registry_management.py\" \\\n --token-file \"$TOKEN_FILE\" \\\n --registry-url \"$REGISTRY_URL\" \\\n --aws-region \"$AWS_REGION\" \\\n --keycloak-url \"$KEYCLOAK_URL\" \\\n register --config \"$config_path\" --overwrite 2>&1 | grep -q \"successfully\\|created\\|registered\\|updated\"\n if [ $? -eq 0 ]; then\n echo -e \"${GREEN} ✓ Registered successfully${NC}\"\n ((SUCCESS_COUNT++))\n else\n echo -e \"${YELLOW} ⚠ Failed${NC}\"\n ((FAIL_COUNT++))\n fi\n set -e # Re-enable exit on error\ndone\n\necho \"\"\necho -e \"${GREEN}Servers: $SUCCESS_COUNT registered, $FAIL_COUNT skipped/failed${NC}\"\necho \"\"\n\n# Register agents\necho -e \"${YELLOW}Step 3: Registering A2A Agents...${NC}\"\nAGENT_SUCCESS=0\nAGENT_FAIL=0\n\nfor config in \"${AGENTS[@]}\"; do\n config_path=\"${REPO_ROOT}/${config}\"\n if [[ ! -f \"$config_path\" ]]; then\n echo -e \"${RED} ✗ Config not found: $config${NC}\"\n ((AGENT_FAIL++))\n continue\n fi\n \n echo -e \"${BLUE} → Registering: $(basename $config)${NC}\"\n set +e # Temporarily disable exit on error\n uv run python \"${SCRIPT_DIR}/registry_management.py\" \\\n --token-file \"$TOKEN_FILE\" \\\n --registry-url \"$REGISTRY_URL\" \\\n --aws-region \"$AWS_REGION\" \\\n --keycloak-url \"$KEYCLOAK_URL\" \\\n agent-register --config \"$config_path\" 2>&1 | grep -q \"successfully\\|created\\|registered\\|updated\"\n if [ $? -eq 0 ]; then\n echo -e \"${GREEN} ✓ Registered successfully${NC}\"\n ((AGENT_SUCCESS++))\n else\n echo -e \"${YELLOW} ⚠ Failed${NC}\"\n ((AGENT_FAIL++))\n fi\n set -e # Re-enable exit on error\ndone\n\necho \"\"\necho -e \"${GREEN}Agents: $AGENT_SUCCESS registered, $AGENT_FAIL skipped/failed${NC}\"\necho \"\"\n\n# Federation configuration\nFEDERATION_CONFIG=\"${REPO_ROOT}/cli/examples/federation-config-example.json\"\nif [[ -f \"$FEDERATION_CONFIG\" ]]; then\n echo -e \"${YELLOW}Step 4: Configuring Federation with Anthropic Registry...${NC}\"\n \n echo -e \"${BLUE} → Saving federation config...${NC}\"\n if uv run python \"${SCRIPT_DIR}/registry_management.py\" \\\n --token-file \"$TOKEN_FILE\" \\\n --registry-url \"$REGISTRY_URL\" \\\n --aws-region \"$AWS_REGION\" \\\n --keycloak-url \"$KEYCLOAK_URL\" \\\n federation-save --config \"$FEDERATION_CONFIG\" ; then\n echo -e \"${GREEN} ✓ Federation config saved${NC}\"\n else\n echo -e \"${RED} ✗ Failed to save federation config${NC}\"\n fi\n\n echo -e \"${BLUE} → Syncing Anthropic federated servers...${NC}\"\n if uv run python \"${SCRIPT_DIR}/registry_management.py\" \\\n --token-file \"$TOKEN_FILE\" \\\n --registry-url \"$REGISTRY_URL\" \\\n --aws-region \"$AWS_REGION\" \\\n --keycloak-url \"$KEYCLOAK_URL\" \\\n federation-sync --source anthropic ; then\n echo -e \"${GREEN} ✓ Federated servers imported${NC}\"\n else\n echo -e \"${RED} ✗ Failed to sync federated servers${NC}\"\n fi\nelse\n echo -e \"${YELLOW}Step 4: Skipping federation (config not found)${NC}\"\nfi\n\necho \"\"\necho -e \"${GREEN}========================================${NC}\"\necho -e \"${GREEN}Registry Population Complete!${NC}\"\necho -e \"${GREEN}========================================${NC}\"\necho \"\"\n\n# Show summary commands\necho -e \"${BLUE}View registered items:${NC}\"\necho \"\"\necho \" # List all servers\"\necho \" uv run python api/registry_management.py \\\\\"\necho \" --token-file $TOKEN_FILE \\\\\"\necho \" --registry-url $REGISTRY_URL \\\\\"\necho \" list\"\necho \"\"\necho \" # List all agents\"\necho \" uv run python api/registry_management.py \\\\\"\necho \" --token-file $TOKEN_FILE \\\\\"\necho \" --registry-url $REGISTRY_URL \\\\\"\necho \" agent-list\"\necho \"\"\necho -e \"${BLUE}Access the Registry UI:${NC}\"\necho \" $REGISTRY_URL\"\necho \"\"\n" }, { "path": "api/registry_client.py", "content": "#!/usr/bin/env python3\n\"\"\"\nMCP Gateway Registry Client - Standalone Pydantic-based client for the Registry API.\n\nThis client provides a type-safe interface to the MCP Gateway Registry API endpoints\ndocumented in:\n- /home/ubuntu/repos/mcp-gateway-registry/docs/api-specs/server-management.yaml (Server Management)\n- /home/ubuntu/repos/mcp-gateway-registry/docs/api-specs/a2a-agent-management.yaml (Agent Management)\n\nAuthentication is handled via JWT tokens retrieved from AWS SSM Parameter Store using\nthe get-m2m-token.sh script.\n\"\"\"\n\nimport json\nimport logging\nfrom datetime import datetime\nfrom enum import Enum\nfrom typing import Any\nfrom urllib.parse import quote\nfrom uuid import UUID\n\nimport requests\nfrom pydantic import BaseModel, ConfigDict, Field\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass HealthStatus(str, Enum):\n \"\"\"Health status enumeration for servers.\"\"\"\n\n HEALTHY = \"healthy\"\n UNHEALTHY = \"unhealthy\"\n UNKNOWN = \"unknown\"\n DISABLED = \"disabled\"\n\n\nclass ServiceRegistration(BaseModel):\n \"\"\"Service registration request model (UI-based registration).\"\"\"\n\n name: str = Field(..., description=\"Service name\")\n description: str = Field(..., description=\"Service description\")\n path: str = Field(..., description=\"Service path\")\n proxy_pass_url: str = Field(..., description=\"Proxy pass URL\")\n tags: str | None = Field(None, description=\"Comma-separated tags\")\n num_tools: int | None = Field(None, description=\"Number of tools\")\n license: str | None = Field(None, description=\"License type\")\n\n\nclass InternalServiceRegistration(BaseModel):\n \"\"\"Internal service registration model (Admin/M2M registration).\"\"\"\n\n service_path: str = Field(\n ..., alias=\"path\", description=\"Service path (e.g., /cloudflare-docs)\"\n )\n name: str | None = Field(None, description=\"Service name\")\n description: str | None = Field(None, description=\"Service description\")\n proxy_pass_url: str | None = Field(None, description=\"Proxy pass URL\")\n version: str | None = Field(None, description=\"Server version (e.g., v1.0.0, v2.0.0)\")\n status: str | None = Field(None, description=\"Version status (stable, beta, deprecated)\")\n auth_provider: str | None = Field(None, description=\"Authentication provider\")\n auth_scheme: str | None = Field(\n None, description=\"Authentication scheme (e.g., 'bearer', 'api_key', 'none')\"\n )\n supported_transports: list[str] | None = Field(None, description=\"Supported transports\")\n headers: dict[str, str] | None = Field(None, description=\"Custom headers\")\n tool_list_json: str | None = Field(None, description=\"Tool list as JSON string\")\n tags: list[str] | None = Field(None, description=\"Categorization tags\")\n overwrite: bool | None = Field(False, description=\"Overwrite if exists\")\n mcp_endpoint: str | None = Field(\n None,\n description=\"Full URL for the MCP streamable-http endpoint (overrides proxy_pass_url + /mcp)\",\n )\n sse_endpoint: str | None = Field(\n None, description=\"Full URL for the SSE endpoint (overrides proxy_pass_url + /sse)\"\n )\n metadata: dict[str, Any] | None = Field(\n default_factory=dict,\n description=\"Additional custom metadata for organization, compliance, or integration purposes\",\n )\n provider_organization: str | None = Field(None, description=\"Provider organization name\")\n provider_url: str | None = Field(None, description=\"Provider URL\")\n source_created_at: str | None = Field(\n None, description=\"Original creation timestamp (ISO format)\"\n )\n source_updated_at: str | None = Field(None, description=\"Last update timestamp (ISO format)\")\n external_tags: list[str] | None = Field(None, description=\"Tags from external/source system\")\n auth_credential: str | None = Field(\n None,\n description=\"Plaintext auth credential (Bearer token or API key). Encrypted before storage.\",\n )\n\n model_config = ConfigDict(populate_by_name=True)\n\n\nclass Server(BaseModel):\n \"\"\"Server information model.\"\"\"\n\n path: str = Field(..., description=\"Service path\")\n display_name: str = Field(..., description=\"Service display name\")\n description: str = Field(..., description=\"Service description\")\n is_enabled: bool = Field(..., description=\"Whether service is enabled\")\n health_status: HealthStatus = Field(..., description=\"Health status\")\n status: str = Field(\n default=\"active\",\n description=\"Lifecycle status (active, deprecated, draft, beta)\",\n )\n\n\nclass ServerDetail(BaseModel):\n \"\"\"Detailed server information model.\"\"\"\n\n path: str = Field(..., description=\"Service path\")\n name: str = Field(..., description=\"Service name\")\n description: str = Field(..., description=\"Service description\")\n url: str = Field(..., description=\"Service URL\")\n is_enabled: bool = Field(..., description=\"Whether service is enabled\")\n num_tools: int = Field(..., description=\"Number of tools\")\n health_status: str = Field(..., description=\"Health status\")\n last_health_check: datetime | None = Field(None, description=\"Last health check timestamp\")\n status: str = Field(\n default=\"active\", description=\"Server status (active, deprecated, draft, beta)\"\n )\n provider: dict[str, str] | None = Field(\n None, description=\"Provider information (organization, url)\"\n )\n source_created_at: str | None = Field(None, description=\"Creation timestamp in source system\")\n source_updated_at: str | None = Field(\n None, description=\"Last update timestamp in source system\"\n )\n external_tags: list[str] = Field(default_factory=list, description=\"Tags from external source\")\n\n\nclass ServerDetailResponse(BaseModel):\n \"\"\"Response model for single server retrieval via GET /api/servers/{path}.\"\"\"\n\n server_name: str = Field(default=\"\", description=\"Server display name\")\n description: str = Field(default=\"\", description=\"Server description\")\n path: str = Field(..., description=\"Server path (e.g., /my-server)\")\n proxy_pass_url: str | None = Field(None, description=\"Backend URL\")\n tags: list[str] = Field(default_factory=list, description=\"Server tags\")\n num_tools: int = Field(default=0, description=\"Number of tools\")\n tool_list: list[dict[str, Any]] = Field(default_factory=list, description=\"Tool definitions\")\n is_enabled: bool = Field(default=False, description=\"Whether server is enabled\")\n health_status: str | None = Field(None, description=\"Health status\")\n transport: str | None = Field(None, description=\"Transport type\")\n version: str | None = Field(None, description=\"Server version\")\n versions: list[dict[str, Any]] | None = Field(None, description=\"Version list\")\n license: str = Field(default=\"N/A\", description=\"License\")\n registered_by: str | None = Field(None, description=\"Who registered\")\n\n model_config = ConfigDict(extra=\"allow\")\n\n\nclass ServerListResponse(BaseModel):\n \"\"\"Server list response model.\"\"\"\n\n servers: list[Server] = Field(..., description=\"List of servers\")\n total_count: int = Field(..., description=\"Total count of matching servers (all pages)\")\n limit: int = Field(..., description=\"Page size applied\")\n offset: int = Field(..., description=\"Offset applied\")\n has_next: bool = Field(..., description=\"Whether more pages exist\")\n\n\nclass ServiceResponse(BaseModel):\n \"\"\"Service operation response model.\"\"\"\n\n path: str = Field(..., description=\"Service path\")\n name: str = Field(..., description=\"Service name\")\n message: str = Field(..., description=\"Response message\")\n\n\nclass ToggleResponse(BaseModel):\n \"\"\"Toggle service response model.\"\"\"\n\n path: str = Field(..., description=\"Service path\")\n is_enabled: bool = Field(..., description=\"Current enabled status\")\n message: str = Field(..., description=\"Response message\")\n\n\nclass ErrorResponse(BaseModel):\n \"\"\"Error response model.\"\"\"\n\n detail: str = Field(..., description=\"Error detail message\")\n error_code: str | None = Field(None, description=\"Error code\")\n request_id: str | None = Field(None, description=\"Request ID\")\n\n\nclass SecurityScanResult(BaseModel):\n \"\"\"Security scan result model.\"\"\"\n\n analysis_results: dict[str, Any] = Field(..., description=\"Analysis results by analyzer\")\n tool_results: list[dict[str, Any]] = Field(..., description=\"Detailed tool scan results\")\n\n\nclass RescanResponse(BaseModel):\n \"\"\"Server rescan response model.\"\"\"\n\n server_url: str = Field(..., description=\"Server URL that was scanned\")\n server_path: str = Field(..., description=\"Server path\")\n scan_timestamp: str = Field(..., description=\"Scan timestamp\")\n is_safe: bool = Field(..., description=\"Whether server is safe\")\n critical_issues: int = Field(..., description=\"Number of critical issues\")\n high_severity: int = Field(..., description=\"Number of high severity issues\")\n medium_severity: int = Field(..., description=\"Number of medium severity issues\")\n low_severity: int = Field(..., description=\"Number of low severity issues\")\n analyzers_used: list[str] = Field(..., description=\"Analyzers used in scan\")\n scan_failed: bool = Field(..., description=\"Whether scan failed\")\n error_message: str | None = Field(None, description=\"Error message if scan failed\")\n raw_output: dict[str, Any] | None = Field(None, description=\"Raw scan output\")\n\n\nclass AgentSecurityScanResponse(BaseModel):\n \"\"\"Agent security scan results response model.\"\"\"\n\n analysis_results: dict[str, Any] = Field(\n default_factory=dict, description=\"Analysis results by analyzer\"\n )\n scan_results: dict[str, Any] = Field(\n default_factory=dict, description=\"Scan results and metadata\"\n )\n\n\nclass AgentRescanResponse(BaseModel):\n \"\"\"Agent rescan response model.\"\"\"\n\n agent_path: str = Field(..., description=\"Agent path\")\n agent_url: str = Field(..., description=\"Agent URL that was scanned\")\n scan_timestamp: str = Field(..., description=\"Scan timestamp\")\n is_safe: bool = Field(..., description=\"Whether agent is safe\")\n critical_issues: int = Field(..., description=\"Number of critical issues\")\n high_severity: int = Field(..., description=\"Number of high severity issues\")\n medium_severity: int = Field(..., description=\"Number of medium severity issues\")\n low_severity: int = Field(..., description=\"Number of low severity issues\")\n analyzers_used: list[str] = Field(..., description=\"Analyzers used in scan\")\n scan_failed: bool = Field(..., description=\"Whether scan failed\")\n error_message: str | None = Field(None, description=\"Error message if scan failed\")\n output_file: str | None = Field(None, description=\"Path to scan output file\")\n\n\nclass SkillSecurityScanResponse(BaseModel):\n \"\"\"Skill security scan results response model.\"\"\"\n\n skill_path: str = Field(..., description=\"Skill path\")\n skill_md_url: str | None = Field(None, description=\"Skill SKILL.md URL\")\n scan_timestamp: str = Field(..., description=\"Scan timestamp\")\n is_safe: bool = Field(..., description=\"Whether skill is safe\")\n critical_issues: int = Field(default=0, description=\"Number of critical issues\")\n high_severity: int = Field(default=0, description=\"Number of high severity issues\")\n medium_severity: int = Field(default=0, description=\"Number of medium severity issues\")\n low_severity: int = Field(default=0, description=\"Number of low severity issues\")\n analyzers_used: list[str] = Field(default_factory=list, description=\"Analyzers used in scan\")\n raw_output: dict[str, Any] = Field(default_factory=dict, description=\"Raw scanner output\")\n scan_failed: bool = Field(default=False, description=\"Whether scan failed\")\n error_message: str | None = Field(None, description=\"Error message if scan failed\")\n\n\nclass SkillRescanResponse(BaseModel):\n \"\"\"Skill rescan response model.\"\"\"\n\n skill_path: str = Field(..., description=\"Skill path\")\n skill_md_url: str | None = Field(None, description=\"Skill SKILL.md URL\")\n scan_timestamp: str = Field(..., description=\"Scan timestamp\")\n is_safe: bool = Field(..., description=\"Whether skill is safe\")\n critical_issues: int = Field(default=0, description=\"Number of critical issues\")\n high_severity: int = Field(default=0, description=\"Number of high severity issues\")\n medium_severity: int = Field(default=0, description=\"Number of medium severity issues\")\n low_severity: int = Field(default=0, description=\"Number of low severity issues\")\n analyzers_used: list[str] = Field(default_factory=list, description=\"Analyzers used in scan\")\n raw_output: dict[str, Any] = Field(default_factory=dict, description=\"Raw scanner output\")\n scan_failed: bool = Field(default=False, description=\"Whether scan failed\")\n error_message: str | None = Field(None, description=\"Error message if scan failed\")\n\n\nclass GroupListResponse(BaseModel):\n \"\"\"Group list response model.\"\"\"\n\n groups: list[dict[str, Any]] = Field(..., description=\"List of groups\")\n total: int = Field(..., description=\"Total number of groups\")\n\n\n# Agent Management Models\n\n\nclass AgentProvider(str, Enum):\n \"\"\"Agent provider enumeration.\"\"\"\n\n ANTHROPIC = \"anthropic\"\n CUSTOM = \"custom\"\n OTHER = \"other\"\n\n\nclass AgentVisibility(str, Enum):\n \"\"\"Agent visibility enumeration.\"\"\"\n\n PUBLIC = \"public\"\n PRIVATE = \"private\"\n GROUP_RESTRICTED = \"group-restricted\"\n\n\nclass Provider(BaseModel):\n \"\"\"\n A2A Agent Provider information.\n\n Represents the service provider of an agent with organization name and website URL.\n Per A2A specification, if provider is present, both organization and url are required.\n \"\"\"\n\n organization: str = Field(..., description=\"Provider organization name\")\n url: str = Field(..., description=\"Provider website or documentation URL\")\n\n\nclass SecuritySchemeType(str, Enum):\n \"\"\"Security scheme type enumeration (A2A spec values).\"\"\"\n\n API_KEY = \"apiKey\"\n HTTP = \"http\"\n OAUTH2 = \"oauth2\"\n OPENID_CONNECT = \"openIdConnect\"\n\n\nclass SecurityScheme(BaseModel):\n \"\"\"\n Security scheme model.\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n type: SecuritySchemeType = Field(..., description=\"Security scheme type\")\n scheme: str | None = Field(\n None,\n description=\"HTTP auth scheme: basic, bearer, digest\",\n )\n in_: str | None = Field(\n None,\n alias=\"in\",\n description=\"API key location: header, query, cookie\",\n )\n name: str | None = Field(\n None,\n description=\"Name of header/query/cookie for API key\",\n )\n bearer_format: str | None = Field(\n None,\n alias=\"bearerFormat\",\n description=\"Bearer token format hint (e.g., JWT)\",\n )\n flows: dict[str, Any] | None = Field(\n None,\n description=\"OAuth2 flows configuration\",\n )\n openid_connect_url: str | None = Field(\n None,\n alias=\"openIdConnectUrl\",\n description=\"OpenID Connect discovery URL\",\n )\n description: str | None = Field(None, description=\"Security scheme description\")\n\n class Config:\n populate_by_name = True # Allow both snake_case and camelCase on input\n\n\nclass Skill(BaseModel):\n \"\"\"\n Agent skill definition per A2A protocol specification.\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n id: str = Field(..., description=\"Unique skill identifier\")\n name: str = Field(..., description=\"Human-readable skill name\")\n description: str = Field(..., description=\"Detailed skill description\")\n tags: list[str] = Field(default_factory=list, description=\"Skill categorization tags\")\n examples: list[str] | None = Field(None, description=\"Usage scenarios and examples\")\n input_modes: list[str] | None = Field(\n None, alias=\"inputModes\", description=\"Skill-specific input MIME types\"\n )\n output_modes: list[str] | None = Field(\n None, alias=\"outputModes\", description=\"Skill-specific output MIME types\"\n )\n security: list[dict[str, list[str]]] | None = Field(\n None, description=\"Skill-level security requirements\"\n )\n\n class Config:\n populate_by_name = True # Allow both snake_case and camelCase on input\n\n\nclass AgentRegistration(BaseModel):\n \"\"\"\n Agent registration request model matching server AgentCard schema.\n This model represents a complete agent card following the A2A protocol\n specification (v0.3.0), with extensions for MCP Gateway Registry integration.\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n # Required A2A fields\n protocol_version: str = Field(\n \"1.0\", alias=\"protocolVersion\", description=\"A2A protocol version (e.g., '1.0')\"\n )\n name: str = Field(..., description=\"Agent name\")\n description: str = Field(..., description=\"Agent description\")\n url: str = Field(..., description=\"Agent endpoint URL (HTTP or HTTPS)\")\n version: str = Field(..., description=\"Agent version\")\n capabilities: dict[str, Any] = Field(\n default_factory=dict, description=\"Feature declarations (e.g., {'streaming': true})\"\n )\n default_input_modes: list[str] = Field(\n default_factory=lambda: [\"text/plain\"],\n alias=\"defaultInputModes\",\n description=\"Supported input MIME types\",\n )\n default_output_modes: list[str] = Field(\n default_factory=lambda: [\"text/plain\"],\n alias=\"defaultOutputModes\",\n description=\"Supported output MIME types\",\n )\n skills: list[Skill] = Field(default_factory=list, description=\"Agent capabilities (skills)\")\n\n # Optional A2A fields\n preferred_transport: str | None = Field(\n \"JSONRPC\",\n alias=\"preferredTransport\",\n description=\"Preferred transport protocol: JSONRPC, GRPC, HTTP+JSON\",\n )\n provider: Provider | None = Field(None, description=\"Agent provider information per A2A spec\")\n icon_url: str | None = Field(None, alias=\"iconUrl\", description=\"Agent icon URL\")\n documentation_url: str | None = Field(\n None, alias=\"documentationUrl\", description=\"Documentation URL\"\n )\n security_schemes: dict[str, SecurityScheme | dict[str, Any]] = Field(\n default_factory=dict,\n alias=\"securitySchemes\",\n description=\"Supported authentication methods\",\n )\n security: list[dict[str, list[str]]] | None = Field(\n None, description=\"Security requirements array\"\n )\n supports_authenticated_extended_card: bool | None = Field(\n None,\n alias=\"supportsAuthenticatedExtendedCard\",\n description=\"Supports extended card with auth\",\n )\n metadata: dict[str, Any] = Field(default_factory=dict, description=\"Additional metadata\")\n\n # MCP Gateway Registry extensions (optional - not part of A2A spec)\n path: str | None = Field(\n None,\n description=\"Registry path (e.g., /agents/my-agent). Optional - auto-generated if not provided.\",\n )\n tags: list[str] = Field(default_factory=list, description=\"Categorization tags\")\n is_enabled: bool = Field(\n False, alias=\"isEnabled\", description=\"Whether agent is enabled in registry\"\n )\n num_stars: int = Field(0, ge=0, alias=\"numStars\", description=\"Community rating\")\n license: str = Field(\"N/A\", description=\"License information\")\n registered_at: datetime | None = Field(\n None, alias=\"registeredAt\", description=\"Registration timestamp\"\n )\n updated_at: datetime | None = Field(\n None, alias=\"updatedAt\", description=\"Last update timestamp\"\n )\n registered_by: str | None = Field(\n None, alias=\"registeredBy\", description=\"Username who registered agent\"\n )\n visibility: str = Field(\"public\", description=\"public, private, or group-restricted\")\n allowed_groups: list[str] = Field(\n default_factory=list, alias=\"allowedGroups\", description=\"Groups with access\"\n )\n signature: str | None = Field(None, description=\"JWS signature for card integrity\")\n trust_level: str = Field(\n \"unverified\", alias=\"trustLevel\", description=\"unverified, community, verified, trusted\"\n )\n supported_protocol: str | None = Field(\n None, alias=\"supportedProtocol\", description=\"Agent protocol: a2a or other\"\n )\n\n class Config:\n populate_by_name = True # Allow both snake_case and camelCase on input\n\n\nclass AgentCard(BaseModel):\n \"\"\"Agent card model (summary view).\"\"\"\n\n name: str = Field(..., description=\"Agent name\")\n path: str = Field(..., description=\"Agent path\")\n url: str = Field(..., description=\"Agent URL\")\n num_skills: int = Field(..., description=\"Number of skills\")\n registered_at: datetime | None = Field(None, description=\"Registration timestamp\")\n is_enabled: bool = Field(..., description=\"Whether agent is enabled\")\n status: str = Field(\n default=\"active\", description=\"Agent status (active, deprecated, draft, beta)\"\n )\n source_created_at: str | None = Field(\n None, alias=\"sourceCreatedAt\", description=\"Creation timestamp in source system\"\n )\n source_updated_at: str | None = Field(\n None, alias=\"sourceUpdatedAt\", description=\"Last update timestamp in source system\"\n )\n external_tags: list[str] = Field(\n default_factory=list, alias=\"externalTags\", description=\"Tags from external source\"\n )\n supported_protocol: str | None = Field(\n None, alias=\"supportedProtocol\", description=\"Agent protocol: 'a2a' or 'other'\"\n )\n\n class Config:\n populate_by_name = True # Allow both snake_case and camelCase on input\n\n\nclass AgentRegistrationResponse(BaseModel):\n \"\"\"Agent registration response model.\"\"\"\n\n message: str = Field(..., description=\"Response message\")\n agent: AgentCard = Field(..., description=\"Registered agent card\")\n\n\nclass SkillDetail(BaseModel):\n \"\"\"\n Detailed skill model - same as Skill.\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n id: str = Field(..., description=\"Unique skill identifier\")\n name: str = Field(..., description=\"Human-readable skill name\")\n description: str = Field(..., description=\"Detailed skill description\")\n tags: list[str] = Field(default_factory=list, description=\"Skill categorization tags\")\n examples: list[str] | None = Field(None, description=\"Usage scenarios and examples\")\n input_modes: list[str] | None = Field(\n None, alias=\"inputModes\", description=\"Skill-specific input MIME types\"\n )\n output_modes: list[str] | None = Field(\n None, alias=\"outputModes\", description=\"Skill-specific output MIME types\"\n )\n security: list[dict[str, list[str]]] | None = Field(\n None, description=\"Skill-level security requirements\"\n )\n\n class Config:\n populate_by_name = True # Allow both snake_case and camelCase on input\n\n\nclass AgentDetail(BaseModel):\n \"\"\"\n Detailed agent model matching server AgentCard schema.\n This model represents a complete agent card following the A2A protocol\n specification (v0.3.0), with extensions for MCP Gateway Registry integration.\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n # Required A2A fields\n protocol_version: str = Field(..., alias=\"protocolVersion\", description=\"A2A protocol version\")\n name: str = Field(..., description=\"Agent name\")\n description: str = Field(..., description=\"Agent description\")\n url: str = Field(..., description=\"Agent endpoint URL\")\n version: str = Field(..., description=\"Agent version\")\n capabilities: dict[str, Any] = Field(\n default_factory=dict, description=\"Feature declarations (e.g., {'streaming': true})\"\n )\n default_input_modes: list[str] = Field(\n default_factory=lambda: [\"text/plain\"],\n alias=\"defaultInputModes\",\n description=\"Supported input MIME types\",\n )\n default_output_modes: list[str] = Field(\n default_factory=lambda: [\"text/plain\"],\n alias=\"defaultOutputModes\",\n description=\"Supported output MIME types\",\n )\n skills: list[SkillDetail] = Field(\n default_factory=list, description=\"Agent capabilities (skills)\"\n )\n\n # Optional A2A fields\n preferred_transport: str | None = Field(\n \"JSONRPC\",\n alias=\"preferredTransport\",\n description=\"Preferred transport protocol: JSONRPC, GRPC, HTTP+JSON\",\n )\n provider: Provider | None = Field(None, description=\"Agent provider information per A2A spec\")\n icon_url: str | None = Field(None, alias=\"iconUrl\", description=\"Agent icon URL\")\n documentation_url: str | None = Field(\n None, alias=\"documentationUrl\", description=\"Documentation URL\"\n )\n security_schemes: dict[str, SecurityScheme | dict[str, Any]] = Field(\n default_factory=dict,\n alias=\"securitySchemes\",\n description=\"Supported authentication methods\",\n )\n security: list[dict[str, list[str]]] | None = Field(\n None, description=\"Security requirements array\"\n )\n supports_authenticated_extended_card: bool | None = Field(\n None,\n alias=\"supportsAuthenticatedExtendedCard\",\n description=\"Supports extended card with auth\",\n )\n metadata: dict[str, Any] = Field(default_factory=dict, description=\"Additional metadata\")\n\n # MCP Gateway Registry extensions (optional - not part of A2A spec)\n path: str | None = Field(None, description=\"Registry path\")\n tags: list[str] = Field(default_factory=list, description=\"Categorization tags\")\n is_enabled: bool = Field(False, alias=\"isEnabled\", description=\"Whether agent is enabled\")\n num_stars: int = Field(0, ge=0, alias=\"numStars\", description=\"Community rating\")\n license: str = Field(\"N/A\", description=\"License information\")\n registered_at: datetime | None = Field(\n None, alias=\"registeredAt\", description=\"Registration timestamp\"\n )\n updated_at: datetime | None = Field(\n None, alias=\"updatedAt\", description=\"Last update timestamp\"\n )\n registered_by: str | None = Field(\n None, alias=\"registeredBy\", description=\"Username who registered agent\"\n )\n visibility: str = Field(\"public\", description=\"Visibility level\")\n allowed_groups: list[str] = Field(\n default_factory=list, alias=\"allowedGroups\", description=\"Groups with access\"\n )\n trust_level: str = Field(\"community\", alias=\"trustLevel\", description=\"Trust level\")\n ans_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"ansMetadata\",\n description=\"ANS (Agent Name Service) verification metadata\",\n )\n signature: str | None = Field(None, description=\"JWS signature for card integrity\")\n status: str = Field(\n default=\"active\", description=\"Agent status (active, deprecated, draft, beta)\"\n )\n source_created_at: str | None = Field(\n None, alias=\"sourceCreatedAt\", description=\"Creation timestamp in source system\"\n )\n source_updated_at: str | None = Field(\n None, alias=\"sourceUpdatedAt\", description=\"Last update timestamp in source system\"\n )\n external_tags: list[str] = Field(\n default_factory=list, alias=\"externalTags\", description=\"Tags from external source\"\n )\n supported_protocol: str | None = Field(\n None, alias=\"supportedProtocol\", description=\"Agent protocol: 'a2a' or 'other'\"\n )\n\n class Config:\n populate_by_name = True # Allow both snake_case and camelCase on input\n\n\nclass AgentListItem(BaseModel):\n \"\"\"\n Agent list item model (AgentInfo from server).\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n name: str = Field(..., description=\"Agent name\")\n description: str = Field(default=\"\", description=\"Agent description\")\n path: str = Field(..., description=\"Agent path\")\n url: str = Field(..., description=\"Agent URL\")\n tags: list[str] = Field(default_factory=list, description=\"Categorization tags\")\n skills: list[str] = Field(default_factory=list, description=\"Skill names\")\n num_skills: int = Field(default=0, alias=\"numSkills\", description=\"Number of skills\")\n num_stars: float = Field(\n default=0.0, alias=\"numStars\", description=\"Average community rating (0.0-5.0)\"\n )\n is_enabled: bool = Field(\n default=False, alias=\"isEnabled\", description=\"Whether agent is enabled\"\n )\n provider: str | None = Field(None, description=\"Agent provider\")\n streaming: bool = Field(default=False, description=\"Supports streaming\")\n trust_level: str = Field(default=\"unverified\", alias=\"trustLevel\", description=\"Trust level\")\n ans_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"ansMetadata\",\n description=\"ANS (Agent Name Service) verification metadata\",\n )\n sync_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"syncMetadata\",\n description=\"Federation sync metadata for items from peer registries\",\n )\n status: str = Field(\n default=\"active\",\n description=\"Lifecycle status (active, deprecated, draft, beta)\",\n )\n\n class Config:\n populate_by_name = True # Allow both snake_case and camelCase on input\n\n\nclass AgentListResponse(BaseModel):\n \"\"\"Agent list response model.\"\"\"\n\n agents: list[AgentListItem] = Field(..., description=\"List of agents\")\n total_count: int = Field(..., description=\"Total count of matching agents (all pages)\")\n limit: int = Field(..., description=\"Page size applied\")\n offset: int = Field(..., description=\"Offset applied\")\n has_next: bool = Field(..., description=\"Whether more pages exist\")\n\n\nclass AgentToggleResponse(BaseModel):\n \"\"\"Agent toggle response model.\"\"\"\n\n path: str = Field(..., description=\"Agent path\")\n is_enabled: bool = Field(..., description=\"Current enabled status\")\n message: str = Field(..., description=\"Response message\")\n\n\nclass SkillDiscoveryRequest(BaseModel):\n \"\"\"Skill-based discovery request model.\"\"\"\n\n skills: list[str] = Field(..., description=\"List of required skills\")\n tags: list[str] | None = Field(None, description=\"Optional tag filters\")\n\n\nclass DiscoveredAgent(BaseModel):\n \"\"\"Discovered agent model (skill-based).\"\"\"\n\n path: str = Field(..., description=\"Agent path\")\n name: str = Field(..., description=\"Agent name\")\n relevance_score: float = Field(..., description=\"Matching score (0.0 to 1.0)\")\n matching_skills: list[str] = Field(..., description=\"Matching skills\")\n\n\nclass AgentDiscoveryResponse(BaseModel):\n \"\"\"Agent discovery response model (skill-based).\"\"\"\n\n agents: list[DiscoveredAgent] = Field(..., description=\"Discovered agents\")\n\n\nclass SemanticDiscoveredAgent(BaseModel):\n \"\"\"Semantically discovered agent model with full AgentCard fields.\"\"\"\n\n # Core identification\n path: str = Field(..., description=\"Agent path\")\n name: str = Field(..., description=\"Agent name\")\n description: str = Field(..., description=\"Agent description\")\n url: str = Field(..., description=\"Agent endpoint URL\")\n\n # Semantic search relevance\n relevance_score: float = Field(..., description=\"Semantic similarity score\")\n\n # Agent metadata\n tags: list[str] = Field(default_factory=list, description=\"Agent tags\")\n skills: list[dict[str, Any]] = Field(default_factory=list, description=\"Agent skills\")\n provider: dict[str, str] | None = Field(None, description=\"Provider information\")\n capabilities: dict[str, Any] = Field(default_factory=dict, description=\"Agent capabilities\")\n trust_level: str = Field(\"unverified\", description=\"Trust level\")\n trust_verified: str | None = Field(None, description=\"ANS trust verification status\")\n ans_metadata: dict[str, Any] | None = Field(None, description=\"ANS verification metadata\")\n num_stars: float = Field(0.0, description=\"Average rating\")\n version: str | None = Field(None, description=\"Agent version\")\n\n # Security and authentication\n security_schemes: dict[str, Any] = Field(default_factory=dict, description=\"Security schemes\")\n\n # Timestamps\n created_at: str | None = Field(None, description=\"Creation timestamp\")\n updated_at: str | None = Field(None, description=\"Last update timestamp\")\n\n class Config:\n extra = \"allow\" # Allow additional fields from API\n\n\nclass AgentSemanticDiscoveryResponse(BaseModel):\n \"\"\"Agent semantic discovery response model.\"\"\"\n\n agents: list[SemanticDiscoveredAgent] = Field(..., description=\"Semantically discovered agents\")\n\n\nclass MatchingToolResult(BaseModel):\n \"\"\"Tool matching result with optional schema for display.\"\"\"\n\n tool_name: str = Field(..., description=\"Tool name\")\n description: str | None = Field(None, description=\"Tool description\")\n relevance_score: float = Field(0.0, ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Why this tool matched\")\n inputSchema: dict[str, Any] | None = Field(\n None, description=\"JSON Schema for tool input parameters\"\n )\n\n\nclass SyncMetadata(BaseModel):\n \"\"\"Metadata for items synced from peer registries.\"\"\"\n\n is_federated: bool = Field(False, description=\"Whether this is from a federated registry\")\n source_peer_id: str | None = Field(None, description=\"Source peer registry ID\")\n synced_at: str | None = Field(None, description=\"When item was synced\")\n original_path: str | None = Field(None, description=\"Original path on source registry\")\n is_orphaned: bool = Field(False, description=\"Whether item is orphaned\")\n orphaned_at: str | None = Field(None, description=\"When item became orphaned\")\n is_read_only: bool = Field(True, description=\"Whether item is read-only\")\n\n\nclass SemanticDiscoveredServer(BaseModel):\n \"\"\"Semantically discovered server model.\"\"\"\n\n path: str = Field(..., description=\"Server path\")\n server_name: str = Field(..., description=\"Server name\")\n relevance_score: float = Field(..., description=\"Semantic similarity score\")\n description: str | None = Field(None, description=\"Server description\")\n tags: list[str] = Field(default_factory=list, description=\"Server tags\")\n num_tools: int = Field(0, description=\"Number of tools\")\n is_enabled: bool = Field(False, description=\"Whether server is enabled\")\n match_context: str | None = Field(None, description=\"Why this matched\")\n matching_tools: list[MatchingToolResult] = Field(\n default_factory=list, description=\"Matching tools\"\n )\n sync_metadata: SyncMetadata | None = Field(\n None, description=\"Sync metadata for federated items\"\n )\n # Endpoint URL for agent connectivity (computed based on deployment mode)\n endpoint_url: str | None = Field(\n None, description=\"URL for agents to connect to this MCP server\"\n )\n # Raw endpoint fields (for advanced use cases)\n proxy_pass_url: str | None = Field(\n None, description=\"Base URL for the MCP server backend (internal)\"\n )\n mcp_endpoint: str | None = Field(None, description=\"Explicit streamable-http endpoint URL\")\n sse_endpoint: str | None = Field(None, description=\"Explicit SSE endpoint URL\")\n supported_transports: list[str] = Field(\n default_factory=list, description=\"Supported transport types\"\n )\n\n\nclass ToolSearchResult(BaseModel):\n \"\"\"Tool search result model.\"\"\"\n\n server_path: str = Field(..., description=\"Parent server path\")\n server_name: str = Field(..., description=\"Parent server name\")\n tool_name: str = Field(..., description=\"Tool name\")\n description: str | None = Field(None, description=\"Tool description\")\n inputSchema: dict[str, Any] | None = Field(None, description=\"JSON Schema for tool input\")\n relevance_score: float = Field(..., ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Why this tool matched\")\n # Endpoint URL for the parent MCP server\n endpoint_url: str | None = Field(\n None, description=\"URL for agents to connect to the parent MCP server\"\n )\n\n\nclass AgentSearchResult(BaseModel):\n \"\"\"Agent search result with minimal top-level fields.\n\n Only search-specific fields are at the top level. All agent details\n (name, description, url, skills, etc.) are in the agent_card.\n \"\"\"\n\n path: str = Field(..., description=\"Agent path for identification\")\n relevance_score: float = Field(..., ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Why this agent matched\")\n agent_card: dict[str, Any] = Field(..., description=\"Full agent card with all details\")\n\n\nclass SkillSearchResult(BaseModel):\n \"\"\"Skill search result model.\"\"\"\n\n path: str = Field(..., description=\"Skill path\")\n skill_name: str = Field(..., description=\"Skill name\")\n description: str | None = Field(None, description=\"Skill description\")\n tags: list[str] = Field(default_factory=list, description=\"Skill tags\")\n skill_md_url: str | None = Field(None, description=\"Skill markdown URL\")\n skill_md_raw_url: str | None = Field(None, description=\"Skill markdown raw URL\")\n version: str | None = Field(None, description=\"Skill version\")\n author: str | None = Field(None, description=\"Skill author\")\n visibility: str | None = Field(None, description=\"Visibility setting\")\n owner: str | None = Field(None, description=\"Skill owner\")\n is_enabled: bool = Field(False, description=\"Whether skill is enabled\")\n health_status: str = Field(\"unknown\", description=\"Health status\")\n last_checked_time: str | None = Field(None, description=\"Last health check time\")\n relevance_score: float = Field(..., ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Why this skill matched\")\n\n\nclass VirtualServerSearchResult(BaseModel):\n \"\"\"Virtual server search result model.\"\"\"\n\n path: str = Field(..., description=\"Virtual server path\")\n server_name: str = Field(..., description=\"Virtual server name\")\n description: str | None = Field(None, description=\"Virtual server description\")\n tags: list[str] = Field(default_factory=list, description=\"Virtual server tags\")\n num_tools: int = Field(0, description=\"Number of tools\")\n backend_count: int = Field(0, description=\"Number of backend servers\")\n backend_paths: list[str] = Field(default_factory=list, description=\"Backend server paths\")\n is_enabled: bool = Field(False, description=\"Whether virtual server is enabled\")\n relevance_score: float = Field(..., ge=0.0, le=1.0, description=\"Relevance score\")\n match_context: str | None = Field(None, description=\"Why this matched\")\n matching_tools: list[MatchingToolResult] = Field(\n default_factory=list, description=\"Matching tools\"\n )\n # Endpoint URL for agent connectivity\n endpoint_url: str | None = Field(\n None, description=\"URL for agents to connect to this virtual MCP server\"\n )\n\n\nclass ToolMapping(BaseModel):\n \"\"\"Tool mapping for virtual MCP servers.\"\"\"\n\n tool_name: str = Field(..., description=\"Original tool name on backend server\")\n alias: str | None = Field(None, description=\"Renamed tool name in virtual server\")\n backend_server_path: str = Field(..., description=\"Backend server path (e.g., /github)\")\n backend_version: str | None = Field(None, description=\"Pin to specific backend version\")\n description_override: str | None = Field(None, description=\"Override tool description\")\n\n\nclass ToolScopeOverride(BaseModel):\n \"\"\"Per-tool scope override for access control.\"\"\"\n\n tool_alias: str = Field(..., description=\"Tool alias or name\")\n required_scopes: list[str] = Field(\n default_factory=list, description=\"Required scopes for this tool\"\n )\n\n\nclass VirtualServerCreateRequest(BaseModel):\n \"\"\"Request to create a virtual MCP server.\"\"\"\n\n path: str = Field(..., description=\"Virtual server path (e.g., /virtual/dev-tools)\")\n server_name: str = Field(..., description=\"Display name for the virtual server\")\n description: str | None = Field(None, description=\"Virtual server description\")\n tool_mappings: list[ToolMapping] = Field(\n ..., min_length=1, description=\"Tool mappings (at least one)\"\n )\n required_scopes: list[str] = Field(\n default_factory=list, description=\"Server-level required scopes\"\n )\n tool_scope_overrides: list[ToolScopeOverride] = Field(\n default_factory=list, description=\"Per-tool scope overrides\"\n )\n tags: list[str] = Field(default_factory=list, description=\"Tags for categorization\")\n supported_transports: list[str] = Field(\n default_factory=lambda: [\"streamable-http\"], description=\"Supported transports\"\n )\n is_enabled: bool = Field(True, description=\"Whether to enable on creation\")\n\n\nclass VirtualServerConfig(BaseModel):\n \"\"\"Full virtual MCP server configuration.\"\"\"\n\n path: str = Field(..., description=\"Virtual server path\")\n server_name: str = Field(..., description=\"Display name\")\n description: str | None = Field(None, description=\"Description\")\n tool_mappings: list[ToolMapping] = Field(default_factory=list, description=\"Tool mappings\")\n required_scopes: list[str] = Field(default_factory=list, description=\"Server-level scopes\")\n tool_scope_overrides: list[ToolScopeOverride] = Field(\n default_factory=list, description=\"Per-tool scope overrides\"\n )\n tags: list[str] = Field(default_factory=list, description=\"Tags\")\n supported_transports: list[str] = Field(\n default_factory=list, description=\"Supported transports\"\n )\n is_enabled: bool = Field(False, description=\"Whether enabled\")\n num_stars: float = Field(0.0, description=\"Average rating\")\n rating_details: list[dict[str, Any]] = Field(\n default_factory=list, description=\"Individual ratings\"\n )\n created_by: str | None = Field(None, description=\"Creator username\")\n created_at: str | None = Field(None, description=\"Creation timestamp\")\n updated_at: str | None = Field(None, description=\"Last update timestamp\")\n\n\nclass VirtualServerListResponse(BaseModel):\n \"\"\"Response for listing virtual servers.\"\"\"\n\n virtual_servers: list[VirtualServerConfig] = Field(\n default_factory=list, description=\"Virtual servers\"\n )\n total: int = Field(0, description=\"Total count\")\n\n\nclass VirtualServerToggleResponse(BaseModel):\n \"\"\"Response from toggling a virtual server.\"\"\"\n\n path: str = Field(..., description=\"Virtual server path\")\n is_enabled: bool = Field(..., description=\"New enabled state\")\n message: str = Field(..., description=\"Status message\")\n\n\nclass VirtualServerDeleteResponse(BaseModel):\n \"\"\"Response from deleting a virtual server.\"\"\"\n\n path: str = Field(..., description=\"Deleted virtual server path\")\n message: str = Field(..., description=\"Status message\")\n\n\nclass SemanticSearchResponse(BaseModel):\n \"\"\"Comprehensive semantic search response with all entity types.\"\"\"\n\n query: str = Field(..., description=\"Search query\")\n search_mode: str = Field(\"hybrid\", description=\"Search mode: hybrid or lexical-only\")\n servers: list[SemanticDiscoveredServer] = Field(\n default_factory=list, description=\"Matching servers\"\n )\n tools: list[ToolSearchResult] = Field(default_factory=list, description=\"Matching tools\")\n agents: list[AgentSearchResult] = Field(default_factory=list, description=\"Matching agents\")\n skills: list[SkillSearchResult] = Field(default_factory=list, description=\"Matching skills\")\n virtual_servers: list[VirtualServerSearchResult] = Field(\n default_factory=list, description=\"Matching virtual servers\"\n )\n total_servers: int = Field(0, description=\"Total server count\")\n total_tools: int = Field(0, description=\"Total tool count\")\n total_agents: int = Field(0, description=\"Total agent count\")\n total_skills: int = Field(0, description=\"Total skill count\")\n total_virtual_servers: int = Field(0, description=\"Total virtual server count\")\n\n\nclass ServerSemanticSearchResponse(BaseModel):\n \"\"\"Server semantic search response model (legacy, use SemanticSearchResponse).\"\"\"\n\n query: str = Field(..., description=\"Search query\")\n servers: list[SemanticDiscoveredServer] = Field(\n default_factory=list, description=\"Matching servers\"\n )\n\n\nclass RatingDetail(BaseModel):\n \"\"\"Individual rating detail.\"\"\"\n\n user: str = Field(..., description=\"Username who submitted the rating\")\n rating: int = Field(..., ge=1, le=5, description=\"Rating value (1-5 stars)\")\n\n\nclass RatingRequest(BaseModel):\n \"\"\"Rating submission request.\"\"\"\n\n rating: int = Field(..., ge=1, le=5, description=\"Rating value (1-5 stars)\")\n\n\nclass RatingResponse(BaseModel):\n \"\"\"Rating submission response.\"\"\"\n\n message: str = Field(..., description=\"Success message\")\n average_rating: float = Field(..., ge=1.0, le=5.0, description=\"Updated average rating\")\n\n\nclass RatingInfoResponse(BaseModel):\n \"\"\"Rating information response.\"\"\"\n\n num_stars: float = Field(..., ge=0.0, le=5.0, description=\"Average rating (0.0 if no ratings)\")\n rating_details: list[RatingDetail] = Field(..., description=\"Individual ratings (max 100)\")\n\n\n# Anthropic Registry API Models (v0.1)\n\n\nclass AnthropicRepository(BaseModel):\n \"\"\"Repository metadata for MCP server source code (Anthropic Registry API).\"\"\"\n\n url: str = Field(..., description=\"Repository URL for browsing source code\")\n source: str = Field(..., description=\"Repository hosting service identifier (e.g., 'github')\")\n id: str | None = Field(None, description=\"Repository ID from hosting service\")\n subfolder: str | None = Field(None, description=\"Path within monorepo\")\n\n\nclass AnthropicStdioTransport(BaseModel):\n \"\"\"Standard I/O transport configuration (Anthropic Registry API).\"\"\"\n\n type: str = Field(default=\"stdio\")\n command: str | None = Field(None, description=\"Command to execute\")\n args: list[str] | None = Field(None, description=\"Command arguments\")\n env: dict[str, str] | None = Field(None, description=\"Environment variables\")\n\n\nclass AnthropicStreamableHttpTransport(BaseModel):\n \"\"\"HTTP-based transport configuration (Anthropic Registry API).\"\"\"\n\n type: str = Field(default=\"streamable-http\")\n url: str = Field(..., description=\"HTTP endpoint URL\")\n headers: dict[str, str] | None = Field(None, description=\"HTTP headers\")\n\n\nclass AnthropicSseTransport(BaseModel):\n \"\"\"Server-Sent Events transport configuration (Anthropic Registry API).\"\"\"\n\n type: str = Field(default=\"sse\")\n url: str = Field(..., description=\"SSE endpoint URL\")\n\n\nclass AnthropicPackage(BaseModel):\n \"\"\"Package information for MCP server distribution (Anthropic Registry API).\"\"\"\n\n registryType: str = Field(..., description=\"Registry type (npm, pypi, oci, etc.)\")\n identifier: str = Field(..., description=\"Package identifier or URL\")\n version: str = Field(..., description=\"Specific package version\")\n registryBaseUrl: str | None = Field(None, description=\"Base URL of package registry\")\n transport: dict[str, Any] = Field(..., description=\"Transport configuration\")\n runtimeHint: str | None = Field(None, description=\"Runtime hint (npx, uvx, docker, etc.)\")\n\n\nclass AnthropicServerDetail(BaseModel):\n \"\"\"Detailed MCP server information (Anthropic Registry API).\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n name: str = Field(..., description=\"Server name in reverse-DNS format\")\n description: str = Field(..., description=\"Server description\")\n version: str = Field(..., description=\"Server version\")\n title: str | None = Field(None, description=\"Human-readable server name\")\n repository: AnthropicRepository | None = Field(None, description=\"Repository information\")\n websiteUrl: str | None = Field(None, description=\"Server website URL\")\n packages: list[AnthropicPackage] | None = Field(None, description=\"Package distributions\")\n meta: dict[str, Any] | None = Field(\n None, alias=\"_meta\", serialization_alias=\"_meta\", description=\"Extensible metadata\"\n )\n\n\nclass AnthropicServerResponse(BaseModel):\n \"\"\"Response for single server query (Anthropic Registry API).\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n server: AnthropicServerDetail = Field(..., description=\"Server details\")\n meta: dict[str, Any] | None = Field(\n None, alias=\"_meta\", serialization_alias=\"_meta\", description=\"Registry-managed metadata\"\n )\n\n\nclass AnthropicPaginationMetadata(BaseModel):\n \"\"\"Pagination information for server lists (Anthropic Registry API).\"\"\"\n\n nextCursor: str | None = Field(None, description=\"Cursor for next page\")\n count: int | None = Field(None, description=\"Number of items in current page\")\n\n\nclass AnthropicServerList(BaseModel):\n \"\"\"Response for server list queries (Anthropic Registry API).\"\"\"\n\n servers: list[AnthropicServerResponse] = Field(..., description=\"List of servers\")\n metadata: AnthropicPaginationMetadata | None = Field(None, description=\"Pagination info\")\n\n\nclass AnthropicErrorResponse(BaseModel):\n \"\"\"Standard error response (Anthropic Registry API).\"\"\"\n\n error: str = Field(..., description=\"Error message\")\n\n\n# Registry Card Models\n\n\nclass RegistryCapabilitiesResponse(BaseModel):\n \"\"\"Registry capabilities response model.\"\"\"\n\n servers: bool = Field(..., description=\"Supports MCP server registry\")\n agents: bool = Field(..., description=\"Supports A2A agent registry\")\n skills: bool = Field(..., description=\"Supports skill registry\")\n prompts: bool = Field(False, description=\"Supports prompt registry\")\n security_scans: bool = Field(True, description=\"Supports security scanning\")\n incremental_sync: bool = Field(False, description=\"Supports incremental federation sync\")\n webhooks: bool = Field(False, description=\"Supports webhook notifications\")\n\n\nclass RegistryAuthConfigResponse(BaseModel):\n \"\"\"Registry authentication configuration response model.\"\"\"\n\n schemes: list[str] = Field(..., description=\"Supported auth schemes (bearer, oauth2, etc.)\")\n oauth2_issuer: str | None = Field(None, description=\"OAuth2 issuer URL\")\n oauth2_token_endpoint: str | None = Field(None, description=\"OAuth2 token endpoint URL\")\n scopes_supported: list[str] = Field(default_factory=list, description=\"Supported OAuth2 scopes\")\n\n\nclass RegistryContactResponse(BaseModel):\n \"\"\"Registry contact information response model.\"\"\"\n\n email: str | None = Field(None, description=\"Contact email address\")\n url: str | None = Field(None, description=\"Contact URL\")\n\n\nclass RegistryCardResponse(BaseModel):\n \"\"\"Registry Card response model.\"\"\"\n\n schema_version: str = Field(..., description=\"Registry card schema version\")\n id: str = Field(..., description=\"Unique registry identifier (UUID)\")\n name: str = Field(..., description=\"Registry name\")\n description: str | None = Field(None, description=\"Registry description\")\n registry_url: str | None = Field(None, description=\"Base URL of this registry\")\n organization_name: str | None = Field(None, description=\"Organization operating this registry\")\n federation_api_version: str = Field(..., description=\"Federation API version\")\n federation_endpoint: str = Field(..., description=\"Federation endpoint URL\")\n capabilities: RegistryCapabilitiesResponse = Field(..., description=\"Registry capabilities\")\n authentication: RegistryAuthConfigResponse = Field(\n ..., description=\"Authentication configuration\"\n )\n visibility_policy: str = Field(..., description=\"Default visibility policy\")\n contact: RegistryContactResponse | None = Field(None, description=\"Contact information\")\n metadata: dict[str, Any] = Field(default_factory=dict, description=\"Additional metadata\")\n created_at: str | None = Field(None, description=\"Creation timestamp\")\n updated_at: str | None = Field(None, description=\"Last update timestamp\")\n\n\n# Management API Models (IAM/User Management)\n\n\nclass M2MAccountRequest(BaseModel):\n \"\"\"Request model for creating M2M service account.\"\"\"\n\n name: str = Field(..., min_length=1, description=\"Service account name/client ID\")\n groups: list[str] = Field(..., min_length=1, description=\"List of group names\")\n description: str | None = Field(None, description=\"Account description\")\n\n\nclass HumanUserRequest(BaseModel):\n \"\"\"Request model for creating human user account.\"\"\"\n\n username: str = Field(..., min_length=1, description=\"Username\")\n email: str = Field(..., description=\"Email address\")\n first_name: str = Field(..., min_length=1, description=\"First name\")\n last_name: str = Field(..., min_length=1, description=\"Last name\")\n groups: list[str] = Field(..., min_length=1, description=\"List of group names\")\n password: str | None = Field(None, description=\"Initial password\")\n\n\nclass UserSummary(BaseModel):\n \"\"\"User summary model.\"\"\"\n\n id: str = Field(..., description=\"User ID\")\n username: str = Field(..., description=\"Username\")\n email: str | None = Field(None, description=\"Email address\")\n firstName: str | None = Field(None, description=\"First name\")\n lastName: str | None = Field(None, description=\"Last name\")\n enabled: bool = Field(True, description=\"Whether user is enabled\")\n groups: list[str] = Field(default_factory=list, description=\"User groups\")\n\n\nclass UserListResponse(BaseModel):\n \"\"\"Response model for list users endpoint.\"\"\"\n\n users: list[UserSummary] = Field(default_factory=list, description=\"List of users\")\n total: int = Field(..., description=\"Total number of users\")\n\n\nclass UserDeleteResponse(BaseModel):\n \"\"\"Response model for delete user endpoint.\"\"\"\n\n username: str = Field(..., description=\"Deleted username\")\n deleted: bool = Field(True, description=\"Deletion status\")\n\n\nclass M2MAccountResponse(BaseModel):\n \"\"\"Response model for M2M account creation.\"\"\"\n\n client_id: str = Field(..., description=\"Client ID (app ID in Entra)\")\n client_secret: str = Field(..., description=\"Client secret\")\n groups: list[str] = Field(default_factory=list, description=\"Assigned groups\")\n client_uuid: str | None = Field(None, description=\"Client UUID (Entra app object ID)\")\n service_principal_id: str | None = Field(None, description=\"Service principal ID (Entra)\")\n\n\nclass GroupCreateRequest(BaseModel):\n \"\"\"Request model for creating a Keycloak group.\"\"\"\n\n name: str = Field(..., min_length=1, description=\"Group name\")\n description: str | None = Field(None, description=\"Group description\")\n\n\nclass GroupSummary(BaseModel):\n \"\"\"Group summary model.\"\"\"\n\n id: str = Field(..., description=\"Group ID\")\n name: str = Field(..., description=\"Group name\")\n path: str = Field(..., description=\"Group path\")\n attributes: dict[str, Any] | None = Field(None, description=\"Group attributes\")\n\n\nclass IdPM2MClient(BaseModel):\n \"\"\"M2M client record as stored in idp_m2m_clients.\n\n Models the response shape from the /api/iam/m2m-clients direct\n registration API (issue #851).\n \"\"\"\n\n client_id: str = Field(..., description=\"IdP application client ID\")\n name: str = Field(..., description=\"Application name\")\n description: str | None = Field(None, description=\"Application description\")\n groups: list[str] = Field(default_factory=list, description=\"Groups this client belongs to\")\n enabled: bool = Field(True, description=\"Whether the client is active\")\n provider: str = Field(..., description=\"Identity provider (okta, keycloak, entra, manual)\")\n idp_app_id: str | None = Field(None, description=\"IdP internal app ID\")\n created_by: str | None = Field(\n None, description=\"Operator who registered this client (manual records)\"\n )\n created_at: datetime = Field(..., description=\"Creation timestamp\")\n updated_at: datetime = Field(..., description=\"Last update timestamp\")\n\n\nclass M2MClientListResponse(BaseModel):\n \"\"\"Paginated response for GET /api/iam/m2m-clients.\"\"\"\n\n total: int = Field(..., description=\"Total number of matching records\")\n limit: int = Field(..., description=\"Limit applied to this page\")\n skip: int = Field(..., description=\"Offset applied to this page\")\n items: list[IdPM2MClient] = Field(default_factory=list, description=\"Records on this page\")\n\n\nclass GroupSyncStatusResponse(BaseModel):\n \"\"\"Response model for list groups endpoint with sync status.\"\"\"\n\n keycloak_groups: list[dict[str, Any]] = Field(\n default_factory=list, description=\"Groups from Keycloak\"\n )\n scopes_groups: dict[str, Any] = Field(\n default_factory=dict, description=\"Groups from scopes storage\"\n )\n synchronized: list[str] = Field(\n default_factory=list, description=\"Groups in both Keycloak and scopes\"\n )\n keycloak_only: list[str] = Field(default_factory=list, description=\"Groups only in Keycloak\")\n scopes_only: list[str] = Field(default_factory=list, description=\"Groups only in scopes\")\n\n\nclass GroupDeleteResponse(BaseModel):\n \"\"\"Response model for delete group endpoint.\"\"\"\n\n name: str = Field(..., description=\"Deleted group name\")\n deleted: bool = Field(True, description=\"Deletion status\")\n\n\n# ==========================================\n# Agent Skills Models\n# ==========================================\n\n\nclass SkillRegistrationRequest(BaseModel):\n \"\"\"Request model for registering a skill.\"\"\"\n\n name: str = Field(..., description=\"Skill name (lowercase alphanumeric with hyphens)\")\n skill_md_url: str = Field(..., description=\"URL to SKILL.md file\")\n description: str | None = Field(None, description=\"Skill description\")\n repository_url: str | None = Field(None, description=\"Repository URL\")\n version: str | None = Field(None, description=\"Skill version (e.g., 1.0.0)\")\n tags: list[str] = Field(default_factory=list, description=\"Tags for categorization\")\n target_agents: list[str] = Field(\n default_factory=list, description=\"Target coding assistants (e.g., claude-code, cursor)\"\n )\n metadata: dict[str, Any] | None = Field(\n None, description=\"Custom metadata key-value pairs for search and organization\"\n )\n visibility: str = Field(default=\"public\", description=\"Visibility: public, private, group\")\n allowed_groups: list[str] = Field(\n default_factory=list, description=\"Groups for group visibility\"\n )\n\n\nclass SkillCard(BaseModel):\n \"\"\"Response model for a skill.\"\"\"\n\n id: UUID = Field(..., description=\"Unique identifier (UUID) for this skill\")\n name: str = Field(..., description=\"Skill name\")\n path: str = Field(..., description=\"Skill path (e.g., /skills/pdf-processing)\")\n description: str | None = Field(None, description=\"Skill description\")\n skill_md_url: str = Field(..., description=\"URL to SKILL.md file\")\n skill_md_raw_url: str | None = Field(None, description=\"Raw content URL\")\n version: str | None = Field(None, description=\"Skill version\")\n author: str | None = Field(None, description=\"Skill author\")\n visibility: str = Field(default=\"public\", description=\"Visibility level\")\n is_enabled: bool = Field(default=True, description=\"Whether skill is enabled\")\n tags: list[str] = Field(default_factory=list, description=\"Tags\")\n target_agents: list[str] = Field(default_factory=list, description=\"Target coding assistants\")\n metadata: dict[str, Any] | None = Field(\n None, description=\"Skill metadata (author, version, extra)\"\n )\n owner: str | None = Field(None, description=\"Skill owner\")\n registry_name: str | None = Field(None, description=\"Source registry\")\n num_stars: float = Field(default=0, description=\"Average rating\")\n health_status: str = Field(default=\"unknown\", description=\"Health status\")\n status: str = Field(\n default=\"active\",\n description=\"Lifecycle status (active, deprecated, draft, beta)\",\n )\n created_at: str | None = Field(None, description=\"Creation timestamp\")\n updated_at: str | None = Field(None, description=\"Last update timestamp\")\n\n\nclass SkillListResponse(BaseModel):\n \"\"\"Response model for listing skills.\"\"\"\n\n skills: list[SkillCard] = Field(default_factory=list, description=\"List of skills\")\n total_count: int = Field(0, description=\"Total number of skills\")\n limit: int = Field(..., description=\"Page size applied\")\n offset: int = Field(..., description=\"Offset applied\")\n has_next: bool = Field(..., description=\"Whether more pages exist\")\n\n\nclass SkillHealthResponse(BaseModel):\n \"\"\"Response model for skill health check.\"\"\"\n\n path: str = Field(..., description=\"Skill path\")\n healthy: bool = Field(..., description=\"Whether SKILL.md is accessible\")\n status_code: int | None = Field(None, description=\"HTTP status code\")\n error: str | None = Field(None, description=\"Error message if unhealthy\")\n response_time_ms: float | None = Field(None, description=\"Response time in ms\")\n\n\nclass SkillContentResponse(BaseModel):\n \"\"\"Response model for skill content.\"\"\"\n\n content: str = Field(..., description=\"SKILL.md content\")\n url: str = Field(..., description=\"URL content was fetched from\")\n\n\nclass SkillSearchResponse(BaseModel):\n \"\"\"Response model for skill search.\"\"\"\n\n query: str = Field(..., description=\"Search query\")\n skills: list[dict[str, Any]] = Field(default_factory=list, description=\"Matching skills\")\n total_count: int = Field(0, description=\"Total matches\")\n\n\nclass SkillToggleResponse(BaseModel):\n \"\"\"Response model for skill toggle.\"\"\"\n\n path: str = Field(..., description=\"Skill path\")\n is_enabled: bool = Field(..., description=\"New enabled state\")\n\n\nclass SkillRatingResponse(BaseModel):\n \"\"\"Response model for skill rating.\"\"\"\n\n num_stars: float = Field(..., description=\"Average rating\")\n rating_details: list[dict[str, Any]] = Field(\n default_factory=list, description=\"Individual ratings\"\n )\n\n\nclass AppLogEntry(BaseModel):\n \"\"\"Single application log entry.\"\"\"\n\n timestamp: str = Field(..., description=\"Log timestamp (ISO-8601)\")\n hostname: str = Field(..., description=\"Pod/hostname that emitted the log\")\n service: str = Field(..., description=\"Service name (registry, auth-server)\")\n level: str = Field(..., description=\"Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\")\n level_no: int = Field(..., description=\"Numeric log level\")\n logger: str = Field(..., description=\"Python logger name\")\n filename: str = Field(..., description=\"Source filename\")\n lineno: int = Field(..., description=\"Source line number\")\n process: int = Field(..., description=\"Process ID\")\n message: str = Field(..., description=\"Log message\")\n\n\nclass AppLogResponse(BaseModel):\n \"\"\"Response model for application log query.\"\"\"\n\n entries: list[AppLogEntry] = Field(default_factory=list, description=\"Log entries\")\n total_count: int = Field(0, description=\"Total matching entries\")\n limit: int = Field(100, description=\"Applied page size\")\n offset: int = Field(0, description=\"Applied offset\")\n has_next: bool = Field(False, description=\"Whether more entries exist\")\n\n\nclass AppLogMetadataResponse(BaseModel):\n \"\"\"Response model for application log metadata.\"\"\"\n\n services: list[str] = Field(default_factory=list, description=\"Available service names\")\n hostnames: list[str] = Field(default_factory=list, description=\"Available hostnames\")\n levels: list[str] = Field(default_factory=list, description=\"Available log levels\")\n\n\nclass RegistryClient:\n \"\"\"\n MCP Gateway Registry API client.\n\n Provides methods for interacting with the Registry API endpoints including:\n - Server Management: registration, removal, toggling, health checks\n - Group Management: create, delete, list groups\n - Agent Management: register, update, delete, discover agents (A2A)\n - Management API: IAM/user management, M2M accounts, user CRUD operations\n\n Authentication is handled via JWT tokens passed to the constructor.\n \"\"\"\n\n def __init__(self, registry_url: str, token: str):\n \"\"\"\n Initialize the Registry Client.\n\n Args:\n registry_url: Base URL of the registry (e.g., https://registry.mycorp.click)\n token: JWT access token for authentication\n \"\"\"\n self.registry_url = registry_url.rstrip(\"/\")\n self._token = token\n\n # Redact token in logs - show only first 8 characters\n redacted_token = f\"{token[:8]}...\" if len(token) > 8 else \"***\"\n logger.info(f\"Initialized RegistryClient for {self.registry_url} (token: {redacted_token})\")\n\n def _get_headers(self) -> dict[str, str]:\n \"\"\"\n Get request headers with JWT token.\n\n Returns:\n Dictionary of HTTP headers\n \"\"\"\n return {\"Authorization\": f\"Bearer {self._token}\"}\n\n def _make_request(\n self,\n method: str,\n endpoint: str,\n data: dict[str, Any] | None = None,\n params: dict[str, Any] | None = None,\n ) -> requests.Response:\n \"\"\"\n Make HTTP request to the Registry API.\n\n Args:\n method: HTTP method (GET, POST, etc.)\n endpoint: API endpoint path\n data: Request body data (sent as form-encoded for POST)\n params: Query parameters\n\n Returns:\n Response object\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n url = f\"{self.registry_url}{endpoint}\"\n headers = self._get_headers()\n\n logger.debug(f\"{method} {url}\")\n\n # Determine content type based on endpoint\n # Agent, Management, Search, Federation, Skills, Virtual Servers, Registry Card, version, and group import endpoints use JSON\n # Server registration uses form data\n if (\n endpoint.startswith(\"/api/agents\")\n or endpoint.startswith(\"/api/management\")\n or endpoint.startswith(\"/api/iam\")\n or endpoint.startswith(\"/api/search\")\n or endpoint.startswith(\"/api/federation\")\n or endpoint.startswith(\"/api/peers\")\n or endpoint.startswith(\"/api/skills\")\n or endpoint.startswith(\"/api/virtual-servers\")\n or endpoint.startswith(\"/api/v1/registry\")\n or endpoint.startswith(\"/api/v1/health\")\n or endpoint == \"/api/servers/groups/import\"\n or \"/auth-credential\" in endpoint\n or \"/versions\" in endpoint\n ):\n # Send as JSON for agent, management, search, federation, and import endpoints\n response = requests.request(\n method=method, url=url, headers=headers, json=data, params=params, timeout=120\n )\n else:\n # Send as form-encoded for server registration\n response = requests.request(\n method=method, url=url, headers=headers, data=data, params=params, timeout=120\n )\n\n try:\n response.raise_for_status()\n except requests.HTTPError as e:\n # For 422 errors, try to extract validation details\n if response.status_code == 422:\n try:\n error_detail = response.json()\n logger.error(f\"Validation error details: {json.dumps(error_detail, indent=2)}\")\n except Exception as e:\n logger.warning(f\"Could not parse 422 error response as JSON: {e}\")\n raise\n return response\n\n def register_service(self, registration: InternalServiceRegistration) -> ServiceResponse:\n \"\"\"\n Register a new service in the registry.\n\n Args:\n registration: Service registration data\n\n Returns:\n Service response with registration details\n\n Raises:\n requests.HTTPError: If registration fails\n \"\"\"\n logger.info(f\"Registering service: {registration.service_path}\")\n\n # Convert model to dict\n data = registration.model_dump(exclude_none=True, by_alias=True)\n\n # Convert tags list to comma-separated string for form encoding\n if \"tags\" in data and isinstance(data[\"tags\"], list):\n data[\"tags\"] = \",\".join(data[\"tags\"])\n\n # Convert external_tags list to comma-separated string for form encoding\n if \"external_tags\" in data and isinstance(data[\"external_tags\"], list):\n data[\"external_tags\"] = \",\".join(data[\"external_tags\"])\n\n # Convert metadata dict to JSON string for form encoding\n if \"metadata\" in data and isinstance(data[\"metadata\"], dict):\n data[\"metadata\"] = json.dumps(data[\"metadata\"])\n\n response = self._make_request(method=\"POST\", endpoint=\"/api/servers/register\", data=data)\n\n logger.info(f\"Service registered successfully: {registration.service_path}\")\n return ServiceResponse(**response.json())\n\n def remove_service(self, service_path: str) -> dict[str, Any]:\n \"\"\"\n Remove a service from the registry.\n\n Args:\n service_path: Path of service to remove\n\n Returns:\n Response data\n\n Raises:\n requests.HTTPError: If removal fails\n \"\"\"\n logger.info(f\"Removing service: {service_path}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/servers/remove\", data={\"path\": service_path}\n )\n\n logger.info(f\"Service removed successfully: {service_path}\")\n return response.json()\n\n def toggle_service(self, service_path: str) -> ToggleResponse:\n \"\"\"\n Toggle service enabled/disabled status.\n\n Args:\n service_path: Path of service to toggle\n\n Returns:\n Toggle response with current status\n\n Raises:\n requests.HTTPError: If toggle fails\n \"\"\"\n logger.info(f\"Toggling service: {service_path}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/servers/toggle\", data={\"service_path\": service_path}\n )\n\n result = ToggleResponse(**response.json())\n logger.info(f\"Service toggled: {service_path} -> enabled={result.is_enabled}\")\n return result\n\n def update_server_credential(\n self,\n service_path: str,\n auth_scheme: str,\n auth_credential: str = None,\n auth_header_name: str = None,\n ) -> dict[str, Any]:\n \"\"\"\n Update authentication credentials for a server.\n\n Args:\n service_path: Path of server to update (e.g., /my-server)\n auth_scheme: Authentication scheme (none, bearer, api_key)\n auth_credential: New credential (required if auth_scheme is not 'none')\n auth_header_name: Custom header name (optional, for api_key)\n\n Returns:\n Response dict with message and updated auth details\n\n Raises:\n requests.HTTPError: If update fails\n \"\"\"\n logger.info(f\"Updating auth credential for: {service_path}\")\n\n # Build payload\n payload = {\"auth_scheme\": auth_scheme}\n if auth_credential:\n payload[\"auth_credential\"] = auth_credential\n if auth_header_name:\n payload[\"auth_header_name\"] = auth_header_name\n\n response = self._make_request(\n method=\"PATCH\", endpoint=f\"/api/servers{service_path}/auth-credential\", data=payload\n )\n\n result = response.json()\n logger.info(f\"Credential updated for {service_path}: scheme={result.get('auth_scheme')}\")\n return result\n\n def list_services(\n self,\n limit: int = 20,\n offset: int = 0,\n ) -> ServerListResponse:\n \"\"\"\n List all services in the registry.\n\n Args:\n limit: Maximum number of services to return per page\n offset: Number of services to skip for pagination\n\n Returns:\n Server list response\n\n Raises:\n requests.HTTPError: If list operation fails\n \"\"\"\n logger.info(\"Listing all services\")\n\n params = {\n \"limit\": limit,\n \"offset\": offset,\n }\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/servers\", params=params)\n\n response_data = response.json()\n logger.debug(f\"Raw API response: {json.dumps(response_data, indent=2, default=str)}\")\n\n try:\n result = ServerListResponse(**response_data)\n logger.info(\n f\"Retrieved {len(result.servers)} services\"\n f\" (total={result.total_count}, offset={result.offset},\"\n f\" limit={result.limit}, has_next={result.has_next})\"\n )\n return result\n except Exception as e:\n logger.error(f\"Failed to parse server list response: {e}\")\n logger.error(f\"Raw response data: {json.dumps(response_data, indent=2, default=str)}\")\n raise\n\n def healthcheck(self) -> dict[str, Any]:\n \"\"\"\n Perform health check on all services.\n\n Returns:\n Health check response with service statuses\n\n Raises:\n requests.HTTPError: If health check fails\n \"\"\"\n logger.info(\"Performing health check on all services\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/servers/health\")\n\n result = response.json()\n logger.info(f\"Health check completed: {result.get('status', 'unknown')}\")\n return result\n\n def get_config(self) -> dict[str, Any]:\n \"\"\"\n Get registry configuration including deployment mode and features.\n\n Returns:\n Configuration response with deployment_mode, registry_mode,\n nginx_updates_enabled, and features dict\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Fetching registry configuration\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/config\")\n\n result = response.json()\n logger.info(\n f\"Registry config: deployment_mode={result.get('deployment_mode')}, \"\n f\"registry_mode={result.get('registry_mode')}\"\n )\n return result\n\n def get_well_known_registry_card(self) -> RegistryCardResponse:\n \"\"\"\n Get the Registry Card via .well-known discovery endpoint.\n\n This is the standard discovery endpoint for registry federation, following\n the .well-known convention used for service discovery (similar to\n .well-known/openid-configuration).\n\n Returns:\n Registry Card response with registry metadata\n\n Raises:\n requests.HTTPError: If request fails or card not initialized\n \"\"\"\n logger.info(\"Fetching registry card via .well-known endpoint\")\n\n response = self._make_request(\n method=\"GET\", endpoint=\"/api/v1/registry/.well-known/registry-card\"\n )\n\n result = RegistryCardResponse(**response.json())\n logger.info(f\"Retrieved registry card: {result.id} (name: {result.name})\")\n return result\n\n def get_registry_card(self) -> RegistryCardResponse:\n \"\"\"\n Get the Registry Card for this registry instance.\n\n The Registry Card provides metadata about the registry including:\n - Capabilities (servers, agents, skills, security scans, etc.)\n - Authentication configuration\n - Federation API version and endpoint\n - Contact information\n\n Returns:\n Registry Card response with registry metadata\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Fetching registry card\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/v1/registry/card\")\n\n result = RegistryCardResponse(**response.json())\n logger.info(f\"Retrieved registry card: {result.id} (name: {result.name})\")\n return result\n\n def update_registry_card(self, card_data: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Update the Registry Card (admin only).\n\n This replaces the entire registry card with the provided data.\n For partial updates, use patch_registry_card() instead.\n\n Args:\n card_data: Complete registry card data\n\n Returns:\n Response with update confirmation\n\n Raises:\n requests.HTTPError: If update fails (e.g., insufficient permissions)\n \"\"\"\n logger.info(\"Updating registry card\")\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/v1/registry/card\", data=card_data\n )\n\n result = response.json()\n logger.info(\"Registry card updated successfully\")\n return result\n\n def patch_registry_card(self, updates: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Partially update the Registry Card (admin only).\n\n Only the fields provided in updates will be modified.\n Other fields will remain unchanged.\n\n Args:\n updates: Partial registry card updates\n\n Returns:\n Response with update confirmation\n\n Raises:\n requests.HTTPError: If update fails (e.g., insufficient permissions)\n \"\"\"\n logger.info(f\"Patching registry card with updates: {list(updates.keys())}\")\n\n response = self._make_request(\n method=\"PATCH\", endpoint=\"/api/v1/registry/card\", data=updates\n )\n\n result = response.json()\n logger.info(\"Registry card patched successfully\")\n return result\n\n def add_server_to_groups(self, server_name: str, group_names: list[str]) -> dict[str, Any]:\n \"\"\"\n Add a server to user groups.\n\n Args:\n server_name: Name of server\n group_names: List of group names\n\n Returns:\n Response data\n\n Raises:\n requests.HTTPError: If operation fails\n \"\"\"\n logger.info(f\"Adding server {server_name} to groups: {group_names}\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/servers/groups/add\",\n data={\"server_name\": server_name, \"group_names\": \",\".join(group_names)},\n )\n\n logger.info(\"Server added to groups successfully\")\n return response.json()\n\n def remove_server_from_groups(self, server_name: str, group_names: list[str]) -> dict[str, Any]:\n \"\"\"\n Remove a server from user groups.\n\n Args:\n server_name: Name of server\n group_names: List of group names\n\n Returns:\n Response data\n\n Raises:\n requests.HTTPError: If operation fails\n \"\"\"\n logger.info(f\"Removing server {server_name} from groups: {group_names}\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/servers/groups/remove\",\n data={\"server_name\": server_name, \"group_names\": \",\".join(group_names)},\n )\n\n logger.info(\"Server removed from groups successfully\")\n return response.json()\n\n def create_group(\n self, group_name: str, description: str | None = None, create_in_idp: bool = False\n ) -> dict[str, Any]:\n \"\"\"\n Create a new user group.\n\n Args:\n group_name: Name of group\n description: Group description\n create_in_idp: Whether to create in IdP (Keycloak/Entra)\n\n Returns:\n Response data\n\n Raises:\n requests.HTTPError: If creation fails\n \"\"\"\n logger.info(f\"Creating group: {group_name}\")\n\n data = {\"group_name\": group_name}\n if description:\n data[\"description\"] = description\n data[\"create_in_idp\"] = str(create_in_idp).lower()\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/servers/groups/create\", data=data\n )\n\n logger.info(f\"Group created successfully: {group_name}\")\n return response.json()\n\n def delete_group(\n self, group_name: str, delete_from_idp: bool = False, force: bool = False\n ) -> dict[str, Any]:\n \"\"\"\n Delete a user group.\n\n Args:\n group_name: Name of group\n delete_from_idp: Whether to delete from IdP (Keycloak/Entra)\n force: Force deletion of system groups\n\n Returns:\n Response data\n\n Raises:\n requests.HTTPError: If deletion fails\n \"\"\"\n logger.info(f\"Deleting group: {group_name}\")\n\n data = {\"group_name\": group_name}\n if delete_from_idp:\n data[\"delete_from_idp\"] = True\n if force:\n data[\"force\"] = True\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/servers/groups/delete\", data=data\n )\n\n logger.info(f\"Group deleted successfully: {group_name}\")\n return response.json()\n\n def import_group(self, group_definition: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Import a complete group definition.\n\n Args:\n group_definition: Complete group definition including:\n - scope_name (required): Name of the scope/group\n - scope_type (optional): Type of scope (default: \"server_scope\")\n - description (optional): Description of the group\n - server_access (optional): List of server access definitions\n - group_mappings (optional): List of group mappings\n - ui_permissions (optional): Dictionary of UI permissions\n - create_in_idp (optional): Whether to create in IdP (default: false)\n\n Returns:\n Response data\n\n Raises:\n requests.HTTPError: If import fails\n \"\"\"\n scope_name = group_definition.get(\"scope_name\")\n if not scope_name:\n raise ValueError(\"scope_name is required in group_definition\")\n\n logger.info(f\"Importing group definition: {scope_name}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/servers/groups/import\", data=group_definition\n )\n\n logger.info(f\"Group imported successfully: {scope_name}\")\n return response.json()\n\n def list_groups(\n self, include_keycloak: bool = True, include_scopes: bool = True\n ) -> GroupSyncStatusResponse:\n \"\"\"\n List all user groups.\n\n Args:\n include_keycloak: Include Keycloak information\n include_scopes: Include scope information\n\n Returns:\n Group list response with sync status\n\n Raises:\n requests.HTTPError: If list operation fails\n \"\"\"\n logger.info(\"Listing all groups\")\n\n params = {\n \"include_keycloak\": str(include_keycloak).lower(),\n \"include_scopes\": str(include_scopes).lower(),\n }\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/servers/groups\", params=params)\n\n result = GroupSyncStatusResponse(**response.json())\n total_groups = len(result.scopes_groups) + len(result.keycloak_groups)\n logger.info(\n f\"Retrieved {total_groups} groups ({len(result.keycloak_groups)} from Keycloak, {len(result.scopes_groups)} from scopes)\"\n )\n return result\n\n def get_group(self, group_name: str) -> dict[str, Any]:\n \"\"\"\n Get full details of a specific group.\n\n Args:\n group_name: Name of the group\n\n Returns:\n Complete group definition with server_access, group_mappings, and ui_permissions\n\n Raises:\n requests.HTTPError: If get operation fails (404 if group not found)\n \"\"\"\n logger.info(f\"Getting group details: {group_name}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/servers/groups/{group_name}\")\n\n logger.info(f\"Retrieved group details for {group_name}\")\n return response.json()\n\n # Agent Management Methods\n\n def register_agent(self, agent: AgentRegistration) -> AgentRegistrationResponse:\n \"\"\"\n Register a new A2A agent.\n\n Args:\n agent: Agent registration data\n\n Returns:\n Agent registration response\n\n Raises:\n requests.HTTPError: If registration fails (409 for conflict, 422 for validation error, 403 for permission denied)\n \"\"\"\n logger.info(f\"Registering agent: {agent.path}\")\n\n agent_data = agent.model_dump(exclude_none=True, by_alias=True)\n logger.debug(f\"Agent data being sent: {json.dumps(agent_data, indent=2, default=str)}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/agents/register\", data=agent_data\n )\n\n result = AgentRegistrationResponse(**response.json())\n logger.info(f\"Agent registered successfully: {agent.path}\")\n return result\n\n def list_agents(\n self,\n query: str | None = None,\n enabled_only: bool = False,\n visibility: str | None = None,\n allowed_groups: str | None = None,\n limit: int = 20,\n offset: int = 0,\n ) -> AgentListResponse:\n \"\"\"\n List agents with optional filtering and pagination.\n\n Args:\n query: Search query string\n enabled_only: Show only enabled agents\n visibility: Filter by visibility level (public, private, internal)\n limit: Number of agents to return (1-100, default 20)\n offset: Number of agents to skip (default 0)\n\n Returns:\n Agent list response with pagination metadata\n\n Raises:\n requests.HTTPError: If list operation fails\n \"\"\"\n logger.info(f\"Listing agents (limit={limit}, offset={offset})\")\n\n params: dict[str, str | int | bool] = {\n \"limit\": limit,\n \"offset\": offset,\n }\n if query:\n params[\"query\"] = query\n if enabled_only:\n params[\"enabled_only\"] = \"true\"\n if visibility:\n params[\"visibility\"] = visibility\n if allowed_groups:\n params[\"allowed_groups\"] = allowed_groups\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/agents\", params=params)\n\n result = AgentListResponse(**response.json())\n logger.info(\n f\"Retrieved {len(result.agents)} agents \"\n f\"(total: {result.total_count}, offset: {result.offset}, limit: {result.limit})\"\n )\n return result\n\n def get_agent(self, path: str) -> AgentDetail:\n \"\"\"\n Get detailed information about a specific agent.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n\n Returns:\n Agent detail\n\n Raises:\n requests.HTTPError: If agent not found (404) or unauthorized (403)\n \"\"\"\n logger.info(f\"Getting agent details: {path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/agents{path}\")\n\n result = AgentDetail(**response.json())\n logger.info(f\"Retrieved agent details: {path}\")\n return result\n\n def update_agent(self, path: str, agent: AgentRegistration) -> AgentDetail:\n \"\"\"\n Update an existing agent.\n\n Args:\n path: Agent path\n agent: Updated agent data\n\n Returns:\n Updated agent detail\n\n Raises:\n requests.HTTPError: If update fails (404 for not found, 403 for permission denied, 422 for validation error)\n \"\"\"\n logger.info(f\"Updating agent: {path}\")\n\n response = self._make_request(\n method=\"PUT\",\n endpoint=f\"/api/agents{path}\",\n data=agent.model_dump(exclude_none=True, by_alias=True),\n )\n\n result = AgentDetail(**response.json())\n logger.info(f\"Agent updated successfully: {path}\")\n return result\n\n def delete_agent(self, path: str) -> None:\n \"\"\"\n Delete an agent from the registry.\n\n Args:\n path: Agent path\n\n Raises:\n requests.HTTPError: If deletion fails (404 for not found, 403 for permission denied)\n \"\"\"\n logger.info(f\"Deleting agent: {path}\")\n\n self._make_request(method=\"DELETE\", endpoint=f\"/api/agents{path}\")\n\n logger.info(f\"Agent deleted successfully: {path}\")\n\n def toggle_agent(self, path: str, enabled: bool) -> AgentToggleResponse:\n \"\"\"\n Toggle agent enabled/disabled status.\n\n Args:\n path: Agent path\n enabled: True to enable, False to disable\n\n Returns:\n Agent toggle response\n\n Raises:\n requests.HTTPError: If toggle fails (404 for not found, 403 for permission denied)\n \"\"\"\n logger.info(f\"Toggling agent {path} to {'enabled' if enabled else 'disabled'}\")\n\n params = {\"enabled\": str(enabled).lower()}\n\n response = self._make_request(\n method=\"POST\", endpoint=f\"/api/agents{path}/toggle\", params=params\n )\n\n result = AgentToggleResponse(**response.json())\n logger.info(\n f\"Agent toggled: {path} is now {'enabled' if result.is_enabled else 'disabled'}\"\n )\n return result\n\n def discover_agents_by_skills(\n self, skills: list[str], tags: list[str] | None = None, max_results: int = 10\n ) -> AgentDiscoveryResponse:\n \"\"\"\n Discover agents by required skills.\n\n Args:\n skills: List of required skills\n tags: Optional tag filters\n max_results: Maximum number of results (default: 10, max: 100)\n\n Returns:\n Agent discovery response\n\n Raises:\n requests.HTTPError: If discovery fails (400 for bad request)\n \"\"\"\n logger.info(f\"Discovering agents by skills: {skills}\")\n\n request_data = SkillDiscoveryRequest(skills=skills, tags=tags)\n params = {\"max_results\": max_results}\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/agents/discover\",\n data=request_data.model_dump(exclude_none=True),\n params=params,\n )\n\n result = AgentDiscoveryResponse(**response.json())\n logger.info(f\"Discovered {len(result.agents)} agents matching skills\")\n return result\n\n def discover_agents_semantic(\n self, query: str, max_results: int = 10\n ) -> AgentSemanticDiscoveryResponse:\n \"\"\"\n Discover agents using semantic search (FAISS vector search).\n\n Args:\n query: Natural language query (e.g., \"Find agents that can analyze code\")\n max_results: Maximum number of results (default: 10, max: 100)\n\n Returns:\n Agent semantic discovery response\n\n Raises:\n requests.HTTPError: If discovery fails (400 for bad request, 500 for search error)\n \"\"\"\n logger.info(f\"Discovering agents semantically: {query}\")\n\n params = {\"query\": query, \"max_results\": max_results}\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/agents/discover/semantic\", params=params\n )\n\n result = AgentSemanticDiscoveryResponse(**response.json())\n logger.info(f\"Discovered {len(result.agents)} agents via semantic search\")\n return result\n\n def semantic_search_servers(\n self,\n query: str,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> ServerSemanticSearchResponse:\n \"\"\"\n Search for servers using semantic search (vector search).\n\n Args:\n query: Natural language query (e.g., \"time and date services\")\n max_results: Maximum number of results (default: 10, max: 100)\n include_draft: Include draft assets in results (default: False)\n include_deprecated: Include deprecated assets in results (default: False)\n include_disabled: Include disabled assets in results (default: False)\n\n Returns:\n Server semantic search response\n\n Raises:\n requests.HTTPError: If search fails (400 for bad request, 500 for search error)\n \"\"\"\n logger.info(f\"Searching servers semantically: {query}\")\n\n request_data: dict[str, Any] = {\n \"query\": query,\n \"entity_types\": [\"mcp_server\"],\n \"max_results\": max_results,\n \"include_draft\": include_draft,\n \"include_deprecated\": include_deprecated,\n \"include_disabled\": include_disabled,\n }\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/search/semantic\", data=request_data\n )\n\n result = ServerSemanticSearchResponse(**response.json())\n logger.info(f\"Found {len(result.servers)} servers via semantic search\")\n return result\n\n def semantic_search(\n self,\n query: str,\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> SemanticSearchResponse:\n \"\"\"\n Comprehensive semantic search across all entity types.\n\n Args:\n query: Natural language query (e.g., \"coding assistants\")\n entity_types: Optional list of entity types to search.\n Valid values: \"mcp_server\", \"tool\", \"a2a_agent\", \"skill\", \"virtual_server\"\n If None, searches all entity types.\n max_results: Maximum number of results per entity type (default: 10, max: 50)\n include_draft: Include draft assets in results (default: False)\n include_deprecated: Include deprecated assets in results (default: False)\n include_disabled: Include disabled assets in results (default: False)\n\n Returns:\n SemanticSearchResponse with servers, tools, agents, skills, and virtual_servers\n\n Raises:\n requests.HTTPError: If search fails (400 for bad request, 500 for search error)\n \"\"\"\n logger.info(f\"Semantic search: {query} (entity_types={entity_types})\")\n\n request_data: dict[str, Any] = {\n \"query\": query,\n \"max_results\": max_results,\n \"include_draft\": include_draft,\n \"include_deprecated\": include_deprecated,\n \"include_disabled\": include_disabled,\n }\n if entity_types:\n request_data[\"entity_types\"] = entity_types\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/search/semantic\", data=request_data\n )\n\n result = SemanticSearchResponse(**response.json())\n logger.info(\n f\"Found: {len(result.servers)} servers, {len(result.tools)} tools, \"\n f\"{len(result.agents)} agents, {len(result.skills)} skills, \"\n f\"{len(result.virtual_servers)} virtual servers\"\n )\n return result\n\n def rate_agent(self, path: str, rating: int) -> RatingResponse:\n \"\"\"\n Submit a rating for an agent (1-5 stars).\n\n Each user can only have one active rating. If user has already rated,\n this updates their existing rating. System maintains a rotating buffer\n of the last 100 ratings.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n rating: Rating value (1-5 stars)\n\n Returns:\n Rating response with success message and updated average rating\n\n Raises:\n requests.HTTPError: If rating fails (400 for invalid rating, 403 for unauthorized, 404 for not found)\n \"\"\"\n logger.info(f\"Rating agent '{path}' with {rating} stars\")\n\n request_data = RatingRequest(rating=rating)\n\n response = self._make_request(\n method=\"POST\", endpoint=f\"/api/agents{path}/rate\", data=request_data.model_dump()\n )\n\n result = RatingResponse(**response.json())\n logger.info(f\"Agent '{path}' rated successfully. New average: {result.average_rating:.2f}\")\n return result\n\n def get_agent_rating(self, path: str) -> RatingInfoResponse:\n \"\"\"\n Get rating information for an agent.\n\n Returns average rating and up to 100 most recent individual ratings\n (maintained as rotating buffer).\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n\n Returns:\n Rating information with average and individual ratings\n\n Raises:\n requests.HTTPError: If retrieval fails (403 for unauthorized, 404 for not found)\n \"\"\"\n logger.info(f\"Getting ratings for agent: {path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/agents{path}/rating\")\n\n result = RatingInfoResponse(**response.json())\n logger.info(\n f\"Retrieved ratings for '{path}': {result.num_stars:.2f} stars ({len(result.rating_details)} ratings)\"\n )\n return result\n\n def rescan_agent(self, path: str) -> AgentRescanResponse:\n \"\"\"\n Trigger a manual security scan for an agent.\n\n Initiates a new security scan for the specified agent and returns\n the results. This endpoint is useful for re-scanning agents after\n updates or for on-demand security assessments.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n\n Returns:\n Newly generated security scan results\n\n Raises:\n requests.HTTPError: If scan fails (403 for unauthorized, 404 for not found)\n \"\"\"\n logger.info(f\"Triggering security scan for agent: {path}\")\n\n response = self._make_request(method=\"POST\", endpoint=f\"/api/agents{path}/rescan\")\n\n result = AgentRescanResponse(**response.json())\n logger.info(\n f\"Security scan completed for '{path}': \"\n f\"Safe={result.is_safe}, Critical={result.critical_issues}, \"\n f\"High={result.high_severity}, Medium={result.medium_severity}, \"\n f\"Low={result.low_severity}\"\n )\n return result\n\n def get_agent_security_scan(self, path: str) -> AgentSecurityScanResponse:\n \"\"\"\n Get security scan results for an agent.\n\n Returns the latest security scan results including threat analysis,\n severity levels, and detailed findings from YARA, specification\n validation, and heuristic analyzers.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n\n Returns:\n Security scan results with analysis_results and scan_results\n\n Raises:\n requests.HTTPError: If retrieval fails (403 for unauthorized, 404 for not found)\n \"\"\"\n logger.info(f\"Getting security scan results for agent: {path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/agents{path}/security-scan\")\n\n result = AgentSecurityScanResponse(**response.json())\n logger.info(f\"Retrieved security scan results for '{path}'\")\n return result\n\n def agent_ans_link(\n self,\n path: str,\n ans_agent_id: str,\n ) -> dict[str, Any]:\n \"\"\"\n Link an ANS Agent ID to an agent.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n ans_agent_id: ANS Agent ID (e.g., ans://v1.example.com)\n\n Returns:\n Link result with success status, message, and ans_metadata\n\n Raises:\n requests.HTTPError: If linking fails\n \"\"\"\n logger.info(f\"Linking ANS ID '{ans_agent_id}' to agent: {path}\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=f\"/api/agents{path}/ans/link\",\n data={\"ans_agent_id\": ans_agent_id},\n )\n\n result = response.json()\n logger.info(f\"ANS link result for '{path}': {result.get('message', '')}\")\n return result\n\n def agent_ans_status(\n self,\n path: str,\n ) -> dict[str, Any]:\n \"\"\"\n Get ANS verification status for an agent.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n\n Returns:\n ANS metadata dict with status, domain, ans_agent_id, etc.\n\n Raises:\n requests.HTTPError: If retrieval fails (404 if no ANS link)\n \"\"\"\n logger.info(f\"Getting ANS status for agent: {path}\")\n\n response = self._make_request(\n method=\"GET\",\n endpoint=f\"/api/agents{path}/ans/status\",\n )\n\n result = response.json()\n logger.info(f\"ANS status for '{path}': {result.get('status', 'unknown')}\")\n return result\n\n def agent_ans_unlink(\n self,\n path: str,\n ) -> dict[str, Any]:\n \"\"\"\n Remove ANS link from an agent.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n\n Returns:\n Unlink result with success status and message\n\n Raises:\n requests.HTTPError: If unlinking fails\n \"\"\"\n logger.info(f\"Unlinking ANS from agent: {path}\")\n\n response = self._make_request(\n method=\"DELETE\",\n endpoint=f\"/api/agents{path}/ans/link\",\n )\n\n result = response.json()\n logger.info(f\"ANS unlink result for '{path}': {result.get('message', '')}\")\n return result\n\n def rate_server(self, path: str, rating: int) -> RatingResponse:\n \"\"\"\n Submit a rating for a server (1-5 stars).\n\n Each user can only have one active rating. If user has already rated,\n this updates their existing rating. System maintains a rotating buffer\n of the last 100 ratings.\n\n Args:\n path: Server path (e.g., /cloudflare-docs)\n rating: Rating value (1-5 stars)\n\n Returns:\n Rating response with success message and updated average rating\n\n Raises:\n requests.HTTPError: If rating fails (400 for invalid rating, 403 for unauthorized, 404 for not found)\n \"\"\"\n logger.info(f\"Rating server '{path}' with {rating} stars\")\n\n request_data = RatingRequest(rating=rating)\n\n response = self._make_request(\n method=\"POST\", endpoint=f\"/api/servers{path}/rate\", data=request_data.model_dump()\n )\n\n result = RatingResponse(**response.json())\n logger.info(f\"Server '{path}' rated successfully. New average: {result.average_rating:.2f}\")\n return result\n\n def get_server(\n self,\n path: str,\n ) -> ServerDetailResponse:\n \"\"\"\n Get detailed information about a specific server.\n\n Args:\n path: Server path (e.g., /my-server)\n\n Returns:\n Server detail response\n\n Raises:\n requests.HTTPError: If server not found (404) or unauthorized (403)\n \"\"\"\n logger.info(f\"Getting server details: {path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/servers{path}\")\n\n result = ServerDetailResponse(**response.json())\n logger.info(f\"Retrieved server details: {path}\")\n return result\n\n def get_server_rating(self, path: str) -> RatingInfoResponse:\n \"\"\"\n Get rating information for a server.\n\n Returns average rating and up to 100 most recent individual ratings\n (maintained as rotating buffer).\n\n Args:\n path: Server path (e.g., /cloudflare-docs)\n\n Returns:\n Rating information with average and individual ratings\n\n Raises:\n requests.HTTPError: If retrieval fails (403 for unauthorized, 404 for not found)\n \"\"\"\n logger.info(f\"Getting ratings for server: {path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/servers{path}/rating\")\n\n result = RatingInfoResponse(**response.json())\n logger.info(\n f\"Retrieved ratings for '{path}': {result.num_stars:.2f} stars ({len(result.rating_details)} ratings)\"\n )\n return result\n\n def get_security_scan(self, path: str) -> SecurityScanResult:\n \"\"\"\n Get security scan results for a server.\n\n Returns the latest security scan results including threat analysis,\n severity levels, and detailed findings for each tool.\n\n Args:\n path: Server path (e.g., /cloudflare-docs)\n\n Returns:\n Security scan results with analysis_results and tool_results\n\n Raises:\n requests.HTTPError: If retrieval fails (403 for unauthorized, 404 for not found)\n \"\"\"\n logger.info(f\"Getting security scan results for server: {path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/servers{path}/security-scan\")\n\n result = SecurityScanResult(**response.json())\n logger.info(f\"Retrieved security scan results for '{path}'\")\n return result\n\n def rescan_server(self, path: str) -> RescanResponse:\n \"\"\"\n Trigger a manual security scan for a server.\n\n Initiates a new security scan for the specified server and returns\n the results. This operation is admin-only.\n\n Args:\n path: Server path (e.g., /cloudflare-docs)\n\n Returns:\n Newly generated security scan results\n\n Raises:\n requests.HTTPError: If scan fails (403 for non-admin, 404 for not found, 500 for scan error)\n \"\"\"\n logger.info(f\"Triggering security scan for server: {path}\")\n\n response = self._make_request(method=\"POST\", endpoint=f\"/api/servers{path}/rescan\")\n\n result = RescanResponse(**response.json())\n safety_status = \"SAFE\" if result.is_safe else \"UNSAFE\"\n logger.info(\n f\"Security scan completed for '{path}': {safety_status} \"\n f\"(Critical: {result.critical_issues}, High: {result.high_severity}, \"\n f\"Medium: {result.medium_severity}, Low: {result.low_severity})\"\n )\n return result\n\n # Anthropic Registry API Methods (v0.1)\n\n def anthropic_list_servers(\n self, cursor: str | None = None, limit: int | None = None\n ) -> AnthropicServerList:\n \"\"\"\n List all MCP servers using the Anthropic Registry API format (v0.1).\n\n This endpoint provides pagination support and returns servers in the\n Anthropic Registry API standard format with reverse-DNS naming.\n\n Args:\n cursor: Pagination cursor (opaque string from previous response)\n limit: Maximum number of results per page (default: 100, max: 1000)\n\n Returns:\n Anthropic ServerList with servers and pagination metadata\n\n Raises:\n requests.HTTPError: If list operation fails\n \"\"\"\n logger.info(\"Listing servers via Anthropic Registry API (v0.1)\")\n\n params = {}\n if cursor:\n params[\"cursor\"] = cursor\n if limit:\n params[\"limit\"] = limit\n\n response = self._make_request(method=\"GET\", endpoint=\"/v0.1/servers\", params=params)\n\n result = AnthropicServerList(**response.json())\n logger.info(f\"Retrieved {len(result.servers)} servers via Anthropic API\")\n return result\n\n def anthropic_list_server_versions(self, server_name: str) -> AnthropicServerList:\n \"\"\"\n List all versions of a specific server using Anthropic Registry API (v0.1).\n\n Currently, the registry maintains only one version per server, so this\n returns a single-item list.\n\n Args:\n server_name: Server name in reverse-DNS format (e.g., \"io.mcpgateway/example-server\")\n Will be URL-encoded automatically.\n\n Returns:\n Anthropic ServerList with single server version\n\n Raises:\n requests.HTTPError: If server not found (404) or user lacks access (403/404)\n \"\"\"\n logger.info(f\"Listing versions for server: {server_name}\")\n\n # URL-encode the server name\n encoded_name = quote(server_name, safe=\"\")\n\n response = self._make_request(\n method=\"GET\", endpoint=f\"/v0.1/servers/{encoded_name}/versions\"\n )\n\n result = AnthropicServerList(**response.json())\n logger.info(f\"Retrieved {len(result.servers)} version(s) for {server_name}\")\n return result\n\n def anthropic_get_server_version(\n self, server_name: str, version: str = \"latest\"\n ) -> AnthropicServerResponse:\n \"\"\"\n Get detailed information about a specific server version using Anthropic Registry API (v0.1).\n\n Args:\n server_name: Server name in reverse-DNS format (e.g., \"io.mcpgateway/example-server\")\n Will be URL-encoded automatically.\n version: Version string (e.g., \"1.0.0\" or \"latest\"). Default: \"latest\"\n Currently only \"latest\" and \"1.0.0\" are supported.\n\n Returns:\n Anthropic ServerResponse with full server details\n\n Raises:\n requests.HTTPError: If server not found (404), version not found (404),\n or user lacks access (403/404)\n \"\"\"\n logger.info(f\"Getting server {server_name} version {version}\")\n\n # URL-encode both server name and version\n encoded_name = quote(server_name, safe=\"\")\n encoded_version = quote(version, safe=\"\")\n\n response = self._make_request(\n method=\"GET\", endpoint=f\"/v0.1/servers/{encoded_name}/versions/{encoded_version}\"\n )\n\n result = AnthropicServerResponse(**response.json())\n logger.info(f\"Retrieved server details for {server_name} v{version}\")\n return result\n\n # Local Server Version Management Methods\n\n def remove_server_version(self, path: str, version: str) -> dict:\n \"\"\"\n Remove a version from a server.\n\n Args:\n path: Server path (e.g., \"/context7\")\n version: Version to remove\n\n Returns:\n Response dict with status and message\n\n Raises:\n requests.HTTPError: If server not found or cannot remove default\n \"\"\"\n logger.info(f\"Removing version {version} from server {path}\")\n\n encoded_path = quote(path.lstrip(\"/\"), safe=\"\")\n encoded_version = quote(version, safe=\"\")\n\n response = self._make_request(\n method=\"DELETE\", endpoint=f\"/api/servers/{encoded_path}/versions/{encoded_version}\"\n )\n\n return response.json()\n\n def set_default_version(self, path: str, version: str) -> dict:\n \"\"\"\n Set the default (latest) version for a server.\n\n Args:\n path: Server path (e.g., \"/context7\")\n version: Version to set as default\n\n Returns:\n Response dict with status and message\n\n Raises:\n requests.HTTPError: If server or version not found\n \"\"\"\n logger.info(f\"Setting default version to {version} for server {path}\")\n\n encoded_path = quote(path.lstrip(\"/\"), safe=\"\")\n\n response = self._make_request(\n method=\"PUT\",\n endpoint=f\"/api/servers/{encoded_path}/versions/default\",\n data={\"version\": version},\n )\n\n return response.json()\n\n def get_server_versions(self, path: str) -> dict:\n \"\"\"\n Get all versions for a server.\n\n Args:\n path: Server path (e.g., \"/context7\")\n\n Returns:\n Dict with path, default_version, and versions list\n\n Raises:\n requests.HTTPError: If server not found\n \"\"\"\n logger.info(f\"Getting versions for server {path}\")\n\n encoded_path = quote(path.lstrip(\"/\"), safe=\"\")\n\n response = self._make_request(\n method=\"GET\", endpoint=f\"/api/servers/{encoded_path}/versions\"\n )\n\n return response.json()\n\n # Management API Methods (IAM/User Management)\n\n def list_users(self, search: str | None = None, limit: int = 500) -> UserListResponse:\n \"\"\"\n List Keycloak users (admin only).\n\n Args:\n search: Optional search string to filter users\n limit: Maximum number of results (default: 500)\n\n Returns:\n UserListResponse with list of users\n\n Raises:\n requests.HTTPError: If not authorized (403) or request fails\n \"\"\"\n logger.info(\"Listing Keycloak users\")\n\n params = {}\n if search:\n params[\"search\"] = search\n if limit != 500:\n params[\"limit\"] = limit\n\n response = self._make_request(\n method=\"GET\", endpoint=\"/api/management/iam/users\", params=params\n )\n\n try:\n response_data = response.json()\n logger.debug(f\"Raw API response: {json.dumps(response_data, indent=2, default=str)}\")\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to decode JSON response: {e}\")\n logger.error(f\"Raw response text: {response.text}\")\n logger.error(f\"Response status code: {response.status_code}\")\n logger.error(f\"Response headers: {dict(response.headers)}\")\n raise\n\n try:\n result = UserListResponse(**response_data)\n logger.info(f\"Retrieved {result.total} users\")\n return result\n except Exception as e:\n logger.error(f\"Failed to parse user list response: {e}\")\n logger.error(f\"Raw response data: {json.dumps(response_data, indent=2, default=str)}\")\n raise\n\n def create_m2m_account(\n self, name: str, groups: list[str], description: str | None = None\n ) -> M2MAccountResponse:\n \"\"\"\n Create a machine-to-machine service account.\n\n Args:\n name: Service account name/client ID\n groups: List of group names for access control\n description: Optional account description\n\n Returns:\n M2MAccountResponse with client credentials\n\n Raises:\n requests.HTTPError: If not authorized (403), already exists (400), or request fails\n \"\"\"\n logger.info(f\"Creating M2M service account: {name}\")\n\n data = {\"name\": name, \"groups\": groups}\n if description:\n data[\"description\"] = description\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/management/iam/users/m2m\", data=data\n )\n\n result = M2MAccountResponse(**response.json())\n logger.info(f\"M2M account created successfully: {name}\")\n return result\n\n def create_human_user(\n self,\n username: str,\n email: str,\n first_name: str,\n last_name: str,\n groups: list[str],\n password: str | None = None,\n ) -> UserSummary:\n \"\"\"\n Create a human user account in Keycloak.\n\n Args:\n username: Username\n email: Email address\n first_name: First name\n last_name: Last name\n groups: List of group names\n password: Optional initial password\n\n Returns:\n UserSummary with created user details\n\n Raises:\n requests.HTTPError: If not authorized (403), already exists (400), or request fails\n \"\"\"\n logger.info(f\"Creating human user: {username}\")\n\n data = {\n \"username\": username,\n \"email\": email,\n \"firstname\": first_name,\n \"lastname\": last_name,\n \"groups\": groups,\n }\n if password:\n data[\"password\"] = password\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/management/iam/users/human\", data=data\n )\n\n result = UserSummary(**response.json())\n logger.info(f\"User created successfully: {username}\")\n return result\n\n def delete_user(self, username: str) -> UserDeleteResponse:\n \"\"\"\n Delete a user by username.\n\n Args:\n username: Username to delete\n\n Returns:\n UserDeleteResponse confirming deletion\n\n Raises:\n requests.HTTPError: If not authorized (403), not found (400/404), or request fails\n \"\"\"\n logger.info(f\"Deleting user: {username}\")\n\n response = self._make_request(\n method=\"DELETE\", endpoint=f\"/api/management/iam/users/{username}\"\n )\n\n result = UserDeleteResponse(**response.json())\n logger.info(f\"User deleted successfully: {username}\")\n return result\n\n def list_keycloak_iam_groups(self) -> GroupListResponse:\n \"\"\"\n List Keycloak IAM groups (admin only).\n\n This is different from list_groups() which returns groups with server associations.\n This method returns raw Keycloak group data without scopes.\n\n Returns:\n GroupListResponse with list of groups\n\n Raises:\n requests.HTTPError: If not authorized (403) or request fails\n \"\"\"\n logger.info(\"Listing Keycloak IAM groups\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/management/iam/groups\")\n\n result = GroupListResponse(**response.json())\n logger.info(f\"Retrieved {result.total} Keycloak groups\")\n return result\n\n def create_keycloak_group(self, name: str, description: str | None = None) -> GroupSummary:\n \"\"\"\n Create a new Keycloak group (admin only).\n\n Args:\n name: Group name\n description: Optional group description\n\n Returns:\n GroupSummary with created group details\n\n Raises:\n requests.HTTPError: If not authorized (403), already exists (400), or request fails\n \"\"\"\n logger.info(f\"Creating Keycloak group: {name}\")\n\n data = {\"name\": name}\n if description:\n data[\"description\"] = description\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/management/iam/groups\", data=data\n )\n\n result = GroupSummary(**response.json())\n logger.info(f\"Group created successfully: {name}\")\n return result\n\n def delete_keycloak_group(self, name: str) -> GroupDeleteResponse:\n \"\"\"\n Delete a Keycloak group by name (admin only).\n\n Args:\n name: Group name to delete\n\n Returns:\n GroupDeleteResponse confirming deletion\n\n Raises:\n requests.HTTPError: If not authorized (403), not found (404), or request fails\n \"\"\"\n logger.info(f\"Deleting Keycloak group: {name}\")\n\n response = self._make_request(\n method=\"DELETE\", endpoint=f\"/api/management/iam/groups/{name}\"\n )\n\n result = GroupDeleteResponse(**response.json())\n logger.info(f\"Group deleted successfully: {name}\")\n return result\n\n def get_federation_config(self, config_id: str = \"default\") -> dict[str, Any]:\n \"\"\"\n Get federation configuration by ID.\n\n Args:\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n Federation configuration dictionary\n\n Raises:\n requests.HTTPError: If not found (404) or request fails\n \"\"\"\n logger.info(f\"Getting federation config: {config_id}\")\n\n response = self._make_request(\n method=\"GET\", endpoint=\"/api/federation/config\", params={\"config_id\": config_id}\n )\n\n result = response.json()\n logger.info(f\"Retrieved federation config: {config_id}\")\n return result\n\n def save_federation_config(\n self, config: dict[str, Any], config_id: str = \"default\"\n ) -> dict[str, Any]:\n \"\"\"\n Create or update federation configuration.\n\n Args:\n config: Federation configuration dictionary\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n Saved configuration response\n\n Raises:\n requests.HTTPError: If validation fails (422) or request fails\n \"\"\"\n logger.info(f\"Saving federation config: {config_id}\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/federation/config\",\n params={\"config_id\": config_id},\n data=config,\n )\n\n result = response.json()\n logger.info(f\"Federation config saved successfully: {config_id}\")\n return result\n\n def delete_federation_config(self, config_id: str = \"default\") -> dict[str, str]:\n \"\"\"\n Delete federation configuration.\n\n Args:\n config_id: Configuration ID to delete\n\n Returns:\n Deletion confirmation message\n\n Raises:\n requests.HTTPError: If not found (404) or request fails\n \"\"\"\n logger.info(f\"Deleting federation config: {config_id}\")\n\n response = self._make_request(\n method=\"DELETE\", endpoint=f\"/api/federation/config/{config_id}\"\n )\n\n result = response.json()\n logger.info(f\"Federation config deleted successfully: {config_id}\")\n return result\n\n def list_federation_configs(self) -> dict[str, Any]:\n \"\"\"\n List all federation configurations.\n\n Returns:\n Dictionary with configs list and total count\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Listing federation configs\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/federation/configs\")\n\n result = response.json()\n logger.info(f\"Retrieved {result.get('total', 0)} federation configs\")\n return result\n\n def add_anthropic_server(self, server_name: str, config_id: str = \"default\") -> dict[str, Any]:\n \"\"\"\n Add Anthropic server to federation configuration.\n\n Args:\n server_name: Server name (e.g., \"io.github.jgador/websharp\")\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n Updated configuration\n\n Raises:\n requests.HTTPError: If config not found (404), already exists (400), or request fails\n \"\"\"\n logger.info(f\"Adding Anthropic server '{server_name}' to config: {config_id}\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=f\"/api/federation/config/{config_id}/anthropic/servers\",\n params={\"server_name\": server_name},\n )\n\n result = response.json()\n logger.info(f\"Anthropic server added successfully: {server_name}\")\n return result\n\n def remove_anthropic_server(\n self, server_name: str, config_id: str = \"default\"\n ) -> dict[str, Any]:\n \"\"\"\n Remove Anthropic server from federation configuration.\n\n Args:\n server_name: Server name to remove\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n Updated configuration\n\n Raises:\n requests.HTTPError: If config or server not found (404) or request fails\n \"\"\"\n logger.info(f\"Removing Anthropic server '{server_name}' from config: {config_id}\")\n\n response = self._make_request(\n method=\"DELETE\",\n endpoint=f\"/api/federation/config/{config_id}/anthropic/servers/{server_name}\",\n )\n\n result = response.json()\n logger.info(f\"Anthropic server removed successfully: {server_name}\")\n return result\n\n def add_asor_agent(self, agent_id: str, config_id: str = \"default\") -> dict[str, Any]:\n \"\"\"\n Add ASOR agent to federation configuration.\n\n Args:\n agent_id: Agent ID (e.g., \"aws_assistant\")\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n Updated configuration\n\n Raises:\n requests.HTTPError: If config not found (404), already exists (400), or request fails\n \"\"\"\n logger.info(f\"Adding ASOR agent '{agent_id}' to config: {config_id}\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=f\"/api/federation/config/{config_id}/asor/agents\",\n params={\"agent_id\": agent_id},\n )\n\n result = response.json()\n logger.info(f\"ASOR agent added successfully: {agent_id}\")\n return result\n\n def remove_asor_agent(self, agent_id: str, config_id: str = \"default\") -> dict[str, Any]:\n \"\"\"\n Remove ASOR agent from federation configuration.\n\n Args:\n agent_id: Agent ID to remove\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n Updated configuration\n\n Raises:\n requests.HTTPError: If config or agent not found (404) or request fails\n \"\"\"\n logger.info(f\"Removing ASOR agent '{agent_id}' from config: {config_id}\")\n\n response = self._make_request(\n method=\"DELETE\", endpoint=f\"/api/federation/config/{config_id}/asor/agents/{agent_id}\"\n )\n\n result = response.json()\n logger.info(f\"ASOR agent removed successfully: {agent_id}\")\n return result\n\n def sync_federation(\n self, config_id: str = \"default\", source: str | None = None\n ) -> dict[str, Any]:\n \"\"\"\n Trigger manual federation sync to import servers/agents.\n\n Args:\n config_id: Configuration ID (default: \"default\")\n source: Optional source filter (\"anthropic\" or \"asor\"). None syncs all enabled sources.\n\n Returns:\n Sync results with counts of synced items\n\n Raises:\n requests.HTTPError: If config not found (404) or request fails\n \"\"\"\n logger.info(f\"Triggering federation sync for config: {config_id}\")\n\n params = {}\n if source:\n params[\"source\"] = source\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/federation/sync\",\n params={\"config_id\": config_id, **params},\n )\n\n result = response.json()\n logger.info(f\"Federation sync completed: {result.get('total_synced', 0)} items synced\")\n return result\n\n # ==========================================\n # Peer Federation Management Methods\n # ==========================================\n\n def list_peers(self, enabled: bool | None = None) -> dict[str, Any]:\n \"\"\"\n List all configured peer registries.\n\n Args:\n enabled: Optional filter by enabled status\n\n Returns:\n Dictionary with peers list\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Listing peer registries\")\n\n params = {}\n if enabled is not None:\n params[\"enabled\"] = str(enabled).lower()\n\n response = self._make_request(\n method=\"GET\", endpoint=\"/api/peers\", params=params if params else None\n )\n\n result = response.json()\n logger.info(f\"Retrieved {len(result) if isinstance(result, list) else 0} peers\")\n return result\n\n def add_peer(self, config: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Add a new peer registry.\n\n Args:\n config: Peer configuration dictionary with peer_id, name, endpoint, etc.\n\n Returns:\n Created peer configuration\n\n Raises:\n requests.HTTPError: If peer already exists (409) or request fails\n \"\"\"\n peer_id = config.get(\"peer_id\", \"unknown\")\n logger.info(f\"Adding peer registry: {peer_id}\")\n\n response = self._make_request(method=\"POST\", endpoint=\"/api/peers\", data=config)\n\n result = response.json()\n logger.info(f\"Peer registry added successfully: {peer_id}\")\n return result\n\n def get_peer(self, peer_id: str) -> dict[str, Any]:\n \"\"\"\n Get details of a specific peer registry.\n\n Args:\n peer_id: Peer registry identifier\n\n Returns:\n Peer configuration details\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Getting peer registry: {peer_id}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/peers/{peer_id}\")\n\n result = response.json()\n logger.info(f\"Retrieved peer registry: {peer_id}\")\n return result\n\n def update_peer(self, peer_id: str, config: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Update an existing peer registry configuration.\n\n Args:\n peer_id: Peer registry identifier\n config: Updated peer configuration\n\n Returns:\n Updated peer configuration\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Updating peer registry: {peer_id}\")\n\n response = self._make_request(method=\"PUT\", endpoint=f\"/api/peers/{peer_id}\", data=config)\n\n result = response.json()\n logger.info(f\"Peer registry updated successfully: {peer_id}\")\n return result\n\n def update_peer_token(self, peer_id: str, federation_token: str) -> dict[str, Any]:\n \"\"\"\n Update only the federation token for a peer registry.\n\n This is useful for recovering from token loss (issue #561) or\n rotating tokens without triggering a full peer update.\n\n Args:\n peer_id: Peer registry identifier\n federation_token: New federation token value\n\n Returns:\n Success message with peer ID\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Updating federation token for peer: {peer_id}\")\n\n response = self._make_request(\n method=\"PATCH\",\n endpoint=f\"/api/peers/{peer_id}/token\",\n data={\"federation_token\": federation_token},\n )\n\n result = response.json()\n logger.info(f\"Federation token updated successfully for peer: {peer_id}\")\n return result\n\n def remove_peer(self, peer_id: str) -> dict[str, Any]:\n \"\"\"\n Remove a peer registry.\n\n Args:\n peer_id: Peer registry identifier\n\n Returns:\n Deletion confirmation\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Removing peer registry: {peer_id}\")\n\n response = self._make_request(method=\"DELETE\", endpoint=f\"/api/peers/{peer_id}\")\n\n # Handle 204 No Content response\n if response.status_code == 204:\n logger.info(f\"Peer registry removed successfully: {peer_id}\")\n return {\"status\": \"deleted\", \"peer_id\": peer_id}\n\n result = response.json()\n logger.info(f\"Peer registry removed successfully: {peer_id}\")\n return result\n\n def sync_peer(self, peer_id: str) -> dict[str, Any]:\n \"\"\"\n Trigger sync from a specific peer registry.\n\n Args:\n peer_id: Peer registry identifier\n\n Returns:\n Sync result with statistics\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Syncing from peer registry: {peer_id}\")\n\n response = self._make_request(method=\"POST\", endpoint=f\"/api/peers/{peer_id}/sync\")\n\n result = response.json()\n logger.info(f\"Peer sync completed: {peer_id}\")\n return result\n\n def sync_all_peers(self) -> dict[str, Any]:\n \"\"\"\n Trigger sync from all enabled peer registries.\n\n Returns:\n Sync results for all peers\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Syncing from all peer registries\")\n\n response = self._make_request(method=\"POST\", endpoint=\"/api/peers/sync\")\n\n result = response.json()\n logger.info(\"All peer sync completed\")\n return result\n\n def get_peer_status(self, peer_id: str) -> dict[str, Any]:\n \"\"\"\n Get sync status for a specific peer registry.\n\n Args:\n peer_id: Peer registry identifier\n\n Returns:\n Sync status with history\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Getting sync status for peer: {peer_id}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/peers/{peer_id}/status\")\n\n result = response.json()\n logger.info(f\"Retrieved sync status for peer: {peer_id}\")\n return result\n\n def enable_peer(self, peer_id: str) -> dict[str, Any]:\n \"\"\"\n Enable a peer registry.\n\n Args:\n peer_id: Peer registry identifier\n\n Returns:\n Updated peer configuration\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Enabling peer registry: {peer_id}\")\n\n response = self._make_request(method=\"POST\", endpoint=f\"/api/peers/{peer_id}/enable\")\n\n result = response.json()\n logger.info(f\"Peer registry enabled: {peer_id}\")\n return result\n\n def disable_peer(self, peer_id: str) -> dict[str, Any]:\n \"\"\"\n Disable a peer registry.\n\n Args:\n peer_id: Peer registry identifier\n\n Returns:\n Updated peer configuration\n\n Raises:\n requests.HTTPError: If peer not found (404) or request fails\n \"\"\"\n logger.info(f\"Disabling peer registry: {peer_id}\")\n\n response = self._make_request(method=\"POST\", endpoint=f\"/api/peers/{peer_id}/disable\")\n\n result = response.json()\n logger.info(f\"Peer registry disabled: {peer_id}\")\n return result\n\n def get_peer_connections(self) -> dict[str, Any]:\n \"\"\"\n Get all federation connections across all peers.\n\n Returns:\n Dictionary with connection details\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Getting all peer connections\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/peers/connections/all\")\n\n result = response.json()\n logger.info(\"Retrieved peer connections\")\n return result\n\n def get_shared_resources(self) -> dict[str, Any]:\n \"\"\"\n Get resource sharing summary across all peers.\n\n Returns:\n Dictionary with shared resource details\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Getting shared resources summary\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/peers/shared-resources\")\n\n result = response.json()\n logger.info(\"Retrieved shared resources summary\")\n return result\n\n # ==========================================\n # Agent Skills Management Methods\n # ==========================================\n\n def register_skill(self, request: SkillRegistrationRequest) -> SkillCard:\n \"\"\"\n Register a new Agent Skill.\n\n Args:\n request: Skill registration request\n\n Returns:\n SkillCard with registered skill details\n\n Raises:\n requests.HTTPError: If skill already exists (409) or validation fails (400/422)\n \"\"\"\n logger.info(f\"Registering skill: {request.name}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/skills\", data=request.model_dump(exclude_none=True)\n )\n\n result = response.json()\n logger.info(f\"Skill registered successfully: {result.get('name')} at {result.get('path')}\")\n return SkillCard(**result)\n\n def list_skills(\n self,\n include_disabled: bool = False,\n tag: str | None = None,\n limit: int = 20,\n offset: int = 0,\n ) -> SkillListResponse:\n \"\"\"\n List all Agent Skills.\n\n Args:\n include_disabled: Include disabled skills\n tag: Filter by tag\n limit: Maximum number of skills to return per page\n offset: Number of skills to skip for pagination\n\n Returns:\n SkillListResponse with list of skills\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(\"Listing skills\")\n\n params: dict[str, str | int] = {\n \"limit\": limit,\n \"offset\": offset,\n }\n if include_disabled:\n params[\"include_disabled\"] = \"true\"\n if tag:\n params[\"tag\"] = tag\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/skills\", params=params)\n\n result = response.json()\n skills = [SkillCard(**s) for s in result.get(\"skills\", [])]\n total_count = result.get(\"total_count\", len(skills))\n resp_limit = result.get(\"limit\", limit)\n resp_offset = result.get(\"offset\", offset)\n has_next = result.get(\"has_next\", False)\n logger.info(\n f\"Retrieved {len(skills)} skills\"\n f\" (total={total_count}, offset={resp_offset},\"\n f\" limit={resp_limit}, has_next={has_next})\"\n )\n return SkillListResponse(\n skills=skills,\n total_count=total_count,\n limit=resp_limit,\n offset=resp_offset,\n has_next=has_next,\n )\n\n def get_skill(self, path: str) -> SkillCard:\n \"\"\"\n Get details for a specific skill.\n\n Args:\n path: Skill path or name\n\n Returns:\n SkillCard with skill details\n\n Raises:\n requests.HTTPError: If skill not found (404)\n \"\"\"\n # Normalize path - remove /skills/ prefix if present\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Getting skill: {api_path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/skills{api_path}\")\n\n result = response.json()\n logger.info(f\"Retrieved skill: {result.get('name')}\")\n return SkillCard(**result)\n\n def update_skill(self, path: str, request: SkillRegistrationRequest) -> SkillCard:\n \"\"\"\n Update an existing skill.\n\n Args:\n path: Skill path or name\n request: Updated skill data\n\n Returns:\n Updated SkillCard\n\n Raises:\n requests.HTTPError: If skill not found (404) or validation fails\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Updating skill: {api_path}\")\n\n response = self._make_request(\n method=\"PUT\",\n endpoint=f\"/api/skills{api_path}\",\n data=request.model_dump(exclude_none=True),\n )\n\n result = response.json()\n logger.info(f\"Skill updated: {result.get('name')}\")\n return SkillCard(**result)\n\n def delete_skill(self, path: str) -> bool:\n \"\"\"\n Delete a skill.\n\n Args:\n path: Skill path or name\n\n Returns:\n True if deleted successfully\n\n Raises:\n requests.HTTPError: If skill not found (404) or permission denied (403)\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Deleting skill: {api_path}\")\n\n self._make_request(method=\"DELETE\", endpoint=f\"/api/skills{api_path}\")\n\n logger.info(f\"Skill deleted: {api_path}\")\n return True\n\n def toggle_skill(self, path: str, enabled: bool) -> SkillToggleResponse:\n \"\"\"\n Toggle skill enabled/disabled state.\n\n Args:\n path: Skill path or name\n enabled: New enabled state\n\n Returns:\n SkillToggleResponse with new state\n\n Raises:\n requests.HTTPError: If skill not found (404)\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Toggling skill {api_path} to enabled={enabled}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=f\"/api/skills{api_path}/toggle\", data={\"enabled\": enabled}\n )\n\n result = response.json()\n logger.info(f\"Skill toggled: {result.get('path')} -> enabled={result.get('is_enabled')}\")\n return SkillToggleResponse(**result)\n\n def check_skill_health(self, path: str) -> SkillHealthResponse:\n \"\"\"\n Check skill health (SKILL.md accessibility).\n\n Args:\n path: Skill path or name\n\n Returns:\n SkillHealthResponse with health status\n\n Raises:\n requests.HTTPError: If skill not found (404)\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Checking health for skill: {api_path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/skills{api_path}/health\")\n\n result = response.json()\n logger.info(f\"Skill health: {result.get('path')} -> healthy={result.get('healthy')}\")\n return SkillHealthResponse(**result)\n\n def get_skill_content(self, path: str) -> SkillContentResponse:\n \"\"\"\n Get SKILL.md content for a skill.\n\n Args:\n path: Skill path or name\n\n Returns:\n SkillContentResponse with content\n\n Raises:\n requests.HTTPError: If skill not found (404) or content unavailable\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Getting content for skill: {api_path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/skills{api_path}/content\")\n\n result = response.json()\n content_len = len(result.get(\"content\", \"\"))\n logger.info(f\"Retrieved skill content: {content_len} characters\")\n return SkillContentResponse(**result)\n\n def search_skills(self, query: str, tags: str | None = None) -> SkillSearchResponse:\n \"\"\"\n Search for skills by query.\n\n Args:\n query: Search query\n tags: Optional comma-separated tags filter\n\n Returns:\n SkillSearchResponse with matching skills\n\n Raises:\n requests.HTTPError: If request fails\n \"\"\"\n logger.info(f\"Searching skills: query='{query}', tags={tags}\")\n\n params = {\"q\": query}\n if tags:\n params[\"tags\"] = tags\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/skills/search\", params=params)\n\n result = response.json()\n logger.info(f\"Found {result.get('total_count', 0)} skills matching '{query}'\")\n return SkillSearchResponse(**result)\n\n def rate_skill(self, path: str, rating: int) -> dict[str, Any]:\n \"\"\"\n Rate a skill (1-5 stars).\n\n Args:\n path: Skill path or name\n rating: Rating value (1-5)\n\n Returns:\n Rating response with average rating\n\n Raises:\n requests.HTTPError: If skill not found (404) or invalid rating (400)\n \"\"\"\n if not 1 <= rating <= 5:\n raise ValueError(\"Rating must be between 1 and 5\")\n\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Rating skill {api_path}: {rating} stars\")\n\n response = self._make_request(\n method=\"POST\", endpoint=f\"/api/skills{api_path}/rate\", data={\"rating\": rating}\n )\n\n result = response.json()\n logger.info(f\"Skill rated: avg={result.get('average_rating')}\")\n return result\n\n def get_skill_rating(self, path: str) -> SkillRatingResponse:\n \"\"\"\n Get rating information for a skill.\n\n Args:\n path: Skill path or name\n\n Returns:\n SkillRatingResponse with rating details\n\n Raises:\n requests.HTTPError: If skill not found (404)\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Getting rating for skill: {api_path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/skills{api_path}/rating\")\n\n result = response.json()\n logger.info(f\"Skill rating: {result.get('num_stars')} stars\")\n return SkillRatingResponse(**result)\n\n def get_skill_security_scan(self, path: str) -> SkillSecurityScanResponse:\n \"\"\"\n Get security scan results for a skill.\n\n Returns the latest security scan results including threat analysis,\n findings by analyzer, and overall safety status.\n\n Args:\n path: Skill path or name\n\n Returns:\n Security scan results with analysis_results and scan_results\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Getting security scan results for skill: {api_path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/skills{api_path}/security-scan\")\n\n result = SkillSecurityScanResponse(**response.json())\n logger.info(f\"Retrieved security scan results for skill '{api_path}'\")\n return result\n\n def rescan_skill(self, path: str) -> SkillRescanResponse:\n \"\"\"\n Trigger a manual security scan for a skill.\n\n Initiates a new security scan for the specified skill and returns\n the scan results. Requires admin privileges.\n\n Args:\n path: Skill path or name\n\n Returns:\n Newly generated security scan results\n \"\"\"\n api_path = path.replace(\"/skills/\", \"/\") if path.startswith(\"/skills/\") else f\"/{path}\"\n logger.info(f\"Triggering security scan for skill: {api_path}\")\n\n response = self._make_request(method=\"POST\", endpoint=f\"/api/skills{api_path}/rescan\")\n\n result = SkillRescanResponse(**response.json())\n safety_status = \"SAFE\" if result.is_safe else \"UNSAFE\"\n logger.info(\n f\"Security scan completed for skill '{api_path}': {safety_status} \"\n f\"(C:{result.critical_issues} H:{result.high_severity} \"\n f\"M:{result.medium_severity} L:{result.low_severity})\"\n )\n return result\n\n # =========================================================================\n # Virtual MCP Server Operations\n # =========================================================================\n\n def create_virtual_server(self, request: VirtualServerCreateRequest) -> VirtualServerConfig:\n \"\"\"\n Create a new virtual MCP server.\n\n Args:\n request: Virtual server creation request with tool mappings\n\n Returns:\n VirtualServerConfig with created server details\n\n Raises:\n requests.HTTPError: If creation fails (400 invalid, 409 conflict)\n \"\"\"\n logger.info(f\"Creating virtual server: {request.path}\")\n logger.debug(f\"Virtual server config:\\n{json.dumps(request.model_dump(), indent=2)}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=\"/api/virtual-servers\", data=request.model_dump()\n )\n\n result = response.json()\n logger.info(f\"Virtual server created: {result.get('path')}\")\n return VirtualServerConfig(**result)\n\n def list_virtual_servers(\n self,\n enabled_only: bool = False,\n tag: str | None = None,\n limit: int = 100,\n offset: int = 0,\n ) -> VirtualServerListResponse:\n \"\"\"\n List virtual MCP servers.\n\n Args:\n enabled_only: If True, only return enabled servers\n tag: Filter by tag\n limit: Maximum number of results\n offset: Pagination offset\n\n Returns:\n VirtualServerListResponse with list of servers\n \"\"\"\n params = {\"limit\": limit, \"offset\": offset}\n if enabled_only:\n params[\"enabled_only\"] = \"true\"\n if tag:\n params[\"tag\"] = tag\n\n logger.info(f\"Listing virtual servers (enabled_only={enabled_only}, tag={tag})\")\n\n response = self._make_request(method=\"GET\", endpoint=\"/api/virtual-servers\", params=params)\n\n result = response.json()\n logger.info(f\"Found {result.get('total', 0)} virtual servers\")\n return VirtualServerListResponse(**result)\n\n def get_virtual_server(self, path: str) -> VirtualServerConfig:\n \"\"\"\n Get details of a virtual MCP server.\n\n Args:\n path: Virtual server path (e.g., /virtual/dev-tools)\n\n Returns:\n VirtualServerConfig with server details\n\n Raises:\n requests.HTTPError: If server not found (404)\n \"\"\"\n api_path = path if path.startswith(\"/\") else f\"/{path}\"\n logger.info(f\"Getting virtual server: {api_path}\")\n\n response = self._make_request(method=\"GET\", endpoint=f\"/api/virtual-servers{api_path}\")\n\n result = response.json()\n logger.info(f\"Virtual server: {result.get('server_name')}\")\n return VirtualServerConfig(**result)\n\n def update_virtual_server(\n self, path: str, request: VirtualServerCreateRequest\n ) -> VirtualServerConfig:\n \"\"\"\n Update an existing virtual MCP server.\n\n Args:\n path: Virtual server path\n request: Updated configuration\n\n Returns:\n VirtualServerConfig with updated server details\n\n Raises:\n requests.HTTPError: If server not found (404) or invalid (400)\n \"\"\"\n api_path = path if path.startswith(\"/\") else f\"/{path}\"\n logger.info(f\"Updating virtual server: {api_path}\")\n logger.debug(f\"Updated config:\\n{json.dumps(request.model_dump(), indent=2)}\")\n\n response = self._make_request(\n method=\"PUT\", endpoint=f\"/api/virtual-servers{api_path}\", data=request.model_dump()\n )\n\n result = response.json()\n logger.info(f\"Virtual server updated: {result.get('path')}\")\n return VirtualServerConfig(**result)\n\n def delete_virtual_server(self, path: str) -> VirtualServerDeleteResponse:\n \"\"\"\n Delete a virtual MCP server.\n\n Args:\n path: Virtual server path\n\n Returns:\n VirtualServerDeleteResponse with confirmation\n\n Raises:\n requests.HTTPError: If server not found (404)\n \"\"\"\n api_path = path if path.startswith(\"/\") else f\"/{path}\"\n logger.info(f\"Deleting virtual server: {api_path}\")\n\n response = self._make_request(method=\"DELETE\", endpoint=f\"/api/virtual-servers{api_path}\")\n\n result = response.json()\n logger.info(f\"Virtual server deleted: {api_path}\")\n return VirtualServerDeleteResponse(**result)\n\n def toggle_virtual_server(self, path: str, enable: bool) -> VirtualServerToggleResponse:\n \"\"\"\n Enable or disable a virtual MCP server.\n\n Args:\n path: Virtual server path\n enable: True to enable, False to disable\n\n Returns:\n VirtualServerToggleResponse with new state\n\n Raises:\n requests.HTTPError: If server not found (404)\n \"\"\"\n api_path = path if path.startswith(\"/\") else f\"/{path}\"\n action = \"enable\" if enable else \"disable\"\n logger.info(f\"Toggling virtual server {api_path}: {action}\")\n\n response = self._make_request(\n method=\"POST\", endpoint=f\"/api/virtual-servers{api_path}/{action}\"\n )\n\n result = response.json()\n logger.info(f\"Virtual server {action}d: {result.get('is_enabled')}\")\n return VirtualServerToggleResponse(**result)\n\n def rate_virtual_server(self, path: str, rating: int) -> dict[str, Any]:\n \"\"\"\n Rate a virtual MCP server (1-5 stars).\n\n Args:\n path: Virtual server path\n rating: Rating value (1-5)\n\n Returns:\n Rating response with average rating\n\n Raises:\n requests.HTTPError: If server not found (404) or invalid rating (400)\n \"\"\"\n if not 1 <= rating <= 5:\n raise ValueError(\"Rating must be between 1 and 5\")\n\n api_path = path if path.startswith(\"/\") else f\"/{path}\"\n logger.info(f\"Rating virtual server {api_path}: {rating} stars\")\n\n response = self._make_request(\n method=\"POST\", endpoint=f\"/api/virtual-servers{api_path}/rate\", data={\"rating\": rating}\n )\n\n result = response.json()\n logger.info(f\"Virtual server rated: avg={result.get('average_rating')}\")\n return result\n\n def get_virtual_server_rating(self, path: str) -> dict[str, Any]:\n \"\"\"\n Get rating information for a virtual MCP server.\n\n Args:\n path: Virtual server path\n\n Returns:\n Dict with rating details (num_stars, rating_count, etc.)\n\n Raises:\n requests.HTTPError: If server not found (404)\n \"\"\"\n api_path = path if path.startswith(\"/\") else f\"/{path}\"\n logger.info(f\"Getting rating for virtual server: {api_path}\")\n\n response = self._make_request(\n method=\"GET\", endpoint=f\"/api/virtual-servers{api_path}/rating\"\n )\n\n result = response.json()\n logger.info(f\"Virtual server rating: {result.get('num_stars')} stars\")\n return result\n\n def force_heartbeat(self) -> dict[str, Any]:\n \"\"\"Force an immediate heartbeat telemetry event (admin only).\n\n Bypasses the 24-hour lock and sends a heartbeat event immediately.\n\n Returns:\n Dict with status and payload summary.\n\n Raises:\n requests.HTTPError: If not authorized (403) or telemetry disabled (409)\n \"\"\"\n logger.info(\"Forcing heartbeat telemetry event\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/registry-management/telemetry/heartbeat\",\n )\n\n result = response.json()\n logger.info(f\"Heartbeat result: {result.get('status')}\")\n return result\n\n def force_startup_ping(self) -> dict[str, Any]:\n \"\"\"Force an immediate startup telemetry event (admin only).\n\n Bypasses the 60-second lock and sends a startup ping immediately.\n\n Returns:\n Dict with status and payload summary.\n\n Raises:\n requests.HTTPError: If not authorized (403) or telemetry disabled (409)\n \"\"\"\n logger.info(\"Forcing startup telemetry event\")\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/registry-management/telemetry/startup\",\n )\n\n result = response.json()\n logger.info(f\"Startup ping result: {result.get('status')}\")\n return result\n\n # -------------------------------------------------------------------------\n # Direct M2M client registration (issue #851, /api/iam/m2m-clients)\n #\n # These endpoints write directly to idp_m2m_clients without calling any\n # IdP Admin API. Useful when OKTA_API_TOKEN / equivalent is unavailable.\n # -------------------------------------------------------------------------\n\n def create_m2m_client(\n self,\n client_id: str,\n client_name: str,\n groups: list[str] | None = None,\n description: str | None = None,\n ) -> IdPM2MClient:\n \"\"\"Register an M2M client directly (admin only).\n\n Args:\n client_id: IdP application client ID to register.\n client_name: Human-readable name for the client.\n groups: Group mappings for authorization.\n description: Optional description.\n\n Returns:\n The persisted M2M client record.\n\n Raises:\n requests.HTTPError: 401/403 on auth, 409 if client_id already exists,\n 422 for invalid payload.\n \"\"\"\n logger.info(f\"Registering M2M client: {client_id}\")\n\n payload: dict[str, Any] = {\n \"client_id\": client_id,\n \"client_name\": client_name,\n \"groups\": list(groups) if groups else [],\n }\n if description is not None:\n payload[\"description\"] = description\n\n response = self._make_request(\n method=\"POST\",\n endpoint=\"/api/iam/m2m-clients\",\n data=payload,\n )\n return IdPM2MClient(**response.json())\n\n def list_m2m_clients(\n self,\n provider: str | None = None,\n limit: int = 500,\n skip: int = 0,\n ) -> M2MClientListResponse:\n \"\"\"List M2M clients with pagination.\n\n Args:\n provider: Optional provider filter (e.g. \"manual\", \"okta\").\n limit: Max records to return (1-1000).\n skip: Offset for pagination.\n\n Returns:\n Paginated envelope with total, limit, skip, items.\n\n Raises:\n requests.HTTPError: 401 if unauthenticated.\n \"\"\"\n logger.info(f\"Listing M2M clients (provider={provider}, limit={limit}, skip={skip})\")\n\n params: dict[str, Any] = {\"limit\": limit, \"skip\": skip}\n if provider is not None:\n params[\"provider\"] = provider\n\n response = self._make_request(\n method=\"GET\",\n endpoint=\"/api/iam/m2m-clients\",\n params=params,\n )\n return M2MClientListResponse(**response.json())\n\n def get_m2m_client(self, client_id: str) -> IdPM2MClient:\n \"\"\"Get a single M2M client by client_id.\n\n Args:\n client_id: IdP application client ID.\n\n Returns:\n The M2M client record.\n\n Raises:\n requests.HTTPError: 401 if unauthenticated, 404 if not found.\n \"\"\"\n logger.info(f\"Getting M2M client: {client_id}\")\n\n response = self._make_request(\n method=\"GET\",\n endpoint=f\"/api/iam/m2m-clients/{quote(client_id, safe='')}\",\n )\n return IdPM2MClient(**response.json())\n\n def patch_m2m_client(\n self,\n client_id: str,\n client_name: str | None = None,\n groups: list[str] | None = None,\n description: str | None = None,\n enabled: bool | None = None,\n ) -> IdPM2MClient:\n \"\"\"Partially update an M2M client (admin only).\n\n Only manual records (provider == \"manual\") can be updated. IdP-synced\n records return 403.\n\n Fields left as None are NOT sent to the server (unchanged). To clear\n groups, pass an empty list explicitly.\n\n Args:\n client_id: IdP application client ID to update.\n client_name: New name, or None to leave unchanged.\n groups: New groups list (empty list clears), or None to leave unchanged.\n description: New description, or None to leave unchanged.\n enabled: New enabled flag, or None to leave unchanged.\n\n Returns:\n The updated M2M client record.\n\n Raises:\n requests.HTTPError: 401/403 on auth, 404 if not found, 403 if record\n was IdP-synced.\n \"\"\"\n logger.info(f\"Updating M2M client: {client_id}\")\n\n payload: dict[str, Any] = {}\n if client_name is not None:\n payload[\"client_name\"] = client_name\n if groups is not None:\n payload[\"groups\"] = list(groups)\n if description is not None:\n payload[\"description\"] = description\n if enabled is not None:\n payload[\"enabled\"] = enabled\n\n response = self._make_request(\n method=\"PATCH\",\n endpoint=f\"/api/iam/m2m-clients/{quote(client_id, safe='')}\",\n data=payload,\n )\n return IdPM2MClient(**response.json())\n\n def delete_m2m_client(self, client_id: str) -> None:\n \"\"\"Delete a manual M2M client (admin only).\n\n Only manual records (provider == \"manual\") can be deleted.\n\n Args:\n client_id: IdP application client ID to delete.\n\n Raises:\n requests.HTTPError: 401/403 on auth, 404 if not found, 403 if record\n was IdP-synced.\n \"\"\"\n logger.info(f\"Deleting M2M client: {client_id}\")\n\n self._make_request(\n method=\"DELETE\",\n endpoint=f\"/api/iam/m2m-clients/{quote(client_id, safe='')}\",\n )\n\n\n # -------------------------------------------------------------------------\n # Application Logs (admin-only, issue #886)\n # -------------------------------------------------------------------------\n\n def get_logs(\n self,\n service: str | None = None,\n level: str | None = None,\n hostname: str | None = None,\n search: str | None = None,\n start: str | None = None,\n end: str | None = None,\n limit: int = 100,\n offset: int = 0,\n ) -> AppLogResponse:\n \"\"\"Query application logs (admin only).\n\n Args:\n service: Filter by service name.\n level: Minimum log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).\n hostname: Filter by hostname/pod.\n search: Substring search in log messages.\n start: Start timestamp (ISO-8601).\n end: End timestamp (ISO-8601).\n limit: Page size (1-10000).\n offset: Offset for pagination.\n\n Returns:\n AppLogResponse with matching log entries.\n \"\"\"\n params: dict[str, Any] = {\"limit\": limit, \"offset\": offset}\n if service:\n params[\"service\"] = service\n if level:\n params[\"level\"] = level\n if hostname:\n params[\"hostname\"] = hostname\n if search:\n params[\"search\"] = search\n if start:\n params[\"start\"] = start\n if end:\n params[\"end\"] = end\n\n response = self._make_request(\n method=\"GET\",\n endpoint=\"/api/admin/logs\",\n params=params,\n )\n return AppLogResponse(**response.json())\n\n def get_log_metadata(self) -> AppLogMetadataResponse:\n \"\"\"Get available filter values for application logs (admin only).\n\n Returns:\n AppLogMetadataResponse with services, hostnames, and levels.\n \"\"\"\n response = self._make_request(\n method=\"GET\",\n endpoint=\"/api/admin/logs/metadata\",\n )\n return AppLogMetadataResponse(**response.json())\n\n def get_log_services(self) -> list[str]:\n \"\"\"Get list of distinct service names from application logs (admin only).\n\n Returns:\n List of service name strings.\n \"\"\"\n metadata = self.get_log_metadata()\n return metadata.services\n\n\ndef _format_tool_result(\n tool: ToolSearchResult,\n) -> dict[str, Any]:\n \"\"\"\n Format a tool search result for display to the agent.\n\n The search API returns inputSchema directly, so no additional server lookup is needed.\n\n Args:\n tool: Tool search result\n\n Returns:\n Formatted tool information dict\n \"\"\"\n result = {\n \"tool_name\": tool.tool_name,\n \"server_path\": tool.server_path,\n \"server_name\": tool.server_name,\n \"description\": tool.description or \"No description available\",\n \"relevance_score\": tool.relevance_score,\n \"supported_transports\": [\"streamable_http\"],\n }\n\n # Use inputSchema from search result if available\n if tool.inputSchema:\n result[\"tool_schema\"] = tool.inputSchema\n\n return result\n" }, { "path": "api/registry_management.py", "content": "#!/usr/bin/env python3\n\"\"\"\nMCP Gateway Registry Management CLI.\n\nHigh-level wrapper for the RegistryClient providing command-line interface\nfor server registration, management, group operations, and A2A agent management.\n\nServer Management:\n # Register a server from JSON config\n uv run python registry_management.py register --config /path/to/config.json\n\n # List all servers\n uv run python registry_management.py list\n\n # Toggle server status\n uv run python registry_management.py toggle --path /cloudflare-docs\n\n # Remove server\n uv run python registry_management.py remove --path /cloudflare-docs\n\n # Health check\n uv run python registry_management.py healthcheck\n\n # Get registry configuration (deployment mode, features)\n uv run python registry_management.py config\n\n # Get registry configuration as JSON\n uv run python registry_management.py config --json\n\n # Rate a server (1-5 stars)\n uv run python registry_management.py server-rate --path /cloudflare-docs --rating 5\n\n # Get server rating information\n uv run python registry_management.py server-rating --path /cloudflare-docs\n\n # Get security scan results for a server\n uv run python registry_management.py security-scan --path /cloudflare-docs\n\n # Trigger manual security scan (admin only)\n uv run python registry_management.py rescan --path /cloudflare-docs\n\nGroup Management:\n # Add server to groups\n uv run python registry_management.py add-to-groups --server my-server --groups group1,group2\n\n # List all groups\n uv run python registry_management.py list-groups\n\nAgent Management (A2A):\n # Register an agent\n uv run python registry_management.py agent-register --config /path/to/agent.json\n\n # List all agents\n uv run python registry_management.py agent-list\n\n # Get agent details\n uv run python registry_management.py agent-get --path /code-reviewer\n\n # Toggle agent status\n uv run python registry_management.py agent-toggle --path /code-reviewer --enabled true\n\n # Delete agent\n uv run python registry_management.py agent-delete --path /code-reviewer\n\n # Rate an agent (1-5 stars)\n uv run python registry_management.py agent-rate --path /code-reviewer --rating 5\n\n # Get agent rating information\n uv run python registry_management.py agent-rating --path /code-reviewer\n\n # Discover agents by skills\n uv run python registry_management.py agent-discover --skills code_analysis,bug_detection\n\n # Semantic agent search\n uv run python registry_management.py agent-search --query \"agents that analyze code\"\n\nAnthropic Registry API (v0.1):\n # List all servers\n uv run python registry_management.py anthropic-list\n\n # List all servers with raw JSON output\n uv run python registry_management.py anthropic-list --raw\n\n # List versions for a specific server\n uv run python registry_management.py anthropic-versions --server-name \"io.mcpgateway/example-server\"\n\n # Get server details\n uv run python registry_management.py anthropic-get --server-name \"io.mcpgateway/example-server\" --version latest\n\nUser Management (IAM):\n # List all Keycloak users\n uv run python registry_management.py user-list\n\n # Search for specific users\n uv run python registry_management.py user-list --search admin\n\n # Create M2M service account\n uv run python registry_management.py user-create-m2m --name my-service --groups registry-admins\n\n # Create human user\n uv run python registry_management.py user-create-human --username john.doe --email john@example.com --first-name John --last-name Doe --groups registry-admins\n\n # Delete user\n uv run python registry_management.py user-delete --username john.doe\n\nGroup Management (IAM):\n # List IAM groups\n uv run python registry_management.py group-list\n\n # Create a new IAM group\n uv run python registry_management.py group-create --name developers --description \"Developer team group\"\n\n # Delete an IAM group\n uv run python registry_management.py group-delete --name developers --force\n\nFederation Management:\n # Get federation configuration\n uv run python registry_management.py federation-get\n\n # Save federation configuration from JSON file\n uv run python registry_management.py federation-save --config federation-config.json\n\n # List all federation configurations\n uv run python registry_management.py federation-list\n\n # Add Anthropic server to federation config\n uv run python registry_management.py federation-add-anthropic-server --server-name io.github.jgador/websharp\n\n # Remove Anthropic server from federation config\n uv run python registry_management.py federation-remove-anthropic-server --server-name io.github.jgador/websharp\n\n # Add ASOR agent to federation config\n uv run python registry_management.py federation-add-asor-agent --agent-id aws_assistant\n\n # Remove ASOR agent from federation config\n uv run python registry_management.py federation-remove-asor-agent --agent-id aws_assistant\n\n # Delete federation configuration\n uv run python registry_management.py federation-delete --config-id default --force\n\nVirtual MCP Server Management:\n # Create a virtual server from JSON config\n uv run python registry_management.py vs-create --config /path/to/virtual-server.json\n\n # List all virtual servers\n uv run python registry_management.py vs-list\n\n # List only enabled virtual servers\n uv run python registry_management.py vs-list --enabled-only\n\n # Get virtual server details\n uv run python registry_management.py vs-get --path /virtual/dev-tools\n\n # Update a virtual server from JSON config\n uv run python registry_management.py vs-update --path /virtual/dev-tools --config updated-config.json\n\n # Enable/disable a virtual server\n uv run python registry_management.py vs-toggle --path /virtual/dev-tools --enabled true\n\n # Delete a virtual server\n uv run python registry_management.py vs-delete --path /virtual/dev-tools --force\n\n # Rate a virtual server (1-5 stars)\n uv run python registry_management.py vs-rate --path /virtual/dev-tools --rating 5\n\n # Get virtual server rating\n uv run python registry_management.py vs-rating --path /virtual/dev-tools\n\nRegistry Card Management:\n # Get registry card\n uv run python registry_management.py registry-card-get\n\n # Update registry card\n uv run python registry_management.py registry-card-update --name \"My Registry\" --description \"Production registry\"\n\n # Update contact information\n uv run python registry_management.py registry-card-update --contact-email admin@example.com --contact-url https://example.com\n\n # Get health status\n uv run python registry_management.py health\n\nGlobal Options (can be set via environment variables or command-line arguments):\n --registry-url URL Registry base URL (overrides REGISTRY_URL env var)\n --aws-region REGION AWS region (overrides AWS_REGION env var)\n --keycloak-url URL Keycloak base URL (overrides KEYCLOAK_URL env var)\n --token-file PATH Path to file containing JWT token (bypasses token script)\n\nEnvironment Variables (used if command-line options not provided):\n REGISTRY_URL: Registry base URL (e.g., https://registry.mycorp.click)\n AWS_REGION: AWS region where Keycloak and SSM are deployed (e.g., us-east-1)\n KEYCLOAK_URL: Keycloak base URL (e.g., https://kc.us-east-1.mycorp.click)\n\nEnvironment Variables (Optional):\n CLIENT_NAME: Keycloak client name (default: registry-admin-bot)\n GET_TOKEN_SCRIPT: Path to get-m2m-token.sh script\n\nLocal Development (running against local Docker Compose setup):\n When running the solution locally with Docker Compose, you can use the --token-file\n option to provide a pre-generated JWT token instead of dynamically fetching one.\n\n Step 1: Generate credentials using the credentials provider script:\n cd credentials-provider\n ./generate_creds.sh\n\n Step 2: Use the generated token file with the CLI:\n uv run python api/registry_management.py --debug \\\\\n --registry-url http://localhost \\\\\n --token-file .oauth-tokens/ingress.json \\\\\n list 2>&1 | tee debug.log\n\n The credentials-provider/generate_creds.sh script creates tokens in .oauth-tokens/\n directory. The ingress.json token file contains the admin JWT token that can be\n used with the registry management CLI.\n\n Other examples for local development:\n # List users\n uv run python api/registry_management.py --debug \\\\\n --registry-url http://localhost \\\\\n --token-file .oauth-tokens/ingress.json \\\\\n user-list\n\n # Health check\n uv run python api/registry_management.py --debug \\\\\n --registry-url http://localhost \\\\\n --token-file .oauth-tokens/ingress.json \\\\\n healthcheck\n\n # Create M2M account\n uv run python api/registry_management.py --debug \\\\\n --registry-url http://localhost \\\\\n --token-file .oauth-tokens/ingress.json \\\\\n user-create-m2m --name test-bot --groups developers\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport subprocess # nosec B404\nimport sys\nfrom pathlib import Path\nfrom typing import Any\n\nfrom registry_client import (\n AgentProvider,\n AgentRegistration,\n AgentRescanResponse,\n AgentSecurityScanResponse,\n AgentVisibility,\n AnthropicServerList,\n AnthropicServerResponse,\n InternalServiceRegistration,\n RatingInfoResponse,\n RatingResponse,\n RegistryClient,\n Skill,\n SkillRegistrationRequest,\n ToolMapping,\n ToolScopeOverride,\n VirtualServerCreateRequest,\n)\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _serialize_security_schemes(\n schemes: dict[str, Any],\n) -> dict[str, Any]:\n \"\"\"Serialize security schemes to plain dicts for JSON output.\n\n Handles both SecurityScheme Pydantic objects and raw dicts\n (e.g. Bedrock AgentCore httpAuthSecurityScheme format).\n\n Args:\n schemes: Dictionary of security scheme name to scheme data\n\n Returns:\n Dictionary safe for json.dumps\n \"\"\"\n result: dict[str, Any] = {}\n for name, scheme in schemes.items():\n if isinstance(scheme, dict):\n result[name] = scheme\n elif hasattr(scheme, \"model_dump\"):\n result[name] = scheme.model_dump(exclude_none=True)\n else:\n result[name] = scheme\n return result\n\n\ndef _get_registry_url(cli_value: str | None = None) -> str:\n \"\"\"\n Get registry URL from command-line argument or environment variable.\n\n Args:\n cli_value: Command-line argument value (overrides environment variable)\n\n Returns:\n Registry base URL\n\n Raises:\n ValueError: If REGISTRY_URL is not provided\n \"\"\"\n registry_url = cli_value or os.getenv(\"REGISTRY_URL\")\n if not registry_url:\n raise ValueError(\n \"REGISTRY_URL is required.\\n\"\n \"Set via environment variable or --registry-url option:\\n\"\n \" export REGISTRY_URL=https://registry.mycorp.click\\n\"\n \" OR\\n\"\n \" --registry-url https://registry.mycorp.click\"\n )\n\n logger.debug(f\"Using registry URL: {registry_url}\")\n return registry_url\n\n\ndef _mask_sensitive_fields(\n data: Any,\n fields_to_mask: list[str] | None = None,\n) -> Any:\n \"\"\"\n Mask sensitive fields in response data for safe logging/printing.\n\n Args:\n data: Response data (dict, list, or other)\n fields_to_mask: List of field names to mask (default: federation_token)\n\n Returns:\n Data with sensitive fields masked\n \"\"\"\n if fields_to_mask is None:\n fields_to_mask = [\"federation_token\"]\n\n if isinstance(data, dict):\n masked = {}\n for key, value in data.items():\n if key in fields_to_mask and value:\n # Show first 3 chars followed by ...\n if isinstance(value, str) and len(value) > 3:\n masked[key] = f\"{value[:3]}...\"\n else:\n masked[key] = \"***\"\n else:\n masked[key] = _mask_sensitive_fields(value, fields_to_mask)\n return masked\n elif isinstance(data, list):\n return [_mask_sensitive_fields(item, fields_to_mask) for item in data]\n else:\n return data\n\n\ndef _get_client_name() -> str:\n \"\"\"\n Get Keycloak client name from environment variable or default.\n\n Returns:\n Client name\n \"\"\"\n client_name = os.getenv(\"CLIENT_NAME\", \"registry-admin-bot\")\n logger.debug(f\"Using client name: {client_name}\")\n return client_name\n\n\ndef _get_token_script() -> str:\n \"\"\"\n Get path to get-m2m-token.sh script.\n\n Returns:\n Script path\n \"\"\"\n # Default to get-m2m-token.sh in the same directory as this script\n script_dir = Path(__file__).parent\n default_script = str(script_dir / \"get-m2m-token.sh\")\n script_path = os.getenv(\"GET_TOKEN_SCRIPT\", default_script)\n logger.debug(f\"Using token script: {script_path}\")\n return script_path\n\n\ndef _get_jwt_token(aws_region: str | None = None, keycloak_url: str | None = None) -> str:\n \"\"\"\n Retrieve JWT token using get-m2m-token.sh script.\n\n Args:\n aws_region: AWS region (passed to script via --aws-region)\n keycloak_url: Keycloak URL (passed to script via --keycloak-url)\n\n Returns:\n JWT access token\n\n Raises:\n RuntimeError: If token retrieval fails\n \"\"\"\n client_name = _get_client_name()\n script_path = _get_token_script()\n\n try:\n # Redact client name in logs for security\n logger.debug(f\"Retrieving token for client: {client_name}\")\n\n # Build command with optional arguments\n cmd = [script_path]\n if aws_region:\n cmd.extend([\"--aws-region\", aws_region])\n if keycloak_url:\n cmd.extend([\"--keycloak-url\", keycloak_url])\n cmd.append(client_name)\n\n result = subprocess.run(cmd, capture_output=True, text=True, check=True)\n\n token = result.stdout.strip()\n\n if not token:\n raise RuntimeError(\"Empty token returned from get-m2m-token.sh\")\n\n # Redact token in logs - show only first 8 characters\n redacted_token = f\"{token[:8]}...\" if len(token) > 8 else \"***\"\n logger.debug(f\"Successfully retrieved JWT token: {redacted_token}\")\n return token\n\n except subprocess.CalledProcessError as e:\n logger.error(f\"Failed to retrieve token: {e.stderr}\")\n raise RuntimeError(f\"Token retrieval failed: {e.stderr}\") from e\n except Exception as e:\n logger.error(f\"Unexpected error retrieving token: {e}\")\n raise RuntimeError(f\"Token retrieval error: {e}\") from e\n\n\ndef _load_json_config(config_path: str) -> dict[str, Any]:\n \"\"\"\n Load JSON configuration file.\n\n Args:\n config_path: Path to JSON config file\n\n Returns:\n Configuration dictionary\n\n Raises:\n FileNotFoundError: If config file not found\n json.JSONDecodeError: If config file is invalid JSON\n \"\"\"\n config_file = Path(config_path)\n\n if not config_file.exists():\n raise FileNotFoundError(f\"Configuration file not found: {config_path}\")\n\n with open(config_file) as f:\n config = json.load(f)\n\n logger.debug(f\"Loaded configuration from {config_path}\")\n return config\n\n\ndef _create_client(args: argparse.Namespace) -> RegistryClient:\n \"\"\"\n Create and return a configured RegistryClient instance.\n\n Args:\n args: Command arguments containing optional CLI values\n\n Returns:\n RegistryClient instance\n\n Raises:\n RuntimeError: If token retrieval fails\n FileNotFoundError: If token file not found\n ValueError: If required configuration is missing\n \"\"\"\n # Check all required configuration upfront\n missing_params = []\n\n # Check REGISTRY_URL\n registry_url = args.registry_url or os.getenv(\"REGISTRY_URL\")\n if not registry_url:\n missing_params.append(\"REGISTRY_URL\")\n\n # Check if token file is provided\n if hasattr(args, \"token_file\") and args.token_file:\n token_path = Path(args.token_file)\n if not token_path.exists():\n raise FileNotFoundError(f\"Token file not found: {args.token_file}\")\n\n logger.debug(f\"Loading token from file: {args.token_file}\")\n\n # Try to parse as JSON first (token files from generate-agent-token.sh or UI)\n try:\n with open(token_path) as f:\n token_data = json.load(f)\n # Extract access_token - handle multiple JSON formats:\n # Format 1: {\"access_token\": \"...\"} (from generate-agent-token.sh)\n # Format 2: {\"tokens\": {\"access_token\": \"...\"}, ...} (from UI \"Get JWT Token\")\n # Format 3: {\"token_data\": {\"access_token\": \"...\"}, ...} (alternative UI format)\n token = token_data.get(\"access_token\")\n if not token and \"tokens\" in token_data:\n token = token_data[\"tokens\"].get(\"access_token\")\n if not token and \"token_data\" in token_data:\n token = token_data[\"token_data\"].get(\"access_token\")\n if not token:\n raise RuntimeError(\n f\"No 'access_token' field found in token file: {args.token_file}\"\n )\n except json.JSONDecodeError:\n # Fall back to plain text token file\n token = token_path.read_text().strip()\n\n if not token:\n raise RuntimeError(f\"Empty token in file: {args.token_file}\")\n\n # Redact token in logs - show only first 8 characters\n redacted_token = f\"{token[:8]}...\" if len(token) > 8 else \"***\"\n logger.debug(f\"Successfully loaded token from file: {redacted_token}\")\n else:\n # Check parameters needed for token script\n aws_region = args.aws_region or os.getenv(\"AWS_REGION\")\n keycloak_url = args.keycloak_url or os.getenv(\"KEYCLOAK_URL\")\n\n if not aws_region:\n missing_params.append(\"AWS_REGION\")\n if not keycloak_url:\n missing_params.append(\"KEYCLOAK_URL\")\n\n # If any parameters are missing, raise comprehensive error\n if missing_params:\n error_msg = \"Missing required configuration:\\n\\n\"\n for param in missing_params:\n error_msg += f\" - {param}\\n\"\n error_msg += \"\\nSet via environment variables or command-line options:\\n\\n\"\n if \"REGISTRY_URL\" in missing_params:\n error_msg += \" export REGISTRY_URL=https://registry.example.com\\n\"\n error_msg += \" OR use --registry-url https://registry.example.com\\n\\n\"\n if \"AWS_REGION\" in missing_params:\n error_msg += \" export AWS_REGION=us-east-1\\n\"\n error_msg += \" OR use --aws-region us-east-1\\n\\n\"\n if \"KEYCLOAK_URL\" in missing_params:\n error_msg += \" export KEYCLOAK_URL=https://keycloak.example.com\\n\"\n error_msg += \" OR use --keycloak-url https://keycloak.example.com\\n\\n\"\n error_msg += \"Alternatively, use --token-file to provide a pre-generated JWT token.\"\n raise ValueError(error_msg)\n\n token = _get_jwt_token(aws_region=aws_region, keycloak_url=keycloak_url)\n\n # Final check for registry URL (in case token file path was provided)\n if missing_params and \"REGISTRY_URL\" in missing_params:\n raise ValueError(\n \"REGISTRY_URL is required.\\n\"\n \"Set via environment variable or --registry-url option:\\n\"\n \" export REGISTRY_URL=https://registry.example.com\\n\"\n \" OR\\n\"\n \" --registry-url https://registry.example.com\"\n )\n\n return RegistryClient(registry_url=registry_url, token=token)\n\n\ndef cmd_register(args: argparse.Namespace) -> int:\n \"\"\"\n Register a new server from JSON configuration.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n config = _load_json_config(args.config)\n\n # Convert config to InternalServiceRegistration\n # Handle both old and new config formats\n registration = InternalServiceRegistration(\n service_path=config.get(\"path\") or config.get(\"service_path\"),\n name=config.get(\"server_name\") or config.get(\"name\"),\n description=config.get(\"description\"),\n proxy_pass_url=config.get(\"proxy_pass_url\"),\n version=config.get(\"version\"),\n status=config.get(\"status\"),\n auth_provider=config.get(\"auth_provider\"),\n auth_scheme=config.get(\"auth_scheme\", config.get(\"auth_type\")),\n supported_transports=config.get(\"supported_transports\"),\n headers=config.get(\"headers\"),\n tool_list_json=config.get(\"tool_list_json\"),\n tags=config.get(\"tags\"),\n overwrite=args.overwrite,\n mcp_endpoint=config.get(\"mcp_endpoint\"),\n sse_endpoint=config.get(\"sse_endpoint\"),\n metadata=config.get(\"metadata\", {}),\n provider_organization=config.get(\"provider_organization\"),\n provider_url=config.get(\"provider_url\"),\n source_created_at=config.get(\"source_created_at\"),\n source_updated_at=config.get(\"source_updated_at\"),\n external_tags=config.get(\"external_tags\"),\n )\n\n client = _create_client(args)\n response = client.register_service(registration)\n\n logger.info(f\"Server registered successfully: {response.path}\")\n logger.info(f\"Message: {response.message}\")\n return 0\n\n except FileNotFoundError as e:\n logger.error(f\"Configuration file error: {e}\")\n return 1\n except json.JSONDecodeError as e:\n logger.error(f\"Invalid JSON configuration: {e}\")\n return 1\n except Exception as e:\n logger.error(f\"Registration failed: {e}\")\n return 1\n\n\ndef cmd_list(args: argparse.Namespace) -> int:\n \"\"\"\n List all registered servers.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n limit = args.limit if hasattr(args, \"limit\") else 20\n offset = args.offset if hasattr(args, \"offset\") else 0\n query = args.query if hasattr(args, \"query\") else None\n\n # Print raw JSON if requested - fetch directly from API to get all fields\n if hasattr(args, \"json\") and args.json:\n import json\n\n params: dict[str, str | int] = {\"limit\": limit, \"offset\": offset}\n if query:\n params[\"query\"] = query\n raw_response = client._make_request(\n method=\"GET\", endpoint=\"/api/servers\", params=params\n )\n print(json.dumps(raw_response.json(), indent=2, default=str))\n return 0\n\n response = client.list_services(\n limit=limit,\n offset=offset,\n )\n\n if not response.servers:\n logger.info(\"No servers registered\")\n return 0\n\n logger.info(\n f\"Found {len(response.servers)} servers \"\n f\"(total: {response.total_count}, offset: {response.offset}, limit: {response.limit}):\\n\"\n )\n\n for server in response.servers:\n status_icon = \"✓\" if server.is_enabled else \"✗\"\n health_icon = {\n \"healthy\": \"🟢\",\n \"unhealthy\": \"🔴\",\n \"unknown\": \"⚪\",\n \"disabled\": \"⚫\",\n }.get(server.health_status.value, \"⚪\")\n\n lifecycle = f\" [{server.status}]\" if server.status != \"active\" else \"\"\n print(f\"{status_icon} {health_icon} {server.path}{lifecycle}\")\n print(f\" Name: {server.display_name}\")\n print(f\" Description: {server.description}\")\n print(f\" Enabled: {server.is_enabled}\")\n print(f\" Health: {server.health_status.value}\")\n if server.status != \"active\":\n print(f\" Lifecycle: {server.status}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List operation failed: {e}\")\n return 1\n\n\ndef cmd_toggle(args: argparse.Namespace) -> int:\n \"\"\"\n Toggle server enabled/disabled status.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.toggle_service(args.path)\n\n status = \"enabled\" if response.is_enabled else \"disabled\"\n logger.info(f\"Server {response.path} is now {status}\")\n logger.info(f\"Message: {response.message}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Toggle operation failed: {e}\")\n return 1\n\n\ndef cmd_remove(args: argparse.Namespace) -> int:\n \"\"\"\n Remove a server from the registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not args.force:\n confirmation = input(f\"Remove server {args.path}? (yes/no): \")\n if confirmation.lower() != \"yes\":\n logger.info(\"Operation cancelled\")\n return 0\n\n client = _create_client(args)\n response = client.remove_service(args.path)\n\n logger.info(f\"Server removed successfully: {args.path}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Remove operation failed: {e}\")\n return 1\n\n\ndef cmd_healthcheck(args: argparse.Namespace) -> int:\n \"\"\"\n Perform health check on all servers.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.healthcheck()\n\n logger.info(f\"Health check status: {response.get('status', 'unknown')}\")\n logger.info(\"\\nHealth check results:\")\n print(json.dumps(response, indent=2))\n return 0\n\n except Exception as e:\n logger.error(f\"Health check failed: {e}\")\n return 1\n\n\ndef cmd_config(args: argparse.Namespace) -> int:\n \"\"\"\n Get registry configuration including deployment mode and features.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_config()\n\n logger.info(f\"Deployment Mode: {response.get('deployment_mode', 'unknown')}\")\n logger.info(f\"Registry Mode: {response.get('registry_mode', 'unknown')}\")\n logger.info(f\"Nginx Updates Enabled: {response.get('nginx_updates_enabled', 'unknown')}\")\n\n if args.json:\n print(json.dumps(response, indent=2))\n else:\n print(\"\\nRegistry Configuration:\")\n print(f\" Deployment Mode: {response.get('deployment_mode')}\")\n print(f\" Registry Mode: {response.get('registry_mode')}\")\n print(f\" Nginx Updates Enabled: {response.get('nginx_updates_enabled')}\")\n print(\"\\nEnabled Features:\")\n features = response.get(\"features\", {})\n for feature, enabled in features.items():\n status = \"enabled\" if enabled else \"disabled\"\n print(f\" {feature}: {status}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to get config: {e}\")\n return 1\n\n\ndef cmd_add_to_groups(args: argparse.Namespace) -> int:\n \"\"\"\n Add server to user groups.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n groups = [g.strip() for g in args.groups.split(\",\")]\n client = _create_client(args)\n response = client.add_server_to_groups(args.server, groups)\n\n logger.info(f\"Server {args.server} added to groups: {', '.join(groups)}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Add to groups failed: {e}\")\n return 1\n\n\ndef cmd_remove_from_groups(args: argparse.Namespace) -> int:\n \"\"\"\n Remove server from user groups.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n groups = [g.strip() for g in args.groups.split(\",\")]\n client = _create_client(args)\n response = client.remove_server_from_groups(args.server, groups)\n\n logger.info(f\"Server {args.server} removed from groups: {', '.join(groups)}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Remove from groups failed: {e}\")\n return 1\n\n\ndef cmd_create_group(args: argparse.Namespace) -> int:\n \"\"\"\n Create a new user group.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.create_group(\n group_name=args.name, description=args.description, create_in_idp=args.idp\n )\n\n logger.info(f\"Group created successfully: {args.name}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Create group failed: {e}\")\n return 1\n\n\ndef cmd_delete_group(args: argparse.Namespace) -> int:\n \"\"\"\n Delete a user group.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not args.force:\n confirmation = input(f\"Delete group {args.name}? (yes/no): \")\n if confirmation.lower() != \"yes\":\n logger.info(\"Operation cancelled\")\n return 0\n\n client = _create_client(args)\n response = client.delete_group(\n group_name=args.name, delete_from_idp=args.idp, force=args.force\n )\n\n logger.info(f\"Group deleted successfully: {args.name}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Delete group failed: {e}\")\n return 1\n\n\ndef cmd_import_group(args: argparse.Namespace) -> int:\n \"\"\"\n Import a complete group definition from JSON file.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n import json\n\n try:\n # Read JSON file\n with open(args.file) as f:\n group_definition = json.load(f)\n\n # Validate required field\n if \"scope_name\" not in group_definition:\n logger.error(\"JSON file must contain 'scope_name' field\")\n return 1\n\n client = _create_client(args)\n response = client.import_group(group_definition)\n\n logger.info(f\"Group imported successfully: {group_definition['scope_name']}\")\n logger.info(f\"Response: {json.dumps(response, indent=2)}\")\n return 0\n\n except FileNotFoundError:\n logger.error(f\"File not found: {args.file}\")\n return 1\n except json.JSONDecodeError as e:\n logger.error(f\"Invalid JSON in file: {e}\")\n return 1\n except Exception as e:\n logger.error(f\"Import group failed: {e}\")\n return 1\n\n\ndef cmd_list_groups(args: argparse.Namespace) -> int:\n \"\"\"\n List all user groups.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n import json\n\n try:\n client = _create_client(args)\n response = client.list_groups(\n include_keycloak=not args.no_keycloak, include_scopes=not args.no_scopes\n )\n\n # If JSON output requested, print raw response and exit\n if hasattr(args, \"json\") and args.json:\n print(json.dumps(response.model_dump(), indent=2, default=str))\n return 0\n\n # Display synchronized groups\n if response.synchronized:\n print(\"\\n=== Synchronized Groups (in both Keycloak and Scopes) ===\")\n for group_name in response.synchronized:\n print(f\" - {group_name}\")\n # Show details from scopes if available\n if group_name in response.scopes_groups:\n group_info = response.scopes_groups[group_name]\n if \"description\" in group_info:\n print(f\" Description: {group_info['description']}\")\n if \"server_count\" in group_info:\n print(f\" Servers: {group_info['server_count']}\")\n\n # Display Keycloak-only groups\n if response.keycloak_only:\n print(\"\\n=== Keycloak-Only Groups (not in Scopes) ===\")\n for group_name in response.keycloak_only:\n print(f\" - {group_name}\")\n\n # Display Scopes-only groups\n if response.scopes_only:\n print(\"\\n=== Scopes-Only Groups (not in Keycloak) ===\")\n for group_name in response.scopes_only:\n print(f\" - {group_name}\")\n if group_name in response.scopes_groups:\n group_info = response.scopes_groups[group_name]\n if \"description\" in group_info:\n print(f\" Description: {group_info['description']}\")\n\n # Summary\n total_keycloak = len(response.keycloak_groups)\n total_scopes = len(response.scopes_groups)\n print(\"\\n=== Summary ===\")\n print(f\"Total Keycloak groups: {total_keycloak}\")\n print(f\"Total Scopes groups: {total_scopes}\")\n print(f\"Synchronized: {len(response.synchronized)}\")\n print(f\"Keycloak-only: {len(response.keycloak_only)}\")\n print(f\"Scopes-only: {len(response.scopes_only)}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"List groups failed: {e}\")\n return 1\n\n\ndef cmd_describe_group(args: argparse.Namespace) -> int:\n \"\"\"\n Describe a specific group with all details.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n import json\n\n try:\n client = _create_client(args)\n group_name = args.name\n\n # Get full group details from scopes storage\n try:\n group_data = client.get_group(group_name)\n except Exception as e:\n if \"404\" in str(e):\n logger.error(f\"Group '{group_name}' not found in scopes storage\")\n group_data = None\n else:\n raise\n\n # If JSON output requested\n if hasattr(args, \"json\") and args.json:\n if group_data:\n print(json.dumps(group_data, indent=2, default=str))\n return 0\n else:\n print(json.dumps({\"error\": \"Group not found\", \"group_name\": group_name}, indent=2))\n return 1\n\n # Human-readable output\n if not group_data:\n print(f\"\\nGroup '{group_name}' not found in scopes storage\\n\")\n return 1\n\n print(f\"\\n=== Group: {group_name} ===\\n\")\n print(f\"Scope Type: {group_data.get('scope_type', 'N/A')}\")\n print(f\"Description: {group_data.get('description', 'N/A')}\")\n print(f\"Created: {group_data.get('created_at', 'N/A')}\")\n print(f\"Updated: {group_data.get('updated_at', 'N/A')}\")\n\n print(\"\\nServer Access:\")\n server_access = group_data.get(\"server_access\", [])\n if server_access:\n for idx, access in enumerate(server_access, 1):\n print(f\" {idx}. Server: {access.get('server', 'N/A')}\")\n if \"methods\" in access:\n print(f\" Methods: {', '.join(access['methods'])}\")\n if \"tools\" in access:\n print(f\" Tools: {', '.join(access['tools'])}\")\n if \"agents\" in access:\n print(f\" Agents: {json.dumps(access['agents'], indent=6)}\")\n else:\n print(\" None\")\n\n print(\"\\nGroup Mappings:\")\n group_mappings = group_data.get(\"group_mappings\", [])\n if group_mappings:\n for mapping in group_mappings:\n print(f\" - {mapping}\")\n else:\n print(\" None\")\n\n print(\"\\nUI Permissions:\")\n ui_permissions = group_data.get(\"ui_permissions\", {})\n if ui_permissions:\n print(json.dumps(ui_permissions, indent=2))\n else:\n print(\" None\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Describe group failed: {e}\")\n return 1\n\n\ndef cmd_server_get(args: argparse.Namespace) -> int:\n \"\"\"\n Get detailed information about a specific server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n server = client.get_server(args.path)\n\n logger.info(f\"Retrieved server: {server.server_name}\")\n output = {\n \"server_name\": server.server_name,\n \"path\": server.path,\n \"description\": server.description,\n \"proxy_pass_url\": server.proxy_pass_url,\n \"tags\": server.tags,\n \"num_tools\": server.num_tools,\n \"tool_list\": server.tool_list,\n \"is_enabled\": server.is_enabled,\n \"health_status\": server.health_status,\n \"transport\": server.transport,\n \"version\": server.version,\n \"versions\": server.versions,\n \"license\": server.license,\n }\n print(json.dumps(output, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Get server failed: {e}\")\n return 1\n\n\ndef cmd_server_rate(args: argparse.Namespace) -> int:\n \"\"\"\n Rate a server (1-5 stars).\n\n Args:\n args: Command arguments with path and rating\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: RatingResponse = client.rate_server(path=args.path, rating=args.rating)\n\n logger.info(f\"✓ {response.message}\")\n logger.info(f\"Average rating: {response.average_rating:.2f} stars\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to rate server: {e}\")\n return 1\n\n\ndef cmd_server_rating(args: argparse.Namespace) -> int:\n \"\"\"\n Get rating information for a server.\n\n Args:\n args: Command arguments with path\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: RatingInfoResponse = client.get_server_rating(path=args.path)\n\n logger.info(f\"\\nRating for server '{args.path}':\")\n logger.info(f\" Average: {response.num_stars:.2f} stars\")\n logger.info(f\" Total ratings: {len(response.rating_details)}\")\n\n if response.rating_details:\n logger.info(\"\\nIndividual ratings (most recent):\")\n # Show first 10 ratings\n for detail in response.rating_details[:10]:\n logger.info(f\" {detail.user}: {detail.rating} stars\")\n\n if len(response.rating_details) > 10:\n logger.info(f\" ... and {len(response.rating_details) - 10} more\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to get ratings: {e}\")\n return 1\n\n\ndef cmd_security_scan(args: argparse.Namespace) -> int:\n \"\"\"\n Get security scan results for a server.\n\n Args:\n args: Command arguments with path and optional json flag\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: SecurityScanResult = client.get_security_scan(path=args.path)\n\n if args.json:\n # Output raw JSON\n print(json.dumps(response.model_dump(), indent=2, default=str))\n else:\n # Pretty print results\n logger.info(f\"\\nSecurity scan results for server '{args.path}':\")\n\n # Display analysis results by analyzer\n if response.analysis_results:\n for analyzer_name, analyzer_data in response.analysis_results.items():\n logger.info(f\"\\n Analyzer: {analyzer_name}\")\n if isinstance(analyzer_data, dict) and \"findings\" in analyzer_data:\n findings = analyzer_data[\"findings\"]\n logger.info(f\" Findings: {len(findings)}\")\n for finding in findings[:5]: # Show first 5\n severity = finding.get(\"severity\", \"UNKNOWN\")\n tool_name = finding.get(\"tool_name\", \"unknown\")\n logger.info(f\" - {tool_name}: {severity}\")\n if len(findings) > 5:\n logger.info(f\" ... and {len(findings) - 5} more\")\n\n # Display tool results summary\n if response.tool_results:\n logger.info(f\"\\n Total tools scanned: {len(response.tool_results)}\")\n safe_count = sum(1 for tool in response.tool_results if tool.get(\"is_safe\", False))\n unsafe_count = len(response.tool_results) - safe_count\n logger.info(f\" Safe tools: {safe_count}\")\n if unsafe_count > 0:\n logger.info(f\" Unsafe tools: {unsafe_count}\")\n logger.warning(\"\\n WARNING: Some tools flagged as potentially unsafe!\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to get security scan results: {e}\")\n return 1\n\n\ndef cmd_rescan(args: argparse.Namespace) -> int:\n \"\"\"\n Trigger manual security scan for a server (admin only).\n\n Args:\n args: Command arguments with path and optional json flag\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: RescanResponse = client.rescan_server(path=args.path)\n\n if args.json:\n # Output raw JSON\n print(json.dumps(response.model_dump(), indent=2, default=str))\n else:\n # Pretty print results\n safety_status = \"SAFE\" if response.is_safe else \"UNSAFE\"\n logger.info(f\"\\nSecurity scan completed for server '{args.path}':\")\n logger.info(f\" Status: {safety_status}\")\n logger.info(f\" Scan timestamp: {response.scan_timestamp}\")\n logger.info(f\" Analyzers used: {', '.join(response.analyzers_used)}\")\n logger.info(\"\\n Severity counts:\")\n logger.info(f\" Critical: {response.critical_issues}\")\n logger.info(f\" High: {response.high_severity}\")\n logger.info(f\" Medium: {response.medium_severity}\")\n logger.info(f\" Low: {response.low_severity}\")\n\n if response.scan_failed:\n logger.error(f\"\\n Scan failed: {response.error_message}\")\n return 1\n\n if not response.is_safe:\n logger.warning(\"\\n WARNING: Server flagged as potentially unsafe!\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to trigger security scan: {e}\")\n return 1\n\n\ndef cmd_server_update_credential(args: argparse.Namespace) -> int:\n \"\"\"\n Update authentication credentials for a server.\n\n Args:\n args: Command arguments with path, auth-scheme, credential, etc.\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n # Validate that credential is provided when auth_scheme is not 'none'\n if args.auth_scheme != \"none\" and not args.credential:\n logger.error(\"--credential is required when --auth-scheme is not 'none'\")\n return 1\n\n client = _create_client(args)\n response = client.update_server_credential(\n service_path=args.path,\n auth_scheme=args.auth_scheme,\n auth_credential=args.credential,\n auth_header_name=args.auth_header_name,\n )\n\n if args.json:\n # Output raw JSON\n print(json.dumps(response, indent=2, default=str))\n else:\n # Pretty print results\n logger.info(f\"\\nAuth credential updated successfully for '{args.path}':\")\n logger.info(f\" Auth scheme: {response.get('auth_scheme')}\")\n if response.get(\"auth_header_name\"):\n logger.info(f\" Header name: {response.get('auth_header_name')}\")\n logger.info(f\" Message: {response.get('message')}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to update server credential: {e}\")\n return 1\n\n\ndef cmd_server_search(args: argparse.Namespace) -> int:\n \"\"\"\n Perform semantic search across all entity types.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.semantic_search(query=args.query, max_results=args.max_results)\n\n if args.json:\n # Output raw JSON\n print(json.dumps(response.model_dump(), indent=2, default=str))\n return 0\n\n total_results = (\n len(response.servers)\n + len(response.tools)\n + len(response.agents)\n + len(response.skills)\n + len(response.virtual_servers)\n )\n\n if total_results == 0:\n logger.info(\"No results found matching the query\")\n return 0\n\n logger.info(f\"Search mode: {response.search_mode}\")\n\n # Display MCP Servers\n if response.servers:\n print(f\"\\n--- MCP Servers ({len(response.servers)}) ---\")\n for server in response.servers:\n print(f\" {server.server_name} ({server.path})\")\n print(f\" Relevance: {server.relevance_score:.2%}\")\n if server.tags:\n print(f\" Tags: {', '.join(server.tags[:5])}\")\n if server.description:\n desc = (\n server.description[:100] + \"...\"\n if len(server.description) > 100\n else server.description\n )\n print(f\" {desc}\")\n print()\n\n # Display Tools\n if response.tools:\n print(f\"\\n--- Tools ({len(response.tools)}) ---\")\n for tool in response.tools:\n print(f\" {tool.tool_name} (from {tool.server_path})\")\n print(f\" Relevance: {tool.relevance_score:.2%}\")\n if tool.description:\n desc = (\n tool.description[:100] + \"...\"\n if len(tool.description) > 100\n else tool.description\n )\n print(f\" {desc}\")\n print()\n\n # Display A2A Agents\n if response.agents:\n print(f\"\\n--- A2A Agents ({len(response.agents)}) ---\")\n for agent in response.agents:\n agent_name = agent.agent_card.get(\"name\", \"Unknown\")\n agent_desc = agent.agent_card.get(\"description\", \"\")\n agent_skills = agent.agent_card.get(\"skills\", [])\n print(f\" {agent_name} ({agent.path})\")\n print(f\" Relevance: {agent.relevance_score:.2%}\")\n if agent_skills:\n skill_names = [\n s.get(\"name\", \"\") if isinstance(s, dict) else str(s)\n for s in agent_skills[:5]\n ]\n print(f\" Skills: {', '.join(skill_names)}\")\n if agent_desc:\n desc = agent_desc[:100] + \"...\" if len(agent_desc) > 100 else agent_desc\n print(f\" {desc}\")\n print()\n\n # Display Skills\n if response.skills:\n print(f\"\\n--- Skills ({len(response.skills)}) ---\")\n for skill in response.skills:\n print(f\" {skill.skill_name} ({skill.path})\")\n print(f\" Relevance: {skill.relevance_score:.2%}\")\n if skill.author:\n print(f\" Author: {skill.author}\")\n if skill.tags:\n print(f\" Tags: {', '.join(skill.tags[:5])}\")\n if skill.description:\n desc = (\n skill.description[:100] + \"...\"\n if len(skill.description) > 100\n else skill.description\n )\n print(f\" {desc}\")\n print()\n\n # Display Virtual MCP Servers\n if response.virtual_servers:\n print(f\"\\n--- Virtual MCP Servers ({len(response.virtual_servers)}) ---\")\n for vs in response.virtual_servers:\n print(f\" {vs.server_name} ({vs.path})\")\n print(f\" Relevance: {vs.relevance_score:.2%}\")\n print(f\" Tools: {vs.num_tools}, Backends: {vs.backend_count}\")\n if vs.backend_paths:\n print(f\" Backend paths: {', '.join(vs.backend_paths)}\")\n if vs.tags:\n print(f\" Tags: {', '.join(vs.tags[:5])}\")\n if vs.description:\n desc = (\n vs.description[:100] + \"...\"\n if len(vs.description) > 100\n else vs.description\n )\n print(f\" {desc}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Semantic search failed: {e}\")\n return 1\n\n\n# Server Version Management Command Handlers\n\n\ndef cmd_list_versions(args: argparse.Namespace) -> int:\n \"\"\"\n List all versions for a server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_server_versions(path=args.path)\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n logger.info(f\"Versions for server {response['path']}:\\n\")\n logger.info(f\"Default version: {response['default_version']}\\n\")\n\n for v in response.get(\"versions\", []):\n default_marker = \" (DEFAULT)\" if v.get(\"is_default\") else \"\"\n status = v.get(\"status\", \"stable\")\n print(f\" {v['version']}{default_marker}\")\n print(f\" Status: {status}\")\n print(f\" URL: {v.get('proxy_pass_url', 'N/A')}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to list versions: {e}\")\n return 1\n\n\ndef cmd_remove_version(args: argparse.Namespace) -> int:\n \"\"\"\n Remove a version from a server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.remove_server_version(path=args.path, version=args.version)\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n logger.info(f\"Successfully removed version {args.version} from {args.path}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to remove version: {e}\")\n return 1\n\n\ndef cmd_set_default_version(args: argparse.Namespace) -> int:\n \"\"\"\n Set the default version for a server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.set_default_version(path=args.path, version=args.version)\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n logger.info(f\"Successfully set default version to {args.version} for {args.path}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to set default version: {e}\")\n return 1\n\n\n# Agent Management Command Handlers\n\n\ndef cmd_agent_register(args: argparse.Namespace) -> int:\n \"\"\"\n Register a new A2A agent from JSON configuration.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n config_path = Path(args.config)\n if not config_path.exists():\n logger.error(f\"Config file not found: {config_path}\")\n return 1\n\n with open(config_path) as f:\n config = json.load(f)\n\n # Convert skills list of dicts to Skill objects\n # Handle both 'input_schema' and 'parameters' field names\n # Also handle 'id' vs 'name' field for skill identifier\n skills = []\n for skill_data in config.get(\"skills\", []):\n # Get skill identifier - prefer 'id', fall back to 'name'\n skill_id = skill_data.get(\"id\") or skill_data.get(\"name\", \"\")\n skill_name = skill_data.get(\"name\", skill_id)\n\n # Normalize field names\n skill_dict = {\n \"id\": skill_id, # Always include id field\n \"name\": skill_name,\n \"description\": skill_data.get(\"description\", \"\"),\n \"tags\": skill_data.get(\"tags\", []), # Include tags field\n }\n # Use 'input_schema' if present, otherwise use 'parameters'\n if \"input_schema\" in skill_data:\n skill_dict[\"input_schema\"] = skill_data[\"input_schema\"]\n elif \"parameters\" in skill_data:\n skill_dict[\"input_schema\"] = skill_data[\"parameters\"]\n\n skills.append(Skill(**skill_dict))\n config[\"skills\"] = skills\n\n # Provider is now a dict object per A2A spec {organization, url}\n # No conversion needed - pass it through as-is\n\n # Normalize and convert visibility string to enum if present\n if \"visibility\" in config:\n # Normalize legacy aliases: \"internal\" -> \"private\", \"group\" -> \"group-restricted\"\n _visibility_aliases = {\"internal\": \"private\", \"group\": \"group-restricted\"}\n normalized = _visibility_aliases.get(\n config[\"visibility\"].lower(), config[\"visibility\"].lower()\n )\n try:\n config[\"visibility\"] = AgentVisibility(normalized)\n except ValueError:\n logger.warning(f\"Unknown visibility '{config['visibility']}', using 'public'\")\n config[\"visibility\"] = AgentVisibility.PUBLIC\n\n # Handle security_schemes conversion\n # Normalize common security type variations to A2A spec values\n if \"security_schemes\" in config:\n transformed_schemes = {}\n for scheme_name, scheme_data in config[\"security_schemes\"].items():\n scheme_type = scheme_data.get(\"type\", \"\").lower()\n # Normalize to A2A spec values: apiKey, http, oauth2, openIdConnect\n # Keep 'http' as is (for bearer auth), not 'bearer'\n type_map = {\n \"http\": \"http\", # HTTP auth (including bearer)\n \"bearer\": \"http\", # Bearer is a type of HTTP auth\n \"apikey\": \"apiKey\",\n \"api_key\": \"apiKey\",\n \"oauth2\": \"oauth2\",\n \"openidconnect\": \"openIdConnect\",\n \"openid\": \"openIdConnect\",\n }\n mapped_type = type_map.get(scheme_type, \"http\")\n\n # Preserve all fields from the original scheme data\n transformed_scheme = dict(scheme_data)\n transformed_scheme[\"type\"] = mapped_type\n\n transformed_schemes[scheme_name] = transformed_scheme\n config[\"security_schemes\"] = transformed_schemes\n\n # Remove fields that aren't in AgentRegistration model\n valid_fields = {\n \"protocol_version\",\n \"name\",\n \"description\",\n \"path\",\n \"url\",\n \"version\",\n \"capabilities\",\n \"metadata\",\n \"default_input_modes\",\n \"default_output_modes\",\n \"provider\",\n \"security_schemes\",\n \"skills\",\n \"tags\",\n \"visibility\",\n \"license\",\n \"supported_protocol\",\n \"supportedProtocol\",\n \"trust_level\",\n \"trustLevel\",\n }\n config = {k: v for k, v in config.items() if k in valid_fields}\n\n agent = AgentRegistration(**config)\n client = _create_client(args)\n response = client.register_agent(agent)\n\n logger.info(\n f\"Agent registered successfully: {response.agent.name} at {response.agent.path}\"\n )\n print(\n json.dumps(\n {\n \"message\": response.message,\n \"agent\": {\n \"name\": response.agent.name,\n \"path\": response.agent.path,\n \"url\": response.agent.url,\n \"num_skills\": response.agent.num_skills,\n \"is_enabled\": response.agent.is_enabled,\n },\n },\n indent=2,\n )\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Agent registration failed: {e}\")\n logger.debug(\"Full error details:\", exc_info=True)\n return 1\n\n\ndef cmd_agent_list(args: argparse.Namespace) -> int:\n \"\"\"\n List all A2A agents.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n limit = args.limit if hasattr(args, \"limit\") else 20\n offset = args.offset if hasattr(args, \"offset\") else 0\n\n # Print raw JSON if requested - fetch directly from API to get all fields\n if hasattr(args, \"json\") and args.json:\n params: dict[str, str | int] = {\"limit\": limit, \"offset\": offset}\n if hasattr(args, \"query\") and args.query:\n params[\"query\"] = args.query\n if hasattr(args, \"enabled_only\") and args.enabled_only:\n params[\"enabled_only\"] = \"true\"\n if hasattr(args, \"visibility\") and args.visibility:\n params[\"visibility\"] = args.visibility\n if hasattr(args, \"allowed_groups\") and args.allowed_groups:\n params[\"allowed_groups\"] = args.allowed_groups\n raw_response = client._make_request(method=\"GET\", endpoint=\"/api/agents\", params=params)\n print(json.dumps(raw_response.json(), indent=2, default=str))\n return 0\n\n response = client.list_agents(\n query=args.query if hasattr(args, \"query\") else None,\n enabled_only=args.enabled_only if hasattr(args, \"enabled_only\") else False,\n visibility=args.visibility if hasattr(args, \"visibility\") else None,\n allowed_groups=args.allowed_groups if hasattr(args, \"allowed_groups\") else None,\n limit=limit,\n offset=offset,\n )\n\n # Debug mode: print full JSON response\n if args.debug:\n logger.debug(\"Full JSON response from API:\")\n print(json.dumps(response.model_dump(by_alias=True), indent=2, default=str))\n print()\n\n if not response.agents:\n logger.info(\"No agents found\")\n return 0\n\n logger.info(\n f\"Found {len(response.agents)} agents \"\n f\"(total: {response.total_count}, offset: {response.offset}, limit: {response.limit}):\\n\"\n )\n for agent in response.agents:\n status_icon = \"✓\" if agent.is_enabled else \"✗\"\n lifecycle = f\" [{agent.status}]\" if agent.status != \"active\" else \"\"\n print(f\"{status_icon} {agent.name} ({agent.path}){lifecycle}\")\n print(f\" {agent.description}\")\n if agent.status != \"active\":\n print(f\" Lifecycle: {agent.status}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List agents failed: {e}\")\n return 1\n\n\ndef cmd_agent_get(args: argparse.Namespace) -> int:\n \"\"\"\n Get detailed information about a specific agent.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n agent = client.get_agent(args.path)\n\n logger.info(f\"Retrieved agent: {agent.name}\")\n output = {\n \"name\": agent.name,\n \"path\": agent.path,\n \"description\": agent.description,\n \"url\": agent.url,\n \"version\": agent.version,\n \"provider\": agent.provider.model_dump() if agent.provider else None,\n \"is_enabled\": agent.is_enabled,\n \"visibility\": agent.visibility,\n \"trust_level\": agent.trust_level,\n \"skills\": [\n {\"name\": skill.name, \"description\": skill.description} for skill in agent.skills\n ],\n \"security_schemes\": _serialize_security_schemes(agent.security_schemes),\n \"default_input_modes\": agent.default_input_modes,\n \"default_output_modes\": agent.default_output_modes,\n \"supported_protocol\": agent.supported_protocol,\n }\n if agent.ans_metadata:\n output[\"ans_metadata\"] = agent.ans_metadata\n if agent.metadata:\n output[\"metadata\"] = agent.metadata\n if agent.capabilities:\n output[\"capabilities\"] = agent.capabilities\n print(json.dumps(output, indent=2))\n return 0\n\n except Exception as e:\n logger.error(f\"Get agent failed: {e}\")\n return 1\n\n\ndef cmd_agent_update(args: argparse.Namespace) -> int:\n \"\"\"\n Update an existing agent.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n config_path = Path(args.config)\n if not config_path.exists():\n logger.error(f\"Config file not found: {config_path}\")\n return 1\n\n with open(config_path) as f:\n config = json.load(f)\n\n # Convert skills list of dicts to Skill objects\n # Handle both 'input_schema' and 'parameters' field names\n skills = []\n for skill_data in config.get(\"skills\", []):\n skill_dict = {\n \"name\": skill_data.get(\"name\", skill_data.get(\"id\", \"\")),\n \"description\": skill_data.get(\"description\", \"\"),\n }\n if \"input_schema\" in skill_data:\n skill_dict[\"input_schema\"] = skill_data[\"input_schema\"]\n elif \"parameters\" in skill_data:\n skill_dict[\"input_schema\"] = skill_data[\"parameters\"]\n skills.append(Skill(**skill_dict))\n config[\"skills\"] = skills\n\n # Convert provider string to enum with validation\n if \"provider\" in config:\n provider_value = config[\"provider\"].lower()\n provider_map = {\n \"anthropic\": AgentProvider.ANTHROPIC,\n \"custom\": AgentProvider.CUSTOM,\n \"other\": AgentProvider.OTHER,\n \"example corp\": AgentProvider.CUSTOM,\n \"example\": AgentProvider.CUSTOM,\n }\n if provider_value in provider_map:\n config[\"provider\"] = provider_map[provider_value]\n else:\n logger.warning(f\"Unknown provider '{config['provider']}', using 'custom'\")\n config[\"provider\"] = AgentProvider.CUSTOM\n\n # Normalize and convert visibility string to enum if present\n if \"visibility\" in config:\n # Normalize legacy aliases: \"internal\" -> \"private\", \"group\" -> \"group-restricted\"\n _visibility_aliases = {\"internal\": \"private\", \"group\": \"group-restricted\"}\n normalized = _visibility_aliases.get(\n config[\"visibility\"].lower(), config[\"visibility\"].lower()\n )\n try:\n config[\"visibility\"] = AgentVisibility(normalized)\n except ValueError:\n logger.warning(f\"Unknown visibility '{config['visibility']}', using 'public'\")\n config[\"visibility\"] = AgentVisibility.PUBLIC\n\n # Handle security_schemes conversion\n if \"security_schemes\" in config:\n transformed_schemes = {}\n for scheme_name, scheme_data in config[\"security_schemes\"].items():\n scheme_type = scheme_data.get(\"type\", \"\").lower()\n type_map = {\n \"http\": \"bearer\",\n \"bearer\": \"bearer\",\n \"apikey\": \"api_key\",\n \"api_key\": \"api_key\",\n \"oauth2\": \"oauth2\",\n }\n mapped_type = type_map.get(scheme_type, \"bearer\")\n transformed_schemes[scheme_name] = {\n \"type\": mapped_type,\n \"description\": scheme_data.get(\"description\", \"\"),\n }\n config[\"security_schemes\"] = transformed_schemes\n\n # Remove fields that aren't in AgentRegistration model\n valid_fields = {\n \"name\",\n \"description\",\n \"path\",\n \"url\",\n \"version\",\n \"capabilities\",\n \"metadata\",\n \"provider\",\n \"security_schemes\",\n \"skills\",\n \"tags\",\n \"visibility\",\n \"license\",\n \"supported_protocol\",\n \"supportedProtocol\",\n \"trust_level\",\n \"trustLevel\",\n }\n config = {k: v for k, v in config.items() if k in valid_fields}\n\n agent = AgentRegistration(**config)\n client = _create_client(args)\n response = client.update_agent(args.path, agent)\n\n logger.info(f\"Agent updated successfully: {response.name}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Agent update failed: {e}\")\n logger.debug(\"Full error details:\", exc_info=True)\n return 1\n\n\ndef cmd_agent_delete(args: argparse.Namespace) -> int:\n \"\"\"\n Delete an agent from the registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not args.force:\n confirmation = input(f\"Delete agent {args.path}? (yes/no): \")\n if confirmation.lower() != \"yes\":\n logger.info(\"Operation cancelled\")\n return 0\n\n client = _create_client(args)\n client.delete_agent(args.path)\n\n logger.info(f\"Agent deleted successfully: {args.path}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Agent deletion failed: {e}\")\n return 1\n\n\ndef cmd_agent_toggle(args: argparse.Namespace) -> int:\n \"\"\"\n Toggle agent enabled/disabled status.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.toggle_agent(args.path, args.enabled)\n\n logger.info(\n f\"Agent {response.path} is now {'enabled' if response.is_enabled else 'disabled'}\"\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Agent toggle failed: {e}\")\n return 1\n\n\ndef cmd_agent_discover(args: argparse.Namespace) -> int:\n \"\"\"\n Discover agents by required skills.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n skills = [s.strip() for s in args.skills.split(\",\")]\n tags = [t.strip() for t in args.tags.split(\",\")] if args.tags else None\n\n client = _create_client(args)\n response = client.discover_agents_by_skills(\n skills=skills, tags=tags, max_results=args.max_results\n )\n\n if not response.agents:\n logger.info(\"No agents found matching the required skills\")\n return 0\n\n logger.info(f\"Found {len(response.agents)} matching agents:\\n\")\n for agent in response.agents:\n print(f\"{agent.name} ({agent.path})\")\n print(f\" Relevance: {agent.relevance_score:.2%}\")\n print(f\" Matching skills: {', '.join(agent.matching_skills)}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Agent discovery failed: {e}\")\n return 1\n\n\ndef cmd_agent_search(args: argparse.Namespace) -> int:\n \"\"\"\n Perform semantic search for agents.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.discover_agents_semantic(query=args.query, max_results=args.max_results)\n\n if not response.agents:\n if args.json:\n print(json.dumps({\"agents\": [], \"query\": args.query}, indent=2))\n else:\n logger.info(\"No agents found matching the query\")\n return 0\n\n if args.json:\n # Output full JSON response\n output = {\n \"query\": args.query,\n \"agents\": [agent.model_dump() for agent in response.agents],\n }\n print(json.dumps(output, indent=2, default=str))\n else:\n # Human-readable output\n logger.info(f\"Found {len(response.agents)} matching agents:\\n\")\n for agent in response.agents:\n print(f\"{agent.name} ({agent.path})\")\n print(f\" Relevance: {agent.relevance_score:.2%}\")\n if agent.trust_verified:\n print(f\" ANS Trust: {agent.trust_verified}\")\n print(f\" {agent.description[:100]}...\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Semantic search failed: {e}\")\n return 1\n\n\ndef cmd_agent_rate(args: argparse.Namespace) -> int:\n \"\"\"\n Rate an agent (1-5 stars).\n\n Args:\n args: Command arguments with path and rating\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: RatingResponse = client.rate_agent(path=args.path, rating=args.rating)\n\n logger.info(f\"✓ {response.message}\")\n logger.info(f\"Average rating: {response.average_rating:.2f} stars\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to rate agent: {e}\")\n return 1\n\n\ndef cmd_agent_rating(args: argparse.Namespace) -> int:\n \"\"\"\n Get rating information for an agent.\n\n Args:\n args: Command arguments with path\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: RatingInfoResponse = client.get_agent_rating(path=args.path)\n\n logger.info(f\"\\nRating for agent '{args.path}':\")\n logger.info(f\" Average: {response.num_stars:.2f} stars\")\n logger.info(f\" Total ratings: {len(response.rating_details)}\")\n\n if response.rating_details:\n logger.info(\"\\nIndividual ratings (most recent):\")\n # Show first 10 ratings\n for detail in response.rating_details[:10]:\n logger.info(f\" {detail.user}: {detail.rating} stars\")\n\n if len(response.rating_details) > 10:\n logger.info(f\" ... and {len(response.rating_details) - 10} more\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to get ratings: {e}\")\n return 1\n\n\ndef cmd_agent_security_scan(args: argparse.Namespace) -> int:\n \"\"\"\n Get security scan results for an agent.\n\n Args:\n args: Command arguments with path and optional json flag\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: AgentSecurityScanResponse = client.get_agent_security_scan(path=args.path)\n\n # Always output as JSON since the response structure is complex\n print(json.dumps(response.model_dump(), indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to get security scan results: {e}\")\n return 1\n\n\ndef cmd_agent_rescan(args: argparse.Namespace) -> int:\n \"\"\"\n Trigger manual security scan for an agent (admin only).\n\n Args:\n args: Command arguments with path and optional json flag\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response: AgentRescanResponse = client.rescan_agent(path=args.path)\n\n if hasattr(args, \"json\") and args.json:\n # Output raw JSON\n print(json.dumps(response.model_dump(), indent=2, default=str))\n else:\n # Pretty print results\n safety_status = \"SAFE\" if response.is_safe else \"UNSAFE\"\n logger.info(f\"\\nSecurity scan completed for agent '{args.path}':\")\n logger.info(f\" Status: {safety_status}\")\n logger.info(f\" Scan timestamp: {response.scan_timestamp}\")\n logger.info(f\" Analyzers used: {', '.join(response.analyzers_used)}\")\n logger.info(\"\\n Severity counts:\")\n logger.info(f\" Critical: {response.critical_issues}\")\n logger.info(f\" High: {response.high_severity}\")\n logger.info(f\" Medium: {response.medium_severity}\")\n logger.info(f\" Low: {response.low_severity}\")\n\n if response.output_file:\n logger.info(f\"\\n Output file: {response.output_file}\")\n\n if response.scan_failed:\n logger.error(f\"\\n Scan failed: {response.error_message}\")\n return 1\n\n if not response.is_safe:\n logger.warning(\"\\n WARNING: Agent flagged as potentially unsafe!\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to trigger security scan: {e}\")\n return 1\n\n\n# ==========================================\n# Agent ANS (Agent Name Service) Command Handlers\n# ==========================================\n\n\ndef cmd_agent_ans_link(args: argparse.Namespace) -> int:\n \"\"\"\n Link an ANS Agent ID to an agent.\n\n Args:\n args: Command arguments with path and ans_agent_id\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.agent_ans_link(\n path=args.path,\n ans_agent_id=args.ans_agent_id,\n )\n\n if result.get(\"success\"):\n logger.info(f\"Successfully linked ANS ID to agent '{args.path}'\")\n if result.get(\"ans_metadata\"):\n print(json.dumps(result[\"ans_metadata\"], indent=2, default=str))\n else:\n logger.error(f\"Failed to link ANS ID: {result.get('message', 'Unknown error')}\")\n return 1\n\n return 0\n\n except Exception as e:\n logger.error(f\"ANS link failed: {e}\")\n return 1\n\n\ndef cmd_agent_ans_status(args: argparse.Namespace) -> int:\n \"\"\"\n Get ANS verification status for an agent.\n\n Args:\n args: Command arguments with path\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.agent_ans_status(path=args.path)\n\n if args.json:\n print(json.dumps(result, indent=2, default=str))\n else:\n logger.info(f\"\\nANS status for agent '{args.path}':\")\n logger.info(f\" Status: {result.get('status', 'unknown')}\")\n logger.info(f\" Domain: {result.get('domain', 'N/A')}\")\n logger.info(f\" ANS Agent ID: {result.get('ans_agent_id', 'N/A')}\")\n if result.get(\"verified_at\"):\n logger.info(f\" Verified at: {result.get('verified_at')}\")\n if result.get(\"last_checked\"):\n logger.info(f\" Last checked: {result.get('last_checked')}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"ANS status check failed: {e}\")\n return 1\n\n\ndef cmd_agent_ans_unlink(args: argparse.Namespace) -> int:\n \"\"\"\n Remove ANS link from an agent.\n\n Args:\n args: Command arguments with path\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.agent_ans_unlink(path=args.path)\n\n if result.get(\"success\"):\n logger.info(f\"Successfully unlinked ANS from agent '{args.path}'\")\n else:\n logger.error(f\"Failed to unlink ANS: {result.get('message', 'Unknown error')}\")\n return 1\n\n return 0\n\n except Exception as e:\n logger.error(f\"ANS unlink failed: {e}\")\n return 1\n\n\n# ==========================================\n# Agent Skills Command Handlers\n# ==========================================\n\n\ndef cmd_skill_register(args: argparse.Namespace) -> int:\n \"\"\"\n Register a new Agent Skill.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n # Parse metadata JSON if provided\n metadata = None\n if hasattr(args, \"metadata\") and args.metadata:\n metadata = json.loads(args.metadata)\n\n request = SkillRegistrationRequest(\n name=args.name,\n skill_md_url=args.url,\n description=args.description if hasattr(args, \"description\") else None,\n version=args.version if hasattr(args, \"version\") else None,\n tags=args.tags.split(\",\") if hasattr(args, \"tags\") and args.tags else [],\n target_agents=args.target_agents.split(\",\")\n if hasattr(args, \"target_agents\") and args.target_agents\n else [],\n metadata=metadata,\n visibility=args.visibility if hasattr(args, \"visibility\") else \"public\",\n )\n\n client = _create_client(args)\n skill = client.register_skill(request)\n\n logger.info(f\"Skill registered successfully: {skill.name} at {skill.path}\")\n print(\n json.dumps(\n {\n \"message\": \"Skill registered successfully\",\n \"skill\": {\n \"name\": skill.name,\n \"path\": skill.path,\n \"description\": skill.description,\n \"skill_md_url\": skill.skill_md_url,\n \"is_enabled\": skill.is_enabled,\n },\n },\n indent=2,\n )\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Skill registration failed: {e}\")\n return 1\n\n\ndef cmd_skill_list(args: argparse.Namespace) -> int:\n \"\"\"\n List all Agent Skills.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n limit = args.limit if hasattr(args, \"limit\") else 20\n offset = args.offset if hasattr(args, \"offset\") else 0\n\n response = client.list_skills(\n include_disabled=args.include_disabled if hasattr(args, \"include_disabled\") else False,\n tag=args.tag if hasattr(args, \"tag\") else None,\n limit=limit,\n offset=offset,\n )\n\n if hasattr(args, \"json\") and args.json:\n print(json.dumps([s.model_dump() for s in response.skills], indent=2, default=str))\n return 0\n\n if not response.skills:\n logger.info(\"No skills found\")\n return 0\n\n logger.info(\n f\"Found {len(response.skills)} skills \"\n f\"(total: {response.total_count}, offset: {response.offset}, limit: {response.limit}):\\n\"\n )\n for skill in response.skills:\n status_icon = \"[+]\" if skill.is_enabled else \"[-]\"\n health = f\"({skill.health_status})\" if skill.health_status else \"\"\n lifecycle = f\" [{skill.status}]\" if skill.status != \"active\" else \"\"\n print(f\"{status_icon} {skill.name} {health}{lifecycle}\")\n print(f\" Path: {skill.path}\")\n if skill.description:\n print(f\" {skill.description[:80]}...\")\n if skill.status != \"active\":\n print(f\" Lifecycle: {skill.status}\")\n if skill.tags:\n print(f\" Tags: {', '.join(skill.tags)}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List skills failed: {e}\")\n return 1\n\n\ndef cmd_skill_get(args: argparse.Namespace) -> int:\n \"\"\"\n Get details for a specific skill.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n skill = client.get_skill(args.path)\n\n logger.info(f\"Retrieved skill: {skill.name}\")\n print(\n json.dumps(\n {\n \"name\": skill.name,\n \"path\": skill.path,\n \"description\": skill.description,\n \"skill_md_url\": skill.skill_md_url,\n \"skill_md_raw_url\": skill.skill_md_raw_url,\n \"version\": skill.version,\n \"author\": skill.author,\n \"visibility\": skill.visibility,\n \"is_enabled\": skill.is_enabled,\n \"tags\": skill.tags,\n \"owner\": skill.owner,\n \"num_stars\": skill.num_stars,\n \"health_status\": skill.health_status,\n \"created_at\": skill.created_at,\n \"updated_at\": skill.updated_at,\n },\n indent=2,\n default=str,\n )\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Get skill failed: {e}\")\n return 1\n\n\ndef cmd_skill_delete(args: argparse.Namespace) -> int:\n \"\"\"\n Delete a skill.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n client.delete_skill(args.path)\n\n logger.info(f\"Skill deleted: {args.path}\")\n print(json.dumps({\"message\": \"Skill deleted successfully\", \"path\": args.path}, indent=2))\n return 0\n\n except Exception as e:\n logger.error(f\"Delete skill failed: {e}\")\n return 1\n\n\ndef cmd_skill_toggle(args: argparse.Namespace) -> int:\n \"\"\"\n Toggle skill enabled/disabled state.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.toggle_skill(args.path, args.enable)\n\n state = \"enabled\" if response.is_enabled else \"disabled\"\n logger.info(f\"Skill {state}: {response.path}\")\n print(json.dumps({\"path\": response.path, \"is_enabled\": response.is_enabled}, indent=2))\n return 0\n\n except Exception as e:\n logger.error(f\"Toggle skill failed: {e}\")\n return 1\n\n\ndef cmd_skill_health(args: argparse.Namespace) -> int:\n \"\"\"\n Check skill health (SKILL.md accessibility).\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.check_skill_health(args.path)\n\n status = \"HEALTHY\" if response.healthy else \"UNHEALTHY\"\n logger.info(f\"Skill health: {status}\")\n print(\n json.dumps(\n {\n \"path\": response.path,\n \"healthy\": response.healthy,\n \"status_code\": response.status_code,\n \"error\": response.error,\n \"response_time_ms\": response.response_time_ms,\n },\n indent=2,\n )\n )\n return 0 if response.healthy else 1\n\n except Exception as e:\n logger.error(f\"Health check failed: {e}\")\n return 1\n\n\ndef cmd_skill_content(args: argparse.Namespace) -> int:\n \"\"\"\n Get SKILL.md content for a skill.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_skill_content(args.path)\n\n if hasattr(args, \"raw\") and args.raw:\n # Output raw content only\n print(response.content)\n else:\n logger.info(f\"Retrieved content from: {response.url}\")\n print(f\"--- SKILL.md ({len(response.content)} chars) ---\")\n print(response.content)\n print(\"--- END ---\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Get content failed: {e}\")\n return 1\n\n\ndef cmd_skill_search(args: argparse.Namespace) -> int:\n \"\"\"\n Search for skills.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.search_skills(\n query=args.query, tags=args.tags if hasattr(args, \"tags\") else None\n )\n\n if args.debug:\n print(json.dumps(response.model_dump(), indent=2, default=str))\n return 0\n\n logger.info(f\"Found {response.total_count} skills matching '{args.query}':\\n\")\n for skill in response.skills:\n print(f\" {skill.get('name')} ({skill.get('path')})\")\n if skill.get(\"description\"):\n print(f\" {skill.get('description')[:60]}...\")\n print(f\" Score: {skill.get('relevance_score', 0):.2f}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Search skills failed: {e}\")\n return 1\n\n\ndef cmd_skill_rate(args: argparse.Namespace) -> int:\n \"\"\"\n Rate a skill (1-5 stars).\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not 1 <= args.rating <= 5:\n logger.error(\"Rating must be between 1 and 5\")\n return 1\n\n client = _create_client(args)\n response = client.rate_skill(args.path, args.rating)\n\n logger.info(f\"Skill rated: {args.rating} stars\")\n print(\n json.dumps(\n {\n \"message\": response.get(\"message\"),\n \"average_rating\": response.get(\"average_rating\"),\n },\n indent=2,\n )\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Rate skill failed: {e}\")\n return 1\n\n\ndef cmd_skill_rating(args: argparse.Namespace) -> int:\n \"\"\"\n Get rating information for a skill.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_skill_rating(args.path)\n\n logger.info(f\"Skill rating: {response.num_stars} stars\")\n print(\n json.dumps(\n {\n \"num_stars\": response.num_stars,\n \"rating_details\": response.rating_details,\n },\n indent=2,\n default=str,\n )\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Get rating failed: {e}\")\n return 1\n\n\ndef cmd_skill_security_scan(args: argparse.Namespace) -> int:\n \"\"\"\n Get security scan results for a skill.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_skill_security_scan(path=args.path)\n\n print(json.dumps(response.model_dump(), indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to get security scan results: {e}\")\n return 1\n\n\ndef cmd_skill_rescan(args: argparse.Namespace) -> int:\n \"\"\"\n Trigger manual security scan for a skill (admin only).\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.rescan_skill(path=args.path)\n\n if not args.json_output:\n safety_status = \"SAFE\" if response.is_safe else \"UNSAFE\"\n logger.info(f\"\\nSecurity scan completed for skill '{args.path}':\")\n logger.info(f\" Status: {safety_status}\")\n logger.info(f\" Critical: {response.critical_issues}\")\n logger.info(f\" High: {response.high_severity}\")\n logger.info(f\" Medium: {response.medium_severity}\")\n logger.info(f\" Low: {response.low_severity}\")\n logger.info(f\" Analyzers: {', '.join(response.analyzers_used)}\")\n\n print(json.dumps(response.model_dump(), indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to trigger security scan: {e}\")\n return 1\n\n\ndef cmd_anthropic_list_servers(args: argparse.Namespace) -> int:\n \"\"\"\n List all servers using Anthropic Registry API v0.1.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result: AnthropicServerList = client.anthropic_list_servers(limit=args.limit)\n\n # Print raw JSON if requested\n if args.raw:\n print(json.dumps(result.model_dump(), indent=2, default=str))\n return 0\n\n logger.info(f\"Retrieved {len(result.servers)} servers\\n\")\n\n if result.metadata:\n logger.info(f\"Next cursor: {result.metadata.nextCursor}\")\n logger.info(f\"Count: {result.metadata.count}\\n\")\n\n # Print server details\n for idx, server_response in enumerate(result.servers, 1):\n server = server_response.server\n print(f\"{idx}. {server.name}\")\n print(f\" Title: {server.title or 'N/A'}\")\n print(f\" Description: {server.description[:100]}...\")\n print(f\" Version: {server.version}\")\n print(f\" Website: {server.websiteUrl or 'N/A'}\")\n\n if server.repository:\n print(f\" Repository: {server.repository.url}\")\n\n if server.packages:\n print(f\" Packages: {len(server.packages)} package(s)\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to list servers: {e}\")\n return 1\n\n\ndef cmd_anthropic_list_versions(args: argparse.Namespace) -> int:\n \"\"\"\n List versions for a specific server using Anthropic Registry API v0.1.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result: AnthropicServerList = client.anthropic_list_server_versions(\n server_name=args.server_name\n )\n\n # Print raw JSON if requested\n if args.raw:\n print(json.dumps(result.model_dump(), indent=2, default=str))\n return 0\n\n logger.info(f\"Found {len(result.servers)} version(s) for {args.server_name}\\n\")\n\n for idx, server_response in enumerate(result.servers, 1):\n server = server_response.server\n print(f\"{idx}. Version {server.version}\")\n print(f\" Name: {server.name}\")\n print(f\" Description: {server.description[:100]}...\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to list server versions: {e}\")\n return 1\n\n\ndef cmd_anthropic_get_server(args: argparse.Namespace) -> int:\n \"\"\"\n Get detailed information about a specific server version using Anthropic Registry API v0.1.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result: AnthropicServerResponse = client.anthropic_get_server_version(\n server_name=args.server_name,\n version=args.version,\n )\n\n # Print raw JSON if requested\n if args.raw:\n print(json.dumps(result.model_dump(), indent=2, default=str))\n return 0\n\n server = result.server\n\n print(f\"\\nServer: {server.name}\")\n print(f\"Title: {server.title or 'N/A'}\")\n print(f\"Version: {server.version}\")\n print(f\"Description: {server.description}\")\n print(f\"Website: {server.websiteUrl or 'N/A'}\")\n\n if server.repository:\n print(\"\\nRepository:\")\n print(f\" URL: {server.repository.url}\")\n print(f\" Source: {server.repository.source}\")\n if server.repository.id:\n print(f\" ID: {server.repository.id}\")\n if server.repository.subfolder:\n print(f\" Subfolder: {server.repository.subfolder}\")\n\n if server.packages:\n print(f\"\\nPackages ({len(server.packages)}):\")\n for idx, package in enumerate(server.packages, 1):\n print(f\" {idx}. {package.registryType}: {package.identifier}\")\n print(f\" Version: {package.version}\")\n if package.runtimeHint:\n print(f\" Runtime: {package.runtimeHint}\")\n\n if server.meta:\n print(\"\\nMetadata:\")\n print(json.dumps(server.meta, indent=2))\n\n if result.meta:\n print(\"\\nRegistry Metadata:\")\n print(json.dumps(result.meta, indent=2))\n\n return 0\n\n except Exception as e:\n logger.error(f\"Failed to get server version: {e}\")\n return 1\n\n\n# User Management Command Handlers (Management API)\n\n\ndef cmd_user_list(args: argparse.Namespace) -> int:\n \"\"\"\n List Keycloak users.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.list_users(\n search=args.search if hasattr(args, \"search\") and args.search else None,\n limit=args.limit if hasattr(args, \"limit\") else 500,\n )\n\n if not response.users:\n logger.info(\"No users found\")\n return 0\n\n logger.info(f\"Found {response.total} users\\n\")\n\n for user in response.users:\n enabled_icon = \"✓\" if user.enabled else \"✗\"\n print(f\"{enabled_icon} {user.username} (ID: {user.id})\")\n print(f\" Email: {user.email or 'N/A'}\")\n if user.firstName or user.lastName:\n name = f\"{user.firstName or ''} {user.lastName or ''}\".strip()\n print(f\" Name: {name}\")\n print(f\" Groups: {', '.join(user.groups) if user.groups else 'None'}\")\n print(f\" Enabled: {user.enabled}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List users failed: {e}\")\n return 1\n\n\ndef cmd_user_create_m2m(args: argparse.Namespace) -> int:\n \"\"\"\n Create M2M service account.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n groups = [g.strip() for g in args.groups.split(\",\")]\n client = _create_client(args)\n result = client.create_m2m_account(\n name=args.name,\n groups=groups,\n description=args.description\n if hasattr(args, \"description\") and args.description\n else None,\n )\n\n logger.info(\"M2M account created successfully\\n\")\n print(f\"Client ID: {result.client_id}\")\n print(f\"Client Secret: {result.client_secret[:8]}...{result.client_secret[-4:]}\")\n print(f\"Groups: {', '.join(result.groups)}\")\n if result.service_principal_id:\n print(f\"Service Principal ID: {result.service_principal_id}\")\n print()\n print(\"IMPORTANT: Save the client secret securely - it cannot be retrieved later.\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Create M2M account failed: {e}\")\n return 1\n\n\ndef cmd_user_create_human(args: argparse.Namespace) -> int:\n \"\"\"\n Create human user account.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n groups = [g.strip() for g in args.groups.split(\",\")]\n client = _create_client(args)\n result = client.create_human_user(\n username=args.username,\n email=args.email,\n first_name=args.first_name,\n last_name=args.last_name,\n groups=groups,\n password=args.password if hasattr(args, \"password\") and args.password else None,\n )\n\n logger.info(\"User created successfully\\n\")\n print(f\"Username: {result.username}\")\n print(f\"User ID: {result.id}\")\n print(f\"Email: {result.email or 'N/A'}\")\n if result.firstName or result.lastName:\n name = f\"{result.firstName or ''} {result.lastName or ''}\".strip()\n print(f\"Name: {name}\")\n print(f\"Groups: {', '.join(result.groups)}\")\n print(f\"Enabled: {result.enabled}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Create user failed: {e}\")\n return 1\n\n\ndef cmd_user_delete(args: argparse.Namespace) -> int:\n \"\"\"\n Delete a user.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not args.force:\n confirmation = input(f\"Delete user '{args.username}'? (yes/no): \")\n if confirmation.lower() != \"yes\":\n logger.info(\"Operation cancelled\")\n return 0\n\n client = _create_client(args)\n result = client.delete_user(args.username)\n\n logger.info(f\"User '{result.username}' deleted successfully\")\n return 0\n\n except Exception as e:\n logger.error(f\"Delete user failed: {e}\")\n return 1\n\n\ndef _print_m2m_client(client: Any) -> None:\n \"\"\"Print an IdPM2MClient record in a readable format.\"\"\"\n print(f\"Client ID: {client.client_id}\")\n print(f\"Name: {client.name}\")\n print(f\"Provider: {client.provider}\")\n print(f\"Enabled: {client.enabled}\")\n print(f\"Groups: {', '.join(client.groups) if client.groups else '(none)'}\")\n print(f\"Description: {client.description or '(none)'}\")\n print(f\"Created by: {client.created_by or '(not set)'}\")\n print(f\"Created at: {client.created_at}\")\n print(f\"Updated at: {client.updated_at}\")\n\n\ndef cmd_m2m_client_create(args: argparse.Namespace) -> int:\n \"\"\"Register an M2M client directly (admin only).\n\n Args:\n args: Command arguments.\n\n Returns:\n Exit code (0 for success, 1 for failure).\n \"\"\"\n try:\n groups = [g.strip() for g in args.groups.split(\",\") if g.strip()] if args.groups else []\n client = _create_client(args)\n result = client.create_m2m_client(\n client_id=args.client_id,\n client_name=args.client_name,\n groups=groups,\n description=args.description,\n )\n logger.info(\"M2M client registered successfully\\n\")\n _print_m2m_client(result)\n return 0\n except Exception as e:\n logger.error(f\"Register M2M client failed: {e}\")\n return 1\n\n\ndef cmd_m2m_client_list(args: argparse.Namespace) -> int:\n \"\"\"List M2M clients with pagination.\n\n Args:\n args: Command arguments.\n\n Returns:\n Exit code (0 for success, 1 for failure).\n \"\"\"\n try:\n client = _create_client(args)\n result = client.list_m2m_clients(\n provider=args.provider,\n limit=args.limit,\n skip=args.skip,\n )\n\n if args.json:\n print(result.model_dump_json(indent=2))\n return 0\n\n print(\n f\"Total: {result.total} (showing {len(result.items)} at skip={result.skip}, limit={result.limit})\\n\"\n )\n for item in result.items:\n _print_m2m_client(item)\n print(\"-\" * 60)\n return 0\n except Exception as e:\n logger.error(f\"List M2M clients failed: {e}\")\n return 1\n\n\ndef cmd_m2m_client_get(args: argparse.Namespace) -> int:\n \"\"\"Get a single M2M client by client_id.\n\n Args:\n args: Command arguments.\n\n Returns:\n Exit code (0 for success, 1 for failure).\n \"\"\"\n try:\n client = _create_client(args)\n result = client.get_m2m_client(args.client_id)\n\n if args.json:\n print(result.model_dump_json(indent=2))\n return 0\n\n _print_m2m_client(result)\n return 0\n except Exception as e:\n logger.error(f\"Get M2M client failed: {e}\")\n return 1\n\n\ndef cmd_m2m_client_update(args: argparse.Namespace) -> int:\n \"\"\"Partially update an M2M client (admin only).\n\n Args:\n args: Command arguments.\n\n Returns:\n Exit code (0 for success, 1 for failure).\n \"\"\"\n try:\n # groups is optional; empty-string input means \"clear groups\".\n groups: list[str] | None = None\n if args.groups is not None:\n groups = [g.strip() for g in args.groups.split(\",\") if g.strip()]\n\n enabled: bool | None = None\n if args.enabled is not None:\n enabled = args.enabled.lower() == \"true\"\n\n client = _create_client(args)\n result = client.patch_m2m_client(\n client_id=args.client_id,\n client_name=args.client_name,\n groups=groups,\n description=args.description,\n enabled=enabled,\n )\n logger.info(\"M2M client updated successfully\\n\")\n _print_m2m_client(result)\n return 0\n except Exception as e:\n logger.error(f\"Update M2M client failed: {e}\")\n return 1\n\n\ndef cmd_m2m_client_delete(args: argparse.Namespace) -> int:\n \"\"\"Delete a manual M2M client (admin only).\n\n Args:\n args: Command arguments.\n\n Returns:\n Exit code (0 for success, 1 for failure).\n \"\"\"\n try:\n if not args.force:\n confirmation = input(f\"Delete M2M client '{args.client_id}'? (yes/no): \")\n if confirmation.lower() != \"yes\":\n logger.info(\"Operation cancelled\")\n return 0\n\n client = _create_client(args)\n client.delete_m2m_client(args.client_id)\n logger.info(f\"M2M client '{args.client_id}' deleted successfully\")\n return 0\n except Exception as e:\n logger.error(f\"Delete M2M client failed: {e}\")\n return 1\n\n\ndef cmd_group_create(args: argparse.Namespace) -> int:\n \"\"\"\n Create a new IAM group.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.create_keycloak_group(name=args.name, description=args.description)\n\n logger.info(f\"IAM group created successfully: {result.name}\")\n print(f\"\\nGroup: {result.name}\")\n print(f\" ID: {result.id}\")\n print(f\" Path: {result.path}\")\n if result.attributes:\n print(f\" Attributes: {json.dumps(result.attributes, indent=4)}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Create IAM group failed: {e}\")\n return 1\n\n\ndef cmd_group_delete(args: argparse.Namespace) -> int:\n \"\"\"\n Delete an IAM group.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not args.force:\n confirmation = input(f\"Delete IAM group '{args.name}'? (yes/no): \")\n if confirmation.lower() != \"yes\":\n logger.info(\"Operation cancelled\")\n return 0\n\n client = _create_client(args)\n result = client.delete_keycloak_group(name=args.name)\n\n logger.info(f\"IAM group deleted successfully: {result.name}\")\n return 0\n\n except Exception as e:\n logger.error(f\"Delete IAM group failed: {e}\")\n return 1\n\n\ndef cmd_group_list(args: argparse.Namespace) -> int:\n \"\"\"\n List IAM groups.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.list_keycloak_iam_groups()\n\n if not response.groups:\n logger.info(\"No IAM groups found\")\n return 0\n\n logger.info(f\"Found {response.total} IAM groups:\\n\")\n\n for group in response.groups:\n print(f\"Group: {group['name']}\")\n print(f\" ID: {group['id']}\")\n print(f\" Path: {group['path']}\")\n if group.get(\"attributes\"):\n print(f\" Attributes: {json.dumps(group['attributes'], indent=4)}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List IAM groups failed: {e}\")\n return 1\n\n\ndef cmd_federation_get(args: argparse.Namespace) -> int:\n \"\"\"\n Get federation configuration.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n config = client.get_federation_config(config_id=args.config_id)\n\n print(json.dumps(config, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Get federation config failed: {e}\")\n return 1\n\n\ndef cmd_federation_save(args: argparse.Namespace) -> int:\n \"\"\"\n Save federation configuration from JSON file.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n # Load config from file\n with open(args.config) as f:\n config_data = json.load(f)\n\n response = client.save_federation_config(config=config_data, config_id=args.config_id)\n\n logger.info(f\"Federation config saved successfully: {args.config_id}\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except FileNotFoundError:\n logger.error(f\"Config file not found: {args.config}\")\n return 1\n except Exception as e:\n logger.error(f\"Save federation config failed: {e}\")\n return 1\n\n\ndef cmd_federation_delete(args: argparse.Namespace) -> int:\n \"\"\"\n Delete federation configuration.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n if not args.force:\n confirm = input(f\"Delete federation config '{args.config_id}'? (y/N): \")\n if confirm.lower() != \"y\":\n logger.info(\"Cancelled\")\n return 0\n\n response = client.delete_federation_config(config_id=args.config_id)\n\n logger.info(f\"Federation config deleted: {args.config_id}\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Delete federation config failed: {e}\")\n return 1\n\n\ndef cmd_federation_list(args: argparse.Namespace) -> int:\n \"\"\"\n List all federation configurations.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.list_federation_configs()\n\n if args.json:\n # Output raw JSON\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n if not response.get(\"configs\"):\n logger.info(\"No federation configs found\")\n return 0\n\n logger.info(f\"Found {response.get('total', 0)} federation configs:\\n\")\n\n for config in response[\"configs\"]:\n print(f\"Config ID: {config.get('id')}\")\n print(f\" Created: {config.get('created_at')}\")\n print(f\" Updated: {config.get('updated_at')}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List federation configs failed: {e}\")\n return 1\n\n\ndef cmd_federation_add_anthropic_server(args: argparse.Namespace) -> int:\n \"\"\"\n Add Anthropic server to federation config.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.add_anthropic_server(\n server_name=args.server_name, config_id=args.config_id\n )\n\n logger.info(f\"Anthropic server added: {args.server_name}\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Add Anthropic server failed: {e}\")\n return 1\n\n\ndef cmd_federation_remove_anthropic_server(args: argparse.Namespace) -> int:\n \"\"\"\n Remove Anthropic server from federation config.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.remove_anthropic_server(\n server_name=args.server_name, config_id=args.config_id\n )\n\n logger.info(f\"Anthropic server removed: {args.server_name}\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Remove Anthropic server failed: {e}\")\n return 1\n\n\ndef cmd_federation_add_asor_agent(args: argparse.Namespace) -> int:\n \"\"\"\n Add ASOR agent to federation config.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.add_asor_agent(agent_id=args.agent_id, config_id=args.config_id)\n\n logger.info(f\"ASOR agent added: {args.agent_id}\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Add ASOR agent failed: {e}\")\n return 1\n\n\ndef cmd_federation_remove_asor_agent(args: argparse.Namespace) -> int:\n \"\"\"\n Remove ASOR agent from federation config.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.remove_asor_agent(agent_id=args.agent_id, config_id=args.config_id)\n\n logger.info(f\"ASOR agent removed: {args.agent_id}\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Remove ASOR agent failed: {e}\")\n return 1\n\n\ndef cmd_federation_sync(args: argparse.Namespace) -> int:\n \"\"\"\n Trigger manual federation sync to import servers/agents.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.sync_federation(config_id=args.config_id, source=args.source)\n\n if args.json:\n # Output raw JSON\n print(json.dumps(response, indent=2, default=str))\n else:\n # Formatted output\n logger.info(f\"Federation sync completed: {response.get('message')}\")\n print(\"\\nSync Results:\")\n print(f\" Config ID: {response.get('config_id')}\")\n print(f\" Total Synced: {response.get('total_synced', 0)}\")\n\n results = response.get(\"results\", {})\n if results.get(\"anthropic\", {}).get(\"count\", 0) > 0:\n print(f\"\\n Anthropic Servers ({results['anthropic']['count']}):\")\n for server in results[\"anthropic\"].get(\"servers\", []):\n print(f\" - {server}\")\n\n if results.get(\"asor\", {}).get(\"count\", 0) > 0:\n print(f\"\\n ASOR Agents ({results['asor']['count']}):\")\n for agent in results[\"asor\"].get(\"agents\", []):\n print(f\" - {agent}\")\n\n if results.get(\"aws_registry\", {}).get(\"count\", 0) > 0:\n aws_reg = results[\"aws_registry\"]\n print(f\"\\n AWS Agent Registry ({aws_reg['count']}):\")\n if aws_reg.get(\"servers\"):\n print(f\" Servers ({len(aws_reg['servers'])}):\")\n for server in aws_reg[\"servers\"]:\n print(f\" - {server}\")\n if aws_reg.get(\"agents\"):\n print(f\" Agents ({len(aws_reg['agents'])}):\")\n for agent in aws_reg[\"agents\"]:\n print(f\" - {agent}\")\n if aws_reg.get(\"skills\"):\n print(f\" Skills ({len(aws_reg['skills'])}):\")\n for skill in aws_reg[\"skills\"]:\n print(f\" - {skill}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Federation sync failed: {e}\")\n return 1\n\n\ndef cmd_peer_list(args: argparse.Namespace) -> int:\n \"\"\"\n List all configured peer registries.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n enabled_filter = None\n if hasattr(args, \"enabled_only\") and args.enabled_only:\n enabled_filter = True\n\n response = client.list_peers(enabled=enabled_filter)\n\n if args.json:\n masked_response = _mask_sensitive_fields(response)\n print(json.dumps(masked_response, indent=2, default=str))\n return 0\n\n peers = response if isinstance(response, list) else response.get(\"peers\", [])\n\n if not peers:\n logger.info(\"No peer registries configured\")\n return 0\n\n logger.info(f\"Found {len(peers)} peer registries:\\n\")\n\n for peer in peers:\n status = \"enabled\" if peer.get(\"enabled\") else \"disabled\"\n print(f\" Peer ID: {peer.get('peer_id')}\")\n print(f\" Name: {peer.get('name')}\")\n print(f\" Endpoint: {peer.get('endpoint')}\")\n print(f\" Status: {status}\")\n print(f\" Sync Mode: {peer.get('sync_mode', 'all')}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List peers failed: {e}\")\n return 1\n\n\ndef cmd_peer_add(args: argparse.Namespace) -> int:\n \"\"\"\n Add a new peer registry from a JSON config file.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n with open(args.config) as f:\n config_data = json.load(f)\n\n # Override federation_token from CLI arg if provided\n if hasattr(args, \"federation_token\") and args.federation_token:\n config_data[\"federation_token\"] = args.federation_token\n\n response = client.add_peer(config=config_data)\n\n logger.info(f\"Peer registry added successfully: {config_data.get('peer_id')}\")\n masked_response = _mask_sensitive_fields(response)\n print(json.dumps(masked_response, indent=2, default=str))\n return 0\n\n except FileNotFoundError:\n logger.error(f\"Config file not found: {args.config}\")\n return 1\n except Exception as e:\n logger.error(f\"Add peer failed: {e}\")\n return 1\n\n\ndef cmd_peer_get(args: argparse.Namespace) -> int:\n \"\"\"\n Get details of a specific peer registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_peer(peer_id=args.peer_id)\n\n if args.json:\n masked_response = _mask_sensitive_fields(response)\n print(json.dumps(masked_response, indent=2, default=str))\n return 0\n\n print(f\"Peer ID: {response.get('peer_id')}\")\n print(f\"Name: {response.get('name')}\")\n print(f\"Endpoint: {response.get('endpoint')}\")\n print(f\"Enabled: {response.get('enabled')}\")\n print(f\"Sync Mode: {response.get('sync_mode', 'all')}\")\n print(f\"Created: {response.get('created_at')}\")\n print(f\"Updated: {response.get('updated_at')}\")\n\n # Mask federation token in non-JSON output\n fed_token = response.get(\"federation_token\")\n if fed_token:\n masked_token = f\"{fed_token[:3]}...\" if len(fed_token) > 3 else \"***\"\n print(f\"Fed Token: {masked_token}\")\n\n whitelist_servers = response.get(\"whitelist_servers\", [])\n if whitelist_servers:\n print(f\"Whitelist: {', '.join(whitelist_servers)}\")\n\n tag_filter = response.get(\"tag_filter\", [])\n if tag_filter:\n print(f\"Tag Filter: {', '.join(tag_filter)}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Get peer failed: {e}\")\n return 1\n\n\ndef cmd_peer_update(args: argparse.Namespace) -> int:\n \"\"\"\n Update an existing peer registry from a JSON config file.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n with open(args.config) as f:\n config_data = json.load(f)\n\n # Override federation_token from CLI arg if provided\n if hasattr(args, \"federation_token\") and args.federation_token:\n config_data[\"federation_token\"] = args.federation_token\n\n response = client.update_peer(peer_id=args.peer_id, config=config_data)\n\n logger.info(f\"Peer registry updated successfully: {args.peer_id}\")\n masked_response = _mask_sensitive_fields(response)\n print(json.dumps(masked_response, indent=2, default=str))\n return 0\n\n except FileNotFoundError:\n logger.error(f\"Config file not found: {args.config}\")\n return 1\n except Exception as e:\n logger.error(f\"Update peer failed: {e}\")\n return 1\n\n\ndef cmd_peer_update_token(args: argparse.Namespace) -> int:\n \"\"\"\n Update only the federation token for a peer registry.\n\n This command is useful for:\n - Recovering from token loss (issue #561)\n - Rotating federation tokens without modifying other peer config\n - Fixing authentication issues after peer updates\n\n Args:\n args: Command arguments with peer_id and federation_token\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n response = client.update_peer_token(\n peer_id=args.peer_id, federation_token=args.federation_token\n )\n\n logger.info(f\"Federation token updated successfully for peer: {args.peer_id}\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Update peer token failed: {e}\")\n return 1\n\n\ndef cmd_peer_remove(args: argparse.Namespace) -> int:\n \"\"\"\n Remove a peer registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not args.force:\n confirm = input(f\"Remove peer registry '{args.peer_id}'? (y/N): \")\n if confirm.lower() != \"y\":\n logger.info(\"Cancelled\")\n return 0\n\n client = _create_client(args)\n response = client.remove_peer(peer_id=args.peer_id)\n\n logger.info(f\"Peer registry removed: {args.peer_id}\")\n masked_response = _mask_sensitive_fields(response)\n print(json.dumps(masked_response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Remove peer failed: {e}\")\n return 1\n\n\ndef cmd_peer_sync(args: argparse.Namespace) -> int:\n \"\"\"\n Trigger sync from a specific peer registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.sync_peer(peer_id=args.peer_id)\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n # Check success field from SyncResult model\n success = response.get(\"success\", False)\n status_text = \"SUCCESS\" if success else \"FAILED\"\n\n print(f\"\\nSync Results for peer '{args.peer_id}':\")\n print(f\" Status: {status_text}\")\n print(f\" Servers Synced: {response.get('servers_synced', 0)}\")\n print(f\" Agents Synced: {response.get('agents_synced', 0)}\")\n print(f\" Servers Orphaned: {response.get('servers_orphaned', 0)}\")\n print(f\" Agents Orphaned: {response.get('agents_orphaned', 0)}\")\n\n # SyncResult has 'error_message' (singular), not 'errors' (plural)\n error_msg = response.get(\"error_message\")\n if error_msg:\n print(\"\\n Error:\")\n print(f\" {error_msg}\")\n\n return 0 if success else 1\n\n except Exception as e:\n logger.error(f\"Peer sync failed: {e}\")\n return 1\n\n\ndef cmd_peer_sync_all(args: argparse.Namespace) -> int:\n \"\"\"\n Trigger sync from all enabled peer registries.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.sync_all_peers()\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n results = response if isinstance(response, list) else response.get(\"results\", [])\n print(\"\\nSync All Peers Results:\")\n print(f\" Total peers synced: {len(results)}\")\n\n for result in results:\n peer_id = result.get(\"peer_id\", \"unknown\")\n status = result.get(\"status\", \"unknown\")\n print(f\"\\n {peer_id}: {status}\")\n print(f\" Servers: {result.get('servers_synced', 0)}\")\n print(f\" Agents: {result.get('agents_synced', 0)}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Sync all peers failed: {e}\")\n return 1\n\n\ndef cmd_peer_status(args: argparse.Namespace) -> int:\n \"\"\"\n Get sync status for a specific peer registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_peer_status(peer_id=args.peer_id)\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n print(f\"\\nSync Status for peer '{args.peer_id}':\")\n\n # Determine last sync status from history or health\n history = response.get(\"sync_history\", [])\n if history:\n last_entry = history[0]\n last_status = \"success\" if last_entry.get(\"success\") else \"failed\"\n last_time = last_entry.get(\"completed_at\") or last_entry.get(\"started_at\")\n else:\n last_status = \"never\"\n last_time = response.get(\"last_successful_sync\") or response.get(\"last_sync_attempt\")\n\n print(f\" Last Sync Status: {last_status}\")\n print(f\" Last Sync Time: {last_time or 'never'}\")\n print(f\" Last Generation: {response.get('current_generation', 0)}\")\n print(f\" Servers Synced: {response.get('total_servers_synced', 0)}\")\n print(f\" Agents Synced: {response.get('total_agents_synced', 0)}\")\n print(f\" Is Healthy: {response.get('is_healthy', False)}\")\n\n if history:\n print(f\"\\n Recent Sync History ({len(history)} entries):\")\n for entry in history[:5]:\n entry_status = \"success\" if entry.get(\"success\") else \"failed\"\n entry_time = entry.get(\"completed_at\") or entry.get(\"started_at\")\n print(f\" {entry_time} - {entry_status}\")\n print(\n f\" Servers: {entry.get('servers_synced', 0)}, \"\n f\"Agents: {entry.get('agents_synced', 0)}\"\n )\n\n return 0\n\n except Exception as e:\n logger.error(f\"Get peer status failed: {e}\")\n return 1\n\n\ndef cmd_peer_enable(args: argparse.Namespace) -> int:\n \"\"\"\n Enable a peer registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.enable_peer(peer_id=args.peer_id)\n\n logger.info(f\"Peer registry enabled: {args.peer_id}\")\n masked_response = _mask_sensitive_fields(response)\n print(json.dumps(masked_response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Enable peer failed: {e}\")\n return 1\n\n\ndef cmd_peer_disable(args: argparse.Namespace) -> int:\n \"\"\"\n Disable a peer registry.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.disable_peer(peer_id=args.peer_id)\n\n logger.info(f\"Peer registry disabled: {args.peer_id}\")\n masked_response = _mask_sensitive_fields(response)\n print(json.dumps(masked_response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Disable peer failed: {e}\")\n return 1\n\n\ndef cmd_peer_connections(args: argparse.Namespace) -> int:\n \"\"\"\n Get all federation connections across all peers.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_peer_connections()\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n connections = response if isinstance(response, list) else response.get(\"connections\", [])\n\n if not connections:\n logger.info(\"No federation connections found\")\n return 0\n\n logger.info(f\"Found {len(connections)} federation connections:\\n\")\n for conn in connections:\n print(f\" Peer: {conn.get('peer_id')}\")\n print(f\" Direction: {conn.get('direction', 'unknown')}\")\n print(f\" Status: {conn.get('status', 'unknown')}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"Get peer connections failed: {e}\")\n return 1\n\n\ndef cmd_peer_shared_resources(args: argparse.Namespace) -> int:\n \"\"\"\n Get resource sharing summary across all peers.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.get_shared_resources()\n\n if args.json:\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n print(\"\\nShared Resources Summary:\")\n print(json.dumps(response, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Get shared resources failed: {e}\")\n return 1\n\n\n# ==========================================\n# Virtual MCP Server Command Handlers\n# ==========================================\n\n\ndef cmd_vs_create(args: argparse.Namespace) -> int:\n \"\"\"\n Create a virtual MCP server from JSON config.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n # Load config from file\n with open(args.config) as f:\n config_data = json.load(f)\n\n # Build tool mappings\n tool_mappings = []\n for mapping in config_data.get(\"tool_mappings\", []):\n tool_mappings.append(\n ToolMapping(\n tool_name=mapping[\"tool_name\"],\n alias=mapping.get(\"alias\"),\n backend_server_path=mapping[\"backend_server_path\"],\n backend_version=mapping.get(\"backend_version\"),\n description_override=mapping.get(\"description_override\"),\n )\n )\n\n # Build tool scope overrides\n tool_scope_overrides = []\n for override in config_data.get(\"tool_scope_overrides\", []):\n tool_scope_overrides.append(\n ToolScopeOverride(\n tool_alias=override[\"tool_alias\"],\n required_scopes=override.get(\"required_scopes\", []),\n )\n )\n\n request = VirtualServerCreateRequest(\n path=config_data[\"path\"],\n server_name=config_data[\"server_name\"],\n description=config_data.get(\"description\"),\n tool_mappings=tool_mappings,\n required_scopes=config_data.get(\"required_scopes\", []),\n tool_scope_overrides=tool_scope_overrides,\n tags=config_data.get(\"tags\", []),\n supported_transports=config_data.get(\"supported_transports\", [\"streamable-http\"]),\n is_enabled=config_data.get(\"is_enabled\", True),\n )\n\n result = client.create_virtual_server(request)\n\n logger.info(f\"Virtual server created: {result.path}\")\n print(\n json.dumps(\n {\n \"message\": \"Virtual server created successfully\",\n \"virtual_server\": {\n \"path\": result.path,\n \"server_name\": result.server_name,\n \"description\": result.description,\n \"is_enabled\": result.is_enabled,\n \"tool_count\": len(result.tool_mappings),\n },\n },\n indent=2,\n )\n )\n return 0\n\n except FileNotFoundError:\n logger.error(f\"Config file not found: {args.config}\")\n return 1\n except KeyError as e:\n logger.error(f\"Missing required field in config: {e}\")\n return 1\n except Exception as e:\n logger.error(f\"Create virtual server failed: {e}\")\n return 1\n\n\ndef cmd_vs_list(args: argparse.Namespace) -> int:\n \"\"\"\n List virtual MCP servers.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n response = client.list_virtual_servers(\n enabled_only=args.enabled_only if hasattr(args, \"enabled_only\") else False,\n tag=args.tag if hasattr(args, \"tag\") else None,\n )\n\n if args.json:\n print(json.dumps(response.model_dump(), indent=2, default=str))\n return 0\n\n print(f\"\\nVirtual MCP Servers ({response.total} total):\")\n print(\"-\" * 80)\n\n for vs in response.virtual_servers:\n status = \"enabled\" if vs.is_enabled else \"disabled\"\n tool_count = len(vs.tool_mappings)\n print(f\" {vs.path}\")\n print(f\" Name: {vs.server_name}\")\n print(f\" Status: {status}\")\n print(f\" Tools: {tool_count}\")\n if vs.description:\n print(f\" Description: {vs.description[:60]}...\")\n if vs.tags:\n print(f\" Tags: {', '.join(vs.tags)}\")\n print()\n\n return 0\n\n except Exception as e:\n logger.error(f\"List virtual servers failed: {e}\")\n return 1\n\n\ndef cmd_vs_get(args: argparse.Namespace) -> int:\n \"\"\"\n Get virtual MCP server details.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.get_virtual_server(args.path)\n\n if args.json:\n print(json.dumps(result.model_dump(), indent=2, default=str))\n return 0\n\n print(f\"\\nVirtual MCP Server: {result.path}\")\n print(\"-\" * 60)\n print(f\" Name: {result.server_name}\")\n print(f\" Status: {'enabled' if result.is_enabled else 'disabled'}\")\n print(f\" Description: {result.description or 'N/A'}\")\n print(f\" Rating: {result.num_stars} stars\")\n print(f\" Tags: {', '.join(result.tags) if result.tags else 'None'}\")\n print(f\" Transports: {', '.join(result.supported_transports)}\")\n print(\n f\" Required Scopes: {', '.join(result.required_scopes) if result.required_scopes else 'None'}\"\n )\n\n print(f\"\\n Tool Mappings ({len(result.tool_mappings)}):\")\n for mapping in result.tool_mappings:\n alias_info = f\" -> {mapping.alias}\" if mapping.alias else \"\"\n version_info = f\" @{mapping.backend_version}\" if mapping.backend_version else \"\"\n print(f\" - {mapping.tool_name}{alias_info}\")\n print(f\" Backend: {mapping.backend_server_path}{version_info}\")\n\n if result.tool_scope_overrides:\n print(\"\\n Tool Scope Overrides:\")\n for override in result.tool_scope_overrides:\n print(f\" - {override.tool_alias}: {', '.join(override.required_scopes)}\")\n\n print(f\"\\n Created: {result.created_at or 'N/A'}\")\n print(f\" Updated: {result.updated_at or 'N/A'}\")\n print(f\" Created By: {result.created_by or 'N/A'}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Get virtual server failed: {e}\")\n return 1\n\n\ndef cmd_vs_update(args: argparse.Namespace) -> int:\n \"\"\"\n Update a virtual MCP server from JSON config.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n # Load config from file\n with open(args.config) as f:\n config_data = json.load(f)\n\n # Build tool mappings\n tool_mappings = []\n for mapping in config_data.get(\"tool_mappings\", []):\n tool_mappings.append(\n ToolMapping(\n tool_name=mapping[\"tool_name\"],\n alias=mapping.get(\"alias\"),\n backend_server_path=mapping[\"backend_server_path\"],\n backend_version=mapping.get(\"backend_version\"),\n description_override=mapping.get(\"description_override\"),\n )\n )\n\n # Build tool scope overrides\n tool_scope_overrides = []\n for override in config_data.get(\"tool_scope_overrides\", []):\n tool_scope_overrides.append(\n ToolScopeOverride(\n tool_alias=override[\"tool_alias\"],\n required_scopes=override.get(\"required_scopes\", []),\n )\n )\n\n request = VirtualServerCreateRequest(\n path=config_data[\"path\"],\n server_name=config_data[\"server_name\"],\n description=config_data.get(\"description\"),\n tool_mappings=tool_mappings,\n required_scopes=config_data.get(\"required_scopes\", []),\n tool_scope_overrides=tool_scope_overrides,\n tags=config_data.get(\"tags\", []),\n supported_transports=config_data.get(\"supported_transports\", [\"streamable-http\"]),\n is_enabled=config_data.get(\"is_enabled\", True),\n )\n\n result = client.update_virtual_server(args.path, request)\n\n logger.info(f\"Virtual server updated: {result.path}\")\n print(\n json.dumps(\n {\n \"message\": \"Virtual server updated successfully\",\n \"virtual_server\": {\n \"path\": result.path,\n \"server_name\": result.server_name,\n \"is_enabled\": result.is_enabled,\n },\n },\n indent=2,\n )\n )\n return 0\n\n except FileNotFoundError:\n logger.error(f\"Config file not found: {args.config}\")\n return 1\n except Exception as e:\n logger.error(f\"Update virtual server failed: {e}\")\n return 1\n\n\ndef cmd_vs_delete(args: argparse.Namespace) -> int:\n \"\"\"\n Delete a virtual MCP server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not args.force:\n confirm = input(f\"Delete virtual server '{args.path}'? [y/N]: \")\n if confirm.lower() != \"y\":\n print(\"Cancelled\")\n return 0\n\n client = _create_client(args)\n result = client.delete_virtual_server(args.path)\n\n logger.info(f\"Virtual server deleted: {args.path}\")\n print(\n json.dumps(\n {\n \"message\": result.message,\n \"path\": result.path,\n },\n indent=2,\n )\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Delete virtual server failed: {e}\")\n return 1\n\n\ndef cmd_vs_toggle(args: argparse.Namespace) -> int:\n \"\"\"\n Enable or disable a virtual MCP server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n enable = args.enabled.lower() == \"true\"\n result = client.toggle_virtual_server(args.path, enable)\n\n action = \"enabled\" if result.is_enabled else \"disabled\"\n logger.info(f\"Virtual server {action}: {args.path}\")\n print(\n json.dumps(\n {\n \"message\": result.message,\n \"path\": result.path,\n \"is_enabled\": result.is_enabled,\n },\n indent=2,\n )\n )\n return 0\n\n except Exception as e:\n logger.error(f\"Toggle virtual server failed: {e}\")\n return 1\n\n\ndef cmd_vs_rate(args: argparse.Namespace) -> int:\n \"\"\"\n Rate a virtual MCP server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n if not 1 <= args.rating <= 5:\n logger.error(\"Rating must be between 1 and 5\")\n return 1\n\n client = _create_client(args)\n result = client.rate_virtual_server(args.path, args.rating)\n\n logger.info(f\"Virtual server rated: {args.path}\")\n print(json.dumps(result, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Rate virtual server failed: {e}\")\n return 1\n\n\ndef cmd_vs_rating(args: argparse.Namespace) -> int:\n \"\"\"\n Get rating information for a virtual MCP server.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.get_virtual_server_rating(args.path)\n\n print(json.dumps(result, indent=2, default=str))\n return 0\n\n except Exception as e:\n logger.error(f\"Get virtual server rating failed: {e}\")\n return 1\n\n\ndef cmd_registry_card_get(args: argparse.Namespace) -> int:\n \"\"\"\n Get the registry card.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n card = client.get_registry_card()\n print(json.dumps(card.model_dump(), indent=2))\n return 0\n\n except Exception as e:\n logger.error(f\"Get registry card failed: {e}\")\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n\n\ndef cmd_registry_card_discover(args: argparse.Namespace) -> int:\n \"\"\"\n Discover registry card via .well-known endpoint.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n card = client.get_well_known_registry_card()\n print(json.dumps(card.model_dump(), indent=2))\n return 0\n\n except Exception as e:\n logger.error(f\"Registry card discovery failed: {e}\")\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n\n\ndef cmd_registry_card_update(args: argparse.Namespace) -> int:\n \"\"\"\n Update the registry card.\n\n Args:\n args: Command arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n updates = {}\n if args.name:\n updates[\"name\"] = args.name\n if args.description:\n updates[\"description\"] = args.description\n if args.contact_email:\n updates[\"contact\"] = updates.get(\"contact\", {})\n updates[\"contact\"][\"email\"] = args.contact_email\n if args.contact_url:\n updates[\"contact\"] = updates.get(\"contact\", {})\n updates[\"contact\"][\"url\"] = args.contact_url\n\n result = client.patch_registry_card(updates)\n print(f\"Success: {result['message']}\")\n print(json.dumps(result[\"registry_card\"], indent=2))\n return 0\n\n except Exception as e:\n logger.error(f\"Update registry card failed: {e}\")\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n\n\ndef cmd_telemetry_heartbeat(args: argparse.Namespace) -> int:\n \"\"\"Force an immediate heartbeat telemetry event.\n\n Args:\n args: Parsed command line arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.force_heartbeat()\n\n print(json.dumps(result, indent=2))\n\n if result.get(\"status\") == \"sent\":\n logger.info(\"Heartbeat sent successfully\")\n return 0\n else:\n logger.warning(f\"Heartbeat status: {result.get('status')}\")\n return 1\n\n except Exception as e:\n logger.error(f\"Force heartbeat failed: {e}\")\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n\n\ndef cmd_telemetry_startup(args: argparse.Namespace) -> int:\n \"\"\"Force an immediate startup telemetry event.\n\n Args:\n args: Parsed command line arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n result = client.force_startup_ping()\n\n print(json.dumps(result, indent=2))\n\n if result.get(\"status\") == \"sent\":\n logger.info(\"Startup ping sent successfully\")\n return 0\n else:\n logger.warning(f\"Startup ping status: {result.get('status')}\")\n return 1\n\n except Exception as e:\n logger.error(f\"Force startup ping failed: {e}\")\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n\n\ndef cmd_logs(args: argparse.Namespace) -> int:\n \"\"\"Query application logs (admin only).\n\n Args:\n args: Parsed command line arguments\n\n Returns:\n Exit code (0 for success, 1 for failure)\n \"\"\"\n try:\n client = _create_client(args)\n\n if getattr(args, \"metadata\", False):\n metadata = client.get_log_metadata()\n print(json.dumps(metadata.model_dump(), indent=2))\n return 0\n\n result = client.get_logs(\n service=getattr(args, \"service\", None),\n level=getattr(args, \"level\", None),\n hostname=getattr(args, \"hostname\", None),\n search=getattr(args, \"search\", None),\n start=getattr(args, \"start\", None),\n end=getattr(args, \"end\", None),\n limit=getattr(args, \"limit\", 100),\n offset=getattr(args, \"offset\", 0),\n )\n\n if getattr(args, \"json\", False):\n print(json.dumps(result.model_dump(), indent=2))\n else:\n print(f\"Total: {result.total_count} (showing {len(result.entries)}, \"\n f\"offset={result.offset}, has_next={result.has_next})\")\n print(\"-\" * 100)\n for entry in result.entries:\n print(f\"[{entry.timestamp}] {entry.level:<8} {entry.service}/{entry.hostname} \"\n f\"{entry.logger}:{entry.lineno} {entry.message}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"Log query failed: {e}\")\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n\n\ndef main() -> int:\n \"\"\"\n Main entry point for the CLI.\n\n Returns:\n Exit code\n \"\"\"\n parser = argparse.ArgumentParser(\n description=\"MCP Gateway Registry Management CLI\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nEnvironment Variables (used if command-line options not provided):\n REGISTRY_URL Registry base URL\n AWS_REGION AWS region where Keycloak and SSM are deployed\n KEYCLOAK_URL Keycloak base URL\n CLIENT_NAME Keycloak client name (default: registry-admin-bot)\n GET_TOKEN_SCRIPT Path to get-m2m-token.sh script\n\nExamples:\n # Register a server (using environment variables)\n export REGISTRY_URL=https://registry.us-east-1.mycorp.click\n export AWS_REGION=us-east-1\n export KEYCLOAK_URL=https://kc.us-east-1.mycorp.click\n uv run python registry_management.py register --config server-config.json\n\n # Register a server (using command-line arguments)\n uv run python registry_management.py \\\\\n --registry-url https://registry.us-east-1.mycorp.click \\\\\n --aws-region us-east-1 \\\\\n --keycloak-url https://kc.us-east-1.mycorp.click \\\\\n register --config server-config.json\n\n # Register a server (using token file)\n uv run python registry_management.py \\\\\n --registry-url https://registry.us-east-1.mycorp.click \\\\\n --token-file /path/to/token.txt \\\\\n register --config server-config.json\n\n # List all servers\n uv run python registry_management.py list\n\n # Toggle server status\n uv run python registry_management.py toggle --path /cloudflare-docs\n\n # Add server to groups\n uv run python registry_management.py add-to-groups --server my-server --groups finance,analytics\n \"\"\",\n )\n\n parser.add_argument(\"--registry-url\", help=\"Registry base URL (overrides REGISTRY_URL env var)\")\n\n parser.add_argument(\"--aws-region\", help=\"AWS region (overrides AWS_REGION env var)\")\n\n parser.add_argument(\"--keycloak-url\", help=\"Keycloak base URL (overrides KEYCLOAK_URL env var)\")\n\n parser.add_argument(\n \"--token-file\", help=\"Path to file containing JWT token (bypasses token script)\"\n )\n\n parser.add_argument(\"--debug\", action=\"store_true\", help=\"Enable debug logging\")\n\n subparsers = parser.add_subparsers(dest=\"command\", help=\"Command to execute\")\n\n # Register command\n register_parser = subparsers.add_parser(\"register\", help=\"Register a new server\")\n register_parser.add_argument(\n \"--config\", required=True, help=\"Path to server configuration JSON file\"\n )\n register_parser.add_argument(\n \"--overwrite\", action=\"store_true\", help=\"Overwrite if server already exists\"\n )\n\n # List command\n list_parser = subparsers.add_parser(\"list\", help=\"List all servers\")\n list_parser.add_argument(\"--query\", help=\"Search query string\")\n list_parser.add_argument(\n \"--limit\", type=int, default=20, help=\"Number of servers to return (1-100, default 20)\"\n )\n list_parser.add_argument(\n \"--offset\", type=int, default=0, help=\"Number of servers to skip (default 0)\"\n )\n list_parser.add_argument(\"--json\", action=\"store_true\", help=\"Print raw JSON response\")\n\n # Toggle command\n toggle_parser = subparsers.add_parser(\"toggle\", help=\"Toggle server status\")\n toggle_parser.add_argument(\"--path\", required=True, help=\"Server path to toggle\")\n\n # Remove command\n remove_parser = subparsers.add_parser(\"remove\", help=\"Remove a server\")\n remove_parser.add_argument(\"--path\", required=True, help=\"Server path to remove\")\n remove_parser.add_argument(\"--force\", action=\"store_true\", help=\"Skip confirmation prompt\")\n\n # Healthcheck command\n healthcheck_parser = subparsers.add_parser(\"healthcheck\", help=\"Health check all servers\")\n\n # Config command\n config_parser = subparsers.add_parser(\n \"config\", help=\"Get registry configuration (deployment mode, features)\"\n )\n config_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Add to groups command\n add_groups_parser = subparsers.add_parser(\"add-to-groups\", help=\"Add server to groups\")\n add_groups_parser.add_argument(\"--server\", required=True, help=\"Server name\")\n add_groups_parser.add_argument(\"--groups\", required=True, help=\"Comma-separated group names\")\n\n # Remove from groups command\n remove_groups_parser = subparsers.add_parser(\n \"remove-from-groups\", help=\"Remove server from groups\"\n )\n remove_groups_parser.add_argument(\"--server\", required=True, help=\"Server name\")\n remove_groups_parser.add_argument(\"--groups\", required=True, help=\"Comma-separated group names\")\n\n # Create group command\n create_group_parser = subparsers.add_parser(\"create-group\", help=\"Create a new group\")\n create_group_parser.add_argument(\"--name\", required=True, help=\"Group name\")\n create_group_parser.add_argument(\"--description\", help=\"Group description\")\n create_group_parser.add_argument(\n \"--idp\", action=\"store_true\", help=\"Also create in IdP (Keycloak/Entra)\"\n )\n\n # Delete group command\n delete_group_parser = subparsers.add_parser(\"delete-group\", help=\"Delete a group\")\n delete_group_parser.add_argument(\"--name\", required=True, help=\"Group name\")\n delete_group_parser.add_argument(\n \"--idp\", action=\"store_true\", help=\"Also delete from IdP (Keycloak/Entra)\"\n )\n delete_group_parser.add_argument(\n \"--force\", action=\"store_true\", help=\"Force deletion of system groups and skip confirmation\"\n )\n\n # Import group command\n import_group_parser = subparsers.add_parser(\n \"import-group\", help=\"Import a complete group definition from JSON file\"\n )\n import_group_parser.add_argument(\n \"--file\", required=True, help=\"Path to JSON file containing group definition\"\n )\n\n # List groups command\n list_groups_parser = subparsers.add_parser(\"list-groups\", help=\"List all groups\")\n list_groups_parser.add_argument(\n \"--no-keycloak\", action=\"store_true\", help=\"Exclude Keycloak information\"\n )\n list_groups_parser.add_argument(\n \"--no-scopes\", action=\"store_true\", help=\"Exclude scope information\"\n )\n list_groups_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON response\")\n\n # Describe group command\n describe_group_parser = subparsers.add_parser(\n \"describe-group\", help=\"Show detailed information about a specific group\"\n )\n describe_group_parser.add_argument(\"--name\", required=True, help=\"Group name to describe\")\n describe_group_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON response\"\n )\n\n # Server get command\n server_get_parser = subparsers.add_parser(\"server-get\", help=\"Get details of a specific server\")\n server_get_parser.add_argument(\"--path\", required=True, help=\"Server path (e.g., /my-server)\")\n\n # Server rate command\n server_rate_parser = subparsers.add_parser(\"server-rate\", help=\"Rate a server (1-5 stars)\")\n server_rate_parser.add_argument(\n \"--path\", required=True, help=\"Server path (e.g., /cloudflare-docs)\"\n )\n server_rate_parser.add_argument(\n \"--rating\",\n required=True,\n type=int,\n choices=[1, 2, 3, 4, 5],\n help=\"Rating value (1-5 stars)\",\n )\n\n # Server rating command\n server_rating_parser = subparsers.add_parser(\n \"server-rating\", help=\"Get rating information for a server\"\n )\n server_rating_parser.add_argument(\n \"--path\", required=True, help=\"Server path (e.g., /cloudflare-docs)\"\n )\n\n # Server security scan command\n security_scan_parser = subparsers.add_parser(\n \"security-scan\", help=\"Get security scan results for a server\"\n )\n security_scan_parser.add_argument(\n \"--path\", required=True, help=\"Server path (e.g., /cloudflare-docs)\"\n )\n security_scan_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n # Server rescan command\n rescan_parser = subparsers.add_parser(\n \"rescan\", help=\"Trigger manual security scan for a server (admin only)\"\n )\n rescan_parser.add_argument(\"--path\", required=True, help=\"Server path (e.g., /cloudflare-docs)\")\n rescan_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n # Server credential update command\n server_update_cred_parser = subparsers.add_parser(\n \"server-update-credential\", help=\"Update authentication credentials for a server\"\n )\n server_update_cred_parser.add_argument(\n \"--path\", required=True, help=\"Server path (e.g., /cloudflare-api)\"\n )\n server_update_cred_parser.add_argument(\n \"--auth-scheme\",\n required=True,\n choices=[\"none\", \"bearer\", \"api_key\"],\n help=\"Authentication scheme\",\n )\n server_update_cred_parser.add_argument(\n \"--credential\", help=\"New credential value (required if auth-scheme is not 'none')\"\n )\n server_update_cred_parser.add_argument(\n \"--auth-header-name\", help=\"Custom header name (optional, for api_key scheme)\"\n )\n server_update_cred_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n # Server search command\n server_search_parser = subparsers.add_parser(\n \"server-search\",\n help=\"Semantic search across all entity types (servers, tools, agents, skills, virtual servers)\",\n )\n server_search_parser.add_argument(\n \"--query\", required=True, help=\"Natural language search query (e.g., 'coding assistants')\"\n )\n server_search_parser.add_argument(\n \"--max-results\",\n type=int,\n default=10,\n help=\"Maximum number of results per entity type (default: 10)\",\n )\n server_search_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON with all entity types\"\n )\n\n # Server Version Management Commands\n\n # List versions command\n list_versions_parser = subparsers.add_parser(\n \"list-versions\", help=\"List all versions for a server\"\n )\n list_versions_parser.add_argument(\"--path\", required=True, help=\"Server path (e.g., /context7)\")\n list_versions_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n # Remove version command\n remove_version_parser = subparsers.add_parser(\n \"remove-version\", help=\"Remove a version from a server\"\n )\n remove_version_parser.add_argument(\n \"--path\", required=True, help=\"Server path (e.g., /context7)\"\n )\n remove_version_parser.add_argument(\"--version\", required=True, help=\"Version to remove\")\n remove_version_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n # Set default version command\n set_default_version_parser = subparsers.add_parser(\n \"set-default-version\", help=\"Set the default version for a server\"\n )\n set_default_version_parser.add_argument(\n \"--path\", required=True, help=\"Server path (e.g., /context7)\"\n )\n set_default_version_parser.add_argument(\n \"--version\", required=True, help=\"Version to set as default\"\n )\n set_default_version_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n # Agent Management Commands\n\n # Agent register command\n agent_register_parser = subparsers.add_parser(\"agent-register\", help=\"Register a new A2A agent\")\n agent_register_parser.add_argument(\n \"--config\", required=True, help=\"Path to agent configuration JSON file\"\n )\n\n # Agent list command\n agent_list_parser = subparsers.add_parser(\"agent-list\", help=\"List all A2A agents\")\n agent_list_parser.add_argument(\"--query\", help=\"Search query string\")\n agent_list_parser.add_argument(\n \"--enabled-only\", action=\"store_true\", help=\"Show only enabled agents\"\n )\n agent_list_parser.add_argument(\n \"--visibility\",\n choices=[\"public\", \"private\", \"group-restricted\"],\n help=\"Filter by visibility level\",\n )\n agent_list_parser.add_argument(\n \"--limit\", type=int, default=20, help=\"Number of agents to return (1-100, default 20)\"\n )\n agent_list_parser.add_argument(\n \"--offset\", type=int, default=0, help=\"Number of agents to skip (default 0)\"\n )\n agent_list_parser.add_argument(\n \"--allowed-groups\",\n help=\"Filter by allowed_groups (comma-separated). Returns only group-restricted agents matching these groups.\",\n )\n agent_list_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON response\")\n\n # Agent get command\n agent_get_parser = subparsers.add_parser(\"agent-get\", help=\"Get agent details\")\n agent_get_parser.add_argument(\"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\")\n\n # Agent update command\n agent_update_parser = subparsers.add_parser(\"agent-update\", help=\"Update an existing agent\")\n agent_update_parser.add_argument(\"--path\", required=True, help=\"Agent path\")\n agent_update_parser.add_argument(\n \"--config\", required=True, help=\"Path to updated agent configuration JSON file\"\n )\n\n # Agent delete command\n agent_delete_parser = subparsers.add_parser(\"agent-delete\", help=\"Delete an agent\")\n agent_delete_parser.add_argument(\"--path\", required=True, help=\"Agent path\")\n agent_delete_parser.add_argument(\n \"--force\", action=\"store_true\", help=\"Skip confirmation prompt\"\n )\n\n # Agent toggle command\n agent_toggle_parser = subparsers.add_parser(\n \"agent-toggle\", help=\"Toggle agent enabled/disabled status\"\n )\n agent_toggle_parser.add_argument(\"--path\", required=True, help=\"Agent path\")\n agent_toggle_parser.add_argument(\n \"--enabled\",\n required=True,\n type=lambda x: x.lower() == \"true\",\n help=\"True to enable, false to disable\",\n )\n\n # Agent discover command\n agent_discover_parser = subparsers.add_parser(\n \"agent-discover\", help=\"Discover agents by skills\"\n )\n agent_discover_parser.add_argument(\n \"--skills\", required=True, help=\"Comma-separated list of required skills\"\n )\n agent_discover_parser.add_argument(\"--tags\", help=\"Comma-separated list of tag filters\")\n agent_discover_parser.add_argument(\n \"--max-results\", type=int, default=10, help=\"Maximum number of results (default: 10)\"\n )\n\n # Agent search command\n agent_search_parser = subparsers.add_parser(\"agent-search\", help=\"Semantic search for agents\")\n agent_search_parser.add_argument(\"--query\", required=True, help=\"Natural language search query\")\n agent_search_parser.add_argument(\n \"--max-results\", type=int, default=10, help=\"Maximum number of results (default: 10)\"\n )\n agent_search_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output results as JSON\")\n\n # Agent rate command\n agent_rate_parser = subparsers.add_parser(\"agent-rate\", help=\"Rate an agent (1-5 stars)\")\n agent_rate_parser.add_argument(\n \"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\"\n )\n agent_rate_parser.add_argument(\n \"--rating\",\n required=True,\n type=int,\n choices=[1, 2, 3, 4, 5],\n help=\"Rating value (1-5 stars)\",\n )\n\n # Agent rating command\n agent_rating_parser = subparsers.add_parser(\n \"agent-rating\", help=\"Get rating information for an agent\"\n )\n agent_rating_parser.add_argument(\n \"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\"\n )\n\n # Agent security scan command\n agent_security_scan_parser = subparsers.add_parser(\n \"agent-security-scan\", help=\"Get security scan results for an agent\"\n )\n agent_security_scan_parser.add_argument(\n \"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\"\n )\n\n # Agent rescan command\n agent_rescan_parser = subparsers.add_parser(\n \"agent-rescan\", help=\"Trigger manual security scan for an agent (admin only)\"\n )\n agent_rescan_parser.add_argument(\n \"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\"\n )\n agent_rescan_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n # Agent ANS (Agent Name Service) commands\n agent_ans_link_parser = subparsers.add_parser(\n \"agent-ans-link\", help=\"Link an ANS Agent ID to an agent\"\n )\n agent_ans_link_parser.add_argument(\n \"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\"\n )\n agent_ans_link_parser.add_argument(\n \"--ans-agent-id\",\n required=True,\n help=\"ANS Agent ID (e.g., ans://v1.example.com)\",\n )\n\n agent_ans_status_parser = subparsers.add_parser(\n \"agent-ans-status\", help=\"Get ANS verification status for an agent\"\n )\n agent_ans_status_parser.add_argument(\n \"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\"\n )\n agent_ans_status_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON\")\n\n agent_ans_unlink_parser = subparsers.add_parser(\n \"agent-ans-unlink\", help=\"Remove ANS link from an agent\"\n )\n agent_ans_unlink_parser.add_argument(\n \"--path\", required=True, help=\"Agent path (e.g., /code-reviewer)\"\n )\n\n # ==========================================\n # Agent Skills Commands\n # ==========================================\n\n # Skill register command\n skill_register_parser = subparsers.add_parser(\n \"skill-register\", help=\"Register a new Agent Skill\"\n )\n skill_register_parser.add_argument(\n \"--name\", required=True, help=\"Skill name (lowercase alphanumeric with hyphens)\"\n )\n skill_register_parser.add_argument(\"--url\", required=True, help=\"URL to SKILL.md file\")\n skill_register_parser.add_argument(\"--description\", help=\"Skill description\")\n skill_register_parser.add_argument(\"--version\", help=\"Skill version (e.g., 1.0.0)\")\n skill_register_parser.add_argument(\"--tags\", help=\"Comma-separated tags\")\n skill_register_parser.add_argument(\n \"--target-agents\",\n help=\"Comma-separated target coding assistants (e.g., claude-code,cursor)\",\n )\n skill_register_parser.add_argument(\n \"--metadata\",\n help='Custom metadata as JSON string (e.g., \\'{\"category\": \"data-processing\"}\\')',\n )\n skill_register_parser.add_argument(\n \"--visibility\",\n choices=[\"public\", \"private\", \"group\"],\n default=\"public\",\n help=\"Visibility level (default: public)\",\n )\n\n # Skill list command\n skill_list_parser = subparsers.add_parser(\"skill-list\", help=\"List all Agent Skills\")\n skill_list_parser.add_argument(\n \"--include-disabled\", action=\"store_true\", help=\"Include disabled skills\"\n )\n skill_list_parser.add_argument(\"--tag\", help=\"Filter by tag\")\n skill_list_parser.add_argument(\n \"--limit\", type=int, default=20, help=\"Number of skills to return (1-100, default 20)\"\n )\n skill_list_parser.add_argument(\n \"--offset\", type=int, default=0, help=\"Number of skills to skip (default 0)\"\n )\n skill_list_parser.add_argument(\"--json\", action=\"store_true\", help=\"Output raw JSON response\")\n\n # Skill get command\n skill_get_parser = subparsers.add_parser(\"skill-get\", help=\"Get skill details\")\n skill_get_parser.add_argument(\n \"--path\", required=True, help=\"Skill path or name (e.g., pdf-processing)\"\n )\n\n # Skill delete command\n skill_delete_parser = subparsers.add_parser(\"skill-delete\", help=\"Delete a skill\")\n skill_delete_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n\n # Skill toggle command\n skill_toggle_parser = subparsers.add_parser(\n \"skill-toggle\", help=\"Toggle skill enabled/disabled state\"\n )\n skill_toggle_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n skill_toggle_parser.add_argument(\n \"--enable\",\n type=lambda x: x.lower() == \"true\",\n required=True,\n help=\"Enable (true) or disable (false)\",\n )\n\n # Skill health command\n skill_health_parser = subparsers.add_parser(\n \"skill-health\", help=\"Check skill health (SKILL.md accessibility)\"\n )\n skill_health_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n\n # Skill content command\n skill_content_parser = subparsers.add_parser(\n \"skill-content\", help=\"Get SKILL.md content for a skill\"\n )\n skill_content_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n skill_content_parser.add_argument(\"--raw\", action=\"store_true\", help=\"Output raw content only\")\n\n # Skill search command\n skill_search_parser = subparsers.add_parser(\"skill-search\", help=\"Search for skills\")\n skill_search_parser.add_argument(\"--query\", required=True, help=\"Search query\")\n skill_search_parser.add_argument(\"--tags\", help=\"Comma-separated tags filter\")\n\n # Skill rate command\n skill_rate_parser = subparsers.add_parser(\"skill-rate\", help=\"Rate a skill (1-5 stars)\")\n skill_rate_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n skill_rate_parser.add_argument(\n \"--rating\", type=int, required=True, choices=[1, 2, 3, 4, 5], help=\"Rating (1-5 stars)\"\n )\n\n # Skill rating command\n skill_rating_parser = subparsers.add_parser(\n \"skill-rating\", help=\"Get rating information for a skill\"\n )\n skill_rating_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n\n # Skill security scan command\n skill_security_scan_parser = subparsers.add_parser(\n \"skill-security-scan\", help=\"Get security scan results for a skill\"\n )\n skill_security_scan_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n\n # Skill rescan command\n skill_rescan_parser = subparsers.add_parser(\n \"skill-rescan\", help=\"Trigger manual security scan for a skill (admin only)\"\n )\n skill_rescan_parser.add_argument(\"--path\", required=True, help=\"Skill path or name\")\n skill_rescan_parser.add_argument(\n \"--json\", dest=\"json_output\", action=\"store_true\", help=\"Output raw JSON only\"\n )\n\n # Anthropic Registry API Commands\n\n # Anthropic list servers command\n anthropic_list_parser = subparsers.add_parser(\n \"anthropic-list\", help=\"List all servers (Anthropic Registry API v0.1)\"\n )\n anthropic_list_parser.add_argument(\"--limit\", type=int, help=\"Maximum results per page\")\n anthropic_list_parser.add_argument(\n \"--raw\", action=\"store_true\", help=\"Output raw JSON response\"\n )\n\n # Anthropic list versions command\n anthropic_versions_parser = subparsers.add_parser(\n \"anthropic-versions\", help=\"List versions for a server (Anthropic Registry API v0.1)\"\n )\n anthropic_versions_parser.add_argument(\n \"--server-name\",\n required=True,\n help=\"Server name in reverse-DNS format (e.g., 'io.mcpgateway/example-server')\",\n )\n anthropic_versions_parser.add_argument(\n \"--raw\", action=\"store_true\", help=\"Output raw JSON response\"\n )\n\n # Anthropic get server command\n anthropic_get_parser = subparsers.add_parser(\n \"anthropic-get\", help=\"Get server details (Anthropic Registry API v0.1)\"\n )\n anthropic_get_parser.add_argument(\n \"--server-name\", required=True, help=\"Server name in reverse-DNS format\"\n )\n anthropic_get_parser.add_argument(\n \"--version\", default=\"latest\", help=\"Server version (default: latest)\"\n )\n anthropic_get_parser.add_argument(\"--raw\", action=\"store_true\", help=\"Output raw JSON response\")\n\n # User Management Commands (Management API)\n\n # List users command\n user_list_parser = subparsers.add_parser(\"user-list\", help=\"List Keycloak users\")\n user_list_parser.add_argument(\"--search\", help=\"Search string to filter users\")\n user_list_parser.add_argument(\n \"--limit\", type=int, default=500, help=\"Maximum number of results (default: 500)\"\n )\n\n # Create M2M account command\n user_m2m_parser = subparsers.add_parser(\"user-create-m2m\", help=\"Create M2M service account\")\n user_m2m_parser.add_argument(\"--name\", required=True, help=\"Service account name/client ID\")\n user_m2m_parser.add_argument(\n \"--groups\", required=True, help=\"Comma-separated list of group names\"\n )\n user_m2m_parser.add_argument(\"--description\", help=\"Account description\")\n\n # Create human user command\n user_human_parser = subparsers.add_parser(\"user-create-human\", help=\"Create human user account\")\n user_human_parser.add_argument(\"--username\", required=True, help=\"Username\")\n user_human_parser.add_argument(\"--email\", required=True, help=\"Email address\")\n user_human_parser.add_argument(\"--first-name\", required=True, help=\"First name\")\n user_human_parser.add_argument(\"--last-name\", required=True, help=\"Last name\")\n user_human_parser.add_argument(\n \"--groups\", required=True, help=\"Comma-separated list of group names\"\n )\n user_human_parser.add_argument(\"--password\", help=\"Initial password (optional)\")\n\n # Delete user command\n user_delete_parser = subparsers.add_parser(\"user-delete\", help=\"Delete a user\")\n user_delete_parser.add_argument(\"--username\", required=True, help=\"Username to delete\")\n user_delete_parser.add_argument(\"--force\", action=\"store_true\", help=\"Skip confirmation prompt\")\n\n # -------------------------------------------------------------------------\n # M2M direct registration commands (issue #851)\n # Write to idp_m2m_clients without IdP Admin API. Admin only for mutations.\n # -------------------------------------------------------------------------\n\n m2m_create_parser = subparsers.add_parser(\n \"m2m-client-create\",\n help=\"Register an M2M client directly (no IdP Admin API required)\",\n )\n m2m_create_parser.add_argument(\n \"--client-id\", required=True, help=\"IdP application client ID to register\"\n )\n m2m_create_parser.add_argument(\n \"--client-name\", required=True, help=\"Human-readable name for the client\"\n )\n m2m_create_parser.add_argument(\n \"--groups\",\n default=\"\",\n help=\"Comma-separated group names (empty string = no groups)\",\n )\n m2m_create_parser.add_argument(\"--description\", help=\"Optional description\")\n\n m2m_list_parser = subparsers.add_parser(\n \"m2m-client-list\", help=\"List registered M2M clients (paginated)\"\n )\n m2m_list_parser.add_argument(\"--provider\", help=\"Filter by provider (e.g. manual, okta, auth0)\")\n m2m_list_parser.add_argument(\n \"--limit\", type=int, default=500, help=\"Max records per page (1-1000, default 500)\"\n )\n m2m_list_parser.add_argument(\n \"--skip\", type=int, default=0, help=\"Offset for pagination (default 0)\"\n )\n m2m_list_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n m2m_get_parser = subparsers.add_parser(\n \"m2m-client-get\", help=\"Get a single M2M client by client_id\"\n )\n m2m_get_parser.add_argument(\"--client-id\", required=True, help=\"IdP client ID\")\n m2m_get_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n m2m_update_parser = subparsers.add_parser(\n \"m2m-client-update\",\n help=\"Partially update an M2M client (manual records only)\",\n )\n m2m_update_parser.add_argument(\"--client-id\", required=True, help=\"IdP client ID\")\n m2m_update_parser.add_argument(\n \"--client-name\", help=\"New client name (omit to leave unchanged)\"\n )\n m2m_update_parser.add_argument(\n \"--groups\",\n help=\"Comma-separated new groups list; empty string clears groups; omit to leave unchanged\",\n )\n m2m_update_parser.add_argument(\n \"--description\", help=\"New description (omit to leave unchanged)\"\n )\n m2m_update_parser.add_argument(\n \"--enabled\",\n choices=[\"true\", \"false\"],\n help=\"Set enabled flag (omit to leave unchanged)\",\n )\n\n m2m_delete_parser = subparsers.add_parser(\n \"m2m-client-delete\",\n help=\"Delete an M2M client (manual records only)\",\n )\n m2m_delete_parser.add_argument(\"--client-id\", required=True, help=\"IdP client ID\")\n m2m_delete_parser.add_argument(\"--force\", action=\"store_true\", help=\"Skip confirmation prompt\")\n\n # Create IAM group command\n group_create_parser = subparsers.add_parser(\"group-create\", help=\"Create a new IAM group\")\n group_create_parser.add_argument(\"--name\", required=True, help=\"Group name\")\n group_create_parser.add_argument(\"--description\", help=\"Group description\")\n\n # Delete IAM group command\n group_delete_parser = subparsers.add_parser(\"group-delete\", help=\"Delete an IAM group\")\n group_delete_parser.add_argument(\"--name\", required=True, help=\"Group name to delete\")\n group_delete_parser.add_argument(\n \"--force\", action=\"store_true\", help=\"Skip confirmation prompt\"\n )\n\n # List IAM groups command\n group_list_parser = subparsers.add_parser(\"group-list\", help=\"List IAM groups\")\n\n # Federation Management Commands\n\n # Get federation config command\n federation_get_parser = subparsers.add_parser(\n \"federation-get\", help=\"Get federation configuration\"\n )\n federation_get_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID (default: default)\"\n )\n federation_get_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Save federation config command\n federation_save_parser = subparsers.add_parser(\n \"federation-save\", help=\"Save federation configuration from JSON file\"\n )\n federation_save_parser.add_argument(\n \"--config\", required=True, help=\"Path to federation config JSON file\"\n )\n federation_save_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID (default: default)\"\n )\n\n # Delete federation config command\n federation_delete_parser = subparsers.add_parser(\n \"federation-delete\", help=\"Delete federation configuration\"\n )\n federation_delete_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID to delete (default: default)\"\n )\n federation_delete_parser.add_argument(\n \"--force\", action=\"store_true\", help=\"Skip confirmation prompt\"\n )\n\n # List federation configs command\n federation_list_parser = subparsers.add_parser(\n \"federation-list\", help=\"List all federation configurations\"\n )\n federation_list_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Add Anthropic server command\n federation_add_anthropic_parser = subparsers.add_parser(\n \"federation-add-anthropic-server\", help=\"Add Anthropic server to federation config\"\n )\n federation_add_anthropic_parser.add_argument(\n \"--server-name\",\n required=True,\n help=\"Anthropic server name (e.g., io.github.jgador/websharp)\",\n )\n federation_add_anthropic_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID (default: default)\"\n )\n\n # Remove Anthropic server command\n federation_remove_anthropic_parser = subparsers.add_parser(\n \"federation-remove-anthropic-server\", help=\"Remove Anthropic server from federation config\"\n )\n federation_remove_anthropic_parser.add_argument(\n \"--server-name\", required=True, help=\"Anthropic server name to remove\"\n )\n federation_remove_anthropic_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID (default: default)\"\n )\n\n # Add ASOR agent command\n federation_add_asor_parser = subparsers.add_parser(\n \"federation-add-asor-agent\", help=\"Add ASOR agent to federation config\"\n )\n federation_add_asor_parser.add_argument(\n \"--agent-id\", required=True, help=\"ASOR agent ID (e.g., aws_assistant)\"\n )\n federation_add_asor_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID (default: default)\"\n )\n\n # Remove ASOR agent command\n federation_remove_asor_parser = subparsers.add_parser(\n \"federation-remove-asor-agent\", help=\"Remove ASOR agent from federation config\"\n )\n federation_remove_asor_parser.add_argument(\n \"--agent-id\", required=True, help=\"ASOR agent ID to remove\"\n )\n federation_remove_asor_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID (default: default)\"\n )\n\n # Federation sync command\n federation_sync_parser = subparsers.add_parser(\n \"federation-sync\", help=\"Trigger manual federation sync to import servers/agents\"\n )\n federation_sync_parser.add_argument(\n \"--config-id\", default=\"default\", help=\"Configuration ID (default: default)\"\n )\n federation_sync_parser.add_argument(\n \"--source\",\n choices=[\"anthropic\", \"asor\", \"aws_registry\"],\n help=\"Optional source filter (anthropic, asor, or aws_registry). Syncs all enabled sources if not specified.\",\n )\n federation_sync_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # ==========================================\n # Peer Registry Management Commands\n # ==========================================\n\n # List peers command\n peer_list_parser = subparsers.add_parser(\n \"peer-list\", help=\"List all configured peer registries\"\n )\n peer_list_parser.add_argument(\n \"--enabled-only\", action=\"store_true\", help=\"Show only enabled peers\"\n )\n peer_list_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Add peer command\n peer_add_parser = subparsers.add_parser(\n \"peer-add\", help=\"Add a new peer registry from JSON config\"\n )\n peer_add_parser.add_argument(\n \"--config\", required=True, help=\"Path to peer configuration JSON file\"\n )\n peer_add_parser.add_argument(\n \"--federation-token\",\n required=False,\n help=\"Federation static token from the remote peer registry. \"\n \"Overrides federation_token in the JSON config file if both are provided.\",\n )\n\n # Get peer command\n peer_get_parser = subparsers.add_parser(\n \"peer-get\", help=\"Get details of a specific peer registry\"\n )\n peer_get_parser.add_argument(\"--peer-id\", required=True, help=\"Peer registry identifier\")\n peer_get_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Update peer command\n peer_update_parser = subparsers.add_parser(\n \"peer-update\", help=\"Update an existing peer registry\"\n )\n peer_update_parser.add_argument(\"--peer-id\", required=True, help=\"Peer registry identifier\")\n peer_update_parser.add_argument(\n \"--config\", required=True, help=\"Path to updated peer configuration JSON file\"\n )\n peer_update_parser.add_argument(\n \"--federation-token\",\n required=False,\n help=\"Federation static token from the remote peer registry. \"\n \"Overrides federation_token in the JSON config file if both are provided.\",\n )\n\n # Update peer token command\n peer_update_token_parser = subparsers.add_parser(\n \"peer-update-token\", help=\"Update only the federation token for a peer registry\"\n )\n peer_update_token_parser.add_argument(\n \"--peer-id\", required=True, help=\"Peer registry identifier\"\n )\n peer_update_token_parser.add_argument(\n \"--federation-token\",\n required=True,\n help=\"New federation static token from the remote peer registry. \"\n \"Use this to recover from token loss (issue #561) or rotate tokens.\",\n )\n\n # Remove peer command\n peer_remove_parser = subparsers.add_parser(\"peer-remove\", help=\"Remove a peer registry\")\n peer_remove_parser.add_argument(\"--peer-id\", required=True, help=\"Peer registry identifier\")\n peer_remove_parser.add_argument(\"--force\", action=\"store_true\", help=\"Skip confirmation prompt\")\n\n # Sync from specific peer command\n peer_sync_parser = subparsers.add_parser(\n \"peer-sync\", help=\"Trigger sync from a specific peer registry\"\n )\n peer_sync_parser.add_argument(\n \"--peer-id\", required=True, help=\"Peer registry identifier to sync from\"\n )\n peer_sync_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Sync from all peers command\n peer_sync_all_parser = subparsers.add_parser(\n \"peer-sync-all\", help=\"Trigger sync from all enabled peer registries\"\n )\n peer_sync_all_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Get peer sync status command\n peer_status_parser = subparsers.add_parser(\n \"peer-status\", help=\"Get sync status for a specific peer registry\"\n )\n peer_status_parser.add_argument(\"--peer-id\", required=True, help=\"Peer registry identifier\")\n peer_status_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Enable peer command\n peer_enable_parser = subparsers.add_parser(\"peer-enable\", help=\"Enable a peer registry\")\n peer_enable_parser.add_argument(\"--peer-id\", required=True, help=\"Peer registry identifier\")\n\n # Disable peer command\n peer_disable_parser = subparsers.add_parser(\"peer-disable\", help=\"Disable a peer registry\")\n peer_disable_parser.add_argument(\"--peer-id\", required=True, help=\"Peer registry identifier\")\n\n # Get peer connections command\n peer_connections_parser = subparsers.add_parser(\n \"peer-connections\", help=\"Get all federation connections across all peers\"\n )\n peer_connections_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Get shared resources command\n peer_shared_resources_parser = subparsers.add_parser(\n \"peer-shared-resources\", help=\"Get resource sharing summary across all peers\"\n )\n peer_shared_resources_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # ==========================================\n # Virtual MCP Server Commands\n # ==========================================\n\n # Create virtual server command\n vs_create_parser = subparsers.add_parser(\n \"vs-create\", help=\"Create a virtual MCP server from JSON config\"\n )\n vs_create_parser.add_argument(\n \"--config\", required=True, help=\"Path to virtual server configuration JSON file\"\n )\n\n # List virtual servers command\n vs_list_parser = subparsers.add_parser(\"vs-list\", help=\"List all virtual MCP servers\")\n vs_list_parser.add_argument(\n \"--enabled-only\", action=\"store_true\", help=\"Show only enabled virtual servers\"\n )\n vs_list_parser.add_argument(\"--tag\", help=\"Filter by tag\")\n vs_list_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Get virtual server command\n vs_get_parser = subparsers.add_parser(\"vs-get\", help=\"Get virtual MCP server details\")\n vs_get_parser.add_argument(\n \"--path\", required=True, help=\"Virtual server path (e.g., /virtual/dev-tools)\"\n )\n vs_get_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n # Update virtual server command\n vs_update_parser = subparsers.add_parser(\n \"vs-update\", help=\"Update a virtual MCP server from JSON config\"\n )\n vs_update_parser.add_argument(\"--path\", required=True, help=\"Virtual server path to update\")\n vs_update_parser.add_argument(\n \"--config\", required=True, help=\"Path to updated configuration JSON file\"\n )\n\n # Delete virtual server command\n vs_delete_parser = subparsers.add_parser(\"vs-delete\", help=\"Delete a virtual MCP server\")\n vs_delete_parser.add_argument(\"--path\", required=True, help=\"Virtual server path to delete\")\n vs_delete_parser.add_argument(\"--force\", action=\"store_true\", help=\"Skip confirmation prompt\")\n\n # Toggle virtual server command\n vs_toggle_parser = subparsers.add_parser(\n \"vs-toggle\", help=\"Enable or disable a virtual MCP server\"\n )\n vs_toggle_parser.add_argument(\"--path\", required=True, help=\"Virtual server path\")\n vs_toggle_parser.add_argument(\n \"--enabled\",\n required=True,\n choices=[\"true\", \"false\"],\n help=\"Enable (true) or disable (false)\",\n )\n\n # Rate virtual server command\n vs_rate_parser = subparsers.add_parser(\"vs-rate\", help=\"Rate a virtual MCP server (1-5 stars)\")\n vs_rate_parser.add_argument(\"--path\", required=True, help=\"Virtual server path\")\n vs_rate_parser.add_argument(\n \"--rating\", required=True, type=int, choices=[1, 2, 3, 4, 5], help=\"Rating (1-5 stars)\"\n )\n\n # Get virtual server rating command\n vs_rating_parser = subparsers.add_parser(\n \"vs-rating\", help=\"Get rating information for a virtual MCP server\"\n )\n vs_rating_parser.add_argument(\"--path\", required=True, help=\"Virtual server path\")\n\n # ==========================================\n # Registry Card Management Commands\n # ==========================================\n\n # Get registry card command\n registry_card_get_parser = subparsers.add_parser(\n \"registry-card-get\", help=\"Get the registry card\"\n )\n\n # Discover registry card via .well-known endpoint\n registry_card_discover_parser = subparsers.add_parser(\n \"registry-card-discover\", help=\"Discover registry card via .well-known endpoint\"\n )\n\n # Update registry card command\n registry_card_update_parser = subparsers.add_parser(\n \"registry-card-update\", help=\"Update the registry card\"\n )\n registry_card_update_parser.add_argument(\"--name\", help=\"Registry name\")\n registry_card_update_parser.add_argument(\"--description\", help=\"Registry description\")\n registry_card_update_parser.add_argument(\"--contact-email\", help=\"Contact email address\")\n registry_card_update_parser.add_argument(\"--contact-url\", help=\"Contact URL\")\n\n # Telemetry management commands\n subparsers.add_parser(\n \"telemetry-heartbeat\",\n help=\"Force an immediate heartbeat telemetry event (admin only)\",\n )\n subparsers.add_parser(\n \"telemetry-startup\",\n help=\"Force an immediate startup telemetry event (admin only)\",\n )\n\n # ==========================================\n # Application Log Commands (issue #886)\n # ==========================================\n\n logs_parser = subparsers.add_parser(\n \"logs\", help=\"Query application logs (admin only)\"\n )\n logs_parser.add_argument(\"--service\", help=\"Filter by service name\")\n logs_parser.add_argument(\n \"--level\",\n choices=[\"DEBUG\", \"INFO\", \"WARNING\", \"ERROR\", \"CRITICAL\"],\n help=\"Minimum log level\",\n )\n logs_parser.add_argument(\"--hostname\", help=\"Filter by hostname/pod\")\n logs_parser.add_argument(\"--search\", help=\"Substring search in messages\")\n logs_parser.add_argument(\"--start\", help=\"Start timestamp (ISO-8601)\")\n logs_parser.add_argument(\"--end\", help=\"End timestamp (ISO-8601)\")\n logs_parser.add_argument(\"--limit\", type=int, default=100, help=\"Page size (default: 100)\")\n logs_parser.add_argument(\"--offset\", type=int, default=0, help=\"Offset for pagination\")\n logs_parser.add_argument(\n \"--metadata\", action=\"store_true\", help=\"Show available filter values instead of logs\"\n )\n logs_parser.add_argument(\n \"--json\", action=\"store_true\", help=\"Output raw JSON instead of formatted text\"\n )\n\n args = parser.parse_args()\n\n # Enable debug logging if requested\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n # Dispatch to command handler\n if not args.command:\n parser.print_help()\n return 1\n\n command_handlers = {\n \"register\": cmd_register,\n \"list\": cmd_list,\n \"toggle\": cmd_toggle,\n \"remove\": cmd_remove,\n \"healthcheck\": cmd_healthcheck,\n \"config\": cmd_config,\n \"add-to-groups\": cmd_add_to_groups,\n \"remove-from-groups\": cmd_remove_from_groups,\n \"create-group\": cmd_create_group,\n \"delete-group\": cmd_delete_group,\n \"import-group\": cmd_import_group,\n \"list-groups\": cmd_list_groups,\n \"describe-group\": cmd_describe_group,\n \"server-get\": cmd_server_get,\n \"server-rate\": cmd_server_rate,\n \"server-rating\": cmd_server_rating,\n \"security-scan\": cmd_security_scan,\n \"rescan\": cmd_rescan,\n \"server-update-credential\": cmd_server_update_credential,\n \"server-search\": cmd_server_search,\n \"list-versions\": cmd_list_versions,\n \"remove-version\": cmd_remove_version,\n \"set-default-version\": cmd_set_default_version,\n \"agent-register\": cmd_agent_register,\n \"agent-list\": cmd_agent_list,\n \"agent-get\": cmd_agent_get,\n \"agent-update\": cmd_agent_update,\n \"agent-delete\": cmd_agent_delete,\n \"agent-toggle\": cmd_agent_toggle,\n \"agent-discover\": cmd_agent_discover,\n \"agent-search\": cmd_agent_search,\n \"agent-rate\": cmd_agent_rate,\n \"agent-rating\": cmd_agent_rating,\n \"agent-security-scan\": cmd_agent_security_scan,\n \"agent-rescan\": cmd_agent_rescan,\n \"agent-ans-link\": cmd_agent_ans_link,\n \"agent-ans-status\": cmd_agent_ans_status,\n \"agent-ans-unlink\": cmd_agent_ans_unlink,\n # Skill commands\n \"skill-register\": cmd_skill_register,\n \"skill-list\": cmd_skill_list,\n \"skill-get\": cmd_skill_get,\n \"skill-delete\": cmd_skill_delete,\n \"skill-toggle\": cmd_skill_toggle,\n \"skill-health\": cmd_skill_health,\n \"skill-content\": cmd_skill_content,\n \"skill-search\": cmd_skill_search,\n \"skill-rate\": cmd_skill_rate,\n \"skill-rating\": cmd_skill_rating,\n \"skill-security-scan\": cmd_skill_security_scan,\n \"skill-rescan\": cmd_skill_rescan,\n \"anthropic-list\": cmd_anthropic_list_servers,\n \"anthropic-versions\": cmd_anthropic_list_versions,\n \"anthropic-get\": cmd_anthropic_get_server,\n \"user-list\": cmd_user_list,\n \"user-create-m2m\": cmd_user_create_m2m,\n \"user-create-human\": cmd_user_create_human,\n \"user-delete\": cmd_user_delete,\n # Direct M2M client registration (issue #851)\n \"m2m-client-create\": cmd_m2m_client_create,\n \"m2m-client-list\": cmd_m2m_client_list,\n \"m2m-client-get\": cmd_m2m_client_get,\n \"m2m-client-update\": cmd_m2m_client_update,\n \"m2m-client-delete\": cmd_m2m_client_delete,\n \"group-create\": cmd_group_create,\n \"group-delete\": cmd_group_delete,\n \"group-list\": cmd_group_list,\n \"federation-get\": cmd_federation_get,\n \"federation-save\": cmd_federation_save,\n \"federation-delete\": cmd_federation_delete,\n \"federation-list\": cmd_federation_list,\n \"federation-add-anthropic-server\": cmd_federation_add_anthropic_server,\n \"federation-remove-anthropic-server\": cmd_federation_remove_anthropic_server,\n \"federation-add-asor-agent\": cmd_federation_add_asor_agent,\n \"federation-remove-asor-agent\": cmd_federation_remove_asor_agent,\n \"federation-sync\": cmd_federation_sync,\n \"peer-list\": cmd_peer_list,\n \"peer-add\": cmd_peer_add,\n \"peer-get\": cmd_peer_get,\n \"peer-update\": cmd_peer_update,\n \"peer-update-token\": cmd_peer_update_token,\n \"peer-remove\": cmd_peer_remove,\n \"peer-sync\": cmd_peer_sync,\n \"peer-sync-all\": cmd_peer_sync_all,\n \"peer-status\": cmd_peer_status,\n \"peer-enable\": cmd_peer_enable,\n \"peer-disable\": cmd_peer_disable,\n \"peer-connections\": cmd_peer_connections,\n \"peer-shared-resources\": cmd_peer_shared_resources,\n # Virtual server commands\n \"vs-create\": cmd_vs_create,\n \"vs-list\": cmd_vs_list,\n \"vs-get\": cmd_vs_get,\n \"vs-update\": cmd_vs_update,\n \"vs-delete\": cmd_vs_delete,\n \"vs-toggle\": cmd_vs_toggle,\n \"vs-rate\": cmd_vs_rate,\n \"vs-rating\": cmd_vs_rating,\n # Registry card commands\n \"registry-card-get\": cmd_registry_card_get,\n \"registry-card-discover\": cmd_registry_card_discover,\n \"registry-card-update\": cmd_registry_card_update,\n # Telemetry management commands\n \"telemetry-heartbeat\": cmd_telemetry_heartbeat,\n \"telemetry-startup\": cmd_telemetry_startup,\n \"logs\": cmd_logs,\n }\n\n handler = command_handlers.get(args.command)\n if not handler:\n logger.error(f\"Unknown command: {args.command}\")\n return 1\n\n return handler(args)\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "api/test-management-api-e2e.md", "content": "# Management API End-to-End Test Guide\n\n**Date:** 2025-12-12\n**Purpose:** Comprehensive end-to-end test of the Management API functionality\n**Location:** `api/test-management-api-e2e.sh`\n\n## Overview\n\nThis guide demonstrates the complete lifecycle of IAM and resource management using the Management API. The test script creates a group, users (both human and M2M), registers servers and agents, verifies the configuration, and then cleans up all resources.\n\n## Prerequisites\n\n### For Local Testing (Docker Compose)\n\n1. Ensure the registry and Keycloak services are running:\n ```bash\n docker-compose up -d\n ```\n\n2. Generate authentication tokens:\n ```bash\n cd credentials-provider\n ./generate_creds.sh\n cd ..\n ```\n\n3. Verify token file exists:\n ```bash\n ls -la .oauth-tokens/ingress.json\n ```\n\n**Note:** The script automatically validates that:\n- The token file exists and is readable\n- The token contains a valid `access_token` field\n- The token has not expired (checks JWT expiration time)\n\n### For Remote Testing (AWS Deployment)\n\nSet the required environment variables:\n\n```bash\nexport REGISTRY_URL=\"https://registry.us-east-1.aroraai.people.aws.dev\"\nexport AWS_REGION=\"us-east-1\"\nexport KEYCLOAK_URL=\"https://kc.us-east-1.aroraai.people.aws.dev\"\n```\n\n## Test Workflow\n\nThe script performs the following operations in sequence:\n\n### Phase 1: Resource Creation\n\n1. **Create IAM Group**\n - Creates a new group with a timestamped name (e.g., `test-team-1702405678`)\n - Description: \"Test group for end-to-end testing\"\n - Command: `group-create --name --description `\n\n2. **Create Human User**\n - Creates a human user account with:\n - Username: `test.user.`\n - Email: `test.user.@example.com`\n - First name: \"Test\"\n - Last name: \"User\"\n - Group membership: The newly created group\n - Password: \"TempPassword123!\"\n - Command: `user-create-human --username --email --first-name --last-name --groups --password `\n\n3. **Create M2M Service Account**\n - Creates a machine-to-machine service account with:\n - Name: `test-service-bot-`\n - Group membership: The newly created group\n - Description: \"Test service account for end-to-end testing\"\n - Returns client credentials (client_id and client_secret)\n - Command: `user-create-m2m --name --groups --description `\n - **Important:** The client secret is only shown once - save it!\n\n4. **Register MCP Server**\n - Registers the Cloudflare Documentation MCP Server\n - Uses JSON configuration from `cli/examples/cloudflare-docs-server-config.json`\n - Server details:\n - Name: \"Cloudflare Documentation MCP Server\"\n - Path: `/cloudflare-docs`\n - Proxy URL: `https://docs.mcp.cloudflare.com/mcp`\n - Transport: streamable-http\n - Command: `register --config `\n\n5. **Register Agent**\n - Registers the Flight Booking Agent\n - Uses JSON configuration from `cli/examples/flight_booking_agent_card.json`\n - Agent details:\n - Name: \"Flight Booking Agent\"\n - Path: `/flight-booking`\n - URL: `http://flight-booking-agent:9000/`\n - Skills: check_availability, reserve_flight, confirm_booking, process_payment, manage_reservation\n - Command: `agent-register --config `\n\n### Phase 2: Verification\n\n6. **List All Users**\n - Lists all users in the system\n - **Validates** that both the human user and M2M service account are present in the response\n - Shows user status (enabled/disabled), email, groups\n - Command: `user-list`\n - Test fails if created users are not found in the list\n\n7. **List All Groups**\n - Lists all groups in the system\n - **Validates** that the test group appears in the response\n - Shows group ID, name, path, and attributes\n - Command: `group-list`\n - Test fails if created group is not found in the list\n\n8. **List All Servers**\n - Lists all registered servers\n - **Validates** that the Cloudflare Documentation MCP Server appears in the response\n - Shows server configuration and group assignment\n - Command: `list`\n - Test fails if registered server is not found in the list\n\n9. **List All Agents**\n - Lists all registered agents\n - **Validates** that the Flight Booking Agent appears in the response\n - Shows agent capabilities and group assignment\n - Command: `agent-list`\n - Test fails if registered agent is not found in the list\n\n10. **Search for Test Users**\n - Searches for users with \"test\" in their username\n - Demonstrates user search functionality\n - Command: `user-list --search test --limit 50`\n\n### Phase 3: Cleanup (Automatic)\n\nThe cleanup phase runs automatically via a trap on script exit, ensuring all resources are deleted even if the script fails:\n\n11. **Delete Agent**\n - Removes the Flight Booking Agent\n - Command: `agent-delete --path /flight-booking --force`\n\n12. **Delete Server**\n - Removes the Cloudflare Documentation MCP Server\n - Command: `remove --path /cloudflare-docs --force`\n\n13. **Delete M2M Account**\n - Removes the M2M service account\n - Command: `user-delete --username --force`\n\n14. **Delete Human User**\n - Removes the human user account\n - Command: `user-delete --username --force`\n\n15. **Delete Group**\n - Removes the test group\n - Command: `group-delete --name --force`\n\n## Usage\n\nThe script requires the `--token-file` parameter and optionally accepts `--registry-url`, `--aws-region`, `--keycloak-url`, and `--quiet`.\n\n### Command Syntax\n\n```bash\n./test-management-api-e2e.sh --token-file [--registry-url ] [--aws-region ] [--keycloak-url ] [--quiet]\n```\n\n**Required Arguments:**\n- `--token-file ` - Path to the OAuth token file (e.g., `.oauth-tokens/ingress.json`)\n\n**Optional Arguments:**\n- `--registry-url ` - Registry URL (default: `http://localhost`)\n- `--aws-region ` - AWS region (e.g., `us-east-1`)\n- `--keycloak-url ` - Keycloak base URL (e.g., `https://kc.us-east-1.aroraai.people.aws.dev`)\n- `--quiet` - Suppress verbose output (verbose mode is enabled by default to show all intermediate command outputs)\n\n### Local Testing (Docker Compose)\n\n```bash\n# First, ensure tokens are generated\ncd credentials-provider\n./generate_creds.sh\ncd ..\n\n# Run the test script with token file (verbose by default)\ncd api\n./test-management-api-e2e.sh --token-file ../.oauth-tokens/ingress.json\n\n# Or run in quiet mode\n./test-management-api-e2e.sh --token-file ../.oauth-tokens/ingress.json --quiet\n```\n\n### Remote Testing (AWS Deployment)\n\n```bash\n# Generate M2M token and save to file\n./api/get-m2m-token.sh \\\n --aws-region us-east-1 \\\n --keycloak-url https://kc.us-east-1.aroraai.people.aws.dev \\\n --output-file api/.token\n\n# Run the test script with all AWS parameters (verbose by default)\ncd api\n./test-management-api-e2e.sh \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.aroraai.people.aws.dev \\\n --aws-region us-east-1 \\\n --keycloak-url https://kc.us-east-1.aroraai.people.aws.dev\n\n# Or run in quiet mode\n./test-management-api-e2e.sh \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.aroraai.people.aws.dev \\\n --aws-region us-east-1 \\\n --keycloak-url https://kc.us-east-1.aroraai.people.aws.dev \\\n --quiet\n```\n\n### Getting Help\n\n```bash\n./test-management-api-e2e.sh --help\n```\n\nOutput:\n```\nUsage: ./test-management-api-e2e.sh --token-file [--registry-url ] [--aws-region ] [--keycloak-url ] [--quiet]\n\nRequired arguments:\n --token-file Path to the OAuth token file (e.g., .oauth-tokens/ingress.json)\n\nOptional arguments:\n --registry-url Registry URL (default: http://localhost)\n --aws-region AWS region (e.g., us-east-1)\n --keycloak-url Keycloak base URL (e.g., https://kc.us-east-1.aroraai.people.aws.dev)\n --quiet Suppress verbose output (verbose is enabled by default)\n\nExamples:\n # Local testing with verbose output (default)\n ./test-management-api-e2e.sh --token-file .oauth-tokens/ingress.json\n\n # Remote testing with all parameters\n ./test-management-api-e2e.sh --token-file api/.token --registry-url https://registry.us-east-1.aroraai.people.aws.dev --aws-region us-east-1 --keycloak-url https://kc.us-east-1.aroraai.people.aws.dev\n```\n\n## Expected Output\n\n### Successful Run\n\n```\n========================================\nManagement API End-to-End Test\n========================================\n\nConfiguration:\n Registry URL: http://localhost\n Token File: ../.oauth-tokens/ingress.json\n Group Name: test-team-1702405678\n Human User: test.user.1702405678\n M2M Account: test-service-bot-1702405678\n\n========================================\nPhase 1: Resource Creation\n========================================\n\n[Step 1] Creating IAM group: test-team-1702405678\nGroup created successfully\n\n[Step 2] Creating human user: test.user.1702405678\nHuman user created successfully\n\n[Step 3] Creating M2M service account: test-service-bot-1702405678\nClient ID: test-service-bot-1702405678\nClient Secret: \nGroups: test-team-1702405678\nM2M service account created successfully\nNote: Save the client secret from the output above - it will not be shown again!\n\n[Step 4] Registering server: Cloudflare Documentation MCP Server\nServer registered successfully\n\n[Step 5] Registering agent: Flight Booking Agent\nAgent registered successfully\n\n========================================\nPhase 2: Verification\n========================================\n\n[Step 6] Listing all users (should include test.user.1702405678 and test-service-bot-1702405678)\nFound 8 users:\n...\n\n[Step 7] Listing all groups (should include test-team-1702405678)\nFound 13 groups:\n...\n\n[Step 8] Listing all servers (should include Cloudflare Documentation MCP Server)\nServers:\n...\n\n[Step 9] Listing all agents (should include Flight Booking Agent)\nAgents:\n...\n\n[Step 10] Checking server health for: /cloudflare-docs\n...\n\n[Step 11] Searching for test users\nFound 2 users matching 'test':\n...\n\n========================================\nAll verification steps completed!\n========================================\n\nThe cleanup function will now run automatically...\n\n========================================\nCleanup: Deleting resources\n========================================\n\n[Step 12] Deleting agent: Flight Booking Agent\n[Step 13] Deleting server: Cloudflare Documentation MCP Server\n[Step 14] Deleting M2M account: test-service-bot-1702405678\n[Step 15] Deleting human user: test.user.1702405678\n[Step 16] Deleting group: test-team-1702405678\n\n========================================\nCleanup complete!\n========================================\n```\n\n## Troubleshooting\n\n### Error: Missing --token-file argument\n\n**Problem:**\n```\nError: --token-file is required\n\nUsage: ./test-management-api-e2e.sh --token-file [--registry-url ]\n```\n\n**Solution:** Provide the required `--token-file` parameter:\n```bash\n./test-management-api-e2e.sh --token-file ../.oauth-tokens/ingress.json\n```\n\n### Error: Token file not found\n\n**Problem:**\n```\nError: Token file not found: .oauth-tokens/ingress.json\n\nTo generate tokens for local testing:\n cd credentials-provider && ./generate_creds.sh && cd ..\n```\n\n**Solution:** Generate tokens first:\n```bash\ncd credentials-provider\n./generate_creds.sh\ncd ..\n```\n\n### Error: 403 Forbidden (Unauthorized)\n\n**Problem:** The user executing the script does not have admin privileges.\n\n**Solution:** Ensure the token used belongs to an admin user. For local testing, the `ingress.json` token should have admin rights. For remote testing, ensure you're using proper credentials.\n\n### Error: 422 Unprocessable Entity\n\n**Problem:** Invalid input data in the request.\n\n**Solution:** Check that:\n- Group names are valid (alphanumeric with hyphens/underscores)\n- Email addresses are properly formatted\n- All required fields are provided\n\n### Error: Server or Agent Registration Failed\n\n**Problem:** JSON configuration file is missing or invalid.\n\n**Solution:** Ensure the JSON files exist:\n```bash\nls -la cli/examples/cloudflare-docs-server-config.json\nls -la cli/examples/flight_booking_agent_card.json\n```\n\nIf missing, the script will attempt to create them automatically.\n\n### Warning: Health Check Failed\n\n**Problem:** Server health check returns an error.\n\n**Solution:** This is expected if the actual server is not running. The health check is included to demonstrate the functionality, but the script will continue even if it fails.\n\n### Cleanup Failures\n\n**Problem:** Cleanup phase reports errors when deleting resources.\n\n**Solution:** This can happen if:\n- Resources were manually deleted during the test\n- Network connectivity issues\n- Permission issues\n\nYou can manually clean up remaining resources:\n```bash\n# List and delete remaining resources\nuv run python registry_management.py --registry-url http://localhost --token-file ../.oauth-tokens/ingress.json user-list\nuv run python registry_management.py --registry-url http://localhost --token-file ../.oauth-tokens/ingress.json group-list\nuv run python registry_management.py --registry-url http://localhost --token-file ../.oauth-tokens/ingress.json list\nuv run python registry_management.py --registry-url http://localhost --token-file ../.oauth-tokens/ingress.json agent-list\n\n# Delete manually if needed\nuv run python registry_management.py --registry-url http://localhost --token-file ../.oauth-tokens/ingress.json user-delete --username --force\nuv run python registry_management.py --registry-url http://localhost --token-file ../.oauth-tokens/ingress.json group-delete --name --force\n```\n\n## API Endpoints Used\n\nThis test script exercises the following Management API endpoints:\n\n### User Management\n- `POST /api/management/iam/users/human` - Create human user\n- `POST /api/management/iam/users/m2m` - Create M2M service account\n- `GET /api/management/iam/users` - List users\n- `DELETE /api/management/iam/users/{username}` - Delete user\n\n### Group Management\n- `POST /api/management/iam/groups` - Create group\n- `GET /api/management/iam/groups` - List groups\n- `DELETE /api/management/iam/groups/{group_name}` - Delete group\n\n### Server Management\n- `POST /api/servers/register` - Register server\n- `GET /api/servers` - List servers\n- `GET /api/servers/health` - Check server health\n- `DELETE /api/servers/{path}` - Remove server\n\n### Agent Management\n- `POST /api/agents/register` - Register agent\n- `GET /api/agents` - List agents\n- `DELETE /api/agents/{path}` - Delete agent\n\n## Integration with CI/CD\n\nThis script can be integrated into CI/CD pipelines for automated testing:\n\n```yaml\n# Example GitHub Actions workflow\ntest-management-api:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n - name: Start services\n run: docker-compose up -d\n - name: Generate tokens\n run: |\n cd credentials-provider\n ./generate_creds.sh\n cd ..\n - name: Run end-to-end test\n run: |\n cd api\n ./test-management-api-e2e.sh --token-file ../.oauth-tokens/ingress.json\n```\n\n## Notes\n\n- **Timestamped Names:** All resource names include timestamps to avoid conflicts with existing resources\n- **Automatic Cleanup:** The script uses a bash trap to ensure cleanup runs even if the script fails\n- **Idempotent:** The script can be run multiple times safely due to unique timestamped names\n- **Admin Only:** All Management API operations require admin privileges\n- **Client Secrets:** M2M client secrets are only shown once during creation - save them immediately\n- **Resource Dependencies:** The cleanup happens in reverse order to respect dependencies (agents/servers before users, users before groups)\n\n## Related Documentation\n\n- [PR #267 Implementation Summary](.scratchpad/pr267-implementation-summary.md)\n- [Management API Complete Testing](.scratchpad/management-api-complete-testing.md)\n- [Group CRUD Implementation](.scratchpad/group-crud-implementation-summary.md)\n- [Management API OpenAPI Specification](../docs/api-specs/management-api.yaml)\n- [Registry Management CLI Tool](./registry_management.py)\n\n## Next Steps\n\nAfter running this test successfully:\n\n1. **Test on AWS Deployment:** Run the script against the remote registry to verify production readiness\n2. **Verify Keycloak:** Check Keycloak admin console to confirm users and groups were created correctly\n3. **Test Authentication:** Use the M2M credentials to authenticate and access protected resources\n4. **Performance Testing:** Run the script multiple times in parallel to test concurrency\n5. **Security Testing:** Verify non-admin users cannot execute Management API operations\n" }, { "path": "api/test-management-api-e2e.sh", "content": "#!/bin/bash\n\n# Continue on error - we want to run all tests and report results at the end\n# set -e # Disabled to allow test suite to continue after failures\n\n# Color codes for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\n# Usage function\nusage() {\n echo \"Usage: $0 --token-file [--registry-url ] [--aws-region ] [--keycloak-url ] [--quiet]\"\n echo \"\"\n echo \"Required arguments:\"\n echo \" --token-file Path to the OAuth token file (e.g., .oauth-tokens/ingress.json)\"\n echo \"\"\n echo \"Optional arguments:\"\n echo \" --registry-url Registry URL (default: http://localhost)\"\n echo \" --aws-region AWS region (e.g., us-east-1)\"\n echo \" --keycloak-url Keycloak base URL (e.g., https://kc.your-domain.example.com)\"\n echo \" --quiet Suppress verbose output (verbose is enabled by default)\"\n echo \"\"\n echo \"Examples:\"\n echo \" # Local testing with verbose output (default)\"\n echo \" $0 --token-file .oauth-tokens/ingress.json\"\n echo \"\"\n echo \" # Remote testing with all parameters\"\n echo \" $0 --token-file api/.token --registry-url https://registry.your-domain.example.com --aws-region us-east-1 --keycloak-url https://kc.your-domain.example.com\"\n exit 1\n}\n\n# Parse command line arguments\nTOKEN_FILE=\"\"\nREGISTRY_URL=\"http://localhost\"\nAWS_REGION=\"\"\nKEYCLOAK_URL=\"\"\nVERBOSE=true # Verbose by default\n\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --token-file)\n TOKEN_FILE=\"$2\"\n shift 2\n ;;\n --registry-url)\n REGISTRY_URL=\"$2\"\n shift 2\n ;;\n --aws-region)\n AWS_REGION=\"$2\"\n shift 2\n ;;\n --keycloak-url)\n KEYCLOAK_URL=\"$2\"\n shift 2\n ;;\n --quiet)\n VERBOSE=false\n shift\n ;;\n -h|--help)\n usage\n ;;\n *)\n echo \"Error: Unknown argument $1\"\n usage\n ;;\n esac\ndone\n\n# Validate required arguments\nif [ -z \"$TOKEN_FILE\" ]; then\n echo -e \"${RED}Error: --token-file is required${NC}\"\n echo \"\"\n usage\nfi\n\n# Validate token file exists\nif [ ! -f \"$TOKEN_FILE\" ]; then\n echo -e \"${RED}Error: Token file not found: $TOKEN_FILE${NC}\"\n echo \"\"\n echo \"To generate tokens for local testing:\"\n echo \" cd credentials-provider && ./generate_creds.sh && cd ..\"\n exit 1\nfi\n\n# Configuration\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nPARENT_DIR=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Validate token is not expired\necho \"Validating token...\"\nTOKEN_CONTENT=$(cat \"$TOKEN_FILE\")\n\n# Detect token format and extract access_token\n# Format 1: JSON with access_token field (from generate_creds.sh)\n# Format 2: Raw JWT token (from get-m2m-token.sh)\n# Format 3: JSON with nested tokens.access_token field (from UI sidebar token generation)\n# Format 4: Plain text token (e.g., network-trusted placeholder)\nif echo \"$TOKEN_CONTENT\" | grep -q \"^eyJ\"; then\n # Format 2: Raw JWT token (starts with eyJ which is base64 for '{\"')\n ACCESS_TOKEN=\"$TOKEN_CONTENT\"\nelif echo \"$TOKEN_CONTENT\" | grep -q \"^{\"; then\n # JSON format - try to extract access_token\n if command -v jq &> /dev/null; then\n ACCESS_TOKEN=$(echo \"$TOKEN_CONTENT\" | jq -r '.access_token // .tokens.access_token // empty')\n else\n ACCESS_TOKEN=$(echo \"$TOKEN_CONTENT\" | grep -o '\"access_token\":\"[^\"]*\"' | head -1 | sed 's/\"access_token\":\"\\([^\"]*\\)\"/\\1/')\n fi\nelse\n # Format 4: Plain text token (use file content verbatim)\n ACCESS_TOKEN=$(echo \"$TOKEN_CONTENT\" | tr -d '[:space:]')\nfi\n\nif [ -z \"$ACCESS_TOKEN\" ]; then\n echo -e \"${RED}Error: Could not extract access_token from token file${NC}\"\n echo \"Token file may be corrupted or in wrong format\"\n echo \"\"\n echo \"Supported formats:\"\n echo \" 1. JSON format: {\\\"access_token\\\": \\\"...\\\"}\"\n echo \" 2. Raw JWT token: eyJ...\"\n echo \" 3. Nested JSON: {\\\"tokens\\\": {\\\"access_token\\\": \\\"...\\\"}}\"\n echo \" 4. Plain text token (used as-is)\"\n echo \"\"\n echo \"To regenerate tokens:\"\n echo \" cd credentials-provider && ./generate_creds.sh && cd ..\"\n exit 1\nfi\n\n# Decode JWT to check expiration (JWT format: header.payload.signature)\n# Skip expiration check for non-JWT tokens (plain text placeholders)\nif ! echo \"$ACCESS_TOKEN\" | grep -q \"^eyJ\"; then\n echo -e \"${YELLOW}Token is not a JWT - skipping expiration check (plain text token)${NC}\"\n echo \"\"\nelse\n# Extract payload (second part)\nPAYLOAD=$(echo \"$ACCESS_TOKEN\" | cut -d. -f2)\n\n# Add padding if needed for base64 decoding\ncase $((${#PAYLOAD} % 4)) in\n 2) PAYLOAD=\"${PAYLOAD}==\" ;;\n 3) PAYLOAD=\"${PAYLOAD}=\" ;;\nesac\n\n# Decode payload\nif command -v base64 &> /dev/null; then\n DECODED_PAYLOAD=$(echo \"$PAYLOAD\" | base64 -d 2>/dev/null || echo \"{}\")\n\n # Extract exp field\n if command -v jq &> /dev/null; then\n EXP=$(echo \"$DECODED_PAYLOAD\" | jq -r '.exp // empty')\n else\n EXP=$(echo \"$DECODED_PAYLOAD\" | grep -o '\"exp\":[0-9]*' | sed 's/\"exp\"://')\n fi\n\n if [ -n \"$EXP\" ]; then\n CURRENT_TIME=$(date +%s)\n if [ \"$EXP\" -lt \"$CURRENT_TIME\" ]; then\n echo -e \"${RED}Error: Token has expired${NC}\"\n echo \"Token expired at: $(date -d @$EXP 2>/dev/null || date -r $EXP 2>/dev/null)\"\n echo \"Current time: $(date)\"\n echo \"\"\n echo \"To regenerate tokens:\"\n echo \" cd credentials-provider && ./generate_creds.sh && cd ..\"\n exit 1\n else\n TIME_LEFT=$((EXP - CURRENT_TIME))\n MINUTES_LEFT=$((TIME_LEFT / 60))\n echo -e \"${GREEN}Token is valid (expires in $MINUTES_LEFT minutes)${NC}\"\n fi\n else\n echo -e \"${YELLOW}Warning: Could not verify token expiration${NC}\"\n fi\nelse\n echo -e \"${YELLOW}Warning: base64 command not found, skipping token expiration check${NC}\"\nfi\nfi # end of JWT expiration check (non-JWT tokens skip this block)\necho \"\"\n\n# Test data with timestamp for uniqueness\nTIMESTAMP=\"$(date +%s)\"\nGROUP_NAME=\"test-team-${TIMESTAMP}\"\nHUMAN_USERNAME=\"test.user.${TIMESTAMP}\"\nHUMAN_EMAIL=\"${HUMAN_USERNAME}@example.com\"\nM2M_NAME=\"test-service-bot-${TIMESTAMP}\"\nSERVER_NAME=\"Cloudflare Documentation MCP Server\"\nAGENT_NAME=\"Flight Booking Agent\"\n\n# Generate random password for human user\nHUMAN_USER_PASSWORD=\"$(openssl rand -base64 16 | tr -d '/+=' | head -c 20)Aa1!\"\n\n# Unique paths with timestamp\nSERVER_PATH=\"/cloudflare-docs-${TIMESTAMP}\"\nAGENT_PATH=\"/flight-booking-${TIMESTAMP}\"\n\n# Temporary files for JSON payloads\nSERVER_JSON_FILE=\"${SCRIPT_DIR}/cloudflare-docs-server-config-${TIMESTAMP}.json\"\nAGENT_JSON_FILE=\"${SCRIPT_DIR}/flight_booking_agent_card-${TIMESTAMP}.json\"\n\n# Variables to store created resource info\nM2M_CLIENT_ID=\"\"\nM2M_CLIENT_SECRET=\"\"\n\n# Arrays to track test results\ndeclare -a TEST_NAMES\ndeclare -a TEST_RESULTS\nTEST_COUNT=0\n\n# Function to record test result\nrecord_result() {\n local test_name=\"$1\"\n local result=\"$2\" # PASS or FAIL\n TEST_NAMES[$TEST_COUNT]=\"$test_name\"\n TEST_RESULTS[$TEST_COUNT]=\"$result\"\n TEST_COUNT=$((TEST_COUNT + 1))\n}\n\necho -e \"${BLUE}========================================${NC}\"\necho -e \"${BLUE}Management API End-to-End Test${NC}\"\necho -e \"${BLUE}========================================${NC}\"\necho \"\"\necho -e \"${YELLOW}Configuration:${NC}\"\necho \" Registry URL: ${REGISTRY_URL}\"\necho \" Token File: ${TOKEN_FILE}\"\n[ -n \"$AWS_REGION\" ] && echo \" AWS Region: ${AWS_REGION}\"\n[ -n \"$KEYCLOAK_URL\" ] && echo \" Keycloak URL: ${KEYCLOAK_URL}\"\necho \" Group Name: ${GROUP_NAME}\"\necho \" Human User: ${HUMAN_USERNAME}\"\necho \" M2M Account: ${M2M_NAME}\"\necho \"\"\n\n# Set up management command\nMGMT_CMD=\"uv run python ${SCRIPT_DIR}/registry_management.py --debug --registry-url ${REGISTRY_URL} --token-file ${TOKEN_FILE}\"\n[ -n \"$AWS_REGION\" ] && MGMT_CMD=\"$MGMT_CMD --aws-region ${AWS_REGION}\"\n[ -n \"$KEYCLOAK_URL\" ] && MGMT_CMD=\"$MGMT_CMD --keycloak-url ${KEYCLOAK_URL}\"\n\n# Function to cleanup on exit\ncleanup() {\n # Display test results summary first (before cleanup)\n if [ $TEST_COUNT -gt 0 ]; then\n echo \"\"\n echo -e \"${BLUE}========================================${NC}\"\n echo -e \"${BLUE}Test Results Summary${NC}\"\n echo -e \"${BLUE}========================================${NC}\"\n echo \"\"\n\n # Print table header\n printf \"%-40s | %-10s\\n\" \"Test Name\" \"Result\"\n printf \"%-40s-+-%-10s\\n\" \"----------------------------------------\" \"----------\"\n\n # Calculate pass/fail counts\n PASS_COUNT=0\n FAIL_COUNT=0\n SKIP_COUNT=0\n\n # Print each result\n for ((i=0; i /dev/null 2>&1\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n echo -e \"${GREEN}Group created successfully${NC}\"\n record_result \"Create IAM Group\" \"PASS\"\n\n # Wait for group to be available in Keycloak\n echo -e \"${YELLOW}Waiting for group to be available in Keycloak...${NC}\"\n GROUP_AVAILABLE=false\n for i in {1..10}; do\n # Use a simple command without --debug to avoid confusion\n # Store output and check separately to avoid set -e issues\n GROUP_LIST_OUTPUT=$(uv run python ${SCRIPT_DIR}/registry_management.py --registry-url ${REGISTRY_URL} --token-file ${TOKEN_FILE} group-list 2>/dev/null || true)\n if echo \"${GROUP_LIST_OUTPUT}\" | grep -q \"${GROUP_NAME}\"; then\n echo -e \"${GREEN}Group is now available${NC}\"\n GROUP_AVAILABLE=true\n break\n else\n echo -e \"${YELLOW}Group not yet available, waiting 10 seconds (attempt $i/10)...${NC}\"\n sleep 10\n fi\n done\n\n if [ \"$GROUP_AVAILABLE\" = false ]; then\n echo -e \"${RED}Group did not become available after 100 seconds${NC}\"\n echo -e \"${YELLOW}Continuing with remaining tests...${NC}\"\n fi\nelse\n echo -e \"${RED}Group creation failed${NC}\"\n record_result \"Create IAM Group\" \"FAIL\"\nfi\necho \"\"\n\n# Step 2: Create human user\necho -e \"${BLUE}[Step 2] Creating human user: ${HUMAN_USERNAME}${NC}\"\nif [ \"$VERBOSE\" = true ]; then\n ${MGMT_CMD} user-create-human \\\n --username \"${HUMAN_USERNAME}\" \\\n --email \"${HUMAN_EMAIL}\" \\\n --first-name \"Test\" \\\n --last-name \"User\" \\\n --groups \"${GROUP_NAME}\" \\\n --password \"${HUMAN_USER_PASSWORD}\"\n CREATE_STATUS=$?\nelse\n ${MGMT_CMD} user-create-human \\\n --username \"${HUMAN_USERNAME}\" \\\n --email \"${HUMAN_EMAIL}\" \\\n --first-name \"Test\" \\\n --last-name \"User\" \\\n --groups \"${GROUP_NAME}\" \\\n --password \"${HUMAN_USER_PASSWORD}\" > /dev/null 2>&1\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n echo -e \"${GREEN}Human user created successfully${NC}\"\n record_result \"Create Human User\" \"PASS\"\nelse\n echo -e \"${RED}Human user creation failed${NC}\"\n record_result \"Create Human User\" \"FAIL\"\nfi\necho \"\"\n\n# Step 3: Create M2M service account\necho -e \"${BLUE}[Step 3] Creating M2M service account: ${M2M_NAME}${NC}\"\nif [ \"$VERBOSE\" = true ]; then\n M2M_OUTPUT=$(${MGMT_CMD} user-create-m2m \\\n --name \"${M2M_NAME}\" \\\n --groups \"${GROUP_NAME}\" \\\n --description \"Test service account for end-to-end testing\" 2>&1)\n CREATE_STATUS=$?\nelse\n M2M_OUTPUT=$(${MGMT_CMD} user-create-m2m \\\n --name \"${M2M_NAME}\" \\\n --groups \"${GROUP_NAME}\" \\\n --description \"Test service account for end-to-end testing\" 2>&1)\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n echo \"${M2M_OUTPUT}\"\n # Extract client ID and secret (these are shown in the output)\n M2M_CLIENT_ID=\"${M2M_NAME}\"\n echo -e \"${GREEN}M2M service account created successfully${NC}\"\n echo -e \"${YELLOW}Note: Save the client secret from the output above - it will not be shown again!${NC}\"\n record_result \"Create M2M Account\" \"PASS\"\nelse\n echo -e \"${RED}M2M account creation failed${NC}\"\n record_result \"Create M2M Account\" \"FAIL\"\nfi\necho \"\"\n\n# Step 4: Register server\necho -e \"${BLUE}[Step 4] Registering server: ${SERVER_NAME} at ${SERVER_PATH}${NC}\"\n# Create the JSON file with timestamped path\ncat > \"${SERVER_JSON_FILE}\" < /dev/null 2>&1\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n echo -e \"${GREEN}Server registered successfully at ${SERVER_PATH}${NC}\"\n record_result \"Register Server\" \"PASS\"\nelse\n echo -e \"${RED}Server registration failed${NC}\"\n record_result \"Register Server\" \"FAIL\"\nfi\necho \"\"\n\n# Step 5: Register agent\necho -e \"${BLUE}[Step 5] Registering agent: ${AGENT_NAME} at ${AGENT_PATH}${NC}\"\n# Create the JSON file with timestamped path\ncat > \"${AGENT_JSON_FILE}\" < /dev/null 2>&1\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n echo -e \"${GREEN}Agent registered successfully at ${AGENT_PATH}${NC}\"\n record_result \"Register Agent\" \"PASS\"\nelse\n echo -e \"${RED}Agent registration failed${NC}\"\n record_result \"Register Agent\" \"FAIL\"\nfi\necho \"\"\n\necho -e \"${BLUE}========================================${NC}\"\necho -e \"${BLUE}Phase 2: Verification${NC}\"\necho -e \"${BLUE}========================================${NC}\"\necho \"\"\n\n# Step 6: List users\necho -e \"${BLUE}[Step 6] Listing all users (should include ${HUMAN_USERNAME} and ${M2M_NAME})${NC}\"\nif [ \"$VERBOSE\" = true ]; then\n USER_LIST_OUTPUT=$(${MGMT_CMD} user-list 2>&1)\n CREATE_STATUS=$?\n echo \"$USER_LIST_OUTPUT\"\nelse\n USER_LIST_OUTPUT=$(${MGMT_CMD} user-list 2>&1)\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n # Verify our created users are in the list\n if echo \"$USER_LIST_OUTPUT\" | grep -q \"${HUMAN_USERNAME}\" && echo \"$USER_LIST_OUTPUT\" | grep -q \"${M2M_NAME}\"; then\n echo -e \"${GREEN}User list retrieved successfully - verified both test users present${NC}\"\n record_result \"List Users\" \"PASS\"\n else\n echo -e \"${RED}User list retrieved but test users not found${NC}\"\n echo -e \"${RED}Expected users: ${HUMAN_USERNAME}, ${M2M_NAME}${NC}\"\n record_result \"List Users\" \"FAIL\"\n fi\nelse\n echo -e \"${RED}User list failed${NC}\"\n record_result \"List Users\" \"FAIL\"\nfi\necho \"\"\n\n# Step 7: List groups\necho -e \"${BLUE}[Step 7] Listing all groups (should include ${GROUP_NAME})${NC}\"\nif [ \"$VERBOSE\" = true ]; then\n GROUP_LIST_OUTPUT=$(${MGMT_CMD} group-list 2>&1)\n CREATE_STATUS=$?\n echo \"$GROUP_LIST_OUTPUT\"\nelse\n GROUP_LIST_OUTPUT=$(${MGMT_CMD} group-list 2>&1)\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n # Verify our created group is in the list\n if echo \"$GROUP_LIST_OUTPUT\" | grep -q \"${GROUP_NAME}\"; then\n echo -e \"${GREEN}Group list retrieved successfully - verified test group present${NC}\"\n record_result \"List Groups\" \"PASS\"\n else\n echo -e \"${RED}Group list retrieved but test group not found${NC}\"\n echo -e \"${RED}Expected group: ${GROUP_NAME}${NC}\"\n record_result \"List Groups\" \"FAIL\"\n fi\nelse\n echo -e \"${RED}Group list failed${NC}\"\n record_result \"List Groups\" \"FAIL\"\nfi\necho \"\"\n\n# Step 8: List servers\necho -e \"${BLUE}[Step 8] Listing all servers (should include ${SERVER_NAME})${NC}\"\nif [ \"$VERBOSE\" = true ]; then\n SERVER_LIST_OUTPUT=$(${MGMT_CMD} list 2>&1)\n CREATE_STATUS=$?\n echo \"$SERVER_LIST_OUTPUT\"\nelse\n SERVER_LIST_OUTPUT=$(${MGMT_CMD} list 2>&1)\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n # Verify our registered server is in the list (check for the path)\n if echo \"$SERVER_LIST_OUTPUT\" | grep -q \"${SERVER_PATH}\"; then\n echo -e \"${GREEN}Server list retrieved successfully - verified test server present${NC}\"\n record_result \"List Servers\" \"PASS\"\n else\n echo -e \"${RED}Server list retrieved but test server not found${NC}\"\n echo -e \"${RED}Expected server path: ${SERVER_PATH}${NC}\"\n record_result \"List Servers\" \"FAIL\"\n fi\nelse\n echo -e \"${RED}Server list failed${NC}\"\n record_result \"List Servers\" \"FAIL\"\nfi\necho \"\"\n\n# Step 9: List agents\necho -e \"${BLUE}[Step 9] Listing all agents (should include ${AGENT_NAME})${NC}\"\nif [ \"$VERBOSE\" = true ]; then\n AGENT_LIST_OUTPUT=$(${MGMT_CMD} agent-list 2>&1)\n CREATE_STATUS=$?\n echo \"$AGENT_LIST_OUTPUT\"\nelse\n AGENT_LIST_OUTPUT=$(${MGMT_CMD} agent-list 2>&1)\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n # Verify our registered agent is in the list (check for the path)\n if echo \"$AGENT_LIST_OUTPUT\" | grep -q \"${AGENT_PATH}\"; then\n echo -e \"${GREEN}Agent list retrieved successfully - verified test agent present${NC}\"\n record_result \"List Agents\" \"PASS\"\n else\n echo -e \"${RED}Agent list retrieved but test agent not found${NC}\"\n echo -e \"${RED}Expected agent path: ${AGENT_PATH}${NC}\"\n record_result \"List Agents\" \"FAIL\"\n fi\nelse\n echo -e \"${RED}Agent list failed${NC}\"\n record_result \"List Agents\" \"FAIL\"\nfi\necho \"\"\n\n# Step 10: Search for test users\necho -e \"${BLUE}[Step 10] Searching for test users${NC}\"\nif [ \"$VERBOSE\" = true ]; then\n ${MGMT_CMD} user-list --search \"test\" --limit 50\n CREATE_STATUS=$?\nelse\n ${MGMT_CMD} user-list --search \"test\" --limit 50 > /dev/null 2>&1\n CREATE_STATUS=$?\nfi\n\nif [ $CREATE_STATUS -eq 0 ]; then\n echo -e \"${GREEN}User search successful${NC}\"\n record_result \"Search Users\" \"PASS\"\nelse\n echo -e \"${RED}User search failed${NC}\"\n record_result \"Search Users\" \"FAIL\"\nfi\necho \"\"\n\necho -e \"${GREEN}========================================${NC}\"\necho -e \"${GREEN}All verification steps completed!${NC}\"\necho -e \"${GREEN}========================================${NC}\"\necho \"\"\n\n# Cleanup will run automatically via trap EXIT and display summary\n" }, { "path": "api/test-mcp-client.sh", "content": "#!/bin/bash\n\n# Simple MCP client for testing MCP servers\n# Usage: ./test-mcp-client.sh [--verbose|-v] \n\nset -e\n\n# Get script directory\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\n\n# Colors\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nRED='\\033[0;31m'\nNC='\\033[0m'\n\n\n_show_usage() {\n echo \"Usage: ./test-mcp-client.sh [--verbose|-v] \"\n echo \"\"\n echo \"Options:\"\n echo \" --verbose, -v Show HTTP status, headers, and raw response\"\n echo \"\"\n echo \"Required arguments:\"\n echo \" method MCP method to call\"\n echo \" server-url Full URL to the MCP server endpoint\"\n echo \" token-file Path to file containing the access token\"\n echo \"\"\n echo \"Available methods:\"\n echo \" ping - Test server connectivity\"\n echo \" initialize - Initialize MCP connection\"\n echo \" tools/list - List available tools\"\n echo \" resources/list - List available resources\"\n echo \" current_time [tz] - Get current time (optional timezone)\"\n echo \"\"\n echo \"Token file formats supported:\"\n echo \" - Plain JWT string\"\n echo \" - JSON with .tokens.access_token\"\n echo \" - JSON with .token_data.access_token\"\n echo \"\"\n echo \"Example:\"\n echo \" ./test-mcp-client.sh ping https://mcpgateway.ddns.net/currenttime/mcp ./api/.token\"\n echo \" ./test-mcp-client.sh --verbose initialize https://example.com/mcp/server/ /path/to/token\"\n echo \" ./test-mcp-client.sh current_time https://example.com/mcp/server/ .token America/New_York\"\n}\n\n\n# Parse --verbose flag\nVERBOSE=false\nif [ \"$1\" = \"--verbose\" ] || [ \"$1\" = \"-v\" ]; then\n VERBOSE=true\n shift\nfi\n\n# Required parameters (no defaults)\nMETHOD=\"$1\"\nSERVER_URL=\"$2\"\nTOKEN_FILE=\"$3\"\nSESSION_FILE=\"${SCRIPT_DIR}/.mcp-session\"\n\n# Validate required parameters\nif [ -z \"$METHOD\" ] || [ -z \"$SERVER_URL\" ] || [ -z \"$TOKEN_FILE\" ]; then\n echo -e \"${RED}Error: Missing required arguments${NC}\"\n echo \"\"\n _show_usage\n exit 1\nfi\n\n# Check if token file exists\nif [ ! -f \"$TOKEN_FILE\" ]; then\n echo -e \"${RED}Error: Token file not found at $TOKEN_FILE${NC}\"\n echo \"Run get-m2m-token.sh first to generate a token\"\n exit 1\nfi\n\n# Read and parse token from file\n# Supports: plain JWT string, or JSON with .tokens.access_token or .token_data.access_token\nTOKEN_CONTENT=$(cat \"$TOKEN_FILE\")\n\n# Try to extract token from JSON structure first\nACCESS_TOKEN=$(echo \"$TOKEN_CONTENT\" | jq -r '.tokens.access_token // .token_data.access_token // empty' 2>/dev/null)\n\n# If no JSON token found, assume the file contains a plain JWT string\nif [ -z \"$ACCESS_TOKEN\" ]; then\n ACCESS_TOKEN=\"$TOKEN_CONTENT\"\nfi\n\n# Validate token is not empty\nif [ -z \"$ACCESS_TOKEN\" ]; then\n echo -e \"${RED}Error: Could not extract access token from $TOKEN_FILE${NC}\"\n exit 1\nfi\n\n# Read session ID if exists\nSESSION_ID=\"\"\nif [ -f \"$SESSION_FILE\" ]; then\n SESSION_ID=$(cat \"$SESSION_FILE\")\nfi\n\necho -e \"${YELLOW}Calling MCP server...${NC}\"\necho \" Method: $METHOD\"\necho \" Server: $SERVER_URL\"\nif [ -n \"$SESSION_ID\" ]; then\n echo \" Session: $SESSION_ID\"\nfi\necho \"\"\n\n# Build the request based on method\ncase \"$METHOD\" in\n ping)\n REQUEST_DATA='{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"ping\"\n }'\n ;;\n initialize)\n REQUEST_DATA='{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {},\n \"clientInfo\": {\n \"name\": \"test-client\",\n \"version\": \"1.0.0\"\n }\n }\n }'\n ;;\n tools/list)\n REQUEST_DATA='{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/list\"\n }'\n ;;\n resources/list)\n REQUEST_DATA='{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"resources/list\"\n }'\n ;;\n current_time)\n TIMEZONE=\"${4:-America/New_York}\"\n REQUEST_DATA=\"{\n \\\"jsonrpc\\\": \\\"2.0\\\",\n \\\"id\\\": 1,\n \\\"method\\\": \\\"tools/call\\\",\n \\\"params\\\": {\n \\\"name\\\": \\\"current_time_by_timezone\\\",\n \\\"arguments\\\": {\n \\\"timezone\\\": \\\"$TIMEZONE\\\"\n }\n }\n }\"\n ;;\n *)\n echo -e \"${RED}Unknown method: $METHOD${NC}\"\n echo \"\"\n _show_usage\n exit 1\n ;;\nesac\n\n# Make the request with proper headers for SSE support\n# Include session ID in mcp-session-id header if available\n# Use temporary file to capture response headers\nHEADERS_FILE=$(mktemp)\nRESPONSE=\"\"\nHTTP_CODE=\"\"\nif [ -n \"$SESSION_ID\" ]; then\n RESPONSE=$(curl -D \"$HEADERS_FILE\" -s -w \"\\n__HTTP_CODE__:%{http_code}\" -X POST \"$SERVER_URL\" \\\n -H \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: application/json, text/event-stream\" \\\n -H \"mcp-session-id: ${SESSION_ID}\" \\\n -d \"$REQUEST_DATA\")\nelse\n RESPONSE=$(curl -D \"$HEADERS_FILE\" -s -w \"\\n__HTTP_CODE__:%{http_code}\" -X POST \"$SERVER_URL\" \\\n -H \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: application/json, text/event-stream\" \\\n -d \"$REQUEST_DATA\")\nfi\n\n# Extract HTTP status code from response\nHTTP_CODE=$(echo \"$RESPONSE\" | grep \"^__HTTP_CODE__:\" | sed 's/^__HTTP_CODE__://')\nRESPONSE=$(echo \"$RESPONSE\" | grep -v \"^__HTTP_CODE__:\")\n\n# Verbose output\nif [ \"$VERBOSE\" = true ]; then\n echo -e \"${YELLOW}--- HTTP Status Code ---${NC}\"\n echo \"$HTTP_CODE\"\n echo \"\"\n echo -e \"${YELLOW}--- Response Headers ---${NC}\"\n cat \"$HEADERS_FILE\"\n echo \"\"\n echo -e \"${YELLOW}--- Raw Response Body ---${NC}\"\n echo \"$RESPONSE\"\n echo \"\"\n echo -e \"${YELLOW}--- Parsed JSON ---${NC}\"\nfi\n\n# Parse SSE response - extract JSON from \"data:\" lines\n# SSE format is: \"event: message\\ndata: {json}\"\nJSON_RESPONSE=$(echo \"$RESPONSE\" | grep \"^data: \" | sed 's/^data: //' | head -1)\n\nif [ -z \"$JSON_RESPONSE\" ]; then\n # No SSE format, assume plain JSON\n JSON_RESPONSE=\"$RESPONSE\"\nfi\n\n# Display response - handle jq errors gracefully\nif ! echo \"$JSON_RESPONSE\" | jq . 2>/dev/null; then\n echo -e \"${RED}Error: Response is not valid JSON (HTTP $HTTP_CODE)${NC}\"\n echo \"$JSON_RESPONSE\"\nfi\n\n# Extract session ID from response headers (mcp-session-id header)\nNEW_SESSION_ID=$(grep -i \"^mcp-session-id:\" \"$HEADERS_FILE\" | sed 's/^mcp-session-id: *//i' | tr -d '\\r\\n')\n\n# Save session ID if present\nif [ -n \"$NEW_SESSION_ID\" ]; then\n echo \"$NEW_SESSION_ID\" > \"$SESSION_FILE\"\n echo -e \"${GREEN}Session ID saved to $SESSION_FILE: $NEW_SESSION_ID${NC}\"\nfi\n\n# Clean up temporary headers file\nrm -f \"$HEADERS_FILE\"\n\necho \"\"\necho -e \"${GREEN}Done!${NC}\"\n" }, { "path": "auth_server/__init__.py", "content": "\"\"\"\nAuth server package for MCP Gateway Registry.\n\"\"\"\n" }, { "path": "auth_server/cognito_utils.py", "content": "\"\"\"\nCognito utilities for token generation and AWS Cognito operations.\n\"\"\"\n\nimport logging\n\nimport requests\n\nlogger = logging.getLogger(__name__)\n\n\ndef generate_token(\n client_id: str,\n client_secret: str,\n user_pool_id: str,\n region: str,\n scopes: list[str] = None,\n domain: str = None,\n) -> dict:\n \"\"\"\n Generate a token using the client credentials flow\n\n Args:\n client_id: Cognito App Client ID\n client_secret: Cognito App Client Secret\n user_pool_id: Cognito User Pool ID\n region: AWS region\n scopes: List of scopes to request (optional)\n domain: Optional custom domain name (e.g., 'mcp-gateway')\n\n Returns:\n Dict containing access token and metadata\n \"\"\"\n try:\n # Construct the Cognito domain\n if domain:\n # Use custom domain if provided\n cognito_domain = f\"https://{domain}.auth.{region}.amazoncognito.com\"\n else:\n # Otherwise use user pool ID without underscores (standard format)\n user_pool_id_wo_underscore = user_pool_id.replace(\"_\", \"\")\n cognito_domain = f\"https://{user_pool_id_wo_underscore}.auth.{region}.amazoncognito.com\"\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n }\n\n if scopes:\n data[\"scope\"] = \" \".join(scopes)\n\n token_url = f\"{cognito_domain}/oauth2/token\"\n\n logger.info(f\"Requesting token from {token_url}\")\n response = requests.post(token_url, headers=headers, data=data, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.info(\"Successfully obtained client credentials token\")\n return token_data\n\n except Exception as e:\n logger.error(f\"Failed to get client credentials token: {e}\")\n raise ValueError(f\"Cannot obtain token: {e}\")\n" }, { "path": "auth_server/metrics_middleware.py", "content": "\"\"\"\nFastAPI middleware for comprehensive metrics collection in the auth server.\n\nThis middleware automatically tracks detailed authentication metrics including:\n- Validation steps and scope checking\n- Tool access control decisions\n- Method/tool usage patterns\n- Error analysis with specific reasons\n\"\"\"\n\nimport asyncio\nimport hashlib\nimport json\nimport logging\nimport os\nimport time\nimport uuid\nfrom collections.abc import Callable\nfrom datetime import datetime\nfrom typing import Any\n\n# Import metrics client - use HTTP API instead of local import\nimport httpx\nfrom fastapi import Request, Response\nfrom starlette.middleware.base import BaseHTTPMiddleware\n\nlogger = logging.getLogger(__name__)\n\n\nclass AuthMetricsMiddleware(BaseHTTPMiddleware):\n \"\"\"\n Comprehensive middleware to collect detailed authentication and tool execution metrics.\n\n Tracks:\n - Authentication flow with detailed validation steps\n - Scope checking and access control decisions\n - Tool and method execution patterns\n - Error analysis with specific failure reasons\n - User activity patterns (hashed for privacy)\n \"\"\"\n\n def __init__(self, app, service_name: str = \"auth-server\"):\n super().__init__(app)\n self.service_name = service_name\n self.metrics_url = os.getenv(\"METRICS_SERVICE_URL\", \"http://localhost:8890\")\n self.api_key = os.getenv(\"METRICS_API_KEY\", \"\")\n self.client = httpx.AsyncClient(timeout=5.0)\n\n # Track request contexts for detailed metrics\n self.request_contexts: dict[str, dict[str, Any]] = {}\n\n # Track session timings for protocol flow analysis\n self.session_timings: dict[str, dict[str, float]] = {}\n\n # Track session client info for consistent metrics across requests\n self.session_client_info: dict[str, dict[str, str]] = {}\n\n # Scalability configuration\n self.max_sessions = 1000 # Limit concurrent sessions\n self.session_ttl = 3600 # 1 hour TTL\n self.cleanup_interval = 300 # Cleanup every 5 minutes\n self.last_cleanup = time.time()\n\n def hash_username(self, username: str) -> str:\n \"\"\"Hash username for privacy in metrics.\"\"\"\n if not username:\n return \"\"\n return hashlib.sha256(username.encode()).hexdigest()[:12]\n\n async def _cleanup_sessions_if_needed(self):\n \"\"\"Perform periodic cleanup of old sessions to prevent memory leaks.\"\"\"\n current_time = time.time()\n\n # Only cleanup every cleanup_interval seconds\n if current_time - self.last_cleanup < self.cleanup_interval:\n return\n\n self.last_cleanup = current_time\n\n # Clean up old session timings\n sessions_to_remove = []\n for session_key, methods in self.session_timings.items():\n # Remove if all methods are old\n if all(current_time - timestamp > self.session_ttl for timestamp in methods.values()):\n sessions_to_remove.append(session_key)\n\n # Also remove oldest sessions if we exceed max_sessions\n if len(self.session_timings) > self.max_sessions:\n # Sort by oldest timestamp and remove excess\n session_ages = [\n (session_key, min(methods.values()) if methods else 0)\n for session_key, methods in self.session_timings.items()\n ]\n session_ages.sort(key=lambda x: x[1])\n excess_count = len(self.session_timings) - self.max_sessions\n sessions_to_remove.extend([s[0] for s in session_ages[:excess_count]])\n\n # Remove sessions\n for session_key in sessions_to_remove:\n self.session_timings.pop(session_key, None)\n self.session_client_info.pop(session_key, None)\n\n if sessions_to_remove:\n logger.debug(f\"Cleaned up {len(sessions_to_remove)} old sessions\")\n\n def extract_server_name_from_url(self, original_url: str) -> str:\n \"\"\"Extract server name from the original URL.\"\"\"\n if not original_url:\n return \"unknown\"\n\n try:\n from urllib.parse import urlparse\n\n parsed_url = urlparse(original_url)\n path = parsed_url.path.strip(\"/\")\n path_parts = path.split(\"/\") if path else []\n return path_parts[0] if path_parts else \"unknown\"\n except Exception:\n return \"unknown\"\n\n async def extract_tool_and_method_info(self, request: Request) -> dict[str, Any]:\n \"\"\"Extract detailed tool and method information from headers (X-Body) instead of consuming body.\"\"\"\n tool_info = {\n \"method\": \"unknown\",\n \"tool_name\": None,\n \"request_id\": None,\n \"protocol_version\": None,\n \"client_info\": {},\n \"params\": {},\n }\n\n try:\n # Get the request body from X-Body header set by Lua script instead of consuming it\n x_body = request.headers.get(\"X-Body\")\n if x_body:\n request_payload = json.loads(x_body)\n\n if isinstance(request_payload, dict):\n tool_info[\"method\"] = request_payload.get(\"method\", \"unknown\")\n tool_info[\"request_id\"] = request_payload.get(\"id\")\n tool_info[\"jsonrpc\"] = request_payload.get(\"jsonrpc\")\n\n # Extract parameters\n params = request_payload.get(\"params\", {})\n tool_info[\"params\"] = params\n\n # For tools/call, extract the actual tool name from params\n if tool_info[\"method\"] == \"tools/call\" and isinstance(params, dict):\n tool_info[\"tool_name\"] = params.get(\"name\", \"\")\n\n # For initialize, extract client info and capabilities\n elif tool_info[\"method\"] == \"initialize\" and isinstance(params, dict):\n tool_info[\"protocol_version\"] = params.get(\"protocolVersion\")\n tool_info[\"client_info\"] = params.get(\"clientInfo\", {})\n\n except Exception as e:\n logger.debug(f\"Could not extract tool information from X-Body header: {e}\")\n\n return tool_info\n\n async def dispatch(self, request: Request, call_next: Callable) -> Response:\n \"\"\"\n Process request and collect comprehensive metrics.\n \"\"\"\n # Skip metrics collection for non-validation endpoints\n if not request.url.path.startswith(\"/validate\"):\n return await call_next(request)\n\n # Start timing and generate request ID\n start_time = time.perf_counter()\n current_timestamp = time.time()\n request_id = f\"req_{uuid.uuid4().hex[:16]}\"\n\n # Extract comprehensive request data\n server_name = \"unknown\"\n user_hash = \"\"\n auth_method = \"unknown\"\n tool_info = {}\n\n # Extract server name from original URL header\n original_url = request.headers.get(\"X-Original-URL\")\n if original_url:\n server_name = self.extract_server_name_from_url(original_url)\n\n # Extract detailed tool/method information\n tool_info = await self.extract_tool_and_method_info(request)\n\n # Process the request\n response = None\n success = False\n error_code = None\n\n try:\n response = await call_next(request)\n\n # Determine success based on response status\n success = response.status_code == 200\n\n if success:\n # Extract user info from response headers if available\n username = response.headers.get(\"X-Username\", \"\")\n user_hash = self.hash_username(username)\n auth_method = response.headers.get(\"X-Auth-Method\", \"unknown\")\n\n # Track session timing for protocol flow analysis\n session_key = (\n f\"{server_name}:{user_hash}\" if user_hash else f\"{server_name}:anonymous\"\n )\n method = tool_info.get(\"method\", \"unknown\")\n\n # Perform periodic cleanup to prevent memory leaks\n await self._cleanup_sessions_if_needed()\n\n if session_key not in self.session_timings:\n self.session_timings[session_key] = {}\n\n # Store timestamp for this method\n self.session_timings[session_key][method] = current_timestamp\n\n # Store client info for initialize requests\n if method == \"initialize\" and tool_info.get(\"client_info\"):\n self.session_client_info[session_key] = tool_info[\"client_info\"]\n else:\n error_code = str(response.status_code)\n session_key = f\"{server_name}:anonymous\"\n\n except Exception as e:\n # Handle exceptions during request processing\n success = False\n error_code = type(e).__name__\n logger.error(f\"Error in auth request: {e}\")\n # Re-raise the exception to maintain normal error handling\n raise\n\n finally:\n # Calculate duration\n duration_ms = (time.perf_counter() - start_time) * 1000\n\n # Emit comprehensive metrics asynchronously (fire and forget)\n # 1. Main auth metric\n asyncio.create_task(\n self._emit_auth_metric(\n success=success,\n method=auth_method,\n duration_ms=duration_ms,\n server_name=server_name,\n user_hash=user_hash,\n error_code=error_code,\n request_id=request_id,\n )\n )\n\n # 2. Tool execution metric (if applicable)\n if tool_info.get(\"method\") and tool_info[\"method\"] != \"unknown\":\n asyncio.create_task(\n self._emit_tool_execution_metric(\n tool_info=tool_info,\n server_name=server_name,\n success=success,\n duration_ms=duration_ms,\n user_hash=user_hash,\n error_code=error_code,\n request_id=request_id,\n auth_method=auth_method,\n )\n )\n\n # 3. Protocol flow latency metric (if we can calculate it)\n if success and session_key in self.session_timings:\n asyncio.create_task(\n self._emit_protocol_latency_metric(\n session_key=session_key,\n current_method=method,\n server_name=server_name,\n user_hash=user_hash,\n request_id=request_id,\n )\n )\n\n return response\n\n async def _emit_auth_metric(\n self,\n success: bool,\n method: str,\n duration_ms: float,\n server_name: str,\n user_hash: str,\n error_code: str = None,\n request_id: str = None,\n ):\n \"\"\"\n Emit authentication metric asynchronously.\n \"\"\"\n try:\n if not self.api_key:\n return\n\n payload = {\n \"service\": self.service_name,\n \"version\": \"1.0.0\",\n \"metrics\": [\n {\n \"type\": \"auth_request\",\n \"timestamp\": datetime.utcnow().isoformat(),\n \"value\": 1.0,\n \"duration_ms\": duration_ms,\n \"dimensions\": {\n \"success\": success,\n \"method\": method,\n \"server\": server_name,\n \"user_hash\": user_hash,\n },\n \"metadata\": {\n \"error_code\": error_code,\n \"request_id\": request_id or f\"req_{uuid.uuid4().hex[:16]}\",\n },\n }\n ],\n }\n\n await self.client.post(\n f\"{self.metrics_url}/metrics\", json=payload, headers={\"X-API-Key\": self.api_key}\n )\n except Exception as e:\n logger.debug(f\"Failed to emit auth metric: {e}\")\n\n async def _emit_tool_execution_metric(\n self,\n tool_info: dict[str, Any],\n server_name: str,\n success: bool,\n duration_ms: float,\n user_hash: str,\n error_code: str = None,\n request_id: str = None,\n auth_method: str = \"unknown\",\n ):\n \"\"\"\n Emit tool execution metric for the specialized tool_metrics table.\n \"\"\"\n try:\n if not self.api_key:\n return\n\n # Extract tool/method details\n method_name = tool_info.get(\"method\", \"unknown\")\n actual_tool_name = tool_info.get(\"tool_name\")\n client_info = tool_info.get(\"client_info\", {})\n\n # If no client_info in current request, try to get it from session\n if not client_info or client_info.get(\"name\") == \"unknown\":\n session_key = (\n f\"{server_name}:{user_hash}\" if user_hash else f\"{server_name}:anonymous\"\n )\n stored_client_info = self.session_client_info.get(session_key, {})\n if stored_client_info:\n client_info = stored_client_info\n\n # Create tool execution metric payload\n metric_data = {\n \"type\": \"tool_execution\",\n \"timestamp\": datetime.utcnow().isoformat(),\n \"value\": 1.0,\n \"duration_ms\": duration_ms,\n \"dimensions\": {\n \"tool_name\": actual_tool_name or method_name,\n \"server_name\": server_name,\n \"success\": success,\n \"method\": method_name,\n \"user_hash\": user_hash,\n \"server_path\": f\"/{server_name}/\",\n \"client_name\": client_info.get(\"name\", \"unknown\"),\n \"client_version\": client_info.get(\"version\", \"unknown\"),\n },\n \"metadata\": {\n \"error_code\": error_code,\n \"auth_method\": auth_method,\n \"request_id\": request_id or f\"req_{uuid.uuid4().hex[:16]}\",\n \"protocol_version\": tool_info.get(\"protocol_version\"),\n \"jsonrpc_id\": tool_info.get(\"request_id\"),\n \"actual_tool_name\": actual_tool_name,\n \"method_type\": method_name,\n \"input_size_bytes\": len(json.dumps(tool_info.get(\"params\", {})).encode()),\n \"output_size_bytes\": 0, # Will be updated if response available\n },\n }\n\n payload = {\"service\": self.service_name, \"version\": \"1.0.0\", \"metrics\": [metric_data]}\n\n await self.client.post(\n f\"{self.metrics_url}/metrics\", json=payload, headers={\"X-API-Key\": self.api_key}\n )\n except Exception as e:\n logger.debug(f\"Failed to emit tool execution metric: {e}\")\n\n async def _emit_protocol_latency_metric(\n self,\n session_key: str,\n current_method: str,\n server_name: str,\n user_hash: str,\n request_id: str,\n ):\n \"\"\"\n Emit protocol flow latency metrics based on session timing data.\n \"\"\"\n try:\n if not self.api_key:\n return\n\n session_data = self.session_timings.get(session_key, {})\n current_time = time.time()\n\n # Calculate latencies between protocol steps\n latency_metrics = []\n\n # Initialize -> Tools List latency\n if \"initialize\" in session_data and \"tools/list\" in session_data:\n init_to_list_latency = session_data[\"tools/list\"] - session_data[\"initialize\"]\n if (\n init_to_list_latency > 0 and init_to_list_latency < 300\n ): # Max 5 minutes reasonable\n latency_metrics.append(\n {\n \"type\": \"protocol_latency\",\n \"timestamp\": datetime.utcnow().isoformat(),\n \"value\": init_to_list_latency,\n \"dimensions\": {\n \"flow_step\": \"initialize_to_tools_list\",\n \"server_name\": server_name,\n \"user_hash\": user_hash,\n \"session_key\": session_key,\n },\n \"metadata\": {\n \"request_id\": request_id,\n \"latency_seconds\": init_to_list_latency,\n \"from_method\": \"initialize\",\n \"to_method\": \"tools/list\",\n },\n }\n )\n\n # Tools List -> Tools Call latency\n if \"tools/list\" in session_data and \"tools/call\" in session_data:\n list_to_call_latency = session_data[\"tools/call\"] - session_data[\"tools/list\"]\n if (\n list_to_call_latency > 0 and list_to_call_latency < 300\n ): # Max 5 minutes reasonable\n latency_metrics.append(\n {\n \"type\": \"protocol_latency\",\n \"timestamp\": datetime.utcnow().isoformat(),\n \"value\": list_to_call_latency,\n \"dimensions\": {\n \"flow_step\": \"tools_list_to_tools_call\",\n \"server_name\": server_name,\n \"user_hash\": user_hash,\n \"session_key\": session_key,\n },\n \"metadata\": {\n \"request_id\": request_id,\n \"latency_seconds\": list_to_call_latency,\n \"from_method\": \"tools/list\",\n \"to_method\": \"tools/call\",\n },\n }\n )\n\n # Initialize -> Tools Call (total flow latency)\n if \"initialize\" in session_data and \"tools/call\" in session_data:\n total_flow_latency = session_data[\"tools/call\"] - session_data[\"initialize\"]\n if total_flow_latency > 0 and total_flow_latency < 600: # Max 10 minutes reasonable\n latency_metrics.append(\n {\n \"type\": \"protocol_latency\",\n \"timestamp\": datetime.utcnow().isoformat(),\n \"value\": total_flow_latency,\n \"dimensions\": {\n \"flow_step\": \"full_protocol_flow\",\n \"server_name\": server_name,\n \"user_hash\": user_hash,\n \"session_key\": session_key,\n },\n \"metadata\": {\n \"request_id\": request_id,\n \"latency_seconds\": total_flow_latency,\n \"from_method\": \"initialize\",\n \"to_method\": \"tools/call\",\n },\n }\n )\n\n # Emit metrics if we have any\n if latency_metrics:\n payload = {\n \"service\": self.service_name,\n \"version\": \"1.0.0\",\n \"metrics\": latency_metrics,\n }\n\n await self.client.post(\n f\"{self.metrics_url}/metrics\", json=payload, headers={\"X-API-Key\": self.api_key}\n )\n\n # Cleanup is now handled by _cleanup_sessions_if_needed method\n\n except Exception as e:\n logger.debug(f\"Failed to emit protocol latency metric: {e}\")\n\n\ndef add_auth_metrics_middleware(app, service_name: str = \"auth-server\"):\n \"\"\"\n Convenience function to add auth metrics middleware to a FastAPI app.\n\n Args:\n app: FastAPI application instance\n service_name: Name of the service for metrics identification\n \"\"\"\n app.add_middleware(AuthMetricsMiddleware, service_name=service_name)\n logger.info(f\"Auth metrics middleware added for service: {service_name}\")\n" }, { "path": "auth_server/mongodb_groups_enrichment.py", "content": "\"\"\"DocumentDB/MongoDB Groups Enrichment for M2M Tokens.\n\nThis module provides functionality to enrich M2M tokens with groups from DocumentDB/MongoDB\nwhen the IdP token has empty groups claim. This solves the authorization problem\nfor M2M clients across all identity providers (Keycloak, Okta, Entra).\n\nWorks with both:\n- AWS DocumentDB (with IAM auth or username/password)\n- MongoDB Community Edition (local or cloud)\n\"\"\"\n\nimport logging\n\nfrom motor.motor_asyncio import AsyncIOMotorDatabase\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\n_mongodb_database: AsyncIOMotorDatabase | None = None\n\n\nasync def _get_mongodb() -> AsyncIOMotorDatabase:\n \"\"\"Get MongoDB/DocumentDB database connection singleton.\n\n This uses the same connection logic as the registry to ensure compatibility\n with both MongoDB Community Edition and AWS DocumentDB.\n\n Returns:\n MongoDB/DocumentDB database instance\n\n Raises:\n ValueError: If database connection parameters not configured\n \"\"\"\n global _mongodb_client, _mongodb_database\n\n if _mongodb_database is not None:\n return _mongodb_database\n\n try:\n # Use the registry's DocumentDB client for compatibility\n # This handles both MongoDB CE and AWS DocumentDB with proper auth mechanisms\n import sys\n from pathlib import Path\n\n # Add registry path to sys.path if not already there\n registry_path = Path(__file__).parent.parent / \"registry\"\n if str(registry_path) not in sys.path:\n sys.path.insert(0, str(registry_path.parent))\n\n from registry.repositories.documentdb.client import get_documentdb_client\n\n _mongodb_database = await get_documentdb_client()\n logger.info(\"✓ Connected to DocumentDB/MongoDB for groups enrichment\")\n\n return _mongodb_database\n\n except Exception as e:\n logger.error(f\"Failed to connect to DocumentDB/MongoDB: {e}\")\n raise ValueError(f\"Database connection failed: {e}\")\n\n\nasync def enrich_groups_from_mongodb(\n client_id: str,\n current_groups: list[str],\n) -> list[str]:\n \"\"\"Enrich groups from DocumentDB/MongoDB if current groups are empty.\n\n This function checks if an M2M client has groups defined in the database\n and returns them if the current groups list is empty. This provides\n a fallback authorization mechanism for M2M tokens.\n\n Works with both AWS DocumentDB and MongoDB Community Edition.\n\n Args:\n client_id: Client ID from the JWT token\n current_groups: Current groups from JWT token\n\n Returns:\n Enriched groups list (either from MongoDB or original)\n \"\"\"\n # If groups already exist in token (non-empty array), use them\n if current_groups:\n logger.debug(f\"Client {client_id} has groups in token: {current_groups}\")\n return current_groups\n\n logger.info(f\"Client {client_id} has no groups in token, querying database\")\n\n # Try to fetch groups from DocumentDB/MongoDB\n try:\n db = await _get_mongodb()\n collection = db[\"idp_m2m_clients\"]\n\n doc = await collection.find_one({\"client_id\": client_id})\n\n if doc:\n db_groups = doc.get(\"groups\", [])\n if db_groups:\n logger.info(f\"Enriched groups for client {client_id} from database: {db_groups}\")\n return db_groups\n else:\n logger.debug(f\"Client {client_id} found in database but has no groups\")\n else:\n logger.debug(f\"Client {client_id} not found in groups database\")\n\n except Exception as e:\n logger.warning(f\"Failed to query database for groups enrichment: {e}\")\n # Don't fail token validation if database is unavailable\n\n # Return original empty groups if no enrichment possible\n return current_groups\n\n\ndef should_enrich_groups(validation_result: dict) -> bool:\n \"\"\"Check if groups should be enriched from MongoDB.\n\n Args:\n validation_result: Token validation result dictionary\n\n Returns:\n True if groups enrichment should be attempted\n \"\"\"\n # Only enrich if:\n # 1. Token is valid\n # 2. Groups list is empty (not present or empty array)\n # 3. Has a client_id\n is_valid = validation_result.get(\"valid\", False)\n groups = validation_result.get(\"groups\", [])\n client_id = validation_result.get(\"client_id\")\n\n return is_valid and not groups and client_id is not None\n" }, { "path": "auth_server/oauth2_providers.yml", "content": "providers:\n keycloak:\n display_name: \"Keycloak\"\n client_id: \"${KEYCLOAK_CLIENT_ID}\"\n client_secret: \"${KEYCLOAK_CLIENT_SECRET}\"\n auth_url: \"${KEYCLOAK_EXTERNAL_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/auth\"\n token_url: \"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token\"\n user_info_url: \"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/userinfo\"\n logout_url: \"${KEYCLOAK_EXTERNAL_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/logout\"\n scopes: [\"openid\", \"email\", \"profile\"]\n response_type: \"code\"\n grant_type: \"authorization_code\"\n # Claims mapping for user info\n username_claim: \"preferred_username\"\n groups_claim: \"groups\"\n email_claim: \"email\"\n name_claim: \"name\"\n enabled: \"${KEYCLOAK_ENABLED}\"\n\n cognito:\n display_name: \"AWS Cognito\"\n client_id: \"${COGNITO_CLIENT_ID}\"\n client_secret: \"${COGNITO_CLIENT_SECRET}\"\n # Domain will be auto-derived from user pool ID if COGNITO_DOMAIN is not set\n auth_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/oauth2/authorize\"\n token_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/oauth2/token\"\n user_info_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/oauth2/userInfo\"\n logout_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/logout\"\n scopes: [\"openid\", \"email\", \"profile\", \"aws.cognito.signin.user.admin\"]\n response_type: \"code\"\n grant_type: \"authorization_code\"\n # Claims mapping for user info\n username_claim: \"email\"\n groups_claim: \"cognito:groups\"\n email_claim: \"email\"\n name_claim: \"name\"\n enabled: \"${COGNITO_ENABLED}\"\n\n entra:\n display_name: \"Microsoft Entra ID\"\n client_id: \"${ENTRA_CLIENT_ID}\"\n client_secret: \"${ENTRA_CLIENT_SECRET}\"\n auth_url: \"https://login.microsoftonline.com/${ENTRA_TENANT_ID}/oauth2/v2.0/authorize\"\n token_url: \"https://login.microsoftonline.com/${ENTRA_TENANT_ID}/oauth2/v2.0/token\"\n user_info_url: \"https://graph.microsoft.com/oidc/userinfo\"\n logout_url: \"https://login.microsoftonline.com/${ENTRA_TENANT_ID}/oauth2/v2.0/logout\"\n # Request only OIDC scopes for user authentication\n # The resulting access token is for Microsoft Graph API\n # For programmatic API access, users get JWT tokens through the /tokens/generate endpoint\n scopes: [\"openid\", \"email\", \"profile\"]\n response_type: \"code\"\n grant_type: \"authorization_code\"\n # Claims mapping for user info\n username_claim: \"preferred_username\"\n groups_claim: \"groups\"\n email_claim: \"email\"\n name_claim: \"name\"\n enabled: \"${ENTRA_ENABLED}\"\n\n okta:\n display_name: \"Okta\"\n client_id: \"${OKTA_CLIENT_ID}\"\n client_secret: \"${OKTA_CLIENT_SECRET}\"\n auth_url: \"https://${OKTA_DOMAIN}/oauth2/v1/authorize\"\n token_url: \"https://${OKTA_DOMAIN}/oauth2/v1/token\"\n user_info_url: \"https://${OKTA_DOMAIN}/oauth2/v1/userinfo\"\n logout_url: \"https://${OKTA_DOMAIN}/oauth2/v1/logout\"\n scopes: [\"openid\", \"email\", \"profile\", \"groups\"]\n response_type: \"code\"\n grant_type: \"authorization_code\"\n username_claim: \"preferred_username\"\n groups_claim: \"groups\"\n email_claim: \"email\"\n name_claim: \"name\"\n enabled: true\n\n github:\n display_name: \"GitHub\"\n client_id: \"${GITHUB_CLIENT_ID}\"\n client_secret: \"${GITHUB_CLIENT_SECRET}\"\n auth_url: \"https://github.com/login/oauth/authorize\"\n token_url: \"https://github.com/login/oauth/access_token\"\n user_info_url: \"https://api.github.com/user\"\n scopes: [\"read:user\", \"user:email\"]\n response_type: \"code\"\n grant_type: \"authorization_code\"\n # GitHub specific claim mapping\n username_claim: \"login\"\n groups_claim: null # GitHub doesn't provide groups in basic scope\n email_claim: \"email\"\n name_claim: \"name\"\n enabled: \"${GITHUB_ENABLED}\"\n\n auth0:\n display_name: \"Auth0\"\n client_id: \"${AUTH0_CLIENT_ID}\"\n client_secret: \"${AUTH0_CLIENT_SECRET}\"\n auth_url: \"https://${AUTH0_DOMAIN}/authorize\"\n token_url: \"https://${AUTH0_DOMAIN}/oauth/token\"\n user_info_url: \"https://${AUTH0_DOMAIN}/userinfo\"\n logout_url: \"https://${AUTH0_DOMAIN}/v2/logout\"\n scopes: [\"openid\", \"email\", \"profile\"]\n response_type: \"code\"\n grant_type: \"authorization_code\"\n # Claims mapping for user info\n # Auth0 uses 'nickname' for display name and requires a custom\n # Rule/Action to add groups to tokens as a namespaced claim\n username_claim: \"nickname\"\n groups_claim: \"${AUTH0_GROUPS_CLAIM}\"\n email_claim: \"email\"\n name_claim: \"name\"\n enabled: \"${AUTH0_ENABLED}\"\n\n google:\n display_name: \"Google\"\n client_id: \"${GOOGLE_CLIENT_ID}\"\n client_secret: \"${GOOGLE_CLIENT_SECRET}\"\n auth_url: \"https://accounts.google.com/o/oauth2/auth\"\n token_url: \"https://oauth2.googleapis.com/token\"\n user_info_url: \"https://www.googleapis.com/oauth2/v2/userinfo\"\n scopes: [\"openid\", \"email\", \"profile\"]\n response_type: \"code\"\n grant_type: \"authorization_code\"\n # Google specific claim mapping\n username_claim: \"email\"\n groups_claim: null # Google doesn't provide groups in basic scope\n email_claim: \"email\"\n name_claim: \"name\"\n enabled: \"${GOOGLE_ENABLED}\"\n\n# Default session settings\nsession:\n max_age_seconds: 28800 # 8 hours\n cookie_name: \"mcp_oauth_session\"\n secure: true # Set to false for development\n httponly: true\n samesite: \"lax\"\n domain: \"${SESSION_COOKIE_DOMAIN}\" # Set to your domain (with leading dot) to share cookies across subdomains, e.g., \".example.com\"\n\n# Registry integration settings\nregistry:\n callback_url: \"${REGISTRY_URL}/auth/callback\"\n success_redirect: \"${REGISTRY_URL}/\"\n error_redirect: \"${REGISTRY_URL}/login\" " }, { "path": "auth_server/providers/__init__.py", "content": "\"\"\"Authentication provider package for MCP Gateway Registry.\"\"\"\n\nfrom .auth0 import Auth0Provider\nfrom .base import AuthProvider\nfrom .cognito import CognitoProvider\nfrom .entra import EntraIdProvider\nfrom .factory import get_auth_provider\nfrom .keycloak import KeycloakProvider\nfrom .okta import OktaProvider\n\n__all__ = [\n \"Auth0Provider\",\n \"AuthProvider\",\n \"CognitoProvider\",\n \"EntraIdProvider\",\n \"KeycloakProvider\",\n \"OktaProvider\",\n \"get_auth_provider\",\n]\n" }, { "path": "auth_server/providers/auth0.py", "content": "\"\"\"Auth0 authentication provider implementation.\"\"\"\n\nimport logging\nimport os\nimport time\nfrom typing import Any\nfrom urllib.parse import urlencode\n\nimport jwt\nimport requests\n\nfrom .base import AuthProvider\n\n# Constants for self-signed token validation\nJWT_ISSUER = os.environ.get(\"JWT_ISSUER\", \"mcp-auth-server\")\nJWT_AUDIENCE = os.environ.get(\"JWT_AUDIENCE\", \"mcp-registry\")\nSECRET_KEY = os.environ.get(\"SECRET_KEY\", \"development-secret-key\")\n\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass Auth0Provider(AuthProvider):\n \"\"\"Auth0 authentication provider implementation.\n\n This provider implements OAuth2/OIDC authentication using Auth0.\n It supports:\n - User authentication via OAuth2 authorization code flow\n - Machine-to-machine authentication via client credentials flow\n - JWT token validation using Auth0 JWKS\n - Group-based authorization via custom claims or Auth0 Organizations\n \"\"\"\n\n def __init__(\n self,\n domain: str,\n client_id: str,\n client_secret: str,\n audience: str | None = None,\n m2m_client_id: str | None = None,\n m2m_client_secret: str | None = None,\n groups_claim: str = \"https://mcp-gateway/groups\",\n ):\n \"\"\"Initialize Auth0 provider.\n\n Args:\n domain: Auth0 domain (e.g., 'your-tenant.auth0.com')\n client_id: OAuth2 client ID for web authentication\n client_secret: OAuth2 client secret for web authentication\n audience: API audience identifier for access tokens\n m2m_client_id: Optional M2M client ID (defaults to client_id)\n m2m_client_secret: Optional M2M client secret (defaults to client_secret)\n groups_claim: Custom claim name for groups in the ID/access token.\n Auth0 requires a namespaced claim via a Rule/Action\n (e.g., 'https://mcp-gateway/groups'). Defaults to\n 'https://mcp-gateway/groups'.\n \"\"\"\n self.domain = domain.rstrip(\"/\")\n self.client_id = client_id\n self.client_secret = client_secret\n self.audience = audience\n self.m2m_client_id = m2m_client_id or client_id\n self.m2m_client_secret = m2m_client_secret or client_secret\n self.groups_claim = groups_claim\n\n # JWKS cache\n self._jwks_cache: dict[str, Any] | None = None\n self._jwks_cache_time: float = 0\n self._jwks_cache_ttl: int = 3600 # 1 hour\n\n # Auth0 endpoints\n base_url = f\"https://{self.domain}\"\n self.auth_url = f\"{base_url}/authorize\"\n self.token_url = f\"{base_url}/oauth/token\"\n self.userinfo_url = f\"{base_url}/userinfo\"\n self.jwks_url = f\"{base_url}/.well-known/jwks.json\"\n self.logout_url = f\"{base_url}/v2/logout\"\n self.issuer = f\"{base_url}/\"\n\n logger.debug(f\"Initialized Auth0 provider for domain '{domain}'\")\n\n def validate_token(self, token: str, **kwargs: Any) -> dict[str, Any]:\n \"\"\"Validate Auth0 JWT token.\n\n Args:\n token: The JWT access token to validate\n **kwargs: Additional provider-specific arguments\n\n Returns:\n Dictionary containing:\n - valid: True if token is valid\n - username: User's sub or nickname claim\n - email: User's email address\n - groups: List of group memberships from custom claim\n - scopes: List of token scopes\n - client_id: Client ID that issued the token\n - method: 'auth0'\n - data: Raw token claims\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n try:\n logger.debug(\"Validating Auth0 JWT token\")\n\n # First check if this is a self-signed token from our auth server\n try:\n unverified_claims = jwt.decode(token, options={\"verify_signature\": False})\n if unverified_claims.get(\"iss\") == JWT_ISSUER:\n logger.debug(\"Token appears to be self-signed, validating...\")\n return self._validate_self_signed_token(token)\n except Exception as e:\n logger.debug(f\"Not a self-signed token: {e}\")\n\n # Get JWKS for validation\n jwks = self.get_jwks()\n\n # Decode token header to get key ID\n unverified_header = jwt.get_unverified_header(token)\n kid = unverified_header.get(\"kid\")\n\n if not kid:\n raise ValueError(\"Token missing 'kid' in header\")\n\n # Find matching key\n signing_key = None\n for key in jwks.get(\"keys\", []):\n if key.get(\"kid\") == kid:\n from jwt import PyJWK\n\n signing_key = PyJWK(key).key\n break\n\n if not signing_key:\n raise ValueError(f\"No matching key found for kid: {kid}\")\n\n # Build audience list for validation\n valid_audiences = [self.client_id]\n if self.audience:\n valid_audiences.append(self.audience)\n\n # Validate and decode token\n claims = jwt.decode(\n token,\n signing_key,\n algorithms=[\"RS256\"],\n issuer=self.issuer,\n audience=valid_audiences,\n options={\"verify_exp\": True, \"verify_iat\": True, \"verify_aud\": True},\n )\n\n logger.debug(\n f\"Token validation successful for user: \"\n f\"{claims.get('nickname', claims.get('sub', 'unknown'))}\"\n )\n\n # Extract groups from custom namespaced claim\n groups = claims.get(self.groups_claim, [])\n if not groups:\n # Fallback: check permissions claim (Auth0 RBAC)\n groups = claims.get(\"permissions\", [])\n\n return {\n \"valid\": True,\n \"username\": claims.get(\"nickname\", claims.get(\"sub\")),\n \"email\": claims.get(\"email\"),\n \"groups\": groups,\n \"scopes\": claims.get(\"scope\", \"\").split() if claims.get(\"scope\") else [],\n \"client_id\": claims.get(\"azp\", self.client_id),\n \"method\": \"auth0\",\n \"data\": claims,\n }\n\n except jwt.ExpiredSignatureError as e:\n logger.warning(\"Token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\") from e\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Token validation failed: Invalid token - {e}\")\n raise ValueError(f\"Invalid token: {e}\") from e\n except Exception as e:\n logger.error(f\"Auth0 token validation error: {e}\")\n raise ValueError(f\"Token validation failed: {e}\") from e\n\n def _validate_self_signed_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a self-signed JWT token generated by our auth server.\n\n Self-signed tokens are generated for OAuth users to use for programmatic\n API access. They contain the user's identity, groups, and scopes.\n\n Args:\n token: The self-signed JWT token to validate\n\n Returns:\n Dictionary containing validation results\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n try:\n claims = jwt.decode(\n token,\n SECRET_KEY,\n algorithms=[\"HS256\"],\n audience=JWT_AUDIENCE,\n issuer=JWT_ISSUER,\n options={\"verify_exp\": True, \"verify_iat\": True, \"verify_aud\": True},\n )\n\n # Check token_use claim\n token_use = claims.get(\"token_use\")\n if token_use != \"access\": # nosec B105 - OAuth2 token type validation per RFC 6749, not a password\n raise ValueError(f\"Invalid token_use: {token_use}\")\n\n # Extract scopes from claims\n scopes = []\n if \"scope\" in claims:\n scope_value = claims[\"scope\"]\n if isinstance(scope_value, str):\n scopes = scope_value.split() if scope_value else []\n elif isinstance(scope_value, list):\n scopes = scope_value\n\n # Extract groups from claims\n groups = claims.get(\"groups\", [])\n if isinstance(groups, str):\n groups = [groups]\n\n logger.info(\n f\"Successfully validated self-signed token for user: {claims.get('sub')}, \"\n f\"groups: {groups}, scopes: {scopes}\"\n )\n\n return {\n \"valid\": True,\n \"method\": \"self_signed\",\n \"data\": claims,\n \"client_id\": claims.get(\"client_id\", \"user-generated\"),\n \"username\": claims.get(\"sub\", \"\"),\n \"email\": claims.get(\"email\", \"\"),\n \"expires_at\": claims.get(\"exp\"),\n \"scopes\": scopes,\n \"groups\": groups,\n \"token_type\": \"user_generated\",\n }\n\n except jwt.ExpiredSignatureError as e:\n logger.warning(\"Self-signed token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\") from e\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Self-signed token validation failed: {e}\")\n raise ValueError(f\"Invalid self-signed token: {e}\") from e\n except Exception as e:\n logger.error(f\"Self-signed token validation error: {e}\")\n raise ValueError(f\"Self-signed token validation failed: {e}\") from e\n\n def get_jwks(self) -> dict[str, Any]:\n \"\"\"Get JSON Web Key Set from Auth0 with caching.\n\n Returns:\n Dictionary containing the JWKS data\n\n Raises:\n ValueError: If JWKS cannot be retrieved\n \"\"\"\n current_time = time.time()\n\n # Check if cache is still valid\n if self._jwks_cache and (current_time - self._jwks_cache_time) < self._jwks_cache_ttl:\n logger.debug(\"Using cached JWKS\")\n return self._jwks_cache\n\n try:\n logger.debug(f\"Fetching JWKS from {self.jwks_url}\")\n response = requests.get(self.jwks_url, timeout=10)\n response.raise_for_status()\n\n self._jwks_cache = response.json()\n self._jwks_cache_time = current_time\n\n logger.debug(\"JWKS fetched and cached successfully\")\n return self._jwks_cache\n\n except Exception as e:\n logger.error(f\"Failed to retrieve JWKS from Auth0: {e}\")\n raise ValueError(f\"Cannot retrieve JWKS: {e}\")\n\n def exchange_code_for_token(self, code: str, redirect_uri: str) -> dict[str, Any]:\n \"\"\"Exchange authorization code for access token.\n\n Args:\n code: Authorization code from OAuth2 flow\n redirect_uri: Redirect URI used in the authorization request\n\n Returns:\n Dictionary containing token response\n\n Raises:\n ValueError: If code exchange fails\n \"\"\"\n try:\n logger.debug(\"Exchanging authorization code for token\")\n\n data = {\n \"grant_type\": \"authorization_code\",\n \"code\": code,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n \"redirect_uri\": redirect_uri,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token exchange successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to exchange code for token: {e}\")\n raise ValueError(f\"Token exchange failed: {e}\")\n\n def get_user_info(self, access_token: str) -> dict[str, Any]:\n \"\"\"Get user information from Auth0.\n\n Args:\n access_token: Valid access token\n\n Returns:\n Dictionary containing user information\n\n Raises:\n ValueError: If user info cannot be retrieved\n \"\"\"\n try:\n logger.debug(\"Fetching user info from Auth0\")\n\n headers = {\"Authorization\": f\"Bearer {access_token}\"}\n response = requests.get(self.userinfo_url, headers=headers, timeout=10)\n response.raise_for_status()\n\n user_info = response.json()\n logger.debug(f\"User info retrieved for: {user_info.get('nickname', 'unknown')}\")\n\n return user_info\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get user info: {e}\")\n raise ValueError(f\"User info retrieval failed: {e}\")\n\n def get_auth_url(self, redirect_uri: str, state: str, scope: str | None = None) -> str:\n \"\"\"Get Auth0 authorization URL.\n\n Args:\n redirect_uri: URI to redirect to after authorization\n state: State parameter for CSRF protection\n scope: Optional scope parameter (defaults to openid email profile)\n\n Returns:\n Full authorization URL\n \"\"\"\n logger.debug(f\"Generating auth URL with redirect_uri: {redirect_uri}\")\n\n params = {\n \"client_id\": self.client_id,\n \"response_type\": \"code\",\n \"scope\": scope or \"openid email profile\",\n \"redirect_uri\": redirect_uri,\n \"state\": state,\n }\n\n # Include audience if configured (required for API access tokens)\n if self.audience:\n params[\"audience\"] = self.audience\n\n auth_url = f\"{self.auth_url}?{urlencode(params)}\"\n logger.debug(f\"Generated auth URL: {auth_url}\")\n\n return auth_url\n\n def get_logout_url(self, redirect_uri: str) -> str:\n \"\"\"Get Auth0 logout URL.\n\n Auth0 uses 'returnTo' parameter and requires client_id.\n\n Args:\n redirect_uri: URI to redirect to after logout\n\n Returns:\n Full logout URL\n \"\"\"\n logger.debug(f\"Generating logout URL with redirect_uri: {redirect_uri}\")\n\n params = {\"client_id\": self.client_id, \"returnTo\": redirect_uri}\n\n logout_url = f\"{self.logout_url}?{urlencode(params)}\"\n logger.debug(f\"Generated logout URL: {logout_url}\")\n\n return logout_url\n\n def refresh_token(self, refresh_token: str) -> dict[str, Any]:\n \"\"\"Refresh an access token using a refresh token.\n\n Args:\n refresh_token: The refresh token\n\n Returns:\n Dictionary containing new token response\n\n Raises:\n ValueError: If token refresh fails\n \"\"\"\n try:\n logger.debug(\"Refreshing access token\")\n\n data = {\n \"grant_type\": \"refresh_token\",\n \"refresh_token\": refresh_token,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token refresh successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to refresh token: {e}\")\n raise ValueError(f\"Token refresh failed: {e}\")\n\n def validate_m2m_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a machine-to-machine token.\n\n Args:\n token: The M2M access token to validate\n\n Returns:\n Dictionary containing validation result\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n return self.validate_token(token)\n\n def get_m2m_token(\n self,\n client_id: str | None = None,\n client_secret: str | None = None,\n scope: str | None = None,\n ) -> dict[str, Any]:\n \"\"\"Get machine-to-machine token using client credentials.\n\n Auth0 M2M tokens require an audience parameter to specify which API\n the token is intended for.\n\n Args:\n client_id: Optional client ID (uses M2M default if not provided)\n client_secret: Optional client secret (uses M2M default if not provided)\n scope: Optional scope for the token\n\n Returns:\n Dictionary containing token response\n\n Raises:\n ValueError: If token generation fails\n \"\"\"\n try:\n logger.debug(\"Requesting M2M token using client credentials\")\n\n data: dict[str, str] = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id or self.m2m_client_id,\n \"client_secret\": client_secret or self.m2m_client_secret,\n }\n\n # Auth0 requires audience for M2M tokens\n if self.audience:\n data[\"audience\"] = self.audience\n\n if scope:\n data[\"scope\"] = scope\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"M2M token generation successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get M2M token: {e}\")\n raise ValueError(f\"M2M token generation failed: {e}\")\n\n def extract_user_from_tokens(self, token_data: dict[str, Any]) -> dict[str, Any]:\n \"\"\"Extract user information from Auth0 token response.\n\n Parses the ID token from the OAuth2 token exchange response to extract\n user identity and group memberships. The ID token is validated for\n issuer and audience claims to prevent token forgery.\n\n Groups are extracted from a custom namespaced claim (e.g.,\n 'https://mcp-gateway/groups') which must be configured via an\n Auth0 Action or Rule. If no groups are found, falls back to the\n 'permissions' claim from Auth0 RBAC.\n\n Args:\n token_data: Token response from Auth0 containing 'id_token'\n and 'access_token' keys\n\n Returns:\n Dictionary containing:\n - username: User's nickname, email, or sub claim\n - email: User's email address\n - name: User's display name\n - groups: List of group memberships\n\n Raises:\n ValueError: If ID token is missing or cannot be parsed\n \"\"\"\n if \"id_token\" not in token_data:\n raise ValueError(\"Missing ID token in Auth0 response\")\n\n try:\n # Validate issuer and audience claims on the ID token.\n # Signature verification is skipped because this token was received\n # directly from Auth0's token endpoint over TLS (OIDC Core 3.1.3.7).\n id_token_claims = jwt.decode(\n token_data[\"id_token\"],\n options={\n \"verify_signature\": False,\n \"verify_iss\": True,\n \"verify_aud\": True,\n \"verify_exp\": True,\n },\n issuer=self.issuer,\n audience=self.client_id,\n )\n logger.info(f\"Auth0 ID token claims decoded for sub: {id_token_claims.get('sub')}\")\n\n # Extract groups from custom namespaced claim.\n # Requires an Auth0 Action or Rule to add groups to the ID token.\n # Example Action: api.idToken.setCustomClaim(\"https://mcp-gateway/groups\", event.user.groups)\n groups = id_token_claims.get(self.groups_claim, [])\n if not groups:\n # Fallback: check permissions claim (Auth0 RBAC)\n groups = id_token_claims.get(\"permissions\", [])\n\n return {\n \"username\": id_token_claims.get(\"nickname\")\n or id_token_claims.get(\"email\")\n or id_token_claims.get(\"sub\"),\n \"email\": id_token_claims.get(\"email\"),\n \"name\": id_token_claims.get(\"name\") or id_token_claims.get(\"given_name\"),\n \"groups\": groups,\n }\n\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Auth0 ID token parsing failed: {e}\")\n raise ValueError(f\"Failed to parse Auth0 ID token: {e}\") from e\n\n def get_provider_info(self) -> dict[str, Any]:\n \"\"\"Get provider-specific information.\n\n Returns:\n Dictionary containing provider configuration and endpoints\n \"\"\"\n return {\n \"provider_type\": \"auth0\",\n \"domain\": self.domain,\n \"client_id\": self.client_id,\n \"audience\": self.audience,\n \"endpoints\": {\n \"auth\": self.auth_url,\n \"token\": self.token_url,\n \"userinfo\": self.userinfo_url,\n \"jwks\": self.jwks_url,\n \"logout\": self.logout_url,\n },\n \"issuer\": self.issuer,\n }\n" }, { "path": "auth_server/providers/base.py", "content": "\"\"\"Base authentication provider interface.\"\"\"\n\nimport logging\nfrom abc import ABC, abstractmethod\nfrom typing import Any\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass AuthProvider(ABC):\n \"\"\"Abstract base class for authentication providers.\"\"\"\n\n @abstractmethod\n def validate_token(self, token: str, **kwargs: Any) -> dict[str, Any]:\n \"\"\"Validate an access token and return user info.\n\n Args:\n token: The access token to validate\n **kwargs: Additional provider-specific arguments\n\n Returns:\n Dictionary containing:\n - valid: Boolean indicating if token is valid\n - username: User's username\n - email: User's email address\n - groups: List of group memberships\n - scopes: List of token scopes\n - client_id: Client ID that issued the token\n - method: Authentication method used\n - data: Raw token claims/data\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n pass\n\n @abstractmethod\n def get_jwks(self) -> dict[str, Any]:\n \"\"\"Get JSON Web Key Set for token validation.\n\n Returns:\n Dictionary containing the JWKS data\n\n Raises:\n ValueError: If JWKS cannot be retrieved\n \"\"\"\n pass\n\n @abstractmethod\n def exchange_code_for_token(self, code: str, redirect_uri: str) -> dict[str, Any]:\n \"\"\"Exchange authorization code for access token.\n\n Args:\n code: Authorization code from OAuth2 flow\n redirect_uri: Redirect URI used in the authorization request\n\n Returns:\n Dictionary containing token response:\n - access_token: The access token\n - id_token: The ID token (if available)\n - refresh_token: The refresh token (if available)\n - token_type: Type of token (usually \"Bearer\")\n - expires_in: Token expiration time in seconds\n\n Raises:\n ValueError: If code exchange fails\n \"\"\"\n pass\n\n @abstractmethod\n def get_user_info(self, access_token: str) -> dict[str, Any]:\n \"\"\"Get user information from access token.\n\n Args:\n access_token: Valid access token\n\n Returns:\n Dictionary containing user information:\n - username: User's username\n - email: User's email\n - groups: User's group memberships\n - Additional provider-specific fields\n\n Raises:\n ValueError: If user info cannot be retrieved\n \"\"\"\n pass\n\n @abstractmethod\n def get_auth_url(self, redirect_uri: str, state: str, scope: str | None = None) -> str:\n \"\"\"Get authorization URL for OAuth2 flow.\n\n Args:\n redirect_uri: URI to redirect to after authorization\n state: State parameter for CSRF protection\n scope: Optional scope parameter (defaults to provider's default)\n\n Returns:\n Full authorization URL\n \"\"\"\n pass\n\n @abstractmethod\n def get_logout_url(self, redirect_uri: str) -> str:\n \"\"\"Get logout URL.\n\n Args:\n redirect_uri: URI to redirect to after logout\n\n Returns:\n Full logout URL\n \"\"\"\n pass\n\n @abstractmethod\n def refresh_token(self, refresh_token: str) -> dict[str, Any]:\n \"\"\"Refresh an access token using a refresh token.\n\n Args:\n refresh_token: The refresh token\n\n Returns:\n Dictionary containing new token response\n\n Raises:\n ValueError: If token refresh fails\n \"\"\"\n pass\n\n @abstractmethod\n def validate_m2m_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a machine-to-machine token.\n\n Args:\n token: The M2M access token to validate\n\n Returns:\n Dictionary containing validation result\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n pass\n\n @abstractmethod\n def get_m2m_token(\n self,\n client_id: str | None = None,\n client_secret: str | None = None,\n scope: str | None = None,\n ) -> dict[str, Any]:\n \"\"\"Get a machine-to-machine token using client credentials.\n\n Args:\n client_id: Optional client ID (uses default if not provided)\n client_secret: Optional client secret (uses default if not provided)\n scope: Optional scope for the token\n\n Returns:\n Dictionary containing token response\n\n Raises:\n ValueError: If token generation fails\n \"\"\"\n pass\n" }, { "path": "auth_server/providers/cognito.py", "content": "\"\"\"AWS Cognito authentication provider implementation.\"\"\"\n\nimport logging\nimport time\nfrom typing import Any\nfrom urllib.parse import urlencode\n\nimport jwt\nimport requests\n\nfrom .base import AuthProvider\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass CognitoProvider(AuthProvider):\n \"\"\"AWS Cognito authentication provider implementation.\"\"\"\n\n def __init__(\n self,\n user_pool_id: str,\n client_id: str,\n client_secret: str,\n region: str,\n domain: str | None = None,\n ):\n \"\"\"Initialize Cognito provider.\n\n Args:\n user_pool_id: AWS Cognito User Pool ID\n client_id: OAuth2 client ID\n client_secret: OAuth2 client secret\n region: AWS region\n domain: Optional custom domain name\n \"\"\"\n self.user_pool_id = user_pool_id\n self.client_id = client_id\n self.client_secret = client_secret\n self.region = region\n self.domain = domain\n\n # Cache for JWKS\n self._jwks_cache: dict[str, Any] | None = None\n self._jwks_cache_time: float = 0\n self._jwks_cache_ttl: int = 3600 # 1 hour\n\n # Cognito endpoints\n if domain:\n self.cognito_domain = f\"https://{domain}.auth.{region}.amazoncognito.com\"\n else:\n user_pool_id_clean = user_pool_id.replace(\"_\", \"\")\n self.cognito_domain = f\"https://{user_pool_id_clean}.auth.{region}.amazoncognito.com\"\n\n self.token_url = f\"{self.cognito_domain}/oauth2/token\"\n self.auth_url = f\"{self.cognito_domain}/oauth2/authorize\"\n self.userinfo_url = f\"{self.cognito_domain}/oauth2/userInfo\"\n self.jwks_url = (\n f\"https://cognito-idp.{region}.amazonaws.com/{user_pool_id}/.well-known/jwks.json\"\n )\n self.logout_url = f\"{self.cognito_domain}/logout\"\n self.issuer = f\"https://cognito-idp.{region}.amazonaws.com/{user_pool_id}\"\n\n logger.debug(\n f\"Initialized Cognito provider for user pool '{user_pool_id}' in region '{region}'\"\n )\n\n def validate_token(self, token: str, **kwargs: Any) -> dict[str, Any]:\n \"\"\"Validate Cognito JWT token.\"\"\"\n try:\n logger.debug(\"Validating Cognito JWT token\")\n\n # Get JWKS for validation\n jwks = self.get_jwks()\n\n # Decode token header to get key ID\n unverified_header = jwt.get_unverified_header(token)\n kid = unverified_header.get(\"kid\")\n\n if not kid:\n raise ValueError(\"Token missing 'kid' in header\")\n\n # Find matching key\n signing_key = None\n for key in jwks.get(\"keys\", []):\n if key.get(\"kid\") == kid:\n from jwt import PyJWK\n\n signing_key = PyJWK(key).key\n break\n\n if not signing_key:\n raise ValueError(f\"No matching key found for kid: {kid}\")\n\n # Validate and decode token\n claims = jwt.decode(\n token,\n signing_key,\n algorithms=[\"RS256\"],\n issuer=self.issuer,\n audience=self.client_id,\n options={\"verify_exp\": True, \"verify_iat\": True, \"verify_aud\": True},\n )\n\n logger.debug(\n f\"Token validation successful for user: {claims.get('username', 'unknown')}\"\n )\n\n # Extract user info from claims\n return {\n \"valid\": True,\n \"username\": claims.get(\"username\", claims.get(\"sub\")),\n \"email\": claims.get(\"email\"),\n \"groups\": claims.get(\"cognito:groups\", []),\n \"scopes\": claims.get(\"scope\", \"\").split() if claims.get(\"scope\") else [],\n \"client_id\": claims.get(\"client_id\", self.client_id),\n \"method\": \"cognito\",\n \"data\": claims,\n }\n\n except jwt.ExpiredSignatureError:\n logger.warning(\"Token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\")\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Token validation failed: Invalid token - {e}\")\n raise ValueError(f\"Invalid token: {e}\")\n except Exception as e:\n logger.error(f\"Cognito token validation error: {e}\")\n raise ValueError(f\"Token validation failed: {e}\")\n\n def get_jwks(self) -> dict[str, Any]:\n \"\"\"Get JSON Web Key Set from Cognito with caching.\"\"\"\n current_time = time.time()\n\n # Check if cache is still valid\n if self._jwks_cache and (current_time - self._jwks_cache_time) < self._jwks_cache_ttl:\n logger.debug(\"Using cached JWKS\")\n return self._jwks_cache\n\n try:\n logger.debug(f\"Fetching JWKS from {self.jwks_url}\")\n response = requests.get(self.jwks_url, timeout=10)\n response.raise_for_status()\n\n self._jwks_cache = response.json()\n self._jwks_cache_time = current_time\n\n logger.debug(\"JWKS fetched and cached successfully\")\n return self._jwks_cache\n\n except Exception as e:\n logger.error(f\"Failed to retrieve JWKS from Cognito: {e}\")\n raise ValueError(f\"Cannot retrieve JWKS: {e}\")\n\n def exchange_code_for_token(self, code: str, redirect_uri: str) -> dict[str, Any]:\n \"\"\"Exchange authorization code for access token.\"\"\"\n try:\n logger.debug(\"Exchanging authorization code for token\")\n\n data = {\n \"grant_type\": \"authorization_code\",\n \"code\": code,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n \"redirect_uri\": redirect_uri,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token exchange successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to exchange code for token: {e}\")\n raise ValueError(f\"Token exchange failed: {e}\")\n\n def get_user_info(self, access_token: str) -> dict[str, Any]:\n \"\"\"Get user information from Cognito.\"\"\"\n try:\n logger.debug(\"Fetching user info from Cognito\")\n\n headers = {\"Authorization\": f\"Bearer {access_token}\"}\n response = requests.get(self.userinfo_url, headers=headers, timeout=10)\n response.raise_for_status()\n\n user_info = response.json()\n logger.debug(f\"User info retrieved for: {user_info.get('username', 'unknown')}\")\n\n return user_info\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get user info: {e}\")\n raise ValueError(f\"User info retrieval failed: {e}\")\n\n def get_auth_url(self, redirect_uri: str, state: str, scope: str | None = None) -> str:\n \"\"\"Get Cognito authorization URL.\"\"\"\n logger.debug(f\"Generating auth URL with redirect_uri: {redirect_uri}\")\n\n params = {\n \"client_id\": self.client_id,\n \"response_type\": \"code\",\n \"scope\": scope or \"openid email profile\",\n \"redirect_uri\": redirect_uri,\n \"state\": state,\n }\n\n auth_url = f\"{self.auth_url}?{urlencode(params)}\"\n logger.debug(f\"Generated auth URL: {auth_url}\")\n\n return auth_url\n\n def get_logout_url(self, redirect_uri: str) -> str:\n \"\"\"Get Cognito logout URL.\"\"\"\n logger.debug(f\"Generating logout URL with redirect_uri: {redirect_uri}\")\n\n params = {\"client_id\": self.client_id, \"logout_uri\": redirect_uri}\n\n logout_url = f\"{self.logout_url}?{urlencode(params)}\"\n logger.debug(f\"Generated logout URL: {logout_url}\")\n\n return logout_url\n\n def refresh_token(self, refresh_token: str) -> dict[str, Any]:\n \"\"\"Refresh an access token using a refresh token.\"\"\"\n try:\n logger.debug(\"Refreshing access token\")\n\n data = {\n \"grant_type\": \"refresh_token\",\n \"refresh_token\": refresh_token,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token refresh successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to refresh token: {e}\")\n raise ValueError(f\"Token refresh failed: {e}\")\n\n def validate_m2m_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a machine-to-machine token.\"\"\"\n # M2M tokens use the same validation as regular tokens in Cognito\n return self.validate_token(token)\n\n def get_m2m_token(\n self,\n client_id: str | None = None,\n client_secret: str | None = None,\n scope: str | None = None,\n ) -> dict[str, Any]:\n \"\"\"Get machine-to-machine token using client credentials.\"\"\"\n try:\n logger.debug(\"Requesting M2M token using client credentials\")\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id or self.client_id,\n \"client_secret\": client_secret or self.client_secret,\n }\n\n if scope:\n data[\"scope\"] = scope\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"M2M token generation successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get M2M token: {e}\")\n raise ValueError(f\"M2M token generation failed: {e}\")\n\n def get_provider_info(self) -> dict[str, Any]:\n \"\"\"Get provider-specific information.\"\"\"\n return {\n \"provider_type\": \"cognito\",\n \"user_pool_id\": self.user_pool_id,\n \"region\": self.region,\n \"client_id\": self.client_id,\n \"endpoints\": {\n \"auth\": self.auth_url,\n \"token\": self.token_url,\n \"userinfo\": self.userinfo_url,\n \"jwks\": self.jwks_url,\n \"logout\": self.logout_url,\n },\n \"issuer\": self.issuer,\n }\n" }, { "path": "auth_server/providers/entra.py", "content": "\"\"\"Microsoft Entra ID (Azure AD) authentication provider implementation.\"\"\"\n\nimport logging\nimport os\nimport time\nfrom typing import Any\nfrom urllib.parse import urlencode\n\nimport jwt\nimport requests\n\nfrom .base import AuthProvider\n\n# Constants for self-signed token validation\nJWT_ISSUER = os.environ.get(\"JWT_ISSUER\", \"mcp-auth-server\")\nJWT_AUDIENCE = os.environ.get(\"JWT_AUDIENCE\", \"mcp-registry\")\nSECRET_KEY = os.environ.get(\"SECRET_KEY\", \"development-secret-key\")\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n# Default Entra ID login base URL\nDEFAULT_ENTRA_LOGIN_BASE_URL = \"https://login.microsoftonline.com\"\n\n\nclass EntraIdProvider(AuthProvider):\n \"\"\"Microsoft Entra ID (Azure AD) authentication provider.\n\n This provider implements OAuth2/OIDC authentication using Microsoft Entra ID\n (formerly Azure Active Directory). It supports:\n - User authentication via OAuth2 authorization code flow\n - Machine-to-machine authentication via client credentials flow\n - JWT token validation using Azure AD JWKS\n - Group-based authorization with Azure AD security groups\n \"\"\"\n\n def __init__(self, tenant_id: str, client_id: str, client_secret: str):\n \"\"\"Initialize Entra ID provider.\n\n Args:\n tenant_id: Azure AD tenant ID (GUID)\n client_id: App registration client ID (GUID)\n client_secret: App registration client secret\n \"\"\"\n self.tenant_id = tenant_id\n self.client_id = client_id\n self.client_secret = client_secret\n\n # JWKS cache\n self._jwks_cache: dict[str, Any] | None = None\n self._jwks_cache_time: float = 0\n self._jwks_cache_ttl: int = 3600 # 1 hour\n\n # Get login base URL from environment variable or use default\n login_base_url = os.environ.get(\"ENTRA_LOGIN_BASE_URL\", DEFAULT_ENTRA_LOGIN_BASE_URL)\n\n # Entra ID endpoints\n base_url = f\"{login_base_url}/{tenant_id}\"\n self.auth_url = f\"{base_url}/oauth2/v2.0/authorize\"\n self.token_url = f\"{base_url}/oauth2/v2.0/token\"\n self.userinfo_url = \"https://graph.microsoft.com/oidc/userinfo\"\n self.jwks_url = f\"{base_url}/discovery/v2.0/keys\"\n self.logout_url = f\"{base_url}/oauth2/v2.0/logout\"\n\n # Entra ID supports two issuer formats:\n # v2.0 endpoint: https://login.microsoftonline.com/{tenant}/v2.0\n # v1.0/M2M endpoint: https://sts.windows.net/{tenant}/\n self.issuer_v2 = f\"{base_url}/v2.0\"\n self.issuer_v1 = f\"https://sts.windows.net/{tenant_id}/\"\n self.valid_issuers = [self.issuer_v2, self.issuer_v1]\n\n logger.debug(f\"Initialized Entra ID provider for tenant '{tenant_id}'\")\n\n def validate_token(self, token: str, **kwargs: Any) -> dict[str, Any]:\n \"\"\"Validate Entra ID JWT token.\n\n Args:\n token: The JWT access token to validate\n **kwargs: Additional provider-specific arguments\n\n Returns:\n Dictionary containing:\n - valid: True if token is valid\n - username: User's preferred_username or sub claim\n - email: User's email address\n - groups: List of Azure AD group Object IDs\n - scopes: List of token scopes\n - client_id: Client ID that issued the token\n - method: 'entra'\n - data: Raw token claims\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n try:\n logger.debug(\"Validating Entra ID JWT token\")\n\n # First check if this is a self-signed token from our auth server\n try:\n unverified_claims = jwt.decode(token, options={\"verify_signature\": False})\n if unverified_claims.get(\"iss\") == JWT_ISSUER:\n logger.debug(\"Token appears to be self-signed, validating...\")\n return self._validate_self_signed_token(token)\n except Exception as e:\n logger.debug(f\"Not a self-signed token: {e}\")\n\n # Get JWKS for validation\n jwks = self.get_jwks()\n\n # Decode token header to get key ID\n unverified_header = jwt.get_unverified_header(token)\n kid = unverified_header.get(\"kid\")\n\n if not kid:\n raise ValueError(\"Token missing 'kid' in header\")\n\n # Find matching key\n signing_key = None\n for key in jwks.get(\"keys\", []):\n if key.get(\"kid\") == kid:\n from jwt import PyJWK\n\n signing_key = PyJWK(key).key\n break\n\n if not signing_key:\n raise ValueError(f\"No matching key found for kid: {kid}\")\n\n # First, decode without validation to check issuer\n unverified_claims = jwt.decode(token, options={\"verify_signature\": False})\n token_issuer = unverified_claims.get(\"iss\")\n\n # Check if issuer is valid (v1.0 or v2.0)\n if token_issuer not in self.valid_issuers:\n raise ValueError(\n f\"Invalid issuer: {token_issuer}. Expected one of: {self.valid_issuers}\"\n )\n\n # Validate and decode token with the correct issuer\n claims = jwt.decode(\n token,\n signing_key,\n algorithms=[\"RS256\"],\n issuer=token_issuer,\n audience=[self.client_id, f\"api://{self.client_id}\"], # Accept both formats\n options={\"verify_exp\": True, \"verify_iat\": True, \"verify_aud\": True},\n )\n\n logger.debug(\n f\"Token validation successful for user: {claims.get('preferred_username', 'unknown')}\"\n )\n\n # Extract user info from claims\n # For M2M tokens, group memberships are in 'roles' claim instead of 'groups'\n # For user tokens, they're in 'groups' claim\n groups = claims.get(\"groups\", [])\n if not groups and \"roles\" in claims:\n # M2M token - use roles claim as groups\n groups = claims.get(\"roles\", [])\n logger.debug(f\"M2M token detected, using roles claim as groups: {groups}\")\n\n return {\n \"valid\": True,\n \"username\": claims.get(\"preferred_username\", claims.get(\"sub\")),\n \"email\": claims.get(\"email\"),\n \"groups\": groups,\n \"scopes\": claims.get(\"scope\", \"\").split() if claims.get(\"scope\") else [],\n \"client_id\": claims.get(\"azp\", self.client_id),\n \"method\": \"entra\",\n \"data\": claims,\n }\n\n except jwt.ExpiredSignatureError:\n logger.warning(\"Token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\")\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Token validation failed: Invalid token - {e}\")\n raise ValueError(f\"Invalid token: {e}\")\n except Exception as e:\n logger.error(f\"Entra ID token validation error: {e}\")\n raise ValueError(f\"Token validation failed: {e}\")\n\n def _validate_self_signed_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a self-signed JWT token generated by our auth server.\n\n Self-signed tokens are generated for OAuth users to use for programmatic\n API access. They contain the user's identity, groups, and scopes.\n\n Args:\n token: The self-signed JWT token to validate\n\n Returns:\n Dictionary containing validation results\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n try:\n claims = jwt.decode(\n token,\n SECRET_KEY,\n algorithms=[\"HS256\"],\n audience=JWT_AUDIENCE,\n issuer=JWT_ISSUER,\n options={\"verify_exp\": True, \"verify_iat\": True, \"verify_aud\": True},\n )\n\n # Check token_use claim\n token_use = claims.get(\"token_use\")\n if token_use != \"access\": # nosec B105 - OAuth2 token type validation per RFC 6749, not a password\n raise ValueError(f\"Invalid token_use: {token_use}\")\n\n # Extract scopes from claims\n scopes = []\n if \"scope\" in claims:\n scope_value = claims[\"scope\"]\n if isinstance(scope_value, str):\n scopes = scope_value.split() if scope_value else []\n elif isinstance(scope_value, list):\n scopes = scope_value\n\n # Extract groups from claims\n groups = claims.get(\"groups\", [])\n if isinstance(groups, str):\n groups = [groups]\n\n logger.info(\n f\"Successfully validated self-signed token for user: {claims.get('sub')}, \"\n f\"groups: {groups}, scopes: {scopes}\"\n )\n\n return {\n \"valid\": True,\n \"method\": \"self_signed\",\n \"data\": claims,\n \"client_id\": claims.get(\"client_id\", \"user-generated\"),\n \"username\": claims.get(\"sub\", \"\"),\n \"email\": claims.get(\"email\", \"\"),\n \"expires_at\": claims.get(\"exp\"),\n \"scopes\": scopes,\n \"groups\": groups,\n \"token_type\": \"user_generated\",\n }\n\n except jwt.ExpiredSignatureError:\n logger.warning(\"Self-signed token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\")\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Self-signed token validation failed: {e}\")\n raise ValueError(f\"Invalid self-signed token: {e}\")\n except Exception as e:\n logger.error(f\"Self-signed token validation error: {e}\")\n raise ValueError(f\"Self-signed token validation failed: {e}\")\n\n def get_jwks(self) -> dict[str, Any]:\n \"\"\"Get JSON Web Key Set from Entra ID with caching.\n\n Returns:\n Dictionary containing the JWKS data\n\n Raises:\n ValueError: If JWKS cannot be retrieved\n \"\"\"\n current_time = time.time()\n\n # Check if cache is still valid\n if self._jwks_cache and (current_time - self._jwks_cache_time) < self._jwks_cache_ttl:\n logger.debug(\"Using cached JWKS\")\n return self._jwks_cache\n\n try:\n logger.debug(f\"Fetching JWKS from {self.jwks_url}\")\n response = requests.get(self.jwks_url, timeout=10)\n response.raise_for_status()\n\n self._jwks_cache = response.json()\n self._jwks_cache_time = current_time\n\n logger.debug(\"JWKS fetched and cached successfully\")\n return self._jwks_cache\n\n except Exception as e:\n logger.error(f\"Failed to retrieve JWKS from Entra ID: {e}\")\n raise ValueError(f\"Cannot retrieve JWKS: {e}\")\n\n def exchange_code_for_token(self, code: str, redirect_uri: str) -> dict[str, Any]:\n \"\"\"Exchange authorization code for access token.\n\n Args:\n code: Authorization code from OAuth2 flow\n redirect_uri: Redirect URI used in the authorization request\n\n Returns:\n Dictionary containing token response:\n - access_token: The access token\n - id_token: The ID token\n - refresh_token: The refresh token (if available)\n - token_type: \"Bearer\"\n - expires_in: Token expiration time in seconds\n\n Raises:\n ValueError: If code exchange fails\n \"\"\"\n try:\n logger.debug(\"Exchanging authorization code for token\")\n\n data = {\n \"grant_type\": \"authorization_code\",\n \"code\": code,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n \"redirect_uri\": redirect_uri,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token exchange successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to exchange code for token: {e}\")\n raise ValueError(f\"Token exchange failed: {e}\")\n\n def get_user_info(self, access_token: str) -> dict[str, Any]:\n \"\"\"Get user information from Entra ID.\n\n Args:\n access_token: Valid access token\n\n Returns:\n Dictionary containing user information:\n - username: User's preferred_username\n - email: User's email\n - groups: User's group memberships (Object IDs)\n\n Raises:\n ValueError: If user info cannot be retrieved\n \"\"\"\n try:\n logger.debug(\"Fetching user info from Entra ID\")\n\n headers = {\"Authorization\": f\"Bearer {access_token}\"}\n response = requests.get(self.userinfo_url, headers=headers, timeout=10)\n response.raise_for_status()\n\n user_info = response.json()\n logger.debug(\n f\"User info retrieved for: {user_info.get('preferred_username', 'unknown')}\"\n )\n\n return user_info\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get user info: {e}\")\n raise ValueError(f\"User info retrieval failed: {e}\")\n\n def get_auth_url(self, redirect_uri: str, state: str, scope: str | None = None) -> str:\n \"\"\"Get Entra ID authorization URL.\n\n Args:\n redirect_uri: URI to redirect to after authorization\n state: State parameter for CSRF protection\n scope: Optional scope parameter (defaults to openid email profile)\n\n Returns:\n Full authorization URL\n \"\"\"\n logger.debug(f\"Generating auth URL with redirect_uri: {redirect_uri}\")\n\n params = {\n \"client_id\": self.client_id,\n \"response_type\": \"code\",\n \"scope\": scope or \"openid email profile\",\n \"redirect_uri\": redirect_uri,\n \"state\": state,\n }\n\n auth_url = f\"{self.auth_url}?{urlencode(params)}\"\n logger.debug(f\"Generated auth URL: {auth_url}\")\n\n return auth_url\n\n def get_logout_url(self, redirect_uri: str) -> str:\n \"\"\"Get Entra ID logout URL.\n\n Args:\n redirect_uri: URI to redirect to after logout\n\n Returns:\n Full logout URL\n \"\"\"\n logger.debug(f\"Generating logout URL with redirect_uri: {redirect_uri}\")\n\n params = {\"client_id\": self.client_id, \"post_logout_redirect_uri\": redirect_uri}\n\n logout_url = f\"{self.logout_url}?{urlencode(params)}\"\n logger.debug(f\"Generated logout URL: {logout_url}\")\n\n return logout_url\n\n def refresh_token(self, refresh_token: str) -> dict[str, Any]:\n \"\"\"Refresh an access token using a refresh token.\n\n Args:\n refresh_token: The refresh token\n\n Returns:\n Dictionary containing new token response\n\n Raises:\n ValueError: If token refresh fails\n \"\"\"\n try:\n logger.debug(\"Refreshing access token\")\n\n data = {\n \"grant_type\": \"refresh_token\",\n \"refresh_token\": refresh_token,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token refresh successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to refresh token: {e}\")\n raise ValueError(f\"Token refresh failed: {e}\")\n\n def validate_m2m_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a machine-to-machine token.\n\n Args:\n token: The M2M access token to validate\n\n Returns:\n Dictionary containing validation result\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n return self.validate_token(token)\n\n def get_m2m_token(\n self,\n client_id: str | None = None,\n client_secret: str | None = None,\n scope: str | None = None,\n ) -> dict[str, Any]:\n \"\"\"Get machine-to-machine token using client credentials.\n\n This method is used for AI agent authentication using Azure AD service principals.\n Each AI agent should have its own service principal (app registration) in Azure AD.\n\n Args:\n client_id: Optional client ID (uses default if not provided)\n client_secret: Optional client secret (uses default if not provided)\n scope: Optional scope for the token (defaults to .default)\n\n Returns:\n Dictionary containing token response:\n - access_token: The M2M access token\n - token_type: \"Bearer\"\n - expires_in: Token expiration time in seconds\n\n Raises:\n ValueError: If token generation fails\n \"\"\"\n try:\n logger.debug(\"Requesting M2M token using client credentials\")\n\n # Default scope for Entra ID M2M tokens\n if not scope:\n scope = f\"api://{client_id or self.client_id}/.default\"\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id or self.client_id,\n \"client_secret\": client_secret or self.client_secret,\n \"scope\": scope,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"M2M token generation successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get M2M token: {e}\")\n raise ValueError(f\"M2M token generation failed: {e}\")\n\n def initiate_device_code_flow(self, scope: str | None = None) -> dict[str, Any]:\n \"\"\"Initiate device code flow for user authentication.\n\n This allows CLI applications to authenticate users by displaying a code\n that the user enters at a browser URL. The user logs in with their\n credentials and the CLI receives a token on their behalf.\n\n Args:\n scope: OAuth scopes to request (defaults to openid profile email)\n\n Returns:\n Dictionary containing:\n - device_code: Code for polling\n - user_code: Code for user to enter\n - verification_uri: URL for user to visit\n - expires_in: Seconds until codes expire\n - interval: Polling interval in seconds\n - message: User-friendly instruction message\n\n Raises:\n ValueError: If device code request fails\n \"\"\"\n try:\n logger.info(\"Initiating device code flow\")\n\n # Default scopes for user authentication\n if not scope:\n scope = f\"api://{self.client_id}/user_impersonation openid profile email\"\n\n data = {\"client_id\": self.client_id, \"scope\": scope}\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n # Device code endpoint\n device_code_url = self.token_url.replace(\"/token\", \"/devicecode\")\n\n response = requests.post(device_code_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n\n result = response.json()\n logger.info(f\"Device code flow initiated, user_code: {result.get('user_code')}\")\n\n return result\n\n except requests.RequestException as e:\n logger.error(f\"Failed to initiate device code flow: {e}\")\n raise ValueError(f\"Device code flow initiation failed: {e}\")\n\n def poll_device_code_token(\n self, device_code: str, interval: int = 5, timeout: int = 300\n ) -> dict[str, Any]:\n \"\"\"Poll for token after user completes device code authentication.\n\n Args:\n device_code: The device code from initiate_device_code_flow\n interval: Polling interval in seconds (default 5)\n timeout: Maximum time to wait in seconds (default 300)\n\n Returns:\n Dictionary containing token response:\n - access_token: The user's access token\n - token_type: \"Bearer\"\n - expires_in: Token expiration time in seconds\n - refresh_token: Token for refreshing access\n - id_token: OpenID Connect ID token\n\n Raises:\n ValueError: If polling times out or fails\n \"\"\"\n try:\n logger.info(\"Polling for device code token\")\n\n data = {\n \"grant_type\": \"urn:ietf:params:oauth:grant-type:device_code\",\n \"client_id\": self.client_id,\n \"device_code\": device_code,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n start_time = time.time()\n\n while (time.time() - start_time) < timeout:\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n\n if response.status_code == 200:\n token_data = response.json()\n logger.info(\"Device code authentication successful\")\n return token_data\n\n error_data = response.json()\n error = error_data.get(\"error\", \"\")\n\n if error == \"authorization_pending\":\n # User hasn't completed auth yet, keep polling\n logger.debug(\"Authorization pending, continuing to poll\")\n time.sleep(interval)\n continue\n elif error == \"slow_down\":\n # Polling too fast, increase interval\n interval += 5\n logger.debug(f\"Slowing down, new interval: {interval}s\")\n time.sleep(interval)\n continue\n elif error == \"expired_token\":\n raise ValueError(\"Device code expired. Please start over.\")\n elif error == \"access_denied\":\n raise ValueError(\"User denied the authorization request.\")\n else:\n raise ValueError(\n f\"Token request failed: {error_data.get('error_description', error)}\"\n )\n\n raise ValueError(\"Device code authentication timed out\")\n\n except requests.RequestException as e:\n logger.error(f\"Failed to poll device code token: {e}\")\n raise ValueError(f\"Device code token polling failed: {e}\")\n\n def get_provider_info(self) -> dict[str, Any]:\n \"\"\"Get provider-specific information.\n\n Returns:\n Dictionary containing provider configuration and endpoints\n \"\"\"\n return {\n \"provider_type\": \"entra\",\n \"tenant_id\": self.tenant_id,\n \"client_id\": self.client_id,\n \"endpoints\": {\n \"auth\": self.auth_url,\n \"token\": self.token_url,\n \"userinfo\": self.userinfo_url,\n \"jwks\": self.jwks_url,\n \"logout\": self.logout_url,\n },\n \"issuers\": {\"v2\": self.issuer_v2, \"v1\": self.issuer_v1},\n }\n" }, { "path": "auth_server/providers/factory.py", "content": "\"\"\"Factory for creating authentication provider instances.\"\"\"\n\nimport logging\nimport os\n\nfrom .auth0 import Auth0Provider\nfrom .base import AuthProvider\nfrom .cognito import CognitoProvider\nfrom .entra import EntraIdProvider\nfrom .keycloak import KeycloakProvider\nfrom .okta import OktaProvider\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef get_auth_provider(provider_type: str | None = None) -> AuthProvider:\n \"\"\"Factory function to get the appropriate auth provider.\n\n Args:\n provider_type: Type of provider to create ('cognito', 'keycloak', or 'entra').\n If None, uses AUTH_PROVIDER environment variable.\n\n Returns:\n AuthProvider instance configured for the specified provider\n\n Raises:\n ValueError: If provider type is unknown or required config is missing\n \"\"\"\n provider_type = provider_type or os.environ.get(\"AUTH_PROVIDER\", \"cognito\")\n\n logger.info(f\"Creating authentication provider: {provider_type}\")\n\n if provider_type == \"keycloak\":\n return _create_keycloak_provider()\n elif provider_type == \"cognito\":\n return _create_cognito_provider()\n elif provider_type == \"entra\":\n return _create_entra_provider()\n elif provider_type == \"okta\":\n return _create_okta_provider()\n elif provider_type == \"auth0\":\n return _create_auth0_provider()\n else:\n raise ValueError(f\"Unknown auth provider: {provider_type}\")\n\n\ndef _create_keycloak_provider() -> KeycloakProvider:\n \"\"\"Create and configure Keycloak provider.\"\"\"\n # Required configuration\n keycloak_url = os.environ.get(\"KEYCLOAK_URL\")\n keycloak_external_url = os.environ.get(\"KEYCLOAK_EXTERNAL_URL\", keycloak_url)\n realm = os.environ.get(\"KEYCLOAK_REALM\", \"mcp-gateway\")\n client_id = os.environ.get(\"KEYCLOAK_CLIENT_ID\")\n client_secret = os.environ.get(\"KEYCLOAK_CLIENT_SECRET\")\n\n # Optional M2M configuration\n m2m_client_id = os.environ.get(\"KEYCLOAK_M2M_CLIENT_ID\")\n m2m_client_secret = os.environ.get(\"KEYCLOAK_M2M_CLIENT_SECRET\")\n\n # Validate required configuration\n missing_vars = []\n if not keycloak_url:\n missing_vars.append(\"KEYCLOAK_URL\")\n if not client_id:\n missing_vars.append(\"KEYCLOAK_CLIENT_ID\")\n if not client_secret:\n missing_vars.append(\"KEYCLOAK_CLIENT_SECRET\")\n\n if missing_vars:\n raise ValueError(\n f\"Missing required Keycloak configuration: {', '.join(missing_vars)}. \"\n \"Please set these environment variables.\"\n )\n\n logger.info(\n f\"Initializing Keycloak provider for realm '{realm}' at {keycloak_url} (external: {keycloak_external_url})\"\n )\n\n return KeycloakProvider(\n keycloak_url=keycloak_url,\n keycloak_external_url=keycloak_external_url,\n realm=realm,\n client_id=client_id,\n client_secret=client_secret,\n m2m_client_id=m2m_client_id,\n m2m_client_secret=m2m_client_secret,\n )\n\n\ndef _create_cognito_provider() -> CognitoProvider:\n \"\"\"Create and configure Cognito provider.\"\"\"\n # Required configuration\n user_pool_id = os.environ.get(\"COGNITO_USER_POOL_ID\")\n client_id = os.environ.get(\"COGNITO_CLIENT_ID\")\n client_secret = os.environ.get(\"COGNITO_CLIENT_SECRET\")\n region = os.environ.get(\"AWS_REGION\", \"us-east-1\")\n\n # Optional configuration\n domain = os.environ.get(\"COGNITO_DOMAIN\")\n\n # Validate required configuration\n missing_vars = []\n if not user_pool_id:\n missing_vars.append(\"COGNITO_USER_POOL_ID\")\n if not client_id:\n missing_vars.append(\"COGNITO_CLIENT_ID\")\n if not client_secret:\n missing_vars.append(\"COGNITO_CLIENT_SECRET\")\n\n if missing_vars:\n raise ValueError(\n f\"Missing required Cognito configuration: {', '.join(missing_vars)}. \"\n \"Please set these environment variables.\"\n )\n\n logger.info(\n f\"Initializing Cognito provider for user pool '{user_pool_id}' in region '{region}'\"\n )\n\n return CognitoProvider(\n user_pool_id=user_pool_id,\n client_id=client_id,\n client_secret=client_secret,\n region=region,\n domain=domain,\n )\n\n\ndef _create_entra_provider() -> EntraIdProvider:\n \"\"\"Create and configure Entra ID provider.\"\"\"\n # Required configuration\n tenant_id = os.environ.get(\"ENTRA_TENANT_ID\")\n client_id = os.environ.get(\"ENTRA_CLIENT_ID\")\n client_secret = os.environ.get(\"ENTRA_CLIENT_SECRET\")\n\n # Validate required configuration\n missing_vars = []\n if not tenant_id:\n missing_vars.append(\"ENTRA_TENANT_ID\")\n if not client_id:\n missing_vars.append(\"ENTRA_CLIENT_ID\")\n if not client_secret:\n missing_vars.append(\"ENTRA_CLIENT_SECRET\")\n\n if missing_vars:\n raise ValueError(\n f\"Missing required Entra ID configuration: {', '.join(missing_vars)}. \"\n \"Please set these environment variables.\"\n )\n\n logger.info(f\"Initializing Entra ID provider for tenant '{tenant_id}'\")\n\n return EntraIdProvider(tenant_id=tenant_id, client_id=client_id, client_secret=client_secret)\n\n\ndef _create_okta_provider() -> OktaProvider:\n \"\"\"Create and configure Okta provider.\"\"\"\n okta_domain = os.environ.get(\"OKTA_DOMAIN\")\n client_id = os.environ.get(\"OKTA_CLIENT_ID\")\n client_secret = os.environ.get(\"OKTA_CLIENT_SECRET\")\n m2m_client_id = os.environ.get(\"OKTA_M2M_CLIENT_ID\")\n m2m_client_secret = os.environ.get(\"OKTA_M2M_CLIENT_SECRET\")\n\n missing_vars = []\n if not okta_domain:\n missing_vars.append(\"OKTA_DOMAIN\")\n if not client_id:\n missing_vars.append(\"OKTA_CLIENT_ID\")\n if not client_secret:\n missing_vars.append(\"OKTA_CLIENT_SECRET\")\n\n if missing_vars:\n raise ValueError(\n f\"Missing required Okta configuration: {', '.join(missing_vars)}. \"\n \"Please set these environment variables.\"\n )\n\n logger.info(f\"Initializing Okta provider for domain '{okta_domain}'\")\n\n return OktaProvider(\n okta_domain=okta_domain,\n client_id=client_id,\n client_secret=client_secret,\n m2m_client_id=m2m_client_id,\n m2m_client_secret=m2m_client_secret,\n )\n\n\ndef _create_auth0_provider() -> Auth0Provider:\n \"\"\"Create and configure Auth0 provider.\"\"\"\n # Required configuration\n domain = os.environ.get(\"AUTH0_DOMAIN\")\n client_id = os.environ.get(\"AUTH0_CLIENT_ID\")\n client_secret = os.environ.get(\"AUTH0_CLIENT_SECRET\")\n\n # Optional configuration\n audience = os.environ.get(\"AUTH0_AUDIENCE\")\n m2m_client_id = os.environ.get(\"AUTH0_M2M_CLIENT_ID\")\n m2m_client_secret = os.environ.get(\"AUTH0_M2M_CLIENT_SECRET\")\n groups_claim = os.environ.get(\"AUTH0_GROUPS_CLAIM\", \"https://mcp-gateway/groups\")\n\n # Validate required configuration\n missing_vars = []\n if not domain:\n missing_vars.append(\"AUTH0_DOMAIN\")\n if not client_id:\n missing_vars.append(\"AUTH0_CLIENT_ID\")\n if not client_secret:\n missing_vars.append(\"AUTH0_CLIENT_SECRET\")\n\n if missing_vars:\n raise ValueError(\n f\"Missing required Auth0 configuration: {', '.join(missing_vars)}. \"\n \"Please set these environment variables.\"\n )\n\n logger.info(f\"Initializing Auth0 provider for domain '{domain}'\")\n\n return Auth0Provider(\n domain=domain,\n client_id=client_id,\n client_secret=client_secret,\n audience=audience,\n m2m_client_id=m2m_client_id,\n m2m_client_secret=m2m_client_secret,\n groups_claim=groups_claim,\n )\n\n\ndef _get_provider_health_info() -> dict:\n \"\"\"Get health information for the current provider.\"\"\"\n try:\n provider = get_auth_provider()\n if hasattr(provider, \"get_provider_info\"):\n return provider.get_provider_info()\n else:\n return {\n \"provider_type\": os.environ.get(\"AUTH_PROVIDER\", \"cognito\"),\n \"status\": \"unknown\",\n }\n except Exception as e:\n logger.error(f\"Failed to get provider health info: {e}\")\n return {\n \"provider_type\": os.environ.get(\"AUTH_PROVIDER\", \"cognito\"),\n \"status\": \"error\",\n \"error\": str(e),\n }\n" }, { "path": "auth_server/providers/keycloak.py", "content": "\"\"\"Keycloak authentication provider implementation.\"\"\"\n\nimport logging\nimport os\nimport time\nfrom functools import lru_cache\nfrom typing import Any\nfrom urllib.parse import urlencode\n\nimport jwt\nimport requests\n\nfrom .base import AuthProvider\n\n# Constants for self-signed token validation\nJWT_ISSUER = os.environ.get(\"JWT_ISSUER\", \"mcp-auth-server\")\nJWT_AUDIENCE = os.environ.get(\"JWT_AUDIENCE\", \"mcp-registry\")\nSECRET_KEY = os.environ.get(\"SECRET_KEY\", \"development-secret-key\")\n\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass KeycloakProvider(AuthProvider):\n \"\"\"Keycloak authentication provider implementation.\"\"\"\n\n def __init__(\n self,\n keycloak_url: str,\n realm: str,\n client_id: str,\n client_secret: str,\n keycloak_external_url: str | None = None,\n m2m_client_id: str | None = None,\n m2m_client_secret: str | None = None,\n ):\n \"\"\"Initialize Keycloak provider.\n\n Args:\n keycloak_url: Base URL of the Keycloak instance for server-to-server communication\n realm: Keycloak realm name\n client_id: OAuth2 client ID for web authentication\n client_secret: OAuth2 client secret for web authentication\n keycloak_external_url: External URL for browser redirects (defaults to keycloak_url)\n m2m_client_id: Optional M2M client ID (defaults to client_id)\n m2m_client_secret: Optional M2M client secret (defaults to client_secret)\n \"\"\"\n self.keycloak_url = keycloak_url.rstrip(\"/\")\n self.keycloak_external_url = (keycloak_external_url or keycloak_url).rstrip(\"/\")\n self.realm = realm\n self.client_id = client_id\n self.client_secret = client_secret\n self.m2m_client_id = m2m_client_id or client_id\n self.m2m_client_secret = m2m_client_secret or client_secret\n\n # Cache for JWKS and configuration\n self._jwks_cache: dict[str, Any] | None = None\n self._jwks_cache_time: float = 0\n self._jwks_cache_ttl: int = 3600 # 1 hour\n\n # Keycloak endpoints - use internal URL for server-to-server, external for browser redirects\n self.realm_url = f\"{self.keycloak_url}/realms/{realm}\"\n self.external_realm_url = f\"{self.keycloak_external_url}/realms/{realm}\"\n self.token_url = f\"{self.realm_url}/protocol/openid-connect/token\"\n self.auth_url = f\"{self.external_realm_url}/protocol/openid-connect/auth\"\n self.userinfo_url = f\"{self.realm_url}/protocol/openid-connect/userinfo\"\n self.jwks_url = f\"{self.realm_url}/protocol/openid-connect/certs\"\n self.logout_url = f\"{self.external_realm_url}/protocol/openid-connect/logout\"\n self.config_url = f\"{self.realm_url}/.well-known/openid_configuration\"\n\n logger.debug(\n f\"Initialized Keycloak provider for realm '{realm}' at {keycloak_url} (external: {self.keycloak_external_url})\"\n )\n\n def validate_token(self, token: str, **kwargs: Any) -> dict[str, Any]:\n \"\"\"Validate Keycloak JWT token.\"\"\"\n try:\n logger.debug(\"Validating Keycloak JWT token\")\n\n # First check if this is a self-signed token from our auth server\n try:\n unverified_claims = jwt.decode(token, options={\"verify_signature\": False})\n if unverified_claims.get(\"iss\") == JWT_ISSUER:\n logger.debug(\"Token appears to be self-signed, validating...\")\n return self._validate_self_signed_token(token)\n except Exception as e:\n logger.debug(f\"Not a self-signed token: {e}\")\n\n # Get JWKS for validation\n jwks = self.get_jwks()\n\n # Decode token header to get key ID\n unverified_header = jwt.get_unverified_header(token)\n kid = unverified_header.get(\"kid\")\n\n if not kid:\n raise ValueError(\"Token missing 'kid' in header\")\n\n # Find matching key\n signing_key = None\n for key in jwks.get(\"keys\", []):\n if key.get(\"kid\") == kid:\n from jwt import PyJWK\n\n signing_key = PyJWK(key).key\n break\n\n if not signing_key:\n raise ValueError(f\"No matching key found for kid: {kid}\")\n\n # Validate and decode token - accept multiple valid issuers\n valid_issuers = [\n self.external_realm_url, # External URL: https://mcpgateway.ddns.net/realms/mcp-gateway\n self.realm_url, # Internal URL: http://keycloak:8080/realms/mcp-gateway\n f\"http://localhost:8080/realms/{self.realm}\", # Localhost URL for development\n ]\n\n claims = None\n last_error = None\n for issuer in valid_issuers:\n try:\n claims = jwt.decode(\n token,\n signing_key,\n algorithms=[\"RS256\"],\n issuer=issuer,\n audience=[\"account\", self.client_id, self.m2m_client_id],\n options={\"verify_exp\": True, \"verify_iat\": True, \"verify_aud\": True},\n )\n logger.debug(f\"Token validation successful with issuer: {issuer}\")\n break\n except jwt.InvalidIssuerError as e:\n last_error = e\n continue\n\n if claims is None:\n raise last_error or ValueError(\"Token validation failed with all valid issuers\")\n\n logger.debug(\n f\"Token validation successful for user: {claims.get('preferred_username', 'unknown')}\"\n )\n\n # Extract user info from claims\n return {\n \"valid\": True,\n \"username\": claims.get(\"preferred_username\", claims.get(\"sub\")),\n \"email\": claims.get(\"email\"),\n \"groups\": claims.get(\"groups\", []),\n \"scopes\": claims.get(\"scope\", \"\").split() if claims.get(\"scope\") else [],\n \"client_id\": claims.get(\"azp\", claims.get(\"aud\", self.client_id)),\n \"method\": \"keycloak\",\n \"data\": claims,\n }\n\n except jwt.ExpiredSignatureError:\n logger.warning(\"Token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\")\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Token validation failed: Invalid token - {e}\")\n raise ValueError(f\"Invalid token: {e}\")\n except Exception as e:\n logger.error(f\"Keycloak token validation error: {e}\")\n raise ValueError(f\"Token validation failed: {e}\")\n\n def _validate_self_signed_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a self-signed JWT token generated by our auth server.\n\n Self-signed tokens are generated for OAuth users to use for programmatic\n API access. They contain the user's identity, groups, and scopes.\n\n Args:\n token: The self-signed JWT token to validate\n\n Returns:\n Dictionary containing validation results\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n try:\n claims = jwt.decode(\n token,\n SECRET_KEY,\n algorithms=[\"HS256\"],\n audience=JWT_AUDIENCE,\n issuer=JWT_ISSUER,\n options={\"verify_exp\": True, \"verify_iat\": True, \"verify_aud\": True},\n )\n\n # Check token_use claim\n token_use = claims.get(\"token_use\")\n if token_use != \"access\": # nosec B105 - OAuth2 token type validation per RFC 6749, not a password\n raise ValueError(f\"Invalid token_use: {token_use}\")\n\n # Extract scopes from claims\n scopes = []\n if \"scope\" in claims:\n scope_value = claims[\"scope\"]\n if isinstance(scope_value, str):\n scopes = scope_value.split() if scope_value else []\n elif isinstance(scope_value, list):\n scopes = scope_value\n\n # Extract groups from claims\n groups = claims.get(\"groups\", [])\n if isinstance(groups, str):\n groups = [groups]\n\n logger.info(\n f\"Successfully validated self-signed token for user: {claims.get('sub')}, \"\n f\"groups: {groups}, scopes: {scopes}\"\n )\n\n return {\n \"valid\": True,\n \"method\": \"self_signed\",\n \"data\": claims,\n \"client_id\": claims.get(\"client_id\", \"user-generated\"),\n \"username\": claims.get(\"sub\", \"\"),\n \"email\": claims.get(\"email\", \"\"),\n \"expires_at\": claims.get(\"exp\"),\n \"scopes\": scopes,\n \"groups\": groups,\n \"token_type\": \"user_generated\",\n }\n\n except jwt.ExpiredSignatureError:\n logger.warning(\"Self-signed token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\")\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Self-signed token validation failed: {e}\")\n raise ValueError(f\"Invalid self-signed token: {e}\")\n except Exception as e:\n logger.error(f\"Self-signed token validation error: {e}\")\n raise ValueError(f\"Self-signed token validation failed: {e}\")\n\n def get_jwks(self) -> dict[str, Any]:\n \"\"\"Get JSON Web Key Set from Keycloak with caching.\"\"\"\n current_time = time.time()\n\n # Check if cache is still valid\n if self._jwks_cache and (current_time - self._jwks_cache_time) < self._jwks_cache_ttl:\n logger.debug(\"Using cached JWKS\")\n return self._jwks_cache\n\n try:\n logger.debug(f\"Fetching JWKS from {self.jwks_url}\")\n response = requests.get(self.jwks_url, timeout=10)\n response.raise_for_status()\n\n self._jwks_cache = response.json()\n self._jwks_cache_time = current_time\n\n logger.debug(\"JWKS fetched and cached successfully\")\n return self._jwks_cache\n\n except Exception as e:\n logger.error(f\"Failed to retrieve JWKS from Keycloak: {e}\")\n raise ValueError(f\"Cannot retrieve JWKS: {e}\")\n\n def exchange_code_for_token(self, code: str, redirect_uri: str) -> dict[str, Any]:\n \"\"\"Exchange authorization code for access token.\"\"\"\n try:\n logger.debug(\"Exchanging authorization code for token\")\n\n data = {\n \"grant_type\": \"authorization_code\",\n \"code\": code,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n \"redirect_uri\": redirect_uri,\n }\n\n response = requests.post(self.token_url, data=data, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token exchange successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to exchange code for token: {e}\")\n raise ValueError(f\"Token exchange failed: {e}\")\n\n def get_user_info(self, access_token: str) -> dict[str, Any]:\n \"\"\"Get user information from Keycloak.\"\"\"\n try:\n logger.debug(\"Fetching user info from Keycloak\")\n\n headers = {\"Authorization\": f\"Bearer {access_token}\"}\n response = requests.get(self.userinfo_url, headers=headers, timeout=10)\n response.raise_for_status()\n\n user_info = response.json()\n logger.debug(\n f\"User info retrieved for: {user_info.get('preferred_username', 'unknown')}\"\n )\n\n return user_info\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get user info: {e}\")\n raise ValueError(f\"User info retrieval failed: {e}\")\n\n def get_auth_url(self, redirect_uri: str, state: str, scope: str | None = None) -> str:\n \"\"\"Get Keycloak authorization URL.\"\"\"\n logger.debug(f\"Generating auth URL with redirect_uri: {redirect_uri}\")\n\n params = {\n \"client_id\": self.client_id,\n \"response_type\": \"code\",\n \"scope\": scope or \"openid email profile\",\n \"redirect_uri\": redirect_uri,\n \"state\": state,\n }\n\n auth_url = f\"{self.auth_url}?{urlencode(params)}\"\n logger.debug(f\"Generated auth URL: {auth_url}\")\n\n return auth_url\n\n def get_logout_url(self, redirect_uri: str) -> str:\n \"\"\"Get Keycloak logout URL.\"\"\"\n logger.debug(f\"Generating logout URL with redirect_uri: {redirect_uri}\")\n\n params = {\"client_id\": self.client_id, \"post_logout_redirect_uri\": redirect_uri}\n\n logout_url = f\"{self.logout_url}?{urlencode(params)}\"\n logger.debug(f\"Generated logout URL: {logout_url}\")\n\n return logout_url\n\n def refresh_token(self, refresh_token: str) -> dict[str, Any]:\n \"\"\"Refresh an access token using a refresh token.\"\"\"\n try:\n logger.debug(\"Refreshing access token\")\n\n data = {\n \"grant_type\": \"refresh_token\",\n \"refresh_token\": refresh_token,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n\n response = requests.post(self.token_url, data=data, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token refresh successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to refresh token: {e}\")\n raise ValueError(f\"Token refresh failed: {e}\")\n\n def validate_m2m_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a machine-to-machine token.\"\"\"\n # M2M tokens use the same validation as regular tokens\n return self.validate_token(token)\n\n def get_m2m_token(\n self,\n client_id: str | None = None,\n client_secret: str | None = None,\n scope: str | None = None,\n ) -> dict[str, Any]:\n \"\"\"Get machine-to-machine token using client credentials.\"\"\"\n try:\n logger.debug(\"Requesting M2M token using client credentials\")\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id or self.m2m_client_id,\n \"client_secret\": client_secret or self.m2m_client_secret,\n \"scope\": scope or \"openid\",\n }\n\n response = requests.post(self.token_url, data=data, timeout=10)\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"M2M token generation successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get M2M token: {e}\")\n raise ValueError(f\"M2M token generation failed: {e}\")\n\n @lru_cache(maxsize=1)\n def _get_openid_configuration(self) -> dict[str, Any]:\n \"\"\"Get OpenID Connect configuration from Keycloak.\"\"\"\n try:\n logger.debug(f\"Fetching OpenID configuration from {self.config_url}\")\n response = requests.get(self.config_url, timeout=10)\n response.raise_for_status()\n\n config = response.json()\n logger.debug(\"OpenID configuration retrieved successfully\")\n\n return config\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get OpenID configuration: {e}\")\n raise ValueError(f\"OpenID configuration retrieval failed: {e}\")\n\n def _check_keycloak_health(self) -> bool:\n \"\"\"Check if Keycloak is healthy and accessible.\"\"\"\n try:\n health_url = f\"{self.keycloak_url}/health/ready\"\n response = requests.get(health_url, timeout=5)\n return response.status_code == 200\n except Exception:\n return False\n\n def get_provider_info(self) -> dict[str, Any]:\n \"\"\"Get provider-specific information.\"\"\"\n return {\n \"provider_type\": \"keycloak\",\n \"keycloak_url\": self.keycloak_url,\n \"realm\": self.realm,\n \"client_id\": self.client_id,\n \"endpoints\": {\n \"auth\": self.auth_url,\n \"token\": self.token_url,\n \"userinfo\": self.userinfo_url,\n \"jwks\": self.jwks_url,\n \"logout\": self.logout_url,\n \"config\": self.config_url,\n },\n \"healthy\": self._check_keycloak_health(),\n }\n" }, { "path": "auth_server/providers/okta.py", "content": "\"\"\"Okta authentication provider implementation.\"\"\"\n\nimport logging\nimport os\nimport re\nimport time\nfrom typing import Any\nfrom urllib.parse import urlencode\n\nimport jwt\nimport requests\n\nfrom .base import AuthProvider\n\n# Constants for self-signed token validation\nJWT_ISSUER = os.environ.get(\"JWT_ISSUER\", \"mcp-auth-server\")\nJWT_AUDIENCE = os.environ.get(\"JWT_AUDIENCE\", \"mcp-registry\")\nSECRET_KEY = os.environ.get(\"SECRET_KEY\", \"development-secret-key\")\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass OktaProvider(AuthProvider):\n \"\"\"Okta authentication provider implementation.\n\n This provider implements OAuth2/OIDC authentication using Okta.\n It supports:\n - User authentication via OAuth2 authorization code flow\n - Machine-to-machine authentication via client credentials flow\n - JWT token validation using Okta JWKS\n - Group-based authorization with Okta groups\n \"\"\"\n\n def __init__(\n self,\n okta_domain: str,\n client_id: str,\n client_secret: str,\n m2m_client_id: str | None = None,\n m2m_client_secret: str | None = None,\n ):\n \"\"\"Initialize Okta provider.\n\n Args:\n okta_domain: Okta org domain (e.g., dev-123456.okta.com)\n client_id: OAuth2 client ID for web authentication\n client_secret: OAuth2 client secret\n m2m_client_id: Optional separate M2M client ID\n m2m_client_secret: Optional separate M2M client secret\n \"\"\"\n # Normalize domain (remove https:// if present)\n self.okta_domain = okta_domain.replace(\"https://\", \"\").rstrip(\"/\")\n self.client_id = client_id\n self.client_secret = client_secret\n self.m2m_client_id = m2m_client_id or client_id\n self.m2m_client_secret = m2m_client_secret or client_secret\n\n # Validate Okta domain format (security: warn on non-standard domains)\n standard_okta_pattern = r\"^[a-zA-Z0-9-]+\\.(okta\\.com|oktapreview\\.com|okta-emea\\.com)$\"\n if not re.match(standard_okta_pattern, self.okta_domain):\n logger.warning(\n f\"Non-standard Okta domain: {self.okta_domain}. \"\n f\"Expected format: *.okta.com, *.oktapreview.com, or *.okta-emea.com\"\n )\n\n # JWKS cache\n self._jwks_cache: dict[str, Any] | None = None\n self._jwks_cache_time: float = 0\n self._jwks_cache_ttl: int = 3600 # 1 hour\n\n # Check for custom authorization server\n auth_server_id = os.environ.get(\"OKTA_AUTH_SERVER_ID\", \"\")\n\n # Okta endpoints (org or custom authorization server)\n base_url = f\"https://{self.okta_domain}\"\n if auth_server_id:\n # Custom authorization server endpoints\n oauth2_base = f\"{base_url}/oauth2/{auth_server_id}/v1\"\n self.auth_url = f\"{oauth2_base}/authorize\"\n self.token_url = f\"{oauth2_base}/token\"\n self.userinfo_url = f\"{oauth2_base}/userinfo\"\n self.jwks_url = f\"{oauth2_base}/keys\"\n self.logout_url = f\"{oauth2_base}/logout\"\n self.issuer = f\"{base_url}/oauth2/{auth_server_id}\"\n logger.info(\n f\"Initialized Okta provider with custom authorization server '{auth_server_id}'\"\n )\n else:\n # Default org authorization server endpoints\n self.auth_url = f\"{base_url}/oauth2/v1/authorize\"\n self.token_url = f\"{base_url}/oauth2/v1/token\"\n self.userinfo_url = f\"{base_url}/oauth2/v1/userinfo\"\n self.jwks_url = f\"{base_url}/oauth2/v1/keys\"\n self.logout_url = f\"{base_url}/oauth2/v1/logout\"\n self.issuer = base_url\n logger.info(f\"Initialized Okta provider for domain '{self.okta_domain}'\")\n\n def validate_token(self, token: str, **kwargs: Any) -> dict[str, Any]:\n \"\"\"Validate Okta JWT token.\n\n Checks for self-signed tokens first (iss == mcp-auth-server), then\n validates against Okta JWKS using RS256.\n\n Args:\n token: The JWT access token to validate\n **kwargs: Additional provider-specific arguments\n\n Returns:\n Dictionary containing validation results with valid=True,\n username, email, groups, scopes, client_id, method, and data.\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n try:\n logger.debug(\"Validating Okta JWT token\")\n\n # First check if this is a self-signed token from our auth server\n try:\n unverified_claims = jwt.decode(token, options={\"verify_signature\": False})\n if unverified_claims.get(\"iss\") == JWT_ISSUER:\n logger.debug(\"Token appears to be self-signed, validating...\")\n return self._validate_self_signed_token(token)\n except Exception as e:\n logger.debug(f\"Not a self-signed token: {e}\")\n\n # Get JWKS for validation\n jwks = self.get_jwks()\n\n # Decode token header to get key ID\n unverified_header = jwt.get_unverified_header(token)\n kid = unverified_header.get(\"kid\")\n\n if not kid:\n raise ValueError(\"Token missing 'kid' in header\")\n\n # Find matching key\n signing_key = None\n for key in jwks.get(\"keys\", []):\n if key.get(\"kid\") == kid:\n from jwt import PyJWK\n\n signing_key = PyJWK(key).key\n break\n\n if not signing_key:\n raise ValueError(f\"No matching key found for kid: {kid}\")\n\n # Accept both web client_id and M2M client_id as valid audiences\n valid_audiences = [self.client_id]\n if self.m2m_client_id and self.m2m_client_id != self.client_id:\n valid_audiences.append(self.m2m_client_id)\n\n # For custom authorization servers, M2M tokens use API identifier as audience\n # Decode without audience validation first to check token type\n unverified_claims = jwt.decode(token, options={\"verify_signature\": False})\n\n # Check if this is an M2M token (has cid but audience is not client_id)\n is_m2m_token = \"cid\" in unverified_claims\n aud_claim = unverified_claims.get(\"aud\", \"\")\n aud_is_client_id = aud_claim in valid_audiences\n\n # For M2M tokens with custom auth server, skip audience validation\n # since Okta uses API identifier (e.g., \"api://ai-registry\") as audience\n verify_audience = not (is_m2m_token and not aud_is_client_id)\n\n # Validate and decode token\n claims = jwt.decode(\n token,\n signing_key,\n algorithms=[\"RS256\"],\n issuer=self.issuer,\n audience=valid_audiences if verify_audience else None,\n options={\n \"verify_exp\": True,\n \"verify_iat\": True,\n \"verify_aud\": verify_audience,\n },\n )\n\n logger.debug(f\"Token validation successful for user: {claims.get('sub', 'unknown')}\")\n\n # Extract and validate groups claim (must be list of strings)\n groups = claims.get(\"groups\", [])\n if not isinstance(groups, list):\n groups = [groups] if groups else []\n if not all(isinstance(g, str) for g in groups):\n raise ValueError(\"Invalid groups claim format: must contain only strings\")\n\n # Extract scopes - Okta uses 'scp' for scopes in access tokens\n scope_claim = claims.get(\"scp\") or claims.get(\"scope\", \"\")\n if isinstance(scope_claim, list):\n scopes = scope_claim\n else:\n scopes = scope_claim.split() if scope_claim else []\n\n return {\n \"valid\": True,\n \"username\": claims.get(\"sub\", claims.get(\"preferred_username\", \"\")),\n \"email\": claims.get(\"email\", \"\"),\n \"groups\": groups,\n \"scopes\": scopes,\n \"client_id\": claims.get(\"cid\", self.client_id),\n \"method\": \"okta\",\n \"data\": claims,\n }\n\n except jwt.ExpiredSignatureError:\n logger.warning(\"Token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\")\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Token validation failed: Invalid token - {e}\")\n raise ValueError(f\"Invalid token: {e}\")\n except Exception as e:\n logger.error(f\"Okta token validation error: {e}\")\n raise ValueError(f\"Token validation failed: {e}\")\n\n def _validate_self_signed_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a self-signed JWT token generated by our auth server.\n\n Self-signed tokens are generated for OAuth users to use for programmatic\n API access. They contain the user's identity, groups, and scopes.\n\n Args:\n token: The self-signed JWT token to validate\n\n Returns:\n Dictionary containing validation results with method=\"self_signed\"\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n try:\n claims = jwt.decode(\n token,\n SECRET_KEY,\n algorithms=[\"HS256\"],\n audience=JWT_AUDIENCE,\n issuer=JWT_ISSUER,\n options={\n \"verify_exp\": True,\n \"verify_iat\": True,\n \"verify_aud\": True,\n },\n )\n\n # Check token_use claim\n token_use = claims.get(\"token_use\")\n if token_use != \"access\": # nosec B105 - OAuth2 token type validation per RFC 6749\n raise ValueError(f\"Invalid token_use: {token_use}\")\n\n # Extract scopes from claims\n scopes = []\n if \"scope\" in claims:\n scope_value = claims[\"scope\"]\n if isinstance(scope_value, str):\n scopes = scope_value.split() if scope_value else []\n elif isinstance(scope_value, list):\n scopes = scope_value\n\n # Extract groups from claims\n groups = claims.get(\"groups\", [])\n if isinstance(groups, str):\n groups = [groups]\n\n logger.info(\n f\"Successfully validated self-signed token for user: {claims.get('sub')}, \"\n f\"groups: {groups}, scopes: {scopes}\"\n )\n\n return {\n \"valid\": True,\n \"method\": \"self_signed\",\n \"data\": claims,\n \"client_id\": claims.get(\"client_id\", \"user-generated\"),\n \"username\": claims.get(\"sub\", \"\"),\n \"email\": claims.get(\"email\", \"\"),\n \"expires_at\": claims.get(\"exp\"),\n \"scopes\": scopes,\n \"groups\": groups,\n \"token_type\": \"user_generated\",\n }\n\n except jwt.ExpiredSignatureError:\n logger.warning(\"Self-signed token validation failed: Token has expired\")\n raise ValueError(\"Token has expired\")\n except jwt.InvalidTokenError as e:\n logger.warning(f\"Self-signed token validation failed: {e}\")\n raise ValueError(f\"Invalid self-signed token: {e}\")\n except Exception as e:\n logger.error(f\"Self-signed token validation error: {e}\")\n raise ValueError(f\"Self-signed token validation failed: {e}\")\n\n def get_jwks(self) -> dict[str, Any]:\n \"\"\"Get JSON Web Key Set from Okta with caching.\n\n Returns cached JWKS if still valid (within TTL), otherwise fetches\n fresh data from Okta. Retries once on failure and falls back to\n stale cache if available.\n\n Returns:\n JWKS dictionary containing keys for token verification\n\n Raises:\n ValueError: If JWKS cannot be retrieved and no cache exists\n \"\"\"\n current_time = time.time()\n\n # Check if cache is still valid\n if self._jwks_cache and (current_time - self._jwks_cache_time) < self._jwks_cache_ttl:\n logger.debug(\"Using cached JWKS\")\n return self._jwks_cache\n\n # Try to fetch fresh JWKS with retry\n max_retries = 2\n last_error = None\n\n for attempt in range(max_retries):\n try:\n logger.debug(f\"Fetching JWKS (attempt {attempt + 1})\")\n response = requests.get(self.jwks_url, timeout=10)\n response.raise_for_status()\n\n self._jwks_cache = response.json()\n self._jwks_cache_time = current_time\n\n logger.debug(\"JWKS fetched and cached successfully\")\n return self._jwks_cache\n\n except Exception as e:\n last_error = e\n logger.warning(f\"JWKS fetch attempt {attempt + 1} failed: {e}\")\n if attempt < max_retries - 1:\n time.sleep(1) # Brief delay before retry\n\n # Graceful degradation: use stale cache if available\n if self._jwks_cache:\n cache_age = current_time - self._jwks_cache_time\n logger.warning(\n f\"JWKS fetch failed after {max_retries} attempts, \"\n f\"using stale cache (age: {cache_age:.0f}s): {last_error}\"\n )\n return self._jwks_cache\n\n # No cache available, must fail\n logger.error(f\"Failed to retrieve JWKS from Okta (no cache available): {last_error}\")\n raise ValueError(f\"Cannot retrieve JWKS: {last_error}\")\n\n def exchange_code_for_token(self, code: str, redirect_uri: str) -> dict[str, Any]:\n \"\"\"Exchange authorization code for access token.\n\n Args:\n code: Authorization code from Okta callback\n redirect_uri: The redirect URI used in the authorization request\n\n Returns:\n Token response dictionary containing access_token, id_token, etc.\n\n Raises:\n ValueError: If the token exchange request fails\n \"\"\"\n try:\n logger.debug(\"Exchanging authorization code for token\")\n data = {\n \"grant_type\": \"authorization_code\",\n \"code\": code,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n \"redirect_uri\": redirect_uri,\n }\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n token_data = response.json()\n logger.debug(\"Token exchange successful\")\n return token_data\n except requests.RequestException as e:\n logger.error(f\"Failed to exchange code for token: {e}\")\n raise ValueError(f\"Token exchange failed: {e}\")\n\n def get_user_info(self, access_token: str) -> dict[str, Any]:\n \"\"\"Get user information from Okta.\n\n Args:\n access_token: Valid Okta access token\n\n Returns:\n User info dictionary from Okta userinfo endpoint\n\n Raises:\n ValueError: If the userinfo request fails\n \"\"\"\n try:\n logger.debug(\"Fetching user info from Okta\")\n headers = {\"Authorization\": f\"Bearer {access_token}\"}\n response = requests.get(self.userinfo_url, headers=headers, timeout=10)\n response.raise_for_status()\n user_info = response.json()\n logger.debug(f\"User info retrieved for: {user_info.get('sub', 'unknown')}\")\n return user_info\n except requests.RequestException as e:\n logger.error(f\"Failed to get user info: {e}\")\n raise ValueError(f\"User info retrieval failed: {e}\")\n\n def get_auth_url(self, redirect_uri: str, state: str, scope: str | None = None) -> str:\n \"\"\"Get Okta authorization URL.\n\n Args:\n redirect_uri: The redirect URI after authentication\n state: CSRF protection state parameter\n scope: OAuth2 scopes (defaults to 'openid email profile groups')\n\n Returns:\n Authorization URL string\n \"\"\"\n logger.debug(f\"Generating auth URL with redirect_uri: {redirect_uri}\")\n params = {\n \"client_id\": self.client_id,\n \"response_type\": \"code\",\n \"scope\": scope or \"openid email profile groups\",\n \"redirect_uri\": redirect_uri,\n \"state\": state,\n }\n auth_url = f\"{self.auth_url}?{urlencode(params)}\"\n logger.debug(f\"Generated auth URL for endpoint: {self.auth_url}\")\n return auth_url\n\n def get_logout_url(self, redirect_uri: str) -> str:\n \"\"\"Get Okta logout URL.\n\n Args:\n redirect_uri: URI to redirect to after logout\n\n Returns:\n Full logout URL with client_id and post_logout_redirect_uri params\n \"\"\"\n logger.debug(f\"Generating logout URL with redirect_uri: {redirect_uri}\")\n\n params = {\n \"client_id\": self.client_id,\n \"post_logout_redirect_uri\": redirect_uri,\n }\n\n logout_url = f\"{self.logout_url}?{urlencode(params)}\"\n logger.debug(f\"Generated logout URL for endpoint: {self.logout_url}\")\n\n return logout_url\n\n def refresh_token(self, refresh_token: str) -> dict[str, Any]:\n \"\"\"Refresh an access token using a refresh token.\n\n Args:\n refresh_token: The refresh token from a previous token response\n\n Returns:\n Dictionary containing new token response\n\n Raises:\n ValueError: If token refresh fails\n \"\"\"\n try:\n logger.debug(\"Refreshing access token\")\n\n data = {\n \"grant_type\": \"refresh_token\",\n \"refresh_token\": refresh_token,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n response = requests.post(\n self.token_url,\n data=data,\n headers=headers,\n timeout=10,\n )\n response.raise_for_status()\n\n token_data = response.json()\n logger.debug(\"Token refresh successful\")\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to refresh token: {e}\")\n raise ValueError(f\"Token refresh failed: {e}\")\n\n def validate_m2m_token(self, token: str) -> dict[str, Any]:\n \"\"\"Validate a machine-to-machine token.\n\n Delegates to the standard validate_token() method since M2M tokens\n use the same JWT validation logic as user tokens.\n\n Args:\n token: JWT token string to validate\n\n Returns:\n Validated token information dictionary\n\n Raises:\n ValueError: If token validation fails\n \"\"\"\n return self.validate_token(token)\n\n def get_m2m_token(\n self,\n client_id: str | None = None,\n client_secret: str | None = None,\n scope: str | None = None,\n ) -> dict[str, Any]:\n \"\"\"Get machine-to-machine token using client credentials.\n\n Args:\n client_id: Optional override client ID (defaults to configured M2M client ID)\n client_secret: Optional override client secret (defaults to configured M2M client secret)\n scope: Optional scope string (defaults to 'openid')\n\n Returns:\n Token response dictionary containing access_token, etc.\n\n Raises:\n ValueError: If the M2M token request fails\n \"\"\"\n try:\n logger.debug(\"Requesting M2M token using client credentials\")\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id or self.m2m_client_id,\n \"client_secret\": client_secret or self.m2m_client_secret,\n \"scope\": scope or \"openid\",\n }\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n response = requests.post(self.token_url, data=data, headers=headers, timeout=10)\n response.raise_for_status()\n token_data = response.json()\n logger.debug(\"M2M token generation successful\")\n return token_data\n except requests.RequestException as e:\n logger.error(f\"Failed to get M2M token: {e}\")\n raise ValueError(f\"M2M token generation failed: {e}\")\n\n def get_provider_info(self) -> dict[str, Any]:\n \"\"\"Get provider-specific information.\n\n Returns:\n Dictionary containing provider configuration and endpoints\n \"\"\"\n return {\n \"provider_type\": \"okta\",\n \"okta_domain\": self.okta_domain,\n \"client_id\": self.client_id,\n \"endpoints\": {\n \"auth\": self.auth_url,\n \"token\": self.token_url,\n \"userinfo\": self.userinfo_url,\n \"jwks\": self.jwks_url,\n \"logout\": self.logout_url,\n },\n \"issuer\": self.issuer,\n }\n" }, { "path": "auth_server/pyproject.toml", "content": "[build-system]\nrequires = [\"setuptools>=42.0\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[tool.setuptools]\npackages = [\"auth_server\"]\n\n[project]\nname = \"auth_server\"\nversion = \"0.1.0\"\ndescription = \"Authentication server for validating JWT tokens against Amazon Cognito\"\nrequires-python = \">=3.14\"\ndependencies = [\n \"fastapi>=0.115.0\",\n \"uvicorn[standard]>=0.34.0\",\n \"pydantic>=2.0.0\",\n \"pydantic-settings>=2.0.0\",\n \"requests>=2.28.0\",\n \"python-jose>=3.3.0\",\n \"python-dotenv>=1.0.0\",\n \"boto3>=1.28.0\",\n \"pyjwt>=2.6.0\",\n \"cryptography>=40.0.0\",\n \"pyyaml>=6.0.0\",\n \"httpx>=0.25.0\",\n \"itsdangerous>=2.1.0\",\n \"opensearch-py>=2.4.0\",\n \"aiohttp>=3.8.0\",\n \"motor>=3.3.0\",\n \"pymongo>=4.6.0\",\n \"aiofiles>=24.1.0\"\n]\n\n[project.optional-dependencies]\ndev = [\n \"pytest>=7.0.0\",\n \"black>=23.0.0\",\n \"isort>=5.12.0\"\n]\n\n[tool.uv]\n# Local-only project - never resolve from PyPI\npackage = false" }, { "path": "auth_server/scopes.yml", "content": "# Scopes Configuration for MCP Gateway Registry\n#\n# This file defines three main top-level groups:\n# 1. UI-Scopes: Agent registry permissions (list, get, publish, modify, delete agents) and MCP service access\n# 2. group_mappings: Maps IdP groups to scope names (supports both Keycloak group names and Entra ID Object IDs)\n# 3. Individual group scopes: Detailed MCP server method/tool access for each group\n#\n# Each group has two types of permissions:\n# - Agent permissions: Actions on agent resources (list_agents, get_agent, publish_agent, modify_agent, delete_agent)\n# - MCP server permissions: Methods and tools accessible on specific MCP servers (currenttime, mcpgw, fininfo, etc.)\n#\n# To add a new group, follow these three steps:\n# 1. Add to UI-Scopes: Define agent and service permissions (what agents/services the group can access)\n# 2. Add to group_mappings: Map the IdP group identifier to the internal scope name\n# - For Keycloak: Use the group name (e.g., \"registry-admins\")\n# - For Entra ID: Use the Azure AD Group Object ID (e.g., \"4c46ec66-a4f7-4b62-9095-b7958662f4b6\")\n# 3. Add individual group scope entry: Define detailed MCP server methods/tools and agent actions for the group\n\n# ==================== UI-SCOPES ====================\n# Define agent registry permissions and service listing rights for each group\nUI-Scopes:\n # Federation service account for peer-to-peer registry sync (read-only)\n federation-service:\n list_agents:\n - all\n get_agent:\n - all\n list_service:\n - all\n health_check_service:\n - all\n\n # Admin user for MCP registry (highest privileges)\n mcp-registry-admin:\n list_agents:\n - all\n get_agent:\n - all\n publish_agent:\n - all\n modify_agent:\n - all\n delete_agent:\n - all\n list_service:\n - all\n register_service:\n - all\n health_check_service:\n - all\n toggle_service:\n - all\n modify_service:\n - all\n\n # Registry admin group (wildcard access to all agents and services)\n registry-admins:\n list_agents:\n - all\n get_agent:\n - all\n publish_agent:\n - all\n modify_agent:\n - all\n delete_agent:\n - all\n list_service:\n - all\n register_service:\n - all\n health_check_service:\n - all\n toggle_service:\n - all\n modify_service:\n - all\n\n # LOB1 (Line of Business 1): Restricted to code-reviewer and test-automation agents\n registry-users-lob1:\n list_agents:\n - /code-reviewer\n - /test-automation\n get_agent:\n - /code-reviewer\n - /test-automation\n publish_agent:\n - /code-reviewer\n - /test-automation\n modify_agent:\n - /code-reviewer\n - /test-automation\n delete_agent:\n - /code-reviewer\n - /test-automation\n list_service:\n - currenttime\n - mcpgw\n health_check_service:\n - currenttime\n - mcpgw\n\n # Public MCP Users: Access to public MCP servers (context7, cloudflare-docs) and flight-booking agent\n public-mcp-users:\n list_agents:\n - /flight-booking\n get_agent:\n - /flight-booking\n list_service:\n - all\n health_check_service:\n - context7\n - cloudflare-docs\n\n # LOB2 (Line of Business 2): Restricted to data-analysis and security-analyzer agents\n registry-users-lob2:\n list_agents:\n - /data-analysis\n - /security-analyzer\n get_agent:\n - /data-analysis\n - /security-analyzer\n publish_agent:\n - /data-analysis\n - /security-analyzer\n modify_agent:\n - /data-analysis\n - /security-analyzer\n delete_agent:\n - /data-analysis\n - /security-analyzer\n list_service:\n - realserverfaketools\n - mcpgw\n - fininfo\n health_check_service:\n - realserverfaketools\n - mcpgw\n - fininfo\n\n# ==================== GROUP MAPPINGS ====================\n# Maps IdP groups to internal scope group names\n# This section supports BOTH Keycloak (group names) and Entra ID (Object IDs)\n#\n# Keycloak: Uses group names directly (e.g., \"registry-admins\")\n# Entra ID: Uses Azure AD Group Object IDs (GUIDs) from Azure Portal -> Groups -> [group] -> Object Id\n\ngroup_mappings:\n # ----- Keycloak Group Mappings (group names) -----\n federation-service:\n - federation-service\n\n mcp-registry-admin:\n - mcp-registry-admin\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n\n registry-admins:\n - registry-admins\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n\n registry-users-lob1:\n - registry-users-lob1\n\n registry-users-lob2:\n - registry-users-lob2\n\n public-mcp-users:\n - public-mcp-users\n\n # ----- Entra ID Group Mappings (Azure AD Object IDs) -----\n # registry-admins group Object ID from Azure AD\n \"4c46ec66-a4f7-4b62-9095-b7958662f4b6\":\n - registry-admins\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n\n # public-mcp-users group Object ID from Azure AD\n \"5f605d68-06bc-4208-b992-bb378eee12c5\":\n - public-mcp-users\n\n # Add additional Entra ID group mappings here as needed:\n # \"your-lob1-group-object-id\":\n # - registry-users-lob1\n #\n # \"your-lob2-group-object-id\":\n # - registry-users-lob2\n\n# ==================== MCP SERVER SCOPES ====================\n# Unrestricted read access: Wildcard access to all servers with all methods and tools\nmcp-servers-unrestricted/read:\n- server: '*'\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n - GET\n tools: '*'\n- server: api\n methods:\n - tokens\n - GET\n\n# Unrestricted execute access: Full CRUD operations on all servers (POST, PUT, DELETE in addition to read)\nmcp-servers-unrestricted/execute:\n- server: '*'\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n - GET\n - POST\n - PUT\n - DELETE\n tools: '*'\n- server: api\n methods:\n - tokens\n - GET\n - POST\n\n# Federation Service Scope: Read-only access for peer-to-peer registry sync\n# This scope is used by peer registries to fetch servers and agents for federation\nfederation-service:\n- server: api\n methods:\n - initialize\n - GET\n- agents:\n actions:\n - action: list_agents\n resources:\n - all\n - action: get_agent\n resources:\n - all\n\n# LOB1 Group Scope: Read-only access to API; currenttime and mcpgw servers; code-reviewer and test-automation agents\nregistry-users-lob1:\n- server: api\n methods:\n - initialize\n - GET\n- server: currenttime\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - current_time_by_timezone\n- server: mcpgw\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - intelligent_tool_finder\n- agents:\n actions:\n - action: list_agents\n resources:\n - /code-reviewer\n - /test-automation\n - action: get_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: publish_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: modify_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: delete_agent\n resources:\n - /code-reviewer\n - /test-automation\n\n# LOB2 Group Scope: Read-only access to API; realserverfaketools, mcpgw, fininfo servers; data-analysis and security-analyzer agents\nregistry-users-lob2:\n- server: api\n methods:\n - initialize\n - GET\n- server: realserverfaketools\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - quantum_flux_analyzer\n - neural_pattern_synthesizer\n - hyper_dimensional_mapper\n- server: mcpgw\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - intelligent_tool_finder\n- server: fininfo\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - get_stock_aggregates\n - print_stock_data\n- agents:\n actions:\n - action: list_agents\n resources:\n - /data-analysis\n - /security-analyzer\n - action: get_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: publish_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: modify_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: delete_agent\n resources:\n - /data-analysis\n - /security-analyzer\n\n# Admin Group Scope: Unrestricted access to all servers with wildcard; unrestricted access to all agents\nregistry-admins:\n- server: '*'\n methods:\n - all\n tools:\n - all\n- agents:\n actions:\n - action: list_agents\n resources:\n - all\n - action: get_agent\n resources:\n - all\n - action: publish_agent\n resources:\n - all\n - action: modify_agent\n resources:\n - all\n - action: delete_agent\n resources:\n - all\n\n# Public MCP Users: Access to public MCP servers and flight-booking agent\npublic-mcp-users:\n- server: api\n methods:\n - initialize\n - GET\n - POST\n - servers\n - agents\n - search\n - rating\n - tools\n - tokens\n tools: []\n- server: v0.1\n methods:\n - agents\n - GET\n - POST\n tools: []\n- server: context7\n methods:\n - initialize\n - tools/list\n - tools/call\n tools: '*'\n- server: /context7\n methods:\n - initialize\n - tools/list\n - tools/call\n tools: '*'\n- server: /context7/\n methods:\n - initialize\n - tools/list\n - tools/call\n tools: '*'\n- server: cloudflare-docs\n methods:\n - initialize\n - tools/list\n - tools/call\n tools: '*'\n- server: /cloudflare-docs\n methods:\n - initialize\n - tools/list\n - tools/call\n tools: '*'\n- server: /cloudflare-docs/\n methods:\n - initialize\n - tools/list\n - tools/call\n tools: '*'\n- agents:\n actions:\n - action: list_agents\n resources:\n - /flight-booking\n - action: get_agent\n resources:\n - /flight-booking\n" }, { "path": "auth_server/scopes.yml.backup", "content": "# Scopes Configuration for MCP Gateway Registry\n#\n# This file defines three main top-level groups:\n# 1. UI-Scopes: Agent registry permissions (list, get, publish, modify, delete agents) and MCP service access\n# 2. group_mappings: Maps Keycloak groups to scope names\n# 3. Individual group scopes: Detailed MCP server method/tool access for each group\n#\n# Each group has two types of permissions:\n# - Agent permissions: Actions on agent resources (list_agents, get_agent, publish_agent, modify_agent, delete_agent)\n# - MCP server permissions: Methods and tools accessible on specific MCP servers (currenttime, mcpgw, fininfo, etc.)\n#\n# To add a new group, follow these three steps:\n# 1. Add to UI-Scopes: Define agent and service permissions (what agents/services the group can access)\n# 2. Add to group_mappings: Map the Keycloak group name to the internal scope name\n# 3. Add individual group scope entry: Define detailed MCP server methods/tools and agent actions for the group\n\n# ==================== UI-SCOPES ====================\n# Define agent registry permissions and service listing rights for each group\nUI-Scopes:\n # Admin user for MCP registry (highest privileges)\n mcp-registry-admin:\n list_agents:\n - all\n get_agent:\n - all\n publish_agent:\n - all\n modify_agent:\n - all\n delete_agent:\n - all\n list_service:\n - all\n register_service:\n - all\n health_check_service:\n - all\n toggle_service:\n - all\n modify_service:\n - all\n\n # Registry admin group (wildcard access to all agents and services)\n registry-admins:\n list_agents:\n - all\n get_agent:\n - all\n publish_agent:\n - all\n modify_agent:\n - all\n delete_agent:\n - all\n list_service:\n - all\n register_service:\n - all\n health_check_service:\n - all\n toggle_service:\n - all\n modify_service:\n - all\n\n # LOB1 (Line of Business 1): Restricted to code-reviewer and test-automation agents\n registry-users-lob1:\n list_agents:\n - /code-reviewer\n - /test-automation\n get_agent:\n - /code-reviewer\n - /test-automation\n publish_agent:\n - /code-reviewer\n - /test-automation\n modify_agent:\n - /code-reviewer\n - /test-automation\n delete_agent:\n - /code-reviewer\n - /test-automation\n list_service:\n - currenttime\n - mcpgw\n health_check_service:\n - currenttime\n - mcpgw\n\n # LOB2 (Line of Business 2): Restricted to data-analysis and security-analyzer agents\n registry-users-lob2:\n list_agents:\n - /data-analysis\n - /security-analyzer\n get_agent:\n - /data-analysis\n - /security-analyzer\n publish_agent:\n - /data-analysis\n - /security-analyzer\n modify_agent:\n - /data-analysis\n - /security-analyzer\n delete_agent:\n - /data-analysis\n - /security-analyzer\n list_service:\n - realserverfaketools\n - mcpgw\n - fininfo\n health_check_service:\n - realserverfaketools\n - mcpgw\n - fininfo\n\n# ==================== GROUP MAPPINGS ====================\n# Maps Keycloak groups to internal scope group names\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n registry-admins:\n - registry-admins\n registry-users-lob1:\n - registry-users-lob1\n registry-users-lob2:\n - registry-users-lob2\n\n# ==================== MCP SERVER SCOPES ====================\n# Unrestricted read access: Wildcard access to all servers with all methods and tools\nmcp-servers-unrestricted/read:\n- server: '*'\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n - GET\n tools: '*'\n\n# Unrestricted execute access: Full CRUD operations on all servers (POST, PUT, DELETE in addition to read)\nmcp-servers-unrestricted/execute:\n- server: '*'\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n - GET\n - POST\n - PUT\n - DELETE\n tools: '*'\n\n# LOB1 Group Scope: Read-only access to API; currenttime and mcpgw servers; code-reviewer and test-automation agents\nregistry-users-lob1:\n- server: api\n methods:\n - initialize\n - GET\n- server: currenttime\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - current_time_by_timezone\n- server: mcpgw\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - intelligent_tool_finder\n- agents:\n actions:\n - action: list_agents\n resources:\n - /code-reviewer\n - /test-automation\n - action: get_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: publish_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: modify_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: delete_agent\n resources:\n - /code-reviewer\n - /test-automation\n\n# LOB2 Group Scope: Read-only access to API; realserverfaketools, mcpgw, fininfo servers; data-analysis and security-analyzer agents\nregistry-users-lob2:\n- server: api\n methods:\n - initialize\n - GET\n- server: realserverfaketools\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - quantum_flux_analyzer\n - neural_pattern_synthesizer\n - hyper_dimensional_mapper\n- server: mcpgw\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - intelligent_tool_finder\n- server: fininfo\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - get_stock_aggregates\n - print_stock_data\n- agents:\n actions:\n - action: list_agents\n resources:\n - /data-analysis\n - /security-analyzer\n - action: get_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: publish_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: modify_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: delete_agent\n resources:\n - /data-analysis\n - /security-analyzer\n\n# Admin Group Scope: Unrestricted access to all servers with wildcard; unrestricted access to all agents\nregistry-admins:\n- server: '*'\n methods:\n - all\n tools:\n - all\n- agents:\n actions:\n - action: list_agents\n resources:\n - all\n - action: get_agent\n resources:\n - all\n - action: publish_agent\n resources:\n - all\n - action: modify_agent\n resources:\n - all\n - action: delete_agent\n resources:\n - all" }, { "path": "auth_server/server.py", "content": "\"\"\"\nSimplified Authentication server that validates JWT tokens against Amazon Cognito.\nConfiguration is passed via headers instead of environment variables.\n\"\"\"\n\nimport argparse\nimport hashlib\nimport hmac\nimport json\nimport logging\nimport os\nimport re\nimport secrets\n\n# Import shared scopes loader and repository factory from registry common module\nimport sys\nimport time\nimport urllib.parse\nfrom contextlib import asynccontextmanager\nfrom datetime import datetime\nfrom pathlib import Path\nfrom string import Template\nfrom typing import Any\nfrom urllib.parse import urlparse\n\nimport boto3\nimport httpx\nimport jwt\nimport requests\nimport uvicorn\nimport yaml\nfrom botocore.exceptions import ClientError\nfrom fastapi import Cookie, FastAPI, Header, HTTPException, Request\nfrom fastapi.responses import JSONResponse, RedirectResponse\nfrom itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer\nfrom jwt.api_jwk import PyJWK\n\n# Import metrics middleware\nfrom metrics_middleware import add_auth_metrics_middleware\n\n# Import provider factory\nfrom providers.factory import get_auth_provider\nfrom pydantic import (\n BaseModel,\n Field,\n field_validator,\n)\n\nsys.path.insert(0, \"/app\")\n# Import MCP audit logging components\nfrom pathlib import Path as _LogPath\n\nfrom registry.audit.mcp_logger import MCPLogger\nfrom registry.audit.models import Identity, MCPServer\nfrom registry.audit.service import AuditLogger\nfrom registry.common.scopes_loader import reload_scopes_config\nfrom registry.core.config import settings\nfrom registry.repositories.factory import get_scope_repository\n\n# Configure logging using shared module (RotatingFileHandler + optional MongoDB)\nfrom registry.utils.logging_setup import setup_logging as _setup_logging\nfrom registry.utils.request_utils import get_client_ip\n\n_auth_log_file = _setup_logging(\n service_name=\"auth-server\",\n log_file=_LogPath(\"/app/logs/auth-server.log\") if _LogPath(\"/app\").exists() else None,\n)\nlogger = logging.getLogger(__name__)\nlogger.info(f\"Auth-server logging configured. Writing to file: {_auth_log_file}\")\n\n# Import JWT constants from shared internal auth module\nfrom registry.auth.internal import (\n _INTERNAL_JWT_AUDIENCE as JWT_AUDIENCE,\n)\nfrom registry.auth.internal import (\n _INTERNAL_JWT_ISSUER as JWT_ISSUER,\n)\n\nMAX_TOKEN_LIFETIME_HOURS = 24\nDEFAULT_TOKEN_LIFETIME_HOURS = 8\n\n# Rate limiting for token generation (simple in-memory counter)\nuser_token_generation_counts = {}\nMAX_TOKENS_PER_USER_PER_HOUR = int(os.environ.get(\"MAX_TOKENS_PER_USER_PER_HOUR\", \"100\"))\n\n# Global scopes configuration (will be loaded during FastAPI startup)\nSCOPES_CONFIG = {}\n\n# Static token auth: use static API key instead of IdP JWT for Registry API\n_registry_static_token_requested: bool = (\n os.environ.get(\"REGISTRY_STATIC_TOKEN_AUTH_ENABLED\", \"false\").lower() == \"true\"\n)\n\n# Static API key for Registry API (must match Bearer token value when enabled)\nREGISTRY_API_TOKEN: str = os.environ.get(\"REGISTRY_API_TOKEN\", \"\")\n\n# OAuth token storage in session cookies (disable for IdPs with large tokens)\n# Default: false - tokens are not used functionally and storing them risks cookie size limits\nOAUTH_STORE_TOKENS_IN_SESSION: bool = (\n os.environ.get(\"OAUTH_STORE_TOKENS_IN_SESSION\", \"false\").lower() == \"true\"\n)\n\nlogging.info(\n f\"OAUTH_STORE_TOKENS_IN_SESSION={'enabled' if OAUTH_STORE_TOKENS_IN_SESSION else 'disabled'}\"\n)\n\n# Issue #779: multiple static API keys with per-key groups.\n_REGISTRY_API_KEYS_RAW: str = os.environ.get(\"REGISTRY_API_KEYS\", \"\").strip()\n\n# Validate configuration: static token auth requires at least one token source\nif _registry_static_token_requested and not REGISTRY_API_TOKEN and not _REGISTRY_API_KEYS_RAW:\n logging.error(\n \"REGISTRY_STATIC_TOKEN_AUTH_ENABLED=true but neither REGISTRY_API_TOKEN \"\n \"nor REGISTRY_API_KEYS is set. Static token auth is DISABLED. \"\n \"Set at least one of these or disable the feature. \"\n \"Falling back to standard IdP JWT validation.\"\n )\n REGISTRY_STATIC_TOKEN_AUTH_ENABLED: bool = False\nelse:\n REGISTRY_STATIC_TOKEN_AUTH_ENABLED: bool = _registry_static_token_requested\n\n\n# ---------------------------------------------------------------------------\n# Multi-key static token config model and parser (Issue #779)\n# ---------------------------------------------------------------------------\n\n_KEY_NAME_PATTERN: re.Pattern = re.compile(r\"^[a-z0-9][a-z0-9_-]{0,63}$\")\n\n_RESERVED_KEY_NAMES: frozenset = frozenset(\n {\n \"legacy\",\n \"network-user\",\n \"network-trusted\",\n }\n)\n\n_STATIC_TOKEN_MAP: dict[str, dict] = {}\n\n\nclass _RegistryApiKeyEntry(BaseModel):\n \"\"\"Config entry parsed from REGISTRY_API_KEYS.\"\"\"\n\n name: str = Field(\n ...,\n description=\"Key name (log-safe identifier)\",\n )\n key: str = Field(\n ...,\n min_length=32,\n description=(\n \"The Bearer token value. Minimum 32 chars matches the default \"\n \"output of python3 -c 'import secrets; print(secrets.token_urlsafe(32))'.\"\n ),\n )\n groups: list[str] = Field(\n ...,\n min_length=1,\n description=\"Groups this key is mapped to\",\n )\n\n @field_validator(\"name\")\n @classmethod\n def _validate_name(\n cls,\n v: str,\n ) -> str:\n if not _KEY_NAME_PATTERN.match(v):\n raise ValueError(f\"Invalid key name '{v}': must match ^[a-z0-9][a-z0-9_-]{{0,63}}$\")\n if v in _RESERVED_KEY_NAMES:\n raise ValueError(\n f\"Key name '{v}' is reserved (legacy/internal). Pick a different name.\"\n )\n return v\n\n\ndef _repair_stripped_json(\n raw: str,\n) -> str:\n \"\"\"Re-quote a JSON-like string where docker-compose stripped double quotes.\n\n Converts e.g. {name:{key:val,groups:[g1]}} back to valid JSON by adding\n double quotes around all bare identifiers and values.\n \"\"\"\n result = []\n i = 0\n while i < len(raw):\n ch = raw[i]\n if ch in \"{}[],:\":\n result.append(ch)\n i += 1\n elif ch in \" \\t\\n\\r\":\n i += 1\n else:\n # Read a bare token (everything until a structural char)\n j = i\n while j < len(raw) and raw[j] not in \"{}[],:\":\n j += 1\n token = raw[i:j].strip()\n result.append(f'\"{token}\"')\n i = j\n return \"\".join(result)\n\n\ndef _parse_registry_api_keys(\n raw: str,\n) -> list[_RegistryApiKeyEntry]:\n \"\"\"Parse REGISTRY_API_KEYS env var into validated entries.\n\n Returns:\n List of entries. Empty list if raw is empty.\n\n Raises:\n ValueError: on malformed JSON, duplicate name, duplicate key value,\n reserved name, or validation failure on any entry.\n \"\"\"\n if not raw:\n return []\n\n try:\n doc = json.loads(raw)\n except json.JSONDecodeError:\n # Docker Compose strips double quotes from .env values containing JSON.\n # Attempt to recover by re-quoting bare identifiers:\n # {name:{key:val,...}} -> {\"name\":{\"key\":\"val\",...}}\n repaired = _repair_stripped_json(raw)\n try:\n doc = json.loads(repaired)\n logging.warning(\n \"REGISTRY_API_KEYS was not valid JSON (docker-compose may have \"\n \"stripped quotes). Auto-repaired successfully.\"\n )\n except json.JSONDecodeError as e2:\n raise ValueError(f\"REGISTRY_API_KEYS is not valid JSON: {e2}\") from e2\n\n if not isinstance(doc, dict):\n raise ValueError(\"REGISTRY_API_KEYS must be a JSON object\")\n\n entries: list[_RegistryApiKeyEntry] = []\n seen_names: set[str] = set()\n seen_keys: set[str] = set()\n\n for name, value in doc.items():\n if name in seen_names:\n raise ValueError(f\"Duplicate key name in REGISTRY_API_KEYS: {name}\")\n\n if not isinstance(value, dict):\n raise ValueError(f\"Entry for '{name}' must be an object\")\n\n try:\n entry = _RegistryApiKeyEntry(name=name, **value)\n except Exception as e:\n raise ValueError(f\"Invalid entry '{name}': {e}\") from e\n\n if entry.key in seen_keys:\n raise ValueError(f\"Duplicate key value across entries (conflicts around name '{name}')\")\n\n seen_names.add(entry.name)\n seen_keys.add(entry.key)\n entries.append(entry)\n\n return entries\n\n\nasync def _build_static_token_map() -> None:\n \"\"\"Build _STATIC_TOKEN_MAP from env config. Fail-closed on any error.\"\"\"\n global REGISTRY_STATIC_TOKEN_AUTH_ENABLED, _STATIC_TOKEN_MAP\n\n if not REGISTRY_STATIC_TOKEN_AUTH_ENABLED:\n return\n\n token_map: dict[str, dict] = {}\n\n try:\n parsed = _parse_registry_api_keys(_REGISTRY_API_KEYS_RAW)\n except ValueError as e:\n logging.error(\n \"Failed to parse REGISTRY_API_KEYS: %s. Static-token auth DISABLED.\",\n e,\n )\n REGISTRY_STATIC_TOKEN_AUTH_ENABLED = False\n return\n\n for entry in parsed:\n scopes = await map_groups_to_scopes(entry.groups)\n if not scopes:\n logging.warning(\n \"Static key '%s' has no scope mappings for groups %s. \"\n \"Requests using this key will get 403 on all protected endpoints.\",\n entry.name,\n entry.groups,\n )\n token_map[entry.name] = {\n \"key_bytes\": entry.key.encode(\"utf-8\"),\n \"groups\": list(entry.groups),\n \"scopes\": scopes,\n }\n\n if REGISTRY_API_TOKEN:\n # Legacy entry uses the well-known admin scopes directly to avoid a DB\n # roundtrip. The list must include the UI scope name \"mcp-registry-admin\"\n # so the registry resolves admin UI permissions through the standard path\n # (the hard-coded admin branch was removed in #779).\n token_map[\"legacy\"] = {\n \"key_bytes\": REGISTRY_API_TOKEN.encode(\"utf-8\"),\n \"groups\": [\"mcp-registry-admin\"],\n \"scopes\": [\n \"mcp-registry-admin\",\n \"mcp-servers-unrestricted/read\",\n \"mcp-servers-unrestricted/execute\",\n ],\n \"username_override\": \"network-user\",\n \"client_id_override\": \"network-trusted\",\n }\n\n _STATIC_TOKEN_MAP = token_map\n\n if not _STATIC_TOKEN_MAP:\n logging.warning(\n \"Static-token auth ENABLED but no keys loaded. \"\n \"Check REGISTRY_API_TOKEN / REGISTRY_API_KEYS. \"\n \"All bearer tokens will fall through to JWT validation.\"\n )\n else:\n logging.info(\n \"Static-token auth: loaded %d key(s): %s\",\n len(_STATIC_TOKEN_MAP),\n sorted(_STATIC_TOKEN_MAP.keys()),\n )\n\n\n# Get ROOT_PATH for path-based routing (auth server's own path, e.g. /auth-server)\nROOT_PATH = os.environ.get(\"ROOT_PATH\", \"\").rstrip(\"/\")\n\n# REGISTRY_ROOT_PATH is the registry's base path (e.g. /registry) used for matching\n# X-Original-URL paths that come from the registry's nginx. Falls back to ROOT_PATH\n# for backward compatibility when both services share the same root path.\nREGISTRY_ROOT_PATH = os.environ.get(\"REGISTRY_ROOT_PATH\", ROOT_PATH).rstrip(\"/\")\n\n# Registry API path patterns that use static token auth when enabled\n# REGISTRY_ROOT_PATH is prepended so pattern matching works when hosted on a base path (e.g. /registry/api/)\nREGISTRY_API_PATTERNS: list = [\n f\"{REGISTRY_ROOT_PATH}/api/\",\n f\"{REGISTRY_ROOT_PATH}/v0.1/\",\n]\n\n# Federation static token auth: scoped token for federation endpoints only\n_federation_static_token_requested: bool = (\n os.environ.get(\"FEDERATION_STATIC_TOKEN_AUTH_ENABLED\", \"false\").lower() == \"true\"\n)\n\nFEDERATION_STATIC_TOKEN: str = os.environ.get(\"FEDERATION_STATIC_TOKEN\", \"\")\n\nif _federation_static_token_requested and not FEDERATION_STATIC_TOKEN:\n logging.error(\n \"FEDERATION_STATIC_TOKEN_AUTH_ENABLED=true but FEDERATION_STATIC_TOKEN is not set. \"\n \"Federation static token auth is DISABLED. Set FEDERATION_STATIC_TOKEN or disable the feature. \"\n \"Falling back to standard IdP JWT validation.\"\n )\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED: bool = False\nelse:\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED: bool = _federation_static_token_requested\n\n# Warn if token is too short (weak entropy)\nMIN_FEDERATION_TOKEN_LENGTH: int = 32\nif (\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED\n and len(FEDERATION_STATIC_TOKEN) < MIN_FEDERATION_TOKEN_LENGTH\n):\n logging.warning(\n f\"FEDERATION_STATIC_TOKEN is only {len(FEDERATION_STATIC_TOKEN)} characters. \"\n f\"Recommended minimum is {MIN_FEDERATION_TOKEN_LENGTH} characters. \"\n 'Generate a stronger token with: python3 -c \"import secrets; print(secrets.token_urlsafe(32))\"'\n )\n\n# Federation endpoint path patterns (scoped access for federation static token)\n# REGISTRY_ROOT_PATH is prepended so pattern matching works when hosted on a base path\nFEDERATION_API_PATTERNS: list = [\n f\"{REGISTRY_ROOT_PATH}/api/federation/\",\n f\"{REGISTRY_ROOT_PATH}/api/peers/\",\n \"/api/peers\", # exact match for list peers (no trailing slash)\n]\n\n# Utility functions for GDPR/SOX compliance\n\n\ndef is_request_https(request) -> bool:\n \"\"\"\n Detect if the original request was HTTPS.\n\n Priority order:\n 1. X-Cloudfront-Forwarded-Proto header (CloudFront deployments)\n 2. x-forwarded-proto header (ALB/custom domain deployments)\n 3. Request URL scheme (direct access)\n\n Args:\n request: FastAPI Request object\n\n Returns:\n True if the original request was HTTPS\n \"\"\"\n # Check CloudFront header first (ALB won't overwrite this)\n cloudfront_proto = request.headers.get(\"x-cloudfront-forwarded-proto\", \"\")\n if cloudfront_proto.lower() == \"https\":\n return True\n\n # Fall back to standard x-forwarded-proto\n x_forwarded_proto = request.headers.get(\"x-forwarded-proto\", \"\")\n if x_forwarded_proto.lower() == \"https\":\n return True\n\n # Finally check request scheme\n return request.url.scheme == \"https\"\n\n\ndef mask_sensitive_id(value: str) -> str:\n \"\"\"Mask sensitive IDs showing only first and last 4 characters.\"\"\"\n if not value or len(value) <= 8:\n return \"***MASKED***\"\n return f\"{value[:4]}...{value[-4:]}\"\n\n\ndef hash_username(username: str) -> str:\n \"\"\"Hash username for privacy compliance.\"\"\"\n if not username:\n return \"anonymous\"\n return f\"user_{hashlib.sha256(username.encode()).hexdigest()[:8]}\"\n\n\ndef anonymize_ip(ip_address: str) -> str:\n \"\"\"Anonymize IP address by masking last octet for IPv4.\"\"\"\n if not ip_address or ip_address == \"unknown\":\n return ip_address\n if \".\" in ip_address: # IPv4\n parts = ip_address.split(\".\")\n if len(parts) == 4:\n return f\"{'.'.join(parts[:3])}.xxx\"\n elif \":\" in ip_address: # IPv6\n # Mask last segment\n parts = ip_address.split(\":\")\n if len(parts) > 1:\n parts[-1] = \"xxxx\"\n return \":\".join(parts)\n return ip_address\n\n\ndef mask_token(token: str) -> str:\n \"\"\"Mask JWT token showing only first 4 characters followed by ellipsis.\"\"\"\n if not token:\n return \"***EMPTY***\"\n if len(token) > 8:\n return f\"{token[:4]}...\"\n return \"***MASKED***\"\n\n\ndef _is_safe_redirect_url(\n url: str,\n allowed_hosts: set[str] | None = None,\n) -> bool:\n \"\"\"Validate that a redirect URL is safe (relative or same-origin).\n\n Prevents open redirect attacks by ensuring the URL is either:\n - A relative path (no scheme or netloc)\n - An absolute URL with an allowed hostname and safe scheme (http/https)\n\n Args:\n url: The URL to validate.\n allowed_hosts: Set of allowed hostnames. If None, only relative URLs are allowed.\n\n Returns:\n True if the URL is safe to redirect to, False otherwise.\n \"\"\"\n if not url:\n return False\n parsed = urlparse(url)\n # Allow relative URLs (no scheme and no netloc)\n if not parsed.scheme and not parsed.netloc:\n return True\n # Block non-http(s) schemes (e.g., javascript:, data:, etc.)\n if parsed.scheme not in (\"http\", \"https\"):\n return False\n # If allowed_hosts is provided, check hostname\n if allowed_hosts is not None:\n return parsed.hostname in allowed_hosts\n # No allowed_hosts and URL is absolute — reject by default\n return False\n\n\ndef _mask_sensitive_dict(\n data: dict,\n sensitive_keys: tuple = (\"access_token\", \"refresh_token\", \"token\", \"secret\", \"password\"),\n) -> dict:\n \"\"\"\n Recursively mask sensitive fields in a dictionary for safe logging.\n\n Args:\n data: Dictionary to process\n sensitive_keys: Tuple of key names to mask\n\n Returns:\n New dictionary with sensitive fields masked\n \"\"\"\n if not isinstance(data, dict):\n return data\n\n masked = {}\n for key, value in data.items():\n key_lower = key.lower()\n if any(sensitive in key_lower for sensitive in sensitive_keys):\n if isinstance(value, str) and value:\n masked[key] = mask_token(value)\n else:\n masked[key] = \"***MASKED***\"\n elif isinstance(value, dict):\n masked[key] = _mask_sensitive_dict(value, sensitive_keys)\n elif isinstance(value, list):\n masked[key] = [\n _mask_sensitive_dict(item, sensitive_keys) if isinstance(item, dict) else item\n for item in value\n ]\n else:\n masked[key] = value\n return masked\n\n\ndef mask_headers(headers: dict) -> dict:\n \"\"\"Mask sensitive headers for logging compliance.\"\"\"\n masked = {}\n for key, value in headers.items():\n key_lower = key.lower()\n if key_lower in [\"x-authorization\", \"authorization\", \"cookie\"]:\n if \"bearer\" in str(value).lower():\n # Extract token part and mask it\n parts = str(value).split(\" \", 1)\n if len(parts) == 2:\n masked[key] = f\"Bearer {mask_token(parts[1])}\"\n else:\n masked[key] = mask_token(value)\n else:\n masked[key] = \"***MASKED***\"\n elif key_lower in [\"x-user-pool-id\", \"x-client-id\"]:\n masked[key] = mask_sensitive_id(value)\n else:\n masked[key] = value\n return masked\n\n\nasync def map_groups_to_scopes(groups: list[str]) -> list[str]:\n \"\"\"\n Map identity provider groups to MCP scopes by querying DocumentDB directly.\n\n Args:\n groups: List of group names from identity provider (Cognito, Keycloak, etc.)\n\n Returns:\n List of MCP scopes\n \"\"\"\n scopes = []\n\n # Query DocumentDB directly for group mappings\n try:\n scope_repo = get_scope_repository()\n\n for group in groups:\n # Query DocumentDB for this group's scope mappings\n group_scopes = await scope_repo.get_group_mappings(group)\n if group_scopes:\n scopes.extend(group_scopes)\n logger.debug(f\"Mapped group '{group}' to scopes: {group_scopes}\")\n else:\n logger.debug(f\"No scope mapping found for group: {group}\")\n except Exception as e:\n logger.error(f\"Error querying group mappings from DocumentDB: {e}\", exc_info=True)\n # Fall back to in-memory config if DocumentDB query fails\n group_mappings = SCOPES_CONFIG.get(\"group_mappings\", {})\n for group in groups:\n if group in group_mappings:\n group_scopes = group_mappings[group]\n scopes.extend(group_scopes)\n logger.debug(f\"Mapped group '{group}' to scopes (fallback): {group_scopes}\")\n\n # Remove duplicates while preserving order\n seen = set()\n unique_scopes = []\n for scope in scopes:\n if scope not in seen:\n seen.add(scope)\n unique_scopes.append(scope)\n\n logger.info(f\"Final mapped scopes: {unique_scopes}\")\n return unique_scopes\n\n\nasync def validate_session_cookie(cookie_value: str) -> dict[str, any]:\n \"\"\"\n Validate session cookie using itsdangerous serializer.\n\n Args:\n cookie_value: The session cookie value\n\n Returns:\n Dict containing validation results matching JWT validation format:\n {\n 'valid': True,\n 'username': str,\n 'scopes': List[str],\n 'method': 'session_cookie',\n 'groups': List[str]\n }\n\n Raises:\n ValueError: If cookie is invalid or expired\n \"\"\"\n # Use global signer initialized at startup\n global signer\n if not signer:\n logger.warning(\"Global signer not configured for session cookie validation\")\n raise ValueError(\"Session cookie validation not configured\")\n\n try:\n # Decrypt cookie (max_age=28800 for 8 hours)\n data = signer.loads(cookie_value, max_age=28800)\n\n # Extract user info\n username = data.get(\"username\")\n groups = data.get(\"groups\", [])\n\n # Map groups to scopes (async call to query DocumentDB)\n scopes = await map_groups_to_scopes(groups)\n\n logger.info(f\"Session cookie validated for user: {hash_username(username)}\")\n\n return {\n \"valid\": True,\n \"username\": username,\n \"scopes\": scopes,\n \"method\": \"session_cookie\",\n \"groups\": groups,\n \"client_id\": \"\", # Not applicable for session\n \"data\": data, # Include full data for consistency\n }\n except SignatureExpired:\n logger.warning(\"Session cookie has expired\")\n raise ValueError(\"Session cookie has expired\")\n except BadSignature:\n logger.warning(\"Invalid session cookie signature\")\n raise ValueError(\"Invalid session cookie\")\n except Exception as e:\n logger.error(f\"Session cookie validation error: {e}\")\n raise ValueError(f\"Session cookie validation failed: {e}\")\n\n\ndef parse_server_and_tool_from_url(original_url: str) -> tuple[str | None, str | None]:\n \"\"\"\n Parse server name and tool name from the original URL and request payload.\n\n Args:\n original_url: The original URL from X-Original-URL header\n\n Returns:\n Tuple of (server_name, tool_name) or (None, None) if parsing fails\n \"\"\"\n try:\n # Extract path from URL (remove query parameters and fragments)\n from urllib.parse import urlparse\n\n parsed_url = urlparse(original_url)\n path = parsed_url.path.strip(\"/\")\n\n # The path should be in format: /server_name/...\n # Extract the first path component as server name\n path_parts = path.split(\"/\") if path else []\n server_name = path_parts[0] if path_parts else None\n\n logger.debug(f\"Parsed server name '{server_name}' from URL path: {path}\")\n return server_name, None # Tool name would need to be extracted from request payload\n\n except Exception as e:\n logger.error(f\"Failed to parse server/tool from URL {original_url}: {e}\")\n return None, None\n\n\ndef _normalize_server_name(name: str) -> str:\n \"\"\"\n Normalize server name by removing leading and trailing slashes for comparison.\n\n This handles cases where a server is registered with a leading or trailing\n slash but accessed without one (or vice versa). Scope configs from the UI\n store server names with a leading slash (e.g. '/cloudflare-docs') while the\n URL extraction produces names without one (e.g. 'cloudflare-docs').\n\n Args:\n name: Server name to normalize\n\n Returns:\n Normalized server name (without leading or trailing slashes)\n \"\"\"\n return name.strip(\"/\") if name else name\n\n\ndef _server_names_match(name1: str, name2: str) -> bool:\n \"\"\"\n Compare two server names, normalizing for trailing slashes.\n Supports wildcard matching with '*'.\n\n Args:\n name1: First server name (can be '*' for wildcard)\n name2: Second server name\n\n Returns:\n True if names match (ignoring trailing slashes) or if name1 is '*', False otherwise\n \"\"\"\n normalized_name1 = _normalize_server_name(name1)\n if normalized_name1 == \"*\":\n return True\n return normalized_name1 == _normalize_server_name(name2)\n\n\nasync def validate_server_tool_access(\n server_name: str, method: str, tool_name: str, user_scopes: list[str]\n) -> bool:\n \"\"\"\n Validate if the user has access to the specified server method/tool based on scopes.\n\n Args:\n server_name: Name of the MCP server\n method: Name of the method being accessed (e.g., 'initialize', 'notifications/initialized', 'tools/list')\n tool_name: Name of the specific tool being accessed (optional, for tools/call)\n user_scopes: List of user scopes from token\n\n Returns:\n True if access is allowed, False otherwise\n \"\"\"\n try:\n # Verbose logging: Print input parameters\n logger.info(\"=== VALIDATE_SERVER_TOOL_ACCESS START ===\")\n logger.info(f\"Requested server: '{server_name}'\")\n logger.info(f\"Requested method: '{method}'\")\n logger.info(f\"Requested tool: '{tool_name}'\")\n logger.info(f\"User scopes: {user_scopes}\")\n\n # Query DocumentDB directly for server access rules\n scope_repo = get_scope_repository()\n\n # Check each user scope to see if it grants access\n for scope in user_scopes:\n logger.info(f\"--- Checking scope: '{scope}' ---\")\n\n # Query DocumentDB for this scope's server access rules\n scope_config = await scope_repo.get_server_scopes(scope)\n\n if not scope_config:\n logger.info(f\"Scope '{scope}' not found in DocumentDB\")\n continue\n\n logger.info(f\"Scope '{scope}' config: {scope_config}\")\n\n # The scope_config is directly a list of server configurations\n # since the permission type is already encoded in the scope name\n for server_config in scope_config:\n logger.info(f\" Examining server config: {server_config}\")\n server_config_name = server_config.get(\"server\")\n logger.info(\n f\" Server name in config: '{server_config_name}' vs requested: '{server_name}'\"\n )\n\n if _server_names_match(server_config_name, server_name):\n logger.info(\" ✓ Server name matches!\")\n\n # Check methods first\n allowed_methods = server_config.get(\"methods\", [])\n logger.info(f\" Allowed methods for server '{server_name}': {allowed_methods}\")\n logger.info(f\" Checking if method '{method}' is in allowed methods...\")\n\n # Check if all methods are allowed (wildcard support)\n has_wildcard_methods = \"all\" in allowed_methods or \"*\" in allowed_methods\n\n # for all methods except tools/call we are good if the method is allowed\n # for tools/call we need to do an extra validation to check if the tool\n # itself is allowed or not\n if (\n method in allowed_methods or has_wildcard_methods\n ) and method != \"tools/call\":\n logger.info(f\" ✓ Method '{method}' found in allowed methods!\")\n logger.info(\n f\"Access granted: scope '{scope}' allows access to {server_name}.{method}\"\n )\n logger.info(\"=== VALIDATE_SERVER_TOOL_ACCESS END: GRANTED ===\")\n return True\n\n # Check tools if method not found in methods\n allowed_tools = server_config.get(\"tools\", [])\n logger.info(f\" Allowed tools for server '{server_name}': {allowed_tools}\")\n\n # Check if all tools are allowed (wildcard support)\n has_wildcard_tools = \"all\" in allowed_tools or \"*\" in allowed_tools\n\n # For tools/call, check if the specific tool is allowed\n if method == \"tools/call\" and tool_name:\n logger.info(\n f\" Checking if tool '{tool_name}' is in allowed tools for tools/call...\"\n )\n if tool_name in allowed_tools or has_wildcard_tools:\n logger.info(f\" ✓ Tool '{tool_name}' found in allowed tools!\")\n logger.info(\n f\"Access granted: scope '{scope}' allows access to {server_name}.{method} for tool {tool_name}\"\n )\n logger.info(\"=== VALIDATE_SERVER_TOOL_ACCESS END: GRANTED ===\")\n return True\n else:\n logger.info(f\" ✗ Tool '{tool_name}' NOT found in allowed tools\")\n else:\n # For other methods, check if method is in tools list (backward compatibility)\n logger.info(f\" Checking if method '{method}' is in allowed tools...\")\n if method in allowed_tools or has_wildcard_tools:\n logger.info(f\" ✓ Method '{method}' found in allowed tools!\")\n logger.info(\n f\"Access granted: scope '{scope}' allows access to {server_name}.{method}\"\n )\n logger.info(\"=== VALIDATE_SERVER_TOOL_ACCESS END: GRANTED ===\")\n return True\n else:\n logger.info(f\" ✗ Method '{method}' NOT found in allowed tools\")\n else:\n logger.info(\" ✗ Server name does not match\")\n\n logger.warning(\n f\"Access denied: no scope allows access to {server_name}.{method} (tool: {tool_name}) for user scopes: {user_scopes}\"\n )\n logger.info(\"=== VALIDATE_SERVER_TOOL_ACCESS END: DENIED ===\")\n return False\n\n except Exception as e:\n logger.error(f\"Error validating server/tool access: {e}\")\n logger.info(\"=== VALIDATE_SERVER_TOOL_ACCESS END: ERROR ===\")\n return False # Deny access on error\n\n\ndef validate_scope_subset(user_scopes: list[str], requested_scopes: list[str]) -> bool:\n \"\"\"\n Validate that requested scopes are a subset of user's current scopes.\n\n Args:\n user_scopes: List of scopes the user currently has\n requested_scopes: List of scopes being requested for the token\n\n Returns:\n True if requested scopes are valid (subset of user scopes), False otherwise\n \"\"\"\n if not requested_scopes:\n return True # Empty request is valid\n\n user_scope_set = set(user_scopes)\n requested_scope_set = set(requested_scopes)\n\n is_valid = requested_scope_set.issubset(user_scope_set)\n\n if not is_valid:\n invalid_scopes = requested_scope_set - user_scope_set\n logger.warning(f\"Invalid scopes requested: {invalid_scopes}\")\n\n return is_valid\n\n\ndef check_rate_limit(username: str) -> bool:\n \"\"\"\n Check if user has exceeded token generation rate limit.\n\n Args:\n username: Username to check\n\n Returns:\n True if under rate limit, False if exceeded\n \"\"\"\n current_time = int(time.time())\n current_hour = current_time // 3600\n\n # Clean up old entries (older than 1 hour)\n keys_to_remove = []\n for key in user_token_generation_counts.keys():\n stored_hour = int(key.split(\":\")[1])\n if current_hour - stored_hour > 1:\n keys_to_remove.append(key)\n\n for key in keys_to_remove:\n del user_token_generation_counts[key]\n\n # Check current hour count\n rate_key = f\"{username}:{current_hour}\"\n current_count = user_token_generation_counts.get(rate_key, 0)\n\n if current_count >= MAX_TOKENS_PER_USER_PER_HOUR:\n logger.warning(\n f\"Rate limit exceeded for user {hash_username(username)}: {current_count} tokens this hour\"\n )\n return False\n\n # Increment counter\n user_token_generation_counts[rate_key] = current_count + 1\n return True\n\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n \"\"\"Lifespan context manager for FastAPI application.\"\"\"\n # Startup: Load scopes configuration\n global SCOPES_CONFIG\n try:\n SCOPES_CONFIG = await reload_scopes_config()\n logger.info(\n f\"Loaded scopes configuration on startup with {len(SCOPES_CONFIG.get('group_mappings', {}))} group mappings\"\n )\n except Exception as e:\n logger.error(f\"Failed to load scopes configuration on startup: {e}\", exc_info=True)\n # Fall back to empty config\n SCOPES_CONFIG = {\"group_mappings\": {}}\n\n # Build multi-key static token map (Issue #779).\n # Runs after scopes are loaded so map_groups_to_scopes can resolve groups.\n await _build_static_token_map()\n\n yield\n\n # Shutdown: Add cleanup code here if needed in the future\n logger.info(\"Shutting down auth server\")\n\n\n# Create FastAPI app\napp = FastAPI(\n title=\"Simplified Auth Server\",\n description=\"Authentication server for validating JWT tokens against Amazon Cognito with header-based configuration\",\n version=\"0.1.0\",\n lifespan=lifespan,\n root_path=ROOT_PATH,\n)\n\n\n@app.on_event(\"startup\")\nasync def startup_event():\n \"\"\"Load scopes configuration on startup.\"\"\"\n global SCOPES_CONFIG\n try:\n SCOPES_CONFIG = await reload_scopes_config()\n logger.info(\n f\"Loaded scopes configuration on startup with {len(SCOPES_CONFIG.get('group_mappings', {}))} group mappings\"\n )\n except Exception as e:\n logger.error(f\"Failed to load scopes configuration on startup: {e}\", exc_info=True)\n # Fall back to empty config\n SCOPES_CONFIG = {\"group_mappings\": {}}\n\n\n# Add metrics collection middleware\nadd_auth_metrics_middleware(app)\n\n\nclass TokenValidationResponse(BaseModel):\n \"\"\"Response model for token validation\"\"\"\n\n valid: bool\n scopes: list[str] = []\n error: str | None = None\n method: str | None = None\n client_id: str | None = None\n username: str | None = None\n\n\nclass GenerateTokenRequest(BaseModel):\n \"\"\"Request model for token generation\"\"\"\n\n user_context: dict[str, Any]\n requested_scopes: list[str] = []\n expires_in_hours: int = DEFAULT_TOKEN_LIFETIME_HOURS\n description: str | None = None\n\n\nclass GenerateTokenResponse(BaseModel):\n \"\"\"Response model for token generation\"\"\"\n\n access_token: str\n refresh_token: str | None = None\n token_type: str = \"Bearer\" # nosec B105 - OAuth2 standard token type per RFC 6750\n expires_in: int\n refresh_expires_in: int | None = None\n scope: str\n issued_at: int\n description: str | None = None\n\n\nclass SimplifiedCognitoValidator:\n \"\"\"\n Simplified Cognito token validator that doesn't rely on environment variables\n \"\"\"\n\n def __init__(self, region: str = \"us-east-1\"):\n \"\"\"\n Initialize with minimal configuration\n\n Args:\n region: Default AWS region\n \"\"\"\n self.default_region = region\n self._cognito_clients = {} # Cache boto3 clients by region\n self._jwks_cache = {} # Cache JWKS by user pool\n\n def _get_cognito_client(self, region: str):\n \"\"\"Get or create boto3 cognito client for region\"\"\"\n if region not in self._cognito_clients:\n self._cognito_clients[region] = boto3.client(\"cognito-idp\", region_name=region)\n return self._cognito_clients[region]\n\n def _get_jwks(self, user_pool_id: str, region: str) -> dict:\n \"\"\"\n Get JSON Web Key Set (JWKS) from Cognito with caching\n \"\"\"\n cache_key = f\"{region}:{user_pool_id}\"\n\n if cache_key not in self._jwks_cache:\n try:\n issuer = f\"https://cognito-idp.{region}.amazonaws.com/{user_pool_id}\"\n jwks_url = f\"{issuer}/.well-known/jwks.json\"\n\n response = requests.get(jwks_url, timeout=10)\n response.raise_for_status()\n jwks = response.json()\n\n self._jwks_cache[cache_key] = jwks\n logger.debug(\n f\"Retrieved JWKS for {cache_key} with {len(jwks.get('keys', []))} keys\"\n )\n\n except Exception as e:\n logger.error(f\"Failed to retrieve JWKS from {jwks_url}: {e}\")\n raise ValueError(f\"Cannot retrieve JWKS: {e}\")\n\n return self._jwks_cache[cache_key]\n\n def validate_jwt_token(\n self, access_token: str, user_pool_id: str, client_id: str, region: str = None\n ) -> dict:\n \"\"\"\n Validate JWT access token\n\n Args:\n access_token: The bearer token to validate\n user_pool_id: Cognito User Pool ID\n client_id: Expected client ID\n region: AWS region (uses default if not provided)\n\n Returns:\n Dict containing token claims if valid\n\n Raises:\n ValueError: If token is invalid\n \"\"\"\n if not region:\n region = self.default_region\n\n try:\n # Decode header to get key ID\n unverified_header = jwt.get_unverified_header(access_token)\n kid = unverified_header.get(\"kid\")\n\n if not kid:\n raise ValueError(\"Token missing 'kid' in header\")\n\n # Get JWKS and find matching key\n jwks = self._get_jwks(user_pool_id, region)\n signing_key = None\n\n for key in jwks.get(\"keys\", []):\n if key.get(\"kid\") == kid:\n # Handle different versions of PyJWT\n try:\n # For newer versions of PyJWT\n from jwt.algorithms import RSAAlgorithm\n\n signing_key = RSAAlgorithm.from_jwk(key)\n except (ImportError, AttributeError):\n try:\n # For older versions of PyJWT\n from jwt.algorithms import get_default_algorithms\n\n algorithms = get_default_algorithms()\n signing_key = algorithms[\"RS256\"].from_jwk(key)\n except (ImportError, AttributeError):\n # For PyJWT 2.0.0+\n signing_key = PyJWK.from_jwk(json.dumps(key)).key\n break\n\n if not signing_key:\n raise ValueError(f\"No matching key found for kid: {kid}\")\n\n # Set up issuer for validation\n issuer = f\"https://cognito-idp.{region}.amazonaws.com/{user_pool_id}\"\n\n # Validate and decode token\n claims = jwt.decode(\n access_token,\n signing_key,\n algorithms=[\"RS256\"],\n issuer=issuer,\n options={\n \"verify_aud\": False, # M2M tokens might not have audience\n \"verify_exp\": True, # Always check expiration\n \"verify_iat\": True, # Check issued at time\n },\n )\n\n # Additional validations\n token_use = claims.get(\"token_use\")\n if token_use not in [\"access\", \"id\"]: # Allow both access and id tokens\n raise ValueError(f\"Invalid token_use: {token_use}\")\n\n # For M2M tokens, check client_id\n token_client_id = claims.get(\"client_id\")\n if token_client_id and token_client_id != client_id:\n logger.warning(\"Token issued for different client than expected\")\n # Don't fail immediately - could be user token with different structure\n\n logger.info(\"Successfully validated JWT token for client/user\")\n return claims\n\n except jwt.ExpiredSignatureError:\n error_msg = \"Token has expired\"\n logger.warning(error_msg)\n raise ValueError(error_msg)\n except jwt.InvalidTokenError as e:\n error_msg = f\"Invalid token: {e}\"\n logger.warning(error_msg)\n raise ValueError(error_msg)\n except Exception as e:\n error_msg = f\"JWT validation error: {e}\"\n logger.error(error_msg)\n raise ValueError(f\"Token validation failed: {e}\")\n\n def validate_with_boto3(self, access_token: str, region: str = None) -> dict:\n \"\"\"\n Validate token using boto3 GetUser API (works for user tokens)\n\n Args:\n access_token: The bearer token to validate\n region: AWS region\n\n Returns:\n Dict containing user information if valid\n\n Raises:\n ValueError: If token is invalid\n \"\"\"\n if not region:\n region = self.default_region\n\n try:\n cognito_client = self._get_cognito_client(region)\n response = cognito_client.get_user(AccessToken=access_token)\n\n # Extract user attributes\n user_attributes = {}\n for attr in response.get(\"UserAttributes\", []):\n user_attributes[attr[\"Name\"]] = attr[\"Value\"]\n\n result = {\n \"username\": response.get(\"Username\"),\n \"user_attributes\": user_attributes,\n \"user_status\": response.get(\"UserStatus\"),\n \"token_use\": \"access\", # boto3 method implies access token\n \"auth_method\": \"boto3\",\n }\n\n logger.info(\n f\"Successfully validated token via boto3 for user {hash_username(result['username'])}\"\n )\n return result\n\n except ClientError as e:\n error_code = e.response[\"Error\"][\"Code\"]\n error_message = e.response[\"Error\"][\"Message\"]\n\n if error_code == \"NotAuthorizedException\":\n error_msg = \"Invalid or expired access token\"\n logger.warning(f\"Cognito error {error_code}: {error_message}\")\n raise ValueError(error_msg)\n elif error_code == \"UserNotFoundException\":\n error_msg = \"User not found\"\n logger.warning(f\"Cognito error {error_code}: {error_message}\")\n raise ValueError(error_msg)\n else:\n logger.error(f\"Cognito error {error_code}: {error_message}\")\n raise ValueError(f\"Token validation failed: {error_message}\")\n\n except Exception as e:\n logger.error(f\"Boto3 validation error: {e}\")\n raise ValueError(f\"Token validation failed: {e}\")\n\n def validate_self_signed_token(self, access_token: str) -> dict:\n \"\"\"\n Validate self-signed JWT token generated by this auth server.\n\n Args:\n access_token: The JWT token to validate\n\n Returns:\n Dict containing validation results\n\n Raises:\n ValueError: If token is invalid\n \"\"\"\n try:\n # Decode and validate JWT using shared SECRET_KEY\n claims = jwt.decode(\n access_token,\n SECRET_KEY,\n algorithms=[\"HS256\"],\n issuer=JWT_ISSUER,\n audience=JWT_AUDIENCE,\n options={\n \"verify_exp\": True,\n \"verify_iat\": True,\n \"verify_iss\": True,\n \"verify_aud\": True,\n },\n leeway=30, # 30 second leeway for clock skew\n )\n\n # Validate token_use\n token_use = claims.get(\"token_use\")\n if token_use != \"access\": # nosec B105 - OAuth2 token type validation per RFC 6749, not a password\n raise ValueError(f\"Invalid token_use: {token_use}\")\n\n # Extract scopes from space-separated string\n scope_string = claims.get(\"scope\", \"\")\n scopes = scope_string.split() if scope_string else []\n\n # Extract groups from claims (for OAuth user tokens)\n groups = claims.get(\"groups\", [])\n if isinstance(groups, str):\n groups = [groups]\n\n logger.info(\n f\"Successfully validated self-signed token for user: {claims.get('sub')}, \"\n f\"groups: {groups}\"\n )\n\n return {\n \"valid\": True,\n \"method\": \"self_signed\",\n \"data\": claims,\n \"client_id\": claims.get(\"client_id\", \"user-generated\"),\n \"username\": claims.get(\"sub\", \"\"),\n \"expires_at\": claims.get(\"exp\"),\n \"scopes\": scopes,\n \"groups\": groups,\n \"token_type\": \"user_generated\",\n }\n\n except jwt.ExpiredSignatureError:\n error_msg = \"Self-signed token has expired\"\n logger.warning(error_msg)\n raise ValueError(error_msg)\n except jwt.InvalidTokenError as e:\n error_msg = f\"Invalid self-signed token: {e}\"\n logger.warning(error_msg)\n raise ValueError(error_msg)\n except Exception as e:\n error_msg = f\"Self-signed token validation error: {e}\"\n logger.error(error_msg)\n raise ValueError(f\"Self-signed token validation failed: {e}\")\n\n def validate_token(\n self, access_token: str, user_pool_id: str, client_id: str, region: str = None\n ) -> dict:\n \"\"\"\n Comprehensive token validation with fallback methods.\n Now supports both Cognito tokens and self-signed tokens.\n\n Args:\n access_token: The bearer token to validate\n user_pool_id: Cognito User Pool ID\n client_id: Expected client ID\n region: AWS region\n\n Returns:\n Dict containing validation results and token information\n \"\"\"\n if not region:\n region = self.default_region\n\n # First try self-signed token validation (faster)\n try:\n # Quick check if it might be our token by attempting to decode without verification\n unverified_claims = jwt.decode(access_token, options={\"verify_signature\": False})\n if unverified_claims.get(\"iss\") == JWT_ISSUER:\n logger.debug(\"Token appears to be self-signed, validating...\")\n return self.validate_self_signed_token(access_token)\n except Exception as e:\n # Not our token or malformed, continue to Cognito validation\n logger.debug(f\"Token is not self-signed or malformed, falling back to Cognito: {e}\")\n\n # Try JWT validation with Cognito\n try:\n jwt_claims = self.validate_jwt_token(access_token, user_pool_id, client_id, region)\n\n # Extract scopes and other info\n scopes = []\n if \"scope\" in jwt_claims:\n scopes = jwt_claims[\"scope\"].split() if jwt_claims[\"scope\"] else []\n\n return {\n \"valid\": True,\n \"method\": \"jwt\",\n \"data\": jwt_claims,\n \"client_id\": jwt_claims.get(\"client_id\") or \"\",\n \"username\": jwt_claims.get(\"cognito:username\") or jwt_claims.get(\"username\") or \"\",\n \"expires_at\": jwt_claims.get(\"exp\"),\n \"scopes\": scopes,\n \"groups\": jwt_claims.get(\"cognito:groups\", []),\n }\n\n except ValueError as jwt_error:\n logger.debug(f\"JWT validation failed: {jwt_error}, trying boto3\")\n\n # Try boto3 validation as fallback\n try:\n boto3_data = self.validate_with_boto3(access_token, region)\n\n return {\n \"valid\": True,\n \"method\": \"boto3\",\n \"data\": boto3_data,\n \"client_id\": \"\", # boto3 method doesn't provide client_id\n \"username\": boto3_data.get(\"username\") or \"\",\n \"user_attributes\": boto3_data.get(\"user_attributes\", {}),\n \"scopes\": [], # boto3 method doesn't provide scopes\n \"groups\": [],\n }\n\n except ValueError as boto3_error:\n logger.debug(f\"Boto3 validation failed: {boto3_error}\")\n raise ValueError(\n f\"All validation methods failed. JWT: {jwt_error}, Boto3: {boto3_error}\"\n )\n\n\n# Create global validator instance\nvalidator = SimplifiedCognitoValidator()\n\n\ndef _is_registry_api_request(\n original_url: str,\n) -> bool:\n \"\"\"Check if the request is for the Registry API (vs MCP Gateway).\n\n Registry API requests include:\n - /api/* - Core registry operations\n - /v0.1/* - Anthropic registry API and A2A agent API\n\n Args:\n original_url: The X-Original-URL header value from nginx.\n\n Returns:\n True if this is a registry API request, False if MCP gateway request.\n \"\"\"\n if not original_url:\n return False\n\n parsed = urlparse(original_url)\n path = parsed.path\n\n for pattern in REGISTRY_API_PATTERNS:\n if path.startswith(pattern):\n return True\n\n return False\n\n\ndef _check_registry_static_token(\n bearer_token: str,\n) -> dict | None:\n \"\"\"Return the identity payload if the bearer matches a configured static\n key, else None.\n\n Each pair-wise comparison uses hmac.compare_digest so individual\n comparisons are constant-time. We iterate all configured entries without\n early return as belt-and-braces so total comparison time is independent\n of which entry (if any) matched. With small N this matters less than the\n per-comparison guarantee, but costs almost nothing.\n\n For the legacy REGISTRY_API_TOKEN entry (map key \"legacy\"), the returned\n username and client_id are overridden to \"network-user\" /\n \"network-trusted\" to preserve back-compat with pre-#779 audit log\n consumers.\n\n See issue #779.\n \"\"\"\n bearer_bytes = bearer_token.encode(\"utf-8\")\n matched_entry: dict | None = None\n matched_name: str | None = None\n\n for name, entry in _STATIC_TOKEN_MAP.items():\n if hmac.compare_digest(bearer_bytes, entry[\"key_bytes\"]):\n if matched_entry is None:\n matched_entry = entry\n matched_name = name\n\n if matched_entry is None:\n return None\n\n username = matched_entry.get(\"username_override\", matched_name)\n client_id = matched_entry.get(\"client_id_override\", matched_name)\n\n return {\n \"username\": username,\n \"client_id\": client_id,\n \"groups\": list(matched_entry[\"groups\"]),\n \"scopes\": list(matched_entry[\"scopes\"]),\n }\n\n\ndef _is_federation_api_request(\n original_url: str,\n) -> bool:\n \"\"\"Check if the request is for federation or peer management APIs.\n\n Args:\n original_url: The X-Original-URL header value from nginx.\n\n Returns:\n True if this is a federation/peer API request.\n \"\"\"\n if not original_url:\n return False\n\n parsed = urlparse(original_url)\n path = parsed.path\n\n for pattern in FEDERATION_API_PATTERNS:\n if path.startswith(pattern):\n return True\n\n return False\n\n\n@app.get(\"/health\")\nasync def health_check():\n \"\"\"Health check endpoint\"\"\"\n return {\"status\": \"healthy\", \"service\": \"simplified-auth-server\"}\n\n\n@app.get(\"/validate\")\nasync def validate_request(request: Request):\n \"\"\"\n Validate a request by extracting configuration from headers and validating the bearer token.\n\n Expected headers:\n - Authorization: Bearer \n - X-User-Pool-Id: \n - X-Client-Id: \n - X-Region: (optional, defaults to us-east-1)\n - X-Original-URL: (optional, for scope validation)\n\n Returns:\n HTTP 200 with user info headers if valid, HTTP 401/403 if invalid\n\n Raises:\n HTTPException: If the token is missing, invalid, or configuration is incomplete\n \"\"\"\n\n # Capture start time for MCP audit logging\n import uuid\n\n start_time = time.perf_counter()\n request_id = request.headers.get(\"X-Request-ID\", str(uuid.uuid4()))\n mcp_session_id = request.headers.get(\"Mcp-Session-Id\")\n\n try:\n # Extract headers\n # Check for X-Authorization first (custom header used by this gateway)\n # Only if X-Authorization is not present, check standard Authorization header\n authorization = request.headers.get(\"X-Authorization\")\n if not authorization:\n authorization = request.headers.get(\"Authorization\")\n cookie_header = request.headers.get(\"Cookie\", \"\")\n user_pool_id = request.headers.get(\"X-User-Pool-Id\")\n client_id = request.headers.get(\"X-Client-Id\")\n region = request.headers.get(\"X-Region\", \"us-east-1\")\n original_url = request.headers.get(\"X-Original-URL\")\n body = request.headers.get(\"X-Body\")\n\n # Extract server_name and endpoint from original_url early for logging\n server_name_from_url = None\n endpoint_from_url = None\n if original_url:\n try:\n parsed_url = urlparse(original_url)\n path = parsed_url.path.strip(\"/\")\n\n # Strip the registry's root path prefix so server_name extraction\n # works correctly when the registry is hosted on a sub-path (e.g. /registry)\n registry_prefix = REGISTRY_ROOT_PATH.strip(\"/\")\n if registry_prefix and path.startswith(registry_prefix):\n path = path[len(registry_prefix) :].lstrip(\"/\")\n\n path_parts = path.split(\"/\") if path else []\n\n # MCP endpoints that should be treated as endpoints, not server names\n mcp_endpoints = {\"mcp\", \"sse\", \"messages\"}\n\n # For peer/federated registries, path is: peer-name/server-name/endpoint\n # For local servers, path is: server-name/endpoint\n # We need to capture the full server path, excluding the MCP endpoint\n if len(path_parts) >= 2 and path_parts[-1] in mcp_endpoints:\n # Last part is MCP endpoint, everything before is server path\n server_name_from_url = \"/\".join(path_parts[:-1])\n endpoint_from_url = path_parts[-1]\n elif len(path_parts) >= 1:\n # No recognized MCP endpoint at end - use entire path as server name\n # This handles MCP server URLs like /peer-registry-lob-1/cloudflare-docs\n # BUT exclude /api/ paths - those are Registry API requests, not MCP servers\n if path_parts[0] != \"api\":\n server_name_from_url = \"/\".join(path_parts)\n endpoint_from_url = None\n\n logger.info(\n f\"Extracted server_name '{server_name_from_url}' and endpoint '{endpoint_from_url}' from original_url: {original_url}\"\n )\n except Exception as e:\n logger.warning(\n f\"Failed to extract server_name from original_url {original_url}: {e}\"\n )\n\n # Read request body\n request_payload = None\n try:\n if body:\n payload_text = body # .decode('utf-8')\n logger.info(\n f\"Raw Request Payload ({len(payload_text)} chars): {payload_text[:1000]}...\"\n )\n request_payload = json.loads(payload_text)\n logger.info(f\"JSON RPC Request Payload: {json.dumps(request_payload, indent=2)}\")\n else:\n logger.info(\"No request body provided, skipping payload parsing\")\n except UnicodeDecodeError as e:\n logger.warning(f\"Could not decode body as UTF-8: {e}\")\n except json.JSONDecodeError as e:\n logger.warning(f\"Could not parse JSON RPC payload: {e}\")\n except Exception as e:\n logger.error(f\"Error reading request payload: {type(e).__name__}: {e}\")\n\n # Log request for debugging with anonymized IP\n client_ip = get_client_ip(request)\n logger.info(f\"Validation request from {anonymize_ip(client_ip)}\")\n logger.info(f\"Request Method: {request.method}\")\n\n # Log masked HTTP headers for GDPR/SOX compliance\n all_headers = dict(request.headers)\n masked_headers = mask_headers(all_headers)\n logger.debug(f\"HTTP Headers (masked): {json.dumps(masked_headers, indent=2)}\")\n\n # Log specific headers for debugging with masked sensitive data\n logger.info(\n f\"Key Headers: Authorization={bool(authorization)}, Cookie={bool(cookie_header)}, \"\n f\"User-Pool-Id={mask_sensitive_id(user_pool_id) if user_pool_id else 'None'}, \"\n f\"Client-Id={mask_sensitive_id(client_id) if client_id else 'None'}, \"\n f\"Region={region}, Original-URL={original_url}\"\n )\n logger.info(f\"Server Name from URL: {server_name_from_url}\")\n\n # Only activate static token auth when there is no session cookie\n # (UI uses cookies, CLI uses Bearer)\n has_session_cookie = cookie_header and \"mcp_gateway_session=\" in cookie_header\n\n # Federation static token auth: scoped access to federation/peer endpoints only\n # Check this BEFORE the full admin static token\n if (\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED\n and _is_federation_api_request(original_url)\n and not has_session_cookie\n ):\n if not authorization:\n logger.warning(\n \"Federation static token: Authorization header missing. \"\n \"Hint: Use 'Authorization: Bearer '.\"\n )\n return JSONResponse(\n content={\"detail\": \"Authorization header required\"},\n status_code=401,\n headers={\"WWW-Authenticate\": \"Bearer\", \"Connection\": \"close\"},\n )\n\n if not authorization.startswith(\"Bearer \"):\n logger.warning(\n \"Federation static token: Authorization header must use Bearer scheme\"\n )\n return JSONResponse(\n content={\"detail\": \"Authorization header must use Bearer scheme\"},\n status_code=401,\n headers={\"WWW-Authenticate\": \"Bearer\", \"Connection\": \"close\"},\n )\n\n bearer_token = authorization[len(\"Bearer \") :].strip()\n\n # Check federation token first, then fall through to admin token check\n if hmac.compare_digest(bearer_token, FEDERATION_STATIC_TOKEN):\n logger.info(f\"Federation static token: Authenticated for {original_url}\")\n\n federation_scopes = [\n \"federation/read\",\n \"federation/peers\",\n ]\n response_data = {\n \"valid\": True,\n \"username\": \"federation-peer\",\n \"client_id\": \"federation-static\",\n \"scopes\": federation_scopes,\n \"method\": \"federation-static\",\n \"groups\": [],\n \"server_name\": None,\n \"tool_name\": None,\n }\n\n response = JSONResponse(content=response_data, status_code=200)\n response.headers[\"X-User\"] = \"federation-peer\"\n response.headers[\"X-Username\"] = \"federation-peer\"\n response.headers[\"X-Client-Id\"] = \"federation-static\"\n response.headers[\"X-Scopes\"] = \" \".join(federation_scopes)\n response.headers[\"X-Auth-Method\"] = \"federation-static\"\n response.headers[\"X-Server-Name\"] = \"\"\n response.headers[\"X-Tool-Name\"] = \"\"\n\n return response\n\n # If federation token didn't match, DON'T return 403 here.\n # Fall through to the admin static token check below (if enabled).\n # If admin token also doesn't match, that block will return 403.\n # If admin token is NOT enabled, fall through to JWT validation.\n\n # Static token auth: accept REGISTRY_API_TOKEN as an ADDITIONAL accepted\n # credential on Registry API paths. A missing or mismatched bearer falls\n # through to JWT/session validation so Okta tokens and UI-issued self-\n # signed JWTs remain accepted. See issue #871.\n #\n # Extension point for #779 (multi-key static tokens) is the helper\n # _check_registry_static_token; the control flow here does not change.\n if (\n REGISTRY_STATIC_TOKEN_AUTH_ENABLED\n and _is_registry_api_request(original_url)\n and not has_session_cookie\n ):\n if authorization and authorization.startswith(\"Bearer \"):\n bearer_token = authorization[len(\"Bearer \") :].strip()\n identity = _check_registry_static_token(bearer_token)\n if identity is not None:\n logger.info(\n \"Network-trusted mode: key='%s' for %s\",\n identity[\"username\"],\n original_url,\n )\n\n response_data = {\n \"valid\": True,\n \"username\": identity[\"username\"],\n \"client_id\": identity[\"client_id\"],\n \"scopes\": identity[\"scopes\"],\n \"method\": \"network-trusted\",\n \"groups\": identity[\"groups\"],\n \"server_name\": None,\n \"tool_name\": None,\n }\n\n response = JSONResponse(content=response_data, status_code=200)\n response.headers[\"X-User\"] = identity[\"username\"]\n response.headers[\"X-Username\"] = identity[\"username\"]\n response.headers[\"X-Client-Id\"] = identity[\"client_id\"]\n response.headers[\"X-Scopes\"] = \" \".join(identity[\"scopes\"])\n response.headers[\"X-Auth-Method\"] = \"network-trusted\"\n response.headers[\"X-Server-Name\"] = \"\"\n response.headers[\"X-Tool-Name\"] = \"\"\n\n return response\n\n # Bearer present but does not match any static token. Fall\n # through to JWT validation below (Okta RS256 / self-signed\n # HS256). Intentionally does NOT log any portion of the bearer.\n logger.debug(\"Static token mismatch; falling through to JWT validation\")\n else:\n # No Authorization header or non-Bearer scheme. Fall through to\n # session/JWT validation, which returns 401 if nothing matches.\n logger.debug(\n \"Registry API request without Bearer credential; \"\n \"falling through to session/JWT validation\"\n )\n\n # Initialize validation result\n validation_result = None\n\n # FIRST: Check for session cookie if present\n if \"mcp_gateway_session=\" in cookie_header:\n logger.info(\"Session cookie detected, attempting session validation\")\n # Extract cookie value\n cookie_value = None\n for cookie in cookie_header.split(\";\"):\n if cookie.strip().startswith(\"mcp_gateway_session=\"):\n cookie_value = cookie.strip().split(\"=\", 1)[1]\n break\n\n if cookie_value:\n try:\n validation_result = await validate_session_cookie(cookie_value)\n # Log validation result without exposing username or tokens\n safe_result = _mask_sensitive_dict(validation_result)\n safe_result[\"username\"] = hash_username(validation_result.get(\"username\", \"\"))\n logger.info(f\"Session cookie validation result: {safe_result}\")\n logger.info(\n f\"Session cookie validation successful for user: {hash_username(validation_result['username'])}\"\n )\n except ValueError as e:\n logger.warning(f\"Session cookie validation failed: {e}\")\n # Fall through to JWT validation\n\n # SECOND: If no valid session cookie, check for JWT token\n if not validation_result:\n # Validate required headers for JWT\n if not authorization or not authorization.startswith(\"Bearer \"):\n logger.warning(\n \"Missing or invalid Authorization header and no valid session cookie\"\n )\n raise HTTPException(\n status_code=401,\n detail=\"Missing or invalid Authorization header. Expected: Bearer or valid session cookie\",\n headers={\"WWW-Authenticate\": \"Bearer\", \"Connection\": \"close\"},\n )\n\n # Extract token\n access_token = authorization.split(\" \")[1]\n\n # Get authentication provider based on AUTH_PROVIDER environment variable\n try:\n auth_provider = get_auth_provider()\n logger.info(f\"Using authentication provider: {auth_provider.__class__.__name__}\")\n\n # Provider-specific validation\n if hasattr(auth_provider, \"validate_token\"):\n # For Keycloak, no additional headers needed\n validation_result = auth_provider.validate_token(access_token)\n logger.info(\n f\"Token validation successful using {auth_provider.__class__.__name__}\"\n )\n else:\n # Fallback to old validation for compatibility\n if not user_pool_id:\n logger.warning(\"Missing X-User-Pool-Id header for Cognito validation\")\n raise HTTPException(\n status_code=400,\n detail=\"Missing X-User-Pool-Id header\",\n headers={\"Connection\": \"close\"},\n )\n\n if not client_id:\n logger.warning(\"Missing X-Client-Id header for Cognito validation\")\n raise HTTPException(\n status_code=400,\n detail=\"Missing X-Client-Id header\",\n headers={\"Connection\": \"close\"},\n )\n\n # Use old validator for backward compatibility\n validation_result = validator.validate_token(\n access_token=access_token,\n user_pool_id=user_pool_id,\n client_id=client_id,\n region=region,\n )\n\n except Exception as e:\n logger.error(f\"Authentication provider error: {e}\")\n raise HTTPException(\n status_code=500,\n detail=\"Authentication provider configuration error\",\n headers={\"Connection\": \"close\"},\n )\n\n logger.info(f\"Token validation successful using method: {validation_result['method']}\")\n\n # Enrich groups from MongoDB if empty (for M2M clients)\n try:\n from mongodb_groups_enrichment import (\n enrich_groups_from_mongodb,\n should_enrich_groups,\n )\n\n client_id = validation_result.get(\"client_id\")\n current_groups = validation_result.get(\"groups\", [])\n should_enrich = should_enrich_groups(validation_result)\n logger.info(\n f\"Enrichment check: client_id={client_id}, \"\n f\"groups={current_groups}, should_enrich={should_enrich}\"\n )\n\n if should_enrich:\n enriched_groups = await enrich_groups_from_mongodb(client_id, current_groups)\n\n if enriched_groups != current_groups:\n validation_result[\"groups\"] = enriched_groups\n logger.info(\n f\"Groups enriched from MongoDB for client {client_id}: {enriched_groups}\"\n )\n except Exception as e:\n logger.warning(f\"Failed to enrich groups from MongoDB: {e}\")\n # Don't fail validation if enrichment fails\n\n # Parse server and tool information from original URL if available\n server_name = server_name_from_url # Use the server_name we extracted earlier\n tool_name = None\n\n if original_url and request_payload:\n # We already extracted server_name above, now just get tool_name from URL parsing\n _, tool_name = parse_server_and_tool_from_url(original_url)\n logger.debug(f\"Parsed from original URL: server='{server_name}', tool='{tool_name}'\")\n\n # Try to extract tool name from request payload if not found in URL\n if server_name and not tool_name and request_payload:\n try:\n # Look for tool name in JSON-RPC 2.0 format and other MCP patterns\n if isinstance(request_payload, dict):\n # JSON-RPC 2.0 format: method field contains the tool name\n tool_name = request_payload.get(\"method\")\n\n # If not found in method, check other common patterns\n if not tool_name:\n tool_name = request_payload.get(\"tool\") or request_payload.get(\"name\")\n\n # Check for nested tool reference in params\n if not tool_name and \"params\" in request_payload:\n params = request_payload[\"params\"]\n if isinstance(params, dict):\n tool_name = (\n params.get(\"name\") or params.get(\"tool\") or params.get(\"method\")\n )\n\n logger.info(f\"Extracted tool name from JSON-RPC payload: '{tool_name}'\")\n else:\n logger.warning(f\"Payload is not a dictionary: {type(request_payload)}\")\n except Exception as e:\n logger.error(f\"Error processing request payload for tool extraction: {e}\")\n\n # Validate scope-based access if we have server/tool information\n # For providers that use groups (Keycloak, Entra ID, Cognito, Okta, Auth0), map groups to scopes\n user_groups = validation_result.get(\"groups\", [])\n auth_method = validation_result.get(\"method\", \"\")\n if user_groups and auth_method in [\"keycloak\", \"entra\", \"cognito\", \"okta\", \"auth0\"]:\n # Map IdP groups to scopes using the group mappings (query DocumentDB)\n user_scopes = await map_groups_to_scopes(user_groups)\n logger.info(f\"Mapped {auth_method} groups {user_groups} to scopes: {user_scopes}\")\n else:\n user_scopes = validation_result.get(\"scopes\", [])\n if server_name:\n # For ANY server access, enforce scope validation (fail closed principle)\n # This includes MCP initialization methods that may not have a specific tool\n\n # Determine the method to validate:\n # 1. If we have a tool_name from JSON-RPC payload, use that\n # 2. If we have an endpoint from the REST API URL, use that\n # 3. Otherwise default to \"initialize\"\n method = (\n tool_name\n if tool_name\n else (endpoint_from_url if endpoint_from_url else \"initialize\")\n )\n logger.info(\n f\"Method determined for validation: '{method}' (tool_name={tool_name}, endpoint_from_url={endpoint_from_url})\"\n )\n actual_tool_name = None\n\n # For tools/call, extract the actual tool name from params\n if method == \"tools/call\" and isinstance(request_payload, dict):\n params = request_payload.get(\"params\", {})\n if isinstance(params, dict):\n actual_tool_name = params.get(\"name\")\n logger.info(f\"Extracted actual tool name for tools/call: '{actual_tool_name}'\")\n\n # Check if user has any scopes - if not, deny access (fail closed)\n if not user_scopes:\n logger.warning(\n f\"Access denied for user {hash_username(validation_result.get('username', ''))} to {server_name}.{method} (tool: {actual_tool_name}) - no scopes configured\"\n )\n raise HTTPException(\n status_code=403,\n detail=f\"Access denied to {server_name}.{method} - user has no scopes configured\",\n headers={\"Connection\": \"close\"},\n )\n\n if not await validate_server_tool_access(\n server_name, method, actual_tool_name, user_scopes\n ):\n logger.warning(\n f\"Access denied for user {hash_username(validation_result.get('username', ''))} to {server_name}.{method} (tool: {actual_tool_name})\"\n )\n raise HTTPException(\n status_code=403,\n detail=f\"Access denied to {server_name}.{method}\",\n headers={\"Connection\": \"close\"},\n )\n logger.info(\n f\"Scope validation passed for {server_name}.{method} (tool: {actual_tool_name})\"\n )\n else:\n logger.debug(\"No server information available, skipping scope validation\")\n\n # Prepare JSON response data\n response_data = {\n \"valid\": True,\n \"username\": validation_result.get(\"username\") or \"\",\n \"client_id\": validation_result.get(\"client_id\") or \"\",\n \"scopes\": user_scopes,\n \"method\": validation_result.get(\"method\") or \"\",\n \"groups\": validation_result.get(\"groups\", []),\n \"server_name\": server_name,\n \"tool_name\": tool_name,\n }\n logger.info(\n f\"Full validation result: {json.dumps(_mask_sensitive_dict(validation_result), indent=2)}\"\n )\n logger.info(f\"Response data being sent: {json.dumps(response_data, indent=2)}\")\n\n # Log MCP server access event if this is an MCP request (has server_name)\n if server_name:\n duration_ms = (time.perf_counter() - start_time) * 1000\n mcp_logger = get_mcp_logger()\n if mcp_logger:\n try:\n # Build identity from validation result\n identity = Identity(\n username=validation_result.get(\"username\") or \"anonymous\",\n auth_method=validation_result.get(\"method\") or \"unknown\",\n provider=validation_result.get(\"provider\"),\n groups=validation_result.get(\"groups\", []),\n scopes=user_scopes,\n is_admin=validation_result.get(\"is_admin\", False),\n credential_type=\"bearer_token\" if authorization else \"session_cookie\",\n )\n\n # Build MCP server info\n mcp_server = MCPServer(\n name=server_name,\n path=f\"/{server_name}\" if server_name else \"/\",\n proxy_target=original_url or \"\",\n )\n\n # Log the MCP access event\n await mcp_logger.log_mcp_access(\n request_id=request_id,\n identity=identity,\n mcp_server=mcp_server,\n request_body=body.encode(\"utf-8\") if body else b\"\",\n response_status=\"success\",\n duration_ms=duration_ms,\n mcp_session_id=mcp_session_id,\n transport=\"streamable-http\", # Default, could be extracted from request\n client_ip=get_client_ip(request),\n forwarded_for=request.headers.get(\"X-Forwarded-For\"),\n user_agent=request.headers.get(\"User-Agent\"),\n )\n logger.debug(f\"MCP access logged for {server_name}\")\n except Exception as e:\n # Don't fail the request if logging fails\n logger.warning(f\"Failed to log MCP access event: {e}\")\n\n # Create JSON response with headers that nginx can use\n response = JSONResponse(content=response_data, status_code=200)\n\n # Set headers for nginx auth_request_set directives\n response.headers[\"X-User\"] = validation_result.get(\"username\") or \"\"\n response.headers[\"X-Username\"] = validation_result.get(\"username\") or \"\"\n response.headers[\"X-Client-Id\"] = validation_result.get(\"client_id\") or \"\"\n response.headers[\"X-Scopes\"] = \" \".join(user_scopes)\n response.headers[\"X-Auth-Method\"] = validation_result.get(\"method\") or \"\"\n response.headers[\"X-Server-Name\"] = server_name or \"\"\n response.headers[\"X-Tool-Name\"] = tool_name or \"\"\n response.headers[\"X-Groups\"] = \" \".join(validation_result.get(\"groups\", []))\n\n return response\n\n except ValueError as e:\n logger.warning(f\"Token validation failed: {e}\")\n # Log failed MCP access attempt\n if server_name_from_url:\n duration_ms = (time.perf_counter() - start_time) * 1000\n mcp_logger = get_mcp_logger()\n if mcp_logger:\n try:\n identity = Identity(\n username=\"anonymous\",\n auth_method=\"unknown\",\n credential_type=\"none\",\n )\n mcp_server = MCPServer(\n name=server_name_from_url,\n path=f\"/{server_name_from_url}\",\n proxy_target=original_url or \"\",\n )\n await mcp_logger.log_mcp_access(\n request_id=request_id,\n identity=identity,\n mcp_server=mcp_server,\n request_body=body.encode(\"utf-8\") if body else b\"\",\n response_status=\"error\",\n duration_ms=duration_ms,\n mcp_session_id=mcp_session_id,\n error_code=401,\n error_message=str(e),\n client_ip=get_client_ip(request),\n forwarded_for=request.headers.get(\"X-Forwarded-For\"),\n user_agent=request.headers.get(\"User-Agent\"),\n )\n except Exception as log_err:\n logger.warning(f\"Failed to log MCP access error: {log_err}\")\n raise HTTPException(\n status_code=401,\n detail=str(e),\n headers={\"WWW-Authenticate\": \"Bearer\", \"Connection\": \"close\"},\n )\n except HTTPException as e:\n # Re-raise client error HTTPExceptions (4xx) as-is\n if 400 <= e.status_code < 500:\n raise\n # For non-client HTTPExceptions, convert to 500\n logger.error(f\"HTTP error during validation: {e}\")\n raise HTTPException(\n status_code=500,\n detail=\"Internal validation error\",\n headers={\"Connection\": \"close\"},\n )\n except Exception as e:\n logger.exception(\"Unexpected error during validation\")\n raise HTTPException(\n status_code=500,\n detail=\"Internal validation error\",\n headers={\"Connection\": \"close\"},\n )\n finally:\n pass\n\n\n@app.get(\"/config\")\nasync def get_auth_config():\n \"\"\"Return the authentication configuration info\"\"\"\n try:\n auth_provider = get_auth_provider()\n provider_info = auth_provider.get_provider_info()\n\n if provider_info.get(\"provider_type\") == \"keycloak\":\n return {\n \"auth_type\": \"keycloak\",\n \"description\": \"Keycloak JWT token validation\",\n \"required_headers\": [\"Authorization: Bearer \"],\n \"optional_headers\": [],\n \"provider_info\": provider_info,\n }\n else:\n return {\n \"auth_type\": \"cognito\",\n \"description\": \"Header-based Cognito token validation\",\n \"required_headers\": [\n \"Authorization: Bearer \",\n \"X-User-Pool-Id: \",\n \"X-Client-Id: \",\n ],\n \"optional_headers\": [\"X-Region: (default: us-east-1)\"],\n \"provider_info\": provider_info,\n }\n except Exception as e:\n logger.exception(\"Error getting auth config\")\n return {\n \"auth_type\": \"unknown\",\n \"description\": \"Error getting provider config\",\n \"error\": \"Internal server error\",\n }\n\n\n@app.post(\"/admin/federation-token\")\nasync def manage_federation_token(request: Request):\n \"\"\"Revoke or rotate federation static token at runtime.\n\n Requires the admin static token (REGISTRY_API_TOKEN) for authentication.\n \"\"\"\n global FEDERATION_STATIC_TOKEN, FEDERATION_STATIC_TOKEN_AUTH_ENABLED\n\n # Authenticate with admin token\n authorization = request.headers.get(\"Authorization\", \"\")\n if not authorization.startswith(\"Bearer \"):\n return JSONResponse(\n content={\"detail\": \"Bearer token required\"},\n status_code=401,\n )\n\n bearer_token = authorization[len(\"Bearer \") :].strip()\n if not REGISTRY_API_TOKEN or not hmac.compare_digest(bearer_token, REGISTRY_API_TOKEN):\n return JSONResponse(\n content={\"detail\": \"Admin token required\"},\n status_code=403,\n )\n\n body = await request.json()\n new_token = body.get(\"new_token\")\n\n # Validate minimum token length if a new token is provided\n if new_token and len(new_token) < MIN_FEDERATION_TOKEN_LENGTH:\n return JSONResponse(\n content={\n \"detail\": (\n f\"Token must be at least {MIN_FEDERATION_TOKEN_LENGTH} characters. \"\n 'Generate with: python3 -c \"import secrets; print(secrets.token_urlsafe(32))\"'\n )\n },\n status_code=400,\n )\n\n if new_token:\n FEDERATION_STATIC_TOKEN = new_token\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED = True\n logger.info(\"Federation static token rotated via admin API\")\n return {\n \"action\": \"rotated\",\n \"message\": (\n \"Federation static token rotated. \"\n \"WARNING: This is an in-memory change only. Update FEDERATION_STATIC_TOKEN \"\n \"in your .env file or container environment for persistence across restarts.\"\n ),\n }\n else:\n FEDERATION_STATIC_TOKEN = \"\" # nosec B105 - Intentional token revocation, clearing the variable\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED = False\n logger.info(\"Federation static token revoked via admin API\")\n return {\n \"action\": \"revoked\",\n \"message\": (\n \"Federation static token revoked. Federation endpoints now require OAuth2 JWT. \"\n \"WARNING: This is an in-memory change only. Update your .env file or container \"\n \"environment to set FEDERATION_STATIC_TOKEN_AUTH_ENABLED=false for persistence \"\n \"across restarts.\"\n ),\n }\n\n\n@app.post(\"/internal/tokens\", response_model=GenerateTokenResponse)\nasync def generate_user_token(request: GenerateTokenRequest):\n \"\"\"\n Generate or refresh a JWT token for a user.\n\n This endpoint supports two modes:\n 1. If user has stored OAuth tokens (from login), refresh them if needed and return\n 2. Otherwise, fall back to generating M2M token using client credentials\n\n This is an internal API endpoint meant to be called only by the registry service.\n The generated token will have the same or fewer privileges than the user currently has.\n\n Args:\n request: Token generation request containing user context and requested scopes\n\n Returns:\n JWT token with expiration info (either refreshed user token or M2M token)\n\n Raises:\n HTTPException: If request is invalid or user doesn't have required permissions\n \"\"\"\n try:\n # Extract user context\n user_context = request.user_context\n username = user_context.get(\"username\")\n user_scopes = user_context.get(\"scopes\", [])\n\n if not username:\n raise HTTPException(\n status_code=400,\n detail=\"Username is required in user context\",\n headers={\"Connection\": \"close\"},\n )\n\n # Check rate limiting\n if not check_rate_limit(username):\n raise HTTPException(\n status_code=429,\n detail=f\"Rate limit exceeded. Maximum {MAX_TOKENS_PER_USER_PER_HOUR} tokens per hour.\",\n headers={\"Connection\": \"close\"},\n )\n\n # Use user's current scopes if no specific scopes requested\n requested_scopes = request.requested_scopes if request.requested_scopes else user_scopes\n\n # Validate that requested scopes are subset of user's current scopes\n if not validate_scope_subset(user_scopes, requested_scopes):\n invalid_scopes = set(requested_scopes) - set(user_scopes)\n raise HTTPException(\n status_code=403,\n detail=f\"Requested scopes exceed user permissions. Invalid scopes: {list(invalid_scopes)}\",\n headers={\"Connection\": \"close\"},\n )\n\n # Check if user has stored OAuth tokens from their login session\n provider = user_context.get(\"provider\")\n auth_method = user_context.get(\"auth_method\")\n user_groups = user_context.get(\"groups\", [])\n user_email = user_context.get(\"email\", \"\")\n\n logger.info(\n f\"Token request for user '{hash_username(username)}': \"\n f\"auth_method={auth_method}, provider={provider}, \"\n f\"groups={user_groups}, scopes={requested_scopes}\"\n )\n\n # For OAuth and network-trusted users, generate a self-signed JWT with their identity and groups\n # This token is issued by our auth server and can be verified using SECRET_KEY\n if auth_method in (\"oauth2\", \"network-trusted\"):\n logger.info(\n f\"Generating self-signed JWT for {auth_method} user '{hash_username(username)}' \"\n f\"with groups: {user_groups}\"\n )\n\n current_time = int(time.time())\n expires_in = DEFAULT_TOKEN_LIFETIME_HOURS * 3600 # 8 hours default\n\n # Build JWT claims\n jwt_claims = {\n \"iss\": JWT_ISSUER,\n \"aud\": JWT_AUDIENCE,\n \"sub\": username,\n \"preferred_username\": username,\n \"email\": user_email,\n \"groups\": user_groups,\n \"scope\": \" \".join(requested_scopes) if requested_scopes else \"\",\n \"token_use\": \"access\",\n \"auth_method\": auth_method,\n \"provider\": provider,\n \"iat\": current_time,\n \"exp\": current_time + expires_in,\n \"description\": request.description,\n }\n\n # Sign the JWT with our SECRET_KEY\n access_token = jwt.encode(jwt_claims, SECRET_KEY, algorithm=\"HS256\")\n\n logger.info(\n f\"Generated self-signed JWT for user '{hash_username(username)}', \"\n f\"expires in {expires_in} seconds\"\n )\n\n return GenerateTokenResponse(\n access_token=access_token,\n refresh_token=None,\n expires_in=expires_in,\n refresh_expires_in=0,\n scope=\" \".join(requested_scopes) if requested_scopes else \"openid profile email\",\n issued_at=current_time,\n description=request.description,\n )\n\n # Fall back to M2M token using client credentials flow\n try:\n auth_provider = get_auth_provider()\n provider_info = auth_provider.get_provider_info()\n provider_type = provider_info.get(\"provider_type\", \"unknown\")\n\n logger.info(\n f\"Generating M2M token for user '{hash_username(username)}' using {provider_type}\"\n )\n\n if provider_type == \"keycloak\":\n # Request token from Keycloak using M2M client credentials\n token_data = auth_provider.get_m2m_token(scope=\"openid email profile\")\n elif provider_type == \"entra\":\n # Request token from Entra ID using client credentials\n token_data = auth_provider.get_m2m_token()\n else:\n raise HTTPException(\n status_code=500,\n detail=f\"Token generation not supported for provider: {provider_type}\",\n headers={\"Connection\": \"close\"},\n )\n\n access_token = token_data.get(\"access_token\")\n refresh_token_value = token_data.get(\"refresh_token\")\n expires_in = token_data.get(\"expires_in\", 300)\n refresh_expires_in = token_data.get(\"refresh_expires_in\", 0)\n scope = token_data.get(\"scope\", \"openid email profile\")\n\n if not access_token:\n raise ValueError(f\"No access token returned from {provider_type}\")\n\n current_time = int(time.time())\n\n logger.info(\n f\"Generated {provider_type} M2M token for user '{hash_username(username)}' \"\n f\"with scopes: {requested_scopes}, expires in {expires_in} seconds\"\n )\n\n return GenerateTokenResponse(\n access_token=access_token,\n refresh_token=refresh_token_value,\n expires_in=expires_in,\n refresh_expires_in=refresh_expires_in,\n scope=scope,\n issued_at=current_time,\n description=request.description,\n )\n\n except ValueError as e:\n logger.error(f\"Token generation failed: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to generate token: {e}\",\n headers={\"Connection\": \"close\"},\n )\n\n except HTTPException:\n raise\n except Exception as e:\n logger.error(f\"Unexpected error generating token: {e}\")\n raise HTTPException(\n status_code=500,\n detail=\"Internal error generating token\",\n headers={\"Connection\": \"close\"},\n )\n\n\n@app.post(\"/internal/reload-scopes\")\nasync def reload_scopes(request: Request, authorization: str | None = Header(None)):\n \"\"\"\n Reload the scopes configuration.\n\n Accepts internal service authentication via self-signed JWT (Bearer token)\n signed with the shared SECRET_KEY.\n \"\"\"\n if not authorization:\n logger.warning(\"No Authorization header found for reload-scopes request\")\n raise HTTPException(\n status_code=401,\n detail=\"Authentication required\",\n headers={\"WWW-Authenticate\": \"Bearer\"},\n )\n\n caller_identity = \"unknown\"\n\n if authorization.startswith(\"Bearer \"):\n # Validate self-signed JWT using shared SECRET_KEY\n token = authorization.split(\" \", 1)[1]\n try:\n claims = jwt.decode(\n token,\n SECRET_KEY,\n algorithms=[\"HS256\"],\n issuer=JWT_ISSUER,\n audience=JWT_AUDIENCE,\n options={\n \"verify_exp\": True,\n \"verify_iat\": True,\n \"verify_iss\": True,\n \"verify_aud\": True,\n },\n leeway=30,\n )\n token_use = claims.get(\"token_use\")\n if token_use != \"access\": # nosec B105 - OAuth2 token type validation per RFC 6749, not a password\n raise ValueError(f\"Invalid token_use: {token_use}\")\n caller_identity = claims.get(\"sub\", \"service\")\n logger.info(f\"Reload-scopes authorized via JWT for: {caller_identity}\")\n except jwt.ExpiredSignatureError:\n logger.warning(\"Expired JWT token for reload-scopes request\")\n raise HTTPException(status_code=401, detail=\"Token has expired\")\n except (jwt.InvalidTokenError, ValueError) as e:\n logger.warning(f\"JWT validation failed for reload-scopes: {e}\")\n raise HTTPException(status_code=401, detail=\"Invalid token\")\n\n else:\n raise HTTPException(status_code=401, detail=\"Unsupported authentication scheme\")\n\n # Reload the scopes configuration\n global SCOPES_CONFIG\n try:\n SCOPES_CONFIG = await reload_scopes_config()\n logger.info(f\"Successfully reloaded scopes configuration by '{caller_identity}'\")\n\n # Rebuild static token map so per-key scopes pick up any\n # group-to-scope mapping changes that triggered this reload.\n await _build_static_token_map()\n\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Scopes configuration reloaded successfully\",\n \"timestamp\": datetime.utcnow().isoformat(),\n \"group_mappings_count\": len(SCOPES_CONFIG.get(\"group_mappings\", {})),\n },\n )\n except Exception as e:\n logger.error(f\"Failed to reload scopes configuration: {e}\")\n raise HTTPException(status_code=500, detail=\"Failed to reload scopes configuration\")\n\n\ndef parse_arguments():\n \"\"\"Parse command line arguments.\"\"\"\n parser = argparse.ArgumentParser(description=\"Simplified Auth Server\")\n\n parser.add_argument(\n \"--host\",\n type=str,\n default=os.getenv(\"AUTH_SERVER_HOST\", \"127.0.0.1\"), # nosec B104\n help=\"Host for the server to listen on (default: 127.0.0.1, override with AUTH_SERVER_HOST env var)\",\n )\n\n parser.add_argument(\n \"--port\",\n type=int,\n default=8888,\n help=\"Port for the server to listen on (default: 8888)\",\n )\n\n parser.add_argument(\n \"--region\",\n type=str,\n default=\"us-east-1\",\n help=\"Default AWS region (default: us-east-1)\",\n )\n\n return parser.parse_args()\n\n\ndef main():\n \"\"\"Run the server\"\"\"\n args = parse_arguments()\n\n # Update global validator with default region\n global validator\n validator = SimplifiedCognitoValidator(region=args.region)\n\n logger.info(f\"Starting simplified auth server on {args.host}:{args.port}\")\n logger.info(f\"Default region: {args.region}\")\n\n uvicorn.run(app, host=args.host, port=args.port, proxy_headers=True, forwarded_allow_ips=\"*\")\n\n\nif __name__ == \"__main__\":\n main()\n\n\n# Load OAuth2 providers configuration\ndef load_oauth2_config():\n \"\"\"Load the OAuth2 providers configuration from oauth2_providers.yml\"\"\"\n try:\n oauth2_file = Path(__file__).parent / \"oauth2_providers.yml\"\n with open(oauth2_file) as f:\n config = yaml.safe_load(f)\n\n # Substitute environment variables in configuration\n processed_config = substitute_env_vars(config)\n return processed_config\n except Exception as e:\n logger.error(f\"Failed to load OAuth2 configuration: {e}\")\n return {\"providers\": {}, \"session\": {}, \"registry\": {}}\n\n\ndef auto_derive_cognito_domain(user_pool_id: str) -> str:\n \"\"\"\n Auto-derive Cognito domain from User Pool ID.\n\n Example: us-east-1_KmP5A3La3 → us-east-1kmp5a3la3\n \"\"\"\n if not user_pool_id:\n return \"\"\n\n # Remove underscore and convert to lowercase\n domain = user_pool_id.replace(\"_\", \"\").lower()\n logger.info(f\"Auto-derived Cognito domain '{domain}' from user pool ID '{user_pool_id}'\")\n return domain\n\n\ndef substitute_env_vars(config):\n \"\"\"Recursively substitute environment variables in configuration\"\"\"\n if isinstance(config, dict):\n return {k: substitute_env_vars(v) for k, v in config.items()}\n elif isinstance(config, list):\n return [substitute_env_vars(item) for item in config]\n elif isinstance(config, str) and \"${\" in config:\n try:\n # Handle special case for auto-derived Cognito domain\n if \"COGNITO_DOMAIN:-auto\" in config:\n # Check if COGNITO_DOMAIN is set, if not auto-derive from user pool ID\n cognito_domain = os.environ.get(\"COGNITO_DOMAIN\")\n if not cognito_domain:\n user_pool_id = os.environ.get(\"COGNITO_USER_POOL_ID\", \"\")\n cognito_domain = auto_derive_cognito_domain(user_pool_id)\n\n # Replace the template with the derived domain\n config = config.replace(\"${COGNITO_DOMAIN:-auto}\", cognito_domain)\n\n template = Template(config)\n result = template.substitute(os.environ)\n\n # Convert string booleans to actual booleans\n if result.lower() == \"true\":\n return True\n elif result.lower() == \"false\":\n return False\n\n return result\n except KeyError as e:\n logger.warning(f\"Environment variable not found for template {config}: {e}\")\n return config\n else:\n return config\n\n\n# Global OAuth2 configuration\nOAUTH2_CONFIG = load_oauth2_config()\n\n# Initialize SECRET_KEY and signer for session management\nSECRET_KEY = os.environ.get(\"SECRET_KEY\")\nif not SECRET_KEY:\n # Generate a secure random key (32 bytes = 256 bits of entropy)\n SECRET_KEY = secrets.token_hex(32)\n logger.warning(\n \"No SECRET_KEY environment variable found. Using a randomly generated key. \"\n \"While this is more secure than a hardcoded default, it will change on restart. \"\n \"Set a permanent SECRET_KEY environment variable for production.\"\n )\n\nsigner = URLSafeTimedSerializer(SECRET_KEY)\n\n# Initialize MCP audit logger for logging MCP server access events\n# This logs all MCP requests that pass through the auth validation\n_mcp_audit_logger = None\n_mcp_logger = None\n_mcp_audit_repository = None\n\n\ndef get_mcp_logger() -> MCPLogger | None:\n \"\"\"Get or initialize the MCP logger instance.\"\"\"\n global _mcp_audit_logger, _mcp_logger, _mcp_audit_repository\n\n if _mcp_logger is None:\n try:\n # Check if MCP audit logging is enabled via settings\n if settings.audit_log_enabled:\n # Initialize MongoDB repository if MongoDB is enabled\n audit_repository = None\n mongodb_enabled = getattr(settings, \"audit_log_mongodb_enabled\", False)\n if mongodb_enabled:\n try:\n from registry.repositories.audit_repository import DocumentDBAuditRepository\n\n _mcp_audit_repository = DocumentDBAuditRepository()\n audit_repository = _mcp_audit_repository\n logger.info(\"MCP audit MongoDB repository initialized\")\n except Exception as e:\n logger.warning(f\"Failed to initialize MCP audit MongoDB repository: {e}\")\n mongodb_enabled = False\n\n _mcp_audit_logger = AuditLogger(\n log_dir=settings.audit_log_dir,\n rotation_hours=settings.audit_log_rotation_hours,\n rotation_max_mb=settings.audit_log_rotation_max_mb,\n local_retention_hours=settings.audit_log_local_retention_hours,\n stream_name=\"mcp-server-access\",\n mongodb_enabled=mongodb_enabled,\n audit_repository=audit_repository,\n )\n _mcp_logger = MCPLogger(_mcp_audit_logger)\n logger.info(\n f\"MCP audit logger initialized successfully (MongoDB: {mongodb_enabled})\"\n )\n else:\n logger.info(\"MCP audit logging is disabled\")\n except Exception as e:\n logger.warning(f\"Failed to initialize MCP audit logger: {e}\")\n _mcp_logger = None\n\n return _mcp_logger\n\n\ndef get_enabled_providers():\n \"\"\"Get list of enabled OAuth2 providers, filtered by AUTH_PROVIDER env var if set\"\"\"\n enabled = []\n\n # Check if AUTH_PROVIDER env var is set to filter to only one provider\n auth_provider_env = os.getenv(\"AUTH_PROVIDER\")\n\n # First, collect all enabled providers from YAML\n yaml_enabled_providers = []\n for provider_name, config in OAUTH2_CONFIG.get(\"providers\", {}).items():\n if config.get(\"enabled\", False):\n yaml_enabled_providers.append(provider_name)\n\n if auth_provider_env:\n logger.info(\n f\"AUTH_PROVIDER is set to '{auth_provider_env}', filtering providers accordingly\"\n )\n\n # Check if the specified provider exists in the config\n if auth_provider_env not in OAUTH2_CONFIG.get(\"providers\", {}):\n logger.error(\n f\"AUTH_PROVIDER '{auth_provider_env}' not found in oauth2_providers.yml configuration\"\n )\n return []\n\n # Check if the specified provider is enabled in YAML\n provider_config = OAUTH2_CONFIG[\"providers\"][auth_provider_env]\n if not provider_config.get(\"enabled\", False):\n logger.warning(\n f\"AUTH_PROVIDER '{auth_provider_env}' is set but this provider is disabled in oauth2_providers.yml\"\n )\n logger.warning(\n f\"To fix this, either set AUTH_PROVIDER to one of the enabled providers: {yaml_enabled_providers} or enable '{auth_provider_env}' in oauth2_providers.yml\"\n )\n return []\n\n # Warn about providers being filtered out\n filtered_providers = [p for p in yaml_enabled_providers if p != auth_provider_env]\n if filtered_providers:\n logger.warning(\n f\"AUTH_PROVIDER override: Filtering out enabled providers {filtered_providers} - only showing '{auth_provider_env}'\"\n )\n logger.warning(\n \"To show all enabled providers, remove the AUTH_PROVIDER environment variable\"\n )\n else:\n logger.info(\"AUTH_PROVIDER not set, returning all enabled providers from config\")\n\n for provider_name, config in OAUTH2_CONFIG.get(\"providers\", {}).items():\n if config.get(\"enabled\", False):\n # If AUTH_PROVIDER is set, only include that specific provider\n if auth_provider_env and provider_name != auth_provider_env:\n logger.debug(f\"Skipping provider '{provider_name}' due to AUTH_PROVIDER filter\")\n continue\n\n enabled.append(\n {\n \"name\": provider_name,\n \"display_name\": config.get(\"display_name\", provider_name.title()),\n }\n )\n logger.debug(f\"Enabled provider: {provider_name}\")\n\n logger.info(f\"Returning {len(enabled)} enabled providers: {[p['name'] for p in enabled]}\")\n return enabled\n\n\n@app.get(\"/oauth2/providers\")\nasync def get_oauth2_providers():\n \"\"\"Get list of enabled OAuth2 providers for the login page\"\"\"\n try:\n # Debug: log environment variable for troubleshooting\n auth_provider_env = os.getenv(\"AUTH_PROVIDER\")\n logger.info(f\"Debug: AUTH_PROVIDER environment variable = '{auth_provider_env}'\")\n\n providers = get_enabled_providers()\n return {\"providers\": providers}\n except Exception as e:\n logger.exception(\"Error getting OAuth2 providers\")\n return {\"providers\": [], \"error\": \"Internal server error\"}\n\n\n@app.get(\"/oauth2/login/{provider}\")\nasync def oauth2_login(provider: str, request: Request, redirect_uri: str = None):\n \"\"\"Initiate OAuth2 login flow\"\"\"\n try:\n if provider not in OAUTH2_CONFIG.get(\"providers\", {}):\n raise HTTPException(status_code=404, detail=f\"Provider {provider} not found\")\n\n provider_config = OAUTH2_CONFIG[\"providers\"][provider]\n if not provider_config.get(\"enabled\", False):\n raise HTTPException(status_code=400, detail=f\"Provider {provider} is disabled\")\n\n # Generate state parameter for security\n state = secrets.token_urlsafe(32)\n\n # Determine the OAuth2 callback URI based on the request origin\n # This is critical for dual-mode (CloudFront + custom domain) deployments\n # The callback_uri MUST match exactly between authorization and token exchange\n auth_server_external_url = os.environ.get(\"AUTH_SERVER_EXTERNAL_URL\", \"\").rstrip(\"/\")\n if auth_server_external_url:\n auth_server_url = f\"{auth_server_external_url}{ROOT_PATH}\"\n scheme = \"https\" if auth_server_external_url.startswith(\"https\") else \"http\"\n logger.info(f\"OAuth2 login - using AUTH_SERVER_EXTERNAL_URL: {auth_server_url}\")\n else:\n host = request.headers.get(\"host\", \"localhost:8888\")\n cloudfront_proto = request.headers.get(\"x-cloudfront-forwarded-proto\", \"\").lower()\n forwarded_proto = request.headers.get(\"x-forwarded-proto\", \"\").lower()\n scheme = (\n \"https\"\n if cloudfront_proto == \"https\"\n or forwarded_proto == \"https\"\n or request.url.scheme == \"https\"\n else \"http\"\n )\n logger.info(\n f\"OAuth2 login - host: {host}, x-cloudfront-forwarded-proto: {cloudfront_proto}, x-forwarded-proto: {forwarded_proto}, scheme: {scheme}\"\n )\n\n if \"localhost\" in host and \":\" not in host:\n auth_server_url = f\"{scheme}://localhost:8888{ROOT_PATH}\"\n else:\n auth_server_url = f\"{scheme}://{host}{ROOT_PATH}\"\n\n callback_uri = f\"{auth_server_url}/oauth2/callback/{provider}\"\n logger.info(f\"OAuth2 callback URI (from request host): {callback_uri}\")\n\n # Store state, redirect URI, and callback_uri in session for callback validation\n # The callback_uri is stored so token exchange uses the exact same URI\n session_data = {\n \"state\": state,\n \"provider\": provider,\n \"redirect_uri\": redirect_uri\n or OAUTH2_CONFIG.get(\"registry\", {}).get(\"success_redirect\", \"/\"),\n \"callback_uri\": callback_uri, # Store for token exchange\n }\n\n # Create temporary session for OAuth2 flow\n temp_session = signer.dumps(session_data)\n\n auth_params = {\n \"client_id\": provider_config[\"client_id\"],\n \"response_type\": provider_config[\"response_type\"],\n \"scope\": \" \".join(provider_config[\"scopes\"]),\n \"state\": state,\n \"redirect_uri\": callback_uri,\n }\n\n auth_url = f\"{provider_config['auth_url']}?{urllib.parse.urlencode(auth_params)}\"\n\n # Validate the OAuth provider auth URL has a safe scheme before redirecting\n parsed_auth_url = urlparse(auth_url)\n if parsed_auth_url.scheme not in (\"http\", \"https\"):\n logger.error(\n f\"Unsafe OAuth2 auth URL scheme '{parsed_auth_url.scheme}' for provider {provider}\"\n )\n raise HTTPException(\n status_code=400,\n detail=\"Invalid OAuth2 provider configuration\",\n )\n\n # Create response with temporary session cookie\n response = RedirectResponse(url=auth_url, status_code=302)\n cookie_secure = scheme == \"https\"\n response.set_cookie(\n key=\"oauth2_temp_session\",\n value=temp_session,\n max_age=600, # 10 minutes for OAuth2 flow\n httponly=True,\n secure=cookie_secure,\n samesite=\"lax\",\n )\n\n logger.info(f\"Initiated OAuth2 login for provider {provider}\")\n return response\n\n except HTTPException:\n raise\n except Exception as e:\n logger.error(f\"Error initiating OAuth2 login for {provider}: {e}\")\n error_url = OAUTH2_CONFIG.get(\"registry\", {}).get(\"error_redirect\", \"/login\")\n if not _is_safe_redirect_url(error_url):\n error_url = \"/login\"\n return RedirectResponse(url=f\"{error_url}?error=oauth2_init_failed\", status_code=302)\n\n\n@app.get(\"/oauth2/callback/{provider}\")\nasync def oauth2_callback(\n provider: str,\n request: Request,\n code: str = None,\n state: str = None,\n error: str = None,\n oauth2_temp_session: str = Cookie(None),\n):\n \"\"\"Handle OAuth2 callback and create user session\"\"\"\n try:\n if error:\n logger.warning(f\"OAuth2 error from {provider}: {error}\")\n error_url = OAUTH2_CONFIG.get(\"registry\", {}).get(\"error_redirect\", \"/login\")\n # Validate error_url is a safe redirect target and URL-encode user-supplied error details\n if not _is_safe_redirect_url(error_url):\n error_url = \"/login\"\n safe_details = urllib.parse.quote(str(error), safe=\"\")\n return RedirectResponse(\n url=f\"{error_url}?error=oauth2_error&details={safe_details}\", status_code=302\n )\n\n if not code or not state or not oauth2_temp_session:\n raise HTTPException(status_code=400, detail=\"Missing required OAuth2 parameters\")\n\n # Validate temporary session\n try:\n temp_session_data = signer.loads(oauth2_temp_session, max_age=600)\n except (SignatureExpired, BadSignature):\n raise HTTPException(status_code=400, detail=\"Invalid or expired OAuth2 session\")\n\n # Validate state parameter\n if state != temp_session_data.get(\"state\"):\n raise HTTPException(status_code=400, detail=\"Invalid state parameter\")\n\n # Validate provider\n if provider != temp_session_data.get(\"provider\"):\n raise HTTPException(status_code=400, detail=\"Provider mismatch\")\n\n provider_config = OAUTH2_CONFIG[\"providers\"][provider]\n\n # Exchange authorization code for access token\n # Use the callback_uri stored in the session (must match what was used in authorization)\n callback_uri = temp_session_data.get(\"callback_uri\")\n if callback_uri:\n # Extract auth_server_url from the stored callback_uri\n # callback_uri format: {auth_server_url}/oauth2/callback/{provider}\n auth_server_url = callback_uri.rsplit(f\"/oauth2/callback/{provider}\", 1)[0]\n logger.info(f\"Using stored callback_uri for token exchange: {callback_uri}\")\n else:\n # Fallback for sessions created before this fix\n auth_server_external_url = os.environ.get(\"AUTH_SERVER_EXTERNAL_URL\")\n if auth_server_external_url:\n auth_server_url = auth_server_external_url.rstrip(\"/\")\n logger.info(\n f\"Fallback: Using AUTH_SERVER_EXTERNAL_URL for token exchange: {auth_server_url}\"\n )\n else:\n host = request.headers.get(\"host\", \"localhost:8888\")\n scheme = (\n \"https\"\n if request.headers.get(\"x-forwarded-proto\") == \"https\"\n or request.url.scheme == \"https\"\n else \"http\"\n )\n if \"localhost\" in host and \":\" not in host:\n auth_server_url = f\"{scheme}://localhost:8888{ROOT_PATH}\"\n else:\n auth_server_url = f\"{scheme}://{host}{ROOT_PATH}\"\n logger.warning(f\"Fallback: Using dynamic URL for token exchange: {auth_server_url}\")\n\n token_data = await exchange_code_for_token(provider, code, provider_config, auth_server_url)\n logger.info(f\"Token data keys: {list(token_data.keys())}\")\n\n # For Cognito and Keycloak, try to extract user info from JWT tokens\n if provider in [\"cognito\", \"keycloak\"]:\n try:\n if provider == \"cognito\":\n # Extract Cognito configuration from environment\n user_pool_id = os.environ.get(\"COGNITO_USER_POOL_ID\")\n client_id = provider_config[\"client_id\"]\n region = os.environ.get(\"AWS_REGION\", \"us-east-1\")\n\n if user_pool_id and client_id:\n # Use our existing token validation to get groups from JWT\n validator = SimplifiedCognitoValidator(region)\n token_validation = validator.validate_token(\n token_data[\"access_token\"], user_pool_id, client_id, region\n )\n\n logger.info(f\"Token validation result: {token_validation}\")\n\n # Extract user info from token validation\n mapped_user = {\n \"username\": token_validation.get(\"username\"),\n \"email\": token_validation.get(\n \"username\"\n ), # Cognito username is usually email\n \"name\": token_validation.get(\"username\"),\n \"groups\": token_validation.get(\"groups\", []),\n }\n logger.info(f\"User extracted from JWT token: {mapped_user}\")\n else:\n logger.warning(\n \"Missing Cognito configuration for JWT validation, falling back to userInfo\"\n )\n raise ValueError(\"Missing Cognito config\")\n elif provider == \"keycloak\":\n # For Keycloak, decode the ID token to get user information\n if \"id_token\" in token_data:\n import jwt\n\n # Decode without verification for now (we trust the token since we just got it)\n id_token_claims = jwt.decode(\n token_data[\"id_token\"], options={\"verify_signature\": False}\n )\n logger.info(f\"ID token claims: {id_token_claims}\")\n\n # Extract user info from ID token claims\n mapped_user = {\n \"username\": id_token_claims.get(\"preferred_username\")\n or id_token_claims.get(\"sub\"),\n \"email\": id_token_claims.get(\"email\"),\n \"name\": id_token_claims.get(\"name\")\n or id_token_claims.get(\"given_name\"),\n \"groups\": id_token_claims.get(\"groups\", []),\n }\n logger.info(f\"User extracted from Keycloak ID token: {mapped_user}\")\n else:\n logger.warning(\n \"No ID token found in Keycloak response, falling back to userInfo\"\n )\n raise ValueError(\"Missing ID token\")\n\n except Exception as e:\n logger.warning(\n f\"JWT token validation failed: {e}, falling back to userInfo endpoint\"\n )\n # Fallback to userInfo endpoint\n user_info = await get_user_info(token_data[\"access_token\"], provider_config)\n logger.info(f\"Raw user info from {provider}: {user_info}\")\n mapped_user = map_user_info(user_info, provider_config)\n logger.info(f\"Mapped user info from userInfo: {mapped_user}\")\n elif provider == \"entra\":\n # For Entra ID, prioritize ID token claims over userinfo endpoint\n try:\n if \"id_token\" in token_data:\n import jwt\n\n # Decode without verification (we trust the token since we just got it from Microsoft)\n id_token_claims = jwt.decode(\n token_data[\"id_token\"], options={\"verify_signature\": False}\n )\n logger.info(f\"Entra ID token claims: {id_token_claims}\")\n\n # Extract user info from ID token claims\n # Entra ID can return groups as either 'groups' or 'roles' depending on configuration\n groups = id_token_claims.get(\"groups\", [])\n if not groups:\n groups = id_token_claims.get(\"roles\", [])\n\n mapped_user = {\n \"username\": id_token_claims.get(\"preferred_username\")\n or id_token_claims.get(\"email\")\n or id_token_claims.get(\"upn\")\n or id_token_claims.get(\"sub\"),\n \"email\": id_token_claims.get(\"email\")\n or id_token_claims.get(\"preferred_username\"),\n \"name\": id_token_claims.get(\"name\") or id_token_claims.get(\"given_name\"),\n \"groups\": groups,\n }\n logger.info(f\"User extracted from Entra ID token: {mapped_user}\")\n else:\n logger.warning(\"No ID token found in Entra response, falling back to userInfo\")\n raise ValueError(\"Missing ID token\")\n\n except Exception as e:\n logger.warning(\n f\"Entra ID token parsing failed: {e}, falling back to userInfo endpoint\"\n )\n # Fallback to userInfo endpoint\n user_info = await get_user_info(token_data[\"access_token\"], provider_config)\n logger.info(f\"Raw user info from {provider}: {user_info}\")\n mapped_user = map_user_info(user_info, provider_config)\n logger.info(f\"Mapped user info from userInfo: {mapped_user}\")\n elif provider == \"okta\":\n # For Okta, decode the ID token to get groups (userinfo doesn't include groups)\n try:\n if \"id_token\" in token_data:\n import jwt\n\n id_token_claims = jwt.decode(\n token_data[\"id_token\"], options={\"verify_signature\": False}\n )\n logger.info(f\"Okta ID token claims: {id_token_claims}\")\n\n mapped_user = {\n \"username\": id_token_claims.get(\"preferred_username\")\n or id_token_claims.get(\"email\")\n or id_token_claims.get(\"sub\"),\n \"email\": id_token_claims.get(\"email\"),\n \"name\": id_token_claims.get(\"name\") or id_token_claims.get(\"given_name\"),\n \"groups\": id_token_claims.get(\"groups\", []),\n }\n logger.info(f\"User extracted from Okta ID token: {mapped_user}\")\n else:\n logger.warning(\"No ID token found in Okta response, falling back to userInfo\")\n raise ValueError(\"Missing ID token\")\n\n except Exception as e:\n logger.warning(\n f\"Okta ID token parsing failed: {e}, falling back to userInfo endpoint\"\n )\n user_info = await get_user_info(token_data[\"access_token\"], provider_config)\n logger.info(f\"Raw user info from {provider}: {user_info}\")\n mapped_user = map_user_info(user_info, provider_config)\n logger.info(f\"Mapped user info from userInfo: {mapped_user}\")\n elif provider == \"auth0\":\n # For Auth0, delegate ID token parsing to the Auth0Provider\n # which validates issuer/audience claims and extracts groups\n # from a custom namespaced claim configured via Auth0 Actions/Rules\n try:\n auth0_provider = get_auth_provider(\"auth0\")\n mapped_user = auth0_provider.extract_user_from_tokens(token_data)\n logger.info(f\"User extracted from Auth0 ID token: {mapped_user}\")\n\n except Exception as e:\n logger.warning(\n f\"Auth0 ID token parsing failed: {e}, falling back to userInfo endpoint\"\n )\n # Fallback to userInfo endpoint\n user_info = await get_user_info(token_data[\"access_token\"], provider_config)\n logger.info(f\"Raw user info from {provider}: {user_info}\")\n mapped_user = map_user_info(user_info, provider_config)\n logger.info(f\"Mapped user info from userInfo: {mapped_user}\")\n else:\n # For other providers, use userInfo endpoint\n user_info = await get_user_info(token_data[\"access_token\"], provider_config)\n logger.info(f\"Raw user info from {provider}: {user_info}\")\n mapped_user = map_user_info(user_info, provider_config)\n logger.info(f\"Mapped user info: {mapped_user}\")\n\n # Create session cookie compatible with registry\n session_data = {\n \"username\": mapped_user[\"username\"],\n \"email\": mapped_user.get(\"email\"),\n \"name\": mapped_user.get(\"name\"),\n \"groups\": mapped_user.get(\"groups\", []),\n \"provider\": provider,\n \"auth_method\": \"oauth2\",\n # Always store id_token for OIDC logout (not a credential, just identity info)\n # Required for proper SSO logout with id_token_hint parameter\n \"id_token\": token_data.get(\"id_token\"),\n }\n\n # Optionally store token metadata (legacy flag, not needed for security)\n # Note: access_token and refresh_token are never stored (removed in issue #490)\n if OAUTH_STORE_TOKENS_IN_SESSION:\n session_data.update(\n {\n \"token_expires_in\": token_data.get(\"expires_in\"),\n \"token_obtained_at\": int(time.time()),\n }\n )\n\n registry_session = signer.dumps(session_data)\n\n # Redirect to registry with session cookie\n redirect_url = temp_session_data.get(\n \"redirect_uri\", OAUTH2_CONFIG.get(\"registry\", {}).get(\"success_redirect\", \"/\")\n )\n # Validate redirect_url to prevent open redirect attacks.\n # Allow relative URLs and absolute URLs within the deployment's cookie domain.\n # SESSION_COOKIE_DOMAIN (e.g., \".example.com\") defines the trust boundary —\n # any service sharing the session cookie is a safe redirect target.\n cookie_domain = os.environ.get(\"SESSION_COOKIE_DOMAIN\", \"\").strip()\n redirect_parsed = urlparse(redirect_url)\n redirect_is_safe = False\n if not redirect_parsed.scheme and not redirect_parsed.netloc:\n # Relative URL — always safe\n redirect_is_safe = True\n elif redirect_parsed.scheme in (\"http\", \"https\"):\n redirect_hostname = redirect_parsed.hostname or \"\"\n if cookie_domain and redirect_hostname.endswith(cookie_domain):\n # Redirect is within the deployment's cookie domain\n redirect_is_safe = True\n if not redirect_is_safe:\n logger.warning(f\"Blocked unsafe redirect URL: {redirect_url}, falling back to /\")\n redirect_url = \"/\"\n response = RedirectResponse(url=redirect_url, status_code=302)\n\n # Set registry-compatible session cookie\n # Check if HTTPS is terminated at load balancer/CloudFront\n is_https = is_request_https(request)\n\n # Only set secure=True if the original request was HTTPS\n cookie_secure_config = OAUTH2_CONFIG.get(\"session\", {}).get(\"secure\", False)\n cookie_secure = cookie_secure_config and is_https\n cookie_samesite = OAUTH2_CONFIG.get(\"session\", {}).get(\"samesite\", \"lax\")\n cookie_domain = OAUTH2_CONFIG.get(\"session\", {}).get(\"domain\", \"\")\n\n # Handle domain configuration - only use explicitly configured values\n # Empty string or placeholder means no domain attribute (exact host only)\n if not cookie_domain or cookie_domain == \"${SESSION_COOKIE_DOMAIN}\":\n cookie_domain = None\n logger.info(\"No cookie domain configured - cookie will be set for exact host only\")\n else:\n logger.info(\"Using explicitly configured cookie domain\")\n\n logger.info(\n f\"Auth server setting session cookie: is_https={is_https}, domain={'configured' if cookie_domain else 'not set'}, x-forwarded-proto={request.headers.get('x-forwarded-proto', 'not set')}, request_scheme={request.url.scheme}\"\n )\n\n cookie_params = {\n \"key\": \"mcp_gateway_session\", # Same as registry SESSION_COOKIE_NAME\n \"value\": registry_session,\n \"max_age\": OAUTH2_CONFIG.get(\"session\", {}).get(\"max_age_seconds\", 28800),\n \"httponly\": OAUTH2_CONFIG.get(\"session\", {}).get(\"httponly\", True),\n \"samesite\": cookie_samesite,\n \"secure\": cookie_secure,\n \"path\": \"/\", # Ensure cookie is sent for all paths\n }\n\n # Only set domain if configured or inferred (for cross-subdomain cookies)\n if cookie_domain:\n cookie_params[\"domain\"] = cookie_domain\n\n response.set_cookie(**cookie_params)\n\n # Clear temporary OAuth2 session\n response.delete_cookie(\"oauth2_temp_session\")\n\n logger.info(\n f\"Successfully authenticated user {hash_username(mapped_user['username'])} via {provider}\"\n )\n return response\n\n except HTTPException:\n raise\n except Exception as e:\n logger.error(f\"Error in OAuth2 callback for {provider}: {e}\")\n error_url = OAUTH2_CONFIG.get(\"registry\", {}).get(\"error_redirect\", \"/login\")\n if not _is_safe_redirect_url(error_url):\n error_url = \"/login\"\n return RedirectResponse(url=f\"{error_url}?error=oauth2_callback_failed\", status_code=302)\n\n\nasync def exchange_code_for_token(\n provider: str, code: str, provider_config: dict, auth_server_url: str = None\n) -> dict:\n \"\"\"Exchange authorization code for access token\"\"\"\n if auth_server_url is None:\n auth_server_url = (\n os.environ.get(\"AUTH_SERVER_URL\", \"http://localhost:8888\").rstrip(\"/\") + ROOT_PATH\n )\n\n async with httpx.AsyncClient() as client:\n token_data = {\n \"grant_type\": provider_config[\"grant_type\"],\n \"client_id\": provider_config[\"client_id\"],\n \"client_secret\": provider_config[\"client_secret\"],\n \"code\": code,\n \"redirect_uri\": f\"{auth_server_url}/oauth2/callback/{provider}\",\n }\n\n headers = {\"Accept\": \"application/json\"}\n if provider == \"github\":\n headers[\"Accept\"] = \"application/json\"\n\n response = await client.post(provider_config[\"token_url\"], data=token_data, headers=headers)\n response.raise_for_status()\n return response.json()\n\n\nasync def get_user_info(access_token: str, provider_config: dict) -> dict:\n \"\"\"Get user information from OAuth2 provider\"\"\"\n async with httpx.AsyncClient() as client:\n headers = {\"Authorization\": f\"Bearer {access_token}\"}\n\n response = await client.get(provider_config[\"user_info_url\"], headers=headers)\n response.raise_for_status()\n return response.json()\n\n\ndef map_user_info(user_info: dict, provider_config: dict) -> dict:\n \"\"\"Map provider-specific user info to our standard format\"\"\"\n mapped = {\n \"username\": user_info.get(provider_config[\"username_claim\"]),\n \"email\": user_info.get(provider_config[\"email_claim\"]),\n \"name\": user_info.get(provider_config[\"name_claim\"]),\n \"groups\": [],\n }\n\n # Handle groups if provider supports them\n groups_claim = provider_config.get(\"groups_claim\")\n logger.info(f\"Looking for groups claim (configured={'yes' if groups_claim else 'no'})\")\n logger.info(f\"Available claims in user_info: {list(user_info.keys())}\")\n\n if groups_claim and groups_claim in user_info:\n groups = user_info[groups_claim]\n if isinstance(groups, list):\n mapped[\"groups\"] = groups\n elif isinstance(groups, str):\n mapped[\"groups\"] = [groups]\n logger.info(f\"Found groups via {groups_claim}: {mapped['groups']}\")\n else:\n # Try alternative group claims for Cognito\n for possible_group_claim in [\"cognito:groups\", \"groups\", \"custom:groups\"]:\n if possible_group_claim in user_info:\n groups = user_info[possible_group_claim]\n if isinstance(groups, list):\n mapped[\"groups\"] = groups\n elif isinstance(groups, str):\n mapped[\"groups\"] = [groups]\n logger.info(\n f\"Found groups via alternative claim {possible_group_claim}: {mapped['groups']}\"\n )\n break\n\n if not mapped[\"groups\"]:\n logger.warning(\n f\"No groups found in user_info. Available fields: {list(user_info.keys())}\"\n )\n\n return mapped\n\n\n@app.get(\"/oauth2/logout/{provider}\")\nasync def oauth2_logout(\n provider: str,\n request: Request,\n redirect_uri: str = None,\n id_token_hint: str | None = None,\n):\n \"\"\"Initiate OAuth2 logout flow to clear provider session\"\"\"\n try:\n if provider not in OAUTH2_CONFIG.get(\"providers\", {}):\n raise HTTPException(status_code=404, detail=f\"Provider {provider} not found\")\n\n provider_config = OAUTH2_CONFIG[\"providers\"][provider]\n logout_url = provider_config.get(\"logout_url\")\n\n if not logout_url:\n # If provider doesn't support logout URL, just redirect\n redirect_url = redirect_uri or OAUTH2_CONFIG.get(\"registry\", {}).get(\n \"success_redirect\", \"/login\"\n )\n return RedirectResponse(url=redirect_url, status_code=302)\n\n # Build full redirect URI\n full_redirect_uri = redirect_uri or \"/login\"\n if not full_redirect_uri.startswith(\"http\"):\n # Make it a full URL - extract registry URL from request's referer or use environment\n registry_base = os.environ.get(\"REGISTRY_URL\")\n if not registry_base:\n # Try to derive from the request\n referer = request.headers.get(\"referer\", \"\")\n if referer:\n from urllib.parse import urlparse\n\n parsed = urlparse(referer)\n registry_base = f\"{parsed.scheme}://{parsed.netloc}\"\n else:\n registry_base = \"http://localhost\"\n\n full_redirect_uri = f\"{registry_base.rstrip('/')}{full_redirect_uri}\"\n\n # Detect provider type and build appropriate logout URL\n # Keycloak uses post_logout_redirect_uri, Cognito uses logout_uri\n parsed_logout_url = urlparse(logout_url)\n logout_hostname = parsed_logout_url.hostname or \"\"\n logout_path = parsed_logout_url.path or \"\"\n\n if \"keycloak\" in provider.lower() or \"/realms/\" in logout_path:\n # Keycloak logout parameters\n logout_params = {\n \"client_id\": provider_config[\"client_id\"],\n \"post_logout_redirect_uri\": full_redirect_uri,\n }\n if id_token_hint:\n logout_params[\"id_token_hint\"] = id_token_hint\n logger.debug(f\"Keycloak logout params built: has_id_token_hint={bool(id_token_hint)}\")\n elif logout_hostname == \"login.microsoftonline.com\" or \"entra\" in provider.lower():\n # Entra ID logout parameters\n logout_params = {\n \"post_logout_redirect_uri\": full_redirect_uri,\n }\n if id_token_hint:\n logout_params[\"id_token_hint\"] = id_token_hint\n logger.debug(f\"Entra ID logout params built: has_id_token_hint={bool(id_token_hint)}\")\n elif \"okta\" in provider.lower() or (\n logout_hostname and logout_hostname.endswith(\".okta.com\")\n ):\n # Okta logout parameters\n logout_params = {\n \"post_logout_redirect_uri\": full_redirect_uri,\n }\n if id_token_hint:\n logout_params[\"id_token_hint\"] = id_token_hint\n logger.debug(f\"Okta logout params built: has_id_token_hint={bool(id_token_hint)}\")\n else:\n # Cognito logout parameters (no id_token_hint support)\n logout_params = {\n \"client_id\": provider_config[\"client_id\"],\n \"logout_uri\": full_redirect_uri,\n }\n logger.debug(\"Cognito logout params built (no id_token_hint)\")\n\n logout_redirect_url = f\"{logout_url}?{urllib.parse.urlencode(logout_params)}\"\n\n logger.info(f\"Redirecting to {provider} logout\")\n return RedirectResponse(url=logout_redirect_url, status_code=302)\n\n except HTTPException:\n raise\n except Exception as e:\n logger.error(f\"Error initiating logout for {provider}: {e}\")\n # Fallback to local redirect\n redirect_url = redirect_uri or OAUTH2_CONFIG.get(\"registry\", {}).get(\n \"success_redirect\", \"/login\"\n )\n return RedirectResponse(url=redirect_url, status_code=302)\n" }, { "path": "build-config.yaml", "content": "# Unified Container Build Configuration\n# Central definition of all Docker images to build and push to ECR\n# This is the SINGLE SOURCE OF TRUTH for all container builds\n#\n# NOTE: The build scripts now dynamically construct the ECR registry URL\n# based on the AWS_REGION environment variable and current AWS credentials.\n# The values below are DEFAULTS and will be overridden if AWS_REGION is set.\n#\n# To deploy to a different region:\n# export AWS_REGION=us-east-1\n# make build-push\n#\n# The build scripts will automatically use the correct ECR registry for your region.\n\naws:\n account_id: \"123456789012\" # Placeholder - overridden by AWS credentials at runtime\n region: \"us-west-2\" # Default region - override with AWS_REGION env var\n ecr_registry: \"123456789012.dkr.ecr.us-west-2.amazonaws.com\" # Placeholder - constructed dynamically at runtime\n\nimages:\n # ========================================\n # ECS-Deployed Core Services (5)\n # ========================================\n\n # Main MCP Gateway Registry with nginx reverse proxy, FAISS, models\n registry:\n repo_name: \"mcp-gateway-registry\"\n dockerfile: \"docker/Dockerfile.registry\"\n context: \".\"\n description: \"MCP Gateway Registry with nginx, FAISS, models\"\n tags:\n - latest\n build_args: {}\n\n # OAuth2/OIDC Authentication Server\n auth_server:\n repo_name: \"mcp-gateway-auth-server\"\n dockerfile: \"docker/Dockerfile.auth\"\n context: \".\"\n description: \"OAuth2/OIDC authentication server\"\n tags:\n - latest\n build_args: {}\n\n # Keycloak Identity Provider\n keycloak:\n repo_name: \"keycloak\"\n dockerfile: \"docker/keycloak/Dockerfile\"\n context: \"docker/keycloak\"\n description: \"Keycloak identity provider\"\n tags:\n - latest\n build_args:\n BASE_IMAGE: \"quay.io/keycloak/keycloak:latest\"\n\n # Keycloak Scopes and Roles Initialization\n scopes_init:\n repo_name: \"mcp-gateway-scopes-init\"\n dockerfile: \"docker/Dockerfile.scopes-init\"\n context: \".\"\n description: \"Initialize Keycloak scopes and roles\"\n tags:\n - latest\n build_args: {}\n\n # Metrics Collection and Monitoring Service\n metrics_service:\n repo_name: \"mcp-gateway-metrics-service\"\n dockerfile: \"metrics-service/Dockerfile\"\n context: \"metrics-service\"\n description: \"Metrics collection and monitoring service\"\n tags:\n - latest\n build_args: {}\n\n # Grafana OSS with pre-provisioned AMP datasource and dashboards\n grafana:\n repo_name: \"mcp-gateway-grafana\"\n dockerfile: \"terraform/aws-ecs/grafana/Dockerfile\"\n context: \"terraform/aws-ecs/grafana\"\n description: \"Grafana OSS with baked-in AMP datasource and MCP dashboards\"\n tags:\n - latest\n build_args: {}\n\n # ========================================\n # Infrastructure Services\n # ========================================\n\n # MongoDB Community Edition 8.2\n mongodb:\n repo_name: \"mongodb\"\n external_image: \"mongo:8.2\"\n description: \"MongoDB Community Edition 8.2 with replica set support for local development (mirrored from Docker Hub)\"\n tags:\n - \"8.2\"\n - latest\n build_args: {}\n\n # ========================================\n # MCP Servers (5)\n # ========================================\n\n # Generic MCP Server Template\n mcp_server:\n repo_name: \"mcp-gateway-mcp-server\"\n dockerfile: \"docker/Dockerfile.mcp-server\"\n context: \".\"\n description: \"Generic MCP server template\"\n tags:\n - latest\n build_args: {}\n\n # CurrentTime MCP Server\n currenttime:\n repo_name: \"mcp-gateway-currenttime\"\n dockerfile: \"docker/Dockerfile.mcp-server\"\n context: \"servers/currenttime\"\n description: \"CurrentTime MCP server providing current time functionality\"\n tags:\n - latest\n build_args: {}\n\n # MCPGW MCP Server\n mcpgw:\n repo_name: \"mcp-gateway-mcpgw\"\n dockerfile: \"docker/Dockerfile.mcp-server\"\n context: \".\"\n description: \"MCPGW MCP server with embeddings support\"\n tags:\n - latest\n build_args:\n SERVER_DIR: \"servers/mcpgw\"\n\n # Real Server Fake Tools MCP Server\n realserverfaketools:\n repo_name: \"mcp-gateway-realserverfaketools\"\n dockerfile: \"docker/Dockerfile.mcp-server\"\n context: \"servers/realserverfaketools\"\n description: \"Real Server Fake Tools MCP server\"\n tags:\n - latest\n build_args: {}\n\n # Financial Info MCP Server\n fininfo:\n repo_name: \"mcp-gateway-fininfo\"\n dockerfile: \"docker/Dockerfile.mcp-server\"\n context: \"servers/fininfo\"\n description: \"Financial Info MCP server\"\n tags:\n - latest\n build_args: {}\n\n # ========================================\n # Agent Services (A2A) (2)\n # ========================================\n\n # Flight Booking Agent\n flight_booking_agent:\n repo_name: \"mcp-gateway-flight-booking-agent\"\n dockerfile: \"agents/a2a/src/flight-booking-agent/Dockerfile\"\n context: \"agents/a2a/src/flight-booking-agent\"\n description: \"Flight booking A2A agent\"\n tags:\n - latest\n build_args: {}\n\n # Travel Assistant Agent\n travel_assistant_agent:\n repo_name: \"mcp-gateway-travel-assistant-agent\"\n dockerfile: \"agents/a2a/src/travel-assistant-agent/Dockerfile\"\n context: \"agents/a2a/src/travel-assistant-agent\"\n description: \"Travel assistant A2A agent\"\n tags:\n - latest\n build_args: {}\n" }, { "path": "build_and_run.sh", "content": "#!/bin/bash\n\n# Enable error handling\nset -e\n\n# Function for logging with timestamp\nlog() {\n echo \"[$(date '+%Y-%m-%d %H:%M:%S')] $1\"\n}\n\n# Function for error handling\nhandle_error() {\n log \"ERROR: $1\"\n exit 1\n}\n\n# Parse command line arguments\nUSE_PREBUILT=false\nUSE_PODMAN=false\nUSE_DHI=false\nDOCKER_COMPOSE_FILE=\"docker-compose.yml\"\nDHI_COMPOSE_FILE=\"docker-compose.dhi.yml\"\nPODMAN_COMPOSE_FILE=\"docker-compose.podman.yml\"\n\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --prebuilt)\n USE_PREBUILT=true\n DOCKER_COMPOSE_FILE=\"docker-compose.prebuilt.yml\"\n shift\n ;;\n --podman)\n USE_PODMAN=true\n shift\n ;;\n --dhi)\n USE_DHI=true\n shift\n ;;\n --help)\n echo \"Usage: $0 [--prebuilt] [--podman] [--dhi] [--help]\"\n echo \"\"\n echo \"Options:\"\n echo \" --prebuilt Use pre-built container images (faster startup)\"\n echo \" --podman Use Podman instead of Docker (rootless-friendly)\"\n echo \" --dhi Use Docker Hardened Images (DHI) from dhi.io\"\n echo \" --help Show this help message\"\n echo \"\"\n echo \"Examples:\"\n echo \" $0 # Build containers locally with Docker (default)\"\n echo \" $0 --prebuilt # Use pre-built images from registry with Docker\"\n echo \" $0 --podman # Build containers locally with Podman\"\n echo \" $0 --prebuilt --podman # Use pre-built images with Podman\"\n echo \" $0 --dhi # Use Docker Hardened Images for infra containers\"\n echo \"\"\n echo \"Benefits of --prebuilt:\"\n echo \" - Instant deployment (no build time)\"\n echo \" - Reduced friction (eliminate build environment issues)\"\n echo \" - Consistent experience (all users get the same tested images)\"\n echo \" - Bandwidth efficient (pull optimized, compressed images)\"\n echo \"\"\n echo \"Benefits of --podman:\"\n echo \" - Rootless container execution (no privileged ports)\"\n echo \" - Compatible with macOS Podman Desktop\"\n echo \" - Uses non-privileged ports (8080 for HTTP, 8443 for HTTPS)\"\n echo \" - No Docker daemon required\"\n echo \"\"\n echo \"Benefits of --dhi:\"\n echo \" - Security-hardened container images from dhi.io\"\n echo \" - Reduced attack surface for infrastructure containers\"\n echo \" - Non-root execution enforced (MongoDB, Prometheus, Grafana, PostgreSQL)\"\n echo \" - Requires: docker login dhi.io (before first use)\"\n exit 0\n ;;\n *)\n echo \"Unknown option $1\"\n echo \"Use --help for usage information\"\n exit 1\n ;;\n esac\ndone\n\necho \"MCP Gateway Registry Deployment\"\necho \"===============================\"\n\n# Detect and configure container engine\nCOMPOSE_CMD=\"\"\nCOMPOSE_FILES=\"\"\n\nif [ \"$USE_PODMAN\" = true ]; then\n # User explicitly requested Podman\n if command -v podman &> /dev/null; then\n COMPOSE_CMD=\"podman compose\"\n # Use standalone Podman compose file to avoid port merge issues\n COMPOSE_FILES=\"-f $PODMAN_COMPOSE_FILE\"\n log \"Using Podman (rootless mode)\"\n log \"Services will be available at:\"\n log \" - HTTP: http://localhost:8080\"\n log \" - HTTPS: https://localhost:8443\"\n else\n log \"ERROR: --podman flag specified but podman command not found\"\n log \"Please install Podman: https://podman.io/getting-started/installation\"\n exit 1\n fi\nelse\n # Auto-detect: prefer Docker, fallback to Podman\n if command -v docker &> /dev/null && docker compose version &> /dev/null; then\n COMPOSE_CMD=\"docker compose\"\n COMPOSE_FILES=\"-f $DOCKER_COMPOSE_FILE\"\n log \"Using Docker\"\n log \"Services will be available at:\"\n log \" - HTTP: http://localhost\"\n log \" - HTTPS: https://localhost\"\n elif command -v podman &> /dev/null; then\n log \"WARNING: Docker not found, automatically using Podman (rootless mode)\"\n log \"To suppress this message, use --podman flag explicitly\"\n COMPOSE_CMD=\"podman compose\"\n # Use standalone Podman compose file to avoid port merge issues\n COMPOSE_FILES=\"-f $PODMAN_COMPOSE_FILE\"\n log \"Services will be available at:\"\n log \" - HTTP: http://localhost:8080\"\n log \" - HTTPS: https://localhost:8443\"\n else\n log \"ERROR: Neither 'docker compose' nor 'podman compose' is available\"\n log \"Please install one of:\"\n log \" - Docker: https://docs.docker.com/compose/install/\"\n log \" - Podman: https://podman.io/getting-started/installation\"\n exit 1\n fi\nfi\n\n# Append DHI override file if --dhi flag is set\nif [ \"$USE_DHI\" = true ]; then\n if [ ! -f \"$DHI_COMPOSE_FILE\" ]; then\n log \"ERROR: DHI compose file not found: $DHI_COMPOSE_FILE\"\n exit 1\n fi\n COMPOSE_FILES=\"$COMPOSE_FILES -f $DHI_COMPOSE_FILE\"\n log \"Using Docker Hardened Images (DHI) from dhi.io\"\n log \"Ensure you have authenticated: docker login dhi.io\"\nfi\n\nOVERRIDE_FILE=\"docker-compose.override.yml\"\nif [ -f \"$OVERRIDE_FILE\" ]; then\n COMPOSE_FILES=\"$COMPOSE_FILES -f $OVERRIDE_FILE\"\n log \"Applying local overrides from $OVERRIDE_FILE\"\nfi\n\nif [ \"$USE_PREBUILT\" = true ]; then\n log \"Using pre-built container images for fast deployment\"\n log \"Will pull latest images from container registry during startup...\"\n\n # Warn about ARM64 compatibility with Podman\n if [[ \"$COMPOSE_CMD\" == \"podman compose\" ]] && [[ $(uname -m) == \"arm64\" ]]; then\n log \"WARNING: Pre-built images are amd64. On Apple Silicon, consider:\"\n log \" - Building locally: ./build_and_run.sh --podman\"\n log \" - Or using Docker Desktop: ./build_and_run.sh --prebuilt\"\n log \" Continuing in 5 seconds... (Ctrl+C to cancel)\"\n sleep 5\n fi\nelse\n log \"Building containers locally (this may take several minutes)\"\nfi\n\nlog \"Using compose files: $COMPOSE_FILES\"\nlog \"Starting MCP Gateway deployment script\"\n\n# Only check Node.js and build frontend when building locally\nif [ \"$USE_PREBUILT\" = false ]; then\n # Check if Node.js and npm are installed\n if ! command -v node &> /dev/null; then\n log \"ERROR: Node.js is not installed\"\n log \"Please install Node.js (version 16 or higher): https://nodejs.org/\"\n exit 1\n fi\n\n if ! command -v npm &> /dev/null; then\n log \"ERROR: npm is not installed\"\n log \"Please install npm (usually comes with Node.js): https://nodejs.org/\"\n exit 1\n fi\n\n # Check Node.js version\n NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)\n if [ \"$NODE_VERSION\" -lt 16 ]; then\n log \"ERROR: Node.js version $NODE_VERSION is too old. Please install Node.js 16 or higher.\"\n exit 1\n fi\n\n log \"Node.js $(node -v) and npm $(npm -v) are available\"\n\n # Build the React frontend\n log \"Building React frontend...\"\n if [ ! -d \"frontend\" ]; then\n handle_error \"Frontend directory not found\"\n fi\n\n cd frontend\n\n # Install frontend dependencies\n log \"Installing frontend dependencies...\"\n npm install || handle_error \"Failed to install frontend dependencies\"\n\n # Build the React application\n log \"Building React application for production...\"\n npm run build || handle_error \"Failed to build React application\"\n\n log \"Frontend build completed successfully\"\n cd ..\nelse\n log \"Skipping frontend build (using pre-built images)\"\nfi\n\n# Check if .env file exists\nif [ ! -f .env ]; then\n log \"ERROR: .env file not found\"\n log \"Please create a .env file with your configuration values:\"\n log \"Example .env file:\"\n log \"SECRET_KEY=your_secret_key_here\"\n log \"# SECRET_KEY is auto-generated if not set. It is used to sign JWT session tokens.\"\n log \"# For Financial Info server API keys, see servers/fininfo/README_SECRETS.md\"\n exit 1\nfi\n\nlog \"Found .env file\"\n\n# Load environment variables from .env file early so we can check STORAGE_BACKEND\nsource .env\n\n# Check if docker compose is installed\nif ! docker compose version &> /dev/null; then\n log \"ERROR: docker compose is not available\"\n log \"Please install Docker Compose v2: https://docs.docker.com/compose/install/\"\n exit 1\nfi\n\n# Stop and remove existing services if they exist\nlog \"Stopping existing services (if any)...\"\n$COMPOSE_CMD $COMPOSE_FILES down --remove-orphans || log \"No existing services to stop\"\nlog \"Existing services stopped\"\n\n# Clean up FAISS index files to force registry to recreate them\nlog \"Checking FAISS index files...\"\nMCPGATEWAY_SERVERS_DIR=\"${HOME}/mcp-gateway/servers\"\nFAISS_FILES=(\"service_index.faiss\" \"service_index_metadata.json\")\n\n# Check if FAISS index files exist\nFAISS_EXISTS=false\nfor file in \"${FAISS_FILES[@]}\"; do\n file_path=\"$MCPGATEWAY_SERVERS_DIR/$file\"\n if [ -f \"$file_path\" ]; then\n FAISS_EXISTS=true\n break\n fi\ndone\n\nif [ \"$FAISS_EXISTS\" = true ]; then\n echo \"\"\n echo \"╔════════════════════════════════════════════════════════════════════════════╗\"\n echo \"║ FAISS INDEX FILES EXIST ║\"\n echo \"╠════════════════════════════════════════════════════════════════════════════╣\"\n echo \"║ ║\"\n echo \"║ Existing FAISS index files were found in: ║\"\n echo \"║ $MCPGATEWAY_SERVERS_DIR/\"\n echo \"║ ║\"\n echo \"║ These files contain your server registry and search index. ║\"\n echo \"║ To preserve your registered servers, these files will NOT be deleted. ║\"\n echo \"║ ║\"\n echo \"║ If you need to regenerate the FAISS index (e.g., after corruption): ║\"\n echo \"║ 1. Delete the existing files: ║\"\n echo \"║ rm $MCPGATEWAY_SERVERS_DIR/service_index*\"\n echo \"║ 2. The registry will automatically rebuild the index on startup ║\"\n echo \"║ ║\"\n echo \"╚════════════════════════════════════════════════════════════════════════════╝\"\n echo \"\"\n log \"Keeping existing FAISS index files - NOT deleting\"\nelse\n log \"No existing FAISS index files found - will be created on first startup\"\nfi\n\n# Clean up any root-owned directories from previous Docker runs\nlog \"Checking for root-owned directories from previous Docker runs...\"\n\n# Check and remove root-owned directories\nfor dir in \"$MCPGATEWAY_SERVERS_DIR\" \"${HOME}/mcp-gateway/agents\" \"${HOME}/mcp-gateway/auth_server\" \"${HOME}/mcp-gateway/security_scans\" \"${HOME}/mcp-gateway/federation.json\"; do\n if [ -e \"$dir\" ] && [ \"$(stat -c '%U' \"$dir\" 2>/dev/null)\" = \"root\" ]; then\n log \"Removing root-owned: $dir\"\n sudo rm -rf \"$dir\"\n fi\ndone\n\n# Copy JSON files from registry/servers to ${HOME}/mcp-gateway/servers with environment variable substitution\nlog \"Copying JSON files from registry/servers to $MCPGATEWAY_SERVERS_DIR...\"\nif [ -d \"registry/servers\" ]; then\n # Create the target directory if it doesn't exist\n mkdir -p \"$MCPGATEWAY_SERVERS_DIR\"\n\n # Copy all JSON files with environment variable substitution\n if ls registry/servers/*.json 1> /dev/null 2>&1; then\n # Export all environment variables from .env file for envsubst\n set -a # Automatically export all variables\n source .env\n set +a # Turn off automatic export\n\n for json_file in registry/servers/*.json; do\n filename=$(basename \"$json_file\")\n log \"Processing $filename with environment variable substitution...\"\n\n # Use envsubst to substitute environment variables, then copy to target\n envsubst < \"$json_file\" > \"$MCPGATEWAY_SERVERS_DIR/$filename\"\n done\n log \"JSON files copied successfully with environment variable substitution\"\n\n # Verify atlassian.json was copied\n if [ -f \"$MCPGATEWAY_SERVERS_DIR/atlassian.json\" ]; then\n log \"atlassian.json copied successfully\"\n else\n log \"WARNING: atlassian.json not found in copied files\"\n fi\n else\n log \"No JSON files found in registry/servers\"\n fi\nelse\n log \"WARNING: registry/servers directory not found\"\nfi\n\n# Copy seed agent JSON files from cli/examples to ${HOME}/mcp-gateway/agents\nAGENTS_DIR=\"${HOME}/mcp-gateway/agents\"\nlog \"Copying seed agent files from cli/examples to $AGENTS_DIR...\"\nif [ -d \"cli/examples\" ]; then\n # Create the target directory if it doesn't exist\n mkdir -p \"$AGENTS_DIR\"\n\n # Copy all agent JSON files from cli/examples\n if ls cli/examples/*agent*.json 1> /dev/null 2>&1; then\n for json_file in cli/examples/*agent*.json; do\n filename=$(basename \"$json_file\")\n log \"Copying seed agent $filename...\"\n\n # Copy agent file to target directory\n cp \"$json_file\" \"$AGENTS_DIR/$filename\"\n done\n log \"Seed agent files copied successfully\"\n else\n log \"No seed agent files found in cli/examples\"\n fi\nelse\n log \"WARNING: cli/examples directory not found - seed agents will not be copied\"\nfi\n\n# Copy scopes.yml to ${HOME}/mcp-gateway/auth_server\nAUTH_SERVER_DIR=\"${HOME}/mcp-gateway/auth_server\"\nTARGET_SCOPES_FILE=\"$AUTH_SERVER_DIR/scopes.yml\"\n\nlog \"Checking scopes.yml configuration...\"\nif [ -f \"auth_server/scopes.yml\" ]; then\n # Create the target directory if it doesn't exist\n mkdir -p \"$AUTH_SERVER_DIR\"\n\n # Check if scopes.yml already exists in the target directory\n if [ -f \"$TARGET_SCOPES_FILE\" ]; then\n echo \"\"\n echo \"╔════════════════════════════════════════════════════════════════════════════╗\"\n echo \"║ SCOPES.YML EXISTS ║\"\n echo \"╠════════════════════════════════════════════════════════════════════════════╣\"\n echo \"║ ║\"\n echo \"║ An existing scopes.yml file was found at: ║\"\n echo \"║ $TARGET_SCOPES_FILE\"\n echo \"║ ║\"\n echo \"║ This file contains your custom groups and server configurations. ║\"\n echo \"║ To preserve your settings, this file will NOT be overwritten. ║\"\n echo \"║ ║\"\n echo \"║ If you need to restore the default scopes.yml from the codebase: ║\"\n echo \"║ 1. Delete the existing file: ║\"\n echo \"║ rm $TARGET_SCOPES_FILE\"\n echo \"║ 2. Re-run this script ║\"\n echo \"║ ║\"\n echo \"╚════════════════════════════════════════════════════════════════════════════╝\"\n echo \"\"\n log \"Keeping existing scopes.yml - NOT overwriting\"\n else\n # Copy scopes.yml for first-time setup\n cp auth_server/scopes.yml \"$AUTH_SERVER_DIR/\"\n log \"scopes.yml copied successfully to $AUTH_SERVER_DIR (initial setup)\"\n fi\nelse\n log \"WARNING: auth_server/scopes.yml not found in codebase\"\nfi\n\n# Create empty security_scans directory for Docker mount\nSECURITY_SCANS_DIR=\"${HOME}/mcp-gateway/security_scans\"\nlog \"Creating empty security_scans directory for Docker mount\"\nmkdir -p \"$SECURITY_SCANS_DIR\"\n\n# Create empty federation.json file for Docker mount\nFEDERATION_JSON_FILE=\"${HOME}/mcp-gateway/federation.json\"\nlog \"Creating empty federation.json for Docker mount\"\ntouch \"$FEDERATION_JSON_FILE\"\n\n# Setup SSL certificate directory structure\nSSL_DIR=\"${HOME}/mcp-gateway/ssl\"\nlog \"Setting up SSL certificate directory structure...\"\nmkdir -p \"$SSL_DIR/certs\"\nmkdir -p \"$SSL_DIR/private\"\n\n# Check if SSL certificates exist and are properly located\nif [ -f \"$SSL_DIR/certs/fullchain.pem\" ] && [ -f \"$SSL_DIR/private/privkey.pem\" ]; then\n log \"SSL certificates found - HTTPS will be enabled\"\n chmod 644 \"$SSL_DIR/certs/fullchain.pem\"\n chmod 600 \"$SSL_DIR/private/privkey.pem\"\nelse\n log \"No SSL certificates found - HTTP-only mode will be used\"\n log \"To enable HTTPS, place certificates at:\"\n log \" - $SSL_DIR/certs/fullchain.pem\"\n log \" - $SSL_DIR/private/privkey.pem\"\nfi\n\n# Generate a random SECRET_KEY if not already in .env\nif ! grep -q \"SECRET_KEY=\" .env || grep -q \"SECRET_KEY=$\" .env || grep -q \"SECRET_KEY=\\\"\\\"\" .env; then\n log \"Generating SECRET_KEY...\"\n SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))') || handle_error \"Failed to generate SECRET_KEY\"\n \n # Remove any existing empty SECRET_KEY line\n sed -i '/^SECRET_KEY=$/d' .env 2>/dev/null || true\n sed -i '/^SECRET_KEY=\"\"$/d' .env 2>/dev/null || true\n \n # Add new SECRET_KEY\n echo \"SECRET_KEY=$SECRET_KEY\" >> .env\n log \"SECRET_KEY added to .env\"\nelse\n log \"SECRET_KEY already exists in .env\"\nfi\n\n# Validate required environment variables\nlog \"Validating required environment variables...\"\nsource .env\n\n# Determine BUILD_VERSION from git\nlog \"Determining version from git...\"\nif command -v git &> /dev/null && [ -d .git ]; then\n # Get the current git tag\n GIT_TAG=$(git describe --tags --exact-match 2>/dev/null || echo \"\")\n\n if [ -n \"$GIT_TAG\" ]; then\n # We're on a tagged commit - use just the tag (remove 'v' prefix)\n export BUILD_VERSION=\"${GIT_TAG#v}\"\n log \"Building release version: $BUILD_VERSION\"\n else\n # Not on a tag - include branch name and commit info\n GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo \"unknown\")\n GIT_DESCRIBE=$(git describe --tags --always 2>/dev/null || echo \"dev\")\n\n # Format: version-branch or describe-branch\n if [[ \"$GIT_DESCRIBE\" =~ ^[0-9] ]]; then\n # Starts with version number from describe\n export BUILD_VERSION=\"${GIT_DESCRIBE#v}-${GIT_BRANCH}\"\n else\n # No version tags found, use commit hash\n export BUILD_VERSION=\"${GIT_DESCRIBE}-${GIT_BRANCH}\"\n fi\n\n log \"Building development version: $BUILD_VERSION\"\n fi\nelse\n export BUILD_VERSION=\"1.0.0-dev\"\n log \"Git not available, using default version: $BUILD_VERSION\"\nfi\n\n# Build or pull container images\nif [ \"$USE_PREBUILT\" = true ]; then\n log \"Pulling pre-built container images...\"\n $COMPOSE_CMD $COMPOSE_FILES pull || handle_error \"Compose pull failed\"\n log \"Pre-built container images pulled successfully\"\nelse\n log \"Building container images with optimization...\"\n # Enable BuildKit for better caching and parallel builds (Docker only)\n if [[ \"$COMPOSE_CMD\" == \"docker compose\" ]]; then\n export DOCKER_BUILDKIT=1\n export COMPOSE_DOCKER_CLI_BUILD=1\n fi\n\n # Build with parallel jobs and build cache\n $COMPOSE_CMD $COMPOSE_FILES build --parallel --progress=auto || handle_error \"Compose build failed\"\n log \"Container images built successfully with optimization\"\nfi\n\n# Start metrics service first to generate API keys\nlog \"Starting metrics service first...\"\n$COMPOSE_CMD $COMPOSE_FILES up -d metrics-service || handle_error \"Failed to start metrics service\"\n\n# Wait for metrics service to be ready\nlog \"Waiting for metrics service to be ready...\"\nmax_retries=30\nretry_count=0\nwhile [ $retry_count -lt $max_retries ]; do\n if curl -f http://localhost:8890/health &>/dev/null; then\n log \"Metrics service is ready\"\n break\n fi\n sleep 2\n retry_count=$((retry_count + 1))\n log \"Waiting for metrics service... ($retry_count/$max_retries)\"\ndone\n\nif [ $retry_count -eq $max_retries ]; then\n handle_error \"Metrics service did not become ready within expected time\"\nfi\n\n# Generate dynamic pre-shared tokens for metrics authentication\nlog \"Setting up dynamic pre-shared tokens for services...\"\n\n# Get all services from compose file that might need metrics (exclude monitoring services)\nMETRICS_SERVICES=$($COMPOSE_CMD $COMPOSE_FILES config --services 2>/dev/null | grep -v -E \"(prometheus|grafana|metrics-db)\" | sort | uniq)\n\nif [ -z \"$METRICS_SERVICES\" ]; then\n log \"WARNING: No services found for metrics configuration\"\nelse\n log \"Found services for metrics: $(echo $METRICS_SERVICES | tr '\\n' ' ')\"\nfi\n\n# Check if tokens already exist in .env\nsource .env 2>/dev/null || true\n\n# Generate tokens for each service dynamically\nfor service in $METRICS_SERVICES; do\n # Convert service name to environment variable format\n # auth-server -> METRICS_API_KEY_AUTH_SERVER\n # metrics-service -> METRICS_API_KEY_METRICS_SERVICE (will be skipped as it's the metrics service itself)\n ENV_VAR_NAME=\"METRICS_API_KEY_$(echo \"$service\" | tr '[:lower:]-' '[:upper:]_')\"\n \n # Skip the metrics service itself and non-metrics services\n if [ \"$service\" = \"metrics-service\" ] || [ \"$service\" = \"prometheus\" ] || [ \"$service\" = \"grafana\" ]; then\n continue\n fi\n \n # Get current value\n CURRENT_VALUE=$(eval echo \"\\$$ENV_VAR_NAME\")\n \n # Generate token only if it doesn't exist or is empty\n if [ -z \"$CURRENT_VALUE\" ] || [ \"$CURRENT_VALUE\" = \"\" ]; then\n NEW_TOKEN=\"mcp_metrics_$(openssl rand -hex 16)\"\n \n # Remove any existing line for this variable\n sed -i \"/^$ENV_VAR_NAME=/d\" .env 2>/dev/null || true\n \n # Add new token\n echo \"$ENV_VAR_NAME=$NEW_TOKEN\" >> .env\n log \"Generated new $service token: ${NEW_TOKEN:0:20}...\"\n else\n log \"Using existing $service token: ${CURRENT_VALUE:0:20}...\"\n fi\ndone\n\nlog \"Dynamic metrics API tokens configured successfully\"\n\n# Now start all other services with the API keys in environment\nlog \"Starting remaining services...\"\n$COMPOSE_CMD $COMPOSE_FILES up -d || handle_error \"Failed to start remaining services\"\n\n# Wait a moment for services to initialize\nlog \"Waiting for services to initialize...\"\nsleep 10\n\n# Check service status\nlog \"Checking service status...\"\n$COMPOSE_CMD $COMPOSE_FILES ps\n\n# Verify key services are running\nlog \"Verifying services are healthy...\"\n\n# Check registry service\nif curl -f http://localhost:7860/health &>/dev/null; then\n log \"Registry service is healthy\"\nelse\n log \"WARNING: Registry service may still be starting up...\"\nfi\n\n# Check auth service\nif curl -f http://localhost:18888/health &>/dev/null; then\n log \"Auth service is healthy\"\nelse\n log \"WARNING: Auth service may still be starting up...\"\nfi\n\n# Check nginx is responding\nif curl -f http://localhost:80 &>/dev/null || curl -k -f https://localhost:443 &>/dev/null; then\n log \"Nginx is responding\"\nelse\n log \"WARNING: Nginx may still be starting up...\"\nfi\n\n# Verify FAISS index creation\nlog \"Verifying FAISS index creation...\"\nsleep 5 # Give registry service time to create the index\n\nif [ -f \"$MCPGATEWAY_SERVERS_DIR/service_index.faiss\" ]; then\n log \"FAISS index created successfully at $MCPGATEWAY_SERVERS_DIR/service_index.faiss\"\n \n # Check if metadata file also exists\n if [ -f \"$MCPGATEWAY_SERVERS_DIR/service_index_metadata.json\" ]; then\n log \"FAISS index metadata created successfully\"\n else\n log \"WARNING: FAISS index metadata file not found\"\n fi\nelse\n log \"WARNING: FAISS index not yet created. The registry service will create it on first access.\"\nfi\n\n# Verify server list includes Atlassian\nlog \"Verifying server list...\"\nif [ -f \"$MCPGATEWAY_SERVERS_DIR/atlassian.json\" ]; then\n log \"Atlassian server configuration present\"\nfi\n\n# List all available server JSON files\nlog \"Available server configurations in $MCPGATEWAY_SERVERS_DIR:\"\nif ls \"$MCPGATEWAY_SERVERS_DIR\"/*.json 2>/dev/null | head -n 10; then\n TOTAL_SERVERS=$(ls \"$MCPGATEWAY_SERVERS_DIR\"/*.json 2>/dev/null | wc -l)\n log \"Total server configurations: $TOTAL_SERVERS\"\nelse\n log \"WARNING: No server configurations found in $MCPGATEWAY_SERVERS_DIR\"\nfi\n\n\nlog \"Deployment completed successfully\"\nlog \"\"\n\n# Display correct URLs based on container engine\nif [[ \"$COMPOSE_CMD\" == \"podman compose\" ]]; then\n log \"Services are available at:\"\n log \" - Main interface: http://localhost:8080 or https://localhost:8443\"\n log \" - Registry API: http://localhost:7860\"\n log \" - Auth service: http://localhost:8888\"\n log \" - Current Time MCP: http://localhost:8000\"\n log \" - Financial Info MCP: http://localhost:8001\"\n log \" - Real Server Fake Tools MCP: http://localhost:8002\"\n log \" - MCP Gateway MCP: http://localhost:8003\"\nelse\n log \"Services are available at:\"\n log \" - Main interface: http://localhost or https://localhost\"\n log \" - Registry API: http://localhost:7860\"\n log \" - Auth service: http://localhost:8888\"\n log \" - Current Time MCP: http://localhost:8000\"\n log \" - Financial Info MCP: http://localhost:8001\"\n log \" - Real Server Fake Tools MCP: http://localhost:8002\"\n log \" - MCP Gateway MCP: http://localhost:8003\"\nfi\nlog \"\"\nlog \"To view logs for all services: $COMPOSE_CMD $COMPOSE_FILES logs -f\"\nlog \"To view logs for a specific service: $COMPOSE_CMD $COMPOSE_FILES logs -f \"\nlog \"To stop services: $COMPOSE_CMD $COMPOSE_FILES down\"\nlog \"\"\n\n# Ask if user wants to follow logs\nread -p \"Do you want to follow the logs? (y/n): \" -n 1 -r\necho\nif [[ $REPLY =~ ^[Yy]$ ]]; then\n log \"Following container logs (press Ctrl+C to stop following logs without stopping the services):\"\n echo \"---------- CONTAINER LOGS ----------\"\n $COMPOSE_CMD $COMPOSE_FILES logs -f\nelse\n log \"Services are running in the background. Use '$COMPOSE_CMD $COMPOSE_FILES logs -f' to view logs.\"\nfi" }, { "path": "charts/README.md", "content": "# MCP Gateway Registry Helm Charts\n\nThis directory contains Helm charts for deploying the MCP Gateway Registry stack on Kubernetes.\n\n## Prerequisites\n\n### EKS Cluster Setup\n\nFor deploying on Amazon EKS, we recommend using the [AWS AI/ML on Amazon EKS](https://github.com/awslabs/ai-on-eks) blueprints to provision an EKS cluster with GPU support, autoscaling, and AI/ML optimizations.\n\n**Quick Start with AI on EKS:**\n\n```bash\n# Clone the AI on EKS repository\ngit clone https://github.com/awslabs/ai-on-eks.git\ncd ai-on-eks\n\n# Until https://github.com/awslabs/ai-on-eks/pull/232 is merged, the custom stack can be used\n\ncd infra/custom\n./install.sh\n```\n\nOnce your EKS cluster is provisioned, return to this directory to deploy the MCP Gateway Registry using the Helm charts.\n\n### Required Components\n\n- Kubernetes cluster (EKS, GKE, AKS, or self-managed)\n- `helm` CLI installed (v3.0+)\n- `kubectl` configured to access your cluster\n- Ingress controller (ALB, NGINX, or Traefik)\n- DNS configuration for your domain\n- SSL/TLS certificates (optional but recommended)\n\n## Charts Overview\n\n### Individual Charts\n\n- **auth-server**: Authentication service for the MCP Gateway (supports Keycloak and Entra ID)\n- **registry**: MCP server registry service\n- **keycloak-configure**: Job to configure Keycloak realms and clients\n- **mongodb-configure**: Job to configure MongoDB and scopes\n\n### Stack Chart\n\n- **mcp-gateway-registry-stack**: Complete stack deployment including identity provider, auth-server, registry, and configuration\n\n## Authentication Providers\n\nThe charts support two authentication providers:\n\n- **Keycloak** (default): Open-source identity and access management\n- **Microsoft Entra ID**: Azure Active Directory / Microsoft Entra ID\n\n### Selecting a Provider\n\nSet the authentication provider in your values file:\n\n```yaml\nglobal:\n authProvider:\n type: keycloak # or \"entra\"\n\n# For Keycloak in stack\nkeycloak:\n create: true\n\n# For external Keycloak\nkeycloak:\n create: false\n externalUrl: https://your-keycloak.com\n\n# For Entra ID\nkeycloak:\n create: false\n```\n\n## Improved Values Structure\n\nThe values files have been standardized with the following structure:\n\n### Global Configuration\n\n```yaml\nglobal:\n image:\n repository: mcpgateway/service-name\n tag: v1.0.7\n pullPolicy: IfNotPresent\n```\n\n### Application Configuration\n\n```yaml\napp:\n name: service-name\n replicas: 1\n externalUrl: http://localhost:8080\n secretKey: your-secret-key\n```\n\n### Service Configuration\n\n```yaml\nservice:\n type: ClusterIP\n port: 8080\n annotations: { }\n```\n\n### Resources\n\n```yaml\nresources:\n requests:\n cpu: 1\n memory: 1Gi\n limits:\n cpu: 2\n memory: 2Gi\n```\n\n### Ingress\n\n```yaml\ningress:\n enabled: false\n className: alb\n hostname: \"\"\n annotations: { }\n tls: false\n```\n\n## Key Improvements\n\n1. **Consistent Structure**: All charts now follow the same values organization\n2. **Standardized Naming**: Unified naming conventions across all charts\n3. **Reduced Duplication**: Eliminated redundant resource definitions\n4. **Better Defaults**: Sensible default values for development and production\n5. **Clean Templates**: Updated all templates to use the new values structure\n6. **Clear Documentation**: Inline comments explaining configuration options\n\n## Usage\n\n### Deploy Individual Services\n\n```bash\nhelm install auth-server ./charts/auth-server\nhelm install registry ./charts/registry\n```\n\n### Deploy Complete Stack\n\n```bash\n# Option 1: Update values.yaml file directly\n# Edit charts/mcp-gateway-registry-stack/values.yaml and change global.domain\n\n# Option 2: Override via command line\nhelm install mcp-stack ./charts/mcp-gateway-registry-stack \\\n --set global.domain=yourdomain.com \\\n --set global.secretKey=your-production-secret\n```\n\n## Configuration Notes\n\n- **Domain**: The stack chart uses the domain from `global.domain` and applies it to all subcharts\n- **Secret Keys**: Change default secret keys in production - they should match across all services\n- **Resources**: Adjust CPU/memory based on your requirements\n- **Ingress**: Configure ingress settings for your environment\n- **Existing Secrets**: All charts support referencing pre-existing Kubernetes secrets instead of having Helm manage them. See the [stack chart README](mcp-gateway-registry-stack/README.md#using-existing-secrets) for details.\n\n### Domain Configuration\n\nThe stack chart uses `global.domain` to automatically configure all service endpoints. You can choose between two routing modes:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ ROUTING MODES │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ SUBDOMAIN MODE (Default) PATH MODE │\n│ ───────────────────── ───────── │\n│ │\n│ ✓ keycloak.domain.com ✓ domain.com/keycloak │\n│ ✓ auth-server.domain.com ✓ domain.com/auth-server│\n│ ✓ mcpregistry.domain.com ✓ domain.com/registry │\n│ ✓ domain.com/ │\n│ │\n│ DNS: Multiple records DNS: Single record │\n│ Cert: Wildcard or multiple Cert: Single │\n│ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n#### Subdomain-Based Routing (Default)\n\nServices are accessed via subdomains:\n- `keycloak.{domain}` - Keycloak authentication server\n- `auth-server.{domain}` - MCP Gateway auth server\n- `mcpregistry.{domain}` - MCP server registry\n\n**Configuration:**\n```yaml\nglobal:\n domain: \"yourdomain.com\"\n ingress:\n routingMode: subdomain\n```\n\n#### Path-Based Routing\n\nServices are accessed via paths on a single domain:\n- `{domain}/keycloak` - Keycloak authentication server\n- `{domain}/auth-server` - MCP Gateway auth server\n- `{domain}/registry` - MCP server registry\n\n**Note:** All paths are configurable. You can customize them to match your URL structure (e.g., `/api/auth`, `/api/registry`).\n\n**Configuration:**\n```yaml\nglobal:\n domain: \"yourdomain.com\"\n ingress:\n routingMode: path\n paths:\n authServer: /auth-server # Customize as needed\n registry: /registry # Customize as needed\n keycloak: /keycloak # Customize as needed\n```\n\n**Important:** If you change the Keycloak path, you must also update the `keycloak.httpRelativePath` environment variable:\n```yaml\nkeycloak:\n httpRelativePath: /keycloak/\n```\n\n**How it works:**\n\n1. Set `global.domain` in the stack values file\n2. Choose `routingMode: subdomain` or `routingMode: path`\n3. All subchart templates reference these values to build URLs and hostnames\n4. Change the domain or routing mode once and all services update automatically\n\n**To change the domain or routing mode:**\n\n```bash\n# Edit the values file\nvim charts/mcp-gateway-registry-stack/values.yaml\n# Change: global.domain: \"your-new-domain.com\"\n# Change: global.ingress.routingMode: \"path\"\n\n# Or override via command line\nhelm upgrade mcp-stack ./charts/mcp-gateway-registry-stack \\\n --set global.domain=your-new-domain.com \\\n --set global.ingress.routingMode=path\n```\n\n**DNS Configuration:**\n\n- **Subdomain mode:** Configure DNS A/CNAME records for each subdomain pointing to your ingress\n- **Path mode:** Configure a single DNS A/CNAME record for your domain pointing to your ingress\n\n## Deployment Options: Kubernetes vs AWS ECS\n\nThis project supports two deployment methods:\n\n### 1. Kubernetes Deployment (This Directory)\n\nDeploy the MCP Gateway Registry on any Kubernetes cluster using Helm charts. Ideal for:\n- Multi-cloud deployments (AWS EKS, Google GKE, Azure AKS)\n- On-premises Kubernetes clusters\n- Organizations with existing Kubernetes infrastructure\n- Scenarios requiring portability and vendor neutrality\n\n**Location:** `/charts` directory (this location)\n\n**Tools:** Helm charts, Kubernetes manifests\n\n### 2. AWS ECS Deployment (Terraform)\n\nDeploy the MCP Gateway Registry on AWS ECS using Terraform for infrastructure-as-code. Ideal for:\n- AWS-native deployments with full AWS integration\n- Organizations using AWS Fargate for serverless containers\n- Teams preferring Terraform for infrastructure management\n- Deployments requiring tight AWS service integration (ALB, ECR, EFS, Secrets Manager)\n\n**Location:** `/terraform/aws-ecs` directory\n\n**Tools:** Terraform modules, AWS ECS task definitions, AWS Fargate\n\n### Choosing Between Kubernetes and ECS\n\n| Feature | Kubernetes (Helm) | AWS ECS (Terraform) |\n|---------|------------------|---------------------|\n| **Portability** | High - works on any K8s cluster | AWS-specific |\n| **Multi-cloud** | Yes | No (AWS only) |\n| **Complexity** | Moderate - requires K8s knowledge | Lower - managed by AWS |\n| **Customization** | High - full K8s ecosystem | Moderate - AWS services |\n| **Auto-scaling** | K8s HPA, Cluster Autoscaler | ECS Service Auto Scaling |\n| **Cost** | Depends on cluster costs | Pay-per-task (Fargate) |\n| **Tools** | kubectl, helm | AWS CLI, terraform |\n\n**Note:** The Helm charts and Terraform configurations are separate deployment methods. Choose the one that best fits your infrastructure and team expertise." }, { "path": "charts/auth-server/Chart.yaml", "content": "apiVersion: v2\nname: auth-server\ndescription: A Helm chart for auth-server for MCP Gateway Registry\ntype: application\nversion: 0.1.0\nappVersion: \"1.0.0\"\n" }, { "path": "charts/auth-server/templates/configmap-app-log.yaml", "content": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: auth-server-app-log-config\n namespace: {{ .Release.Namespace | quote }}\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\ndata:\n APP_LOG_MAX_BYTES: {{ .Values.app.appLogMaxBytes | default \"52428800\" | quote }}\n APP_LOG_BACKUP_COUNT: {{ .Values.app.appLogBackupCount | default \"5\" | quote }}\n APP_LOG_CENTRALIZED_ENABLED: {{ .Values.app.appLogCentralizedEnabled | default \"true\" | quote }}\n APP_LOG_CENTRALIZED_TTL_DAYS: {{ .Values.app.appLogCentralizedTtlDays | default \"1\" | quote }}\n APP_LOG_MONGODB_BUFFER_SIZE: {{ .Values.app.appLogMongodbBufferSize | default \"50\" | quote }}\n APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS: {{ .Values.app.appLogMongodbFlushIntervalSeconds | default \"5.0\" | quote }}\n APP_LOG_LEVEL: {{ .Values.app.appLogLevel | default \"INFO\" | quote }}\n APP_LOG_EXCLUDED_LOGGERS: {{ .Values.app.appLogExcludedLoggers | default \"uvicorn.access,httpx,pymongo,motor\" | quote }}\n" }, { "path": "charts/auth-server/templates/deployment.yaml", "content": "{{- /* Determine auth provider type - prefer global, fallback to local, default to keycloak */ -}}\n{{- $authProviderType := .Values.authProvider.type | default \"keycloak\" }}\n{{- if .Values.global.authProvider }}\n {{- $authProviderType = .Values.global.authProvider.type | default $authProviderType }}\n{{- end }}\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\nspec:\n replicas: {{ .Values.app.replicas }}\n selector:\n matchLabels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n template:\n metadata:\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n spec:\n {{- with .Values.nodeSelector }}\n nodeSelector:\n {{- toYaml . | nindent 8 }}\n {{- end }}\n securityContext:\n runAsNonRoot: true\n runAsUser: 1000\n runAsGroup: 1000\n fsGroup: 1000\n containers:\n - name: {{ .Values.app.name }}\n image: \"{{ .Values.global.image.repository }}:{{ .Values.global.image.tag }}\"\n imagePullPolicy: {{ .Values.global.image.pullPolicy }}\n securityContext:\n allowPrivilegeEscalation: false\n capabilities:\n drop:\n - ALL\n ports:\n - containerPort: {{ .Values.service.port }}\n name: http\n resources:\n {{- toYaml .Values.resources | nindent 12 }}\n envFrom:\n - configMapRef:\n name: auth-server-app-log-config\n - secretRef:\n name: {{ .Values.app.existingSecret | default .Values.app.envSecretName }}\n {{- if eq $authProviderType \"keycloak\" }}\n - secretRef:\n name: keycloak-client-secret\n {{- end }}\n - secretRef:\n name: {{ .Values.global.existingMongoCredentialsSecret | default \"mongo-credentials\" }}\n {{- if .Values.global.sharedSecretName }}\n - secretRef:\n name: {{ .Values.global.existingSharedSecret | default .Values.global.sharedSecretName }}\n {{- end }}\n {{- if .Values.global.oauthProviderSecretName }}\n - secretRef:\n name: {{ .Values.global.existingOauthProviderSecret | default .Values.global.oauthProviderSecretName }}\n {{- end }}\n env:\n {{- if .Values.entra.clientSecretExistingSecret }}\n - name: ENTRA_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.entra.clientSecretExistingSecret }}\n key: {{ .Values.entra.clientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.okta.clientSecretExistingSecret }}\n - name: OKTA_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.okta.clientSecretExistingSecret }}\n key: {{ .Values.okta.clientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.okta.m2mClientSecretExistingSecret }}\n - name: OKTA_M2M_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.okta.m2mClientSecretExistingSecret }}\n key: {{ .Values.okta.m2mClientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.okta.apiTokenExistingSecret }}\n - name: OKTA_API_TOKEN\n valueFrom:\n secretKeyRef:\n name: {{ .Values.okta.apiTokenExistingSecret }}\n key: {{ .Values.okta.apiTokenExistingSecretKey }}\n {{- end }}\n {{- if .Values.auth0.clientSecretExistingSecret }}\n - name: AUTH0_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.auth0.clientSecretExistingSecret }}\n key: {{ .Values.auth0.clientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.auth0.m2mClientSecretExistingSecret }}\n - name: AUTH0_M2M_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.auth0.m2mClientSecretExistingSecret }}\n key: {{ .Values.auth0.m2mClientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.auth0.managementApiTokenExistingSecret }}\n - name: AUTH0_MANAGEMENT_API_TOKEN\n valueFrom:\n secretKeyRef:\n name: {{ .Values.auth0.managementApiTokenExistingSecret }}\n key: {{ .Values.auth0.managementApiTokenExistingSecretKey }}\n {{- end }}\n livenessProbe:\n httpGet:\n path: /health\n port: 8888\n initialDelaySeconds: 30\n periodSeconds: 10\n timeoutSeconds: 5\n failureThreshold: 3\n readinessProbe:\n httpGet:\n path: /health\n port: 8888\n initialDelaySeconds: 10\n periodSeconds: 5\n timeoutSeconds: 3\n failureThreshold: 3\n" }, { "path": "charts/auth-server/templates/ingress.yaml", "content": "{{- if .Values.ingress.enabled }}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $domain := .Values.global.domain | default .Values.ingress.hostname }}\n{{- $pathPrefix := .Values.global.ingress.paths.authServer | default .Values.ingress.path | default \"/auth-server\" }}\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n annotations:\n {{- if eq $routingMode \"path\" }}\n alb.ingress.kubernetes.io/group.name: mcp-gateway-stack\n alb.ingress.kubernetes.io/group.order: '10'\n {{- end }}\n alb.ingress.kubernetes.io/listen-ports: '[{\"HTTPS\": 443}]'\n alb.ingress.kubernetes.io/scheme: internet-facing\n alb.ingress.kubernetes.io/ssl-redirect: '443'\n alb.ingress.kubernetes.io/target-type: ip\n alb.ingress.kubernetes.io/success-codes: 200,302\n alb.ingress.kubernetes.io/healthcheck-path: /health\n {{- if .Values.global.ingress.inboundCidrs }}\n alb.ingress.kubernetes.io/inbound-cidrs: {{ .Values.global.ingress.inboundCidrs }}\n {{- end }}\nspec:\n ingressClassName: {{ .Values.ingress.className }}\n rules:\n {{- if eq $routingMode \"path\" }}\n - host: {{ $domain | quote }}\n http:\n paths:\n - path: {{ $pathPrefix }}\n pathType: Prefix\n backend:\n service:\n name: {{ .Values.app.name }}\n port:\n name: http\n {{- else }}\n - host: {{ printf \"auth-server.%s\" $domain | quote }}\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: {{ .Values.app.name }}\n port:\n name: http\n {{- end }}\n{{- end }}\n" }, { "path": "charts/auth-server/templates/secret.yaml", "content": "{{- if and .Values.entra.clientSecret .Values.entra.clientSecretExistingSecret }}\n {{- fail \"Cannot set both entra.clientSecret and entra.clientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.okta.clientSecret .Values.okta.clientSecretExistingSecret }}\n {{- fail \"Cannot set both okta.clientSecret and okta.clientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.okta.m2mClientSecret .Values.okta.m2mClientSecretExistingSecret }}\n {{- fail \"Cannot set both okta.m2mClientSecret and okta.m2mClientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.okta.apiToken .Values.okta.apiTokenExistingSecret }}\n {{- fail \"Cannot set both okta.apiToken and okta.apiTokenExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.auth0.clientSecret .Values.auth0.clientSecretExistingSecret }}\n {{- fail \"Cannot set both auth0.clientSecret and auth0.clientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.auth0.m2mClientSecret .Values.auth0.m2mClientSecretExistingSecret }}\n {{- fail \"Cannot set both auth0.m2mClientSecret and auth0.m2mClientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.auth0.managementApiToken .Values.auth0.managementApiTokenExistingSecret }}\n {{- fail \"Cannot set both auth0.managementApiToken and auth0.managementApiTokenExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if not .Values.app.existingSecret }}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $domain := .Values.global.domain | default \"localhost\" }}\n{{- $protocol := ternary \"https\" \"http\" .Values.global.ingress.tls }}\n{{- $authServerPath := .Values.global.ingress.paths.authServer | default \"/auth-server\" }}\n{{- $registryPath := .Values.global.ingress.paths.registry | default \"/registry\" }}\n{{- $keycloakPath := .Values.global.ingress.paths.keycloak | default \"/keycloak\" }}\n{{- $authServerExternalUrl := \"\" }}\n{{- $keycloakExternalUrl := \"\" }}\n{{- $keycloakUrl := printf \"http://%s-keycloak-headless.%s.svc.cluster.local:8080\" .Release.Name .Release.Namespace}}\n{{- $rootPath := \"\" }}\n{{- $registryRootPath := \"\" }}\n{{- /* Determine auth provider type - prefer global, fallback to local, default to keycloak */ -}}\n{{- $authProviderType := .Values.authProvider.type | default \"keycloak\" }}\n{{- if .Values.global.authProvider }}\n {{- $authProviderType = .Values.global.authProvider.type | default $authProviderType }}\n{{- end }}\n{{- if eq $routingMode \"path\" }}\n {{- $authServerExternalUrl = printf \"%s://%s%s\" $protocol $domain $authServerPath }}\n {{- $keycloakExternalUrl = printf \"%s://%s%s\" $protocol $domain $keycloakPath }}\n {{- $keycloakUrl = printf \"%s%s\" $keycloakUrl $keycloakPath }}\n {{- $rootPath = $authServerPath }}\n {{- $registryRootPath = $registryPath }}\n{{- else }}\n {{- $authServerExternalUrl = printf \"%s://auth-server.%s\" $protocol $domain }}\n {{- $keycloakExternalUrl = printf \"%s://keycloak.%s\" $protocol $domain }}\n{{- end }}\n{{- /* Auto-generate federation tokens if not provided */ -}}\n{{- /* Resolve federation values - prefer global, fallback to local app values */ -}}\n{{- $federationEnabled := .Values.app.federationStaticTokenAuthEnabled | default false }}\n{{- if .Values.global.federation }}\n {{- $federationEnabled = .Values.global.federation.staticTokenAuthEnabled | default $federationEnabled }}\n{{- end }}\n{{- $federationStaticTokenRaw := .Values.app.federationStaticToken }}\n{{- $federationEncryptionKeyRaw := .Values.app.federationEncryptionKey }}\n{{- $registryId := .Values.app.registryId }}\n{{- if .Values.global.federation }}\n {{- $federationStaticTokenRaw = .Values.global.federation.staticToken | default $federationStaticTokenRaw }}\n {{- $federationEncryptionKeyRaw = .Values.global.federation.encryptionKey | default $federationEncryptionKeyRaw }}\n {{- $registryId = .Values.global.federation.registryId | default $registryId }}\n{{- end }}\n{{- /* Generate URL-safe token (equivalent to secrets.token_urlsafe(32)) */ -}}\n{{- $federationStaticToken := $federationStaticTokenRaw | default (randBytes 32 | replace \"+\" \"-\" | replace \"/\" \"_\" | trimSuffix \"=\") }}\n{{- /* Generate Fernet-compatible key (32 random bytes, base64-encoded) */ -}}\n{{- $federationEncryptionKey := $federationEncryptionKeyRaw | default (randBytes 32) }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: {{ .Values.app.envSecretName }}\n namespace: {{ .Release.Namespace | quote }}\ndata:\n AUTH_SERVER_EXTERNAL_URL: {{ $authServerExternalUrl | b64enc | quote }}\n REGISTRY_URL: {{ printf \"http://registry.%s.svc.cluster.local:8000\" .Release.Namespace | b64enc | quote }}\n{{- if not .Values.global.oauthProviderSecretName }}\n {{/* OAuth provider vars managed per-chart in standalone deployment */}}\n AUTH_PROVIDER: {{ $authProviderType | b64enc | quote }}\n {{- if eq $authProviderType \"keycloak\" }}\n KEYCLOAK_ENABLED: {{ .Values.keycloak.enabled | toString | b64enc | quote }}\n KEYCLOAK_EXTERNAL_URL: {{ $keycloakExternalUrl | b64enc | quote }}\n KEYCLOAK_REALM: {{ .Values.keycloak.realm | b64enc | quote }}\n KEYCLOAK_URL: {{ $keycloakUrl | b64enc | quote }}\n {{- if .Values.keycloak.m2mClientId }}\n KEYCLOAK_M2M_CLIENT_ID: {{ .Values.keycloak.m2mClientId | b64enc | quote }}\n {{- end }}\n {{- if .Values.keycloak.m2mClientSecret }}\n KEYCLOAK_M2M_CLIENT_SECRET: {{ .Values.keycloak.m2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"entra\" }}\n ENTRA_ENABLED: {{ \"true\" | b64enc | quote }}\n ENTRA_CLIENT_ID: {{ .Values.entra.clientId | b64enc | quote }}\n {{- if not .Values.entra.clientSecretExistingSecret }}\n ENTRA_CLIENT_SECRET: {{ .Values.entra.clientSecret | b64enc | quote }}\n {{- end }}\n ENTRA_TENANT_ID: {{ .Values.entra.tenantId | b64enc | quote }}\n {{- if .Values.entra.loginBaseUrl }}\n ENTRA_LOGIN_BASE_URL: {{ .Values.entra.loginBaseUrl | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"okta\" }}\n OKTA_ENABLED: {{ \"true\" | b64enc | quote }}\n OKTA_DOMAIN: {{ .Values.okta.domain | b64enc | quote }}\n OKTA_CLIENT_ID: {{ .Values.okta.clientId | b64enc | quote }}\n {{- if not .Values.okta.clientSecretExistingSecret }}\n OKTA_CLIENT_SECRET: {{ .Values.okta.clientSecret | b64enc | quote }}\n {{- end }}\n {{- if .Values.okta.m2mClientId }}\n OKTA_M2M_CLIENT_ID: {{ .Values.okta.m2mClientId | b64enc | quote }}\n {{- end }}\n {{- if and .Values.okta.m2mClientSecret (not .Values.okta.m2mClientSecretExistingSecret) }}\n OKTA_M2M_CLIENT_SECRET: {{ .Values.okta.m2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- if and .Values.okta.apiToken (not .Values.okta.apiTokenExistingSecret) }}\n OKTA_API_TOKEN: {{ .Values.okta.apiToken | b64enc | quote }}\n {{- end }}\n {{- if .Values.okta.authServerId }}\n OKTA_AUTH_SERVER_ID: {{ .Values.okta.authServerId | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"auth0\" }}\n AUTH0_ENABLED: {{ \"true\" | b64enc | quote }}\n AUTH0_DOMAIN: {{ .Values.auth0.domain | b64enc | quote }}\n AUTH0_CLIENT_ID: {{ .Values.auth0.clientId | b64enc | quote }}\n {{- if not .Values.auth0.clientSecretExistingSecret }}\n AUTH0_CLIENT_SECRET: {{ .Values.auth0.clientSecret | b64enc | quote }}\n {{- end }}\n {{- if .Values.auth0.audience }}\n AUTH0_AUDIENCE: {{ .Values.auth0.audience | b64enc | quote }}\n {{- end }}\n AUTH0_GROUPS_CLAIM: {{ .Values.auth0.groupsClaim | b64enc | quote }}\n {{- if .Values.auth0.m2mClientId }}\n AUTH0_M2M_CLIENT_ID: {{ .Values.auth0.m2mClientId | b64enc | quote }}\n {{- end }}\n {{- if and .Values.auth0.m2mClientSecret (not .Values.auth0.m2mClientSecretExistingSecret) }}\n AUTH0_M2M_CLIENT_SECRET: {{ .Values.auth0.m2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- if and .Values.auth0.managementApiToken (not .Values.auth0.managementApiTokenExistingSecret) }}\n AUTH0_MANAGEMENT_API_TOKEN: {{ .Values.auth0.managementApiToken | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"cognito\" }}\n COGNITO_ENABLED: {{ \"true\" | b64enc | quote }}\n COGNITO_USER_POOL_ID: {{ required \"cognito.userPoolId is required when authProvider.type is cognito\" .Values.cognito.userPoolId | b64enc | quote }}\n COGNITO_CLIENT_ID: {{ required \"cognito.clientId is required when authProvider.type is cognito\" .Values.cognito.clientId | b64enc | quote }}\n COGNITO_CLIENT_SECRET: {{ required \"cognito.clientSecret is required when authProvider.type is cognito\" .Values.cognito.clientSecret | b64enc | quote }}\n {{- if .Values.cognito.domain }}\n COGNITO_DOMAIN: {{ .Values.cognito.domain | b64enc | quote }}\n {{- end }}\n {{- if .Values.cognito.region }}\n AWS_REGION: {{ .Values.cognito.region | b64enc | quote }}\n {{- end }}\n {{- end }}\n{{- end }}\n ROOT_PATH: {{ $rootPath | b64enc | quote }}\n REGISTRY_ROOT_PATH: {{ $registryRootPath | b64enc | quote }}\n JWT_ISSUER: {{ (.Values.app.jwtIssuer | default \"mcp-auth-server\") | b64enc | quote }}\n JWT_AUDIENCE: {{ (.Values.app.jwtAudience | default \"mcp-registry\") | b64enc | quote }}\n {{- if .Values.app.registryStaticTokenAuthEnabled }}\n REGISTRY_STATIC_TOKEN_AUTH_ENABLED: {{ \"true\" | b64enc | quote }}\n REGISTRY_API_TOKEN: {{ required \"app.registryApiToken is required when registryStaticTokenAuthEnabled is true\" .Values.app.registryApiToken | b64enc | quote }}\n {{- end }}\n MAX_TOKENS_PER_USER_PER_HOUR: {{ (.Values.app.maxTokensPerUserPerHour | default \"100\") | toString | b64enc | quote }}\n OAUTH_STORE_TOKENS_IN_SESSION: {{ .Values.app.oauthStoreTokensInSession | toString | b64enc | quote }}\n SESSION_COOKIE_SECURE: {{ .Values.app.sessionCookieSecure | toString | b64enc | quote }}\n SESSION_COOKIE_DOMAIN: {{ printf \".%s\" $domain | b64enc | quote }}\n{{- if not .Values.global.sharedSecretName }}\n {{/* Federation and SECRET_KEY managed per-chart in standalone deployment */}}\n {{- if $federationEnabled }}\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED: {{ $federationEnabled | toString | b64enc | quote }}\n FEDERATION_STATIC_TOKEN: {{ $federationStaticToken | b64enc | quote }}\n FEDERATION_ENCRYPTION_KEY: {{ $federationEncryptionKey | b64enc | quote }}\n {{- end }}\n {{- if $registryId }}\n REGISTRY_ID: {{ $registryId | b64enc | quote }}\n {{- end }}\n {{/* SECRET_KEY required for standalone deployment - must match registry's key */}}\n SECRET_KEY: {{ required \"app.secretKey or global.secretKey is required for standalone deployment\" (.Values.global.secretKey | default .Values.app.secretKey) | b64enc | quote }}\n{{- end }}\n{{- end }}\n" }, { "path": "charts/auth-server/templates/service.yaml", "content": "apiVersion: v1\nkind: Service\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n {{- with .Values.service.annotations }}\n annotations:\n {{- toYaml . | nindent 4 }}\n {{- end }}\nspec:\n type: {{ .Values.service.type }}\n ports:\n - port: {{ .Values.service.port }}\n targetPort: http\n protocol: TCP\n name: http\n selector:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n" }, { "path": "charts/auth-server/values.yaml", "content": "# Global configuration\nglobal:\n image:\n repository: public.ecr.aws/p3v1o3c6/auth-server\n tag: 1.0.21\n pullPolicy: IfNotPresent\n\n# Application configuration\napp:\n name: auth-server\n replicas: 1\n envSecretName: auth-server-secret\n existingSecret: \"\" # If set, use this existing secret instead of creating one\n\n # External URLs\n externalUrl: http://localhost:8888\n\n # Security settings\n # secretKey: If not provided, a random 64-character key is auto-generated.\n # When deployed via mcp-gateway-registry-stack, the key is shared with registry.\n # Uncomment to use a specific key:\n # secretKey: \"your-secure-key-here\"\n sessionCookieDomain: \"\" # Auto-inferred from Host header if empty\n sessionCookieSecure: true\n oauthStoreTokensInSession: false # Store OAuth tokens in session (default: false)\n\n # Internal JWT configuration for service-to-service tokens\n jwtIssuer: \"mcp-auth-server\" # Issuer claim for internal JWT tokens\n jwtAudience: \"mcp-registry\" # Audience claim for internal JWT tokens\n\n # Static token authentication (alternative to IdP JWT for Registry API)\n registryStaticTokenAuthEnabled: false # Enable static API key auth for Registry API\n registryApiToken: \"\" # Static API key value (required when registryStaticTokenAuthEnabled is true)\n\n # Rate limiting\n maxTokensPerUserPerHour: \"100\" # Max token generations per user per hour\n\n # Federation configuration\n federationStaticTokenAuthEnabled: false #If not provided, defaults to false\n federationStaticToken: # If not provided, a random token is auto-generated\n federationEncryptionKey: # If not provided, a Fernet key is auto-generated\n registryId: # Unique identifier for this registry instance (optional)\n\n # Application Log Configuration (centralized log rotation and retrieval)\n appLogMaxBytes: \"52428800\" # Max size per log file before rotation (default 50 MB)\n appLogBackupCount: \"5\" # Number of rotated backup log files to keep\n appLogCentralizedEnabled: \"true\" # Write application logs to centralized store (requires MongoDB backend)\n appLogCentralizedTtlDays: \"1\" # Days to retain log entries in centralized store (TTL index)\n appLogMongodbBufferSize: \"50\" # Records to buffer before flushing to MongoDB\n appLogMongodbFlushIntervalSeconds: \"5.0\" # Seconds between periodic flushes\n appLogLevel: \"INFO\" # Application log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n appLogExcludedLoggers: \"uvicorn.access,httpx,pymongo,motor\" # Comma-separated logger names to exclude from MongoDB\n\n# Authentication Provider Configuration\n# Choose ONE provider: keycloak, entra, okta, auth0, or cognito\nauthProvider:\n # Provider type: \"keycloak\", \"entra\", \"okta\", \"auth0\", or \"cognito\"\n type: keycloak\n\n# Keycloak integration (used when authProvider.type = \"keycloak\")\nkeycloak:\n enabled: true\n externalUrl: http://localhost:8080\n realm: mcp-gateway\n m2mClientId: \"\" # Optional: M2M client ID for machine-to-machine authentication\n m2mClientSecret: \"\" # Optional: M2M client secret\n\n# Entra ID integration (used when authProvider.type = \"entra\")\nentra:\n clientId: \"\"\n clientSecret: \"\"\n clientSecretExistingSecret: \"\" # If set, read ENTRA_CLIENT_SECRET from this K8s secret instead of clientSecret\n clientSecretExistingSecretKey: \"ENTRA_CLIENT_SECRET\" # Key within the existing secret\n tenantId: \"\"\n loginBaseUrl: \"\" # Custom Entra login base URL for sovereign/national clouds (default: https://login.microsoftonline.com)\n\n# Okta integration (used when authProvider.type = \"okta\")\nokta:\n domain: \"\" # e.g., dev-123456.okta.com\n clientId: \"\"\n clientSecret: \"\"\n clientSecretExistingSecret: \"\" # If set, read OKTA_CLIENT_SECRET from this K8s secret\n clientSecretExistingSecretKey: \"OKTA_CLIENT_SECRET\"\n m2mClientId: \"\" # Optional: defaults to clientId\n m2mClientSecret: \"\" # Optional: defaults to clientSecret\n m2mClientSecretExistingSecret: \"\" # If set, read OKTA_M2M_CLIENT_SECRET from this K8s secret\n m2mClientSecretExistingSecretKey: \"OKTA_M2M_CLIENT_SECRET\"\n apiToken: \"\" # Optional: required for IAM operations\n apiTokenExistingSecret: \"\" # If set, read OKTA_API_TOKEN from this K8s secret\n apiTokenExistingSecretKey: \"OKTA_API_TOKEN\"\n authServerId: \"\" # Optional: uses default Org Authorization Server if not set\n\n# Auth0 integration (used when authProvider.type = \"auth0\")\nauth0:\n domain: \"\" # e.g., your-tenant.us.auth0.com\n clientId: \"\"\n clientSecret: \"\"\n clientSecretExistingSecret: \"\" # If set, read AUTH0_CLIENT_SECRET from this K8s secret\n clientSecretExistingSecretKey: \"AUTH0_CLIENT_SECRET\"\n audience: \"\" # Optional: API audience for M2M tokens\n groupsClaim: \"https://mcp-gateway/groups\" # Custom namespaced claim for groups\n m2mClientId: \"\" # Required for IAM Management (user/role administration)\n m2mClientSecret: \"\" # Required for IAM Management\n m2mClientSecretExistingSecret: \"\" # If set, read AUTH0_M2M_CLIENT_SECRET from this K8s secret\n m2mClientSecretExistingSecretKey: \"AUTH0_M2M_CLIENT_SECRET\"\n managementApiToken: \"\" # Optional: alternative to M2M credentials (expires after 24h)\n managementApiTokenExistingSecret: \"\" # If set, read AUTH0_MANAGEMENT_API_TOKEN from this K8s secret\n managementApiTokenExistingSecretKey: \"AUTH0_MANAGEMENT_API_TOKEN\"\n\n# Cognito integration (used when authProvider.type = \"cognito\")\ncognito:\n userPoolId: \"\" # Cognito User Pool ID\n clientId: \"\"\n clientSecret: \"\"\n domain: \"\" # Optional: custom Cognito domain\n region: \"us-east-1\" # AWS region for the User Pool\n\n# Service configuration\nservice:\n type: ClusterIP\n port: 8888\n annotations: { }\n\n# Resource limits and requests\nresources:\n requests:\n cpu: 1\n memory: 1Gi\n limits:\n cpu: 2\n memory: 2Gi\n\n# Ingress configuration\ningress:\n enabled: false\n className: alb\n hostname: \"\"\n annotations: { }\n tls: false\n # Routing mode: \"subdomain\" or \"path\"\n # - subdomain: auth-server.domain.com\n # - path: domain.com/auth-server (configurable via path setting)\n routingMode: subdomain\n # Path prefix when using path-based routing (default: /auth-server)\n path: /auth-server\n\nnodeSelector: {}\n" }, { "path": "charts/keycloak-configure/Chart.yaml", "content": "apiVersion: v2\nname: keycloak-configure\ndescription: A Helm chart for configuring Keycloak\ntype: application\nversion: 0.1.0\nappVersion: \"1.0.0\"\n" }, { "path": "charts/keycloak-configure/templates/configmap.yaml", "content": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: setup-keycloak\n namespace: {{ .Release.Namespace | quote }}\ndata:\n script.sh: |\n #!/bin/bash\n apt update\n apt install -y curl jq kubectl\n\n # Initialize Keycloak with MCP Gateway configuration\n # This script sets up the initial realm, clients, groups, and users\n\n set -e\n\n # These will be set properly after loading .env in main()\n KEYCLOAK_URL=\"\" # Will be overridden with KEYCLOAK_ADMIN_URL after .env is loaded\n REALM=\"mcp-gateway\"\n KEYCLOAK_ADMIN=$KEYCLOAK_ADMIN\n KEYCLOAK_ADMIN_PASSWORD=$KEYCLOAK_ADMIN_PASSWORD\n\n # Colors for output\n RED='\\033[0;31m'\n GREEN='\\033[0;32m'\n YELLOW='\\033[1;33m'\n NC='\\033[0m' # No Color\n\n echo -e \"${YELLOW}Keycloak initialization script for MCP Gateway Registry${NC}\"\n echo \"==============================================\"\n\n # Function to wait for Keycloak to be ready\n wait_for_keycloak() {\n echo -n \"Waiting for Keycloak to be ready...\"\n local max_attempts=60\n local attempt=0\n\n while [ $attempt -lt $max_attempts ]; do\n # Try to access the admin console which indicates Keycloak is ready\n if curl -f -s \"${KEYCLOAK_URL}/admin/\" > /dev/null 2>&1; then\n echo -e \" ${GREEN}Ready!${NC}\"\n return 0\n fi\n echo -n \".\"\n sleep 5\n attempt=$((attempt + 1))\n done\n\n echo -e \" ${RED}Timeout!${NC}\"\n echo \"Keycloak did not become ready within 5 minutes\"\n exit 1\n }\n\n # Function to get admin token\n get_admin_token() {\n local response=$(curl -s -X POST \"${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\")\n\n echo \"$response\" | grep -o '\"access_token\":\"[^\"]*' | cut -d'\"' -f4\n }\n\n # Function to check if realm exists\n realm_exists() {\n local token=$1\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}\")\n\n [ \"$response\" = \"200\" ]\n }\n\n # Function to create realm step by step\n create_realm() {\n local token=$1\n\n echo \"Creating MCP Gateway realm...\"\n\n # Check if realm already exists\n if realm_exists \"$token\"; then\n echo -e \"${YELLOW}Realm already exists. Skipping creation...${NC}\"\n return 0\n fi\n\n # Create basic realm\n local realm_json='{\n \"realm\": \"mcp-gateway\",\n \"enabled\": true,\n \"registrationAllowed\": false,\n \"loginWithEmailAllowed\": true,\n \"duplicateEmailsAllowed\": false,\n \"resetPasswordAllowed\": true,\n \"editUsernameAllowed\": false,\n \"sslRequired\": \"none\"\n }'\n\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$realm_json\")\n\n if [ \"$response\" = \"201\" ]; then\n echo -e \"${GREEN}Realm created successfully!${NC}\"\n return 0\n elif [ \"$response\" = \"409\" ]; then\n echo -e \"${YELLOW}Realm already exists. Continuing...${NC}\"\n return 0\n else\n echo -e \"${RED}Failed to create realm. HTTP status: ${response}${NC}\"\n echo \"Response body:\"\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$realm_json\"\n echo \"\"\n return 1\n fi\n }\n\n # Function to create clients\n create_clients() {\n local token=$1\n\n echo \"Creating OAuth2 clients...\"\n\n # Create web client\n local web_client_json='{\n \"clientId\": \"mcp-gateway-web\",\n \"name\": \"MCP Gateway Web Client\",\n \"enabled\": true,\n \"clientAuthenticatorType\": \"client-secret\",\n \"redirectUris\": [\n \"'${AUTH_SERVER_EXTERNAL_URL:-http://localhost:8888}'/oauth2/callback/keycloak\",\n \"'${REGISTRY_URL:-http://localhost:7860}'/*\",\n \"http://localhost:7860/*\",\n \"http://localhost:8888/*\"\n ],\n \"webOrigins\": [\n \"'${REGISTRY_URL:-http://localhost:7860}'\",\n \"http://localhost:7860\",\n \"+\"\n ],\n \"protocol\": \"openid-connect\",\n \"standardFlowEnabled\": true,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": true,\n \"serviceAccountsEnabled\": false,\n \"publicClient\": false\n }'\n\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$web_client_json\" > /dev/null\n\n # Create M2M client\n local m2m_client_json='{\n \"clientId\": \"mcp-gateway-m2m\",\n \"name\": \"MCP Gateway M2M Client\",\n \"enabled\": true,\n \"clientAuthenticatorType\": \"client-secret\",\n \"protocol\": \"openid-connect\",\n \"standardFlowEnabled\": false,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": false,\n \"serviceAccountsEnabled\": true,\n \"publicClient\": false\n }'\n\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$m2m_client_json\" > /dev/null\n\n echo -e \"${GREEN}Clients created successfully!${NC}\"\n }\n\n # Function to create groups\n create_groups() {\n local token=$1\n\n echo \"Creating user groups...\"\n\n local groups=(\"mcp-registry-admin\" \"mcp-registry-user\" \"mcp-registry-developer\" \"mcp-registry-operator\" \"mcp-servers-unrestricted\" \"mcp-servers-restricted\" \"a2a-agent-admin\" \"a2a-agent-publisher\" \"a2a-agent-user\")\n\n for group in \"${groups[@]}\"; do\n local group_json='{\n \"name\": \"'$group'\",\n \"attributes\": {\n \"description\": [\"'$group' group for MCP Gateway access\"]\n }\n }'\n\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/mcp-gateway/groups\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$group_json\" > /dev/null\n done\n\n echo -e \"${GREEN}Groups created successfully!${NC}\"\n }\n\n # Function to create custom scopes\n create_scopes() {\n local token=$1\n\n echo \"Creating custom MCP scopes...\"\n\n local scopes=(\"mcp-servers-unrestricted/read\" \"mcp-servers-unrestricted/execute\" \"mcp-servers-restricted/read\" \"mcp-servers-restricted/execute\")\n\n for scope in \"${scopes[@]}\"; do\n local scope_json='{\n \"name\": \"'$scope'\",\n \"description\": \"MCP Gateway scope for '$scope' access\",\n \"protocol\": \"openid-connect\"\n }'\n\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/client-scopes\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$scope_json\")\n\n if [ \"$response\" = \"201\" ]; then\n echo \" - Created scope: $scope\"\n elif [ \"$response\" = \"409\" ]; then\n echo \" - Scope already exists: $scope\"\n else\n echo -e \"${RED} - Failed to create scope: $scope (HTTP $response)${NC}\"\n fi\n done\n\n echo -e \"${GREEN}Custom scopes created successfully!${NC}\"\n }\n\n # Function to assign scopes to M2M client\n setup_m2m_scopes() {\n local token=$1\n\n echo \"Setting up M2M client scopes...\"\n\n # Get M2M client ID\n local m2m_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-m2m\" | \\\n jq -r '.[0].id')\n\n if [ -z \"$m2m_client_id\" ] || [ \"$m2m_client_id\" = \"null\" ]; then\n echo -e \"${RED}Error: Could not find mcp-gateway-m2m client${NC}\"\n return 1\n fi\n\n # Get all available client scopes\n local scopes=(\"mcp-servers-unrestricted/read\" \"mcp-servers-unrestricted/execute\" \"mcp-servers-restricted/read\" \"mcp-servers-restricted/execute\")\n\n for scope in \"${scopes[@]}\"; do\n # Get scope ID\n local scope_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/client-scopes\" | \\\n jq -r '.[] | select(.name==\"'$scope'\") | .id')\n\n if [ ! -z \"$scope_id\" ] && [ \"$scope_id\" != \"null\" ]; then\n # Add scope as default client scope\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/default-client-scopes/${scope_id}\" \\\n -H \"Authorization: Bearer ${token}\")\n\n if [ \"$response\" = \"204\" ]; then\n echo \" - Assigned scope: $scope\"\n else\n echo -e \"${YELLOW} - Warning: Could not assign scope $scope (HTTP $response)${NC}\"\n fi\n else\n echo -e \"${RED} - Error: Could not find scope: $scope${NC}\"\n fi\n done\n\n echo -e \"${GREEN}M2M client scopes configured successfully!${NC}\"\n }\n\n # Function to create service account user for M2M client\n create_service_account_user() {\n local token=$1\n local service_account_username=\"service-account-mcp-gateway-m2m\"\n\n echo \"Creating service account user: $service_account_username\"\n\n # Check if user already exists\n local existing_user=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$service_account_username\" | \\\n jq -r '.[0].id // empty')\n\n if [ ! -z \"$existing_user\" ]; then\n echo -e \"${YELLOW}Service account user already exists with ID: $existing_user${NC}\"\n return 0\n fi\n\n # Create service account user\n local user_json='{\n \"username\": \"'$service_account_username'\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"serviceAccountClientId\": \"mcp-gateway-m2m\"\n }'\n\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/users\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$user_json\")\n\n if [ \"$response\" = \"201\" ]; then\n echo -e \"${GREEN}Service account user created successfully!${NC}\"\n\n # Get the newly created user ID\n local user_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$service_account_username\" | \\\n jq -r '.[0].id')\n\n echo \"Created service account user with ID: $user_id\"\n\n # Assign user to mcp-servers-unrestricted group\n local group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-servers-unrestricted\") | .id')\n\n if [ ! -z \"$group_id\" ] && [ \"$group_id\" != \"null\" ]; then\n local group_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$user_id/groups/$group_id\" \\\n -H \"Authorization: Bearer ${token}\")\n\n if [ \"$group_response\" = \"204\" ]; then\n echo -e \"${GREEN}Service account assigned to mcp-servers-unrestricted group!${NC}\"\n else\n echo -e \"${YELLOW}Warning: Could not assign service account to mcp-servers-unrestricted group (HTTP $group_response)${NC}\"\n fi\n else\n echo -e \"${RED}Error: Could not find mcp-servers-unrestricted group${NC}\"\n fi\n\n # Assign user to a2a-agent-admin group for A2A agent access\n local a2a_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"a2a-agent-admin\") | .id')\n\n if [ ! -z \"$a2a_group_id\" ] && [ \"$a2a_group_id\" != \"null\" ]; then\n local a2a_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$user_id/groups/$a2a_group_id\" \\\n -H \"Authorization: Bearer ${token}\")\n\n if [ \"$a2a_response\" = \"204\" ]; then\n echo -e \"${GREEN}Service account assigned to a2a-agent-admin group!${NC}\"\n else\n echo -e \"${YELLOW}Warning: Could not assign service account to a2a-agent-admin group (HTTP $a2a_response)${NC}\"\n fi\n else\n echo -e \"${YELLOW}Warning: a2a-agent-admin group not found. Create it manually if A2A agent support is needed.${NC}\"\n fi\n\n return 0\n elif [ \"$response\" = \"409\" ]; then\n echo -e \"${YELLOW}Service account user already exists. Continuing...${NC}\"\n return 0\n else\n echo -e \"${RED}Failed to create service account user. HTTP status: ${response}${NC}\"\n return 1\n fi\n }\n\n # Function to create test users\n create_users() {\n local token=$1\n\n echo \"Creating test users...\"\n\n # Define usernames for consistency\n local admin_username=\"admin\"\n local test_username=\"testuser\"\n\n # Create admin user\n local admin_user_json='{\n \"username\": \"'$admin_username'\",\n \"email\": \"'$admin_username'@example.com\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"firstName\": \"Admin\",\n \"lastName\": \"User\",\n \"credentials\": [\n {\n \"type\": \"password\",\n \"value\": \"'${INITIAL_ADMIN_PASSWORD}'\",\n \"temporary\": false\n }\n ]\n }'\n\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/users\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$admin_user_json\" > /dev/null\n\n # Create test user\n local test_user_json='{\n \"username\": \"'$test_username'\",\n \"email\": \"'$test_username'@example.com\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"firstName\": \"Test\",\n \"lastName\": \"User\",\n \"credentials\": [\n {\n \"type\": \"password\",\n \"value\": \"'${INITIAL_USER_PASSWORD}'\",\n \"temporary\": false\n }\n ]\n }'\n\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/users\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$test_user_json\" > /dev/null\n\n echo \"Assigning users to groups...\"\n\n # Get user IDs\n local admin_user_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$admin_username\" | \\\n jq -r '.[0].id')\n\n local test_user_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$test_username\" | \\\n jq -r '.[0].id')\n\n # Get all group IDs\n local admin_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-admin\") | .id')\n\n local user_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-user\") | .id')\n\n local developer_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-developer\") | .id')\n\n local operator_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-operator\") | .id')\n\n local unrestricted_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-servers-unrestricted\") | .id')\n\n local restricted_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-servers-restricted\") | .id')\n\n # Define usernames for consistent logging\n local admin_username=\"admin\"\n local test_username=\"testuser\"\n\n # Assign admin user to admin group and unrestricted servers group\n if [ ! -z \"$admin_user_id\" ] && [ ! -z \"$admin_group_id\" ]; then\n curl -s -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$admin_user_id/groups/$admin_group_id\" \\\n -H \"Authorization: Bearer ${token}\" > /dev/null\n echo \" - $admin_username assigned to mcp-registry-admin group\"\n fi\n\n # Also assign admin to unrestricted servers group for full access\n if [ ! -z \"$admin_user_id\" ] && [ ! -z \"$unrestricted_group_id\" ]; then\n curl -s -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$admin_user_id/groups/$unrestricted_group_id\" \\\n -H \"Authorization: Bearer ${token}\" > /dev/null\n echo \" - $admin_username assigned to mcp-servers-unrestricted group\"\n fi\n\n # Assign test user to all groups except admin\n if [ ! -z \"$test_user_id\" ]; then\n # Arrays of group IDs and names for loop processing\n local group_ids=(\"$user_group_id\" \"$developer_group_id\" \"$operator_group_id\" \"$unrestricted_group_id\" \"$restricted_group_id\")\n local group_names=(\"mcp-registry-user\" \"mcp-registry-developer\" \"mcp-registry-operator\" \"mcp-servers-unrestricted\" \"mcp-servers-restricted\")\n\n # Loop through groups and assign test user to each\n for i in \"${!group_ids[@]}\"; do\n local group_id=\"${group_ids[$i]}\"\n local group_name=\"${group_names[$i]}\"\n\n if [ ! -z \"$group_id\" ]; then\n curl -s -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$test_user_id/groups/$group_id\" \\\n -H \"Authorization: Bearer ${token}\" > /dev/null\n echo \" - $test_username assigned to $group_name group\"\n fi\n done\n fi\n\n echo -e \"${GREEN}Users created and assigned to groups successfully!${NC}\"\n }\n\n # Function to create client secrets\n setup_client_secrets() {\n local token=$1\n\n echo \"Setting up client secrets...\"\n\n # Get web client ID\n local web_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-web\" | \\\n jq -r '.[0].id')\n\n # Generate secret for web client\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${web_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" > /dev/null\n\n local web_secret_response=$(curl -s \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${web_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\")\n web_secret=$(echo \"$web_secret_response\" | jq -r '.value // empty')\n\n # Get M2M client ID\n local m2m_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-m2m\" | \\\n jq -r '.[0].id')\n\n # Generate secret for M2M client\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" > /dev/null\n\n local m2m_secret_response=$(curl -s \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\")\n m2m_secret=$(echo \"$m2m_secret_response\" | jq -r '.value // empty')\n\n echo -e \"${GREEN}Client secrets generated!${NC}\"\n echo \"\"\n echo \"==============================================\"\n echo -e \"${YELLOW}Client credentials have been created.${NC}\"\n echo \"==============================================\"\n echo \"\"\n echo -e \"${GREEN}To retrieve all client credentials, run:${NC}\"\n echo \" ./keycloak/setup/get-all-client-credentials.sh\"\n echo \"\"\n echo \"This will save all credentials to .oauth-tokens/\"\n echo \"==============================================\"\n\n kubectl create secret generic keycloak-client-secret --from-literal=KEYCLOAK_CLIENT_ID=mcp-gateway-web --from-literal=KEYCLOAK_CLIENT_SECRET=$web_secret --from-literal=KEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m --from-literal=KEYCLOAK_M2M_CLIENT_SECRET=$m2m_secret\n }\n\n # Function to setup groups mapper for OAuth2 clients\n setup_groups_mapper() {\n local token=$1\n\n echo \"Setting up groups mapper for OAuth2 clients...\"\n\n # Create groups mapper JSON\n local groups_mapper_json='{\n \"name\": \"groups\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-group-membership-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"full.path\": \"false\",\n \"id.token.claim\": \"true\",\n \"access.token.claim\": \"true\",\n \"claim.name\": \"groups\",\n \"userinfo.token.claim\": \"true\"\n }\n }'\n\n # Setup groups mapper for mcp-gateway-web client\n echo \"Setting up groups mapper for mcp-gateway-web client...\"\n local web_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-web\" | \\\n jq -r '.[0].id')\n\n if [ -z \"$web_client_id\" ] || [ \"$web_client_id\" = \"null\" ]; then\n echo -e \"${RED}Error: Could not find mcp-gateway-web client${NC}\"\n return 1\n fi\n\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${web_client_id}/protocol-mappers/models\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$groups_mapper_json\")\n\n if [ \"$response\" = \"201\" ]; then\n echo -e \"${GREEN}Groups mapper created for mcp-gateway-web!${NC}\"\n elif [ \"$response\" = \"409\" ]; then\n echo -e \"${YELLOW}Groups mapper already exists for mcp-gateway-web. Continuing...${NC}\"\n else\n echo -e \"${RED}Failed to create groups mapper for mcp-gateway-web. HTTP status: ${response}${NC}\"\n return 1\n fi\n\n # Setup groups mapper for mcp-gateway-m2m client\n echo \"Setting up groups mapper for mcp-gateway-m2m client...\"\n local m2m_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-m2m\" | \\\n jq -r '.[0].id')\n\n if [ -z \"$m2m_client_id\" ] || [ \"$m2m_client_id\" = \"null\" ]; then\n echo -e \"${RED}Error: Could not find mcp-gateway-m2m client${NC}\"\n return 1\n fi\n\n local m2m_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/protocol-mappers/models\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$groups_mapper_json\")\n\n if [ \"$m2m_response\" = \"201\" ]; then\n echo -e \"${GREEN}Groups mapper created for mcp-gateway-m2m!${NC}\"\n elif [ \"$m2m_response\" = \"409\" ]; then\n echo -e \"${YELLOW}Groups mapper already exists for mcp-gateway-m2m. Continuing...${NC}\"\n else\n echo -e \"${RED}Failed to create groups mapper for mcp-gateway-m2m. HTTP status: ${m2m_response}${NC}\"\n return 1\n fi\n }\n\n # Function to generate random password\n generate_password() {\n # Generate a 16-character random password with alphanumeric characters\n openssl rand -base64 12 | tr -d \"=+/\" | cut -c1-16\n }\n\n # Main execution\n main() {\n # Get script directory and find .env file\n SCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\n PROJECT_ROOT=\"$( cd \"$SCRIPT_DIR/../..\" && pwd )\"\n ENV_FILE=\"$PROJECT_ROOT/.env\"\n\n # Load environment variables from .env file if it exists\n if [ -f \"$ENV_FILE\" ]; then\n echo \"Loading environment variables from $ENV_FILE...\"\n set -a # Automatically export all variables\n source \"$ENV_FILE\"\n set +a # Turn off automatic export\n echo \"Environment variables loaded successfully\"\n else\n echo \"No .env file found at $ENV_FILE\"\n echo \"Current directory: $(pwd)\"\n echo \"Script directory: $SCRIPT_DIR\"\n echo \"Project root: $PROJECT_ROOT\"\n fi\n\n # Generate random passwords if not provided\n if [ -z \"$INITIAL_ADMIN_PASSWORD\" ]; then\n INITIAL_ADMIN_PASSWORD=$(generate_password)\n echo -e \"${YELLOW}Generated random admin password${NC}\"\n fi\n\n if [ -z \"$INITIAL_USER_PASSWORD\" ]; then\n INITIAL_USER_PASSWORD=$(generate_password)\n echo -e \"${YELLOW}Generated random user password${NC}\"\n fi\n\n # Store passwords in variables for later use\n export INITIAL_ADMIN_PASSWORD\n export INITIAL_USER_PASSWORD\n\n # Override KEYCLOAK_URL with KEYCLOAK_ADMIN_URL for API calls\n KEYCLOAK_URL=\"${KEYCLOAK_ADMIN_URL:-http://localhost:8080}\"\n KEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\n echo \"Using Keycloak API URL: $KEYCLOAK_URL\"\n\n # Check if admin password is set\n if [ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ]; then\n echo -e \"${RED}Error: KEYCLOAK_ADMIN_PASSWORD environment variable is not set${NC}\"\n echo \"Please set it in .env file or export it before running this script\"\n exit 1\n fi\n\n # Wait for Keycloak to be ready\n wait_for_keycloak\n\n # Get admin token\n echo \"Authenticating with Keycloak...\"\n TOKEN=$(get_admin_token)\n\n if [ -z \"$TOKEN\" ]; then\n echo -e \"${RED}Error: Failed to authenticate with Keycloak${NC}\"\n echo \"Please check your admin credentials\"\n exit 1\n fi\n\n echo -e \"${GREEN}Authentication successful!${NC}\"\n\n # Create realm and configure it step by step\n if create_realm \"$TOKEN\"; then\n create_clients \"$TOKEN\"\n create_scopes \"$TOKEN\"\n create_groups \"$TOKEN\"\n create_users \"$TOKEN\"\n create_service_account_user \"$TOKEN\"\n setup_client_secrets \"$TOKEN\"\n setup_groups_mapper \"$TOKEN\"\n setup_m2m_scopes \"$TOKEN\"\n else\n exit 1\n fi\n\n # Save generated passwords to a Kubernetes secret\n kubectl create secret generic registry-login-credentials --from-literal=REGISTRY_ADMIN_NAME=admin --from-literal=REGISTRY_ADMIN_PASSWORD=$INITIAL_ADMIN_PASSWORD --from-literal=REGISTRY_USER_NAME=testuser --from-literal=REGISTRY_USER_PASSWORD=$INITIAL_USER_PASSWORD\n\n echo \"\"\n echo -e \"${GREEN}Keycloak initialization complete!${NC}\"\n echo \"\"\n echo \"You can now access Keycloak at: ${KEYCLOAK_URL}\"\n echo \"Admin console: ${KEYCLOAK_URL}/admin\"\n echo \"Realm: ${REALM}\"\n echo \"\"\n echo \"Default users created:\"\n echo \" - admin/${INITIAL_ADMIN_PASSWORD} (admin access)\"\n echo \" - testuser/${INITIAL_USER_PASSWORD} (user access)\"\n echo \"\"\n echo -e \"${YELLOW}IMPORTANT: Save these passwords! They are randomly generated.${NC}\"\n echo -e \"${YELLOW}Passwords have been saved to the Kubernetes secret: registry-login-credentials${NC}\"\n echo -e \"${YELLOW}Consider changing them after first login for security.${NC}\"\n }\n\n # Run main function\n main\n\n" }, { "path": "charts/keycloak-configure/templates/job.yaml", "content": "apiVersion: batch/v1\nkind: Job\nmetadata:\n name: setup-keycloak\n namespace: {{ .Release.Namespace | quote }}\nspec:\n template:\n spec:\n containers:\n - name: job\n image: public.ecr.aws/docker/library/python:3.13-slim\n command: [\"/bin/bash\", \"/app/script.sh\"]\n envFrom:\n - secretRef:\n name: {{ .Values.keycloak.existingSecret | default \"keycloak-configure-secret\" }}\n env:\n - valueFrom:\n secretKeyRef:\n key: admin-password\n name: {{ .Release.Name}}-keycloak\n name: KEYCLOAK_ADMIN_PASSWORD\n volumeMounts:\n - mountPath: /app/script.sh\n name: script\n subPath: script.sh\n restartPolicy: Never\n volumes:\n - name: script\n configMap:\n name: setup-keycloak\n serviceAccountName: keycloak-configure-sa\n backoffLimit: 4\n" }, { "path": "charts/keycloak-configure/templates/role.yaml", "content": "apiVersion: rbac.authorization.k8s.io/v1\nkind: Role\nmetadata:\n name: secret-read-write\n namespace: {{ .Release.Namespace | quote }}\nrules:\n - apiGroups: [\"\"] # \"\" indicates the core API group\n resources: [\"secrets\"]\n verbs: [\"get\", \"watch\", \"list\", \"create\"]\n\n" }, { "path": "charts/keycloak-configure/templates/rolebinding.yaml", "content": "apiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\n name: secret-read-write\n namespace: {{ .Release.Namespace | quote }}\nsubjects:\n - kind: ServiceAccount\n name: keycloak-configure-sa # \"name\" is case sensitive\n apiGroup: \"\"\nroleRef:\n # \"roleRef\" specifies the binding to a Role / ClusterRole\n kind: Role #this must be Role or ClusterRole\n name: secret-read-write # this must match the name of the Role or ClusterRole you wish to bind to\n apiGroup: rbac.authorization.k8s.io\n\n" }, { "path": "charts/keycloak-configure/templates/sa.yaml", "content": "apiVersion: v1\nkind: ServiceAccount\nmetadata:\n name: keycloak-configure-sa\n namespace: {{ .Release.Namespace | quote }}\nautomountServiceAccountToken: true\n" }, { "path": "charts/keycloak-configure/templates/secret.yaml", "content": "{{- if not .Values.keycloak.existingSecret }}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $domain := .Values.global.domain | default \"localhost\" }}\n{{- $protocol := ternary \"https\" \"http\" .Values.global.ingress.tls }}\n{{- $authServerPath := .Values.global.ingress.paths.authServer | default \"/auth-server\" }}\n{{- $keycloakPath := .Values.global.ingress.paths.keycloak | default \"/keycloak\" }}\n{{- $keycloakBaseUrl := printf \"http://%s-keycloak-headless.%s.svc.cluster.local:8080\" .Release.Name .Release.Namespace }}\n{{- $keycloakUrl := $keycloakBaseUrl }}\n{{- $authServerExternalUrl := \"\" }}\n{{- if eq $routingMode \"path\" }}\n {{- $keycloakUrl = printf \"%s%s\" $keycloakBaseUrl $keycloakPath }}\n {{- $authServerExternalUrl = printf \"%s://%s%s\" $protocol $domain $authServerPath }}\n{{- else }}\n {{- $authServerExternalUrl = printf \"%s://auth-server.%s\" $protocol $domain }}\n{{- end }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: keycloak-configure-secret\n namespace: {{ .Release.Namespace | quote }}\ndata:\n KEYCLOAK_ADMIN: {{ .Values.keycloak.adminUser | b64enc | quote }}\n KEYCLOAK_ADMIN_URL: {{ $keycloakUrl | b64enc | quote }}\n KEYCLOAK_URL: {{ $keycloakUrl | b64enc | quote }}\n REALM: {{ .Values.keycloak.realm | b64enc | quote }}\n AUTH_SERVER_EXTERNAL_URL: {{ $authServerExternalUrl | b64enc | quote }}\n{{- end }}\n" }, { "path": "charts/keycloak-configure/values.yaml", "content": "# Keycloak configuration\nkeycloak:\n adminUser: user\n realm: mcp-gateway\n existingSecret: \"\" # If set, use this existing secret instead of creating one\n\n# Auth server configuration\nauthServer:\n externalUrl: http://localhost:8888\n\n" }, { "path": "charts/mcp-gateway-registry-stack/Chart.yaml", "content": "apiVersion: v2\nname: mcp-gateway-registry-stack\ndescription: A Helm chart for deploying the MCP Gateway Registry Stack\ntype: application\nversion: 0.1.0\nappVersion: \"1.0.0\"\ndependencies:\n - name: keycloak\n version: 25.2.0\n repository: oci://registry-1.docker.io/bitnamicharts\n condition: keycloak.create\n - name: mongodb-kubernetes\n version: 1.6.1\n repository: https://mongodb.github.io/helm-charts\n condition: mongodb.enabled\n - name: auth-server\n version: 0.1.0\n repository: \"file://../auth-server\"\n - name: registry\n version: 0.1.0\n repository: \"file://../registry\"\n - name: mcpgw\n version: 0.1.0\n repository: \"file://../mcpgw\"\n condition: mcpgw.enabled\n - name: keycloak-configure\n version: 0.1.0\n repository: \"file://../keycloak-configure\"\n condition: keycloak-configure.enabled\n - name: mongodb-configure\n version: 0.1.0\n repository: \"file://../mongodb-configure\"\n condition: mongodb-configure.enabled\n" }, { "path": "charts/mcp-gateway-registry-stack/README.md", "content": "# MCP Gateway Registry Stack Charts\n\nThis collection of charts deploys everything needed to install the MCP Gateway Registry using Helm or ArgoCD.\n\n## Prerequisites\n\n### Amazon EKS Cluster\n\nFor production deployments, we recommend using the [AWS AI/ML on Amazon EKS](https://github.com/awslabs/ai-on-eks)\nblueprints to provision an EKS cluster:\n\n```bash\n# Clone AI on EKS repository\ngit clone https://github.com/awslabs/ai-on-eks.git\ncd ai-on-eks\n\ncd infra/solutions/agents-on-eks\n\n# Edit the terraform/blueprint.tfvars to set your domain\n\n./install.sh\n```\n\nThe ai-on-eks blueprints provide:\n\n- GPU support for AI/ML workloads\n- Karpenter for efficient auto-scaling\n- EKS-optimized configurations\n- Security best practices\n- Observability with Prometheus/Grafana\n- Well-documented infrastructure patterns\n\n### Additional Requirements\n\n- `helm` CLI installed (v3.0+)\n- `kubectl` configured to access your EKS cluster\n- AWS Load Balancer Controller for EKS\n- ExternalDNS (optional, for automatic DNS management)\n- Domain name with DNS access\n- TLS certificates (AWS Certificate Manager or Let's Encrypt)\n\n## Setup\n\n```\ngit clone https://github.com/agentic-community/mcp-gateway-registry\ncd mcp-gateway-registry/charts/mcp-gateway-registry-stack\n```\n\n## Values file\n\nThe `values.yaml` file needs to be updated for your setup, specifically:\n\n- `DOMAIN`: there are placeholders for `DOMAIN` that should be updated with your full domain. For example, if you intend\n to use `example.com`, replace `DOMAIN` with `example.com`. If you intend to use a subdomain like\n `subdomain.example.com`, `DOMAIN` should be replaced with `subdomain.example.com`\n- `secretKey`: the registry and auth-server both have a placeholder for `secretKey`, this should be updated to the same\n random, secure key that is used in both locations\n- `routingMode`: choose between `subdomain` (default) or `path` based routing (see Routing Modes section below)\n\n### Authentication Provider Selection\n\nThis chart supports five authentication providers: Keycloak (default), Microsoft Entra ID, Okta, Auth0, and AWS Cognito.\n\nWhen using any provider other than Keycloak, disable the Keycloak components:\n\n```yaml\nkeycloak:\n create: false\nkeycloak-configure:\n enabled: false\n```\n\n#### Option 1: Keycloak (Default)\n\n**Deploy Keycloak in the stack:**\n\n```yaml\nglobal:\n authProvider:\n type: keycloak\n\nkeycloak:\n create: true # Deploy Keycloak as part of this stack\n\nkeycloak-configure:\n enabled: true # Run Keycloak configuration job\n```\n\n**Use an external Keycloak instance:**\n\n```yaml\nglobal:\n authProvider:\n type: keycloak\n\nkeycloak:\n create: false # Don't deploy Keycloak\n externalUrl: https://your-keycloak.example.com\n realm: mcp-gateway\n\nkeycloak-configure:\n enabled: true # Still configure the external Keycloak\n```\n\n**Optional: Keycloak M2M authentication:**\n\n```yaml\nauth-server:\n keycloak:\n m2mClientId: \"mcp-gateway-m2m\"\n m2mClientSecret: \"your-m2m-client-secret\"\n```\n\n#### Option 2: Microsoft Entra ID\n\n```yaml\nglobal:\n authProvider:\n type: entra\n entra:\n adminGroupId: \"your-admin-group-uuid\" # Optional: maps Entra group to admin role\n\nauth-server:\n entra:\n clientId: \"your-entra-client-id\"\n clientSecret: \"your-entra-client-secret\"\n tenantId: \"your-entra-tenant-id\"\n loginBaseUrl: \"\" # Optional: override for sovereign clouds (e.g., https://login.microsoftonline.us)\n```\n\nSee the [Entra ID documentation](../../docs/entra.md) for details on setting up your Entra ID app registration.\n\n#### Option 3: Okta\n\n```yaml\nglobal:\n authProvider:\n type: okta\n\nauth-server:\n okta:\n domain: \"dev-123456.okta.com\"\n clientId: \"your-client-id\"\n clientSecret: \"your-client-secret\"\n m2mClientId: \"\" # Optional: for machine-to-machine auth\n m2mClientSecret: \"\" # Optional: for machine-to-machine auth\n apiToken: \"\" # Optional: for IAM operations\n authServerId: \"\" # Optional: custom authorization server\n```\n\n#### Option 4: Auth0\n\n```yaml\nglobal:\n authProvider:\n type: auth0\n\nauth-server:\n auth0:\n domain: \"your-tenant.us.auth0.com\"\n clientId: \"your-client-id\"\n clientSecret: \"your-client-secret\"\n audience: \"\" # Optional: API audience for M2M tokens\n groupsClaim: \"https://mcp-gateway/groups\" # Custom claim for group memberships\n m2mClientId: \"\" # Required for IAM management\n m2mClientSecret: \"\" # Required for IAM management\n managementApiToken: \"\" # Optional: alternative to M2M credentials (expires 24h)\n```\n\n#### Option 5: AWS Cognito\n\n```yaml\nglobal:\n authProvider:\n type: cognito\n\nauth-server:\n cognito:\n userPoolId: \"us-east-1_xxxxxxxxx\"\n clientId: \"your-client-id\"\n clientSecret: \"your-client-secret\"\n domain: \"\" # Optional: custom Cognito domain\n region: \"us-east-1\" # AWS region for the User Pool\n```\n\n### Routing Modes\n\nThe stack supports two routing modes for accessing services:\n\n#### Subdomain-Based Routing (Default)\n\nServices are accessed via subdomains:\n\n- `keycloak.{domain}` - Keycloak authentication server\n- `auth-server.{domain}` - MCP Gateway auth server\n- `mcpregistry.{domain}` - MCP server registry\n\n**Configuration:**\n\n```yaml\nglobal:\n domain: \"yourdomain.com\"\n ingress:\n routingMode: subdomain\n```\n\n**DNS Requirements:** Configure A/CNAME records for each subdomain pointing to your ingress load balancer.\n\n#### Path-Based Routing\n\nServices are accessed via paths on a single domain:\n\n- `{domain}/keycloak` - Keycloak authentication server (default, configurable)\n- `{domain}/auth-server` - MCP Gateway auth server (default, configurable)\n- `{domain}/registry` - MCP server registry (default, configurable)\n- `{domain}/` - MCP server registry (root path)\n\n**Configuration:**\n\n```yaml\nglobal:\n domain: \"yourdomain.com\"\n ingress:\n routingMode: path\n paths:\n authServer: /auth-server # Customize as needed (e.g., /api/auth)\n registry: /registry # Customize as needed (e.g., /api)\n keycloak: /keycloak # Customize as needed (e.g., /auth/keycloak)\n```\n\n**Important:** If you customize the Keycloak path, update the helm variable:\n\n```yaml\nkeycloak:\n httpRelativePath: /keycloak/\n```\n\n**DNS Requirements:** Configure a single A/CNAME record for your domain pointing to your ingress load balancer.\n\n## Install\n\nOnce the `values.yaml` file is updated and saved, run (substitute MYNAMESPACE for the namespace in which this should be\ninstalled):\n\n```bash\nhelm dependency build && helm dependency update\nhelm install mcp-gateway-registry -n MYNAMESPACE --create-namespace . \n```\n\nThis will deploy the necessary resources for a Kubernetes deployment of the MCP Gateway Registry\n\n**Note:** You can add `--set global.chartVersion=$(git rev-parse HEAD)` to your helm install command, which will create\na configmap that has the version of the repository as the value. This can aid in debugging by making it much faster to\nidentify which version was used to deploy the charts.\n\n## Deploy Process\n\n### With Keycloak:\n\n- postgres, keycloak, registry, and auth-server will be deployed as the core components\n- A `keycloak-configure` job will also be created\n- Postgres will need to be running first before Keycloak will run\n- Keycloak needs to be available before the `keycloak-configure` job will run\n- auth-server will not start until the `keycloak-configure` job has succeeded and generated a secret that is needed for\n the auth-server.\n- The registry will start as soon as the image is pulled\n\n### With Entra ID, Okta, Auth0, or Cognito:\n\n- MongoDB, registry, and auth-server will be deployed as the core components\n- Keycloak and keycloak-configure are skipped\n- auth-server will use the configured IdP credentials from your values file\n- The registry will start as soon as the image is pulled\n\n## Deployment Examples (all run from charts/mcp-gateway-registry-stack)\n\n### Subdomain with Keycloak\n\nCreates a self-contained deployment. This is the simplest deployment.\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n --set global.domain=agents.domain.example\n```\n\n### Subdomain with Entra and Inbound IP Allowlisting\n\nCreates a deployment using Entra. Please follow the [instructions](../../docs/entra-id-setup.md) to set up Entra.\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n--set global.domain=agents.domain.example \\\n--set global.ingress.routingMode=subdomain \\\n--set global.authProvider.type=entra \\\n--set auth-server.entra.clientId=ENTRA_CLIENT_UUID \\\n--set auth-server.entra.clientSecret=ENTRA_CLIENT_SECRET \\\n--set auth-server.entra.tenantId=ENTRA_TENANT_ID \\\n--set global.authProvider.entra.adminGroupId=ENTRA_ADMIN_GROUP_UUID \\\n--set keycloak-configure.enabled=false \\\n--set keycloak.create=false \\\n--set global.ingress.inboundCidrs='my.public.ip.address/32'\n```\n\n### Subdomain with Okta and Inbound IP Allowlisting\n\nCreates a deployment using Okta.\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n--set global.domain=agents.domain.example \\\n--set global.ingress.routingMode=subdomain \\\n--set global.authProvider.type=okta \\\n--set auth-server.okta.domain=OKTA_DOMAIN \\\n--set auth-server.okta.clientId=OKTA_CLIENT_ID \\\n--set auth-server.okta.clientSecret=OKTA_CLIENT_SECRET \\\n--set keycloak-configure.enabled=false \\\n--set keycloak.create=false \\\n--set global.ingress.inboundCidrs='my.public.ip.address/32'\n```\n\n\n### Subdomain with Auth0\n\nCreates a deployment using Auth0.\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n--set global.domain=agents.domain.example \\\n--set global.authProvider.type=auth0 \\\n--set auth-server.auth0.domain=YOUR_TENANT.us.auth0.com \\\n--set auth-server.auth0.clientId=AUTH0_CLIENT_ID \\\n--set auth-server.auth0.clientSecret=AUTH0_CLIENT_SECRET \\\n--set keycloak-configure.enabled=false \\\n--set keycloak.create=false\n```\n\n### Subdomain with AWS Cognito\n\nCreates a deployment using AWS Cognito.\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n--set global.domain=agents.domain.example \\\n--set global.authProvider.type=cognito \\\n--set auth-server.cognito.userPoolId=us-east-1_XXXXXXXXX \\\n--set auth-server.cognito.clientId=COGNITO_CLIENT_ID \\\n--set auth-server.cognito.clientSecret=COGNITO_CLIENT_SECRET \\\n--set keycloak-configure.enabled=false \\\n--set keycloak.create=false\n```\n\n### Path with Keycloak and git hash retention for debugging\n\nWill create a configmap in the `mcp-gateway-registry` namespace called `chart-version` with the git hash of the current\nrepo (if cloned) to aid in debugging.\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n--set global.domain=agents.domain.example \\\n--set global.ingress.routingMode=path \\\n--set keycloak.httpRelativePath=/keycloak/ \\\n--set global.chartVersion=$(git rev-parse --short HEAD)\n```\n\n### Federation with Keycloak on path\n\nWill enable registry federation for this deployment. Creates a static token in the `shared-secret` in the\n`mcp-gateway-registry` namespace that needs to be shared with the connecting registry. If used with `inboundCidr` allow\nlisting, the connecting registry IP needs to be part of the allowed CIDR range.\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n --set global.domain=agents.domain.example \\\n --set global.ingress.routingMode=path \\\n --set keycloak.httpRelativePath=/keycloak/ \\\n --set global.federation.staticTokenAuthEnabled=true\n```\n\n**Federation with OAuth2 for outbound peer connections:**\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n --set global.domain=agents.domain.example \\\n --set global.federation.staticTokenAuthEnabled=true \\\n --set registry.app.federationTokenEndpoint=https://idp.example.com/oauth2/token \\\n --set registry.app.federationClientId=federation-client \\\n --set registry.app.federationClientSecret=federation-secret\n```\n\n### ASOR (Workday) Integration\n\nASOR integration is independent of peer federation and can be enabled alongside any auth provider:\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n --set global.domain=agents.domain.example \\\n --set registry.app.asorAccessToken=your-asor-access-token \\\n --set registry.app.workdayTokenUrl=https://services.wd101.myworkday.com/ccx/oauth2/instance/token\n```\n\n### Auth Server Advanced Configuration\n\n**Static token authentication** (use a static API key instead of IdP JWT for Registry API):\n\n```bash\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n --set global.domain=agents.domain.example \\\n --set auth-server.app.registryStaticTokenAuthEnabled=true \\\n --set auth-server.app.registryApiToken=your-secure-api-token\n```\n\n**Custom JWT configuration** (override internal service-to-service token claims):\n\n```yaml\nauth-server:\n app:\n jwtIssuer: \"custom-issuer\" # Default: mcp-auth-server\n jwtAudience: \"custom-audience\" # Default: mcp-registry\n maxTokensPerUserPerHour: \"50\" # Default: 100\n```\n\n## Use\n\nNavigate to the registry based on your routing mode:\n\n**Subdomain mode:** https://mcpregistry.DOMAIN\n\n**Path mode:** https://DOMAIN/registry or https://DOMAIN/\n\n### With Keycloak\n\nThe username/password are displayed in the output of the `keycloak-configure job`\n\n```bash\nkubectl get pods -l job-name=setup-keycloak -n MYNAMESPACE \n```\n\nThe output will look similar to:\n\n```\nNAME READY STATUS RESTARTS AGE\nsetup-keycloak-d6g2r 0/1 Completed 0 29m\nsetup-keycloak-nnqgj 0/1 Error 0 31m\n```\n\nUse the pod name that completed successfully:\n\n```\nkubectl logs -n MYNAMESPACE setup-keycloak-d6g2r --tail 20\n```\n\nYou will see the credentials in the output\n\n### With Entra ID:\n\nNavigate to https://mcpregistry.DOMAIN to log in. Users will authenticate using their Microsoft Entra ID credentials.\nEnsure that:\n\n1. Your Entra ID app registration has the correct redirect URIs configured\n2. Users are assigned to the appropriate Entra ID groups\n3. Group mappings are configured in your scopes.yml or MongoDB\n\nSee the [Entra ID documentation](../../docs/entra.md) for complete setup instructions.\n\n### With Okta, Auth0, or Cognito:\n\nNavigate to https://mcpregistry.DOMAIN to log in. Users will authenticate through your configured identity provider.\nEnsure that your IdP application has the correct redirect URIs configured:\n\n- Callback URL: `https://auth-server.DOMAIN/callback` (subdomain) or `https://DOMAIN/auth-server/callback` (path)\n- Logout URL: `https://mcpregistry.DOMAIN` (subdomain) or `https://DOMAIN/registry` (path)\n\n## Scaling and Redundancy\n\n### Replica Configuration\n\nBoth the auth-server and registry deployments support configuring the number of replicas via `values.yaml`:\n\n```yaml\nauth-server:\n replicaCount: 2\n\nregistry:\n replicaCount: 2\n```\n\nFor production environments, we recommend running at least 2 replicas of each service for redundancy.\n\n### Topology Spread Constraints\n\nBy default, neither the auth-server nor registry deployments include `topologySpreadConstraints`. This is intentional\nfor several reasons:\n\n1. **Routing Complexity**: Routing is complex and handled differently between deployments\n2. **Development Flexibility**: Single-node or small clusters (common in dev/test) would fail to schedule pods with\n strict spread constraints\n3. **Custom Requirements**: Organizations often have specific topology requirements that vary by environment\n\nFor production deployments on multi-AZ clusters, we recommend adding topology spread constraints to both deployments to\ndistribute pods across availability zones and nodes. This improves fault tolerance and ensures service availability\nduring zone or node failures.\n\n#### Adding Topology Spread Constraints\n\nTo add topology spread constraints, patch the deployments after installation:\n\n```bash\n# Patch auth-server deployment\nkubectl patch deployment auth-server -n MYNAMESPACE --type='json' -p='[\n {\n \"op\": \"add\",\n \"path\": \"/spec/template/spec/topologySpreadConstraints\",\n \"value\": [\n {\n \"maxSkew\": 1,\n \"topologyKey\": \"topology.kubernetes.io/zone\",\n \"whenUnsatisfiable\": \"ScheduleAnyway\",\n \"labelSelector\": {\n \"matchLabels\": {\n \"app.kubernetes.io/name\": \"auth-server\",\n \"app.kubernetes.io/component\": \"auth-server\"\n }\n }\n },\n {\n \"maxSkew\": 1,\n \"topologyKey\": \"kubernetes.io/hostname\",\n \"whenUnsatisfiable\": \"ScheduleAnyway\",\n \"labelSelector\": {\n \"matchLabels\": {\n \"app.kubernetes.io/name\": \"auth-server\",\n \"app.kubernetes.io/component\": \"auth-server\"\n }\n }\n }\n ]\n }\n]'\n\n# Patch registry deployment\nkubectl patch deployment registry -n MYNAMESPACE --type='json' -p='[\n {\n \"op\": \"add\",\n \"path\": \"/spec/template/spec/topologySpreadConstraints\",\n \"value\": [\n {\n \"maxSkew\": 1,\n \"topologyKey\": \"topology.kubernetes.io/zone\",\n \"whenUnsatisfiable\": \"ScheduleAnyway\",\n \"labelSelector\": {\n \"matchLabels\": {\n \"app.kubernetes.io/name\": \"registry\",\n \"app.kubernetes.io/component\": \"registry\"\n }\n }\n },\n {\n \"maxSkew\": 1,\n \"topologyKey\": \"kubernetes.io/hostname\",\n \"whenUnsatisfiable\": \"ScheduleAnyway\",\n \"labelSelector\": {\n \"matchLabels\": {\n \"app.kubernetes.io/name\": \"registry\",\n \"app.kubernetes.io/component\": \"registry\"\n }\n }\n }\n ]\n }\n]'\n```\n\n#### Constraint Explanation\n\n- **`topology.kubernetes.io/zone`**: Spreads pods across availability zones for zone-level fault tolerance\n- **`kubernetes.io/hostname`**: Spreads pods across different nodes within each zone for node-level fault tolerance\n- **`maxSkew: 1`**: Ensures pods are distributed as evenly as possible (difference between zones/nodes is at most 1)\n- **`whenUnsatisfiable: ScheduleAnyway`**: Uses soft constraints that prefer even distribution but won't block\n scheduling if perfect distribution isn't possible. Change to `DoNotSchedule` for strict enforcement\n\n## Using Existing Secrets\n\nBy default, the stack chart creates and manages Kubernetes Secrets for all components. For production environments\nusing external secret management (e.g., AWS Secrets Manager with External Secrets Operator, HashiCorp Vault), you\ncan reference pre-existing secrets instead.\n\n### Stack-Level Existing Secrets\n\n| Value | Default Secret Name | Description |\n|-------|---------------------|-------------|\n| `global.existingSharedSecret` | `shared-secret` | SECRET_KEY and federation tokens shared by auth-server and registry |\n| `global.existingOauthProviderSecret` | `oauth-provider-secret` | Auth provider credentials (Keycloak/Entra/Okta/Auth0/Cognito) |\n| `global.existingMongoCredentialsSecret` | `mongo-credentials` | MongoDB connection credentials used by auth-server and registry |\n| `mongodb.existingPasswordSecret` | `my-user-password` | MongoDB operator user password |\n\n### Per-Service Existing Secrets\n\nWhen deploying individual charts (not the stack), each chart supports its own existing secret:\n\n| Chart | Value | Default Secret Name |\n|-------|-------|---------------------|\n| auth-server | `app.existingSecret` | `auth-server-secret` |\n| registry | `app.existingSecret` | `registry-secret` |\n| mcpgw | `app.existingSecret` | `mcpgw-secret` |\n| keycloak-configure | `keycloak.existingSecret` | `keycloak-configure-secret` |\n| mongodb-configure | `mongodb.existingSecret` | `mongo-credentials` |\n\n### Per-Key Existing Secrets\n\nFor finer-grained control, individual sensitive values can be sourced from separate existing secrets. Each sensitive field supports two companion values: `{field}ExistingSecret` (secret name) and `{field}ExistingSecretKey` (key within that secret, defaults to the env var name).\n\n**auth-server and registry:**\n\n| Field | ExistingSecret value | ExistingSecretKey default |\n|-------|---------------------|--------------------------|\n| `entra.clientSecret` | `entra.clientSecretExistingSecret` | `ENTRA_CLIENT_SECRET` |\n| `okta.clientSecret` | `okta.clientSecretExistingSecret` | `OKTA_CLIENT_SECRET` |\n| `okta.m2mClientSecret` | `okta.m2mClientSecretExistingSecret` | `OKTA_M2M_CLIENT_SECRET` |\n| `okta.apiToken` | `okta.apiTokenExistingSecret` | `OKTA_API_TOKEN` |\n| `auth0.clientSecret` | `auth0.clientSecretExistingSecret` | `AUTH0_CLIENT_SECRET` |\n| `auth0.m2mClientSecret` | `auth0.m2mClientSecretExistingSecret` | `AUTH0_M2M_CLIENT_SECRET` |\n| `auth0.managementApiToken` | `auth0.managementApiTokenExistingSecret` | `AUTH0_MANAGEMENT_API_TOKEN` |\n\n**registry only:**\n\n| Field | ExistingSecret value | ExistingSecretKey default |\n|-------|---------------------|--------------------------|\n| `ans.apiKey` | `ans.apiKeyExistingSecret` | `ANS_API_KEY` |\n| `ans.apiSecret` | `ans.apiSecretExistingSecret` | `ANS_API_SECRET` |\n\n**mcpgw only:**\n\n| Field | ExistingSecret value | ExistingSecretKey default |\n|-------|---------------------|--------------------------|\n| `app.embeddingsApiKey` | `app.embeddingsApiKeyExistingSecret` | `EMBEDDINGS_API_KEY` |\n\nWhen a per-key existing secret is set, the chart skips writing that key into its managed secret and instead injects the value via `env.valueFrom.secretKeyRef`. The key name within the existing secret can be customized using the corresponding `ExistingSecretKey` value.\n\n### Example: Using External Secrets\n\n```bash\n# Deploy stack using pre-existing secrets\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n --set global.domain=agents.domain.example \\\n --set global.existingSharedSecret=my-shared-secret \\\n --set global.existingOauthProviderSecret=my-oauth-secret \\\n --set global.existingMongoCredentialsSecret=my-mongo-creds \\\n --set mongodb.existingPasswordSecret=my-mongo-password\n```\n\n```bash\n# Deploy auth-server with Okta client secret from a separate existing secret\nhelm install mcp-gateway-registry -n mcp-gateway-registry --create-namespace . \\\n --set global.domain=agents.domain.example \\\n --set global.authProvider.type=okta \\\n --set auth-server.okta.domain=dev-123456.okta.com \\\n --set auth-server.okta.clientId=MY_CLIENT_ID \\\n --set auth-server.okta.clientSecretExistingSecret=my-okta-secret \\\n --set auth-server.okta.clientSecretExistingSecretKey=clientSecret\n```\n\nWhen an existing secret is specified:\n\n1. The chart skips creating the corresponding managed Secret resource (or skips that key for per-key references)\n2. Deployments and jobs reference the specified secret name instead\n3. The existing secret must contain the expected key (defaulting to the env var name)\n\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/_helpers.tpl", "content": "{{/*\nExpand the name of the chart.\n*/}}\n{{- define \"mcp-gateway-registry-stack.name\" -}}\n{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix \"-\" }}\n{{- end }}\n\n{{/*\nCreate a default fully qualified app name.\n*/}}\n{{- define \"mcp-gateway-registry-stack.fullname\" -}}\n{{- if .Values.fullnameOverride }}\n{{- .Values.fullnameOverride | trunc 63 | trimSuffix \"-\" }}\n{{- else }}\n{{- $name := default .Chart.Name .Values.nameOverride }}\n{{- if contains $name .Release.Name }}\n{{- .Release.Name | trunc 63 | trimSuffix \"-\" }}\n{{- else }}\n{{- printf \"%s-%s\" .Release.Name $name | trunc 63 | trimSuffix \"-\" }}\n{{- end }}\n{{- end }}\n{{- end }}\n\n{{/*\nCreate chart name and version as used by the chart label.\n*/}}\n{{- define \"mcp-gateway-registry-stack.chart\" -}}\n{{- printf \"%s-%s\" .Chart.Name .Chart.Version | replace \"+\" \"_\" | trunc 63 | trimSuffix \"-\" }}\n{{- end }}\n\n{{/*\nCommon labels\n*/}}\n{{- define \"mcp-gateway-registry-stack.labels\" -}}\nhelm.sh/chart: {{ include \"mcp-gateway-registry-stack.chart\" . }}\n{{ include \"mcp-gateway-registry-stack.selectorLabels\" . }}\n{{- if .Chart.AppVersion }}\napp.kubernetes.io/version: {{ .Chart.AppVersion | quote }}\n{{- end }}\napp.kubernetes.io/managed-by: {{ .Release.Service }}\n{{- end }}\n\n{{/*\nSelector labels\n*/}}\n{{- define \"mcp-gateway-registry-stack.selectorLabels\" -}}\napp.kubernetes.io/name: {{ include \"mcp-gateway-registry-stack.name\" . }}\napp.kubernetes.io/instance: {{ .Release.Name }}\n{{- end }}\n\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/keycloak-admin-secret.yaml", "content": "{{/*\nKeycloak admin password secret.\nGenerates a random password on first install and preserves it across helm upgrades.\nThis prevents the admin password from being regenerated by the Bitnami chart on\neach helm upgrade, which can cause authentication issues.\n*/}}\n{{- if .Values.keycloak.create }}\n{{- $secretName := printf \"%s-keycloak\" .Release.Name }}\n{{- $existingSecret := lookup \"v1\" \"Secret\" .Release.Namespace $secretName }}\n{{- $adminPassword := \"\" }}\n{{- if $existingSecret }}\n {{- $adminPassword = index $existingSecret.data \"admin-password\" | b64dec }}\n{{- else }}\n {{- $adminPassword = randAlphaNum 32 }}\n{{- end }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: {{ $secretName }}\n namespace: {{ .Release.Namespace | quote }}\n labels:\n {{- include \"mcp-gateway-registry-stack.labels\" . | nindent 4 }}\ntype: Opaque\ndata:\n admin-password: {{ $adminPassword | b64enc | quote }}\n{{- end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/keycloak-ingress-patch.yaml", "content": "# This template patches the Keycloak ingress hostname to use the global domain\n# Only deployed when the auth provider is keycloak (not entra)\n{{- if eq .Values.global.authProvider.type \"keycloak\" }}\n{{- if .Values.keycloakIngress.enabled }}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $pathPrefix := .Values.global.ingress.paths.keycloak | default \"/keycloak\" }}\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: {{ .Release.Name }}-keycloak\n namespace: {{ .Release.Namespace | quote }}\n annotations:\n {{- if eq $routingMode \"path\" }}\n alb.ingress.kubernetes.io/group.name: mcp-gateway-stack\n alb.ingress.kubernetes.io/group.order: '30'\n {{- end }}\n alb.ingress.kubernetes.io/listen-ports: '[{\"HTTPS\": 443}]'\n alb.ingress.kubernetes.io/scheme: internet-facing\n alb.ingress.kubernetes.io/ssl-redirect: '443'\n alb.ingress.kubernetes.io/target-type: ip\n alb.ingress.kubernetes.io/success-codes: 200,302\n {{- if .Values.global.ingress.inboundCidrs }}\n alb.ingress.kubernetes.io/inbound-cidrs: {{ .Values.global.ingress.inboundCidrs }}\n {{- end }}\nspec:\n ingressClassName: {{ .Values.global.ingress.className }}\n rules:\n {{- if eq $routingMode \"path\" }}\n - host: {{ .Values.global.domain }}\n http:\n paths:\n - path: {{ $pathPrefix }}\n pathType: Prefix\n backend:\n service:\n name: {{ .Release.Name }}-keycloak-headless\n port:\n number: 8080\n {{- else }}\n - host: keycloak.{{ .Values.global.domain }}\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: {{ .Release.Name }}-keycloak-headless\n port:\n number: 8080\n {{- end }}\n{{- end }}\n{{- end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/keycloak-pg-secret.yaml", "content": "{{/*\nKeycloak PostgreSQL secret.\nGenerates random passwords on first install and preserves them across helm upgrades.\nThis prevents the bn_keycloak authentication failure that occurs when Bitnami's\nPostgreSQL subchart regenerates passwords but the PVC retains the original ones.\n*/}}\n{{- if .Values.keycloak.create }}\n{{- $secretName := printf \"%s-keycloak-postgresql\" .Release.Name }}\n{{- $existingSecret := lookup \"v1\" \"Secret\" .Release.Namespace $secretName }}\n{{- $password := \"\" }}\n{{- $postgresPassword := \"\" }}\n{{- if $existingSecret }}\n {{- $password = index $existingSecret.data \"password\" | b64dec }}\n {{- $postgresPassword = index $existingSecret.data \"postgres-password\" | b64dec }}\n{{- else }}\n {{- $password = randAlphaNum 32 }}\n {{- $postgresPassword = randAlphaNum 32 }}\n{{- end }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: {{ $secretName }}\n namespace: {{ .Release.Namespace | quote }}\n labels:\n {{- include \"mcp-gateway-registry-stack.labels\" . | nindent 4 }}\ntype: Opaque\ndata:\n password: {{ $password | b64enc | quote }}\n postgres-password: {{ $postgresPassword | b64enc | quote }}\n{{- end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/mongodb-cluster.yaml", "content": "{{ if .Values.mongodb.enabled }}\napiVersion: mongodbcommunity.mongodb.com/v1\nkind: MongoDBCommunity\nmetadata:\n name: {{ default .Values.mongodb.host \"mcp-registry-mongodb\" }}\n namespace: {{ .Release.Namespace | quote }}\nspec:\n members: {{ default .Values.mongodb.replicas \"3\"}}\n type: ReplicaSet\n version: {{ default .Values.mongodb.version \"8.0.16\" | quote }}\n security:\n authentication:\n modes: [\"SCRAM\"]\n users:\n - name: {{ .Values.mongodb.user }}\n db: admin\n passwordSecretRef:\n name: {{ .Values.mongodb.existingPasswordSecret | default \"my-user-password\" }}\n roles:\n - name: clusterAdmin\n db: admin\n - name: root\n db: admin\n - name: userAdminAnyDatabase\n db: admin\n scramCredentialsSecretName: my-scram\n additionalMongodConfig:\n storage.wiredTiger.engineConfig.journalCompressor: zlib\n {{- with .Values.global.nodeSelector }}\n statefulSet:\n spec:\n template:\n spec:\n nodeSelector:\n {{- toYaml . | nindent 12 }}\n {{- end }}\n{{ end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/mongodb-secret.yaml", "content": "{{ if .Values.mongodb.enabled }}\n{{- if not .Values.mongodb.existingPasswordSecret }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: my-user-password\n namespace: {{ .Release.Namespace | quote }}\ntype: Opaque\ndata:\n password: {{ .Values.mongodb.password | b64enc | quote}}\n{{- end }}\n{{ end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/oauth-provider-secret.yaml", "content": "{{/*\nShared OAuth provider secret for auth-server and registry.\nContains the auth provider type and identity provider credentials\n(Keycloak, Entra, or Okta) that both services need.\n*/}}\n{{- if not .Values.global.existingOauthProviderSecret }}\n{{- $secretName := .Values.global.oauthProviderSecretName | default \"oauth-provider-secret\" }}\n{{- $existingSecret := lookup \"v1\" \"Secret\" .Release.Namespace $secretName }}\n{{- $authProviderType := .Values.global.authProvider.type | default \"keycloak\" }}\n{{- /* Resolve Keycloak URLs and realm */ -}}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $domain := .Values.global.domain | default \"localhost\" }}\n{{- $protocol := ternary \"https\" \"http\" .Values.global.ingress.tls }}\n{{- $keycloakPath := .Values.global.ingress.paths.keycloak | default \"/keycloak\" }}\n{{- $keycloakUrl := printf \"http://%s-keycloak-headless.%s.svc.cluster.local:8080\" .Release.Name .Release.Namespace }}\n{{- $keycloakExternalUrl := \"\" }}\n{{- if eq $routingMode \"path\" }}\n {{- $keycloakUrl = printf \"%s%s\" $keycloakUrl $keycloakPath }}\n {{- $keycloakExternalUrl = printf \"%s://%s%s\" $protocol $domain $keycloakPath }}\n{{- else }}\n {{- $keycloakExternalUrl = printf \"%s://keycloak.%s\" $protocol $domain }}\n{{- end }}\n{{- $keycloakRealm := .Values.global.authProvider.keycloak.realm | default \"mcp-gateway\" }}\n{{- /* Resolve Keycloak M2M credentials */ -}}\n{{- $keycloakM2mClientId := \"\" }}\n{{- $keycloakM2mClientSecret := \"\" }}\n{{- if (index .Values \"auth-server\") }}\n {{- if (index .Values \"auth-server\" \"keycloak\") }}\n {{- $keycloakM2mClientId = (index .Values \"auth-server\" \"keycloak\" \"m2mClientId\") | default \"\" }}\n {{- $keycloakM2mClientSecret = (index .Values \"auth-server\" \"keycloak\" \"m2mClientSecret\") | default \"\" }}\n {{- end }}\n{{- end }}\n{{- /* Resolve Entra credentials - prefer values, fallback to existing secret */ -}}\n{{- $entraClientId := \"\" }}\n{{- $entraClientSecret := \"\" }}\n{{- $entraTenantId := \"\" }}\n{{- if (index .Values \"auth-server\") }}\n {{- if (index .Values \"auth-server\" \"entra\") }}\n {{- $entraClientId = (index .Values \"auth-server\" \"entra\" \"clientId\") | default \"\" }}\n {{- $entraClientSecret = (index .Values \"auth-server\" \"entra\" \"clientSecret\") | default \"\" }}\n {{- $entraTenantId = (index .Values \"auth-server\" \"entra\" \"tenantId\") | default \"\" }}\n {{- end }}\n{{- end }}\n{{- /* Resolve Entra login base URL */ -}}\n{{- $entraLoginBaseUrl := \"\" }}\n{{- if (index .Values \"auth-server\") }}\n {{- if (index .Values \"auth-server\" \"entra\") }}\n {{- $entraLoginBaseUrl = (index .Values \"auth-server\" \"entra\" \"loginBaseUrl\") | default \"\" }}\n {{- end }}\n{{- end }}\n{{- /* Persist Entra credentials across upgrades */ -}}\n{{- if and (not $entraClientId) $existingSecret }}\n {{- if index $existingSecret.data \"ENTRA_CLIENT_ID\" }}\n {{- $entraClientId = index $existingSecret.data \"ENTRA_CLIENT_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $entraClientSecret) $existingSecret }}\n {{- if index $existingSecret.data \"ENTRA_CLIENT_SECRET\" }}\n {{- $entraClientSecret = index $existingSecret.data \"ENTRA_CLIENT_SECRET\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $entraTenantId) $existingSecret }}\n {{- if index $existingSecret.data \"ENTRA_TENANT_ID\" }}\n {{- $entraTenantId = index $existingSecret.data \"ENTRA_TENANT_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- /* Resolve Okta credentials - prefer values, fallback to existing secret */ -}}\n{{- $oktaDomain := \"\" }}\n{{- $oktaClientId := \"\" }}\n{{- $oktaClientSecret := \"\" }}\n{{- $oktaM2mClientId := \"\" }}\n{{- $oktaM2mClientSecret := \"\" }}\n{{- $oktaApiToken := \"\" }}\n{{- $oktaAuthServerId := \"\" }}\n{{- if (index .Values \"auth-server\") }}\n {{- if (index .Values \"auth-server\" \"okta\") }}\n {{- $oktaDomain = (index .Values \"auth-server\" \"okta\" \"domain\") | default \"\" }}\n {{- $oktaClientId = (index .Values \"auth-server\" \"okta\" \"clientId\") | default \"\" }}\n {{- $oktaClientSecret = (index .Values \"auth-server\" \"okta\" \"clientSecret\") | default \"\" }}\n {{- $oktaM2mClientId = (index .Values \"auth-server\" \"okta\" \"m2mClientId\") | default \"\" }}\n {{- $oktaM2mClientSecret = (index .Values \"auth-server\" \"okta\" \"m2mClientSecret\") | default \"\" }}\n {{- $oktaApiToken = (index .Values \"auth-server\" \"okta\" \"apiToken\") | default \"\" }}\n {{- $oktaAuthServerId = (index .Values \"auth-server\" \"okta\" \"authServerId\") | default \"\" }}\n {{- end }}\n{{- end }}\n{{- /* Persist Okta credentials across upgrades */ -}}\n{{- if and (not $oktaDomain) $existingSecret }}\n {{- if index $existingSecret.data \"OKTA_DOMAIN\" }}\n {{- $oktaDomain = index $existingSecret.data \"OKTA_DOMAIN\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $oktaClientId) $existingSecret }}\n {{- if index $existingSecret.data \"OKTA_CLIENT_ID\" }}\n {{- $oktaClientId = index $existingSecret.data \"OKTA_CLIENT_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $oktaClientSecret) $existingSecret }}\n {{- if index $existingSecret.data \"OKTA_CLIENT_SECRET\" }}\n {{- $oktaClientSecret = index $existingSecret.data \"OKTA_CLIENT_SECRET\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $oktaM2mClientId) $existingSecret }}\n {{- if index $existingSecret.data \"OKTA_M2M_CLIENT_ID\" }}\n {{- $oktaM2mClientId = index $existingSecret.data \"OKTA_M2M_CLIENT_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $oktaM2mClientSecret) $existingSecret }}\n {{- if index $existingSecret.data \"OKTA_M2M_CLIENT_SECRET\" }}\n {{- $oktaM2mClientSecret = index $existingSecret.data \"OKTA_M2M_CLIENT_SECRET\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $oktaApiToken) $existingSecret }}\n {{- if index $existingSecret.data \"OKTA_API_TOKEN\" }}\n {{- $oktaApiToken = index $existingSecret.data \"OKTA_API_TOKEN\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $oktaAuthServerId) $existingSecret }}\n {{- if index $existingSecret.data \"OKTA_AUTH_SERVER_ID\" }}\n {{- $oktaAuthServerId = index $existingSecret.data \"OKTA_AUTH_SERVER_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- /* Resolve Auth0 credentials - prefer values, fallback to existing secret */ -}}\n{{- $auth0Domain := \"\" }}\n{{- $auth0ClientId := \"\" }}\n{{- $auth0ClientSecret := \"\" }}\n{{- $auth0Audience := \"\" }}\n{{- $auth0GroupsClaim := \"https://mcp-gateway/groups\" }}\n{{- $auth0M2mClientId := \"\" }}\n{{- $auth0M2mClientSecret := \"\" }}\n{{- $auth0ManagementApiToken := \"\" }}\n{{- if (index .Values \"auth-server\") }}\n {{- if (index .Values \"auth-server\" \"auth0\") }}\n {{- $auth0Domain = (index .Values \"auth-server\" \"auth0\" \"domain\") | default \"\" }}\n {{- $auth0ClientId = (index .Values \"auth-server\" \"auth0\" \"clientId\") | default \"\" }}\n {{- $auth0ClientSecret = (index .Values \"auth-server\" \"auth0\" \"clientSecret\") | default \"\" }}\n {{- $auth0Audience = (index .Values \"auth-server\" \"auth0\" \"audience\") | default \"\" }}\n {{- $auth0GroupsClaim = (index .Values \"auth-server\" \"auth0\" \"groupsClaim\") | default \"https://mcp-gateway/groups\" }}\n {{- $auth0M2mClientId = (index .Values \"auth-server\" \"auth0\" \"m2mClientId\") | default \"\" }}\n {{- $auth0M2mClientSecret = (index .Values \"auth-server\" \"auth0\" \"m2mClientSecret\") | default \"\" }}\n {{- $auth0ManagementApiToken = (index .Values \"auth-server\" \"auth0\" \"managementApiToken\") | default \"\" }}\n {{- end }}\n{{- end }}\n{{- /* Persist Auth0 credentials across upgrades */ -}}\n{{- if and (not $auth0Domain) $existingSecret }}\n {{- if index $existingSecret.data \"AUTH0_DOMAIN\" }}\n {{- $auth0Domain = index $existingSecret.data \"AUTH0_DOMAIN\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $auth0ClientId) $existingSecret }}\n {{- if index $existingSecret.data \"AUTH0_CLIENT_ID\" }}\n {{- $auth0ClientId = index $existingSecret.data \"AUTH0_CLIENT_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $auth0ClientSecret) $existingSecret }}\n {{- if index $existingSecret.data \"AUTH0_CLIENT_SECRET\" }}\n {{- $auth0ClientSecret = index $existingSecret.data \"AUTH0_CLIENT_SECRET\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $auth0Audience) $existingSecret }}\n {{- if index $existingSecret.data \"AUTH0_AUDIENCE\" }}\n {{- $auth0Audience = index $existingSecret.data \"AUTH0_AUDIENCE\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $auth0M2mClientId) $existingSecret }}\n {{- if index $existingSecret.data \"AUTH0_M2M_CLIENT_ID\" }}\n {{- $auth0M2mClientId = index $existingSecret.data \"AUTH0_M2M_CLIENT_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $auth0M2mClientSecret) $existingSecret }}\n {{- if index $existingSecret.data \"AUTH0_M2M_CLIENT_SECRET\" }}\n {{- $auth0M2mClientSecret = index $existingSecret.data \"AUTH0_M2M_CLIENT_SECRET\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $auth0ManagementApiToken) $existingSecret }}\n {{- if index $existingSecret.data \"AUTH0_MANAGEMENT_API_TOKEN\" }}\n {{- $auth0ManagementApiToken = index $existingSecret.data \"AUTH0_MANAGEMENT_API_TOKEN\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- /* Resolve Cognito credentials - prefer values, fallback to existing secret */ -}}\n{{- $cognitoUserPoolId := \"\" }}\n{{- $cognitoClientId := \"\" }}\n{{- $cognitoClientSecret := \"\" }}\n{{- $cognitoDomain := \"\" }}\n{{- $cognitoRegion := \"us-east-1\" }}\n{{- if (index .Values \"auth-server\") }}\n {{- if (index .Values \"auth-server\" \"cognito\") }}\n {{- $cognitoUserPoolId = (index .Values \"auth-server\" \"cognito\" \"userPoolId\") | default \"\" }}\n {{- $cognitoClientId = (index .Values \"auth-server\" \"cognito\" \"clientId\") | default \"\" }}\n {{- $cognitoClientSecret = (index .Values \"auth-server\" \"cognito\" \"clientSecret\") | default \"\" }}\n {{- $cognitoDomain = (index .Values \"auth-server\" \"cognito\" \"domain\") | default \"\" }}\n {{- $cognitoRegion = (index .Values \"auth-server\" \"cognito\" \"region\") | default \"us-east-1\" }}\n {{- end }}\n{{- end }}\n{{- /* Persist Cognito credentials across upgrades */ -}}\n{{- if and (not $cognitoUserPoolId) $existingSecret }}\n {{- if index $existingSecret.data \"COGNITO_USER_POOL_ID\" }}\n {{- $cognitoUserPoolId = index $existingSecret.data \"COGNITO_USER_POOL_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $cognitoClientId) $existingSecret }}\n {{- if index $existingSecret.data \"COGNITO_CLIENT_ID\" }}\n {{- $cognitoClientId = index $existingSecret.data \"COGNITO_CLIENT_ID\" | b64dec }}\n {{- end }}\n{{- end }}\n{{- if and (not $cognitoClientSecret) $existingSecret }}\n {{- if index $existingSecret.data \"COGNITO_CLIENT_SECRET\" }}\n {{- $cognitoClientSecret = index $existingSecret.data \"COGNITO_CLIENT_SECRET\" | b64dec }}\n {{- end }}\n{{- end }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: {{ $secretName }}\n namespace: {{ .Release.Namespace | quote }}\n labels:\n {{- include \"mcp-gateway-registry-stack.labels\" . | nindent 4 }}\ntype: Opaque\ndata:\n AUTH_PROVIDER: {{ $authProviderType | b64enc | quote }}\n {{- if eq $authProviderType \"keycloak\" }}\n KEYCLOAK_ENABLED: {{ \"true\" | b64enc | quote }}\n KEYCLOAK_URL: {{ $keycloakUrl | b64enc | quote }}\n KEYCLOAK_EXTERNAL_URL: {{ $keycloakExternalUrl | b64enc | quote }}\n KEYCLOAK_REALM: {{ $keycloakRealm | b64enc | quote }}\n {{- if $keycloakM2mClientId }}\n KEYCLOAK_M2M_CLIENT_ID: {{ $keycloakM2mClientId | b64enc | quote }}\n {{- end }}\n {{- if $keycloakM2mClientSecret }}\n KEYCLOAK_M2M_CLIENT_SECRET: {{ $keycloakM2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"entra\" }}\n ENTRA_ENABLED: {{ \"true\" | b64enc | quote }}\n ENTRA_CLIENT_ID: {{ $entraClientId | b64enc | quote }}\n ENTRA_CLIENT_SECRET: {{ $entraClientSecret | b64enc | quote }}\n ENTRA_TENANT_ID: {{ $entraTenantId | b64enc | quote }}\n {{- if $entraLoginBaseUrl }}\n ENTRA_LOGIN_BASE_URL: {{ $entraLoginBaseUrl | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"okta\" }}\n OKTA_ENABLED: {{ \"true\" | b64enc | quote }}\n OKTA_DOMAIN: {{ $oktaDomain | b64enc | quote }}\n OKTA_CLIENT_ID: {{ $oktaClientId | b64enc | quote }}\n OKTA_CLIENT_SECRET: {{ $oktaClientSecret | b64enc | quote }}\n {{- if $oktaM2mClientId }}\n OKTA_M2M_CLIENT_ID: {{ $oktaM2mClientId | b64enc | quote }}\n {{- end }}\n {{- if $oktaM2mClientSecret }}\n OKTA_M2M_CLIENT_SECRET: {{ $oktaM2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- if $oktaApiToken }}\n OKTA_API_TOKEN: {{ $oktaApiToken | b64enc | quote }}\n {{- end }}\n {{- if $oktaAuthServerId }}\n OKTA_AUTH_SERVER_ID: {{ $oktaAuthServerId | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"auth0\" }}\n AUTH0_ENABLED: {{ \"true\" | b64enc | quote }}\n AUTH0_DOMAIN: {{ $auth0Domain | b64enc | quote }}\n AUTH0_CLIENT_ID: {{ $auth0ClientId | b64enc | quote }}\n AUTH0_CLIENT_SECRET: {{ $auth0ClientSecret | b64enc | quote }}\n {{- if $auth0Audience }}\n AUTH0_AUDIENCE: {{ $auth0Audience | b64enc | quote }}\n {{- end }}\n AUTH0_GROUPS_CLAIM: {{ $auth0GroupsClaim | b64enc | quote }}\n {{- if $auth0M2mClientId }}\n AUTH0_M2M_CLIENT_ID: {{ $auth0M2mClientId | b64enc | quote }}\n {{- end }}\n {{- if $auth0M2mClientSecret }}\n AUTH0_M2M_CLIENT_SECRET: {{ $auth0M2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- if $auth0ManagementApiToken }}\n AUTH0_MANAGEMENT_API_TOKEN: {{ $auth0ManagementApiToken | b64enc | quote }}\n {{- end }}\n {{- else if eq $authProviderType \"cognito\" }}\n COGNITO_ENABLED: {{ \"true\" | b64enc | quote }}\n COGNITO_USER_POOL_ID: {{ $cognitoUserPoolId | b64enc | quote }}\n COGNITO_CLIENT_ID: {{ $cognitoClientId | b64enc | quote }}\n COGNITO_CLIENT_SECRET: {{ $cognitoClientSecret | b64enc | quote }}\n {{- if $cognitoDomain }}\n COGNITO_DOMAIN: {{ $cognitoDomain | b64enc | quote }}\n {{- end }}\n {{- if $cognitoRegion }}\n AWS_REGION: {{ $cognitoRegion | b64enc | quote }}\n {{- end }}\n {{- end }}\n{{- end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/shared-secret.yaml", "content": "{{/*\nShared secret for auth-server and registry.\nGenerates random values if not provided via global values.\nBoth services reference this single secret for SECRET_KEY and federation tokens.\n*/}}\n{{- if not .Values.global.existingSharedSecret }}\n{{- $secretName := .Values.global.sharedSecretName | default \"shared-secret\" }}\n{{- $existingSecret := lookup \"v1\" \"Secret\" .Release.Namespace $secretName }}\n{{- $secretKey := \"\" }}\n{{- if .Values.global.secretKey }}\n {{- $secretKey = .Values.global.secretKey }}\n{{- else if $existingSecret }}\n {{- $secretKey = index $existingSecret.data \"SECRET_KEY\" | b64dec }}\n{{- else }}\n {{- $secretKey = randAlphaNum 64 }}\n{{- end }}\n{{- /* Resolve federation values */ -}}\n{{- $federationEnabled := false }}\n{{- $federationStaticTokenRaw := \"\" }}\n{{- $federationEncryptionKeyRaw := \"\" }}\n{{- $registryId := \"\" }}\n{{- if .Values.global.federation }}\n {{- $federationEnabled = .Values.global.federation.staticTokenAuthEnabled | default false }}\n {{- $federationStaticTokenRaw = .Values.global.federation.staticToken | default \"\" }}\n {{- $federationEncryptionKeyRaw = .Values.global.federation.encryptionKey | default \"\" }}\n {{- $registryId = .Values.global.federation.registryId | default \"\" }}\n{{- end }}\n{{- /* Reuse existing values from secret on upgrade, or generate new ones */ -}}\n{{- $federationStaticToken := \"\" }}\n{{- $federationEncryptionKey := \"\" }}\n{{- if $federationStaticTokenRaw }}\n {{- $federationStaticToken = $federationStaticTokenRaw }}\n{{- else if and $existingSecret (index $existingSecret.data \"FEDERATION_STATIC_TOKEN\") }}\n {{- $federationStaticToken = index $existingSecret.data \"FEDERATION_STATIC_TOKEN\" | b64dec }}\n{{- else }}\n {{- $federationStaticToken = randBytes 32 | replace \"+\" \"-\" | replace \"/\" \"_\" | trimSuffix \"=\" }}\n{{- end }}\n{{- if $federationEncryptionKeyRaw }}\n {{- $federationEncryptionKey = $federationEncryptionKeyRaw }}\n{{- else if and $existingSecret (index $existingSecret.data \"FEDERATION_ENCRYPTION_KEY\") }}\n {{- $federationEncryptionKey = index $existingSecret.data \"FEDERATION_ENCRYPTION_KEY\" | b64dec }}\n{{- else }}\n {{- $federationEncryptionKey = randBytes 32 }}\n{{- end }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: {{ $secretName }}\n namespace: {{ .Release.Namespace | quote }}\n labels:\n {{- include \"mcp-gateway-registry-stack.labels\" . | nindent 4 }}\ntype: Opaque\ndata:\n SECRET_KEY: {{ $secretKey | b64enc | quote }}\n {{- /* Resolve registry app values for federation and ASOR */ -}}\n {{- $fedTokenEndpoint := \"\" }}\n {{- $fedClientId := \"\" }}\n {{- $fedClientSecret := \"\" }}\n {{- $asorAccessToken := \"\" }}\n {{- $workdayTokenUrl := \"\" }}\n {{- if .Values.registry }}\n {{- if .Values.registry.app }}\n {{- $fedTokenEndpoint = .Values.registry.app.federationTokenEndpoint | default \"\" }}\n {{- $fedClientId = .Values.registry.app.federationClientId | default \"\" }}\n {{- $fedClientSecret = .Values.registry.app.federationClientSecret | default \"\" }}\n {{- $asorAccessToken = .Values.registry.app.asorAccessToken | default \"\" }}\n {{- $workdayTokenUrl = .Values.registry.app.workdayTokenUrl | default \"\" }}\n {{- end }}\n {{- end }}\n {{- if $federationEnabled }}\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED: {{ $federationEnabled | toString | b64enc | quote }}\n FEDERATION_STATIC_TOKEN: {{ $federationStaticToken | b64enc | quote }}\n FEDERATION_ENCRYPTION_KEY: {{ $federationEncryptionKey | b64enc | quote }}\n {{- if $fedTokenEndpoint }}\n FEDERATION_TOKEN_ENDPOINT: {{ $fedTokenEndpoint | b64enc | quote }}\n {{- end }}\n {{- if $fedClientId }}\n FEDERATION_CLIENT_ID: {{ $fedClientId | b64enc | quote }}\n {{- end }}\n {{- if $fedClientSecret }}\n FEDERATION_CLIENT_SECRET: {{ $fedClientSecret | b64enc | quote }}\n {{- end }}\n {{- end }}\n {{- if $registryId }}\n REGISTRY_ID: {{ $registryId | b64enc | quote }}\n {{- end }}\n {{- /* ASOR/Workday integration (independent of federation) */ -}}\n {{- if $asorAccessToken }}\n ASOR_ACCESS_TOKEN: {{ $asorAccessToken | b64enc | quote }}\n {{- end }}\n {{- if $workdayTokenUrl }}\n WORKDAY_TOKEN_URL: {{ $workdayTokenUrl | b64enc | quote }}\n {{- end }}\n{{- end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/templates/version-configmap.yaml", "content": "{{ if .Values.global.chartVersion }}\napiVersion: v1\nkind: ConfigMap\nmetadata:\n name: chart-version\n namespace: {{ include \"common.names.namespace\" . | quote }}\ndata:\n version: {{ .Values.global.chartVersion | quote }}\n{{ end }}\n" }, { "path": "charts/mcp-gateway-registry-stack/values.yaml", "content": "# Global configuration - these values are passed to all subcharts\nglobal:\n # Image tag for all services (auth-server, registry, mcpgw)\n # This value is passed down to all subcharts via Helm's global scope\n image:\n tag: 1.0.21\n\n # When installing chart from repository, add --set global.chartVersion=$(git rev-parse HEAD) to add the git hash to a configmap for debugging\n chartVersion:\n\n # Domain configuration - update this to your actual domain\n domain: \"DOMAIN\"\n\n # Security settings\n # secretKey: If not provided, a random 64-character key is auto-generated\n # and shared between auth-server and registry via a shared secret.\n # The generated key persists across helm upgrades.\n # Uncomment and set to use a specific key:\n # secretKey: \"your-secure-key-here\"\n\n # Shared secret name - automatically set for stack deployment\n # Both auth-server and registry will use this secret for SECRET_KEY and federation (if enabled)\n sharedSecretName: \"shared-secret\"\n\n # OAuth provider shared secret - contains auth provider type and IdP credentials\n # Both auth-server and registry reference this secret for Keycloak/Entra configuration\n oauthProviderSecretName: \"oauth-provider-secret\"\n\n # Existing secret references - set these to use pre-existing secrets instead of chart-managed ones.\n # When set, the chart skips creating the corresponding managed Secret resource.\n # The existing secret must contain the same keys the chart would have created.\n existingSharedSecret: \"\" # If set, skip creating shared-secret and use this name instead\n existingOauthProviderSecret: \"\" # If set, skip creating oauth-provider-secret and use this name instead\n existingMongoCredentialsSecret: \"\" # If set, use this name instead of mongo-credentials in deployments\n\n # Federation configuration - shared between registry and auth-server\n federation:\n staticTokenAuthEnabled: false # If not provided, defaults to false\n staticToken: # If not provided, a random token is auto-generated\n encryptionKey: # If not provided, a Fernet key is auto-generated\n registryId: # Unique identifier for this registry instance (optional)\n\n # Authentication Provider Configuration\n # Choose ONE provider: keycloak, entra, okta, auth0, or cognito\n authProvider:\n # Provider type: \"keycloak\", \"entra\", \"okta\", \"auth0\", or \"cognito\"\n type: keycloak\n keycloak:\n adminUsername: &keycloakAdmin \"user\"\n realm: &keycloakRealm \"mcp-gateway\"\n # Don't set password here - let Keycloak chart generate it\n entra:\n adminGroupId: # UUID of Entra admin group\n\n # Common ingress settings\n ingress:\n inboundCidrs: # optional comma separated list of allowed inbound CIDR ranges\n className: alb\n tls: true\n # Routing mode: \"subdomain\" or \"path\"\n # - subdomain: auth-server.domain.com, mcpregistry.domain.com, keycloak.domain.com\n # - path: domain.com/auth-server, domain.com/registry, domain.com/keycloak\n routingMode: subdomain\n # Path configuration (only used when routingMode: path)\n paths:\n authServer: /auth-server\n registry: /registry\n mcpgw: /mcpgw\n keycloak: /keycloak # make sure to update keycloak.httpRelativePath (/keycloak/)\n\nmongodb-kubernetes:\n operator:\n enableClusterMongoDBRoles: false\n telemetry:\n installClusterRole: false\n nodeSelector: {}\n\n# MongoDB configuration\nmongodb:\n enabled: true\n user: &mongoUser my-user # username for MongoDB\n password: &mongoPassword CHANGEME # Set the password for the MongoDB user\n database: &mongoDatabase mcp_registry\n existingPasswordSecret: \"\" # If set, skip creating my-user-password secret and use this name instead\n\n# Keycloak configuration\n# Set create: true to deploy Keycloak as part of this stack\n# Set create: false to use an external Keycloak instance\n# NOTE: When using Entra (global.authProvider.type: entra), set create: false\nkeycloak:\n create: true # Deploy Keycloak in this stack (set to false for external Keycloak or Entra)\n image:\n registry: public.ecr.aws\n\n global:\n security:\n allowInsecureImages: true\n\n auth:\n adminUser: *keycloakAdmin\n existingSecret: '{{ .Release.Name }}-keycloak'\n\n postgresql:\n auth:\n existingSecret: '{{ .Release.Name }}-keycloak-postgresql'\n image:\n registry: public.ecr.aws\n\n # HTTP relative path for path-based routing\n # IMPORTANT: This must match global.ingress.paths.keycloak when routingMode is \"path\"\n # For subdomain routing, set to \"/\"\n # IMPORTANT: This must have a trailing \"/\"\n httpRelativePath: /\n\n extraEnvVars:\n - name: KC_PROXY\n value: edge\n - name: KC_PROXY_HEADERS\n value: xforwarded\n\n ingress:\n enabled: false # We use a custom ingress template that supports global.domain\n\n nodeSelector: {}\n\n # Lifecycle hook to configure realm SSL settings\n lifecycleHooks:\n postStart:\n exec:\n command:\n - \"/bin/bash\"\n - \"-c\"\n - |\n (\n echo \"PostStart: Waiting for Keycloak to be ready...\"\n # Determine the base path - check if KC_HTTP_RELATIVE_PATH is set\n BASE_PATH=\"${KC_HTTP_RELATIVE_PATH:-}\"\n BASE_URL=\"http://localhost:8080${BASE_PATH}\"\n echo \"Using base URL: $BASE_URL\"\n for i in {1..120}; do\n if curl -sf ${BASE_URL}/realms/$KC_SPI_ADMIN_REALM > /dev/null 2>&1; then\n echo \"Keycloak ready after $i attempts\"\n break\n fi\n sleep 5\n done\n sleep 10\n echo \"Configuring $KC_SPI_ADMIN_REALM realm...\"\n /opt/bitnami/keycloak/bin/kcadm.sh config credentials \\\n --config /tmp/kcadm.config \\\n --server ${BASE_URL} \\\n --realm $KC_SPI_ADMIN_REALM \\\n --user $KC_BOOTSTRAP_ADMIN_USERNAME \\\n --password $(cat $KC_BOOTSTRAP_ADMIN_PASSWORD_FILE)\n /opt/bitnami/keycloak/bin/kcadm.sh update \\\n --config /tmp/kcadm.config \\\n realms/$KC_SPI_ADMIN_REALM \\\n -s sslRequired=NONE\n echo \"✓ $KC_SPI_ADMIN_REALM realm configured!\"\n ) > /tmp/poststart-config.log 2>&1 &\n\n# Keycloak configuration job\n# Automatically enabled when global.authProvider.type = \"keycloak\"\n# Set to false to skip configuration (e.g., when using pre-configured Keycloak)\n# NOTE: When using Entra (global.authProvider.type: entra), set enabled: false\nkeycloak-configure:\n enabled: true # Set to false to skip Keycloak configuration or when using Entra\n keycloak:\n realm: *keycloakRealm\n adminUser: *keycloakAdmin\n # authServer.externalUrl will be templated in the subchart using global.domain\n\n# Keycloak ingress for mcp-gateway-registry\n# Whether to create an ingress for Keycloak with this Chart (only applicable when keycloak.create: true)\nkeycloakIngress:\n enabled: true\n\n# Mongodb configuration job\nmongodb-configure:\n enabled: true # Whether to run the MongoDB configuration job\n mongodb:\n username: *mongoUser\n password: *mongoPassword\n database: *mongoDatabase\n\n# Registry service configuration\nregistry:\n app:\n replicas: 2 # set to > 1 replica for high availability\n # Deployment mode: with-gateway (nginx integration) or registry-only (catalog only)\n deploymentMode: with-gateway\n\n # Registry mode: full, skills-only, mcp-servers-only, agents-only\n registryMode: full\n\n # Tab visibility overrides (AND-ed with registryMode)\n showServersTab: true\n showVirtualServersTab: true\n showSkillsTab: true\n showAgentsTab: true\n\n # Federation OAuth2 authentication (alternative to static token)\n federationTokenEndpoint: \"\"\n federationClientId: \"\"\n federationClientSecret: \"\"\n\n # ASOR (Workday) federation integration\n asorAccessToken: \"\"\n workdayTokenUrl: \"\"\n\n # Skill security scanning configuration\n skillSecurityScanEnabled: true # Enable/disable skill security scanning\n skillSecurityAnalyzers: \"static\" # Comma-separated: static, behavioral, llm, meta, virustotal, ai-defense\n\n # Static API keys for registry path authentication (JSON string)\n registryApiKeys: \"\"\n registryApiKeysExistingSecret: \"\" # If set, read REGISTRY_API_KEYS from this K8s secret instead\n registryApiKeysExistingSecretKey: \"REGISTRY_API_KEYS\" # Key within the existing secret\n\n # Registration webhook (issue #742)\n registrationWebhookUrl: \"\"\n registrationWebhookAuthHeader: \"Authorization\"\n registrationWebhookAuthToken: \"\"\n registrationWebhookTimeoutSeconds: \"10\"\n\n # Registration gate / admission control (issue #809)\n registrationGateEnabled: false\n registrationGateUrl: \"\"\n registrationGateAuthType: \"none\"\n registrationGateAuthCredential: \"\"\n registrationGateAuthHeaderName: \"X-Api-Key\"\n registrationGateTimeoutSeconds: \"5\"\n registrationGateMaxRetries: \"2\"\n\n # M2M direct client registration (issue #851)\n # Exposes /api/iam/m2m-clients admin API for registering M2M client_ids and\n # their group mappings directly, without requiring an IdP Admin API token.\n m2mDirectRegistrationEnabled: true\n\n # OpenTelemetry direct OTLP push export configuration\n otelOtlpEndpoint: \"\" # OTLP endpoint URL (e.g., https://otlp.datadoghq.com)\n otelExporterOtlpHeaders: \"\" # OTLP headers (e.g., dd-api-key=YOUR_KEY)\n otelOtlpExportIntervalMs: \"30000\" # Export interval in milliseconds\n otelExporterOtlpMetricsTemporalityPreference: \"cumulative\" # cumulative or delta\n\n # Telemetry configuration\n # Anonymous usage telemetry (startup ping + daily heartbeat, both on by default)\n mcpTelemetryDisabled: false # Set to true to disable all telemetry\n mcpTelemetryOptOut: false # Set to true to disable daily heartbeat only (startup ping still sent)\n telemetryHeartbeatIntervalMinutes: \"1440\" # Heartbeat interval in minutes (default: 1440 = 24 hours)\n telemetryDebug: false # Set to true to log payloads instead of sending\n\n # Application Log Configuration (centralized log rotation and retrieval)\n # NOTE: Centralized logging is ON by default (appLogCentralizedEnabled: \"true\").\n # Set to \"false\" to disable writing application logs to centralized store for the /admin/logs API.\n # Anchor &appLogConfig is reused by auth-server below to keep values in sync.\n <<: &appLogConfig\n appLogMaxBytes: \"52428800\" # Max size per log file before rotation (default 50 MB)\n appLogBackupCount: \"5\" # Number of rotated backup log files to keep\n appLogCentralizedEnabled: \"true\" # Write application logs to centralized store (requires MongoDB backend)\n appLogCentralizedTtlDays: \"1\" # Days to retain log entries in centralized store (TTL index)\n appLogMongodbBufferSize: \"50\" # Records to buffer before flushing to MongoDB\n appLogMongodbFlushIntervalSeconds: \"5.0\" # Seconds between periodic flushes\n appLogLevel: \"INFO\" # Application log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n appLogExcludedLoggers: \"uvicorn.access,httpx,pymongo,motor\" # Comma-separated logger names to exclude from MongoDB\n\n # Demo server configuration\n disableAiRegistryToolsServer: false # Set to true to disable auto-registration of the built-in airegistry-tools server\n\n # AWS Agent Registry Federation\n awsRegistry:\n federationEnabled: false # Enable AWS Agent Registry federation (overrides MongoDB config on startup)\n\n # ANS (Agent Name Service) Integration\n ans:\n enabled: false # Enable ANS integration for trust verification\n apiEndpoint: \"https://api.godaddy.com\" # ANS API base URL\n apiKey: \"\" # GoDaddy API key (required when enabled)\n apiSecret: \"\" # GoDaddy API secret (required when enabled)\n apiTimeoutSeconds: \"30\" # HTTP request timeout for ANS API calls\n syncIntervalHours: \"6\" # Background re-verification interval\n verificationCacheTtlSeconds: \"3600\" # Cache TTL for verification results\n\n # Registry Card Configuration (for federation and discovery)\n registryCard:\n url: \"\" # External URL of the registry (defaults to computed ingress URL)\n name: \"AI Registry\" # Human-readable name\n organizationName: \"\" # Organization operating the registry\n description: \"\" # Optional description\n contactEmail: \"\" # Optional contact email\n contactUrl: \"\" # Optional contact URL/website\n\n # IdP group filtering (applies to all identity providers)\n # When set, only groups whose name starts with any of these prefixes are shown in IAM > Groups\n # Example: \"mcp-,registry-,ai-\"\n idpGroupFilterPrefix: \"\"\n\n ingress:\n enabled: true\n ingressClassName: alb\n\n nodeSelector: {}\n\n# MCPGW MCP server configuration\nmcpgw:\n enabled: true # Set to true to deploy the MCPGW MCP server\n app:\n replicas: 1\n\n # Embeddings configuration\n embeddingsProvider: sentence-transformers\n embeddingsModelName: all-MiniLM-L6-v2\n embeddingsModelDimensions: \"384\"\n\n ingress:\n enabled: true\n ingressClassName: alb\n\n nodeSelector: {}\n\n# Auth server configuration\nauth-server:\n app:\n replicas: 2 # set to > 1 replica for high availability\n oauthStoreTokensInSession: false # Store OAuth tokens in session (default: false)\n # Internal JWT configuration\n jwtIssuer: \"mcp-auth-server\" # Issuer claim for internal JWT tokens\n jwtAudience: \"mcp-registry\" # Audience claim for internal JWT tokens\n # Static token authentication (alternative to IdP JWT for Registry API)\n registryStaticTokenAuthEnabled: false\n registryApiToken: \"\"\n # Rate limiting\n maxTokensPerUserPerHour: \"100\"\n\n # Application Log Configuration - reuses anchor from registry.app above\n <<: *appLogConfig\n\n keycloak:\n enabled: true\n realm: *keycloakRealm\n m2mClientId: \"\" # Optional: M2M client ID\n m2mClientSecret: \"\" # Optional: M2M client secret\n # externalUrl will be templated in the subchart using global.domain\n\n # Entra ID settings (used when global.authProvider.type = \"entra\")\n entra:\n clientId: \"\"\n clientSecret: \"\"\n tenantId: \"\"\n loginBaseUrl: \"\" # Custom Entra login base URL for sovereign clouds\n\n # Okta settings (used when global.authProvider.type = \"okta\")\n okta:\n domain: \"\" # e.g., dev-123456.okta.com\n clientId: \"\"\n clientSecret: \"\"\n m2mClientId: \"\" # Optional: defaults to clientId\n m2mClientSecret: \"\" # Optional: defaults to clientSecret\n apiToken: \"\" # Optional: required for IAM operations\n authServerId: \"\" # Optional: uses default Org Authorization Server if not set\n\n # Auth0 settings (used when global.authProvider.type = \"auth0\")\n auth0:\n domain: \"\" # e.g., your-tenant.us.auth0.com\n clientId: \"\"\n clientSecret: \"\"\n audience: \"\" # Optional: API audience for M2M tokens\n groupsClaim: \"https://mcp-gateway/groups\"\n m2mClientId: \"\"\n m2mClientSecret: \"\"\n managementApiToken: \"\" # Optional: alternative to M2M credentials (expires after 24h)\n\n # Cognito settings (used when global.authProvider.type = \"cognito\")\n cognito:\n userPoolId: \"\"\n clientId: \"\"\n clientSecret: \"\"\n domain: \"\" # Optional: custom Cognito domain\n region: \"us-east-1\"\n\n ingress:\n enabled: true\n ingressClassName: alb\n\n nodeSelector: {}\n" }, { "path": "charts/mcpgw/Chart.yaml", "content": "apiVersion: v2\nname: mcpgw\ndescription: A Helm chart for the MCPGW MCP server with embeddings support\ntype: application\nversion: 0.1.0\nappVersion: \"1.0.0\"\n" }, { "path": "charts/mcpgw/templates/deployment.yaml", "content": "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\nspec:\n replicas: {{ .Values.app.replicas }}\n selector:\n matchLabels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n template:\n metadata:\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n spec:\n {{- with .Values.nodeSelector }}\n nodeSelector:\n {{- toYaml . | nindent 8 }}\n {{- end }}\n securityContext:\n runAsNonRoot: true\n runAsUser: 1000\n runAsGroup: 1000\n fsGroup: 1000\n containers:\n - name: {{ .Values.app.name }}\n image: \"{{ .Values.global.image.repository }}:{{ .Values.global.image.tag }}\"\n imagePullPolicy: {{ .Values.global.image.pullPolicy }}\n securityContext:\n allowPrivilegeEscalation: false\n capabilities:\n drop:\n - ALL\n ports:\n - containerPort: {{ .Values.app.port }}\n name: http\n resources:\n {{- toYaml .Values.resources | nindent 12 }}\n envFrom:\n - secretRef:\n name: {{ .Values.app.existingSecret | default .Values.app.envSecretName }}\n {{- if .Values.global.sharedSecretName }}\n - secretRef:\n name: {{ .Values.global.existingSharedSecret | default .Values.global.sharedSecretName }}\n {{- end }}\n env:\n - name: HOST\n value: 0.0.0.0\n {{- if .Values.app.embeddingsApiKeyExistingSecret }}\n - name: EMBEDDINGS_API_KEY\n valueFrom:\n secretKeyRef:\n name: {{ .Values.app.embeddingsApiKeyExistingSecret }}\n key: {{ .Values.app.embeddingsApiKeyExistingSecretKey }}\n {{- end }}\n {{- /* GitHub private repo auth (SKILL.md fetching) */}}\n {{- if .Values.app.githubAppId }}\n - name: GITHUB_APP_ID\n value: {{ .Values.app.githubAppId | quote }}\n {{- end }}\n {{- if .Values.app.githubAppInstallationId }}\n - name: GITHUB_APP_INSTALLATION_ID\n value: {{ .Values.app.githubAppInstallationId | quote }}\n {{- end }}\n {{- if .Values.app.githubExtraHosts }}\n - name: GITHUB_EXTRA_HOSTS\n value: {{ .Values.app.githubExtraHosts | quote }}\n {{- end }}\n {{- if ne .Values.app.githubApiBaseUrl \"https://api.github.com\" }}\n - name: GITHUB_API_BASE_URL\n value: {{ .Values.app.githubApiBaseUrl | quote }}\n {{- end }}\n {{- if .Values.app.githubPatExistingSecret }}\n - name: GITHUB_PAT\n valueFrom:\n secretKeyRef:\n name: {{ .Values.app.githubPatExistingSecret }}\n key: {{ .Values.app.githubPatExistingSecretKey }}\n {{- else if .Values.app.githubPat }}\n - name: GITHUB_PAT\n value: {{ .Values.app.githubPat | quote }}\n {{- end }}\n {{- if .Values.app.githubAppPrivateKeyExistingSecret }}\n - name: GITHUB_APP_PRIVATE_KEY\n valueFrom:\n secretKeyRef:\n name: {{ .Values.app.githubAppPrivateKeyExistingSecret }}\n key: {{ .Values.app.githubAppPrivateKeyExistingSecretKey }}\n {{- else if .Values.app.githubAppPrivateKey }}\n - name: GITHUB_APP_PRIVATE_KEY\n value: {{ .Values.app.githubAppPrivateKey | quote }}\n {{- end }}\n livenessProbe:\n tcpSocket:\n port: 8000\n initialDelaySeconds: 30\n periodSeconds: 10\n readinessProbe:\n tcpSocket:\n port: 8000\n initialDelaySeconds: 10\n periodSeconds: 5\n" }, { "path": "charts/mcpgw/templates/ingress.yaml", "content": "{{- if .Values.ingress.enabled }}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $domain := .Values.global.domain | default .Values.ingress.hostname }}\n{{- $pathPrefix := .Values.global.ingress.paths.mcpgw | default .Values.ingress.path | default \"/mcpgw\" }}\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n annotations:\n {{- if eq $routingMode \"path\" }}\n alb.ingress.kubernetes.io/group.name: mcp-gateway-stack\n alb.ingress.kubernetes.io/group.order: '40'\n {{- end }}\n alb.ingress.kubernetes.io/healthcheck-path: /mcp/\n alb.ingress.kubernetes.io/listen-ports: '[{\"HTTPS\": 443}]'\n alb.ingress.kubernetes.io/scheme: internet-facing\n alb.ingress.kubernetes.io/ssl-redirect: '443'\n alb.ingress.kubernetes.io/target-type: ip\n alb.ingress.kubernetes.io/success-codes: 200,302,307\n {{- if .Values.global.ingress.inboundCidrs }}\n alb.ingress.kubernetes.io/inbound-cidrs: {{ .Values.global.ingress.inboundCidrs }}\n {{- end }}\nspec:\n ingressClassName: {{ .Values.ingress.className }}\n rules:\n {{- if eq $routingMode \"path\" }}\n - host: {{ $domain | quote }}\n http:\n paths:\n - path: {{ $pathPrefix }}\n pathType: Prefix\n backend:\n service:\n name: {{ .Values.app.name }}\n port:\n name: http\n {{- else }}\n - host: {{ printf \"mcpgw.%s\" $domain | quote }}\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: {{ .Values.app.name }}\n port:\n name: http\n {{- end }}\n{{- end }}\n" }, { "path": "charts/mcpgw/templates/secret.yaml", "content": "{{- if and .Values.app.embeddingsApiKey .Values.app.embeddingsApiKeyExistingSecret }}\n {{- fail \"Cannot set both app.embeddingsApiKey and app.embeddingsApiKeyExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if not .Values.app.existingSecret }}\n{{- $registryUrl := .Values.app.registryUrl }}\n{{- if .Values.global.domain }}\n {{- $registryUrl = printf \"http://registry.%s.svc.cluster.local:8000\" .Release.Namespace }}\n{{- end }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: {{ .Values.app.envSecretName }}\n namespace: {{ .Release.Namespace | quote }}\ndata:\n PORT: {{ .Values.app.port | toString | b64enc | quote }}\n REGISTRY_BASE_URL: {{ $registryUrl | b64enc | quote }}\n EMBEDDINGS_PROVIDER: {{ .Values.app.embeddingsProvider | b64enc | quote }}\n EMBEDDINGS_MODEL_NAME: {{ .Values.app.embeddingsModelName | b64enc | quote }}\n EMBEDDINGS_MODEL_DIMENSIONS: {{ .Values.app.embeddingsModelDimensions | b64enc | quote }}\n {{- if and .Values.app.embeddingsApiKey (not .Values.app.embeddingsApiKeyExistingSecret) }}\n EMBEDDINGS_API_KEY: {{ .Values.app.embeddingsApiKey | b64enc | quote }}\n {{- end }}\n {{- if .Values.app.embeddingsApiBase }}\n EMBEDDINGS_API_BASE: {{ .Values.app.embeddingsApiBase | b64enc | quote }}\n {{- end }}\n EMBEDDINGS_AWS_REGION: {{ .Values.app.embeddingsAwsRegion | b64enc | quote }}\n{{- if not .Values.global.sharedSecretName }}\n {{/* SECRET_KEY managed per-chart in standalone deployment */}}\n SECRET_KEY: {{ required \"app.secretKey or global.secretKey is required for standalone deployment\" (.Values.global.secretKey | default .Values.app.secretKey) | b64enc | quote }}\n{{- end }}\n{{- end }}\n" }, { "path": "charts/mcpgw/templates/service.yaml", "content": "apiVersion: v1\nkind: Service\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n {{- with .Values.service.annotations }}\n annotations:\n {{- toYaml . | nindent 4 }}\n {{- end }}\nspec:\n type: {{ .Values.service.type }}\n ports:\n - port: {{ .Values.service.port }}\n targetPort: http\n protocol: TCP\n name: http\n selector:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n" }, { "path": "charts/mcpgw/values.yaml", "content": "# Global configuration\nglobal:\n image:\n repository: public.ecr.aws/p3v1o3c6/mcpgw\n tag: 1.0.21\n pullPolicy: IfNotPresent\n\n# Application configuration\napp:\n name: mcpgw-server\n replicas: 1\n envSecretName: mcpgw-secret\n existingSecret: \"\" # If set, use this existing secret instead of creating one\n port: 8000\n\n # Registry connection\n registryUrl: http://registry:8080\n\n # Security settings\n # secretKey: Required for standalone deployment (not needed when deployed via stack).\n # When deployed via mcp-gateway-registry-stack, SECRET_KEY comes from the shared secret.\n # Uncomment to use a specific key:\n # secretKey: \"your-secure-key-here\"\n\n # Embeddings configuration\n embeddingsProvider: sentence-transformers\n embeddingsModelName: all-MiniLM-L6-v2\n embeddingsModelDimensions: \"384\"\n embeddingsApiKey: \"\"\n embeddingsApiKeyExistingSecret: \"\" # If set, read EMBEDDINGS_API_KEY from this K8s secret instead of embeddingsApiKey\n embeddingsApiKeyExistingSecretKey: \"EMBEDDINGS_API_KEY\" # Key within the existing secret\n embeddingsApiBase: \"\"\n embeddingsAwsRegion: us-east-1\n\n # GitHub private repo auth (SKILL.md fetching)\n githubPat: \"\"\n githubPatExistingSecret: \"\" # If set, read GITHUB_PAT from this K8s secret\n githubPatExistingSecretKey: \"GITHUB_PAT\"\n githubAppId: \"\"\n githubAppInstallationId: \"\"\n githubAppPrivateKey: \"\"\n githubAppPrivateKeyExistingSecret: \"\" # If set, read GITHUB_APP_PRIVATE_KEY from this K8s secret\n githubAppPrivateKeyExistingSecretKey: \"GITHUB_APP_PRIVATE_KEY\"\n githubExtraHosts: \"\"\n githubApiBaseUrl: \"https://api.github.com\"\n\n# Service configuration\nservice:\n type: ClusterIP\n port: 8003\n annotations: {}\n\n# Resource limits and requests\nresources:\n requests:\n cpu: 500m\n memory: 1Gi\n limits:\n cpu: 1\n memory: 2Gi\n\n# Ingress configuration\ningress:\n enabled: false\n className: alb\n hostname: \"\"\n annotations: {}\n tls: false\n # Routing mode: \"subdomain\" or \"path\"\n # - subdomain: mcpgw.domain.com\n # - path: domain.com/mcpgw\n routingMode: subdomain\n # Path prefix when using path-based routing (default: /mcpgw)\n path: /mcpgw\n\nnodeSelector: {}\n" }, { "path": "charts/mongodb-configure/Chart.yaml", "content": "apiVersion: v2\nname: mongodb-configure\ndescription: A Helm chart for configuring MongoDB\ntype: application\nversion: 0.1.0\nappVersion: \"1.0.0\"\n" }, { "path": "charts/mongodb-configure/templates/configmap.yaml", "content": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: setup-mongodb\n namespace: {{ .Release.Namespace | quote }}\ndata:\n registry-admins.json: |\n {\n \"_id\": \"registry-admins\",\n \"group_mappings\": [\n \"registry-admins\"{{ if eq .Values.global.authProvider.type \"entra\"}}{{ printf \", %s\" (.Values.global.authProvider.entra.adminGroupId | quote) }}{{ end }}\n\n ],\n \"server_access\": [\n {\n \"server\": \"*\",\n \"methods\": [\"all\"],\n \"tools\": [\"all\"]\n },\n {\n \"agents\": {\n \"actions\": [\n {\"action\": \"list_agents\", \"resources\": [\"all\"]},\n {\"action\": \"get_agent\", \"resources\": [\"all\"]},\n {\"action\": \"publish_agent\", \"resources\": [\"all\"]},\n {\"action\": \"modify_agent\", \"resources\": [\"all\"]},\n {\"action\": \"delete_agent\", \"resources\": [\"all\"]}\n ]\n }\n }\n ],\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"get_agent\": [\"all\"],\n \"publish_agent\": [\"all\"],\n \"modify_agent\": [\"all\"],\n \"delete_agent\": [\"all\"],\n \"list_service\": [\"all\"],\n \"register_service\": [\"all\"],\n \"health_check_service\": [\"all\"],\n \"toggle_service\": [\"all\"],\n \"modify_service\": [\"all\"],\n \"delete_service\": [\"all\"]\n }\n }\n\n wait.py: |\n import pymongo\n import os\n import time\n import sys\n\n MONGO_HOST = os.getenv(\"DOCUMENTDB_HOST\", \"mongodb\")\n MONGO_PORT = os.getenv(\"DOCUMENTDB_PORT\", \"27017\")\n REPLICA_SET = os.getenv(\"DOCUMENTDB_REPLICA_SET\", \"rs0\")\n USERNAME = os.getenv(\"DOCUMENTDB_USERNAME\", \"\")\n PASSWORD = os.getenv(\"DOCUMENTDB_PASSWORD\", \"\")\n\n def wait_for_mongodb():\n while True:\n try:\n # First check basic connectivity\n client = pymongo.MongoClient(f\"mongodb://{USERNAME}:{PASSWORD}@{MONGO_HOST}:{MONGO_PORT}/?authMechanism=SCRAM-SHA-256&authSource=admin\",\n serverSelectionTimeoutMS=5000,\n connectTimeoutMS=5000)\n client.admin.command('ping')\n print(\"MongoDB is accepting connections. Checking replica set status...\")\n\n # Check replica set status\n status = client.admin.command('replSetGetStatus')\n\n if status['ok'] != 1:\n print(\"Replica set not initialized yet\")\n time.sleep(10)\n continue\n\n ready_members = [m for m in status['members'] if m['state'] in [1, 2]] # PRIMARY or SECONDARY\n total_members = len(status['members'])\n\n if len(ready_members) == total_members:\n print(f\"All replica set members are ready ({len(ready_members)}/{total_members})\")\n break\n else:\n print(f\"Waiting for replica set members: {len(ready_members)}/{total_members} ready\")\n time.sleep(10)\n\n except Exception as e:\n print(f\"MongoDB not ready yet: {e}\")\n time.sleep(5)\n finally:\n try:\n client.close()\n except:\n pass\n\n wait_for_mongodb()\n print(\"MongoDB replica set is fully ready!\")\n\n mcp-registry-admin.json: |\n {\n \"_id\": \"mcp-registry-admin\",\n \"group_mappings\": [\"mcp-registry-admin\", \"mcp-servers-unrestricted/read\", \"mcp-servers-unrestricted/execute\"],\n \"server_access\": [\n {\n \"server\": \"*\",\n \"methods\": [\"all\"],\n \"tools\": [\"all\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"tokens\", \"GET\", \"POST\"]\n }\n ],\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"get_agent\": [\"all\"],\n \"publish_agent\": [\"all\"],\n \"modify_agent\": [\"all\"],\n \"delete_agent\": [\"all\"],\n \"list_service\": [\"all\"],\n \"register_service\": [\"all\"],\n \"health_check_service\": [\"all\"],\n \"toggle_service\": [\"all\"],\n \"modify_service\": [\"all\"],\n \"delete_service\": [\"all\"]\n }\n }\n\n mcp-servers-unrestricted-execute.json: |\n {\n \"_id\": \"mcp-servers-unrestricted/execute\",\n \"group_mappings\": [],\n \"server_access\": [\n {\n \"server\": \"*\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\", \"GET\", \"POST\", \"PUT\", \"DELETE\"],\n \"tools\": \"*\"\n },\n {\n \"server\": \"api\",\n \"methods\": [\"tokens\", \"GET\", \"POST\"]\n }\n ]\n }\n\n mcp-servers-unrestricted-read.json: |\n {\n \"_id\": \"mcp-servers-unrestricted/read\",\n \"group_mappings\": [],\n \"server_access\": [\n {\n \"server\": \"*\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\", \"GET\"],\n \"tools\": \"*\"\n },\n {\n \"server\": \"api\",\n \"methods\": [\"tokens\", \"GET\"]\n }\n ]\n }\n\n script.py: |\n #!/usr/bin/env python3\n \"\"\"\n Initialize MongoDB CE for local development.\n\n This script:\n 1. Initializes replica set (rs0)\n 2. Creates collections and indexes\n 3. Loads default admin scope from registry-admins.json\n\n Usage:\n python init-mongodb-ce.py\n \"\"\"\n\n import asyncio\n import json\n import logging\n import os\n import sys\n import time\n from pathlib import Path\n from typing import Optional\n\n from motor.motor_asyncio import AsyncIOMotorClient\n from pymongo import ASCENDING\n from pymongo.errors import ServerSelectionTimeoutError, OperationFailure\n\n\n # Configure logging with basicConfig\n logging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n )\n logger = logging.getLogger(__name__)\n\n\n # Collection names\n COLLECTION_SERVERS = \"mcp_servers\"\n COLLECTION_AGENTS = \"mcp_agents\"\n COLLECTION_SCOPES = \"mcp_scopes\"\n COLLECTION_EMBEDDINGS = \"mcp_embeddings_1536\"\n COLLECTION_SECURITY_SCANS = \"mcp_security_scans\"\n COLLECTION_FEDERATION_CONFIG = \"mcp_federation_config\"\n COLLECTION_AUDIT_EVENTS = \"audit_events\"\n\n\n def _get_config_from_env() -> dict:\n \"\"\"Get MongoDB CE configuration from environment variables.\"\"\"\n return {\n \"host\": os.getenv(\"DOCUMENTDB_HOST\", \"mongodb\"),\n \"port\": int(os.getenv(\"DOCUMENTDB_PORT\", \"27017\")),\n \"database\": os.getenv(\"DOCUMENTDB_DATABASE\", \"mcp_registry\"),\n \"namespace\": os.getenv(\"DOCUMENTDB_NAMESPACE\", \"default\"),\n \"username\": os.getenv(\"DOCUMENTDB_USERNAME\", \"\"),\n \"password\": os.getenv(\"DOCUMENTDB_PASSWORD\", \"\"),\n \"replicaset\": os.getenv(\"DOCUMENTDB_REPLICA_SET\", \"rs0\"),\n }\n\n\n def _initialize_replica_set(\n host: str,\n port: int,\n username: str,\n password: str,\n ) -> None:\n \"\"\"Initialize MongoDB replica set using pymongo (synchronous).\"\"\"\n from pymongo import MongoClient\n\n logger.info(\"Initializing MongoDB replica set...\")\n\n try:\n # Connect without replica set for initialization\n client = MongoClient(\n f\"mongodb://{username}:{password}@{host}:{port}/?authMechanism=SCRAM-SHA-256&authSource=admin\",\n serverSelectionTimeoutMS=5000,\n directConnection=True,\n )\n\n # Check if already initialized\n try:\n status = client.admin.command(\"replSetGetStatus\")\n logger.info(\"Replica set already initialized\")\n client.close()\n return\n except OperationFailure as e:\n if \"no replset config has been received\" in str(e).lower():\n # Not initialized, proceed\n pass\n else:\n raise\n\n # Initialize replica set\n config = {\n \"_id\": \"rs0\",\n \"members\": [\n {\"_id\": 0, \"host\": f\"{host}:{port}\"}\n ]\n }\n\n result = client.admin.command(\"replSetInitiate\", config)\n logger.info(f\"Replica set initialized: {result}\")\n client.close()\n\n # Wait for replica set to elect primary\n logger.info(\"Waiting for replica set to elect primary...\")\n time.sleep(10)\n\n except Exception as e:\n logger.error(f\"Error initializing replica set: {e}\")\n raise\n\n\n async def _create_standard_indexes(\n collection,\n collection_name: str,\n namespace: str,\n ) -> None:\n \"\"\"Create standard indexes for collections.\"\"\"\n full_name = f\"{collection_name}_{namespace}\"\n\n if collection_name == COLLECTION_SERVERS:\n # Note: path is stored as _id, so no separate path index needed\n await collection.create_index([(\"enabled\", ASCENDING)])\n await collection.create_index([(\"tags\", ASCENDING)])\n await collection.create_index([(\"manifest.serverInfo.name\", ASCENDING)])\n logger.info(f\"Created indexes for {full_name}\")\n\n elif collection_name == COLLECTION_AGENTS:\n # Note: path is stored as _id, so no separate path index needed\n await collection.create_index([(\"enabled\", ASCENDING)])\n await collection.create_index([(\"tags\", ASCENDING)])\n await collection.create_index([(\"card.name\", ASCENDING)])\n logger.info(f\"Created indexes for {full_name}\")\n\n elif collection_name == COLLECTION_SCOPES:\n # No additional indexes needed - scopes use _id as primary key\n # group_mappings is an array, not indexed\n logger.info(f\"Created indexes for {full_name}\")\n\n elif collection_name == COLLECTION_EMBEDDINGS:\n # Note: path is stored as _id, so no separate path index needed\n await collection.create_index([(\"entity_type\", ASCENDING)])\n logger.info(f\"Created indexes for {full_name} (vector search via app code)\")\n\n elif collection_name == COLLECTION_SECURITY_SCANS:\n await collection.create_index([(\"server_path\", ASCENDING)])\n await collection.create_index([(\"scan_status\", ASCENDING)])\n await collection.create_index([(\"scanned_at\", ASCENDING)])\n logger.info(f\"Created indexes for {full_name}\")\n\n elif collection_name == COLLECTION_FEDERATION_CONFIG:\n await collection.create_index([(\"registry_name\", ASCENDING)], unique=True)\n await collection.create_index([(\"enabled\", ASCENDING)])\n logger.info(f\"Created indexes for {full_name}\")\n\n elif collection_name == COLLECTION_AUDIT_EVENTS:\n # Indexes for audit event queries (Requirements 6.2)\n # Note: timestamp index is created as TTL index below, so we use compound indexes here\n await collection.create_index([(\"identity.username\", ASCENDING), (\"timestamp\", ASCENDING)])\n await collection.create_index([(\"action.operation\", ASCENDING), (\"timestamp\", ASCENDING)])\n await collection.create_index([(\"action.resource_type\", ASCENDING), (\"timestamp\", ASCENDING)])\n await collection.create_index([(\"request_id\", ASCENDING)], unique=True)\n\n # TTL index for automatic expiration (Requirements 6.3)\n # This also serves as the timestamp index for sorting\n # Default 7 days (604800 seconds), configurable via AUDIT_LOG_MONGODB_TTL_DAYS\n ttl_days = int(os.getenv(\"AUDIT_LOG_MONGODB_TTL_DAYS\", \"7\"))\n ttl_seconds = ttl_days * 24 * 60 * 60\n await collection.create_index(\n [(\"timestamp\", ASCENDING)],\n expireAfterSeconds=ttl_seconds,\n name=\"timestamp_ttl\"\n )\n logger.info(f\"Created indexes for {full_name} (TTL: {ttl_days} days)\")\n\n async def _load_default_scopes(\n db,\n namespace: str,\n ) -> None:\n \"\"\"Load default scopes from JSON files into scopes collection.\n\n This loads all scope JSON files from the scripts directory:\n - registry-admins.json: Bootstrap admin scope with full permissions\n - mcp-registry-admin.json: MCP registry admin scope (Keycloak group)\n - mcp-servers-unrestricted-read.json: Read-only access to all servers\n - mcp-servers-unrestricted-execute.json: Full CRUD access to all servers\n \"\"\"\n collection_name = f\"{COLLECTION_SCOPES}_{namespace}\"\n collection = db[collection_name]\n\n # Find scope files in the same directory as this script\n script_dir = Path(__file__).parent\n\n # List of scope files to load (order matters - base scopes first)\n scope_files = [\n \"registry-admins.json\",\n \"mcp-registry-admin.json\",\n \"mcp-servers-unrestricted-read.json\",\n \"mcp-servers-unrestricted-execute.json\",\n ]\n\n loaded_count = 0\n for scope_filename in scope_files:\n scope_file = script_dir / scope_filename\n\n if not scope_file.exists():\n logger.warning(f\"Scope file not found: {scope_file}\")\n continue\n\n try:\n with open(scope_file, \"r\") as f:\n scope_data = json.load(f)\n\n logger.info(f\"Loading scope from {scope_filename}\")\n\n # Upsert the scope document\n result = await collection.update_one(\n {\"_id\": scope_data[\"_id\"]},\n {\"$set\": scope_data},\n upsert=True\n )\n\n if result.upserted_id:\n logger.info(f\"Inserted scope: {scope_data['_id']}\")\n loaded_count += 1\n elif result.modified_count > 0:\n logger.info(f\"Updated scope: {scope_data['_id']}\")\n loaded_count += 1\n else:\n logger.info(f\"Scope already up-to-date: {scope_data['_id']}\")\n\n if \"group_mappings\" in scope_data:\n logger.info(\n f\" group_mappings: {scope_data.get('group_mappings', [])}\"\n )\n\n except Exception as e:\n logger.error(f\"Failed to load scope from {scope_filename}: {e}\", exc_info=True)\n\n logger.info(f\"Loaded {loaded_count} scopes into {collection_name}\")\n\n\n async def _initialize_mongodb_ce() -> None:\n \"\"\"Main initialization function.\"\"\"\n config = _get_config_from_env()\n\n logger.info(\"=\" * 60)\n logger.info(\"MongoDB CE Initialization for MCP Gateway\")\n logger.info(\"=\" * 60)\n logger.info(f\"Host: {config['host']}:{config['port']}\")\n logger.info(f\"Database: {config['database']}\")\n logger.info(f\"Namespace: {config['namespace']}\")\n logger.info(\"\")\n\n # Wait for MongoDB to be ready\n logger.info(\"Waiting for MongoDB to be ready...\")\n time.sleep(10)\n\n # Initialize replica set (synchronous)\n _initialize_replica_set(config[\"host\"], config[\"port\"], config[\"username\"], config[\"password\"])\n\n # Connect with motor for async operations\n connection_string = f\"mongodb://{config['username']}:{config['password']}@{config['host']}:{config['port']}/{config['database']}?replicaSet={config['replicaset']}&authMechanism=SCRAM-SHA-256&authSource=admin\"\n try:\n client = AsyncIOMotorClient(\n connection_string,\n serverSelectionTimeoutMS=10000,\n )\n\n # Verify connection\n await client.admin.command(\"ping\")\n logger.info(\"Connected to MongoDB successfully\")\n\n db = client[config[\"database\"]]\n namespace = config[\"namespace\"]\n\n # Create collections and indexes\n logger.info(\"Creating collections and indexes...\")\n\n collections = [\n COLLECTION_SERVERS,\n COLLECTION_AGENTS,\n COLLECTION_SCOPES,\n COLLECTION_EMBEDDINGS,\n COLLECTION_SECURITY_SCANS,\n COLLECTION_FEDERATION_CONFIG,\n COLLECTION_AUDIT_EVENTS,\n ]\n\n for coll_name in collections:\n full_name = f\"{coll_name}_{namespace}\"\n\n # Check if collection already exists\n existing_collections = await db.list_collection_names()\n\n if full_name in existing_collections:\n logger.info(f\"Collection {full_name} already exists, skipping creation\")\n else:\n logger.info(f\"Creating collection: {full_name}\")\n await db.create_collection(full_name)\n\n # Create indexes (idempotent - MongoDB handles duplicates)\n collection = db[full_name]\n await _create_standard_indexes(collection, coll_name, namespace)\n\n # Load default admin scope\n await _load_default_scopes(db, namespace)\n\n logger.info(\"\")\n logger.info(\"=\" * 60)\n logger.info(\"MongoDB CE Initialization Complete!\")\n logger.info(\"=\" * 60)\n logger.info(\"Collections created:\")\n for coll_name in collections:\n if coll_name == COLLECTION_EMBEDDINGS:\n logger.info(f\" - {coll_name}_{namespace} (with vector search)\")\n elif coll_name == COLLECTION_AUDIT_EVENTS:\n ttl_days = int(os.getenv(\"AUDIT_LOG_MONGODB_TTL_DAYS\", \"7\"))\n logger.info(f\" - {coll_name}_{namespace} (TTL: {ttl_days} days)\")\n else:\n logger.info(f\" - {coll_name}_{namespace}\")\n logger.info(\"\")\n logger.info(\"To use MongoDB CE:\")\n logger.info(\" export STORAGE_BACKEND=mongodb-ce\")\n logger.info(\" docker-compose up registry\")\n logger.info(\"\")\n logger.info(\"Or for AWS DocumentDB:\")\n logger.info(\" export STORAGE_BACKEND=documentdb\")\n logger.info(\" docker-compose up registry\")\n logger.info(\"=\" * 60)\n\n client.close()\n\n except ServerSelectionTimeoutError as e:\n logger.error(f\"Failed to connect to MongoDB: {e}\")\n logger.error(\"Make sure MongoDB is running and accessible\")\n sys.exit(1)\n except Exception as e:\n logger.error(f\"Error during initialization: {e}\")\n raise\n\n\n def main() -> None:\n \"\"\"Entry point.\"\"\"\n asyncio.run(_initialize_mongodb_ce())\n\n\n if __name__ == \"__main__\":\n main()\n" }, { "path": "charts/mongodb-configure/templates/job.yaml", "content": "{{- $existingSecret := .Values.mongodb.existingSecret | default .Values.global.existingMongoCredentialsSecret }}\napiVersion: batch/v1\nkind: Job\nmetadata:\n name: setup-mongodb\n namespace: {{ .Release.Namespace | quote }}\nspec:\n template:\n spec:\n initContainers:\n - name: wait-for-mongodb\n image: public.ecr.aws/docker/library/python:3.13-slim\n command: ['sh', '-c']\n envFrom:\n - secretRef:\n name: {{ $existingSecret | default \"mongo-credentials\" }}\n args:\n - |\n echo \"Installing pymongo...\"\n pip install --no-cache-dir pymongo\n \n echo \"Waiting for MongoDB replica set to be ready...\"\n python3 /app/wait.py\n volumeMounts:\n - mountPath: /app/wait.py\n name: script\n subPath: wait.py\n containers:\n - name: job\n image: public.ecr.aws/docker/library/python:3.13-slim\n command: [\"/bin/sh\", \"-c\"]\n args: [\n \"pip install --no-cache-dir pyyaml motor && python /app/script.py\"\n ]\n envFrom:\n - secretRef:\n name: {{ $existingSecret | default \"mongo-credentials\" }}\n volumeMounts:\n - mountPath: /app/script.py\n name: script\n subPath: script.py\n - mountPath: /app/registry-admins.json\n name: script\n subPath: registry-admins.json\n - mountPath: /app/mcp-registry-admin.json\n name: script\n subPath: mcp-registry-admin.json\n - mountPath: /app/mcp-servers-unrestricted-execute.json\n name: script\n subPath: mcp-servers-unrestricted-execute.json\n - mountPath: /app/mcp-servers-unrestricted-read.json\n name: script\n subPath: mcp-servers-unrestricted-read.json\n restartPolicy: Never\n volumes:\n - name: script\n configMap:\n name: setup-mongodb\n backoffLimit: 4\n" }, { "path": "charts/mongodb-configure/templates/secret.yaml", "content": "{{- $existingSecret := .Values.mongodb.existingSecret | default .Values.global.existingMongoCredentialsSecret }}\n{{- if not $existingSecret }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: mongo-credentials\n namespace: {{ .Release.Namespace | quote }}\ndata:\n DOCUMENTDB_DATABASE: {{.Values.mongodb.database | b64enc | quote}}\n DOCUMENTDB_HOST: {{ if contains \".\" .Values.mongodb.host }}{{ .Values.mongodb.host | b64enc | quote }}{{ else }}{{ printf \"%s.%s.svc.cluster.local\" .Values.mongodb.host .Release.Namespace | b64enc | quote }}{{ end }}\n DOCUMENTDB_NAMESPACE: {{.Values.mongodb.namespace | b64enc | quote}}\n DOCUMENTDB_PASSWORD: {{.Values.mongodb.password | b64enc | quote}}\n DOCUMENTDB_PORT: {{.Values.mongodb.port | toString | b64enc | quote}}\n DOCUMENTDB_REPLICA_SET: {{.Values.mongodb.replica_set | b64enc | quote}}\n DOCUMENTDB_USERNAME: {{.Values.mongodb.username | b64enc | quote}}\n DOCUMENTDB_USE_TLS: {{.Values.mongodb.use_tls | toString | b64enc | quote}}\n STORAGE_BACKEND: {{.Values.mongodb.storage_backend | b64enc | quote}}\ntype: Opaque\n{{- end }}\n" }, { "path": "charts/mongodb-configure/values.yaml", "content": "global:\n existingMongoCredentialsSecret: \"\" # If set, use this existing secret instead of creating one\n authProvider:\n type: keycloak\n entra:\n adminGroupId:\n\n# MongoDB configuration\nmongodb:\n database: mcp_registry\n # host: Can be either:\n # - A Kubernetes service name (e.g., \"mcp-registry-mongodb-svc\") - will be templated to include namespace\n # - A full hostname/FQDN (e.g., \"mongodb.example.com\" or \"10.0.1.100\") - will be used as-is\n host: mcp-registry-mongodb-svc\n namespace: default\n password: CHANGEME\n port: 27017\n replica_set: mcp-registry-mongodb\n username: my-user\n use_tls: false\n storage_backend: mongodb-ce\n" }, { "path": "charts/registry/Chart.yaml", "content": "apiVersion: v2\nname: registry\ndescription: A Helm chart for registry for MCP Gateway Registry\ntype: application\nversion: 0.1.0\nappVersion: \"1.0.0\"\n" }, { "path": "charts/registry/templates/configmap-app-log.yaml", "content": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: registry-app-log-config\n namespace: {{ .Release.Namespace | quote }}\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\ndata:\n APP_LOG_MAX_BYTES: {{ .Values.app.appLogMaxBytes | default \"52428800\" | quote }}\n APP_LOG_BACKUP_COUNT: {{ .Values.app.appLogBackupCount | default \"5\" | quote }}\n APP_LOG_CENTRALIZED_ENABLED: {{ .Values.app.appLogCentralizedEnabled | default \"true\" | quote }}\n APP_LOG_CENTRALIZED_TTL_DAYS: {{ .Values.app.appLogCentralizedTtlDays | default \"1\" | quote }}\n APP_LOG_MONGODB_BUFFER_SIZE: {{ .Values.app.appLogMongodbBufferSize | default \"50\" | quote }}\n APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS: {{ .Values.app.appLogMongodbFlushIntervalSeconds | default \"5.0\" | quote }}\n APP_LOG_LEVEL: {{ .Values.app.appLogLevel | default \"INFO\" | quote }}\n APP_LOG_EXCLUDED_LOGGERS: {{ .Values.app.appLogExcludedLoggers | default \"uvicorn.access,httpx,pymongo,motor\" | quote }}\n" }, { "path": "charts/registry/templates/configmap-otel.yaml", "content": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: registry-otel-config\n namespace: {{ .Release.Namespace | quote }}\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\ndata:\n {{- if .Values.app.otelOtlpEndpoint }}\n OTEL_OTLP_ENDPOINT: {{ .Values.app.otelOtlpEndpoint | quote }}\n {{- end }}\n {{- if .Values.app.otelExporterOtlpHeaders }}\n OTEL_EXPORTER_OTLP_HEADERS: {{ .Values.app.otelExporterOtlpHeaders | quote }}\n {{- end }}\n {{- if .Values.app.otelOtlpExportIntervalMs }}\n OTEL_OTLP_EXPORT_INTERVAL_MS: {{ .Values.app.otelOtlpExportIntervalMs | quote }}\n {{- end }}\n {{- if .Values.app.otelExporterOtlpMetricsTemporalityPreference }}\n OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: {{ .Values.app.otelExporterOtlpMetricsTemporalityPreference | quote }}\n {{- end }}\n {{- if .Values.app.mcpTelemetryDisabled }}\n MCP_TELEMETRY_DISABLED: {{ .Values.app.mcpTelemetryDisabled | quote }}\n {{- end }}\n {{- if .Values.app.mcpTelemetryOptOut }}\n MCP_TELEMETRY_OPT_OUT: {{ .Values.app.mcpTelemetryOptOut | quote }}\n {{- end }}\n {{- if .Values.app.telemetryHeartbeatIntervalMinutes }}\n MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES: {{ .Values.app.telemetryHeartbeatIntervalMinutes | quote }}\n {{- end }}\n {{- if .Values.app.telemetryDebug }}\n MCP_TELEMETRY_DEBUG: {{ .Values.app.telemetryDebug | quote }}\n {{- end }}\n {{- if .Values.app.disableAiRegistryToolsServer }}\n DISABLE_AI_REGISTRY_TOOLS_SERVER: {{ .Values.app.disableAiRegistryToolsServer | quote }}\n {{- end }}\n\n" }, { "path": "charts/registry/templates/deployment.yaml", "content": "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\nspec:\n replicas: {{ .Values.app.replicas }}\n selector:\n matchLabels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n template:\n metadata:\n labels:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n spec:\n {{- with .Values.nodeSelector }}\n nodeSelector:\n {{- toYaml . | nindent 8 }}\n {{- end }}\n securityContext:\n runAsNonRoot: true\n runAsUser: 1000\n runAsGroup: 1000\n fsGroup: 1000\n containers:\n - name: {{ .Values.app.name }}\n image: \"{{ .Values.global.image.repository }}:{{ .Values.global.image.tag }}\"\n imagePullPolicy: {{ .Values.global.image.pullPolicy }}\n securityContext:\n allowPrivilegeEscalation: false\n capabilities:\n drop:\n - ALL\n ports:\n - containerPort: 8080\n name: http\n - containerPort: 8443\n name: https\n - containerPort: 7860\n name: registry\n resources:\n {{- toYaml .Values.resources | nindent 12 }}\n envFrom:\n - configMapRef:\n name: registry-otel-config\n - configMapRef:\n name: registry-app-log-config\n - secretRef:\n name: {{ .Values.app.existingSecret | default .Values.app.envSecretName }}\n {{- if eq (.Values.global.authProvider.type | default \"keycloak\") \"keycloak\" }}\n - secretRef:\n name: keycloak-client-secret\n {{- end }}\n - secretRef:\n name: {{ .Values.global.existingMongoCredentialsSecret | default \"mongo-credentials\" }}\n {{- if .Values.global.sharedSecretName }}\n - secretRef:\n name: {{ .Values.global.existingSharedSecret | default .Values.global.sharedSecretName }}\n {{- end }}\n {{- if .Values.global.oauthProviderSecretName }}\n - secretRef:\n name: {{ .Values.global.existingOauthProviderSecret | default .Values.global.oauthProviderSecretName }}\n {{- end }}\n env:\n - name: DEPLOYMENT_MODE\n value: {{ .Values.app.deploymentMode | default \"with-gateway\" | quote }}\n - name: REGISTRY_MODE\n value: {{ .Values.app.registryMode | default \"full\" | quote }}\n - name: SHOW_SERVERS_TAB\n value: {{ .Values.app.showServersTab | default true | quote }}\n - name: SHOW_VIRTUAL_SERVERS_TAB\n value: {{ .Values.app.showVirtualServersTab | default true | quote }}\n - name: SHOW_SKILLS_TAB\n value: {{ .Values.app.showSkillsTab | default true | quote }}\n - name: SHOW_AGENTS_TAB\n value: {{ .Values.app.showAgentsTab | default true | quote }}\n {{- if .Values.awsRegistry.federationEnabled }}\n - name: AWS_REGISTRY_FEDERATION_ENABLED\n value: \"true\"\n {{- end }}\n {{- if eq (.Values.global.authProvider.type | default \"keycloak\") \"keycloak\" }}\n - name: KEYCLOAK_ADMIN_PASSWORD\n valueFrom:\n secretKeyRef:\n name: {{ .Release.Name }}-keycloak\n key: admin-password\n {{- end }}\n {{- if .Values.entra.clientSecretExistingSecret }}\n - name: ENTRA_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.entra.clientSecretExistingSecret }}\n key: {{ .Values.entra.clientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.okta.clientSecretExistingSecret }}\n - name: OKTA_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.okta.clientSecretExistingSecret }}\n key: {{ .Values.okta.clientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.okta.m2mClientSecretExistingSecret }}\n - name: OKTA_M2M_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.okta.m2mClientSecretExistingSecret }}\n key: {{ .Values.okta.m2mClientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.okta.apiTokenExistingSecret }}\n - name: OKTA_API_TOKEN\n valueFrom:\n secretKeyRef:\n name: {{ .Values.okta.apiTokenExistingSecret }}\n key: {{ .Values.okta.apiTokenExistingSecretKey }}\n {{- end }}\n {{- if .Values.auth0.clientSecretExistingSecret }}\n - name: AUTH0_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.auth0.clientSecretExistingSecret }}\n key: {{ .Values.auth0.clientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.auth0.m2mClientSecretExistingSecret }}\n - name: AUTH0_M2M_CLIENT_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.auth0.m2mClientSecretExistingSecret }}\n key: {{ .Values.auth0.m2mClientSecretExistingSecretKey }}\n {{- end }}\n {{- if .Values.auth0.managementApiTokenExistingSecret }}\n - name: AUTH0_MANAGEMENT_API_TOKEN\n valueFrom:\n secretKeyRef:\n name: {{ .Values.auth0.managementApiTokenExistingSecret }}\n key: {{ .Values.auth0.managementApiTokenExistingSecretKey }}\n {{- end }}\n {{- if .Values.app.registryApiKeysExistingSecret }}\n - name: REGISTRY_API_KEYS\n valueFrom:\n secretKeyRef:\n name: {{ .Values.app.registryApiKeysExistingSecret }}\n key: {{ .Values.app.registryApiKeysExistingSecretKey }}\n {{- end }}\n {{- if .Values.ans.apiKeyExistingSecret }}\n - name: ANS_API_KEY\n valueFrom:\n secretKeyRef:\n name: {{ .Values.ans.apiKeyExistingSecret }}\n key: {{ .Values.ans.apiKeyExistingSecretKey }}\n {{- end }}\n {{- if .Values.ans.apiSecretExistingSecret }}\n - name: ANS_API_SECRET\n valueFrom:\n secretKeyRef:\n name: {{ .Values.ans.apiSecretExistingSecret }}\n key: {{ .Values.ans.apiSecretExistingSecretKey }}\n {{- end }}\n livenessProbe:\n httpGet:\n path: /health\n port: 8080\n initialDelaySeconds: 30\n periodSeconds: 10\n timeoutSeconds: 5\n failureThreshold: 3\n readinessProbe:\n httpGet:\n path: /health\n port: 8080\n initialDelaySeconds: 10\n periodSeconds: 5\n timeoutSeconds: 3\n failureThreshold: 3\n" }, { "path": "charts/registry/templates/ingress.yaml", "content": "{{- if .Values.ingress.enabled }}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $domain := .Values.global.domain | default .Values.ingress.hostname }}\n{{- $pathPrefix := .Values.global.ingress.paths.registry | default .Values.ingress.path | default \"/registry\" }}\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n annotations:\n {{- if eq $routingMode \"path\" }}\n alb.ingress.kubernetes.io/group.name: mcp-gateway-stack\n alb.ingress.kubernetes.io/group.order: '20'\n {{- end }}\n alb.ingress.kubernetes.io/listen-ports: '[{\"HTTPS\": 443}]'\n alb.ingress.kubernetes.io/scheme: internet-facing\n alb.ingress.kubernetes.io/ssl-redirect: '443'\n alb.ingress.kubernetes.io/target-type: ip\n alb.ingress.kubernetes.io/success-codes: 200,302\n {{- if .Values.global.ingress.inboundCidrs }}\n alb.ingress.kubernetes.io/inbound-cidrs: {{ .Values.global.ingress.inboundCidrs }}\n {{- end }}\nspec:\n ingressClassName: {{ .Values.ingress.className }}\n rules:\n {{- if eq $routingMode \"path\" }}\n - host: {{ $domain | quote }}\n http:\n paths:\n - path: {{ $pathPrefix }}\n pathType: Prefix\n backend:\n service:\n name: {{ .Values.app.name }}\n port:\n name: http\n {{- else }}\n - host: {{ printf \"mcpregistry.%s\" $domain | quote }}\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: {{ .Values.app.name }}\n port:\n name: http\n {{- end }}\n{{- end }}\n" }, { "path": "charts/registry/templates/secret.yaml", "content": "{{- if and .Values.entra.clientSecret .Values.entra.clientSecretExistingSecret }}\n {{- fail \"Cannot set both entra.clientSecret and entra.clientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.okta.clientSecret .Values.okta.clientSecretExistingSecret }}\n {{- fail \"Cannot set both okta.clientSecret and okta.clientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.okta.m2mClientSecret .Values.okta.m2mClientSecretExistingSecret }}\n {{- fail \"Cannot set both okta.m2mClientSecret and okta.m2mClientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.okta.apiToken .Values.okta.apiTokenExistingSecret }}\n {{- fail \"Cannot set both okta.apiToken and okta.apiTokenExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.auth0.clientSecret .Values.auth0.clientSecretExistingSecret }}\n {{- fail \"Cannot set both auth0.clientSecret and auth0.clientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.auth0.m2mClientSecret .Values.auth0.m2mClientSecretExistingSecret }}\n {{- fail \"Cannot set both auth0.m2mClientSecret and auth0.m2mClientSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.auth0.managementApiToken .Values.auth0.managementApiTokenExistingSecret }}\n {{- fail \"Cannot set both auth0.managementApiToken and auth0.managementApiTokenExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.ans.apiKey .Values.ans.apiKeyExistingSecret }}\n {{- fail \"Cannot set both ans.apiKey and ans.apiKeyExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.ans.apiSecret .Values.ans.apiSecretExistingSecret }}\n {{- fail \"Cannot set both ans.apiSecret and ans.apiSecretExistingSecret — env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if and .Values.app.registryApiKeys .Values.app.registryApiKeysExistingSecret }}\n {{- fail \"Cannot set both app.registryApiKeys and app.registryApiKeysExistingSecret, env overrides envFrom and can cause confusing behavior\" }}\n{{- end }}\n{{- if not .Values.app.existingSecret }}\n{{- $routingMode := .Values.global.ingress.routingMode | default \"subdomain\" }}\n{{- $domain := .Values.global.domain | default \"localhost\" }}\n{{- $protocol := ternary \"https\" \"http\" .Values.global.ingress.tls }}\n{{- $authServerPath := .Values.global.ingress.paths.authServer | default \"/auth-server\" }}\n{{- $registryPath := .Values.global.ingress.paths.registry | default \"/registry\" }}\n{{- $keycloakPath := .Values.global.ingress.paths.keycloak | default \"/keycloak\" }}\n{{- $authServerExternalUrl := \"\" }}\n{{- $registryExternalUrl := \"\" }}\n{{- $keycloakUrl := printf \"http://%s-keycloak-headless.%s.svc.cluster.local:8080\" .Release.Name .Release.Namespace}}\n{{- $rootPath := \"\" }}\n{{- $gatewayAdditionalServerNames := $domain}}\n{{- if eq $routingMode \"path\" }}\n {{- $authServerExternalUrl = printf \"%s://%s%s\" $protocol $domain $authServerPath }}\n {{- $registryExternalUrl = printf \"%s://%s%s\" $protocol $domain $registryPath }}\n {{- $keycloakUrl = printf \"%s%s\" $keycloakUrl $keycloakPath }}\n {{- $rootPath = $registryPath }}\n{{- else }}\n {{- $authServerExternalUrl = printf \"%s://auth-server.%s\" $protocol $domain }}\n {{- $registryExternalUrl = printf \"%s://mcpregistry.%s\" $protocol $domain }}\n {{- $gatewayAdditionalServerNames = printf \"mcpregistry.%s\" $domain }}\n{{- end }}\n{{- /* Auto-generate federation tokens if not provided */ -}}\n{{- /* Resolve federation values - prefer global, fallback to local app values */ -}}\n{{- $federationEnabled := .Values.app.federationStaticTokenAuthEnabled | default false }}\n{{- if .Values.global.federation }}\n {{- $federationEnabled = .Values.global.federation.staticTokenAuthEnabled | default $federationEnabled }}\n{{- end }}\n{{- $federationStaticTokenRaw := .Values.app.federationStaticToken }}\n{{- $federationEncryptionKeyRaw := .Values.app.federationEncryptionKey }}\n{{- $registryId := .Values.app.registryId }}\n{{- if .Values.global.federation }}\n {{- $federationStaticTokenRaw = .Values.global.federation.staticToken | default $federationStaticTokenRaw }}\n {{- $federationEncryptionKeyRaw = .Values.global.federation.encryptionKey | default $federationEncryptionKeyRaw }}\n {{- $registryId = .Values.global.federation.registryId | default $registryId }}\n{{- end }}\n{{- /* Generate URL-safe token (equivalent to secrets.token_urlsafe(32)) */ -}}\n{{- $federationStaticToken := $federationStaticTokenRaw | default (randBytes 32 | replace \"+\" \"-\" | replace \"/\" \"_\" | trimSuffix \"=\") }}\n{{- /* Generate Fernet-compatible key (32 random bytes, base64-encoded) */ -}}\n{{- $federationEncryptionKey := $federationEncryptionKeyRaw | default (randBytes 32) }}\napiVersion: v1\nkind: Secret\nmetadata:\n name: {{ .Values.app.envSecretName }}\n namespace: {{ .Release.Namespace | quote }}\ndata:\n AUTH_SERVER_EXTERNAL_URL: {{ $authServerExternalUrl | b64enc | quote }}\n AUTH_SERVER_URL: {{ printf \"http://auth-server.%s.svc.cluster.local:8888\" .Release.Namespace | b64enc | quote }}\n {{- if eq (.Values.global.authProvider.type | default \"keycloak\") \"keycloak\" }}\n KEYCLOAK_ADMIN: {{ (.Values.global.authProvider.keycloak.adminUsername | default \"user\") | b64enc | quote }}\n {{- end }}\n GATEWAY_ADDITIONAL_SERVER_NAMES: {{ $gatewayAdditionalServerNames| b64enc | quote }}\n{{- if not .Values.global.oauthProviderSecretName }}\n {{/* OAuth provider vars managed per-chart in standalone deployment */}}\n AUTH_PROVIDER: {{ (.Values.global.authProvider.type | default \"keycloak\") | b64enc | quote }}\n {{- if eq (.Values.global.authProvider.type | default \"keycloak\") \"keycloak\" }}\n KEYCLOAK_ENABLED: {{ \"true\" | b64enc | quote }}\n KEYCLOAK_URL: {{ $keycloakUrl | b64enc | quote }}\n KEYCLOAK_REALM: {{ (.Values.global.authProvider.keycloak.realm | default \"mcp-gateway\") | b64enc | quote }}\n {{- else if eq (.Values.global.authProvider.type | default \"keycloak\") \"entra\" }}\n ENTRA_ENABLED: {{ \"true\" | b64enc | quote }}\n ENTRA_CLIENT_ID: {{ .Values.entra.clientId | b64enc | quote }}\n {{- if not .Values.entra.clientSecretExistingSecret }}\n ENTRA_CLIENT_SECRET: {{ .Values.entra.clientSecret | b64enc | quote }}\n {{- end }}\n ENTRA_TENANT_ID: {{ .Values.entra.tenantId | b64enc | quote }}\n {{- else if eq (.Values.global.authProvider.type | default \"keycloak\") \"okta\" }}\n OKTA_ENABLED: {{ \"true\" | b64enc | quote }}\n OKTA_DOMAIN: {{ .Values.okta.domain | b64enc | quote }}\n OKTA_CLIENT_ID: {{ .Values.okta.clientId | b64enc | quote }}\n {{- if not .Values.okta.clientSecretExistingSecret }}\n OKTA_CLIENT_SECRET: {{ .Values.okta.clientSecret | b64enc | quote }}\n {{- end }}\n {{- if .Values.okta.m2mClientId }}\n OKTA_M2M_CLIENT_ID: {{ .Values.okta.m2mClientId | b64enc | quote }}\n {{- end }}\n {{- if and .Values.okta.m2mClientSecret (not .Values.okta.m2mClientSecretExistingSecret) }}\n OKTA_M2M_CLIENT_SECRET: {{ .Values.okta.m2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- if and .Values.okta.apiToken (not .Values.okta.apiTokenExistingSecret) }}\n OKTA_API_TOKEN: {{ .Values.okta.apiToken | b64enc | quote }}\n {{- end }}\n {{- if .Values.okta.authServerId }}\n OKTA_AUTH_SERVER_ID: {{ .Values.okta.authServerId | b64enc | quote }}\n {{- end }}\n {{- else if eq (.Values.global.authProvider.type | default \"keycloak\") \"auth0\" }}\n AUTH0_ENABLED: {{ \"true\" | b64enc | quote }}\n AUTH0_DOMAIN: {{ .Values.auth0.domain | b64enc | quote }}\n AUTH0_CLIENT_ID: {{ .Values.auth0.clientId | b64enc | quote }}\n {{- if not .Values.auth0.clientSecretExistingSecret }}\n AUTH0_CLIENT_SECRET: {{ .Values.auth0.clientSecret | b64enc | quote }}\n {{- end }}\n {{- if .Values.auth0.audience }}\n AUTH0_AUDIENCE: {{ .Values.auth0.audience | b64enc | quote }}\n {{- end }}\n AUTH0_GROUPS_CLAIM: {{ .Values.auth0.groupsClaim | b64enc | quote }}\n {{- if .Values.auth0.m2mClientId }}\n AUTH0_M2M_CLIENT_ID: {{ .Values.auth0.m2mClientId | b64enc | quote }}\n {{- end }}\n {{- if and .Values.auth0.m2mClientSecret (not .Values.auth0.m2mClientSecretExistingSecret) }}\n AUTH0_M2M_CLIENT_SECRET: {{ .Values.auth0.m2mClientSecret | b64enc | quote }}\n {{- end }}\n {{- if and .Values.auth0.managementApiToken (not .Values.auth0.managementApiTokenExistingSecret) }}\n AUTH0_MANAGEMENT_API_TOKEN: {{ .Values.auth0.managementApiToken | b64enc | quote }}\n {{- end }}\n {{- else if eq (.Values.global.authProvider.type | default \"keycloak\") \"cognito\" }}\n COGNITO_ENABLED: {{ \"true\" | b64enc | quote }}\n COGNITO_USER_POOL_ID: {{ required \"cognito.userPoolId is required\" .Values.cognito.userPoolId | b64enc | quote }}\n COGNITO_CLIENT_ID: {{ required \"cognito.clientId is required\" .Values.cognito.clientId | b64enc | quote }}\n COGNITO_CLIENT_SECRET: {{ required \"cognito.clientSecret is required\" .Values.cognito.clientSecret | b64enc | quote }}\n {{- if .Values.cognito.domain }}\n COGNITO_DOMAIN: {{ .Values.cognito.domain | b64enc | quote }}\n {{- end }}\n {{- if .Values.cognito.region }}\n AWS_REGION: {{ .Values.cognito.region | b64enc | quote }}\n {{- end }}\n {{- end }}\n{{- end }}\n ROOT_PATH: {{ $rootPath | b64enc | quote }}\n {{- if .Values.idpGroupFilterPrefix }}\n IDP_GROUP_FILTER_PREFIX: {{ .Values.idpGroupFilterPrefix | b64enc | quote }}\n {{- end }}\n SKILL_SECURITY_SCAN_ENABLED: {{ .Values.app.skillSecurityScanEnabled | toString | b64enc | quote }}\n SKILL_SECURITY_ANALYZERS: {{ .Values.app.skillSecurityAnalyzers | b64enc | quote }}\n # Static API keys for registry path authentication (JSON string)\n {{- if and .Values.app.registryApiKeys (not .Values.app.registryApiKeysExistingSecret) }}\n REGISTRY_API_KEYS: {{ .Values.app.registryApiKeys | b64enc | quote }}\n {{- end }}\n # Registration webhook (issue #742)\n {{- if .Values.app.registrationWebhookUrl }}\n REGISTRATION_WEBHOOK_URL: {{ .Values.app.registrationWebhookUrl | b64enc | quote }}\n {{- end }}\n REGISTRATION_WEBHOOK_AUTH_HEADER: {{ .Values.app.registrationWebhookAuthHeader | b64enc | quote }}\n {{- if .Values.app.registrationWebhookAuthToken }}\n REGISTRATION_WEBHOOK_AUTH_TOKEN: {{ .Values.app.registrationWebhookAuthToken | b64enc | quote }}\n {{- end }}\n REGISTRATION_WEBHOOK_TIMEOUT_SECONDS: {{ .Values.app.registrationWebhookTimeoutSeconds | toString | b64enc | quote }}\n # Registration gate / admission control (issue #809)\n REGISTRATION_GATE_ENABLED: {{ .Values.app.registrationGateEnabled | toString | b64enc | quote }}\n {{- if .Values.app.registrationGateUrl }}\n REGISTRATION_GATE_URL: {{ .Values.app.registrationGateUrl | b64enc | quote }}\n {{- end }}\n REGISTRATION_GATE_AUTH_TYPE: {{ .Values.app.registrationGateAuthType | b64enc | quote }}\n {{- if .Values.app.registrationGateAuthCredential }}\n REGISTRATION_GATE_AUTH_CREDENTIAL: {{ .Values.app.registrationGateAuthCredential | b64enc | quote }}\n {{- end }}\n REGISTRATION_GATE_AUTH_HEADER_NAME: {{ .Values.app.registrationGateAuthHeaderName | b64enc | quote }}\n REGISTRATION_GATE_TIMEOUT_SECONDS: {{ .Values.app.registrationGateTimeoutSeconds | toString | b64enc | quote }}\n REGISTRATION_GATE_MAX_RETRIES: {{ .Values.app.registrationGateMaxRetries | toString | b64enc | quote }}\n # M2M direct client registration (issue #851)\n M2M_DIRECT_REGISTRATION_ENABLED: {{ .Values.app.m2mDirectRegistrationEnabled | toString | b64enc | quote }}\n # ANS (Agent Name Service) Integration\n {{- if .Values.ans.enabled }}\n ANS_INTEGRATION_ENABLED: {{ \"true\" | b64enc | quote }}\n ANS_API_ENDPOINT: {{ .Values.ans.apiEndpoint | b64enc | quote }}\n {{- if and .Values.ans.apiKey (not .Values.ans.apiKeyExistingSecret) }}\n ANS_API_KEY: {{ .Values.ans.apiKey | b64enc | quote }}\n {{- end }}\n {{- if and .Values.ans.apiSecret (not .Values.ans.apiSecretExistingSecret) }}\n ANS_API_SECRET: {{ .Values.ans.apiSecret | b64enc | quote }}\n {{- end }}\n {{- if .Values.ans.apiTimeoutSeconds }}\n ANS_API_TIMEOUT_SECONDS: {{ .Values.ans.apiTimeoutSeconds | toString | b64enc | quote }}\n {{- end }}\n {{- if .Values.ans.syncIntervalHours }}\n ANS_SYNC_INTERVAL_HOURS: {{ .Values.ans.syncIntervalHours | toString | b64enc | quote }}\n {{- end }}\n {{- if .Values.ans.verificationCacheTtlSeconds }}\n ANS_VERIFICATION_CACHE_TTL_SECONDS: {{ .Values.ans.verificationCacheTtlSeconds | toString | b64enc | quote }}\n {{- end }}\n {{- end }}\n # Registry Card Configuration\n REGISTRY_URL: {{ (.Values.registryCard.url | default $registryExternalUrl) | b64enc | quote }}\n REGISTRY_NAME: {{ (.Values.registryCard.name | default \"AI Registry\") | b64enc | quote }}\n REGISTRY_ORGANIZATION_NAME: {{ (.Values.registryCard.organizationName | default \"ACME Inc.\") | b64enc | quote }}\n REGISTRY_DESCRIPTION: {{ (.Values.registryCard.description | default \"\") | b64enc | quote }}\n REGISTRY_CONTACT_EMAIL: {{ (.Values.registryCard.contactEmail | default \"\") | b64enc | quote }}\n REGISTRY_CONTACT_URL: {{ (.Values.registryCard.contactUrl | default \"\") | b64enc | quote }}\n{{- if not .Values.global.sharedSecretName }}\n {{/* Federation and SECRET_KEY managed per-chart in standalone deployment */}}\n {{- if $federationEnabled }}\n FEDERATION_STATIC_TOKEN_AUTH_ENABLED: {{ $federationEnabled | toString | b64enc | quote }}\n FEDERATION_STATIC_TOKEN: {{ $federationStaticToken | b64enc | quote }}\n FEDERATION_ENCRYPTION_KEY: {{ $federationEncryptionKey | b64enc | quote }}\n {{- if .Values.app.federationTokenEndpoint }}\n FEDERATION_TOKEN_ENDPOINT: {{ .Values.app.federationTokenEndpoint | b64enc | quote }}\n {{- end }}\n {{- if .Values.app.federationClientId }}\n FEDERATION_CLIENT_ID: {{ .Values.app.federationClientId | b64enc | quote }}\n {{- end }}\n {{- if .Values.app.federationClientSecret }}\n FEDERATION_CLIENT_SECRET: {{ .Values.app.federationClientSecret | b64enc | quote }}\n {{- end }}\n {{- end }}\n {{- if $registryId }}\n REGISTRY_ID: {{ $registryId | b64enc | quote }}\n {{- end }}\n {{- if .Values.app.asorAccessToken }}\n ASOR_ACCESS_TOKEN: {{ .Values.app.asorAccessToken | b64enc | quote }}\n {{- end }}\n {{- if .Values.app.workdayTokenUrl }}\n WORKDAY_TOKEN_URL: {{ .Values.app.workdayTokenUrl | b64enc | quote }}\n {{- end }}\n {{/* SECRET_KEY required for standalone deployment - must match auth-server's key */}}\n SECRET_KEY: {{ required \"app.secretKey or global.secretKey is required for standalone deployment\" (.Values.global.secretKey | default .Values.app.secretKey) | b64enc | quote }}\n{{- end }}\n{{- end }}\n" }, { "path": "charts/registry/templates/service.yaml", "content": "apiVersion: v1\nkind: Service\nmetadata:\n name: {{ .Values.app.name }}\n namespace: {{ .Release.Namespace | quote }}\n {{- with .Values.service.annotations }}\n annotations:\n {{- toYaml . | nindent 4 }}\n {{- end }}\nspec:\n type: {{ .Values.service.type }}\n ports:\n - port: {{ .Values.service.port }}\n targetPort: http\n protocol: TCP\n name: http\n - port: 443\n targetPort: https\n protocol: TCP\n name: https\n - port: 7860\n targetPort: registry\n protocol: TCP\n name: registry\n selector:\n app.kubernetes.io/name: {{ .Values.app.name }}\n app.kubernetes.io/component: {{ .Values.app.name }}\n" }, { "path": "charts/registry/values.yaml", "content": "# Global configuration\nglobal:\n image:\n repository: public.ecr.aws/p3v1o3c6/registry\n tag: 1.0.21\n pullPolicy: IfNotPresent\n\n# Application configuration\napp:\n name: registry\n replicas: 1\n envSecretName: registry-secret\n existingSecret: \"\" # If set, use this existing secret instead of creating one\n\n # External URLs\n authServerUrl: http://localhost:8888\n\n # Security settings\n # secretKey: If not provided, a random 64-character key is auto-generated.\n # When deployed via mcp-gateway-registry-stack, the key is shared with auth-server.\n # Uncomment to use a specific key:\n # secretKey: \"your-secure-key-here\"\n\n # Federation configuration\n federationStaticTokenAuthEnabled: false #If not provided, defaults to false\n federationStaticToken: # If not provided, a random token is auto-generated\n federationEncryptionKey: # If not provided, a Fernet key is auto-generated\n registryId: # Unique identifier for this registry instance (optional)\n # Federation OAuth2 authentication (alternative to static token for outbound peer connections)\n federationTokenEndpoint: \"\" # OAuth2 token endpoint for federation authentication\n federationClientId: \"\" # OAuth2 client ID for federation\n federationClientSecret: \"\" # OAuth2 client secret for federation\n\n # ASOR (Workday) integration (independent of peer federation)\n asorAccessToken: \"\" # Pre-obtained access token for ASOR federation\n workdayTokenUrl: \"\" # Workday OAuth2 token endpoint URL\n\n # Skill security scanning configuration\n skillSecurityScanEnabled: true # Enable/disable skill security scanning\n skillSecurityAnalyzers: \"static\" # Comma-separated: static, behavioral, llm, meta, virustotal, ai-defense\n\n # Static API keys for registry path authentication (JSON string)\n # Configures multiple static API keys that fall through to JWT validation when unmatched\n registryApiKeys: \"\"\n registryApiKeysExistingSecret: \"\" # If set, read REGISTRY_API_KEYS from this K8s secret instead\n registryApiKeysExistingSecretKey: \"REGISTRY_API_KEYS\" # Key within the existing secret\n\n # Registration webhook (issue #742)\n # Fire an async POST when a server, agent, or skill is registered or deleted.\n registrationWebhookUrl: \"\" # Webhook URL. Disabled when empty.\n registrationWebhookAuthHeader: \"Authorization\" # If \"Authorization\", Bearer is auto-prepended.\n registrationWebhookAuthToken: \"\" # Auth token. Leave empty for unauthenticated webhooks.\n registrationWebhookTimeoutSeconds: \"10\"\n\n # Registration gate / admission control (issue #809)\n # Calls an external endpoint to approve or deny registrations and updates\n # BEFORE they are persisted. Fail-closed when gate is unreachable.\n registrationGateEnabled: false\n registrationGateUrl: \"\" # Gate URL. Must be set when enabled.\n registrationGateAuthType: \"none\" # none, api_key, or bearer\n registrationGateAuthCredential: \"\" # Credential for api_key or bearer\n registrationGateAuthHeaderName: \"X-Api-Key\" # Header for api_key auth\n registrationGateTimeoutSeconds: \"5\"\n registrationGateMaxRetries: \"2\"\n\n # M2M direct client registration (issue #851)\n # Exposes /api/iam/m2m-clients admin API for registering M2M client_ids and\n # their group mappings directly, without requiring an IdP Admin API token.\n m2mDirectRegistrationEnabled: true\n\n # OpenTelemetry direct OTLP push export configuration\n otelOtlpEndpoint: \"\" # OTLP endpoint URL (e.g., https://otlp.datadoghq.com)\n otelExporterOtlpHeaders: \"\" # OTLP headers (e.g., dd-api-key=YOUR_KEY)\n otelOtlpExportIntervalMs: \"30000\" # Export interval in milliseconds\n otelExporterOtlpMetricsTemporalityPreference: \"cumulative\" # cumulative or delta\n\n # Telemetry configuration\n # Anonymous usage telemetry (startup ping + daily heartbeat, both on by default)\n mcpTelemetryDisabled: false # Set to true to disable all telemetry\n mcpTelemetryOptOut: false # Set to true to disable daily heartbeat only (startup ping still sent)\n telemetryHeartbeatIntervalMinutes: \"1440\" # Heartbeat interval in minutes (default: 1440 = 24 hours)\n telemetryDebug: false # Set to true to log payloads instead of sending\n\n # Demo server configuration\n disableAiRegistryToolsServer: false # Set to true to disable auto-registration of the built-in airegistry-tools server\n\n # Deployment mode: with-gateway (nginx integration) or registry-only (catalog only)\n deploymentMode: with-gateway\n\n # Registry mode: full, skills-only, mcp-servers-only, agents-only\n registryMode: full\n\n # Tab visibility overrides (AND-ed with registryMode)\n showServersTab: true\n showVirtualServersTab: true\n showSkillsTab: true\n showAgentsTab: true\n\n # Application Log Configuration (centralized log rotation and retrieval)\n appLogMaxBytes: \"52428800\" # Max size per log file before rotation (default 50 MB)\n appLogBackupCount: \"5\" # Number of rotated backup log files to keep\n appLogCentralizedEnabled: \"true\" # Write application logs to centralized store (requires MongoDB backend)\n appLogCentralizedTtlDays: \"1\" # Days to retain log entries in centralized store (TTL index)\n appLogMongodbBufferSize: \"50\" # Records to buffer before flushing to MongoDB\n appLogMongodbFlushIntervalSeconds: \"5.0\" # Seconds between periodic flushes\n appLogLevel: \"INFO\" # Application log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n appLogExcludedLoggers: \"uvicorn.access,httpx,pymongo,motor\" # Comma-separated logger names to exclude from MongoDB\n\n# AWS Agent Registry Federation\nawsRegistry:\n federationEnabled: false # Enable AWS Agent Registry federation (overrides MongoDB config on startup)\n\n# ANS (Agent Name Service) Integration\nans:\n enabled: false # Enable ANS integration for trust verification\n apiEndpoint: \"https://api.godaddy.com\" # ANS API base URL\n apiKey: \"\" # GoDaddy API key (required when enabled)\n apiKeyExistingSecret: \"\" # If set, read ANS_API_KEY from this K8s secret instead of apiKey\n apiKeyExistingSecretKey: \"ANS_API_KEY\" # Key within the existing secret\n apiSecret: \"\" # GoDaddy API secret (required when enabled)\n apiSecretExistingSecret: \"\" # If set, read ANS_API_SECRET from this K8s secret instead of apiSecret\n apiSecretExistingSecretKey: \"ANS_API_SECRET\" # Key within the existing secret\n apiTimeoutSeconds: \"30\" # HTTP request timeout for ANS API calls\n syncIntervalHours: \"6\" # Background re-verification interval\n verificationCacheTtlSeconds: \"3600\" # Cache TTL for verification results\n\n# Registry Card Configuration (for federation and discovery)\nregistryCard:\n url: \"\" # External URL of the registry (e.g., https://registry.example.com). Defaults to computed ingress URL.\n name: \"AI Registry\" # Human-readable name\n organizationName: \"ACME Inc.\" # Organization operating the registry\n description: \"\" # Optional description\n contactEmail: \"\" # Optional contact email\n contactUrl: \"\" # Optional contact URL/website\n\n# Entra ID integration (used when authProvider.type = \"entra\" in standalone deployment)\nentra:\n clientId: \"\"\n clientSecret: \"\"\n clientSecretExistingSecret: \"\" # If set, read ENTRA_CLIENT_SECRET from this K8s secret instead of clientSecret\n clientSecretExistingSecretKey: \"ENTRA_CLIENT_SECRET\" # Key within the existing secret\n tenantId: \"\"\n\n# IdP group filtering (applies to all identity providers)\n# When set, only groups matching any of these prefixes are shown in IAM > Groups\n# Example: \"mcp-,registry-,ai-\"\nidpGroupFilterPrefix: \"\"\n\n# Okta integration (used when authProvider.type = \"okta\" in standalone deployment)\nokta:\n domain: \"\" # e.g., dev-123456.okta.com\n clientId: \"\"\n clientSecret: \"\"\n clientSecretExistingSecret: \"\" # If set, read OKTA_CLIENT_SECRET from this K8s secret\n clientSecretExistingSecretKey: \"OKTA_CLIENT_SECRET\"\n m2mClientId: \"\" # Optional: defaults to clientId\n m2mClientSecret: \"\" # Optional: defaults to clientSecret\n m2mClientSecretExistingSecret: \"\" # If set, read OKTA_M2M_CLIENT_SECRET from this K8s secret\n m2mClientSecretExistingSecretKey: \"OKTA_M2M_CLIENT_SECRET\"\n apiToken: \"\" # Optional: required for IAM operations\n apiTokenExistingSecret: \"\" # If set, read OKTA_API_TOKEN from this K8s secret\n apiTokenExistingSecretKey: \"OKTA_API_TOKEN\"\n authServerId: \"\" # Optional: uses default Org Authorization Server if not set\n\n# Auth0 integration (used when authProvider.type = \"auth0\" in standalone deployment)\nauth0:\n domain: \"\" # e.g., your-tenant.us.auth0.com\n clientId: \"\"\n clientSecret: \"\"\n clientSecretExistingSecret: \"\" # If set, read AUTH0_CLIENT_SECRET from this K8s secret\n clientSecretExistingSecretKey: \"AUTH0_CLIENT_SECRET\"\n audience: \"\" # Optional: API audience for M2M tokens\n groupsClaim: \"https://mcp-gateway/groups\" # Custom namespaced claim for groups\n m2mClientId: \"\" # Required for IAM Management (user/role administration)\n m2mClientSecret: \"\" # Required for IAM Management\n m2mClientSecretExistingSecret: \"\" # If set, read AUTH0_M2M_CLIENT_SECRET from this K8s secret\n m2mClientSecretExistingSecretKey: \"AUTH0_M2M_CLIENT_SECRET\"\n managementApiToken: \"\" # Optional: alternative to M2M credentials (expires after 24h)\n managementApiTokenExistingSecret: \"\" # If set, read AUTH0_MANAGEMENT_API_TOKEN from this K8s secret\n managementApiTokenExistingSecretKey: \"AUTH0_MANAGEMENT_API_TOKEN\"\n\n# Cognito integration (used when authProvider.type = \"cognito\" in standalone deployment)\ncognito:\n userPoolId: \"\" # Cognito User Pool ID\n clientId: \"\"\n clientSecret: \"\"\n domain: \"\" # Optional: custom Cognito domain\n region: \"us-east-1\" # AWS region for the User Pool\n\n# Service configuration\nservice:\n type: ClusterIP\n port: 8000\n annotations: {}\n\n# Resource limits and requests\nresources:\n requests:\n cpu: 1\n memory: 1Gi\n limits:\n cpu: 2\n memory: 2Gi\n\n# Ingress configuration\ningress:\n enabled: false\n className: alb\n hostname: \"\"\n annotations: {}\n tls: false\n # Routing mode: \"subdomain\" or \"path\"\n # - subdomain: mcpregistry.domain.com\n # - path: domain.com/registry (configurable via path setting)\n routingMode: subdomain\n # Path prefix when using path-based routing (default: /registry)\n path: /registry\n\nnodeSelector: {}\n" }, { "path": "cli/agent_mgmt.py", "content": "#!/usr/bin/env python3\n\"\"\"\nAgent Management Script for MCP Gateway Registry.\n\nThis tool provides CLI commands for managing A2A agents via the A2A Agent Management API.\nIt uses JWT Bearer tokens from Keycloak for authentication via the mcp-gateway-m2m service account.\n\nSERVICE ACCOUNT: mcp-gateway-m2m\nThe mcp-gateway-m2m service account is a Keycloak M2M client that provides authentication\nfor both MCP server management and A2A agent management operations. The JWT token from this\naccount is automatically loaded from .oauth-tokens/ingress.json.\n\nPERMISSIONS:\n- Token scopes: mcp-servers-restricted/*, mcp-servers-unrestricted/*, a2a-agent-admin\n- Agent operations: register, modify, delete, list (full admin access)\n- Group assignment: mcp-servers-unrestricted, a2a-agent-admin\n\nAPI: /api/agents (A2A Agent Management API - dedicated endpoints for agent management)\n- List agents: GET /api/agents\n- Get agent: GET /api/agents/{path}\n- Register agent: POST /api/agents/register\n- Update agent: PUT /api/agents/{path}\n- Delete agent: DELETE /api/agents/{path}\n- Toggle agent: POST /api/agents/{path}/toggle\n- Search agents: POST /api/agents/discover/semantic\n\nHEALTH CHECKS:\n- The 'test' command performs two-level verification:\n 1. Registry Check: Verifies agent metadata in the registry (always performed)\n 2. Service Health: Fetches agent card from /.well-known/agent-card.json (if agent is enabled)\n- Results show: PASSED (agent responds), FAILED (agent unavailable), SKIPPED (disabled/no URL)\n\nSEMANTIC SEARCH:\n- The 'search' command performs natural language semantic search using FAISS vector index\n- Returns enabled agents matching the query with relevance scores\n\nUsage:\n # Automatically loads token from .oauth-tokens/ingress.json (generated by credentials-provider/generate_creds.sh)\n uv run python cli/agent_mgmt.py list\n uv run python cli/agent_mgmt.py get /code-reviewer\n uv run python cli/agent_mgmt.py test /code-reviewer # Test single agent with health check\n uv run python cli/agent_mgmt.py test-all # Test all agents with health checks\n uv run python cli/agent_mgmt.py search \"code review agent\" # Semantic search for agents\n\nFor agent creation, registration, toggle, and delete operations, the mcp-gateway-m2m\nservice account must be assigned to the a2a-agent-admin group in Keycloak.\n\"\"\"\n\nimport argparse\nimport base64\nimport json\nimport logging\nimport os\nimport subprocess # nosec B404\nimport sys\nimport time\nfrom typing import Any\n\nimport requests\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nDEFAULT_BASE_URL: str = \"http://localhost\" # Goes through nginx (port 80), not direct :7860\nDEFAULT_TOKEN_FILE: str = \".oauth-tokens/ingress.json\"\nREQUEST_TIMEOUT: int = 10\nAPI_BASE: str = \"/api/agents\"\n\n\ndef _extract_username_from_jwt(token: str) -> str:\n \"\"\"Extract username from JWT token payload.\"\"\"\n try:\n parts = token.split(\".\")\n if len(parts) != 3:\n return \"unknown\"\n\n payload = parts[1]\n padding = 4 - (len(payload) % 4)\n if padding != 4:\n payload += \"=\" * padding\n\n decoded = base64.urlsafe_b64decode(payload)\n claims = json.loads(decoded)\n\n username = claims.get(\"preferred_username\") or claims.get(\"sub\") or \"unknown\"\n return username\n except Exception:\n return \"unknown\"\n\n\ndef _get_token_expiration(token: str) -> int | None:\n \"\"\"Extract expiration timestamp from JWT token.\n\n Returns:\n Expiration timestamp (seconds since epoch) or None if unable to extract\n \"\"\"\n try:\n parts = token.split(\".\")\n if len(parts) != 3:\n return None\n\n payload = parts[1]\n padding = 4 - (len(payload) % 4)\n if padding != 4:\n payload += \"=\" * padding\n\n decoded = base64.urlsafe_b64decode(payload)\n claims = json.loads(decoded)\n return claims.get(\"exp\")\n except Exception:\n return None\n\n\ndef _is_token_expired(token: str, buffer_seconds: int = 30) -> bool:\n \"\"\"Check if token is expired or about to expire.\n\n Args:\n token: JWT token string\n buffer_seconds: Seconds before actual expiration to consider token expired\n\n Returns:\n True if token is expired or expiring soon, False otherwise\n \"\"\"\n exp_timestamp = _get_token_expiration(token)\n if exp_timestamp is None:\n return False\n\n current_time = time.time()\n return current_time >= (exp_timestamp - buffer_seconds)\n\n\ndef _regenerate_token(token_file: str) -> bool:\n \"\"\"Regenerate token using generate_creds.sh script.\n\n Args:\n token_file: Path to the token file\n\n Returns:\n True if regeneration succeeded, False otherwise\n \"\"\"\n logger.info(\"Token expired, regenerating credentials...\")\n\n # Extract the agent name from token file if it's a bot account\n # e.g., .oauth-tokens/bot-x-token.json -> bot-x\n token_filename = os.path.basename(token_file)\n if token_filename.endswith(\"-token.json\"):\n agent_name = token_filename[:-11] # Remove \"-token.json\"\n else:\n # Fallback to running generate_creds.sh for main ingress token\n agent_name = None\n\n try:\n script_dir = os.path.dirname(os.path.abspath(__file__))\n project_root = os.path.dirname(script_dir)\n\n if agent_name:\n # Use generate-agent-token.sh for specific agent\n # Call from keycloak/setup directory so relative paths work\n token_script = os.path.join(project_root, \"keycloak/setup/generate-agent-token.sh\")\n keycloak_setup_dir = os.path.join(project_root, \"keycloak/setup\")\n logger.info(f\"Running: {token_script} {agent_name}\")\n result = subprocess.run( # nosec B603 - hardcoded internal script path\n [token_script, agent_name],\n cwd=keycloak_setup_dir, # Run from keycloak/setup so ../../.oauth-tokens works\n capture_output=True,\n text=True,\n timeout=30,\n )\n else:\n # Use generate_creds.sh for ingress token\n creds_script = os.path.join(project_root, \"credentials-provider/generate_creds.sh\")\n logger.info(f\"Running: {creds_script} --ingress-only\")\n result = subprocess.run( # nosec B603 - hardcoded internal script path and flags\n [creds_script, \"--ingress-only\"],\n cwd=project_root,\n capture_output=True,\n text=True,\n timeout=60,\n )\n\n if result.returncode == 0:\n logger.info(\"✓ Token regenerated successfully\")\n return True\n else:\n logger.error(\"✗ Token regeneration failed\")\n logger.error(f\" Error output: {result.stderr}\")\n return False\n\n except FileNotFoundError as e:\n logger.error(f\"✗ Token regeneration script not found: {e}\")\n return False\n except subprocess.TimeoutExpired:\n logger.error(\"✗ Token regeneration script timed out\")\n return False\n except Exception as e:\n logger.error(f\"✗ Token regeneration failed: {e}\")\n return False\n\n\ndef _load_token(token_file: str) -> tuple[str, str]:\n \"\"\"Load JWT token from file and extract username.\n\n If token is expired, automatically regenerate it.\n\n Returns:\n Tuple of (token, username)\n \"\"\"\n abs_path = os.path.abspath(token_file)\n try:\n with open(abs_path) as f:\n data = json.load(f)\n token = data.get(\"access_token\") or data.get(\"token\")\n if not token:\n raise ValueError(\"No access_token found in token file\")\n\n # Check if token is expired\n if _is_token_expired(token):\n logger.warning(\"Token is expired or expiring soon, regenerating...\")\n if _regenerate_token(token_file):\n # Reload token from file after regeneration\n with open(abs_path) as f2:\n data = json.load(f2)\n token = data.get(\"access_token\") or data.get(\"token\")\n if not token:\n raise ValueError(\"No access_token found after regeneration\")\n else:\n raise RuntimeError(\"Failed to regenerate expired token\")\n\n username = _extract_username_from_jwt(token)\n logger.info(f\"✓ Token loaded from: {abs_path}\")\n logger.info(f\" User: {username}\")\n logger.info(f\" Token length: {len(token)} characters\")\n return token, username\n except FileNotFoundError:\n logger.error(f\"✗ Token file not found: {abs_path}\")\n logger.error(f\" Current directory: {os.getcwd()}\")\n logger.error(f\" Looking for: {abs_path}\")\n raise FileNotFoundError(f\"Token file not found: {abs_path}\")\n except json.JSONDecodeError as e:\n logger.error(f\"✗ Invalid JSON in token file: {abs_path}\")\n logger.error(f\" Error: {e}\")\n raise ValueError(f\"Invalid JSON in token file: {abs_path}\")\n\n\ndef _make_request(\n method: str,\n url: str,\n token: str,\n data: dict[str, Any] | None = None,\n params: dict[str, Any] | None = None,\n timeout: int = REQUEST_TIMEOUT,\n) -> requests.Response:\n \"\"\"Make HTTP request with Bearer token.\"\"\"\n headers = {\n \"Authorization\": f\"Bearer {token[:50]}...\" if token else \"Bearer \",\n \"Content-Type\": \"application/json\",\n }\n\n logger.info(f\"HTTP {method} Request:\")\n logger.info(f\" URL: {url}\")\n logger.info(\" Headers:\")\n logger.info(\n f\" Authorization: Bearer {token[:50]}...\" if token else \" Authorization: \"\n )\n logger.info(\" Content-Type: application/json\")\n if params:\n logger.info(f\" Query Params: {json.dumps(params, indent=2)}\")\n if data:\n logger.info(f\" Request Body: {len(json.dumps(data))} bytes\")\n logger.debug(f\" Request Data: {json.dumps(data, indent=2)}\")\n logger.info(f\" Timeout: {timeout}s\")\n\n headers[\"Authorization\"] = f\"Bearer {token}\"\n\n try:\n logger.info(f\"→ Sending {method} request to {url}...\")\n response = requests.request(\n method=method,\n url=url,\n json=data,\n params=params,\n headers=headers,\n timeout=timeout,\n )\n\n # Log response details\n logger.info(f\"← Received HTTP {response.status_code}\")\n logger.info(\" Response Headers:\")\n for header_name, header_value in response.headers.items():\n # Hide sensitive headers\n if header_name.lower() in [\"authorization\", \"x-scopes\"]:\n logger.info(\n f\" {header_name}: {header_value[:50]}...\"\n if len(str(header_value)) > 50\n else f\" {header_name}: {header_value}\"\n )\n else:\n logger.info(f\" {header_name}: {header_value}\")\n\n response_size = len(response.content) if response.content else 0\n logger.info(f\" Response Body: {response_size} bytes\")\n\n if response.status_code >= 400:\n logger.warning(f\"✗ HTTP {response.status_code} Error\")\n try:\n resp_json = response.json()\n logger.warning(f\" Error Response: {json.dumps(resp_json, indent=2)}\")\n except json.JSONDecodeError:\n logger.warning(f\" Error Response (raw): {response.text[:200]}\")\n else:\n logger.info(f\"✓ HTTP {response.status_code} Success\")\n\n return response\n\n except requests.exceptions.Timeout as e:\n logger.error(f\"✗ Request timed out after {timeout}s: {url}\")\n logger.error(f\" Error: {e}\")\n raise TimeoutError(f\"Request timed out after {timeout} seconds: {url}\")\n except requests.exceptions.ConnectionError as e:\n logger.error(f\"✗ Failed to connect to {url}\")\n logger.error(f\" Error: {e}\")\n logger.error(f\" Check if service is running at {url}\")\n raise ConnectionError(f\"Failed to connect to {url}: {e}\")\n except requests.exceptions.RequestException as e:\n logger.error(f\"✗ Request failed: {e}\")\n raise RuntimeError(f\"Request failed: {e}\")\n\n\ndef _print_response(response: requests.Response) -> None:\n \"\"\"Pretty print response.\"\"\"\n try:\n data = response.json()\n print(json.dumps(data, indent=2))\n except json.JSONDecodeError:\n print(response.text)\n\n\ndef list_agents(\n base_url: str,\n token: str,\n) -> None:\n \"\"\"List all agents via A2A Agent Management API.\"\"\"\n endpoint = f\"{base_url}{API_BASE}\"\n logger.info(f\"Listing all agents from {endpoint}...\")\n\n try:\n response = _make_request(\"GET\", endpoint, token)\n\n if response.status_code == 200:\n data = response.json()\n agents = data.get(\"agents\", [])\n total_count = data.get(\"total_count\", 0)\n\n if agents:\n print(f\"Found {total_count} agent(s):\")\n print(\"-\" * 120)\n print(f\"{'Agent Name':<40} | {'Path':<25} | {'Status':<8}\")\n print(\"-\" * 120)\n for agent in agents:\n name = agent.get(\"name\", \"unknown\")\n path = agent.get(\"path\", \"unknown\")\n is_enabled = agent.get(\"is_enabled\", False)\n status = \"ENABLED\" if is_enabled else \"DISABLED\"\n print(f\"{name:<40} | {path:<25} | {status:<8}\")\n print(\"-\" * 120)\n else:\n print(\"No agents found\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n print(\"Make sure your JWT token is valid and not expired\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef get_agent(\n base_url: str,\n token: str,\n agent_path: str,\n) -> None:\n \"\"\"Get agent details via A2A Agent Management API.\"\"\"\n # Normalize path: /code-reviewer -> /code-reviewer\n if not agent_path.startswith(\"/\"):\n agent_path = \"/\" + agent_path\n\n endpoint = f\"{base_url}{API_BASE}{agent_path}\"\n\n logger.info(f\"Getting agent details for path '{agent_path}'...\")\n\n try:\n response = _make_request(\"GET\", endpoint, token)\n\n if response.status_code == 200:\n print(f\"Agent details for: {agent_path}\")\n _print_response(response)\n elif response.status_code == 404:\n print(f\"Error: Agent at path '{agent_path}' not found\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n elif response.status_code == 403:\n print(\"Error: Access denied - you do not have permission to view this agent\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef _check_agent_health(\n agent_url: str,\n) -> tuple[bool, str]:\n \"\"\"\n Check agent health by fetching agent card from /.well-known/agent-card.json.\n\n Args:\n agent_url: Base URL of the agent service\n\n Returns:\n Tuple of (success: bool, message: str)\n \"\"\"\n if not agent_url:\n return False, \"Agent URL not provided\"\n\n health_endpoint = f\"{agent_url}/.well-known/agent-card.json\"\n logger.info(f\"Checking agent health at: {health_endpoint}\")\n\n try:\n response = requests.get(\n health_endpoint,\n timeout=REQUEST_TIMEOUT,\n headers={\"Content-Type\": \"application/json\"},\n )\n\n if response.status_code == 200:\n try:\n card_data = response.json()\n agent_name = card_data.get(\"name\", \"unknown\")\n return True, f\"Agent card retrieved successfully from {agent_name}\"\n except json.JSONDecodeError:\n return False, \"Agent returned invalid JSON for agent card\"\n elif response.status_code == 404:\n return False, \"Agent card endpoint not found (/.well-known/agent-card.json)\"\n elif response.status_code == 503:\n return False, \"Agent service unavailable (503)\"\n else:\n return False, f\"Agent returned HTTP {response.status_code}\"\n\n except requests.exceptions.Timeout:\n return False, f\"Agent health check timed out ({REQUEST_TIMEOUT}s)\"\n except requests.exceptions.ConnectionError:\n return False, \"Cannot connect to agent service (connection refused)\"\n except Exception as e:\n return False, f\"Health check error: {str(e)}\"\n\n\ndef test_agent(\n base_url: str,\n token: str,\n agent_path: str,\n) -> None:\n \"\"\"Test agent accessibility and health via A2A Agent Management API.\"\"\"\n # Normalize path\n if not agent_path.startswith(\"/\"):\n agent_path = \"/\" + agent_path\n\n endpoint = f\"{base_url}{API_BASE}{agent_path}\"\n\n logger.info(f\"Testing agent at path '{agent_path}'...\")\n\n try:\n response = _make_request(\"GET\", endpoint, token)\n\n if response.status_code == 200:\n data = response.json()\n name = data.get(\"name\", \"unknown\")\n description = data.get(\"description\", \"\")\n is_enabled = data.get(\"is_enabled\", False)\n agent_url = data.get(\"url\", \"\")\n\n print(f\"Agent: {name}\")\n print(f\"Path: {agent_path}\")\n print(f\"Status: {'ENABLED' if is_enabled else 'DISABLED'}\")\n print(f\"Description: {description}\")\n print(f\"Service URL: {agent_url}\")\n\n # Perform health check if agent is enabled and has URL\n if is_enabled and agent_url:\n print(\"\\nPerforming health check...\")\n health_passed, health_message = _check_agent_health(agent_url)\n if health_passed:\n print(\" Health Check: PASSED\")\n print(f\" Details: {health_message}\")\n else:\n print(\" Health Check: FAILED\")\n print(f\" Reason: {health_message}\")\n elif not is_enabled:\n print(\"\\nHealth Check: SKIPPED (agent is disabled)\")\n elif not agent_url:\n print(\"\\nHealth Check: SKIPPED (no service URL configured)\")\n\n print(\"\\nAgent Registry Details:\")\n _print_response(response)\n elif response.status_code == 404:\n print(f\"Error: Agent at path '{agent_path}' not found\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n elif response.status_code == 403:\n print(\"Error: Access denied - you do not have permission to view this agent\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef test_all_agents(\n base_url: str,\n token: str,\n) -> None:\n \"\"\"Test all agents accessibility and health.\"\"\"\n endpoint = f\"{base_url}{API_BASE}\"\n logger.info(\"Testing all agents...\")\n\n try:\n response = _make_request(\"GET\", endpoint, token)\n\n if response.status_code == 200:\n data = response.json()\n agents = data.get(\"agents\", [])\n\n if not agents:\n print(\"No agents to test\")\n return\n\n passed = 0\n failed = 0\n\n print(\"Testing agents:\")\n print(\"-\" * 100)\n print(f\"{'Agent Name':<35} | {'Registry':<8} | {'Health Check':<20}\")\n print(\"-\" * 100)\n\n for agent in agents:\n name = agent.get(\"name\", \"unknown\")\n is_enabled = agent.get(\"is_enabled\", False)\n agent_url = agent.get(\"url\", \"\")\n registry_status = \"ENABLED\" if is_enabled else \"DISABLED\"\n\n # Perform health check if agent is enabled\n if is_enabled and agent_url:\n health_passed, _ = _check_agent_health(agent_url)\n health_status = \"PASSED\" if health_passed else \"FAILED\"\n if health_passed:\n passed += 1\n else:\n failed += 1\n else:\n health_status = \"SKIPPED\"\n passed += 1\n\n # Color-coded status\n if health_status == \"PASSED\":\n result_icon = \"✓\"\n elif health_status == \"FAILED\":\n result_icon = \"✗\"\n else:\n result_icon = \"-\"\n\n print(f\"{name:<35} | {registry_status:<8} | {result_icon} {health_status:<17}\")\n\n print(\"-\" * 100)\n print(f\"Summary: {passed} passed, {failed} failed\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef search_agents(\n base_url: str,\n token: str,\n query: str,\n max_results: int = 10,\n) -> None:\n \"\"\"Search agents using semantic search via natural language query.\"\"\"\n endpoint = f\"{base_url}{API_BASE}/discover/semantic\"\n logger.info(f\"Searching agents with query: {query}\")\n\n params = {\n \"query\": query,\n \"max_results\": max_results,\n }\n\n try:\n response = _make_request(\"POST\", endpoint, token, params=params)\n\n if response.status_code == 200:\n data = response.json()\n results = data.get(\"agents\", [])\n\n if results:\n print(f\"Found {len(results)} agent(s) matching '{query}':\")\n print(\"-\" * 110)\n print(f\"{'Agent Name':<40} | {'Path':<25} | {'Score':<8}\")\n print(\"-\" * 110)\n for result in results:\n name = result.get(\"name\", \"unknown\")\n path = result.get(\"path\", \"unknown\")\n score = result.get(\"score\", 0.0)\n print(f\"{name:<40} | {path:<25} | {score:>7.4f}\")\n print(\"-\" * 110)\n else:\n print(f\"No agents found matching '{query}'\")\n elif response.status_code == 400:\n print(\"Error: Invalid search query (empty or malformed)\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef register_agent(\n base_url: str,\n token: str,\n agent_file: str,\n) -> None:\n \"\"\"Register agent from JSON file via A2A Agent Management API.\"\"\"\n import os\n\n abs_agent_file = os.path.abspath(agent_file)\n logger.info(f\"Loading agent file from: {abs_agent_file}\")\n\n try:\n with open(abs_agent_file) as f:\n agent_data = json.load(f)\n logger.info(\"✓ Agent file loaded successfully\")\n except FileNotFoundError:\n logger.error(f\"✗ Agent file not found: {abs_agent_file}\")\n print(f\"Error: File not found: {abs_agent_file}\")\n sys.exit(1)\n except json.JSONDecodeError as e:\n logger.error(f\"✗ Invalid JSON in file: {abs_agent_file}\")\n logger.error(f\" Error: {e}\")\n print(f\"Error: Invalid JSON in file: {abs_agent_file}\")\n sys.exit(1)\n\n # Use A2A Agent Management API endpoint for registration\n # Note: Goes through Nginx for JWT Bearer token validation via auth-server\n endpoint = f\"{base_url}/api/agents/register\"\n agent_name = agent_data.get(\"name\", \"Unknown\")\n\n logger.info(\"=\" * 80)\n logger.info(\"AGENT REGISTRATION REQUEST\")\n logger.info(\"=\" * 80)\n logger.info(f\"Base URL: {base_url}\")\n logger.info(f\"Endpoint: {endpoint}\")\n logger.info(f\"Agent Name: {agent_name}\")\n logger.info(f\"Agent Path: {agent_data.get('path', 'N/A')}\")\n logger.info(f\"Agent File: {abs_agent_file}\")\n logger.info(\"=\" * 80)\n\n try:\n response = _make_request(\"POST\", endpoint, token, agent_data)\n\n if response.status_code == 201:\n logger.info(f\"✓ Agent '{agent_name}' registered successfully!\")\n print(f\"Agent '{agent_name}' registered successfully!\")\n _print_response(response)\n elif response.status_code == 401:\n logger.error(\"✗ Authentication failed (HTTP 401)\")\n logger.error(f\" Token file location: {os.path.abspath('.oauth-tokens/ingress.json')}\")\n logger.error(f\" Token length: {len(token) if token else 0} characters\")\n logger.error(\n f\" Authorization header: Bearer {token[:50]}...\"\n if token\n else \" Authorization header: \"\n )\n print(\"Error: Authentication failed (HTTP 401)\")\n print(\"\\nDEBUG INFORMATION:\")\n print(f\" Token file: {os.path.abspath('.oauth-tokens/ingress.json')}\")\n print(f\" Token length: {len(token) if token else 0} characters\")\n print(\"\\nNOTE: Make sure you have a valid token in '.oauth-tokens/ingress.json'\")\n print(\" The token should contain 'a2a-agent-admin' in groups claim\")\n print(\" Regenerate with: ./credentials-provider/generate_creds.sh\")\n print(\"\\nRESPONSE:\")\n _print_response(response)\n elif response.status_code == 409:\n path = agent_data.get(\"path\", \"unknown\")\n print(f\"Error: Agent with path '{path}' already exists\")\n _print_response(response)\n elif response.status_code == 422:\n print(\"Error: Validation failed - check agent JSON format\")\n _print_response(response)\n elif response.status_code == 403:\n print(\"Error: Permission denied. You do not have permission to register agents\")\n print(\n \"\\nNote: Agent registration requires proper Keycloak authentication with 'register_service' permission.\"\n )\n print(\"For testing/development, you may need to:\")\n print(\" 1. Configure a Keycloak user with appropriate permissions\")\n print(\" 2. Use the web UI dashboard to register agents\")\n print(\" 3. Contact your administrator to grant registration permissions\")\n _print_response(response)\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef update_agent(\n base_url: str,\n token: str,\n agent_path: str,\n agent_file: str,\n) -> None:\n \"\"\"Update agent via A2A Agent Management API.\"\"\"\n # Normalize path\n if not agent_path.startswith(\"/\"):\n agent_path = \"/\" + agent_path\n\n abs_agent_file = os.path.abspath(agent_file)\n logger.info(f\"Loading agent file from: {abs_agent_file}\")\n\n try:\n with open(abs_agent_file) as f:\n agent_data = json.load(f)\n logger.info(\"✓ Agent file loaded successfully\")\n except FileNotFoundError:\n logger.error(f\"✗ Agent file not found: {abs_agent_file}\")\n print(f\"Error: File not found: {abs_agent_file}\")\n sys.exit(1)\n except json.JSONDecodeError as e:\n logger.error(f\"✗ Invalid JSON in file: {abs_agent_file}\")\n logger.error(f\" Error: {e}\")\n print(f\"Error: Invalid JSON in file: {abs_agent_file}\")\n sys.exit(1)\n\n endpoint = f\"{base_url}{API_BASE}{agent_path}\"\n agent_name = agent_data.get(\"name\", \"Unknown\")\n\n logger.info(f\"Updating agent at path '{agent_path}'...\")\n\n try:\n response = _make_request(\"PUT\", endpoint, token, agent_data)\n\n if response.status_code == 200:\n logger.info(f\"✓ Agent '{agent_name}' updated successfully!\")\n print(f\"Agent '{agent_name}' updated successfully!\")\n _print_response(response)\n elif response.status_code == 404:\n print(f\"Error: Agent at path '{agent_path}' not found\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n elif response.status_code == 403:\n print(\"Error: Access denied - you do not have permission to update this agent\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef delete_agent(\n base_url: str,\n token: str,\n agent_path: str,\n) -> None:\n \"\"\"Delete agent via A2A Agent Management API.\"\"\"\n # Normalize path\n if not agent_path.startswith(\"/\"):\n agent_path = \"/\" + agent_path\n\n endpoint = f\"{base_url}{API_BASE}{agent_path}\"\n\n logger.info(f\"Deleting agent at path '{agent_path}'...\")\n\n try:\n response = _make_request(\"DELETE\", endpoint, token)\n\n if response.status_code == 204:\n logger.info(f\"✓ Agent at path '{agent_path}' deleted successfully!\")\n print(f\"Agent at path '{agent_path}' deleted successfully!\")\n elif response.status_code == 404:\n print(f\"Error: Agent at path '{agent_path}' not found\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n elif response.status_code == 403:\n print(\"Error: Access denied - you do not have permission to delete this agent\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef toggle_agent(\n base_url: str,\n token: str,\n agent_path: str,\n enabled: bool,\n) -> None:\n \"\"\"Toggle agent enabled/disabled status via A2A Agent Management API.\"\"\"\n # Normalize path\n if not agent_path.startswith(\"/\"):\n agent_path = \"/\" + agent_path\n\n endpoint = f\"{base_url}{API_BASE}{agent_path}/toggle\"\n params = f\"?enabled={str(enabled).lower()}\"\n\n logger.info(f\"Setting agent at path '{agent_path}' to {enabled}...\")\n\n try:\n response = _make_request(\"POST\", endpoint + params, token)\n\n if response.status_code == 200:\n data = response.json()\n is_enabled = data.get(\"is_enabled\", False)\n status = \"ENABLED\" if is_enabled else \"DISABLED\"\n logger.info(f\"✓ Agent at path '{agent_path}' toggled successfully!\")\n print(f\"Agent at path '{agent_path}' is now {status}\")\n _print_response(response)\n elif response.status_code == 404:\n print(f\"Error: Agent at path '{agent_path}' not found\")\n elif response.status_code == 401:\n print(\"Error: Authentication failed (401)\")\n elif response.status_code == 403:\n print(\"Error: Access denied - you do not have permission to toggle this agent\")\n else:\n print(f\"Error: HTTP {response.status_code}\")\n _print_response(response)\n\n except (TimeoutError, ConnectionError, RuntimeError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\ndef main() -> None:\n \"\"\"Main entry point.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Agent Management Script for MCP Gateway Registry - A2A Agent Management API\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # List all agents\n uv run python cli/agent_mgmt.py list\n\n # Get agent details\n uv run python cli/agent_mgmt.py get /code-reviewer\n\n # Register an agent from JSON file\n uv run python cli/agent_mgmt.py register cli/examples/test_code_reviewer_agent.json\n\n # Update an agent with new JSON\n uv run python cli/agent_mgmt.py update /code-reviewer cli/examples/updated_agent.json\n\n # Enable an agent\n uv run python cli/agent_mgmt.py toggle /code-reviewer true\n\n # Disable an agent\n uv run python cli/agent_mgmt.py toggle /code-reviewer false\n\n # Delete an agent\n uv run python cli/agent_mgmt.py delete /code-reviewer\n\n # Test agent accessibility\n uv run python cli/agent_mgmt.py test /code-reviewer\n\n # Test all agents\n uv run python cli/agent_mgmt.py test-all\n\n # Search agents with semantic query\n uv run python cli/agent_mgmt.py search \"code review tool\"\n\nFor more information on creating agent JSON files:\n cat cli/examples/README.md\n\"\"\",\n )\n\n parser.add_argument(\n \"--base-url\",\n default=DEFAULT_BASE_URL,\n help=f\"Base URL for API (default: {DEFAULT_BASE_URL})\",\n )\n parser.add_argument(\n \"--token-file\",\n default=DEFAULT_TOKEN_FILE,\n help=f\"Path to token JSON file (default: {DEFAULT_TOKEN_FILE})\",\n )\n parser.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable debug logging\",\n )\n\n subparsers = parser.add_subparsers(dest=\"command\", help=\"Command to execute\")\n\n # Register command\n register_parser = subparsers.add_parser(\"register\", help=\"Register agent from JSON file\")\n register_parser.add_argument(\"file\", help=\"Path to agent JSON file\")\n\n # List command\n subparsers.add_parser(\"list\", help=\"List all agents\")\n\n # Get command\n get_parser = subparsers.add_parser(\"get\", help=\"Get agent details\")\n get_parser.add_argument(\"path\", help=\"Agent path (e.g., /code-reviewer)\")\n\n # Test command\n test_parser = subparsers.add_parser(\"test\", help=\"Test agent accessibility\")\n test_parser.add_argument(\"path\", help=\"Agent path (e.g., /code-reviewer)\")\n\n # Test all command\n subparsers.add_parser(\"test-all\", help=\"Test all agents\")\n\n # Search command\n search_parser = subparsers.add_parser(\"search\", help=\"Search agents using semantic query\")\n search_parser.add_argument(\n \"query\", help=\"Natural language search query (e.g., 'code review agent')\"\n )\n search_parser.add_argument(\n \"--max-results\",\n type=int,\n default=10,\n help=\"Maximum number of results (default: 10)\",\n )\n\n # Update command\n update_parser = subparsers.add_parser(\"update\", help=\"Update agent from JSON file\")\n update_parser.add_argument(\"path\", help=\"Agent path (e.g., /code-reviewer)\")\n update_parser.add_argument(\"file\", help=\"Path to updated agent JSON file\")\n\n # Delete command\n delete_parser = subparsers.add_parser(\"delete\", help=\"Delete agent\")\n delete_parser.add_argument(\"path\", help=\"Agent path (e.g., /code-reviewer)\")\n\n # Toggle command\n toggle_parser = subparsers.add_parser(\"toggle\", help=\"Toggle agent enabled/disabled status\")\n toggle_parser.add_argument(\"path\", help=\"Agent path (e.g., /code-reviewer)\")\n toggle_parser.add_argument(\n \"enabled\",\n type=lambda x: x.lower() == \"true\",\n help=\"Enable (true) or disable (false) the agent\",\n )\n\n args = parser.parse_args()\n\n if args.debug:\n logger.setLevel(logging.DEBUG)\n\n if not args.command:\n parser.print_help()\n sys.exit(1)\n\n # Load token\n try:\n token, username = _load_token(args.token_file)\n except (FileNotFoundError, ValueError) as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n # Execute command\n if args.command == \"list\":\n list_agents(args.base_url, token)\n elif args.command == \"get\":\n get_agent(args.base_url, token, args.path)\n elif args.command == \"test\":\n test_agent(args.base_url, token, args.path)\n elif args.command == \"test-all\":\n test_all_agents(args.base_url, token)\n elif args.command == \"search\":\n search_agents(args.base_url, token, args.query, args.max_results)\n elif args.command == \"register\":\n register_agent(args.base_url, token, args.file)\n elif args.command == \"update\":\n update_agent(args.base_url, token, args.path, args.file)\n elif args.command == \"delete\":\n delete_agent(args.base_url, token, args.path)\n elif args.command == \"toggle\":\n toggle_agent(args.base_url, token, args.path, args.enabled)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/agent_mgmt.sh", "content": "#!/bin/bash\n\n# DEPRECATED: This script is deprecated in favor of the Registry Management API\n# Use: uv run python api/registry_management.py OR cli/registry_cli_wrapper.py\n# See: api/README.md for documentation\n#\n# Agent Management Script for MCP Gateway Registry\n# Usage: ./cli/agent_mgmt.sh {register|list|get|test|test-all} [args...]\n\necho \"WARNING: This script is DEPRECATED. Please use the Registry Management API instead:\"\necho \" uv run python api/registry_management.py agent-register --help\"\necho \" uv run python api/registry_management.py agent-list --help\"\necho \"See api/README.md for full documentation.\"\necho \"\"\n\nset -e\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m' # No Color\n\n# Get script directory and project root\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nPROJECT_ROOT=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Load environment variables from .env file if it exists\nif [ -f \"$PROJECT_ROOT/.env\" ]; then\n set -a\n source \"$PROJECT_ROOT/.env\"\n set +a\nfi\n\n# Default values\nBASE_URL=\"${BASE_URL:-http://localhost}\" # Goes through nginx (port 80), not direct :7860\nTOKEN_FILE=\"${TOKEN_FILE:-.oauth-tokens/ingress.json}\"\nDEBUG=\"${DEBUG:-false}\"\n\nprint_success() {\n echo -e \"${GREEN}✓ $1${NC}\"\n}\n\nprint_error() {\n echo -e \"${RED}✗ $1${NC}\"\n}\n\nprint_info() {\n echo -e \"${YELLOW}ℹ $1${NC}\"\n}\n\nshow_usage() {\n cat << EOF\nAgent Management Script for MCP Gateway Registry\n\nUsage: $0 {command} [options]\n\nCommands:\n register Register agent from JSON file\n list List all agents\n get Get agent details\n update Update agent from JSON file\n delete Delete agent\n toggle Enable/disable agent\n test Test agent accessibility\n test-all Test all agents\n search Search agents using semantic query\n\nOptions:\n --base-url URL Base URL for API (default: $BASE_URL)\n --token-file FILE Path to token JSON file (default: $TOKEN_FILE)\n --debug Enable debug logging\n\nExamples:\n # Register an agent from JSON file\n $0 register cli/examples/test_code_reviewer_agent.json\n\n # List all agents\n $0 list\n\n # Get agent details\n $0 get /test-reviewer\n\n # Update an agent\n $0 update /test-reviewer cli/examples/updated_agent.json\n\n # Enable an agent\n $0 toggle /test-reviewer true\n\n # Disable an agent\n $0 toggle /test-reviewer false\n\n # Delete an agent\n $0 delete /test-reviewer\n\n # Test agent accessibility\n $0 test /test-reviewer\n\n # Test all agents\n $0 test-all\n\n # Search agents with semantic query\n $0 search \"code review tool\"\n\nPrerequisites:\n Ensure the registry and nginx services are running:\n 1. Registry service (port 7860)\n 2. Nginx reverse proxy (port 80)\n\n Docker setup:\n docker-compose up -d\n\nFor more information, run:\n uv run python cli/agent_mgmt.py --help\n cat cli/examples/README.md\nEOF\n}\n\n# Check if no arguments provided\nif [ $# -eq 0 ]; then\n show_usage\n exit 1\nfi\n\n# Parse command\ncommand=\"$1\"\nshift\n\n# Check if help is requested\nif [ \"$command\" = \"-h\" ] || [ \"$command\" = \"--help\" ]; then\n show_usage\n exit 0\nfi\n\n# Build Python command with arguments\npython_args=(\"--base-url\" \"$BASE_URL\" \"--token-file\" \"$TOKEN_FILE\")\n\nif [ \"$DEBUG\" = \"true\" ]; then\n python_args+=(\"--debug\")\nfi\n\npython_args+=(\"$command\")\n\n# Add remaining arguments\nwhile [ $# -gt 0 ]; do\n python_args+=(\"$1\")\n shift\ndone\n\nprint_info \"Running: uv run python cli/agent_mgmt.py ${python_args[@]}\"\n\n# Execute Python script\ncd \"$PROJECT_ROOT\"\nif uv run python cli/agent_mgmt.py \"${python_args[@]}\"; then\n exit 0\nelse\n print_error \"Agent management command failed\"\n exit 1\nfi\n" }, { "path": "cli/agentcore/__init__.py", "content": "\"\"\"AgentCore Auto-Registration CLI package.\n\nAutomates discovery and registration of AWS Bedrock AgentCore Gateways\nand Agent Runtimes with the MCP Gateway Registry.\n\nUsage:\n python -m cli.agentcore.sync [sync|list] [options]\n\"\"\"\n\n__version__ = \"0.1.0\"\n" }, { "path": "cli/agentcore/__main__.py", "content": "\"\"\"Allow ``python -m cli.agentcore`` invocation.\"\"\"\n\nimport sys\n\nfrom .sync import main\n\nsys.exit(main())\n" }, { "path": "cli/agentcore/discovery.py", "content": "\"\"\"AWS AgentCore resource discovery via boto3.\n\nScans AgentCore Gateways and Agent Runtimes using the\n``bedrock-agentcore-control`` boto3 client, filtering to READY\nresources and paginating through all pages.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom typing import Any\n\nimport boto3\nfrom botocore.config import Config as BotoConfig\n\nfrom .models import DEFAULT_TIMEOUT, READY_STATUS\n\nlogger = logging.getLogger(__name__)\n\n\nclass AgentCoreScanner:\n \"\"\"Scans AWS AgentCore resources using boto3.\n\n Configures the boto3 client with connect/read timeouts and\n standard retry mode (3 attempts). All list operations paginate\n via ``nextToken`` and only READY resources are returned.\n \"\"\"\n\n def __init__(\n self,\n region: str,\n timeout: int = DEFAULT_TIMEOUT,\n session: boto3.Session | None = None,\n ) -> None:\n \"\"\"Initialize scanner with AWS region, timeout, and optional boto3 session.\n\n Args:\n region: AWS region to scan.\n timeout: AWS API call timeout in seconds.\n session: Optional boto3 session (e.g. from STS AssumeRole for\n cross-account scanning). Uses default credentials if None.\n \"\"\"\n self.region = region\n self.timeout = timeout\n\n boto_config = BotoConfig(\n connect_timeout=timeout,\n read_timeout=timeout,\n retries={\"max_attempts\": 3, \"mode\": \"standard\"},\n )\n if session:\n self.client = session.client(\n \"bedrock-agentcore-control\",\n region_name=region,\n config=boto_config,\n )\n else:\n self.client = boto3.client(\n \"bedrock-agentcore-control\",\n region_name=region,\n config=boto_config,\n )\n logger.info(\n f\"Initialized AgentCore scanner for region: {region} \"\n f\"(timeout: {timeout}s, cross_account: {session is not None})\"\n )\n\n # ------------------------------------------------------------------\n # Gateway scanning\n # ------------------------------------------------------------------\n\n def scan_gateways(self) -> list[dict[str, Any]]:\n \"\"\"Scan all AgentCore Gateways in the region.\n\n Paginates through ``list_gateways()``, filters to READY status,\n fetches full details via ``get_gateway()``, and collects targets.\n \"\"\"\n gateways: list[dict[str, Any]] = []\n paginator_params: dict[str, Any] = {}\n\n while True:\n response = self.client.list_gateways(**paginator_params)\n\n for item in response.get(\"items\", []):\n if item.get(\"status\") == READY_STATUS:\n gateway = self.client.get_gateway(gatewayIdentifier=item[\"gatewayId\"])\n gateway[\"targets\"] = self._get_gateway_targets(item[\"gatewayId\"])\n gateways.append(gateway)\n else:\n logger.debug(\n f\"Skipping gateway {item['gatewayId']} with status {item['status']}\"\n )\n\n if \"nextToken\" in response:\n paginator_params[\"nextToken\"] = response[\"nextToken\"]\n else:\n break\n\n logger.info(f\"Found {len(gateways)} READY gateways\")\n return gateways\n\n def _get_gateway_targets(\n self,\n gateway_id: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Get all targets for a gateway.\n\n Paginates through ``list_gateway_targets()`` and fetches full\n details for READY targets.\n \"\"\"\n targets: list[dict[str, Any]] = []\n paginator_params: dict[str, Any] = {\"gatewayIdentifier\": gateway_id}\n\n while True:\n response = self.client.list_gateway_targets(**paginator_params)\n\n for item in response.get(\"items\", []):\n if item.get(\"status\") == READY_STATUS:\n target = self.client.get_gateway_target(\n gatewayIdentifier=gateway_id,\n targetId=item[\"targetId\"],\n )\n targets.append(target)\n\n if \"nextToken\" in response:\n paginator_params[\"nextToken\"] = response[\"nextToken\"]\n else:\n break\n\n return targets\n\n # ------------------------------------------------------------------\n # Runtime scanning\n # ------------------------------------------------------------------\n\n def scan_runtimes(self) -> list[dict[str, Any]]:\n \"\"\"Scan all AgentCore Runtimes in the region.\n\n Paginates through ``list_agent_runtimes()``, filters to READY\n status, fetches full details via ``get_agent_runtime()``, and\n collects endpoints.\n \"\"\"\n runtimes: list[dict[str, Any]] = []\n paginator_params: dict[str, Any] = {}\n\n while True:\n response = self.client.list_agent_runtimes(**paginator_params)\n\n for item in response.get(\"agentRuntimes\", []):\n if item.get(\"status\") == READY_STATUS:\n runtime = self.client.get_agent_runtime(agentRuntimeId=item[\"agentRuntimeId\"])\n runtime[\"endpoints\"] = self._get_runtime_endpoints(item[\"agentRuntimeId\"])\n runtimes.append(runtime)\n else:\n logger.debug(\n f\"Skipping runtime {item['agentRuntimeId']} with status {item['status']}\"\n )\n\n if \"nextToken\" in response:\n paginator_params[\"nextToken\"] = response[\"nextToken\"]\n else:\n break\n\n logger.info(f\"Found {len(runtimes)} READY runtimes\")\n return runtimes\n\n def _get_runtime_endpoints(\n self,\n runtime_id: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Get all endpoints for a runtime.\n\n Paginates through ``list_agent_runtime_endpoints()`` and\n returns READY endpoints.\n \"\"\"\n endpoints: list[dict[str, Any]] = []\n paginator_params: dict[str, Any] = {\"agentRuntimeId\": runtime_id}\n\n while True:\n response = self.client.list_agent_runtime_endpoints(**paginator_params)\n\n for item in response.get(\"runtimeEndpoints\", []):\n if item.get(\"status\") == READY_STATUS:\n endpoints.append(item)\n\n if \"nextToken\" in response:\n paginator_params[\"nextToken\"] = response[\"nextToken\"]\n else:\n break\n\n return endpoints\n" }, { "path": "cli/agentcore/models.py", "content": "\"\"\"Pydantic models and helper functions for AgentCore auto-registration.\n\nContains data models for discovered resources and sync results,\nplus utility functions for URL construction, slugification, auth\nscheme mapping, and token loading.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport re\nfrom typing import Any\nfrom urllib.parse import quote\n\nfrom pydantic import BaseModel, Field\n\nlogger = logging.getLogger(__name__)\n\n# Constants\nDEFAULT_REGISTRY_URL = \"http://localhost\"\nDEFAULT_TOKEN_FILE = \".token\"\nDEFAULT_REGION = \"us-east-1\"\nDEFAULT_TIMEOUT = 30\nDEFAULT_MANIFEST_PATH = \"token_refresh_manifest.json\"\nREADY_STATUS = \"READY\"\n\n\n# ---------------------------------------------------------------------------\n# Pydantic Models\n# ---------------------------------------------------------------------------\n\n\nclass TargetInfo(BaseModel):\n \"\"\"Discovered Gateway Target information.\"\"\"\n\n target_id: str = Field(..., description=\"Target ID\")\n name: str = Field(..., description=\"Target name\")\n description: str | None = Field(None, description=\"Target description\")\n status: str = Field(..., description=\"Target status\")\n target_type: str = Field(..., description=\"mcpServer, lambda, apiGateway, etc.\")\n endpoint: str | None = Field(None, description=\"MCP server endpoint (for mcpServer type)\")\n\n\nclass GatewayInfo(BaseModel):\n \"\"\"Discovered AgentCore Gateway information.\"\"\"\n\n gateway_id: str = Field(..., description=\"Gateway ID\")\n gateway_arn: str = Field(..., description=\"Gateway ARN\")\n gateway_url: str = Field(..., description=\"Gateway MCP endpoint URL\")\n name: str = Field(..., description=\"Gateway name\")\n description: str | None = Field(None, description=\"Gateway description\")\n status: str = Field(..., description=\"Gateway status\")\n authorizer_type: str = Field(..., description=\"CUSTOM_JWT, AWS_IAM, or NONE\")\n authorizer_config: dict[str, Any] | None = Field(None, description=\"Authorizer configuration\")\n targets: list[TargetInfo] = Field(default_factory=list, description=\"Gateway targets\")\n\n\nclass RuntimeInfo(BaseModel):\n \"\"\"Discovered AgentCore Runtime information.\"\"\"\n\n runtime_id: str = Field(..., description=\"Runtime ID\")\n runtime_arn: str = Field(..., description=\"Runtime ARN\")\n runtime_name: str = Field(..., description=\"Runtime name\")\n description: str | None = Field(None, description=\"Runtime description\")\n status: str = Field(..., description=\"Runtime status\")\n server_protocol: str = Field(..., description=\"MCP, HTTP, or A2A\")\n authorizer_config: dict[str, Any] | None = Field(None, description=\"Authorizer configuration\")\n invocation_url: str = Field(..., description=\"Constructed invocation URL\")\n\n\nclass SyncResult(BaseModel):\n \"\"\"Result of a sync operation.\"\"\"\n\n resource_type: str = Field(..., description=\"gateway, runtime, or target\")\n resource_name: str = Field(..., description=\"Resource name\")\n resource_arn: str = Field(..., description=\"Resource ARN\")\n registration_type: str = Field(..., description=\"mcp_server or agent\")\n path: str = Field(..., description=\"Registry path\")\n status: str = Field(..., description=\"registered, skipped, failed, dry_run\")\n message: str | None = Field(None, description=\"Status message or error\")\n\n\nclass SyncSummary(BaseModel):\n \"\"\"Summary of sync operation.\"\"\"\n\n total_gateways: int = Field(0, description=\"Total gateways found\")\n total_runtimes: int = Field(0, description=\"Total runtimes found\")\n total_targets: int = Field(0, description=\"Total mcpServer targets found\")\n registered: int = Field(0, description=\"Successfully registered\")\n skipped: int = Field(0, description=\"Skipped (already exists)\")\n failed: int = Field(0, description=\"Failed to register\")\n credentials_saved: int = Field(0, description=\"Credentials persisted to .env\")\n tokens_generated: int = Field(0, description=\"Egress tokens generated\")\n dry_run: bool = Field(False, description=\"Whether this was a dry run\")\n results: list[SyncResult] = Field(default_factory=list, description=\"Individual results\")\n\n\n# ---------------------------------------------------------------------------\n# Helper functions\n# ---------------------------------------------------------------------------\n\n\ndef _slugify(name: str) -> str:\n \"\"\"Convert name to URL-safe slug.\n\n Lowercase, replace spaces/underscores with hyphens, remove\n non-alphanumeric characters, collapse consecutive hyphens,\n strip leading/trailing hyphens. Idempotent.\n \"\"\"\n slug = name.lower().replace(\" \", \"-\").replace(\"_\", \"-\")\n slug = re.sub(r\"[^a-z0-9-]\", \"\", slug)\n slug = re.sub(r\"-+\", \"-\", slug)\n slug = slug.strip(\"-\")\n return slug\n\n\n_UPPERCASE_WORDS: set[str] = {\n \"mcp\",\n \"a2a\",\n \"sre\",\n \"api\",\n \"http\",\n \"https\",\n \"aws\",\n \"iam\",\n \"jwt\",\n \"oidc\",\n \"sso\",\n \"idp\",\n \"llm\",\n \"ai\",\n \"ml\",\n}\n\n\ndef _display_name(name: str) -> str:\n \"\"\"Convert a slug or underscore-separated name to a human-readable title.\n\n Preserves common acronyms in uppercase (MCP, A2A, SRE, API, etc.).\n\n Examples:\n geo-mcp -> Geo MCP\n weather_time_observability_gateway -> Weather Time Observability Gateway\n my-custom-sre-agent -> My Custom SRE Agent\n \"\"\"\n words = name.replace(\"-\", \" \").replace(\"_\", \" \").split()\n result = []\n for word in words:\n if word.lower() in _UPPERCASE_WORDS:\n result.append(word.upper())\n else:\n result.append(word.capitalize())\n return \" \".join(result)\n\n\ndef _validate_https_url(url: str, resource_name: str) -> bool:\n \"\"\"Validate that URL uses HTTPS protocol.\n\n Args:\n url: URL to validate.\n resource_name: Name of resource for logging.\n\n Returns:\n True if valid HTTPS URL, False otherwise.\n \"\"\"\n if not url:\n logger.warning(f\"Empty URL for resource: {resource_name}\")\n return False\n\n if not url.startswith(\"https://\"):\n logger.warning(\n f\"Insecure URL for {resource_name}: {url} - Expected HTTPS, skipping registration\"\n )\n return False\n\n return True\n\n\ndef _build_invocation_url(region: str, runtime_arn: str) -> str:\n \"\"\"Build the invocation URL for an AgentCore Runtime.\n\n Format: https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{encoded-ARN}/invocations\n \"\"\"\n encoded_arn = quote(runtime_arn, safe=\"\")\n return f\"https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{encoded_arn}/invocations\"\n\n\ndef _get_auth_scheme(authorizer_type: str) -> str:\n \"\"\"Map AgentCore authorizer type to registry auth scheme.\n\n CUSTOM_JWT -> bearer, AWS_IAM -> bearer, NONE -> none.\n Unknown types default to none.\n \"\"\"\n mapping = {\n \"CUSTOM_JWT\": \"bearer\",\n \"AWS_IAM\": \"bearer\",\n \"NONE\": \"none\",\n }\n return mapping.get(authorizer_type, \"none\")\n\n\ndef _load_token(token_file: str) -> str:\n \"\"\"Load JWT token from a JSON file.\n\n Supports two formats:\n - Flat: ``{\"access_token\": \"...\"}`` or ``{\"token\": \"...\"}``\n - Nested: ``{\"tokens\": {\"access_token\": \"...\"}}``\n\n Raises FileNotFoundError, ValueError on missing file, bad JSON,\n or missing token field.\n \"\"\"\n abs_path = os.path.abspath(token_file)\n try:\n with open(abs_path) as f:\n data = json.load(f)\n # Try top-level first, then nested under \"tokens\"\n token = data.get(\"access_token\") or data.get(\"token\")\n if not token:\n tokens_obj = data.get(\"tokens\", {})\n if isinstance(tokens_obj, dict):\n token = tokens_obj.get(\"access_token\") or tokens_obj.get(\"token\")\n if not token:\n raise ValueError(f\"No access_token or token field in token file: {abs_path}\")\n return token\n except FileNotFoundError:\n raise FileNotFoundError(f\"Token file not found: {abs_path}\")\n except json.JSONDecodeError as e:\n raise ValueError(f\"Invalid JSON in token file {abs_path}: {e}\")\n" }, { "path": "cli/agentcore/registration.py", "content": "\"\"\"Registry integration -- build registrations and orchestrate sync.\n\nContains ``RegistrationBuilder`` (maps discovered AWS resources to\nregistry models) and ``SyncOrchestrator`` (coordinates scanning,\nregistration, and manifest generation for token refresh).\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport sys\nfrom typing import Any\n\nimport boto3\nimport requests\nfrom tenacity import (\n retry,\n retry_if_exception,\n stop_after_attempt,\n wait_exponential,\n)\n\nfrom .models import (\n _build_invocation_url,\n _display_name,\n _get_auth_scheme,\n _slugify,\n _validate_https_url,\n)\n\n# Add parent directory to path for api imports\nsys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))\nfrom api.registry_client import (\n AgentRegistration,\n InternalServiceRegistration,\n RegistryClient,\n)\n\nlogger = logging.getLogger(__name__)\n\n\n# ---------------------------------------------------------------------------\n# Constants\n# ---------------------------------------------------------------------------\n\nIDP_PATTERNS: dict[str, str] = {\n \"cognito-idp\": \"cognito\",\n \"auth0.com\": \"auth0\",\n \"okta.com\": \"okta\",\n \"microsoftonline.com\": \"entra\",\n \"/realms/\": \"keycloak\",\n}\n\n\n# ---------------------------------------------------------------------------\n# Private helper functions\n# ---------------------------------------------------------------------------\n\n\ndef _detect_idp_vendor(discovery_url: str) -> str:\n \"\"\"Detect IdP vendor from OIDC discovery URL.\n\n Scans the URL for known identity-provider patterns and returns\n a short vendor label (e.g. \"cognito\", \"okta\"). Returns \"unknown\"\n when no pattern matches.\n \"\"\"\n for pattern, vendor in IDP_PATTERNS.items():\n if pattern in discovery_url:\n return vendor\n return \"unknown\"\n\n\ndef _retry_registry_call(func):\n \"\"\"Decorator: retry on ``requests.exceptions.RequestException``.\n\n 3 attempts, exponential backoff 1-4 s.\n Does NOT retry on 409 Conflict (idempotency -- resource already exists).\n \"\"\"\n\n def _should_retry(exc: BaseException) -> bool:\n if isinstance(exc, requests.exceptions.HTTPError):\n # Don't retry 409 Conflict -- it means the resource already exists\n if exc.response is not None and exc.response.status_code == 409:\n return False\n return isinstance(exc, requests.exceptions.RequestException)\n\n return retry(\n stop=stop_after_attempt(3),\n wait=wait_exponential(multiplier=1, min=1, max=4),\n retry=retry_if_exception(_should_retry),\n before_sleep=lambda retry_state: logger.warning(\n f\"Registry call failed, retrying in {retry_state.next_action.sleep}s...\"\n ),\n )(func)\n\n\ndef _is_conflict_error(exc: Exception) -> bool:\n \"\"\"Check if an exception indicates a 409 Conflict (resource already exists).\n\n Handles:\n - Direct HTTPError with 409 status code\n - Error message containing \"already exists\" or \"already registered\"\n - Tenacity RetryError wrapping any of the above\n \"\"\"\n # Check direct HTTPError response\n if hasattr(exc, \"response\") and getattr(exc.response, \"status_code\", None) == 409:\n return True\n\n # Check error message\n err_str = str(exc).lower()\n if \"already exists\" in err_str or \"already registered\" in err_str:\n return True\n\n # Unwrap tenacity RetryError\n if hasattr(exc, \"last_attempt\"):\n inner = exc.last_attempt.exception()\n if inner:\n if hasattr(inner, \"response\") and getattr(inner.response, \"status_code\", None) == 409:\n return True\n inner_str = str(inner).lower()\n if \"already exists\" in inner_str or \"already registered\" in inner_str:\n return True\n\n return False\n\n\n# ---------------------------------------------------------------------------\n# Registration Builder\n# ---------------------------------------------------------------------------\n\n\nclass RegistrationBuilder:\n \"\"\"Builds registration models from discovered AWS resources.\"\"\"\n\n def __init__(\n self,\n region: str,\n visibility: str = \"internal\",\n session: boto3.Session | None = None,\n ) -> None:\n self.region = region\n self.visibility = visibility\n self._session = session\n self.account_id = self._get_account_id()\n\n def _get_account_id(self) -> str:\n if self._session:\n sts = self._session.client(\"sts\")\n else:\n sts = boto3.client(\"sts\")\n return sts.get_caller_identity()[\"Account\"]\n\n def build_gateway_registration(\n self,\n gateway: dict[str, Any],\n ) -> InternalServiceRegistration:\n \"\"\"Build MCP Server registration from a gateway.\n\n Includes OIDC metadata (discovery_url, allowed_clients, idp_vendor)\n when the gateway uses CUSTOM_JWT authorization with a discovery URL.\n \"\"\"\n raw_name = gateway.get(\"name\", gateway[\"gatewayId\"])\n path = f\"/{_slugify(raw_name)}\"\n display = _display_name(raw_name)\n gateway_url = gateway.get(\"gatewayUrl\", \"\")\n authorizer_type = gateway.get(\"authorizerType\", \"NONE\")\n\n metadata: dict[str, Any] = {\n \"source\": \"agentcore-sync\",\n \"gateway_arn\": gateway.get(\"gatewayArn\"),\n \"gateway_id\": gateway.get(\"gatewayId\"),\n \"authorizer_type\": authorizer_type,\n \"region\": self.region,\n \"account_id\": self.account_id,\n }\n\n # Enrich metadata with OIDC details for CUSTOM_JWT gateways\n if authorizer_type == \"CUSTOM_JWT\":\n authorizer_config = gateway.get(\"authorizerConfiguration\", {})\n jwt_config = authorizer_config.get(\"customJWTAuthorizer\", {})\n discovery_url = jwt_config.get(\"discoveryUrl\", \"\")\n allowed_clients = jwt_config.get(\"allowedClients\", [])\n\n if discovery_url:\n metadata[\"discovery_url\"] = discovery_url\n metadata[\"allowed_clients\"] = allowed_clients\n metadata[\"idp_vendor\"] = _detect_idp_vendor(discovery_url)\n\n return InternalServiceRegistration(\n path=path,\n name=display,\n description=gateway.get(\"description\", f\"AgentCore Gateway: {display}\"),\n proxy_pass_url=gateway_url,\n mcp_endpoint=gateway_url,\n auth_provider=\"bedrock-agentcore\",\n auth_scheme=_get_auth_scheme(authorizer_type),\n supported_transports=[\"streamable-http\"],\n tags=[\"agentcore\", \"gateway\", \"auto-registered\"],\n overwrite=False,\n metadata=metadata,\n )\n\n def build_target_registration(\n self,\n gateway: dict[str, Any],\n target: dict[str, Any],\n ) -> InternalServiceRegistration | None:\n \"\"\"Build MCP Server registration from an mcpServer target.\n\n Returns ``None`` for non-mcpServer targets.\n \"\"\"\n target_config = target.get(\"targetConfiguration\", {})\n mcp_config = target_config.get(\"mcp\", {})\n\n if \"mcpServer\" not in mcp_config:\n return None\n\n mcp_server = mcp_config[\"mcpServer\"]\n endpoint = mcp_server.get(\"endpoint\")\n if not endpoint:\n return None\n\n target_name = target.get(\"name\", target[\"targetId\"])\n gateway_name = gateway.get(\"name\", gateway[\"gatewayId\"])\n path = f\"/{_slugify(gateway_name)}-{_slugify(target_name)}\"\n\n return InternalServiceRegistration(\n path=path,\n name=f\"{_display_name(gateway_name)} - {_display_name(target_name)}\",\n description=target.get(\n \"description\", f\"MCP Server target: {_display_name(target_name)}\"\n ),\n proxy_pass_url=endpoint,\n mcp_endpoint=endpoint,\n auth_provider=\"bedrock-agentcore\",\n auth_scheme=\"bearer\",\n supported_transports=[\"streamable-http\"],\n tags=[\"agentcore\", \"gateway-target\", \"mcp-server\", \"auto-registered\"],\n overwrite=False,\n metadata={\n \"source\": \"agentcore-sync\",\n \"gateway_arn\": gateway.get(\"gatewayArn\"),\n \"target_id\": target.get(\"targetId\"),\n \"region\": self.region,\n \"account_id\": self.account_id,\n },\n )\n\n def build_runtime_mcp_registration(\n self,\n runtime: dict[str, Any],\n ) -> InternalServiceRegistration:\n \"\"\"Build MCP Server registration from a runtime with MCP protocol.\"\"\"\n raw_name = runtime.get(\"agentRuntimeName\", runtime[\"agentRuntimeId\"])\n path = f\"/{_slugify(raw_name)}\"\n display = _display_name(raw_name)\n invocation_url = _build_invocation_url(self.region, runtime.get(\"agentRuntimeArn\", \"\"))\n\n return InternalServiceRegistration(\n path=path,\n name=display,\n description=runtime.get(\"description\", f\"AgentCore MCP Server: {display}\"),\n proxy_pass_url=invocation_url,\n mcp_endpoint=invocation_url,\n auth_provider=\"bedrock-agentcore\",\n auth_scheme=\"bearer\",\n supported_transports=[\"streamable-http\"],\n tags=[\"agentcore\", \"runtime\", \"mcp-server\", \"auto-registered\"],\n overwrite=False,\n metadata={\n \"source\": \"agentcore-sync\",\n \"runtime_arn\": runtime.get(\"agentRuntimeArn\"),\n \"runtime_id\": runtime.get(\"agentRuntimeId\"),\n \"server_protocol\": \"MCP\",\n \"region\": self.region,\n \"account_id\": self.account_id,\n },\n )\n\n def build_runtime_agent_registration(\n self,\n runtime: dict[str, Any],\n ) -> AgentRegistration:\n \"\"\"Build A2A Agent registration from a runtime with HTTP/A2A protocol.\"\"\"\n raw_name = runtime.get(\"agentRuntimeName\", runtime[\"agentRuntimeId\"])\n path = f\"/{_slugify(raw_name)}\"\n display = _display_name(raw_name)\n invocation_url = _build_invocation_url(self.region, runtime.get(\"agentRuntimeArn\", \"\"))\n protocol = runtime.get(\"protocolConfiguration\", {}).get(\"serverProtocol\", \"HTTP\")\n\n tags = [\"agentcore\", \"runtime\", \"agent\", \"auto-registered\"]\n if protocol == \"A2A\":\n tags.append(\"a2a\")\n\n return AgentRegistration(\n name=display,\n description=runtime.get(\"description\", f\"AgentCore Agent: {display}\"),\n url=invocation_url,\n path=path,\n version=\"1.0.0\",\n tags=tags,\n # Agent validator accepts: public, private, group-restricted (not \"internal\").\n # MCP Servers use \"internal\" but A2A Agents use \"public\" as the default,\n # so we map \"internal\" -> \"public\" for Agent registrations.\n visibility=\"public\" if self.visibility == \"internal\" else self.visibility,\n security_schemes={\n \"sigv4\": {\n \"type\": \"http\",\n \"scheme\": \"AWS4-HMAC-SHA256\",\n \"description\": \"AWS SigV4 request signing (IAM auth)\",\n }\n },\n security=[{\"sigv4\": []}],\n metadata={\n \"source\": \"agentcore-sync\",\n \"runtime_arn\": runtime.get(\"agentRuntimeArn\"),\n \"runtime_id\": runtime.get(\"agentRuntimeId\"),\n \"server_protocol\": protocol,\n \"region\": self.region,\n \"account_id\": self.account_id,\n },\n )\n\n\n# ---------------------------------------------------------------------------\n# Sync Orchestrator\n# ---------------------------------------------------------------------------\n\n\nclass SyncOrchestrator:\n \"\"\"Orchestrates discovery, registration, and manifest generation.\n\n Coordinates the full sync lifecycle:\n 1. Scan gateways / runtimes via ``AgentCoreScanner``\n 2. Build registrations via ``RegistrationBuilder``\n 3. Register with the registry via ``RegistryClient``\n 4. Collect manifest entries for CUSTOM_JWT gateways\n 5. Write a token-refresh manifest file for downstream tooling\n\n Supports dry-run, overwrite, scope filtering, and JSON output.\n \"\"\"\n\n def __init__(\n self,\n scanner: AgentCoreScanner,\n builder: RegistrationBuilder,\n registry_client: RegistryClient,\n dry_run: bool = False,\n overwrite: bool = False,\n include_mcp_targets: bool = False,\n output_format: str = \"text\",\n manifest_path: str = \"token_refresh_manifest.json\",\n ) -> None:\n self.scanner = scanner\n self.builder = builder\n self.registry = registry_client\n self.dry_run = dry_run\n self.overwrite = overwrite\n self.include_mcp_targets = include_mcp_targets\n self.output_format = output_format\n self.manifest_path = manifest_path\n self.results: list[dict[str, Any]] = []\n self._manifest_entries: list[dict[str, Any]] = []\n\n # ------------------------------------------------------------------\n # Public API\n # ------------------------------------------------------------------\n\n def sync_gateways(self) -> None:\n \"\"\"Scan and register all gateways.\"\"\"\n logger.info(\"Scanning AgentCore Gateways...\")\n gateways = self.scanner.scan_gateways()\n\n for gateway in gateways:\n self._register_gateway(gateway)\n\n if self.include_mcp_targets:\n for target in gateway.get(\"targets\", []):\n self._register_target(gateway, target)\n\n def sync_runtimes(self) -> None:\n \"\"\"Scan and register all runtimes.\"\"\"\n logger.info(\"Scanning AgentCore Runtimes...\")\n runtimes = self.scanner.scan_runtimes()\n\n for runtime in runtimes:\n self._register_runtime(runtime)\n\n def write_manifest(self) -> None:\n \"\"\"Write the token-refresh manifest for CUSTOM_JWT gateways.\n\n The manifest is consumed by downstream tooling (e.g. a token\n refresh cron) to obtain and rotate egress tokens.\n \"\"\"\n if self.dry_run:\n logger.info(\n f\"[DRY-RUN] Would write manifest with {len(self._manifest_entries)} entries\"\n )\n return\n\n if not self._manifest_entries:\n logger.info(\"No CUSTOM_JWT gateways -- skipping manifest\")\n return\n\n with open(self.manifest_path, \"w\") as f:\n json.dump(self._manifest_entries, f, indent=2)\n\n logger.info(f\"Wrote {len(self._manifest_entries)} entries to {self.manifest_path}\")\n\n def print_summary(self) -> None:\n \"\"\"Print sync summary in text or JSON format.\"\"\"\n registered = sum(1 for r in self.results if r[\"status\"] == \"registered\")\n skipped = sum(1 for r in self.results if r[\"status\"] == \"skipped\")\n failed = sum(1 for r in self.results if r[\"status\"] == \"failed\")\n dry_run_count = sum(1 for r in self.results if r[\"status\"] == \"dry_run\")\n\n summary = {\n \"dry_run\": self.dry_run,\n \"registered\": registered,\n \"skipped\": skipped,\n \"failed\": failed,\n \"manifest_entries\": len(self._manifest_entries),\n \"would_register\": dry_run_count if self.dry_run else 0,\n \"total\": len(self.results),\n \"results\": self.results,\n }\n\n if self.output_format == \"json\":\n print(json.dumps(summary, indent=2, default=str))\n return\n\n print(\"\\n\" + \"=\" * 80)\n print(\"AGENTCORE SYNC SUMMARY\")\n print(\"=\" * 80)\n\n if self.dry_run:\n print(\"MODE: DRY-RUN (no changes made)\")\n print(f\"Would register: {dry_run_count}\")\n else:\n print(f\"Registered: {registered}\")\n print(f\"Skipped: {skipped}\")\n print(f\"Failed: {failed}\")\n print(f\"Manifest entries: {len(self._manifest_entries)}\")\n\n print(\"\\nDETAILS:\")\n print(\"-\" * 80)\n print(f\"{'Type':<10} {'Name':<30} {'Path':<25} {'Status':<10}\")\n print(\"-\" * 80)\n\n for r in self.results:\n print(\n f\"{r['resource_type']:<10} \"\n f\"{r['resource_name'][:30]:<30} \"\n f\"{r['path'][:25]:<25} \"\n f\"{r['status']:<10}\"\n )\n\n print(\"=\" * 80)\n\n # ------------------------------------------------------------------\n # Internal -- manifest collection\n # ------------------------------------------------------------------\n\n def _collect_manifest_entry(\n self,\n gateway: dict[str, Any],\n server_path: str,\n ) -> None:\n \"\"\"Collect a manifest entry for a CUSTOM_JWT gateway.\n\n Only gateways with CUSTOM_JWT authorization and a valid\n discovery URL are included in the manifest.\n \"\"\"\n if gateway.get(\"authorizerType\") != \"CUSTOM_JWT\":\n return\n\n jwt_config = gateway.get(\"authorizerConfiguration\", {}).get(\"customJWTAuthorizer\", {})\n discovery_url = jwt_config.get(\"discoveryUrl\", \"\")\n if not discovery_url:\n return\n\n self._manifest_entries.append(\n {\n \"server_path\": server_path,\n \"gateway_arn\": gateway.get(\"gatewayArn\", \"\"),\n \"discovery_url\": discovery_url,\n \"allowed_clients\": jwt_config.get(\"allowedClients\", []),\n \"idp_vendor\": _detect_idp_vendor(discovery_url),\n }\n )\n\n # ------------------------------------------------------------------\n # Internal -- gateway registration\n # ------------------------------------------------------------------\n\n def _register_gateway(self, gateway: dict[str, Any]) -> None:\n \"\"\"Register a single gateway as an MCP Server.\"\"\"\n gateway_name = gateway.get(\"name\", gateway[\"gatewayId\"])\n gateway_url = gateway.get(\"gatewayUrl\", \"\")\n gateway_arn = gateway.get(\"gatewayArn\", \"\")\n\n if not _validate_https_url(gateway_url, gateway_name):\n self.results.append(\n {\n \"resource_type\": \"gateway\",\n \"resource_name\": gateway_name,\n \"resource_arn\": gateway_arn,\n \"registration_type\": \"mcp_server\",\n \"path\": f\"/{_slugify(gateway_name)}\",\n \"status\": \"skipped\",\n \"message\": \"Invalid URL (must be HTTPS)\",\n }\n )\n return\n\n registration = self.builder.build_gateway_registration(gateway)\n registration.overwrite = self.overwrite\n\n result: dict[str, Any] = {\n \"resource_type\": \"gateway\",\n \"resource_name\": gateway_name,\n \"resource_arn\": gateway_arn,\n \"registration_type\": \"mcp_server\",\n \"path\": registration.service_path,\n }\n\n if self.dry_run:\n result[\"status\"] = \"dry_run\"\n result[\"message\"] = \"Would register as MCP Server\"\n logger.info(f\"[DRY-RUN] Would register gateway: {gateway_name}\")\n self.results.append(result)\n self._collect_manifest_entry(gateway, registration.service_path)\n return\n\n try:\n self._register_service_with_retry(registration)\n result[\"status\"] = \"registered\"\n result[\"message\"] = \"Successfully registered\"\n logger.info(f\"Registered gateway: {gateway_name}\")\n except Exception as e:\n if _is_conflict_error(e) and not self.overwrite:\n result[\"status\"] = \"skipped\"\n result[\"message\"] = \"Already registered - skipping (use --overwrite)\"\n logger.warning(f\"Already registered - skipping: {gateway_name} (use --overwrite)\")\n else:\n result[\"status\"] = \"failed\"\n result[\"message\"] = str(e)\n logger.error(f\"Failed to register gateway: {e}\")\n self.results.append(result)\n return\n\n self.results.append(result)\n self._collect_manifest_entry(gateway, registration.service_path)\n\n # ------------------------------------------------------------------\n # Internal -- target registration\n # ------------------------------------------------------------------\n\n def _register_target(self, gateway: dict[str, Any], target: dict[str, Any]) -> None:\n registration = self.builder.build_target_registration(gateway, target)\n if not registration:\n return\n\n registration.overwrite = self.overwrite\n target_name = target.get(\"name\", target[\"targetId\"])\n\n result: dict[str, Any] = {\n \"resource_type\": \"target\",\n \"resource_name\": target_name,\n \"resource_arn\": (f\"{gateway.get('gatewayArn', '')}:target:{target['targetId']}\"),\n \"registration_type\": \"mcp_server\",\n \"path\": registration.service_path,\n }\n\n if self.dry_run:\n result[\"status\"] = \"dry_run\"\n result[\"message\"] = \"Would register as MCP Server\"\n logger.info(f\"[DRY-RUN] Would register target: {target_name}\")\n else:\n try:\n self._register_service_with_retry(registration)\n result[\"status\"] = \"registered\"\n result[\"message\"] = \"Successfully registered\"\n logger.info(f\"Registered target: {target_name}\")\n except Exception as e:\n if \"already exists\" in str(e).lower() and not self.overwrite:\n result[\"status\"] = \"skipped\"\n result[\"message\"] = \"Already exists\"\n else:\n result[\"status\"] = \"failed\"\n result[\"message\"] = str(e)\n logger.error(f\"Failed to register target: {e}\")\n\n self.results.append(result)\n\n # ------------------------------------------------------------------\n # Internal -- runtime registration\n # ------------------------------------------------------------------\n\n def _register_runtime(self, runtime: dict[str, Any]) -> None:\n protocol_config = runtime.get(\"protocolConfiguration\", {})\n server_protocol = protocol_config.get(\"serverProtocol\", \"HTTP\")\n\n if server_protocol == \"MCP\":\n self._register_runtime_as_server(runtime)\n else:\n self._register_runtime_as_agent(runtime)\n\n def _register_runtime_as_server(self, runtime: dict[str, Any]) -> None:\n registration = self.builder.build_runtime_mcp_registration(runtime)\n registration.overwrite = self.overwrite\n runtime_name = runtime.get(\"agentRuntimeName\", runtime[\"agentRuntimeId\"])\n\n result: dict[str, Any] = {\n \"resource_type\": \"runtime\",\n \"resource_name\": runtime_name,\n \"resource_arn\": runtime.get(\"agentRuntimeArn\", \"\"),\n \"registration_type\": \"mcp_server\",\n \"path\": registration.service_path,\n }\n\n if self.dry_run:\n result[\"status\"] = \"dry_run\"\n result[\"message\"] = \"Would register as MCP Server\"\n logger.info(f\"[DRY-RUN] Would register runtime as MCP Server: {runtime_name}\")\n else:\n try:\n self._register_service_with_retry(registration)\n result[\"status\"] = \"registered\"\n logger.info(f\"Registered runtime as MCP Server: {runtime_name}\")\n except Exception as e:\n if \"already exists\" in str(e).lower() and not self.overwrite:\n result[\"status\"] = \"skipped\"\n result[\"message\"] = \"Already exists\"\n else:\n result[\"status\"] = \"failed\"\n result[\"message\"] = str(e)\n logger.error(f\"Failed to register runtime: {e}\")\n\n self.results.append(result)\n\n def _register_runtime_as_agent(self, runtime: dict[str, Any]) -> None:\n registration = self.builder.build_runtime_agent_registration(runtime)\n runtime_name = runtime.get(\"agentRuntimeName\", runtime[\"agentRuntimeId\"])\n\n result: dict[str, Any] = {\n \"resource_type\": \"runtime\",\n \"resource_name\": runtime_name,\n \"resource_arn\": runtime.get(\"agentRuntimeArn\", \"\"),\n \"registration_type\": \"agent\",\n \"path\": registration.path,\n }\n\n if self.dry_run:\n result[\"status\"] = \"dry_run\"\n result[\"message\"] = \"Would register as A2A Agent\"\n logger.info(f\"[DRY-RUN] Would register runtime as Agent: {runtime_name}\")\n else:\n try:\n self._register_agent_with_retry(registration)\n result[\"status\"] = \"registered\"\n logger.info(f\"Registered runtime as Agent: {runtime_name}\")\n except Exception as e:\n if _is_conflict_error(e) and self.overwrite:\n # AgentRegistration has no overwrite field,\n # so update via PUT when conflict + overwrite\n try:\n self._update_agent_with_retry(registration.path, registration)\n result[\"status\"] = \"registered\"\n result[\"message\"] = \"Updated (overwrite)\"\n logger.info(f\"Updated existing agent: {runtime_name}\")\n except Exception as update_err:\n result[\"status\"] = \"failed\"\n result[\"message\"] = str(update_err)\n logger.error(f\"Failed to update agent {runtime_name}: {update_err}\")\n elif _is_conflict_error(e):\n result[\"status\"] = \"skipped\"\n result[\"message\"] = \"Already registered - use --overwrite to update\"\n else:\n result[\"status\"] = \"failed\"\n result[\"message\"] = str(e)\n logger.error(f\"Failed to register runtime as agent: {e}\")\n\n self.results.append(result)\n\n # ------------------------------------------------------------------\n # Retry-wrapped registry calls\n # ------------------------------------------------------------------\n\n @_retry_registry_call\n def _register_service_with_retry(self, registration: InternalServiceRegistration) -> None:\n self.registry.register_service(registration)\n\n @_retry_registry_call\n def _register_agent_with_retry(self, registration: AgentRegistration) -> None:\n self.registry.register_agent(registration)\n\n @_retry_registry_call\n def _update_agent_with_retry(\n self,\n path: str,\n registration: AgentRegistration,\n ) -> None:\n self.registry.update_agent(path, registration)\n" }, { "path": "cli/agentcore/sync.py", "content": "\"\"\"CLI entry point for AgentCore auto-registration.\n\nProvides ``sync`` and ``list`` subcommands via argparse.\n\nUsage::\n\n python -m cli.agentcore.sync sync [options]\n python -m cli.agentcore.sync list [options]\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\n\nfrom .models import (\n DEFAULT_MANIFEST_PATH,\n DEFAULT_REGION,\n DEFAULT_REGISTRY_URL,\n DEFAULT_TIMEOUT,\n DEFAULT_TOKEN_FILE,\n _load_token,\n)\n\nlogger = logging.getLogger(__name__)\n\n\n# ---------------------------------------------------------------------------\n# Argparse setup\n# ---------------------------------------------------------------------------\n\n\ndef build_parser() -> argparse.ArgumentParser:\n \"\"\"Build the CLI argument parser with sync and list subcommands.\"\"\"\n parser = argparse.ArgumentParser(\n prog=\"agentcore-sync\",\n description=(\n \"Discover and register AWS Bedrock AgentCore Gateways and \"\n \"Agent Runtimes with the MCP Gateway Registry.\"\n ),\n epilog=(\n \"Environment variables:\\n\"\n \" AWS_REGION AWS region (default: us-east-1)\\n\"\n \" REGISTRY_URL Registry base URL\\n\"\n \" REGISTRY_TOKEN_FILE Path to registry auth token file\\n\"\n \" AGENTCORE_ACCOUNTS Comma-separated account IDs (cross-account)\\n\"\n \" AGENTCORE_ASSUME_ROLE_NAME Role name to assume (default: AgentCoreSyncRole)\\n\"\n ),\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n\n subparsers = parser.add_subparsers(dest=\"command\")\n\n # -- shared arguments --------------------------------------------------\n def add_common_args(sub: argparse.ArgumentParser) -> None:\n sub.add_argument(\n \"--region\",\n default=os.environ.get(\"AWS_REGION\", DEFAULT_REGION),\n help=\"AWS region (default: AWS_REGION env or us-east-1)\",\n )\n sub.add_argument(\n \"--registry-url\",\n default=os.environ.get(\"REGISTRY_URL\", DEFAULT_REGISTRY_URL),\n help=\"Registry base URL (default: REGISTRY_URL env or http://localhost)\",\n )\n sub.add_argument(\n \"--token-file\",\n default=os.environ.get(\"REGISTRY_TOKEN_FILE\", DEFAULT_TOKEN_FILE),\n help=\"Path to registry auth token file\",\n )\n sub.add_argument(\n \"--timeout\",\n type=int,\n default=DEFAULT_TIMEOUT,\n help=\"AWS API call timeout in seconds (default: 30)\",\n )\n sub.add_argument(\n \"--gateways-only\",\n action=\"store_true\",\n help=\"Only process gateways\",\n )\n sub.add_argument(\n \"--runtimes-only\",\n action=\"store_true\",\n help=\"Only process runtimes\",\n )\n sub.add_argument(\n \"--output\",\n choices=[\"text\", \"json\"],\n default=\"text\",\n help=\"Output format (default: text)\",\n )\n sub.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable DEBUG logging\",\n )\n\n # -- cross-account arguments (shared by sync and list) ----------------\n def add_cross_account_args(sub: argparse.ArgumentParser) -> None:\n sub.add_argument(\n \"--accounts\",\n default=os.environ.get(\"AGENTCORE_ACCOUNTS\", \"\"),\n help=(\n \"Comma-separated AWS account IDs to scan (cross-account). \"\n \"Requires a role in each account that the caller can assume. \"\n \"(default: current account only)\"\n ),\n )\n sub.add_argument(\n \"--assume-role-name\",\n default=os.environ.get(\"AGENTCORE_ASSUME_ROLE_NAME\", \"AgentCoreSyncRole\"),\n help=(\n \"IAM role name to assume in each target account \"\n \"(default: AGENTCORE_ASSUME_ROLE_NAME env or AgentCoreSyncRole)\"\n ),\n )\n\n # -- sync subcommand ---------------------------------------------------\n sync_parser = subparsers.add_parser(\n \"sync\",\n help=\"Discover and register AgentCore resources\",\n )\n add_common_args(sync_parser)\n add_cross_account_args(sync_parser)\n sync_parser.add_argument(\n \"--dry-run\",\n action=\"store_true\",\n help=\"Preview without registering or persisting credentials\",\n )\n sync_parser.add_argument(\n \"--overwrite\",\n action=\"store_true\",\n help=\"Overwrite existing registrations\",\n )\n sync_parser.add_argument(\n \"--visibility\",\n choices=[\"public\", \"internal\", \"group-restricted\"],\n default=\"internal\",\n help=\"Registration visibility (default: internal)\",\n )\n sync_parser.add_argument(\n \"--include-mcp-targets\",\n action=\"store_true\",\n help=\"Register mcpServer gateway targets as separate MCP Servers\",\n )\n sync_parser.add_argument(\n \"--manifest\",\n default=DEFAULT_MANIFEST_PATH,\n help=\"Output path for token refresh manifest (default: token_refresh_manifest.json)\",\n )\n\n # -- list subcommand ---------------------------------------------------\n list_parser = subparsers.add_parser(\n \"list\",\n help=\"Discover and display AgentCore resources without registering\",\n )\n add_common_args(list_parser)\n add_cross_account_args(list_parser)\n\n return parser\n\n\n# ---------------------------------------------------------------------------\n# Cross-account helpers\n# ---------------------------------------------------------------------------\n\n\ndef _parse_account_ids(accounts_str: str) -> list[str]:\n \"\"\"Parse comma-separated account IDs, stripping whitespace.\"\"\"\n if not accounts_str or not accounts_str.strip():\n return []\n return [a.strip() for a in accounts_str.split(\",\") if a.strip()]\n\n\ndef _assume_role_session(\n account_id: str,\n role_name: str,\n region: str,\n) -> boto3.Session:\n \"\"\"Assume an IAM role in a target account and return a boto3 Session.\n\n Args:\n account_id: Target AWS account ID.\n role_name: IAM role name to assume in the target account.\n region: AWS region for the STS call.\n\n Returns:\n boto3.Session with temporary credentials from the assumed role.\n\n Raises:\n botocore.exceptions.ClientError: If AssumeRole fails.\n \"\"\"\n import boto3\n\n role_arn = f\"arn:aws:iam::{account_id}:role/{role_name}\"\n logger.info(f\"Assuming role {role_arn} for cross-account access...\")\n\n sts = boto3.client(\"sts\", region_name=region)\n response = sts.assume_role(\n RoleArn=role_arn,\n RoleSessionName=f\"agentcore-sync-{account_id}\",\n DurationSeconds=3600,\n )\n creds = response[\"Credentials\"]\n\n session = boto3.Session(\n aws_access_key_id=creds[\"AccessKeyId\"],\n aws_secret_access_key=creds[\"SecretAccessKey\"],\n aws_session_token=creds[\"SessionToken\"],\n region_name=region,\n )\n logger.info(f\"Assumed role in account {account_id} successfully\")\n return session\n\n\n# ---------------------------------------------------------------------------\n# cmd_sync\n# ---------------------------------------------------------------------------\n\n\ndef cmd_sync(args: argparse.Namespace) -> int:\n \"\"\"Execute the sync subcommand: discover, register, write manifest.\"\"\"\n # Load registry token\n try:\n token = _load_token(args.token_file)\n except (FileNotFoundError, ValueError) as e:\n logger.error(str(e))\n return 1\n\n # Late imports to keep argparse fast\n from .discovery import AgentCoreScanner\n from .registration import RegistrationBuilder, SyncOrchestrator\n\n # Add project root so api.registry_client is importable\n sys.path.insert(\n 0,\n os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))),\n )\n from api.registry_client import RegistryClient\n\n registry = RegistryClient(registry_url=args.registry_url, token=token)\n\n # Determine accounts to scan\n account_ids = _parse_account_ids(getattr(args, \"accounts\", \"\"))\n role_name = getattr(args, \"assume_role_name\", \"AgentCoreSyncRole\")\n\n # Build list of (label, session_or_none) pairs\n # Empty list = current account only (session=None)\n account_sessions: list[tuple[str, object]] = []\n if account_ids:\n for acct in account_ids:\n try:\n session = _assume_role_session(acct, role_name, args.region)\n account_sessions.append((acct, session))\n except Exception as e:\n logger.error(f\"Failed to assume role in account {acct}: {e}\")\n if args.output == \"json\":\n print(json.dumps({\"error\": f\"AssumeRole failed for {acct}: {e}\"}))\n return 1\n else:\n account_sessions.append((\"current\", None))\n\n # Run sync for each account\n for label, session in account_sessions:\n if len(account_sessions) > 1:\n logger.info(f\"\\n{'=' * 60}\")\n logger.info(f\"Syncing account: {label}\")\n logger.info(f\"{'=' * 60}\")\n\n scanner = AgentCoreScanner(region=args.region, timeout=args.timeout, session=session)\n builder = RegistrationBuilder(\n region=args.region, visibility=args.visibility, session=session\n )\n\n orchestrator = SyncOrchestrator(\n scanner=scanner,\n builder=builder,\n registry_client=registry,\n dry_run=args.dry_run,\n overwrite=args.overwrite,\n include_mcp_targets=args.include_mcp_targets,\n output_format=args.output,\n manifest_path=args.manifest,\n )\n\n # Scope filtering\n if not args.runtimes_only:\n orchestrator.sync_gateways()\n if not args.gateways_only:\n orchestrator.sync_runtimes()\n\n # Write token refresh manifest\n orchestrator.write_manifest()\n\n # Summary\n orchestrator.print_summary()\n\n return 0\n\n\n# ---------------------------------------------------------------------------\n# cmd_list\n# ---------------------------------------------------------------------------\n\n\ndef cmd_list(args: argparse.Namespace) -> int:\n \"\"\"Execute the list subcommand: discover and display resources.\"\"\"\n from .discovery import AgentCoreScanner\n\n # Determine accounts to scan\n account_ids = _parse_account_ids(getattr(args, \"accounts\", \"\"))\n role_name = getattr(args, \"assume_role_name\", \"AgentCoreSyncRole\")\n\n account_sessions: list[tuple[str, object]] = []\n if account_ids:\n for acct in account_ids:\n try:\n session = _assume_role_session(acct, role_name, args.region)\n account_sessions.append((acct, session))\n except Exception as e:\n logger.error(f\"Failed to assume role in account {acct}: {e}\")\n return 1\n else:\n account_sessions.append((\"current\", None))\n\n all_gateways: list = []\n all_runtimes: list = []\n all_errors: list[str] = []\n\n for label, session in account_sessions:\n scanner = AgentCoreScanner(region=args.region, timeout=args.timeout, session=session)\n\n if not args.runtimes_only:\n try:\n gateways = scanner.scan_gateways()\n # Tag with account for multi-account output\n if len(account_sessions) > 1:\n for gw in gateways:\n gw[\"_account\"] = label\n all_gateways.extend(gateways)\n except Exception as e:\n all_errors.append(f\"[{label}] Gateway scan error: {e}\")\n logger.error(f\"Failed to scan gateways in {label}: {e}\")\n\n if not args.gateways_only:\n try:\n runtimes = scanner.scan_runtimes()\n if len(account_sessions) > 1:\n for rt in runtimes:\n rt[\"_account\"] = label\n all_runtimes.extend(runtimes)\n except Exception as e:\n all_errors.append(f\"[{label}] Runtime scan error: {e}\")\n logger.error(f\"Failed to scan runtimes in {label}: {e}\")\n\n if args.output == \"json\":\n print(\n json.dumps(\n {\n \"region\": args.region,\n \"accounts\": account_ids or [\"current\"],\n \"gateways\": all_gateways,\n \"runtimes\": all_runtimes,\n \"errors\": all_errors,\n },\n indent=2,\n default=str,\n )\n )\n else:\n _print_list_text(all_gateways, all_runtimes, args.region, all_errors)\n\n return 0\n\n\ndef _print_list_text(\n gateways: list,\n runtimes: list,\n region: str,\n errors: list[str],\n) -> None:\n \"\"\"Print discovered resources in text format.\"\"\"\n print(f\"\\nAgentCore Resources in {region}\")\n print(\"=\" * 70)\n\n if gateways:\n print(f\"\\nGateways ({len(gateways)}):\")\n print(\"-\" * 70)\n for gw in gateways:\n name = gw.get(\"name\", gw.get(\"gatewayId\", \"unknown\"))\n auth = gw.get(\"authorizerType\", \"unknown\")\n status = gw.get(\"status\", \"unknown\")\n targets = len(gw.get(\"targets\", []))\n print(f\" {name:<30} auth={auth:<12} targets={targets} [{status}]\")\n else:\n print(\"\\nNo gateways found.\")\n\n if runtimes:\n print(f\"\\nRuntimes ({len(runtimes)}):\")\n print(\"-\" * 70)\n for rt in runtimes:\n name = rt.get(\"agentRuntimeName\", rt.get(\"agentRuntimeId\", \"unknown\"))\n protocol = rt.get(\"protocolConfiguration\", {}).get(\"serverProtocol\", \"unknown\")\n status = rt.get(\"status\", \"unknown\")\n print(f\" {name:<30} protocol={protocol:<8} [{status}]\")\n else:\n print(\"\\nNo runtimes found.\")\n\n if errors:\n print(f\"\\nErrors ({len(errors)}):\")\n for err in errors:\n print(f\" - {err}\")\n\n print(\"=\" * 70)\n\n\n# ---------------------------------------------------------------------------\n# main\n# ---------------------------------------------------------------------------\n\n\ndef main(argv: list[str] | None = None) -> int:\n \"\"\"Entry point: parse args, configure logging, dispatch subcommand.\"\"\"\n # Load .env before anything reads os.environ\n try:\n from dotenv import load_dotenv\n\n load_dotenv()\n except ImportError:\n pass\n\n parser = build_parser()\n args = parser.parse_args(argv)\n\n if not args.command:\n parser.print_help()\n return 1\n\n # Logging\n level = logging.DEBUG if args.debug else logging.INFO\n logging.basicConfig(\n level=level,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n )\n\n logger.debug(f\"CLI args: {args}\")\n\n if args.command == \"sync\":\n return cmd_sync(args)\n elif args.command == \"list\":\n return cmd_list(args)\n\n parser.print_help()\n return 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "cli/agentcore/token_refresher.py", "content": "\"\"\"Token refresher for AgentCore CUSTOM_JWT gateways.\n\nReads token_refresh_manifest.json (produced by ``cli.agentcore sync``),\nresolves client secrets per IdP vendor, fetches OAuth2 access tokens\nvia standard OIDC client_credentials grant, and PATCHes them into the\nMCP Gateway Registry.\n\nUsage::\n\n # One-time refresh\n uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n # Continuous mode (sidecar)\n uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n --loop --interval 2700\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport logging\nimport os\nimport time\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nimport boto3\nimport requests\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n# Constants\nOIDC_DISCOVERY_TIMEOUT: int = 10\nTOKEN_REQUEST_TIMEOUT: int = 15\nREGISTRY_REQUEST_TIMEOUT: int = 15\nSECURITY_SCAN_TIMEOUT: int = 120\n\nIDP_PATTERNS: dict[str, str] = {\n \"cognito-idp\": \"cognito\",\n \"auth0.com\": \"auth0\",\n \"okta.com\": \"okta\",\n \"microsoftonline.com\": \"entra\",\n \"/realms/\": \"keycloak\",\n}\n\nIDP_SECRET_ENV_VARS: dict[str, str] = {\n \"auth0\": \"AUTH0_CLIENT_SECRET\",\n \"okta\": \"OKTA_CLIENT_SECRET\",\n \"entra\": \"ENTRA_CLIENT_SECRET\",\n \"keycloak\": \"KEYCLOAK_CLIENT_SECRET\",\n}\n\nENV_VAR_PREFIX: str = \"OAUTH_CLIENT_SECRET_\"\n\n\n# ---------------------------------------------------------------------------\n# Private functions\n# ---------------------------------------------------------------------------\n\n\ndef _read_manifest(\n manifest_path: str,\n) -> list[dict[str, Any]]:\n \"\"\"Read token refresh manifest from JSON file.\n\n Args:\n manifest_path: Path to the manifest JSON file.\n\n Returns:\n List of manifest entries.\n\n Raises:\n FileNotFoundError: If manifest file does not exist.\n ValueError: If manifest file contains invalid JSON.\n \"\"\"\n abs_path = os.path.abspath(manifest_path)\n try:\n with open(abs_path) as f:\n entries = json.load(f)\n except FileNotFoundError:\n raise FileNotFoundError(f\"Manifest file not found: {abs_path}\")\n except json.JSONDecodeError as e:\n raise ValueError(f\"Invalid JSON in manifest file {abs_path}: {e}\")\n\n if not isinstance(entries, list):\n raise ValueError(f\"Manifest must be a JSON array, got {type(entries).__name__}\")\n\n logger.info(f\"Read {len(entries)} entries from {manifest_path}\")\n return entries\n\n\ndef _detect_idp_vendor(\n discovery_url: str,\n) -> str:\n \"\"\"Detect IdP vendor from OIDC discovery URL.\n\n Matches known patterns in the URL string.\n\n Args:\n discovery_url: OIDC discovery URL.\n\n Returns:\n Vendor name (cognito, auth0, okta, entra, keycloak, or unknown).\n \"\"\"\n for pattern, vendor in IDP_PATTERNS.items():\n if pattern in discovery_url:\n return vendor\n return \"unknown\"\n\n\ndef _get_cognito_client_secret(\n discovery_url: str,\n client_id: str,\n) -> str | None:\n \"\"\"Auto-retrieve client secret from Cognito.\n\n Parses user_pool_id and region from the discoveryUrl,\n calls describe_user_pool_client() via boto3.\n\n Args:\n discovery_url: Cognito OIDC discovery URL containing pool_id and region.\n client_id: Cognito app client ID.\n\n Returns:\n Client secret string, or None if not available.\n \"\"\"\n try:\n # Parse: https://cognito-idp.{region}.amazonaws.com/{pool_id}/...\n region = discovery_url.split(\"cognito-idp.\")[1].split(\".amazonaws\")[0]\n pool_id = discovery_url.split(\"amazonaws.com/\")[1].split(\"/\")[0]\n\n client = boto3.client(\"cognito-idp\", region_name=region)\n response = client.describe_user_pool_client(\n UserPoolId=pool_id,\n ClientId=client_id,\n )\n secret = response[\"UserPoolClient\"].get(\"ClientSecret\")\n if secret:\n logger.info(f\"Auto-retrieved client secret from Cognito (pool: {pool_id})\")\n else:\n logger.warning(f\"Cognito app client {client_id} has no client secret\")\n return secret\n except Exception as e:\n logger.error(f\"Failed to retrieve Cognito client secret: {e}\")\n return None\n\n\ndef _get_client_secret(\n idp_vendor: str,\n discovery_url: str,\n client_id: str,\n) -> str | None:\n \"\"\"Resolve client secret using this priority order:\n\n 1. Per-client env var: OAUTH_CLIENT_SECRET_\n 2. Cognito auto-retrieval via AWS API (cognito only)\n 3. Vendor env var: AUTH0_CLIENT_SECRET, OKTA_CLIENT_SECRET, etc.\n\n Args:\n idp_vendor: Detected IdP vendor name.\n discovery_url: OIDC discovery URL (used for Cognito parsing).\n client_id: OAuth2 client ID.\n\n Returns:\n Client secret string, or None if not available.\n \"\"\"\n # Priority 1: per-client env var (OAUTH_CLIENT_SECRET_)\n env_var_name = f\"{ENV_VAR_PREFIX}{client_id}\"\n secret = os.environ.get(env_var_name)\n if secret:\n logger.info(f\"Using client secret from env var {env_var_name}\")\n return secret\n\n # Priority 2: Cognito auto-retrieval via AWS API\n if idp_vendor == \"cognito\":\n return _get_cognito_client_secret(discovery_url, client_id)\n\n # Priority 3: vendor-specific env var\n vendor_env_var = IDP_SECRET_ENV_VARS.get(idp_vendor)\n if not vendor_env_var:\n logger.warning(f\"No env var mapping for IdP vendor: {idp_vendor}\")\n return None\n\n secret = os.environ.get(vendor_env_var)\n if not secret:\n logger.warning(f\"Env var {vendor_env_var} not set for {idp_vendor}\")\n else:\n logger.debug(f\"Using client secret from vendor env var {vendor_env_var}\")\n return secret\n\n\ndef _get_token_endpoint(\n discovery_url: str,\n) -> str | None:\n \"\"\"Fetch token_endpoint from OIDC discovery document.\n\n GETs the discoveryUrl and extracts the token_endpoint field.\n Standard OIDC -- works for all providers.\n\n Args:\n discovery_url: OIDC discovery URL.\n\n Returns:\n Token endpoint URL, or None on failure.\n \"\"\"\n try:\n response = requests.get(\n discovery_url,\n timeout=OIDC_DISCOVERY_TIMEOUT,\n )\n response.raise_for_status()\n token_endpoint = response.json().get(\"token_endpoint\")\n if not token_endpoint:\n logger.error(f\"No token_endpoint in OIDC discovery: {discovery_url}\")\n return token_endpoint\n except Exception as e:\n logger.error(f\"OIDC discovery failed for {discovery_url}: {e}\")\n return None\n\n\ndef _request_token(\n token_endpoint: str,\n client_id: str,\n client_secret: str,\n) -> str | None:\n \"\"\"Request access token via OAuth2 client_credentials grant.\n\n Args:\n token_endpoint: OAuth2 token endpoint URL.\n client_id: OAuth2 client ID.\n client_secret: OAuth2 client secret.\n\n Returns:\n Access token string, or None on failure.\n \"\"\"\n try:\n response = requests.post(\n token_endpoint,\n headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n data={\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n },\n timeout=TOKEN_REQUEST_TIMEOUT,\n )\n response.raise_for_status()\n token = response.json().get(\"access_token\")\n if not token:\n logger.error(\"Token response missing access_token field\")\n return token\n except Exception as e:\n logger.error(f\"Token request failed: {e}\")\n return None\n\n\ndef _update_registry_credential(\n registry_url: str,\n registry_token: str,\n server_path: str,\n auth_credential: str,\n) -> bool:\n \"\"\"PATCH auth_credential for a server in the registry.\n\n Uses the /api/servers{path}/auth-credential endpoint.\n\n Args:\n registry_url: Registry base URL.\n registry_token: Registry auth token (Bearer).\n server_path: Server path in the registry (e.g., /my-server).\n auth_credential: New auth credential (access token).\n\n Returns:\n True if update succeeded, False otherwise.\n \"\"\"\n url = f\"{registry_url.rstrip('/')}/api/servers{server_path}/auth-credential\"\n try:\n response = requests.patch(\n url,\n headers={\n \"Authorization\": f\"Bearer {registry_token}\",\n \"Content-Type\": \"application/json\",\n },\n json={\n \"auth_scheme\": \"bearer\",\n \"auth_credential\": auth_credential,\n },\n timeout=REGISTRY_REQUEST_TIMEOUT,\n )\n response.raise_for_status()\n logger.info(f\"Updated auth_credential for {server_path}\")\n return True\n except requests.HTTPError as e:\n status = e.response.status_code if e.response is not None else \"?\"\n if status == 500 and \"text/html\" in (\n e.response.headers.get(\"content-type\", \"\") if e.response is not None else \"\"\n ):\n logger.error(\n f\"Failed to update credential for {server_path}: \"\n f\"HTTP {status} from nginx -- registry token may be expired, \"\n f\"regenerate and retry\"\n )\n else:\n logger.error(f\"Failed to update credential for {server_path}: {e}\")\n return False\n except Exception as e:\n logger.error(f\"Failed to update credential for {server_path}: {e}\")\n return False\n\n\ndef _trigger_security_scan(\n registry_url: str,\n registry_token: str,\n server_path: str,\n) -> bool:\n \"\"\"Trigger a security rescan for a server after credential update.\n\n POSTs to /api/servers/{path}/rescan. Requires admin privileges\n on the registry token.\n\n Args:\n registry_url: Registry base URL.\n registry_token: Registry auth token (Bearer).\n server_path: Server path in the registry (e.g., /my-server).\n\n Returns:\n True if scan was triggered successfully, False otherwise.\n \"\"\"\n url = f\"{registry_url.rstrip('/')}/api/servers{server_path}/rescan\"\n try:\n response = requests.post(\n url,\n headers={\n \"Authorization\": f\"Bearer {registry_token}\",\n \"Content-Type\": \"application/json\",\n },\n timeout=SECURITY_SCAN_TIMEOUT,\n )\n response.raise_for_status()\n scan_data = response.json()\n is_safe = scan_data.get(\"is_safe\", False)\n critical = scan_data.get(\"critical_issues\", 0)\n high = scan_data.get(\"high_severity\", 0)\n\n if is_safe:\n logger.info(f\"Security scan passed for {server_path}\")\n else:\n logger.warning(\n f\"Security scan for {server_path}: \"\n f\"critical={critical}, high={high}, is_safe={is_safe}\"\n )\n return True\n except requests.HTTPError as e:\n status_code = e.response.status_code if e.response is not None else \"?\"\n if status_code == 403:\n logger.warning(\n f\"Security scan skipped for {server_path}: registry token lacks admin privileges\"\n )\n else:\n logger.error(f\"Security scan failed for {server_path}: HTTP {status_code}\")\n return False\n except Exception as e:\n logger.error(f\"Security scan failed for {server_path}: {e}\")\n return False\n\n\ndef _load_registry_token(\n token_file: str,\n) -> str:\n \"\"\"Load registry auth token from JSON file.\n\n Supports two formats:\n - Flat: ``{\"access_token\": \"...\"}`` or ``{\"token\": \"...\"}``\n - Nested: ``{\"tokens\": {\"access_token\": \"...\"}}``\n\n Args:\n token_file: Path to the token JSON file.\n\n Returns:\n Token string.\n\n Raises:\n FileNotFoundError: If token file does not exist.\n ValueError: If token file is invalid or missing token field.\n \"\"\"\n abs_path = os.path.abspath(token_file)\n try:\n with open(abs_path) as f:\n data = json.load(f)\n # Try top-level first, then nested under \"tokens\"\n token = data.get(\"access_token\") or data.get(\"token\")\n if not token:\n tokens_obj = data.get(\"tokens\", {})\n if isinstance(tokens_obj, dict):\n token = tokens_obj.get(\"access_token\") or tokens_obj.get(\"token\")\n if not token:\n raise ValueError(f\"No access_token or token field in token file: {abs_path}\")\n return token\n except FileNotFoundError:\n raise FileNotFoundError(f\"Token file not found: {abs_path}\")\n except json.JSONDecodeError as e:\n raise ValueError(f\"Invalid JSON in token file {abs_path}: {e}\")\n\n\n# ---------------------------------------------------------------------------\n# Public function\n# ---------------------------------------------------------------------------\n\n\ndef refresh_all(\n manifest_path: str,\n registry_url: str,\n registry_token: str,\n run_scan: bool = True,\n) -> dict[str, Any]:\n \"\"\"Refresh tokens for all entries in the manifest.\n\n For each CUSTOM_JWT gateway:\n 1. Resolve client_secret (per-client env -> Cognito auto -> vendor env)\n 2. GET discoveryUrl -> extract token_endpoint\n 3. POST client_credentials grant -> get access_token\n 4. PATCH auth_credential in the registry\n 5. Trigger security rescan (if run_scan is True)\n\n Args:\n manifest_path: Path to token_refresh_manifest.json.\n registry_url: Registry base URL.\n registry_token: Registry auth token (Bearer).\n run_scan: If True, trigger security rescan after each credential update.\n\n Returns:\n Summary dict with success/failure/skipped counts and scan results.\n \"\"\"\n entries = _read_manifest(manifest_path)\n start_time = time.time()\n\n success_count = 0\n failure_count = 0\n skipped_count = 0\n scan_success_count = 0\n scan_failure_count = 0\n\n for entry in entries:\n server_path = entry[\"server_path\"]\n discovery_url = entry[\"discovery_url\"]\n allowed_clients = entry.get(\"allowed_clients\", [])\n idp_vendor = entry.get(\"idp_vendor\") or _detect_idp_vendor(discovery_url)\n\n if not allowed_clients:\n logger.warning(f\"No allowed_clients for {server_path} -- skipping\")\n skipped_count += 1\n continue\n\n client_id = allowed_clients[0]\n\n # Step 1: Resolve client_secret (per-client env -> auto -> vendor env)\n client_secret = _get_client_secret(idp_vendor, discovery_url, client_id)\n if not client_secret:\n skipped_count += 1\n continue\n\n # Step 2: Get token_endpoint via OIDC discovery\n token_endpoint = _get_token_endpoint(discovery_url)\n if not token_endpoint:\n failure_count += 1\n continue\n\n # Step 3: Request token\n token = _request_token(token_endpoint, client_id, client_secret)\n if not token:\n failure_count += 1\n continue\n\n # Step 4: Update registry\n updated = _update_registry_credential(registry_url, registry_token, server_path, token)\n if updated:\n success_count += 1\n entry[\"last_refreshed\"] = datetime.now(UTC).isoformat()\n\n # Step 5: Trigger security rescan\n if run_scan:\n scanned = _trigger_security_scan(registry_url, registry_token, server_path)\n if scanned:\n scan_success_count += 1\n else:\n scan_failure_count += 1\n else:\n failure_count += 1\n\n # Update manifest with timestamps\n with open(manifest_path, \"w\") as f:\n json.dump(entries, f, indent=2)\n\n elapsed = time.time() - start_time\n summary: dict[str, Any] = {\n \"total\": len(entries),\n \"success\": success_count,\n \"failed\": failure_count,\n \"skipped\": skipped_count,\n \"elapsed_seconds\": round(elapsed, 1),\n }\n\n if run_scan:\n summary[\"scans_triggered\"] = scan_success_count\n summary[\"scans_failed\"] = scan_failure_count\n\n logger.info(f\"Token refresh complete: {json.dumps(summary)}\")\n return summary\n\n\n# ---------------------------------------------------------------------------\n# Main\n# ---------------------------------------------------------------------------\n\n\ndef main() -> None:\n \"\"\"Parse arguments and run token refresh.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Refresh auth tokens for AgentCore CUSTOM_JWT gateways\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExample usage:\n # One-time refresh\n uv run python -m cli.agentcore.token_refresher \\\\\n --manifest token_refresh_manifest.json \\\\\n --registry-url https://registry.example.com \\\\\n --token-file .token\n\n # With per-client env vars (from .env)\n OAUTH_CLIENT_SECRET_49ujl0b9ser72gnp6q1ph9v6vs=mysecret \\\\\n uv run python -m cli.agentcore.token_refresher \\\\\n --manifest token_refresh_manifest.json \\\\\n --registry-url https://registry.example.com \\\\\n --token-file .token\n\n # Continuous mode (run as sidecar)\n uv run python -m cli.agentcore.token_refresher \\\\\n --manifest token_refresh_manifest.json \\\\\n --registry-url https://registry.example.com \\\\\n --token-file .token \\\\\n --loop --interval 2700\n\nSecret resolution priority (per client_id):\n 1. Per-client env var: OAUTH_CLIENT_SECRET_=\n 2. Cognito auto-retrieval via AWS API (cognito only)\n 3. Vendor env var:\n AUTH0_CLIENT_SECRET Client secret for Auth0 gateways\n OKTA_CLIENT_SECRET Client secret for Okta gateways\n ENTRA_CLIENT_SECRET Client secret for Entra gateways\n KEYCLOAK_CLIENT_SECRET Client secret for Keycloak gateways\n\"\"\",\n )\n parser.add_argument(\n \"--manifest\",\n default=\"token_refresh_manifest.json\",\n help=\"Path to token refresh manifest (default: token_refresh_manifest.json)\",\n )\n parser.add_argument(\n \"--registry-url\",\n default=os.environ.get(\"REGISTRY_URL\", \"http://localhost\"),\n help=\"Registry base URL (default: REGISTRY_URL env or http://localhost)\",\n )\n parser.add_argument(\n \"--token-file\",\n default=os.environ.get(\"REGISTRY_TOKEN_FILE\", \".token\"),\n help=\"Path to registry auth token file (default: REGISTRY_TOKEN_FILE env or .token)\",\n )\n parser.add_argument(\n \"--loop\",\n action=\"store_true\",\n help=\"Run continuously (for sidecar deployment)\",\n )\n parser.add_argument(\n \"--interval\",\n type=int,\n default=2700,\n help=\"Refresh interval in seconds (default: 2700 = 45 min)\",\n )\n parser.add_argument(\n \"--scan\",\n action=argparse.BooleanOptionalAction,\n default=True,\n help=\"Trigger security rescan after each credential update (default: enabled, use --no-scan to disable)\",\n )\n parser.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable DEBUG logging\",\n )\n args = parser.parse_args()\n\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n registry_token = _load_registry_token(args.token_file)\n\n if args.loop:\n logger.info(f\"Running in continuous mode, interval: {args.interval}s\")\n while True:\n try:\n refresh_all(\n args.manifest,\n args.registry_url,\n registry_token,\n run_scan=args.scan,\n )\n except Exception as e:\n logger.error(f\"Refresh cycle failed: {e}\")\n logger.info(f\"Sleeping {args.interval}s until next refresh...\")\n time.sleep(args.interval)\n else:\n refresh_all(\n args.manifest,\n args.registry_url,\n registry_token,\n run_scan=args.scan,\n )\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/anthropic_transformer.py", "content": "#!/usr/bin/env python3\n\"\"\"Transform Anthropic MCP Registry server format to Gateway Registry format.\n\nThis module provides utilities to convert server definitions from the\nAnthropic MCP Registry API format into the format expected by the\nMCP Gateway Registry.\n\"\"\"\n\nimport json\nimport logging\nfrom typing import (\n Any,\n)\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nDEFAULT_BASE_PORT: int = 8100\nDEFAULT_TRANSPORT: str = \"stdio\"\nDEFAULT_DESCRIPTION: str = \"MCP server imported from Anthropic Registry\"\nDEFAULT_LICENSE: str = \"MIT\"\nDEFAULT_AUTH_PROVIDER: str = \"keycloak\"\nDEFAULT_AUTH_SCHEME: str = \"bearer\"\n\n\ndef _substitute_env_vars_in_headers(headers: list[dict[str, str]]) -> list[dict[str, str]]:\n \"\"\"Substitute environment variables in header values.\n\n Replaces ${VAR_NAME} or $VAR_NAME with actual environment variable values.\n If the environment variable is not set, keeps the placeholder.\n\n Args:\n headers: List of header dictionaries\n\n Returns:\n List of headers with environment variables substituted\n \"\"\"\n import os\n import re\n\n substituted_headers = []\n\n for header_dict in headers:\n substituted_header = {}\n for header_name, header_value in header_dict.items():\n # Match ${VAR_NAME} or $VAR_NAME pattern\n def replace_env_var(match):\n var_name = match.group(1)\n env_value = os.getenv(var_name)\n if env_value:\n logger.info(f\"Substituted {var_name} in header {header_name}\")\n return env_value\n else:\n logger.warning(\n f\"Environment variable {var_name} not found, keeping placeholder\"\n )\n return match.group(0) # Keep original placeholder\n\n # Replace ${VAR} pattern first\n substituted_value = re.sub(r\"\\$\\{([^}]+)\\}\", replace_env_var, header_value)\n # Then replace $VAR pattern (only for uppercase variables)\n substituted_value = re.sub(r\"\\$([A-Z_][A-Z0-9_]*)\", replace_env_var, substituted_value)\n\n substituted_header[header_name] = substituted_value\n\n substituted_headers.append(substituted_header)\n\n return substituted_headers\n\n\ndef _extract_remote_info(\n remotes: list[dict[str, Any]],\n) -> tuple[str | None, str, str, list[dict[str, str]]]:\n \"\"\"Extract remote URL, transport type, auth scheme, and headers from remotes field.\n\n Args:\n remotes: List of remote server configurations\n\n Returns:\n Tuple of (remote_url, transport_type, auth_scheme, headers)\n \"\"\"\n import re\n\n remote_url = None\n transport_type = DEFAULT_TRANSPORT\n auth_scheme = \"none\"\n output_headers = []\n\n if remotes:\n remote = remotes[0]\n remote_url = remote.get(\"url\")\n transport_type = remote.get(\"type\", \"streamable-http\")\n\n # Check if remote has authentication headers\n headers = remote.get(\"headers\", [])\n if headers:\n for header in headers:\n header_name = header.get(\"name\", \"\")\n header_value = header.get(\"value\", \"\")\n\n # Check for auth-related headers\n if header_name.lower() in [\"authorization\", \"x-api-key\", \"api-key\"]:\n # Extract variable name from the placeholder (e.g., {smithery_api_key})\n match = re.search(r\"\\{([^}]+)\\}\", header_value)\n if match:\n var_name = match.group(1)\n # Convert to uppercase with underscores (e.g., smithery_api_key -> SMITHERY_API_KEY)\n env_var_name = var_name.upper()\n\n # Determine auth scheme and create header value\n if \"bearer\" in header_value.lower():\n auth_scheme = \"bearer\"\n output_headers.append({header_name: f\"Bearer ${{{env_var_name}}}\"})\n elif \"api\" in header_value.lower() or \"key\" in header_value.lower():\n auth_scheme = \"api_key\"\n output_headers.append({header_name: f\"${{{env_var_name}}}\"})\n else:\n auth_scheme = \"bearer\"\n output_headers.append({header_name: f\"${{{env_var_name}}}\"})\n break\n\n return remote_url, transport_type, auth_scheme, output_headers\n\n\ndef _generate_tags(name: str) -> list[str]:\n \"\"\"Generate tags from server name.\n\n Args:\n name: Server name (may contain slashes)\n\n Returns:\n List of tags including name parts and 'anthropic-registry'\n \"\"\"\n name_parts = name.replace(\"/\", \"-\").split(\"-\")\n tags = name_parts + [\"anthropic-registry\"]\n return tags\n\n\ndef transform_anthropic_to_gateway(\n anthropic_response: dict[str, Any], base_port: int = DEFAULT_BASE_PORT\n) -> dict[str, Any]:\n \"\"\"Transform Anthropic ServerResponse to Gateway Registry Config format.\n\n Args:\n anthropic_response: Server data from Anthropic Registry API\n base_port: Base port number for local proxy URLs\n\n Returns:\n Dictionary in Gateway Registry configuration format\n\n Example:\n >>> response = {\"server\": {\"name\": \"brave-search\", ...}}\n >>> config = transform_anthropic_to_gateway(response)\n >>> print(config[\"server_name\"])\n brave-search\n \"\"\"\n server = anthropic_response.get(\"server\", anthropic_response)\n name = server[\"name\"]\n\n tags = _generate_tags(name)\n\n remotes = server.get(\"remotes\", [])\n remote_url, transport_type, auth_scheme, auth_headers = _extract_remote_info(remotes)\n\n # Substitute environment variables in headers\n if auth_headers:\n auth_headers = _substitute_env_vars_in_headers(auth_headers)\n\n safe_path = name.replace(\"/\", \"-\")\n\n proxy_url = remote_url if remote_url else f\"http://localhost:{base_port}/\"\n\n return {\n \"server_name\": name,\n \"description\": server.get(\"description\", DEFAULT_DESCRIPTION),\n \"path\": f\"/{safe_path}\",\n \"proxy_pass_url\": proxy_url,\n \"auth_provider\": DEFAULT_AUTH_PROVIDER if auth_scheme != \"none\" else None,\n \"auth_scheme\": auth_scheme,\n \"supported_transports\": [transport_type],\n \"tags\": tags,\n \"headers\": auth_headers if auth_headers else [],\n \"num_tools\": 0,\n \"license\": DEFAULT_LICENSE,\n \"remote_url\": remote_url,\n \"tool_list\": [],\n }\n\n\ndef _run_example() -> None:\n \"\"\"Run example transformation and print result.\"\"\"\n example_input = {\n \"name\": \"brave-search\",\n \"description\": \"MCP server for Brave Search API\",\n \"version\": \"0.1.0\",\n \"repository\": {\n \"type\": \"github\",\n \"url\": \"https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search\",\n },\n \"websiteUrl\": \"https://brave.com/search/api/\",\n \"packages\": {\"npm\": \"@modelcontextprotocol/server-brave-search\"},\n }\n\n result = transform_anthropic_to_gateway(example_input)\n print(json.dumps(result, indent=2))\n\n\nif __name__ == \"__main__\":\n _run_example()\n" }, { "path": "cli/bin/registry.js", "content": "#!/usr/bin/env node\n\nimport { spawn } from 'child_process';\nimport { fileURLToPath } from 'url';\nimport { dirname, join } from 'path';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst projectRoot = dirname(__dirname);\n\nconst child = spawn('npx', ['tsx', join(projectRoot, 'src/index.tsx'), ...process.argv.slice(2)], {\n stdio: 'inherit',\n shell: true\n});\n\nchild.on('exit', (code) => {\n process.exit(code);\n});\n" }, { "path": "cli/bootstrap_user_and_m2m_setup.sh", "content": "#!/bin/bash\n# Bootstrap script for setting up LOB users and M2M service accounts\n# Creates registry-users-lob1 and registry-users-lob2 groups\n# Then creates bot and human users in these groups\n\nset -e\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nPROJECT_ROOT=\"$(dirname \"$SCRIPT_DIR\")\"\nENV_FILE=\"$PROJECT_ROOT/.env\"\nUSER_MGMT_SCRIPT=\"$SCRIPT_DIR/user_mgmt.sh\"\n\n# Load environment variables from .env file\nif [ ! -f \"$ENV_FILE\" ]; then\n echo \"Error: .env file not found at $ENV_FILE\"\n exit 1\nfi\n\nset -a\nsource \"$ENV_FILE\"\nset +a\n\n# Configuration - read from .env variables\nADMIN_URL=\"${KEYCLOAK_ADMIN_URL}\"\nREALM=\"${KEYCLOAK_REALM}\"\nADMIN_USER=\"${KEYCLOAK_ADMIN}\"\nADMIN_PASS=\"${KEYCLOAK_ADMIN_PASSWORD}\"\nINITIAL_USER_PASSWORD=\"${INITIAL_USER_PASSWORD}\"\n\n# Colors for output\nGREEN='\\033[0;32m'\nRED='\\033[0;31m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m'\n\n\n_print_section() {\n echo \"\"\n echo -e \"${BLUE}==============================================\"\n echo \"$1\"\n echo \"===============================================${NC}\"\n}\n\n\n_print_success() {\n echo -e \"${GREEN}✓ $1${NC}\"\n}\n\n\n_print_error() {\n echo -e \"${RED}Error: $1${NC}\"\n}\n\n\n_print_info() {\n echo -e \"${YELLOW}$1${NC}\"\n}\n\n\n_validate_environment() {\n local missing_vars=()\n\n if [ -z \"$ADMIN_URL\" ]; then\n missing_vars+=(\"KEYCLOAK_ADMIN_URL\")\n fi\n\n if [ -z \"$REALM\" ]; then\n missing_vars+=(\"KEYCLOAK_REALM\")\n fi\n\n if [ -z \"$ADMIN_USER\" ]; then\n missing_vars+=(\"KEYCLOAK_ADMIN\")\n fi\n\n if [ -z \"$ADMIN_PASS\" ]; then\n missing_vars+=(\"KEYCLOAK_ADMIN_PASSWORD\")\n fi\n\n if [ -z \"$INITIAL_USER_PASSWORD\" ]; then\n missing_vars+=(\"INITIAL_USER_PASSWORD\")\n fi\n\n if [ ${#missing_vars[@]} -gt 0 ]; then\n _print_error \"Missing required environment variables in .env file:\"\n for var in \"${missing_vars[@]}\"; do\n echo \" - $var\"\n done\n echo \"\"\n echo \"Please update $ENV_FILE with the missing values\"\n exit 1\n fi\n}\n\n\n_get_admin_token() {\n TOKEN=$(curl -s -X POST \"$ADMIN_URL/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=$ADMIN_USER\" \\\n -d \"password=$ADMIN_PASS\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token // empty')\n\n if [ -z \"$TOKEN\" ]; then\n _print_error \"Failed to get admin token\"\n exit 1\n fi\n}\n\n\n_create_group() {\n local group_name=\"$1\"\n\n echo \"Creating group: $group_name\"\n\n # Check if group already exists\n EXISTING_GROUP=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$group_name\\\") | .id\")\n\n if [ -n \"$EXISTING_GROUP\" ] && [ \"$EXISTING_GROUP\" != \"null\" ]; then\n _print_info \"Group '$group_name' already exists (ID: $EXISTING_GROUP)\"\n return 0\n fi\n\n # Create the group\n GROUP_JSON=\"{\n \\\"name\\\": \\\"$group_name\\\"\n }\"\n\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/groups\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$GROUP_JSON\")\n\n if [ \"$RESPONSE\" = \"201\" ]; then\n _print_success \"Created group: $group_name\"\n else\n _print_error \"Failed to create group '$group_name'. HTTP: $RESPONSE\"\n exit 1\n fi\n}\n\n\n_check_user_mgmt_script() {\n if [ ! -f \"$USER_MGMT_SCRIPT\" ]; then\n _print_error \"user_mgmt.sh not found at $USER_MGMT_SCRIPT\"\n exit 1\n fi\n\n if [ ! -x \"$USER_MGMT_SCRIPT\" ]; then\n chmod +x \"$USER_MGMT_SCRIPT\"\n fi\n\n _print_success \"user_mgmt.sh found and is executable\"\n}\n\n\n_create_lob1_users() {\n _print_section \"Creating LOB1 Bot and Human Users\"\n\n echo \"Creating M2M service account: lob1-bot\"\n if \"$USER_MGMT_SCRIPT\" create-m2m \\\n --name \"lob1-bot\" \\\n --groups \"registry-users-lob1\" \\\n --description \"M2M service account for LOB1\" 2>&1 | tee /tmp/lob1_bot_output.txt; then\n _print_success \"Created lob1-bot\"\n else\n if grep -q \"already exists\" /tmp/lob1_bot_output.txt; then\n _print_info \"lob1-bot already exists, continuing...\"\n else\n _print_error \"Failed to create lob1-bot\"\n exit 1\n fi\n fi\n\n echo \"\"\n echo \"Creating human user: lob1-user\"\n if \"$USER_MGMT_SCRIPT\" create-human \\\n --username \"lob1-user\" \\\n --email \"lob1-user@example.com\" \\\n --firstname \"LOB1\" \\\n --lastname \"User\" \\\n --groups \"registry-users-lob1\" \\\n --password \"$INITIAL_USER_PASSWORD\" 2>&1 | tee /tmp/lob1_user_output.txt; then\n _print_success \"Created lob1-user\"\n else\n if grep -q \"already exists\" /tmp/lob1_user_output.txt; then\n _print_info \"lob1-user already exists, continuing...\"\n else\n _print_error \"Failed to create lob1-user\"\n exit 1\n fi\n fi\n}\n\n\n_create_lob2_users() {\n _print_section \"Creating LOB2 Bot and Human Users\"\n\n echo \"Creating M2M service account: lob2-bot\"\n if \"$USER_MGMT_SCRIPT\" create-m2m \\\n --name \"lob2-bot\" \\\n --groups \"registry-users-lob2\" \\\n --description \"M2M service account for LOB2\" 2>&1 | tee /tmp/lob2_bot_output.txt; then\n _print_success \"Created lob2-bot\"\n else\n if grep -q \"already exists\" /tmp/lob2_bot_output.txt; then\n _print_info \"lob2-bot already exists, continuing...\"\n else\n _print_error \"Failed to create lob2-bot\"\n exit 1\n fi\n fi\n\n echo \"\"\n echo \"Creating human user: lob2-user\"\n if \"$USER_MGMT_SCRIPT\" create-human \\\n --username \"lob2-user\" \\\n --email \"lob2-user@example.com\" \\\n --firstname \"LOB2\" \\\n --lastname \"User\" \\\n --groups \"registry-users-lob2\" \\\n --password \"$INITIAL_USER_PASSWORD\" 2>&1 | tee /tmp/lob2_user_output.txt; then\n _print_success \"Created lob2-user\"\n else\n if grep -q \"already exists\" /tmp/lob2_user_output.txt; then\n _print_info \"lob2-user already exists, continuing...\"\n else\n _print_error \"Failed to create lob2-user\"\n exit 1\n fi\n fi\n}\n\n\n_create_admin_users() {\n _print_section \"Creating Admin Bot and Admin User\"\n\n echo \"Creating M2M service account: admin-bot\"\n if \"$USER_MGMT_SCRIPT\" create-m2m \\\n --name \"admin-bot\" \\\n --groups \"registry-admins\" \\\n --description \"M2M service account for admin operations\" 2>&1 | tee /tmp/admin_bot_output.txt; then\n _print_success \"Created admin-bot\"\n else\n if grep -q \"already exists\" /tmp/admin_bot_output.txt; then\n _print_info \"admin-bot already exists, continuing...\"\n else\n _print_error \"Failed to create admin-bot\"\n exit 1\n fi\n fi\n\n echo \"\"\n echo \"Creating human user: admin-user\"\n if \"$USER_MGMT_SCRIPT\" create-human \\\n --username \"admin-user\" \\\n --email \"admin-user@example.com\" \\\n --firstname \"Admin\" \\\n --lastname \"User\" \\\n --groups \"registry-admins\" \\\n --password \"$INITIAL_USER_PASSWORD\" 2>&1 | tee /tmp/admin_user_output.txt; then\n _print_success \"Created admin-user\"\n else\n if grep -q \"already exists\" /tmp/admin_user_output.txt; then\n _print_info \"admin-user already exists, continuing...\"\n else\n _print_error \"Failed to create admin-user\"\n exit 1\n fi\n fi\n}\n\n\n_assign_mcp_gateway_to_registry_admins() {\n _print_section \"Assigning MCP Gateway Service Account to registry-admins\"\n\n local service_account_name=\"service-account-mcp-gateway-m2m\"\n\n echo \"Looking up service account: $service_account_name\"\n local service_account_id=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$service_account_name\" | \\\n jq -r '.[0].id // empty')\n\n if [ -z \"$service_account_id\" ]; then\n _print_info \"Service account '$service_account_name' not found in Keycloak. This may be expected if using external M2M setup.\"\n return 0\n fi\n\n echo \"Found service account with ID: $service_account_id\"\n\n echo \"Looking up registry-admins group\"\n local registry_admins_group_id=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r '.[] | select(.name==\"registry-admins\") | .id')\n\n if [ -z \"$registry_admins_group_id\" ] || [ \"$registry_admins_group_id\" = \"null\" ]; then\n _print_error \"Could not find registry-admins group\"\n return 1\n fi\n\n echo \"Found registry-admins group with ID: $registry_admins_group_id\"\n\n echo \"Assigning service account to registry-admins group\"\n local assign_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"$ADMIN_URL/admin/realms/$REALM/users/$service_account_id/groups/$registry_admins_group_id\" \\\n -H \"Authorization: Bearer $TOKEN\")\n\n if [ \"$assign_response\" = \"204\" ]; then\n _print_success \"Service account assigned to registry-admins group\"\n else\n _print_error \"Failed to assign service account to registry-admins group (HTTP $assign_response)\"\n return 1\n fi\n}\n\n\n_print_summary() {\n _print_section \"Bootstrap Setup Complete\"\n\n echo \"\"\n _print_info \"Created Groups:\"\n echo \" - registry-users-lob1\"\n echo \" - registry-users-lob2\"\n echo \" - registry-admins\"\n\n echo \"\"\n _print_info \"Created LOB1 Users:\"\n echo \" - Bot: lob1-bot (M2M service account)\"\n echo \" - Human: lob1-user (password: INITIAL_USER_PASSWORD env var)\"\n\n echo \"\"\n _print_info \"Created LOB2 Users:\"\n echo \" - Bot: lob2-bot (M2M service account)\"\n echo \" - Human: lob2-user (password: INITIAL_USER_PASSWORD env var)\"\n\n echo \"\"\n _print_info \"Created Admin Users:\"\n echo \" - Bot: admin-bot (M2M service account)\"\n echo \" - Human: admin-user (password: INITIAL_USER_PASSWORD env var)\"\n\n echo \"\"\n _print_info \"Next Steps:\"\n echo \" 1. Update scopes.yml to configure access for these groups\"\n echo \" 2. Regenerate admin-bot token using: ./keycloak/setup/generate-agent-token.sh admin-bot\"\n echo \" 3. Test access with the generated tokens\"\n echo \" 4. Login to dashboard as admin-user, lob1-user, or lob2-user\"\n\n echo \"\"\n _print_info \"Credentials saved to: .oauth-tokens/\"\n}\n\n\nmain() {\n _print_section \"Bootstrap: LOB User and M2M Setup\"\n\n # Validate environment variables\n _validate_environment\n\n # Check if user_mgmt.sh exists\n _check_user_mgmt_script\n\n # Get admin token\n echo \"Authenticating with Keycloak...\"\n _get_admin_token\n _print_success \"Authentication successful\"\n\n # Create groups\n _print_section \"Creating Keycloak Groups\"\n _create_group \"registry-users-lob1\"\n _create_group \"registry-users-lob2\"\n _create_group \"registry-admins\"\n\n # Create LOB1 users\n _create_lob1_users\n\n # Create LOB2 users\n _create_lob2_users\n\n # Create Admin users\n _create_admin_users\n\n # Assign MCP Gateway service account to registry-admins group\n _assign_mcp_gateway_to_registry_admins\n\n # Print summary\n _print_summary\n}\n\n\nmain \"$@\"\n" }, { "path": "cli/examples/README.md", "content": "# Agent Management Examples\n\nThis directory contains example JSON files for registering A2A agents using the agent management CLI.\n\n## Quick Start\n\n### Service Account: `mcp-gateway-m2m`\n\nThe agent management CLI uses the **`mcp-gateway-m2m`** service account for all operations.\n\n**Token Details:**\n- **Service Account ID:** `mcp-gateway-m2m`\n- **Token Location:** `.oauth-tokens/ingress.json`\n- **Token Generation:** `./credentials-provider/generate_creds.sh`\n- **Required Keycloak Groups:**\n - `mcp-servers-unrestricted` (for MCP server access)\n - `a2a-agent-admin` (for agent management permissions)\n\n### Prerequisites\n\nStart the registry service in one terminal:\n\n```bash\npython -m uvicorn registry.main:app --reload\n```\n\nWait for: `Uvicorn running on http://127.0.0.1:8000`\n\n### Register an Agent\n\nIn another terminal, the agent management CLI will automatically use the `mcp-gateway-m2m` token from `.oauth-tokens/ingress.json`:\n\n```bash\n# Register the test code reviewer agent\n# Token is automatically loaded from .oauth-tokens/ingress.json (mcp-gateway-m2m service account)\nuv run python cli/agent_mgmt.py register cli/examples/test_code_reviewer_agent.json\n```\n\n### Verify Registration\n\n```bash\n# List all agents\nuv run python cli/agent_mgmt.py list\n\n# Get specific agent details\nuv run python cli/agent_mgmt.py get /test-reviewer\n\n# Test agent accessibility\nuv run python cli/agent_mgmt.py test /test-reviewer\n```\n\n## Available Examples\n\nAll example files use the complete A2A agent schema with all fields documented:\n\n### code_reviewer_agent.json\n\nComprehensive code review agent analyzing code quality, bugs, and improvements.\n\n**Skills:**\n- Analyze Code Quality\n- Detect Bugs\n- Suggest Improvements\n\n**Security:** JWT Bearer token authentication\n**Features:** Streaming enabled, verified trust level\n\n**Usage:**\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/code_reviewer_agent.json\n```\n\n### test_automation_agent.json\n\nIntelligent test automation agent for generating and executing test cases.\n\n**Skills:**\n- Generate Unit Tests\n- Execute Tests\n- Analyze Test Coverage\n- Generate Test Report\n\n**Security:** API Key + OAuth2 authentication\n**Features:** Streaming enabled, community trust level\n\n**Usage:**\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/test_automation_agent.json\n```\n\n### data_analysis_agent.json\n\nAdvanced data analysis agent for statistical analysis and visualization.\n\n**Skills:**\n- Statistical Analysis\n- Data Visualization\n- Predictive Modeling\n- Anomaly Detection\n- Data Transformation\n\n**Security:** JWT Bearer + OpenID Connect\n**Features:** GPU-enabled, verified trust level, supports large datasets\n\n**Usage:**\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/data_analysis_agent.json\n```\n\n### security_analyzer_agent.json\n\nComprehensive security analysis agent for vulnerability detection and compliance.\n\n**Skills:**\n- Scan for Vulnerabilities\n- Check Compliance\n- Analyze Authentication\n- Penetration Testing\n- Generate Security Report\n\n**Security:** Mutual TLS + API Key authentication\n**Features:** Trusted level, comprehensive CVE database\n\n**Usage:**\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/security_analyzer_agent.json\n```\n\n### documentation_agent.json\n\nDocumentation agent for generating and maintaining API docs and guides.\n\n**Skills:**\n- Generate API Documentation\n- Extract and Format Docstrings\n- Generate README\n- Maintain Documentation\n- Generate Changelog\n\n**Security:** Basic Auth + API Token\n**Features:** Supports multiple documentation formats, community trust level\n\n**Usage:**\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/documentation_agent.json\n```\n\n### devops_deployment_agent.json\n\nDevOps automation agent for infrastructure and deployment management.\n\n**Skills:**\n- Deploy Application\n- Manage Infrastructure\n- Configure CI/CD Pipeline\n- Monitor Health and Performance\n- Manage Secrets and Credentials\n- Auto-Scale Application\n\n**Security:** AWS SigV4 + Client Certificate\n**Features:** Multi-cloud support, verified trust level\n\n**Usage:**\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/devops_deployment_agent.json\n```\n\n## Complete A2A Schema Fields\n\nAll example files include the complete A2A agent schema:\n\n**Required Fields:**\n- `protocol_version`: A2A protocol version (e.g., \"1.0\")\n- `name`: Agent display name\n- `description`: What the agent does\n- `url`: Agent endpoint URL\n- `path`: Registry path (must start with `/`)\n\n**Optional A2A Fields:**\n- `version`: Semantic version\n- `provider`: Agent provider/author\n- `security_schemes`: Authentication methods (http, apiKey, oauth2, openIdConnect)\n- `security`: Security requirements array\n- `skills`: Array of capabilities with parameters\n- `streaming`: Supports streaming responses (boolean)\n- `metadata`: Additional metadata key-value pairs\n\n**Registry Extensions:**\n- `tags`: Array of categorization tags\n- `is_enabled`: Whether agent is enabled\n- `num_stars`: Community rating\n- `license`: License information\n- `visibility`: \"public\", \"private\", or \"group-restricted\"\n- `allowed_groups`: Groups with access (for group-restricted)\n- `trust_level`: \"unverified\", \"community\", \"verified\", or \"trusted\"\n- `registered_at`: Registration timestamp (auto-set)\n- `updated_at`: Last update timestamp (auto-set)\n- `registered_by`: Username who registered (auto-set)\n- `signature`: JWS signature for integrity\n\n**Federation & Lifecycle Metadata (New):**\n- `status`: Lifecycle status - \"active\", \"beta\", \"draft\", or \"deprecated\"\n- `provider`: Provider information object with:\n - `organization`: Provider organization name\n - `url`: Provider website or documentation URL\n- `source_created_at`: Original creation timestamp from source system (ISO 8601 format)\n- `source_updated_at`: Last update timestamp from source system (ISO 8601 format)\n\n### Complete Examples with All Fields\n\nFor reference implementations showing all available fields including the new federation and lifecycle metadata:\n\n**complete-server-example.json**\n- Shows all server configuration fields\n- Includes lifecycle status, provider info, federation timestamps\n- Demonstrates custom metadata usage\n\n**complete-agent-example.json**\n- Shows all agent configuration fields\n- Includes lifecycle status, provider info, federation timestamps\n- Full agent card schema example\n\n**Usage:**\n```bash\n# Register server with all fields\nuv run python cli/registry_mgmt.py register cli/examples/complete-server-example.json\n\n# Register agent with all fields\nuv run python cli/agent_mgmt.py register cli/examples/complete-agent-example.json\n```\n\n## Creating Your Own Agent File\n\nCopy an example and modify the fields:\n\n```bash\ncp cli/examples/test_code_reviewer_agent.json cli/examples/my_custom_agent.json\n```\n\nThen edit the JSON with your agent details:\n\n```json\n{\n \"name\": \"My Custom Agent\",\n \"path\": \"/my-agent\",\n \"description\": \"What my agent does\",\n \"url\": \"http://my-domain.com/agents/my-agent\",\n \"version\": \"1.0.0\",\n \"visibility\": \"public\",\n \"trust_level\": \"community\",\n \"tags\": [\"custom\", \"my-agent\"],\n \"security_schemes\": {\n \"bearer\": {\n \"type\": \"bearer\"\n }\n },\n \"protocol_version\": \"1.0\"\n}\n```\n\nRegister your agent:\n\n```bash\nexport TOKEN=\"test-token\"\nuv run python cli/agent_mgmt.py register cli/examples/my_custom_agent.json\n```\n\n## Required Fields\n\nAll agent JSON files must include:\n\n- `name` - Agent display name (string)\n- `path` - Internal path identifier (string, must start with `/`)\n- `description` - Brief description (string)\n- `url` - Agent endpoint URL (string)\n- `version` - Version number (string, e.g., \"1.0.0\")\n- `visibility` - Public visibility (string: \"public\", \"private\", \"community\")\n- `trust_level` - Trust classification (string)\n- `tags` - Discovery tags (array of strings)\n- `security_schemes` - Authentication config (object)\n- `protocol_version` - A2A protocol version (string)\n\n## Error Handling\n\n### Agent Already Exists (HTTP 409)\n\nIf you get: `Error: Agent with path '/test-reviewer' already exists`\n\nSolution: Change the path in your JSON file or delete the existing agent.\n\n### Validation Failed (HTTP 422)\n\nIf you get: `Error: Validation failed - check agent JSON format`\n\nSolution: Verify all required fields are present and properly formatted. Validate with:\n\n```bash\njq . cli/examples/test_code_reviewer_agent.json\n```\n\n### Connection Refused\n\nIf you get connection errors:\n\n1. Ensure the registry service is running\n2. Check it's on the correct port (default: `localhost:8000`)\n3. Verify with: `curl http://localhost:8000/api/health`\n\n## Storage\n\nAfter registration, agent files are stored in:\n\n```bash\nls registry/agents/\ncat registry/agents/test-reviewer.json\ncat registry/agents/agent_state.json\n```\n\n## Next Steps\n\n1. Register a test agent\n2. View agents in the frontend dashboard\n3. Test agent accessibility\n4. Explore the admin panel for agent management\n\nFor complete documentation, see: `.scratchpad/A2A_AGENT_CLI_REGISTRATION_GUIDE.md`\n" }, { "path": "cli/examples/airegistry.json", "content": "{\n \"server_name\": \"AI Registry tools\",\n \"description\": \"Provides tools to discover and list servers, agents, and skills in the AI Registry. Includes intelligent tool finder which uses semantic search to discover the most relevant tools across all registered services.\",\n \"path\": \"/airegistry-tools/\",\n \"proxy_pass_url\": \"http://mcpgw-server:8003/\",\n \"supported_transports\": [\"streamable-http\"],\n \"auth_scheme\": \"none\",\n \"tags\": [\"registry\", \"discovery\", \"search\", \"semantic-search\", \"tool-finder\", \"servers\", \"agents\", \"skills\"],\n \"num_tools\": 0,\n \"license\": \"N/A\",\n \"tool_list\": [\n ]\n}\n" }, { "path": "cli/examples/aws-kb-server.json", "content": "{\n \"server_name\": \"AWS kb\",\n \"description\": \"A fully managed remote MCP server that provides up-to-date documentation, code samples, knowledge about the regional availability of AWS APIs and CloudFormation resources, and other official AWS content.\",\n \"path\": \"/aws-kb\",\n \"proxy_pass_url\": \"https://knowledge-mcp.global.api.aws\",\n \"tags\": [\"aws\", \"kb\", \"documentation\", \"knowledge-base\"],\n \"auth_scheme\": \"none\",\n \"supported_transports\": [\"streamable-http\"],\n \"mcp_endpoint\": \"https://knowledge-mcp.global.api.aws\",\n \"metadata\": {\n \"category\": \"documentation\",\n \"official\": true,\n \"provider\": \"AWS\"\n },\n \"status\": \"active\",\n \"provider_organization\": \"Amazon Web Services\",\n \"provider_url\": \"https://aws.amazon.com\",\n \"visibility\": \"public\"\n}\n" }, { "path": "cli/examples/cloudflare-docs-server-config.json", "content": "{\n \"server_name\": \"Cloudflare Documentation MCP Server\",\n \"description\": \"Search Cloudflare documentation and get migration guides\",\n \"path\": \"/cloudflare-docs\",\n \"proxy_pass_url\": \"https://docs.mcp.cloudflare.com/mcp\",\n \"supported_transports\": [\"streamable-http\"],\n \"tags\": [\"documentation\", \"cloudflare\", \"cdn\", \"workers\", \"pages\", \"migration-guide\"],\n \"status\": \"active\",\n \"provider_organization\": \"Cloudflare Inc.\",\n \"provider_url\": \"https://www.cloudflare.com\",\n \"visibility\": \"public\",\n \"metadata\": {\n \"category\": \"documentation\",\n \"official\": true,\n \"mcp_compatible\": \"1.0\"\n }\n}\n" }, { "path": "cli/examples/code_reviewer_agent.json", "content": "{\n \"protocolVersion\": \"1.0\",\n \"name\": \"Code Reviewer Agent\",\n \"description\": \"Comprehensive code review agent that analyzes code quality, identifies bugs, suggests improvements, and provides detailed feedback on code structure and best practices\",\n \"url\": \"https://example.com/agents/code-reviewer\",\n \"version\": \"2.1.0\",\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\"text/plain\", \"application/json\"],\n \"defaultOutputModes\": [\"text/plain\", \"application/json\"],\n \"skills\": [\n {\n \"id\": \"analyze_code_quality\",\n \"name\": \"Analyze Code Quality\",\n \"description\": \"Analyze code for quality metrics including complexity, duplication, and maintainability\",\n \"tags\": [\n \"analysis\",\n \"metrics\"\n ],\n \"examples\": [\n \"Analyze code quality for this Python function\",\n \"Check code quality metrics for JavaScript module\"\n ],\n \"inputModes\": [\"text/plain\"],\n \"outputModes\": [\"application/json\"]\n },\n {\n \"id\": \"detect_bugs\",\n \"name\": \"Detect Bugs\",\n \"description\": \"Identify potential bugs and issues in the code\",\n \"tags\": [\n \"bug-detection\",\n \"validation\"\n ],\n \"examples\": [\n \"Detect critical bugs in this code\",\n \"Find high severity issues\"\n ],\n \"inputModes\": [\"text/plain\"],\n \"outputModes\": [\"application/json\"]\n },\n {\n \"id\": \"suggest_improvements\",\n \"name\": \"Suggest Improvements\",\n \"description\": \"Provide suggestions for code improvements and refactoring\",\n \"tags\": [\n \"improvement\",\n \"refactoring\"\n ],\n \"examples\": [\n \"Suggest performance improvements for this code\",\n \"Recommend security enhancements\"\n ],\n \"inputModes\": [\"text/plain\"],\n \"outputModes\": [\"application/json\"]\n }\n ],\n \"preferredTransport\": \"JSONRPC\",\n \"provider\": \"Example Corp\",\n \"securitySchemes\": {\n \"bearer_auth\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\",\n \"bearerFormat\": \"JWT\"\n }\n },\n \"security\": [\n {\n \"bearer_auth\": []\n }\n ],\n \"metadata\": {\n \"max_code_size_mb\": 10,\n \"supported_formats\": [\n \"json\",\n \"xml\",\n \"yaml\"\n ],\n \"response_time_ms\": 2000,\n \"availability\": \"99.9%\"\n },\n \"path\": \"/code-reviewer\",\n \"tags\": [\"code-review\", \"quality-analysis\", \"testing\", \"best-practices\"],\n \"isEnabled\": true,\n \"numStars\": 42,\n \"license\": \"MIT\",\n \"visibility\": \"public\",\n \"trustLevel\": \"verified\"\n}\n" }, { "path": "cli/examples/complete-agent-example.json", "content": "{\n \"protocolVersion\": \"0.3.0\",\n \"name\": \"Complete Agent Example\",\n \"description\": \"Example showing all available agent configuration fields including new lifecycle and federation metadata\",\n \"url\": \"https://agent.example.com:9000/\",\n \"path\": \"/complete-agent-example\",\n \"version\": \"1.0.0\",\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\"text/plain\", \"application/json\"],\n \"defaultOutputModes\": [\"text/plain\", \"application/json\"],\n \"tags\": [\"example\", \"documentation\", \"reference\"],\n \"visibility\": \"public\",\n \"status\": \"active\",\n \"provider\": {\n \"organization\": \"ACME AI Labs\",\n \"url\": \"https://ai.acme.com\"\n },\n \"skills\": [\n {\n \"id\": \"example_skill\",\n \"name\": \"Example Skill\",\n \"description\": \"An example skill demonstrating agent capabilities\",\n \"tags\": [\"example\", \"demo\"]\n }\n ]\n}\n" }, { "path": "cli/examples/complete-server-example.json", "content": "{\n \"server_name\": \"Complete Server Example\",\n \"description\": \"Example showing all available server configuration fields including new lifecycle and federation metadata\",\n \"path\": \"/complete-example\",\n \"proxy_pass_url\": \"https://example.com:8080\",\n \"tags\": [\"example\", \"documentation\", \"reference\"],\n \"auth_scheme\": \"none\",\n \"supported_transports\": [\"streamable-http\", \"sse\"],\n \"mcp_endpoint\": \"https://example.com:8080/custom-mcp\",\n \"sse_endpoint\": \"https://example.com:8080/custom-sse\",\n \"metadata\": {\n \"team\": \"platform-engineering\",\n \"owner\": \"alice@example.com\",\n \"cost_center\": \"CC-1001\",\n \"environment\": \"production\"\n },\n \"status\": \"active\",\n \"provider_organization\": \"ACME Corporation\",\n \"provider_url\": \"https://www.acme.com\",\n \"visibility\": \"public\"\n}\n" }, { "path": "cli/examples/context7-server-config.json", "content": "{\n \"server_name\": \"Context7 MCP Server\",\n \"description\": \"Up-to-date Docs for LLMs and AI code editors\",\n \"path\": \"/context7\",\n \"version\": \"v1.0.0\",\n \"proxy_pass_url\": \"https://mcp.context7.com/mcp\",\n \"supported_transports\": [\"streamable-http\"],\n \"tags\": [\"documentation\", \"search\", \"libraries\", \"packages\", \"api-reference\", \"code-examples\"]\n}\n" }, { "path": "cli/examples/context7-v2-server-config.json", "content": "{\n \"server_name\": \"Context7 MCP Server\",\n \"description\": \"Up-to-date Docs for LLMs and AI code editors (Version 2 - Beta)\",\n \"path\": \"/context7\",\n \"version\": \"v2.0.0\",\n \"status\": \"beta\",\n \"proxy_pass_url\": \"https://mcp-v2.context7.com/mcp\",\n \"supported_transports\": [\"streamable-http\"],\n \"tags\": [\"documentation\", \"search\", \"libraries\", \"packages\", \"api-reference\", \"code-examples\"]\n}\n" }, { "path": "cli/examples/currenttime-users.json", "content": "{\n \"scope_name\": \"currenttime-users\",\n \"description\": \"Users with access to currenttime server\",\n \"server_access\": [\n {\n \"server\": \"currenttime\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"current_time_by_timezone\"]\n },\n {\n \"server\": \"/currenttime/\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"current_time_by_timezone\"]\n },\n {\n \"server\": \"/currenttime\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"current_time_by_timezone\"]\n },\n {\n \"server\": \"context7\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"initialize\", \"GET\", \"POST\", \"servers\", \"agents\", \"search\", \"rating\"],\n \"tools\": []\n }\n ],\n \"group_mappings\": [\"currenttime-users\"],\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"health_check_service\": [\"all\"]\n },\n \"create_in_idp\": true\n}\n" }, { "path": "cli/examples/currenttime-v2.json", "content": "{\n \"server_name\": \"Current Time API\",\n \"description\": \"A simple API that returns the current server time in various formats.\",\n \"path\": \"/currenttime/\",\n \"proxy_pass_url\": \"http://currenttime-server:8000/\",\n \"mcp_endpoint\": \"http://currenttime-server:8000/mcp\",\n \"auth_scheme\": \"none\",\n \"tags\": [\"time\", \"timezone\", \"datetime\", \"api\", \"utility\", \"v0.9\"],\n \"num_tools\": 1,\n \"version\": \"v0.9\",\n \"status\": \"beta\",\n \"license\": \"MIT-0\",\n \"metadata\": {\n \"team\": \"platform-services\",\n \"owner\": \"alice@example.com\",\n \"cost_center\": \"CC-1001\",\n \"compliance\": [\"SOC2\"],\n \"deployment_region\": \"us-east-1\",\n \"jira_project\": \"PLAT-123\",\n \"environment\": \"production\"\n }\n}" }, { "path": "cli/examples/currenttime.json", "content": "{\n \"server_name\": \"Current Time API\",\n \"description\": \"A simple API that returns the current server time in various formats.\",\n \"path\": \"/currenttime/\",\n \"proxy_pass_url\": \"http://currenttime-server:8000/\",\n \"auth_scheme\": \"none\",\n \"tags\": [\"time\", \"timezone\", \"datetime\", \"api\", \"utility\"],\n \"num_tools\": 1,\n \"license\": \"MIT-0\",\n \"status\": \"active\",\n \"visibility\": \"public\"\n}" }, { "path": "cli/examples/data_analysis_agent.json", "content": "{\n \"protocol_version\": \"1.0\",\n \"name\": \"Data Analysis Agent\",\n \"description\": \"Advanced data analysis agent for statistical analysis, data visualization, and insight generation. Supports multiple data formats and provides predictive analytics\",\n \"url\": \"https://example.com/agents/data-analysis\",\n \"version\": \"3.2.1\",\n \"provider\": \"Analytics Solutions Inc\",\n \"path\": \"/data-analysis\",\n \"tags\": \"analytics,data-science,visualization,statistics\",\n \"is_enabled\": true,\n \"num_stars\": 56,\n \"license\": \"GPL-3.0\",\n \"visibility\": \"public\",\n \"trust_level\": \"verified\",\n \"streaming\": true,\n \"security_schemes\": {\n \"bearer_jwt\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\",\n \"bearer_format\": \"JWT\"\n },\n \"openid\": {\n \"type\": \"openIdConnect\",\n \"openid_connect_url\": \"https://auth.example.com/.well-known/openid-configuration\"\n }\n },\n \"security\": [\n {\n \"bearer_jwt\": []\n },\n {\n \"openid\": []\n }\n ],\n \"skills\": [\n {\n \"id\": \"statistical_analysis\",\n \"name\": \"Statistical Analysis\",\n \"description\": \"Perform comprehensive statistical analysis including hypothesis testing and distribution analysis\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"type\": \"array\",\n \"description\": \"Array of numerical data points\"\n },\n \"analyses\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"mean\",\n \"median\",\n \"std_dev\",\n \"variance\",\n \"quartiles\",\n \"skewness\",\n \"kurtosis\"\n ]\n },\n \"description\": \"Statistical measures to calculate\"\n },\n \"confidence_level\": {\n \"type\": \"number\",\n \"minimum\": 0.9,\n \"maximum\": 0.99,\n \"description\": \"Confidence level for hypothesis tests\"\n }\n },\n \"required\": [\n \"data\",\n \"analyses\"\n ]\n },\n \"tags\": [\n \"statistics\",\n \"analysis\"\n ]\n },\n {\n \"id\": \"data_visualization\",\n \"name\": \"Data Visualization\",\n \"description\": \"Create visualizations and charts from data\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"type\": \"object\",\n \"description\": \"Data object with values and labels\"\n },\n \"chart_type\": {\n \"type\": \"string\",\n \"enum\": [\n \"line\",\n \"bar\",\n \"pie\",\n \"scatter\",\n \"heatmap\",\n \"box-plot\"\n ],\n \"description\": \"Type of chart to create\"\n },\n \"title\": {\n \"type\": \"string\",\n \"description\": \"Chart title\"\n },\n \"export_format\": {\n \"type\": \"string\",\n \"enum\": [\n \"svg\",\n \"png\",\n \"pdf\"\n ],\n \"description\": \"Output format\"\n }\n },\n \"required\": [\n \"data\",\n \"chart_type\"\n ]\n },\n \"tags\": [\n \"visualization\",\n \"charts\"\n ]\n },\n {\n \"id\": \"predictive_modeling\",\n \"name\": \"Predictive Modeling\",\n \"description\": \"Build and train machine learning models for predictions\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"training_data\": {\n \"type\": \"object\",\n \"description\": \"Training dataset\"\n },\n \"model_type\": {\n \"type\": \"string\",\n \"enum\": [\n \"linear_regression\",\n \"logistic_regression\",\n \"random_forest\",\n \"neural_network\"\n ],\n \"description\": \"Type of model to train\"\n },\n \"test_size\": {\n \"type\": \"number\",\n \"minimum\": 0.1,\n \"maximum\": 0.5,\n \"description\": \"Proportion of data to use for testing\"\n },\n \"hyperparameters\": {\n \"type\": \"object\",\n \"description\": \"Model-specific hyperparameters\"\n }\n },\n \"required\": [\n \"training_data\",\n \"model_type\"\n ]\n },\n \"tags\": [\n \"machine-learning\",\n \"prediction\"\n ]\n },\n {\n \"id\": \"anomaly_detection\",\n \"name\": \"Anomaly Detection\",\n \"description\": \"Detect anomalies and outliers in data\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"type\": \"array\",\n \"description\": \"Data points to analyze\"\n },\n \"method\": {\n \"type\": \"string\",\n \"enum\": [\n \"isolation_forest\",\n \"local_outlier_factor\",\n \"statistical\",\n \"dbscan\"\n ],\n \"description\": \"Detection method\"\n },\n \"contamination\": {\n \"type\": \"number\",\n \"minimum\": 0.01,\n \"maximum\": 0.5,\n \"description\": \"Proportion of outliers expected\"\n }\n },\n \"required\": [\n \"data\",\n \"method\"\n ]\n },\n \"tags\": [\n \"anomaly-detection\",\n \"outliers\"\n ]\n },\n {\n \"id\": \"data_transformation\",\n \"name\": \"Data Transformation\",\n \"description\": \"Transform and preprocess data for analysis\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"type\": \"object\",\n \"description\": \"Input data\"\n },\n \"transformations\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"normalize\",\n \"standardize\",\n \"log_scale\",\n \"one_hot_encode\"\n ]\n },\n \"description\": \"Transformations to apply\"\n }\n },\n \"required\": [\n \"data\",\n \"transformations\"\n ]\n },\n \"tags\": [\n \"preprocessing\",\n \"transformation\"\n ]\n }\n ],\n \"metadata\": {\n \"max_dataset_size_gb\": 100,\n \"supported_formats\": [\n \"csv\",\n \"json\",\n \"parquet\",\n \"xlsx\"\n ],\n \"computation_gpu_enabled\": true,\n \"avg_analysis_time_seconds\": 30\n }\n}\n" }, { "path": "cli/examples/devops_deployment_agent.json", "content": "{\n \"protocol_version\": \"1.0\",\n \"name\": \"DevOps Deployment Agent\",\n \"description\": \"DevOps automation agent for infrastructure management, deployment orchestration, and continuous integration/deployment pipeline management across multiple cloud platforms\",\n \"url\": \"https://example.com/agents/devops-deployment\",\n \"version\": \"2.3.0\",\n \"provider\": \"CloudOps Inc\",\n \"path\": \"/devops-deployment\",\n \"tags\": \"devops,deployment,infrastructure,ci-cd,cloud\",\n \"is_enabled\": true,\n \"num_stars\": 64,\n \"license\": \"Apache-2.0\",\n \"visibility\": \"public\",\n \"trust_level\": \"verified\",\n \"streaming\": true,\n \"security_schemes\": {\n \"aws_sigv4\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\",\n \"bearer_format\": \"AWS4-HMAC-SHA256\"\n },\n \"client_cert\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\",\n \"bearer_format\": \"X.509\"\n }\n },\n \"security\": [\n {\n \"aws_sigv4\": []\n },\n {\n \"client_cert\": []\n }\n ],\n \"skills\": [\n {\n \"id\": \"deploy_application\",\n \"name\": \"Deploy Application\",\n \"description\": \"Deploy applications to various cloud platforms and Kubernetes clusters\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"deployment_config\": {\n \"type\": \"object\",\n \"description\": \"Deployment configuration (Dockerfile, K8s manifest, etc)\"\n },\n \"target_environment\": {\n \"type\": \"string\",\n \"enum\": [\n \"development\",\n \"staging\",\n \"production\"\n ],\n \"description\": \"Target environment\"\n },\n \"cloud_provider\": {\n \"type\": \"string\",\n \"enum\": [\n \"aws\",\n \"gcp\",\n \"azure\",\n \"kubernetes\"\n ],\n \"description\": \"Cloud platform to deploy to\"\n },\n \"rollback_on_failure\": {\n \"type\": \"boolean\",\n \"description\": \"Automatically rollback on deployment failure\"\n }\n },\n \"required\": [\n \"deployment_config\",\n \"target_environment\"\n ]\n },\n \"tags\": [\n \"deployment\",\n \"orchestration\"\n ]\n },\n {\n \"id\": \"manage_infrastructure\",\n \"name\": \"Manage Infrastructure\",\n \"description\": \"Create, update, and manage cloud infrastructure as code\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"infrastructure_code\": {\n \"type\": \"string\",\n \"description\": \"IaC code (Terraform, CloudFormation, etc)\"\n },\n \"action\": {\n \"type\": \"string\",\n \"enum\": [\n \"plan\",\n \"apply\",\n \"destroy\",\n \"validate\"\n ],\n \"description\": \"IaC action to perform\"\n },\n \"cloud_provider\": {\n \"type\": \"string\",\n \"enum\": [\n \"aws\",\n \"gcp\",\n \"azure\"\n ],\n \"description\": \"Cloud provider\"\n }\n },\n \"required\": [\n \"infrastructure_code\",\n \"action\"\n ]\n },\n \"tags\": [\n \"infrastructure\",\n \"iac\"\n ]\n },\n {\n \"id\": \"configure_cicd\",\n \"name\": \"Configure CI/CD Pipeline\",\n \"description\": \"Set up and configure continuous integration and deployment pipelines\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"repository_url\": {\n \"type\": \"string\",\n \"description\": \"Git repository URL\"\n },\n \"pipeline_type\": {\n \"type\": \"string\",\n \"enum\": [\n \"github-actions\",\n \"gitlab-ci\",\n \"jenkins\",\n \"circleci\"\n ],\n \"description\": \"CI/CD platform\"\n },\n \"stages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"test\",\n \"build\",\n \"deploy\",\n \"monitor\"\n ]\n },\n \"description\": \"Pipeline stages to include\"\n }\n },\n \"required\": [\n \"repository_url\",\n \"pipeline_type\"\n ]\n },\n \"tags\": [\n \"ci-cd\",\n \"automation\"\n ]\n },\n {\n \"id\": \"monitor_health\",\n \"name\": \"Monitor Health and Performance\",\n \"description\": \"Monitor application health, performance metrics, and alerting\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"deployment_id\": {\n \"type\": \"string\",\n \"description\": \"ID of deployed application\"\n },\n \"metrics\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"cpu\",\n \"memory\",\n \"network\",\n \"latency\",\n \"error_rate\"\n ]\n },\n \"description\": \"Metrics to monitor\"\n },\n \"alert_thresholds\": {\n \"type\": \"object\",\n \"description\": \"Threshold values for alerts\"\n }\n },\n \"required\": [\n \"deployment_id\"\n ]\n },\n \"tags\": [\n \"monitoring\",\n \"observability\"\n ]\n },\n {\n \"id\": \"manage_secrets\",\n \"name\": \"Manage Secrets and Credentials\",\n \"description\": \"Securely manage and rotate secrets, API keys, and credentials\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"secret_name\": {\n \"type\": \"string\",\n \"description\": \"Name of the secret\"\n },\n \"secret_type\": {\n \"type\": \"string\",\n \"enum\": [\n \"api_key\",\n \"database_password\",\n \"certificate\",\n \"oauth_token\"\n ],\n \"description\": \"Type of secret\"\n },\n \"rotation_policy\": {\n \"type\": \"string\",\n \"enum\": [\n \"daily\",\n \"weekly\",\n \"monthly\",\n \"manual\"\n ],\n \"description\": \"Secret rotation policy\"\n }\n },\n \"required\": [\n \"secret_name\",\n \"secret_type\"\n ]\n },\n \"tags\": [\n \"security\",\n \"secrets-management\"\n ]\n },\n {\n \"id\": \"scale_application\",\n \"name\": \"Auto-Scale Application\",\n \"description\": \"Configure auto-scaling policies based on metrics and demand\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"deployment_id\": {\n \"type\": \"string\",\n \"description\": \"ID of application to scale\"\n },\n \"scaling_metric\": {\n \"type\": \"string\",\n \"enum\": [\n \"cpu_utilization\",\n \"memory_usage\",\n \"request_count\"\n ],\n \"description\": \"Metric to trigger scaling\"\n },\n \"min_instances\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": \"Minimum number of instances\"\n },\n \"max_instances\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": \"Maximum number of instances\"\n }\n },\n \"required\": [\n \"deployment_id\",\n \"scaling_metric\"\n ]\n },\n \"tags\": [\n \"scaling\",\n \"optimization\"\n ]\n }\n ],\n \"metadata\": {\n \"supported_cloud_providers\": [\n \"aws\",\n \"gcp\",\n \"azure\",\n \"digitalocean\",\n \"linode\"\n ],\n \"supported_container_platforms\": [\n \"docker\",\n \"kubernetes\",\n \"ecs\",\n \"gke\"\n ],\n \"iac_frameworks\": [\n \"terraform\",\n \"cloudformation\",\n \"pulumi\",\n \"ansible\"\n ],\n \"cicd_platforms\": [\n \"github-actions\",\n \"gitlab-ci\",\n \"jenkins\",\n \"circleci\",\n \"travis-ci\"\n ],\n \"sla_uptime_percent\": 99.95,\n \"deployment_speed_seconds\": 120\n }\n}\n" }, { "path": "cli/examples/documentation_agent.json", "content": "{\n \"protocol_version\": \"1.0\",\n \"name\": \"Documentation Agent\",\n \"description\": \"Intelligent documentation agent that generates, updates, and maintains API documentation, guides, and technical specifications from source code and configuration\",\n \"url\": \"https://example.com/agents/documentation\",\n \"version\": \"1.6.3\",\n \"provider\": \"Doc Systems\",\n \"path\": \"/documentation\",\n \"tags\": \"documentation,code-generation,api-docs,knowledge-management\",\n \"is_enabled\": true,\n \"num_stars\": 31,\n \"license\": \"MIT\",\n \"visibility\": \"public\",\n \"trust_level\": \"community\",\n \"streaming\": false,\n \"security_schemes\": {\n \"basic_auth\": {\n \"type\": \"http\",\n \"scheme\": \"basic\"\n },\n \"api_token\": {\n \"type\": \"apiKey\",\n \"name\": \"Authorization\",\n \"in\": \"header\"\n }\n },\n \"security\": [\n {\n \"basic_auth\": []\n },\n {\n \"api_token\": []\n }\n ],\n \"skills\": [\n {\n \"id\": \"generate_api_docs\",\n \"name\": \"Generate API Documentation\",\n \"description\": \"Auto-generate comprehensive API documentation from source code and API specifications\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"code_path\": {\n \"type\": \"string\",\n \"description\": \"Path to source code or API definition\"\n },\n \"doc_format\": {\n \"type\": \"string\",\n \"enum\": [\n \"openapi\",\n \"postman\",\n \"markdown\",\n \"html\"\n ],\n \"description\": \"Documentation format\"\n },\n \"include_examples\": {\n \"type\": \"boolean\",\n \"description\": \"Include code examples\"\n }\n },\n \"required\": [\n \"code_path\",\n \"doc_format\"\n ]\n },\n \"tags\": [\n \"documentation\",\n \"api-generation\"\n ]\n },\n {\n \"id\": \"extract_docstrings\",\n \"name\": \"Extract and Format Docstrings\",\n \"description\": \"Extract docstrings from source code and format them into documentation\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"source_files\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Source files to extract docstrings from\"\n },\n \"docstring_style\": {\n \"type\": \"string\",\n \"enum\": [\n \"google\",\n \"numpy\",\n \"sphinx\",\n \"rest\"\n ],\n \"description\": \"Docstring style to parse\"\n },\n \"output_format\": {\n \"type\": \"string\",\n \"enum\": [\n \"markdown\",\n \"rst\",\n \"html\"\n ],\n \"description\": \"Output documentation format\"\n }\n },\n \"required\": [\n \"source_files\"\n ]\n },\n \"tags\": [\n \"extraction\",\n \"formatting\"\n ]\n },\n {\n \"id\": \"generate_readme\",\n \"name\": \"Generate README\",\n \"description\": \"Generate project README with installation, usage, and contribution guidelines\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"project_info\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"version\": {\n \"type\": \"string\"\n }\n },\n \"description\": \"Project metadata\"\n },\n \"sections\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"installation\",\n \"usage\",\n \"contributing\",\n \"license\",\n \"changelog\"\n ]\n },\n \"description\": \"README sections to include\"\n }\n },\n \"required\": [\n \"project_info\"\n ]\n },\n \"tags\": [\n \"readme\",\n \"project-info\"\n ]\n },\n {\n \"id\": \"maintain_docs\",\n \"name\": \"Maintain Documentation\",\n \"description\": \"Keep documentation in sync with code changes and updates\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"source_path\": {\n \"type\": \"string\",\n \"description\": \"Path to source code\"\n },\n \"docs_path\": {\n \"type\": \"string\",\n \"description\": \"Path to documentation\"\n },\n \"auto_update\": {\n \"type\": \"boolean\",\n \"description\": \"Automatically update outdated sections\"\n }\n },\n \"required\": [\n \"source_path\",\n \"docs_path\"\n ]\n },\n \"tags\": [\n \"maintenance\",\n \"synchronization\"\n ]\n },\n {\n \"id\": \"generate_changelog\",\n \"name\": \"Generate Changelog\",\n \"description\": \"Generate changelog from commit history or release notes\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"git_repo_path\": {\n \"type\": \"string\",\n \"description\": \"Path to git repository\"\n },\n \"from_version\": {\n \"type\": \"string\",\n \"description\": \"Starting version tag\"\n },\n \"to_version\": {\n \"type\": \"string\",\n \"description\": \"Ending version tag\"\n },\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\n \"keep-a-changelog\",\n \"conventional\",\n \"markdown\"\n ],\n \"description\": \"Changelog format\"\n }\n },\n \"required\": [\n \"git_repo_path\"\n ]\n },\n \"tags\": [\n \"changelog\",\n \"versioning\"\n ]\n }\n ],\n \"metadata\": {\n \"supported_languages\": [\n \"python\",\n \"javascript\",\n \"java\",\n \"go\",\n \"rust\",\n \"csharp\",\n \"typescript\"\n ],\n \"documentation_formats\": [\n \"markdown\",\n \"html\",\n \"pdf\",\n \"postman\",\n \"openapi\"\n ],\n \"average_generation_time_seconds\": 45,\n \"max_project_size_mb\": 500\n }\n}\n" }, { "path": "cli/examples/federation-config-agentcore-example.json", "content": "{\n\"anthropic\": {\n \"enabled\": true,\n \"endpoint\": \"https://registry.modelcontextprotocol.io\",\n \"sync_on_startup\": true,\n \"servers\": [\n {\"name\": \"com.hydrata/hydrata-mcp-server\"},\n {\"name\": \"io.github.OneNicolas/mcp-service-public\"},\n {\"name\": \"ai.exa/exa\"}\n ]\n },\n \"asor\": {\n \"enabled\": false,\n \"endpoint\": \"\",\n \"auth_env_var\": \"ASOR_ACCESS_TOKEN\",\n \"sync_on_startup\": false,\n \"agents\": []\n },\n \"aws_registry\": {\n \"enabled\": true,\n \"sync_on_startup\": true,\n \"sync_interval_minutes\": 60,\n \"sync_timeout_seconds\": 300,\n \"max_concurrent_fetches\": 5,\n \"registries\": [\n {\n \"registry_id\": \"arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rCu9kFIgrbNOpEsF\",\n \"aws_account_id\": \"123456789012\",\n \"aws_region\": \"us-east-1\",\n \"descriptor_types\": [\"MCP\", \"A2A\", \"CUSTOM\", \"AGENT_SKILLS\"],\n \"sync_status_filter\": \"APPROVED\"\n }\n ]\n }\n}\n" }, { "path": "cli/examples/federation-config-example.json", "content": "{\n \"anthropic\": {\n \"enabled\": true,\n \"endpoint\": \"https://registry.modelcontextprotocol.io\",\n \"sync_on_startup\": true,\n \"servers\": [\n {\"name\": \"com.hydrata/hydrata-mcp-server\"},\n {\"name\": \"io.github.OneNicolas/mcp-service-public\"},\n {\"name\": \"ai.exa/exa\"}\n ]\n },\n \"asor\": {\n \"enabled\": false,\n \"endpoint\": \"https://your-asor-endpoint.example.com/api/asor/v1/your-tenant\",\n \"auth_env_var\": \"ASOR_ACCESS_TOKEN\",\n \"sync_on_startup\": false,\n \"agents\": [\n {\"id\": \"agent_1\"},\n {\"id\": \"agent_2\"}\n ]\n }\n}\n" }, { "path": "cli/examples/flight_booking_agent_card.json", "content": "{\n \"protocolVersion\": \"0.3.0\",\n \"supportedProtocol\": \"a2a\",\n \"name\": \"Flight Booking Agent\",\n \"description\": \"Flight booking and reservation management agent\",\n \"url\": \"http://flight-booking-agent:9000/\",\n \"version\": \"0.0.1\",\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\"text/plain\", \"application/json\"],\n \"defaultOutputModes\": [\"text/plain\", \"application/json\"],\n \"provider\": {\n \"organization\": \"Example Corp\",\n \"url\": \"https://example-corp.com\"\n },\n \"status\": \"active\",\n \"skills\": [\n {\n \"id\": \"check_availability\",\n \"name\": \"Check Availability\",\n \"description\": \"Check seat availability for a specific flight.\",\n \"tags\": [\"flight\", \"availability\", \"booking\"]\n },\n {\n \"id\": \"reserve_flight\",\n \"name\": \"Reserve Flight\",\n \"description\": \"Reserve seats on a flight for passengers.\",\n \"tags\": [\"flight\", \"reservation\", \"booking\"]\n },\n {\n \"id\": \"confirm_booking\",\n \"name\": \"Confirm Booking\",\n \"description\": \"Confirm and finalize a flight booking.\",\n \"tags\": [\"flight\", \"confirmation\", \"booking\"]\n },\n {\n \"id\": \"process_payment\",\n \"name\": \"Process Payment\",\n \"description\": \"Process payment for a booking (simulated).\",\n \"tags\": [\"payment\", \"processing\", \"booking\"]\n },\n {\n \"id\": \"manage_reservation\",\n \"name\": \"Manage Reservation\",\n \"description\": \"Update, view, or cancel existing reservations.\",\n \"tags\": [\"reservation\", \"management\", \"booking\"]\n }\n ],\n \"tags\": [\"travel\", \"flight-booking\", \"reservation\"],\n \"visibility\": \"public\",\n \"license\": \"MIT\",\n \"path\": \"/flight-booking\"\n}\n" }, { "path": "cli/examples/flight_booking_agent_ecs.json", "content": "{\n \"protocolVersion\": \"0.3.0\",\n \"name\": \"Flight Booking Agent\",\n \"description\": \"Flight booking and reservation management agent\",\n \"url\": \"http://flight-booking-agent.mcp-gateway-v2.local:9000\",\n \"version\": \"0.0.1\",\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\"text/plain\", \"application/json\"],\n \"defaultOutputModes\": [\"text/plain\", \"application/json\"],\n \"provider\": {\n \"organization\": \"MCP Gateway\",\n \"url\": \"https://github.com/agentic-community/mcp-gateway-registry\"\n },\n \"skills\": [\n {\n \"id\": \"check_availability\",\n \"name\": \"Check Availability\",\n \"description\": \"Check seat availability for a specific flight.\",\n \"tags\": [\"flight\", \"availability\", \"booking\"]\n },\n {\n \"id\": \"reserve_flight\",\n \"name\": \"Reserve Flight\",\n \"description\": \"Reserve seats on a flight for passengers.\",\n \"tags\": [\"flight\", \"reservation\", \"booking\"]\n },\n {\n \"id\": \"confirm_booking\",\n \"name\": \"Confirm Booking\",\n \"description\": \"Confirm and finalize a flight booking.\",\n \"tags\": [\"flight\", \"confirmation\", \"booking\"]\n },\n {\n \"id\": \"process_payment\",\n \"name\": \"Process Payment\",\n \"description\": \"Process payment for a booking (simulated).\",\n \"tags\": [\"payment\", \"processing\", \"booking\"]\n },\n {\n \"id\": \"manage_reservation\",\n \"name\": \"Manage Reservation\",\n \"description\": \"Update, view, or cancel existing reservations.\",\n \"tags\": [\"reservation\", \"management\", \"booking\"]\n }\n ],\n \"tags\": [\"travel\", \"flight-booking\", \"reservation\"],\n \"visibility\": \"public\",\n \"license\": \"MIT\",\n \"path\": \"/flight-booking-agent\"\n}\n" }, { "path": "cli/examples/geospatial_route_planner_agent.json", "content": "{\n \"protocolVersion\": \"0.2.9\",\n \"name\": \"GeoSpatial Route Planner Agent\",\n \"description\": \"Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.\",\n \"url\": \"https://georoute-agent.example.com/a2a/v1\",\n \"preferredTransport\": \"JSONRPC\",\n \"additionalInterfaces\" : [\n {\"url\": \"https://georoute-agent.example.com/a2a/v1\", \"transport\": \"JSONRPC\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/grpc\", \"transport\": \"GRPC\"},\n {\"url\": \"https://georoute-agent.example.com/a2a/json\", \"transport\": \"HTTP+JSON\"}\n ],\n \"provider\": {\n \"organization\": \"Example Geo Services Inc.\",\n \"url\": \"https://www.examplegeoservices.com\"\n },\n \"iconUrl\": \"https://georoute-agent.example.com/icon.png\",\n \"version\": \"1.2.0\",\n \"documentationUrl\": \"https://docs.examplegeoservices.com/georoute-agent/api\",\n \"capabilities\": {\n \"streaming\": true,\n \"pushNotifications\": true,\n \"stateTransitionHistory\": false\n },\n \"securitySchemes\": {\n \"google\": {\n \"type\": \"openIdConnect\",\n \"openIdConnectUrl\": \"https://accounts.google.com/.well-known/openid-configuration\"\n }\n },\n \"security\": [{ \"google\": [\"openid\", \"profile\", \"email\"] }],\n \"defaultInputModes\": [\"application/json\", \"text/plain\"],\n \"defaultOutputModes\": [\"application/json\", \"image/png\"],\n \"skills\": [\n {\n \"id\": \"route-optimizer-traffic\",\n \"name\": \"Traffic-Aware Route Optimizer\",\n \"description\": \"Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).\",\n \"tags\": [\"maps\", \"routing\", \"navigation\", \"directions\", \"traffic\"],\n \"examples\": [\n \"Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.\",\n \"{\\\"origin\\\": {\\\"lat\\\": 37.422, \\\"lng\\\": -122.084}, \\\"destination\\\": {\\\"lat\\\": 37.7749, \\\"lng\\\": -122.4194}, \\\"preferences\\\": [\\\"avoid_ferries\\\"]}\"\n ],\n \"inputModes\": [\"application/json\", \"text/plain\"],\n \"outputModes\": [\n \"application/json\",\n \"application/vnd.geo+json\",\n \"text/html\"\n ]\n },\n {\n \"id\": \"custom-map-generator\",\n \"name\": \"Personalized Map Generator\",\n \"description\": \"Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.\",\n \"tags\": [\"maps\", \"customization\", \"visualization\", \"cartography\"],\n \"examples\": [\n \"Generate a map of my upcoming road trip with all planned stops highlighted.\",\n \"Show me a map visualizing all coffee shops within a 1-mile radius of my current location.\"\n ],\n \"inputModes\": [\"application/json\"],\n \"outputModes\": [\n \"image/png\",\n \"image/jpeg\",\n \"application/json\",\n \"text/html\"\n ]\n }\n ],\n \"supportsAuthenticatedExtendedCard\": true,\n \"signatures\": [\n {\n \"protected\": \"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0\",\n \"signature\": \"QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ\"\n }\n ]\n}" }, { "path": "cli/examples/invalid-config.json", "content": "{\n \"server_name\": \"Invalid Server\",\n \"description\": \"Missing required fields\",\n \"proxy_pass_url\": \"not-a-valid-url\"\n}" }, { "path": "cli/examples/jewel_homes_support_agent_card.json", "content": "{\n \"name\": \"Jewel Homes Support Agent\",\n \"description\": \"AI customer support agent for Jewel Homes: answers questions about products and services, looks up orders, and resolves issues\",\n \"url\": \"https://support-c17fedfd-13da-4026-87f5-d3c78b3f6f95.helpagent.club/a2a\",\n \"preferredTransport\": \"JSONRPC\",\n \"protocolVersion\": \"0.3.0\",\n \"version\": \"1.0.0\",\n \"capabilities\": {\n \"streaming\": false\n },\n \"defaultInputModes\": [\n \"text/plain\"\n ],\n \"defaultOutputModes\": [\n \"text/plain\"\n ],\n \"skills\": [\n {\n \"id\": \"answer-questions\",\n \"name\": \"Answer Questions\",\n \"description\": \"Answer customer questions about products and services\",\n \"tags\": [\"customer-support\", \"faq\", \"product-info\", \"guidance\"]\n },\n {\n \"id\": \"order-lookup\",\n \"name\": \"Order Lookup\",\n \"description\": \"Look up order status and details\",\n \"tags\": [\"orders\", \"order-status\"]\n }\n ],\n \"tags\": [\"customer-support\", \"faq\", \"order-status\", \"a2a\", \"ans-verified\"],\n \"path\": \"/jewel-homes-support-agent\",\n \"status\": \"active\",\n \"provider\": {\n \"organization\": \"GoDaddy\",\n \"url\": \"https://godaddy.com\"\n },\n \"visibility\": \"public\",\n \"ans_agent_id\": \"ans://v1.0.0.support-c17fedfd-13da-4026-87f5-d3c78b3f6f95.helpagent.club\"\n}\n" }, { "path": "cli/examples/minimal-server-config.json", "content": "{\n \"server_name\": \"Minimal MCP Server\",\n \"description\": \"A minimal server configuration with only required fields\",\n \"path\": \"/minimal-server\",\n \"proxy_pass_url\": \"http://minimal-server:9001/\",\n \"supported_transports\": [\"streamable-http\"],\n \"tags\": [\"mcp\", \"minimal\", \"example\"]\n}" }, { "path": "cli/examples/peer-registry-lob-1.json.example", "content": "{\n \"peer_id\": \"peer-registry-lob-1\",\n \"name\": \"LOB-1 Peer Registry\",\n \"endpoint\": \"https://mcpregistry.ddns.net\",\n \"enabled\": true,\n \"sync_mode\": \"all\",\n \"sync_interval_minutes\": 60,\n \"federation_token\": \"your-actual-token-here\"\n\n}\n" }, { "path": "cli/examples/public-mcp-users.json", "content": "{\n \"scope_name\": \"public-mcp-users\",\n \"description\": \"Users with access to public MCP servers (context7, cloudflare-docs) and flight-booking agent\",\n \"server_access\": [\n {\n \"server\": \"context7\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"/context7\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"/context7/\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"cloudflare-docs\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"/cloudflare-docs\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"/cloudflare-docs/\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\", \"resources/list\", \"resources/templates/list\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"initialize\", \"GET\", \"POST\", \"servers\", \"agents\", \"search\", \"rating\", \"tools\", \"tokens\"],\n \"tools\": []\n },\n {\n \"server\": \"v0.1\",\n \"methods\": [\"agents\", \"GET\", \"POST\"],\n \"tools\": []\n },\n {\n \"agents\": {\n \"actions\": [\n {\n \"action\": \"list_agents\",\n \"resources\": [\"/flight-booking\"]\n },\n {\n \"action\": \"get_agent\",\n \"resources\": [\"/flight-booking\"]\n }\n ]\n }\n }\n ],\n \"group_mappings\": [\"public-mcp-users\", \"5f605d68-06bc-4208-b992-bb378eee12c5\"],\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n },\n \"create_in_idp\": true\n}\n" }, { "path": "cli/examples/realserverfaketools.json", "content": "{\n \"server_name\": \"Real Server Fake Tools\",\n \"description\": \"A collection of fake tools with interesting names that take different parameter types\",\n \"path\": \"/realserverfaketools/\",\n \"proxy_pass_url\": \"http://realserverfaketools-server:8002/\", \n \"supported_transports\": [\"streamable-http\"],\n \"auth_scheme\": \"none\",\n \"tags\": [\"demo\", \"fake\", \"tools\", \"testing\"],\n \"num_tools\": 6,\n \"license\": \"MIT\",\n \"tool_list\": [\n {\n \"name\": \"quantum_flux_analyzer\",\n \"parsed_description\": {\n \"main\": \"Analyzes quantum flux patterns with configurable energy levels and stabilization.\",\n \"args\": \"energy_level: Energy level for quantum analysis (1-10), stabilization_factor: Stabilization factor for quantum flux, enable_temporal_shift: Whether to enable temporal shifting in the analysis\",\n \"returns\": \"str: JSON response with mock quantum flux analysis results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"energy_level\": {\n \"default\": 5,\n \"description\": \"Energy level for quantum analysis (1-10)\",\n \"maximum\": 10,\n \"minimum\": 1,\n \"title\": \"Energy Level\",\n \"type\": \"integer\"\n },\n \"stabilization_factor\": {\n \"default\": 0.75,\n \"description\": \"Stabilization factor for quantum flux\",\n \"title\": \"Stabilization Factor\",\n \"type\": \"number\"\n },\n \"enable_temporal_shift\": {\n \"default\": false,\n \"description\": \"Whether to enable temporal shifting in the analysis\",\n \"title\": \"Enable Temporal Shift\",\n \"type\": \"boolean\"\n }\n },\n \"title\": \"quantum_flux_analyzerArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"neural_pattern_synthesizer\",\n \"parsed_description\": {\n \"main\": \"Synthesizes neural patterns into coherent structures.\",\n \"args\": \"input_patterns: List of neural patterns to synthesize, coherence_threshold: Threshold for pattern coherence (0.0-1.0), dimensions: Number of dimensions for synthesis (1-10)\",\n \"returns\": \"Dict[str, Any]: Dictionary with mock neural pattern synthesis results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"input_patterns\": {\n \"description\": \"List of neural patterns to synthesize\",\n \"items\": {\n \"type\": \"string\"\n },\n \"title\": \"Input Patterns\",\n \"type\": \"array\"\n },\n \"coherence_threshold\": {\n \"default\": 0.7,\n \"description\": \"Threshold for pattern coherence (0.0-1.0)\",\n \"maximum\": 1.0,\n \"minimum\": 0.0,\n \"title\": \"Coherence Threshold\",\n \"type\": \"number\"\n },\n \"dimensions\": {\n \"default\": 3,\n \"description\": \"Number of dimensions for synthesis (1-10)\",\n \"maximum\": 10,\n \"minimum\": 1,\n \"title\": \"Dimensions\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"input_patterns\"\n ],\n \"title\": \"neural_pattern_synthesizerArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"hyper_dimensional_mapper\",\n \"parsed_description\": {\n \"main\": \"Maps geographical coordinates to hyper-dimensional space.\",\n \"args\": \"coordinates: Geographical coordinates to map, dimension_count: Number of hyper-dimensions to map to (4-11), reality_anchoring: Reality anchoring factor (0.1-1.0)\",\n \"returns\": \"str: JSON response with mock hyper-dimensional mapping results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"$defs\": {\n \"GeoCoordinates\": {\n \"properties\": {\n \"latitude\": {\n \"description\": \"Latitude coordinate\",\n \"title\": \"Latitude\",\n \"type\": \"number\"\n },\n \"longitude\": {\n \"description\": \"Longitude coordinate\",\n \"title\": \"Longitude\",\n \"type\": \"number\"\n },\n \"altitude\": {\n \"description\": \"Altitude in meters (optional)\",\n \"title\": \"Altitude\",\n \"type\": [\"number\", \"null\"]\n }\n },\n \"required\": [\n \"latitude\",\n \"longitude\"\n ],\n \"title\": \"GeoCoordinates\",\n \"type\": \"object\"\n }\n },\n \"properties\": {\n \"coordinates\": {\n \"$ref\": \"#/$defs/GeoCoordinates\",\n \"description\": \"Geographical coordinates to map to hyper-dimensions\"\n },\n \"dimension_count\": {\n \"default\": 5,\n \"description\": \"Number of hyper-dimensions to map to (4-11)\",\n \"maximum\": 11,\n \"minimum\": 4,\n \"title\": \"Dimension Count\",\n \"type\": \"integer\"\n },\n \"reality_anchoring\": {\n \"default\": 0.8,\n \"description\": \"Reality anchoring factor (0.1-1.0)\",\n \"maximum\": 1.0,\n \"minimum\": 0.1,\n \"title\": \"Reality Anchoring\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"coordinates\"\n ],\n \"title\": \"hyper_dimensional_mapperArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"temporal_anomaly_detector\",\n \"parsed_description\": {\n \"main\": \"Detects temporal anomalies within a specified timeframe.\",\n \"args\": \"timeframe: Dictionary with 'start' and 'end' times for anomaly detection, sensitivity: Sensitivity level for detection (1-10), anomaly_types: Types of anomalies to detect\",\n \"returns\": \"Dict[str, Any]: Dictionary with mock temporal anomaly detection results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"timeframe\": {\n \"description\": \"Start and end times for anomaly detection\",\n \"properties\": {\n \"start\": {\n \"type\": \"string\"\n },\n \"end\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\"start\", \"end\"],\n \"title\": \"Timeframe\",\n \"type\": \"object\"\n },\n \"sensitivity\": {\n \"default\": 7,\n \"description\": \"Sensitivity level for detection (1-10)\",\n \"maximum\": 10,\n \"minimum\": 1,\n \"title\": \"Sensitivity\",\n \"type\": \"integer\"\n },\n \"anomaly_types\": {\n \"default\": [\"temporal_shift\", \"causal_loop\", \"timeline_divergence\"],\n \"description\": \"Types of anomalies to detect\",\n \"items\": {\n \"type\": \"string\"\n },\n \"title\": \"Anomaly Types\",\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"timeframe\"\n ],\n \"title\": \"temporal_anomaly_detectorArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"user_profile_analyzer\",\n \"parsed_description\": {\n \"main\": \"Analyzes a user profile with configurable analysis options.\",\n \"args\": \"profile: User profile to analyze, analysis_options: Options for the analysis\",\n \"returns\": \"str: JSON response with mock user profile analysis results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"$defs\": {\n \"UserProfile\": {\n \"properties\": {\n \"username\": {\n \"description\": \"User's username\",\n \"title\": \"Username\",\n \"type\": \"string\"\n },\n \"email\": {\n \"description\": \"User's email address\",\n \"title\": \"Email\",\n \"type\": \"string\"\n },\n \"age\": {\n \"description\": \"User's age (optional)\",\n \"title\": \"Age\",\n \"type\": [\"integer\", \"null\"]\n },\n \"interests\": {\n \"default\": [],\n \"description\": \"List of user interests\",\n \"items\": {\n \"type\": \"string\"\n },\n \"title\": \"Interests\",\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"username\",\n \"email\"\n ],\n \"title\": \"UserProfile\",\n \"type\": \"object\"\n },\n \"AnalysisOptions\": {\n \"properties\": {\n \"depth\": {\n \"default\": 3,\n \"description\": \"Depth of analysis (1-10)\",\n \"title\": \"Depth\",\n \"type\": \"integer\"\n },\n \"include_metadata\": {\n \"default\": true,\n \"description\": \"Whether to include metadata\",\n \"title\": \"Include Metadata\",\n \"type\": \"boolean\"\n },\n \"filters\": {\n \"default\": {},\n \"description\": \"Filters to apply\",\n \"title\": \"Filters\",\n \"type\": \"object\"\n }\n },\n \"title\": \"AnalysisOptions\",\n \"type\": \"object\"\n }\n },\n \"properties\": {\n \"profile\": {\n \"$ref\": \"#/$defs/UserProfile\",\n \"description\": \"User profile to analyze\"\n },\n \"analysis_options\": {\n \"$ref\": \"#/$defs/AnalysisOptions\",\n \"default\": {},\n \"description\": \"Options for the analysis\"\n }\n },\n \"required\": [\n \"profile\"\n ],\n \"title\": \"user_profile_analyzerArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"synthetic_data_generator\",\n \"parsed_description\": {\n \"main\": \"Generates synthetic data based on a provided schema.\",\n \"args\": \"schema: Schema defining the structure of synthetic data, record_count: Number of synthetic records to generate (1-1000), seed: Random seed for reproducibility (optional)\",\n \"returns\": \"Dict[str, Any]: Dictionary with mock synthetic data generation results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"schema\": {\n \"description\": \"Schema defining the structure of synthetic data\",\n \"title\": \"Schema\",\n \"type\": \"object\"\n },\n \"record_count\": {\n \"default\": 10,\n \"description\": \"Number of synthetic records to generate (1-1000)\",\n \"maximum\": 1000,\n \"minimum\": 1,\n \"title\": \"Record Count\",\n \"type\": \"integer\"\n },\n \"seed\": {\n \"description\": \"Random seed for reproducibility (optional)\",\n \"title\": \"Seed\",\n \"type\": [\"integer\", \"null\"]\n }\n },\n \"required\": [\n \"schema\"\n ],\n \"title\": \"synthetic_data_generatorArguments\",\n \"type\": \"object\"\n }\n }\n ]\n}" }, { "path": "cli/examples/security_analyzer_agent.json", "content": "{\n \"protocol_version\": \"1.0\",\n \"name\": \"Security Analyzer Agent\",\n \"description\": \"Comprehensive security analysis agent for vulnerability detection, penetration testing, and compliance checking. Identifies security risks and recommends mitigations\",\n \"url\": \"https://example.com/agents/security-analyzer\",\n \"version\": \"2.5.0\",\n \"provider\": \"CyberSec Corp\",\n \"path\": \"/security-analyzer\",\n \"tags\": \"security,vulnerability-detection,compliance,penetration-testing\",\n \"is_enabled\": true,\n \"num_stars\": 72,\n \"license\": \"MIT\",\n \"visibility\": \"public\",\n \"trust_level\": \"trusted\",\n \"streaming\": true,\n \"security_schemes\": {\n \"mutual_tls\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\",\n \"bearer_format\": \"X.509\"\n },\n \"api_key_secure\": {\n \"type\": \"apiKey\",\n \"name\": \"X-API-Key\",\n \"in\": \"header\"\n }\n },\n \"security\": [\n {\n \"mutual_tls\": []\n },\n {\n \"api_key_secure\": []\n }\n ],\n \"skills\": [\n {\n \"id\": \"scan_vulnerabilities\",\n \"name\": \"Scan for Vulnerabilities\",\n \"description\": \"Scan code and dependencies for known vulnerabilities\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"code_path\": {\n \"type\": \"string\",\n \"description\": \"Path to source code or project directory\"\n },\n \"severity_threshold\": {\n \"type\": \"string\",\n \"enum\": [\n \"critical\",\n \"high\",\n \"medium\",\n \"low\"\n ],\n \"description\": \"Minimum severity to report\"\n },\n \"include_dependencies\": {\n \"type\": \"boolean\",\n \"description\": \"Also scan dependencies and third-party libraries\"\n }\n },\n \"required\": [\n \"code_path\"\n ]\n },\n \"tags\": [\n \"scanning\",\n \"vulnerability-detection\"\n ]\n },\n {\n \"id\": \"check_compliance\",\n \"name\": \"Check Compliance\",\n \"description\": \"Check compliance with security standards and regulations\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"artifact\": {\n \"type\": \"string\",\n \"description\": \"Code, configuration, or artifact to check\"\n },\n \"standards\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"owasp-top-10\",\n \"cis\",\n \"pci-dss\",\n \"hipaa\",\n \"gdpr\",\n \"iso27001\"\n ]\n },\n \"description\": \"Standards to check against\"\n }\n },\n \"required\": [\n \"artifact\",\n \"standards\"\n ]\n },\n \"tags\": [\n \"compliance\",\n \"standards\"\n ]\n },\n {\n \"id\": \"analyze_authentication\",\n \"name\": \"Analyze Authentication\",\n \"description\": \"Analyze authentication mechanisms and identify weaknesses\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"auth_config\": {\n \"type\": \"object\",\n \"description\": \"Authentication configuration to analyze\"\n },\n \"check_types\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"password_policy\",\n \"mfa\",\n \"session_management\",\n \"token_expiry\"\n ]\n },\n \"description\": \"Authentication aspects to check\"\n }\n },\n \"required\": [\n \"auth_config\"\n ]\n },\n \"tags\": [\n \"authentication\",\n \"access-control\"\n ]\n },\n {\n \"id\": \"penetration_test\",\n \"name\": \"Penetration Testing\",\n \"description\": \"Perform authorized penetration testing to identify exploitable vulnerabilities\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"target_url\": {\n \"type\": \"string\",\n \"description\": \"URL or endpoint to test\"\n },\n \"test_scope\": {\n \"type\": \"string\",\n \"enum\": [\n \"basic\",\n \"standard\",\n \"comprehensive\"\n ],\n \"description\": \"Scope of penetration testing\"\n },\n \"attack_vectors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"sql_injection\",\n \"xss\",\n \"csrf\",\n \"rce\",\n \"privilege_escalation\"\n ]\n },\n \"description\": \"Specific attack vectors to test\"\n }\n },\n \"required\": [\n \"target_url\"\n ]\n },\n \"tags\": [\n \"penetration-testing\",\n \"exploitation\"\n ]\n },\n {\n \"id\": \"generate_security_report\",\n \"name\": \"Generate Security Report\",\n \"description\": \"Generate detailed security assessment report with recommendations\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"findings\": {\n \"type\": \"array\",\n \"description\": \"Security findings and issues\"\n },\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\n \"html\",\n \"pdf\",\n \"json\"\n ],\n \"description\": \"Report format\"\n },\n \"include_remediations\": {\n \"type\": \"boolean\",\n \"description\": \"Include remediation steps\"\n }\n },\n \"required\": [\n \"findings\",\n \"format\"\n ]\n },\n \"tags\": [\n \"reporting\",\n \"recommendations\"\n ]\n }\n ],\n \"metadata\": {\n \"cves_checked\": 185000,\n \"supported_languages\": [\n \"python\",\n \"javascript\",\n \"java\",\n \"go\",\n \"rust\",\n \"csharp\"\n ],\n \"compliance_frameworks\": [\n \"owasp\",\n \"cis\",\n \"pci-dss\",\n \"hipaa\",\n \"gdpr\"\n ],\n \"reporting_templates\": 12,\n \"updates_frequency\": \"daily\"\n }\n}\n" }, { "path": "cli/examples/server-config.json", "content": "{\n \"server_name\": \"Example MCP Server\",\n \"description\": \"An example MCP server configuration for the CLI tool\",\n \"path\": \"/example-server\",\n \"proxy_pass_url\": \"http://example-server:9000/\",\n \"tags\": [\"example\", \"demo\", \"test\"],\n \"num_tools\": 3,\n \"license\": \"MIT\"\n}" }, { "path": "cli/examples/test-peer-config.json", "content": "{\n \"peer_id\": \"test-peer-registry-1\",\n \"name\": \"Test Peer Registry 1\",\n \"endpoint\": \"https://peer1.registry.example.com\",\n \"enabled\": true,\n \"sync_mode\": \"all\",\n \"whitelist_servers\": [],\n \"whitelist_agents\": [],\n \"tag_filter\": [],\n \"federation_token\": \"YOUR_FEDERATION_TOKEN_HERE\"\n}\n" }, { "path": "cli/examples/test-timing-server.json", "content": "{\n \"server_name\": \"Test Timing Server\",\n \"description\": \"Test server to verify timing optimizations\",\n \"path\": \"/test-timing-123\",\n \"proxy_pass_url\": \"https://example.com/mcp\",\n \"supported_transports\": [\"streamable-http\"],\n \"auth_scheme\": \"none\",\n \"tags\": [\"test\", \"timing\"]\n}\n" }, { "path": "cli/examples/test_automation_agent.json", "content": "{\n \"protocol_version\": \"1.0\",\n \"name\": \"Test Automation Agent\",\n \"description\": \"Intelligent test automation agent that generates, executes, and manages test cases. Supports unit tests, integration tests, and end-to-end test scenarios\",\n \"url\": \"https://example.com/agents/test-automation\",\n \"version\": \"1.8.2\",\n \"provider\": \"Quality Assurance Labs\",\n \"path\": \"/test-automation\",\n \"tags\": \"testing,automation,qa,test-generation\",\n \"is_enabled\": true,\n \"num_stars\": 38,\n \"license\": \"Apache-2.0\",\n \"visibility\": \"public\",\n \"trust_level\": \"community\",\n \"streaming\": true,\n \"security_schemes\": {\n \"api_key\": {\n \"type\": \"apiKey\",\n \"name\": \"X-API-Key\",\n \"in\": \"header\"\n },\n \"oauth2\": {\n \"type\": \"oauth2\",\n \"flows\": {\n \"clientCredentials\": {\n \"tokenUrl\": \"https://auth.example.com/oauth/token\",\n \"scopes\": {\n \"test:read\": \"Read test results\",\n \"test:write\": \"Create and modify tests\"\n }\n }\n }\n }\n },\n \"security\": [\n {\n \"api_key\": []\n },\n {\n \"oauth2\": [\n \"test:read\",\n \"test:write\"\n ]\n }\n ],\n \"skills\": [\n {\n \"id\": \"generate_unit_tests\",\n \"name\": \"Generate Unit Tests\",\n \"description\": \"Generate comprehensive unit test cases from source code\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"source_code\": {\n \"type\": \"string\",\n \"description\": \"Source code to generate tests for\"\n },\n \"framework\": {\n \"type\": \"string\",\n \"enum\": [\n \"pytest\",\n \"unittest\",\n \"jest\",\n \"junit\"\n ],\n \"description\": \"Testing framework to use\"\n },\n \"coverage_target\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 100,\n \"description\": \"Target code coverage percentage\"\n }\n },\n \"required\": [\n \"source_code\",\n \"framework\"\n ]\n },\n \"tags\": [\n \"generation\",\n \"unit-testing\"\n ]\n },\n {\n \"id\": \"execute_tests\",\n \"name\": \"Execute Tests\",\n \"description\": \"Execute test suite and return results with detailed metrics\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"test_suite_path\": {\n \"type\": \"string\",\n \"description\": \"Path to test suite directory or file\"\n },\n \"parallel_execution\": {\n \"type\": \"boolean\",\n \"description\": \"Execute tests in parallel\"\n },\n \"timeout_seconds\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": \"Timeout per test in seconds\"\n }\n },\n \"required\": [\n \"test_suite_path\"\n ]\n },\n \"tags\": [\n \"execution\",\n \"reporting\"\n ]\n },\n {\n \"id\": \"analyze_test_coverage\",\n \"name\": \"Analyze Test Coverage\",\n \"description\": \"Analyze test coverage and identify untested code paths\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"source_path\": {\n \"type\": \"string\",\n \"description\": \"Path to source code directory\"\n },\n \"exclude_patterns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Glob patterns to exclude from coverage\"\n }\n },\n \"required\": [\n \"source_path\"\n ]\n },\n \"tags\": [\n \"analysis\",\n \"coverage\"\n ]\n },\n {\n \"id\": \"generate_test_report\",\n \"name\": \"Generate Test Report\",\n \"description\": \"Generate comprehensive test report with visualizations and metrics\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"test_results\": {\n \"type\": \"object\",\n \"description\": \"Test execution results\"\n },\n \"format\": {\n \"type\": \"string\",\n \"enum\": [\n \"html\",\n \"pdf\",\n \"json\",\n \"markdown\"\n ],\n \"description\": \"Report format\"\n }\n },\n \"required\": [\n \"test_results\",\n \"format\"\n ]\n },\n \"tags\": [\n \"reporting\",\n \"documentation\"\n ]\n }\n ],\n \"metadata\": {\n \"frameworks_supported\": [\n \"pytest\",\n \"unittest\",\n \"jest\",\n \"mocha\",\n \"rspec\"\n ],\n \"languages_supported\": [\n \"python\",\n \"javascript\",\n \"java\",\n \"ruby\",\n \"go\"\n ],\n \"concurrent_tests\": 8,\n \"test_history_days\": 90\n }\n}\n" }, { "path": "cli/examples/test_code_reviewer_agent.json", "content": "{\n \"name\": \"Test Code Reviewer Agent\",\n \"path\": \"/test-reviewer\",\n \"description\": \"A test A2A agent for code review and quality analysis\",\n \"url\": \"https://example.com/agents/test-reviewer\",\n \"version\": \"1.0.0\",\n \"visibility\": \"public\",\n \"trust_level\": \"community\",\n \"tags\": \"test,code-review,quality-analysis\",\n \"security_schemes\": {\n \"bearer\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\"\n }\n },\n \"protocol_version\": \"1.0\"\n}\n" }, { "path": "cli/examples/tourist_guide_agent_card.json", "content": "{\n \"name\": \"AI Tourist Guide\",\n \"description\": \"AI tourist guide - destination + duration + interests to day-by-day itinerary\",\n \"url\": \"https://tourist-guide.agentworks.fr/a2a\",\n \"preferredTransport\": \"STREAMABLE-HTTP\",\n \"protocolVersion\": \"0.3.0\",\n \"version\": \"2.0.0\",\n \"capabilities\": {\n \"streaming\": false,\n \"pushNotifications\": false\n },\n \"defaultInputModes\": [\"text/plain\", \"application/json\"],\n \"defaultOutputModes\": [\"application/json\"],\n \"skills\": [\n {\n \"id\": \"touristguide\",\n \"name\": \"AI Tourist Guide\",\n \"description\": \"AI tourist guide - destination + duration + interests to day-by-day itinerary\",\n \"tags\": [\"tourism\", \"travel\", \"itinerary\"]\n }\n ],\n \"provider\": {\n \"organization\": \"MARAMEO\",\n \"url\": \"https://marameo.tv\"\n },\n \"tags\": [\"tourism\", \"travel\", \"itinerary\", \"a2a\", \"ans-verified\"],\n \"ans_agent_id\": \"ans://v1.0.0.tourist-guide.agentworks.fr\"\n}\n" }, { "path": "cli/examples/travel_assistant_agent_card.json", "content": "{\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\n \"text\"\n ],\n \"defaultOutputModes\": [\n \"text\"\n ],\n \"description\": \"Flight search and trip planning agent\",\n \"name\": \"Travel Assistant Agent\",\n \"preferredTransport\": \"JSONRPC\",\n \"protocolVersion\": \"0.3.0\",\n \"skills\": [\n {\n \"description\": \"Search for available flights between cities on a specific date.\",\n \"id\": \"search_flights\",\n \"name\": \"search_flights\",\n \"tags\": []\n },\n {\n \"description\": \"Get pricing and seat availability for a specific flight.\",\n \"id\": \"check_prices\",\n \"name\": \"check_prices\",\n \"tags\": []\n },\n {\n \"description\": \"Get flight recommendations based on customer preferences.\",\n \"id\": \"get_recommendations\",\n \"name\": \"get_recommendations\",\n \"tags\": []\n },\n {\n \"description\": \"Create and save a trip planning record.\",\n \"id\": \"create_trip_plan\",\n \"name\": \"create_trip_plan\",\n \"tags\": []\n }\n ],\n \"url\": \"http://travel-assistant-agent:9000/\",\n \"version\": \"0.0.1\",\n \"tags\": [\"travel\", \"flight-search\", \"trip-planning\", \"booking\"],\n \"path\": \"/travel-assistant-agent\",\n \"status\": \"active\",\n \"provider\": {\n \"organization\": \"Travel Solutions Inc.\",\n \"url\": \"https://travel-solutions.example.com\"\n },\n \"visibility\": \"public\"\n}\n" }, { "path": "cli/examples/travel_assistant_agent_ecs.json", "content": "{\n \"protocolVersion\": \"0.3.0\",\n \"name\": \"Travel Assistant Agent\",\n \"description\": \"Intelligent travel planning and assistance agent\",\n \"url\": \"http://travel-assistant-agent.mcp-gateway-v2.local:9000\",\n \"version\": \"0.0.1\",\n \"capabilities\": {\n \"streaming\": true\n },\n \"defaultInputModes\": [\"text/plain\", \"application/json\"],\n \"defaultOutputModes\": [\"text/plain\", \"application/json\"],\n \"provider\": {\n \"organization\": \"MCP Gateway\",\n \"url\": \"https://github.com/agentic-community/mcp-gateway-registry\"\n },\n \"skills\": [\n {\n \"id\": \"plan_trip\",\n \"name\": \"Plan Trip\",\n \"description\": \"Plan a complete trip including flights, hotels, and activities.\",\n \"tags\": [\"travel\", \"planning\", \"itinerary\"]\n },\n {\n \"id\": \"find_destinations\",\n \"name\": \"Find Destinations\",\n \"description\": \"Discover travel destinations based on preferences and budget.\",\n \"tags\": [\"travel\", \"destinations\", \"recommendations\"]\n },\n {\n \"id\": \"get_recommendations\",\n \"name\": \"Get Recommendations\",\n \"description\": \"Get personalized travel recommendations and tips.\",\n \"tags\": [\"travel\", \"recommendations\", \"advice\"]\n },\n {\n \"id\": \"manage_itinerary\",\n \"name\": \"Manage Itinerary\",\n \"description\": \"Create, update, and manage travel itineraries.\",\n \"tags\": [\"travel\", \"itinerary\", \"management\"]\n },\n {\n \"id\": \"coordinate_bookings\",\n \"name\": \"Coordinate Bookings\",\n \"description\": \"Coordinate flight bookings and other travel services.\",\n \"tags\": [\"travel\", \"coordination\", \"booking\"]\n }\n ],\n \"tags\": [\"travel\", \"assistant\", \"planning\"],\n \"visibility\": \"public\",\n \"license\": \"MIT\",\n \"path\": \"/travel-assistant-agent\"\n}\n" }, { "path": "cli/examples/virtual-server-combined-example.json", "content": "{\n \"path\": \"/virtual/combined-tools\",\n \"server_name\": \"Combined Context7 and CurrentTime Tools\",\n \"description\": \"Virtual server aggregating documentation search tools from Context7 and timezone tools from CurrentTime server\",\n \"tool_mappings\": [\n {\n \"tool_name\": \"resolve-library-id\",\n \"backend_server_path\": \"/context7\"\n },\n {\n \"tool_name\": \"query-docs\",\n \"backend_server_path\": \"/context7\"\n },\n {\n \"tool_name\": \"current_time_by_timezone\",\n \"alias\": \"get-current-time\",\n \"backend_server_path\": \"/currenttime/\"\n }\n ],\n \"required_scopes\": [],\n \"tool_scope_overrides\": [],\n \"tags\": [\n \"documentation\",\n \"time\",\n \"timezone\",\n \"libraries\",\n \"combined\"\n ],\n \"supported_transports\": [\n \"streamable-http\"\n ],\n \"is_enabled\": true\n}\n" }, { "path": "cli/examples/virtual-server-scoped-example.json", "content": "{\n \"path\": \"/virtual/scoped-tools\",\n \"server_name\": \"Scoped Documentation and Time Tools\",\n \"description\": \"Virtual server with scope-based access control combining cloudflare-docs and currenttime tools\",\n \"tool_mappings\": [\n {\n \"tool_name\": \"search_cloudflare_documentation\",\n \"backend_server_path\": \"/cloudflare-docs\"\n },\n {\n \"tool_name\": \"current_time_by_timezone\",\n \"alias\": \"get-time\",\n \"backend_server_path\": \"/currenttime/\"\n }\n ],\n \"required_scopes\": [\n \"virtual-scoped-tools/access\"\n ],\n \"tool_scope_overrides\": [\n {\n \"tool_alias\": \"get-time\",\n \"required_scopes\": [\"virtual-scoped-tools/time-access\"]\n }\n ],\n \"tags\": [\n \"documentation\",\n \"cloudflare\",\n \"time\",\n \"scoped\",\n \"access-control\"\n ],\n \"supported_transports\": [\n \"streamable-http\"\n ],\n \"is_enabled\": true\n}\n" }, { "path": "cli/examples/virtual-server-scoped-users.json", "content": "{\n \"scope_name\": \"virtual-scoped-tools-users\",\n \"description\": \"Users with access to the scoped virtual server combining cloudflare-docs and currenttime tools\",\n \"server_access\": [\n {\n \"server\": \"/virtual/scoped-tools\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"GET\", \"POST\", \"servers\", \"virtual-servers\", \"search\"],\n \"tools\": []\n }\n ],\n \"group_mappings\": [\"virtual-scoped-tools-users\"],\n \"custom_scopes\": [\"virtual-scoped-tools/access\"],\n \"create_in_idp\": true\n}\n" }, { "path": "cli/examples/working_agent.json", "content": "{\n \"protocol_version\": \"1.0\",\n \"name\": \"Flight Booking Agent\",\n \"description\": \"Flight booking and reservation management agent\",\n \"url\": \"http://flight-booking-agent:9000/\",\n \"version\": \"0.0.1\",\n \"capabilities\": {},\n \"default_input_modes\": [\n \"text/plain\"\n ],\n \"default_output_modes\": [\n \"text/plain\"\n ],\n \"skills\": [\n {\n \"id\": \"check_availability\",\n \"name\": \"Check Availability\",\n \"description\": \"Check seat availability for a specific flight.\",\n \"tags\": [],\n \"examples\": null,\n \"input_modes\": null,\n \"output_modes\": null,\n \"security\": null\n },\n {\n \"id\": \"reserve_flight\",\n \"name\": \"Reserve Flight\",\n \"description\": \"Reserve seats on a flight for passengers.\",\n \"tags\": [],\n \"examples\": null,\n \"input_modes\": null,\n \"output_modes\": null,\n \"security\": null\n },\n {\n \"id\": \"confirm_booking\",\n \"name\": \"Confirm Booking\",\n \"description\": \"Confirm and finalize a flight booking.\",\n \"tags\": [],\n \"examples\": null,\n \"input_modes\": null,\n \"output_modes\": null,\n \"security\": null\n },\n {\n \"id\": \"process_payment\",\n \"name\": \"Process Payment\",\n \"description\": \"Process payment for a booking (simulated).\",\n \"tags\": [],\n \"examples\": null,\n \"input_modes\": null,\n \"output_modes\": null,\n \"security\": null\n },\n {\n \"id\": \"manage_reservation\",\n \"name\": \"Manage Reservation\",\n \"description\": \"Update, view, or cancel existing reservations.\",\n \"tags\": [],\n \"examples\": null,\n \"input_modes\": null,\n \"output_modes\": null,\n \"security\": null\n }\n ],\n \"preferred_transport\": \"JSONRPC\",\n \"provider\": {\n \"organization\": \"Example Corp\",\n \"url\": \"https://example-corp.com\"\n },\n \"icon_url\": null,\n \"documentation_url\": null,\n \"security_schemes\": {},\n \"security\": null,\n \"supports_authenticated_extended_card\": null,\n \"metadata\": {},\n \"path\": \"/flight-booking\",\n \"tags\": [\n \"travel\",\n \"flight-booking\",\n \"reservation\"\n ],\n \"is_enabled\": false,\n \"num_stars\": 0,\n \"license\": \"MIT\",\n \"registered_at\": \"2025-11-19T13:43:19.354979+00:00\",\n \"updated_at\": \"2025-11-19T13:43:19.355018+00:00\",\n \"registered_by\": \"service-account-registry-admin-bot\",\n \"visibility\": \"public\",\n \"allowed_groups\": [],\n \"signature\": null,\n \"trust_level\": \"unverified\"\n}" }, { "path": "cli/get_user_token.py", "content": "#!/usr/bin/env python3\n\"\"\"\nCLI tool to authenticate users and obtain access tokens for programmatic API access.\n\nThis script implements the OAuth2 Device Code Flow, which allows users to authenticate\nby visiting a URL and entering a code, without needing to expose their credentials\nto the CLI application.\n\nUsage:\n # Authenticate and save token to file\n uv run python cli/get_user_token.py --output .token\n\n # Authenticate with custom output file\n uv run python cli/get_user_token.py --output my-token.json\n\n # Show token on stdout (don't save)\n uv run python cli/get_user_token.py --stdout\n\nEnvironment Variables:\n ENTRA_TENANT_ID: Azure AD tenant ID\n ENTRA_CLIENT_ID: App registration client ID\n ENTRA_CLIENT_SECRET: App registration client secret (optional for public clients)\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nimport time\nfrom datetime import datetime\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Default Entra ID login base URL\nDEFAULT_ENTRA_LOGIN_BASE_URL = \"https://login.microsoftonline.com\"\n\n\ndef _get_env_or_error(name: str, default: str | None = None) -> str:\n \"\"\"Get environment variable or raise error if not set.\n\n Args:\n name: Environment variable name\n default: Default value if not set\n\n Returns:\n Environment variable value\n\n Raises:\n ValueError: If variable not set and no default\n \"\"\"\n value = os.environ.get(name, default)\n if not value:\n raise ValueError(f\"Environment variable {name} is required\")\n return value\n\n\ndef _initiate_device_code_flow(tenant_id: str, client_id: str, scope: str | None = None) -> dict:\n \"\"\"Initiate device code flow.\n\n Args:\n tenant_id: Azure AD tenant ID\n client_id: App registration client ID\n scope: OAuth scopes to request\n\n Returns:\n Device code response from Entra ID\n \"\"\"\n import requests\n\n login_base_url = os.environ.get(\"ENTRA_LOGIN_BASE_URL\", DEFAULT_ENTRA_LOGIN_BASE_URL)\n\n device_code_url = f\"{login_base_url}/{tenant_id}/oauth2/v2.0/devicecode\"\n\n if not scope:\n scope = f\"api://{client_id}/user_impersonation openid profile email\"\n\n data = {\"client_id\": client_id, \"scope\": scope}\n\n response = requests.post(device_code_url, data=data, timeout=10)\n\n if response.status_code != 200:\n error_data = response.json()\n error_desc = error_data.get(\"error_description\", error_data.get(\"error\", \"Unknown error\"))\n logger.error(f\"Device code request failed: {error_desc}\")\n raise ValueError(f\"Device code flow not available: {error_desc}\")\n\n return response.json()\n\n\ndef _poll_for_token(\n tenant_id: str, client_id: str, device_code: str, interval: int = 5, timeout: int = 300\n) -> dict:\n \"\"\"Poll for token after user completes authentication.\n\n Args:\n tenant_id: Azure AD tenant ID\n client_id: App registration client ID\n device_code: Device code from initiation\n interval: Polling interval in seconds\n timeout: Maximum wait time in seconds\n\n Returns:\n Token response from Entra ID\n \"\"\"\n import requests\n\n login_base_url = os.environ.get(\"ENTRA_LOGIN_BASE_URL\", DEFAULT_ENTRA_LOGIN_BASE_URL)\n\n token_url = f\"{login_base_url}/{tenant_id}/oauth2/v2.0/token\"\n\n data = {\n \"grant_type\": \"urn:ietf:params:oauth:grant-type:device_code\",\n \"client_id\": client_id,\n \"device_code\": device_code,\n }\n\n start_time = time.time()\n\n while (time.time() - start_time) < timeout:\n response = requests.post(token_url, data=data, timeout=10)\n\n if response.status_code == 200:\n return response.json()\n\n error_data = response.json()\n error = error_data.get(\"error\", \"\")\n\n if error == \"authorization_pending\":\n sys.stdout.write(\".\")\n sys.stdout.flush()\n time.sleep(interval)\n continue\n elif error == \"slow_down\":\n interval += 5\n time.sleep(interval)\n continue\n elif error == \"expired_token\":\n raise ValueError(\"Device code expired. Please try again.\")\n elif error == \"access_denied\":\n raise ValueError(\"Authorization was denied.\")\n else:\n error_desc = error_data.get(\"error_description\", error)\n raise ValueError(f\"Token request failed: {error_desc}\")\n\n raise ValueError(\"Authentication timed out. Please try again.\")\n\n\ndef _save_token(token_data: dict, output_path: str) -> None:\n \"\"\"Save token data to file.\n\n Args:\n token_data: Token response from Entra ID\n output_path: Path to save token file\n \"\"\"\n # Add metadata\n token_data[\"obtained_at\"] = datetime.utcnow().isoformat()\n\n with open(output_path, \"w\") as f:\n json.dump(token_data, f, indent=2)\n\n # Set restrictive permissions\n os.chmod(output_path, 0o600)\n\n logger.info(f\"Token saved to {output_path}\")\n\n\ndef _extract_access_token(token_data: dict) -> str:\n \"\"\"Extract just the access token from response.\n\n Args:\n token_data: Full token response\n\n Returns:\n Access token string\n \"\"\"\n return token_data.get(\"access_token\", \"\")\n\n\ndef main() -> int:\n \"\"\"Main entry point.\n\n Returns:\n Exit code (0 for success)\n \"\"\"\n parser = argparse.ArgumentParser(\n description=\"Authenticate with Entra ID and obtain an access token for API access\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Authenticate and save token to .token file\n uv run python cli/get_user_token.py --output .token\n\n # Authenticate and print token to stdout\n uv run python cli/get_user_token.py --stdout\n\n # Use the token with registry_management.py\n uv run python api/registry_management.py --token-file .token --registry-url http://localhost list\n\nEnvironment Variables:\n ENTRA_TENANT_ID Azure AD tenant ID (required)\n ENTRA_CLIENT_ID App registration client ID (required)\n ENTRA_LOGIN_BASE_URL Login URL (default: https://login.microsoftonline.com)\n\"\"\",\n )\n\n parser.add_argument(\n \"--output\",\n \"-o\",\n type=str,\n help=\"Path to save the token file (default: .token)\",\n default=\".token\",\n )\n\n parser.add_argument(\n \"--stdout\", action=\"store_true\", help=\"Print token to stdout instead of saving to file\"\n )\n\n parser.add_argument(\n \"--full\",\n action=\"store_true\",\n help=\"Output full token response (with refresh token, expiry, etc.)\",\n )\n\n parser.add_argument(\n \"--scope\",\n type=str,\n help=\"OAuth scopes to request (default: user_impersonation openid profile email)\",\n )\n\n parser.add_argument(\n \"--timeout\", type=int, default=300, help=\"Authentication timeout in seconds (default: 300)\"\n )\n\n args = parser.parse_args()\n\n try:\n # Get configuration from environment\n tenant_id = _get_env_or_error(\"ENTRA_TENANT_ID\")\n client_id = _get_env_or_error(\"ENTRA_CLIENT_ID\")\n\n logger.info(\"Starting device code authentication flow\")\n logger.info(f\"Tenant ID: {tenant_id}\")\n logger.info(f\"Client ID: {client_id}\")\n\n # Initiate device code flow\n device_code_response = _initiate_device_code_flow(\n tenant_id=tenant_id, client_id=client_id, scope=args.scope\n )\n\n # Display instructions to user\n print(\"\\n\" + \"=\" * 60)\n print(\"AUTHENTICATION REQUIRED\")\n print(\"=\" * 60)\n print(f\"\\n{device_code_response.get('message', '')}\\n\")\n print(f\" URL: {device_code_response.get('verification_uri', '')}\")\n print(f\" Code: {device_code_response.get('user_code', '')}\")\n print(\"\\n\" + \"=\" * 60)\n print(\"\\nWaiting for authentication\", end=\"\")\n\n # Poll for token\n token_data = _poll_for_token(\n tenant_id=tenant_id,\n client_id=client_id,\n device_code=device_code_response[\"device_code\"],\n interval=device_code_response.get(\"interval\", 5),\n timeout=args.timeout,\n )\n\n print(\"\\n\\nAuthentication successful!\")\n\n # Output token\n if args.stdout:\n if args.full:\n print(json.dumps(token_data, indent=2))\n else:\n print(token_data[\"access_token\"])\n else:\n if args.full:\n _save_token(token_data, args.output)\n else:\n # Save just the access token for compatibility with CLI tools\n with open(args.output, \"w\") as f:\n f.write(token_data[\"access_token\"])\n os.chmod(args.output, 0o600)\n logger.info(f\"Access token saved to {args.output}\")\n\n print(f\"\\nToken saved to: {args.output}\")\n print(f\"Token expires in: {token_data.get('expires_in', 'unknown')} seconds\")\n print(\"\\nUsage:\")\n print(\n f\" uv run python api/registry_management.py --token-file {args.output} --registry-url http://localhost list\"\n )\n\n return 0\n\n except ValueError as e:\n logger.error(f\"Authentication failed: {e}\")\n print(f\"\\nError: {e}\", file=sys.stderr)\n return 1\n except Exception as e:\n logger.exception(f\"Unexpected error: {e}\")\n print(f\"\\nUnexpected error: {e}\", file=sys.stderr)\n return 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "cli/import_from_anthropic_registry.sh", "content": "#!/bin/bash\n#\n# Import MCP servers from Anthropic Registry\n#\n# This script fetches server definitions from the Anthropic MCP Registry\n# and registers them with the local MCP Gateway Registry.\n#\n# Usage:\n# ./import_from_anthropic_registry.sh [--dry-run] [--import-list ] [--analyzers ]\n#\n# Environment Variables:\n# GATEWAY_URL - Gateway URL (default: http://localhost)\n# Example: export GATEWAY_URL=https://mcpgateway.ddns.net\n# MCP_SCANNER_LLM_API_KEY - API key for LLM-based security analysis (required if using llm analyzer)\n#\n\nset -e\n\n# Get the directory where this script is located\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nPROJECT_ROOT=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Load environment variables from .env file if it exists\nif [ -f \"$PROJECT_ROOT/.env\" ]; then\n set -a # Automatically export all variables\n source \"$PROJECT_ROOT/.env\"\n set +a # Turn off automatic export\nfi\n\n# Configuration\nANTHROPIC_API_BASE=\"https://registry.modelcontextprotocol.io\"\nTEMP_DIR=\"$PROJECT_ROOT/.tmp/anthropic-import\"\nBASE_PORT=8100\n\n# Read API version from constants.py\nANTHROPIC_API_VERSION=$(python3 -c \"\nimport sys\nsys.path.insert(0, '$PROJECT_ROOT')\nfrom registry.constants import REGISTRY_CONSTANTS\nprint(REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION)\n\")\n\n# Gateway URL (can be overridden with GATEWAY_URL environment variable)\nGATEWAY_URL=\"${GATEWAY_URL:-http://localhost}\"\n\n# Colors for terminal output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nBLUE='\\033[0;34m'\nNC='\\033[0m'\n\n# Output formatting functions (minimal emoji use per coding standards)\nprint_success() { echo -e \"${GREEN}[SUCCESS] $1${NC}\"; }\nprint_error() { echo -e \"${RED}[ERROR] $1${NC}\"; }\nprint_info() { echo -e \"${BLUE}[INFO] $1${NC}\"; }\n\n# Generate deployment instructions for a server\ndetect_transport() {\n local anthropic_json=\"$1\"\n # Most MCP servers from Anthropic registry use stdio transport\n # Only a few support HTTP/SSE\n echo \"stdio\"\n}\n\nvalidate_package() {\n local package_type=\"$1\"\n local package_name=\"$2\"\n \n if [ -z \"$package_name\" ] || [ \"$package_name\" = \"null\" ]; then\n return 1\n fi\n \n case \"$package_type\" in\n \"npm\")\n # Check if NPM package exists (simplified check)\n return 0\n ;;\n \"pypi\")\n # Check if PyPI package exists (simplified check)\n return 0\n ;;\n *)\n return 1\n ;;\n esac\n}\n\n# Parse arguments\nDRY_RUN=false\nIMPORT_LIST=\"$SCRIPT_DIR/import_server_list.txt\"\nANALYZERS=\"yara\"\n\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --dry-run) DRY_RUN=true; shift ;;\n --import-list) IMPORT_LIST=\"$2\"; shift 2 ;;\n --analyzers) ANALYZERS=\"$2\"; shift 2 ;;\n --help)\n echo \"Usage: $0 [--dry-run] [--import-list ] [--analyzers ]\"\n echo \"\"\n echo \"Options:\"\n echo \" --dry-run Dry run mode (don't register servers)\"\n echo \" --import-list Server list file (default: import_server_list.txt)\"\n echo \" --analyzers Security analyzers: yara, llm, or yara,llm (default: yara)\"\n echo \"\"\n echo \"Environment Variables:\"\n echo \" GATEWAY_URL - Gateway URL (default: http://localhost)\"\n echo \" Example: export GATEWAY_URL=https://mcpgateway.ddns.net\"\n echo \" MCP_SCANNER_LLM_API_KEY - API key for LLM analyzer (required if using llm)\"\n echo \"\"\n echo \"Examples:\"\n echo \" # Import with default YARA analyzer\"\n echo \" $0\"\n echo \"\"\n echo \" # Import with both YARA and LLM analyzers\"\n echo \" export MCP_SCANNER_LLM_API_KEY=sk-...\"\n echo \" $0 --analyzers yara,llm\"\n echo \"\"\n echo \" # Import with only LLM analyzer\"\n echo \" export MCP_SCANNER_LLM_API_KEY=sk-...\"\n echo \" $0 --analyzers llm\"\n exit 0 ;;\n *) echo \"Unknown option: $1\"; exit 1 ;;\n esac\ndone\n\n# Check prerequisites\ncommand -v jq >/dev/null || { print_error \"jq required\"; exit 1; }\ncommand -v curl >/dev/null || { print_error \"curl required\"; exit 1; }\n[ -f \"$IMPORT_LIST\" ] || { print_error \"Import list not found: $IMPORT_LIST\"; exit 1; }\n\n# Check if LLM analyzer is requested and API key is available\nif [[ \"$ANALYZERS\" == *\"llm\"* ]]; then\n if [ -z \"$MCP_SCANNER_LLM_API_KEY\" ] || [[ \"$MCP_SCANNER_LLM_API_KEY\" == *\"your_\"* ]] || [[ \"$MCP_SCANNER_LLM_API_KEY\" == *\"placeholder\"* ]]; then\n echo \"\"\n print_error \"LLM analyzer requested but MCP_SCANNER_LLM_API_KEY is not configured\"\n print_info \"Current value: ${MCP_SCANNER_LLM_API_KEY:-}\"\n print_info \"\"\n print_info \"Options:\"\n print_info \" 1. Add real API key to .env file: MCP_SCANNER_LLM_API_KEY=sk-...\"\n print_info \" 2. Set environment variable: export MCP_SCANNER_LLM_API_KEY=sk-...\"\n print_info \" 3. Use only YARA analyzer: $0 --analyzers yara\"\n exit 1\n fi\nfi\n\nmkdir -p \"$TEMP_DIR\"\n\n# Read server list\nservers=()\nwhile IFS= read -r line; do\n [[ \"$line\" =~ ^[[:space:]]*# ]] && continue\n [[ -z \"${line// }\" ]] && continue\n servers+=(\"$(echo \"$line\" | xargs)\")\ndone < \"$IMPORT_LIST\"\n\nprint_info \"Found ${#servers[@]} servers to import\"\nprint_info \"Security analyzers: $ANALYZERS\"\n\n# Process each server\nsuccess_count=0\ncurrent_port=$BASE_PORT\n\nfor server_name in \"${servers[@]}\"; do\n print_info \"Processing: $server_name\"\n\n # Fetch from Anthropic API (URL encode server name)\n # API version is dynamically read from registry/constants.py\n encoded_name=$(echo \"$server_name\" | sed 's|/|%2F|g')\n api_url=\"${ANTHROPIC_API_BASE}/${ANTHROPIC_API_VERSION}/servers/${encoded_name}/versions/latest\"\n safe_name=$(echo \"$server_name\" | sed 's|/|-|g')\n anthropic_file=\"${TEMP_DIR}/${safe_name}-anthropic.json\"\n\n if ! curl -s -f \"$api_url\" > \"$anthropic_file\"; then\n print_error \"Failed to fetch $server_name\"\n continue\n fi\n\n # Transform to registry format\n config_file=\"${TEMP_DIR}/${safe_name}-config.json\"\n anthropic_json=$(cat \"$anthropic_file\")\n \n # Extract from nested server object\n description=$(echo \"$anthropic_json\" | jq -r '.server.description // \"Imported from Anthropic MCP Registry\"')\n version=$(echo \"$anthropic_json\" | jq -r '.server.version // \"latest\"')\n repo_url=$(echo \"$anthropic_json\" | jq -r '.server.repository.url // \"\"')\n \n # Detect transport type from packages or remotes\n transport_type=\"stdio\"\n if echo \"$anthropic_json\" | jq -e '.server.packages[]? | .transport.type' > /dev/null 2>&1; then\n transport_type=$(echo \"$anthropic_json\" | jq -r '.server.packages[]? | .transport.type' | head -1)\n elif echo \"$anthropic_json\" | jq -e '.server.remotes[]? | .type' > /dev/null 2>&1; then\n transport_type=$(echo \"$anthropic_json\" | jq -r '.server.remotes[]? | .type' | head -1)\n fi\n \n # Generate tags from server name\n IFS='/' read -ra name_parts <<< \"$server_name\"\n server_basename=\"${name_parts[${#name_parts[@]}-1]}\"\n IFS='-' read -ra tag_parts <<< \"$server_basename\"\n tags_json=$(printf '%s\\n' \"${tag_parts[@]}\" \"anthropic-registry\" | jq -R . | jq -s .)\n \n # Generate safe path and proxy URL\n safe_path=$(echo \"$server_name\" | sed 's|/|-|g')\n \n # For imported servers, use a placeholder URL since they're not deployed yet\n proxy_url=\"http://localhost:${current_port}/\"\n \n # Use Python transformer for complete transformation\n python3 -c \"\nimport json\nimport sys\n\nsys.path.append('$SCRIPT_DIR')\nfrom anthropic_transformer import transform_anthropic_to_gateway\n\n# Load Anthropic server data\nwith open('$anthropic_file') as f:\n data = json.load(f)\n\n# Transform to Gateway Registry format\nresult = transform_anthropic_to_gateway(data, $current_port)\nresult['path'] = '/$safe_path'\n\n# Remove unsupported fields for register_service tool\n# The user-facing register_service tool only supports basic fields\n# Note: auth_scheme, auth_provider, headers, supported_transports, and tool_list are kept\nunsupported_fields = [\n 'repository_url', 'website_url', 'package_npm', 'remote_url'\n]\nfor field in unsupported_fields:\n result.pop(field, None)\n\n# Write transformed configuration\nwith open('$config_file', 'w') as f:\n json.dump(result, f, indent=2)\n\"\n \n print_success \"Created config for $server_name (transport: $transport_type)\"\n \n # Register with service_mgmt.sh (if not dry run)\n if [ \"$DRY_RUN\" = false ]; then\n if GATEWAY_URL=\"$GATEWAY_URL\" \"$SCRIPT_DIR/service_mgmt.sh\" add \"$config_file\" \"$ANALYZERS\"; then\n print_success \"Registered $server_name\"\n success_count=$((success_count + 1))\n else\n print_error \"Failed to register $server_name\"\n fi\n else\n print_info \"[DRY RUN] Would register $server_name with analyzers: $ANALYZERS\"\n success_count=$((success_count + 1))\n fi\n \n current_port=$((current_port + 1))\ndone\n\n\nprint_info \"Import completed: $success_count/${#servers[@]} successful\"\nprint_info \"Configuration files saved to: $TEMP_DIR\"" }, { "path": "cli/import_server_list.txt", "content": "# MCP Servers to Import from Anthropic Registry\n# One server name per line, comments start with #\n#\n# Curated list of popular streamable-http servers\n# Auto-selected based on popularity, development utility, and reliability\n# Last updated: 2025-10-14\n\n# GitHub API access - file operations, repository management, search\nai.smithery/smithery-ai-github\n\n# GitHub-hosted Obsidian vault integration for AI assistants\nai.smithery/Hint-Services-obsidian-github-mcp\n\n# Web search and article text extraction for LLMs\nio.github.jgador/websharp\n\n# Google Forms management - create surveys and collect data\nai.smithery/data-mindset-sts-google-forms-mcp\n\n# Automated GitHub PR and issue analysis\nai.smithery/saidsef-mcp-github-pr-issue-analyser\n\n# Search-only commerce MCP server backed by Stripe (test)\nai.shawndurrani/mcp-merchant\n\n" }, { "path": "cli/mcp_client.py", "content": "#!/usr/bin/env python3\n\"\"\"\nSimple MCP Client using shared MCP utilities\n\nThis client uses the shared mcp_utils module which provides a standardized\nMCP client implementation using only standard Python libraries. This approach\navoids dependency issues with the fastmcp library in some environments.\n\"\"\"\n\nimport argparse\nimport base64\nimport json\nimport os\nimport sys\nfrom datetime import UTC, datetime\n\n# Import shared MCP utility\nfrom mcp_utils import create_mcp_session\n\n\ndef _check_token_expiration(access_token: str) -> None:\n \"\"\"\n Check if JWT token is expired and exit with informative message if so.\n\n Args:\n access_token: JWT access token to check\n\n Exits:\n If token is expired or will expire soon\n \"\"\"\n try:\n # Decode JWT payload (without verification, just to check expiry)\n parts = access_token.split(\".\")\n if len(parts) != 3:\n print(\"Warning: Invalid JWT format, cannot check expiration\")\n return\n\n # Decode payload\n payload = parts[1]\n # Add padding if needed\n padding = len(payload) % 4\n if padding:\n payload += \"=\" * (4 - padding)\n\n decoded = base64.urlsafe_b64decode(payload)\n token_data = json.loads(decoded)\n\n # Check expiration\n exp = token_data.get(\"exp\")\n if not exp:\n print(\"Warning: Token does not have expiration field\")\n return\n\n exp_dt = datetime.fromtimestamp(exp, tz=UTC)\n now = datetime.now(UTC)\n time_until_expiry = exp_dt - now\n\n if time_until_expiry.total_seconds() < 0:\n # Token is expired\n print(\"=\" * 80)\n print(\"TOKEN EXPIRED\")\n print(\"=\" * 80)\n print(f\"Token expired at: {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n print(f\"Current time is: {now.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n print(f\"Token expired {abs(time_until_expiry.total_seconds()):.0f} seconds ago\")\n print(\"\")\n print(\"Please regenerate your token using one of these methods:\")\n print(\"\")\n print(\" 1. For LOB bot agents (recommended):\")\n print(\" ./keycloak/setup/generate-agent-token.sh lob1-bot\")\n print(\" ./keycloak/setup/generate-agent-token.sh lob2-bot\")\n print(\"\")\n print(\" 2. Use token file (for Cognito/OAuth):\")\n print(\" --token-file /path/to/your/.token_file\")\n print(\"\")\n print(\" 3. Use M2M authentication:\")\n print(\" Set environment variables: CLIENT_ID, CLIENT_SECRET,\")\n print(\" KEYCLOAK_URL, KEYCLOAK_REALM\")\n print(\"=\" * 80)\n sys.exit(1)\n elif time_until_expiry.total_seconds() < 60:\n # Token expires soon\n print(\n f\"Warning: Token will expire in {int(time_until_expiry.total_seconds())} seconds at {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}\"\n )\n else:\n print(\n f\"Token is valid until {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')} ({int(time_until_expiry.total_seconds())} seconds remaining)\"\n )\n\n except Exception as e:\n print(f\"Warning: Could not check token expiration: {e}\")\n\n\ndef _load_token_from_file(file_path: str) -> str | None:\n \"\"\"Load access token from a file\n\n Supports multiple formats:\n 1. Plain JWT token (single line)\n 2. JSON object with 'access_token' field (from agent token generation)\n 3. JSON object with 'tokens.access_token' field (from UI \"Get JWT Token\")\n 4. JSON object with 'token_data.access_token' field (alternative UI format)\n \"\"\"\n try:\n with open(file_path) as f:\n content = f.read().strip()\n if not content:\n return None\n\n # Try to parse as JSON first (for agent token files)\n try:\n token_data = json.loads(content)\n if isinstance(token_data, dict):\n # Format 1: {\"access_token\": \"...\"}\n if \"access_token\" in token_data:\n return token_data[\"access_token\"]\n # Format 2: {\"tokens\": {\"access_token\": \"...\"}} (from UI)\n if \"tokens\" in token_data and isinstance(token_data[\"tokens\"], dict):\n if \"access_token\" in token_data[\"tokens\"]:\n return token_data[\"tokens\"][\"access_token\"]\n # Format 3: {\"token_data\": {\"access_token\": \"...\"}}\n if \"token_data\" in token_data and isinstance(token_data[\"token_data\"], dict):\n if \"access_token\" in token_data[\"token_data\"]:\n return token_data[\"token_data\"][\"access_token\"]\n except json.JSONDecodeError:\n # Not JSON, treat as plain token string\n pass\n\n # Return as-is (plain JWT token)\n return content if content else None\n except FileNotFoundError:\n print(f\"Warning: Token file not found: {file_path}\")\n except Exception as e:\n print(f\"Warning: Failed to read token file {file_path}: {e}\")\n return None\n\n\ndef _load_m2m_credentials() -> str | None:\n \"\"\"Load M2M credentials and get access token from Keycloak\"\"\"\n client_id = os.getenv(\"CLIENT_ID\")\n client_secret = os.getenv(\"CLIENT_SECRET\")\n keycloak_url = os.getenv(\"KEYCLOAK_URL\")\n keycloak_realm = os.getenv(\"KEYCLOAK_REALM\")\n\n if not all([client_id, client_secret, keycloak_url, keycloak_realm]):\n return None\n\n # Import requests only when needed for M2M authentication\n try:\n import requests\n except ImportError:\n print(\"Warning: requests library not available for M2M authentication\")\n return None\n\n # Get access token from Keycloak\n token_url = f\"{keycloak_url}/realms/{keycloak_realm}/protocol/openid-connect/token\"\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"scope\": \"openid\",\n }\n\n try:\n response = requests.post(token_url, data=data, timeout=30)\n response.raise_for_status()\n token_data = response.json()\n return token_data.get(\"access_token\")\n except Exception as e:\n print(f\"Failed to get M2M token: {e}\")\n return None\n\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Simple MCP Client - Communicate with MCP Gateway using JSON-RPC\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Test connectivity\n uv run mcp_client.py ping\n\n # List available tools\n uv run mcp_client.py list\n\n # Find tools using natural language\n uv run mcp_client.py call --tool intelligent_tool_finder --args '{\"natural_language_query\":\"get current time in New York\"}'\n\n # Call any tool with arguments (specify correct server URL)\n uv run mcp_client.py --url http://localhost/currenttime/mcp call --tool current_time_by_timezone --args '{\"tz_name\":\"America/New_York\"}'\n\n # Use different gateway URL\n uv run mcp_client.py --url http://localhost/currenttime/mcp ping\n\n # Use token from file (e.g., for Cognito/OAuth servers)\n uv run mcp_client.py --url http://localhost/customer-support-assistant/mcp --token-file /path/to/.cognito_access_token list\n\nAuthentication (priority order):\n 1. --token-file: Path to file containing access token\n 2. OAUTH_TOKEN environment variable: Direct JWT token\n 3. Environment variables: CLIENT_ID, CLIENT_SECRET, KEYCLOAK_URL, KEYCLOAK_REALM\n 4. Ingress token: Automatically loaded from ~/.mcp/ingress_token if available\n \"\"\",\n )\n parser.add_argument(\n \"--url\", default=\"http://localhost/mcpgw/mcp\", help=\"Gateway URL (default: %(default)s)\"\n )\n parser.add_argument(\n \"--token-file\", help=\"Path to file containing access token (e.g., .cognito_access_token)\"\n )\n parser.add_argument(\n \"command\", choices=[\"ping\", \"list\", \"call\", \"init\"], help=\"Command to execute\"\n )\n parser.add_argument(\"--tool\", help=\"Tool name for call command\")\n parser.add_argument(\"--args\", help=\"Tool arguments as JSON string\")\n\n args = parser.parse_args()\n\n # Load authentication (priority: token-file > OAUTH_TOKEN env var > M2M > ingress token)\n access_token = None\n\n # Try loading from file first if specified\n if args.token_file:\n access_token = _load_token_from_file(args.token_file)\n\n # Fall back to OAUTH_TOKEN environment variable if no token file or file loading failed\n if not access_token:\n access_token = os.getenv(\"OAUTH_TOKEN\")\n\n # Fall back to M2M credentials if no OAUTH_TOKEN\n if not access_token:\n access_token = _load_m2m_credentials()\n\n # Check token expiration before making any API calls\n if access_token:\n _check_token_expiration(access_token)\n\n # Create MCP session using shared utility (it will auto-load ingress token if needed)\n try:\n with create_mcp_session(args.url, access_token) as client:\n # Check what authentication was actually used\n if client.access_token:\n if args.token_file:\n print(f\"✓ Token file authentication successful ({args.token_file})\")\n elif os.getenv(\"OAUTH_TOKEN\"):\n print(\"✓ OAuth token authentication successful (OAUTH_TOKEN env var)\")\n elif access_token:\n print(\"✓ M2M authentication successful\")\n else:\n print(\"✓ Ingress token authentication successful\")\n else:\n print(\"⚠ No authentication available\")\n # Execute command\n if args.command == \"init\":\n result = {\"status\": \"initialized\", \"session_id\": client.session_id}\n elif args.command == \"ping\":\n result = client.ping()\n elif args.command == \"list\":\n result = client.list_tools()\n elif args.command == \"call\":\n if not args.tool:\n print(\"Error: --tool is required for call command\")\n sys.exit(1)\n\n # Parse arguments if provided\n tool_args = {}\n if args.args:\n try:\n tool_args = json.loads(args.args)\n except json.JSONDecodeError as e:\n print(f\"Error: Invalid JSON in --args: {e}\")\n sys.exit(1)\n\n result = client.call_tool(args.tool, tool_args)\n\n # Print result\n print(json.dumps(result, indent=2))\n\n except Exception as e:\n print(f\"Error: {e}\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/mcp_security_scanner.py", "content": "#!/usr/bin/env python3\n\"\"\"\nMCP Security Scanner CLI Tool\n\nScans MCP servers for security vulnerabilities using cisco-ai-mcp-scanner.\nIntegrates with service_mgmt.sh to provide security analysis during server registration.\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport re\nimport subprocess # nosec B404\nimport sys\nfrom datetime import UTC, datetime\nfrom pathlib import Path\n\nfrom pydantic import BaseModel, Field\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nDEFAULT_ANALYZERS = \"yara\"\nLLM_API_KEY_ENV = \"MCP_SCANNER_LLM_API_KEY\"\n# Use absolute path relative to project root\nPROJECT_ROOT = Path(__file__).parent.parent\nOUTPUT_DIR = PROJECT_ROOT / \"security_scans\"\n\n\nclass SecurityScanResult(BaseModel):\n \"\"\"Security scan result model.\"\"\"\n\n server_url: str = Field(..., description=\"URL of the scanned MCP server\")\n scan_timestamp: str = Field(..., description=\"ISO timestamp of the scan\")\n is_safe: bool = Field(..., description=\"Overall safety assessment\")\n critical_issues: int = Field(default=0, description=\"Count of critical severity issues\")\n high_severity: int = Field(default=0, description=\"Count of high severity issues\")\n medium_severity: int = Field(default=0, description=\"Count of medium severity issues\")\n low_severity: int = Field(default=0, description=\"Count of low severity issues\")\n raw_output: dict = Field(..., description=\"Full scanner output\")\n output_file: str = Field(..., description=\"Path to detailed JSON output file\")\n\n\ndef _get_llm_api_key(cli_value: str | None = None) -> str:\n \"\"\"Retrieve LLM API key from CLI argument or environment variable.\n\n Args:\n cli_value: API key provided via command line\n\n Returns:\n LLM API key for security scanning\n\n Raises:\n ValueError: If API key is not found\n \"\"\"\n if cli_value:\n return cli_value\n\n env_value = os.getenv(LLM_API_KEY_ENV)\n if env_value:\n return env_value\n\n raise ValueError(f\"LLM API key must be provided via --api-key or {LLM_API_KEY_ENV} env var\")\n\n\ndef _ensure_output_directory() -> Path:\n \"\"\"Ensure output directory exists.\"\"\"\n OUTPUT_DIR.mkdir(parents=True, exist_ok=True)\n return OUTPUT_DIR\n\n\ndef _run_mcp_scanner(\n server_url: str,\n analyzers: str = DEFAULT_ANALYZERS,\n api_key: str | None = None,\n headers: str | None = None,\n) -> dict:\n \"\"\"Run mcp-scanner command and return raw output.\n\n Args:\n server_url: URL of the MCP server to scan\n analyzers: Comma-separated list of analyzers to use\n api_key: OpenAI API key for LLM-based analysis\n headers: JSON string of headers to include in requests\n\n Returns:\n Dictionary containing raw scanner output\n\n Raises:\n subprocess.CalledProcessError: If scanner command fails\n \"\"\"\n logger.info(f\"Running security scan on: {server_url}\")\n logger.info(f\"Using analyzers: {analyzers}\")\n\n # Build command - global options before subcommand, subcommand options after\n cmd = [\n \"mcp-scanner\",\n \"--analyzers\",\n analyzers,\n \"--raw\", # Use raw format instead of summary\n \"remote\", # Subcommand to scan remote MCP server\n \"--server-url\",\n server_url,\n ]\n\n # Add headers if provided - parse JSON and extract bearer token\n if headers:\n logger.info(\"Adding custom headers for scanning\")\n try:\n headers_dict = json.loads(headers)\n # Check for X-Authorization header with Bearer token\n auth_header = headers_dict.get(\"X-Authorization\", \"\")\n if auth_header.startswith(\"Bearer \"):\n bearer_token = auth_header.replace(\"Bearer \", \"\")\n cmd.extend([\"--bearer-token\", bearer_token])\n logger.info(\"Using bearer token authentication\")\n else:\n logger.warning(\n \"Headers provided but no Bearer token found in X-Authorization header\"\n )\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to parse headers JSON: {e}\")\n raise ValueError(f\"Invalid headers JSON: {headers}\") from e\n\n # Set environment variable for API key if provided\n env = os.environ.copy()\n if api_key:\n env[LLM_API_KEY_ENV] = api_key\n\n # Run scanner\n try:\n result = subprocess.run( # nosec B603 - mcp-scanner tool with validated args\n cmd, capture_output=True, text=True, check=True, env=env\n )\n\n # Log raw output for debugging\n logger.debug(f\"Raw scanner stdout:\\n{result.stdout[:500]}\")\n\n # Parse JSON output - scanner outputs JSON array after log messages\n stdout = result.stdout.strip()\n\n # Remove ANSI color codes that can interfere with JSON parsing\n ansi_escape = re.compile(r\"\\x1B(?:[@-Z\\\\-_]|\\[[0-?]*[ -/]*[@-~])\")\n stdout = ansi_escape.sub(\"\", stdout)\n\n # Find the start of JSON array - look for '[\\n {' pattern (array with objects)\n # This is more robust than just finding first '[' or '{'\n json_start = -1\n\n # Try to find JSON array start\n for i in range(len(stdout) - 1):\n if stdout[i] == \"[\" and (i == 0 or stdout[i - 1] in \"\\n\\r\"):\n # Found '[' at start of line, likely start of JSON\n json_start = i\n break\n\n # Fallback: find any '[' followed by whitespace and '{'\n if json_start == -1:\n pattern = r\"\\[\\s*\\{\"\n match = re.search(pattern, stdout)\n if match:\n json_start = match.start()\n\n if json_start == -1:\n raise ValueError(\"No JSON array found in scanner output\")\n\n # Extract and parse JSON\n json_str = stdout[json_start:]\n tool_results = json.loads(json_str)\n\n # Wrap in expected format with analysis_results\n # Convert array of tool results to the expected structure\n raw_output = {\"analysis_results\": {}, \"tool_results\": tool_results}\n\n # Extract findings from tool results and organize by analyzer\n for tool_result in tool_results:\n findings_dict = tool_result.get(\"findings\", {})\n for analyzer_name, analyzer_findings in findings_dict.items():\n if analyzer_name not in raw_output[\"analysis_results\"]:\n raw_output[\"analysis_results\"][analyzer_name] = {\"findings\": []}\n\n # Convert analyzer findings to expected format\n if isinstance(analyzer_findings, dict):\n finding = {\n \"tool_name\": tool_result.get(\"tool_name\"),\n \"severity\": analyzer_findings.get(\"severity\", \"unknown\"),\n \"threat_names\": analyzer_findings.get(\"threat_names\", []),\n \"threat_summary\": analyzer_findings.get(\"threat_summary\", \"\"),\n \"is_safe\": tool_result.get(\"is_safe\", True),\n }\n raw_output[\"analysis_results\"][analyzer_name][\"findings\"].append(finding)\n\n logger.debug(f\"Scanner output:\\n{json.dumps(raw_output, indent=2, default=str)}\")\n return raw_output\n\n except subprocess.CalledProcessError as e:\n logger.error(f\"Scanner command failed with exit code {e.returncode}\")\n logger.error(f\"stderr: {e.stderr}\")\n raise\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to parse scanner output as JSON: {e}\")\n logger.error(f\"Raw stdout: {result.stdout[:1000]}\")\n raise\n\n\ndef _analyze_scan_results(raw_output: dict) -> tuple[bool, int, int, int, int]:\n \"\"\"Analyze scan results and extract severity counts.\n\n Args:\n raw_output: Raw scanner output dictionary\n\n Returns:\n Tuple of (is_safe, critical_count, high_count, medium_count, low_count)\n \"\"\"\n critical_count = 0\n high_count = 0\n medium_count = 0\n low_count = 0\n\n # Navigate the raw output structure to find findings\n # Structure: raw_output -> analysis_results -> [analyzer_name] -> findings\n analysis_results = raw_output.get(\"analysis_results\", {})\n\n for _analyzer_name, analyzer_data in analysis_results.items():\n if isinstance(analyzer_data, dict):\n findings = analyzer_data.get(\"findings\", [])\n for finding in findings:\n severity = finding.get(\"severity\", \"\").lower()\n if severity == \"critical\":\n critical_count += 1\n elif severity == \"high\":\n high_count += 1\n elif severity == \"medium\":\n medium_count += 1\n elif severity == \"low\":\n low_count += 1\n\n # Determine if safe: no critical or high severity issues\n is_safe = critical_count == 0 and high_count == 0\n\n logger.info(\"Security analysis results:\")\n logger.info(f\" Critical Issues: {critical_count}\")\n logger.info(f\" High Severity: {high_count}\")\n logger.info(f\" Medium Severity: {medium_count}\")\n logger.info(f\" Low Severity: {low_count}\")\n logger.info(f\" Overall Assessment: {'SAFE' if is_safe else 'UNSAFE'}\")\n\n return is_safe, critical_count, high_count, medium_count, low_count\n\n\ndef _save_scan_output(server_url: str, raw_output: dict) -> str:\n \"\"\"Save detailed scan output to JSON file.\n\n Saves in two locations:\n 1. security_scans/YYYY-MM-DD/scan__.json (archived)\n 2. security_scans/scan__latest.json (always current)\n\n Args:\n server_url: URL of the scanned server\n raw_output: Raw scanner output\n\n Returns:\n Path to saved output file (latest version)\n \"\"\"\n output_dir = _ensure_output_directory()\n\n # Generate safe filename from server URL\n safe_url = server_url.replace(\"https://\", \"\").replace(\"http://\", \"\").replace(\"/\", \"_\")\n\n # Create date-based subdirectory for archival\n timestamp = datetime.now(UTC)\n date_folder = timestamp.strftime(\"%Y-%m-%d\")\n archive_dir = output_dir / date_folder\n archive_dir.mkdir(exist_ok=True)\n\n # Save timestamped version in date folder (archived)\n timestamp_str = timestamp.strftime(\"%Y%m%d_%H%M%S\")\n archived_filename = f\"scan_{safe_url}_{timestamp_str}.json\"\n archived_file = archive_dir / archived_filename\n\n with open(archived_file, \"w\") as f:\n json.dump(raw_output, f, indent=2, default=str)\n\n logger.info(f\"Archived scan output saved to: {archived_file}\")\n\n # Save latest version in root security_scans folder (always current)\n # Extract server name from URL for cleaner filename\n # e.g., http://localhost/realserverfaketools/mcp -> realserverfaketools_mcp.json\n server_name = safe_url.replace(\"localhost_\", \"\")\n latest_filename = f\"{server_name}.json\"\n latest_file = output_dir / latest_filename\n\n with open(latest_file, \"w\") as f:\n json.dump(raw_output, f, indent=2, default=str)\n\n logger.info(f\"Latest scan output saved to: {latest_file}\")\n\n return str(latest_file)\n\n\ndef _disable_unsafe_server(server_path: str) -> bool:\n \"\"\"Disable a server that failed security scan.\n\n Args:\n server_path: Path of the server to disable (e.g., /mcpgw)\n\n Returns:\n True if server was disabled successfully, False otherwise\n \"\"\"\n logger.info(f\"Disabling unsafe server: {server_path}\")\n\n try:\n # Call service_mgmt.sh to disable the server\n cmd = [str(PROJECT_ROOT / \"cli\" / \"service_mgmt.sh\"), \"disable\", server_path]\n\n result = subprocess.run( # nosec B603 - hardcoded internal script, server_path from URL parsing\n cmd, capture_output=True, text=True, check=True\n )\n\n logger.info(f\"Server {server_path} disabled successfully\")\n logger.debug(f\"Output: {result.stdout}\")\n return True\n\n except subprocess.CalledProcessError as e:\n logger.error(f\"Failed to disable server {server_path}: {e}\")\n logger.error(f\"stderr: {e.stderr}\")\n return False\n except Exception as e:\n logger.error(f\"Unexpected error disabling server {server_path}: {e}\")\n return False\n\n\ndef _extract_server_path_from_url(server_url: str) -> str | None:\n \"\"\"Extract server path from URL.\n\n Args:\n server_url: Full server URL (e.g., http://localhost/mcpgw/mcp)\n\n Returns:\n Server path (e.g., /mcpgw) or None if cannot be extracted\n \"\"\"\n try:\n # Parse URL to extract path component\n # Expected format: http://localhost/server-path/mcp\n from urllib.parse import urlparse\n\n parsed = urlparse(server_url)\n path_parts = [p for p in parsed.path.split(\"/\") if p and p != \"mcp\"]\n\n if path_parts:\n server_path = f\"/{path_parts[0]}\"\n logger.debug(f\"Extracted server path '{server_path}' from URL '{server_url}'\")\n return server_path\n else:\n logger.warning(f\"Could not extract server path from URL: {server_url}\")\n return None\n\n except Exception as e:\n logger.error(f\"Error parsing server URL {server_url}: {e}\")\n return None\n\n\ndef scan_server(\n server_url: str,\n analyzers: str = DEFAULT_ANALYZERS,\n api_key: str | None = None,\n output_json: bool = False,\n auto_disable: bool = False,\n headers: str | None = None,\n) -> SecurityScanResult:\n \"\"\"Scan an MCP server for security vulnerabilities.\n\n Args:\n server_url: URL of the MCP server to scan\n analyzers: Comma-separated list of analyzers to use\n api_key: OpenAI API key for LLM-based analysis\n output_json: If True, output raw mcp-scanner JSON directly\n auto_disable: If True, automatically disable servers that fail security scan\n headers: JSON string of headers to include in requests\n\n Returns:\n SecurityScanResult containing scan results\n \"\"\"\n # Run scanner\n try:\n raw_output = _run_mcp_scanner(server_url, analyzers, api_key, headers)\n except subprocess.CalledProcessError as e:\n # Scanner failed - create error output and save it\n logger.error(f\"Scanner failed with exit code {e.returncode}\")\n raw_output = {\n \"error\": str(e),\n \"stderr\": e.stderr if hasattr(e, \"stderr\") else \"\",\n \"analysis_results\": {},\n \"tool_results\": [],\n \"scan_failed\": True,\n }\n # Save the error output\n output_file = _save_scan_output(server_url, raw_output)\n\n # Create error result\n result = SecurityScanResult(\n server_url=server_url,\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=False, # Treat scanner failures as unsafe\n critical_issues=0,\n high_severity=0,\n medium_severity=0,\n low_severity=0,\n raw_output=raw_output,\n output_file=output_file,\n )\n\n # Output result\n if output_json:\n print(json.dumps(result.model_dump(), indent=2, default=str))\n else:\n print(\"\\n\" + \"=\" * 60)\n print(\"SECURITY SCAN FAILED\")\n print(\"=\" * 60)\n print(f\"Server URL: {result.server_url}\")\n print(f\"Scan Time: {result.scan_timestamp}\")\n print(\"\\nError: Scanner failed to complete scan\")\n print(f\"Details: {e}\")\n print(\"\\nMarking server as UNSAFE due to scanner failure\")\n print(f\"\\nDetailed output saved to: {result.output_file}\")\n print(\"=\" * 60 + \"\\n\")\n\n return result\n\n # Analyze results\n is_safe, critical, high, medium, low = _analyze_scan_results(raw_output)\n\n # Save detailed output\n output_file = _save_scan_output(server_url, raw_output)\n\n # Auto-disable server if unsafe\n if auto_disable and not is_safe:\n logger.warning(\"Server marked as UNSAFE - attempting to disable\")\n server_path = _extract_server_path_from_url(server_url)\n if server_path:\n if _disable_unsafe_server(server_path):\n logger.info(f\"✓ Server {server_path} has been disabled for security reasons\")\n else:\n logger.error(f\"✗ Failed to disable server {server_path}\")\n else:\n logger.error(\"✗ Could not extract server path from URL - manual intervention required\")\n\n # Create result object\n result = SecurityScanResult(\n server_url=server_url,\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=is_safe,\n critical_issues=critical,\n high_severity=high,\n medium_severity=medium,\n low_severity=low,\n raw_output=raw_output,\n output_file=output_file,\n )\n\n # Output result\n if output_json:\n # Output raw mcp-scanner format directly (same as --raw)\n print(json.dumps(raw_output, indent=2, default=str))\n else:\n print(\"\\n\" + \"=\" * 60)\n print(\"SECURITY SCAN SUMMARY\")\n print(\"=\" * 60)\n print(f\"Server URL: {result.server_url}\")\n print(f\"Scan Time: {result.scan_timestamp}\")\n print(\"\\nEXECUTIVE SUMMARY OF ISSUES:\")\n print(f\" Critical Issues: {result.critical_issues}\")\n print(f\" High Severity: {result.high_severity}\")\n print(f\" Medium Severity: {result.medium_severity}\")\n print(f\" Low Severity: {result.low_severity}\")\n print(f\"\\nOverall Assessment: {'SAFE ✓' if result.is_safe else 'UNSAFE ✗'}\")\n\n # Show auto-disable status if applicable\n if auto_disable and not result.is_safe:\n server_path = _extract_server_path_from_url(server_url)\n if server_path:\n print(\n f\"\\n⚠️ ACTION TAKEN: Server {server_path} has been DISABLED due to security issues\"\n )\n else:\n print(\"\\n⚠️ WARNING: Could not auto-disable server - manual intervention required\")\n\n print(f\"\\nDetailed output saved to: {result.output_file}\")\n print(\"=\" * 60 + \"\\n\")\n\n return result\n\n\ndef main():\n \"\"\"Main entry point for CLI.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Scan MCP servers for security vulnerabilities\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExample usage:\n # Basic scan with YARA analyzer (default)\n uv run cli/mcp_security_scanner.py --server-url https://mcp.deepwki.com/mcp\n\n # Scan with both YARA and LLM analyzers\n export MCP_SCANNER_LLM_API_KEY=sk-...\n uv run cli/mcp_security_scanner.py --server-url https://example.com/mcp --analyzers yara,llm\n\n # Scan with LLM only, passing API key directly\n uv run cli/mcp_security_scanner.py --server-url https://example.com/mcp --analyzers llm --api-key sk-...\n\n # Scan with custom headers (e.g., authentication)\n uv run cli/mcp_security_scanner.py --server-url https://example.com/mcp --headers '{\"X-Authorization\": \"Bearer token123\"}'\n\n # Output as JSON\n uv run cli/mcp_security_scanner.py --server-url https://example.com/mcp --json\n\"\"\",\n )\n\n parser.add_argument(\"--server-url\", required=True, help=\"URL of the MCP server to scan\")\n\n parser.add_argument(\n \"--analyzers\",\n default=DEFAULT_ANALYZERS,\n help=f\"Comma-separated list of analyzers to use (default: {DEFAULT_ANALYZERS})\",\n )\n\n parser.add_argument(\n \"--api-key\",\n help=f\"LLM API key for security scanning (can also use {LLM_API_KEY_ENV} env var)\",\n )\n\n parser.add_argument(\"--json\", action=\"store_true\", help=\"Output result as JSON\")\n\n parser.add_argument(\"--debug\", action=\"store_true\", help=\"Enable debug logging\")\n\n parser.add_argument(\n \"--auto-disable\",\n action=\"store_true\",\n help=\"Automatically disable servers that fail security scan (is_safe: false)\",\n )\n\n parser.add_argument(\n \"--headers\",\n help='JSON string of headers to include in requests (e.g., \\'{\"X-Authorization\": \"token\"}\\')',\n )\n\n args = parser.parse_args()\n\n # Set debug level if requested\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n try:\n # Get API key if needed for LLM analyzer\n api_key = None\n if \"llm\" in args.analyzers.lower():\n api_key = _get_llm_api_key(args.api_key)\n\n # Run scan\n result = scan_server(\n server_url=args.server_url,\n analyzers=args.analyzers,\n api_key=api_key,\n output_json=args.json,\n auto_disable=args.auto_disable,\n headers=args.headers,\n )\n\n # Exit with non-zero code if unsafe\n sys.exit(0 if result.is_safe else 1)\n\n except Exception as e:\n logger.exception(f\"Security scan failed: {e}\")\n sys.exit(2)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/mcp_utils.py", "content": "#!/usr/bin/env python3\n\"\"\"\nShared MCP Client Utility\n\nThis module provides a reusable MCP (Model Context Protocol) client implementation\nusing only standard Python libraries. We created this because some environments\nblock certain Python package installs, causing the fastmcp library install to fail.\nThis handy dandy MCP client implementation avoids external dependencies beyond\nthe standard library plus commonly available packages like requests.\n\nThe client supports:\n- JSON-RPC 2.0 protocol over HTTP\n- Authentication via Bearer tokens\n- Session management with automatic initialization\n- Both synchronous and asynchronous operations\n- Server-Sent Events (SSE) response handling\n- Automatic token loading from OAuth files\n\"\"\"\n\nimport json\nimport logging\nimport os\nimport time\nimport urllib.error\nimport urllib.parse\nimport urllib.request\nfrom pathlib import Path\nfrom typing import Any\n\nlogger = logging.getLogger(__name__)\n\n_ALLOWED_URL_SCHEMES = (\"http\", \"https\")\n\n\ndef _validate_url_scheme(url: str) -> None:\n \"\"\"Validate that a URL uses an allowed scheme (http or https).\n\n Prevents SSRF via file://, ftp://, or other unexpected schemes.\n\n Args:\n url: The URL string to validate.\n\n Raises:\n ValueError: If the URL scheme is not http or https.\n \"\"\"\n parsed = urllib.parse.urlparse(url)\n if parsed.scheme not in _ALLOWED_URL_SCHEMES:\n raise ValueError(\n f\"Invalid URL scheme '{parsed.scheme}' in URL '{url}'. \"\n f\"Only {_ALLOWED_URL_SCHEMES} are allowed.\"\n )\n\n\ndef _load_oauth_token_from_file(token_file_path: str | Path) -> str | None:\n \"\"\"\n Load OAuth access token from JSON file.\n\n Args:\n token_file_path: Path to OAuth token file\n\n Returns:\n Access token if found and valid, None otherwise\n \"\"\"\n try:\n token_path = Path(token_file_path)\n if not token_path.exists():\n return None\n\n with open(token_path) as f:\n token_data = json.load(f)\n\n # Support both flat and nested token structures\n # Nested: {\"tokens\": {\"access_token\": \"...\", \"expires_at\": ...}}\n # Flat: {\"access_token\": \"...\", \"expires_at\": ...}\n if \"tokens\" in token_data:\n tokens = token_data[\"tokens\"]\n access_token = tokens.get(\"access_token\")\n expires_at = tokens.get(\"expires_at\", 0)\n else:\n access_token = token_data.get(\"access_token\")\n expires_at = token_data.get(\"expires_at\", 0)\n\n # Check if token is expired\n if expires_at and time.time() >= expires_at:\n logger.warning(f\"Token in {token_file_path} has expired\")\n return None\n\n return access_token\n\n except (json.JSONDecodeError, FileNotFoundError, KeyError) as e:\n logger.debug(f\"Could not load token from {token_file_path}: {e}\")\n return None\n\n\ndef _get_auth_token(\n explicit_token: str | None = None, env_var_name: str = \"MCP_AUTH_TOKEN\"\n) -> str | None:\n \"\"\"\n Get authentication token from multiple sources in priority order.\n\n Priority order:\n 1. Explicit token parameter\n 2. Environment variable\n 3. Ingress token file (.oauth-tokens/ingress.json)\n\n Args:\n explicit_token: Token provided directly\n env_var_name: Name of environment variable to check\n\n Returns:\n Access token if found, None otherwise\n \"\"\"\n # 1. Explicit token has highest priority\n if explicit_token:\n return explicit_token\n\n # 2. Check environment variable\n env_token = os.getenv(env_var_name)\n if env_token:\n return env_token\n\n # 3. Try to load from ingress token file\n ingress_token_path = Path.cwd() / \".oauth-tokens\" / \"ingress.json\"\n return _load_oauth_token_from_file(ingress_token_path)\n\n\nclass MCPClient:\n \"\"\"\n MCP (Model Context Protocol) client implementation using standard Python libraries.\n\n This client handles JSON-RPC 2.0 communication over HTTP with MCP servers,\n including authentication, session management, and response parsing.\n \"\"\"\n\n def __init__(\n self,\n gateway_url: str,\n access_token: str | None = None,\n backend_token: str | None = None,\n timeout: int = 30,\n ):\n \"\"\"\n Initialize MCP client.\n\n Args:\n gateway_url: URL of the MCP gateway endpoint\n access_token: Optional Bearer token for backend server authentication (Authorization header)\n backend_token: Optional separate token for backend server (if different from gateway token)\n timeout: Request timeout in seconds\n \"\"\"\n self.gateway_url = gateway_url.rstrip(\"/\")\n # Backend token for Authorization header (forwarded to backend servers)\n self.backend_token = access_token\n # Gateway token for X-Authorization header (gateway auth) - use provided token or ingress token\n # Only fall back to ingress token if no explicit token was provided\n self.gateway_token = _get_auth_token(\n access_token\n ) # Use explicit token if provided, else ingress\n # Keep access_token for backwards compatibility\n self.access_token = self.backend_token or self.gateway_token\n self.timeout = timeout\n self.session_id: str | None = None\n self._request_id = 0\n\n def _get_next_request_id(self) -> int:\n \"\"\"Get next request ID for JSON-RPC calls.\"\"\"\n self._request_id += 1\n return self._request_id\n\n def _build_headers(self) -> dict[str, str]:\n \"\"\"Build HTTP headers for requests.\"\"\"\n headers = {\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json, text/event-stream\",\n \"User-Agent\": \"mcp-utils-client/1.0.0\",\n }\n\n # X-Authorization: Gateway authentication (uses ingress token)\n if self.gateway_token:\n headers[\"X-Authorization\"] = f\"Bearer {self.gateway_token}\"\n\n # Authorization: Backend server authentication (uses token from --token-file)\n if self.backend_token:\n headers[\"Authorization\"] = f\"Bearer {self.backend_token}\"\n\n if self.session_id:\n headers[\"mcp-session-id\"] = self.session_id\n\n return headers\n\n def _make_request(self, payload: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Make HTTP request to MCP gateway.\n\n Args:\n payload: JSON-RPC payload\n\n Returns:\n Parsed response data\n\n Raises:\n Exception: If request fails or response is invalid\n \"\"\"\n _validate_url_scheme(self.gateway_url)\n\n headers = self._build_headers()\n data = json.dumps(payload).encode(\"utf-8\")\n\n try:\n request = urllib.request.Request(\n self.gateway_url, data=data, headers=headers, method=\"POST\"\n )\n\n with urllib.request.urlopen(request, timeout=self.timeout) as response: # nosec B310\n response_data = response.read().decode(\"utf-8\")\n content_type = response.headers.get(\"content-type\", \"\")\n\n # Extract session ID from response headers if available\n session_id = response.headers.get(\"mcp-session-id\")\n if session_id and not self.session_id:\n self.session_id = session_id\n logger.debug(f\"Session ID established: {session_id}\")\n\n # Handle Server-Sent Events (SSE) response\n if \"text/event-stream\" in content_type:\n return self._parse_sse_response(response_data)\n else:\n # Handle regular JSON response\n return json.loads(response_data)\n\n except urllib.error.HTTPError as e:\n error_msg = f\"HTTP {e.code}: {e.reason}\"\n try:\n error_response = e.read().decode(\"utf-8\")\n error_data = json.loads(error_response)\n if \"error\" in error_data:\n error_msg = f\"HTTP {e.code}: {error_data['error']}\"\n except (json.JSONDecodeError, UnicodeDecodeError):\n pass\n raise Exception(error_msg)\n\n except urllib.error.URLError as e:\n raise Exception(f\"Network error: {e.reason}\")\n\n except json.JSONDecodeError as e:\n raise Exception(f\"Invalid JSON response: {e}\")\n\n def _parse_sse_response(self, sse_data: str) -> dict[str, Any]:\n \"\"\"\n Parse Server-Sent Events response format.\n\n Args:\n sse_data: Raw SSE response data\n\n Returns:\n Parsed JSON data from SSE stream\n \"\"\"\n lines = sse_data.strip().split(\"\\n\")\n for line in lines:\n if line.startswith(\"data: \"):\n data_json = line[6:] # Remove 'data: ' prefix\n try:\n return json.loads(data_json)\n except json.JSONDecodeError:\n continue\n raise Exception(\"No valid JSON found in SSE response\")\n\n def initialize(self) -> dict[str, Any]:\n \"\"\"\n Initialize MCP session with the gateway.\n\n Returns:\n Initialization response\n \"\"\"\n payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": self._get_next_request_id(),\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {},\n \"clientInfo\": {\"name\": \"mcp-utils-client\", \"version\": \"1.0.0\"},\n },\n }\n\n result = self._make_request(payload)\n\n # Send initialized notification to complete handshake\n self._send_initialized()\n\n return result\n\n def _send_initialized(self) -> None:\n \"\"\"Send initialized notification to complete MCP handshake.\"\"\"\n payload = {\"jsonrpc\": \"2.0\", \"method\": \"notifications/initialized\"}\n try:\n self._make_request(payload)\n except Exception as e:\n # This is expected for some MCP servers that don't require the notification\n logger.debug(f\"Initialized notification not sent (this is normal): {e}\")\n\n def ping(self) -> dict[str, Any]:\n \"\"\"\n Test connectivity with ping.\n\n Returns:\n Ping response\n \"\"\"\n payload = {\"jsonrpc\": \"2.0\", \"id\": self._get_next_request_id(), \"method\": \"ping\"}\n return self._make_request(payload)\n\n def list_tools(self) -> dict[str, Any]:\n \"\"\"\n List available tools.\n\n Returns:\n Tools list response\n \"\"\"\n payload = {\"jsonrpc\": \"2.0\", \"id\": self._get_next_request_id(), \"method\": \"tools/list\"}\n return self._make_request(payload)\n\n def call_tool(self, tool_name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:\n \"\"\"\n Call a specific tool.\n\n Args:\n tool_name: Name of the tool to call\n arguments: Tool arguments (optional)\n\n Returns:\n Tool execution result\n \"\"\"\n if arguments is None:\n arguments = {}\n\n payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": self._get_next_request_id(),\n \"method\": \"tools/call\",\n \"params\": {\"name\": tool_name, \"arguments\": arguments},\n }\n\n response = self._make_request(payload)\n\n # Handle MCP response format\n if \"error\" in response:\n raise Exception(f\"MCP tool error: {response['error']}\")\n\n if \"result\" in response:\n return response[\"result\"]\n\n return response\n\n def call_mcpgw_tool(self, tool_name: str, params: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Call a tool using mcpgw-specific parameter format.\n\n This method wraps parameters in the format expected by mcpgw tools.\n\n Args:\n tool_name: Name of the tool to call\n params: Parameters for the tool\n\n Returns:\n Tool execution result\n \"\"\"\n arguments = {\"params\": params}\n return self.call_tool(tool_name, arguments)\n\n\nclass MCPSession:\n \"\"\"\n Context manager for MCP client sessions.\n\n Automatically initializes the session on entry and ensures proper cleanup.\n Provides a convenient way to work with MCP clients in a session context.\n \"\"\"\n\n def __init__(self, client: MCPClient):\n \"\"\"\n Initialize session context.\n\n Args:\n client: MCP client instance\n \"\"\"\n self.client = client\n self._initialized = False\n\n def __enter__(self) -> MCPClient:\n \"\"\"Enter session context and initialize.\"\"\"\n try:\n self.client.initialize()\n self._initialized = True\n logger.debug(\"MCP session initialized successfully\")\n except Exception as e:\n logger.error(f\"Failed to initialize MCP session: {e}\")\n raise\n return self.client\n\n def __exit__(self, exc_type, exc_val, exc_tb):\n \"\"\"Exit session context.\"\"\"\n if self._initialized:\n logger.debug(\"MCP session closed\")\n\n\ndef create_mcp_client(\n gateway_url: str, access_token: str | None = None, timeout: int = 30\n) -> MCPClient:\n \"\"\"\n Create and return a configured MCP client.\n\n Args:\n gateway_url: URL of the MCP gateway endpoint\n access_token: Optional Bearer token for authentication\n timeout: Request timeout in seconds\n\n Returns:\n Configured MCP client instance\n \"\"\"\n return MCPClient(gateway_url, access_token, timeout)\n\n\ndef create_mcp_session(\n gateway_url: str, access_token: str | None = None, timeout: int = 30\n) -> MCPSession:\n \"\"\"\n Create and return an MCP session context manager.\n\n Args:\n gateway_url: URL of the MCP gateway endpoint\n access_token: Optional Bearer token for authentication\n timeout: Request timeout in seconds\n\n Returns:\n MCP session context manager\n \"\"\"\n client = create_mcp_client(gateway_url, access_token, timeout)\n return MCPSession(client)\n" }, { "path": "cli/package.json", "content": "{\n \"name\": \"@mcp-gateway/ink-cli\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"type\": \"module\",\n \"description\": \"Interactive MCP Gateway client powered by Ink.\",\n \"bin\": {\n \"registry\": \"./bin/registry.js\"\n },\n \"scripts\": {\n \"start\": \"tsx src/index.tsx\",\n \"dev\": \"tsx watch src/index.tsx\",\n \"build\": \"tsc --project tsconfig.json\",\n \"typecheck\": \"tsc --noEmit --project tsconfig.json\"\n },\n \"dependencies\": {\n \"@anthropic-ai/sdk\": \"^0.21.0\",\n \"@aws-sdk/client-bedrock-runtime\": \"^3.982.0\",\n \"dotenv\": \"^17.2.3\",\n \"ink\": \"^5.1.0\",\n \"ink-select-input\": \"^6.0.0\",\n \"ink-spinner\": \"^5.0.0\",\n \"ink-text-input\": \"^6.0.0\",\n \"marked\": \"^15.0.12\",\n \"marked-terminal\": \"^7.3.0\",\n \"react\": \"^18.3.1\",\n \"zod\": \"^3.23.8\"\n },\n \"devDependencies\": {\n \"@types/marked-terminal\": \"^6.1.1\",\n \"@types/node\": \"^20.12.7\",\n \"@types/react\": \"^18.3.3\",\n \"tsx\": \"^4.7.1\",\n \"typescript\": \"^5.5.4\"\n },\n \"engines\": {\n \"node\": \">=18.19.0\"\n }\n}\n" }, { "path": "cli/registry_cli_wrapper.py", "content": "#!/usr/bin/env python3\n\"\"\"\nCLI Wrapper for Registry Management API\n\nThis module provides a command-line interface that wraps the Registry Management API,\nmaintaining backwards compatibility with the deprecated shell scripts while using\nthe modern Python API underneath.\n\nThis wrapper is designed to be called from the TypeScript CLI application via subprocess.\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nfrom pathlib import Path\nfrom typing import Any\n\n# Add parent directory to path to import registry_client\nsys.path.insert(0, str(Path(__file__).parent.parent))\n\nfrom api.registry_client import RegistryClient\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _load_token_from_file(\n token_file: str,\n) -> str:\n \"\"\"Load access token from JSON file.\n\n Args:\n token_file: Path to token file containing access_token field\n\n Returns:\n Access token string\n \"\"\"\n with open(token_file) as f:\n token_data = json.load(f)\n access_token = token_data.get(\"access_token\")\n if not access_token:\n raise ValueError(f\"No access_token found in {token_file}\")\n return access_token\n\n\ndef _get_registry_client(\n base_url: str,\n token_file: str | None = None,\n) -> RegistryClient:\n \"\"\"Create and return a configured RegistryClient.\n\n Args:\n base_url: Registry base URL\n token_file: Optional path to token file\n\n Returns:\n Configured RegistryClient instance\n \"\"\"\n if token_file:\n access_token = _load_token_from_file(token_file)\n else:\n # Try to get from environment\n access_token = os.getenv(\"GATEWAY_TOKEN\")\n if not access_token:\n raise ValueError(\"No token provided via --token-file or GATEWAY_TOKEN env var\")\n\n return RegistryClient(registry_url=base_url, token=access_token)\n\n\ndef _print_json_response(\n data: Any,\n) -> None:\n \"\"\"Pretty-print JSON response.\n\n Args:\n data: Data to print as JSON\n \"\"\"\n print(json.dumps(data, indent=2, default=str))\n\n\ndef _handle_service_add(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle service add command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n # Load config from file\n with open(args.config_path) as f:\n config = json.load(f)\n\n result = client.register_server(config)\n _print_json_response(result.model_dump())\n\n\ndef _handle_service_delete(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle service delete command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.remove_server(args.path, force=True)\n _print_json_response(result.model_dump())\n\n\ndef _handle_service_list(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle service list command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.anthropic_list_servers(limit=1000)\n _print_json_response(result.model_dump())\n\n\ndef _handle_service_monitor(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle service monitor command.\"\"\"\n # Monitor is essentially list with detailed output\n _handle_service_list(args)\n\n\ndef _handle_group_create(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle group create command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.group_create(name=args.name, description=args.description)\n _print_json_response(result.model_dump())\n\n\ndef _handle_group_delete(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle group delete command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.group_delete(name=args.name, force=True)\n _print_json_response(result.model_dump())\n\n\ndef _handle_group_list(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle group list command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.group_list()\n _print_json_response(result)\n\n\ndef _handle_user_create_m2m(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle M2M user creation command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n groups = args.groups.split(\",\") if args.groups else []\n\n result = client.user_create_m2m(name=args.name, groups=groups, description=args.description)\n _print_json_response(result.model_dump())\n\n\ndef _handle_user_create_human(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle human user creation command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n groups = args.groups.split(\",\") if args.groups else []\n\n result = client.user_create_human(\n username=args.username,\n email=args.email,\n first_name=args.first_name,\n last_name=args.last_name,\n groups=groups,\n password=args.password,\n )\n _print_json_response(result.model_dump())\n\n\ndef _handle_user_delete(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle user delete command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.user_delete(username=args.username, force=True)\n _print_json_response(result.model_dump())\n\n\ndef _handle_user_list(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle user list command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.user_list()\n _print_json_response(result)\n\n\ndef _handle_anthropic_list(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle Anthropic API list command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.anthropic_list_servers(limit=args.limit if hasattr(args, \"limit\") else 100)\n _print_json_response(result.model_dump())\n\n\ndef _handle_anthropic_get(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle Anthropic API get command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.anthropic_get_server(server_name=args.server_name)\n _print_json_response(result.model_dump())\n\n\ndef _handle_agent_list(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle agent list command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n query = args.query if hasattr(args, \"query\") else None\n enabled_only = args.enabled_only if hasattr(args, \"enabled_only\") else False\n\n result = client.list_agents(query=query, enabled_only=enabled_only)\n _print_json_response(result.model_dump())\n\n\ndef _handle_agent_get(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle agent get command.\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.get_agent(path=args.path)\n _print_json_response(result.model_dump())\n\n\ndef _handle_agent_search(\n args: argparse.Namespace,\n) -> None:\n \"\"\"Handle agent search command (alias for list with query).\"\"\"\n client = _get_registry_client(args.base_url, args.token_file)\n\n result = client.list_agents(query=args.query, enabled_only=False)\n _print_json_response(result.model_dump())\n\n\ndef main() -> None:\n \"\"\"Main CLI entry point.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Registry Management CLI Wrapper\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n\n parser.add_argument(\n \"--base-url\",\n default=os.getenv(\"GATEWAY_BASE_URL\", \"http://localhost\"),\n help=\"Registry base URL (default: http://localhost)\",\n )\n\n parser.add_argument(\"--token-file\", help=\"Path to token file containing access_token\")\n\n subparsers = parser.add_subparsers(dest=\"command\", help=\"Command to execute\")\n\n # Service management commands\n service_parser = subparsers.add_parser(\"service\", help=\"Service management commands\")\n service_subparsers = service_parser.add_subparsers(dest=\"subcommand\")\n\n # Service add\n add_parser = service_subparsers.add_parser(\"add\", help=\"Add a service\")\n add_parser.add_argument(\"config_path\", help=\"Path to service config JSON file\")\n\n # Service delete\n delete_parser = service_subparsers.add_parser(\"delete\", help=\"Delete a service\")\n delete_parser.add_argument(\"path\", help=\"Service path\")\n\n # Service list\n service_subparsers.add_parser(\"list\", help=\"List services\")\n\n # Service monitor\n service_subparsers.add_parser(\"monitor\", help=\"Monitor services\")\n\n # Group management commands\n group_parser = subparsers.add_parser(\"group\", help=\"Group management commands\")\n group_subparsers = group_parser.add_subparsers(dest=\"subcommand\")\n\n # Group create\n group_create_parser = group_subparsers.add_parser(\"create\", help=\"Create a group\")\n group_create_parser.add_argument(\"--name\", required=True, help=\"Group name\")\n group_create_parser.add_argument(\"--description\", help=\"Group description\")\n\n # Group delete\n group_delete_parser = group_subparsers.add_parser(\"delete\", help=\"Delete a group\")\n group_delete_parser.add_argument(\"--name\", required=True, help=\"Group name\")\n\n # Group list\n group_subparsers.add_parser(\"list\", help=\"List groups\")\n\n # User management commands\n user_parser = subparsers.add_parser(\"user\", help=\"User management commands\")\n user_subparsers = user_parser.add_subparsers(dest=\"subcommand\")\n\n # User create M2M\n m2m_parser = user_subparsers.add_parser(\"create-m2m\", help=\"Create M2M user\")\n m2m_parser.add_argument(\"--name\", required=True, help=\"Service account name\")\n m2m_parser.add_argument(\"--groups\", help=\"Comma-separated list of groups\")\n m2m_parser.add_argument(\"--description\", help=\"Service account description\")\n\n # User create human\n human_parser = user_subparsers.add_parser(\"create-human\", help=\"Create human user\")\n human_parser.add_argument(\"--username\", required=True, help=\"Username\")\n human_parser.add_argument(\"--email\", required=True, help=\"Email address\")\n human_parser.add_argument(\"--first-name\", required=True, help=\"First name\")\n human_parser.add_argument(\"--last-name\", required=True, help=\"Last name\")\n human_parser.add_argument(\"--groups\", help=\"Comma-separated list of groups\")\n human_parser.add_argument(\"--password\", required=True, help=\"Password\")\n\n # User delete\n user_delete_parser = user_subparsers.add_parser(\"delete\", help=\"Delete user\")\n user_delete_parser.add_argument(\"--username\", required=True, help=\"Username\")\n\n # User list\n user_subparsers.add_parser(\"list\", help=\"List users\")\n\n # Anthropic API commands\n anthropic_parser = subparsers.add_parser(\"anthropic\", help=\"Anthropic API commands\")\n anthropic_subparsers = anthropic_parser.add_subparsers(dest=\"subcommand\")\n\n # Anthropic list\n list_parser = anthropic_subparsers.add_parser(\"list\", help=\"List servers (Anthropic API)\")\n list_parser.add_argument(\"--limit\", type=int, default=100, help=\"Limit results\")\n\n # Anthropic get\n get_parser = anthropic_subparsers.add_parser(\"get\", help=\"Get server details (Anthropic API)\")\n get_parser.add_argument(\"server_name\", help=\"Server name\")\n\n # Agent management commands\n agent_parser = subparsers.add_parser(\"agent\", help=\"Agent management commands\")\n agent_subparsers = agent_parser.add_subparsers(dest=\"subcommand\")\n\n # Agent list\n agent_list_parser = agent_subparsers.add_parser(\"list\", help=\"List agents\")\n agent_list_parser.add_argument(\"--query\", help=\"Search query\")\n agent_list_parser.add_argument(\n \"--enabled-only\", action=\"store_true\", help=\"Show only enabled agents\"\n )\n\n # Agent get\n agent_get_parser = agent_subparsers.add_parser(\"get\", help=\"Get agent details\")\n agent_get_parser.add_argument(\"path\", help=\"Agent path\")\n\n # Agent search\n agent_search_parser = agent_subparsers.add_parser(\"search\", help=\"Search agents\")\n agent_search_parser.add_argument(\"query\", help=\"Search query\")\n\n args = parser.parse_args()\n\n if not args.command:\n parser.print_help()\n sys.exit(1)\n\n try:\n # Route to appropriate handler\n if args.command == \"service\":\n if args.subcommand == \"add\":\n _handle_service_add(args)\n elif args.subcommand == \"delete\":\n _handle_service_delete(args)\n elif args.subcommand == \"list\":\n _handle_service_list(args)\n elif args.subcommand == \"monitor\":\n _handle_service_monitor(args)\n else:\n service_parser.print_help()\n sys.exit(1)\n\n elif args.command == \"group\":\n if args.subcommand == \"create\":\n _handle_group_create(args)\n elif args.subcommand == \"delete\":\n _handle_group_delete(args)\n elif args.subcommand == \"list\":\n _handle_group_list(args)\n else:\n group_parser.print_help()\n sys.exit(1)\n\n elif args.command == \"user\":\n if args.subcommand == \"create-m2m\":\n _handle_user_create_m2m(args)\n elif args.subcommand == \"create-human\":\n _handle_user_create_human(args)\n elif args.subcommand == \"delete\":\n _handle_user_delete(args)\n elif args.subcommand == \"list\":\n _handle_user_list(args)\n else:\n user_parser.print_help()\n sys.exit(1)\n\n elif args.command == \"anthropic\":\n if args.subcommand == \"list\":\n _handle_anthropic_list(args)\n elif args.subcommand == \"get\":\n _handle_anthropic_get(args)\n else:\n anthropic_parser.print_help()\n sys.exit(1)\n\n elif args.command == \"agent\":\n if args.subcommand == \"list\":\n _handle_agent_list(args)\n elif args.subcommand == \"get\":\n _handle_agent_get(args)\n elif args.subcommand == \"search\":\n _handle_agent_search(args)\n else:\n agent_parser.print_help()\n sys.exit(1)\n\n else:\n parser.print_help()\n sys.exit(1)\n\n except Exception as e:\n logger.error(f\"Command failed: {e}\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/scan_all_servers.py", "content": "#!/usr/bin/env python3\n\"\"\"\nScan all enabled MCP servers for security vulnerabilities.\n\nThis script:\n1. Uses the Registry Management API client to get a list of all servers\n2. Filters for enabled servers\n3. Runs security scans on each enabled server using mcp_security_scanner.py\n\nUsage:\n uv run python cli/scan_all_servers.py\n uv run python cli/scan_all_servers.py --base-url http://localhost\n uv run python cli/scan_all_servers.py --analyzers yara,llm\n uv run python cli/scan_all_servers.py --token-file .oauth-tokens/ingress.json\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport subprocess # nosec B404\nimport sys\nfrom datetime import UTC, datetime\nfrom pathlib import Path\nfrom typing import Any\n\n# Add project root to path to import registry client\nSCRIPT_DIR = Path(__file__).parent\nPROJECT_ROOT = SCRIPT_DIR.parent\nsys.path.insert(0, str(PROJECT_ROOT / \"api\"))\n\nfrom registry_client import RegistryClient\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nDEFAULT_TOKEN_FILE = PROJECT_ROOT / \".oauth-tokens\" / \"ingress.json\"\nDEFAULT_BASE_URL = \"http://localhost\"\nDEFAULT_ANALYZERS = \"yara\"\n\n\ndef _run_security_scan(\n server_url: str, analyzers: str, api_key: str | None = None, access_token: str | None = None\n) -> dict[str, Any]:\n \"\"\"Run security scan on a server using mcp_security_scanner.py directly.\n\n Args:\n server_url: URL of the MCP server to scan\n analyzers: Comma-separated list of analyzers (e.g., 'yara', 'yara,llm')\n api_key: Optional API key for LLM analyzer\n access_token: Optional access token for authenticated MCP servers\n\n Returns:\n Dictionary with scan results including:\n - success: bool\n - scan_output_file: Path to scan results JSON file\n - critical_issues: int\n - high_severity: int\n - medium_severity: int\n - low_severity: int\n - is_safe: bool\n \"\"\"\n scanner_script = SCRIPT_DIR / \"mcp_security_scanner.py\"\n\n if not scanner_script.exists():\n logger.error(f\"mcp_security_scanner.py not found at: {scanner_script}\")\n return {\n \"success\": False,\n \"scan_output_file\": None,\n \"critical_issues\": 0,\n \"high_severity\": 0,\n \"medium_severity\": 0,\n \"low_severity\": 0,\n \"is_safe\": False,\n \"error_message\": \"Scanner script not found\",\n }\n\n cmd = [\n \"uv\",\n \"run\",\n \"python\",\n str(scanner_script),\n \"--server-url\",\n server_url,\n \"--analyzers\",\n analyzers,\n ]\n\n if api_key:\n cmd.extend([\"--api-key\", api_key])\n\n # Add headers with authorization token if provided\n if access_token:\n headers_json = json.dumps({\"X-Authorization\": f\"Bearer {access_token}\"})\n cmd.extend([\"--headers\", headers_json])\n\n # Log command with masked token for security\n cmd_for_log = cmd.copy()\n if access_token and \"--headers\" in cmd_for_log:\n header_idx = cmd_for_log.index(\"--headers\") + 1\n headers_masked = json.dumps(\n {\"X-Authorization\": f\"Bearer {access_token[:20]}...{access_token[-10:]}\"}\n )\n cmd_for_log[header_idx] = headers_masked\n logger.info(f\"Running: {' '.join(cmd_for_log)}\")\n\n try:\n result = subprocess.run( # nosec B603 - internal script invoked via uv run with validated args\n cmd, capture_output=True, text=True, check=False, cwd=str(PROJECT_ROOT)\n )\n\n # Log output\n if result.stdout:\n logger.info(f\"Scan output:\\n{result.stdout}\")\n if result.stderr:\n logger.warning(f\"Scan stderr:\\n{result.stderr}\")\n\n # Parse scan results from security_scans directory\n scan_result = {\n \"success\": result.returncode == 0,\n \"scan_output_file\": None,\n \"critical_issues\": 0,\n \"high_severity\": 0,\n \"medium_severity\": 0,\n \"low_severity\": 0,\n \"is_safe\": result.returncode == 0,\n \"error_message\": None,\n }\n\n # Try to find and parse the scan output file\n try:\n # Extract server name from URL for finding scan file\n from urllib.parse import urlparse\n\n parsed = urlparse(server_url)\n path_parts = [p for p in parsed.path.split(\"/\") if p and p != \"mcp\"]\n if path_parts:\n server_name = path_parts[0]\n scan_file = PROJECT_ROOT / \"security_scans\" / f\"{server_name}_mcp.json\"\n\n if scan_file.exists():\n scan_result[\"scan_output_file\"] = str(scan_file)\n with open(scan_file) as f:\n scan_data = json.load(f)\n\n # Extract severity counts from analysis_results\n analysis_results = scan_data.get(\"analysis_results\", {})\n for analyzer_name, analyzer_data in analysis_results.items():\n if isinstance(analyzer_data, dict):\n findings = analyzer_data.get(\"findings\", [])\n for finding in findings:\n severity = finding.get(\"severity\", \"\").lower()\n if severity == \"critical\":\n scan_result[\"critical_issues\"] += 1\n elif severity == \"high\":\n scan_result[\"high_severity\"] += 1\n elif severity == \"medium\":\n scan_result[\"medium_severity\"] += 1\n elif severity == \"low\":\n scan_result[\"low_severity\"] += 1\n\n # Determine if safe based on scan data\n scan_result[\"is_safe\"] = (\n scan_result[\"critical_issues\"] == 0 and scan_result[\"high_severity\"] == 0\n )\n except Exception as e:\n logger.warning(f\"Could not parse scan results: {e}\")\n\n # Check exit code\n if result.returncode == 0:\n logger.info(\"✓ Scan completed successfully\")\n else:\n logger.error(f\"✗ Scan failed with exit code: {result.returncode}\")\n scan_result[\"error_message\"] = f\"Scanner exit code: {result.returncode}\"\n\n return scan_result\n\n except Exception as e:\n logger.error(f\"Failed to run scan: {e}\")\n return {\n \"success\": False,\n \"scan_output_file\": None,\n \"critical_issues\": 0,\n \"high_severity\": 0,\n \"medium_severity\": 0,\n \"low_severity\": 0,\n \"is_safe\": False,\n \"error_message\": str(e),\n }\n\n\ndef _generate_markdown_report(\n scan_results: list[dict[str, Any]], stats: dict[str, int], analyzers: str, scan_timestamp: str\n) -> str:\n \"\"\"Generate markdown report from scan results.\n\n Args:\n scan_results: List of scan result dictionaries\n stats: Dictionary with summary statistics\n analyzers: Analyzers used for scanning\n scan_timestamp: ISO timestamp of scan\n\n Returns:\n Markdown formatted report as string\n \"\"\"\n lines = []\n\n # Header\n lines.append(\"# MCP Server Security Scan Report\")\n lines.append(\"\")\n lines.append(f\"**Scan Date:** {scan_timestamp}\")\n lines.append(f\"**Analyzers Used:** {analyzers}\")\n lines.append(\"\")\n\n # Executive Summary\n lines.append(\"## Executive Summary\")\n lines.append(\"\")\n total = stats[\"total\"]\n passed = stats[\"passed\"]\n failed = stats[\"failed\"]\n pass_rate = (passed / total * 100) if total > 0 else 0\n\n lines.append(f\"- **Total Servers Scanned:** {total}\")\n lines.append(f\"- **Passed:** {passed} ({pass_rate:.1f}%)\")\n lines.append(f\"- **Failed:** {failed} ({100 - pass_rate:.1f}%)\")\n lines.append(\"\")\n\n # Aggregate Vulnerability Statistics\n total_critical = sum(r.get(\"critical_issues\", 0) for r in scan_results)\n total_high = sum(r.get(\"high_severity\", 0) for r in scan_results)\n total_medium = sum(r.get(\"medium_severity\", 0) for r in scan_results)\n total_low = sum(r.get(\"low_severity\", 0) for r in scan_results)\n\n lines.append(\"### Aggregate Vulnerability Statistics\")\n lines.append(\"\")\n lines.append(\"| Severity | Count |\")\n lines.append(\"|----------|-------|\")\n lines.append(f\"| Critical | {total_critical} |\")\n lines.append(f\"| High | {total_high} |\")\n lines.append(f\"| Medium | {total_medium} |\")\n lines.append(f\"| Low | {total_low} |\")\n lines.append(\"\")\n\n # Per-Server Results\n lines.append(\"## Per-Server Scan Results\")\n lines.append(\"\")\n\n for result in scan_results:\n server_name = result.get(\"server_name\", \"Unknown\")\n server_url = result.get(\"server_url\", \"Unknown\")\n is_safe = result.get(\"is_safe\", False)\n status = \"✅ SAFE\" if is_safe else \"❌ UNSAFE\"\n\n lines.append(f\"### {server_name}\")\n lines.append(\"\")\n lines.append(f\"- **URL:** `{server_url}`\")\n lines.append(f\"- **Status:** {status}\")\n lines.append(\"\")\n\n # Vulnerability table\n lines.append(\"| Severity | Count |\")\n lines.append(\"|----------|-------|\")\n lines.append(f\"| Critical | {result.get('critical_issues', 0)} |\")\n lines.append(f\"| High | {result.get('high_severity', 0)} |\")\n lines.append(f\"| Medium | {result.get('medium_severity', 0)} |\")\n lines.append(f\"| Low | {result.get('low_severity', 0)} |\")\n lines.append(\"\")\n\n # Show detailed findings for tools with issues\n scan_file = result.get(\"scan_output_file\")\n if scan_file and Path(scan_file).exists():\n try:\n with open(scan_file) as f:\n scan_data = json.load(f)\n\n tool_results = scan_data.get(\"tool_results\", [])\n tools_with_findings = [\n tool\n for tool in tool_results\n if any(\n finding.get(\"total_findings\", 0) > 0\n for finding in tool.get(\"findings\", {}).values()\n )\n ]\n\n if tools_with_findings:\n lines.append(\"#### Detailed Findings\")\n lines.append(\"\")\n\n for tool in tools_with_findings:\n tool_name = tool.get(\"tool_name\", \"Unknown\")\n lines.append(f\"**Tool: `{tool_name}`**\")\n lines.append(\"\")\n\n # Show findings for each analyzer\n findings = tool.get(\"findings\", {})\n for analyzer_name, analyzer_findings in findings.items():\n total_findings = analyzer_findings.get(\"total_findings\", 0)\n if total_findings > 0:\n severity = analyzer_findings.get(\"severity\", \"UNKNOWN\")\n threat_names = analyzer_findings.get(\"threat_names\", [])\n threat_summary = analyzer_findings.get(\"threat_summary\", \"\")\n\n lines.append(f\"- **Analyzer:** {analyzer_name}\")\n lines.append(f\"- **Severity:** {severity}\")\n lines.append(\n f\"- **Threats:** {', '.join(threat_names) if threat_names else 'None'}\"\n )\n lines.append(f\"- **Summary:** {threat_summary}\")\n\n # Include taxonomy if available\n taxonomy = analyzer_findings.get(\"mcp_taxonomy\", {})\n if taxonomy:\n lines.append(\"\")\n lines.append(\"**Taxonomy:**\")\n lines.append(\"```json\")\n lines.append(json.dumps(taxonomy, indent=2))\n lines.append(\"```\")\n\n lines.append(\"\")\n\n # Show tool description if available\n tool_desc = tool.get(\"tool_description\", \"\")\n if tool_desc:\n lines.append(\"
\")\n lines.append(\"Tool Description\")\n lines.append(\"\")\n lines.append(\"```\")\n lines.append(tool_desc)\n lines.append(\"```\")\n lines.append(\"
\")\n lines.append(\"\")\n\n except Exception as e:\n logger.warning(f\"Could not parse detailed findings from {scan_file}: {e}\")\n lines.append(f\"**Detailed Report:** [{Path(scan_file).name}]({scan_file})\")\n lines.append(\"\")\n else:\n if scan_file:\n lines.append(f\"**Detailed Report:** [{Path(scan_file).name}]({scan_file})\")\n lines.append(\"\")\n\n if result.get(\"error_message\"):\n lines.append(f\"**Error:** {result['error_message']}\")\n lines.append(\"\")\n\n # Footer\n lines.append(\"---\")\n lines.append(\"\")\n lines.append(f\"*Report generated on {scan_timestamp}*\")\n lines.append(\"\")\n\n return \"\\n\".join(lines)\n\n\ndef _scan_all_servers(\n base_url: str, token_file: Path, analyzers: str = DEFAULT_ANALYZERS, api_key: str | None = None\n) -> dict[str, Any]:\n \"\"\"Scan all enabled servers.\n\n Args:\n base_url: Base URL of the registry\n token_file: Path to token file\n analyzers: Comma-separated list of analyzers\n api_key: Optional API key for LLM analyzer\n\n Returns:\n Dictionary with scan statistics\n \"\"\"\n logger.info(\"=\" * 80)\n logger.info(\"Scan All MCP Servers - Security Vulnerability Scanner\")\n logger.info(\"=\" * 80)\n\n # Load access token from file\n try:\n with open(token_file) as f:\n token_data = json.load(f)\n access_token = token_data.get(\"access_token\")\n if not access_token:\n raise ValueError(f\"No access_token found in {token_file}\")\n logger.info(f\"Loaded token from: {token_file}\")\n except Exception as e:\n logger.error(f\"Failed to load token: {e}\")\n sys.exit(1)\n\n # Create registry client\n try:\n client = RegistryClient(registry_url=base_url, token=access_token)\n logger.info(f\"Connected to registry at: {base_url}\")\n except Exception as e:\n logger.error(f\"Failed to create registry client: {e}\")\n sys.exit(1)\n\n # Get server list using the Anthropic Registry API (v0.1)\n try:\n servers_response = client.anthropic_list_servers(limit=1000)\n servers = servers_response.servers if hasattr(servers_response, \"servers\") else []\n logger.info(f\"Retrieved {len(servers)} servers from registry using Anthropic API v0.1\")\n except Exception as e:\n logger.error(f\"Failed to get server list: {e}\")\n sys.exit(1)\n\n # Filter enabled servers (using Pydantic attribute access)\n enabled_servers = []\n for server_response in servers:\n # AnthropicServerResponse has a .server attribute of type AnthropicServerDetail\n server = server_response.server\n\n # Access meta attribute (Optional[Dict[str, Any]])\n # The meta field has alias \"_meta\" but is accessed via .meta attribute\n if server.meta and \"io.mcpgateway/internal\" in server.meta:\n internal_meta = server.meta[\"io.mcpgateway/internal\"]\n is_enabled = internal_meta.get(\"is_enabled\", False)\n\n if is_enabled:\n enabled_servers.append(server)\n\n logger.info(f\"Found {len(enabled_servers)} enabled servers\")\n\n if not enabled_servers:\n logger.warning(\"No enabled servers found to scan\")\n return {\n \"stats\": {\"total\": 0, \"passed\": 0, \"failed\": 0},\n \"scan_results\": [],\n \"scan_timestamp\": \"\",\n \"analyzers\": analyzers,\n }\n\n # Scan each server\n stats = {\"total\": len(enabled_servers), \"passed\": 0, \"failed\": 0}\n\n scan_results = []\n scan_timestamp = datetime.now(UTC).strftime(\"%Y-%m-%d %H:%M:%S UTC\")\n\n logger.info(\"\")\n logger.info(\"=\" * 80)\n logger.info(f\"Scanning {stats['total']} enabled servers\")\n logger.info(\"=\" * 80)\n logger.info(\"\")\n\n # Note: access_token already loaded above for RegistryClient\n\n for idx, server in enumerate(enabled_servers, 1):\n # Server is AnthropicServerDetail with direct attribute access\n server_name = server.name\n\n # Get the path from metadata (meta is Optional[Dict])\n server_path = None\n if server.meta and \"io.mcpgateway/internal\" in server.meta:\n internal_meta = server.meta[\"io.mcpgateway/internal\"]\n server_path = internal_meta.get(\"path\")\n\n if not server_path:\n logger.warning(\n f\"[{idx}/{stats['total']}] {server_name}: No path found in metadata, skipping\"\n )\n stats[\"failed\"] += 1\n scan_results.append(\n {\n \"server_name\": server_name,\n \"server_url\": \"N/A\",\n \"success\": False,\n \"is_safe\": False,\n \"critical_issues\": 0,\n \"high_severity\": 0,\n \"medium_severity\": 0,\n \"low_severity\": 0,\n \"error_message\": \"No path found in metadata\",\n }\n )\n continue\n\n # Construct the gateway proxy URL using the path and base_url\n if not server_path.endswith(\"/\"):\n server_path = server_path + \"/\"\n server_url = f\"{base_url}{server_path}mcp\"\n\n logger.info(\"-\" * 80)\n logger.info(f\"[{idx}/{stats['total']}] Scanning: {server_name}\")\n logger.info(f\"URL: {server_url}\")\n logger.info(f\"Analyzers: {analyzers}\")\n\n # Run scan with access token for authentication\n scan_result = _run_security_scan(server_url, analyzers, api_key, access_token)\n scan_result[\"server_name\"] = server_name\n scan_result[\"server_url\"] = server_url\n scan_results.append(scan_result)\n\n if scan_result[\"success\"] and scan_result[\"is_safe\"]:\n stats[\"passed\"] += 1\n else:\n stats[\"failed\"] += 1\n\n logger.info(\"\")\n\n return {\n \"stats\": stats,\n \"scan_results\": scan_results,\n \"scan_timestamp\": scan_timestamp,\n \"analyzers\": analyzers,\n }\n\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Scan all enabled MCP servers for security vulnerabilities\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Scan all servers with default YARA analyzer\n uv run python cli/scan_all_servers.py\n\n # Scan with both YARA and LLM analyzers\n export MCP_SCANNER_LLM_API_KEY=sk-your-api-key\n uv run python cli/scan_all_servers.py --analyzers yara,llm\n\n # Use specific base URL\n uv run python cli/scan_all_servers.py --base-url http://localhost\n\n # Use custom token file\n uv run python cli/scan_all_servers.py --token-file .oauth-tokens/custom.json\n\n # Production example\n uv run python cli/scan_all_servers.py \\\\\n --base-url https://registry.us-east-1.example.com \\\\\n --token-file api/.token \\\\\n --analyzers yara,llm\n\"\"\",\n )\n\n parser.add_argument(\n \"--base-url\",\n default=DEFAULT_BASE_URL,\n help=f\"Registry base URL (default: {DEFAULT_BASE_URL})\",\n )\n parser.add_argument(\n \"--token-file\",\n type=Path,\n default=DEFAULT_TOKEN_FILE,\n help=f\"Path to token file (default: {DEFAULT_TOKEN_FILE})\",\n )\n parser.add_argument(\n \"--analyzers\",\n default=DEFAULT_ANALYZERS,\n help=f\"Comma-separated list of analyzers: yara, llm, or yara,llm (default: {DEFAULT_ANALYZERS})\",\n )\n parser.add_argument(\n \"--api-key\", help=\"LLM API key (optional, can also use MCP_SCANNER_LLM_API_KEY env var)\"\n )\n parser.add_argument(\"--debug\", action=\"store_true\", help=\"Enable debug logging\")\n\n args = parser.parse_args()\n\n # Set debug level if requested\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n # Run scans\n results = _scan_all_servers(\n base_url=args.base_url,\n token_file=args.token_file,\n analyzers=args.analyzers,\n api_key=args.api_key,\n )\n\n stats = results[\"stats\"]\n scan_results = results[\"scan_results\"]\n scan_timestamp = results[\"scan_timestamp\"]\n analyzers = results[\"analyzers\"]\n\n # Generate markdown report\n logger.info(\"\")\n logger.info(\"=\" * 80)\n logger.info(\"Generating markdown report...\")\n logger.info(\"=\" * 80)\n\n markdown_report = _generate_markdown_report(\n scan_results=scan_results, stats=stats, analyzers=analyzers, scan_timestamp=scan_timestamp\n )\n\n # Save markdown report\n report_base_dir = PROJECT_ROOT / \"security_scans\"\n report_base_dir.mkdir(parents=True, exist_ok=True)\n\n # Create reports subdirectory for timestamped reports\n reports_dir = report_base_dir / \"reports\"\n reports_dir.mkdir(parents=True, exist_ok=True)\n\n # Save timestamped report in reports/ subdirectory\n timestamp_str = datetime.now(UTC).strftime(\"%Y%m%d_%H%M%S\")\n timestamped_report = reports_dir / f\"scan_report_{timestamp_str}.md\"\n\n with open(timestamped_report, \"w\") as f:\n f.write(markdown_report)\n\n # Save latest report directly in security_scans/\n latest_report = report_base_dir / \"scan_report.md\"\n with open(latest_report, \"w\") as f:\n f.write(markdown_report)\n\n logger.info(f\"Markdown report saved to: {timestamped_report}\")\n logger.info(f\"Latest report: {latest_report}\")\n\n # Print summary\n logger.info(\"\")\n logger.info(\"=\" * 80)\n logger.info(\"SCAN SUMMARY\")\n logger.info(\"=\" * 80)\n logger.info(f\"Total servers scanned: {stats['total']}\")\n logger.info(f\"Passed: {stats['passed']}\")\n logger.info(f\"Failed: {stats['failed']}\")\n logger.info(\"\")\n logger.info(\"Security scan results saved to: ./security_scans/\")\n logger.info(f\"Markdown report: {latest_report}\")\n logger.info(\"=\" * 80)\n\n # Exit with error code if any scans failed\n if stats[\"failed\"] > 0:\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/service_mgmt.sh", "content": "#!/bin/bash\n\n# DEPRECATED: This script is deprecated in favor of the Registry Management API\n# Use: uv run python api/registry_management.py OR cli/registry_cli_wrapper.py\n# See: api/README.md for documentation\n#\n# Service Management Script for MCP Gateway Registry\n# Usage: ./cli/service_mgmt.sh {add|delete|monitor|test|add-to-groups|remove-from-groups|create-group|delete-group|list-groups} [args...]\n\necho \"WARNING: This script is DEPRECATED. Please use the Registry Management API instead:\"\necho \" uv run python api/registry_management.py --help\"\necho \" OR cli/registry_cli_wrapper.py --help\"\necho \"See api/README.md for full documentation.\"\necho \"\"\n\nset -e\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m' # No Color\n\n# Unicode symbols\nCHECK_MARK=\"✓\"\nCROSS_MARK=\"✗\"\n\n# Get script directory and project root\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nPROJECT_ROOT=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Load environment variables from .env file if it exists\nif [ -f \"$PROJECT_ROOT/.env\" ]; then\n set -a # automatically export all variables\n source \"$PROJECT_ROOT/.env\"\n set +a\nfi\n\n# Gateway URL (can be overridden with GATEWAY_URL environment variable)\nGATEWAY_URL=\"${GATEWAY_URL:-http://localhost}\"\n\n# Default service name\nDEFAULT_SERVICE=\"example-server\"\n\nprint_success() {\n echo -e \"${GREEN}${CHECK_MARK} $1${NC}\"\n}\n\nprint_error() {\n echo -e \"${RED}${CROSS_MARK} $1${NC}\"\n}\n\nprint_info() {\n echo -e \"${YELLOW}ℹ $1${NC}\"\n}\n\ncheck_prerequisites() {\n print_info \"Checking prerequisites...\"\n\n # Check and refresh credentials if needed\n if ! \"$PROJECT_ROOT/credentials-provider/check_and_refresh_creds.sh\"; then\n print_error \"Failed to setup credentials\"\n exit 1\n fi\n print_success \"Credentials ready\"\n}\n\nrun_mcp_command() {\n local tool=\"$1\"\n local args=\"$2\"\n local description=\"$3\"\n\n print_info \"$description\"\n\n # Print the exact command being executed\n echo \"🔍 Executing: uv run cli/mcp_client.py --url ${GATEWAY_URL}/mcpgw/mcp call --tool $tool --args '$args'\"\n\n if output=$(cd \"$PROJECT_ROOT\" && uv run cli/mcp_client.py --url \"${GATEWAY_URL}/mcpgw/mcp\" call --tool \"$tool\" --args \"$args\" 2>&1); then\n print_success \"$description completed\"\n echo \"$output\"\n return 0\n else\n print_error \"$description failed\"\n echo \"$output\"\n return 1\n fi\n}\n\nverify_server_in_list() {\n local service_name=\"$1\"\n local should_exist=\"$2\" # \"true\" or \"false\"\n\n print_info \"Checking server in service list...\"\n\n if output=$(cd \"$PROJECT_ROOT\" && uv run cli/mcp_client.py --url \"${GATEWAY_URL}/mcpgw/mcp\" call --tool list_services --args '{}' 2>&1); then\n if echo \"$output\" | grep -q \"$service_name\"; then\n if [ \"$should_exist\" = \"true\" ]; then\n print_success \"Server found in service list\"\n echo \"$output\" | grep -A2 -B2 \"$service_name\"\n return 0\n else\n print_error \"Server still exists in service list (should be removed)\"\n return 1\n fi\n else\n if [ \"$should_exist\" = \"false\" ]; then\n print_success \"Server not found in service list (expected)\"\n return 0\n else\n print_error \"Server not found in service list\"\n return 1\n fi\n fi\n else\n print_error \"Failed to check service list\"\n echo \"$output\"\n return 1\n fi\n}\n\nverify_scopes_yml() {\n local service_name=\"$1\"\n local should_exist=\"$2\" # \"true\" or \"false\"\n\n print_info \"Checking scopes.yml files...\"\n\n # Check container scopes.yml\n local container_count\n container_count=$(docker exec mcp-gateway-registry-auth-server-1 grep -c \"$service_name\" /app/scopes.yml 2>/dev/null || echo \"0\")\n # Ensure we only get the last line if multiple lines are returned\n container_count=$(echo \"$container_count\" | tail -1)\n\n if [ \"$should_exist\" = \"true\" ] && [ \"$container_count\" -gt \"0\" ]; then\n print_success \"Server found in container scopes.yml ($container_count occurrences)\"\n elif [ \"$should_exist\" = \"false\" ] && [ \"$container_count\" -eq \"0\" ]; then\n print_success \"Server not found in container scopes.yml (expected)\"\n else\n if [ \"$should_exist\" = \"true\" ]; then\n print_error \"Server not found in container scopes.yml\"\n else\n print_error \"Server still exists in container scopes.yml ($container_count occurrences)\"\n fi\n return 1\n fi\n\n # Check host scopes.yml\n local host_count\n host_count=$(grep -c \"$service_name\" \"${HOME}/mcp-gateway/auth_server/scopes.yml\" 2>/dev/null || echo \"0\")\n # Ensure we only get the last line if multiple lines are returned\n host_count=$(echo \"$host_count\" | tail -1)\n\n if [ \"$should_exist\" = \"true\" ] && [ \"$host_count\" -gt \"0\" ]; then\n print_success \"Server found in host scopes.yml ($host_count occurrences)\"\n elif [ \"$should_exist\" = \"false\" ] && [ \"$host_count\" -eq \"0\" ]; then\n print_success \"Server not found in host scopes.yml (expected)\"\n else\n if [ \"$should_exist\" = \"true\" ]; then\n print_error \"Server not found in host scopes.yml\"\n else\n print_error \"Server still exists in host scopes.yml ($host_count occurrences)\"\n fi\n return 1\n fi\n}\n\nverify_faiss_metadata() {\n local service_name=\"$1\"\n local should_exist=\"$2\" # \"true\" or \"false\"\n\n print_info \"Checking FAISS index metadata...\"\n\n local metadata_count\n metadata_count=$(docker exec mcp-gateway-registry-registry-1 grep -c \"$service_name\" /app/registry/servers/service_index_metadata.json 2>/dev/null || echo \"0\")\n # Ensure we only get the last line if multiple lines are returned\n metadata_count=$(echo \"$metadata_count\" | tail -1)\n\n if [ \"$should_exist\" = \"true\" ] && [ \"$metadata_count\" -gt \"0\" ]; then\n print_success \"Server found in FAISS metadata ($metadata_count occurrences)\"\n elif [ \"$should_exist\" = \"false\" ] && [ \"$metadata_count\" -eq \"0\" ]; then\n print_success \"Server not found in FAISS metadata (expected)\"\n else\n if [ \"$should_exist\" = \"true\" ]; then\n print_error \"Server not found in FAISS metadata\"\n else\n print_error \"Server still exists in FAISS metadata ($metadata_count occurrences)\"\n fi\n return 1\n fi\n}\n\nparse_health_output() {\n local json_output=\"$1\"\n local service_filter=\"$2\"\n\n # Write output to temp file to avoid shell escaping issues\n local temp_file=$(mktemp)\n echo \"$json_output\" > \"$temp_file\"\n\n # Use Python to parse JSON and format output\n python3 -c \"\nimport json\nimport sys\nfrom datetime import datetime, timezone\nimport re\n\ntry:\n # Read from temp file\n with open('$temp_file', 'r') as f:\n output = f.read()\n\n # Look for the main JSON response (starts after authentication message)\n json_start = output.find('{')\n if json_start == -1:\n print('No JSON found in output')\n sys.exit(1)\n\n # Find the matching closing brace\n brace_count = 0\n json_end = json_start\n for i, char in enumerate(output[json_start:], json_start):\n if char == '{':\n brace_count += 1\n elif char == '}':\n brace_count -= 1\n if brace_count == 0:\n json_end = i + 1\n break\n\n json_text = output[json_start:json_end]\n data = json.loads(json_text)\n\n # Extract health data from structuredContent if available, otherwise from top level\n if 'structuredContent' in data:\n health_data = data['structuredContent']\n else:\n # Fallback to top level if no structuredContent\n health_data = data\n\n current_time = datetime.now(timezone.utc)\n\n print('Health Check Results:')\n print('=' * 50)\n\n for service_path, info in health_data.items():\n # Skip if filtering for specific service and this doesn't match\n if '$service_filter' and '$service_filter' not in service_path:\n continue\n\n status = info.get('status', 'unknown')\n last_checked = info.get('last_checked_iso', '')\n num_tools = info.get('num_tools', 0)\n\n # Calculate time difference\n if last_checked:\n try:\n check_time = datetime.fromisoformat(last_checked.replace('Z', '+00:00'))\n time_diff = current_time - check_time\n seconds_ago = int(time_diff.total_seconds())\n time_str = f'{seconds_ago} seconds ago'\n except:\n time_str = 'unknown time'\n else:\n time_str = 'never checked'\n\n # Format status with color indicators\n if status == 'healthy':\n status_display = '✓ healthy'\n elif status == 'unhealthy':\n status_display = '✗ unhealthy'\n elif 'auth-expired' in status:\n status_display = '⚠ healthy-auth-expired'\n else:\n status_display = f'? {status}'\n\n print(f'Service: {service_path}')\n print(f' Status: {status_display}')\n print(f' Last checked: {time_str}')\n print(f' Tools available: {num_tools}')\n print()\n\nexcept json.JSONDecodeError as e:\n print(f'Error parsing JSON: {e}')\n with open('$temp_file', 'r') as f:\n print('Raw output:')\n print(f.read())\n sys.exit(1)\nexcept Exception as e:\n print(f'Error processing health check: {e}')\n sys.exit(1)\n\"\n\n # Clean up temp file\n rm -f \"$temp_file\"\n}\n\nrun_health_check() {\n local service_name=\"$1\"\n\n print_info \"Running health check...\"\n\n if output=$(cd \"$PROJECT_ROOT\" && uv run cli/mcp_client.py --url \"${GATEWAY_URL}/mcpgw/mcp\" call --tool healthcheck --args '{}' 2>&1); then\n print_success \"Health check completed\"\n echo \"\"\n\n # Parse and display formatted output\n if ! parse_health_output \"$output\" \"$service_name\"; then\n print_error \"Failed to parse health check output\"\n echo \"Raw output:\"\n echo \"$output\"\n return 1\n fi\n return 0\n else\n print_error \"Health check failed\"\n echo \"$output\"\n return 1\n fi\n}\n\nvalidate_config() {\n local config_json=\"$1\"\n\n # Use Python to validate fields according to register_service tool spec\n python3 -c \"\nimport json\nimport sys\n\ntry:\n config = json.loads('''$config_json''')\n\n # Required fields (based on register_service tool spec)\n required_fields = ['server_name', 'path', 'proxy_pass_url']\n missing_fields = []\n\n for field in required_fields:\n if field not in config or not config[field]:\n missing_fields.append(field)\n\n if missing_fields:\n print(f'ERROR: Missing required fields in config: {missing_fields}')\n sys.exit(1)\n\n # Handle bedrock-agentcore specific URL formatting\n auth_provider = config.get('auth_provider', '')\n if auth_provider == 'bedrock-agentcore':\n # Ensure path begins and ends with '/'\n path = config['path']\n if not path.startswith('/'):\n path = '/' + path\n if not path.endswith('/'):\n path = path + '/'\n config['path'] = path\n\n # Ensure proxy_pass_url ends with '/' and does not have '/mcp' or '/mcp/' at the end\n proxy_url = config['proxy_pass_url']\n # Remove trailing '/mcp/' or '/mcp'\n if proxy_url.endswith('/mcp/'):\n proxy_url = proxy_url[:-5] # Remove '/mcp/'\n elif proxy_url.endswith('/mcp'):\n proxy_url = proxy_url[:-4] # Remove '/mcp'\n # Ensure it ends with '/'\n if not proxy_url.endswith('/'):\n proxy_url = proxy_url + '/'\n config['proxy_pass_url'] = proxy_url\n\n # Validate field types and constraints\n errors = []\n\n # server_name: must be string and non-empty\n if not isinstance(config['server_name'], str) or not config['server_name'].strip():\n errors.append('server_name must be a non-empty string')\n\n # path: must be string, start with '/', and be unique URL path prefix\n if not isinstance(config['path'], str):\n errors.append('path must be a string')\n elif not config['path'].startswith('/'):\n errors.append('path must start with \\\"/\\\"')\n elif len(config['path']) < 2:\n errors.append('path must be more than just \\\"/\\\"')\n\n # proxy_pass_url: must be string and valid URL format\n if not isinstance(config['proxy_pass_url'], str):\n errors.append('proxy_pass_url must be a string')\n elif not (config['proxy_pass_url'].startswith('http://') or config['proxy_pass_url'].startswith('https://')):\n errors.append('proxy_pass_url must start with http:// or https://')\n\n # Check for unknown fields (not part of tool spec)\n allowed_fields = {'server_name', 'path', 'proxy_pass_url', 'description', 'tags', 'num_tools', 'license', 'auth_provider', 'auth_scheme', 'supported_transports', 'headers', 'tool_list', 'repository_url', 'website_url', 'package_npm'}\n unknown_fields = set(config.keys()) - allowed_fields\n if unknown_fields:\n errors.append(f'Unknown fields not allowed by register_service tool spec: {sorted(unknown_fields)}')\n\n # Optional field validations\n if 'description' in config and config['description'] is not None:\n if not isinstance(config['description'], str):\n errors.append('description must be a string')\n\n if 'tags' in config and config['tags'] is not None:\n if not isinstance(config['tags'], list):\n errors.append('tags must be a list')\n elif not all(isinstance(tag, str) for tag in config['tags']):\n errors.append('all tags must be strings')\n\n if 'num_tools' in config and config['num_tools'] is not None:\n if not isinstance(config['num_tools'], int) or config['num_tools'] < 0:\n errors.append('num_tools must be a non-negative integer')\n\n if 'license' in config and config['license'] is not None:\n if not isinstance(config['license'], str):\n errors.append('license must be a string')\n\n if errors:\n print('ERROR: Config validation failed:')\n for error in errors:\n print(f' - {error}')\n sys.exit(1)\n\n # Extract service name from path for validation\n service_name = config['path'].lstrip('/').rstrip('/')\n\n # Output both the modified config and service name\n # First line: modified config as JSON\n # Second line: service name\n print(json.dumps(config))\n print(service_name)\n\nexcept json.JSONDecodeError as e:\n print(f'ERROR: Invalid JSON in config: {e}')\n sys.exit(1)\nexcept Exception as e:\n print(f'ERROR: Config validation failed: {e}')\n sys.exit(1)\n\"\n}\n\nadd_service() {\n local config_file=\"${1}\"\n local analyzers=\"${2:-yara}\"\n\n if [ -z \"$config_file\" ]; then\n print_error \"Usage: $0 add [analyzers]\"\n print_error \"Example: $0 add cli/examples/example-server-config.json\"\n print_error \"Example: $0 add cli/examples/example-server-config.json yara,llm\"\n exit 1\n fi\n\n if [ ! -f \"$config_file\" ]; then\n print_error \"Config file not found: $config_file\"\n print_error \"Full path searched: $(pwd)/$config_file\"\n exit 1\n fi\n\n print_info \"Loading config from: $config_file\"\n local config_json\n config_json=\"$(cat \"$config_file\")\"\n\n # Validate config and extract service name\n local validation_output service_name modified_config\n if ! validation_output=$(validate_config \"$config_json\"); then\n print_error \"Config validation failed\"\n echo \"$validation_output\" # This contains error message\n exit 1\n fi\n\n # Parse the two-line output: first line is modified config, second is service name\n modified_config=$(echo \"$validation_output\" | head -n 1)\n service_name=$(echo \"$validation_output\" | tail -n 1)\n\n # Use the modified config for registration\n config_json=\"$modified_config\"\n\n # Extract service_path from config for later use\n local service_path\n service_path=$(python3 -c \"\nimport json\nconfig = json.loads('''$config_json''')\nprint(config.get('path', ''))\n\")\n\n echo \"=== Adding Service: $service_name ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Extract proxy_pass_url for security scanning\n local proxy_pass_url\n proxy_pass_url=$(python3 -c \"\nimport json\nconfig = json.loads('''$config_json''')\nprint(config.get('proxy_pass_url', ''))\n\")\n\n # Extract headers from config if present\n local headers_json\n headers_json=$(python3 -c \"\nimport json\nconfig = json.loads('''$config_json''')\nheaders = config.get('headers', {})\nif headers:\n print(json.dumps(headers))\nelse:\n print('')\n\")\n\n # Check if LLM analyzer is requested and API key is available\n if [[ \"$analyzers\" == *\"llm\"* ]]; then\n if [ -z \"$MCP_SCANNER_LLM_API_KEY\" ] || [[ \"$MCP_SCANNER_LLM_API_KEY\" == *\"your_\"* ]] || [[ \"$MCP_SCANNER_LLM_API_KEY\" == *\"placeholder\"* ]]; then\n echo \"\"\n print_error \"LLM analyzer requested but MCP_SCANNER_LLM_API_KEY is not configured\"\n print_info \"Current value: ${MCP_SCANNER_LLM_API_KEY:-}\"\n print_info \"\"\n print_info \"Options:\"\n print_info \" 1. Add real API key to .env file: MCP_SCANNER_LLM_API_KEY=sk-...\"\n print_info \" 2. Set environment variable: export MCP_SCANNER_LLM_API_KEY=sk-...\"\n print_info \" 3. Use only YARA analyzer: $0 add $config_file yara\"\n exit 1\n fi\n fi\n\n # Run security scan\n echo \"\"\n echo \"=== Security Scan ===\"\n print_info \"Scanning server for security vulnerabilities...\"\n print_info \"Using analyzers: $analyzers\"\n\n local is_safe=\"true\"\n local scan_output=\"\"\n\n # Prepare scan URL - append /mcp if not already present\n local scan_url=\"$proxy_pass_url\"\n if [[ ! \"$scan_url\" =~ /mcp/?$ ]] && [[ ! \"$scan_url\" =~ /sse/?$ ]]; then\n # Remove trailing slash if present, then add /mcp\n scan_url=\"${scan_url%/}/mcp\"\n print_info \"Appending /mcp to scan URL: $scan_url\"\n fi\n\n # Run scan using Python CLI and capture JSON output\n # Note: Scanner exits with code 1 when unsafe, so we need to capture both success and \"failure\" cases\n local scan_exit_code=0\n local scan_cmd=\"cd \\\"$PROJECT_ROOT\\\" && uv run cli/mcp_security_scanner.py --server-url \\\"$scan_url\\\" --analyzers \\\"$analyzers\\\" --json\"\n\n # Add headers if present in config\n if [ -n \"$headers_json\" ]; then\n print_info \"Using custom headers from config for security scan\"\n scan_cmd=\"$scan_cmd --headers '$headers_json'\"\n fi\n\n scan_output=$(eval \"$scan_cmd\" 2>&1) || scan_exit_code=$?\n print_info \"scan_exit_code - $scan_exit_code\"\n\n # Exit code 0 = safe, exit code 1 = unsafe, exit code 2 = error\n if [ $scan_exit_code -eq 0 ]; then\n print_success \"Security scan passed - Server is SAFE\"\n elif [ $scan_exit_code -eq 1 ]; then\n print_error \"Security scan failed - Server has critical or high severity issues\"\n print_info \"Server will be registered but marked as UNHEALTHY with security-pending status\"\n\n # Add security-pending tag to config_json BEFORE registration\n echo \"\"\n echo \"====Adding security-pending tag to configuration====\"\n print_info \"Adding 'security-pending' tag to server configuration before registration...\"\n\n config_json=$(python3 -c \"\nimport json\nimport sys\n\ntry:\n config = json.loads('''$config_json''')\n\n # Add security-pending tag if not already present\n tags = config.get('tags', [])\n if 'security-pending' not in tags:\n tags.append('security-pending')\n config['tags'] = tags\n\n print(json.dumps(config))\n sys.exit(0)\nexcept Exception as e:\n print(f'Failed to add tag: {e}', file=sys.stderr)\n sys.exit(1)\n\")\n\n if [ $? -eq 0 ]; then\n print_success \"Added 'security-pending' tag to configuration\"\n else\n print_error \"Failed to add 'security-pending' tag to configuration\"\n exit 1\n fi\n else\n print_error \"Security scan encountered an error (exit code: $scan_exit_code)\"\n print_info \"Server will be registered but marked as UNHEALTHY with security-pending status\"\n fi\n\n echo \"\"\n\n # Register the service\n if ! run_mcp_command \"register_service\" \"$config_json\" \"Registering service\"; then\n exit 1\n fi\n\n # Verify registration\n echo \"\"\n echo \"=== Verifying Registration ===\"\n\n if ! verify_server_in_list \"$service_path\" \"true\"; then\n exit 1\n fi\n\n if ! verify_scopes_yml \"$service_name\" \"true\"; then\n exit 1\n fi\n\n if ! verify_faiss_metadata \"$service_name\" \"true\"; then\n exit 1\n fi\n\n if [ $scan_exit_code -eq 1 ]; then\n #Disabling the server\n echo \"\"\n echo \"====Disabling the server====\"\n\n # Generate JWT token for internal auth using shared SECRET_KEY\n if [ -z \"$SECRET_KEY\" ]; then\n print_error \"SECRET_KEY not set in environment - cannot disable server\"\n else\n local auth_token\n auth_token=$(python3 -c \"\nfrom registry.auth.internal import generate_internal_token\nprint(generate_internal_token(subject='cli-service-mgmt', purpose='toggle-service'))\n\" 2>/dev/null)\n\n if [ -z \"$auth_token\" ]; then\n print_error \"Failed to generate auth token - cannot disable server\"\n else\n # Call the internal toggle endpoint to set service to disabled (false)\n # Since the server was just auto-enabled during registration, we need to toggle it OFF\n print_info \"Calling toggle endpoint with: ${GATEWAY_URL}/api/internal/toggle\"\n print_info \"Service path: $service_path\"\n\n output=$(curl -s -w \"\\nHTTP_STATUS:%{http_code}\" -X POST \"${GATEWAY_URL}/api/internal/toggle\" \\\n -H \"Authorization: Bearer $auth_token\" \\\n --data-urlencode \"service_path=$service_path\" 2>&1)\n\n # Extract HTTP status code from response\n http_status=$(echo \"$output\" | grep \"HTTP_STATUS:\" | cut -d':' -f2)\n response_body=$(echo \"$output\" | sed '/HTTP_STATUS:/d')\n\n print_info \"Toggle API HTTP Status: $http_status\"\n print_info \"Toggle API Response: $response_body\"\n\n if [ \"$http_status\" = \"200\" ]; then\n print_success \"Server disabled due to failed security scan\"\n else\n print_error \"Failed to disable server - HTTP Status: $http_status\"\n print_error \"Response: $response_body\"\n fi\n print_info \"Review the security scan report before enabling this server\"\n fi\n fi\n fi\n\n # Run health check\n echo \"\"\n echo \"=== Health Check ===\"\n if ! run_health_check \"$service_name\"; then\n exit 1\n fi\n\n echo \"\"\n print_success \"Service $service_name successfully added and verified!\"\n}\n\ndelete_service() {\n local service_path=\"${1}\"\n local service_name=\"${2}\"\n\n if [ -z \"$service_path\" ] || [ -z \"$service_name\" ]; then\n print_error \"Usage: $0 delete \"\n print_error \"Example: $0 delete /example-server example-server\"\n exit 1\n fi\n\n echo \"=== Deleting Service: $service_name (path: $service_path) ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Remove the service\n if ! run_mcp_command \"remove_service\" \"{\\\"service_path\\\": \\\"$service_path\\\"}\" \"Removing service\"; then\n exit 1\n fi\n\n # Verify deletion\n echo \"\"\n echo \"=== Verifying Deletion ===\"\n\n if ! verify_server_in_list \"$service_path\" \"false\"; then\n exit 1\n fi\n\n if ! verify_scopes_yml \"$service_name\" \"false\"; then\n exit 1\n fi\n\n if ! verify_faiss_metadata \"$service_name\" \"false\"; then\n exit 1\n fi\n\n echo \"\"\n print_success \"Service $service_name successfully deleted and verified!\"\n}\n\ntest_service() {\n local config_file=\"${1}\"\n\n if [ -z \"$config_file\" ]; then\n print_error \"Usage: $0 test \"\n print_error \"Example: $0 test cli/examples/example-server-config.json\"\n exit 1\n fi\n\n if [ ! -f \"$config_file\" ]; then\n print_error \"Config file not found: $config_file\"\n print_error \"Full path searched: $(pwd)/$config_file\"\n exit 1\n fi\n\n print_info \"Loading config from: $config_file\"\n local config_json\n config_json=\"$(cat \"$config_file\")\"\n\n # Validate config and extract service info\n local validation_output service_name modified_config\n if ! validation_output=$(validate_config \"$config_json\"); then\n print_error \"Config validation failed\"\n echo \"$validation_output\" # This contains error message\n exit 1\n fi\n\n # Parse the two-line output: first line is modified config, second is service name\n modified_config=$(echo \"$validation_output\" | head -n 1)\n service_name=$(echo \"$validation_output\" | tail -n 1)\n\n # Use the modified config\n config_json=\"$modified_config\"\n\n # Extract description and tags for testing\n local description tags_json\n description=$(python3 -c \"\nimport json\nconfig = json.loads('''$config_json''')\nprint(config.get('description', ''))\n\")\n tags_json=$(python3 -c \"\nimport json\nconfig = json.loads('''$config_json''')\ntags = config.get('tags', [])\nprint(json.dumps(tags))\n\")\n\n echo \"=== Testing Service: $service_name ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Test intelligent tool finder with description\n if [ -n \"$description\" ]; then\n print_info \"Testing search with description: \\\"$description\\\"\"\n if ! run_mcp_command \"intelligent_tool_finder\" \"{\\\"natural_language_query\\\": \\\"$description\\\"}\" \"Searching with description\"; then\n print_error \"Failed to search with description\"\n else\n print_success \"Search with description completed\"\n fi\n echo \"\"\n fi\n\n # Test intelligent tool finder with tags only\n if [ \"$tags_json\" != \"[]\" ]; then\n print_info \"Testing search with tags: $tags_json\"\n if ! run_mcp_command \"intelligent_tool_finder\" \"{\\\"tags\\\": $tags_json}\" \"Searching with tags\"; then\n print_error \"Failed to search with tags\"\n else\n print_success \"Search with tags completed\"\n fi\n echo \"\"\n fi\n\n # Test combined search\n if [ -n \"$description\" ] && [ \"$tags_json\" != \"[]\" ]; then\n print_info \"Testing combined search with description and tags\"\n if ! run_mcp_command \"intelligent_tool_finder\" \"{\\\"natural_language_query\\\": \\\"$description\\\", \\\"tags\\\": $tags_json}\" \"Combined search\"; then\n print_error \"Failed combined search\"\n else\n print_success \"Combined search completed\"\n fi\n echo \"\"\n fi\n\n echo \"\"\n print_success \"Service testing completed!\"\n}\n\n\nmonitor_services() {\n local config_file=\"${1}\"\n local service_name=\"\"\n\n if [ -n \"$config_file\" ]; then\n if [ ! -f \"$config_file\" ]; then\n print_error \"Config file not found: $config_file\"\n exit 1\n fi\n\n print_info \"Loading config from: $config_file\"\n local config_json\n config_json=\"$(cat \"$config_file\")\"\n\n # Validate config and extract service name\n local validation_output modified_config\n if ! validation_output=$(validate_config \"$config_json\"); then\n print_error \"Config validation failed\"\n echo \"$validation_output\" # This contains error message\n exit 1\n fi\n\n # Parse the two-line output: first line is modified config, second is service name\n modified_config=$(echo \"$validation_output\" | head -n 1)\n service_name=$(echo \"$validation_output\" | tail -n 1)\n\n echo \"=== Monitoring Service: $service_name ===\"\n else\n echo \"=== Monitoring All Services ===\"\n fi\n\n # Check prerequisites\n check_prerequisites\n\n # Run health check\n if ! run_health_check \"$service_name\"; then\n exit 1\n fi\n\n echo \"\"\n print_success \"Monitoring completed!\"\n}\n\nscan_server_security() {\n local server_url=\"$1\"\n local analyzers=\"${2:-yara}\"\n local api_key=\"${3:-}\"\n local headers=\"${4:-}\"\n\n if [ -z \"$server_url\" ]; then\n print_error \"Usage: $0 scan [analyzers] [api-key] [headers]\"\n print_error \"Example: $0 scan https://mcp.deepwki.com/mcp\"\n print_error \"Example: $0 scan https://mcp.deepwki.com/mcp yara,llm\"\n print_error \"Example: $0 scan https://mcp.deepwki.com/mcp yara,llm \\$MCP_SCANNER_LLM_API_KEY\"\n print_error \"Example: $0 scan https://mcp.deepwki.com/mcp yara '' '{\\\"X-Authorization\\\": \\\"token123\\\"}'\"\n print_error \"\"\n print_error \"Note: For LLM analyzer, set MCP_SCANNER_LLM_API_KEY environment variable\"\n print_error \" or pass API key as third argument\"\n print_error \"Note: For custom headers, pass JSON string as fourth argument\"\n exit 1\n fi\n\n echo \"=== Security Scan: $server_url ===\"\n\n # Check if LLM analyzer is requested and API key is available\n if [[ \"$analyzers\" == *\"llm\"* ]]; then\n # Check both environment variable and CLI argument\n local key_to_check=\"${api_key:-$MCP_SCANNER_LLM_API_KEY}\"\n if [ -z \"$key_to_check\" ] || [[ \"$key_to_check\" == *\"your_\"* ]] || [[ \"$key_to_check\" == *\"placeholder\"* ]]; then\n echo \"\"\n print_error \"LLM analyzer requested but MCP_SCANNER_LLM_API_KEY is not configured\"\n print_info \"Current value: ${MCP_SCANNER_LLM_API_KEY:-}\"\n print_info \"\"\n print_info \"Options:\"\n print_info \" 1. Add real API key to .env file: MCP_SCANNER_LLM_API_KEY=sk-...\"\n print_info \" 2. Set environment variable: export MCP_SCANNER_LLM_API_KEY=sk-...\"\n print_info \" 3. Pass API key as argument: $0 scan $server_url $analyzers sk-your-key\"\n print_info \" 4. Use only YARA analyzer: $0 scan $server_url yara\"\n return 1\n fi\n fi\n\n # Build command\n local cmd=\"cd \\\"$PROJECT_ROOT\\\" && uv run cli/mcp_security_scanner.py --server-url \\\"$server_url\\\" --analyzers \\\"$analyzers\\\"\"\n\n # Add API key if provided\n if [ -n \"$api_key\" ]; then\n cmd=\"$cmd --api-key \\\"$api_key\\\"\"\n fi\n\n # Add headers if provided\n if [ -n \"$headers\" ]; then\n cmd=\"$cmd --headers '$headers'\"\n fi\n\n print_info \"Running security scan...\"\n print_info \"Analyzers: $analyzers\"\n\n # Run scan and capture exit code\n if eval \"$cmd\"; then\n print_success \"Security scan completed - Server is SAFE\"\n return 0\n else\n local exit_code=$?\n if [ $exit_code -eq 1 ]; then\n print_error \"Security scan completed - Server is UNSAFE (has critical or high severity issues)\"\n else\n print_error \"Security scan failed with error code $exit_code\"\n fi\n return $exit_code\n fi\n}\n\nshow_usage() {\n echo \"Usage: $0 {add|delete|monitor|test|scan|add-to-groups|remove-from-groups|create-group|delete-group|list-groups} [args...]\"\n echo \"\"\n echo \"Service Commands:\"\n echo \" add [analyzers] - Add a service using JSON config and verify registration\"\n echo \" analyzers: yara (default), llm, or yara,llm\"\n echo \" delete - Delete a service by path and name\"\n echo \" monitor [config-file] - Run health check (all services or specific service from config)\"\n echo \" test - Test service searchability using intelligent_tool_finder\"\n echo \" scan [analyzers] [api-key] - Run security scan on MCP server\"\n echo \" analyzers: yara (default), llm, or yara,llm\"\n echo \"\"\n echo \"Server-to-Group Commands:\"\n echo \" add-to-groups - Add server to specific scopes groups (comma-separated)\"\n echo \" remove-from-groups - Remove server from specific scopes groups (comma-separated)\"\n echo \"\"\n echo \"Group Management Commands:\"\n echo \" create-group [description] - Create a new group in Keycloak and scopes.yml\"\n echo \" delete-group - Delete a group from Keycloak and scopes.yml\"\n echo \" list-groups - List all groups with synchronization status\"\n echo \"\"\n echo \"Config File Requirements:\"\n echo \" Required fields: server_name, path, proxy_pass_url\"\n echo \" Optional fields: description, tags, num_tools, license,\"\n echo \" auth_provider, auth_scheme, supported_transports, headers, tool_list\"\n echo \" Constraints:\"\n echo \" - path must start with '/' and be more than just '/'\"\n echo \" - proxy_pass_url must start with http:// or https://\"\n echo \" - server_name must be non-empty string\"\n echo \" - tags must be array of strings\"\n echo \" - num_tools must be a non-negative integer\"\n echo \" - supported_transports must be array of strings\"\n echo \" - headers must be array of objects\"\n echo \" - tool_list must be array of objects\"\n echo \"\"\n echo \"Examples:\"\n echo \" # Service operations\"\n echo \" $0 add cli/examples/example-server-config.json # Add with default YARA analyzer\"\n echo \" export MCP_SCANNER_LLM_API_KEY=sk-...\"\n echo \" $0 add cli/examples/example-server-config.json yara,llm # Add with both analyzers\"\n echo \" $0 add cli/examples/example-server-config.json llm # Add with only LLM analyzer\"\n echo \" $0 delete /example-server example-server\"\n echo \" $0 monitor # All services\"\n echo \" $0 monitor cli/examples/example-server-config.json # Specific service\"\n echo \" $0 test cli/examples/example-server-config.json # Test searchability\"\n echo \"\"\n echo \" # Security scanning\"\n echo \" $0 scan https://mcp.deepwki.com/mcp # Security scan with default YARA\"\n echo \" export MCP_SCANNER_LLM_API_KEY=sk-...\"\n echo \" $0 scan https://mcp.deepwki.com/mcp yara,llm # Scan with both analyzers (uses env var)\"\n echo \" $0 scan https://mcp.deepwki.com/mcp llm sk-... # Scan with only LLM (pass API key directly)\"\n echo \" $0 scan https://mcp.deepwki.com/mcp yara '' '{\\\"X-Authorization\\\": \\\"token\\\"}' # Scan with custom headers\"\n echo \"\"\n echo \" # Server-to-group operations\"\n echo \" $0 add-to-groups example-server 'mcp-servers-restricted/read,mcp-servers-restricted/execute'\"\n echo \" $0 remove-from-groups example-server 'mcp-servers-restricted/read,mcp-servers-restricted/execute'\"\n echo \"\"\n echo \" # Group management operations\"\n echo \" $0 create-group mcp-servers-finance/read 'Finance team read access'\"\n echo \" $0 delete-group mcp-servers-finance/read\"\n echo \" $0 list-groups\"\n}\n\nadd_to_groups() {\n local server_name=\"$1\"\n local groups=\"$2\"\n\n if [ -z \"$server_name\" ] || [ -z \"$groups\" ]; then\n print_error \"Usage: $0 add-to-groups \"\n print_error \"Example: $0 add-to-groups example-server 'mcp-servers-restricted/read,mcp-servers-restricted/execute'\"\n exit 1\n fi\n\n echo \"=== Adding Server to Scopes Groups: $server_name ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Convert comma-separated groups to JSON array format\n local groups_json\n groups_json=$(echo \"$groups\" | sed 's/,/\",\"/g' | sed 's/^/\"/' | sed 's/$/\"/')\n groups_json=\"[$groups_json]\"\n\n print_info \"Adding server '$server_name' to groups: $groups\"\n\n # Call the MCP tool\n local response\n if response=$(run_mcp_command \"add_server_to_scopes_groups\" \"{\\\"server_name\\\": \\\"$server_name\\\", \\\"group_names\\\": $groups_json}\"); then\n # Check if the response indicates success\n if echo \"$response\" | grep -q '\"success\": true'; then\n print_success \"Server successfully added to groups\"\n\n # Extract and display details\n local server_path\n server_path=$(echo \"$response\" | grep -o '\"server_path\": \"[^\"]*\"' | cut -d'\"' -f4)\n if [ -n \"$server_path\" ]; then\n print_info \"Server path: $server_path\"\n fi\n\n print_info \"Groups: $groups\"\n print_success \"Scopes groups updated and auth server reloaded\"\n else\n # Extract error message if available\n local error_msg\n error_msg=$(echo \"$response\" | grep -o '\"error\": \"[^\"]*\"' | cut -d'\"' -f4)\n if [ -n \"$error_msg\" ]; then\n print_error \"Failed to add server to groups: $error_msg\"\n else\n print_error \"Failed to add server to groups (unknown error)\"\n echo \"Response: $response\"\n fi\n exit 1\n fi\n else\n print_error \"Failed to call add_server_to_scopes_groups tool\"\n exit 1\n fi\n\n echo \"\"\n print_success \"Add to groups operation completed!\"\n}\n\nremove_from_groups() {\n local server_name=\"$1\"\n local groups=\"$2\"\n\n if [ -z \"$server_name\" ] || [ -z \"$groups\" ]; then\n print_error \"Usage: $0 remove-from-groups \"\n print_error \"Example: $0 remove-from-groups example-server 'mcp-servers-restricted/read,mcp-servers-restricted/execute'\"\n exit 1\n fi\n\n echo \"=== Removing Server from Scopes Groups: $server_name ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Convert comma-separated groups to JSON array format\n local groups_json\n groups_json=$(echo \"$groups\" | sed 's/,/\",\"/g' | sed 's/^/\"/' | sed 's/$/\"/')\n groups_json=\"[$groups_json]\"\n\n print_info \"Removing server '$server_name' from groups: $groups\"\n\n # Call the MCP tool\n local response\n if response=$(run_mcp_command \"remove_server_from_scopes_groups\" \"{\\\"server_name\\\": \\\"$server_name\\\", \\\"group_names\\\": $groups_json}\"); then\n # Check if the response indicates success\n if echo \"$response\" | grep -q '\"success\": true'; then\n print_success \"Server successfully removed from groups\"\n\n # Extract and display details\n local server_path\n server_path=$(echo \"$response\" | grep -o '\"server_path\": \"[^\"]*\"' | cut -d'\"' -f4)\n if [ -n \"$server_path\" ]; then\n print_info \"Server path: $server_path\"\n fi\n\n print_info \"Groups: $groups\"\n print_success \"Scopes groups updated and auth server reloaded\"\n else\n # Extract error message if available\n local error_msg\n error_msg=$(echo \"$response\" | grep -o '\"error\": \"[^\"]*\"' | cut -d'\"' -f4)\n if [ -n \"$error_msg\" ]; then\n print_error \"Failed to remove server from groups: $error_msg\"\n else\n print_error \"Failed to remove server from groups (unknown error)\"\n echo \"Response: $response\"\n fi\n exit 1\n fi\n else\n print_error \"Failed to call remove_server_from_scopes_groups tool\"\n exit 1\n fi\n\n echo \"\"\n print_success \"Remove from groups operation completed!\"\n}\n\n\ncreate_group() {\n local group_name=\"$1\"\n local description=\"${2:-}\"\n\n if [ -z \"$group_name\" ]; then\n print_error \"Group name is required\"\n echo \"Usage: $0 create-group [description]\"\n exit 1\n fi\n\n echo \"=== Creating Group: $group_name ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Prepare arguments for create_group MCP tool\n local args=\"{\\\"group_name\\\": \\\"$group_name\\\"\"\n if [ -n \"$description\" ]; then\n # Escape description for JSON\n local escaped_desc=$(echo \"$description\" | sed 's/\"/\\\\\"/g')\n args=\"$args, \\\"description\\\": \\\"$escaped_desc\\\"\"\n fi\n args=\"$args}\"\n\n # Call create_group MCP tool\n if ! run_mcp_command \"create_group\" \"$args\" \"Creating group '$group_name'\"; then\n print_error \"Failed to create group\"\n exit 1\n fi\n\n # Verify in scopes.yml (container)\n print_info \"Verifying group in container scopes.yml...\"\n if docker exec mcp-gateway-registry-auth-server-1 cat /app/scopes.yml | grep -q \"^$group_name:\"; then\n print_success \"Group found in container scopes.yml\"\n else\n print_error \"Group NOT found in container scopes.yml\"\n fi\n\n # Verify in scopes.yml (host)\n local host_scopes_file=\"$HOME/mcp-gateway/auth_server/scopes.yml\"\n if [ -f \"$host_scopes_file\" ]; then\n print_info \"Verifying group in host scopes.yml...\"\n if grep -q \"^$group_name:\" \"$host_scopes_file\"; then\n print_success \"Group found in host scopes.yml\"\n else\n print_error \"Group NOT found in host scopes.yml\"\n fi\n fi\n\n echo \"\"\n print_success \"Create group operation completed!\"\n}\n\n\ndelete_group() {\n local group_name=\"$1\"\n\n if [ -z \"$group_name\" ]; then\n print_error \"Group name is required\"\n echo \"Usage: $0 delete-group \"\n exit 1\n fi\n\n echo \"=== Deleting Group: $group_name ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Prepare arguments for delete_group MCP tool\n local args=\"{\\\"group_name\\\": \\\"$group_name\\\"}\"\n\n # Call delete_group MCP tool\n if ! run_mcp_command \"delete_group\" \"$args\" \"Deleting group '$group_name'\"; then\n print_error \"Failed to delete group\"\n exit 1\n fi\n\n # Verify removal from scopes.yml (container)\n print_info \"Verifying group removal from container scopes.yml...\"\n if docker exec mcp-gateway-registry-auth-server-1 cat /app/scopes.yml | grep -q \"^$group_name:\"; then\n print_error \"Group still found in container scopes.yml\"\n else\n print_success \"Group removed from container scopes.yml\"\n fi\n\n # Verify removal from scopes.yml (host)\n local host_scopes_file=\"$HOME/mcp-gateway/auth_server/scopes.yml\"\n if [ -f \"$host_scopes_file\" ]; then\n print_info \"Verifying group removal from host scopes.yml...\"\n if grep -q \"^$group_name:\" \"$host_scopes_file\"; then\n print_error \"Group still found in host scopes.yml\"\n else\n print_success \"Group removed from host scopes.yml\"\n fi\n fi\n\n echo \"\"\n print_success \"Delete group operation completed!\"\n}\n\n\nlist_groups() {\n echo \"=== Listing All Groups ===\"\n\n # Check prerequisites\n check_prerequisites\n\n # Call list_groups MCP tool\n local args=\"{}\"\n\n print_info \"Fetching groups from Keycloak and scopes.yml...\"\n\n if output=$(cd \"$PROJECT_ROOT\" && uv run cli/mcp_client.py --url \"${GATEWAY_URL}/mcpgw/mcp\" call --tool list_groups --args \"$args\" 2>&1); then\n print_success \"Groups retrieved successfully\"\n echo \"\"\n echo \"$output\"\n else\n print_error \"Failed to list groups\"\n echo \"$output\"\n exit 1\n fi\n\n echo \"\"\n print_success \"List groups operation completed!\"\n}\n\n\n# Main script logic\ncase \"${1:-}\" in\n add)\n add_service \"$2\" \"$3\"\n ;;\n delete)\n delete_service \"$2\" \"$3\"\n ;;\n monitor)\n monitor_services \"$2\"\n ;;\n test)\n test_service \"$2\"\n ;;\n scan)\n scan_server_security \"$2\" \"$3\" \"$4\" \"$5\"\n ;;\n add-to-groups)\n add_to_groups \"$2\" \"$3\"\n ;;\n remove-from-groups)\n remove_from_groups \"$2\" \"$3\"\n ;;\n create-group)\n create_group \"$2\" \"$3\"\n ;;\n delete-group)\n delete_group \"$2\"\n ;;\n list-groups)\n list_groups\n ;;\n *)\n show_usage\n exit 1\n ;;\nesac" }, { "path": "cli/src/agent/agentRunner.ts", "content": "import { anthropicTools, buildTaskContext, executeMappedTool, mapToolCall } from \"./tools.js\";\nimport type { TaskContext } from \"../tasks/types.js\";\nimport { sendMessage, getDefaultProvider, getDefaultModel, type ModelProvider, type TokenUsage } from \"./modelClient.js\";\n\nexport interface AgentMessage {\n role: \"user\" | \"assistant\" | \"system\";\n content: string;\n}\n\nexport interface AgentConfig {\n gatewayUrl: string;\n gatewayBaseUrl: string;\n gatewayToken?: string;\n backendToken?: string;\n model?: string;\n provider?: ModelProvider;\n}\n\nexport interface AgentResult {\n messages: AgentMessage[];\n toolOutputs: Array<{ name: string; output: string; isError?: boolean }>;\n tokenUsage?: TokenUsage;\n}\n\nconst DEFAULT_PROVIDER = getDefaultProvider();\nconst DEFAULT_MODEL = getDefaultModel(DEFAULT_PROVIDER);\n\ntype ConversationEntry = {\n role: string;\n content: any;\n tool_use_id?: string;\n};\n\nexport async function runAgentTurn(history: AgentMessage[], config: AgentConfig): Promise {\n const provider = config.provider ?? DEFAULT_PROVIDER;\n const model = config.model ?? DEFAULT_MODEL;\n\n // Fetch registry version\n let registryVersion: string | undefined;\n try {\n const versionResponse = await fetch(`${config.gatewayBaseUrl}/api/version`);\n if (versionResponse.ok) {\n const versionData = await versionResponse.json();\n registryVersion = versionData.version;\n }\n } catch (err) {\n // Silently fail if version fetch fails\n }\n\n const systemMessages = history.filter((msg) => msg.role === \"system\").map((msg) => msg.content);\n const systemPrompt = [buildSystemPrompt(registryVersion), ...systemMessages].join(\"\\n\\n\");\n\n const messages = history\n .filter((msg) => msg.role === \"user\" || msg.role === \"assistant\")\n .map((msg) => ({ role: msg.role, content: msg.content })) as ConversationEntry[];\n\n const context: TaskContext = buildTaskContext(config.gatewayUrl, config.gatewayBaseUrl, config.gatewayToken, config.backendToken);\n\n const finalMessages: AgentMessage[] = [];\n const toolOutputs: Array<{ name: string; output: string; isError?: boolean }> = [];\n\n // Track cumulative token usage across all turns\n let totalInputTokens = 0;\n let totalOutputTokens = 0;\n\n let toolIteration = 0;\n let conversation: ConversationEntry[] = [...messages];\n if (conversation.length === 0) {\n conversation.push({ role: \"user\", content: history.filter((msg) => msg.role !== \"system\").map((msg) => msg.content).join(\"\\n\") || \"Hello.\" });\n }\n\n while (toolIteration < 25) {\n const response = await sendMessage(provider, {\n model,\n system: systemPrompt,\n messages: conversation,\n max_tokens: 16384,\n tools: anthropicTools\n });\n\n // Accumulate token usage from this turn\n if (response.usage) {\n totalInputTokens += response.usage.input_tokens;\n totalOutputTokens += response.usage.output_tokens;\n }\n\n const outputBlocks = (response.content ?? []) as any[];\n const toolCalls = outputBlocks.filter((block) => block.type === \"tool_use\");\n const textBlocks = outputBlocks.filter((block) => block.type === \"text\");\n\n if (toolCalls.length === 0) {\n const content = textBlocks.map((block) => (block.type === \"text\" ? block.text : \"\")).join(\"\\n\");\n finalMessages.push({ role: \"assistant\", content });\n break;\n }\n\n const assistantMessage: ConversationEntry = { role: \"assistant\", content: outputBlocks };\n conversation = [...conversation, assistantMessage];\n\n for (const call of toolCalls) {\n const invocation = mapToolCall(call);\n const result = await executeMappedTool(invocation, config.gatewayUrl, context);\n toolOutputs.push({ name: call.name, output: result.output, isError: result.isError });\n conversation = [\n ...conversation,\n {\n role: \"user\",\n content: [\n {\n type: \"tool_result\",\n tool_use_id: call.id,\n content: result.output\n }\n ]\n }\n ];\n }\n\n toolIteration += 1;\n }\n\n if (toolIteration >= 25) {\n finalMessages.push({ role: \"assistant\", content: \"Reached tool usage limit without final response.\" });\n }\n\n // Create token usage summary\n const tokenUsage: TokenUsage | undefined = (totalInputTokens > 0 || totalOutputTokens > 0) ? {\n input_tokens: totalInputTokens,\n output_tokens: totalOutputTokens,\n total_tokens: totalInputTokens + totalOutputTokens\n } : undefined;\n\n return { messages: finalMessages, toolOutputs, tokenUsage };\n}\n\nfunction buildSystemPrompt(registryVersion?: string): string {\n const versionInfo = registryVersion ? `\n\n\nYou are connected to MCP Gateway Registry version ${registryVersion}.\n\nIMPORTANT: When users ask about versions or \"what version\":\n- The Registry version is: ${registryVersion}\n- MCP Gateway servers (mcpgw, currenttime, etc.) may have their own versions (often 1.0.0)\n- Always clarify which component's version you're referring to\n- The Registry is the central service managing all MCP servers\n\n` : '';\n\n return `You are the MCP Registry Assistant, an AI assistant with direct access to MCP (Model Context Protocol) Registry tools.${versionInfo}\n\n\nYou have access to powerful tools for managing and interacting with MCP servers:\n\n\nCall MCP gateway commands directly:\n- ping: Check connectivity to MCP servers\n- list: List available MCP tools and resources\n- call: Execute specific MCP tools with arguments\n- init: Initialize new MCP connections\n\n\n\nExecute administrative tasks via slash commands:\n- Service management (add, remove, configure servers)\n- Import servers from registries\n- User and access management\n- System diagnostics and health checks\n\nCRITICAL: When providing server configuration examples, the field name MUST be \\`proxy_pass_url\\` (with underscores).\n\n\n\nExecute shell commands for system diagnostics, debugging, and operations:\n- Read files and tokens: \\`cat /path/to/file.json\\`\n- Debug credentials and authentication: Decode JWT tokens, check group membership\n- Execute any bash command with full output capture\n\nCRITICAL USAGE NOTES:\n- Use this to read and inspect token files, JSON configs, and logs\n- Decode JWT tokens by extracting the payload (middle section) and base64 decoding\n- Parse JSON using \\`jq\\` for filtering and analysis\n- This is essential for diagnosing authentication, authorization, and group membership issues\n\nEXAMPLES:\n- \\`cat .oauth-tokens/ingress.json | jq '.access_token'\\` - Extract JWT token\n- \\`cat .oauth-tokens/ingress.json | jq -r '.access_token' | cut -d'.' -f2 | base64 -d | jq\\` - Decode JWT payload to see claims and groups\n- \\`ls -la /path/to/directory\\` - List files and directories\n\n\n\nSearch and read project documentation:\n- Search by keywords: Use search_query parameter\n- Read specific file: Use file_path parameter (e.g., 'auth.md', 'complete-setup-guide.md')\n- List all docs: Call with no parameters\n\nWhen to use: When users ask about features, setup, configuration, authentication, troubleshooting, or any project-related questions. Use this tool to find relevant documentation and provide accurate answers based on the docs content.\n\nIMPORTANT: When answering questions based on documentation, ALWAYS include the specific section/heading from the markdown file that you're referencing. Format it as:\n\n**Source:** \\`filename.md\\` - Section Name\n\nThis helps users know exactly where the information comes from and allows them to read more context if needed.\n\n\n\n\n\nWhen users ask who you are or about your identity (e.g., \"who are you?\", \"are you Claude?\"):\n- Respond: \"I am an assistant to MCP Registry, here to help you manage and interact with MCP servers.\"\n- Keep it brief and redirect focus to how you can help them\n- Don't elaborate on underlying models or capabilities unless specifically asked\n\n\n\nBefore responding, always think through:\n1. What is the user really asking?\n2. Do I need to use tools to answer this?\n3. What's the best way to present this information?\n\n\n\n- Use tools whenever the user needs to perform actions or needs current information\n- Call tools with precise, correct parameters\n- After tool execution, synthesize and summarize results in a user-friendly way\n- CRITICAL: Do NOT show raw tool output to users unless there's an error\n- Only include raw tool output when debugging errors or when explicitly requested\n- If a tool fails, explain what went wrong, show the error output, and suggest alternatives\n\n\n\nALWAYS format your responses as clean, well-structured markdown:\n\nCRITICAL FIELD NAME: When showing server configurations, always use \\`proxy_pass_url\\` (snake_case with underscores), never \\`proxypassurl\\` or \\`proxyPassUrl\\`.\n\n1. Use clear headings (##, ###) to organize information\n2. Use bullet points (•, -, *) for lists\n3. Use numbered lists for sequential steps\n4. Wrap all file paths, commands, tool names, and technical terms in backticks: \\`like this\\`\n5. For JSON output, ALWAYS pretty-print with proper indentation:\n \\`\\`\\`json\n {\n \"key\": \"value\",\n \"nested\": {\n \"data\": \"here\"\n }\n }\n \\`\\`\\`\n6. For code blocks, use triple backticks with language identifier\n7. Use **bold** for emphasis on key points\n8. Use > blockquotes for important notes or warnings\n\nExample of well-formatted output:\n## How to Add a Server\n\nFollow these steps:\n\n1. Create your config file at \\`config.json\\`\n2. Run the command: \\`/service add configPath=config.json\\`\n3. Verify with: \\`/service monitor\\`\n\n**Sample Configuration:**\n\\`\\`\\`json\n{\n \"server_name\": \"Cloudflare Documentation MCP Server\",\n \"description\": \"Search Cloudflare documentation and get migration guides\",\n \"path\": \"/cloudflare-docs\",\n \"proxy_pass_url\": \"https://docs.mcp.cloudflare.com/mcp\",\n \"supported_transports\": [\"streamable-http\"]\n}\n\\`\\`\\`\n\nIMPORTANT: Always use \\`proxy_pass_url\\` (with underscores), NOT \\`proxypassurl\\` or \\`proxyPassUrl\\`.\n\n> **Note:** Ensure your server is running before adding it to the registry.\n\n\n\n- Be comprehensive but concise\n- Provide complete information - don't truncate explanations\n- Include all relevant details, examples, and steps\n- Anticipate follow-up questions and address them proactively\n- Use clear, professional language\n- Format everything for easy reading in a terminal\n- NEVER use emojis in your responses - keep all output text-only\n\n\n\n- Never expose raw tokens, secrets, or credentials\n- Redact sensitive information from outputs\n- Warn users about potentially destructive operations\n\n\n\n\nWhen users ask about project features, setup, or configuration, use the read_docs tool to find relevant documentation. The project contains comprehensive documentation covering:\n- Authentication and authorization (Keycloak, JWT, OAuth)\n- Service management and deployment\n- MCP server integration\n- Configuration and setup guides\n- Troubleshooting and FAQ\n\n\nRemember: You are a conversational AI assistant that helps users interact with MCP tools through natural language. Keep responses:\n- Concise and friendly (avoid verbose explanations unless asked)\n- Well-formatted for terminal display\n- Action-oriented (discover and use tools proactively when appropriate)\n- Conversational (chat naturally, not like a command interpreter)\n`;\n}\n" }, { "path": "cli/src/agent/anthropicClient.ts", "content": "import Anthropic from \"@anthropic-ai/sdk\";\n\nlet cachedClient: Anthropic | null = null;\n\nexport function getAnthropicClient(): Anthropic {\n if (cachedClient) {\n return cachedClient;\n }\n\n const apiKey = process.env.ANTHROPIC_API_KEY;\n if (!apiKey) {\n throw new Error(\"ANTHROPIC_API_KEY is not set. Please export it before using the agent mode.\");\n }\n\n cachedClient = new Anthropic({apiKey});\n return cachedClient;\n}\n" }, { "path": "cli/src/agent/bedrockClient.ts", "content": "import { BedrockRuntimeClient } from \"@aws-sdk/client-bedrock-runtime\";\n\nlet cachedClient: BedrockRuntimeClient | null = null;\n\nexport function getBedrockClient(): BedrockRuntimeClient {\n if (cachedClient) {\n return cachedClient;\n }\n\n // AWS SDK will automatically use credentials from environment variables:\n // AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN\n // Or from ~/.aws/credentials or EC2/ECS instance metadata\n const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || \"us-east-1\";\n\n // Support for explicit profile\n const profile = process.env.AWS_PROFILE;\n\n const clientConfig: any = {\n region\n };\n\n // If a profile is specified, let the SDK handle it\n if (profile) {\n // The AWS SDK will automatically load credentials from the profile\n clientConfig.profile = profile;\n }\n\n cachedClient = new BedrockRuntimeClient(clientConfig);\n\n return cachedClient;\n}\n" }, { "path": "cli/src/agent/modelClient.ts", "content": "import { InvokeModelCommand } from \"@aws-sdk/client-bedrock-runtime\";\nimport { getBedrockClient } from \"./bedrockClient.js\";\nimport { getAnthropicClient } from \"./anthropicClient.js\";\n\nexport type ModelProvider = \"bedrock\" | \"anthropic\";\n\nexport interface MessageRequest {\n model: string;\n system: string;\n messages: any[];\n max_tokens: number;\n tools: any[];\n}\n\nexport interface TokenUsage {\n input_tokens: number;\n output_tokens: number;\n total_tokens: number;\n}\n\nexport interface MessageResponse {\n content: any[];\n stop_reason?: string;\n usage?: TokenUsage;\n}\n\nexport async function sendMessage(\n provider: ModelProvider,\n request: MessageRequest\n): Promise {\n if (provider === \"bedrock\") {\n return sendBedrockMessage(request);\n } else {\n return sendAnthropicMessage(request);\n }\n}\n\nasync function sendBedrockMessage(request: MessageRequest): Promise {\n try {\n const client = getBedrockClient();\n\n // Prepare the request body for Bedrock\n const body = {\n anthropic_version: \"bedrock-2023-05-31\",\n max_tokens: request.max_tokens,\n system: request.system,\n messages: request.messages,\n tools: request.tools\n };\n\n const command = new InvokeModelCommand({\n modelId: request.model,\n contentType: \"application/json\",\n accept: \"application/json\",\n body: JSON.stringify(body)\n });\n\n const response = await client.send(command);\n const responseBody = JSON.parse(new TextDecoder().decode(response.body));\n\n // Extract token usage from Bedrock response\n const usage: TokenUsage | undefined = responseBody.usage ? {\n input_tokens: responseBody.usage.input_tokens || 0,\n output_tokens: responseBody.usage.output_tokens || 0,\n total_tokens: (responseBody.usage.input_tokens || 0) + (responseBody.usage.output_tokens || 0)\n } : undefined;\n\n return {\n content: responseBody.content || [],\n stop_reason: responseBody.stop_reason,\n usage\n };\n } catch (error: any) {\n // Provide helpful error messages for common Bedrock issues\n if (error.name === \"AccessDeniedException\") {\n throw new Error(\n \"Amazon Bedrock access denied. Ensure your IAM user/role has 'bedrock:InvokeModel' permission and access to Claude models. \" +\n \"You may also need to enable model access in the Amazon Bedrock console.\"\n );\n } else if (error.name === \"ResourceNotFoundException\") {\n throw new Error(\n `Model '${request.model}' not found in your AWS region. Check that the model ID is correct and available in your region (${process.env.AWS_REGION || \"us-east-1\"}).`\n );\n } else if (error.name === \"ValidationException\") {\n throw new Error(\n \"Invalid request to Amazon Bedrock. This might be due to an unsupported parameter or malformed request. \" +\n \"Error: \" + error.message\n );\n }\n throw error;\n }\n}\n\nasync function sendAnthropicMessage(request: MessageRequest): Promise {\n try {\n const client = getAnthropicClient();\n\n const response = await (client as any).beta.tools.messages.create({\n model: request.model,\n system: request.system,\n messages: request.messages,\n max_tokens: request.max_tokens,\n tools: request.tools\n });\n\n // Extract token usage from Anthropic API response\n const usage: TokenUsage | undefined = response.usage ? {\n input_tokens: response.usage.input_tokens || 0,\n output_tokens: response.usage.output_tokens || 0,\n total_tokens: (response.usage.input_tokens || 0) + (response.usage.output_tokens || 0)\n } : undefined;\n\n return {\n content: response.content || [],\n stop_reason: response.stop_reason,\n usage\n };\n } catch (error: any) {\n // Provide helpful error messages for Anthropic API issues\n if (error.status === 401) {\n throw new Error(\n \"Anthropic API authentication failed. Check that your ANTHROPIC_API_KEY is valid.\"\n );\n } else if (error.status === 429) {\n throw new Error(\n \"Anthropic API rate limit exceeded. Please wait a moment before trying again.\"\n );\n }\n throw error;\n }\n}\n\nexport function getDefaultProvider(): ModelProvider {\n // Check if AWS credentials are configured\n const hasAwsCredentials = process.env.AWS_ACCESS_KEY_ID ||\n process.env.AWS_SECRET_ACCESS_KEY ||\n process.env.AWS_PROFILE;\n\n // Use Bedrock by default if AWS credentials are available\n if (hasAwsCredentials) {\n return \"bedrock\";\n }\n\n // Fall back to Anthropic if ANTHROPIC_API_KEY is set\n if (process.env.ANTHROPIC_API_KEY) {\n return \"anthropic\";\n }\n\n // Default to bedrock\n return \"bedrock\";\n}\n\nexport function getDefaultModel(provider: ModelProvider): string {\n if (provider === \"bedrock\") {\n // Use environment variable or default to Claude Haiku 4.5 on Bedrock (fast and efficient)\n // Note: Claude 4+ models require inference profile IDs (us.anthropic.* or global.anthropic.*)\n // Claude 3.x models can use direct model IDs (anthropic.claude-*)\n return process.env.BEDROCK_MODEL_ID || \"us.anthropic.claude-haiku-4-5-20251001-v1:0\";\n } else {\n // Use environment variable or default to Haiku for Anthropic API\n return process.env.ANTHROPIC_MODEL || \"claude-haiku-4-5-20251001\";\n }\n}\n" }, { "path": "cli/src/agent/tools.ts", "content": "import {executeMcpCommand} from \"../runtime/mcp.js\";\nimport type {TaskContext} from \"../tasks/types.js\";\nimport {taskCatalog} from \"../tasks/index.js\";\nimport {executeSlashCommand} from \"../commands/executor.js\";\n\nexport interface AgentToolInvocation {\n type: \"mcp\" | \"task\" | \"shell\" | \"docs\" | \"unknown\";\n name: string;\n input: Record;\n}\n\nexport const anthropicTools: any[] = [\n {\n name: \"mcp_command\",\n description: \"Call MCP gateway commands (ping, list, call, init).\",\n input_schema: {\n type: \"object\",\n properties: {\n command: {\n type: \"string\",\n enum: [\"ping\", \"list\", \"call\", \"init\"],\n description: \"Which MCP command to execute.\"\n },\n tool: {\n type: \"string\",\n description: \"Tool name for the call command\"\n },\n args: {\n type: \"object\",\n description: \"JSON arguments for the tool.\"\n }\n },\n required: [\"command\"]\n }\n },\n {\n name: \"registry_task\",\n description: \"Run service management, imports, user management, or diagnostics tasks.\",\n input_schema: {\n type: \"object\",\n properties: {\n command: {\n type: \"string\",\n description: \"Slash command matching the CLI syntax, e.g. /service add configPath=...\"\n }\n },\n required: [\"command\"]\n }\n },\n {\n name: \"shell_command\",\n description: \"Execute shell commands for system diagnostics, file operations, and debugging. Safe for read-only operations and credential inspection.\",\n input_schema: {\n type: \"object\",\n properties: {\n command: {\n type: \"string\",\n description: \"Bash command to execute (e.g., './cli/service_mgmt.sh list-groups', 'cat /path/to/file.json')\"\n }\n },\n required: [\"command\"]\n }\n },\n {\n name: \"read_docs\",\n description: \"Search and read documentation files from the docs folder. Use this when users ask questions about the project, features, setup, configuration, or troubleshooting.\",\n input_schema: {\n type: \"object\",\n properties: {\n search_query: {\n type: \"string\",\n description: \"Keywords to search for in doc files (e.g., 'authentication', 'keycloak', 'setup'). Leave empty to list all docs.\"\n },\n file_path: {\n type: \"string\",\n description: \"Specific doc file to read (e.g., 'auth.md', 'complete-setup-guide.md'). If provided, reads this file directly.\"\n }\n }\n }\n }\n];\n\nexport function mapToolCall(tool: any): AgentToolInvocation {\n if (tool.name === \"mcp_command\") {\n const input = tool.input as Record;\n return {type: \"mcp\", name: tool.name, input};\n }\n if (tool.name === \"registry_task\") {\n const input = tool.input as Record;\n return {type: \"task\", name: tool.name, input};\n }\n if (tool.name === \"shell_command\") {\n const input = tool.input as Record;\n return {type: \"shell\", name: tool.name, input};\n }\n if (tool.name === \"read_docs\") {\n const input = tool.input as Record;\n return {type: \"docs\", name: tool.name, input};\n }\n return {type: \"unknown\", name: tool.name, input: tool.input as Record};\n}\n\nexport async function executeMappedTool(\n invocation: AgentToolInvocation,\n gatewayUrl: string,\n context: TaskContext\n): Promise<{output: string; isError?: boolean}> {\n if (invocation.type === \"mcp\") {\n const command = String(invocation.input.command || \"\");\n if (!command) {\n return {output: \"Missing command field\", isError: true};\n }\n const toolName = invocation.input.tool ? String(invocation.input.tool) : undefined;\n const args = invocation.input.args && typeof invocation.input.args === \"object\" ? (invocation.input.args as Record) : {};\n try {\n const {handshake, response} = await executeMcpCommand(command as any, gatewayUrl, context.gatewayToken, context.backendToken, toolName ? {tool: toolName, args} : undefined);\n return {output: JSON.stringify({handshake, response}, null, 2)};\n } catch (error) {\n return {output: (error as Error).message, isError: true};\n }\n }\n\n if (invocation.type === \"task\") {\n let commandText = String(invocation.input.command || \"\").trim();\n if (!commandText.startsWith(\"/\")) {\n commandText = `/${commandText}`;\n }\n const result = await executeSlashCommand(commandText, context);\n return {output: result.lines.join(\"\\n\"), isError: result.isError};\n }\n\n if (invocation.type === \"shell\") {\n const { execFileSync } = await import(\"child_process\");\n const command = String(invocation.input.command || \"\").trim();\n if (!command) {\n return {output: \"Missing command field\", isError: true};\n }\n // Split command into executable and arguments to avoid shell injection\n const parts = command.split(/\\s+/);\n const executable = parts[0];\n const args = parts.slice(1);\n try {\n const output = execFileSync(executable, args, {encoding: \"utf-8\", maxBuffer: 10 * 1024 * 1024, timeout: 30000});\n return {output};\n } catch (error) {\n const errorMessage = (error as Error).message || String(error);\n return {output: errorMessage, isError: true};\n }\n }\n\n if (invocation.type === \"docs\") {\n const { searchDocs, readDocFile, getAllDocFiles } = await import(\"../utils/docsReader.js\");\n\n const filePath = invocation.input.file_path ? String(invocation.input.file_path) : undefined;\n const searchQuery = invocation.input.search_query ? String(invocation.input.search_query) : undefined;\n\n try {\n if (filePath) {\n // Read specific file\n const doc = readDocFile(filePath);\n if (!doc) {\n return { output: `File not found: ${filePath}`, isError: true };\n }\n return { output: `# ${doc.name}\\n\\n${doc.content}` };\n } else if (searchQuery) {\n // Search docs\n const results = searchDocs(searchQuery);\n if (results.length === 0) {\n return { output: `No documentation found for: ${searchQuery}` };\n }\n const output = results.map(doc =>\n `## ${doc.path}\\n\\n${doc.content.substring(0, 1500)}...\\n\\n---\\n`\n ).join('\\n');\n return { output };\n } else {\n // List all docs\n const files = getAllDocFiles();\n return { output: `Available documentation files:\\n${files.map(f => `- ${f}`).join('\\n')}` };\n }\n } catch (error) {\n return { output: (error as Error).message, isError: true };\n }\n }\n\n return {output: `Unknown tool invocation: ${invocation.name}`, isError: true};\n}\n\nexport function buildTaskContext(gatewayUrl: string, baseUrl: string, gatewayToken?: string, backendToken?: string): TaskContext {\n return {\n gatewayUrl,\n gatewayBaseUrl: baseUrl,\n gatewayToken,\n backendToken\n };\n}\n\nexport function describeAvailableTasks(): string {\n const lines: string[] = [];\n for (const [category, tasks] of Object.entries(taskCatalog)) {\n lines.push(`Category: ${category}`);\n tasks.forEach((task) => {\n lines.push(` - ${task.key.replace(`${category}-`, \"\")}: ${task.description ?? \"\"}`);\n });\n }\n return lines.join(\"\\n\");\n}\n" }, { "path": "cli/src/app.tsx", "content": "import React, {useCallback, useEffect, useMemo, useRef, useState} from \"react\";\nimport {Box, Text, useInput, Static} from \"ink\";\nimport TextInput from \"ink-text-input\";\nimport Spinner from \"ink-spinner\";\nimport {renderMarkdown, hasMarkdown, formatToolOutput} from \"./utils/markdown.js\";\nimport {Banner} from \"./components/Banner.js\";\nimport {CommandSuggestions} from \"./components/CommandSuggestions.js\";\nimport {TokenStatusFooter} from \"./components/TokenStatusFooter.js\";\nimport {getCommandSuggestions} from \"./utils/commands.js\";\n\nimport {resolveAuth} from \"./auth.js\";\nimport type {ParsedArgs} from \"./parseArgs.js\";\nimport {executeSlashCommand, overviewMessage} from \"./commands/executor.js\";\nimport {runAgentTurn} from \"./agent/agentRunner.js\";\nimport type {AgentMessage} from \"./agent/agentRunner.js\";\nimport type {CommandExecutionContext} from \"./commands/executor.js\";\nimport {getDefaultProvider, getDefaultModel} from \"./agent/modelClient.js\";\nimport {executeMcpCommand, formatMcpResult} from \"./runtime/mcp.js\";\nimport {refreshTokens, shouldRefreshToken} from \"./utils/tokenRefresh.js\";\nimport {calculateCost} from \"./utils/costCalculator.js\";\n\ntype ChatRole = \"system\" | \"user\" | \"assistant\" | \"tool\";\n\ninterface ChatMessage {\n id: number;\n role: ChatRole;\n text: string;\n}\n\ninterface AuthReadyState {\n status: \"ready\";\n context: Awaited>;\n}\n\ntype AuthState = {status: \"loading\"} | AuthReadyState | {status: \"error\"; message: string};\n\ninterface AppProps {\n options: ParsedArgs;\n}\n\nexport default function App({options}: AppProps) {\n const interactive = options.interactive !== false;\n const [messages, setMessages] = useState([]);\n const messageCounter = useRef(1);\n const [inputValue, setInputValue] = useState(\"\");\n const [authState, setAuthState] = useState({status: \"loading\"});\n const [authAttempt, setAuthAttempt] = useState(0);\n const [busy, setBusy] = useState(false);\n const [initialised, setInitialised] = useState(false);\n const [hasShownWelcome, setHasShownWelcome] = useState(false);\n const [commandSuggestions, setCommandSuggestions] = useState>([]);\n const [selectedSuggestionIndex, setSelectedSuggestionIndex] = useState(0);\n\n // Token status state\n const [tokenSecondsRemaining, setTokenSecondsRemaining] = useState();\n const [tokenExpired, setTokenExpired] = useState(false);\n const [isRefreshingToken, setIsRefreshingToken] = useState(false);\n const [lastTokenRefresh, setLastTokenRefresh] = useState();\n const [tokenSource, setTokenSource] = useState();\n\n // Session token usage and cost tracking\n const [sessionInputTokens, setSessionInputTokens] = useState(0);\n const [sessionOutputTokens, setSessionOutputTokens] = useState(0);\n const [sessionTotalCost, setSessionTotalCost] = useState(0);\n\n // Registry version\n const [registryVersion, setRegistryVersion] = useState();\n\n const gatewayUrl = useMemo(() => options.url ?? \"http://localhost/mcpgw/mcp\", [options.url]);\n const gatewayBaseUrl = useMemo(() => deriveGatewayBase(gatewayUrl), [gatewayUrl]);\n const agentAvailable = useMemo(() => {\n // Check credentials: AWS Profile, Anthropic API key, or default to true\n // (let AWS SDK discover execution role credentials at runtime)\n const hasAwsProfile = Boolean(process.env.AWS_PROFILE);\n const hasAnthropicKey = Boolean(process.env.ANTHROPIC_API_KEY);\n\n // If no explicit credentials, assume execution role is available\n // AWS SDK will attempt to get credentials from EC2 instance metadata\n return hasAwsProfile || hasAnthropicKey || true;\n }, []);\n\n const addMessage = useCallback((role: ChatRole, text: string) => {\n const id = messageCounter.current++;\n setMessages((prev) => [...prev, {id, role, text}]);\n }, []);\n\n useEffect(() => {\n let cancelled = false;\n setAuthState({status: \"loading\"});\n\n // Try to resolve auth, and if it fails due to missing/invalid tokens, automatically refresh\n resolveAuth({\n tokenFile: options.tokenFile,\n explicitToken: options.token,\n cwd: process.cwd()\n })\n .then(async (context) => {\n if (cancelled) return;\n\n // Check if we have a gateway token - if not, try to generate one\n if (!context.gatewayToken || context.gatewaySource === \"none\") {\n addMessage(\"assistant\", \"No gateway token found. Attempting automatic generation...\");\n\n try {\n const result = await refreshTokens();\n if (result.success) {\n addMessage(\"assistant\", \"✅ OAuth tokens generated successfully. Authenticating...\");\n // Trigger auth reload\n setAuthAttempt((attempt) => attempt + 1);\n } else {\n setAuthState({status: \"error\", message: `Token generation failed: ${result.message}`});\n }\n } catch (refreshError) {\n setAuthState({status: \"error\", message: `Token generation failed: ${(refreshError as Error).message}`});\n }\n return;\n }\n\n setAuthState({status: \"ready\", context});\n })\n .catch(async (error: unknown) => {\n if (cancelled) return;\n\n const errorMessage = (error as Error).message;\n\n // If auth failed due to missing or invalid tokens, try to refresh automatically\n if (errorMessage.includes(\"token\") || errorMessage.includes(\"ENOENT\") || errorMessage.includes(\"Failed to load\")) {\n addMessage(\"assistant\", \"OAuth tokens missing or invalid. Attempting automatic generation...\");\n\n try {\n const result = await refreshTokens();\n if (result.success) {\n addMessage(\"assistant\", \"✅ OAuth tokens generated successfully. Authenticating...\");\n // Trigger auth reload\n setAuthAttempt((attempt) => attempt + 1);\n } else {\n setAuthState({status: \"error\", message: `Token generation failed: ${result.message}`});\n }\n } catch (refreshError) {\n setAuthState({status: \"error\", message: `Token generation failed: ${(refreshError as Error).message}`});\n }\n } else {\n setAuthState({status: \"error\", message: errorMessage});\n }\n });\n return () => {\n cancelled = true;\n };\n }, [options.token, options.tokenFile, authAttempt, addMessage]);\n\n useEffect(() => {\n if (authState.status === \"ready\" && !initialised) {\n // Only show welcome messages the first time\n if (!hasShownWelcome) {\n const infoLines = summariseAuth(authState, gatewayUrl);\n infoLines.forEach((line) => addMessage(\"assistant\", line));\n setHasShownWelcome(true);\n }\n setInitialised(true);\n\n // Initialize token status\n const gatewayInspection = authState.context.inspections.find(i => i.label.includes(\"Gateway\"));\n if (gatewayInspection && shouldRefreshToken(gatewayInspection.secondsRemaining)) {\n refreshTokens()\n .then((result) => {\n if (result.success) {\n // Silently refresh tokens without showing messages\n // Trigger auth reload\n setAuthAttempt((attempt) => attempt + 1);\n } else {\n addMessage(\"assistant\", `❌ ${result.message}. Please run: ./credentials-provider/generate_creds.sh --ingress-only`);\n }\n })\n .catch((error) => {\n addMessage(\"assistant\", `❌ Token refresh failed: ${error.message}. Please run: ./credentials-provider/generate_creds.sh --ingress-only`);\n });\n }\n\n // Fetch registry version\n fetch(`${gatewayBaseUrl}/api/version`)\n .then(res => res.json())\n .then(data => setRegistryVersion(data.version))\n .catch(() => {\n // Silently fail if version fetch fails\n });\n }\n }, [authState, addMessage, initialised, gatewayUrl, gatewayBaseUrl, setAuthAttempt, hasShownWelcome]);\n\n useEffect(() => {\n if (!interactive && authState.status === \"ready\" && options.command) {\n const command = options.command;\n (async () => {\n try {\n const extras = options.tool\n ? {\n tool: options.tool,\n args: options.args ? JSON.parse(options.args) : {}\n }\n : undefined;\n const result = await executeMcpCommand(\n command,\n gatewayUrl,\n authState.context.gatewayToken,\n authState.context.backendToken,\n extras\n );\n const lines = formatMcpResult(command, result.handshake, result.response, options.tool);\n // eslint-disable-next-line no-console\n console.log(options.json ? JSON.stringify({lines}) : lines.join(\"\\n\"));\n process.exit(0);\n } catch (error) {\n // eslint-disable-next-line no-console\n console.error((error as Error).message);\n process.exit(1);\n }\n })();\n }\n }, [authState, gatewayUrl, interactive, options]);\n\n // Update command suggestions when input changes\n useEffect(() => {\n if (inputValue.startsWith(\"/\")) {\n const suggestions = getCommandSuggestions(inputValue);\n setCommandSuggestions(suggestions);\n setSelectedSuggestionIndex(0);\n } else {\n setCommandSuggestions([]);\n setSelectedSuggestionIndex(0);\n }\n }, [inputValue]);\n\n // Timer effect to update token status every second\n useEffect(() => {\n if (authState.status !== \"ready\") return;\n\n const gatewayInspection = authState.context.inspections.find(i => i.label.includes(\"Gateway\"));\n if (gatewayInspection) {\n // Initialize token status on mount\n const now = Date.now() / 1000;\n const expiresAt = gatewayInspection.expiresAt ? gatewayInspection.expiresAt.getTime() / 1000 : 0;\n const remaining = Math.floor(expiresAt - now);\n setTokenSecondsRemaining(remaining);\n setTokenExpired(remaining <= 0);\n setTokenSource(authState.context.gatewaySource);\n }\n\n const interval = setInterval(() => {\n if (authState.status !== \"ready\") return;\n\n const gatewayInspection = authState.context.inspections.find(i => i.label.includes(\"Gateway\"));\n if (gatewayInspection) {\n const now = Date.now() / 1000;\n const expiresAt = gatewayInspection.expiresAt ? gatewayInspection.expiresAt.getTime() / 1000 : 0;\n const remaining = Math.floor(expiresAt - now);\n setTokenSecondsRemaining(remaining);\n setTokenExpired(remaining <= 0);\n\n // Auto-refresh when <= 10 seconds remaining\n if (shouldRefreshToken(remaining) && !isRefreshingToken) {\n setIsRefreshingToken(true);\n refreshTokens()\n .then((result) => {\n if (result.success) {\n setLastTokenRefresh(new Date());\n // Trigger auth reload\n setAuthAttempt((attempt) => attempt + 1);\n setInitialised(false);\n }\n setIsRefreshingToken(false);\n })\n .catch(() => {\n setIsRefreshingToken(false);\n });\n }\n }\n }, 1000);\n\n return () => clearInterval(interval);\n }, [authState, isRefreshingToken, setAuthAttempt]);\n\n useInput(\n (input, key) => {\n if (key.ctrl && input === \"c\") {\n process.exit();\n }\n\n // Handle arrow keys for command suggestions\n if (commandSuggestions.length > 0) {\n if (key.upArrow) {\n setSelectedSuggestionIndex((prev) =>\n prev > 0 ? prev - 1 : commandSuggestions.length - 1\n );\n } else if (key.downArrow) {\n setSelectedSuggestionIndex((prev) =>\n prev < commandSuggestions.length - 1 ? prev + 1 : 0\n );\n } else if (key.tab || key.return) {\n // Tab or Enter to autocomplete\n const selected = commandSuggestions[selectedSuggestionIndex];\n if (selected) {\n setInputValue(selected.command + \" \");\n }\n // Prevent Enter from submitting when autocompleting\n if (key.return) {\n return;\n }\n }\n }\n },\n {isActive: interactive}\n );\n\n const handleSubmit = useCallback(\n async (value: string) => {\n // If suggestions are visible, don't submit - let Enter autocomplete instead\n if (commandSuggestions.length > 0) {\n return;\n }\n\n const trimmed = value.trim();\n if (!trimmed) {\n return;\n }\n\n setInputValue(\"\");\n\n const userMessage: ChatMessage = {id: messageCounter.current++, role: \"user\", text: trimmed};\n setMessages((prev) => [...prev, userMessage]);\n\n if (trimmed === \"/retry\") {\n setAuthAttempt((attempt) => attempt + 1);\n setInitialised(false);\n addMessage(\"assistant\", \"Retrying authentication...\");\n return;\n }\n\n if (trimmed === \"/refresh-tokens\" || trimmed === \"/refresh\") {\n setBusy(true);\n refreshTokens()\n .then((result) => {\n if (result.success) {\n addMessage(\"assistant\", \"✅ OAuth tokens refreshed successfully. Reloading authentication...\");\n setAuthAttempt((attempt) => attempt + 1);\n setInitialised(false);\n } else {\n addMessage(\"assistant\", `❌ ${result.message}. Try running: ./credentials-provider/generate_creds.sh --ingress-only`);\n }\n })\n .catch((error) => {\n addMessage(\"assistant\", `❌ Token refresh failed: ${error.message}`);\n })\n .finally(() => {\n setBusy(false);\n });\n return;\n }\n\n if (authState.status !== \"ready\") {\n addMessage(\"assistant\", \"Authentication is not ready yet. Try /retry or wait a moment.\");\n return;\n }\n\n // Token refresh is now handled automatically by the timer effect in the footer\n\n const commandContext: CommandExecutionContext = {\n gatewayUrl,\n gatewayBaseUrl,\n gatewayToken: authState.context.gatewayToken,\n backendToken: authState.context.backendToken\n };\n\n const history: AgentMessage[] = buildAgentHistory([...messages, userMessage]);\n\n if (trimmed.startsWith(\"/\")) {\n setBusy(true);\n try {\n const result = await executeSlashCommand(trimmed, commandContext);\n addMessage(result.isError ? \"assistant\" : \"tool\", result.lines.join(\"\\n\"));\n\n // Handle exit command\n if (result.shouldExit) {\n setTimeout(() => process.exit(0), 500);\n }\n } catch (error) {\n addMessage(\"assistant\", `Command failed: ${(error as Error).message}`);\n } finally {\n setBusy(false);\n }\n return;\n }\n\n if (!agentAvailable) {\n addMessage(\n \"assistant\",\n \"Agent mode is disabled. Configure AWS_PROFILE, ensure execution role is available, or set ANTHROPIC_API_KEY. Alternatively, use slash commands like /ping.\"\n );\n return;\n }\n\n setBusy(true);\n try {\n const result = await runAgentTurn(history, {\n gatewayUrl,\n gatewayBaseUrl,\n gatewayToken: authState.context.gatewayToken,\n backendToken: authState.context.backendToken,\n model: process.env.ANTHROPIC_MODEL\n });\n\n // Only show tool outputs if there's an error (for debugging)\n result.toolOutputs.forEach((tool) => {\n if (tool.isError) {\n const formatted = formatToolOutput(tool.name, tool.output, tool.isError);\n addMessage(\"tool\", formatted);\n }\n });\n\n if (result.messages.length === 0) {\n addMessage(\"assistant\", \"No response from the agent. Try a different prompt or use /help.\");\n } else {\n result.messages.forEach((msg) => addMessage(msg.role, msg.content));\n\n // Track token usage and cost\n if (result.tokenUsage) {\n const {input_tokens, output_tokens, total_tokens} = result.tokenUsage;\n\n // Get the current model being used\n const currentModel = process.env.ANTHROPIC_MODEL || getDefaultModel(getDefaultProvider());\n\n // Calculate cost for this turn\n const turnCost = calculateCost(currentModel, input_tokens, output_tokens);\n\n // Update session totals\n setSessionInputTokens((prev) => prev + input_tokens);\n setSessionOutputTokens((prev) => prev + output_tokens);\n if (turnCost !== undefined) {\n setSessionTotalCost((prev) => prev + turnCost);\n }\n }\n }\n } catch (error) {\n addMessage(\"assistant\", `Agent error: ${(error as Error).message}`);\n } finally {\n setBusy(false);\n }\n },\n [messages, authState, gatewayUrl, gatewayBaseUrl, agentAvailable, addMessage, commandSuggestions]\n );\n\n const renderMessages = () => {\n const items = [{id: 0, type: 'banner' as const}, ...messages.map(m => ({...m, type: 'message' as const}))];\n return (\n \n {(item) => {\n if (item.type === 'banner') {\n return ;\n }\n return (\n \n \n \n );\n }}\n \n );\n };\n\n const inputPrompt = useMemo(() => {\n if (busy) {\n return (\n \n Working...\n \n );\n }\n if (authState.status === \"loading\") {\n return (\n \n Authenticating...\n \n );\n }\n if (authState.status === \"error\") {\n return Auth error. Type /retry once credentials are fixed.;\n }\n return ›;\n }, [authState, busy]);\n\n if (!interactive) {\n if (authState.status === \"loading\") {\n return (\n \n Authenticating...\n \n );\n }\n if (authState.status === \"error\") {\n return (\n \n Authentication failed: {authState.message}\n \n );\n }\n return (\n \n Processing non-interactive command...\n \n );\n }\n\n return (\n \n {renderMessages()}\n {commandSuggestions.length > 0 && (\n \n )}\n \n \n {\"═\".repeat(Math.min(process.stdout.columns || 80, 80))}\n \n \n {inputPrompt}\n \n \n \n {commandSuggestions.length > 0 && commandSuggestions[selectedSuggestionIndex] && (\n \n {commandSuggestions[selectedSuggestionIndex].command.substring(inputValue.length)}\n \n )}\n \n \n \n \n {\"═\".repeat(Math.min(process.stdout.columns || 80, 80))}\n \n {commandSuggestions.length > 0 && commandSuggestions[selectedSuggestionIndex] && (\n \n \n {commandSuggestions[selectedSuggestionIndex].command}\n \n \n {\" — \"}\n {commandSuggestions[selectedSuggestionIndex].description}\n \n \n )}\n {authState.status === \"ready\" && (\n \n \n \n )}\n \n \n );\n}\n\nfunction buildAgentHistory(messages: ChatMessage[]): AgentMessage[] {\n return messages\n .filter((message) => message.role !== \"tool\")\n .map((message) => ({\n role:\n message.role === \"system\"\n ? \"system\"\n : message.role === \"assistant\"\n ? \"assistant\"\n : \"user\",\n content: message.text\n }));\n}\n\nfunction summariseAuth(_authState: AuthReadyState, gatewayUrl: string): string[] {\n // Simplified - only show gateway URL and help. Token/model info shown in footer\n const lines = [`Authenticated against ${gatewayUrl}`];\n lines.push(\"\");\n lines.push(overviewMessage());\n return lines;\n}\n\ninterface MessageBubbleProps {\n role: ChatRole;\n text: string;\n}\n\nfunction MessageBubble({role, text}: MessageBubbleProps) {\n const color = roleColor(role);\n const label = roleLabel(role);\n\n // Render markdown for assistant and tool messages\n const shouldRenderMarkdown = (role === \"assistant\" || role === \"tool\") && hasMarkdown(text);\n const displayText = shouldRenderMarkdown ? renderMarkdown(text) : text;\n\n // Helper to render text with inline code highlighting\n const renderTextWithHighlights = (content: string) => {\n const parts = content.split(/(`[^`]+`)/g);\n return parts.map((part, i) => {\n if (part.startsWith('`') && part.endsWith('`')) {\n // Remove backticks and render in cyan\n return (\n \n {part.slice(1, -1)}\n \n );\n }\n return {part};\n });\n };\n\n return (\n \n \n \n {label}\n \n \n \n \n {renderTextWithHighlights(displayText)}\n \n \n \n );\n}\n\nfunction roleLabel(role: ChatRole): string {\n switch (role) {\n case \"user\":\n return \"You\";\n case \"assistant\":\n return \"Assistant\";\n case \"tool\":\n return \"Tool\";\n case \"system\":\n default:\n return \"System\";\n }\n}\n\nfunction roleColor(role: ChatRole): string | undefined {\n switch (role) {\n case \"user\":\n return \"green\";\n case \"assistant\":\n return \"cyan\";\n case \"tool\":\n return \"yellow\";\n case \"system\":\n default:\n return \"magenta\";\n }\n}\n\nfunction deriveGatewayBase(url: string): string {\n if (!url) {\n return \"\";\n }\n try {\n const parsed = new URL(url);\n const pathname = parsed.pathname.replace(/\\/mcpgw\\/mcp(?:\\/.*)?$/, \"\");\n return `${parsed.origin}${pathname.endsWith(\"/\") || pathname.length === 0 ? pathname : `${pathname}/`}`;\n } catch {\n return url.replace(/\\/mcpgw\\/mcp(?:\\/.*)?$/, \"\");\n }\n}\n" }, { "path": "cli/src/auth.ts", "content": "import {promises as fs} from \"node:fs\";\nimport path from \"node:path\";\nimport os from \"node:os\";\n\nexport type BackendSource = \"none\" | \"token-file\" | \"m2m\" | \"explicit\";\nexport type GatewaySource = \"none\" | \"ingress-json\" | \"env\" | \"token-file\";\n\nexport interface TokenInspection {\n label: string;\n expiresAt?: Date;\n secondsRemaining?: number;\n expired: boolean;\n warning?: string;\n}\n\nexport interface AuthContext {\n backendToken?: string;\n backendSource: BackendSource;\n gatewayToken?: string;\n gatewaySource: GatewaySource;\n tokenFile?: string;\n warnings: string[];\n inspections: TokenInspection[];\n}\n\nexport interface ResolveAuthOptions {\n tokenFile?: string;\n explicitToken?: string;\n cwd?: string;\n}\n\nconst ONE_MINUTE = 60;\n\nexport async function resolveAuth(options: ResolveAuthOptions): Promise {\n const warnings: string[] = [];\n const inspections: TokenInspection[] = [];\n\n // Use parent directory if running from cli/ subdirectory\n let cwd = options.cwd ?? process.cwd();\n if (cwd.endsWith('/cli') || cwd.endsWith('\\\\cli')) {\n cwd = path.dirname(cwd);\n }\n\n let backendToken: string | undefined;\n let backendSource: BackendSource = \"none\";\n let tokenFile: string | undefined;\n\n if (options.explicitToken) {\n backendToken = options.explicitToken;\n backendSource = \"explicit\";\n tokenFile = undefined;\n } else if (options.tokenFile) {\n const loaded = await loadTokenFromPlainFile(options.tokenFile);\n if (loaded) {\n backendToken = loaded;\n backendSource = \"token-file\";\n tokenFile = options.tokenFile;\n } else {\n warnings.push(`Failed to read token file: ${options.tokenFile}`);\n }\n }\n\n if (!backendToken) {\n const m2mToken = await fetchM2MToken();\n if (m2mToken?.token) {\n backendToken = m2mToken.token;\n backendSource = \"m2m\";\n inspections.push(buildInspection(\"M2M token\", backendToken));\n if (m2mToken.warning) {\n warnings.push(m2mToken.warning);\n }\n } else if (m2mToken?.warning) {\n warnings.push(m2mToken.warning);\n }\n } else {\n inspections.push(buildInspection(\"Backend token\", backendToken));\n }\n\n const gatewayTokenResult = await resolveGatewayToken(cwd);\n let gatewayToken: string | undefined = gatewayTokenResult.token;\n let gatewaySource: GatewaySource = gatewayTokenResult.source;\n if (gatewayToken) {\n inspections.push(buildInspection(\"Gateway token\", gatewayToken));\n if (gatewayTokenResult.warning) {\n warnings.push(gatewayTokenResult.warning);\n }\n }\n\n // Filter out falsy warnings\n const filteredWarnings = warnings.filter(Boolean);\n\n return {\n backendToken,\n backendSource,\n gatewayToken,\n gatewaySource,\n tokenFile,\n warnings: filteredWarnings,\n inspections\n };\n}\n\nasync function loadTokenFromPlainFile(filePath: string): Promise {\n try {\n const absolutePath = path.resolve(filePath);\n const content = await fs.readFile(absolutePath, \"utf-8\");\n const token = content.trim();\n return token.length > 0 ? token : undefined;\n } catch {\n return undefined;\n }\n}\n\nasync function resolveGatewayToken(cwd: string): Promise<{token?: string; source: GatewaySource; warning?: string}> {\n const envToken = process.env.MCP_GATEWAY_TOKEN;\n if (envToken) {\n return {\n token: envToken,\n source: \"env\"\n };\n }\n\n const ingressJsonPath = path.join(cwd, \".oauth-tokens\", \"ingress.json\");\n const ingressToken = await loadOAuthTokenFromFile(ingressJsonPath);\n if (ingressToken) {\n const inspection = inspectJwt(ingressToken);\n let warning: string | undefined;\n if (inspection && inspection.expired) {\n warning = `Ingress token in ${ingressJsonPath} is expired`;\n } else if (inspection && inspection.secondsRemaining !== undefined && inspection.secondsRemaining <= ONE_MINUTE) {\n warning = `Ingress token in ${ingressJsonPath} expires in ${inspection.secondsRemaining} seconds`;\n }\n return {\n token: ingressToken,\n source: \"ingress-json\",\n warning\n };\n }\n\n const homeIngressPath = path.join(os.homedir(), \".mcp\", \"ingress_token\");\n const fallbackToken = await loadTokenFromPlainFile(homeIngressPath);\n if (fallbackToken) {\n return {\n token: fallbackToken,\n source: \"token-file\"\n };\n }\n\n return {\n source: \"none\"\n };\n}\n\nasync function loadOAuthTokenFromFile(filePath: string): Promise {\n try {\n const content = await fs.readFile(filePath, \"utf-8\");\n const json = JSON.parse(content) as Record;\n\n let accessToken: unknown;\n let expiresAt: number | undefined;\n\n if (\"tokens\" in json && typeof json.tokens === \"object\" && json.tokens !== null) {\n const tokens = json.tokens as Record;\n accessToken = tokens.access_token ?? tokens.token;\n if (typeof tokens.expires_at === \"number\") {\n expiresAt = tokens.expires_at;\n }\n } else {\n accessToken = json.access_token ?? json.token;\n if (typeof json.expires_at === \"number\") {\n expiresAt = json.expires_at;\n }\n }\n\n if (typeof accessToken !== \"string\") {\n return undefined;\n }\n\n if (expiresAt && expiresAt <= Date.now() / 1000) {\n return undefined;\n }\n\n return accessToken;\n } catch {\n return undefined;\n }\n}\n\nasync function fetchM2MToken(): Promise<{token?: string; warning?: string} | undefined> {\n const clientId = process.env.CLIENT_ID;\n const clientSecret = process.env.CLIENT_SECRET;\n const keycloakUrl = process.env.KEYCLOAK_URL;\n const realm = process.env.KEYCLOAK_REALM;\n\n if (!clientId || !clientSecret || !keycloakUrl || !realm) {\n return undefined;\n }\n\n const params = new URLSearchParams();\n params.set(\"grant_type\", \"client_credentials\");\n params.set(\"client_id\", clientId);\n params.set(\"client_secret\", clientSecret);\n params.set(\"scope\", \"openid\");\n\n const tokenUrl = `${keycloakUrl.replace(/\\/$/, \"\")}/realms/${realm}/protocol/openid-connect/token`;\n\n try {\n const response = await fetch(tokenUrl, {\n method: \"POST\",\n headers: {\n \"content-type\": \"application/x-www-form-urlencoded\"\n },\n body: params.toString()\n });\n\n if (!response.ok) {\n return {warning: `Failed to obtain M2M token (${response.status} ${response.statusText})`};\n }\n\n const data = (await response.json()) as Record;\n const accessToken = data.access_token;\n const expiresIn = typeof data.expires_in === \"number\" ? data.expires_in : undefined;\n\n if (typeof accessToken !== \"string\" || accessToken.length === 0) {\n return {warning: \"M2M token response did not include an access_token field\"};\n }\n\n let warning: string | undefined;\n if (expiresIn !== undefined && expiresIn <= ONE_MINUTE) {\n warning = `M2M token expires in ${expiresIn} seconds`;\n }\n\n return {\n token: accessToken,\n warning\n };\n } catch (error) {\n return {warning: `Failed to fetch M2M token: ${(error as Error).message}`};\n }\n}\n\nfunction buildInspection(label: string, token: string): TokenInspection {\n const inspection = inspectJwt(token);\n if (!inspection) {\n return {\n label,\n expired: false\n };\n }\n\n const warning = inspection.warning ?? (inspection.secondsRemaining !== undefined && inspection.secondsRemaining <= ONE_MINUTE\n ? `${label} expires in ${inspection.secondsRemaining} seconds`\n : undefined);\n\n return {\n label,\n expiresAt: inspection.expiresAt,\n secondsRemaining: inspection.secondsRemaining,\n expired: inspection.expired,\n warning\n };\n}\n\nfunction inspectJwt(token: string): {\n expiresAt?: Date;\n secondsRemaining?: number;\n expired: boolean;\n warning?: string;\n} | undefined {\n const parts = token.split(\".\");\n if (parts.length !== 3) {\n return {\n expired: false,\n warning: \"Token is not a valid JWT format\"\n };\n }\n\n try {\n const payload = JSON.parse(base64UrlDecode(parts[1])) as Record;\n if (typeof payload.exp !== \"number\") {\n return {\n expired: false,\n warning: \"Token does not declare an expiration time\"\n };\n }\n const expiresAt = new Date(payload.exp * 1000);\n const secondsRemaining = Math.floor(payload.exp - Date.now() / 1000);\n return {\n expiresAt,\n secondsRemaining,\n expired: secondsRemaining <= 0\n };\n } catch {\n return {\n expired: false,\n warning: \"Token payload could not be decoded\"\n };\n }\n}\n\nfunction base64UrlDecode(segment: string): string {\n const normalized = segment.replace(/-/g, \"+\").replace(/_/g, \"/\");\n const padding = normalized.length % 4;\n const padded = padding === 0 ? normalized : normalized + \"=\".repeat(4 - padding);\n const buffer = Buffer.from(padded, \"base64\");\n return buffer.toString(\"utf-8\");\n}\n" }, { "path": "cli/src/chat/commandParser.ts", "content": "import type {TaskCategory} from \"../tasks/types.js\";\n\nexport type CommandKind = \"help\" | \"ping\" | \"list\" | \"servers\" | \"init\" | \"call\" | \"task\" | \"agents\" | \"exit\" | \"unknown\";\n\nexport interface BaseParsedCommand {\n kind: CommandKind;\n}\n\nexport interface HelpCommand extends BaseParsedCommand {\n kind: \"help\";\n}\n\nexport interface ExitCommand extends BaseParsedCommand {\n kind: \"exit\";\n}\n\nexport interface PingCommand extends BaseParsedCommand {\n kind: \"ping\" | \"list\" | \"servers\" | \"init\";\n}\n\nexport interface CallCommand extends BaseParsedCommand {\n kind: \"call\";\n tool?: string;\n argsJson?: string;\n rawTokens: string[];\n}\n\nexport interface TaskCommand extends BaseParsedCommand {\n kind: \"task\";\n category: TaskCategory;\n subcommand: string;\n tokens: string[];\n}\n\nexport interface AgentsCommand extends BaseParsedCommand {\n kind: \"agents\";\n subcommand: string;\n tokens: string[];\n}\n\nexport interface UnknownCommand extends BaseParsedCommand {\n kind: \"unknown\";\n message: string;\n}\n\nexport type ParsedCommand = HelpCommand | ExitCommand | PingCommand | CallCommand | TaskCommand | AgentsCommand | UnknownCommand;\n\nconst TASK_PREFIXES: Record = {\n service: \"service\",\n services: \"service\",\n svc: \"service\",\n import: \"import\",\n imports: \"import\",\n registry: \"import\",\n user: \"user\",\n users: \"user\",\n diagnostic: \"diagnostic\",\n diagnostics: \"diagnostic\",\n diag: \"diagnostic\"\n};\n\nconst SIMPLE_COMMANDS: Record = {\n ping: \"ping\",\n list: \"list\",\n tools: \"list\",\n servers: \"servers\",\n init: \"init\",\n initialize: \"init\"\n};\n\nexport function parseCommand(input: string): ParsedCommand {\n const trimmed = input.trim();\n const withoutSlash = trimmed.startsWith(\"/\") ? trimmed.slice(1).trim() : trimmed;\n if (!withoutSlash) {\n return {kind: \"help\"};\n }\n\n const tokens = tokenize(withoutSlash);\n if (tokens.length === 0) {\n return {kind: \"help\"};\n }\n\n const keyword = tokens.shift()!.toLowerCase();\n\n if (keyword === \"help\" || keyword === \"?\") {\n return {kind: \"help\"};\n }\n\n if (keyword === \"exit\" || keyword === \"quit\" || keyword === \"q\") {\n return {kind: \"exit\"};\n }\n\n if (keyword === \"call\") {\n return parseCall(tokens);\n }\n\n if (keyword === \"agents\" || keyword === \"agent\") {\n if (tokens.length === 0) {\n return {\n kind: \"unknown\",\n message: `I need a subcommand for agents. Try \"/agents help\" or \"/help\".`\n };\n }\n\n const subcommand = tokens.shift()!.toLowerCase();\n\n if (subcommand === \"help\") {\n return {\n kind: \"agents\",\n subcommand: \"help\",\n tokens: []\n };\n }\n\n return {\n kind: \"agents\",\n subcommand,\n tokens\n };\n }\n\n const simpleKind = SIMPLE_COMMANDS[keyword];\n if (simpleKind) {\n return {kind: simpleKind};\n }\n\n const category = TASK_PREFIXES[keyword];\n if (category) {\n if (tokens.length === 0) {\n return {\n kind: \"unknown\",\n message: `I need a subcommand for ${category} tasks. Try \"/${category} help\" or \"/help\".`\n };\n }\n\n const subcommand = tokens.shift()!.toLowerCase();\n\n if (subcommand === \"help\") {\n return {\n kind: \"unknown\",\n message: describeCategory(category)\n };\n }\n\n return {\n kind: \"task\",\n category,\n subcommand,\n tokens\n };\n }\n\n return {\n kind: \"unknown\",\n message: `I don't recognise the command \"${keyword}\". Try \"/help\" to see what I can do.`\n };\n}\n\nfunction parseCall(tokens: string[]): CallCommand {\n let tool: string | undefined;\n let argsJson: string | undefined;\n\n if (tokens.length > 0 && !tokens[0].includes(\"=\")) {\n tool = tokens.shift();\n }\n\n for (const token of tokens) {\n const [key, value] = splitToken(token);\n if (!key || value === undefined) {\n continue;\n }\n if (key === \"tool\" && !tool) {\n tool = value;\n }\n if (key === \"args\" || key === \"json\") {\n argsJson = value;\n }\n }\n\n return {\n kind: \"call\",\n tool,\n argsJson,\n rawTokens: tokens\n };\n}\n\nfunction describeCategory(category: TaskCategory): string {\n switch (category) {\n case \"service\":\n return \"Service toolkit commands: /service add, /service delete, /service monitor, /service test, /service add-groups, /service remove-groups, /service create-group, /service delete-group, /service list-groups.\";\n case \"import\":\n return \"Registry import commands: /import dry, /import apply (optional import-list=).\";\n case \"user\":\n return \"User management commands: /user create-m2m, /user create-human, /user delete, /user list, /user list-groups.\";\n case \"diagnostic\":\n return \"Diagnostics commands: /diagnostic run-suite, /diagnostic run-test.\";\n default:\n return \"Unknown category.\";\n }\n}\n\nexport function tokenize(text: string): string[] {\n const tokens: string[] = [];\n const regex = /\"([^\"\\\\]*(\\\\.[^\"\\\\]*)*)\"|'([^'\\\\]*(\\\\.[^'\\\\]*)*)'|[^\\s]+/g;\n let match: RegExpExecArray | null;\n while ((match = regex.exec(text)) !== null) {\n const token = match[0];\n tokens.push(unquote(token));\n }\n return tokens;\n}\n\nfunction unquote(token: string): string {\n if (token.length >= 2) {\n const first = token[0];\n const last = token[token.length - 1];\n if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\")) {\n const inner = token.slice(1, -1);\n return inner.replace(/\\\\([\"'\\\\])/g, \"$1\").replace(/\\\\n/g, \"\\n\").replace(/\\\\t/g, \"\\t\");\n }\n }\n return token;\n}\n\nexport function splitToken(token: string): [string | undefined, string | undefined] {\n const index = token.indexOf(\"=\");\n if (index === -1) {\n return [undefined, token];\n }\n const key = token.slice(0, index).toLowerCase();\n const value = token.slice(index + 1);\n return [key, value];\n}\n" }, { "path": "cli/src/chat/taskInterpreter.ts", "content": "import {getTaskByKey, resolveDefaultValues, taskCatalog} from \"../tasks/index.js\";\nimport type {ScriptTask, TaskCategory, TaskField} from \"../tasks/types.js\";\nimport type {TaskCommand} from \"./commandParser.js\";\nimport {splitToken} from \"./commandParser.js\";\n\ninterface TaskResolutionSuccess {\n task: ScriptTask;\n values: Record;\n}\n\ninterface TaskResolutionError {\n error: string;\n}\n\nexport type TaskResolution = TaskResolutionSuccess | TaskResolutionError;\n\nexport function resolveTaskCommand(command: TaskCommand): TaskResolution {\n const {category, subcommand} = command;\n const taskKey = resolveTaskKey(category, subcommand);\n if (!taskKey) {\n const available = taskCatalog[category].map((task) => task.key.replace(`${category}-`, \"\")).join(\", \");\n return {\n error: `I don't recognise \"/${category} ${subcommand}\". Available subcommands: ${available}.`\n };\n }\n\n const task = getTaskByKey(category, taskKey);\n if (!task) {\n return {\n error: `Task \"${taskKey}\" is not available.`\n };\n }\n\n const values = resolveDefaultValues(task);\n const assignments: Record = {...values};\n const positionalFields = task.fields.filter((field) => !field.optional && !(field.name in assignments));\n let positionalIndex = 0;\n\n for (const token of command.tokens) {\n const [key, value] = splitToken(token);\n if (key) {\n const field = findField(task.fields, key);\n if (!field) {\n return {error: `Unknown option \"${key}\" for \"/${category} ${subcommand}\".`};\n }\n assignments[field.name] = value ?? \"\";\n } else {\n if (positionalIndex >= task.fields.length) {\n return {error: `Too many positional values for \"/${category} ${subcommand}\".`};\n }\n let field = positionalFields[positionalIndex];\n while (field && field.name in assignments && assignments[field.name]) {\n positionalIndex += 1;\n field = positionalFields[positionalIndex];\n }\n if (!field) {\n return {error: `Unexpected extra value \"${token}\" for \"/${category} ${subcommand}\".`};\n }\n assignments[field.name] = token;\n positionalIndex += 1;\n }\n }\n\n for (const field of task.fields) {\n if (!field.optional) {\n const value = assignments[field.name];\n if (!value || value.trim().length === 0) {\n return {\n error: `Missing required option \"${field.name}\" for \"/${category} ${subcommand}\".`\n };\n }\n }\n }\n\n return {\n task,\n values: assignments\n };\n}\n\nfunction resolveTaskKey(category: TaskCategory, subcommand: string): string | undefined {\n const normalized = subcommand.toLowerCase().replace(/_/g, \"-\");\n const candidate = `${category}-${normalized}`;\n const hasTask = taskCatalog[category].some((task) => task.key === candidate);\n if (hasTask) {\n return candidate;\n }\n // Attempt to add common suffixes/prefixes\n const alt = taskCatalog[category].find((task) => {\n const suffix = task.key.replace(`${category}-`, \"\");\n return suffix === normalized;\n });\n return alt?.key;\n}\n\nfunction findField(fields: TaskField[], inputKey: string): TaskField | undefined {\n const lower = inputKey.toLowerCase();\n return fields.find((field) => field.name.toLowerCase() === lower);\n}\n" }, { "path": "cli/src/commands/executor.ts", "content": "import {parseCommand, type CallCommand, type TaskCommand, type AgentsCommand} from \"../chat/commandParser.js\";\nimport {resolveTaskCommand} from \"../chat/taskInterpreter.js\";\nimport {executeMcpCommand, formatMcpResult} from \"../runtime/mcp.js\";\nimport {runScriptTaskToString} from \"../runtime/script.js\";\nimport type {TaskContext} from \"../tasks/types.js\";\nimport {spawn} from \"node:child_process\";\nimport {REGISTRY_CLI_WRAPPER, REPO_ROOT} from \"../paths.js\";\n\nexport interface CommandExecutionContext extends TaskContext {}\n\n// Helper function to call the registry CLI wrapper\nasync function callRegistryWrapper(args: string[], context: CommandExecutionContext): Promise<{stdout: string; stderr: string; exitCode: number}> {\n const baseArgs = [\n \"run\",\n \"python\",\n REGISTRY_CLI_WRAPPER,\n \"--base-url\",\n context.gatewayBaseUrl,\n ...args\n ];\n\n // Use backendToken if available, otherwise fall back to gatewayToken\n const token = context.backendToken || context.gatewayToken;\n\n const env = token\n ? {...process.env, GATEWAY_TOKEN: token}\n : process.env;\n\n return new Promise((resolve) => {\n const child = spawn(\"uv\", baseArgs, {\n cwd: REPO_ROOT,\n env: env as NodeJS.ProcessEnv,\n stdio: [\"ignore\", \"pipe\", \"pipe\"]\n });\n\n let stdout = \"\";\n let stderr = \"\";\n\n child.stdout?.on(\"data\", (chunk) => {\n stdout += chunk.toString();\n });\n child.stderr?.on(\"data\", (chunk) => {\n stderr += chunk.toString();\n });\n\n child.on(\"close\", (code) => {\n resolve({stdout, stderr, exitCode: code ?? -1});\n });\n child.on(\"error\", (error) => {\n resolve({\n stdout,\n stderr: `${stderr}\\nFailed to start process: ${(error as Error).message}`,\n exitCode: -1\n });\n });\n });\n}\n\nexport async function executeSlashCommand(\n input: string,\n context: CommandExecutionContext\n): Promise<{lines: string[]; isError?: boolean; shouldExit?: boolean}> {\n const parsed = parseCommand(input);\n\n switch (parsed.kind) {\n case \"help\":\n return {lines: [detailedHelpMessage()]};\n\n case \"exit\":\n return {lines: [\"Goodbye!\"], shouldExit: true};\n\n case \"ping\":\n case \"list\":\n case \"init\":\n return await executeMcp(parsed.kind, context);\n\n case \"servers\":\n return await executeServers(context);\n\n case \"call\":\n return await executeCall(parsed, context);\n\n case \"agents\":\n return await executeAgents(parsed as AgentsCommand, context);\n\n case \"task\": {\n const resolution = resolveTaskCommand(parsed as TaskCommand);\n if (\"error\" in resolution) {\n return {lines: [resolution.error], isError: true};\n }\n const result = await runScriptTaskToString(parsed.category, resolution.task, resolution.values, context);\n const lines = [\n `$ ${result.command.command} ${result.command.args.join(\" \")}`,\n result.stdout.trim(),\n result.stderr ? `stderr:\\n${result.stderr.trim()}` : \"\",\n `exitCode: ${result.exitCode ?? 0}`\n ]\n .filter((line) => line && line.trim().length > 0)\n .join(\"\\n\\n\");\n return {lines: [lines]};\n }\n\n case \"unknown\":\n default:\n return {lines: [(parsed as any).message], isError: true};\n }\n}\n\nasync function executeMcp(command: \"ping\" | \"list\" | \"init\", context: CommandExecutionContext) {\n const {handshake, response} = await executeMcpCommand(\n command,\n context.gatewayUrl,\n context.gatewayToken,\n context.backendToken\n );\n const lines = formatMcpResult(command, handshake, response);\n return {lines};\n}\n\nasync function executeServers(context: CommandExecutionContext) {\n // Use the registry client to list servers instead of MCP call\n const result = await callRegistryWrapper([\"anthropic\", \"list\", \"--limit\", \"1000\"], context);\n\n if (result.exitCode !== 0) {\n return {\n lines: [`Error listing servers:`, result.stderr || result.stdout],\n isError: true\n };\n }\n\n try {\n const data = JSON.parse(result.stdout);\n const servers = data.servers || [];\n\n if (servers.length === 0) {\n return {lines: [\"No servers found.\"]};\n }\n\n const lines: string[] = [`Found ${servers.length} MCP servers:\\n`];\n\n servers.forEach((serverResponse: any, index: number) => {\n const server = serverResponse.server || serverResponse;\n const meta = server._meta || server.meta || {};\n const internalMeta = meta['io.mcpgateway/internal'] || {};\n\n lines.push(`${index + 1}. ${server.name || 'Unknown'}`);\n lines.push(` Path: ${internalMeta.path || 'N/A'}`);\n lines.push(` Status: ${internalMeta.is_enabled ? 'enabled' : 'disabled'}`);\n if (server.description) {\n const desc = server.description.length > 80\n ? server.description.substring(0, 80) + '...'\n : server.description;\n lines.push(` Description: ${desc}`);\n }\n if (server.tags && server.tags.length > 0) {\n lines.push(` Tags: ${server.tags.slice(0, 5).join(', ')}${server.tags.length > 5 ? '...' : ''}`);\n }\n if (server.tools && server.tools.length > 0) {\n lines.push(` Tools: ${server.tools.length}`);\n }\n lines.push('');\n });\n\n lines.push(`Total: ${servers.length} servers\\n`);\n lines.push('Tip: Ask \"tell me more about server X\" for detailed info');\n\n return {lines};\n } catch (error) {\n return {lines: [`Error parsing server list: ${(error as Error).message}`], isError: true};\n }\n}\n\nasync function executeCall(parsed: CallCommand, context: CommandExecutionContext) {\n if (!parsed.tool) {\n return {lines: [\"Tool name is required for /call.\"], isError: true};\n }\n\n let args: Record = {};\n if (parsed.argsJson) {\n try {\n args = JSON.parse(parsed.argsJson);\n } catch (error) {\n return {lines: [`Invalid JSON for args: ${(error as Error).message}`], isError: true};\n }\n }\n\n const {handshake, response} = await executeMcpCommand(\n \"call\",\n context.gatewayUrl,\n context.gatewayToken,\n context.backendToken,\n {tool: parsed.tool, args}\n );\n const lines = formatMcpResult(\"call\", handshake, response, parsed.tool);\n return {lines};\n}\n\nasync function executeAgents(parsed: AgentsCommand, context: CommandExecutionContext) {\n const subcommand = parsed.subcommand.toLowerCase();\n\n switch (subcommand) {\n case \"help\":\n return {lines: [describeAgents()]};\n\n case \"list\":\n return await executeAgentsList(context);\n\n case \"get\":\n if (parsed.tokens.length === 0) {\n return {lines: [\"Agent path required. Usage: /agents get /agent-path\"], isError: true};\n }\n return await executeAgentsGet(parsed.tokens[0], context);\n\n case \"search\":\n if (parsed.tokens.length === 0) {\n return {lines: [\"Search query required. Usage: /agents search \"], isError: true};\n }\n return await executeAgentsSearch(parsed.tokens.join(\" \"), context);\n\n case \"test\":\n if (parsed.tokens.length === 0) {\n return {lines: [\"Agent path required. Usage: /agents test /agent-path\"], isError: true};\n }\n return await executeAgentsTest(parsed.tokens[0], context);\n\n case \"test-all\":\n return await executeAgentsTestAll(context);\n\n default:\n return {lines: [`Unknown agent subcommand: ${subcommand}. Try \"/agents help\".`], isError: true};\n }\n}\n\nasync function executeAgentsList(context: CommandExecutionContext) {\n const result = await callRegistryWrapper([\"agent\", \"list\"], context);\n\n if (result.exitCode !== 0) {\n return {\n lines: [`Error listing agents:`, result.stderr || result.stdout],\n isError: true\n };\n }\n\n return {lines: [result.stdout]};\n}\n\nasync function executeAgentsGet(agentPath: string, context: CommandExecutionContext) {\n const result = await callRegistryWrapper([\"agent\", \"get\", agentPath], context);\n\n if (result.exitCode !== 0) {\n return {\n lines: [`Error getting agent:`, result.stderr || result.stdout],\n isError: true\n };\n }\n\n return {lines: [result.stdout]};\n}\n\nasync function executeAgentsSearch(query: string, context: CommandExecutionContext) {\n const result = await callRegistryWrapper([\"agent\", \"search\", query], context);\n\n if (result.exitCode !== 0) {\n return {\n lines: [`Error searching agents:`, result.stderr || result.stdout],\n isError: true\n };\n }\n\n return {lines: [result.stdout]};\n}\n\nasync function executeAgentsTest(agentPath: string, context: CommandExecutionContext) {\n const result = await callRegistryWrapper([\"agent\", \"get\", agentPath], context);\n\n if (result.exitCode !== 0) {\n return {\n lines: [`Error testing agent:`, result.stderr || result.stdout],\n isError: true\n };\n }\n\n try {\n const agent = JSON.parse(result.stdout);\n const lines: string[] = [];\n\n lines.push(`Testing agent: ${agent.name || agentPath}`);\n lines.push(`✓ Agent registered`);\n lines.push(`✓ Endpoint accessible`);\n if (agent.is_enabled) {\n lines.push(`✓ Agent enabled`);\n } else {\n lines.push(`⚠ Agent is disabled`);\n }\n\n return {lines};\n } catch (error) {\n return {lines: [`Error parsing agent data: ${(error as Error).message}`], isError: true};\n }\n}\n\nasync function executeAgentsTestAll(context: CommandExecutionContext) {\n const result = await callRegistryWrapper([\"agent\", \"list\"], context);\n\n if (result.exitCode !== 0) {\n return {\n lines: [`Error testing agents:`, result.stderr || result.stdout],\n isError: true\n };\n }\n\n try {\n const data = JSON.parse(result.stdout);\n const agents = Array.isArray(data.agents) ? data.agents : [];\n\n if (agents.length === 0) {\n return {lines: [\"No agents to test.\"]};\n }\n\n const lines: string[] = [`Testing ${agents.length} agent(s)...\\n`];\n let healthy = 0;\n let unhealthy = 0;\n\n agents.forEach((agent: any) => {\n if (agent.is_enabled) {\n lines.push(`✓ ${agent.name || agent.path} - operational`);\n healthy++;\n } else {\n lines.push(`✗ ${agent.name || agent.path} - disabled`);\n unhealthy++;\n }\n });\n\n lines.push(\"\");\n lines.push(`Summary: ${healthy}/${agents.length} agents operational`);\n if (unhealthy > 0) {\n lines.push(`Issue detected: ${unhealthy} agent(s) disabled or unavailable`);\n }\n\n return {lines};\n } catch (error) {\n return {lines: [`Error parsing agent data: ${(error as Error).message}`], isError: true};\n }\n}\n\nfunction describeAgents(): string {\n return [\n \"Agent Registry Commands\",\n \"\",\n \"Discover and interact with registered A2A agents:\",\n \"\",\n \" /agents list List all available agents\",\n \" /agents get Get details about a specific agent\",\n \" /agents search Search agents by capability\",\n \" /agents test Test agent availability\",\n \" /agents test-all Test all agents\",\n \"\",\n \"Examples:\",\n \" /agents list\",\n \" /agents get /code-reviewer\",\n \" /agents search \\\"code review\\\"\",\n \" /agents test /code-reviewer\",\n \"\",\n \"For more information, see the Agent CLI Guide: docs/agents-cli-guide.md\"\n ].join(\"\\n\");\n}\n\nexport function overviewMessage(): string {\n return [\n \"Chat with me using natural language - I can discover and use MCP tools for you!\",\n \"\",\n \"Essential commands:\",\n \" /help Show help message\",\n \" /exit Exit the CLI\",\n \" /ping Test gateway connectivity\",\n \" /list List available tools\",\n \" /servers List all MCP servers\",\n \" /agents Discover and use A2A agents\",\n \"\",\n \"Examples:\",\n \" \\\"How do I import servers from the Anthropic registry?\\\"\",\n \" \\\"What authentication methods are supported by the servers?\\\"\",\n \" \\\"What transport types do the servers support (stdio, SSE, HTTP)?\\\"\",\n \" \\\"What agents are available?\\\"\",\n \" \\\"Can you review my code?\\\"\",\n\n \"\"\n ].join(\"\\n\");\n}\n\nexport function detailedHelpMessage(): string {\n const basicCommands = [\n { cmd: \"/help\", desc: \"Show this help message\" },\n { cmd: \"/servers\", desc: \"List all MCP servers\" },\n { cmd: \"/exit\", desc: \"Exit the CLI (aliases: /quit, /q)\" }\n ];\n\n const advancedCommands = [\n { cmd: \"/ping\", desc: \"Check MCP gateway connectivity\" },\n { cmd: \"/list\", desc: \"List MCP tools from current server\" },\n { cmd: \"/call\", args: \"tool= args=''\", desc: \"Invoke a tool directly\" },\n { cmd: \"/refresh\", desc: \"Refresh OAuth tokens\" },\n { cmd: \"/retry\", desc: \"Retry authentication\" }\n ];\n\n const agentCommands = [\n { cmd: \"/agents\", desc: \"Agent registry help\" },\n { cmd: \"/agents list\", desc: \"List all available agents\" },\n { cmd: \"/agents get\", args: \"\", desc: \"Get details about an agent\" },\n { cmd: \"/agents search\", args: \"\", desc: \"Search agents by capability\" },\n { cmd: \"/agents test\", args: \"\", desc: \"Test agent availability\" },\n { cmd: \"/agents test-all\", desc: \"Test all registered agents\" }\n ];\n\n const registryCommands = [\n { cmd: \"/service\", desc: \"Service management (add, delete, monitor, test, groups)\" },\n { cmd: \"/import\", desc: \"Import from registry (dry, apply)\" },\n { cmd: \"/user\", desc: \"User management (create-m2m, create-human, delete, list)\" },\n { cmd: \"/diagnostic\", desc: \"Run diagnostics (run-suite, run-test)\" }\n ];\n\n const formatCommands = (cmds: Array<{cmd: string; args?: string; desc: string}>) => {\n const maxLength = Math.max(...cmds.map(c => (c.cmd + (c.args ? \" \" + c.args : \"\")).length));\n return cmds.map(({cmd, args, desc}) => {\n const full = cmd + (args ? \" \" + args : \"\");\n const padding = \" \".repeat(maxLength - full.length + 2);\n return ` ${full}${padding}${desc}`;\n });\n };\n\n return [\n \"MCP Gateway CLI - Natural Language Interface\",\n \"\",\n \"PREFERRED: Use natural language to interact with MCP tools\",\n \"Examples:\",\n \" \\\"What tools are available?\\\"\",\n \" \\\"Check the current time in New York\\\"\",\n \" \\\"Find tools for weather information\\\"\",\n \" \\\"What agents are available?\\\"\",\n \" \\\"Can you find an agent for code review?\\\"\",\n \"\",\n \"Basic Commands:\",\n ...formatCommands(basicCommands),\n \"\",\n \"Advanced Commands (for debugging):\",\n ...formatCommands(advancedCommands),\n \"\",\n \"Agent Management:\",\n ...formatCommands(agentCommands),\n \"\",\n \"Registry Management:\",\n ...formatCommands(registryCommands)\n ].join(\"\\n\");\n}\n" }, { "path": "cli/src/components/Banner.tsx", "content": "import React from \"react\";\nimport { Box, Text } from \"ink\";\n\nexport function Banner() {\n return (\n \n \n \n {\"███╗ ███╗ ██████╗██████╗ \"}\n {\"██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗ ██╗\"}\n {\" ██████╗██╗ ██╗\"}\n \n \n \n \n {\"████╗ ████║██╔════╝██╔══██╗\"}\n {\"██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝\"}\n {\" ██╔════╝██║ ██║\"}\n \n \n \n \n {\"██╔████╔██║██║ ██████╔╝\"}\n {\"██████╔╝█████╗ ██║ ███╗██║███████╗ ██║ ██████╔╝ ╚████╔╝ \"}\n {\" ██║ ██║ ██║\"}\n \n \n \n \n {\"██║╚██╔╝██║██║ ██╔═══╝ \"}\n {\"██╔══██╗██╔══╝ ██║ ██║██║╚════██║ ██║ ██╔══██╗ ╚██╔╝ \"}\n {\" ██║ ██║ ██║\"}\n \n \n \n \n {\"██║ ╚═╝ ██║╚██████╗██║ \"}\n {\"██║ ██║███████╗╚██████╔╝██║███████║ ██║ ██║ ██║ ██║ \"}\n {\" ╚██████╗███████╗██║\"}\n \n \n \n \n {\"╚═╝ ╚═╝ ╚═════╝╚═╝ \"}\n {\"╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ \"}\n {\" ╚═════╝╚══════╝╚═╝\"}\n \n \n \n );\n}\n" }, { "path": "cli/src/components/CallToolForm.tsx", "content": "import React, {useState} from \"react\";\nimport {Box, Text, useInput} from \"ink\";\nimport TextInput from \"ink-text-input\";\n\nexport interface CallToolPayload {\n tool: string;\n args: string;\n}\n\ninterface CallToolFormProps {\n initialTool?: string;\n initialArgs?: string;\n onSubmit: (payload: CallToolPayload) => void;\n onCancel: () => void;\n}\n\nconst DEFAULT_ARGS = \"{}\";\n\nexport function CallToolForm({initialTool, initialArgs, onSubmit, onCancel}: CallToolFormProps) {\n const [step, setStep] = useState<\"tool\" | \"args\">(\"tool\");\n const [tool, setTool] = useState(initialTool ?? \"\");\n const [args, setArgs] = useState(initialArgs ?? DEFAULT_ARGS);\n\n useInput((_input, key) => {\n if (key.escape) {\n onCancel();\n }\n });\n\n const handleToolSubmit = (value: string) => {\n const trimmed = value.trim();\n if (trimmed.length === 0) {\n return;\n }\n setTool(trimmed);\n setStep(\"args\");\n };\n\n const handleArgsSubmit = (value: string) => {\n onSubmit({\n tool,\n args: value.trim().length === 0 ? DEFAULT_ARGS : value.trim()\n });\n };\n\n return (\n \n \n Tool name\n \n \n {step === \"args\" && (\n \n Tool arguments (JSON)\n \n \n Press ↵ to run, Esc to cancel. Leave blank to send {DEFAULT_ARGS}.\n \n \n )}\n \n );\n}\n" }, { "path": "cli/src/components/CommandSuggestions.tsx", "content": "import React from \"react\";\nimport { Box, Text } from \"ink\";\nimport type { CommandOption } from \"../utils/commands.js\";\n\ninterface CommandSuggestionsProps {\n suggestions: CommandOption[];\n selectedIndex: number;\n}\n\nexport function CommandSuggestions({ suggestions, selectedIndex }: CommandSuggestionsProps) {\n if (suggestions.length === 0) {\n return null;\n }\n\n // Calculate max command length for alignment\n const maxCommandLength = Math.max(...suggestions.map(s => s.command.length));\n\n return (\n \n {suggestions.map((suggestion, index) => {\n const isSelected = index === selectedIndex;\n const padding = \" \".repeat(maxCommandLength - suggestion.command.length);\n\n return (\n \n \n {isSelected ? \"› \" : \" \"}\n \n \n {suggestion.command}\n \n \n {padding} {suggestion.description}\n \n \n );\n })}\n \n );\n}\n" }, { "path": "cli/src/components/JsonViewer.tsx", "content": "import React from \"react\";\nimport {Box, Text} from \"ink\";\n\ninterface JsonViewerProps {\n data: unknown;\n label?: string;\n raw?: boolean;\n}\n\nexport function JsonViewer({data, label, raw}: JsonViewerProps) {\n const json = stringify(data, raw);\n return (\n \n {label ? (\n \n {label}\n \n \n ) : null}\n {json}\n \n );\n}\n\nfunction stringify(data: unknown, raw = false): string {\n if (raw) {\n return typeof data === \"string\" ? data : JSON.stringify(data);\n }\n return JSON.stringify(data, null, 2);\n}\n" }, { "path": "cli/src/components/MultiStepForm.tsx", "content": "import React, {useEffect, useMemo, useState} from \"react\";\nimport {Box, Text, useInput} from \"ink\";\nimport TextInput from \"ink-text-input\";\n\nimport type {TaskField} from \"../tasks/types.js\";\n\ninterface MultiStepFormProps {\n fields: TaskField[];\n initialValues?: Record;\n onSubmit: (values: Record) => void;\n onCancel: () => void;\n heading: string;\n}\n\nexport function MultiStepForm({fields, initialValues = {}, onSubmit, onCancel, heading}: MultiStepFormProps) {\n const [stepIndex, setStepIndex] = useState(0);\n const [values, setValues] = useState>({...initialValues});\n const [inputValue, setInputValue] = useState(\"\");\n const [error, setError] = useState();\n\n const currentField = fields[stepIndex];\n\n useEffect(() => {\n if (fields.length === 0) {\n onSubmit(values);\n }\n }, [fields, onSubmit, values]);\n\n useEffect(() => {\n if (currentField) {\n setInputValue(values[currentField.name] ?? currentField.defaultValue ?? \"\");\n }\n }, [currentField, values]);\n\n useInput((input, key) => {\n if (key.escape) {\n onCancel();\n }\n if (!currentField) {\n if (key.return) {\n onSubmit(values);\n }\n return;\n }\n if (input === \"\\u0017\") {\n // ctrl+w clears input\n setInputValue(\"\");\n }\n });\n\n const instructions = useMemo(() => {\n if (!currentField) {\n return \"Press ↵ to continue or Esc to cancel.\";\n }\n return currentField.optional ? \"Enter a value or leave blank, ↵ to accept, Esc to cancel.\" : \"Enter a value, ↵ to accept, Esc to cancel.\";\n }, [currentField]);\n\n const handleSubmit = (value: string) => {\n if (!currentField) {\n onSubmit(values);\n return;\n }\n\n const trimmed = value.trim();\n if (!currentField.optional && trimmed.length === 0 && !(currentField.defaultValue && currentField.defaultValue.length > 0)) {\n setError(\"This field is required.\");\n return;\n }\n\n setError(undefined);\n\n const nextValues = {\n ...values,\n [currentField.name]: trimmed.length === 0 ? \"\" : trimmed\n };\n\n setValues(nextValues);\n\n if (stepIndex + 1 >= fields.length) {\n onSubmit(nextValues);\n return;\n }\n\n setStepIndex((index) => index + 1);\n };\n\n if (!currentField && fields.length > 0) {\n return null;\n }\n\n return (\n \n {heading}\n {currentField ? (\n \n \n {currentField.label}\n {currentField.optional ? (optional) : null}\n \n {currentField.placeholder ? {currentField.placeholder} : null}\n \n \n ) : (\n All fields captured. Press ↵ to continue.\n )}\n {instructions}\n {error ? {error} : null}\n \n );\n}\n" }, { "path": "cli/src/components/StatusMessage.tsx", "content": "import React from \"react\";\nimport {Text} from \"ink\";\n\ninterface StatusMessageProps {\n variant: \"info\" | \"warning\" | \"error\";\n message: string;\n}\n\nexport function StatusMessage({variant, message}: StatusMessageProps) {\n if (variant === \"warning\") {\n return {message};\n }\n\n if (variant === \"error\") {\n return {`❌ ${message}`};\n }\n\n return {message};\n}\n" }, { "path": "cli/src/components/TaskRunner.tsx", "content": "import React, {useEffect, useRef, useState} from \"react\";\nimport {Box, Text, useInput} from \"ink\";\nimport {spawn} from \"node:child_process\";\n\nimport {REPO_ROOT} from \"../paths.js\";\nimport type {ScriptCommand} from \"../tasks/types.js\";\n\ntype RunnerStatus = \"running\" | \"success\" | \"error\";\n\ninterface LogEntry {\n id: number;\n type: \"stdout\" | \"stderr\";\n text: string;\n}\n\ninterface TaskRunnerProps {\n title: string;\n description?: string;\n command: ScriptCommand;\n onDone: (exitCode: number | null) => void;\n}\n\nexport function TaskRunner({title, description, command, onDone}: TaskRunnerProps) {\n const [status, setStatus] = useState(\"running\");\n const [exitCode, setExitCode] = useState(null);\n const [logs, setLogs] = useState([]);\n const nextId = useRef(0);\n const processRef = useRef | null>(null);\n\n useEffect(() => {\n const env = command.env ? {...process.env, ...command.env} : process.env;\n const child = spawn(command.command, command.args, {\n cwd: REPO_ROOT,\n env,\n stdio: [\"ignore\", \"pipe\", \"pipe\"]\n });\n processRef.current = child;\n\n const handleData = (type: LogEntry[\"type\"]) => (chunk: Buffer) => {\n const text = chunk.toString();\n const lines = text.replace(/\\r\\n/g, \"\\n\").split(\"\\n\");\n setLogs((prev) => [\n ...prev,\n ...lines\n .filter((line) => line.length > 0)\n .map((line) => ({\n id: nextId.current++,\n type,\n text: line\n }))\n ]);\n };\n\n child.stdout?.on(\"data\", handleData(\"stdout\"));\n child.stderr?.on(\"data\", handleData(\"stderr\"));\n\n child.on(\"close\", (code) => {\n setExitCode(code);\n setStatus(code === 0 ? \"success\" : \"error\");\n });\n\n child.on(\"error\", (error) => {\n setLogs((prev) => [\n ...prev,\n {\n id: nextId.current++,\n type: \"stderr\",\n text: `Failed to start process: ${error.message}`\n }\n ]);\n setExitCode(-1);\n setStatus(\"error\");\n });\n\n return () => {\n if (processRef.current && status === \"running\") {\n processRef.current.kill(\"SIGTERM\");\n }\n };\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, []);\n\n useInput((input, key) => {\n if (status === \"running\") {\n if (key.escape || (key.ctrl && input === \"c\")) {\n processRef.current?.kill(\"SIGINT\");\n }\n return;\n }\n\n if (key.return || input === \"q\") {\n onDone(exitCode);\n }\n });\n\n return (\n \n \n {title}\n \n {description ? {description} : null}\n \n Command: \n \n {command.command} {command.args.join(\" \")}\n \n \n \n {logs.length === 0 ? No output yet... : null}\n {logs.map((entry) => (\n \n {entry.text}\n \n ))}\n \n {status === \"running\" ? (\n Running… (Esc to cancel)\n ) : status === \"success\" ? (\n \n ✓ Completed with exit code {exitCode ?? 0}. Press ↵ to return or q to quit this view.\n \n ) : (\n \n ✗ Failed with exit code {exitCode ?? -1}. Press ↵ to return or q to quit this view.\n \n )}\n \n );\n}\n" }, { "path": "cli/src/components/TokenFileEditor.tsx", "content": "import React, {useState} from \"react\";\nimport {Box, Text, useInput} from \"ink\";\nimport TextInput from \"ink-text-input\";\n\ninterface TokenFileEditorProps {\n initialPath?: string;\n onSubmit: (value?: string) => void;\n onCancel: () => void;\n}\n\nexport function TokenFileEditor({initialPath, onSubmit, onCancel}: TokenFileEditorProps) {\n const [value, setValue] = useState(initialPath ?? \"\");\n\n useInput((_input, key) => {\n if (key.escape) {\n onCancel();\n }\n });\n\n const handleSubmit = (input: string) => {\n const trimmed = input.trim();\n onSubmit(trimmed.length > 0 ? trimmed : undefined);\n };\n\n return (\n \n Token file path\n \n Enter a path to use, leave blank to clear, Esc to cancel.\n \n );\n}\n" }, { "path": "cli/src/components/TokenStatusFooter.tsx", "content": "import {Box, Text} from \"ink\";\n\ninterface TokenStatusFooterProps {\n secondsRemaining?: number;\n expired: boolean;\n isRefreshing: boolean;\n lastRefresh?: Date;\n source?: string;\n model?: string;\n inputTokens?: number;\n outputTokens?: number;\n cost?: number;\n registryVersion?: string;\n}\n\nexport function TokenStatusFooter({\n secondsRemaining,\n expired,\n isRefreshing,\n lastRefresh,\n source,\n model,\n inputTokens,\n outputTokens,\n cost,\n registryVersion\n}: TokenStatusFooterProps) {\n const formatTime = (seconds: number): string => {\n if (seconds < 0) return \"expired\";\n if (seconds < 60) return `${seconds}s`;\n const mins = Math.floor(seconds / 60);\n const secs = seconds % 60;\n return `${mins}m ${secs}s`;\n };\n\n const getStatusText = (): string => {\n if (isRefreshing) return \"Refreshing...\";\n if (expired || (secondsRemaining !== undefined && secondsRemaining <= 0)) return \"Expired\";\n if (secondsRemaining !== undefined) return `Valid for ${formatTime(secondsRemaining)}`;\n return \"Unknown\";\n };\n\n const getStatusColor = (): string => {\n if (isRefreshing) return \"cyan\";\n if (expired || (secondsRemaining !== undefined && secondsRemaining <= 0)) return \"red\";\n if (secondsRemaining !== undefined && secondsRemaining < 60) return \"yellow\";\n return \"green\";\n };\n\n const lastRefreshText = lastRefresh\n ? lastRefresh.toLocaleTimeString(\"en-US\", {hour12: false})\n : \"N/A\";\n\n const formatCost = (costValue: number): string => {\n if (costValue >= 0.01) {\n return `$${costValue.toFixed(2)}`;\n } else if (costValue >= 0.001) {\n return `$${costValue.toFixed(4)}`;\n } else if (costValue > 0) {\n return `$${costValue.toFixed(6)}`;\n } else {\n return \"$0.00\";\n }\n };\n\n return (\n \n \n Token: {getStatusText()}\n \n {source && (\n \n | Source: \n {source}\n \n )}\n \n | Last refresh: \n {lastRefreshText}\n \n {model && (\n \n | Model: \n {model}\n \n )}\n {(inputTokens !== undefined || outputTokens !== undefined) && (inputTokens! > 0 || outputTokens! > 0) && (\n \n | Tokens: \n In: {(inputTokens || 0).toLocaleString()}\n | \n Out: {(outputTokens || 0).toLocaleString()}\n \n )}\n {cost !== undefined && cost > 0 && (\n \n | Cost: \n {formatCost(cost)}\n \n )}\n {registryVersion && (\n \n | Registry: \n {registryVersion}\n \n )}\n \n );\n}\n" }, { "path": "cli/src/components/UrlEditor.tsx", "content": "import React, {useState} from \"react\";\nimport {Box, Text, useInput} from \"ink\";\nimport TextInput from \"ink-text-input\";\n\ninterface UrlEditorProps {\n initialUrl: string;\n onSubmit: (value: string) => void;\n onCancel: () => void;\n}\n\nexport function UrlEditor({initialUrl, onSubmit, onCancel}: UrlEditorProps) {\n const [value, setValue] = useState(initialUrl);\n\n useInput((_input, key) => {\n if (key.escape) {\n onCancel();\n }\n });\n\n const handleSubmit = (url: string) => {\n const trimmed = url.trim();\n if (trimmed.length > 0) {\n onSubmit(trimmed);\n } else {\n onCancel();\n }\n };\n\n return (\n \n Gateway URL\n \n Press ↵ to confirm or Esc to keep the current URL.\n \n );\n}\n" }, { "path": "cli/src/index.tsx", "content": "#!/usr/bin/env node\nimport \"dotenv/config\";\nimport React from \"react\";\nimport {render} from \"ink\";\n\nimport App from \"./app.js\";\nimport {HELP_TEXT, parseArgs} from \"./parseArgs.js\";\n\nconst parsed = parseArgs(process.argv.slice(2));\n\nif (parsed.helpRequested) {\n // eslint-disable-next-line no-console\n console.log(HELP_TEXT);\n process.exit(0);\n}\n\nif (parsed.unknown.length > 0) {\n // eslint-disable-next-line no-console\n console.warn(`Ignoring unknown arguments: ${parsed.unknown.join(\", \")}`);\n}\n\nrender();\n" }, { "path": "cli/src/parseArgs.ts", "content": "export type CommandName = \"ping\" | \"list\" | \"call\" | \"init\";\n\nexport interface ParsedArgs {\n url?: string;\n tokenFile?: string;\n token?: string;\n command?: CommandName;\n tool?: string;\n args?: string;\n json?: boolean;\n interactive: boolean;\n helpRequested?: boolean;\n unknown: string[];\n}\n\nconst COMMANDS = new Set([\"ping\", \"list\", \"call\", \"init\"]);\n\nexport const HELP_TEXT = `\nUsage\n mcp-ink [options] [command]\n\nCommands\n ping Test connectivity with the configured MCP gateway\n list List available tools for the current session\n call Invoke a specific tool (use --tool and --args)\n init Initialize the session and print the handshake payload\n\nOptions\n --url, -u Override the MCP gateway URL (default: http://localhost/mcpgw/mcp)\n --token-file, -t Path to a file containing a bearer token\n --token Explicit bearer token (overrides token file)\n --command Run a command non-interactively (alias for specifying the command positionally)\n --tool Tool name for the call command\n --args JSON string with tool arguments for the call command\n --json Print raw JSON responses without formatting\n --interactive Force interactive mode even when a command is provided\n --no-interactive Force non-interactive mode\n --help, -h Show this help message\n`.trim();\n\nexport function parseArgs(argv: string[]): ParsedArgs {\n const result: ParsedArgs = {\n interactive: true,\n unknown: []\n };\n\n const consumeValue = (index: number): string | undefined => {\n const value = argv[index + 1];\n if (value === undefined) {\n return undefined;\n }\n return value;\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const arg = argv[i];\n\n switch (arg) {\n case \"--url\":\n case \"-u\": {\n const value = consumeValue(i);\n if (value !== undefined) {\n result.url = value;\n i += 1;\n }\n break;\n }\n case \"--token-file\":\n case \"-t\": {\n const value = consumeValue(i);\n if (value !== undefined) {\n result.tokenFile = value;\n i += 1;\n }\n break;\n }\n case \"--token\": {\n const value = consumeValue(i);\n if (value !== undefined) {\n result.token = value;\n i += 1;\n }\n break;\n }\n case \"--command\": {\n const value = consumeValue(i);\n if (value !== undefined && isCommand(value)) {\n result.command = value;\n result.interactive = false;\n i += 1;\n }\n break;\n }\n case \"--tool\": {\n const value = consumeValue(i);\n if (value !== undefined) {\n result.tool = value;\n i += 1;\n }\n break;\n }\n case \"--args\": {\n const value = consumeValue(i);\n if (value !== undefined) {\n result.args = value;\n i += 1;\n }\n break;\n }\n case \"--json\": {\n result.json = true;\n break;\n }\n case \"--interactive\": {\n result.interactive = true;\n break;\n }\n case \"--no-interactive\": {\n result.interactive = false;\n break;\n }\n case \"--help\":\n case \"-h\": {\n result.helpRequested = true;\n result.interactive = false;\n break;\n }\n default: {\n if (arg.startsWith(\"--\")) {\n result.unknown.push(arg);\n break;\n }\n\n if (!result.command && isCommand(arg)) {\n result.command = arg;\n result.interactive = false;\n break;\n }\n\n if (result.command === \"call\") {\n if (!result.tool) {\n result.tool = arg;\n break;\n }\n if (!result.args) {\n result.args = arg;\n break;\n }\n }\n\n result.unknown.push(arg);\n }\n }\n }\n\n return result;\n}\n\nfunction isCommand(value: string): value is CommandName {\n return COMMANDS.has(value as CommandName);\n}\n" }, { "path": "cli/src/paths.ts", "content": "import path from \"node:path\";\nimport {fileURLToPath} from \"node:url\";\n\nconst SRC_DIR = fileURLToPath(new URL(\".\", import.meta.url));\nexport const CLI_ROOT = path.resolve(SRC_DIR, \"..\");\nexport const REPO_ROOT = path.resolve(CLI_ROOT, \"..\");\n\n// Modern Python API wrapper (replaces deprecated shell scripts)\nexport const REGISTRY_CLI_WRAPPER = path.join(CLI_ROOT, \"registry_cli_wrapper.py\");\n\n// Legacy scripts (deprecated - kept for backwards compatibility)\nexport const SERVICE_MANAGEMENT_SCRIPT = path.join(CLI_ROOT, \"service_mgmt.sh\");\nexport const IMPORT_ANTHROPIC_SCRIPT = path.join(CLI_ROOT, \"import_from_anthropic_registry.sh\");\nexport const USER_MANAGEMENT_SCRIPT = path.join(CLI_ROOT, \"user_mgmt.sh\");\nexport const TEST_ANTHROPIC_SCRIPT = path.join(CLI_ROOT, \"test_anthropic_api.py\");\nexport const DEFAULT_IMPORT_LIST = path.join(CLI_ROOT, \"import_server_list.txt\");\n" }, { "path": "cli/src/runtime/mcp.ts", "content": "import type {CommandName} from \"../parseArgs.js\";\nimport type {JsonRpcResponse} from \"../types/mcp.js\";\nimport {executePythonMcpCommand} from \"./pythonClient.js\";\n\nexport interface McpExecutionResult {\n handshake: JsonRpcResponse;\n response: JsonRpcResponse;\n}\n\n/**\n * Execute MCP command using the Python client backend.\n *\n * This function bridges the TypeScript CLI to the Python mcp_client.py,\n * eliminating duplicate client implementations while maintaining the Ink UI.\n */\nexport async function executeMcpCommand(\n command: CommandName,\n gatewayUrl: string,\n gatewayToken?: string,\n backendToken?: string,\n callOptions?: {tool: string; args: Record}\n): Promise {\n // Delegate to Python client\n return executePythonMcpCommand(\n command,\n gatewayUrl,\n gatewayToken,\n backendToken,\n callOptions\n );\n}\n\nexport function formatMcpResult(\n command: \"ping\" | \"list\" | \"init\" | \"call\",\n handshake: JsonRpcResponse,\n response: JsonRpcResponse,\n tool?: string\n): string[] {\n const lines: string[] = [];\n const sessionId = (handshake as {result?: {sessionId?: string}}).result?.sessionId;\n if (sessionId) {\n lines.push(`Session established: ${sessionId}`);\n }\n if (command === \"ping\") {\n lines.push(\"Ping response:\");\n lines.push(JSON.stringify(response, null, 2));\n } else if (command === \"list\") {\n lines.push(\"Available tools:\");\n lines.push(JSON.stringify(response, null, 2));\n } else if (command === \"call\") {\n lines.push(`Tool \"${tool}\" response:`);\n lines.push(JSON.stringify(response, null, 2));\n } else if (command === \"init\") {\n lines.push(\"Initialization payload:\");\n lines.push(JSON.stringify(handshake, null, 2));\n }\n return lines;\n}\n" }, { "path": "cli/src/runtime/pythonClient.ts", "content": "import {spawn, type ChildProcess} from \"child_process\";\nimport {resolve, join, dirname} from \"path\";\nimport {writeFileSync, unlinkSync, mkdtempSync} from \"fs\";\nimport {tmpdir} from \"os\";\nimport {fileURLToPath} from \"url\";\nimport type {JsonRpcResponse} from \"../types/mcp.js\";\n\n// ES module compatibility for __dirname\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nexport interface PythonMcpExecutionResult {\n handshake: JsonRpcResponse;\n response: JsonRpcResponse;\n}\n\n/**\n * Execute Python MCP client command\n *\n * This bridges the TypeScript CLI to the Python mcp_client.py,\n * eliminating duplicate client code while maintaining the Ink UI.\n */\nexport async function executePythonMcpCommand(\n command: \"ping\" | \"list\" | \"init\" | \"call\",\n gatewayUrl: string,\n gatewayToken?: string,\n backendToken?: string,\n callOptions?: {tool: string; args: Record}\n): Promise {\n // Build Python command arguments\n const pythonScript = resolve(__dirname, \"../../mcp_client.py\");\n const args = [\"--url\", gatewayUrl];\n\n let tokenFile: string | undefined;\n\n // Add authentication if available\n // Priority: gatewayToken (for MCP gateway) > backendToken (for specific servers)\n const tokenToUse = gatewayToken || backendToken;\n if (tokenToUse) {\n // Use a temporary file to pass the token\n // Write ONLY the token string (not JSON) as Python client expects plain token\n const tmpDir = mkdtempSync(join(tmpdir(), \"mcp-token-\"));\n tokenFile = join(tmpDir, \".mcp_token\");\n\n try {\n // Ensure we write just the token string, not any JSON wrapper\n const tokenString = tokenToUse.trim();\n writeFileSync(tokenFile, tokenString);\n args.push(\"--token-file\", tokenFile);\n } catch (error) {\n // Clean up temp file\n try {\n if (tokenFile) {\n unlinkSync(tokenFile);\n }\n } catch {\n // Ignore cleanup errors\n }\n throw error;\n }\n }\n\n // Add command\n args.push(command);\n\n // Add tool call parameters if needed\n if (command === \"call\" && callOptions) {\n args.push(\"--tool\", callOptions.tool);\n if (callOptions.args && Object.keys(callOptions.args).length > 0) {\n args.push(\"--args\", JSON.stringify(callOptions.args));\n }\n }\n\n // Execute Python script\n return new Promise((promiseResolve, promiseReject) => {\n let stdout = \"\";\n let stderr = \"\";\n\n // Use uv run to execute the Python script\n const proc: ChildProcess = spawn(\"uv\", [\"run\", pythonScript, ...args], {\n cwd: resolve(__dirname, \"../..\"),\n env: process.env\n });\n\n if (proc.stdout) {\n proc.stdout.on(\"data\", (data: Buffer) => {\n stdout += data.toString();\n });\n }\n\n if (proc.stderr) {\n proc.stderr.on(\"data\", (data: Buffer) => {\n stderr += data.toString();\n });\n }\n\n proc.on(\"error\", (error: Error) => {\n // Clean up temp file\n if (tokenFile) {\n try {\n unlinkSync(tokenFile);\n } catch {\n // Ignore cleanup errors\n }\n }\n promiseReject(new Error(`Failed to execute Python client: ${error.message}`));\n });\n\n proc.on(\"close\", (code: number | null) => {\n // Clean up temp file\n if (tokenFile) {\n try {\n unlinkSync(tokenFile);\n } catch {\n // Ignore cleanup errors\n }\n }\n\n if (code !== 0) {\n promiseReject(new Error(`Python client exited with code ${code}: ${stderr}`));\n return;\n }\n\n try {\n // Parse the JSON output from Python client\n const lines = stdout.trim().split(\"\\n\");\n\n // Find the JSON response (skip authentication success messages)\n // The JSON may span multiple lines, so we need to collect all lines from the first { to the last }\n let jsonStartIndex = -1;\n let jsonEndIndex = -1;\n\n for (let i = 0; i < lines.length; i++) {\n const line = lines[i].trim();\n if (jsonStartIndex === -1 && (line.startsWith(\"{\") || line.startsWith(\"[\"))) {\n jsonStartIndex = i;\n }\n if (jsonStartIndex !== -1 && (line.endsWith(\"}\") || line.endsWith(\"]\"))) {\n jsonEndIndex = i;\n // Continue to find the last closing brace\n }\n }\n\n if (jsonStartIndex === -1 || jsonEndIndex === -1) {\n promiseReject(new Error(`No JSON output from Python client: ${stdout}`));\n return;\n }\n\n // Collect all lines from start to end of JSON\n const jsonOutput = lines.slice(jsonStartIndex, jsonEndIndex + 1).join(\"\\n\");\n\n const result = JSON.parse(jsonOutput);\n\n // Transform Python response to match TypeScript interface\n let handshake: JsonRpcResponse;\n let response: JsonRpcResponse;\n\n if (command === \"init\") {\n // For init, both are the same\n handshake = result;\n response = result;\n } else {\n // For other commands, create a basic handshake response\n handshake = {\n jsonrpc: \"2.0\",\n result: {\n protocolVersion: \"2024-11-05\",\n capabilities: {},\n serverInfo: {\n name: \"mcp-gateway\",\n version: \"1.0.0\"\n }\n }\n };\n response = result;\n }\n\n promiseResolve({handshake, response});\n } catch (error) {\n promiseReject(new Error(`Failed to parse Python client output: ${(error as Error).message}\\nOutput: ${stdout}`));\n }\n });\n });\n}\n" }, { "path": "cli/src/runtime/script.ts", "content": "import {spawn} from \"node:child_process\";\n\nimport {REPO_ROOT} from \"../paths.js\";\nimport {taskCatalog} from \"../tasks/index.js\";\nimport type {ScriptCommand, ScriptTask, TaskCategory, TaskContext} from \"../tasks/types.js\";\n\nexport interface ScriptRunResult {\n stdout: string;\n stderr: string;\n exitCode: number | null;\n command: ScriptCommand;\n task: ScriptTask;\n}\n\nexport function resolveTask(category: TaskCategory, key: string): ScriptTask | undefined {\n return taskCatalog[category].find((task) => task.key === key);\n}\n\nexport async function runScriptTaskToString(\n category: TaskCategory,\n task: ScriptTask,\n values: Record,\n context: TaskContext\n): Promise {\n const command = task.build(values, context);\n const env = command.env ? {...process.env, ...command.env} : process.env;\n return new Promise((resolve) => {\n const child = spawn(command.command, command.args, {\n cwd: REPO_ROOT,\n env,\n stdio: [\"ignore\", \"pipe\", \"pipe\"]\n });\n\n let stdout = \"\";\n let stderr = \"\";\n\n child.stdout?.on(\"data\", (chunk) => {\n stdout += chunk.toString();\n });\n child.stderr?.on(\"data\", (chunk) => {\n stderr += chunk.toString();\n });\n\n child.on(\"close\", (code) => {\n resolve({stdout, stderr, exitCode: code, command, task});\n });\n child.on(\"error\", (error) => {\n resolve({\n stdout,\n stderr: `${stderr}\\nFailed to start process: ${(error as Error).message}`,\n exitCode: -1,\n command,\n task\n });\n });\n });\n}\n" }, { "path": "cli/src/tasks/index.ts", "content": "import path from \"node:path\";\n\nimport {\n DEFAULT_IMPORT_LIST,\n IMPORT_ANTHROPIC_SCRIPT,\n REGISTRY_CLI_WRAPPER,\n SERVICE_MANAGEMENT_SCRIPT,\n TEST_ANTHROPIC_SCRIPT,\n USER_MANAGEMENT_SCRIPT\n} from \"../paths.js\";\nimport type {ScriptCommand, ScriptTask, TaskCategory, TaskContext} from \"./types.js\";\n\nconst trim = (value: string | undefined): string => value?.trim() ?? \"\";\n\nconst buildBashCommand = (scriptPath: string, args: string[], env?: Record): ScriptCommand => ({\n command: \"bash\",\n args: [scriptPath, ...args],\n env\n});\n\nconst buildUvPythonCommand = (scriptPath: string, args: string[], env?: Record): ScriptCommand => ({\n command: \"uv\",\n args: [\"run\", \"python\", scriptPath, ...args],\n env\n});\n\n// Build command for Registry Management API wrapper\nconst buildRegistryCommand = (args: string[], context: TaskContext): ScriptCommand => {\n const baseArgs = [\n \"run\",\n \"python\",\n REGISTRY_CLI_WRAPPER,\n \"--base-url\",\n context.gatewayBaseUrl\n ];\n\n // Add token from context if available (backend token takes precedence)\n if (context.backendToken) {\n // Token is already a string, pass it as environment variable\n // since the wrapper can read from GATEWAY_TOKEN env var\n return {\n command: \"uv\",\n args: [...baseArgs, ...args],\n env: {\n ...process.env,\n GATEWAY_TOKEN: context.backendToken\n }\n };\n }\n\n return {\n command: \"uv\",\n args: [...baseArgs, ...args],\n env: process.env as Record\n };\n};\n\nconst computeGatewayEnv = (context: TaskContext): Record => ({\n ...process.env,\n GATEWAY_URL: context.gatewayBaseUrl\n});\n\nconst serviceTasks: ScriptTask[] = [\n {\n key: \"service-add\",\n label: \"Add service from config\",\n description: \"Validate the config and register the service via MCP gateway tools.\",\n fields: [\n {\n name: \"configPath\",\n label: \"Config file path\",\n placeholder: \"cli/examples/server-config.json\"\n }\n ],\n build(values, context) {\n const configPath = trim(values.configPath);\n if (!configPath) {\n throw new Error(\"Config file path is required.\");\n }\n return buildRegistryCommand(\n [\"service\", \"add\", configPath],\n context\n );\n }\n },\n {\n key: \"service-delete\",\n label: \"Delete service\",\n description: \"Remove a service by path and name and clean up group assignments.\",\n fields: [\n {\n name: \"servicePath\",\n label: \"Service path (e.g. /example-server)\",\n placeholder: \"/example-server\"\n },\n {\n name: \"serviceName\",\n label: \"Service name\",\n placeholder: \"example-server\"\n }\n ],\n build(values, context) {\n const servicePath = trim(values.servicePath);\n const serviceName = trim(values.serviceName);\n if (!servicePath || !serviceName) {\n throw new Error(\"Service path and name are required.\");\n }\n return buildRegistryCommand(\n [\"service\", \"delete\", servicePath],\n context\n );\n }\n },\n {\n key: \"service-monitor\",\n label: \"Monitor services\",\n description: \"Run health checks for all services or a specific config.\",\n fields: [\n {\n name: \"configPath\",\n label: \"Optional config file path\",\n placeholder: \"(leave blank for all services)\",\n optional: true\n }\n ],\n build(values, context) {\n // Monitor is essentially list with detailed output\n return buildRegistryCommand(\n [\"service\", \"list\"],\n context\n );\n }\n },\n {\n key: \"service-create-group\",\n label: \"Create group\",\n description: \"Create a Keycloak group for MCP servers.\",\n fields: [\n {\n name: \"groupName\",\n label: \"Group name\",\n placeholder: \"mcp-servers-team-x\"\n },\n {\n name: \"description\",\n label: \"Description\",\n placeholder: \"Team X access\",\n optional: true\n }\n ],\n build(values, context) {\n const groupName = trim(values.groupName);\n if (!groupName) {\n throw new Error(\"Group name is required.\");\n }\n const description = trim(values.description);\n const args = description\n ? [\"group\", \"create\", \"--name\", groupName, \"--description\", description]\n : [\"group\", \"create\", \"--name\", groupName];\n return buildRegistryCommand(args, context);\n }\n },\n {\n key: \"service-delete-group\",\n label: \"Delete group\",\n description: \"Delete a Keycloak group.\",\n fields: [\n {\n name: \"groupName\",\n label: \"Group name\",\n placeholder: \"mcp-servers-team-x\"\n }\n ],\n build(values, context) {\n const groupName = trim(values.groupName);\n if (!groupName) {\n throw new Error(\"Group name is required.\");\n }\n return buildRegistryCommand(\n [\"group\", \"delete\", \"--name\", groupName],\n context\n );\n }\n },\n {\n key: \"service-list-groups\",\n label: \"List groups\",\n description: \"List Keycloak groups.\",\n fields: [],\n build(_values, context) {\n return buildRegistryCommand(\n [\"group\", \"list\"],\n context\n );\n }\n }\n];\n\nconst importTasks: ScriptTask[] = [\n {\n key: \"import-anthropic-dry\",\n label: \"Anthropic import (dry run)\",\n description: \"Preview the servers that would be imported from the Anthropic registry.\",\n fields: [\n {\n name: \"importList\",\n label: \"Import list file\",\n placeholder: DEFAULT_IMPORT_LIST,\n optional: true,\n defaultValue: DEFAULT_IMPORT_LIST\n }\n ],\n build(values, context) {\n const importList = trim(values.importList);\n const args = [\"--dry-run\"];\n if (importList) {\n args.push(\"--import-list\", importList);\n }\n return buildBashCommand(\n IMPORT_ANTHROPIC_SCRIPT,\n args,\n computeGatewayEnv(context)\n );\n }\n },\n {\n key: \"import-anthropic-apply\",\n label: \"Anthropic import (apply)\",\n description: \"Fetch and register servers from the Anthropic MCP registry.\",\n fields: [\n {\n name: \"importList\",\n label: \"Import list file\",\n placeholder: DEFAULT_IMPORT_LIST,\n optional: true,\n defaultValue: DEFAULT_IMPORT_LIST\n }\n ],\n build(values, context) {\n const importList = trim(values.importList);\n const args: string[] = [];\n if (importList) {\n args.push(\"--import-list\", importList);\n }\n return buildBashCommand(\n IMPORT_ANTHROPIC_SCRIPT,\n args,\n computeGatewayEnv(context)\n );\n }\n }\n];\n\nconst userTasks: ScriptTask[] = [\n {\n key: \"user-create-m2m\",\n label: \"Create M2M service account\",\n description: \"Creates a service account client with group assignments (requires Keycloak admin access).\",\n fields: [\n {\n name: \"name\",\n label: \"Service account name\",\n placeholder: \"agent-finance-bot\"\n },\n {\n name: \"groups\",\n label: \"Groups (comma separated)\",\n placeholder: \"mcp-servers-finance/read,mcp-servers-finance/execute\"\n },\n {\n name: \"description\",\n label: \"Description\",\n placeholder: \"Finance bot account\",\n optional: true\n }\n ],\n build(values, context) {\n const name = trim(values.name);\n const groups = trim(values.groups);\n const description = trim(values.description);\n if (!name || !groups) {\n throw new Error(\"Name and groups are required.\");\n }\n const args = [\n \"user\",\n \"create-m2m\",\n \"--name\",\n name,\n \"--groups\",\n groups\n ];\n if (description) {\n args.push(\"--description\", description);\n }\n return buildRegistryCommand(args, context);\n }\n },\n {\n key: \"user-create-human\",\n label: \"Create human user\",\n description: \"Create a human user in Keycloak with group assignments.\",\n fields: [\n {name: \"username\", label: \"Username\", placeholder: \"jdoe\"},\n {name: \"email\", label: \"Email\", placeholder: \"jdoe@example.com\"},\n {name: \"firstName\", label: \"First name\", placeholder: \"John\"},\n {name: \"lastName\", label: \"Last name\", placeholder: \"Doe\"},\n {\n name: \"groups\",\n label: \"Groups (comma separated)\",\n placeholder: \"mcp-servers-restricted/read\"\n },\n {\n name: \"password\",\n label: \"Initial password (optional)\",\n placeholder: \"(leave blank to be prompted later)\",\n optional: true\n }\n ],\n build(values, context) {\n const username = trim(values.username);\n const email = trim(values.email);\n const firstName = trim(values.firstName);\n const lastName = trim(values.lastName);\n const groups = trim(values.groups);\n const password = trim(values.password);\n if (!username || !email || !firstName || !lastName || !groups) {\n throw new Error(\"Username, email, first name, last name, and groups are required.\");\n }\n const args = [\n \"user\",\n \"create-human\",\n \"--username\",\n username,\n \"--email\",\n email,\n \"--first-name\",\n firstName,\n \"--last-name\",\n lastName,\n \"--groups\",\n groups\n ];\n if (password) {\n args.push(\"--password\", password);\n }\n return buildRegistryCommand(args, context);\n }\n },\n {\n key: \"user-delete\",\n label: \"Delete user\",\n description: \"Delete a user (service account or human) from Keycloak.\",\n fields: [\n {\n name: \"username\",\n label: \"Username\",\n placeholder: \"agent-finance-bot\"\n }\n ],\n build(values, context) {\n const username = trim(values.username);\n if (!username) {\n throw new Error(\"Username is required.\");\n }\n return buildRegistryCommand([\"user\", \"delete\", \"--username\", username], context);\n }\n },\n {\n key: \"user-list-users\",\n label: \"List users\",\n description: \"List all users in the Keycloak realm.\",\n fields: [],\n build(_values, context) {\n return buildRegistryCommand([\"user\", \"list\"], context);\n }\n },\n {\n key: \"user-list-groups\",\n label: \"List groups\",\n description: \"List all groups in Keycloak.\",\n fields: [],\n build(_values, context) {\n return buildRegistryCommand([\"group\", \"list\"], context);\n }\n }\n];\n\nconst diagnosticTasks: ScriptTask[] = [\n {\n key: \"diagnostic-run-suite\",\n label: \"Run Anthropic API suite\",\n description: \"Run the full Anthropic MCP Registry API smoke test.\",\n fields: [\n {\n name: \"tokenFile\",\n label: \"Token file path\",\n placeholder: \".oauth-tokens/ingress.json\"\n },\n {\n name: \"baseUrl\",\n label: \"Base URL\",\n placeholder: \"http://localhost\",\n optional: true,\n defaultValue: \"http://localhost\"\n }\n ],\n build(values, context) {\n const tokenFile = trim(values.tokenFile);\n const baseUrl = trim(values.baseUrl);\n if (!tokenFile) {\n throw new Error(\"Token file path is required.\");\n }\n const args = [\"anthropic\", \"list\", \"--limit\", \"100\"];\n if (baseUrl) {\n args.push(\"--base-url\", baseUrl);\n }\n return buildRegistryCommand(args, context);\n }\n },\n {\n key: \"diagnostic-run-test\",\n label: \"Run specific Anthropic API test\",\n description: \"Call a specific API test case (e.g., list-servers, get-server).\",\n fields: [\n {\n name: \"tokenFile\",\n label: \"Token file path\",\n placeholder: \".oauth-tokens/ingress.json\"\n },\n {\n name: \"testName\",\n label: \"Test name\",\n placeholder: \"list-servers\"\n },\n {\n name: \"serverName\",\n label: \"Server name (for get-server)\",\n placeholder: \"io.mcpgateway/currenttime\",\n optional: true\n },\n {\n name: \"baseUrl\",\n label: \"Base URL\",\n placeholder: \"http://localhost\",\n optional: true,\n defaultValue: \"http://localhost\"\n }\n ],\n build(values, context) {\n const tokenFile = trim(values.tokenFile);\n const testName = trim(values.testName);\n const serverName = trim(values.serverName);\n const baseUrl = trim(values.baseUrl);\n if (!tokenFile || !testName) {\n throw new Error(\"Token file and test name are required.\");\n }\n\n // Map test name to Anthropic API command\n if (testName === \"get-server\" && serverName) {\n const args = [\"anthropic\", \"get\", serverName];\n if (baseUrl) {\n args.push(\"--base-url\", baseUrl);\n }\n return buildRegistryCommand(args, context);\n } else {\n const args = [\"anthropic\", \"list\", \"--limit\", \"100\"];\n if (baseUrl) {\n args.push(\"--base-url\", baseUrl);\n }\n return buildRegistryCommand(args, context);\n }\n }\n }\n];\n\nexport const taskCatalog: Record = {\n service: serviceTasks,\n import: importTasks,\n user: userTasks,\n diagnostic: diagnosticTasks\n};\n\nexport const getTaskByKey = (category: TaskCategory, key: string): ScriptTask | undefined =>\n taskCatalog[category].find((task) => task.key === key);\n\nexport const resolveDefaultValues = (task: ScriptTask): Record =>\n task.fields.reduce>((acc, field) => {\n if (typeof field.defaultValue === \"string\") {\n acc[field.name] = field.defaultValue;\n }\n return acc;\n }, {});\n" }, { "path": "cli/src/tasks/types.ts", "content": "export interface TaskField {\n name: string;\n label: string;\n placeholder?: string;\n optional?: boolean;\n defaultValue?: string;\n}\n\nexport interface ScriptCommand {\n command: string;\n args: string[];\n env?: Record;\n}\n\nexport interface TaskContext {\n gatewayUrl: string;\n gatewayBaseUrl: string;\n gatewayToken?: string;\n backendToken?: string;\n}\n\nexport interface ScriptTask {\n key: string;\n label: string;\n description?: string;\n fields: TaskField[];\n build(values: Record, context: TaskContext): ScriptCommand;\n}\n\nexport type TaskCategory = \"service\" | \"import\" | \"user\" | \"diagnostic\";\n" }, { "path": "cli/src/types/mcp.ts", "content": "/**\n * MCP Protocol Type Definitions\n *\n * These types define the JSON-RPC 2.0 interface used by the Model Context Protocol (MCP).\n * They are shared between the Python client bridge and the rest of the TypeScript CLI.\n */\n\nexport interface JsonRpcRequest {\n jsonrpc: \"2.0\";\n id?: number;\n method: string;\n params?: Record;\n}\n\nexport interface JsonRpcResponse {\n jsonrpc: \"2.0\";\n result?: T;\n error?: unknown;\n id?: number | string;\n}\n\nexport type ToolArguments = Record;\n" }, { "path": "cli/src/utils/commands.ts", "content": "/**\n * Available slash commands for autocomplete\n */\n\nexport interface CommandOption {\n command: string;\n description: string;\n category: string;\n}\n\nexport const AVAILABLE_COMMANDS: CommandOption[] = [\n // Essential commands only - focus on natural language interaction\n { command: \"/help\", description: \"Show help message\", category: \"Basic\" },\n { command: \"/exit\", description: \"Exit the CLI\", category: \"Basic\" },\n { command: \"/ping\", description: \"Test gateway connectivity\", category: \"Basic\" },\n { command: \"/list\", description: \"List available tools\", category: \"Basic\" },\n { command: \"/servers\", description: \"List all MCP servers\", category: \"Basic\" },\n];\n\n/**\n * Get command suggestions based on partial input\n */\nexport function getCommandSuggestions(input: string): CommandOption[] {\n if (!input.startsWith(\"/\")) {\n return [];\n }\n\n const normalized = input.toLowerCase();\n\n return AVAILABLE_COMMANDS.filter(cmd =>\n cmd.command.toLowerCase().startsWith(normalized)\n ).slice(0, 10); // Limit to 10 suggestions\n}\n\n/**\n * Get all commands for a specific category\n */\nexport function getCommandsByCategory(category: string): CommandOption[] {\n return AVAILABLE_COMMANDS.filter(cmd => cmd.category === category);\n}\n" }, { "path": "cli/src/utils/cost.json", "content": "{\n \"sample_spec\": {\n \"code_interpreter_cost_per_session\": 0.0,\n \"computer_use_input_cost_per_1k_tokens\": 0.0,\n \"computer_use_output_cost_per_1k_tokens\": 0.0,\n \"deprecation_date\": \"date when the model becomes deprecated in the format YYYY-MM-DD\",\n \"file_search_cost_per_1k_calls\": 0.0,\n \"file_search_cost_per_gb_per_day\": 0.0,\n \"input_cost_per_audio_token\": 0.0,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"one of https://docs.litellm.ai/docs/providers\",\n \"max_input_tokens\": \"max input tokens, if the provider specifies it. if not default to max_tokens\",\n \"max_output_tokens\": \"max output tokens, if the provider specifies it. if not default to max_tokens\",\n \"max_tokens\": \"LEGACY parameter. set to max_output_tokens if provider specifies it. IF not set to max_input_tokens, if provider specifies it.\",\n \"mode\": \"one of: chat, embedding, completion, image_generation, audio_transcription, audio_speech, image_generation, moderation, rerank, search\",\n \"output_cost_per_reasoning_token\": 0.0,\n \"output_cost_per_token\": 0.0,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.0,\n \"search_context_size_low\": 0.0,\n \"search_context_size_medium\": 0.0\n },\n \"supported_regions\": [\n \"global\",\n \"us-west-2\",\n \"eu-west-1\",\n \"ap-southeast-1\",\n \"ap-northeast-1\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"vector_store_cost_per_gb_per_day\": 0.0\n },\n \"1024-x-1024/50-steps/bedrock/amazon.nova-canvas-v1:0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 2600,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.06\n },\n \"1024-x-1024/50-steps/stability.stable-diffusion-xl-v1\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04\n },\n \"1024-x-1024/dall-e-2\": {\n \"input_cost_per_pixel\": 1.9e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"1024-x-1024/max-steps/stability.stable-diffusion-xl-v1\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.08\n },\n \"256-x-256/dall-e-2\": {\n \"input_cost_per_pixel\": 2.4414e-07,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"512-x-512/50-steps/stability.stable-diffusion-xl-v0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.018\n },\n \"512-x-512/dall-e-2\": {\n \"input_cost_per_pixel\": 6.86e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"512-x-512/max-steps/stability.stable-diffusion-xl-v0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.036\n },\n \"ai21.j2-mid-v1\": {\n \"input_cost_per_token\": 1.25e-05,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8191,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-05\n },\n \"ai21.j2-ultra-v1\": {\n \"input_cost_per_token\": 1.88e-05,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8191,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.88e-05\n },\n \"ai21.jamba-1-5-large-v1:0\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06\n },\n \"ai21.jamba-1-5-mini-v1:0\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07\n },\n \"ai21.jamba-instruct-v1:0\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 70000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"supports_system_messages\": true\n },\n \"aiml/dall-e-2\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"DALL-E 2 via AI/ML API - Reliable text-to-image generation\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.021,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/dall-e-3\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"DALL-E 3 via AI/ML API - High-quality text-to-image generation\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.042,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux-pro\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"Flux Dev - Development version optimized for experimentation\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.053,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux-pro/v1.1\": {\n \"litellm_provider\": \"aiml\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.042,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux-pro/v1.1-ultra\": {\n \"litellm_provider\": \"aiml\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.063,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux-realism\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"Flux Pro - Professional-grade image generation model\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.037,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux/dev\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"Flux Dev - Development version optimized for experimentation\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.026,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux/kontext-max/text-to-image\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"Flux Pro v1.1 - Enhanced version with improved capabilities and 6x faster inference speed\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.084,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux/kontext-pro/text-to-image\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"Flux Pro v1.1 - Enhanced version with improved capabilities and 6x faster inference speed\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.042,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"aiml/flux/schnell\": {\n \"litellm_provider\": \"aiml\",\n \"metadata\": {\n \"notes\": \"Flux Schnell - Fast generation model optimized for speed\"\n },\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.003,\n \"source\": \"https://docs.aimlapi.com/\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"amazon.nova-lite-v1:0\": {\n \"input_cost_per_token\": 6e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-07,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"amazon.nova-micro-v1:0\": {\n \"input_cost_per_token\": 3.5e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.4e-07,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true\n },\n \"amazon.nova-pro-v1:0\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.2e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"amazon.rerank-v1:0\": {\n \"input_cost_per_query\": 0.001,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"bedrock\",\n \"max_document_chunks_per_query\": 100,\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_query_tokens\": 32000,\n \"max_tokens\": 32000,\n \"max_tokens_per_document_chunk\": 512,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"amazon.titan-embed-image-v1\": {\n \"input_cost_per_image\": 6e-05,\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128,\n \"max_tokens\": 128,\n \"metadata\": {\n \"notes\": \"'supports_image_input' is a deprecated field. Use 'supports_embedding_image_input' instead.\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"source\": \"https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/providers?model=amazon.titan-image-generator-v1\",\n \"supports_embedding_image_input\": true,\n \"supports_image_input\": true\n },\n \"amazon.titan-embed-text-v1\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1536\n },\n \"amazon.titan-embed-text-v2:0\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024\n },\n \"amazon.titan-image-generator-v1\": {\n \"input_cost_per_image\": 0.0,\n \"output_cost_per_image\": 0.008,\n \"output_cost_per_image_premium_image\": 0.01,\n \"output_cost_per_image_above_512_and_512_pixels\": 0.01,\n \"output_cost_per_image_above_512_and_512_pixels_and_premium_image\": 0.012,\n \"litellm_provider\": \"bedrock\",\n \"mode\": \"image_generation\"\n },\n \"amazon.titan-image-generator-v2\": {\n \"input_cost_per_image\": 0.0,\n \"output_cost_per_image\": 0.008,\n \"output_cost_per_image_premium_image\": 0.01,\n \"output_cost_per_image_above_1024_and_1024_pixels\": 0.01,\n \"output_cost_per_image_above_1024_and_1024_pixels_and_premium_image\": 0.012,\n \"litellm_provider\": \"bedrock\",\n \"mode\": \"image_generation\"\n },\n \"twelvelabs.marengo-embed-2-7-v1:0\": {\n \"input_cost_per_token\": 7e-05,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"supports_embedding_image_input\": true,\n \"supports_image_input\": true\n },\n \"us.twelvelabs.marengo-embed-2-7-v1:0\": {\n \"input_cost_per_token\": 7e-05,\n \"input_cost_per_video_per_second\": 0.0007,\n \"input_cost_per_audio_per_second\": 0.00014,\n \"input_cost_per_image\": 0.0001,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"supports_embedding_image_input\": true,\n \"supports_image_input\": true\n },\n \"eu.twelvelabs.marengo-embed-2-7-v1:0\": {\n \"input_cost_per_token\": 7e-05,\n \"input_cost_per_video_per_second\": 0.0007,\n \"input_cost_per_audio_per_second\": 0.00014,\n \"input_cost_per_image\": 0.0001,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"supports_embedding_image_input\": true,\n \"supports_image_input\": true\n },\n \"twelvelabs.pegasus-1-2-v1:0\": {\n \"input_cost_per_video_per_second\": 0.00049,\n \"output_cost_per_token\": 7.5e-06,\n \"litellm_provider\": \"bedrock\",\n \"mode\": \"chat\",\n \"supports_video_input\": true\n },\n \"us.twelvelabs.pegasus-1-2-v1:0\": {\n \"input_cost_per_video_per_second\": 0.00049,\n \"output_cost_per_token\": 7.5e-06,\n \"litellm_provider\": \"bedrock\",\n \"mode\": \"chat\",\n \"supports_video_input\": true\n },\n \"eu.twelvelabs.pegasus-1-2-v1:0\": {\n \"input_cost_per_video_per_second\": 0.00049,\n \"output_cost_per_token\": 7.5e-06,\n \"litellm_provider\": \"bedrock\",\n \"mode\": \"chat\",\n \"supports_video_input\": true\n },\n \"amazon.titan-text-express-v1\": {\n \"input_cost_per_token\": 1.3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 8000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.7e-06\n },\n \"amazon.titan-text-lite-v1\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 4000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07\n },\n \"amazon.titan-text-premier-v1:0\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06\n },\n \"anthropic.claude-3-5-haiku-20241022-v1:0\": {\n \"cache_creation_input_token_cost\": 1e-06,\n \"cache_read_input_token_cost\": 8e-08,\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"anthropic.claude-haiku-4-5-20251001-v1:0\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://aws.amazon.com/about-aws/whats-new/2025/10/claude-4-5-haiku-anthropic-amazon-bedrock\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"anthropic.claude-haiku-4-5@20251001\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://aws.amazon.com/about-aws/whats-new/2025/10/claude-4-5-haiku-anthropic-amazon-bedrock\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"anthropic.claude-3-5-sonnet-20240620-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"anthropic.claude-3-5-sonnet-20241022-v2:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"anthropic.claude-3-7-sonnet-20240620-v1:0\": {\n \"cache_creation_input_token_cost\": 4.5e-06,\n \"cache_read_input_token_cost\": 3.6e-07,\n \"input_cost_per_token\": 3.6e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"anthropic.claude-3-7-sonnet-20250219-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"anthropic.claude-3-haiku-20240307-v1:0\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"anthropic.claude-3-opus-20240229-v1:0\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"anthropic.claude-3-sonnet-20240229-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"anthropic.claude-instant-v1\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-06,\n \"supports_tool_choice\": true\n },\n \"anthropic.claude-opus-4-1-20250805-v1:0\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"anthropic.claude-opus-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"anthropic.claude-sonnet-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"anthropic.claude-v1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05\n },\n \"anthropic.claude-v2:1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"anyscale/HuggingFaceH4/zephyr-7b-beta\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07\n },\n \"anyscale/codellama/CodeLlama-34b-Instruct-hf\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"anyscale/codellama/CodeLlama-70b-Instruct-hf\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06,\n \"source\": \"https://docs.anyscale.com/preview/endpoints/text-generation/supported-models/codellama-CodeLlama-70b-Instruct-hf\"\n },\n \"anyscale/google/gemma-7b-it\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://docs.anyscale.com/preview/endpoints/text-generation/supported-models/google-gemma-7b-it\"\n },\n \"anyscale/meta-llama/Llama-2-13b-chat-hf\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07\n },\n \"anyscale/meta-llama/Llama-2-70b-chat-hf\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"anyscale/meta-llama/Llama-2-7b-chat-hf\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07\n },\n \"anyscale/meta-llama/Meta-Llama-3-70B-Instruct\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06,\n \"source\": \"https://docs.anyscale.com/preview/endpoints/text-generation/supported-models/meta-llama-Meta-Llama-3-70B-Instruct\"\n },\n \"anyscale/meta-llama/Meta-Llama-3-8B-Instruct\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://docs.anyscale.com/preview/endpoints/text-generation/supported-models/meta-llama-Meta-Llama-3-8B-Instruct\"\n },\n \"anyscale/mistralai/Mistral-7B-Instruct-v0.1\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://docs.anyscale.com/preview/endpoints/text-generation/supported-models/mistralai-Mistral-7B-Instruct-v0.1\",\n \"supports_function_calling\": true\n },\n \"anyscale/mistralai/Mixtral-8x22B-Instruct-v0.1\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"source\": \"https://docs.anyscale.com/preview/endpoints/text-generation/supported-models/mistralai-Mixtral-8x22B-Instruct-v0.1\",\n \"supports_function_calling\": true\n },\n \"anyscale/mistralai/Mixtral-8x7B-Instruct-v0.1\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"anyscale\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://docs.anyscale.com/preview/endpoints/text-generation/supported-models/mistralai-Mixtral-8x7B-Instruct-v0.1\",\n \"supports_function_calling\": true\n },\n \"apac.amazon.nova-lite-v1:0\": {\n \"input_cost_per_token\": 6.3e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.52e-07,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"apac.amazon.nova-micro-v1:0\": {\n \"input_cost_per_token\": 3.7e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.48e-07,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true\n },\n \"apac.amazon.nova-pro-v1:0\": {\n \"input_cost_per_token\": 8.4e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.36e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"apac.anthropic.claude-3-5-sonnet-20240620-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"apac.anthropic.claude-3-5-sonnet-20241022-v2:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"apac.anthropic.claude-3-haiku-20240307-v1:0\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"apac.anthropic.claude-haiku-4-5-20251001-v1:0\": {\n \"cache_creation_input_token_cost\": 1.375e-06,\n \"cache_read_input_token_cost\": 1.1e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.5e-06,\n \"source\": \"https://aws.amazon.com/about-aws/whats-new/2025/10/claude-4-5-haiku-anthropic-amazon-bedrock\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"apac.anthropic.claude-3-sonnet-20240229-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"apac.anthropic.claude-sonnet-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"assemblyai/best\": {\n \"input_cost_per_second\": 3.333e-05,\n \"litellm_provider\": \"assemblyai\",\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0\n },\n \"assemblyai/nano\": {\n \"input_cost_per_second\": 0.00010278,\n \"litellm_provider\": \"assemblyai\",\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0\n },\n \"au.anthropic.claude-sonnet-4-5-20250929-v1:0\": {\n \"cache_creation_input_token_cost\": 4.125e-06,\n \"cache_read_input_token_cost\": 3.3e-07,\n \"input_cost_per_token\": 3.3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6.6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.475e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 8.25e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6.6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.65e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"azure/ada\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/codex-mini\": {\n \"cache_read_input_token_cost\": 3.75e-07,\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 6e-06,\n \"supported_endpoints\": [\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/command-r-plus\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true\n },\n \"azure/computer-use-preview\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-05,\n \"supported_endpoints\": [\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": false,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/eu/gpt-4o-2024-08-06\": {\n \"deprecation_date\": \"2026-02-27\",\n \"cache_read_input_token_cost\": 1.375e-06,\n \"input_cost_per_token\": 2.75e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/eu/gpt-4o-2024-11-20\": {\n \"deprecation_date\": \"2026-03-01\",\n \"cache_creation_input_token_cost\": 1.38e-06,\n \"input_cost_per_token\": 2.75e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/eu/gpt-4o-mini-2024-07-18\": {\n \"cache_read_input_token_cost\": 8.3e-08,\n \"input_cost_per_token\": 1.65e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/eu/gpt-4o-mini-realtime-preview-2024-12-17\": {\n \"cache_creation_input_audio_token_cost\": 3.3e-07,\n \"cache_read_input_token_cost\": 3.3e-07,\n \"input_cost_per_audio_token\": 1.1e-05,\n \"input_cost_per_token\": 6.6e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2.2e-05,\n \"output_cost_per_token\": 2.64e-06,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/eu/gpt-4o-realtime-preview-2024-10-01\": {\n \"cache_creation_input_audio_token_cost\": 2.2e-05,\n \"cache_read_input_token_cost\": 2.75e-06,\n \"input_cost_per_audio_token\": 0.00011,\n \"input_cost_per_token\": 5.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 0.00022,\n \"output_cost_per_token\": 2.2e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/eu/gpt-4o-realtime-preview-2024-12-17\": {\n \"cache_read_input_audio_token_cost\": 2.5e-06,\n \"cache_read_input_token_cost\": 2.75e-06,\n \"input_cost_per_audio_token\": 4.4e-05,\n \"input_cost_per_token\": 5.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 2.2e-05,\n \"supported_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/eu/o1-2024-12-17\": {\n \"cache_read_input_token_cost\": 8.25e-06,\n \"input_cost_per_token\": 1.65e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/eu/o1-mini-2024-09-12\": {\n \"cache_read_input_token_cost\": 6.05e-07,\n \"input_cost_per_token\": 1.21e-06,\n \"input_cost_per_token_batches\": 6.05e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.84e-06,\n \"output_cost_per_token_batches\": 2.42e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_vision\": false\n },\n \"azure/eu/o1-preview-2024-09-12\": {\n \"cache_read_input_token_cost\": 8.25e-06,\n \"input_cost_per_token\": 1.65e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_vision\": false\n },\n \"azure/eu/o3-mini-2025-01-31\": {\n \"cache_read_input_token_cost\": 6.05e-07,\n \"input_cost_per_token\": 1.21e-06,\n \"input_cost_per_token_batches\": 6.05e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.84e-06,\n \"output_cost_per_token_batches\": 2.42e-06,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure/global-standard/gpt-4o-2024-08-06\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"deprecation_date\": \"2026-02-27\",\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/global-standard/gpt-4o-2024-11-20\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"deprecation_date\": \"2026-03-01\",\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/global-standard/gpt-4o-mini\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/global/gpt-4o-2024-08-06\": {\n \"deprecation_date\": \"2026-02-27\",\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/global/gpt-4o-2024-11-20\": {\n \"deprecation_date\": \"2026-03-01\",\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-3.5-turbo\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 4097,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-3.5-turbo-0125\": {\n \"deprecation_date\": \"2025-03-31\",\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-3.5-turbo-instruct-0914\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"azure_text\",\n \"max_input_tokens\": 4097,\n \"max_tokens\": 4097,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"azure/gpt-35-turbo\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 4097,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-35-turbo-0125\": {\n \"deprecation_date\": \"2025-05-31\",\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-35-turbo-0301\": {\n \"deprecation_date\": \"2025-02-13\",\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 4097,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4097,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-35-turbo-0613\": {\n \"deprecation_date\": \"2025-02-13\",\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 4097,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4097,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-35-turbo-1106\": {\n \"deprecation_date\": \"2025-03-31\",\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-35-turbo-16k\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-35-turbo-16k-0613\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-35-turbo-instruct\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"azure_text\",\n \"max_input_tokens\": 4097,\n \"max_tokens\": 4097,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"azure/gpt-35-turbo-instruct-0914\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"azure_text\",\n \"max_input_tokens\": 4097,\n \"max_tokens\": 4097,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"azure/gpt-4\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4-0125-preview\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4-0613\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4-1106-preview\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4-32k\": {\n \"input_cost_per_token\": 6e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00012,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4-32k-0613\": {\n \"input_cost_per_token\": 6e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00012,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4-turbo\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4-turbo-2024-04-09\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4-turbo-vision-preview\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4.1\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_batches\": 1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"output_cost_per_token_batches\": 4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": false\n },\n \"azure/gpt-4.1-2025-04-14\": {\n \"deprecation_date\": \"2026-11-04\",\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_batches\": 1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"output_cost_per_token_batches\": 4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": false\n },\n \"azure/gpt-4.1-mini\": {\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 4e-07,\n \"input_cost_per_token_batches\": 2e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06,\n \"output_cost_per_token_batches\": 8e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": false\n },\n \"azure/gpt-4.1-mini-2025-04-14\": {\n \"deprecation_date\": \"2026-11-04\",\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 4e-07,\n \"input_cost_per_token_batches\": 2e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06,\n \"output_cost_per_token_batches\": 8e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": false\n },\n \"azure/gpt-4.1-nano\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"input_cost_per_token_batches\": 5e-08,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"output_cost_per_token_batches\": 2e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4.1-nano-2025-04-14\": {\n \"deprecation_date\": \"2026-11-04\",\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"input_cost_per_token_batches\": 5e-08,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"output_cost_per_token_batches\": 2e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4.5-preview\": {\n \"cache_read_input_token_cost\": 3.75e-05,\n \"input_cost_per_token\": 7.5e-05,\n \"input_cost_per_token_batches\": 3.75e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00015,\n \"output_cost_per_token_batches\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4o\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4o-2024-05-13\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4o-2024-08-06\": {\n \"deprecation_date\": \"2026-02-27\",\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4o-2024-11-20\": {\n \"deprecation_date\": \"2026-03-01\",\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.75e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4o-audio-preview-2024-12-17\": {\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": false,\n \"supports_reasoning\": false,\n \"supports_response_schema\": false,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure/gpt-4o-mini\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_token\": 1.65e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4o-mini-2024-07-18\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_token\": 1.65e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-4o-mini-audio-preview-2024-12-17\": {\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": false,\n \"supports_reasoning\": false,\n \"supports_response_schema\": false,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure/gpt-4o-mini-realtime-preview-2024-12-17\": {\n \"cache_creation_input_audio_token_cost\": 3e-07,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_audio_token\": 1e-05,\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2e-05,\n \"output_cost_per_token\": 2.4e-06,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4o-mini-transcribe\": {\n \"input_cost_per_audio_token\": 3e-06,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 16000,\n \"max_output_tokens\": 2000,\n \"mode\": \"audio_transcription\",\n \"output_cost_per_token\": 5e-06,\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"azure/gpt-4o-mini-tts\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"mode\": \"audio_speech\",\n \"output_cost_per_audio_token\": 1.2e-05,\n \"output_cost_per_second\": 0.00025,\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/audio/speech\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"audio\"\n ]\n },\n \"azure/gpt-4o-realtime-preview-2024-10-01\": {\n \"cache_creation_input_audio_token_cost\": 2e-05,\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_audio_token\": 0.0001,\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 0.0002,\n \"output_cost_per_token\": 2e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4o-realtime-preview-2024-12-17\": {\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 2e-05,\n \"supported_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/gpt-4o-transcribe\": {\n \"input_cost_per_audio_token\": 6e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 16000,\n \"max_output_tokens\": 2000,\n \"mode\": \"audio_transcription\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"azure/gpt-5\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-5-2025-08-07\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-5-chat\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"source\": \"https://azure.microsoft.com/en-us/blog/gpt-5-in-azure-ai-foundry-the-future-of-ai-apps-and-agents-starts-here/\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"azure/gpt-5-chat-latest\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"azure/gpt-5-codex\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-5-mini\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-5-mini-2025-08-07\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-5-nano\": {\n \"cache_read_input_token_cost\": 5e-09,\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-5-nano-2025-08-07\": {\n \"cache_read_input_token_cost\": 5e-09,\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/hd/1024-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 7.629e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/hd/1024-x-1792/dall-e-3\": {\n \"input_cost_per_pixel\": 6.539e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/hd/1792-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 6.539e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/high/1024-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.59263611e-07,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/high/1024-x-1536/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.58945719e-07,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/high/1536-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.58945719e-07,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/low/1024-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.0490417e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/low/1024-x-1536/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.0172526e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/low/1536-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.0172526e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/medium/1024-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/medium/1024-x-1536/gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/medium/1536-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure/mistral-large-2402\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_function_calling\": true\n },\n \"azure/mistral-large-latest\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_function_calling\": true\n },\n \"azure/o1\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/o1-2024-12-17\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/o1-mini\": {\n \"cache_read_input_token_cost\": 6.05e-07,\n \"input_cost_per_token\": 1.21e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.84e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_vision\": false\n },\n \"azure/o1-mini-2024-09-12\": {\n \"cache_read_input_token_cost\": 5.5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_vision\": false\n },\n \"azure/o1-preview\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_vision\": false\n },\n \"azure/o1-preview-2024-09-12\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_vision\": false\n },\n \"azure/o3\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/o3-2025-04-16\": {\n \"deprecation_date\": \"2026-04-16\",\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/o3-deep-research\": {\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 4e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"azure/o3-mini\": {\n \"cache_read_input_token_cost\": 5.5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure/o3-mini-2025-01-31\": {\n \"cache_read_input_token_cost\": 5.5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure/o3-pro\": {\n \"input_cost_per_token\": 2e-05,\n \"input_cost_per_token_batches\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 8e-05,\n \"output_cost_per_token_batches\": 4e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": false,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/o3-pro-2025-06-10\": {\n \"input_cost_per_token\": 2e-05,\n \"input_cost_per_token_batches\": 1e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 8e-05,\n \"output_cost_per_token_batches\": 4e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": false,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/o4-mini\": {\n \"cache_read_input_token_cost\": 2.75e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/o4-mini-2025-04-16\": {\n \"cache_read_input_token_cost\": 2.75e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/standard/1024-x-1024/dall-e-2\": {\n \"input_cost_per_pixel\": 0.0,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/standard/1024-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 3.81469e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/standard/1024-x-1792/dall-e-3\": {\n \"input_cost_per_pixel\": 4.359e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/standard/1792-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 4.359e-08,\n \"litellm_provider\": \"azure\",\n \"mode\": \"image_generation\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/text-embedding-3-large\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/text-embedding-3-small\": {\n \"deprecation_date\": \"2026-04-30\",\n \"input_cost_per_token\": 2e-08,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/text-embedding-ada-002\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"azure/speech/azure-tts\": {\n \"input_cost_per_character\": 15e-06,\n \"litellm_provider\": \"azure\",\n \"mode\": \"audio_speech\",\n \"source\": \"https://azure.microsoft.com/en-us/pricing/calculator/\"\n },\n \"azure/speech/azure-tts-hd\": {\n \"input_cost_per_character\": 30e-06,\n \"litellm_provider\": \"azure\",\n \"mode\": \"audio_speech\",\n \"source\": \"https://azure.microsoft.com/en-us/pricing/calculator/\"\n },\n \"azure/tts-1\": {\n \"input_cost_per_character\": 1.5e-05,\n \"litellm_provider\": \"azure\",\n \"mode\": \"audio_speech\"\n },\n \"azure/tts-1-hd\": {\n \"input_cost_per_character\": 3e-05,\n \"litellm_provider\": \"azure\",\n \"mode\": \"audio_speech\"\n },\n \"azure/us/gpt-4o-2024-08-06\": {\n \"deprecation_date\": \"2026-02-27\",\n \"cache_read_input_token_cost\": 1.375e-06,\n \"input_cost_per_token\": 2.75e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/us/gpt-4o-2024-11-20\": {\n \"deprecation_date\": \"2026-03-01\",\n \"cache_creation_input_token_cost\": 1.38e-06,\n \"input_cost_per_token\": 2.75e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/us/gpt-4o-mini-2024-07-18\": {\n \"cache_read_input_token_cost\": 8.3e-08,\n \"input_cost_per_token\": 1.65e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/us/gpt-4o-mini-realtime-preview-2024-12-17\": {\n \"cache_creation_input_audio_token_cost\": 3.3e-07,\n \"cache_read_input_token_cost\": 3.3e-07,\n \"input_cost_per_audio_token\": 1.1e-05,\n \"input_cost_per_token\": 6.6e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2.2e-05,\n \"output_cost_per_token\": 2.64e-06,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/us/gpt-4o-realtime-preview-2024-10-01\": {\n \"cache_creation_input_audio_token_cost\": 2.2e-05,\n \"cache_read_input_token_cost\": 2.75e-06,\n \"input_cost_per_audio_token\": 0.00011,\n \"input_cost_per_token\": 5.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 0.00022,\n \"output_cost_per_token\": 2.2e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/us/gpt-4o-realtime-preview-2024-12-17\": {\n \"cache_read_input_audio_token_cost\": 2.5e-06,\n \"cache_read_input_token_cost\": 2.75e-06,\n \"input_cost_per_audio_token\": 4.4e-05,\n \"input_cost_per_token\": 5.5e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 2.2e-05,\n \"supported_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"azure/us/o1-2024-12-17\": {\n \"cache_read_input_token_cost\": 8.25e-06,\n \"input_cost_per_token\": 1.65e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure/us/o1-mini-2024-09-12\": {\n \"cache_read_input_token_cost\": 6.05e-07,\n \"input_cost_per_token\": 1.21e-06,\n \"input_cost_per_token_batches\": 6.05e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.84e-06,\n \"output_cost_per_token_batches\": 2.42e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_vision\": false\n },\n \"azure/us/o1-preview-2024-09-12\": {\n \"cache_read_input_token_cost\": 8.25e-06,\n \"input_cost_per_token\": 1.65e-05,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_vision\": false\n },\n \"azure/us/o3-mini-2025-01-31\": {\n \"cache_read_input_token_cost\": 6.05e-07,\n \"input_cost_per_token\": 1.21e-06,\n \"input_cost_per_token_batches\": 6.05e-07,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.84e-06,\n \"output_cost_per_token_batches\": 2.42e-06,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure/whisper-1\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"azure\",\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0001\n },\n \"azure_ai/Cohere-embed-v3-english\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"source\": \"https://azuremarketplace.microsoft.com/en-us/marketplace/apps/cohere.cohere-embed-v3-english-offer?tab=PlansAndPrice\",\n \"supports_embedding_image_input\": true\n },\n \"azure_ai/Cohere-embed-v3-multilingual\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"source\": \"https://azuremarketplace.microsoft.com/en-us/marketplace/apps/cohere.cohere-embed-v3-english-offer?tab=PlansAndPrice\",\n \"supports_embedding_image_input\": true\n },\n \"azure_ai/FLUX-1.1-pro\": {\n \"litellm_provider\": \"azure_ai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://techcommunity.microsoft.com/blog/azure-ai-foundry-blog/black-forest-labs-flux-1-kontext-pro-and-flux1-1-pro-now-available-in-azure-ai-f/4434659\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure_ai/FLUX.1-Kontext-pro\": {\n \"litellm_provider\": \"azure_ai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://azuremarketplace.microsoft.com/pt-br/marketplace/apps/cohere.cohere-embed-4-offer?tab=PlansAndPrice\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"azure_ai/Llama-3.2-11B-Vision-Instruct\": {\n \"input_cost_per_token\": 3.7e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.7e-07,\n \"source\": \"https://azuremarketplace.microsoft.com/en/marketplace/apps/metagenai.meta-llama-3-2-11b-vision-instruct-offer?tab=Overview\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure_ai/Llama-3.2-90B-Vision-Instruct\": {\n \"input_cost_per_token\": 2.04e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.04e-06,\n \"source\": \"https://azuremarketplace.microsoft.com/en/marketplace/apps/metagenai.meta-llama-3-2-90b-vision-instruct-offer?tab=Overview\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure_ai/Llama-3.3-70B-Instruct\": {\n \"input_cost_per_token\": 7.1e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.1e-07,\n \"source\": \"https://azuremarketplace.microsoft.com/en/marketplace/apps/metagenai.llama-3-3-70b-instruct-offer?tab=Overview\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/Llama-4-Maverick-17B-128E-Instruct-FP8\": {\n \"input_cost_per_token\": 1.41e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-07,\n \"source\": \"https://azure.microsoft.com/en-us/blog/introducing-the-llama-4-herd-in-azure-ai-foundry-and-azure-databricks/\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure_ai/Llama-4-Scout-17B-16E-Instruct\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 10000000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.8e-07,\n \"source\": \"https://azure.microsoft.com/en-us/blog/introducing-the-llama-4-herd-in-azure-ai-foundry-and-azure-databricks/\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure_ai/Meta-Llama-3-70B-Instruct\": {\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.7e-07,\n \"supports_tool_choice\": true\n },\n \"azure_ai/Meta-Llama-3.1-405B-Instruct\": {\n \"input_cost_per_token\": 5.33e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-05,\n \"source\": \"https://azuremarketplace.microsoft.com/en-us/marketplace/apps/metagenai.meta-llama-3-1-405b-instruct-offer?tab=PlansAndPrice\",\n \"supports_tool_choice\": true\n },\n \"azure_ai/Meta-Llama-3.1-70B-Instruct\": {\n \"input_cost_per_token\": 2.68e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.54e-06,\n \"source\": \"https://azuremarketplace.microsoft.com/en-us/marketplace/apps/metagenai.meta-llama-3-1-70b-instruct-offer?tab=PlansAndPrice\",\n \"supports_tool_choice\": true\n },\n \"azure_ai/Meta-Llama-3.1-8B-Instruct\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.1e-07,\n \"source\": \"https://azuremarketplace.microsoft.com/en-us/marketplace/apps/metagenai.meta-llama-3-1-8b-instruct-offer?tab=PlansAndPrice\",\n \"supports_tool_choice\": true\n },\n \"azure_ai/Phi-3-medium-128k-instruct\": {\n \"input_cost_per_token\": 1.7e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.8e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3-medium-4k-instruct\": {\n \"input_cost_per_token\": 1.7e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.8e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3-mini-128k-instruct\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.2e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3-mini-4k-instruct\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.2e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3-small-128k-instruct\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3-small-8k-instruct\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3.5-MoE-instruct\": {\n \"input_cost_per_token\": 1.6e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.4e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3.5-mini-instruct\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.2e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-3.5-vision-instruct\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.2e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/phi-3/\",\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"azure_ai/Phi-4\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"source\": \"https://techcommunity.microsoft.com/blog/machinelearningblog/affordable-innovation-unveiling-the-pricing-of-phi-3-slms-on-models-as-a-service/4156495\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"azure_ai/Phi-4-mini-instruct\": {\n \"input_cost_per_token\": 7.5e-08,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://techcommunity.microsoft.com/blog/Azure-AI-Services-blog/announcing-new-phi-pricing-empowering-your-business-with-small-language-models/4395112\",\n \"supports_function_calling\": true\n },\n \"azure_ai/Phi-4-multimodal-instruct\": {\n \"input_cost_per_audio_token\": 4e-06,\n \"input_cost_per_token\": 8e-08,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.2e-07,\n \"source\": \"https://techcommunity.microsoft.com/blog/Azure-AI-Services-blog/announcing-new-phi-pricing-empowering-your-business-with-small-language-models/4395112\",\n \"supports_audio_input\": true,\n \"supports_function_calling\": true,\n \"supports_vision\": true\n },\n \"azure_ai/Phi-4-mini-reasoning\": {\n \"input_cost_per_token\": 8e-08,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.2e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/ai-foundry-models/microsoft/\",\n \"supports_function_calling\": true\n },\n \"azure_ai/Phi-4-reasoning\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/ai-foundry-models/microsoft/\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_reasoning\": true\n },\n \"azure_ai/mistral-document-ai-2505\": {\n \"litellm_provider\": \"azure_ai\",\n \"ocr_cost_per_page\": 3e-3,\n \"mode\": \"ocr\",\n \"supported_endpoints\": [\n \"/v1/ocr\"\n ],\n \"source\": \"https://devblogs.microsoft.com/foundry/whats-new-in-azure-ai-foundry-august-2025/#mistral-document-ai-(ocr)-%E2%80%94-serverless-in-foundry\"\n },\n \"azure_ai/MAI-DS-R1\": {\n \"input_cost_per_token\": 1.35e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.4e-06,\n \"source\": \"https://azure.microsoft.com/en-us/pricing/details/ai-foundry-models/microsoft/\",\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/cohere-rerank-v3-english\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"azure_ai/cohere-rerank-v3-multilingual\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"azure_ai/cohere-rerank-v3.5\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"azure_ai/deepseek-r1\": {\n \"input_cost_per_token\": 1.35e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.4e-06,\n \"source\": \"https://techcommunity.microsoft.com/blog/machinelearningblog/deepseek-r1-improved-performance-higher-limits-and-transparent-pricing/4386367\",\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/deepseek-v3\": {\n \"input_cost_per_token\": 1.14e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.56e-06,\n \"source\": \"https://techcommunity.microsoft.com/blog/machinelearningblog/announcing-deepseek-v3-on-azure-ai-foundry-and-github/4390438\",\n \"supports_tool_choice\": true\n },\n \"azure_ai/deepseek-v3-0324\": {\n \"input_cost_per_token\": 1.14e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.56e-06,\n \"source\": \"https://techcommunity.microsoft.com/blog/machinelearningblog/announcing-deepseek-v3-on-azure-ai-foundry-and-github/4390438\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/embed-v-4-0\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 3072,\n \"source\": \"https://azuremarketplace.microsoft.com/pt-br/marketplace/apps/cohere.cohere-embed-4-offer?tab=PlansAndPrice\",\n \"supported_endpoints\": [\n \"/v1/embeddings\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_embedding_image_input\": true\n },\n \"azure_ai/global/grok-3\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"source\": \"https://devblogs.microsoft.com/foundry/announcing-grok-3-and-grok-3-mini-on-azure-ai-foundry/\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/global/grok-3-mini\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.27e-06,\n \"source\": \"https://devblogs.microsoft.com/foundry/announcing-grok-3-and-grok-3-mini-on-azure-ai-foundry/\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/grok-3\": {\n \"input_cost_per_token\": 3.3e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.65e-05,\n \"source\": \"https://devblogs.microsoft.com/foundry/announcing-grok-3-and-grok-3-mini-on-azure-ai-foundry/\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/grok-3-mini\": {\n \"input_cost_per_token\": 2.75e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.38e-06,\n \"source\": \"https://devblogs.microsoft.com/foundry/announcing-grok-3-and-grok-3-mini-on-azure-ai-foundry/\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/grok-4\": {\n \"input_cost_per_token\": 5.5e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.75e-05,\n \"source\": \"https://azure.microsoft.com/en-us/blog/grok-4-is-now-available-in-azure-ai-foundry-unlock-frontier-intelligence-and-business-ready-capabilities/\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/grok-4-fast-non-reasoning\": {\n \"input_cost_per_token\": 0.43e-06,\n \"output_cost_per_token\": 1.73e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/grok-4-fast-reasoning\": {\n \"input_cost_per_token\": 0.43e-06,\n \"output_cost_per_token\": 1.73e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"source\": \"https://techcommunity.microsoft.com/blog/azure-ai-foundry-blog/announcing-the-grok-4-fast-models-from-xai-now-available-in-azure-ai-foundry/4456701\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/grok-code-fast-1\": {\n \"input_cost_per_token\": 3.5e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.75e-05,\n \"source\": \"https://azure.microsoft.com/en-us/blog/grok-4-is-now-available-in-azure-ai-foundry-unlock-frontier-intelligence-and-business-ready-capabilities/\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"azure_ai/jais-30b-chat\": {\n \"input_cost_per_token\": 0.0032,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00971,\n \"source\": \"https://azure.microsoft.com/en-us/products/ai-services/ai-foundry/models/jais-30b-chat\"\n },\n \"azure_ai/jamba-instruct\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 70000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"supports_tool_choice\": true\n },\n \"azure_ai/ministral-3b\": {\n \"input_cost_per_token\": 4e-08,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-08,\n \"source\": \"https://azuremarketplace.microsoft.com/en/marketplace/apps/000-000.ministral-3b-2410-offer?tab=Overview\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/mistral-large\": {\n \"input_cost_per_token\": 4e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/mistral-large-2407\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"source\": \"https://azuremarketplace.microsoft.com/en/marketplace/apps/000-000.mistral-ai-large-2407-offer?tab=Overview\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/mistral-large-latest\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"source\": \"https://azuremarketplace.microsoft.com/en/marketplace/apps/000-000.mistral-ai-large-2407-offer?tab=Overview\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/mistral-medium-2505\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/mistral-nemo\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://azuremarketplace.microsoft.com/en/marketplace/apps/000-000.mistral-nemo-12b-2407?tab=PlansAndPrice\",\n \"supports_function_calling\": true\n },\n \"azure_ai/mistral-small\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"azure_ai/mistral-small-2503\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"azure_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"babbage-002\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"text-completion-openai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16384,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 4e-07\n },\n \"bedrock/*/1-month-commitment/cohere.command-light-text-v14\": {\n \"input_cost_per_second\": 0.001902,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.001902,\n \"supports_tool_choice\": true\n },\n \"bedrock/*/1-month-commitment/cohere.command-text-v14\": {\n \"input_cost_per_second\": 0.011,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.011,\n \"supports_tool_choice\": true\n },\n \"bedrock/*/6-month-commitment/cohere.command-light-text-v14\": {\n \"input_cost_per_second\": 0.0011416,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0011416,\n \"supports_tool_choice\": true\n },\n \"bedrock/*/6-month-commitment/cohere.command-text-v14\": {\n \"input_cost_per_second\": 0.0066027,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0066027,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-northeast-1/1-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.01475,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.01475,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-northeast-1/1-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.0455,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0455\n },\n \"bedrock/ap-northeast-1/1-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.0455,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0455,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-northeast-1/6-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.008194,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.008194,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-northeast-1/6-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.02527,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.02527\n },\n \"bedrock/ap-northeast-1/6-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.02527,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.02527,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-northeast-1/anthropic.claude-instant-v1\": {\n \"input_cost_per_token\": 2.23e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.55e-06,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-northeast-1/anthropic.claude-v1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-northeast-1/anthropic.claude-v2:1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"bedrock/ap-south-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.18e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.2e-06\n },\n \"bedrock/ap-south-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.6e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07\n },\n \"bedrock/ca-central-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.05e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.03e-06\n },\n \"bedrock/ca-central-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.9e-07\n },\n \"bedrock/eu-central-1/1-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.01635,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.01635,\n \"supports_tool_choice\": true\n },\n \"bedrock/eu-central-1/1-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.0415,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0415\n },\n \"bedrock/eu-central-1/1-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.0415,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0415,\n \"supports_tool_choice\": true\n },\n \"bedrock/eu-central-1/6-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.009083,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.009083,\n \"supports_tool_choice\": true\n },\n \"bedrock/eu-central-1/6-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.02305,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.02305\n },\n \"bedrock/eu-central-1/6-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.02305,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.02305,\n \"supports_tool_choice\": true\n },\n \"bedrock/eu-central-1/anthropic.claude-instant-v1\": {\n \"input_cost_per_token\": 2.48e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.38e-06,\n \"supports_tool_choice\": true\n },\n \"bedrock/eu-central-1/anthropic.claude-v1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05\n },\n \"bedrock/eu-central-1/anthropic.claude-v2:1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"bedrock/eu-west-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.86e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.78e-06\n },\n \"bedrock/eu-west-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.5e-07\n },\n \"bedrock/eu-west-2/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.45e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.55e-06\n },\n \"bedrock/eu-west-2/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.9e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.8e-07\n },\n \"bedrock/eu-west-3/mistral.mistral-7b-instruct-v0:2\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.6e-07,\n \"supports_tool_choice\": true\n },\n \"bedrock/eu-west-3/mistral.mistral-large-2402-v1:0\": {\n \"input_cost_per_token\": 1.04e-05,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.12e-05,\n \"supports_function_calling\": true\n },\n \"bedrock/eu-west-3/mistral.mixtral-8x7b-instruct-v0:1\": {\n \"input_cost_per_token\": 5.9e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.1e-07,\n \"supports_tool_choice\": true\n },\n \"bedrock/invoke/anthropic.claude-3-5-sonnet-20240620-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Anthropic via Invoke route does not currently support pdf input.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"bedrock/sa-east-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 4.45e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.88e-06\n },\n \"bedrock/sa-east-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.01e-06\n },\n \"bedrock/us-east-1/1-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.011,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.011,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/1-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.0175,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0175\n },\n \"bedrock/us-east-1/1-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.0175,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0175,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/6-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.00611,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.00611,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/6-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.00972,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.00972\n },\n \"bedrock/us-east-1/6-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.00972,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.00972,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/anthropic.claude-instant-v1\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-06,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/anthropic.claude-v1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/anthropic.claude-v2:1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.65e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-06\n },\n \"bedrock/us-east-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"bedrock/us-east-1/mistral.mistral-7b-instruct-v0:2\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-east-1/mistral.mistral-large-2402-v1:0\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_function_calling\": true\n },\n \"bedrock/us-east-1/mistral.mixtral-8x7b-instruct-v0:1\": {\n \"input_cost_per_token\": 4.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-gov-east-1/amazon.nova-pro-v1:0\": {\n \"input_cost_per_token\": 9.6e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.84e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"bedrock/us-gov-east-1/amazon.titan-embed-text-v1\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1536\n },\n \"bedrock/us-gov-east-1/amazon.titan-embed-text-v2:0\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024\n },\n \"bedrock/us-gov-east-1/amazon.titan-text-express-v1\": {\n \"input_cost_per_token\": 1.3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 8000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.7e-06\n },\n \"bedrock/us-gov-east-1/amazon.titan-text-lite-v1\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 4000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07\n },\n \"bedrock/us-gov-east-1/amazon.titan-text-premier-v1:0\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06\n },\n \"bedrock/us-gov-east-1/anthropic.claude-3-5-sonnet-20240620-v1:0\": {\n \"input_cost_per_token\": 3.6e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"bedrock/us-gov-east-1/anthropic.claude-3-haiku-20240307-v1:0\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"bedrock/us-gov-east-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.65e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-06,\n \"supports_pdf_input\": true\n },\n \"bedrock/us-gov-east-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.65e-06,\n \"supports_pdf_input\": true\n },\n \"bedrock/us-gov-west-1/amazon.nova-pro-v1:0\": {\n \"input_cost_per_token\": 9.6e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.84e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"bedrock/us-gov-west-1/amazon.titan-embed-text-v1\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1536\n },\n \"bedrock/us-gov-west-1/amazon.titan-embed-text-v2:0\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1024\n },\n \"bedrock/us-gov-west-1/amazon.titan-text-express-v1\": {\n \"input_cost_per_token\": 1.3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 8000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.7e-06\n },\n \"bedrock/us-gov-west-1/amazon.titan-text-lite-v1\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 4000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07\n },\n \"bedrock/us-gov-west-1/amazon.titan-text-premier-v1:0\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 42000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06\n },\n \"bedrock/us-gov-west-1/anthropic.claude-3-7-sonnet-20250219-v1:0\": {\n \"cache_creation_input_token_cost\": 4.5e-06,\n \"cache_read_input_token_cost\": 3.6e-07,\n \"input_cost_per_token\": 3.6e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"bedrock/us-gov-west-1/anthropic.claude-3-5-sonnet-20240620-v1:0\": {\n \"input_cost_per_token\": 3.6e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"bedrock/us-gov-west-1/anthropic.claude-3-haiku-20240307-v1:0\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"bedrock/us-gov-west-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.65e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-06,\n \"supports_pdf_input\": true\n },\n \"bedrock/us-gov-west-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.65e-06,\n \"supports_pdf_input\": true\n },\n \"bedrock/us-west-1/meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.65e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-06\n },\n \"bedrock/us-west-1/meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"bedrock/us-west-2/1-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.011,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.011,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/1-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.0175,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0175\n },\n \"bedrock/us-west-2/1-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.0175,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.0175,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/6-month-commitment/anthropic.claude-instant-v1\": {\n \"input_cost_per_second\": 0.00611,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.00611,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/6-month-commitment/anthropic.claude-v1\": {\n \"input_cost_per_second\": 0.00972,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.00972\n },\n \"bedrock/us-west-2/6-month-commitment/anthropic.claude-v2:1\": {\n \"input_cost_per_second\": 0.00972,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_second\": 0.00972,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/anthropic.claude-instant-v1\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-06,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/anthropic.claude-v1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/anthropic.claude-v2:1\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/mistral.mistral-7b-instruct-v0:2\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_tool_choice\": true\n },\n \"bedrock/us-west-2/mistral.mistral-large-2402-v1:0\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_function_calling\": true\n },\n \"bedrock/us-west-2/mistral.mixtral-8x7b-instruct-v0:1\": {\n \"input_cost_per_token\": 4.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"supports_tool_choice\": true\n },\n \"bedrock/us.anthropic.claude-3-5-haiku-20241022-v1:0\": {\n \"cache_creation_input_token_cost\": 1e-06,\n \"cache_read_input_token_cost\": 8e-08,\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"cerebras/llama-3.3-70b\": {\n \"input_cost_per_token\": 8.5e-07,\n \"litellm_provider\": \"cerebras\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"cerebras/llama3.1-70b\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"cerebras\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"cerebras/llama3.1-8b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"cerebras\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"cerebras/openai/gpt-oss-120b\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"cerebras\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.9e-07,\n \"source\": \"https://www.cerebras.ai/blog/openai-gpt-oss-120b-runs-fastest-on-cerebras\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"cerebras/qwen-3-32b\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"cerebras\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"source\": \"https://inference-docs.cerebras.ai/support/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"chat-bison\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-chat-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"chat-bison-32k\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-chat-models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"chat-bison-32k@002\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-chat-models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"chat-bison@001\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-chat-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"chat-bison@002\": {\n \"deprecation_date\": \"2025-04-09\",\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-chat-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"chatdolphin\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"nlp_cloud\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07\n },\n \"chatgpt-4o-latest\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"claude-3-5-haiku-20241022\": {\n \"cache_creation_input_token_cost\": 1e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 8e-08,\n \"deprecation_date\": \"2025-10-01\",\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tool_use_system_prompt_tokens\": 264\n },\n \"claude-3-5-haiku-latest\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"deprecation_date\": \"2025-10-01\",\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tool_use_system_prompt_tokens\": 264\n },\n \"claude-haiku-4-5-20251001\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_creation_input_token_cost_above_1hr\": 2e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_computer_use\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"claude-haiku-4-5\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_creation_input_token_cost_above_1hr\": 2e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_computer_use\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"claude-3-5-sonnet-20240620\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"deprecation_date\": \"2025-06-01\",\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-3-5-sonnet-20241022\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"deprecation_date\": \"2025-10-01\",\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-3-5-sonnet-latest\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"deprecation_date\": \"2025-06-01\",\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-3-7-sonnet-20250219\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"deprecation_date\": \"2026-02-19\",\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-3-7-sonnet-latest\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"deprecation_date\": \"2025-06-01\",\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-3-haiku-20240307\": {\n \"cache_creation_input_token_cost\": 3e-07,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 3e-08,\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 264\n },\n \"claude-3-opus-20240229\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"deprecation_date\": \"2026-05-01\",\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 395\n },\n \"claude-3-opus-latest\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"deprecation_date\": \"2025-03-01\",\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 395\n },\n \"claude-4-opus-20250514\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-4-sonnet-20250514\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-sonnet-4-5\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"claude-sonnet-4-5-20250929\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"claude-opus-4-1\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_creation_input_token_cost_above_1hr\": 3e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-opus-4-1-20250805\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_creation_input_token_cost_above_1hr\": 3e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"deprecation_date\": \"2026-08-05\",\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-opus-4-20250514\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_creation_input_token_cost_above_1hr\": 3e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"deprecation_date\": \"2026-05-14\",\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"claude-sonnet-4-20250514\": {\n \"deprecation_date\": \"2026-05-14\",\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_1hr\": 6e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"anthropic\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"cloudflare/@cf/meta/llama-2-7b-chat-fp16\": {\n \"input_cost_per_token\": 1.923e-06,\n \"litellm_provider\": \"cloudflare\",\n \"max_input_tokens\": 3072,\n \"max_output_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.923e-06\n },\n \"cloudflare/@cf/meta/llama-2-7b-chat-int8\": {\n \"input_cost_per_token\": 1.923e-06,\n \"litellm_provider\": \"cloudflare\",\n \"max_input_tokens\": 2048,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.923e-06\n },\n \"cloudflare/@cf/mistral/mistral-7b-instruct-v0.1\": {\n \"input_cost_per_token\": 1.923e-06,\n \"litellm_provider\": \"cloudflare\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.923e-06\n },\n \"cloudflare/@hf/thebloke/codellama-7b-instruct-awq\": {\n \"input_cost_per_token\": 1.923e-06,\n \"litellm_provider\": \"cloudflare\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.923e-06\n },\n \"code-bison\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"code-bison-32k@002\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"code-bison32k\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"code-bison@001\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"code-bison@002\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"code-gecko\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 2048,\n \"max_output_tokens\": 64,\n \"max_tokens\": 64,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"code-gecko-latest\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 2048,\n \"max_output_tokens\": 64,\n \"max_tokens\": 64,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"code-gecko@001\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 2048,\n \"max_output_tokens\": 64,\n \"max_tokens\": 64,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"code-gecko@002\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-text-models\",\n \"max_input_tokens\": 2048,\n \"max_output_tokens\": 64,\n \"max_tokens\": 64,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"codechat-bison\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-chat-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"codechat-bison-32k\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-chat-models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"codechat-bison-32k@002\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-chat-models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"codechat-bison@001\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-chat-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"codechat-bison@002\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-chat-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"codechat-bison@latest\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-code-chat-models\",\n \"max_input_tokens\": 6144,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"codestral/codestral-2405\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"codestral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://docs.mistral.ai/capabilities/code_generation/\",\n \"supports_assistant_prefill\": true,\n \"supports_tool_choice\": true\n },\n \"codestral/codestral-latest\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"codestral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://docs.mistral.ai/capabilities/code_generation/\",\n \"supports_assistant_prefill\": true,\n \"supports_tool_choice\": true\n },\n \"codex-mini-latest\": {\n \"cache_read_input_token_cost\": 3.75e-07,\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 6e-06,\n \"supported_endpoints\": [\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"cohere.command-light-text-v14\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_tool_choice\": true\n },\n \"cohere.command-r-plus-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_tool_choice\": true\n },\n \"cohere.command-r-v1:0\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_tool_choice\": true\n },\n \"cohere.command-text-v14\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_tool_choice\": true\n },\n \"cohere.embed-english-v3\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"supports_embedding_image_input\": true\n },\n \"cohere.embed-multilingual-v3\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"supports_embedding_image_input\": true\n },\n \"cohere.embed-v4:0\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1536,\n \"supports_embedding_image_input\": true\n },\n \"cohere.rerank-v3-5:0\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"bedrock\",\n \"max_document_chunks_per_query\": 100,\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_query_tokens\": 32000,\n \"max_tokens\": 32000,\n \"max_tokens_per_document_chunk\": 512,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"command\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"command-a-03-2025\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"cohere_chat\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 8000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"command-light\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"cohere_chat\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_tool_choice\": true\n },\n \"command-nightly\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"command-r\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"cohere_chat\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"command-r-08-2024\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"cohere_chat\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"command-r-plus\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"cohere_chat\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"command-r-plus-08-2024\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"cohere_chat\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"command-r7b-12-2024\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"cohere_chat\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.75e-08,\n \"source\": \"https://docs.cohere.com/v2/docs/command-r7b\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"computer-use-preview\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"azure\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-05,\n \"supported_endpoints\": [\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": false,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"deepseek-chat\": {\n \"cache_read_input_token_cost\": 6e-08,\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"deepseek\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.7e-06,\n \"source\": \"https://api-docs.deepseek.com/quick_start/pricing\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"deepseek-reasoner\": {\n \"cache_read_input_token_cost\": 6e-08,\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"deepseek\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.7e-06,\n \"source\": \"https://api-docs.deepseek.com/quick_start/pricing\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supports_function_calling\": false,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": false\n },\n \"dashscope/qwen-coder\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-flash\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 5e-08,\n \"output_cost_per_token\": 4e-07,\n \"range\": [\n 0,\n 256000.0\n ]\n },\n {\n \"input_cost_per_token\": 2.5e-07,\n \"output_cost_per_token\": 2e-06,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen-flash-2025-07-28\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 5e-08,\n \"output_cost_per_token\": 4e-07,\n \"range\": [\n 0,\n 256000.0\n ]\n },\n {\n \"input_cost_per_token\": 2.5e-07,\n \"output_cost_per_token\": 2e-06,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen-max\": {\n \"input_cost_per_token\": 1.6e-06,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 30720,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.4e-06,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-plus\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 129024,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-plus-2025-01-25\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 129024,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-plus-2025-04-28\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 129024,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-06,\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-plus-2025-07-14\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 129024,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-06,\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-plus-2025-07-28\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 4e-07,\n \"output_cost_per_reasoning_token\": 4e-06,\n \"output_cost_per_token\": 1.2e-06,\n \"range\": [\n 0,\n 256000.0\n ]\n },\n {\n \"input_cost_per_token\": 1.2e-06,\n \"output_cost_per_reasoning_token\": 1.2e-05,\n \"output_cost_per_token\": 3.6e-06,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen-plus-2025-09-11\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 4e-07,\n \"output_cost_per_reasoning_token\": 4e-06,\n \"output_cost_per_token\": 1.2e-06,\n \"range\": [\n 0,\n 256000.0\n ]\n },\n {\n \"input_cost_per_token\": 1.2e-06,\n \"output_cost_per_reasoning_token\": 1.2e-05,\n \"output_cost_per_token\": 3.6e-06,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen-plus-latest\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 4e-07,\n \"output_cost_per_reasoning_token\": 4e-06,\n \"output_cost_per_token\": 1.2e-06,\n \"range\": [\n 0,\n 256000.0\n ]\n },\n {\n \"input_cost_per_token\": 1.2e-06,\n \"output_cost_per_reasoning_token\": 1.2e-05,\n \"output_cost_per_token\": 3.6e-06,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen-turbo\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 129024,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 5e-07,\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-turbo-2024-11-01\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-turbo-2025-04-28\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 5e-07,\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen-turbo-latest\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 5e-07,\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen3-30b-a3b\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 129024,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dashscope/qwen3-coder-flash\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"cache_read_input_token_cost\": 8e-08,\n \"input_cost_per_token\": 3e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"range\": [\n 0,\n 32000.0\n ]\n },\n {\n \"cache_read_input_token_cost\": 1.2e-07,\n \"input_cost_per_token\": 5e-07,\n \"output_cost_per_token\": 2.5e-06,\n \"range\": [\n 32000.0,\n 128000.0\n ]\n },\n {\n \"cache_read_input_token_cost\": 2e-07,\n \"input_cost_per_token\": 8e-07,\n \"output_cost_per_token\": 4e-06,\n \"range\": [\n 128000.0,\n 256000.0\n ]\n },\n {\n \"cache_read_input_token_cost\": 4e-07,\n \"input_cost_per_token\": 1.6e-06,\n \"output_cost_per_token\": 9.6e-06,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen3-coder-flash-2025-07-28\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 3e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"range\": [\n 0,\n 32000.0\n ]\n },\n {\n \"input_cost_per_token\": 5e-07,\n \"output_cost_per_token\": 2.5e-06,\n \"range\": [\n 32000.0,\n 128000.0\n ]\n },\n {\n \"input_cost_per_token\": 8e-07,\n \"output_cost_per_token\": 4e-06,\n \"range\": [\n 128000.0,\n 256000.0\n ]\n },\n {\n \"input_cost_per_token\": 1.6e-06,\n \"output_cost_per_token\": 9.6e-06,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen3-coder-plus\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"output_cost_per_token\": 5e-06,\n \"range\": [\n 0,\n 32000.0\n ]\n },\n {\n \"cache_read_input_token_cost\": 1.8e-07,\n \"input_cost_per_token\": 1.8e-06,\n \"output_cost_per_token\": 9e-06,\n \"range\": [\n 32000.0,\n 128000.0\n ]\n },\n {\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"output_cost_per_token\": 1.5e-05,\n \"range\": [\n 128000.0,\n 256000.0\n ]\n },\n {\n \"cache_read_input_token_cost\": 6e-07,\n \"input_cost_per_token\": 6e-06,\n \"output_cost_per_token\": 6e-05,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen3-coder-plus-2025-07-22\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 997952,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 1e-06,\n \"output_cost_per_token\": 5e-06,\n \"range\": [\n 0,\n 32000.0\n ]\n },\n {\n \"input_cost_per_token\": 1.8e-06,\n \"output_cost_per_token\": 9e-06,\n \"range\": [\n 32000.0,\n 128000.0\n ]\n },\n {\n \"input_cost_per_token\": 3e-06,\n \"output_cost_per_token\": 1.5e-05,\n \"range\": [\n 128000.0,\n 256000.0\n ]\n },\n {\n \"input_cost_per_token\": 6e-06,\n \"output_cost_per_token\": 6e-05,\n \"range\": [\n 256000.0,\n 1000000.0\n ]\n }\n ]\n },\n \"dashscope/qwen3-max-preview\": {\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 258048,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"tiered_pricing\": [\n {\n \"input_cost_per_token\": 1.2e-06,\n \"output_cost_per_token\": 6e-06,\n \"range\": [\n 0,\n 32000.0\n ]\n },\n {\n \"input_cost_per_token\": 2.4e-06,\n \"output_cost_per_token\": 1.2e-05,\n \"range\": [\n 32000.0,\n 128000.0\n ]\n },\n {\n \"input_cost_per_token\": 3e-06,\n \"output_cost_per_token\": 1.5e-05,\n \"range\": [\n 128000.0,\n 252000.0\n ]\n }\n ]\n },\n \"dashscope/qwq-plus\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"dashscope\",\n \"max_input_tokens\": 98304,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-06,\n \"source\": \"https://www.alibabacloud.com/help/en/model-studio/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-bge-large-en\": {\n \"input_cost_per_token\": 1.0003e-07,\n \"input_dbu_cost_per_token\": 1.429e-06,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_dbu_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\"\n },\n \"databricks/databricks-claude-3-7-sonnet\": {\n \"input_cost_per_token\": 2.5e-06,\n \"input_dbu_cost_per_token\": 3.571e-05,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 200000,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Claude 3.7 conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.7857e-05,\n \"output_db_cost_per_token\": 0.000214286,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-gte-large-en\": {\n \"input_cost_per_token\": 1.2999e-07,\n \"input_dbu_cost_per_token\": 1.857e-06,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_dbu_cost_per_token\": 0.0,\n \"output_vector_size\": 1024,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\"\n },\n \"databricks/databricks-llama-2-70b-chat\": {\n \"input_cost_per_token\": 5.0001e-07,\n \"input_dbu_cost_per_token\": 7.143e-06,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"output_dbu_cost_per_token\": 2.1429e-05,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-llama-4-maverick\": {\n \"input_cost_per_token\": 5e-06,\n \"input_dbu_cost_per_token\": 7.143e-05,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"metadata\": {\n \"notes\": \"Databricks documentation now provides both DBU costs (_dbu_cost_per_token) and dollar costs(_cost_per_token).\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_dbu_cost_per_token\": 0.00021429,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-meta-llama-3-1-405b-instruct\": {\n \"input_cost_per_token\": 5e-06,\n \"input_dbu_cost_per_token\": 7.1429e-05,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.500002e-05,\n \"output_db_cost_per_token\": 0.000214286,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-meta-llama-3-3-70b-instruct\": {\n \"input_cost_per_token\": 1.00002e-06,\n \"input_dbu_cost_per_token\": 1.4286e-05,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.99999e-06,\n \"output_dbu_cost_per_token\": 4.2857e-05,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-meta-llama-3-70b-instruct\": {\n \"input_cost_per_token\": 1.00002e-06,\n \"input_dbu_cost_per_token\": 1.4286e-05,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.99999e-06,\n \"output_dbu_cost_per_token\": 4.2857e-05,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-mixtral-8x7b-instruct\": {\n \"input_cost_per_token\": 5.0001e-07,\n \"input_dbu_cost_per_token\": 7.143e-06,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9902e-07,\n \"output_dbu_cost_per_token\": 1.4286e-05,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-mpt-30b-instruct\": {\n \"input_cost_per_token\": 9.9902e-07,\n \"input_dbu_cost_per_token\": 1.4286e-05,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9902e-07,\n \"output_dbu_cost_per_token\": 1.4286e-05,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"databricks/databricks-mpt-7b-instruct\": {\n \"input_cost_per_token\": 5.0001e-07,\n \"input_dbu_cost_per_token\": 7.143e-06,\n \"litellm_provider\": \"databricks\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"metadata\": {\n \"notes\": \"Input/output cost per token is dbu cost * $0.070, based on databricks Llama 3.1 70B conversion. Number provided for reference, '*_dbu_cost_per_token' used in actual calculation.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"output_dbu_cost_per_token\": 0.0,\n \"source\": \"https://www.databricks.com/product/pricing/foundation-model-serving\",\n \"supports_tool_choice\": true\n },\n \"dataforseo/search\": {\n \"input_cost_per_query\": 0.003,\n \"litellm_provider\": \"dataforseo\",\n \"mode\": \"search\"\n },\n \"davinci-002\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"text-completion-openai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16384,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"deepgram/base\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/base-conversationalai\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/base-finance\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/base-general\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/base-meeting\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/base-phonecall\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/base-video\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/base-voicemail\": {\n \"input_cost_per_second\": 0.00020833,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0125/60 seconds = $0.00020833 per second\",\n \"original_pricing_per_minute\": 0.0125\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/enhanced\": {\n \"input_cost_per_second\": 0.00024167,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0145/60 seconds = $0.00024167 per second\",\n \"original_pricing_per_minute\": 0.0145\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/enhanced-finance\": {\n \"input_cost_per_second\": 0.00024167,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0145/60 seconds = $0.00024167 per second\",\n \"original_pricing_per_minute\": 0.0145\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/enhanced-general\": {\n \"input_cost_per_second\": 0.00024167,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0145/60 seconds = $0.00024167 per second\",\n \"original_pricing_per_minute\": 0.0145\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/enhanced-meeting\": {\n \"input_cost_per_second\": 0.00024167,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0145/60 seconds = $0.00024167 per second\",\n \"original_pricing_per_minute\": 0.0145\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/enhanced-phonecall\": {\n \"input_cost_per_second\": 0.00024167,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0145/60 seconds = $0.00024167 per second\",\n \"original_pricing_per_minute\": 0.0145\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-atc\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-automotive\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-conversationalai\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-drivethru\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-finance\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-general\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-meeting\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-phonecall\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-video\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-2-voicemail\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-3\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-3-general\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-3-medical\": {\n \"input_cost_per_second\": 8.667e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0052/60 seconds = $0.00008667 per second (multilingual)\",\n \"original_pricing_per_minute\": 0.0052\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-general\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/nova-phonecall\": {\n \"input_cost_per_second\": 7.167e-05,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"calculation\": \"$0.0043/60 seconds = $0.00007167 per second\",\n \"original_pricing_per_minute\": 0.0043\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/whisper\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"notes\": \"Deepgram's hosted OpenAI Whisper models - pricing may differ from native Deepgram models\"\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/whisper-base\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"notes\": \"Deepgram's hosted OpenAI Whisper models - pricing may differ from native Deepgram models\"\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/whisper-large\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"notes\": \"Deepgram's hosted OpenAI Whisper models - pricing may differ from native Deepgram models\"\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/whisper-medium\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"notes\": \"Deepgram's hosted OpenAI Whisper models - pricing may differ from native Deepgram models\"\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/whisper-small\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"notes\": \"Deepgram's hosted OpenAI Whisper models - pricing may differ from native Deepgram models\"\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepgram/whisper-tiny\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"deepgram\",\n \"metadata\": {\n \"notes\": \"Deepgram's hosted OpenAI Whisper models - pricing may differ from native Deepgram models\"\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://deepgram.com/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"deepinfra/Gryphe/MythoMax-L2-13b\": {\n \"max_tokens\": 4096,\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"input_cost_per_token\": 8e-08,\n \"output_cost_per_token\": 9e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/NousResearch/Hermes-3-Llama-3.1-405B\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 1e-06,\n \"output_cost_per_token\": 1e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/NousResearch/Hermes-3-Llama-3.1-70B\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 3e-07,\n \"output_cost_per_token\": 3e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/Qwen/QwQ-32B\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 1.5e-07,\n \"output_cost_per_token\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen2.5-72B-Instruct\": {\n \"max_tokens\": 32768,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"input_cost_per_token\": 1.2e-07,\n \"output_cost_per_token\": 3.9e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen2.5-7B-Instruct\": {\n \"max_tokens\": 32768,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"input_cost_per_token\": 4e-08,\n \"output_cost_per_token\": 1e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/Qwen/Qwen2.5-VL-32B-Instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 2e-07,\n \"output_cost_per_token\": 6e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-14B\": {\n \"max_tokens\": 40960,\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 40960,\n \"input_cost_per_token\": 6e-08,\n \"output_cost_per_token\": 2.4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-235B-A22B\": {\n \"max_tokens\": 40960,\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 40960,\n \"input_cost_per_token\": 1.8e-07,\n \"output_cost_per_token\": 5.4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-235B-A22B-Instruct-2507\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 9e-08,\n \"output_cost_per_token\": 6e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-235B-A22B-Thinking-2507\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 3e-07,\n \"output_cost_per_token\": 2.9e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-30B-A3B\": {\n \"max_tokens\": 40960,\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 40960,\n \"input_cost_per_token\": 8e-08,\n \"output_cost_per_token\": 2.9e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-32B\": {\n \"max_tokens\": 40960,\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 40960,\n \"input_cost_per_token\": 1e-07,\n \"output_cost_per_token\": 2.8e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-Coder-480B-A35B-Instruct\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 4e-07,\n \"output_cost_per_token\": 1.6e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-Coder-480B-A35B-Instruct-Turbo\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 2.9e-07,\n \"output_cost_per_token\": 1.2e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-Next-80B-A3B-Instruct\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 1.4e-07,\n \"output_cost_per_token\": 1.4e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Qwen/Qwen3-Next-80B-A3B-Thinking\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 1.4e-07,\n \"output_cost_per_token\": 1.4e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/Sao10K/L3-8B-Lunaris-v1-Turbo\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 4e-08,\n \"output_cost_per_token\": 5e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/Sao10K/L3.1-70B-Euryale-v2.2\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 6.5e-07,\n \"output_cost_per_token\": 7.5e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/Sao10K/L3.3-70B-Euryale-v2.3\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 6.5e-07,\n \"output_cost_per_token\": 7.5e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/allenai/olmOCR-7B-0725-FP8\": {\n \"max_tokens\": 16384,\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"input_cost_per_token\": 2.7e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/anthropic/claude-3-7-sonnet-latest\": {\n \"max_tokens\": 200000,\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 200000,\n \"input_cost_per_token\": 3.3e-06,\n \"output_cost_per_token\": 1.65e-05,\n \"cache_read_input_token_cost\": 3.3e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/anthropic/claude-4-opus\": {\n \"max_tokens\": 200000,\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 200000,\n \"input_cost_per_token\": 1.65e-05,\n \"output_cost_per_token\": 8.25e-05,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/anthropic/claude-4-sonnet\": {\n \"max_tokens\": 200000,\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 200000,\n \"input_cost_per_token\": 3.3e-06,\n \"output_cost_per_token\": 1.65e-05,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-R1\": {\n \"max_tokens\": 163840,\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"input_cost_per_token\": 7e-07,\n \"output_cost_per_token\": 2.4e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-R1-0528\": {\n \"max_tokens\": 163840,\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"input_cost_per_token\": 5e-07,\n \"output_cost_per_token\": 2.15e-06,\n \"cache_read_input_token_cost\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-R1-0528-Turbo\": {\n \"max_tokens\": 32768,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"input_cost_per_token\": 1e-06,\n \"output_cost_per_token\": 3e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-R1-Distill-Llama-70B\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 2e-07,\n \"output_cost_per_token\": 6e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 2.7e-07,\n \"output_cost_per_token\": 2.7e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-R1-Turbo\": {\n \"max_tokens\": 40960,\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 40960,\n \"input_cost_per_token\": 1e-06,\n \"output_cost_per_token\": 3e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-V3\": {\n \"max_tokens\": 163840,\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"input_cost_per_token\": 3.8e-07,\n \"output_cost_per_token\": 8.9e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-V3-0324\": {\n \"max_tokens\": 163840,\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"input_cost_per_token\": 2.5e-07,\n \"output_cost_per_token\": 8.8e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-V3.1\": {\n \"max_tokens\": 163840,\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"input_cost_per_token\": 2.7e-07,\n \"output_cost_per_token\": 1e-06,\n \"cache_read_input_token_cost\": 2.16e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true,\n \"supports_reasoning\": true\n },\n \"deepinfra/deepseek-ai/DeepSeek-V3.1-Terminus\": {\n \"max_tokens\": 163840,\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"input_cost_per_token\": 2.7e-07,\n \"output_cost_per_token\": 1e-06,\n \"cache_read_input_token_cost\": 2.16e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/google/gemini-2.0-flash-001\": {\n \"max_tokens\": 1000000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 1000000,\n \"input_cost_per_token\": 1e-07,\n \"output_cost_per_token\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/google/gemini-2.5-flash\": {\n \"max_tokens\": 1000000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 1000000,\n \"input_cost_per_token\": 3e-07,\n \"output_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/google/gemini-2.5-pro\": {\n \"max_tokens\": 1000000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 1000000,\n \"input_cost_per_token\": 1.25e-06,\n \"output_cost_per_token\": 1e-05,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/google/gemma-3-12b-it\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 5e-08,\n \"output_cost_per_token\": 1e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/google/gemma-3-27b-it\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 9e-08,\n \"output_cost_per_token\": 1.6e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/google/gemma-3-4b-it\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 4e-08,\n \"output_cost_per_token\": 8e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Llama-3.2-11B-Vision-Instruct\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 4.9e-08,\n \"output_cost_per_token\": 4.9e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/meta-llama/Llama-3.2-3B-Instruct\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 2e-08,\n \"output_cost_per_token\": 2e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Llama-3.3-70B-Instruct\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 2.3e-07,\n \"output_cost_per_token\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Llama-3.3-70B-Instruct-Turbo\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 1.3e-07,\n \"output_cost_per_token\": 3.9e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8\": {\n \"max_tokens\": 1048576,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 1048576,\n \"input_cost_per_token\": 1.5e-07,\n \"output_cost_per_token\": 6e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Llama-4-Scout-17B-16E-Instruct\": {\n \"max_tokens\": 327680,\n \"max_input_tokens\": 327680,\n \"max_output_tokens\": 327680,\n \"input_cost_per_token\": 8e-08,\n \"output_cost_per_token\": 3e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Llama-Guard-3-8B\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 5.5e-08,\n \"output_cost_per_token\": 5.5e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/meta-llama/Llama-Guard-4-12B\": {\n \"max_tokens\": 163840,\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"input_cost_per_token\": 1.8e-07,\n \"output_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/meta-llama/Meta-Llama-3-8B-Instruct\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 3e-08,\n \"output_cost_per_token\": 6e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Meta-Llama-3.1-70B-Instruct\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 1e-07,\n \"output_cost_per_token\": 2.8e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Meta-Llama-3.1-8B-Instruct\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 3e-08,\n \"output_cost_per_token\": 5e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 2e-08,\n \"output_cost_per_token\": 3e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/microsoft/WizardLM-2-8x22B\": {\n \"max_tokens\": 65536,\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 65536,\n \"input_cost_per_token\": 4.8e-07,\n \"output_cost_per_token\": 4.8e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": false\n },\n \"deepinfra/microsoft/phi-4\": {\n \"max_tokens\": 16384,\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"input_cost_per_token\": 7e-08,\n \"output_cost_per_token\": 1.4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/mistralai/Mistral-Nemo-Instruct-2407\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 2e-08,\n \"output_cost_per_token\": 4e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/mistralai/Mistral-Small-24B-Instruct-2501\": {\n \"max_tokens\": 32768,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"input_cost_per_token\": 5e-08,\n \"output_cost_per_token\": 8e-08,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/mistralai/Mistral-Small-3.2-24B-Instruct-2506\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 7.5e-08,\n \"output_cost_per_token\": 2e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/mistralai/Mixtral-8x7B-Instruct-v0.1\": {\n \"max_tokens\": 32768,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"input_cost_per_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/moonshotai/Kimi-K2-Instruct\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 5e-07,\n \"output_cost_per_token\": 2e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/moonshotai/Kimi-K2-Instruct-0905\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 5e-07,\n \"output_cost_per_token\": 2e-06,\n \"cache_read_input_token_cost\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/nvidia/Llama-3.1-Nemotron-70B-Instruct\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 6e-07,\n \"output_cost_per_token\": 6e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/nvidia/Llama-3.3-Nemotron-Super-49B-v1.5\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 1e-07,\n \"output_cost_per_token\": 4e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/nvidia/NVIDIA-Nemotron-Nano-9B-v2\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 4e-08,\n \"output_cost_per_token\": 1.6e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/openai/gpt-oss-120b\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 5e-08,\n \"output_cost_per_token\": 4.5e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/openai/gpt-oss-20b\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 4e-08,\n \"output_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepinfra/zai-org/GLM-4.5\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 4e-07,\n \"output_cost_per_token\": 1.6e-06,\n \"litellm_provider\": \"deepinfra\",\n \"mode\": \"chat\",\n \"supports_tool_choice\": true\n },\n \"deepseek/deepseek-chat\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 7e-08,\n \"input_cost_per_token\": 2.7e-07,\n \"input_cost_per_token_cache_hit\": 7e-08,\n \"litellm_provider\": \"deepseek\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true\n },\n \"deepseek/deepseek-coder\": {\n \"input_cost_per_token\": 1.4e-07,\n \"input_cost_per_token_cache_hit\": 1.4e-08,\n \"litellm_provider\": \"deepseek\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true\n },\n \"deepseek/deepseek-r1\": {\n \"input_cost_per_token\": 5.5e-07,\n \"input_cost_per_token_cache_hit\": 1.4e-07,\n \"litellm_provider\": \"deepseek\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.19e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"deepseek/deepseek-reasoner\": {\n \"input_cost_per_token\": 5.5e-07,\n \"input_cost_per_token_cache_hit\": 1.4e-07,\n \"litellm_provider\": \"deepseek\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.19e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"deepseek/deepseek-v3\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 7e-08,\n \"input_cost_per_token\": 2.7e-07,\n \"input_cost_per_token_cache_hit\": 7e-08,\n \"litellm_provider\": \"deepseek\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true\n },\n \"deepseek.v3-v1:0\": {\n \"input_cost_per_token\": 5.8e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 81920,\n \"max_tokens\": 163840,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.68e-06,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"dolphin\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"nlp_cloud\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 5e-07\n },\n \"doubao-embedding\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"volcengine\",\n \"max_input_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Volcengine Doubao embedding model - standard version with 2560 dimensions\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 2560\n },\n \"doubao-embedding-large\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"volcengine\",\n \"max_input_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Volcengine Doubao embedding model - large version with 2048 dimensions\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 2048\n },\n \"doubao-embedding-large-text-240915\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"volcengine\",\n \"max_input_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Volcengine Doubao embedding model - text-240915 version with 4096 dimensions\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 4096\n },\n \"doubao-embedding-large-text-250515\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"volcengine\",\n \"max_input_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Volcengine Doubao embedding model - text-250515 version with 2048 dimensions\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 2048\n },\n \"doubao-embedding-text-240715\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"volcengine\",\n \"max_input_tokens\": 4096,\n \"max_tokens\": 4096,\n \"metadata\": {\n \"notes\": \"Volcengine Doubao embedding model - text-240715 version with 2560 dimensions\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 2560\n },\n \"exa_ai/search\": {\n \"litellm_provider\": \"exa_ai\",\n \"mode\": \"search\",\n \"tiered_pricing\": [\n {\n \"input_cost_per_query\": 5e-03,\n \"max_results_range\": [\n 0,\n 25\n ]\n },\n {\n \"input_cost_per_query\": 25e-03,\n \"max_results_range\": [\n 26,\n 100\n ]\n }\n ]\n },\n \"perplexity/search\": {\n \"input_cost_per_query\": 5e-03,\n \"litellm_provider\": \"perplexity\",\n \"mode\": \"search\"\n },\n \"elevenlabs/scribe_v1\": {\n \"input_cost_per_second\": 6.11e-05,\n \"litellm_provider\": \"elevenlabs\",\n \"metadata\": {\n \"calculation\": \"$0.22/hour = $0.00366/minute = $0.0000611 per second (enterprise pricing)\",\n \"notes\": \"ElevenLabs Scribe v1 - state-of-the-art speech recognition model with 99 language support\",\n \"original_pricing_per_hour\": 0.22\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://elevenlabs.io/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"elevenlabs/scribe_v1_experimental\": {\n \"input_cost_per_second\": 6.11e-05,\n \"litellm_provider\": \"elevenlabs\",\n \"metadata\": {\n \"calculation\": \"$0.22/hour = $0.00366/minute = $0.0000611 per second (enterprise pricing)\",\n \"notes\": \"ElevenLabs Scribe v1 experimental - enhanced version of the main Scribe model\",\n \"original_pricing_per_hour\": 0.22\n },\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0,\n \"source\": \"https://elevenlabs.io/pricing\",\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"embed-english-light-v2.0\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"embed-english-light-v3.0\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"embed-english-v2.0\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"embed-english-v3.0\": {\n \"input_cost_per_image\": 0.0001,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"metadata\": {\n \"notes\": \"'supports_image_input' is a deprecated field. Use 'supports_embedding_image_input' instead.\"\n },\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"supports_embedding_image_input\": true,\n \"supports_image_input\": true\n },\n \"embed-multilingual-v2.0\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 768,\n \"max_tokens\": 768,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"embed-multilingual-v3.0\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"supports_embedding_image_input\": true\n },\n \"eu.amazon.nova-lite-v1:0\": {\n \"input_cost_per_token\": 7.8e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.12e-07,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"eu.amazon.nova-micro-v1:0\": {\n \"input_cost_per_token\": 4.6e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.84e-07,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true\n },\n \"eu.amazon.nova-pro-v1:0\": {\n \"input_cost_per_token\": 1.05e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.2e-06,\n \"source\": \"https://aws.amazon.com/bedrock/pricing/\",\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"eu.anthropic.claude-3-5-haiku-20241022-v1:0\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"eu.anthropic.claude-haiku-4-5-20251001-v1:0\": {\n \"cache_creation_input_token_cost\": 1.375e-06,\n \"cache_read_input_token_cost\": 1.1e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"deprecation_date\": \"2026-10-15\",\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.5e-06,\n \"source\": \"https://aws.amazon.com/about-aws/whats-new/2025/10/claude-4-5-haiku-anthropic-amazon-bedrock\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"eu.anthropic.claude-3-5-sonnet-20240620-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"eu.anthropic.claude-3-5-sonnet-20241022-v2:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"eu.anthropic.claude-3-7-sonnet-20250219-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"eu.anthropic.claude-3-haiku-20240307-v1:0\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"eu.anthropic.claude-3-opus-20240229-v1:0\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"eu.anthropic.claude-3-sonnet-20240229-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"eu.anthropic.claude-opus-4-1-20250805-v1:0\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"eu.anthropic.claude-opus-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"eu.anthropic.claude-sonnet-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"eu.anthropic.claude-sonnet-4-5-20250929-v1:0\": {\n \"cache_creation_input_token_cost\": 4.125e-06,\n \"cache_read_input_token_cost\": 3.3e-07,\n \"input_cost_per_token\": 3.3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6.6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.475e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 8.25e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6.6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.65e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"eu.meta.llama3-2-1b-instruct-v1:0\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.3e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"eu.meta.llama3-2-3b-instruct-v1:0\": {\n \"input_cost_per_token\": 1.9e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.9e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"eu.mistral.pixtral-large-2502-v1:0\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"featherless_ai/featherless-ai/Qwerky-72B\": {\n \"litellm_provider\": \"featherless_ai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 32768,\n \"mode\": \"chat\"\n },\n \"featherless_ai/featherless-ai/Qwerky-QwQ-32B\": {\n \"litellm_provider\": \"featherless_ai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 32768,\n \"mode\": \"chat\"\n },\n \"fireworks-ai-4.1b-to-16b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"output_cost_per_token\": 2e-07\n },\n \"fireworks-ai-56b-to-176b\": {\n \"input_cost_per_token\": 1.2e-06,\n \"litellm_provider\": \"fireworks_ai\",\n \"output_cost_per_token\": 1.2e-06\n },\n \"fireworks-ai-above-16b\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"output_cost_per_token\": 9e-07\n },\n \"fireworks-ai-default\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"fireworks_ai\",\n \"output_cost_per_token\": 0.0\n },\n \"fireworks-ai-embedding-150m-to-350m\": {\n \"input_cost_per_token\": 1.6e-08,\n \"litellm_provider\": \"fireworks_ai-embedding-models\",\n \"output_cost_per_token\": 0.0\n },\n \"fireworks-ai-embedding-up-to-150m\": {\n \"input_cost_per_token\": 8e-09,\n \"litellm_provider\": \"fireworks_ai-embedding-models\",\n \"output_cost_per_token\": 0.0\n },\n \"fireworks-ai-moe-up-to-56b\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"output_cost_per_token\": 5e-07\n },\n \"fireworks-ai-up-to-4b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"output_cost_per_token\": 2e-07\n },\n \"fireworks_ai/WhereIsAI/UAE-Large-V1\": {\n \"input_cost_per_token\": 1.6e-08,\n \"litellm_provider\": \"fireworks_ai-embedding-models\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://fireworks.ai/pricing\"\n },\n \"fireworks_ai/accounts/fireworks/models/deepseek-coder-v2-instruct\": {\n \"input_cost_per_token\": 1.2e-06,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/deepseek-r1\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 20480,\n \"max_tokens\": 20480,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/deepseek-r1-0528\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 160000,\n \"max_output_tokens\": 160000,\n \"max_tokens\": 160000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/deepseek-r1-basic\": {\n \"input_cost_per_token\": 5.5e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 20480,\n \"max_tokens\": 20480,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.19e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/deepseek-v3\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/deepseek-v3-0324\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"max_tokens\": 163840,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"source\": \"https://fireworks.ai/models/fireworks/deepseek-v3-0324\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/deepseek-v3p1\": {\n \"input_cost_per_token\": 5.6e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.68e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/firefunction-v2\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/glm-4p5\": {\n \"input_cost_per_token\": 5.5e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 96000,\n \"max_tokens\": 96000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.19e-06,\n \"source\": \"https://fireworks.ai/models/fireworks/glm-4p5\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/glm-4p5-air\": {\n \"input_cost_per_token\": 2.2e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 96000,\n \"max_tokens\": 96000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.8e-07,\n \"source\": \"https://artificialanalysis.ai/models/glm-4-5-air\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/gpt-oss-120b\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/gpt-oss-20b\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/kimi-k2-instruct\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-06,\n \"source\": \"https://fireworks.ai/models/fireworks/kimi-k2-instruct\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/llama-v3p1-405b-instruct\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/llama-v3p1-8b-instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/llama-v3p2-11b-vision-instruct\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"fireworks_ai/accounts/fireworks/models/llama-v3p2-1b-instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/llama-v3p2-3b-instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/llama-v3p2-90b-vision-instruct\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"fireworks_ai/accounts/fireworks/models/llama4-maverick-instruct-basic\": {\n \"input_cost_per_token\": 2.2e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.8e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/llama4-scout-instruct-basic\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/mixtral-8x22b-instruct-hf\": {\n \"input_cost_per_token\": 1.2e-06,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"fireworks_ai/accounts/fireworks/models/qwen2-72b-instruct\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/qwen2p5-coder-32b-instruct\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/accounts/fireworks/models/yi-large\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"fireworks_ai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://fireworks.ai/pricing\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"fireworks_ai/nomic-ai/nomic-embed-text-v1\": {\n \"input_cost_per_token\": 8e-09,\n \"litellm_provider\": \"fireworks_ai-embedding-models\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://fireworks.ai/pricing\"\n },\n \"fireworks_ai/nomic-ai/nomic-embed-text-v1.5\": {\n \"input_cost_per_token\": 8e-09,\n \"litellm_provider\": \"fireworks_ai-embedding-models\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://fireworks.ai/pricing\"\n },\n \"fireworks_ai/thenlper/gte-base\": {\n \"input_cost_per_token\": 8e-09,\n \"litellm_provider\": \"fireworks_ai-embedding-models\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://fireworks.ai/pricing\"\n },\n \"fireworks_ai/thenlper/gte-large\": {\n \"input_cost_per_token\": 1.6e-08,\n \"litellm_provider\": \"fireworks_ai-embedding-models\",\n \"max_input_tokens\": 512,\n \"max_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://fireworks.ai/pricing\"\n },\n \"friendliai/meta-llama-3.1-70b-instruct\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"friendliai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"friendliai/meta-llama-3.1-8b-instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"friendliai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"ft:babbage-002\": {\n \"input_cost_per_token\": 4e-07,\n \"input_cost_per_token_batches\": 2e-07,\n \"litellm_provider\": \"text-completion-openai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16384,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 4e-07,\n \"output_cost_per_token_batches\": 2e-07\n },\n \"ft:davinci-002\": {\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_batches\": 1e-06,\n \"litellm_provider\": \"text-completion-openai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16384,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06,\n \"output_cost_per_token_batches\": 1e-06\n },\n \"ft:gpt-3.5-turbo\": {\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_batches\": 1.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"output_cost_per_token_batches\": 3e-06,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"ft:gpt-3.5-turbo-0125\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"ft:gpt-3.5-turbo-0613\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"ft:gpt-3.5-turbo-1106\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"ft:gpt-4-0613\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"source\": \"OpenAI needs to add pricing for this ft model, will be updated when added by OpenAI. Defaulting to base model pricing\",\n \"supports_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"ft:gpt-4o-2024-08-06\": {\n \"input_cost_per_token\": 3.75e-06,\n \"input_cost_per_token_batches\": 1.875e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_cost_per_token_batches\": 7.5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"ft:gpt-4o-2024-11-20\": {\n \"cache_creation_input_token_cost\": 1.875e-06,\n \"input_cost_per_token\": 3.75e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"ft:gpt-4o-mini-2024-07-18\": {\n \"cache_read_input_token_cost\": 1.5e-07,\n \"input_cost_per_token\": 3e-07,\n \"input_cost_per_token_batches\": 1.5e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"output_cost_per_token_batches\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.0-pro\": {\n \"input_cost_per_character\": 1.25e-07,\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_video_per_second\": 0.002,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 32760,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 3.75e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#google_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-1.0-pro-001\": {\n \"deprecation_date\": \"2025-04-09\",\n \"input_cost_per_character\": 1.25e-07,\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_video_per_second\": 0.002,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 32760,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 3.75e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-1.0-pro-002\": {\n \"deprecation_date\": \"2025-04-09\",\n \"input_cost_per_character\": 1.25e-07,\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_video_per_second\": 0.002,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 32760,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 3.75e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-1.0-pro-vision\": {\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"vertex_ai-vision-models\",\n \"max_images_per_prompt\": 16,\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"max_video_length\": 2,\n \"max_videos_per_prompt\": 1,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.0-pro-vision-001\": {\n \"deprecation_date\": \"2025-04-09\",\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"vertex_ai-vision-models\",\n \"max_images_per_prompt\": 16,\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"max_video_length\": 2,\n \"max_videos_per_prompt\": 1,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.0-ultra\": {\n \"input_cost_per_character\": 1.25e-07,\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_video_per_second\": 0.002,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 3.75e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"As of Jun, 2024. There is no available doc on vertex ai pricing gemini-1.0-ultra-001. Using gemini-1.0-pro pricing. Got max_tokens info here: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-1.0-ultra-001\": {\n \"input_cost_per_character\": 1.25e-07,\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_video_per_second\": 0.002,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 3.75e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"As of Jun, 2024. There is no available doc on vertex ai pricing gemini-1.0-ultra-001. Using gemini-1.0-pro pricing. Got max_tokens info here: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-1.5-flash\": {\n \"input_cost_per_audio_per_second\": 2e-06,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 4e-06,\n \"input_cost_per_character\": 1.875e-08,\n \"input_cost_per_character_above_128k_tokens\": 2.5e-07,\n \"input_cost_per_image\": 2e-05,\n \"input_cost_per_image_above_128k_tokens\": 4e-05,\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1e-06,\n \"input_cost_per_video_per_second\": 2e-05,\n \"input_cost_per_video_per_second_above_128k_tokens\": 4e-05,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 7.5e-08,\n \"output_cost_per_character_above_128k_tokens\": 1.5e-07,\n \"output_cost_per_token\": 3e-07,\n \"output_cost_per_token_above_128k_tokens\": 6e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-flash-001\": {\n \"deprecation_date\": \"2025-05-24\",\n \"input_cost_per_audio_per_second\": 2e-06,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 4e-06,\n \"input_cost_per_character\": 1.875e-08,\n \"input_cost_per_character_above_128k_tokens\": 2.5e-07,\n \"input_cost_per_image\": 2e-05,\n \"input_cost_per_image_above_128k_tokens\": 4e-05,\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1e-06,\n \"input_cost_per_video_per_second\": 2e-05,\n \"input_cost_per_video_per_second_above_128k_tokens\": 4e-05,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 7.5e-08,\n \"output_cost_per_character_above_128k_tokens\": 1.5e-07,\n \"output_cost_per_token\": 3e-07,\n \"output_cost_per_token_above_128k_tokens\": 6e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-flash-002\": {\n \"deprecation_date\": \"2025-09-24\",\n \"input_cost_per_audio_per_second\": 2e-06,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 4e-06,\n \"input_cost_per_character\": 1.875e-08,\n \"input_cost_per_character_above_128k_tokens\": 2.5e-07,\n \"input_cost_per_image\": 2e-05,\n \"input_cost_per_image_above_128k_tokens\": 4e-05,\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1e-06,\n \"input_cost_per_video_per_second\": 2e-05,\n \"input_cost_per_video_per_second_above_128k_tokens\": 4e-05,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 7.5e-08,\n \"output_cost_per_character_above_128k_tokens\": 1.5e-07,\n \"output_cost_per_token\": 3e-07,\n \"output_cost_per_token_above_128k_tokens\": 6e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-1.5-flash\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-flash-exp-0827\": {\n \"input_cost_per_audio_per_second\": 2e-06,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 4e-06,\n \"input_cost_per_character\": 1.875e-08,\n \"input_cost_per_character_above_128k_tokens\": 2.5e-07,\n \"input_cost_per_image\": 2e-05,\n \"input_cost_per_image_above_128k_tokens\": 4e-05,\n \"input_cost_per_token\": 4.688e-09,\n \"input_cost_per_token_above_128k_tokens\": 1e-06,\n \"input_cost_per_video_per_second\": 2e-05,\n \"input_cost_per_video_per_second_above_128k_tokens\": 4e-05,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.875e-08,\n \"output_cost_per_character_above_128k_tokens\": 3.75e-08,\n \"output_cost_per_token\": 4.6875e-09,\n \"output_cost_per_token_above_128k_tokens\": 9.375e-09,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-flash-preview-0514\": {\n \"input_cost_per_audio_per_second\": 2e-06,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 4e-06,\n \"input_cost_per_character\": 1.875e-08,\n \"input_cost_per_character_above_128k_tokens\": 2.5e-07,\n \"input_cost_per_image\": 2e-05,\n \"input_cost_per_image_above_128k_tokens\": 4e-05,\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1e-06,\n \"input_cost_per_video_per_second\": 2e-05,\n \"input_cost_per_video_per_second_above_128k_tokens\": 4e-05,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.875e-08,\n \"output_cost_per_character_above_128k_tokens\": 3.75e-08,\n \"output_cost_per_token\": 4.6875e-09,\n \"output_cost_per_token_above_128k_tokens\": 9.375e-09,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-pro\": {\n \"input_cost_per_audio_per_second\": 3.125e-05,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 6.25e-05,\n \"input_cost_per_character\": 3.125e-07,\n \"input_cost_per_character_above_128k_tokens\": 6.25e-07,\n \"input_cost_per_image\": 0.00032875,\n \"input_cost_per_image_above_128k_tokens\": 0.0006575,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_128k_tokens\": 2.5e-06,\n \"input_cost_per_video_per_second\": 0.00032875,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0.0006575,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.25e-06,\n \"output_cost_per_character_above_128k_tokens\": 2.5e-06,\n \"output_cost_per_token\": 5e-06,\n \"output_cost_per_token_above_128k_tokens\": 1e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-pro-001\": {\n \"deprecation_date\": \"2025-05-24\",\n \"input_cost_per_audio_per_second\": 3.125e-05,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 6.25e-05,\n \"input_cost_per_character\": 3.125e-07,\n \"input_cost_per_character_above_128k_tokens\": 6.25e-07,\n \"input_cost_per_image\": 0.00032875,\n \"input_cost_per_image_above_128k_tokens\": 0.0006575,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_128k_tokens\": 2.5e-06,\n \"input_cost_per_video_per_second\": 0.00032875,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0.0006575,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.25e-06,\n \"output_cost_per_character_above_128k_tokens\": 2.5e-06,\n \"output_cost_per_token\": 5e-06,\n \"output_cost_per_token_above_128k_tokens\": 1e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-pro-002\": {\n \"deprecation_date\": \"2025-09-24\",\n \"input_cost_per_audio_per_second\": 3.125e-05,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 6.25e-05,\n \"input_cost_per_character\": 3.125e-07,\n \"input_cost_per_character_above_128k_tokens\": 6.25e-07,\n \"input_cost_per_image\": 0.00032875,\n \"input_cost_per_image_above_128k_tokens\": 0.0006575,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_128k_tokens\": 2.5e-06,\n \"input_cost_per_video_per_second\": 0.00032875,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0.0006575,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.25e-06,\n \"output_cost_per_character_above_128k_tokens\": 2.5e-06,\n \"output_cost_per_token\": 5e-06,\n \"output_cost_per_token_above_128k_tokens\": 1e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-1.5-pro\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini-1.5-pro-preview-0215\": {\n \"input_cost_per_audio_per_second\": 3.125e-05,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 6.25e-05,\n \"input_cost_per_character\": 3.125e-07,\n \"input_cost_per_character_above_128k_tokens\": 6.25e-07,\n \"input_cost_per_image\": 0.00032875,\n \"input_cost_per_image_above_128k_tokens\": 0.0006575,\n \"input_cost_per_token\": 7.8125e-08,\n \"input_cost_per_token_above_128k_tokens\": 1.5625e-07,\n \"input_cost_per_video_per_second\": 0.00032875,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0.0006575,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.25e-06,\n \"output_cost_per_character_above_128k_tokens\": 2.5e-06,\n \"output_cost_per_token\": 3.125e-07,\n \"output_cost_per_token_above_128k_tokens\": 6.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-1.5-pro-preview-0409\": {\n \"input_cost_per_audio_per_second\": 3.125e-05,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 6.25e-05,\n \"input_cost_per_character\": 3.125e-07,\n \"input_cost_per_character_above_128k_tokens\": 6.25e-07,\n \"input_cost_per_image\": 0.00032875,\n \"input_cost_per_image_above_128k_tokens\": 0.0006575,\n \"input_cost_per_token\": 7.8125e-08,\n \"input_cost_per_token_above_128k_tokens\": 1.5625e-07,\n \"input_cost_per_video_per_second\": 0.00032875,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0.0006575,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.25e-06,\n \"output_cost_per_character_above_128k_tokens\": 2.5e-06,\n \"output_cost_per_token\": 3.125e-07,\n \"output_cost_per_token_above_128k_tokens\": 6.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-1.5-pro-preview-0514\": {\n \"input_cost_per_audio_per_second\": 3.125e-05,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 6.25e-05,\n \"input_cost_per_character\": 3.125e-07,\n \"input_cost_per_character_above_128k_tokens\": 6.25e-07,\n \"input_cost_per_image\": 0.00032875,\n \"input_cost_per_image_above_128k_tokens\": 0.0006575,\n \"input_cost_per_token\": 7.8125e-08,\n \"input_cost_per_token_above_128k_tokens\": 1.5625e-07,\n \"input_cost_per_video_per_second\": 0.00032875,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0.0006575,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.25e-06,\n \"output_cost_per_character_above_128k_tokens\": 2.5e-06,\n \"output_cost_per_token\": 3.125e-07,\n \"output_cost_per_token_above_128k_tokens\": 6.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-2.0-flash\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"source\": \"https://ai.google.dev/pricing#2_0flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-flash-001\": {\n \"cache_read_input_token_cost\": 3.75e-08,\n \"deprecation_date\": \"2026-02-05\",\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-flash-exp\": {\n \"cache_read_input_token_cost\": 3.75e-08,\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 1.5e-07,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 6e-07,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-flash-lite\": {\n \"cache_read_input_token_cost\": 1.875e-08,\n \"input_cost_per_audio_token\": 7.5e-08,\n \"input_cost_per_token\": 7.5e-08,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 50,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-flash-lite-001\": {\n \"cache_read_input_token_cost\": 1.875e-08,\n \"deprecation_date\": \"2026-02-25\",\n \"input_cost_per_audio_token\": 7.5e-08,\n \"input_cost_per_token\": 7.5e-08,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 50,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-flash-live-preview-04-09\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 3e-06,\n \"input_cost_per_image\": 3e-06,\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_video_per_second\": 3e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 1.2e-05,\n \"output_cost_per_token\": 2e-06,\n \"rpm\": 10,\n \"source\": \"https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini#gemini-2-0-flash-live-preview-04-09\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini-2.0-flash-preview-image-generation\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"source\": \"https://ai.google.dev/pricing#2_0flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-flash-thinking-exp\": {\n \"cache_read_input_token_cost\": 0.0,\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-flash-thinking-exp-01-21\": {\n \"cache_read_input_token_cost\": 0.0,\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65536,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": false,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.0-pro-exp-02-05\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_input\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_video_input\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-flash\": {\n \"cache_read_input_token_cost\": 3e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-flash-image\": {\n \"cache_read_input_token_cost\": 3e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"max_pdf_size_mb\": 30,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.039,\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"rpm\": 100000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-flash-image\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": false,\n \"tpm\": 8000000\n },\n \"gemini-2.5-flash-image-preview\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.039,\n \"output_cost_per_reasoning_token\": 3e-05,\n \"output_cost_per_token\": 3e-05,\n \"rpm\": 100000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 8000000\n },\n \"gemini-2.5-flash-lite\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 5e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-flash-lite-preview-09-2025\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 3e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"source\": \"https://developers.googleblog.com/en/continuing-to-bring-you-our-latest-models-with-an-improved-gemini-2-5-flash-and-flash-lite-release/\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-flash-preview-09-2025\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"source\": \"https://developers.googleblog.com/en/continuing-to-bring-you-our-latest-models-with-an-improved-gemini-2-5-flash-and-flash-lite-release/\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-flash-lite-preview-06-17\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 5e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-flash-preview-04-17\": {\n \"cache_read_input_token_cost\": 3.75e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 3.5e-06,\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-flash-preview-05-20\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-pro\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"cache_creation_input_token_cost_above_200k_tokens\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_input\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_video_input\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-pro-exp-03-25\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_input\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_video_input\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-pro-preview-03-25\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 1.25e-06,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-pro-preview-05-06\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 1.25e-06,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supported_regions\": [\n \"global\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-pro-preview-06-05\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 1.25e-06,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-2.5-pro-preview-tts\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-pro-preview\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"audio\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gemini-embedding-001\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 3072,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models\"\n },\n \"gemini-flash-experimental\": {\n \"input_cost_per_character\": 0,\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_token\": 0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/gemini-experimental\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-pro\": {\n \"input_cost_per_character\": 1.25e-07,\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_video_per_second\": 0.002,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 32760,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 3.75e-07,\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-pro-experimental\": {\n \"input_cost_per_character\": 0,\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_token\": 0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/gemini-experimental\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"gemini-pro-vision\": {\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"vertex_ai-vision-models\",\n \"max_images_per_prompt\": 16,\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"max_video_length\": 2,\n \"max_videos_per_prompt\": 1,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini/gemini-1.5-flash\": {\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"output_cost_per_token_above_128k_tokens\": 6e-07,\n \"rpm\": 2000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-flash-001\": {\n \"cache_creation_input_token_cost\": 1e-06,\n \"cache_read_input_token_cost\": 1.875e-08,\n \"deprecation_date\": \"2025-05-24\",\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"output_cost_per_token_above_128k_tokens\": 6e-07,\n \"rpm\": 2000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-flash-002\": {\n \"cache_creation_input_token_cost\": 1e-06,\n \"cache_read_input_token_cost\": 1.875e-08,\n \"deprecation_date\": \"2025-09-24\",\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"output_cost_per_token_above_128k_tokens\": 6e-07,\n \"rpm\": 2000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-flash-8b\": {\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 4000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-flash-8b-exp-0827\": {\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 4000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-flash-8b-exp-0924\": {\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 4000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-flash-exp-0827\": {\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 2000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-flash-latest\": {\n \"input_cost_per_token\": 7.5e-08,\n \"input_cost_per_token_above_128k_tokens\": 1.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"output_cost_per_token_above_128k_tokens\": 6e-07,\n \"rpm\": 2000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-pro\": {\n \"input_cost_per_token\": 3.5e-06,\n \"input_cost_per_token_above_128k_tokens\": 7e-06,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-05,\n \"output_cost_per_token_above_128k_tokens\": 2.1e-05,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-pro-001\": {\n \"deprecation_date\": \"2025-05-24\",\n \"input_cost_per_token\": 3.5e-06,\n \"input_cost_per_token_above_128k_tokens\": 7e-06,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-05,\n \"output_cost_per_token_above_128k_tokens\": 2.1e-05,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-pro-002\": {\n \"deprecation_date\": \"2025-09-24\",\n \"input_cost_per_token\": 3.5e-06,\n \"input_cost_per_token_above_128k_tokens\": 7e-06,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-05,\n \"output_cost_per_token_above_128k_tokens\": 2.1e-05,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-pro-exp-0801\": {\n \"input_cost_per_token\": 3.5e-06,\n \"input_cost_per_token_above_128k_tokens\": 7e-06,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-05,\n \"output_cost_per_token_above_128k_tokens\": 2.1e-05,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-pro-exp-0827\": {\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-1.5-pro-latest\": {\n \"input_cost_per_token\": 3.5e-06,\n \"input_cost_per_token_above_128k_tokens\": 7e-06,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-06,\n \"output_cost_per_token_above_128k_tokens\": 2.1e-05,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-2.0-flash\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"rpm\": 10000,\n \"source\": \"https://ai.google.dev/pricing#2_0flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-2.0-flash-001\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"rpm\": 10000,\n \"source\": \"https://ai.google.dev/pricing#2_0flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-2.0-flash-exp\": {\n \"cache_read_input_token_cost\": 0.0,\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 10,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-2.0-flash-lite\": {\n \"cache_read_input_token_cost\": 1.875e-08,\n \"input_cost_per_audio_token\": 7.5e-08,\n \"input_cost_per_token\": 7.5e-08,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 50,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"rpm\": 4000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.0-flash-lite\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-2.0-flash-lite-preview-02-05\": {\n \"cache_read_input_token_cost\": 1.875e-08,\n \"input_cost_per_audio_token\": 7.5e-08,\n \"input_cost_per_token\": 7.5e-08,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"rpm\": 60000,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash-lite\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-2.0-flash-live-001\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 2.1e-06,\n \"input_cost_per_image\": 2.1e-06,\n \"input_cost_per_token\": 3.5e-07,\n \"input_cost_per_video_per_second\": 2.1e-06,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8.5e-06,\n \"output_cost_per_token\": 1.5e-06,\n \"rpm\": 10,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2-0-flash-live-001\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.0-flash-preview-image-generation\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"rpm\": 10000,\n \"source\": \"https://ai.google.dev/pricing#2_0flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-2.0-flash-thinking-exp\": {\n \"cache_read_input_token_cost\": 0.0,\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 10,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-2.0-flash-thinking-exp-01-21\": {\n \"cache_read_input_token_cost\": 0.0,\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 10,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-2.0-flash\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-2.0-pro-exp-02-05\": {\n \"cache_read_input_token_cost\": 0.0,\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 2,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_audio_input\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_video_input\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 1000000\n },\n \"gemini/gemini-2.5-flash\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"rpm\": 100000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 8000000\n },\n \"gemini/gemini-2.5-flash-image\": {\n \"cache_read_input_token_cost\": 3e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"max_pdf_size_mb\": 30,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.039,\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"rpm\": 100000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-flash-image\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 8000000\n },\n \"gemini/gemini-2.5-flash-image-preview\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.039,\n \"output_cost_per_reasoning_token\": 3e-05,\n \"output_cost_per_token\": 3e-05,\n \"rpm\": 100000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 8000000\n },\n \"gemini/gemini-2.5-flash-lite\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 5e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"rpm\": 15,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-lite\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-flash-lite-preview-09-2025\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 3e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"rpm\": 15,\n \"source\": \"https://developers.googleblog.com/en/continuing-to-bring-you-our-latest-models-with-an-improved-gemini-2-5-flash-and-flash-lite-release/\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-flash-preview-09-2025\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"rpm\": 15,\n \"source\": \"https://developers.googleblog.com/en/continuing-to-bring-you-our-latest-models-with-an-improved-gemini-2-5-flash-and-flash-lite-release/\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-flash-latest\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"rpm\": 15,\n \"source\": \"https://developers.googleblog.com/en/continuing-to-bring-you-our-latest-models-with-an-improved-gemini-2-5-flash-and-flash-lite-release/\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-flash-lite-latest\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 3e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"rpm\": 15,\n \"source\": \"https://developers.googleblog.com/en/continuing-to-bring-you-our-latest-models-with-an-improved-gemini-2-5-flash-and-flash-lite-release/\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-flash-lite-preview-06-17\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_audio_token\": 5e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 4e-07,\n \"output_cost_per_token\": 4e-07,\n \"rpm\": 15,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-lite\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-flash-preview-04-17\": {\n \"cache_read_input_token_cost\": 3.75e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 3.5e-06,\n \"output_cost_per_token\": 6e-07,\n \"rpm\": 10,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-flash-preview-05-20\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 2.5e-06,\n \"output_cost_per_token\": 2.5e-06,\n \"rpm\": 10,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-flash-preview-tts\": {\n \"cache_read_input_token_cost\": 3.75e-08,\n \"input_cost_per_audio_token\": 1e-06,\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 3.5e-06,\n \"output_cost_per_token\": 6e-07,\n \"rpm\": 10,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"audio\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-pro\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"rpm\": 2000,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_input\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_video_input\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 800000\n },\n \"gemini/gemini-2.5-pro-exp-03-25\": {\n \"cache_read_input_token_cost\": 0.0,\n \"input_cost_per_token\": 0.0,\n \"input_cost_per_token_above_200k_tokens\": 0.0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"output_cost_per_token_above_200k_tokens\": 0.0,\n \"rpm\": 5,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/completions\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_input\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_video_input\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 250000\n },\n \"gemini/gemini-2.5-pro-preview-03-25\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"rpm\": 10000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-pro-preview\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-2.5-pro-preview-05-06\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"rpm\": 10000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-pro-preview\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-2.5-pro-preview-06-05\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"rpm\": 10000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-pro-preview\",\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\",\n \"video\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_url_context\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-2.5-pro-preview-tts\": {\n \"cache_read_input_token_cost\": 3.125e-07,\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_above_200k_tokens\": 2.5e-06,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65535,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 65535,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_above_200k_tokens\": 1.5e-05,\n \"rpm\": 10000,\n \"source\": \"https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-pro-preview\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"audio\"\n ],\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true,\n \"tpm\": 10000000\n },\n \"gemini/gemini-exp-1114\": {\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"metadata\": {\n \"notes\": \"Rate limits not documented for gemini-exp-1114. Assuming same as gemini-1.5-pro.\",\n \"supports_tool_choice\": true\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-exp-1206\": {\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 2097152,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"metadata\": {\n \"notes\": \"Rate limits not documented for gemini-exp-1206. Assuming same as gemini-1.5-pro.\",\n \"supports_tool_choice\": true\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"rpm\": 1000,\n \"source\": \"https://ai.google.dev/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 4000000\n },\n \"gemini/gemini-gemma-2-27b-it\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini/gemini-gemma-2-9b-it\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"gemini\",\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini/gemini-pro\": {\n \"input_cost_per_token\": 3.5e-07,\n \"input_cost_per_token_above_128k_tokens\": 7e-07,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 32760,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-06,\n \"output_cost_per_token_above_128k_tokens\": 2.1e-06,\n \"rpd\": 30000,\n \"rpm\": 360,\n \"source\": \"https://ai.google.dev/gemini-api/docs/models/gemini\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"tpm\": 120000\n },\n \"gemini/gemini-pro-vision\": {\n \"input_cost_per_token\": 3.5e-07,\n \"input_cost_per_token_above_128k_tokens\": 7e-07,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 30720,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.05e-06,\n \"output_cost_per_token_above_128k_tokens\": 2.1e-06,\n \"rpd\": 30000,\n \"rpm\": 360,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tpm\": 120000\n },\n \"gemini/gemma-3-27b-it\": {\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"source\": \"https://aistudio.google.com\",\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini/imagen-3.0-fast-generate-001\": {\n \"litellm_provider\": \"gemini\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.02,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"gemini/imagen-3.0-generate-001\": {\n \"litellm_provider\": \"gemini\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"gemini/imagen-3.0-generate-002\": {\n \"litellm_provider\": \"gemini\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"gemini/imagen-4.0-fast-generate-001\": {\n \"litellm_provider\": \"gemini\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.02,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"gemini/imagen-4.0-generate-001\": {\n \"litellm_provider\": \"gemini\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"gemini/imagen-4.0-ultra-generate-001\": {\n \"litellm_provider\": \"gemini\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"gemini/learnlm-1.5-pro-experimental\": {\n \"input_cost_per_audio_per_second\": 0,\n \"input_cost_per_audio_per_second_above_128k_tokens\": 0,\n \"input_cost_per_character\": 0,\n \"input_cost_per_character_above_128k_tokens\": 0,\n \"input_cost_per_image\": 0,\n \"input_cost_per_image_above_128k_tokens\": 0,\n \"input_cost_per_token\": 0,\n \"input_cost_per_token_above_128k_tokens\": 0,\n \"input_cost_per_video_per_second\": 0,\n \"input_cost_per_video_per_second_above_128k_tokens\": 0,\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 32767,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 0,\n \"output_cost_per_character_above_128k_tokens\": 0,\n \"output_cost_per_token\": 0,\n \"output_cost_per_token_above_128k_tokens\": 0,\n \"source\": \"https://aistudio.google.com\",\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gemini/veo-2.0-generate-001\": {\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"video_generation\",\n \"output_cost_per_second\": 0.35,\n \"source\": \"https://ai.google.dev/gemini-api/docs/video\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ]\n },\n \"gemini/veo-3.0-fast-generate-preview\": {\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"video_generation\",\n \"output_cost_per_second\": 0.4,\n \"source\": \"https://ai.google.dev/gemini-api/docs/video\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ]\n },\n \"gemini/veo-3.0-generate-preview\": {\n \"litellm_provider\": \"gemini\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"video_generation\",\n \"output_cost_per_second\": 0.75,\n \"source\": \"https://ai.google.dev/gemini-api/docs/video\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ]\n },\n \"google_pse/search\": {\n \"input_cost_per_query\": 0.005,\n \"litellm_provider\": \"google_pse\",\n \"mode\": \"search\"\n },\n \"global.anthropic.claude-sonnet-4-5-20250929-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"global.anthropic.claude-sonnet-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"global.anthropic.claude-haiku-4-5-20251001-v1:0\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"gpt-3.5-turbo\": {\n \"input_cost_per_token\": 0.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4097,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-3.5-turbo-0125\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16385,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-3.5-turbo-0301\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 4097,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4097,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-3.5-turbo-0613\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 4097,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4097,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-3.5-turbo-1106\": {\n \"deprecation_date\": \"2026-09-28\",\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16385,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-3.5-turbo-16k\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16385,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-3.5-turbo-16k-0613\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16385,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-3.5-turbo-instruct\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"text-completion-openai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"gpt-3.5-turbo-instruct-0914\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"text-completion-openai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4097,\n \"max_tokens\": 4097,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2e-06\n },\n \"gpt-4\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-0125-preview\": {\n \"deprecation_date\": \"2026-03-26\",\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-0314\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-0613\": {\n \"deprecation_date\": \"2025-06-06\",\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-1106-preview\": {\n \"deprecation_date\": \"2026-03-26\",\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-1106-vision-preview\": {\n \"deprecation_date\": \"2024-12-06\",\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4-32k\": {\n \"input_cost_per_token\": 6e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00012,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-32k-0314\": {\n \"input_cost_per_token\": 6e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00012,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-32k-0613\": {\n \"input_cost_per_token\": 6e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00012,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-turbo\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4-turbo-2024-04-09\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4-turbo-preview\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4-vision-preview\": {\n \"deprecation_date\": \"2024-12-06\",\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4.1\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"cache_read_input_token_cost_priority\": 8.75e-07,\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_batches\": 1e-06,\n \"input_cost_per_token_priority\": 3.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"output_cost_per_token_batches\": 4e-06,\n \"output_cost_per_token_priority\": 1.4e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4.1-2025-04-14\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_batches\": 1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"output_cost_per_token_batches\": 4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4.1-mini\": {\n \"cache_read_input_token_cost\": 1e-07,\n \"cache_read_input_token_cost_priority\": 1.75e-07,\n \"input_cost_per_token\": 4e-07,\n \"input_cost_per_token_batches\": 2e-07,\n \"input_cost_per_token_priority\": 7e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06,\n \"output_cost_per_token_batches\": 8e-07,\n \"output_cost_per_token_priority\": 2.8e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4.1-mini-2025-04-14\": {\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 4e-07,\n \"input_cost_per_token_batches\": 2e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06,\n \"output_cost_per_token_batches\": 8e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4.1-nano\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"cache_read_input_token_cost_priority\": 5e-08,\n \"input_cost_per_token\": 1e-07,\n \"input_cost_per_token_batches\": 5e-08,\n \"input_cost_per_token_priority\": 2e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"output_cost_per_token_batches\": 2e-07,\n \"output_cost_per_token_priority\": 8e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4.1-nano-2025-04-14\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"input_cost_per_token_batches\": 5e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"output_cost_per_token_batches\": 2e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4.5-preview\": {\n \"cache_read_input_token_cost\": 3.75e-05,\n \"input_cost_per_token\": 7.5e-05,\n \"input_cost_per_token_batches\": 3.75e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00015,\n \"output_cost_per_token_batches\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4.5-preview-2025-02-27\": {\n \"cache_read_input_token_cost\": 3.75e-05,\n \"deprecation_date\": \"2025-07-14\",\n \"input_cost_per_token\": 7.5e-05,\n \"input_cost_per_token_batches\": 3.75e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.00015,\n \"output_cost_per_token_batches\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4o\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"cache_read_input_token_cost_priority\": 2.125e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"input_cost_per_token_batches\": 1.25e-06,\n \"input_cost_per_token_priority\": 4.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_batches\": 5e-06,\n \"output_cost_per_token_priority\": 1.7e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-2024-05-13\": {\n \"input_cost_per_token\": 5e-06,\n \"input_cost_per_token_batches\": 2.5e-06,\n \"input_cost_per_token_priority\": 8.75e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_cost_per_token_batches\": 7.5e-06,\n \"output_cost_per_token_priority\": 2.625e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-2024-08-06\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"input_cost_per_token_batches\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_batches\": 5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-2024-11-20\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"input_cost_per_token_batches\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_batches\": 5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-audio-preview\": {\n \"input_cost_per_audio_token\": 0.0001,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 0.0002,\n \"output_cost_per_token\": 1e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-audio-preview-2024-10-01\": {\n \"input_cost_per_audio_token\": 0.0001,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 0.0002,\n \"output_cost_per_token\": 1e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-audio-preview-2024-12-17\": {\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 1e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-audio-preview-2025-06-03\": {\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 1e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-mini\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"cache_read_input_token_cost_priority\": 1.25e-07,\n \"input_cost_per_token\": 1.5e-07,\n \"input_cost_per_token_batches\": 7.5e-08,\n \"input_cost_per_token_priority\": 2.5e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"output_cost_per_token_batches\": 3e-07,\n \"output_cost_per_token_priority\": 1e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-mini-2024-07-18\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_token\": 1.5e-07,\n \"input_cost_per_token_batches\": 7.5e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"output_cost_per_token_batches\": 3e-07,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.03,\n \"search_context_size_low\": 0.025,\n \"search_context_size_medium\": 0.0275\n },\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-mini-audio-preview\": {\n \"input_cost_per_audio_token\": 1e-05,\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2e-05,\n \"output_cost_per_token\": 6e-07,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-mini-audio-preview-2024-12-17\": {\n \"input_cost_per_audio_token\": 1e-05,\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2e-05,\n \"output_cost_per_token\": 6e-07,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-mini-realtime-preview\": {\n \"cache_creation_input_audio_token_cost\": 3e-07,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_audio_token\": 1e-05,\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2e-05,\n \"output_cost_per_token\": 2.4e-06,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-mini-realtime-preview-2024-12-17\": {\n \"cache_creation_input_audio_token_cost\": 3e-07,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_audio_token\": 1e-05,\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2e-05,\n \"output_cost_per_token\": 2.4e-06,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-mini-search-preview\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_token\": 1.5e-07,\n \"input_cost_per_token_batches\": 7.5e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"output_cost_per_token_batches\": 3e-07,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.03,\n \"search_context_size_low\": 0.025,\n \"search_context_size_medium\": 0.0275\n },\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gpt-4o-mini-search-preview-2025-03-11\": {\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_token\": 1.5e-07,\n \"input_cost_per_token_batches\": 7.5e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"output_cost_per_token_batches\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-mini-transcribe\": {\n \"input_cost_per_audio_token\": 3e-06,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16000,\n \"max_output_tokens\": 2000,\n \"mode\": \"audio_transcription\",\n \"output_cost_per_token\": 5e-06,\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"gpt-4o-mini-tts\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"mode\": \"audio_speech\",\n \"output_cost_per_audio_token\": 1.2e-05,\n \"output_cost_per_second\": 0.00025,\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/audio/speech\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"audio\"\n ]\n },\n \"gpt-4o-realtime-preview\": {\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 2e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-realtime-preview-2024-10-01\": {\n \"cache_creation_input_audio_token_cost\": 2e-05,\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_audio_token\": 0.0001,\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 0.0002,\n \"output_cost_per_token\": 2e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-realtime-preview-2024-12-17\": {\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 2e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-realtime-preview-2025-06-03\": {\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_audio_token\": 4e-05,\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 8e-05,\n \"output_cost_per_token\": 2e-05,\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-4o-search-preview\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"input_cost_per_token_batches\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_batches\": 5e-06,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.05,\n \"search_context_size_low\": 0.03,\n \"search_context_size_medium\": 0.035\n },\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gpt-4o-search-preview-2025-03-11\": {\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"input_cost_per_token_batches\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_batches\": 5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-4o-transcribe\": {\n \"input_cost_per_audio_token\": 6e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 16000,\n \"max_output_tokens\": 2000,\n \"mode\": \"audio_transcription\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"gpt-5\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"cache_read_input_token_cost_flex\": 6.25e-08,\n \"cache_read_input_token_cost_priority\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_flex\": 6.25e-07,\n \"input_cost_per_token_priority\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_flex\": 5e-06,\n \"output_cost_per_token_priority\": 2e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-5-pro\": {\n \"input_cost_per_token\": 1.5e-05,\n \"input_cost_per_token_batches\": 7.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 400000,\n \"max_output_tokens\": 272000,\n \"max_tokens\": 272000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 1.2e-04,\n \"output_cost_per_token_batches\": 6e-05,\n \"supported_endpoints\": [\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": false,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gpt-5-pro-2025-10-06\": {\n \"input_cost_per_token\": 1.5e-05,\n \"input_cost_per_token_batches\": 7.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 400000,\n \"max_output_tokens\": 272000,\n \"max_tokens\": 272000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 1.2e-04,\n \"output_cost_per_token_batches\": 6e-05,\n \"supported_endpoints\": [\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": false,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"gpt-5-2025-08-07\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"cache_read_input_token_cost_flex\": 6.25e-08,\n \"cache_read_input_token_cost_priority\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"input_cost_per_token_flex\": 6.25e-07,\n \"input_cost_per_token_priority\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"output_cost_per_token_flex\": 5e-06,\n \"output_cost_per_token_priority\": 2e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-5-chat\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": false,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"gpt-5-chat-latest\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": false,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"gpt-5-codex\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 1e-05,\n \"supported_endpoints\": [\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": false,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-5-mini\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"cache_read_input_token_cost_flex\": 1.25e-08,\n \"cache_read_input_token_cost_priority\": 4.5e-08,\n \"input_cost_per_token\": 2.5e-07,\n \"input_cost_per_token_flex\": 1.25e-07,\n \"input_cost_per_token_priority\": 4.5e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"output_cost_per_token_flex\": 1e-06,\n \"output_cost_per_token_priority\": 3.6e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-5-mini-2025-08-07\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"cache_read_input_token_cost_flex\": 1.25e-08,\n \"cache_read_input_token_cost_priority\": 4.5e-08,\n \"input_cost_per_token\": 2.5e-07,\n \"input_cost_per_token_flex\": 1.25e-07,\n \"input_cost_per_token_priority\": 4.5e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"output_cost_per_token_flex\": 1e-06,\n \"output_cost_per_token_priority\": 3.6e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"gpt-5-nano\": {\n \"cache_read_input_token_cost\": 5e-09,\n \"cache_read_input_token_cost_flex\": 2.5e-09,\n \"input_cost_per_token\": 5e-08,\n \"input_cost_per_token_flex\": 2.5e-08,\n \"input_cost_per_token_priority\": 2.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"output_cost_per_token_flex\": 2e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-5-nano-2025-08-07\": {\n \"cache_read_input_token_cost\": 5e-09,\n \"cache_read_input_token_cost_flex\": 2.5e-09,\n \"input_cost_per_token\": 5e-08,\n \"input_cost_per_token_flex\": 2.5e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"output_cost_per_token_flex\": 2e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"gpt-image-1-mini\": {\n \"cache_read_input_image_token_cost\": 2.5e-07,\n \"cache_read_input_token_cost\": 2e-07,\n \"input_cost_per_image_token\": 2.5e-06,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"openai\",\n \"mode\": \"chat\",\n \"output_cost_per_image_token\": 8e-06,\n \"supported_endpoints\": [\n \"/v1/images/generations\",\n \"/v1/images/edits\"\n ]\n },\n \"gpt-realtime\": {\n \"cache_creation_input_audio_token_cost\": 4e-07,\n \"cache_read_input_token_cost\": 4e-07,\n \"input_cost_per_audio_token\": 3.2e-05,\n \"input_cost_per_image\": 5e-06,\n \"input_cost_per_token\": 4e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 6.4e-05,\n \"output_cost_per_token\": 1.6e-05,\n \"supported_endpoints\": [\n \"/v1/realtime\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-realtime-mini\": {\n \"cache_creation_input_audio_token_cost\": 3e-07,\n \"cache_read_input_audio_token_cost\": 3e-07,\n \"input_cost_per_audio_token\": 1e-05,\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 2e-05,\n \"output_cost_per_token\": 2.4e-06,\n \"supported_endpoints\": [\n \"/v1/realtime\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gpt-realtime-2025-08-28\": {\n \"cache_creation_input_audio_token_cost\": 4e-07,\n \"cache_read_input_token_cost\": 4e-07,\n \"input_cost_per_audio_token\": 3.2e-05,\n \"input_cost_per_image\": 5e-06,\n \"input_cost_per_token\": 4e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_audio_token\": 6.4e-05,\n \"output_cost_per_token\": 1.6e-05,\n \"supported_endpoints\": [\n \"/v1/realtime\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"audio\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"audio\"\n ],\n \"supports_audio_input\": true,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"gradient_ai/alibaba-qwen3-32b\": {\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/anthropic-claude-3-opus\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/anthropic-claude-3.5-haiku\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/anthropic-claude-3.5-sonnet\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/anthropic-claude-3.7-sonnet\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/deepseek-r1-distill-llama-70b\": {\n \"input_cost_per_token\": 9.9e-07,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 8000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/llama3-8b-instruct\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 512,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/llama3.3-70b-instruct\": {\n \"input_cost_per_token\": 6.5e-07,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.5e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/mistral-nemo-instruct-2407\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 512,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/openai-gpt-4o\": {\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/openai-gpt-4o-mini\": {\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/openai-o3\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"gradient_ai/openai-o3-mini\": {\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"gradient_ai\",\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\"\n ],\n \"supported_modalities\": [\n \"text\"\n ],\n \"supports_tool_choice\": false\n },\n \"lemonade/Qwen3-Coder-30B-A3B-Instruct-GGUF\": {\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"lemonade\",\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"lemonade/gpt-oss-20b-mxfp4-GGUF\": {\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"lemonade\",\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"lemonade/gpt-oss-120b-mxfp-GGUF\": {\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"lemonade\",\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"lemonade/Gemma-3-4b-it-GGUF\": {\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"lemonade\",\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"lemonade/Qwen3-4B-Instruct-2507-GGUF\": {\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"lemonade\",\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/deepseek-r1-distill-llama-70b\": {\n \"input_cost_per_token\": 7.5e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9e-07,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/distil-whisper-large-v3-en\": {\n \"input_cost_per_second\": 5.56e-06,\n \"litellm_provider\": \"groq\",\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0\n },\n \"groq/gemma-7b-it\": {\n \"deprecation_date\": \"2024-12-18\",\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-08,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/gemma2-9b-it\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"groq/llama-3.1-405b-reasoning\": {\n \"input_cost_per_token\": 5.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.9e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.1-70b-versatile\": {\n \"deprecation_date\": \"2025-01-24\",\n \"input_cost_per_token\": 5.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.9e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.1-8b-instant\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-08,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.2-11b-text-preview\": {\n \"deprecation_date\": \"2024-10-28\",\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.2-11b-vision-preview\": {\n \"deprecation_date\": \"2025-04-14\",\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"groq/llama-3.2-1b-preview\": {\n \"deprecation_date\": \"2025-04-14\",\n \"input_cost_per_token\": 4e-08,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-08,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.2-3b-preview\": {\n \"deprecation_date\": \"2025-04-14\",\n \"input_cost_per_token\": 6e-08,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-08,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.2-90b-text-preview\": {\n \"deprecation_date\": \"2024-11-25\",\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.2-90b-vision-preview\": {\n \"deprecation_date\": \"2025-04-14\",\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"groq/llama-3.3-70b-specdec\": {\n \"deprecation_date\": \"2025-04-14\",\n \"input_cost_per_token\": 5.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9e-07,\n \"supports_tool_choice\": true\n },\n \"groq/llama-3.3-70b-versatile\": {\n \"input_cost_per_token\": 5.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.9e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama-guard-3-8b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07\n },\n \"groq/llama2-70b-4096\": {\n \"input_cost_per_token\": 7e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama3-groq-70b-8192-tool-use-preview\": {\n \"deprecation_date\": \"2025-01-06\",\n \"input_cost_per_token\": 8.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.9e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/llama3-groq-8b-8192-tool-use-preview\": {\n \"deprecation_date\": \"2025-01-06\",\n \"input_cost_per_token\": 1.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.9e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/meta-llama/llama-4-maverick-17b-128e-instruct\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/meta-llama/llama-4-scout-17b-16e-instruct\": {\n \"input_cost_per_token\": 1.1e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.4e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/mistral-saba-24b\": {\n \"input_cost_per_token\": 7.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.9e-07\n },\n \"groq/mixtral-8x7b-32768\": {\n \"deprecation_date\": \"2025-03-20\",\n \"input_cost_per_token\": 2.4e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-07,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/moonshotai/kimi-k2-instruct\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/moonshotai/kimi-k2-instruct-0905\": {\n \"input_cost_per_token\": 1e-06,\n \"output_cost_per_token\": 3e-06,\n \"cache_read_input_token_cost\": 0.5e-06,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 278528,\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/openai/gpt-oss-120b\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32766,\n \"max_tokens\": 32766,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"groq/openai/gpt-oss-20b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"groq/playai-tts\": {\n \"input_cost_per_character\": 5e-05,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 10000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"audio_speech\"\n },\n \"groq/qwen/qwen3-32b\": {\n \"input_cost_per_token\": 2.9e-07,\n \"litellm_provider\": \"groq\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131000,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.9e-07,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"groq/whisper-large-v3\": {\n \"input_cost_per_second\": 3.083e-05,\n \"litellm_provider\": \"groq\",\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0\n },\n \"groq/whisper-large-v3-turbo\": {\n \"input_cost_per_second\": 1.111e-05,\n \"litellm_provider\": \"groq\",\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0\n },\n \"hd/1024-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 7.629e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"hd/1024-x-1792/dall-e-3\": {\n \"input_cost_per_pixel\": 6.539e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"hd/1792-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 6.539e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"heroku/claude-3-5-haiku\": {\n \"litellm_provider\": \"heroku\",\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"heroku/claude-3-5-sonnet-latest\": {\n \"litellm_provider\": \"heroku\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"heroku/claude-3-7-sonnet\": {\n \"litellm_provider\": \"heroku\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"heroku/claude-4-sonnet\": {\n \"litellm_provider\": \"heroku\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"high/1024-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.59263611e-07,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"high/1024-x-1536/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.58945719e-07,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"high/1536-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.58945719e-07,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"hyperbolic/NousResearch/Hermes-3-Llama-3.1-70B\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/Qwen/QwQ-32B\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/Qwen/Qwen2.5-72B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/Qwen/Qwen2.5-Coder-32B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/Qwen/Qwen3-235B-A22B\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/deepseek-ai/DeepSeek-R1\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/deepseek-ai/DeepSeek-R1-0528\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/deepseek-ai/DeepSeek-V3\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/deepseek-ai/DeepSeek-V3-0324\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/meta-llama/Llama-3.2-3B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/meta-llama/Llama-3.3-70B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/meta-llama/Meta-Llama-3-70B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/meta-llama/Meta-Llama-3.1-405B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/meta-llama/Meta-Llama-3.1-70B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/meta-llama/Meta-Llama-3.1-8B-Instruct\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"hyperbolic/moonshotai/Kimi-K2-Instruct\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"hyperbolic\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"j2-light\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 3e-06\n },\n \"j2-mid\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1e-05\n },\n \"j2-ultra\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"jamba-1.5\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"jamba-1.5-large\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_tool_choice\": true\n },\n \"jamba-1.5-large@001\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_tool_choice\": true\n },\n \"jamba-1.5-mini\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"jamba-1.5-mini@001\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"jamba-large-1.6\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_tool_choice\": true\n },\n \"jamba-large-1.7\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_tool_choice\": true\n },\n \"jamba-mini-1.6\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"jamba-mini-1.7\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"ai21\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"jina-reranker-v2-base-multilingual\": {\n \"input_cost_per_token\": 1.8e-08,\n \"litellm_provider\": \"jina_ai\",\n \"max_document_chunks_per_query\": 2048,\n \"max_input_tokens\": 1024,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 1.8e-08\n },\n \"jp.anthropic.claude-sonnet-4-5-20250929-v1:0\": {\n \"cache_creation_input_token_cost\": 4.125e-06,\n \"cache_read_input_token_cost\": 3.3e-07,\n \"input_cost_per_token\": 3.3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6.6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.475e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 8.25e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6.6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.65e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"jp.anthropic.claude-haiku-4-5-20251001-v1:0\": {\n \"cache_creation_input_token_cost\": 1.375e-06,\n \"cache_read_input_token_cost\": 1.1e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.5e-06,\n \"source\": \"https://aws.amazon.com/about-aws/whats-new/2025/10/claude-4-5-haiku-anthropic-amazon-bedrock\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/deepseek-llama3.3-70b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/deepseek-r1-0528\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/deepseek-r1-671b\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/deepseek-v3-0324\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/hermes3-405b\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/hermes3-70b\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/hermes3-8b\": {\n \"input_cost_per_token\": 2.5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-08,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/lfm-40b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/lfm-7b\": {\n \"input_cost_per_token\": 2.5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-08,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama-4-maverick-17b-128e-instruct-fp8\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama-4-scout-17b-16e-instruct\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama3.1-405b-instruct-fp8\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama3.1-70b-instruct-fp8\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama3.1-8b-instruct\": {\n \"input_cost_per_token\": 2.5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-08,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama3.1-nemotron-70b-instruct-fp8\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama3.2-11b-vision-instruct\": {\n \"input_cost_per_token\": 1.5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-08,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"lambda_ai/llama3.2-3b-instruct\": {\n \"input_cost_per_token\": 1.5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-08,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/llama3.3-70b-instruct-fp8\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/qwen25-coder-32b-instruct\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"lambda_ai/qwen3-32b-fp8\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"lambda_ai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true\n },\n \"low/1024-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.0490417e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"low/1024-x-1536/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.0172526e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"low/1536-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 1.0172526e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"luminous-base\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"aleph_alpha\",\n \"max_tokens\": 2048,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 3.3e-05\n },\n \"luminous-base-control\": {\n \"input_cost_per_token\": 3.75e-05,\n \"litellm_provider\": \"aleph_alpha\",\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.125e-05\n },\n \"luminous-extended\": {\n \"input_cost_per_token\": 4.5e-05,\n \"litellm_provider\": \"aleph_alpha\",\n \"max_tokens\": 2048,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 4.95e-05\n },\n \"luminous-extended-control\": {\n \"input_cost_per_token\": 5.625e-05,\n \"litellm_provider\": \"aleph_alpha\",\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.1875e-05\n },\n \"luminous-supreme\": {\n \"input_cost_per_token\": 0.000175,\n \"litellm_provider\": \"aleph_alpha\",\n \"max_tokens\": 2048,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0001925\n },\n \"luminous-supreme-control\": {\n \"input_cost_per_token\": 0.00021875,\n \"litellm_provider\": \"aleph_alpha\",\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.000240625\n },\n \"max-x-max/50-steps/stability.stable-diffusion-xl-v0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.036\n },\n \"max-x-max/max-steps/stability.stable-diffusion-xl-v0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.072\n },\n \"medium/1024-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"medium/1024-x-1536/gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"medium/1536-x-1024/gpt-image-1\": {\n \"input_cost_per_pixel\": 4.0054321e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"low/1024-x-1024/gpt-image-1-mini\": {\n \"input_cost_per_image\": 0.005,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"low/1024-x-1536/gpt-image-1-mini\": {\n \"input_cost_per_image\": 0.006,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"low/1536-x-1024/gpt-image-1-mini\": {\n \"input_cost_per_image\": 0.006,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"medium/1024-x-1024/gpt-image-1-mini\": {\n \"input_cost_per_image\": 0.011,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"medium/1024-x-1536/gpt-image-1-mini\": {\n \"input_cost_per_image\": 0.015,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"medium/1536-x-1024/gpt-image-1-mini\": {\n \"input_cost_per_image\": 0.015,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"medlm-large\": {\n \"input_cost_per_character\": 5e-06,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1.5e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"medlm-medium\": {\n \"input_cost_per_character\": 5e-07,\n \"litellm_provider\": \"vertex_ai-language-models\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_character\": 1e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\",\n \"supports_tool_choice\": true\n },\n \"meta.llama2-13b-chat-v1\": {\n \"input_cost_per_token\": 7.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"meta.llama2-70b-chat-v1\": {\n \"input_cost_per_token\": 1.95e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.56e-06\n },\n \"meta.llama3-1-405b-instruct-v1:0\": {\n \"input_cost_per_token\": 5.32e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta.llama3-1-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 9.9e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta.llama3-1-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.2e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta.llama3-2-11b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"meta.llama3-2-1b-instruct-v1:0\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta.llama3-2-3b-instruct-v1:0\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta.llama3-2-90b-instruct-v1:0\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"meta.llama3-3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta.llama3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.65e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-06\n },\n \"meta.llama3-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"meta.llama4-maverick-17b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.4e-07,\n \"input_cost_per_token_batches\": 1.2e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.7e-07,\n \"output_cost_per_token_batches\": 4.85e-07,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta.llama4-scout-17b-instruct-v1:0\": {\n \"input_cost_per_token\": 1.7e-07,\n \"input_cost_per_token_batches\": 8.5e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-07,\n \"output_cost_per_token_batches\": 3.3e-07,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"meta_llama/Llama-3.3-70B-Instruct\": {\n \"litellm_provider\": \"meta_llama\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4028,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"source\": \"https://llama.developer.meta.com/docs/models\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"meta_llama/Llama-3.3-8B-Instruct\": {\n \"litellm_provider\": \"meta_llama\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4028,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"source\": \"https://llama.developer.meta.com/docs/models\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8\": {\n \"litellm_provider\": \"meta_llama\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 4028,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"source\": \"https://llama.developer.meta.com/docs/models\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8\": {\n \"litellm_provider\": \"meta_llama\",\n \"max_input_tokens\": 10000000,\n \"max_output_tokens\": 4028,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"source\": \"https://llama.developer.meta.com/docs/models\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"mistral.mistral-7b-instruct-v0:2\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_tool_choice\": true\n },\n \"mistral.mistral-large-2402-v1:0\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_function_calling\": true\n },\n \"mistral.mistral-large-2407-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"mistral.mistral-small-2402-v1:0\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_function_calling\": true\n },\n \"mistral.mixtral-8x7b-instruct-v0:1\": {\n \"input_cost_per_token\": 4.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"supports_tool_choice\": true\n },\n \"mistral/codestral-2405\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/codestral-latest\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/codestral-mamba-latest\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"source\": \"https://mistral.ai/technology/\",\n \"supports_assistant_prefill\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/devstral-medium-2507\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"source\": \"https://mistral.ai/news/devstral\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/devstral-small-2505\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://mistral.ai/news/devstral\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/devstral-small-2507\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://mistral.ai/news/devstral\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/magistral-medium-2506\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 40000,\n \"max_output_tokens\": 40000,\n \"max_tokens\": 40000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://mistral.ai/news/magistral\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-ocr-latest\": {\n \"litellm_provider\": \"mistral\",\n \"ocr_cost_per_page\": 1e-3,\n \"annotation_cost_per_page\": 3e-3,\n \"mode\": \"ocr\",\n \"supported_endpoints\": [\n \"/v1/ocr\"\n ],\n \"source\": \"https://mistral.ai/pricing#api-pricing\"\n },\n \"mistral/mistral-ocr-2505-completion\": {\n \"litellm_provider\": \"mistral\",\n \"ocr_cost_per_page\": 1e-3,\n \"annotation_cost_per_page\": 3e-3,\n \"mode\": \"ocr\",\n \"supported_endpoints\": [\n \"/v1/ocr\"\n ],\n \"source\": \"https://mistral.ai/pricing#api-pricing\"\n },\n \"mistral/magistral-medium-latest\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 40000,\n \"max_output_tokens\": 40000,\n \"max_tokens\": 40000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://mistral.ai/news/magistral\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/magistral-small-2506\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 40000,\n \"max_output_tokens\": 40000,\n \"max_tokens\": 40000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://mistral.ai/pricing#api-pricing\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/magistral-small-latest\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 40000,\n \"max_output_tokens\": 40000,\n \"max_tokens\": 40000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://mistral.ai/pricing#api-pricing\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-embed\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\"\n },\n \"mistral/mistral-large-2402\": {\n \"input_cost_per_token\": 4e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-large-2407\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-large-2411\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-large-latest\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-medium\": {\n \"input_cost_per_token\": 2.7e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.1e-06,\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-medium-2312\": {\n \"input_cost_per_token\": 2.7e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.1e-06,\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-medium-2505\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-medium-latest\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-small\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-small-latest\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/mistral-tiny\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/open-codestral-mamba\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"source\": \"https://mistral.ai/technology/\",\n \"supports_assistant_prefill\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/open-mistral-7b\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/open-mistral-nemo\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://mistral.ai/technology/\",\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/open-mistral-nemo-2407\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://mistral.ai/technology/\",\n \"supports_assistant_prefill\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/open-mixtral-8x22b\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 65336,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/open-mixtral-8x7b\": {\n \"input_cost_per_token\": 7e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"mistral/pixtral-12b-2409\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"mistral/pixtral-large-2411\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"mistral/pixtral-large-latest\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"mistral\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/kimi-k2-0711-preview\": {\n \"cache_read_input_token_cost\": 1.5e-07,\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing/chat#generation-model-kimi-k2\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"moonshot/kimi-latest\": {\n \"cache_read_input_token_cost\": 1.5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/kimi-latest-128k\": {\n \"cache_read_input_token_cost\": 1.5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/kimi-latest-32k\": {\n \"cache_read_input_token_cost\": 1.5e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/kimi-latest-8k\": {\n \"cache_read_input_token_cost\": 1.5e-07,\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/kimi-thinking-preview\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_vision\": true\n },\n \"moonshot/moonshot-v1-128k\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"moonshot/moonshot-v1-128k-0430\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"moonshot/moonshot-v1-128k-vision-preview\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/moonshot-v1-32k\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"moonshot/moonshot-v1-32k-0430\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"moonshot/moonshot-v1-32k-vision-preview\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/moonshot-v1-8k\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"moonshot/moonshot-v1-8k-0430\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"moonshot/moonshot-v1-8k-vision-preview\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"moonshot/moonshot-v1-auto\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"moonshot\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://platform.moonshot.ai/docs/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"morph/morph-v3-fast\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"morph\",\n \"max_input_tokens\": 16000,\n \"max_output_tokens\": 16000,\n \"max_tokens\": 16000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": false\n },\n \"morph/morph-v3-large\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"morph\",\n \"max_input_tokens\": 16000,\n \"max_output_tokens\": 16000,\n \"max_tokens\": 16000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.9e-06,\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": false\n },\n \"multimodalembedding\": {\n \"input_cost_per_character\": 2e-07,\n \"input_cost_per_image\": 0.0001,\n \"input_cost_per_token\": 8e-07,\n \"input_cost_per_video_per_second\": 0.0005,\n \"input_cost_per_video_per_second_above_15s_interval\": 0.002,\n \"input_cost_per_video_per_second_above_8s_interval\": 0.001,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models\",\n \"supported_endpoints\": [\n \"/v1/embeddings\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"video\"\n ]\n },\n \"multimodalembedding@001\": {\n \"input_cost_per_character\": 2e-07,\n \"input_cost_per_image\": 0.0001,\n \"input_cost_per_token\": 8e-07,\n \"input_cost_per_video_per_second\": 0.0005,\n \"input_cost_per_video_per_second_above_15s_interval\": 0.002,\n \"input_cost_per_video_per_second_above_8s_interval\": 0.001,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models\",\n \"supported_endpoints\": [\n \"/v1/embeddings\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\",\n \"video\"\n ]\n },\n \"nscale/Qwen/QwQ-32B\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"nscale\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/Qwen/Qwen2.5-Coder-32B-Instruct\": {\n \"input_cost_per_token\": 6e-08,\n \"litellm_provider\": \"nscale\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/Qwen/Qwen2.5-Coder-3B-Instruct\": {\n \"input_cost_per_token\": 1e-08,\n \"litellm_provider\": \"nscale\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-08,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/Qwen/Qwen2.5-Coder-7B-Instruct\": {\n \"input_cost_per_token\": 1e-08,\n \"litellm_provider\": \"nscale\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-08,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/black-forest-labs/FLUX.1-schnell\": {\n \"input_cost_per_pixel\": 1.3e-09,\n \"litellm_provider\": \"nscale\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#image-models\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"nscale/deepseek-ai/DeepSeek-R1-Distill-Llama-70B\": {\n \"input_cost_per_token\": 3.75e-07,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.75/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.75e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/deepseek-ai/DeepSeek-R1-Distill-Llama-8B\": {\n \"input_cost_per_token\": 2.5e-08,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.05/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-08,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B\": {\n \"input_cost_per_token\": 9e-08,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.18/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-08,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/deepseek-ai/DeepSeek-R1-Distill-Qwen-14B\": {\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.14/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-08,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.30/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/deepseek-ai/DeepSeek-R1-Distill-Qwen-7B\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.40/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/meta-llama/Llama-3.1-8B-Instruct\": {\n \"input_cost_per_token\": 3e-08,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.06/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-08,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/meta-llama/Llama-3.3-70B-Instruct\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $0.40/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/meta-llama/Llama-4-Scout-17B-16E-Instruct\": {\n \"input_cost_per_token\": 9e-08,\n \"litellm_provider\": \"nscale\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.9e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/mistralai/mixtral-8x22b-instruct-v0.1\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"nscale\",\n \"metadata\": {\n \"notes\": \"Pricing listed as $1.20/1M tokens total. Assumed 50/50 split for input/output.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#chat-models\"\n },\n \"nscale/stabilityai/stable-diffusion-xl-base-1.0\": {\n \"input_cost_per_pixel\": 3e-09,\n \"litellm_provider\": \"nscale\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0,\n \"source\": \"https://docs.nscale.com/docs/inference/serverless-models/current#image-models\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"o1\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o1-2024-12-17\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o1-mini\": {\n \"cache_read_input_token_cost\": 5.5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_vision\": true\n },\n \"o1-mini-2024-09-12\": {\n \"deprecation_date\": \"2025-10-27\",\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-05,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_vision\": true\n },\n \"o1-preview\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_vision\": true\n },\n \"o1-preview-2024-09-12\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_vision\": true\n },\n \"o1-pro\": {\n \"input_cost_per_token\": 0.00015,\n \"input_cost_per_token_batches\": 7.5e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 0.0006,\n \"output_cost_per_token_batches\": 0.0003,\n \"supported_endpoints\": [\n \"/v1/responses\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": false,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o1-pro-2025-03-19\": {\n \"input_cost_per_token\": 0.00015,\n \"input_cost_per_token_batches\": 7.5e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 0.0006,\n \"output_cost_per_token_batches\": 0.0003,\n \"supported_endpoints\": [\n \"/v1/responses\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": false,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o3\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"cache_read_input_token_cost_flex\": 2.5e-07,\n \"cache_read_input_token_cost_priority\": 8.75e-07,\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_flex\": 1e-06,\n \"input_cost_per_token_priority\": 3.5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"output_cost_per_token_flex\": 4e-06,\n \"output_cost_per_token_priority\": 1.4e-05,\n \"supported_endpoints\": [\n \"/v1/responses\",\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"o3-2025-04-16\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supported_endpoints\": [\n \"/v1/responses\",\n \"/v1/chat/completions\",\n \"/v1/completions\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"o3-deep-research\": {\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_token\": 1e-05,\n \"input_cost_per_token_batches\": 5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 4e-05,\n \"output_cost_per_token_batches\": 2e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o3-deep-research-2025-06-26\": {\n \"cache_read_input_token_cost\": 2.5e-06,\n \"input_cost_per_token\": 1e-05,\n \"input_cost_per_token_batches\": 5e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 4e-05,\n \"output_cost_per_token_batches\": 2e-05,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o3-mini\": {\n \"cache_read_input_token_cost\": 5.5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"o3-mini-2025-01-31\": {\n \"cache_read_input_token_cost\": 5.5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"o3-pro\": {\n \"input_cost_per_token\": 2e-05,\n \"input_cost_per_token_batches\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 8e-05,\n \"output_cost_per_token_batches\": 4e-05,\n \"supported_endpoints\": [\n \"/v1/responses\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o3-pro-2025-06-10\": {\n \"input_cost_per_token\": 2e-05,\n \"input_cost_per_token_batches\": 1e-05,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 8e-05,\n \"output_cost_per_token_batches\": 4e-05,\n \"supported_endpoints\": [\n \"/v1/responses\",\n \"/v1/batch\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o4-mini\": {\n \"cache_read_input_token_cost\": 2.75e-07,\n \"cache_read_input_token_cost_flex\": 1.375e-07,\n \"cache_read_input_token_cost_priority\": 5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"input_cost_per_token_flex\": 5.5e-07,\n \"input_cost_per_token_priority\": 2e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"output_cost_per_token_flex\": 2.2e-06,\n \"output_cost_per_token_priority\": 8e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"o4-mini-2025-04-16\": {\n \"cache_read_input_token_cost\": 2.75e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_service_tier\": true,\n \"supports_vision\": true\n },\n \"o4-mini-deep-research\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_batches\": 1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 8e-06,\n \"output_cost_per_token_batches\": 4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"o4-mini-deep-research-2025-06-26\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"input_cost_per_token_batches\": 1e-06,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"responses\",\n \"output_cost_per_token\": 8e-06,\n \"output_cost_per_token_batches\": 4e-06,\n \"supported_endpoints\": [\n \"/v1/chat/completions\",\n \"/v1/batch\",\n \"/v1/responses\"\n ],\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_function_calling\": true,\n \"supports_native_streaming\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"oci/meta.llama-3.1-405b-instruct\": {\n \"input_cost_per_token\": 1.068e-05,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.068e-05,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/meta.llama-3.2-90b-vision-instruct\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/meta.llama-3.3-70b-instruct\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/meta.llama-4-maverick-17b-128e-instruct-fp8\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 512000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 512000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/meta.llama-4-scout-17b-16e-instruct\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 192000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 192000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/xai.grok-3\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/xai.grok-3-fast\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-05,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/xai.grok-3-mini\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/xai.grok-3-mini-fast\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/xai.grok-4\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/cohere.command-latest\": {\n \"input_cost_per_token\": 1.56e-06,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.56e-06,\n \"source\": \"https://www.oracle.com/cloud/ai/generative-ai/pricing/\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/cohere.command-a-03-2025\": {\n \"input_cost_per_token\": 1.56e-06,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.56e-06,\n \"source\": \"https://www.oracle.com/cloud/ai/generative-ai/pricing/\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"oci/cohere.command-plus-latest\": {\n \"input_cost_per_token\": 1.56e-06,\n \"litellm_provider\": \"oci\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.56e-06,\n \"source\": \"https://www.oracle.com/cloud/ai/generative-ai/pricing/\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false\n },\n \"ollama/codegeex4\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": false\n },\n \"ollama/codegemma\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/codellama\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/deepseek-coder-v2-base\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/deepseek-coder-v2-instruct\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/deepseek-coder-v2-lite-base\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/deepseek-coder-v2-lite-instruct\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/deepseek-v3.1:671b-cloud\" : {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"max_tokens\": 163840,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/gpt-oss:120b-cloud\" : {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/gpt-oss:20b-cloud\" : {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/internlm2_5-20b-chat\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/llama2\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/llama2-uncensored\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/llama2:13b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/llama2:70b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/llama2:7b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/llama3\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/llama3.1\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/llama3:70b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/llama3:8b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/mistral\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/mistral-7B-Instruct-v0.1\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/mistral-7B-Instruct-v0.2\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/mistral-large-instruct-2407\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/mixtral-8x22B-Instruct-v0.1\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/mixtral-8x7B-Instruct-v0.1\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/orca-mini\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"ollama/qwen3-coder:480b-cloud\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_function_calling\": true\n },\n \"ollama/vicuna\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"ollama\",\n \"max_input_tokens\": 2048,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"omni-moderation-2024-09-26\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 0,\n \"max_tokens\": 32768,\n \"mode\": \"moderation\",\n \"output_cost_per_token\": 0.0\n },\n \"omni-moderation-latest\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 0,\n \"max_tokens\": 32768,\n \"mode\": \"moderation\",\n \"output_cost_per_token\": 0.0\n },\n \"omni-moderation-latest-intents\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 0,\n \"max_tokens\": 32768,\n \"mode\": \"moderation\",\n \"output_cost_per_token\": 0.0\n },\n \"openai.gpt-oss-120b-1:0\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"openai.gpt-oss-20b-1:0\": {\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/anthropic/claude-2\": {\n \"input_cost_per_token\": 1.102e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_output_tokens\": 8191,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.268e-05,\n \"supports_tool_choice\": true\n },\n \"openrouter/anthropic/claude-3-5-haiku\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/anthropic/claude-3-5-haiku-20241022\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"tool_use_system_prompt_tokens\": 264\n },\n \"openrouter/anthropic/claude-3-haiku\": {\n \"input_cost_per_image\": 0.0004,\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/anthropic/claude-3-haiku-20240307\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 264\n },\n \"openrouter/anthropic/claude-3-opus\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 395\n },\n \"openrouter/anthropic/claude-3-sonnet\": {\n \"input_cost_per_image\": 0.0048,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/anthropic/claude-3.5-sonnet\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-3.5-sonnet:beta\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-3.7-sonnet\": {\n \"input_cost_per_image\": 0.0048,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-3.7-sonnet:beta\": {\n \"input_cost_per_image\": 0.0048,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-instant-v1\": {\n \"input_cost_per_token\": 1.63e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_output_tokens\": 8191,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.51e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/anthropic/claude-opus-4\": {\n \"input_cost_per_image\": 0.0048,\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-opus-4.1\": {\n \"input_cost_per_image\": 0.0048,\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_creation_input_token_cost_above_1hr\": 3e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-sonnet-4\": {\n \"input_cost_per_image\": 0.0048,\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-sonnet-4.5\": {\n \"input_cost_per_image\": 0.0048,\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 1000000,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"openrouter/anthropic/claude-haiku-4.5\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 200000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"openrouter/bytedance/ui-tars-1.5-7b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://openrouter.ai/api/v1/models/bytedance/ui-tars-1.5-7b\",\n \"supports_tool_choice\": true\n },\n \"openrouter/cognitivecomputations/dolphin-mixtral-8x7b\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 32769,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/cohere/command-r-plus\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_tool_choice\": true\n },\n \"openrouter/databricks/dbrx-instruct\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/deepseek/deepseek-chat\": {\n \"input_cost_per_token\": 1.4e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/deepseek/deepseek-chat-v3-0324\": {\n \"input_cost_per_token\": 1.4e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/deepseek/deepseek-chat-v3.1\": {\n \"input_cost_per_token\": 2e-07,\n \"input_cost_per_token_cache_hit\": 2e-08,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 163840,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/deepseek/deepseek-coder\": {\n \"input_cost_per_token\": 1.4e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 66000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07,\n \"supports_prompt_caching\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/deepseek/deepseek-r1\": {\n \"input_cost_per_token\": 5.5e-07,\n \"input_cost_per_token_cache_hit\": 1.4e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 65336,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.19e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/deepseek/deepseek-r1-0528\": {\n \"input_cost_per_token\": 5e-07,\n \"input_cost_per_token_cache_hit\": 1.4e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 65336,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.15e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/fireworks/firellava-13b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/google/gemini-2.0-flash-001\": {\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/google/gemini-2.5-flash\": {\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-06,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/google/gemini-2.5-pro\": {\n \"input_cost_per_audio_token\": 7e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_audio_length_hours\": 8.4,\n \"max_audio_per_prompt\": 1,\n \"max_images_per_prompt\": 3000,\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_pdf_size_mb\": 30,\n \"max_tokens\": 8192,\n \"max_video_length\": 1,\n \"max_videos_per_prompt\": 10,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_audio_output\": true,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/google/gemini-pro-1.5\": {\n \"input_cost_per_image\": 0.00265,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/google/gemini-pro-vision\": {\n \"input_cost_per_image\": 0.0025,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 45875,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.75e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/google/palm-2-chat-bison\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 25804,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/google/palm-2-codechat-bison\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 20070,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/gryphe/mythomax-l2-13b\": {\n \"input_cost_per_token\": 1.875e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.875e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/jondurbin/airoboros-l2-70b-2.1\": {\n \"input_cost_per_token\": 1.3875e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.3875e-05,\n \"supports_tool_choice\": true\n },\n \"openrouter/mancer/weaver\": {\n \"input_cost_per_token\": 5.625e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.625e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/meta-llama/codellama-34b-instruct\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/meta-llama/llama-2-13b-chat\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/meta-llama/llama-2-70b-chat\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/meta-llama/llama-3-70b-instruct\": {\n \"input_cost_per_token\": 5.9e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.9e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/meta-llama/llama-3-70b-instruct:nitro\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/meta-llama/llama-3-8b-instruct:extended\": {\n \"input_cost_per_token\": 2.25e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.25e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/meta-llama/llama-3-8b-instruct:free\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_tool_choice\": true\n },\n \"openrouter/microsoft/wizardlm-2-8x22b:nitro\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/mistralai/mistral-7b-instruct\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.3e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/mistralai/mistral-7b-instruct:free\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"supports_tool_choice\": true\n },\n \"openrouter/mistralai/mistral-large\": {\n \"input_cost_per_token\": 8e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-05,\n \"supports_tool_choice\": true\n },\n \"openrouter/mistralai/mistral-small-3.1-24b-instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/mistralai/mistral-small-3.2-24b-instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/mistralai/mixtral-8x22b-instruct\": {\n \"input_cost_per_token\": 6.5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.5e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/nousresearch/nous-hermes-llama2-13b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-3.5-turbo\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 4095,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-3.5-turbo-16k\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 16383,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-4\": {\n \"input_cost_per_token\": 3e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-4-vision-preview\": {\n \"input_cost_per_image\": 0.01445,\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 130000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4.1\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4.1-2025-04-14\": {\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4.1-mini\": {\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4.1-mini-2025-04-14\": {\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4.1-nano\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4.1-nano-2025-04-14\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4o\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-4o-2024-05-13\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/gpt-5-chat\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-5-codex\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-5\": {\n \"cache_read_input_token_cost\": 1.25e-07,\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-5-mini\": {\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-5-nano\": {\n \"cache_read_input_token_cost\": 5e-09,\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 272000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\"\n ],\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-oss-120b\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"source\": \"https://openrouter.ai/openai/gpt-oss-120b\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/gpt-oss-20b\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"source\": \"https://openrouter.ai/openai/gpt-oss-20b\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"openrouter/openai/o1\": {\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 100000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"openrouter/openai/o1-mini\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"openrouter/openai/o1-mini-2024-09-12\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"openrouter/openai/o1-preview\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"openrouter/openai/o1-preview-2024-09-12\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"openrouter/openai/o3-mini\": {\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"openrouter/openai/o3-mini-high\": {\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"openrouter/pygmalionai/mythalion-13b\": {\n \"input_cost_per_token\": 1.875e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.875e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/qwen/qwen-2.5-coder-32b-instruct\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 33792,\n \"max_output_tokens\": 33792,\n \"max_tokens\": 33792,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/qwen/qwen-vl-plus\": {\n \"input_cost_per_token\": 2.1e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.3e-07,\n \"supports_tool_choice\": true\n },\n \"openrouter/qwen/qwen3-coder\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 1000000,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://openrouter.ai/qwen/qwen3-coder\",\n \"supports_tool_choice\": true\n },\n \"openrouter/switchpoint/router\": {\n \"input_cost_per_token\": 8.5e-07,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.4e-06,\n \"source\": \"https://openrouter.ai/switchpoint/router\",\n \"supports_tool_choice\": true\n },\n \"openrouter/undi95/remm-slerp-l2-13b\": {\n \"input_cost_per_token\": 1.875e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_tokens\": 6144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.875e-06,\n \"supports_tool_choice\": true\n },\n \"openrouter/x-ai/grok-4\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"source\": \"https://openrouter.ai/x-ai/grok-4\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"openrouter/x-ai/grok-4-fast:free\": {\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"openrouter\",\n \"max_input_tokens\": 2000000,\n \"max_output_tokens\": 30000,\n \"max_tokens\": 2000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"source\": \"https://openrouter.ai/x-ai/grok-4-fast:free\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": false\n },\n \"ovhcloud/DeepSeek-R1-Distill-Llama-70B\": {\n \"input_cost_per_token\": 6.7e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131000,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.7e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/deepseek-r1-distill-llama-70b\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"ovhcloud/Llama-3.1-8B-Instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131000,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/llama-3-1-8b-instruct\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"ovhcloud/Meta-Llama-3_1-70B-Instruct\": {\n \"input_cost_per_token\": 6.7e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131000,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.7e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/meta-llama-3-1-70b-instruct\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": false\n },\n \"ovhcloud/Meta-Llama-3_3-70B-Instruct\": {\n \"input_cost_per_token\": 6.7e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131000,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.7e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/meta-llama-3-3-70b-instruct\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"ovhcloud/Mistral-7B-Instruct-v0.3\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 127000,\n \"max_output_tokens\": 127000,\n \"max_tokens\": 127000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/mistral-7b-instruct-v0-3\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"ovhcloud/Mistral-Nemo-Instruct-2407\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 118000,\n \"max_output_tokens\": 118000,\n \"max_tokens\": 118000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.3e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/mistral-nemo-instruct-2407\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"ovhcloud/Mistral-Small-3.2-24B-Instruct-2506\": {\n \"input_cost_per_token\": 9e-08,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/mistral-small-3-2-24b-instruct-2506\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"ovhcloud/Mixtral-8x7B-Instruct-v0.1\": {\n \"input_cost_per_token\": 6.3e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.3e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/mixtral-8x7b-instruct-v0-1\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"ovhcloud/Qwen2.5-Coder-32B-Instruct\": {\n \"input_cost_per_token\": 8.7e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.7e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/qwen2-5-coder-32b-instruct\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"ovhcloud/Qwen2.5-VL-72B-Instruct\": {\n \"input_cost_per_token\": 9.1e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.1e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/qwen2-5-vl-72b-instruct\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"ovhcloud/Qwen3-32B\": {\n \"input_cost_per_token\": 8e-08,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.3e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/qwen3-32b\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"ovhcloud/gpt-oss-120b\": {\n \"input_cost_per_token\": 8e-08,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131000,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/gpt-oss-120b\",\n \"supports_function_calling\": false,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"ovhcloud/gpt-oss-20b\": {\n \"input_cost_per_token\": 4e-08,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131000,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/gpt-oss-20b\",\n \"supports_function_calling\": false,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"ovhcloud/llava-v1.6-mistral-7b-hf\": {\n \"input_cost_per_token\": 2.9e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.9e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/llava-next-mistral-7b\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"ovhcloud/mamba-codestral-7B-v0.1\": {\n \"input_cost_per_token\": 1.9e-07,\n \"litellm_provider\": \"ovhcloud\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.9e-07,\n \"source\": \"https://endpoints.ai.cloud.ovh.net/models/mamba-codestral-7b-v0-1\",\n \"supports_function_calling\": false,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": false\n },\n \"palm/chat-bison\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"palm\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"palm/chat-bison-001\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"palm\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"palm/text-bison\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"palm\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"palm/text-bison-001\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"palm\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"palm/text-bison-safety-off\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"palm\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"palm/text-bison-safety-recitation-off\": {\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"palm\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"parallel_ai/search\": {\n \"input_cost_per_query\": 0.004,\n \"litellm_provider\": \"parallel_ai\",\n \"mode\": \"search\"\n },\n \"parallel_ai/search-pro\": {\n \"input_cost_per_query\": 0.009,\n \"litellm_provider\": \"parallel_ai\",\n \"mode\": \"search\"\n },\n \"perplexity/codellama-34b-instruct\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.4e-06\n },\n \"perplexity/codellama-70b-instruct\": {\n \"input_cost_per_token\": 7e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-06\n },\n \"perplexity/llama-2-70b-chat\": {\n \"input_cost_per_token\": 7e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-06\n },\n \"perplexity/llama-3.1-70b-instruct\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"perplexity/llama-3.1-8b-instruct\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07\n },\n \"perplexity/llama-3.1-sonar-huge-128k-online\": {\n \"deprecation_date\": \"2025-02-22\",\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 127072,\n \"max_output_tokens\": 127072,\n \"max_tokens\": 127072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06\n },\n \"perplexity/llama-3.1-sonar-large-128k-chat\": {\n \"deprecation_date\": \"2025-02-22\",\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"perplexity/llama-3.1-sonar-large-128k-online\": {\n \"deprecation_date\": \"2025-02-22\",\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 127072,\n \"max_output_tokens\": 127072,\n \"max_tokens\": 127072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"perplexity/llama-3.1-sonar-small-128k-chat\": {\n \"deprecation_date\": \"2025-02-22\",\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07\n },\n \"perplexity/llama-3.1-sonar-small-128k-online\": {\n \"deprecation_date\": \"2025-02-22\",\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 127072,\n \"max_output_tokens\": 127072,\n \"max_tokens\": 127072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07\n },\n \"perplexity/mistral-7b-instruct\": {\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07\n },\n \"perplexity/mixtral-8x7b-instruct\": {\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07\n },\n \"perplexity/pplx-70b-chat\": {\n \"input_cost_per_token\": 7e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-06\n },\n \"perplexity/pplx-70b-online\": {\n \"input_cost_per_request\": 0.005,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-06\n },\n \"perplexity/pplx-7b-chat\": {\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07\n },\n \"perplexity/pplx-7b-online\": {\n \"input_cost_per_request\": 0.005,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07\n },\n \"perplexity/sonar\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.012,\n \"search_context_size_low\": 0.005,\n \"search_context_size_medium\": 0.008\n },\n \"supports_web_search\": true\n },\n \"perplexity/sonar-deep-research\": {\n \"citation_cost_per_token\": 2e-06,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_reasoning_token\": 3e-06,\n \"output_cost_per_token\": 8e-06,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.005,\n \"search_context_size_low\": 0.005,\n \"search_context_size_medium\": 0.005\n },\n \"supports_reasoning\": true,\n \"supports_web_search\": true\n },\n \"perplexity/sonar-medium-chat\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-06\n },\n \"perplexity/sonar-medium-online\": {\n \"input_cost_per_request\": 0.005,\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 12000,\n \"max_output_tokens\": 12000,\n \"max_tokens\": 12000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-06\n },\n \"perplexity/sonar-pro\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 8000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.014,\n \"search_context_size_low\": 0.006,\n \"search_context_size_medium\": 0.01\n },\n \"supports_web_search\": true\n },\n \"perplexity/sonar-reasoning\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.014,\n \"search_context_size_low\": 0.005,\n \"search_context_size_medium\": 0.008\n },\n \"supports_reasoning\": true,\n \"supports_web_search\": true\n },\n \"perplexity/sonar-reasoning-pro\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.014,\n \"search_context_size_low\": 0.006,\n \"search_context_size_medium\": 0.01\n },\n \"supports_reasoning\": true,\n \"supports_web_search\": true\n },\n \"perplexity/sonar-small-chat\": {\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07\n },\n \"perplexity/sonar-small-online\": {\n \"input_cost_per_request\": 0.005,\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"perplexity\",\n \"max_input_tokens\": 12000,\n \"max_output_tokens\": 12000,\n \"max_tokens\": 12000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07\n },\n \"qwen.qwen3-coder-480b-a35b-v1:0\": {\n \"input_cost_per_token\": 2.2e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 262000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-06,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"qwen.qwen3-235b-a22b-2507-v1:0\": {\n \"input_cost_per_token\": 2.2e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.8e-07,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"qwen.qwen3-coder-30b-a3b-v1:0\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.0e-07,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"qwen.qwen3-32b-v1:0\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.0e-07,\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"recraft/recraftv2\": {\n \"litellm_provider\": \"recraft\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.022,\n \"source\": \"https://www.recraft.ai/docs#pricing\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"recraft/recraftv3\": {\n \"litellm_provider\": \"recraft\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://www.recraft.ai/docs#pricing\",\n \"supported_endpoints\": [\n \"/v1/images/generations\"\n ]\n },\n \"replicate/meta/llama-2-13b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-2-13b-chat\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-2-70b\": {\n \"input_cost_per_token\": 6.5e-07,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.75e-06,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-2-70b-chat\": {\n \"input_cost_per_token\": 6.5e-07,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.75e-06,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-2-7b\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-2-7b-chat\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-3-70b\": {\n \"input_cost_per_token\": 6.5e-07,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.75e-06,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-3-70b-instruct\": {\n \"input_cost_per_token\": 6.5e-07,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.75e-06,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-3-8b\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 8086,\n \"max_output_tokens\": 8086,\n \"max_tokens\": 8086,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/meta/llama-3-8b-instruct\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 8086,\n \"max_output_tokens\": 8086,\n \"max_tokens\": 8086,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/mistralai/mistral-7b-instruct-v0.2\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/mistralai/mistral-7b-v0.1\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-07,\n \"supports_tool_choice\": true\n },\n \"replicate/mistralai/mixtral-8x7b-instruct-v0.1\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"replicate\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06,\n \"supports_tool_choice\": true\n },\n \"rerank-english-v2.0\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"rerank-english-v3.0\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"rerank-multilingual-v2.0\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"rerank-multilingual-v3.0\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"rerank-v3.5\": {\n \"input_cost_per_query\": 0.002,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"cohere\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_query_tokens\": 2048,\n \"max_tokens\": 4096,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"nvidia_nim/nvidia/nv-rerankqa-mistral-4b-v3\": {\n \"input_cost_per_query\": 0.0,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"nvidia_nim\",\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"nvidia_nim/nvidia/llama-3_2-nv-rerankqa-1b-v2\": {\n \"input_cost_per_query\": 0.0,\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"nvidia_nim\",\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"sagemaker/meta-textgeneration-llama-2-13b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"sagemaker\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"sagemaker/meta-textgeneration-llama-2-13b-f\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"sagemaker\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"sagemaker/meta-textgeneration-llama-2-70b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"sagemaker\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"sagemaker/meta-textgeneration-llama-2-70b-b-f\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"sagemaker\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"sagemaker/meta-textgeneration-llama-2-7b\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"sagemaker\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0\n },\n \"sagemaker/meta-textgeneration-llama-2-7b-f\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"sagemaker\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"sambanova/DeepSeek-R1\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-06,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n \"sambanova/DeepSeek-R1-Distill-Llama-70B\": {\n \"input_cost_per_token\": 7e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.4e-06,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n \"sambanova/DeepSeek-V3-0324\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.5e-06,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"sambanova/Llama-4-Maverick-17B-128E-Instruct\": {\n \"input_cost_per_token\": 6.3e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"metadata\": {\n \"notes\": \"For vision models, images are converted to 6432 input tokens and are billed at that amount\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-06,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"sambanova/Llama-4-Scout-17B-16E-Instruct\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"metadata\": {\n \"notes\": \"For vision models, images are converted to 6432 input tokens and are billed at that amount\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"sambanova/Meta-Llama-3.1-405B-Instruct\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"sambanova/Meta-Llama-3.1-8B-Instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"sambanova/Meta-Llama-3.2-1B-Instruct\": {\n \"input_cost_per_token\": 4e-08,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-08,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n \"sambanova/Meta-Llama-3.2-3B-Instruct\": {\n \"input_cost_per_token\": 8e-08,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-07,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n \"sambanova/Meta-Llama-3.3-70B-Instruct\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"sambanova/Meta-Llama-Guard-3-8B\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n \"sambanova/QwQ-32B\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 16384,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n \"sambanova/Qwen2-Audio-7B-Instruct\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0001,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_audio_input\": true\n },\n \"sambanova/Qwen3-32B\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"sambanova\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"sambanova/DeepSeek-V3.1\": {\n \"max_tokens\": 32768,\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"input_cost_per_token\": 3e-06,\n \"output_cost_per_token\": 4.5e-06,\n \"litellm_provider\": \"sambanova\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_reasoning\": true,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n \"sambanova/gpt-oss-120b\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 3e-06,\n \"output_cost_per_token\": 4.5e-06,\n \"litellm_provider\": \"sambanova\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_reasoning\": true,\n \"source\": \"https://cloud.sambanova.ai/plans/pricing\"\n },\n\n \"snowflake/claude-3-5-sonnet\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 18000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 18000,\n \"mode\": \"chat\",\n \"supports_computer_use\": true\n },\n \"snowflake/deepseek-r1\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"supports_reasoning\": true\n },\n \"snowflake/gemma-7b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8000,\n \"mode\": \"chat\"\n },\n \"snowflake/jamba-1.5-large\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 256000,\n \"mode\": \"chat\"\n },\n \"snowflake/jamba-1.5-mini\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 256000,\n \"mode\": \"chat\"\n },\n \"snowflake/jamba-instruct\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 256000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama2-70b-chat\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 4096,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3-70b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3-8b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3.1-405b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3.1-70b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3.1-8b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3.2-1b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3.2-3b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\"\n },\n \"snowflake/llama3.3-70b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\"\n },\n \"snowflake/mistral-7b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32000,\n \"mode\": \"chat\"\n },\n \"snowflake/mistral-large\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32000,\n \"mode\": \"chat\"\n },\n \"snowflake/mistral-large2\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\"\n },\n \"snowflake/mixtral-8x7b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32000,\n \"mode\": \"chat\"\n },\n \"snowflake/reka-core\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 32000,\n \"mode\": \"chat\"\n },\n \"snowflake/reka-flash\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 100000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 100000,\n \"mode\": \"chat\"\n },\n \"snowflake/snowflake-arctic\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 4096,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 4096,\n \"mode\": \"chat\"\n },\n \"snowflake/snowflake-llama-3.1-405b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8000,\n \"mode\": \"chat\"\n },\n \"snowflake/snowflake-llama-3.3-70b\": {\n \"litellm_provider\": \"snowflake\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8000,\n \"mode\": \"chat\"\n },\n \"stability.sd3-5-large-v1:0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.08\n },\n \"stability.sd3-large-v1:0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.08\n },\n \"stability.stable-image-core-v1:0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04\n },\n \"stability.stable-image-core-v1:1\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04\n },\n \"stability.stable-image-ultra-v1:0\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.14\n },\n \"stability.stable-image-ultra-v1:1\": {\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 77,\n \"max_tokens\": 77,\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.14\n },\n \"standard/1024-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 3.81469e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"standard/1024-x-1792/dall-e-3\": {\n \"input_cost_per_pixel\": 4.359e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"standard/1792-x-1024/dall-e-3\": {\n \"input_cost_per_pixel\": 4.359e-08,\n \"litellm_provider\": \"openai\",\n \"mode\": \"image_generation\",\n \"output_cost_per_pixel\": 0.0\n },\n \"tavily/search\": {\n \"input_cost_per_query\": 0.008,\n \"litellm_provider\": \"tavily\",\n \"mode\": \"search\"\n },\n \"tavily/search-advanced\": {\n \"input_cost_per_query\": 0.016,\n \"litellm_provider\": \"tavily\",\n \"mode\": \"search\"\n },\n \"text-bison\": {\n \"input_cost_per_character\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-text-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"text-bison32k\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-text-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"text-bison32k@002\": {\n \"input_cost_per_character\": 2.5e-07,\n \"input_cost_per_token\": 1.25e-07,\n \"litellm_provider\": \"vertex_ai-text-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"output_cost_per_token\": 1.25e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"text-bison@001\": {\n \"input_cost_per_character\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-text-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"text-bison@002\": {\n \"input_cost_per_character\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-text-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_character\": 5e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"text-completion-codestral/codestral-2405\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"text-completion-codestral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://docs.mistral.ai/capabilities/code_generation/\"\n },\n \"text-completion-codestral/codestral-latest\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"text-completion-codestral\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://docs.mistral.ai/capabilities/code_generation/\"\n },\n \"text-embedding-004\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models\"\n },\n \"text-embedding-005\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models\"\n },\n \"text-embedding-3-large\": {\n \"input_cost_per_token\": 1.3e-07,\n \"input_cost_per_token_batches\": 6.5e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_cost_per_token_batches\": 0.0,\n \"output_vector_size\": 3072\n },\n \"text-embedding-3-small\": {\n \"input_cost_per_token\": 2e-08,\n \"input_cost_per_token_batches\": 1e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_cost_per_token_batches\": 0.0,\n \"output_vector_size\": 1536\n },\n \"text-embedding-ada-002\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 1536\n },\n \"text-embedding-ada-002-v2\": {\n \"input_cost_per_token\": 1e-07,\n \"input_cost_per_token_batches\": 5e-08,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_cost_per_token_batches\": 0.0\n },\n \"text-embedding-large-exp-03-07\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 3072,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models\"\n },\n \"text-embedding-preview-0409\": {\n \"input_cost_per_token\": 6.25e-09,\n \"input_cost_per_token_batch_requests\": 5e-09,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"text-moderation-007\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 0,\n \"max_tokens\": 32768,\n \"mode\": \"moderation\",\n \"output_cost_per_token\": 0.0\n },\n \"text-moderation-latest\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 0,\n \"max_tokens\": 32768,\n \"mode\": \"moderation\",\n \"output_cost_per_token\": 0.0\n },\n \"text-moderation-stable\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"openai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 0,\n \"max_tokens\": 32768,\n \"mode\": \"moderation\",\n \"output_cost_per_token\": 0.0\n },\n \"text-multilingual-embedding-002\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 2048,\n \"max_tokens\": 2048,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models\"\n },\n \"text-multilingual-embedding-preview-0409\": {\n \"input_cost_per_token\": 6.25e-09,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"text-unicorn\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"vertex_ai-text-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2.8e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"text-unicorn@001\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"vertex_ai-text-models\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"completion\",\n \"output_cost_per_token\": 2.8e-05,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"textembedding-gecko\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"textembedding-gecko-multilingual\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"textembedding-gecko-multilingual@001\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"textembedding-gecko@001\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"textembedding-gecko@003\": {\n \"input_cost_per_character\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vertex_ai-embedding-models\",\n \"max_input_tokens\": 3072,\n \"max_tokens\": 3072,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0,\n \"output_vector_size\": 768,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#foundation_models\"\n },\n \"together-ai-21.1b-41b\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-07\n },\n \"together-ai-4.1b-8b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07\n },\n \"together-ai-41.1b-80b\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07\n },\n \"together-ai-8.1b-21b\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_tokens\": 1000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07\n },\n \"together-ai-81.1b-110b\": {\n \"input_cost_per_token\": 1.8e-06,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-06\n },\n \"together-ai-embedding-151m-to-350m\": {\n \"input_cost_per_token\": 1.6e-08,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"together-ai-embedding-up-to-150m\": {\n \"input_cost_per_token\": 8e-09,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"together_ai/baai/bge-base-en-v1.5\": {\n \"input_cost_per_token\": 8e-09,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 768\n },\n \"together_ai/BAAI/bge-base-en-v1.5\": {\n \"input_cost_per_token\": 8e-09,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 512,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0,\n \"output_vector_size\": 768\n },\n \"together-ai-up-to-4b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07\n },\n \"together_ai/Qwen/Qwen2.5-72B-Instruct-Turbo\": {\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/Qwen/Qwen2.5-7B-Instruct-Turbo\": {\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/Qwen/Qwen3-235B-A22B-Instruct-2507-tput\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 262000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"source\": \"https://www.together.ai/models/qwen3-235b-a22b-instruct-2507-fp8\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/Qwen/Qwen3-235B-A22B-Thinking-2507\": {\n \"input_cost_per_token\": 6.5e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://www.together.ai/models/qwen3-235b-a22b-thinking-2507\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/Qwen/Qwen3-235B-A22B-fp8-tput\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 40000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://www.together.ai/models/qwen3-235b-a22b-fp8-tput\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_tool_choice\": false\n },\n \"together_ai/Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"source\": \"https://www.together.ai/models/qwen3-coder-480b-a35b-instruct\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/deepseek-ai/DeepSeek-R1\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 20480,\n \"max_tokens\": 20480,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/deepseek-ai/DeepSeek-R1-0528-tput\": {\n \"input_cost_per_token\": 5.5e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.19e-06,\n \"source\": \"https://www.together.ai/models/deepseek-r1-0528-throughput\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/deepseek-ai/DeepSeek-V3\": {\n \"input_cost_per_token\": 1.25e-06,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/deepseek-ai/DeepSeek-V3.1\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.7e-06,\n \"source\": \"https://www.together.ai/models/deepseek-v3-1\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Llama-3.2-3B-Instruct-Turbo\": {\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo\": {\n \"input_cost_per_token\": 8.8e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.8e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free\": {\n \"input_cost_per_token\": 0,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8\": {\n \"input_cost_per_token\": 2.7e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.5e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Llama-4-Scout-17B-16E-Instruct\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.9e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo\": {\n \"input_cost_per_token\": 3.5e-06,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-06,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo\": {\n \"input_cost_per_token\": 8.8e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8.8e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.8e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/mistralai/Mistral-7B-Instruct-v0.1\": {\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/mistralai/Mistral-Small-24B-Instruct-2501\": {\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/mistralai/Mixtral-8x7B-Instruct-v0.1\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/moonshotai/Kimi-K2-Instruct\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://www.together.ai/models/kimi-k2-instruct\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/openai/gpt-oss-120b\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://www.together.ai/models/gpt-oss-120b\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/openai/gpt-oss-20b\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07,\n \"source\": \"https://www.together.ai/models/gpt-oss-20b\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/togethercomputer/CodeLlama-34b-Instruct\": {\n \"litellm_provider\": \"together_ai\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/zai-org/GLM-4.5-Air-FP8\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-06,\n \"source\": \"https://www.together.ai/models/glm-4-5-air\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/moonshotai/Kimi-K2-Instruct-0905\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"source\": \"https://www.together.ai/models/kimi-k2-0905\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/Qwen/Qwen3-Next-80B-A3B-Instruct\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://www.together.ai/models/qwen3-next-80b-a3b-instruct\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"together_ai/Qwen/Qwen3-Next-80B-A3B-Thinking\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"together_ai\",\n \"max_input_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://www.together.ai/models/qwen3-next-80b-a3b-thinking\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"tts-1\": {\n \"input_cost_per_character\": 1.5e-05,\n \"litellm_provider\": \"openai\",\n \"mode\": \"audio_speech\",\n \"supported_endpoints\": [\n \"/v1/audio/speech\"\n ]\n },\n \"tts-1-hd\": {\n \"input_cost_per_character\": 3e-05,\n \"litellm_provider\": \"openai\",\n \"mode\": \"audio_speech\",\n \"supported_endpoints\": [\n \"/v1/audio/speech\"\n ]\n },\n \"us.amazon.nova-lite-v1:0\": {\n \"input_cost_per_token\": 6e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-07,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"us.amazon.nova-micro-v1:0\": {\n \"input_cost_per_token\": 3.5e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.4e-07,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true\n },\n \"us.amazon.nova-premier-v1:0\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": false,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"us.amazon.nova-pro-v1:0\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 10000,\n \"max_tokens\": 10000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.2e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_vision\": true\n },\n \"us.anthropic.claude-3-5-haiku-20241022-v1:0\": {\n \"cache_creation_input_token_cost\": 1e-06,\n \"cache_read_input_token_cost\": 8e-08,\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"us.anthropic.claude-haiku-4-5-20251001-v1:0\": {\n \"cache_creation_input_token_cost\": 1.375e-06,\n \"cache_read_input_token_cost\": 1.1e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.5e-06,\n \"source\": \"https://aws.amazon.com/about-aws/whats-new/2025/10/claude-4-5-haiku-anthropic-amazon-bedrock\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"us.anthropic.claude-3-5-sonnet-20240620-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"us.anthropic.claude-3-5-sonnet-20241022-v2:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"us.anthropic.claude-3-7-sonnet-20250219-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"us.anthropic.claude-3-haiku-20240307-v1:0\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"us.anthropic.claude-3-opus-20240229-v1:0\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"us.anthropic.claude-3-sonnet-20240229-v1:0\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"us.anthropic.claude-opus-4-1-20250805-v1:0\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"us.anthropic.claude-sonnet-4-5-20250929-v1:0\": {\n \"cache_creation_input_token_cost\": 4.125e-06,\n \"cache_read_input_token_cost\": 3.3e-07,\n \"input_cost_per_token\": 3.3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6.6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.475e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 8.25e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6.6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.65e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"au.anthropic.claude-haiku-4-5-20251001-v1:0\": {\n \"cache_creation_input_token_cost\": 1.375e-06,\n \"cache_read_input_token_cost\": 1.1e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 346\n },\n \"us.anthropic.claude-opus-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"us.anthropic.claude-sonnet-4-20250514-v1:0\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"us.deepseek.r1-v1:0\": {\n \"input_cost_per_token\": 1.35e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.4e-06,\n \"supports_function_calling\": false,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama3-1-405b-instruct-v1:0\": {\n \"input_cost_per_token\": 5.32e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama3-1-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 9.9e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama3-1-8b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.2e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.2e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama3-2-11b-instruct-v1:0\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.5e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"us.meta.llama3-2-1b-instruct-v1:0\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama3-2-3b-instruct-v1:0\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama3-2-90b-instruct-v1:0\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"bedrock\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false,\n \"supports_vision\": true\n },\n \"us.meta.llama3-3-70b-instruct-v1:0\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama4-maverick-17b-instruct-v1:0\": {\n \"input_cost_per_token\": 2.4e-07,\n \"input_cost_per_token_batches\": 1.2e-07,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.7e-07,\n \"output_cost_per_token_batches\": 4.85e-07,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.meta.llama4-scout-17b-instruct-v1:0\": {\n \"input_cost_per_token\": 1.7e-07,\n \"input_cost_per_token_batches\": 8.5e-08,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6.6e-07,\n \"output_cost_per_token_batches\": 3.3e-07,\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"us.mistral.pixtral-large-2502-v1:0\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"bedrock_converse\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": false\n },\n \"v0/v0-1.0-md\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"v0\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"v0/v0-1.5-lg\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"v0\",\n \"max_input_tokens\": 512000,\n \"max_output_tokens\": 512000,\n \"max_tokens\": 512000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"v0/v0-1.5-md\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"v0\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vercel_ai_gateway/alibaba/qwen-3-14b\": {\n \"input_cost_per_token\": 8e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 40960,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-07\n },\n \"vercel_ai_gateway/glm-4.6\": {\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"cache_read_input_token_cost\": 1.1e-07,\n \"input_cost_per_token\": 6e-07,\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 200000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.2e-06\n },\n \"vercel_ai_gateway/alibaba/qwen-3-235b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 40960,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"vercel_ai_gateway/alibaba/qwen-3-30b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 40960,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07\n },\n \"vercel_ai_gateway/alibaba/qwen-3-32b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 40960,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 40960,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07\n },\n \"vercel_ai_gateway/alibaba/qwen3-coder\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 66536,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06\n },\n \"vercel_ai_gateway/amazon/nova-lite\": {\n \"input_cost_per_token\": 6e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 300000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.4e-07\n },\n \"vercel_ai_gateway/amazon/nova-micro\": {\n \"input_cost_per_token\": 3.5e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.4e-07\n },\n \"vercel_ai_gateway/amazon/nova-pro\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 300000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 300000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3.2e-06\n },\n \"vercel_ai_gateway/amazon/titan-embed-text-v2\": {\n \"input_cost_per_token\": 2e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/anthropic/claude-3-haiku\": {\n \"cache_creation_input_token_cost\": 3e-07,\n \"cache_read_input_token_cost\": 3e-08,\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06\n },\n \"vercel_ai_gateway/anthropic/claude-3-opus\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05\n },\n \"vercel_ai_gateway/anthropic/claude-3.5-haiku\": {\n \"cache_creation_input_token_cost\": 1e-06,\n \"cache_read_input_token_cost\": 8e-08,\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06\n },\n \"vercel_ai_gateway/anthropic/claude-3.5-sonnet\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/anthropic/claude-3.7-sonnet\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/anthropic/claude-4-opus\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05\n },\n \"vercel_ai_gateway/anthropic/claude-4-sonnet\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/cohere/command-a\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05\n },\n \"vercel_ai_gateway/cohere/command-r\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"vercel_ai_gateway/cohere/command-r-plus\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05\n },\n \"vercel_ai_gateway/cohere/embed-v4.0\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/deepseek/deepseek-r1\": {\n \"input_cost_per_token\": 5.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.19e-06\n },\n \"vercel_ai_gateway/deepseek/deepseek-r1-distill-llama-70b\": {\n \"input_cost_per_token\": 7.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9.9e-07\n },\n \"vercel_ai_gateway/deepseek/deepseek-v3\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07\n },\n \"vercel_ai_gateway/google/gemini-2.0-flash\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 1048576,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"vercel_ai_gateway/google/gemini-2.0-flash-lite\": {\n \"input_cost_per_token\": 7.5e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 1048576,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07\n },\n \"vercel_ai_gateway/google/gemini-2.5-flash\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-06\n },\n \"vercel_ai_gateway/google/gemini-2.5-pro\": {\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_tokens\": 1048576,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05\n },\n \"vercel_ai_gateway/google/gemini-embedding-001\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/google/gemma-2-9b\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-07\n },\n \"vercel_ai_gateway/google/text-embedding-005\": {\n \"input_cost_per_token\": 2.5e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/google/text-multilingual-embedding-002\": {\n \"input_cost_per_token\": 2.5e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/inception/mercury-coder-small\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"vercel_ai_gateway/meta/llama-3-70b\": {\n \"input_cost_per_token\": 5.9e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.9e-07\n },\n \"vercel_ai_gateway/meta/llama-3-8b\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-08\n },\n \"vercel_ai_gateway/meta/llama-3.1-70b\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07\n },\n \"vercel_ai_gateway/meta/llama-3.1-8b\": {\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131000,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-08\n },\n \"vercel_ai_gateway/meta/llama-3.2-11b\": {\n \"input_cost_per_token\": 1.6e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-07\n },\n \"vercel_ai_gateway/meta/llama-3.2-1b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07\n },\n \"vercel_ai_gateway/meta/llama-3.2-3b\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07\n },\n \"vercel_ai_gateway/meta/llama-3.2-90b\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07\n },\n \"vercel_ai_gateway/meta/llama-3.3-70b\": {\n \"input_cost_per_token\": 7.2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.2e-07\n },\n \"vercel_ai_gateway/meta/llama-4-maverick\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"vercel_ai_gateway/meta/llama-4-scout\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07\n },\n \"vercel_ai_gateway/mistral/codestral\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07\n },\n \"vercel_ai_gateway/mistral/codestral-embed\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/mistral/devstral-small\": {\n \"input_cost_per_token\": 7e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.8e-07\n },\n \"vercel_ai_gateway/mistral/magistral-medium\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06\n },\n \"vercel_ai_gateway/mistral/magistral-small\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06\n },\n \"vercel_ai_gateway/mistral/ministral-3b\": {\n \"input_cost_per_token\": 4e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-08\n },\n \"vercel_ai_gateway/mistral/ministral-8b\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-07\n },\n \"vercel_ai_gateway/mistral/mistral-embed\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/mistral/mistral-large\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06\n },\n \"vercel_ai_gateway/mistral/mistral-saba-24b\": {\n \"input_cost_per_token\": 7.9e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.9e-07\n },\n \"vercel_ai_gateway/mistral/mistral-small\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07\n },\n \"vercel_ai_gateway/mistral/mixtral-8x22b-instruct\": {\n \"input_cost_per_token\": 1.2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 65536,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 65536,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06\n },\n \"vercel_ai_gateway/mistral/pixtral-12b\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07\n },\n \"vercel_ai_gateway/mistral/pixtral-large\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06\n },\n \"vercel_ai_gateway/moonshotai/kimi-k2\": {\n \"input_cost_per_token\": 5.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.2e-06\n },\n \"vercel_ai_gateway/morph/morph-v3-fast\": {\n \"input_cost_per_token\": 8e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06\n },\n \"vercel_ai_gateway/morph/morph-v3-large\": {\n \"input_cost_per_token\": 9e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.9e-06\n },\n \"vercel_ai_gateway/openai/gpt-3.5-turbo\": {\n \"input_cost_per_token\": 5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 16385,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 16385,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06\n },\n \"vercel_ai_gateway/openai/gpt-3.5-turbo-instruct\": {\n \"input_cost_per_token\": 1.5e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06\n },\n \"vercel_ai_gateway/openai/gpt-4-turbo\": {\n \"input_cost_per_token\": 1e-05,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-05\n },\n \"vercel_ai_gateway/openai/gpt-4.1\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1047576,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06\n },\n \"vercel_ai_gateway/openai/gpt-4.1-mini\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1047576,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-06\n },\n \"vercel_ai_gateway/openai/gpt-4.1-nano\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 2.5e-08,\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 1047576,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 1047576,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07\n },\n \"vercel_ai_gateway/openai/gpt-4o\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 1.25e-06,\n \"input_cost_per_token\": 2.5e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05\n },\n \"vercel_ai_gateway/openai/gpt-4o-mini\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 7.5e-08,\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07\n },\n \"vercel_ai_gateway/openai/o1\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 7.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-05\n },\n \"vercel_ai_gateway/openai/o3\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 5e-07,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06\n },\n \"vercel_ai_gateway/openai/o3-mini\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 5.5e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06\n },\n \"vercel_ai_gateway/openai/o4-mini\": {\n \"cache_creation_input_token_cost\": 0.0,\n \"cache_read_input_token_cost\": 2.75e-07,\n \"input_cost_per_token\": 1.1e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 100000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4.4e-06\n },\n \"vercel_ai_gateway/openai/text-embedding-3-large\": {\n \"input_cost_per_token\": 1.3e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/openai/text-embedding-3-small\": {\n \"input_cost_per_token\": 2e-08,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/openai/text-embedding-ada-002\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 0,\n \"max_output_tokens\": 0,\n \"max_tokens\": 0,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"vercel_ai_gateway/perplexity/sonar\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 127000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 127000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06\n },\n \"vercel_ai_gateway/perplexity/sonar-pro\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 200000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/perplexity/sonar-reasoning\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 127000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 127000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06\n },\n \"vercel_ai_gateway/perplexity/sonar-reasoning-pro\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 127000,\n \"max_output_tokens\": 8000,\n \"max_tokens\": 127000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06\n },\n \"vercel_ai_gateway/vercel/v0-1.0-md\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/vercel/v0-1.5-md\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/xai/grok-2\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 4000,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05\n },\n \"vercel_ai_gateway/xai/grok-2-vision\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05\n },\n \"vercel_ai_gateway/xai/grok-3\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/xai/grok-3-fast\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-05\n },\n \"vercel_ai_gateway/xai/grok-3-mini\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07\n },\n \"vercel_ai_gateway/xai/grok-3-mini-fast\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06\n },\n \"vercel_ai_gateway/xai/grok-4\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05\n },\n \"vercel_ai_gateway/zai/glm-4.5\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.2e-06\n },\n \"vercel_ai_gateway/zai/glm-4.5-air\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vercel_ai_gateway\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 96000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.1e-06\n },\n \"vertex_ai/claude-3-5-haiku\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/claude-3-5-haiku@20241022\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/claude-haiku-4-5@20251001\": {\n \"cache_creation_input_token_cost\": 1.25e-06,\n \"cache_read_input_token_cost\": 1e-07,\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/claude/haiku-4-5\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/claude-3-5-sonnet\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-5-sonnet-v2\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-5-sonnet-v2@20241022\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-5-sonnet@20240620\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-7-sonnet@20250219\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"deprecation_date\": \"2025-06-01\",\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"vertex_ai/claude-3-haiku\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-haiku@20240307\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.25e-06,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-opus\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-opus@20240229\": {\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-sonnet\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-3-sonnet@20240229\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-opus-4\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"vertex_ai/claude-opus-4-1\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"input_cost_per_token_batches\": 7.5e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"output_cost_per_token_batches\": 3.75e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-opus-4-1@20250805\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"input_cost_per_token_batches\": 7.5e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"output_cost_per_token_batches\": 3.75e-05,\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-sonnet-4-5\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"input_cost_per_token_batches\": 1.5e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_cost_per_token_batches\": 7.5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-sonnet-4-5@20250929\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"input_cost_per_token_batches\": 1.5e-06,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_cost_per_token_batches\": 7.5e-06,\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/claude-opus-4@20250514\": {\n \"cache_creation_input_token_cost\": 1.875e-05,\n \"cache_read_input_token_cost\": 1.5e-06,\n \"input_cost_per_token\": 1.5e-05,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 200000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"vertex_ai/claude-sonnet-4\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"vertex_ai/claude-sonnet-4@20250514\": {\n \"cache_creation_input_token_cost\": 3.75e-06,\n \"cache_read_input_token_cost\": 3e-07,\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_200k_tokens\": 6e-06,\n \"output_cost_per_token_above_200k_tokens\": 2.25e-05,\n \"cache_creation_input_token_cost_above_200k_tokens\": 7.5e-06,\n \"cache_read_input_token_cost_above_200k_tokens\": 6e-07,\n \"litellm_provider\": \"vertex_ai-anthropic_models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 64000,\n \"max_tokens\": 64000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"search_context_cost_per_query\": {\n \"search_context_size_high\": 0.01,\n \"search_context_size_low\": 0.01,\n \"search_context_size_medium\": 0.01\n },\n \"supports_assistant_prefill\": true,\n \"supports_computer_use\": true,\n \"supports_function_calling\": true,\n \"supports_pdf_input\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"tool_use_system_prompt_tokens\": 159\n },\n \"vertex_ai/mistralai/codestral-2@001\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/codestral-2\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/codestral-2@001\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistralai/codestral-2\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 9e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/codestral-2501\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/codestral@2405\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/codestral@latest\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/deepseek-ai/deepseek-v3.1-maas\": {\n \"input_cost_per_token\": 1.35e-06,\n \"litellm_provider\": \"vertex_ai-deepseek_models\",\n \"max_input_tokens\": 163840,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 163840,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.4e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supported_regions\": [\n \"us-west2\"\n ],\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/deepseek-ai/deepseek-r1-0528-maas\": {\n \"input_cost_per_token\": 1.35e-06,\n \"litellm_provider\": \"vertex_ai-deepseek_models\",\n \"max_input_tokens\": 65336,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5.4e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supports_assistant_prefill\": true,\n \"supports_function_calling\": true,\n \"supports_prompt_caching\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/imagegeneration@006\": {\n \"litellm_provider\": \"vertex_ai-image-models\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.02,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"vertex_ai/imagen-3.0-fast-generate-001\": {\n \"litellm_provider\": \"vertex_ai-image-models\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.02,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"vertex_ai/imagen-3.0-generate-001\": {\n \"litellm_provider\": \"vertex_ai-image-models\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"vertex_ai/imagen-3.0-generate-002\": {\n \"litellm_provider\": \"vertex_ai-image-models\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"vertex_ai/imagen-4.0-fast-generate-001\": {\n \"litellm_provider\": \"vertex_ai-image-models\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.02,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"vertex_ai/imagen-4.0-generate-001\": {\n \"litellm_provider\": \"vertex_ai-image-models\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.04,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"vertex_ai/imagen-4.0-ultra-generate-001\": {\n \"litellm_provider\": \"vertex_ai-image-models\",\n \"mode\": \"image_generation\",\n \"output_cost_per_image\": 0.06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\"\n },\n \"vertex_ai/jamba-1.5\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vertex_ai-ai21_models\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/jamba-1.5-large\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vertex_ai-ai21_models\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/jamba-1.5-large@001\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vertex_ai-ai21_models\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 8e-06,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/jamba-1.5-mini\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vertex_ai-ai21_models\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/jamba-1.5-mini@001\": {\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"vertex_ai-ai21_models\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-07,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/meta/llama-3.1-405b-instruct-maas\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.6e-05,\n \"source\": \"https://console.cloud.google.com/vertex-ai/publishers/meta/model-garden/llama-3.2-90b-vision-instruct-maas\",\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/meta/llama-3.1-70b-instruct-maas\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://console.cloud.google.com/vertex-ai/publishers/meta/model-garden/llama-3.2-90b-vision-instruct-maas\",\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/meta/llama-3.1-8b-instruct-maas\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"metadata\": {\n \"notes\": \"VertexAI states that The Llama 3.1 API service for llama-3.1-70b-instruct-maas and llama-3.1-8b-instruct-maas are in public preview and at no cost.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://console.cloud.google.com/vertex-ai/publishers/meta/model-garden/llama-3.2-90b-vision-instruct-maas\",\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/meta/llama-3.2-90b-vision-instruct-maas\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 2048,\n \"max_tokens\": 128000,\n \"metadata\": {\n \"notes\": \"VertexAI states that The Llama 3.2 API service is at no cost during public preview, and will be priced as per dollar-per-1M-tokens at GA.\"\n },\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://console.cloud.google.com/vertex-ai/publishers/meta/model-garden/llama-3.2-90b-vision-instruct-maas\",\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/meta/llama-4-maverick-17b-128e-instruct-maas\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 1000000,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.15e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/meta/llama-4-maverick-17b-16e-instruct-maas\": {\n \"input_cost_per_token\": 3.5e-07,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 1000000,\n \"max_output_tokens\": 1000000,\n \"max_tokens\": 1000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.15e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/meta/llama-4-scout-17b-128e-instruct-maas\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 10000000,\n \"max_output_tokens\": 10000000,\n \"max_tokens\": 10000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/meta/llama-4-scout-17b-16e-instruct-maas\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 10000000,\n \"max_output_tokens\": 10000000,\n \"max_tokens\": 10000000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 7e-07,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"text\",\n \"code\"\n ],\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/meta/llama3-405b-instruct-maas\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supports_tool_choice\": true\n },\n \"vertex_ai/meta/llama3-70b-instruct-maas\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supports_tool_choice\": true\n },\n \"vertex_ai/meta/llama3-8b-instruct-maas\": {\n \"input_cost_per_token\": 0.0,\n \"litellm_provider\": \"vertex_ai-llama_models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.0,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing#partner-models\",\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-medium-3\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-medium-3@001\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistralai/mistral-medium-3\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistralai/mistral-medium-3@001\": {\n \"input_cost_per_token\": 4e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-large-2411\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-large@2407\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-large@2411-001\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-large@latest\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-nemo@2407\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-nemo@latest\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-07,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/mistral-small-2503\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"max_tokens\": 128000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true\n },\n \"vertex_ai/mistral-small-2503@001\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vertex_ai-mistral_models\",\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 8191,\n \"max_tokens\": 8191,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-06,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/openai/gpt-oss-120b-maas\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-openai_models\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 6e-07,\n \"source\": \"https://console.cloud.google.com/vertex-ai/publishers/openai/model-garden/gpt-oss-120b-maas\",\n \"supports_reasoning\": true\n },\n \"vertex_ai/openai/gpt-oss-20b-maas\": {\n \"input_cost_per_token\": 7.5e-08,\n \"litellm_provider\": \"vertex_ai-openai_models\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 3e-07,\n \"source\": \"https://console.cloud.google.com/vertex-ai/publishers/openai/model-garden/gpt-oss-120b-maas\",\n \"supports_reasoning\": true\n },\n \"vertex_ai/qwen/qwen3-235b-a22b-instruct-2507-maas\": {\n \"input_cost_per_token\": 2.5e-07,\n \"litellm_provider\": \"vertex_ai-qwen_models\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 16384,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/qwen/qwen3-coder-480b-a35b-instruct-maas\": {\n \"input_cost_per_token\": 1e-06,\n \"litellm_provider\": \"vertex_ai-qwen_models\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/qwen/qwen3-next-80b-a3b-instruct-maas\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-qwen_models\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/qwen/qwen3-next-80b-a3b-thinking-maas\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-qwen_models\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/veo-2.0-generate-001\": {\n \"litellm_provider\": \"vertex_ai-video-models\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"video_generation\",\n \"output_cost_per_second\": 0.35,\n \"source\": \"https://ai.google.dev/gemini-api/docs/video\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ]\n },\n \"vertex_ai/veo-3.0-fast-generate-preview\": {\n \"litellm_provider\": \"vertex_ai-video-models\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"video_generation\",\n \"output_cost_per_second\": 0.4,\n \"source\": \"https://ai.google.dev/gemini-api/docs/video\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ]\n },\n \"vertex_ai/veo-3.0-generate-preview\": {\n \"litellm_provider\": \"vertex_ai-video-models\",\n \"max_input_tokens\": 1024,\n \"max_tokens\": 1024,\n \"mode\": \"video_generation\",\n \"output_cost_per_second\": 0.75,\n \"source\": \"https://ai.google.dev/gemini-api/docs/video\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ]\n },\n \"voyage/rerank-2\": {\n \"input_cost_per_query\": 5e-08,\n \"input_cost_per_token\": 5e-08,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 16000,\n \"max_output_tokens\": 16000,\n \"max_query_tokens\": 16000,\n \"max_tokens\": 16000,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/rerank-2-lite\": {\n \"input_cost_per_query\": 2e-08,\n \"input_cost_per_token\": 2e-08,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 8000,\n \"max_output_tokens\": 8000,\n \"max_query_tokens\": 8000,\n \"max_tokens\": 8000,\n \"mode\": \"rerank\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-2\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 4000,\n \"max_tokens\": 4000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-3\": {\n \"input_cost_per_token\": 6e-08,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-3-large\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-3-lite\": {\n \"input_cost_per_token\": 2e-08,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-code-2\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 16000,\n \"max_tokens\": 16000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-code-3\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-context-3\": {\n \"input_cost_per_token\": 1.8e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 120000,\n \"max_tokens\": 120000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-finance-2\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-large-2\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 16000,\n \"max_tokens\": 16000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-law-2\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 16000,\n \"max_tokens\": 16000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-lite-01\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 4096,\n \"max_tokens\": 4096,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-lite-02-instruct\": {\n \"input_cost_per_token\": 1e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 4000,\n \"max_tokens\": 4000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"voyage/voyage-multimodal-3\": {\n \"input_cost_per_token\": 1.2e-07,\n \"litellm_provider\": \"voyage\",\n \"max_input_tokens\": 32000,\n \"max_tokens\": 32000,\n \"mode\": \"embedding\",\n \"output_cost_per_token\": 0.0\n },\n \"wandb/openai/gpt-oss-120b\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 0.015,\n \"output_cost_per_token\": 0.06,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/openai/gpt-oss-20b\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 0.005,\n \"output_cost_per_token\": 0.02,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/zai-org/GLM-4.5\": {\n \"max_tokens\": 131072,\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"input_cost_per_token\": 0.055,\n \"output_cost_per_token\": 0.2,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/Qwen/Qwen3-235B-A22B-Instruct-2507\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 0.01,\n \"output_cost_per_token\": 0.01,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/Qwen/Qwen3-Coder-480B-A35B-Instruct\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 0.1,\n \"output_cost_per_token\": 0.15,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/Qwen/Qwen3-235B-A22B-Thinking-2507\": {\n \"max_tokens\": 262144,\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"input_cost_per_token\": 0.01,\n \"output_cost_per_token\": 0.01,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/moonshotai/Kimi-K2-Instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.135,\n \"output_cost_per_token\": 0.4,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/meta-llama/Llama-3.1-8B-Instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.022,\n \"output_cost_per_token\": 0.022,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/deepseek-ai/DeepSeek-V3.1\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.055,\n \"output_cost_per_token\": 0.165,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/deepseek-ai/DeepSeek-R1-0528\": {\n \"max_tokens\": 161000,\n \"max_input_tokens\": 161000,\n \"max_output_tokens\": 161000,\n \"input_cost_per_token\": 0.135,\n \"output_cost_per_token\": 0.54,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/deepseek-ai/DeepSeek-V3-0324\": {\n \"max_tokens\": 161000,\n \"max_input_tokens\": 161000,\n \"max_output_tokens\": 161000,\n \"input_cost_per_token\": 0.114,\n \"output_cost_per_token\": 0.275,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/meta-llama/Llama-3.3-70B-Instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.071,\n \"output_cost_per_token\": 0.071,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/meta-llama/Llama-4-Scout-17B-16E-Instruct\": {\n \"max_tokens\": 64000,\n \"max_input_tokens\": 64000,\n \"max_output_tokens\": 64000,\n \"input_cost_per_token\": 0.017,\n \"output_cost_per_token\": 0.066,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"wandb/microsoft/Phi-4-mini-instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.008,\n \"output_cost_per_token\": 0.035,\n \"litellm_provider\": \"wandb\",\n \"mode\": \"chat\"\n },\n \"watsonx/ibm/granite-3-8b-instruct\": {\n \"input_cost_per_token\": 0.2e-06,\n \"litellm_provider\": \"watsonx\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 1024,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 0.2e-06,\n \"supports_audio_input\": false,\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"watsonx/mistralai/mistral-large\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"watsonx\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 16384,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 10e-06,\n \"supports_audio_input\": false,\n \"supports_audio_output\": false,\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": false,\n \"supports_prompt_caching\": true,\n \"supports_response_schema\": true,\n \"supports_system_messages\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": false\n },\n \"watsonx/bigscience/mt0-xxl-13b\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.0005,\n \"output_cost_per_token\": 0.002,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/core42/jais-13b-chat\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.0005,\n \"output_cost_per_token\": 0.002,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/google/flan-t5-xl-3b\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.6e-06,\n \"output_cost_per_token\": 0.6e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-13b-chat-v2\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.6e-06,\n \"output_cost_per_token\": 0.6e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-13b-instruct-v2\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.6e-06,\n \"output_cost_per_token\": 0.6e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-3-3-8b-instruct\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.2e-06,\n \"output_cost_per_token\": 0.2e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-4-h-small\": {\n \"max_tokens\": 20480,\n \"max_input_tokens\": 20480,\n \"max_output_tokens\": 20480,\n \"input_cost_per_token\": 0.06e-06,\n \"output_cost_per_token\": 0.25e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-guardian-3-2-2b\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.1e-06,\n \"output_cost_per_token\": 0.1e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-guardian-3-3-8b\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.2e-06,\n \"output_cost_per_token\": 0.2e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-ttm-1024-96-r2\": {\n \"max_tokens\": 512,\n \"max_input_tokens\": 512,\n \"max_output_tokens\": 512,\n \"input_cost_per_token\": 0.38e-06,\n \"output_cost_per_token\": 0.38e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-ttm-1536-96-r2\": {\n \"max_tokens\": 512,\n \"max_input_tokens\": 512,\n \"max_output_tokens\": 512,\n \"input_cost_per_token\": 0.38e-06,\n \"output_cost_per_token\": 0.38e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-ttm-512-96-r2\": {\n \"max_tokens\": 512,\n \"max_input_tokens\": 512,\n \"max_output_tokens\": 512,\n \"input_cost_per_token\": 0.38e-06,\n \"output_cost_per_token\": 0.38e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/ibm/granite-vision-3-2-2b\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.1e-06,\n \"output_cost_per_token\": 0.1e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": true\n },\n \"watsonx/meta-llama/llama-3-2-11b-vision-instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.35e-06,\n \"output_cost_per_token\": 0.35e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": true\n },\n \"watsonx/meta-llama/llama-3-2-1b-instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.1e-06,\n \"output_cost_per_token\": 0.1e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/meta-llama/llama-3-2-3b-instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.15e-06,\n \"output_cost_per_token\": 0.15e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/meta-llama/llama-3-2-90b-vision-instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 2e-06,\n \"output_cost_per_token\": 2e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": true\n },\n \"watsonx/meta-llama/llama-3-3-70b-instruct\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.71e-06,\n \"output_cost_per_token\": 0.71e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/meta-llama/llama-4-maverick-17b\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.35e-06,\n \"output_cost_per_token\": 1.4e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/meta-llama/llama-guard-3-11b-vision\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.35e-06,\n \"output_cost_per_token\": 0.35e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": true\n },\n \"watsonx/mistralai/mistral-medium-2505\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 3e-06,\n \"output_cost_per_token\": 10e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/mistralai/mistral-small-2503\": {\n \"max_tokens\": 32000,\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"input_cost_per_token\": 0.1e-06,\n \"output_cost_per_token\": 0.3e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/mistralai/mistral-small-3-1-24b-instruct-2503\": {\n \"max_tokens\": 32000,\n \"max_input_tokens\": 32000,\n \"max_output_tokens\": 32000,\n \"input_cost_per_token\": 0.1e-06,\n \"output_cost_per_token\": 0.3e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": true,\n \"supports_parallel_function_calling\": true,\n \"supports_vision\": false\n },\n \"watsonx/mistralai/pixtral-12b-2409\": {\n \"max_tokens\": 128000,\n \"max_input_tokens\": 128000,\n \"max_output_tokens\": 128000,\n \"input_cost_per_token\": 0.35e-06,\n \"output_cost_per_token\": 0.35e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": true\n },\n \"watsonx/openai/gpt-oss-120b\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 0.15e-06,\n \"output_cost_per_token\": 0.6e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n \"watsonx/sdaia/allam-1-13b-instruct\": {\n \"max_tokens\": 8192,\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"input_cost_per_token\": 1.8e-06,\n \"output_cost_per_token\": 1.8e-06,\n \"litellm_provider\": \"watsonx\",\n \"mode\": \"chat\",\n \"supports_function_calling\": false,\n \"supports_parallel_function_calling\": false,\n \"supports_vision\": false\n },\n\n \"whisper-1\": {\n \"input_cost_per_second\": 0.0001,\n \"litellm_provider\": \"openai\",\n \"mode\": \"audio_transcription\",\n \"output_cost_per_second\": 0.0001,\n \"supported_endpoints\": [\n \"/v1/audio/transcriptions\"\n ]\n },\n \"vertex_ai/qwen/qwen3-next-80b-a3b-instruct-maas\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-qwen_models\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"vertex_ai/qwen/qwen3-next-80b-a3b-thinking-maas\": {\n \"input_cost_per_token\": 1.5e-07,\n \"litellm_provider\": \"vertex_ai-qwen_models\",\n \"max_input_tokens\": 262144,\n \"max_output_tokens\": 262144,\n \"max_tokens\": 262144,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.2e-06,\n \"source\": \"https://cloud.google.com/vertex-ai/generative-ai/pricing\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true\n },\n \"xai/grok-2\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-2-1212\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-2-latest\": {\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-2-vision\": {\n \"input_cost_per_image\": 2e-06,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-2-vision-1212\": {\n \"input_cost_per_image\": 2e-06,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-2-vision-latest\": {\n \"input_cost_per_image\": 2e-06,\n \"input_cost_per_token\": 2e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 32768,\n \"max_output_tokens\": 32768,\n \"max_tokens\": 32768,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-beta\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-fast-beta\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-05,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-fast-latest\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 2.5e-05,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-latest\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-mini\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-mini-beta\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-mini-fast\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-mini-fast-beta\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-mini-fast-latest\": {\n \"input_cost_per_token\": 6e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 4e-06,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-3-mini-latest\": {\n \"input_cost_per_token\": 3e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 5e-07,\n \"source\": \"https://x.ai/api#pricing\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_response_schema\": false,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-4\": {\n \"input_cost_per_token\": 3e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-4-fast-reasoning\": {\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 2e6,\n \"max_output_tokens\": 2e6,\n \"max_tokens\": 2e6,\n \"mode\": \"chat\",\n \"input_cost_per_token\": 0.2e-06,\n \"input_cost_per_token_above_128k_tokens\": 0.4e-06,\n \"output_cost_per_token\": 0.5e-06,\n \"output_cost_per_token_above_128k_tokens\": 1e-06,\n \"cache_read_input_token_cost\": 0.05e-06,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-4-fast-non-reasoning\": {\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 2e6,\n \"max_output_tokens\": 2e6,\n \"cache_read_input_token_cost\": 0.05e-06,\n \"max_tokens\": 2e6,\n \"mode\": \"chat\",\n \"input_cost_per_token\": 0.2e-06,\n \"input_cost_per_token_above_128k_tokens\": 0.4e-06,\n \"output_cost_per_token\": 0.5e-06,\n \"output_cost_per_token_above_128k_tokens\": 1e-06,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-4-0709\": {\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_128k_tokens\": 6e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_cost_per_token_above_128k_tokens\": 30e-06,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-4-latest\": {\n \"input_cost_per_token\": 3e-06,\n \"input_cost_per_token_above_128k_tokens\": 6e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"output_cost_per_token_above_128k_tokens\": 30e-06,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-beta\": {\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 131072,\n \"max_output_tokens\": 131072,\n \"max_tokens\": 131072,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"xai/grok-code-fast\": {\n \"cache_read_input_token_cost\": 2e-08,\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"xai/grok-code-fast-1\": {\n \"cache_read_input_token_cost\": 2e-08,\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"xai/grok-code-fast-1-0825\": {\n \"cache_read_input_token_cost\": 2e-08,\n \"input_cost_per_token\": 2e-07,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 256000,\n \"max_output_tokens\": 256000,\n \"max_tokens\": 256000,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-06,\n \"source\": \"https://docs.x.ai/docs/models\",\n \"supports_function_calling\": true,\n \"supports_reasoning\": true,\n \"supports_tool_choice\": true\n },\n \"xai/grok-vision-beta\": {\n \"input_cost_per_image\": 5e-06,\n \"input_cost_per_token\": 5e-06,\n \"litellm_provider\": \"xai\",\n \"max_input_tokens\": 8192,\n \"max_output_tokens\": 8192,\n \"max_tokens\": 8192,\n \"mode\": \"chat\",\n \"output_cost_per_token\": 1.5e-05,\n \"supports_function_calling\": true,\n \"supports_tool_choice\": true,\n \"supports_vision\": true,\n \"supports_web_search\": true\n },\n \"vertex_ai/search_api\": {\n \"input_cost_per_query\": 1.5e-03,\n \"litellm_provider\": \"vertex_ai\",\n \"mode\": \"vector_store\"\n },\n \"openai/sora-2\": {\n \"litellm_provider\": \"openai\",\n \"mode\": \"video_generation\",\n \"output_cost_per_video_per_second\": 0.10,\n \"source\": \"https://platform.openai.com/docs/api-reference/videos\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ],\n \"supported_resolutions\": [\n \"720x1280\",\n \"1280x720\"\n ]\n },\n \"openai/sora-2-pro\": {\n \"litellm_provider\": \"openai\",\n \"mode\": \"video_generation\",\n \"output_cost_per_video_per_second\": 0.30,\n \"source\": \"https://platform.openai.com/docs/api-reference/videos\",\n \"supported_modalities\": [\n \"text\",\n \"image\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ],\n \"supported_resolutions\": [\n \"720x1280\",\n \"1280x720\"\n ]\n },\n \"azure/sora-2\": {\n \"litellm_provider\": \"azure\",\n \"mode\": \"video_generation\",\n \"output_cost_per_video_per_second\": 0.10,\n \"source\": \"https://azure.microsoft.com/en-us/products/ai-services/video-generation\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ],\n \"supported_resolutions\": [\n \"720x1280\",\n \"1280x720\"\n ]\n },\n \"azure/sora-2-pro\": {\n \"litellm_provider\": \"azure\",\n \"mode\": \"video_generation\",\n \"output_cost_per_video_per_second\": 0.30,\n \"source\": \"https://azure.microsoft.com/en-us/products/ai-services/video-generation\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ],\n \"supported_resolutions\": [\n \"720x1280\",\n \"1280x720\"\n ]\n },\n \"azure/sora-2-pro-high-res\": {\n \"litellm_provider\": \"azure\",\n \"mode\": \"video_generation\",\n \"output_cost_per_video_per_second\": 0.50,\n \"source\": \"https://azure.microsoft.com/en-us/products/ai-services/video-generation\",\n \"supported_modalities\": [\n \"text\"\n ],\n \"supported_output_modalities\": [\n \"video\"\n ],\n \"supported_resolutions\": [\n \"1024x1792\",\n \"1792x1024\"\n ]\n }\n}" }, { "path": "cli/src/utils/costCalculator.ts", "content": "import costData from './cost.json' with { type: 'json' };\n\ninterface ModelCost {\n input_cost_per_token?: number;\n output_cost_per_token?: number;\n cache_creation_input_token_cost?: number;\n cache_read_input_token_cost?: number;\n}\n\n/**\n * Calculate the total cost for a given model and token usage\n * @param modelId The model identifier (e.g., \"us.anthropic.claude-haiku-4-5-20251001-v1:0\")\n * @param inputTokens Number of input tokens used\n * @param outputTokens Number of output tokens used\n * @returns Total cost in dollars, or undefined if model cost data not found\n */\nexport function calculateCost(\n modelId: string,\n inputTokens: number,\n outputTokens: number\n): number | undefined {\n const modelCostData = (costData as Record)[modelId];\n\n if (!modelCostData) {\n return undefined;\n }\n\n const inputCostPerToken = modelCostData.input_cost_per_token ?? 0;\n const outputCostPerToken = modelCostData.output_cost_per_token ?? 0;\n\n const inputCost = inputTokens * inputCostPerToken;\n const outputCost = outputTokens * outputCostPerToken;\n const totalCost = inputCost + outputCost;\n\n return totalCost;\n}\n\n/**\n * Format cost as a readable string with appropriate precision\n * @param cost Cost in dollars\n * @returns Formatted string (e.g., \"$0.0023\" or \"$0.00\")\n */\nexport function formatCost(cost: number): string {\n if (cost >= 0.01) {\n return `$${cost.toFixed(2)}`;\n } else if (cost >= 0.001) {\n return `$${cost.toFixed(4)}`;\n } else if (cost > 0) {\n return `$${cost.toFixed(6)}`;\n } else {\n return \"$0.00\";\n }\n}\n" }, { "path": "cli/src/utils/docsReader.ts", "content": "import fs from 'fs';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nconst DOCS_DIR = path.resolve(__dirname, '../../..', 'docs');\n\nexport interface DocFile {\n path: string;\n name: string;\n content: string;\n}\n\n\nfunction _walkDirectory(dir: string, baseDir: string, files: string[] = []): string[] {\n const entries = fs.readdirSync(dir, { withFileTypes: true });\n const resolvedBase = path.resolve(baseDir);\n\n for (const entry of entries) {\n // Validate entry name doesn't contain path traversal sequences\n if (entry.name.includes('..') || entry.name.includes('/') || entry.name.includes('\\\\')) {\n continue;\n }\n\n const fullPath = path.join(dir, entry.name);\n\n // Ensure resolved path is still within baseDir\n const resolvedPath = path.resolve(fullPath);\n if (!resolvedPath.startsWith(resolvedBase)) {\n continue;\n }\n\n if (entry.isDirectory()) {\n _walkDirectory(fullPath, baseDir, files);\n } else if (entry.isFile() && entry.name.endsWith('.md')) {\n const relativePath = path.relative(baseDir, fullPath);\n files.push(relativePath);\n }\n }\n\n return files;\n}\n\n\nfunction _scoreDocument(content: string, fileName: string, keywords: string[]): number {\n let score = 0;\n const lowerContent = content.toLowerCase();\n const lowerFileName = fileName.toLowerCase();\n\n for (const keyword of keywords) {\n const lowerKeyword = keyword.toLowerCase();\n\n // Count occurrences in content\n const contentMatches = (lowerContent.match(new RegExp(lowerKeyword, 'g')) || []).length;\n score += contentMatches;\n\n // Boost score if keyword appears in filename or path\n if (lowerFileName.includes(lowerKeyword)) {\n score += 10;\n }\n }\n\n return score;\n}\n\n\nexport function getAllDocFiles(): string[] {\n if (!fs.existsSync(DOCS_DIR)) {\n return [];\n }\n\n return _walkDirectory(DOCS_DIR, DOCS_DIR);\n}\n\n\nexport function readDocFile(filePath: string): DocFile | null {\n // Reject path traversal sequences and absolute paths\n if (filePath.includes('..') || path.isAbsolute(filePath)) {\n throw new Error(`Invalid file path: ${filePath}`);\n }\n\n const fullPath = path.join(DOCS_DIR, filePath);\n\n // Resolve paths and ensure result is within DOCS_DIR\n const resolvedPath = path.resolve(fullPath);\n const resolvedBase = path.resolve(DOCS_DIR);\n if (!resolvedPath.startsWith(resolvedBase)) {\n throw new Error(`Path traversal detected: ${filePath}`);\n }\n\n if (!fs.existsSync(resolvedPath)) {\n return null;\n }\n\n try {\n const content = fs.readFileSync(resolvedPath, 'utf-8');\n const name = path.basename(filePath);\n\n return {\n path: filePath,\n name,\n content\n };\n } catch (error) {\n return null;\n }\n}\n\n\nexport function searchDocs(query: string): DocFile[] {\n const keywords = query.trim().split(/\\s+/).filter(k => k.length > 0);\n\n if (keywords.length === 0) {\n return [];\n }\n\n const allFiles = getAllDocFiles();\n const scoredDocs: Array<{ doc: DocFile; score: number }> = [];\n\n for (const filePath of allFiles) {\n const doc = readDocFile(filePath);\n if (!doc) continue;\n\n const score = _scoreDocument(doc.content, doc.path, keywords);\n\n if (score > 0) {\n scoredDocs.push({ doc, score });\n }\n }\n\n // Sort by score descending and return top 3\n scoredDocs.sort((a, b) => b.score - a.score);\n\n return scoredDocs.slice(0, 3).map(item => item.doc);\n}\n" }, { "path": "cli/src/utils/markdown.ts", "content": "/**\n * Render markdown to terminal-friendly format\n * Simple cleanup for terminal display - doesn't do heavy rendering\n */\nexport function renderMarkdown(markdown: string): string {\n try {\n let text = markdown;\n\n // Render tables before other processing\n text = renderMarkdownTables(text);\n\n // Remove markdown headers but keep the text\n text = text.replace(/^#{1,6}\\s+/gm, '');\n\n // Remove bold/italic markers\n text = text.replace(/\\*\\*(.+?)\\*\\*/g, '$1');\n text = text.replace(/\\*(.+?)\\*/g, '$1');\n text = text.replace(/_(.+?)_/g, '$1');\n\n // Keep code blocks simple - just remove the markers\n text = text.replace(/```(\\w+)?\\n([\\s\\S]*?)```/g, (_match, _lang, code) => {\n return `\\n${code.trim()}\\n`;\n });\n\n // Keep inline code with special markers for highlighting\n // Using ANSI-style markers that Ink will preserve\n text = text.replace(/`([^`]+)`/g, '`$1`');\n\n // Links - show just the text\n text = text.replace(/\\[([^\\]]+)\\]\\([^)]+\\)/g, '$1');\n\n return text;\n } catch (error) {\n // Fallback to plain text if parsing fails\n return markdown;\n }\n}\n\n/**\n * Render markdown tables to a cleaner terminal format\n */\nfunction renderMarkdownTables(text: string): string {\n // Match markdown tables (header row, separator row, and data rows)\n // Allow leading whitespace before the table\n const tableRegex = /^[ \\t]*(\\|.+\\|)[ \\t]*\\n[ \\t]*(\\|(?:[\\s:-]+\\|)+)[ \\t]*\\n((?:[ \\t]*\\|.+\\|[ \\t]*\\n?)*)/gm;\n\n return text.replace(tableRegex, (_match, headerRow, _separatorRow, dataRows) => {\n const parseRow = (row: string): string[] => {\n return row\n .split('|')\n .map(cell => cell.trim())\n .filter(cell => cell.length > 0);\n };\n\n const headers = parseRow(headerRow);\n const rows = dataRows\n .trim()\n .split('\\n')\n .filter((row: string) => row.trim().length > 0)\n .map(parseRow);\n\n // Calculate column widths\n const columnWidths = headers.map((header, i) => {\n const maxDataWidth = Math.max(...rows.map((row: string[]) => (row[i] || '').length));\n return Math.max(header.length, maxDataWidth);\n });\n\n // Format a row with proper padding\n const formatRow = (cells: string[]): string => {\n return ' ' + cells.map((cell, i) => {\n const width = columnWidths[i] || 0;\n return cell.padEnd(width, ' ');\n }).join(' | ');\n };\n\n // Build the formatted table\n const lines: string[] = [];\n lines.push(''); // Empty line before table\n lines.push(formatRow(headers));\n lines.push(' ' + columnWidths.map((w: number) => '─'.repeat(w)).join('──┼──'));\n rows.forEach((row: string[]) => lines.push(formatRow(row)));\n lines.push(''); // Empty line after table\n\n return lines.join('\\n');\n });\n}\n\n/**\n * Check if text contains markdown formatting\n */\nexport function hasMarkdown(text: string): boolean {\n const markdownPatterns = [\n /^#{1,6}\\s/m, // Headers\n /\\*\\*.*?\\*\\*/, // Bold\n /_.*?_/, // Italic\n /`.*?`/, // Inline code\n /```[\\s\\S]*?```/, // Code blocks\n /^\\s*[-*+]\\s/m, // Lists\n /^\\s*\\d+\\.\\s/m, // Numbered lists\n /\\[.*?\\]\\(.*?\\)/, // Links\n ];\n\n return markdownPatterns.some(pattern => pattern.test(text));\n}\n\n/**\n * Format tool output with syntax highlighting hints\n */\nexport function formatToolOutput(toolName: string, output: string, isError: boolean = false): string {\n const status = isError ? \"✗\" : \"✓\";\n const header = `\\n${status} **${toolName}**\\n`;\n\n // Try to parse as JSON for better formatting\n try {\n const parsed = JSON.parse(output);\n return `${header}\\`\\`\\`json\\n${JSON.stringify(parsed, null, 2)}\\n\\`\\`\\``;\n } catch {\n // Not JSON, return as code block\n return `${header}\\`\\`\\`\\n${output}\\n\\`\\`\\``;\n }\n}\n" }, { "path": "cli/src/utils/tokenRefresh.ts", "content": "import {exec} from \"node:child_process\";\nimport {promisify} from \"node:util\";\nimport path from \"node:path\";\n\nconst execAsync = promisify(exec);\n\nexport interface TokenRefreshResult {\n success: boolean;\n message: string;\n}\n\n/**\n * Automatically refresh OAuth tokens by calling generate_creds.sh\n * @param projectRoot - Path to the project root directory\n * @returns Result of the token refresh operation\n */\nexport async function refreshTokens(projectRoot?: string): Promise {\n try {\n // Default to parent of cli directory\n const root = projectRoot || path.join(process.cwd(), \"..\");\n const scriptPath = path.join(root, \"credentials-provider\", \"generate_creds.sh\");\n\n // Check if script exists\n try {\n await execAsync(`test -f \"${scriptPath}\"`);\n } catch {\n return {\n success: false,\n message: `Token refresh script not found at ${scriptPath}`\n };\n }\n\n // Run the script with --ingress-only and --force flags\n const {stdout, stderr} = await execAsync(\n `cd \"${root}\" && ./credentials-provider/generate_creds.sh --ingress-only --force`,\n {\n timeout: 30000, // 30 second timeout\n maxBuffer: 1024 * 1024 // 1MB buffer\n }\n );\n\n // Check if successful by looking for success indicators in output\n const output = stdout + stderr;\n if (output.includes(\"Successfully\") || output.includes(\"Token generated\") || output.includes(\"Tokens saved\")) {\n return {\n success: true,\n message: \"OAuth tokens refreshed successfully\"\n };\n }\n\n return {\n success: false,\n message: `Token refresh completed but status unclear: ${output.substring(0, 200)}`\n };\n } catch (error: any) {\n return {\n success: false,\n message: `Failed to refresh tokens: ${error.message}`\n };\n }\n}\n\n/**\n * Check if we should attempt automatic token refresh\n * @param secondsRemaining - Seconds until token expires\n * @returns true if we should refresh\n */\nexport function shouldRefreshToken(secondsRemaining: number | undefined): boolean {\n // Refresh if token expires in less than 10 seconds or already expired\n return secondsRemaining !== undefined && secondsRemaining <= 10;\n}\n" }, { "path": "cli/sync_okta_m2m.py", "content": "\"\"\"CLI script to sync Okta M2M clients to MongoDB.\n\nThis script connects to MongoDB and syncs all Okta M2M applications,\nstoring their client IDs and group mappings for authorization decisions.\n\"\"\"\n\nimport asyncio\nimport logging\nimport os\nimport sys\n\nfrom motor.motor_asyncio import AsyncIOMotorClient\n\n# Add parent directory to path so we can import registry modules\nsys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))\n\nfrom registry.services.okta_m2m_sync import OktaM2MSync\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nasync def main():\n \"\"\"Main function to sync Okta M2M clients.\"\"\"\n # Get configuration from environment\n mongo_uri = os.getenv(\"DOCUMENTDB_URI\", \"mongodb://localhost:27017\")\n mongo_db_name = os.getenv(\"DOCUMENTDB_DB_NAME\", \"mcp_registry\")\n okta_domain = os.getenv(\"OKTA_DOMAIN\")\n okta_api_token = os.getenv(\"OKTA_API_TOKEN\")\n\n if not okta_domain or not okta_api_token:\n logger.error(\"ERROR: OKTA_DOMAIN and OKTA_API_TOKEN environment variables must be set\")\n logger.error(\"Example:\")\n logger.error(\" export OKTA_DOMAIN=integrator-9917255.okta.com\")\n logger.error(\" export OKTA_API_TOKEN=your_api_token_here\")\n sys.exit(1)\n\n logger.info(\"=\" * 60)\n logger.info(\"Okta M2M Client Sync\")\n logger.info(\"=\" * 60)\n logger.info(f\"MongoDB URI: {mongo_uri}\")\n logger.info(f\"Database: {mongo_db_name}\")\n logger.info(f\"Okta Domain: {okta_domain}\")\n logger.info(\"=\" * 60)\n\n # Connect to MongoDB\n try:\n mongo_client = AsyncIOMotorClient(mongo_uri)\n db = mongo_client[mongo_db_name]\n\n # Test connection\n await db.command(\"ping\")\n logger.info(\"✓ Connected to MongoDB\")\n\n except Exception as e:\n logger.error(f\"Failed to connect to MongoDB: {e}\")\n sys.exit(1)\n\n # Initialize Okta sync service\n try:\n okta_sync = OktaM2MSync(\n db=db,\n okta_domain=okta_domain,\n okta_api_token=okta_api_token,\n )\n\n # Perform sync\n logger.info(\"\\nStarting sync from Okta...\")\n result = await okta_sync.sync_from_okta(force_full_sync=True)\n\n logger.info(\"\\n\" + \"=\" * 60)\n logger.info(\"SYNC COMPLETE\")\n logger.info(\"=\" * 60)\n logger.info(f\"Added: {result['added_count']} clients\")\n logger.info(f\"Updated: {result['updated_count']} clients\")\n logger.info(f\"Total synced: {result['synced_count']} clients\")\n\n if result[\"errors\"]:\n logger.warning(f\"\\nErrors encountered: {len(result['errors'])}\")\n for error in result[\"errors\"]:\n logger.warning(f\" - {error}\")\n\n # Display synced clients\n logger.info(\"\\nSynced clients:\")\n clients = await okta_sync.get_all_clients()\n for client in clients:\n logger.info(f\" - {client.name} (ID: {client.client_id}, Groups: {client.groups})\")\n\n logger.info(\"\\n✓ Sync successful!\")\n\n except Exception as e:\n logger.exception(f\"Sync failed: {e}\")\n sys.exit(1)\n finally:\n mongo_client.close()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "cli/test_a2a_agents.py", "content": "#!/usr/bin/env python3\n\"\"\"\nTest A2A Agents Public API Endpoints.\n\nThis script tests the A2A Agents API endpoints using JWT tokens\ngenerated from the MCP Registry UI or credentials provider.\n\nUsage:\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --test list-agents\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --test get-agent --agent-name test-agent\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --test pagination-flow\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --test all --verbose\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --base-url http://localhost --debug\n\nNote: Tokens have a short lifetime for security. If your token expires, generate a new one\nfrom the UI or ask your administrator to increase the access token timeout in Keycloak.\n\"\"\"\n\nimport argparse\nimport base64\nimport json\nimport logging\nimport sys\nimport time\nfrom datetime import UTC, datetime\nfrom pathlib import Path\nfrom typing import Any\nfrom urllib.parse import quote\n\nimport requests\n\n# Add project root to path to import constants\nSCRIPT_DIR = Path(__file__).parent\nPROJECT_ROOT = SCRIPT_DIR.parent\nsys.path.insert(0, str(PROJECT_ROOT))\n\nfrom registry.constants import REGISTRY_CONSTANTS\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nDEFAULT_BASE_URL: str = \"http://localhost\"\nAGENTS_API_VERSION: str = REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION\n\n\nclass TestResult:\n \"\"\"Container for test results.\"\"\"\n\n def __init__(self, test_name: str) -> None:\n \"\"\"Initialize test result.\"\"\"\n self.test_name = test_name\n self.passed = False\n self.duration_ms = 0\n self.response = None\n self.error = None\n self.message = \"\"\n\n\ndef _check_token_expiration(access_token: str) -> None:\n \"\"\"\n Check if JWT token is expired and warn if expiring soon.\n\n Args:\n access_token: JWT access token to check\n \"\"\"\n try:\n parts = access_token.split(\".\")\n if len(parts) != 3:\n logger.warning(\"Invalid JWT format, cannot check expiration\")\n return\n\n payload = parts[1]\n padding = len(payload) % 4\n if padding:\n payload += \"=\" * (4 - padding)\n\n decoded = base64.urlsafe_b64decode(payload)\n token_data = json.loads(decoded)\n\n exp = token_data.get(\"exp\")\n if not exp:\n logger.warning(\"Token does not have expiration field\")\n return\n\n exp_dt = datetime.fromtimestamp(exp, tz=UTC)\n now = datetime.now(UTC)\n time_until_expiry = exp_dt - now\n\n if time_until_expiry.total_seconds() < 0:\n logger.error(\"=\" * 80)\n logger.error(\"TOKEN EXPIRED\")\n logger.error(\"=\" * 80)\n logger.error(f\"Token expired at: {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n logger.error(f\"Current time is: {now.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n logger.error(f\"Token expired {abs(time_until_expiry.total_seconds())} seconds ago\")\n logger.error(\"\")\n logger.error(\"Please regenerate your token:\")\n logger.error(\" ./credentials-provider/generate_creds.sh\")\n logger.error(\"=\" * 80)\n sys.exit(1)\n elif time_until_expiry.total_seconds() < 120:\n seconds = int(time_until_expiry.total_seconds())\n logger.warning(\n f\"WARNING: Token will expire in {seconds} seconds at {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}\"\n )\n else:\n remaining_seconds = int(time_until_expiry.total_seconds())\n logger.info(\n f\"Token is valid until {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')} ({remaining_seconds} seconds remaining)\"\n )\n\n except Exception as e:\n logger.warning(f\"Could not check token expiration: {e}\")\n\n\ndef _load_token_file(token_file_path: Path) -> dict[str, Any]:\n \"\"\"\n Load token data from JSON file.\n\n Args:\n token_file_path: Path to token JSON file\n\n Returns:\n Token data dictionary\n \"\"\"\n try:\n with open(token_file_path) as f:\n token_data = json.load(f)\n logger.info(f\"Loaded token file: {token_file_path}\")\n return token_data\n except (OSError, json.JSONDecodeError) as e:\n logger.error(f\"Failed to load token file: {e}\")\n sys.exit(1)\n\n\ndef _make_api_request(\n endpoint: str,\n access_token: str,\n base_url: str,\n method: str = \"GET\",\n params: dict[str, Any] | None = None,\n) -> dict[str, Any] | None:\n \"\"\"\n Make an API request to the A2A Agents API.\n\n Args:\n endpoint: API endpoint\n access_token: JWT access token\n base_url: Base URL for the API\n method: HTTP method\n params: Query parameters\n\n Returns:\n Response JSON or None if request fails\n \"\"\"\n url = f\"{base_url}{endpoint}\"\n headers = {\"X-Authorization\": f\"Bearer {access_token}\", \"Content-Type\": \"application/json\"}\n\n try:\n logger.debug(f\"Making {method} request to: {url}\")\n response = requests.request(\n method=method, url=url, headers=headers, params=params, timeout=10\n )\n\n if response.status_code == 401:\n logger.warning(\"Received 401 Unauthorized\")\n return None\n\n response.raise_for_status()\n return response.json()\n\n except requests.exceptions.RequestException as e:\n logger.debug(f\"API request failed: {e}\")\n if hasattr(e, \"response\") and e.response is not None:\n logger.debug(f\"Response status: {e.response.status_code}\")\n logger.debug(f\"Response body: {e.response.text}\")\n return None\n\n\ndef _format_json_output(data: Any, verbose: bool = False) -> str:\n \"\"\"\n Format JSON output for display.\n\n Args:\n data: Data to format\n verbose: Whether to show full output\n\n Returns:\n Formatted JSON string\n \"\"\"\n if verbose:\n return json.dumps(data, indent=2)\n return json.dumps(data, indent=2)[:200] + (\"...\" if len(json.dumps(data)) > 200 else \"\")\n\n\ndef _print_test_result(result: TestResult, verbose: bool = False) -> None:\n \"\"\"\n Print formatted test result.\n\n Args:\n result: Test result object\n verbose: Whether to show full output\n \"\"\"\n status = \"PASS\" if result.passed else \"FAIL\"\n print(f\"[TEST] {result.test_name}: {status} ({result.duration_ms}ms)\")\n\n if result.message:\n print(f\" {result.message}\")\n\n if verbose and result.response:\n print(f\" Response: {_format_json_output(result.response, verbose=True)}\")\n\n if result.error:\n print(f\" Error: {result.error}\")\n\n print()\n\n\ndef _test_list_agents(access_token: str, base_url: str, limit: int = 10) -> TestResult:\n \"\"\"\n Test listing agents endpoint.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n limit: Number of agents to list\n\n Returns:\n Test result object\n \"\"\"\n result = TestResult(\"list-agents\")\n start_time = time.time()\n\n endpoint = f\"/{AGENTS_API_VERSION}/agents\"\n response = _make_api_request(\n endpoint=endpoint, access_token=access_token, base_url=base_url, params={\"limit\": limit}\n )\n\n result.duration_ms = int((time.time() - start_time) * 1000)\n\n if response:\n result.response = response\n result.passed = True\n agents = response.get(\"agents\", [])\n next_cursor = response.get(\"metadata\", {}).get(\"nextCursor\")\n result.message = f\"{len(agents)} agents returned\"\n if next_cursor:\n result.message += f\", nextCursor={next_cursor}\"\n else:\n result.error = \"Failed to list agents\"\n\n return result\n\n\ndef _test_list_agents_paginated(access_token: str, base_url: str, limit: int = 3) -> TestResult:\n \"\"\"\n Test pagination endpoint.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n limit: Number of agents per page\n\n Returns:\n Test result object\n \"\"\"\n result = TestResult(\"list-agents-paginated\")\n start_time = time.time()\n\n endpoint = f\"/{AGENTS_API_VERSION}/agents\"\n response = _make_api_request(\n endpoint=endpoint, access_token=access_token, base_url=base_url, params={\"limit\": limit}\n )\n\n result.duration_ms = int((time.time() - start_time) * 1000)\n\n if response:\n result.response = response\n result.passed = True\n agents = response.get(\"agents\", [])\n next_cursor = response.get(\"metadata\", {}).get(\"nextCursor\")\n result.message = f\"Page 1: {len(agents)} agents\"\n if next_cursor:\n result.message += \", nextCursor available\"\n else:\n result.error = \"Failed to list agents\"\n\n return result\n\n\ndef _test_get_agent(access_token: str, base_url: str, agent_name: str) -> TestResult:\n \"\"\"\n Test getting specific agent endpoint.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n agent_name: Agent name (URL-encoded or plain)\n\n Returns:\n Test result object\n \"\"\"\n result = TestResult(f\"get-agent ({agent_name})\")\n start_time = time.time()\n\n encoded_name = quote(agent_name, safe=\"\")\n endpoint = f\"/{AGENTS_API_VERSION}/agents/{encoded_name}\"\n response = _make_api_request(endpoint=endpoint, access_token=access_token, base_url=base_url)\n\n result.duration_ms = int((time.time() - start_time) * 1000)\n\n if response:\n result.response = response\n result.passed = True\n agent_data = response.get(\"agent\", {})\n name = agent_data.get(\"name\", agent_name)\n description = agent_data.get(\"description\", \"\")[:50]\n result.message = f\"Agent name={name}\"\n if description:\n result.message += f\", desc={description}...\"\n else:\n result.error = \"Failed to get agent\"\n\n return result\n\n\ndef _test_get_agent_versions(access_token: str, base_url: str, agent_name: str) -> TestResult:\n \"\"\"\n Test getting agent versions endpoint.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n agent_name: Agent name (URL-encoded or plain)\n\n Returns:\n Test result object\n \"\"\"\n result = TestResult(f\"get-agent-versions ({agent_name})\")\n start_time = time.time()\n\n encoded_name = quote(agent_name, safe=\"\")\n endpoint = f\"/{AGENTS_API_VERSION}/agents/{encoded_name}/versions\"\n response = _make_api_request(endpoint=endpoint, access_token=access_token, base_url=base_url)\n\n result.duration_ms = int((time.time() - start_time) * 1000)\n\n if response:\n result.response = response\n result.passed = True\n versions = response.get(\"versions\", [])\n result.message = f\"{len(versions)} versions found\"\n else:\n result.error = \"Failed to get agent versions\"\n\n return result\n\n\ndef _test_pagination_flow(access_token: str, base_url: str) -> TestResult:\n \"\"\"\n Test full pagination flow through pages.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n\n Returns:\n Test result object\n \"\"\"\n result = TestResult(\"pagination-flow\")\n start_time = time.time()\n\n endpoint = f\"/{AGENTS_API_VERSION}/agents\"\n all_agents = []\n cursor = None\n page_count = 0\n max_pages = 5\n\n try:\n while page_count < max_pages:\n params = {\"limit\": 3}\n if cursor:\n params[\"cursor\"] = cursor\n\n response = _make_api_request(\n endpoint=endpoint, access_token=access_token, base_url=base_url, params=params\n )\n\n if not response:\n result.error = \"Failed to fetch page\"\n break\n\n agents = response.get(\"agents\", [])\n all_agents.extend(agents)\n page_count += 1\n\n cursor = response.get(\"metadata\", {}).get(\"nextCursor\")\n if not cursor:\n break\n\n result.duration_ms = int((time.time() - start_time) * 1000)\n\n if all_agents:\n result.response = {\"agents\": all_agents[:3], \"total_collected\": len(all_agents)}\n result.passed = True\n result.message = f\"Collected {len(all_agents)} agents across {page_count} pages\"\n else:\n result.error = \"No agents found\"\n\n except Exception as e:\n result.error = str(e)\n\n return result\n\n\ndef _test_error_invalid_token(base_url: str) -> TestResult:\n \"\"\"\n Test error handling with invalid token.\n\n Args:\n base_url: Base URL for the API\n\n Returns:\n Test result object\n \"\"\"\n result = TestResult(\"error-invalid-token\")\n start_time = time.time()\n\n endpoint = f\"/{AGENTS_API_VERSION}/agents\"\n url = f\"{base_url}{endpoint}\"\n headers = {\"X-Authorization\": \"Bearer invalid_token_here\", \"Content-Type\": \"application/json\"}\n\n try:\n response = requests.get(url, headers=headers, timeout=10)\n result.duration_ms = int((time.time() - start_time) * 1000)\n\n if response.status_code == 401:\n result.passed = True\n result.message = \"Correctly returned 401 Unauthorized\"\n result.response = response.json() if response.text else {}\n else:\n result.error = f\"Expected 401, got {response.status_code}\"\n\n except requests.exceptions.RequestException as e:\n result.error = str(e)\n\n return result\n\n\ndef _test_error_missing_agent(access_token: str, base_url: str) -> TestResult:\n \"\"\"\n Test error handling with non-existent agent.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n\n Returns:\n Test result object\n \"\"\"\n result = TestResult(\"error-missing-agent\")\n start_time = time.time()\n\n endpoint = f\"/{AGENTS_API_VERSION}/agents/non-existent-agent-xyz-123\"\n url = f\"{base_url}{endpoint}\"\n headers = {\"X-Authorization\": f\"Bearer {access_token}\", \"Content-Type\": \"application/json\"}\n\n try:\n response = requests.get(url, headers=headers, timeout=10)\n result.duration_ms = int((time.time() - start_time) * 1000)\n\n if response.status_code == 404:\n result.passed = True\n result.message = \"Correctly returned 404 Not Found\"\n result.response = response.json() if response.text else {}\n else:\n result.error = f\"Expected 404, got {response.status_code}\"\n\n except requests.exceptions.RequestException as e:\n result.error = str(e)\n\n return result\n\n\ndef _run_all_tests(\n access_token: str, base_url: str, agent_name: str | None = None, verbose: bool = False\n) -> list[TestResult]:\n \"\"\"\n Run all API tests.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n agent_name: Optional agent name for specific tests\n verbose: Show verbose output\n\n Returns:\n List of test results\n \"\"\"\n logger.info(\"Running all API tests...\")\n results = []\n\n results.append(_test_list_agents(access_token, base_url, limit=10))\n _print_test_result(results[-1], verbose)\n\n time.sleep(0.5)\n\n results.append(_test_list_agents_paginated(access_token, base_url, limit=3))\n _print_test_result(results[-1], verbose)\n\n time.sleep(0.5)\n\n results.append(_test_pagination_flow(access_token, base_url))\n _print_test_result(results[-1], verbose)\n\n time.sleep(0.5)\n\n if agent_name:\n results.append(_test_get_agent(access_token, base_url, agent_name))\n _print_test_result(results[-1], verbose)\n\n time.sleep(0.5)\n\n results.append(_test_get_agent_versions(access_token, base_url, agent_name))\n _print_test_result(results[-1], verbose)\n\n time.sleep(0.5)\n\n results.append(_test_error_invalid_token(base_url))\n _print_test_result(results[-1], verbose)\n\n time.sleep(0.5)\n\n results.append(_test_error_missing_agent(access_token, base_url))\n _print_test_result(results[-1], verbose)\n\n return results\n\n\ndef _print_summary(results: list[TestResult]) -> None:\n \"\"\"\n Print test summary report.\n\n Args:\n results: List of test results\n \"\"\"\n passed = sum(1 for r in results if r.passed)\n total = len(results)\n status = \"ALL PASSED\" if passed == total else f\"{passed}/{total} PASSED\"\n\n print(\"=\" * 80)\n print(f\"[SUMMARY] {status}\")\n print(\"=\" * 80)\n for result in results:\n status_str = \"PASS\" if result.passed else \"FAIL\"\n print(f\" {result.test_name:<40} {status_str:<8} {result.duration_ms}ms\")\n\n\ndef _parse_arguments() -> argparse.Namespace:\n \"\"\"\n Parse command-line arguments.\n\n Returns:\n Parsed arguments\n \"\"\"\n parser = argparse.ArgumentParser(\n description=f\"Test A2A Agents API {AGENTS_API_VERSION}\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --test list-agents\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --test get-agent --agent-name test-agent\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --test pagination-flow --verbose\n uv run python cli/test_a2a_agents.py --token-file .oauth-tokens/ingress.json --base-url https://api.example.com --debug\n\nNote: If your token expires, generate a new one from the UI. Administrators can increase\ntoken lifetime in Keycloak: Realm Settings → Tokens → Access Token Lifespan\n\"\"\",\n )\n\n parser.add_argument(\n \"--token-file\",\n type=str,\n required=True,\n help=\"Path to token JSON file (e.g., .oauth-tokens/ingress.json)\",\n )\n\n parser.add_argument(\n \"--base-url\",\n type=str,\n default=DEFAULT_BASE_URL,\n help=f\"Base URL for API (default: {DEFAULT_BASE_URL})\",\n )\n\n parser.add_argument(\n \"--test\",\n type=str,\n choices=[\n \"all\",\n \"list-agents\",\n \"list-agents-paginated\",\n \"get-agent\",\n \"get-agent-versions\",\n \"pagination-flow\",\n \"error-invalid-token\",\n \"error-missing-agent\",\n ],\n default=\"all\",\n help=\"Which test to run (default: all)\",\n )\n\n parser.add_argument(\n \"--agent-name\", type=str, help=\"Agent name for get-agent or get-agent-versions tests\"\n )\n\n parser.add_argument(\n \"--verbose\", action=\"store_true\", help=\"Show detailed output including full responses\"\n )\n\n parser.add_argument(\"--debug\", action=\"store_true\", help=\"Enable debug logging\")\n\n return parser.parse_args()\n\n\ndef _execute_test(\n test_name: str, access_token: str, base_url: str, agent_name: str | None, verbose: bool\n) -> list[TestResult]:\n \"\"\"\n Execute a single test based on test name.\n\n Args:\n test_name: Name of test to execute\n access_token: JWT access token\n base_url: Base URL for API\n agent_name: Optional agent name\n verbose: Verbose output flag\n\n Returns:\n List of test results\n \"\"\"\n results = []\n\n if test_name == \"all\":\n results = _run_all_tests(access_token, base_url, agent_name, verbose)\n elif test_name == \"list-agents\":\n result = _test_list_agents(access_token, base_url)\n results.append(result)\n _print_test_result(result, verbose)\n elif test_name == \"list-agents-paginated\":\n result = _test_list_agents_paginated(access_token, base_url)\n results.append(result)\n _print_test_result(result, verbose)\n elif test_name == \"get-agent\":\n if not agent_name:\n logger.error(\"--agent-name required for get-agent test\")\n sys.exit(1)\n result = _test_get_agent(access_token, base_url, agent_name)\n results.append(result)\n _print_test_result(result, verbose)\n elif test_name == \"get-agent-versions\":\n if not agent_name:\n logger.error(\"--agent-name required for get-agent-versions test\")\n sys.exit(1)\n result = _test_get_agent_versions(access_token, base_url, agent_name)\n results.append(result)\n _print_test_result(result, verbose)\n elif test_name == \"pagination-flow\":\n result = _test_pagination_flow(access_token, base_url)\n results.append(result)\n _print_test_result(result, verbose)\n elif test_name == \"error-invalid-token\":\n result = _test_error_invalid_token(base_url)\n results.append(result)\n _print_test_result(result, verbose)\n elif test_name == \"error-missing-agent\":\n result = _test_error_missing_agent(access_token, base_url)\n results.append(result)\n _print_test_result(result, verbose)\n\n return results\n\n\ndef main():\n \"\"\"Main entry point.\"\"\"\n args = _parse_arguments()\n\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n logger.info(\"=\" * 80)\n logger.info(f\"A2A Agents API {AGENTS_API_VERSION} Test Tool\")\n logger.info(\"=\" * 80)\n\n token_file_path = Path(args.token_file)\n if not token_file_path.exists():\n logger.error(f\"Token file not found: {token_file_path}\")\n sys.exit(1)\n\n token_data = _load_token_file(token_file_path)\n\n access_token = None\n if \"tokens\" in token_data:\n access_token = token_data[\"tokens\"].get(\"access_token\")\n else:\n access_token = token_data.get(\"access_token\")\n\n if not access_token:\n logger.error(\"No access_token found in token file\")\n sys.exit(1)\n\n logger.info(\"Access token loaded successfully\")\n logger.info(f\"Base URL: {args.base_url}\")\n\n _check_token_expiration(access_token)\n\n results = _execute_test(args.test, access_token, args.base_url, args.agent_name, args.verbose)\n\n if results:\n _print_summary(results)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/test_anthropic_api.py", "content": "#!/usr/bin/env python3\n\"\"\"\nDEPRECATED: This script is deprecated in favor of the Registry Management API.\n\nUse instead:\n uv run python api/registry_management.py anthropic-list --help\n uv run python api/registry_management.py anthropic-get --help\n\nSee api/README.md for full documentation.\n\nTest Anthropic MCP Registry API.\n\nThis script tests the Anthropic MCP Registry API endpoints using JWT tokens\ngenerated from the MCP Registry UI.\n\nUsage:\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/mcp-registry-api-tokens-2025-10-12.json\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/ingress.json --base-url http://localhost\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/ingress.json --test list-servers\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/ingress.json --test get-server --server-name io.mcpgateway/atlassian\n\nNote: Tokens have a short lifetime for security. If your token expires, generate a new one\nfrom the UI or ask your administrator to increase the access token timeout in Keycloak.\n\"\"\"\n\nprint(\"=\" * 80)\nprint(\"WARNING: This script is DEPRECATED.\")\nprint(\"Please use the Registry Management API instead:\")\nprint(\" uv run python api/registry_management.py anthropic-list --help\")\nprint(\" uv run python api/registry_management.py anthropic-get --help\")\nprint(\"See api/README.md for full documentation.\")\nprint(\"=\" * 80)\nprint()\n\nimport argparse\nimport base64\nimport json\nimport logging\nimport sys\nimport time\nfrom datetime import UTC, datetime\nfrom pathlib import Path\nfrom typing import Any\n\nimport requests\n\n# Add project root to path to import constants\nSCRIPT_DIR = Path(__file__).parent\nPROJECT_ROOT = SCRIPT_DIR.parent\nsys.path.insert(0, str(PROJECT_ROOT))\n\nfrom registry.constants import REGISTRY_CONSTANTS\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nDEFAULT_BASE_URL: str = \"http://localhost\"\n\n\ndef _check_token_expiration(access_token: str) -> None:\n \"\"\"\n Check if JWT token is expired and exit with informative message if so.\n\n Args:\n access_token: JWT access token to check\n\n Exits:\n If token is expired or will expire soon\n \"\"\"\n try:\n # Decode JWT payload (without verification, just to check expiry)\n parts = access_token.split(\".\")\n if len(parts) != 3:\n logger.warning(\"Invalid JWT format, cannot check expiration\")\n return\n\n # Decode payload\n payload = parts[1]\n # Add padding if needed\n padding = len(payload) % 4\n if padding:\n payload += \"=\" * (4 - padding)\n\n decoded = base64.urlsafe_b64decode(payload)\n token_data = json.loads(decoded)\n\n # Check expiration\n exp = token_data.get(\"exp\")\n if not exp:\n logger.warning(\"Token does not have expiration field\")\n return\n\n exp_dt = datetime.fromtimestamp(exp, tz=UTC)\n now = datetime.now(UTC)\n time_until_expiry = exp_dt - now\n\n if time_until_expiry.total_seconds() < 0:\n # Token is expired\n logger.error(\"=\" * 80)\n logger.error(\"TOKEN EXPIRED\")\n logger.error(\"=\" * 80)\n logger.error(f\"Token expired at: {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n logger.error(f\"Current time is: {now.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n logger.error(f\"Token expired {abs(time_until_expiry.total_seconds())} seconds ago\")\n logger.error(\"\")\n logger.error(\"Please regenerate your token:\")\n logger.error(\" ./credentials-provider/generate_creds.sh\")\n logger.error(\"=\" * 80)\n sys.exit(1)\n elif time_until_expiry.total_seconds() < 60:\n # Token expires soon\n logger.warning(\n f\"Token will expire in {int(time_until_expiry.total_seconds())} seconds at {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')}\"\n )\n else:\n logger.info(\n f\"Token is valid until {exp_dt.strftime('%Y-%m-%d %H:%M:%S UTC')} ({int(time_until_expiry.total_seconds())} seconds remaining)\"\n )\n\n except Exception as e:\n logger.warning(f\"Could not check token expiration: {e}\")\n\n\ndef _load_token_file(token_file_path: Path) -> dict[str, Any]:\n \"\"\"\n Load token data from JSON file.\n\n Args:\n token_file_path: Path to token JSON file\n\n Returns:\n Token data dictionary\n \"\"\"\n try:\n with open(token_file_path) as f:\n token_data = json.load(f)\n logger.info(f\"Loaded token file: {token_file_path}\")\n return token_data\n except (OSError, json.JSONDecodeError) as e:\n logger.error(f\"Failed to load token file: {e}\")\n sys.exit(1)\n\n\ndef _save_token_file(token_file_path: Path, token_data: dict[str, Any]) -> None:\n \"\"\"\n Save updated token data to JSON file.\n\n Args:\n token_file_path: Path to token JSON file\n token_data: Token data dictionary\n \"\"\"\n try:\n with open(token_file_path, \"w\") as f:\n json.dump(token_data, f, indent=2)\n logger.info(f\"Saved updated tokens to: {token_file_path}\")\n except OSError as e:\n logger.error(f\"Failed to save token file: {e}\")\n\n\ndef _make_api_request(\n endpoint: str,\n access_token: str,\n base_url: str,\n method: str = \"GET\",\n params: dict[str, Any] | None = None,\n) -> dict[str, Any] | None:\n \"\"\"\n Make an API request to the Anthropic MCP Registry API.\n\n Args:\n endpoint: API endpoint (e.g., /{ANTHROPIC_API_VERSION}/servers)\n access_token: JWT access token\n base_url: Base URL for the API\n method: HTTP method\n params: Query parameters\n\n Returns:\n Response JSON or None if request fails\n \"\"\"\n url = f\"{base_url}{endpoint}\"\n\n headers = {\"X-Authorization\": f\"Bearer {access_token}\", \"Content-Type\": \"application/json\"}\n\n try:\n logger.info(f\"Making {method} request to: {url}\")\n response = requests.request(\n method=method, url=url, headers=headers, params=params, timeout=10\n )\n\n if response.status_code == 401:\n logger.warning(\"Received 401 Unauthorized - token may be expired\")\n return None\n\n response.raise_for_status()\n return response.json()\n\n except requests.exceptions.RequestException as e:\n logger.error(f\"API request failed: {e}\")\n if hasattr(e, \"response\") and e.response is not None:\n logger.error(f\"Response status: {e.response.status_code}\")\n logger.error(f\"Response body: {e.response.text}\")\n return None\n\n\ndef _test_list_servers(access_token: str, base_url: str, limit: int = 5) -> None:\n \"\"\"\n Test listing servers endpoint.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n limit: Number of servers to list\n \"\"\"\n logger.info(f\"Testing: List servers (limit={limit})\")\n\n result = _make_api_request(\n endpoint=f\"/{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION}/servers\",\n access_token=access_token,\n base_url=base_url,\n params={\"limit\": limit},\n )\n\n if result:\n print(\"\\n\" + \"=\" * 80)\n print(\"LIST SERVERS RESPONSE:\")\n print(\"=\" * 80)\n print(json.dumps(result, indent=2))\n print(\"=\" * 80 + \"\\n\")\n\n servers = result.get(\"servers\", [])\n logger.info(f\"Found {len(servers)} servers\")\n else:\n logger.error(\"Failed to list servers\")\n\n\ndef _test_get_server_versions(access_token: str, base_url: str, server_name: str) -> None:\n \"\"\"\n Test getting server versions endpoint.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n server_name: Server name (e.g., io.mcpgateway/atlassian)\n \"\"\"\n logger.info(f\"Testing: Get server versions for {server_name}\")\n\n encoded_name = server_name.replace(\"/\", \"%2F\")\n endpoint = f\"/{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION}/servers/{encoded_name}/versions\"\n\n result = _make_api_request(endpoint=endpoint, access_token=access_token, base_url=base_url)\n\n if result:\n print(\"\\n\" + \"=\" * 80)\n print(f\"SERVER VERSIONS RESPONSE: {server_name}\")\n print(\"=\" * 80)\n print(json.dumps(result, indent=2))\n print(\"=\" * 80 + \"\\n\")\n else:\n logger.error(f\"Failed to get versions for {server_name}\")\n\n\ndef _test_get_server_version_details(\n access_token: str, base_url: str, server_name: str, version: str = \"latest\"\n) -> None:\n \"\"\"\n Test getting server version details endpoint.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n server_name: Server name (e.g., io.mcpgateway/atlassian)\n version: Version (default: latest)\n \"\"\"\n logger.info(f\"Testing: Get server version details for {server_name} v{version}\")\n\n encoded_name = server_name.replace(\"/\", \"%2F\")\n endpoint = (\n f\"/{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION}/servers/{encoded_name}/versions/{version}\"\n )\n\n result = _make_api_request(endpoint=endpoint, access_token=access_token, base_url=base_url)\n\n if result:\n print(\"\\n\" + \"=\" * 80)\n print(f\"SERVER VERSION DETAILS: {server_name} v{version}\")\n print(\"=\" * 80)\n print(json.dumps(result, indent=2))\n print(\"=\" * 80 + \"\\n\")\n else:\n logger.error(f\"Failed to get version details for {server_name}\")\n\n\ndef _run_all_tests(access_token: str, base_url: str) -> None:\n \"\"\"\n Run all API tests.\n\n Args:\n access_token: JWT access token\n base_url: Base URL for the API\n \"\"\"\n logger.info(\"Running all API tests...\")\n\n _test_list_servers(access_token, base_url, limit=10)\n\n time.sleep(1)\n\n _test_get_server_versions(access_token, base_url, \"io.mcpgateway/atlassian\")\n\n time.sleep(1)\n\n _test_get_server_version_details(access_token, base_url, \"io.mcpgateway/atlassian\", \"latest\")\n\n logger.info(\"All tests completed\")\n\n\ndef main():\n \"\"\"Main entry point.\"\"\"\n parser = argparse.ArgumentParser(\n description=f\"Test Anthropic MCP Registry API {REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION}\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Run all tests with default settings\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/mcp-registry-api-tokens-2025-10-12.json\n\n # Test specific endpoint\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/ingress.json --test list-servers\n\n # Get server details\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/ingress.json --test get-server --server-name io.mcpgateway/atlassian\n\n # Custom base URL\n uv run python cli/test_anthropic_api.py --token-file .oauth-tokens/ingress.json --base-url https://mcpgateway.ddns.net\n\nNote: If your token expires, generate a new one from the UI. Administrators can increase\ntoken lifetime in Keycloak: Realm Settings → Tokens → Access Token Lifespan\n\"\"\",\n )\n\n parser.add_argument(\n \"--token-file\",\n type=str,\n required=True,\n help=\"Path to token JSON file (e.g., .oauth-tokens/mcp-registry-api-tokens-2025-10-12.json)\",\n )\n\n parser.add_argument(\n \"--base-url\",\n type=str,\n default=DEFAULT_BASE_URL,\n help=f\"Base URL for API (default: {DEFAULT_BASE_URL})\",\n )\n\n parser.add_argument(\n \"--test\",\n type=str,\n choices=[\"all\", \"list-servers\", \"get-versions\", \"get-server\"],\n default=\"all\",\n help=\"Which test to run (default: all)\",\n )\n\n parser.add_argument(\n \"--server-name\",\n type=str,\n help=\"Server name for get-versions or get-server tests (e.g., io.mcpgateway/atlassian)\",\n )\n\n parser.add_argument(\n \"--limit\", type=int, default=5, help=\"Number of servers to list (default: 5)\"\n )\n\n parser.add_argument(\"--debug\", action=\"store_true\", help=\"Enable debug logging\")\n\n args = parser.parse_args()\n\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n logger.info(\"=\" * 80)\n logger.info(f\"Anthropic MCP Registry API {REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION} Test Tool\")\n logger.info(\"=\" * 80)\n\n token_file_path = Path(args.token_file)\n if not token_file_path.exists():\n logger.error(f\"Token file not found: {token_file_path}\")\n sys.exit(1)\n\n token_data = _load_token_file(token_file_path)\n\n access_token = None\n\n if \"tokens\" in token_data:\n access_token = token_data[\"tokens\"].get(\"access_token\")\n else:\n access_token = token_data.get(\"access_token\")\n\n if not access_token:\n logger.error(\"No access_token found in token file\")\n sys.exit(1)\n\n logger.info(\"Access token loaded successfully\")\n logger.info(f\"Base URL: {args.base_url}\")\n\n # Check token expiration before making any API calls\n _check_token_expiration(access_token)\n\n if args.test == \"all\":\n _run_all_tests(access_token, args.base_url)\n elif args.test == \"list-servers\":\n _test_list_servers(access_token, args.base_url, args.limit)\n elif args.test == \"get-versions\":\n if not args.server_name:\n logger.error(\"--server-name required for get-versions test\")\n sys.exit(1)\n _test_get_server_versions(access_token, args.base_url, args.server_name)\n elif args.test == \"get-server\":\n if not args.server_name:\n logger.error(\"--server-name required for get-server test\")\n sys.exit(1)\n _test_get_server_version_details(access_token, args.base_url, args.server_name, \"latest\")\n\n # Note: Tokens have a short lifetime for security. If your token expires,\n # generate a new one from the UI or ask your administrator to increase\n # the access token timeout in Keycloak (Realm Settings → Tokens → Access Token Lifespan)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/test_asor_complete.py", "content": "#!/usr/bin/env python3\n\"\"\"\nComplete ASOR API test with token exchange\n\"\"\"\n\nimport json\nimport os\nimport urllib.parse\n\nimport requests\n\n# Configuration\nCLIENT_ID = os.getenv(\"ASOR_CLIENT_ID\")\nCLIENT_SECRET = os.getenv(\"ASOR_CLIENT_SECRET\")\nTENANT_NAME = os.getenv(\"ASOR_TENANT_NAME\")\nHOSTNAME = os.getenv(\"ASOR_HOSTNAME\")\nBASE_URL = f\"https://{HOSTNAME}/ccx/api/asor/v1/{TENANT_NAME}\"\n\n\ndef get_token():\n \"\"\"Get access token via OAuth flow\"\"\"\n print(\"🔑 OAuth Token Exchange\")\n print(\"=\" * 30)\n\n # Generate auth URL\n auth_url = f\"https://wcpdev.wd103.myworkday.com/{TENANT_NAME}/authorize\"\n params = {\n \"response_type\": \"code\",\n \"client_id\": CLIENT_ID,\n \"redirect_uri\": \"https://localhost:7860/callback\",\n \"scope\": \"Agent System of Record\",\n }\n\n print(f\"1. Visit: {auth_url}?{urllib.parse.urlencode(params)}\")\n auth_code = input(\"2. Enter authorization code: \").strip()\n\n if not auth_code:\n return None\n\n # Exchange code for token\n token_url = f\"https://{HOSTNAME}/ccx/oauth2/{TENANT_NAME}/token\"\n data = {\n \"grant_type\": \"authorization_code\",\n \"client_id\": CLIENT_ID,\n \"client_secret\": CLIENT_SECRET,\n \"code\": auth_code,\n \"redirect_uri\": \"https://localhost:7860/callback\",\n }\n\n try:\n response = requests.post(token_url, data=data, timeout=30)\n if response.status_code == 200:\n tokens = response.json()\n access_token = tokens.get(\"access_token\")\n masked_token = (\n f\"{access_token[:8]}...\" if access_token and len(access_token) > 8 else \"***\"\n )\n print(f\"✅ Token obtained: {masked_token}\")\n return access_token\n else:\n print(f\"❌ Token exchange failed: {response.status_code} - {response.text}\")\n return None\n except Exception as e:\n print(f\"❌ Error: {e}\")\n return None\n\n\ndef api_call(token, method, endpoint, data=None):\n \"\"\"Make ASOR API call\"\"\"\n headers = {\n \"Authorization\": f\"Bearer {token}\",\n \"Accept\": \"application/json\",\n \"Content-Type\": \"application/json\",\n }\n\n url = f\"{BASE_URL}{endpoint}\"\n print(url)\n\n try:\n if method == \"GET\":\n response = requests.get(url, headers=headers, timeout=15)\n elif method == \"POST\":\n response = requests.post(url, headers=headers, json=data, timeout=15)\n elif method == \"PUT\":\n response = requests.put(url, headers=headers, json=data, timeout=15)\n\n return response.status_code, response.text\n except Exception as e:\n return None, str(e)\n\n\ndef test_agent_definition_crud(token):\n \"\"\"Test Agent Definition CRUD operations\"\"\"\n print(\"\\n🤖 Testing Agent Definition API\")\n print(\"=\" * 40)\n\n # GET /agentDefinition (list agents)\n print(\"1. GET /agentDefinition (list existing agents)\")\n status, response = api_call(token, \"GET\", \"/agentDefinition\")\n\n if status == 200:\n print(\"✅ SUCCESS\")\n try:\n data = json.loads(response)\n print(f\" Found {data.get('total', 0)} agents\")\n print(\"dddddddddd\")\n print(json.dumps(data, indent=2))\n if data.get(\"data\"):\n agent = data[\"data\"][0] # Get first agent\n print(\"\\n 📋 Agent JSON (Pretty Printed):\")\n print(\" \" + \"=\" * 50)\n print(json.dumps(agent, indent=2))\n print(\" \" + \"=\" * 50)\n except Exception as e:\n print(f\"⚠️ Failed to parse agent list response: {e}\")\n else:\n print(f\"❌ Failed: {status} - {response[:200]}\")\n\n if status in [200, 201]:\n print(\"✅ Agent created successfully!\")\n print(f\" Response: {response[:200]}...\")\n elif status == 400:\n print(f\"⚠️ Bad Request: {response[:300]}\")\n elif status == 403:\n print(\"🚫 Forbidden - may need different permissions\")\n else:\n print(f\"❌ Failed: {status} - {response[:200]}\")\n\n\ndef main():\n print(\"🔍 Complete ASOR API Test Suite with OAuth\")\n print(\"=\" * 50)\n print(f\"Base URL: {BASE_URL}\")\n print()\n\n # Get access token\n token = get_token()\n if not token:\n print(\"❌ Failed to get access token\")\n return\n\n # Test main Agent Definition API\n test_agent_definition_crud(token)\n\n print(\"\\n📋 SUMMARY\")\n print(\"=\" * 50)\n print(\"✅ OAuth Flow: SUCCESS\")\n print(\"✅ ASOR API Base URL confirmed working\")\n print(\"✅ Agent Definition endpoint accessible\")\n print(\"✅ Ready for MCP Gateway integration\")\n\n print(\"\\n🔧 Final MCP Gateway Configuration:\")\n print(\"{\")\n print(' \"name\": \"workday-asor\",')\n print(f' \"url\": \"{BASE_URL}\",')\n print(' \"auth_type\": \"oauth_3lo\",')\n print(' \"oauth_config\": {')\n print(f' \"client_id\": \"{CLIENT_ID}\",')\n print(' \"client_secret\": \"***REDACTED***\",')\n print(f' \"auth_url\": \"https://wcpdev.wd103.myworkday.com/{TENANT_NAME}/authorize\",')\n print(f' \"token_url\": \"https://{HOSTNAME}/ccx/oauth2/{TENANT_NAME}/token\",')\n print(' \"scope\": \"Agent System of Record\"')\n print(\" }\")\n print(\"}\")\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "cli/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"jsx\": \"react-jsx\",\n \"lib\": [\n \"ES2022\",\n \"DOM\"\n ],\n \"strict\": true,\n \"esModuleInterop\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"skipLibCheck\": true,\n \"outDir\": \"dist\",\n \"rootDir\": \"src\",\n \"types\": [\n \"node\"\n ]\n },\n \"include\": [\n \"src/**/*\"\n ]\n}\n" }, { "path": "cli/user_mgmt.sh", "content": "#!/bin/bash\n# DEPRECATED: This script is deprecated in favor of the Registry Management API\n# Use: uv run python api/registry_management.py OR cli/registry_cli_wrapper.py\n# See: api/README.md for documentation\n#\n# User Management Script for MCP Gateway Registry\n# This script manages both M2M (machine-to-machine) service accounts and human users\n\necho \"WARNING: This script is DEPRECATED. Please use the Registry Management API instead:\"\necho \" uv run python api/registry_management.py --help\"\necho \" OR cli/registry_cli_wrapper.py --help\"\necho \"See api/README.md for full documentation.\"\necho \"\"\n\nset -e\n\n# Configuration\nADMIN_URL=\"http://localhost:8080\"\nREALM=\"mcp-gateway\"\nADMIN_USER=\"admin\"\nADMIN_PASS=\"${KEYCLOAK_ADMIN_PASSWORD}\"\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nOAUTH_TOKENS_DIR=\"$SCRIPT_DIR/../.oauth-tokens\"\nCLIENT_SECRETS_FILE=\"$OAUTH_TOKENS_DIR/keycloak-client-secrets.txt\"\n\n# Colors for output\nGREEN='\\033[0;32m'\nRED='\\033[0;31m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m'\n\n\n# Usage function\nusage() {\n echo \"Usage: $0 {create-m2m|create-human|delete-user|list-users|list-groups} [OPTIONS]\"\n echo \"\"\n echo \"Commands:\"\n echo \" create-m2m - Create M2M service account for machine-to-machine authentication\"\n echo \" create-human - Create human user with Keycloak login capabilities\"\n echo \" delete-user - Delete a user (M2M or human)\"\n echo \" list-users - List all users in the realm\"\n echo \" list-groups - List all available groups\"\n echo \"\"\n echo \"M2M Service Account Options:\"\n echo \" -n, --name NAME - Service account name (required)\"\n echo \" -g, --groups GROUPS - Comma-separated list of groups (required)\"\n echo \" -d, --description DESC - Description of the service account\"\n echo \"\"\n echo \"Human User Options:\"\n echo \" -u, --username USERNAME - Username (required)\"\n echo \" -e, --email EMAIL - Email address (required)\"\n echo \" -f, --firstname NAME - First name (required)\"\n echo \" -l, --lastname NAME - Last name (required)\"\n echo \" -g, --groups GROUPS - Comma-separated list of groups (required)\"\n echo \" -p, --password PASS - Initial password (optional, will prompt if not provided)\"\n echo \"\"\n echo \"Delete User Options:\"\n echo \" -u, --username USERNAME - Username to delete (required)\"\n echo \"\"\n echo \"Examples:\"\n echo \" # Create M2M service account\"\n echo \" $0 create-m2m --name agent-finance-bot --groups 'mcp-servers-finance/read,mcp-servers-finance/execute'\"\n echo \"\"\n echo \" # Create human user\"\n echo \" $0 create-human --username jdoe --email jdoe@example.com --firstname John --lastname Doe --groups 'mcp-servers-restricted/read'\"\n echo \"\"\n echo \" # Delete user\"\n echo \" $0 delete-user --username agent-finance-bot\"\n echo \"\"\n echo \" # List all users\"\n echo \" $0 list-users\"\n echo \"\"\n echo \" # List all groups\"\n echo \" $0 list-groups\"\n}\n\n\n# Function to get admin token\nget_admin_token() {\n if [ -z \"$ADMIN_PASS\" ]; then\n echo -e \"${RED}Error: KEYCLOAK_ADMIN_PASSWORD environment variable is required${NC}\"\n echo \"Please set it before running this script:\"\n echo \"export KEYCLOAK_ADMIN_PASSWORD=\\\"your-secure-password\\\"\"\n exit 1\n fi\n\n TOKEN=$(curl -s -X POST \"$ADMIN_URL/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=$ADMIN_USER\" \\\n -d \"password=$ADMIN_PASS\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token // empty')\n\n if [ -z \"$TOKEN\" ]; then\n echo -e \"${RED}Failed to get admin token${NC}\"\n exit 1\n fi\n}\n\n\n# Function to list all groups\nlist_groups() {\n echo -e \"${BLUE}Listing all groups in realm '$REALM'${NC}\"\n echo \"==============================================\"\n\n get_admin_token\n\n GROUPS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\")\n\n echo \"$GROUPS\" | jq -r '.[] | \"\\(.name) (ID: \\(.id))\"'\n\n echo \"\"\n echo -e \"${GREEN}Total groups: $(echo \"$GROUPS\" | jq '. | length')${NC}\"\n}\n\n\n# Function to list all users\nlist_users() {\n echo -e \"${BLUE}Listing all users in realm '$REALM'${NC}\"\n echo \"==============================================\"\n\n get_admin_token\n\n USERS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users\")\n\n echo \"$USERS\" | jq -r '.[] | \"Username: \\(.username), Email: \\(.email // \"N/A\"), Enabled: \\(.enabled), ID: \\(.id)\"'\n\n echo \"\"\n echo -e \"${GREEN}Total users: $(echo \"$USERS\" | jq '. | length')${NC}\"\n}\n\n\n# Function to check if group exists\ncheck_group_exists() {\n local group_name=\"$1\"\n\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$group_name\\\") | .id\")\n\n if [ -z \"$GROUP_ID\" ] || [ \"$GROUP_ID\" = \"null\" ]; then\n return 1\n fi\n return 0\n}\n\n\n# Function to validate groups\nvalidate_groups() {\n local groups_input=\"$1\"\n IFS=',' read -ra GROUPS_ARRAY <<< \"$groups_input\"\n\n local invalid_groups=()\n\n for group in \"${GROUPS_ARRAY[@]}\"; do\n group=$(echo \"$group\" | xargs) # trim whitespace\n if ! check_group_exists \"$group\"; then\n invalid_groups+=(\"$group\")\n fi\n done\n\n if [ ${#invalid_groups[@]} -gt 0 ]; then\n echo -e \"${RED}Error: The following groups do not exist:${NC}\"\n for group in \"${invalid_groups[@]}\"; do\n echo \" - $group\"\n done\n echo \"\"\n echo -e \"${YELLOW}Available groups:${NC}\"\n curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r '.[].name' | sed 's/^/ - /'\n return 1\n fi\n\n return 0\n}\n\n\n# Function to create M2M client\ncreate_m2m_client() {\n local client_id=\"$1\"\n local description=\"$2\"\n\n echo \"Creating M2M client: $client_id\"\n\n # Check if client already exists\n EXISTING_CLIENT=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients?clientId=$client_id\" | \\\n jq -r '.[0].id // empty')\n\n if [ -n \"$EXISTING_CLIENT\" ]; then\n echo -e \"${YELLOW}Client '$client_id' already exists, using existing client${NC}\"\n CLIENT_UUID=\"$EXISTING_CLIENT\"\n return 0\n fi\n\n # Create the client\n CLIENT_JSON=\"{\n \\\"clientId\\\": \\\"$client_id\\\",\n \\\"name\\\": \\\"$client_id\\\",\n \\\"description\\\": \\\"$description\\\",\n \\\"enabled\\\": true,\n \\\"clientAuthenticatorType\\\": \\\"client-secret\\\",\n \\\"serviceAccountsEnabled\\\": true,\n \\\"standardFlowEnabled\\\": false,\n \\\"directAccessGrantsEnabled\\\": false,\n \\\"publicClient\\\": false,\n \\\"protocol\\\": \\\"openid-connect\\\"\n }\"\n\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/clients\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$CLIENT_JSON\")\n\n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ M2M client created successfully${NC}\"\n\n # Get the client UUID\n CLIENT_UUID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients?clientId=$client_id\" | \\\n jq -r '.[0].id')\n\n echo \"Client UUID: $CLIENT_UUID\"\n else\n echo -e \"${RED}Failed to create M2M client. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n\n# Function to get client secret\nget_client_secret() {\n local client_uuid=\"$1\"\n\n CLIENT_SECRET=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$client_uuid/client-secret\" | \\\n jq -r '.value')\n\n if [ -z \"$CLIENT_SECRET\" ] || [ \"$CLIENT_SECRET\" = \"null\" ]; then\n echo -e \"${RED}Failed to retrieve client secret${NC}\"\n exit 1\n fi\n}\n\n\n# Function to add groups mapper to client\nadd_groups_mapper() {\n local client_uuid=\"$1\"\n\n echo \"Adding groups mapper to client...\"\n\n # Check if groups mapper already exists\n EXISTING_MAPPER=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$client_uuid/protocol-mappers/models\" | \\\n jq -r '.[] | select(.name==\"groups\") | .id')\n\n if [ -n \"$EXISTING_MAPPER\" ] && [ \"$EXISTING_MAPPER\" != \"null\" ]; then\n echo -e \"${GREEN}✓ Groups mapper already exists${NC}\"\n return 0\n fi\n\n GROUPS_MAPPER='{\n \"name\": \"groups\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-group-membership-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"full.path\": \"false\",\n \"id.token.claim\": \"true\",\n \"access.token.claim\": \"true\",\n \"claim.name\": \"groups\",\n \"userinfo.token.claim\": \"true\"\n }\n }'\n\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/clients/$client_uuid/protocol-mappers/models\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$GROUPS_MAPPER\")\n\n if [ \"$RESPONSE\" = \"201\" ] || [ \"$RESPONSE\" = \"409\" ]; then\n echo -e \"${GREEN}✓ Groups mapper configured${NC}\"\n else\n echo -e \"${RED}Failed to add groups mapper. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n\n# Function to get service account user ID\nget_service_account_user() {\n local client_uuid=\"$1\"\n\n SERVICE_ACCOUNT_USER=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$client_uuid/service-account-user\" | \\\n jq -r '.id')\n\n if [ -z \"$SERVICE_ACCOUNT_USER\" ] || [ \"$SERVICE_ACCOUNT_USER\" = \"null\" ]; then\n echo -e \"${RED}Failed to retrieve service account user${NC}\"\n exit 1\n fi\n}\n\n\n# Function to assign user to groups\nassign_user_to_groups() {\n local user_id=\"$1\"\n local groups_input=\"$2\"\n\n IFS=',' read -ra GROUPS_ARRAY <<< \"$groups_input\"\n\n for group in \"${GROUPS_ARRAY[@]}\"; do\n group=$(echo \"$group\" | xargs) # trim whitespace\n\n # Get group ID\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$group\\\") | .id\")\n\n if [ -z \"$GROUP_ID\" ] || [ \"$GROUP_ID\" = \"null\" ]; then\n echo -e \"${RED}Group '$group' not found${NC}\"\n continue\n fi\n\n # Assign to group\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"$ADMIN_URL/admin/realms/$REALM/users/$user_id/groups/$GROUP_ID\" \\\n -H \"Authorization: Bearer $TOKEN\")\n\n if [ \"$RESPONSE\" = \"204\" ]; then\n echo -e \"${GREEN}✓ Assigned to group: $group${NC}\"\n else\n echo -e \"${RED}Failed to assign to group '$group'. HTTP: $RESPONSE${NC}\"\n fi\n done\n}\n\n\n# Function to refresh all credentials using get-all-client-credentials.sh\nrefresh_all_credentials() {\n echo \"Refreshing all client credentials...\"\n\n # Call the existing script to regenerate all credential files\n # Run from project root so it saves to .oauth-tokens/ at the root\n PROJECT_ROOT=\"$SCRIPT_DIR/..\"\n KEYCLOAK_SETUP_SCRIPT=\"$PROJECT_ROOT/keycloak/setup/get-all-client-credentials.sh\"\n\n if [ -f \"$KEYCLOAK_SETUP_SCRIPT\" ]; then\n (cd \"$PROJECT_ROOT\" && ./keycloak/setup/get-all-client-credentials.sh)\n echo -e \"${GREEN}✓ All credentials refreshed${NC}\"\n else\n echo -e \"${RED}Error: get-all-client-credentials.sh not found at $KEYCLOAK_SETUP_SCRIPT${NC}\"\n exit 1\n fi\n}\n\n\n# Function to generate access token for M2M client\ngenerate_access_token() {\n local client_id=\"$1\"\n\n echo \"Generating access token for: $client_id\"\n\n # Call the existing script to generate token and .env files\n PROJECT_ROOT=\"$SCRIPT_DIR/..\"\n GENERATE_TOKEN_SCRIPT=\"$PROJECT_ROOT/keycloak/setup/generate-agent-token.sh\"\n\n if [ -f \"$GENERATE_TOKEN_SCRIPT\" ]; then\n (cd \"$PROJECT_ROOT/keycloak/setup\" && ./generate-agent-token.sh \"$client_id\")\n echo -e \"${GREEN}✓ Access token generated${NC}\"\n else\n echo -e \"${RED}Error: generate-agent-token.sh not found at $GENERATE_TOKEN_SCRIPT${NC}\"\n exit 1\n fi\n}\n\n\n# Function to create M2M service account\ncreate_m2m_account() {\n local name=\"\"\n local groups=\"\"\n local description=\"\"\n\n # Parse arguments\n while [[ $# -gt 0 ]]; do\n case $1 in\n -n|--name)\n name=\"$2\"\n shift 2\n ;;\n -g|--groups)\n groups=\"$2\"\n shift 2\n ;;\n -d|--description)\n description=\"$2\"\n shift 2\n ;;\n *)\n echo -e \"${RED}Unknown option: $1${NC}\"\n usage\n exit 1\n ;;\n esac\n done\n\n # Validate required parameters\n if [ -z \"$name\" ]; then\n echo -e \"${RED}Error: Service account name is required${NC}\"\n usage\n exit 1\n fi\n\n if [ -z \"$groups\" ]; then\n echo -e \"${RED}Error: Groups are required${NC}\"\n usage\n exit 1\n fi\n\n if [ -z \"$description\" ]; then\n description=\"M2M service account for $name\"\n fi\n\n CLIENT_ID=\"$name\"\n\n echo -e \"${BLUE}Creating M2M Service Account${NC}\"\n echo \"==============================================\"\n echo \"Name: $name\"\n echo \"Groups: $groups\"\n echo \"Description: $description\"\n echo \"\"\n\n # Get admin token\n get_admin_token\n\n # Validate groups\n if ! validate_groups \"$groups\"; then\n exit 1\n fi\n\n # Create M2M client\n create_m2m_client \"$CLIENT_ID\" \"$description\"\n\n # Add groups mapper\n add_groups_mapper \"$CLIENT_UUID\"\n\n # Get service account user\n get_service_account_user \"$CLIENT_UUID\"\n\n # Assign to groups\n assign_user_to_groups \"$SERVICE_ACCOUNT_USER\" \"$groups\"\n\n # Get client secret\n get_client_secret \"$CLIENT_UUID\"\n\n # Refresh all credentials using the existing script\n echo \"\"\n refresh_all_credentials\n\n # Generate access token and .env file\n echo \"\"\n generate_access_token \"$CLIENT_ID\"\n\n echo \"\"\n echo -e \"${GREEN}SUCCESS! M2M service account created${NC}\"\n echo \"==============================================\"\n echo \"Client ID: $CLIENT_ID\"\n echo \"Client Secret: $CLIENT_SECRET\"\n echo \"Groups: $groups\"\n echo \"\"\n echo -e \"${YELLOW}Credentials saved to:${NC}\"\n echo \" $OAUTH_TOKENS_DIR/${CLIENT_ID}.json (client credentials)\"\n echo \" $OAUTH_TOKENS_DIR/${CLIENT_ID}-token.json (access token)\"\n echo \" $OAUTH_TOKENS_DIR/${CLIENT_ID}.env (environment variables)\"\n echo \" $OAUTH_TOKENS_DIR/keycloak-client-secrets.txt (all client secrets)\"\n echo \"\"\n echo -e \"${YELLOW}Test the account:${NC}\"\n echo \"curl -X POST '$ADMIN_URL/realms/$REALM/protocol/openid-connect/token' \\\\\"\n echo \" -H 'Content-Type: application/x-www-form-urlencoded' \\\\\"\n echo \" -d 'grant_type=client_credentials' \\\\\"\n echo \" -d 'client_id=$CLIENT_ID' \\\\\"\n echo \" -d 'client_secret=$CLIENT_SECRET'\"\n}\n\n\n# Function to create human user\ncreate_human_user() {\n local username=\"\"\n local email=\"\"\n local firstname=\"\"\n local lastname=\"\"\n local groups=\"\"\n local password=\"\"\n\n # Parse arguments\n while [[ $# -gt 0 ]]; do\n case $1 in\n -u|--username)\n username=\"$2\"\n shift 2\n ;;\n -e|--email)\n email=\"$2\"\n shift 2\n ;;\n -f|--firstname)\n firstname=\"$2\"\n shift 2\n ;;\n -l|--lastname)\n lastname=\"$2\"\n shift 2\n ;;\n -g|--groups)\n groups=\"$2\"\n shift 2\n ;;\n -p|--password)\n password=\"$2\"\n shift 2\n ;;\n *)\n echo -e \"${RED}Unknown option: $1${NC}\"\n usage\n exit 1\n ;;\n esac\n done\n\n # Validate required parameters\n if [ -z \"$username\" ]; then\n echo -e \"${RED}Error: Username is required${NC}\"\n usage\n exit 1\n fi\n\n if [ -z \"$email\" ]; then\n echo -e \"${RED}Error: Email is required${NC}\"\n usage\n exit 1\n fi\n\n if [ -z \"$firstname\" ]; then\n echo -e \"${RED}Error: First name is required${NC}\"\n usage\n exit 1\n fi\n\n if [ -z \"$lastname\" ]; then\n echo -e \"${RED}Error: Last name is required${NC}\"\n usage\n exit 1\n fi\n\n if [ -z \"$groups\" ]; then\n echo -e \"${RED}Error: Groups are required${NC}\"\n usage\n exit 1\n fi\n\n # Prompt for password if not provided\n if [ -z \"$password\" ]; then\n echo -n \"Enter password for user: \"\n read -s password\n echo \"\"\n echo -n \"Confirm password: \"\n read -s password_confirm\n echo \"\"\n\n if [ \"$password\" != \"$password_confirm\" ]; then\n echo -e \"${RED}Error: Passwords do not match${NC}\"\n exit 1\n fi\n fi\n\n echo -e \"${BLUE}Creating Human User${NC}\"\n echo \"==============================================\"\n echo \"Username: $username\"\n echo \"Email: $email\"\n echo \"Name: $firstname $lastname\"\n echo \"Groups: $groups\"\n echo \"\"\n\n # Get admin token\n get_admin_token\n\n # Validate groups\n if ! validate_groups \"$groups\"; then\n exit 1\n fi\n\n # Check if user already exists\n EXISTING_USER=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$username\" | \\\n jq -r '.[0].id // empty')\n\n if [ -n \"$EXISTING_USER\" ]; then\n echo -e \"${RED}Error: User '$username' already exists${NC}\"\n exit 1\n fi\n\n # Create user\n USER_JSON=\"{\n \\\"username\\\": \\\"$username\\\",\n \\\"email\\\": \\\"$email\\\",\n \\\"firstName\\\": \\\"$firstname\\\",\n \\\"lastName\\\": \\\"$lastname\\\",\n \\\"enabled\\\": true,\n \\\"emailVerified\\\": true,\n \\\"credentials\\\": [{\n \\\"type\\\": \\\"password\\\",\n \\\"value\\\": \\\"$password\\\",\n \\\"temporary\\\": false\n }]\n }\"\n\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/users\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$USER_JSON\")\n\n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ User created successfully${NC}\"\n\n # Get the user ID\n USER_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$username\" | \\\n jq -r '.[0].id')\n\n echo \"User ID: $USER_ID\"\n\n # Assign to groups\n assign_user_to_groups \"$USER_ID\" \"$groups\"\n\n echo \"\"\n echo -e \"${GREEN}SUCCESS! Human user created${NC}\"\n echo \"==============================================\"\n echo \"Username: $username\"\n echo \"Email: $email\"\n echo \"Groups: $groups\"\n echo \"\"\n echo -e \"${YELLOW}User can login to Keycloak at:${NC}\"\n echo \"$ADMIN_URL/realms/$REALM/account\"\n echo \"\"\n echo -e \"${YELLOW}Or authenticate via API:${NC}\"\n echo \"curl -X POST '$ADMIN_URL/realms/$REALM/protocol/openid-connect/token' \\\\\"\n echo \" -H 'Content-Type: application/x-www-form-urlencoded' \\\\\"\n echo \" -d 'grant_type=password' \\\\\"\n echo \" -d 'client_id=mcp-gateway-m2m' \\\\\"\n echo \" -d 'username=$username' \\\\\"\n echo \" -d 'password=YOUR_PASSWORD'\"\n else\n echo -e \"${RED}Failed to create user. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n\n# Function to delete user\ndelete_user() {\n local username=\"\"\n\n # Parse arguments\n while [[ $# -gt 0 ]]; do\n case $1 in\n -u|--username)\n username=\"$2\"\n shift 2\n ;;\n *)\n echo -e \"${RED}Unknown option: $1${NC}\"\n usage\n exit 1\n ;;\n esac\n done\n\n # Validate required parameters\n if [ -z \"$username\" ]; then\n echo -e \"${RED}Error: Username is required${NC}\"\n usage\n exit 1\n fi\n\n echo -e \"${BLUE}Deleting User${NC}\"\n echo \"==============================================\"\n echo \"Username: $username\"\n echo \"\"\n\n # Get admin token\n get_admin_token\n\n # Find user\n USER_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$username\" | \\\n jq -r '.[0].id // empty')\n\n if [ -z \"$USER_ID\" ]; then\n echo -e \"${RED}Error: User '$username' not found${NC}\"\n exit 1\n fi\n\n # Delete user\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X DELETE \"$ADMIN_URL/admin/realms/$REALM/users/$USER_ID\" \\\n -H \"Authorization: Bearer $TOKEN\")\n\n if [ \"$RESPONSE\" = \"204\" ]; then\n echo -e \"${GREEN}✓ User deleted successfully${NC}\"\n\n # Refresh all credentials to update files\n echo \"\"\n refresh_all_credentials\n\n echo \"\"\n echo -e \"${GREEN}✓ Credential files updated${NC}\"\n else\n echo -e \"${RED}Failed to delete user. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n\n# Main execution\nmain() {\n if [ $# -eq 0 ]; then\n usage\n exit 1\n fi\n\n COMMAND=$1\n shift\n\n case $COMMAND in\n create-m2m)\n create_m2m_account \"$@\"\n ;;\n create-human)\n create_human_user \"$@\"\n ;;\n delete-user)\n delete_user \"$@\"\n ;;\n list-users)\n list_users\n ;;\n list-groups)\n list_groups\n ;;\n -h|--help|help)\n usage\n exit 0\n ;;\n *)\n echo -e \"${RED}Unknown command: $COMMAND${NC}\"\n usage\n exit 1\n ;;\n esac\n}\n\n# Run main function\nmain \"$@\"\n" }, { "path": "config/grafana/dashboards/dashboard.yml", "content": "apiVersion: 1\n\nproviders:\n - name: 'MCP Dashboards'\n orgId: 1\n folder: ''\n type: file\n disableDeletion: false\n updateIntervalSeconds: 10\n allowUiUpdates: true\n options:\n path: /etc/grafana/provisioning/dashboards" }, { "path": "config/grafana/dashboards/mcp-analytics-comprehensive.json", "content": "{\n \"id\": null,\n \"title\": \"MCP Gateway - Analytics Dashboard\",\n \"tags\": [\n \"mcp\",\n \"analytics\",\n \"auth\",\n \"tools\"\n ],\n \"timezone\": \"browser\",\n \"refresh\": \"30s\",\n \"time\": {\n \"from\": \"now-1h\",\n \"to\": \"now\"\n },\n \"panels\": [\n {\n \"id\": 1,\n \"title\": \"Real-time Protocol Activity\",\n \"type\": \"timeseries\",\n \"targets\": [\n {\n \"legendFormat\": \"Initialize Rate\",\n \"expr\": \"sum(increase(mcp_tool_executions_total{method=\\\"initialize\\\", success=\\\"true\\\"}[1m]))\"\n },\n {\n \"legendFormat\": \"Tools List Rate\",\n \"expr\": \"sum(increase(mcp_tool_executions_total{method=\\\"tools/list\\\", success=\\\"true\\\"}[1m]))\"\n },\n {\n \"legendFormat\": \"Tool Call Rate\",\n \"expr\": \"sum(increase(mcp_tool_executions_total{method=\\\"tools/call\\\", success=\\\"true\\\"}[1m]))\"\n },\n {\n \"legendFormat\": \"Auth Success Rate\",\n \"expr\": \"sum(increase(mcp_auth_requests_total{success=\\\"true\\\"}[1m]))\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 0,\n \"y\": 0\n },\n \"options\": {\n \"legend\": {\n \"displayMode\": \"table\",\n \"placement\": \"bottom\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"custom\": {\n \"axisLabel\": \"Requests per Second\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"reqps\"\n }\n }\n },\n {\n \"id\": 2,\n \"title\": \"Authentication Flow Analysis\",\n \"type\": \"timeseries\",\n \"targets\": [\n {\n \"expr\": \"sum(rate(mcp_auth_requests_total{success=\\\"true\\\"}[5m]))\",\n \"legendFormat\": \"Successful Auth\"\n },\n {\n \"expr\": \"sum(rate(mcp_auth_requests_total{success=\\\"false\\\"}[5m]))\",\n \"legendFormat\": \"Failed Auth\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 12,\n \"y\": 0\n },\n \"options\": {\n \"legend\": {\n \"displayMode\": \"table\",\n \"placement\": \"bottom\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"custom\": {\n \"axisLabel\": \"Auth Requests per Second\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"reqps\"\n }\n }\n },\n {\n \"id\": 3,\n \"title\": \"Authentication Success Rate\",\n \"type\": \"stat\",\n \"targets\": [\n {\n \"expr\": \"sum(mcp_auth_requests_total{success=\\\"true\\\"}) / sum(mcp_auth_requests_total) * 100\",\n \"legendFormat\": \"Success Rate %\"\n }\n ],\n \"gridPos\": {\n \"h\": 4,\n \"w\": 6,\n \"x\": 0,\n \"y\": 8\n },\n \"options\": {\n \"colorMode\": \"background\",\n \"graphMode\": \"area\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"unit\": \"percent\",\n \"thresholds\": {\n \"steps\": [\n {\n \"color\": \"red\",\n \"value\": 0\n },\n {\n \"color\": \"orange\",\n \"value\": 85\n },\n {\n \"color\": \"green\",\n \"value\": 95\n }\n ]\n }\n }\n }\n },\n {\n \"id\": 4,\n \"title\": \"Active MCP Servers\",\n \"type\": \"stat\",\n \"targets\": [\n {\n \"expr\": \"count(count by (server_name)(mcp_tool_executions_total))\",\n \"legendFormat\": \"Active Servers\"\n }\n ],\n \"gridPos\": {\n \"h\": 4,\n \"w\": 6,\n \"x\": 6,\n \"y\": 8\n },\n \"options\": {\n \"colorMode\": \"background\",\n \"graphMode\": \"area\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"thresholds\"\n },\n \"unit\": \"short\",\n \"thresholds\": {\n \"steps\": [\n {\n \"color\": \"blue\",\n \"value\": 0\n },\n {\n \"color\": \"green\",\n \"value\": 3\n },\n {\n \"color\": \"green\",\n \"value\": 10\n }\n ]\n }\n }\n }\n },\n {\n \"id\": 5,\n \"title\": \"Tool Executions per Hour\",\n \"type\": \"stat\",\n \"targets\": [\n {\n \"expr\": \"sum(increase(mcp_tool_executions_total[1h]))\",\n \"legendFormat\": \"Tools/Hour\"\n }\n ],\n \"gridPos\": {\n \"h\": 4,\n \"w\": 6,\n \"x\": 12,\n \"y\": 8\n },\n \"options\": {\n \"colorMode\": \"background\",\n \"graphMode\": \"area\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"thresholds\"\n },\n \"unit\": \"short\",\n \"thresholds\": {\n \"steps\": [\n {\n \"color\": \"blue\",\n \"value\": 0\n },\n {\n \"color\": \"blue\",\n \"value\": 50\n },\n {\n \"color\": \"blue\",\n \"value\": 100\n }\n ]\n }\n }\n }\n },\n {\n \"id\": 6,\n \"title\": \"Most Popular Tool\",\n \"type\": \"stat\",\n \"targets\": [\n {\n \"expr\": \"topk(1, sum(mcp_tool_executions_total{method=\\\"tools/call\\\"}) by (tool_name))\",\n \"legendFormat\": \"{{tool_name}}\"\n }\n ],\n \"gridPos\": {\n \"h\": 4,\n \"w\": 6,\n \"x\": 18,\n \"y\": 8\n },\n \"options\": {\n \"colorMode\": \"background\",\n \"textMode\": \"name\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"thresholds\"\n },\n \"thresholds\": {\n \"steps\": [\n {\n \"color\": \"purple\",\n \"value\": 0\n }\n ]\n }\n }\n }\n },\n {\n \"id\": 7,\n \"title\": \"MCP Latency P95 (by Server & Method)\",\n \"type\": \"timeseries\",\n \"targets\": [\n {\n \"expr\": \"histogram_quantile(0.95, sum by (le, server_name)(rate(mcp_tool_execution_duration_seconds_bucket[5m])))\",\n \"legendFormat\": \"{{server_name}} P95\"\n },\n {\n \"expr\": \"histogram_quantile(0.95, sum by (le, method)(rate(mcp_tool_execution_duration_seconds_bucket[5m])))\",\n \"legendFormat\": \"{{method}} P95\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 0,\n \"y\": 12\n },\n \"options\": {\n \"legend\": {\n \"displayMode\": \"table\",\n \"placement\": \"bottom\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"custom\": {\n \"axisLabel\": \"Latency (seconds)\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"s\"\n }\n }\n },\n {\n \"id\": 8,\n \"title\": \"Request Volume Over Time\",\n \"type\": \"timeseries\",\n \"targets\": [\n {\n \"expr\": \"sum(rate(mcp_tool_executions_total[5m])) by (method)\",\n \"legendFormat\": \"{{method}}\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 12,\n \"y\": 12\n },\n \"options\": {\n \"legend\": {\n \"displayMode\": \"table\",\n \"placement\": \"bottom\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"custom\": {\n \"axisLabel\": \"Requests per Second\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"reqps\"\n }\n }\n },\n {\n \"id\": 9,\n \"title\": \"Error Rate Analysis\",\n \"type\": \"timeseries\",\n \"targets\": [\n {\n \"legendFormat\": \"Auth Error Rate\",\n \"expr\": \"sum(increase(mcp_auth_requests_total{success=\\\"false\\\"}[5m])) / sum(increase(mcp_auth_requests_total[5m])) * 100\"\n },\n {\n \"legendFormat\": \"Tool Execution Error Rate\",\n \"expr\": \"sum(increase(mcp_tool_executions_total{success=\\\"false\\\"}[5m])) / sum(increase(mcp_tool_executions_total[5m])) * 100\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 0,\n \"y\": 20\n },\n \"options\": {\n \"legend\": {\n \"displayMode\": \"table\",\n \"placement\": \"bottom\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"custom\": {\n \"axisLabel\": \"Error Rate (%)\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"percent\",\n \"thresholds\": {\n \"steps\": [\n {\n \"color\": \"green\",\n \"value\": 0\n },\n {\n \"color\": \"yellow\",\n \"value\": 1\n },\n {\n \"color\": \"red\",\n \"value\": 5\n }\n ]\n }\n }\n }\n },\n {\n \"id\": 10,\n \"title\": \"Average Response Times\",\n \"type\": \"timeseries\",\n \"targets\": [\n {\n \"expr\": \"avg(rate(mcp_auth_request_duration_seconds_sum[5m])) / avg(rate(mcp_auth_request_duration_seconds_count[5m]))\",\n \"legendFormat\": \"Auth Avg Response Time\"\n },\n {\n \"expr\": \"avg(rate(mcp_tool_execution_duration_seconds_sum[5m])) / avg(rate(mcp_tool_execution_duration_seconds_count[5m]))\",\n \"legendFormat\": \"Tool Exec Avg Response Time\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 12,\n \"y\": 20\n },\n \"options\": {\n \"legend\": {\n \"displayMode\": \"table\",\n \"placement\": \"bottom\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"custom\": {\n \"axisLabel\": \"Response Time (seconds)\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"s\"\n }\n }\n },\n {\n \"id\": 11,\n \"title\": \"Server Performance Dashboard\",\n \"type\": \"table\",\n \"targets\": [\n {\n \"expr\": \"sum(mcp_tool_executions_total) by (server_name)\",\n \"legendFormat\": \"{{server_name}}_total_calls\",\n \"format\": \"table\",\n \"instant\": true\n },\n {\n \"expr\": \"sum(increase(mcp_tool_executions_total[1h])) by (server_name)\",\n \"legendFormat\": \"{{server_name}}_calls_per_hour\",\n \"format\": \"table\",\n \"instant\": true\n },\n {\n \"expr\": \"count(count by (server_name, tool_name)(mcp_tool_executions_total)) by (server_name)\",\n \"legendFormat\": \"{{server_name}}_unique_tools\",\n \"format\": \"table\",\n \"instant\": true\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 0,\n \"y\": 28\n },\n \"transformations\": [\n {\n \"id\": \"merge\",\n \"options\": {}\n },\n {\n \"id\": \"organize\",\n \"options\": {\n \"excludeByName\": {\n \"Time\": true\n },\n \"renameByName\": {\n \"server_name\": \"Server\",\n \"Value #A\": \"Total Calls\",\n \"Value #B\": \"Calls/Hour\",\n \"Value #C\": \"Unique Tools\"\n }\n }\n }\n ]\n },\n {\n \"id\": 12,\n \"title\": \"Tool Usage Rankings\",\n \"type\": \"table\",\n \"targets\": [\n {\n \"expr\": \"sum(mcp_tool_executions_total{method=\\\"tools/call\\\"}) by (tool_name)\",\n \"legendFormat\": \"{{tool_name}}\",\n \"format\": \"table\",\n \"instant\": true\n },\n {\n \"expr\": \"sum(increase(mcp_tool_executions_total{method=\\\"tools/call\\\"}[1h])) by (tool_name)\",\n \"legendFormat\": \"{{tool_name}}_rate\",\n \"format\": \"table\",\n \"instant\": true\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 12,\n \"y\": 28\n },\n \"transformations\": [\n {\n \"id\": \"merge\",\n \"options\": {}\n },\n {\n \"id\": \"organize\",\n \"options\": {\n \"excludeByName\": {\n \"Time\": true\n },\n \"renameByName\": {\n \"tool_name\": \"Tool Name\",\n \"Value #A\": \"Total Calls\",\n \"Value #B\": \"Calls/Hour\"\n }\n }\n }\n ],\n \"options\": {\n \"sortBy\": [\n {\n \"desc\": true,\n \"displayName\": \"Total Calls\"\n }\n ]\n }\n },\n {\n \"id\": 13,\n \"title\": \"MCP Protocol Methods Distribution\",\n \"type\": \"bargauge\",\n \"targets\": [\n {\n \"expr\": \"topk(10, sum(mcp_tool_executions_total{method!=\\\"tools/call\\\"}) by (method))\",\n \"legendFormat\": \"{{method}}\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 8,\n \"x\": 0,\n \"y\": 36\n },\n \"options\": {\n \"orientation\": \"horizontal\",\n \"displayMode\": \"gradient\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"palette-classic\"\n },\n \"custom\": {\n \"axisLabel\": \"Request Count\"\n },\n \"unit\": \"short\"\n }\n }\n },\n {\n \"id\": 14,\n \"title\": \"Tool Usage by Call Count\",\n \"type\": \"barchart\",\n \"targets\": [\n {\n \"expr\": \"topk(10, sum(mcp_tool_executions_total{method=\\\"tools/call\\\"}) by (tool_name))\",\n \"legendFormat\": \"{{tool_name}}\",\n \"instant\": true,\n \"format\": \"table\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 8,\n \"x\": 8,\n \"y\": 36\n },\n \"options\": {\n \"orientation\": \"vertical\",\n \"xTickLabelRotation\": -45,\n \"legend\": {\n \"displayMode\": \"hidden\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"palette-classic\"\n },\n \"custom\": {\n \"axisLabel\": \"Tool Call Count\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"short\"\n }\n }\n },\n {\n \"id\": 15,\n \"title\": \"Client Applications Distribution\",\n \"type\": \"bargauge\",\n \"targets\": [\n {\n \"expr\": \"topk(10, sum(mcp_tool_executions_total) by (client_name))\",\n \"legendFormat\": \"{{client_name}}\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 8,\n \"x\": 16,\n \"y\": 36\n },\n \"options\": {\n \"orientation\": \"horizontal\",\n \"displayMode\": \"gradient\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"palette-classic\"\n },\n \"custom\": {\n \"axisLabel\": \"Total Executions\"\n },\n \"unit\": \"short\"\n }\n }\n },\n {\n \"id\": 16,\n \"title\": \"MCP Protocol Flow Analysis\",\n \"type\": \"table\",\n \"targets\": [\n {\n \"expr\": \"sum(mcp_tool_executions_total{method=\\\"initialize\\\"}) by (client_name)\",\n \"legendFormat\": \"{{client_name}}_init\",\n \"format\": \"table\",\n \"instant\": true\n },\n {\n \"expr\": \"sum(mcp_tool_executions_total{method=\\\"tools/list\\\"}) by (client_name)\",\n \"legendFormat\": \"{{client_name}}_list\",\n \"format\": \"table\",\n \"instant\": true\n },\n {\n \"expr\": \"sum(mcp_tool_executions_total{method=\\\"tools/call\\\"}) by (client_name)\",\n \"legendFormat\": \"{{client_name}}_call\",\n \"format\": \"table\",\n \"instant\": true\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 0,\n \"y\": 44\n },\n \"transformations\": [\n {\n \"id\": \"merge\",\n \"options\": {}\n },\n {\n \"id\": \"organize\",\n \"options\": {\n \"excludeByName\": {\n \"Time\": true\n },\n \"renameByName\": {\n \"client_name\": \"Client\",\n \"Value #A\": \"Initialize\",\n \"Value #B\": \"Tools List\",\n \"Value #C\": \"Tool Calls\"\n }\n }\n }\n ]\n },\n {\n \"id\": 17,\n \"title\": \"Authentication Methods Distribution\",\n \"type\": \"bargauge\",\n \"targets\": [\n {\n \"expr\": \"sum(mcp_auth_requests_total) by (method)\",\n \"legendFormat\": \"{{method}}\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 12,\n \"y\": 44\n },\n \"options\": {\n \"orientation\": \"horizontal\",\n \"displayMode\": \"gradient\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"palette-classic\"\n },\n \"custom\": {\n \"axisLabel\": \"Request Count\"\n },\n \"unit\": \"short\"\n }\n }\n },\n {\n \"id\": 18,\n \"title\": \"Tool Execution Success Rate\",\n \"type\": \"timeseries\",\n \"targets\": [\n {\n \"legendFormat\": \"Success Rate\",\n \"expr\": \"sum(increase(mcp_tool_executions_total{success=\\\"true\\\"}[5m])) / sum(increase(mcp_tool_executions_total[5m])) * 100\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 0,\n \"y\": 52\n },\n \"options\": {\n \"legend\": {\n \"displayMode\": \"list\",\n \"placement\": \"bottom\"\n }\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"custom\": {\n \"axisLabel\": \"Success Rate (%)\",\n \"axisPlacement\": \"left\"\n },\n \"unit\": \"percent\",\n \"min\": 0,\n \"max\": 100,\n \"thresholds\": {\n \"mode\": \"absolute\",\n \"steps\": [\n {\n \"value\": 0,\n \"color\": \"red\"\n },\n {\n \"value\": 90,\n \"color\": \"yellow\"\n },\n {\n \"value\": 95,\n \"color\": \"green\"\n }\n ]\n }\n }\n }\n },\n {\n \"id\": 19,\n \"title\": \"Session Activity by Client\",\n \"type\": \"bargauge\",\n \"targets\": [\n {\n \"expr\": \"topk(15, sum(rate(mcp_tool_executions_total[5m])) by (client_name))\",\n \"legendFormat\": \"{{client_name}}\"\n }\n ],\n \"gridPos\": {\n \"h\": 8,\n \"w\": 12,\n \"x\": 12,\n \"y\": 52\n },\n \"options\": {\n \"orientation\": \"horizontal\",\n \"displayMode\": \"gradient\"\n },\n \"fieldConfig\": {\n \"defaults\": {\n \"color\": {\n \"mode\": \"continuous-GrYlRd\"\n },\n \"custom\": {\n \"axisLabel\": \"Activity Rate (req/s)\"\n },\n \"unit\": \"reqps\"\n }\n }\n }\n ],\n \"templating\": {\n \"list\": [\n {\n \"name\": \"server\",\n \"type\": \"query\",\n \"query\": \"label_values(mcp_auth_requests_total, server)\",\n \"refresh\": 1,\n \"includeAll\": true,\n \"allValue\": \".*\"\n },\n {\n \"name\": \"client\",\n \"type\": \"query\",\n \"query\": \"label_values(mcp_tool_executions_total, client_name)\",\n \"refresh\": 1,\n \"includeAll\": true,\n \"allValue\": \".*\"\n },\n {\n \"name\": \"method\",\n \"type\": \"query\",\n \"query\": \"label_values(mcp_tool_executions_total, method)\",\n \"refresh\": 1,\n \"includeAll\": true,\n \"allValue\": \".*\"\n }\n ]\n },\n \"schemaVersion\": 16,\n \"version\": 1\n}\n" }, { "path": "config/grafana/datasources/prometheus.yml", "content": "apiVersion: 1\n\ndatasources:\n - name: Prometheus\n type: prometheus\n access: proxy\n url: http://prometheus:9090\n isDefault: true\n editable: true" }, { "path": "config/prometheus.yml", "content": "global:\n scrape_interval: 15s\n evaluation_interval: 15s\n\nscrape_configs:\n - job_name: 'prometheus'\n static_configs:\n - targets: ['localhost:9090']\n\n - job_name: 'mcp-metrics-service'\n static_configs:\n - targets: ['metrics-service:9465']\n scrape_interval: 10s\n metrics_path: /metrics\n \n" }, { "path": "credentials-provider/add_noauth_services.py", "content": "#!/usr/bin/env python3\n\"\"\"\nAdd No-Auth Services to MCP Configuration\n\nThis script scans the registry/servers JSON files and adds services with\nauth_scheme: \"none\" to the MCP configuration files (vscode_mcp.json and mcp.json).\nThese services only require ingress authentication headers for access.\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nfrom pathlib import Path\nfrom typing import Any\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _load_env_file() -> None:\n \"\"\"Load environment variables from .env file in project root.\"\"\"\n # Get the project root directory (parent of credentials-provider)\n script_dir = Path(__file__).parent\n project_root = script_dir.parent\n env_file = project_root / \".env\"\n\n if env_file.exists():\n try:\n with open(env_file) as f:\n for line in f:\n line = line.strip()\n if line and not line.startswith(\"#\") and \"=\" in line:\n key, value = line.split(\"=\", 1)\n # Remove quotes if present\n value = value.strip('\"').strip(\"'\")\n os.environ[key] = value\n logger.debug(f\"Loaded environment variables from {env_file}\")\n except Exception as e:\n logger.warning(f\"Failed to load .env file: {e}\")\n else:\n logger.debug(f\"No .env file found at {env_file}\")\n\n\ndef _load_json_file(file_path: Path) -> dict[str, Any] | None:\n \"\"\"Load and parse a JSON file safely.\"\"\"\n try:\n with open(file_path, encoding=\"utf-8\") as f:\n return json.load(f)\n except (FileNotFoundError, json.JSONDecodeError) as e:\n logger.error(f\"Failed to load {file_path}: {type(e).__name__}\")\n return None\n\n\ndef _save_json_file(file_path: Path, data: dict[str, Any], description: str) -> None:\n \"\"\"Save data to JSON file safely.\"\"\"\n try:\n with open(file_path, \"w\", encoding=\"utf-8\") as f:\n json.dump(data, f, indent=2, ensure_ascii=False)\n os.chmod(file_path, 0o600)\n logger.info(f\"Updated {description}: {file_path}\")\n except Exception as e:\n logger.error(f\"Failed to save {description} to {file_path}: {type(e).__name__}\")\n\n\ndef _get_registry_servers_dir() -> Path:\n \"\"\"Get the path to the registry servers directory.\"\"\"\n script_dir = Path(__file__).parent\n registry_dir = script_dir.parent / \"registry\" / \"servers\"\n\n if not registry_dir.exists():\n raise FileNotFoundError(f\"Registry servers directory not found: {registry_dir}\")\n\n return registry_dir\n\n\ndef _get_oauth_tokens_dir() -> Path:\n \"\"\"Get the path to the oauth tokens directory.\"\"\"\n script_dir = Path(__file__).parent\n tokens_dir = script_dir.parent / \".oauth-tokens\"\n\n if not tokens_dir.exists():\n tokens_dir.mkdir(mode=0o700, parents=True)\n logger.info(f\"Created oauth tokens directory: {tokens_dir}\")\n\n return tokens_dir\n\n\ndef _scan_noauth_services() -> list[dict[str, Any]]:\n \"\"\"Scan registry servers and find services with auth_scheme: none.\"\"\"\n registry_dir = _get_registry_servers_dir()\n noauth_services = []\n\n logger.info(f\"Scanning registry servers directory: {registry_dir}\")\n\n for json_file in registry_dir.glob(\"*.json\"):\n # Skip server_state.json as requested\n if json_file.name == \"server_state.json\":\n continue\n\n server_config = _load_json_file(json_file)\n if not server_config:\n continue\n\n # Backward-compatible read: prefer auth_scheme, fall back to auth_type\n auth_scheme = server_config.get(\"auth_scheme\", server_config.get(\"auth_type\", \"none\"))\n if auth_scheme == \"none\":\n # Extract relevant service information\n service = {\n \"server_name\": server_config.get(\"server_name\", \"Unknown\"),\n \"path\": server_config.get(\"path\", \"\"),\n \"proxy_pass_url\": server_config.get(\"proxy_pass_url\", \"\"),\n \"supported_transports\": server_config.get(\n \"supported_transports\", [\"streamable-http\"]\n ),\n \"description\": server_config.get(\"description\", \"\"),\n \"file_name\": json_file.name,\n }\n noauth_services.append(service)\n logger.info(f\"Found no-auth service: {service['server_name']} ({service['path']})\")\n\n return noauth_services\n\n\ndef _get_ingress_headers() -> dict[str, str] | None:\n \"\"\"Get ingress authentication headers from tokens file.\"\"\"\n tokens_dir = _get_oauth_tokens_dir()\n ingress_file = tokens_dir / \"ingress.json\"\n\n # Check AUTH_PROVIDER from environment\n auth_provider = os.environ.get(\"AUTH_PROVIDER\", \"\")\n\n if auth_provider == \"keycloak\":\n # When using Keycloak, get token from agent token file\n agent_token_file = tokens_dir / \"agent-ai-coding-assistant-m2m-token.json\"\n if agent_token_file.exists():\n agent_data = _load_json_file(agent_token_file)\n if agent_data and agent_data.get(\"access_token\"):\n logger.debug(\"Using Keycloak agent token for ingress authentication\")\n headers = {\"X-Authorization\": f\"Bearer {agent_data.get('access_token', '')}\"}\n return headers\n\n # If no Keycloak token found, fall through to check ingress.json\n logger.warning(\"No Keycloak agent token found, trying ingress.json\")\n\n if not ingress_file.exists():\n if auth_provider == \"keycloak\":\n logger.warning(\n \"No ingress.json or Keycloak agent token found - no-auth services will have no headers\"\n )\n else:\n logger.warning(\"No ingress.json file found - no-auth services will have no headers\")\n return None\n\n ingress_data = _load_json_file(ingress_file)\n if not ingress_data:\n return None\n\n headers = {\n \"X-Authorization\": f\"Bearer {ingress_data.get('access_token', '')}\",\n \"X-User-Pool-Id\": ingress_data.get(\"user_pool_id\", \"\"),\n \"X-Client-Id\": ingress_data.get(\"client_id\", \"\"),\n \"X-Region\": ingress_data.get(\"region\", \"us-east-1\"),\n }\n\n return headers\n\n\ndef _update_vscode_config(\n noauth_services: list[dict[str, Any]], ingress_headers: dict[str, str] | None\n) -> None:\n \"\"\"Update VS Code MCP configuration with no-auth services.\"\"\"\n tokens_dir = _get_oauth_tokens_dir()\n vscode_file = tokens_dir / \"vscode_mcp.json\"\n\n # Load existing config or create new one\n config = _load_json_file(vscode_file) or {\"mcp\": {\"servers\": {}}}\n\n # Ensure structure exists\n if \"mcp\" not in config:\n config[\"mcp\"] = {}\n if \"servers\" not in config[\"mcp\"]:\n config[\"mcp\"][\"servers\"] = {}\n\n registry_url = os.environ.get(\"REGISTRY_URL\", \"https://mcpgateway.ddns.net\")\n\n # Add no-auth services\n for service in noauth_services:\n # Use path as server key (remove leading and trailing slashes)\n server_key = service[\"path\"].strip(\"/\")\n if not server_key:\n continue\n\n # Construct service URL (handle trailing slashes properly)\n path = service[\"path\"].rstrip(\"/\")\n # Check if this server should skip the /mcp suffix (e.g., atlassian)\n servers_no_mcp_suffix = [\"/atlassian\"]\n if path in servers_no_mcp_suffix:\n service_url = f\"{registry_url}{path}\"\n else:\n service_url = f\"{registry_url}{path}/mcp\"\n\n # Create server configuration\n server_config = {\"url\": service_url}\n\n # Add headers if ingress auth is available\n if ingress_headers:\n server_config[\"headers\"] = ingress_headers.copy()\n\n config[\"mcp\"][\"servers\"][server_key] = server_config\n logger.info(f\"Added {server_key} to VS Code config\")\n\n _save_json_file(vscode_file, config, \"VS Code MCP configuration\")\n\n\ndef _update_roocode_config(\n noauth_services: list[dict[str, Any]], ingress_headers: dict[str, str] | None\n) -> None:\n \"\"\"Update Roocode MCP configuration with no-auth services.\"\"\"\n tokens_dir = _get_oauth_tokens_dir()\n roocode_file = tokens_dir / \"mcp.json\"\n\n # Load existing config or create new one\n config = _load_json_file(roocode_file) or {\"mcpServers\": {}}\n\n # Ensure structure exists\n if \"mcpServers\" not in config:\n config[\"mcpServers\"] = {}\n\n registry_url = os.environ.get(\"REGISTRY_URL\", \"https://mcpgateway.ddns.net\")\n\n # Add no-auth services\n for service in noauth_services:\n # Use path as server key (remove leading and trailing slashes)\n server_key = service[\"path\"].strip(\"/\")\n if not server_key:\n continue\n\n # Construct service URL (handle trailing slashes properly)\n path = service[\"path\"].rstrip(\"/\")\n # Check if this server should skip the /mcp suffix (e.g., atlassian)\n servers_no_mcp_suffix = [\"/atlassian\"]\n if path in servers_no_mcp_suffix:\n service_url = f\"{registry_url}{path}\"\n else:\n service_url = f\"{registry_url}{path}/mcp\"\n\n # Determine transport type\n supported_transports = service.get(\"supported_transports\", [\"streamable-http\"])\n transport_type = supported_transports[0] if supported_transports else \"streamable-http\"\n\n # Create server configuration\n server_config = {\n \"type\": transport_type,\n \"url\": service_url,\n \"disabled\": False,\n \"alwaysAllow\": [],\n }\n\n # Add headers if ingress auth is available\n if ingress_headers:\n server_config[\"headers\"] = ingress_headers.copy()\n\n config[\"mcpServers\"][server_key] = server_config\n logger.info(f\"Added {server_key} to Roocode config ({transport_type})\")\n\n _save_json_file(roocode_file, config, \"Roocode MCP configuration\")\n\n\ndef _parse_arguments() -> argparse.Namespace:\n \"\"\"Parse command line arguments.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Add no-auth services to MCP configurations\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n\n parser.add_argument(\"--verbose\", \"-v\", action=\"store_true\", help=\"Enable verbose debug logging\")\n\n return parser.parse_args()\n\n\ndef main() -> None:\n \"\"\"Main function to add no-auth services to MCP configurations.\"\"\"\n try:\n # Load environment variables from .env file\n _load_env_file()\n\n # Parse command line arguments\n args = _parse_arguments()\n\n # Set logging level based on verbose flag\n if args.verbose:\n logging.getLogger().setLevel(logging.DEBUG)\n logger.debug(\"Verbose logging enabled\")\n\n logger.info(\"🔍 Starting no-auth services discovery and configuration update\")\n\n # Scan for no-auth services\n noauth_services = _scan_noauth_services()\n\n if not noauth_services:\n logger.info(\"No services with auth_scheme: 'none' found\")\n return\n\n logger.info(f\"Found {len(noauth_services)} no-auth services\")\n\n # Get ingress authentication headers\n ingress_headers = _get_ingress_headers()\n\n if ingress_headers:\n logger.info(\"Using ingress authentication headers for no-auth services\")\n else:\n logger.warning(\"No ingress authentication available - services will have no headers\")\n\n # Update both MCP configuration files\n _update_vscode_config(noauth_services, ingress_headers)\n _update_roocode_config(noauth_services, ingress_headers)\n\n logger.info(\"✅ Successfully updated MCP configurations with no-auth services\")\n\n except Exception as e:\n logger.error(f\"Failed to update MCP configurations: {e}\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "credentials-provider/agentcore-auth/.env.example", "content": "# AgentCore Gateway Access Token Configuration\n# Copy this file to .env and update with your values\n\n# =============================================================================\n# SINGLETON COGNITO CONFIGURATION\n# =============================================================================\n# Amazon Cognito Configuration - shared across all gateways\nCOGNITO_DOMAIN=https://your-cognito-domain.auth.region.amazoncognito.com\nCOGNITO_USER_POOL_ID=region_your_pool_id\n\n# Alternative: Auth0 or Other OAuth Provider Configuration\n# OAUTH_DOMAIN=https://your-domain.auth0.com\n\n# =============================================================================\n# GATEWAY-SPECIFIC CONFIGURATIONS\n# =============================================================================\n# Support for multiple gateways with _1, _2, _3, etc. suffixes (up to _100)\n# Each configuration set requires all four parameters\n\n# Configuration Set 1\nAGENTCORE_CLIENT_ID_1=your_client_id_here\nAGENTCORE_CLIENT_SECRET_1=your_client_secret_here\nAGENTCORE_GATEWAY_ARN_1=arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-1\nAGENTCORE_SERVER_NAME_1=my-gateway-1\n\n# Configuration Set 2 (uncomment and configure as needed)\n# AGENTCORE_CLIENT_ID_2=your_client_id_here\n# AGENTCORE_CLIENT_SECRET_2=your_client_secret_here\n# AGENTCORE_GATEWAY_ARN_2=arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-2\n# AGENTCORE_SERVER_NAME_2=my-gateway-2\n\n# Configuration Set 3 (uncomment and configure as needed)\n# AGENTCORE_CLIENT_ID_3=your_client_id_here\n# AGENTCORE_CLIENT_SECRET_3=your_client_secret_here\n# AGENTCORE_GATEWAY_ARN_3=arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-3\n# AGENTCORE_SERVER_NAME_3=my-gateway-3" }, { "path": "credentials-provider/agentcore-auth/README.md", "content": "# AgentCore Gateway Access Token Utility\n\nA standalone utility for generating OAuth2 access tokens for existing Amazon Bedrock AgentCore Gateways.\n\n## Overview\n\nThis utility extracts the essential token generation functionality from the main SRE Agent gateway scripts, allowing you to easily generate access tokens for existing gateways without needing the full gateway creation infrastructure.\n\n## Features\n\n- Generate OAuth2 access tokens for existing AgentCore Gateways\n- Support for Amazon Cognito and Auth0 OAuth providers\n- Flexible configuration via YAML files and environment variables\n- Minimal dependencies for easy deployment\n- Command-line interface with comprehensive options\n\n## Prerequisites\n\n- Python 3.14+\n- AWS credentials configured (if using Cognito)\n- Access to the OAuth provider (Cognito User Pool or Auth0)\n- Client ID and Client Secret for your OAuth application\n\n## Installation\n\n1. Copy the `agentcore` folder to your desired location\n2. Install dependencies:\n ```bash\n cd agentcore\n uv install\n # or with pip:\n pip install -r requirements.txt\n ```\n\n## Configuration\n\n### Option 1: Configuration File\n\nCreate or edit `config.yaml`:\n\n```yaml\n# Gateway Configuration (optional, for reference)\ngateway_arn: \"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/your-gateway-id\"\n\n# Cognito Configuration\nuser_pool_id: \"us-west-2_abcdef123\"\nclient_id: \"your_cognito_client_id\"\n\n# OAuth Configuration (alternative to Cognito)\n# oauth_domain: \"https://your-domain.auth0.com\"\n# oauth_client_id: \"your_oauth_client_id\"\n# oauth_audience: \"MCPGateway\"\n```\n\n### Option 2: Environment Variables\n\nCreate a `.env` file:\n\n```env\n# For Cognito\nCOGNITO_DOMAIN=https://cognito-idp.us-west-2.amazonaws.com/us-west-2_abcdef123\nCOGNITO_CLIENT_ID=your_cognito_client_id\nCOGNITO_CLIENT_SECRET=your_cognito_client_secret\n\n# For Auth0 or other OAuth providers\n# OAUTH_DOMAIN=https://your-domain.auth0.com\n# OAUTH_CLIENT_ID=your_oauth_client_id\n# OAUTH_CLIENT_SECRET=your_oauth_client_secret\n```\n\n## Usage\n\n### Basic Usage\n\nGenerate a token using configuration file and environment variables:\n\n```bash\npython get_m2m_token.py\n```\n\n### Advanced Usage\n\n```bash\n# Specify gateway ARN for reference\npython get_m2m_token.py --gateway-arn arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway\n\n# Use custom config file\npython get_m2m_token.py --config-file my-config.yaml\n\n# Save token to custom file\npython get_m2m_token.py --output-file my-token.txt\n\n# Use custom audience for Auth0\npython get_m2m_token.py --audience \"https://api.mycompany.com\"\n\n# Enable debug logging\npython get_m2m_token.py --debug\n```\n\n### Using as a Module\n\n```python\nfrom generate_access_token import generate_access_token\n\n# Generate token programmatically\ngenerate_access_token(\n gateway_arn=\"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway\",\n output_file=\"my_token.txt\"\n)\n```\n\n## Configuration Priority\n\nThe utility uses the following priority order for configuration:\n\n1. Environment variables (highest priority)\n2. Configuration file values\n3. Command-line arguments\n4. Default values (lowest priority)\n\n## Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `COGNITO_DOMAIN` | Full Cognito domain URL | Yes* |\n| `COGNITO_CLIENT_ID` | Cognito App Client ID | Yes |\n| `COGNITO_CLIENT_SECRET` | Cognito App Client Secret | Yes |\n| `OAUTH_DOMAIN` | OAuth provider domain (Auth0, etc.) | Yes* |\n| `OAUTH_CLIENT_ID` | OAuth client ID | Yes* |\n| `OAUTH_CLIENT_SECRET` | OAuth client secret | Yes* |\n\n*Either Cognito or OAuth variables are required, not both.\n\n## Output\n\nThe utility generates:\n- `.access_token` file containing the access token (default)\n- Console output with token expiration information\n- Logs showing the generation process\n\n## Example Output\n\n```\n2024-07-31 10:30:15,p12345,{get_m2m_token.py:89},INFO,Loaded configuration from config.yaml\n2024-07-31 10:30:15,p12345,{get_m2m_token.py:156},INFO,Generating OAuth2 access token...\n2024-07-31 10:30:16,p12345,{get_m2m_token.py:76},INFO,Successfully obtained Cognito access token\n2024-07-31 10:30:16,p12345,{get_m2m_token.py:98},INFO,Access token saved to .access_token\n2024-07-31 10:30:16,p12345,{get_m2m_token.py:100},INFO,Token expires in 3600 seconds\n2024-07-31 10:30:16,p12345,{get_m2m_token.py:178},INFO,Token generation completed successfully! Token saved to .access_token\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Missing environment variables**\n ```\n ERROR: Missing required parameters: COGNITO_CLIENT_SECRET\n ```\n Solution: Ensure all required environment variables are set in your `.env` file.\n\n2. **Invalid User Pool ID**\n ```\n ERROR: Invalid User Pool ID format: invalid_pool_id\n ```\n Solution: Ensure the User Pool ID follows the format `region_poolId` (e.g., `us-west-2_abcdef123`).\n\n3. **Authentication failed**\n ```\n ERROR: Error getting token: 401 Client Error: Unauthorized\n ```\n Solution: Verify your client ID and client secret are correct and that the client has the necessary permissions.\n\n### Debug Mode\n\nEnable debug logging to see detailed information:\n\n```bash\npython get_m2m_token.py --debug\n```\n\n## Dependencies\n\nMinimal dependencies for easy deployment:\n- `requests` - HTTP client for OAuth requests\n- `python-dotenv` - Environment variable loading\n- `pyyaml` - YAML configuration file parsing\n\n## Security Notes\n\n- Never commit `.env` files or access tokens to version control\n- Access tokens are temporary and should be regenerated as needed\n- Store client secrets securely using environment variables or secret management systems\n- The generated access token file (`.access_token`) should be protected with appropriate file permissions\n\n## Integration with AgentCore\n\nOnce you have generated an access token, you can use it with AgentCore Gateway APIs:\n\n```bash\n# Use the generated token in API requests\nTOKEN=$(cat .access_token)\ncurl -H \"Authorization: Bearer $TOKEN\" https://your-gateway-url/api/endpoint\n```\n\n## Support\n\nFor issues related to:\n- Gateway creation: See the main SRE Agent documentation\n- OAuth configuration: Consult your OAuth provider documentation\n- This utility: Check the troubleshooting section above" }, { "path": "credentials-provider/agentcore-auth/get_m2m_token.py", "content": "#!/usr/bin/env python3\n\"\"\"\nAgentCore Gateway Access Token Generator\n\nThis standalone utility generates OAuth2 access tokens for existing AgentCore Gateways\nusing Cognito or other OAuth providers. It can be used independently from the main\ngateway creation scripts.\n\nUsage:\n # Using Cognito (default)\n python generate_access_token.py\n\n # Using custom gateway ARN\n python generate_access_token.py --gateway-arn arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway\n\n # Using environment variables\n export COGNITO_DOMAIN=https://your-cognito-domain.auth.us-west-2.amazoncognito.com\n export COGNITO_CLIENT_ID=your_client_id\n export COGNITO_CLIENT_SECRET=your_client_secret\n python generate_access_token.py\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport time\nfrom datetime import UTC, datetime\nfrom pathlib import Path\nfrom typing import Any\nfrom urllib.parse import urlparse\n\nimport requests\nfrom dotenv import load_dotenv\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _load_gateway_configs() -> list[dict[str, Any]]:\n \"\"\"\n Load gateway configurations from environment variables.\n Supports multiple configurations with _1, _2, _3 suffixes.\n\n Returns:\n List of gateway configuration dictionaries\n \"\"\"\n configs = []\n\n # Check for numbered configurations (up to 100)\n for i in range(1, 101):\n client_id = os.environ.get(f\"AGENTCORE_CLIENT_ID_{i}\")\n client_secret = os.environ.get(f\"AGENTCORE_CLIENT_SECRET_{i}\")\n gateway_arn = os.environ.get(f\"AGENTCORE_GATEWAY_ARN_{i}\")\n server_name = os.environ.get(f\"AGENTCORE_SERVER_NAME_{i}\")\n\n # If we find a configuration set, add it\n if client_id and client_secret:\n config = {\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"gateway_arn\": gateway_arn,\n \"server_name\": server_name,\n \"index\": i,\n }\n configs.append(config)\n logger.debug(f\"Found gateway configuration #{i}: {server_name or 'unnamed'}\")\n elif any([client_id, client_secret, gateway_arn, server_name]):\n # Partial configuration found - warn user\n logger.warning(f\"Incomplete configuration set #{i} - skipping\")\n\n return configs\n\n\ndef _extract_cognito_region_from_pool_id(user_pool_id: str) -> str:\n \"\"\"\n Extract Cognito region from User Pool ID.\n\n Args:\n user_pool_id: Cognito User Pool ID (format: region_poolId)\n\n Returns:\n AWS region extracted from pool ID\n \"\"\"\n try:\n return user_pool_id.split(\"_\")[0]\n except (IndexError, AttributeError):\n logger.error(f\"Invalid User Pool ID format: {user_pool_id}\")\n raise ValueError(f\"Invalid User Pool ID format: {user_pool_id}\")\n\n\ndef _get_cognito_token(\n cognito_domain_url: str,\n client_id: str,\n client_secret: str,\n audience: str = \"MCPGateway\",\n) -> dict[str, Any]:\n \"\"\"\n Get OAuth2 token from Amazon Cognito or Auth0 using client credentials grant type.\n\n Args:\n cognito_domain_url: The full Cognito/Auth0 domain URL\n client_id: The App Client ID\n client_secret: The App Client Secret\n audience: The audience for the token (default: MCPGateway)\n\n Returns:\n Token response containing access_token, expires_in, token_type\n \"\"\"\n # Construct the token endpoint URL\n parsed_domain = urlparse(cognito_domain_url)\n domain_hostname = parsed_domain.hostname or \"\"\n is_auth0 = domain_hostname == \"auth0.com\" or domain_hostname.endswith(\".auth0.com\")\n\n if is_auth0:\n url = f\"{cognito_domain_url.rstrip('/')}/oauth/token\"\n # Use JSON format for Auth0\n headers = {\"Content-Type\": \"application/json\"}\n data = {\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"audience\": audience,\n \"grant_type\": \"client_credentials\",\n \"scope\": \"invoke:gateway\",\n }\n # Send as JSON for Auth0\n response_method = lambda: requests.post(url, headers=headers, json=data, timeout=30)\n else:\n # Cognito format\n url = f\"{cognito_domain_url.rstrip('/')}/oauth2/token\"\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n }\n # Send as form data for Cognito\n response_method = lambda: requests.post(url, headers=headers, data=data, timeout=30)\n\n try:\n # Make the request\n response = response_method()\n response.raise_for_status() # Raise exception for bad status codes\n\n provider_type = \"Auth0\" if is_auth0 else \"Cognito\"\n logger.info(f\"Successfully obtained {provider_type} access token\")\n return response.json()\n\n except requests.exceptions.RequestException as e:\n logger.error(f\"Error getting token: {type(e).__name__}\")\n if hasattr(response, \"text\") and response.text:\n logger.debug(\"Token endpoint returned an error response\")\n raise\n\n\ndef _save_egress_token(\n token_response: dict[str, Any],\n provider: str = \"bedrock-agentcore\",\n server_name: str | None = None,\n oauth_tokens_dir: str = \".oauth-tokens\",\n) -> str:\n \"\"\"\n Save the access token as an egress token file following the same structure as Atlassian tokens.\n\n Args:\n token_response: Token response from OAuth provider\n provider: Auth provider name (default: bedrock-agentcore)\n server_name: Server name from config (for filename)\n oauth_tokens_dir: Path to .oauth-tokens directory\n\n Returns:\n Path to the saved token file\n \"\"\"\n # Create oauth-tokens directory if it doesn't exist\n tokens_dir = Path(oauth_tokens_dir)\n tokens_dir.mkdir(exist_ok=True, mode=0o700)\n\n # Calculate expiration timestamp and human-readable format\n expires_in = token_response.get(\"expires_in\", 10800) # Default 3 hours\n current_time = time.time()\n expires_at = current_time + expires_in\n expires_at_human = datetime.fromtimestamp(expires_at, tz=UTC).strftime(\"%Y-%m-%d %H:%M:%S UTC\")\n saved_at = datetime.fromtimestamp(current_time, tz=UTC).strftime(\"%Y-%m-%d %H:%M:%S UTC\")\n\n # Build egress token data structure\n egress_data = {\n \"provider\": provider,\n \"access_token\": token_response[\"access_token\"],\n \"expires_at\": expires_at,\n \"expires_at_human\": expires_at_human,\n \"token_type\": token_response.get(\"token_type\", \"Bearer\"), # nosec B105 - OAuth2 standard token type per RFC 6750\n \"scope\": token_response.get(\"scope\", \"invoke:gateway\"),\n \"saved_at\": saved_at,\n \"usage_notes\": f\"This token is for EGRESS authentication to {provider} external services\",\n }\n\n # Add refresh token if present (though Cognito client credentials doesn't have refresh tokens)\n if \"refresh_token\" in token_response:\n egress_data[\"refresh_token\"] = token_response[\"refresh_token\"]\n\n # Determine filename: {provider}-{server_name}-egress.json or {provider}-egress.json\n if server_name:\n filename = f\"{provider}-{server_name.lower()}-egress.json\"\n else:\n filename = f\"{provider}-egress.json\"\n\n # Save to file\n egress_path = tokens_dir / filename\n with open(egress_path, \"w\") as f:\n json.dump(egress_data, f, indent=2)\n\n # Set secure file permissions\n egress_path.chmod(0o600)\n\n logger.info(f\"Egress token saved to {egress_path}\")\n logger.info(f\"Token expires at: {expires_at_human} (in {expires_in} seconds)\")\n\n return str(egress_path)\n\n\ndef _get_cognito_domain_from_env() -> tuple[str, str | None]:\n \"\"\"\n Get Cognito domain and user pool ID from environment variables.\n\n Returns:\n Tuple of (cognito_domain, user_pool_id)\n \"\"\"\n cognito_domain = os.environ.get(\"COGNITO_DOMAIN\") or os.environ.get(\"OAUTH_DOMAIN\")\n user_pool_id = os.environ.get(\"COGNITO_USER_POOL_ID\")\n\n # If no domain provided, try to construct from user_pool_id\n if not cognito_domain and user_pool_id:\n cognito_region = _extract_cognito_region_from_pool_id(user_pool_id)\n cognito_domain = f\"https://cognito-idp.{cognito_region}.amazonaws.com/{user_pool_id}\"\n logger.info(\"Constructed Cognito domain from pool ID\")\n\n return cognito_domain, user_pool_id\n\n\ndef generate_access_token(\n gateway_index: int | None = None,\n gateway_name: str | None = None,\n oauth_tokens_dir: str = \".oauth-tokens\",\n audience: str = \"MCPGateway\",\n generate_all: bool = False,\n) -> None:\n \"\"\"\n Generate access token for AgentCore Gateway using environment variables.\n\n Args:\n gateway_index: Index of gateway configuration to use (1-100)\n gateway_name: Name of gateway to generate token for\n oauth_tokens_dir: Path to .oauth-tokens directory\n audience: Token audience for OAuth providers\n generate_all: Generate tokens for all configured gateways\n \"\"\"\n # Load environment variables\n load_dotenv()\n\n # Get singleton Cognito configuration\n cognito_domain, user_pool_id = _get_cognito_domain_from_env()\n\n if not cognito_domain:\n raise ValueError(\"COGNITO_DOMAIN or COGNITO_USER_POOL_ID must be set in .env file\")\n\n # Load gateway configurations\n gateway_configs = _load_gateway_configs()\n\n if not gateway_configs:\n raise ValueError(\n \"No gateway configurations found. Please set AGENTCORE_CLIENT_ID_1, AGENTCORE_CLIENT_SECRET_1, etc. in .env file\"\n )\n\n # Determine which configurations to process\n configs_to_process = []\n\n if generate_all:\n configs_to_process = gateway_configs\n logger.info(f\"Generating tokens for all {len(gateway_configs)} configured gateways\")\n elif gateway_index:\n config = next((c for c in gateway_configs if c[\"index\"] == gateway_index), None)\n if not config:\n raise ValueError(f\"No configuration found for index {gateway_index}\")\n configs_to_process = [config]\n elif gateway_name:\n config = next((c for c in gateway_configs if c.get(\"server_name\") == gateway_name), None)\n if not config:\n available_names = [\n c.get(\"server_name\", f\"config_{c['index']}\") for c in gateway_configs\n ]\n raise ValueError(\n f\"No configuration found for gateway '{gateway_name}'. Available: {', '.join(available_names)}\"\n )\n configs_to_process = [config]\n else:\n # Default to first configuration\n configs_to_process = [gateway_configs[0]]\n logger.info(\"Using first gateway configuration (index 1)\")\n\n # Resolve oauth_tokens_dir path relative to current working directory\n if not Path(oauth_tokens_dir).is_absolute():\n oauth_tokens_path = Path.cwd() / oauth_tokens_dir\n else:\n oauth_tokens_path = Path(oauth_tokens_dir)\n\n # Process each configuration\n for config in configs_to_process:\n client_id = config[\"client_id\"]\n client_secret = config[\"client_secret\"]\n gateway_arn = config.get(\"gateway_arn\")\n server_name = config.get(\"server_name\")\n\n logger.info(\n f\"\\nProcessing gateway configuration #{config['index']}: {server_name or 'unnamed'}\"\n )\n\n if gateway_arn:\n logger.debug(f\"Gateway ARN: {gateway_arn}\")\n\n logger.info(\"Generating OAuth2 access token...\")\n\n try:\n # Generate token\n token_response = _get_cognito_token(\n cognito_domain_url=cognito_domain,\n client_id=client_id,\n client_secret=client_secret,\n audience=audience,\n )\n\n # Save token as egress token file\n saved_path = _save_egress_token(\n token_response=token_response,\n provider=\"bedrock-agentcore\",\n server_name=server_name,\n oauth_tokens_dir=str(oauth_tokens_path),\n )\n\n logger.info(\"Token generation completed successfully!\")\n\n except Exception as e:\n config_label = server_name or f\"config_{config['index']}\"\n logger.error(f\"Failed to generate token for {config_label}: {type(e).__name__}\")\n if not generate_all:\n raise\n\n\ndef _parse_arguments() -> argparse.Namespace:\n \"\"\"\n Parse command line arguments.\n\n Returns:\n Parsed command line arguments\n \"\"\"\n parser = argparse.ArgumentParser(\n description=\"Generate OAuth2 access tokens for AgentCore Gateways\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Generate token for first configured gateway\n python generate_access_token.py\n\n # Generate token for specific gateway by index\n python generate_access_token.py --gateway-index 2\n\n # Generate token for specific gateway by name\n python generate_access_token.py --gateway-name sre-gateway\n\n # Generate tokens for ALL configured gateways\n python generate_access_token.py --all\n\n # Custom oauth-tokens directory\n python generate_access_token.py --oauth-tokens-dir /path/to/.oauth-tokens\n\n # Custom audience for Auth0\n python generate_access_token.py --audience \"https://api.mycompany.com\"\n\nEnvironment Variables:\n # Singleton configuration (shared across all gateways):\n COGNITO_DOMAIN - Cognito/OAuth domain URL\n COGNITO_USER_POOL_ID - Cognito User Pool ID\n\n # Per-gateway configuration (use _1, _2, etc. suffixes):\n AGENTCORE_CLIENT_ID_1 - OAuth client ID for gateway 1\n AGENTCORE_CLIENT_SECRET_1 - OAuth client secret for gateway 1\n AGENTCORE_GATEWAY_ARN_1 - Gateway ARN for gateway 1\n AGENTCORE_SERVER_NAME_1 - Server name for gateway 1\n \"\"\",\n )\n\n parser.add_argument(\n \"--gateway-index\",\n type=int,\n help=\"Index of gateway configuration to use (1-100)\",\n )\n\n parser.add_argument(\n \"--gateway-name\",\n help=\"Name of gateway to generate token for\",\n )\n\n parser.add_argument(\n \"--all\",\n action=\"store_true\",\n help=\"Generate tokens for all configured gateways\",\n )\n\n parser.add_argument(\n \"--oauth-tokens-dir\",\n default=\".oauth-tokens\",\n help=\"Path to .oauth-tokens directory (default: .oauth-tokens)\",\n )\n\n parser.add_argument(\n \"--audience\",\n default=\"MCPGateway\",\n help=\"Token audience (default: MCPGateway)\",\n )\n\n parser.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable debug logging\",\n )\n\n return parser.parse_args()\n\n\ndef main() -> None:\n \"\"\"Main entry point.\"\"\"\n args = _parse_arguments()\n\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n try:\n generate_access_token(\n gateway_index=args.gateway_index,\n gateway_name=args.gateway_name,\n oauth_tokens_dir=args.oauth_tokens_dir,\n audience=args.audience,\n generate_all=args.all,\n )\n except Exception as e:\n logger.error(f\"Token generation failed: {e}\")\n exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "credentials-provider/auth0/README.md", "content": "# Auth0 Credentials Provider\n\nGet M2M (Machine-to-Machine) JWT tokens from Auth0 using OAuth2 client credentials flow.\n\n## Prerequisites\n\n1. **Auth0 M2M Application**: Create a Machine-to-Machine application in Auth0\n2. **Management API Authorization**: Authorize the M2M app for Auth0 Management API\n3. **Required Scopes**: Grant appropriate scopes (e.g., `read:users`, `create:users`, `read:roles`, etc.)\n\n## Installation\n\nNo additional dependencies required beyond the main project dependencies (`requests`, `PyJWT`).\n\n## Usage\n\n### Method 1: Environment Variables (Recommended)\n\n```bash\nexport AUTH0_DOMAIN=dev-abc123.us.auth0.com\nexport AUTH0_M2M_CLIENT_ID=your_m2m_client_id\nexport AUTH0_M2M_CLIENT_SECRET=your_m2m_client_secret\n\nuv run python -m credentials-provider.auth0.get_m2m_token\n```\n\n### Method 2: Command-Line Arguments\n\n```bash\nuv run python -m credentials-provider.auth0.get_m2m_token \\\n --auth0-domain dev-abc123.us.auth0.com \\\n --client-id your_m2m_client_id \\\n --client-secret your_m2m_client_secret\n```\n\n### Custom API Audience\n\nBy default, the script requests tokens for the Auth0 Management API (`https://{domain}/api/v2/`). To request tokens for a custom API:\n\n```bash\nuv run python -m credentials-provider.auth0.get_m2m_token \\\n --audience https://my-custom-api.example.com\n```\n\n### Options\n\n- `--auth0-domain`: Auth0 domain (e.g., `dev-abc123.us.auth0.com`)\n- `--client-id`: OAuth2 M2M client ID\n- `--client-secret`: OAuth2 M2M client secret\n- `--audience`: API audience (default: Management API)\n- `--show-token`: Display decoded token claims (default: true)\n- `--no-show-token`: Skip displaying token claims\n- `--debug`: Enable debug logging\n\n## Output\n\nThe script:\n1. Requests an M2M token from Auth0\n2. Displays decoded token claims (unless `--no-show-token` is specified)\n3. Saves the token to a temporary file in `/tmp/`\n4. Prints the file path to stdout\n\nExample output:\n\n```\nToken saved to: /tmp/auth0_m2m_token_abc123.json\n```\n\nThe token file contains:\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 86400\n}\n```\n\n## Token Lifetime\n\nAuth0 M2M tokens typically have a 24-hour lifetime (86400 seconds). The token expiration is displayed when `--show-token` is enabled.\n\n## Security\n\n- Token files are created with restrictive permissions (0600)\n- Tokens are stored in `/tmp/` which is cleared on system restart\n- Never commit tokens or credentials to version control\n- Use environment variables or secure secret management for credentials\n\n## Troubleshooting\n\n### Error: \"Auth0 domain must be provided\"\n\nSet the `AUTH0_DOMAIN` environment variable or use the `--auth0-domain` flag.\n\n### Error: \"Client ID must be provided\"\n\nSet the `AUTH0_M2M_CLIENT_ID` environment variable or use the `--client-id` flag.\n\n### Error: \"Client secret must be provided\"\n\nSet the `AUTH0_M2M_CLIENT_SECRET` environment variable or use the `--client-secret` flag.\n\n### Error: \"M2M token request failed\"\n\nCheck that:\n1. Your M2M application is authorized for the target API\n2. The client ID and secret are correct\n3. The audience matches your API identifier\n4. Network connectivity to Auth0 is available\n\n## Integration with MCP Gateway\n\nThe MCP Gateway Registry uses these credentials to manage users and roles via the Auth0 Management API. The credentials are configured in:\n\n- `.env` file: `AUTH0_DOMAIN`, `AUTH0_M2M_CLIENT_ID`, `AUTH0_M2M_CLIENT_SECRET`\n- Terraform: `terraform/aws-ecs/variables.tf` and `terraform.tfvars`\n- Docker Compose: `docker-compose.yml`\n- Helm: `charts/*/values.yaml`\n\n## Related Files\n\n- `registry/utils/auth0_manager.py`: Auth0 Management API integration\n- `registry/utils/iam_manager.py`: IAM manager factory including Auth0\n" }, { "path": "credentials-provider/auth0/__init__.py", "content": "\"\"\"Auth0 credentials provider module.\"\"\"\n" }, { "path": "credentials-provider/auth0/get_m2m_token.py", "content": "\"\"\"Get Auth0 M2M token using client credentials flow.\n\nThis script obtains a JWT token from Auth0 using OAuth2 client credentials grant.\nThe token is saved to a temporary file and the file path is printed.\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nimport tempfile\n\nimport jwt\nimport requests\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _get_auth0_domain() -> str:\n \"\"\"Get Auth0 domain from CLI arg or environment variable.\n\n Returns:\n Auth0 domain (e.g., dev-abc123.us.auth0.com)\n\n Raises:\n ValueError: If domain not provided\n \"\"\"\n domain = os.getenv(\"AUTH0_DOMAIN\")\n if domain:\n return domain.replace(\"https://\", \"\").rstrip(\"/\")\n\n raise ValueError(\"Auth0 domain must be provided via --auth0-domain or AUTH0_DOMAIN env var\")\n\n\ndef _get_client_id() -> str:\n \"\"\"Get client ID from CLI arg or environment variable.\n\n Returns:\n Auth0 M2M client ID\n\n Raises:\n ValueError: If client ID not provided\n \"\"\"\n client_id = os.getenv(\"AUTH0_M2M_CLIENT_ID\")\n if client_id:\n return client_id\n\n raise ValueError(\"Client ID must be provided via --client-id or AUTH0_M2M_CLIENT_ID env var\")\n\n\ndef _get_client_secret() -> str:\n \"\"\"Get client secret from CLI arg or environment variable.\n\n Returns:\n Auth0 M2M client secret\n\n Raises:\n ValueError: If client secret not provided\n \"\"\"\n client_secret = os.getenv(\"AUTH0_M2M_CLIENT_SECRET\")\n if client_secret:\n return client_secret\n\n raise ValueError(\n \"Client secret must be provided via --client-secret or AUTH0_M2M_CLIENT_SECRET env var\"\n )\n\n\ndef _request_m2m_token(\n auth0_domain: str,\n client_id: str,\n client_secret: str,\n audience: str | None = None,\n) -> dict[str, str]:\n \"\"\"Request M2M token from Auth0 using client credentials.\n\n Args:\n auth0_domain: Auth0 domain (e.g., dev-abc123.us.auth0.com)\n client_id: OAuth2 client ID\n client_secret: OAuth2 client secret\n audience: API audience (defaults to Management API: https://{domain}/api/v2/)\n\n Returns:\n Token response dictionary with access_token, token_type, expires_in\n\n Raises:\n ValueError: If token request fails\n \"\"\"\n # Default to Management API audience if not provided\n if not audience:\n audience = f\"https://{auth0_domain}/api/v2/\"\n\n token_url = f\"https://{auth0_domain}/oauth/token\"\n\n logger.info(f\"Requesting M2M token from {token_url}\")\n logger.info(f\"Audience: {audience}\")\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"audience\": audience,\n }\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n try:\n response = requests.post(\n token_url,\n data=data,\n headers=headers,\n timeout=30,\n )\n\n # Log response details for debugging\n if response.status_code != 200:\n try:\n error_data = response.json()\n logger.error(f\"Auth0 error response: {json.dumps(error_data, indent=2)}\")\n except Exception:\n logger.error(f\"Auth0 error response (non-JSON): {response.text}\")\n\n response.raise_for_status()\n\n token_data = response.json()\n logger.info(\n f\"Successfully obtained M2M token, expires in {token_data.get('expires_in', 'unknown')} seconds\"\n )\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get M2M token: {e}\")\n raise ValueError(f\"M2M token request failed: {e}\")\n\n\ndef _decode_token(access_token: str) -> dict[str, str]:\n \"\"\"Decode JWT token without verification to display claims.\n\n Args:\n access_token: JWT access token string\n\n Returns:\n Dictionary of decoded token claims\n \"\"\"\n try:\n claims = jwt.decode(access_token, options={\"verify_signature\": False})\n return claims\n except Exception as e:\n logger.warning(f\"Failed to decode token: {e}\")\n return {}\n\n\ndef _display_decoded_token(claims: dict[str, str]) -> None:\n \"\"\"Display decoded token claims in a readable format.\n\n Args:\n claims: Dictionary of decoded JWT claims\n \"\"\"\n if not claims:\n return\n\n print(\"\\n\" + \"=\" * 60)\n print(\"DECODED JWT TOKEN CLAIMS\")\n print(\"=\" * 60)\n print(json.dumps(claims, indent=2))\n print(\"\\n\" + \"=\" * 60)\n print(\"KEY INFORMATION\")\n print(\"=\" * 60)\n print(f\"Grant ID (gty): {claims.get('gty', 'N/A')}\")\n print(f\"Azure AD (azp): {claims.get('azp', 'N/A')}\")\n print(f\"Subject (sub): {claims.get('sub', 'N/A')}\")\n print(f\"Issuer (iss): {claims.get('iss', 'N/A')}\")\n print(f\"Audience (aud): {claims.get('aud', 'N/A')}\")\n print(f\"Scopes (scope): {claims.get('scope', 'N/A')}\")\n print(f\"Permissions: {claims.get('permissions', [])}\")\n\n # Display expiration info\n if \"exp\" in claims and \"iat\" in claims:\n from datetime import datetime\n\n exp_time = datetime.fromtimestamp(claims[\"exp\"])\n iat_time = datetime.fromtimestamp(claims[\"iat\"])\n lifetime_hours = (claims[\"exp\"] - claims[\"iat\"]) / 3600\n print(f\"\\nIssued at: {iat_time} UTC\")\n print(f\"Expires at: {exp_time} UTC\")\n print(f\"Lifetime: {lifetime_hours:.1f} hours\")\n print(\"=\" * 60 + \"\\n\")\n\n\ndef _save_token_to_file(token_data: dict[str, str]) -> str:\n \"\"\"Save token data to temporary file.\n\n Args:\n token_data: Token response dictionary\n\n Returns:\n Path to temporary file containing token\n \"\"\"\n # Create temporary file with secure permissions (0600)\n fd, temp_path = tempfile.mkstemp(\n prefix=\"auth0_m2m_token_\",\n suffix=\".json\",\n dir=\"/tmp\",\n )\n\n try:\n # Write token data as JSON\n with os.fdopen(fd, \"w\") as f:\n json.dump(token_data, f, indent=2)\n\n # Ensure file has restrictive permissions\n os.chmod(temp_path, 0o600)\n\n logger.info(f\"Token saved to {temp_path}\")\n return temp_path\n\n except Exception as e:\n # Clean up on error\n try:\n os.unlink(temp_path)\n except Exception:\n pass\n raise ValueError(f\"Failed to save token to file: {e}\")\n\n\ndef main() -> None:\n \"\"\"Main function to get Auth0 M2M token and save to file.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Get Auth0 M2M token using client credentials flow\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExample usage:\n # Using environment variables\n export AUTH0_DOMAIN=dev-abc123.us.auth0.com\n export AUTH0_M2M_CLIENT_ID=KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\n export AUTH0_M2M_CLIENT_SECRET=lbjH6Z81GkovgAHwXRV-qiKV9f6sUVzsnheJoX7KJcu2ojGXMTjJ4i0Zn49kKfVm\n uv run python -m credentials-provider.auth0.get_m2m_token\n\n # Using CLI arguments (Management API)\n uv run python -m credentials-provider.auth0.get_m2m_token \\\\\n --auth0-domain dev-abc123.us.auth0.com \\\\\n --client-id KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd \\\\\n --client-secret lbjH6Z81GkovgAHwXRV-qiKV9f6sUVzsnheJoX7KJcu2ojGXMTjJ4i0Zn49kKfVm\n\n # Custom API audience\n uv run python -m credentials-provider.auth0.get_m2m_token \\\\\n --auth0-domain dev-abc123.us.auth0.com \\\\\n --client-id KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd \\\\\n --client-secret lbjH6Z81GkovgAHwXRV-qiKV9f6sUVzsnheJoX7KJcu2ojGXMTjJ4i0Zn49kKfVm \\\\\n --audience https://my-api.example.com\n\"\"\",\n )\n\n parser.add_argument(\n \"--auth0-domain\",\n type=str,\n help=\"Auth0 domain (e.g., dev-abc123.us.auth0.com). Can also use AUTH0_DOMAIN env var.\",\n )\n\n parser.add_argument(\n \"--client-id\",\n type=str,\n help=\"OAuth2 M2M client ID. Can also use AUTH0_M2M_CLIENT_ID env var.\",\n )\n\n parser.add_argument(\n \"--client-secret\",\n type=str,\n help=\"OAuth2 M2M client secret. Can also use AUTH0_M2M_CLIENT_SECRET env var.\",\n )\n\n parser.add_argument(\n \"--audience\",\n type=str,\n help=\"API audience (default: https://{domain}/api/v2/ for Management API)\",\n )\n\n parser.add_argument(\n \"--show-token\",\n action=\"store_true\",\n help=\"Display decoded token claims (default: True)\",\n default=True,\n )\n\n parser.add_argument(\n \"--no-show-token\",\n action=\"store_true\",\n help=\"Do not display decoded token claims\",\n )\n\n parser.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable debug logging\",\n )\n\n args = parser.parse_args()\n\n # Set debug logging if requested\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n try:\n # Get configuration from CLI args or environment variables\n auth0_domain = args.auth0_domain or _get_auth0_domain()\n client_id = args.client_id or _get_client_id()\n client_secret = args.client_secret or _get_client_secret()\n\n # Request M2M token from Auth0\n token_data = _request_m2m_token(\n auth0_domain=auth0_domain,\n client_id=client_id,\n client_secret=client_secret,\n audience=args.audience,\n )\n\n # Decode and display token if requested\n show_token = args.show_token and not args.no_show_token\n if show_token and \"access_token\" in token_data:\n claims = _decode_token(token_data[\"access_token\"])\n _display_decoded_token(claims)\n\n # Save token to temporary file\n token_file_path = _save_token_to_file(token_data)\n\n # Print the file path\n print(f\"Token saved to: {token_file_path}\")\n\n except ValueError as e:\n logger.error(f\"Error: {e}\")\n sys.exit(1)\n except Exception as e:\n logger.exception(f\"Unexpected error: {e}\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "credentials-provider/check_and_refresh_creds.sh", "content": "#!/bin/bash\n\n# Script to check JWT token validity and refresh credentials only if needed\n# Usage: ./scripts/check_and_refresh_creds.sh\n\nset -e\n\n# Get the directory where this script is located\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nPROJECT_ROOT=\"$(dirname \"$SCRIPT_DIR\")\"\n\n# Check if token is valid using Python\necho \"Checking token validity...\"\nTOKEN_VALID=$(cd \"$PROJECT_ROOT\" && python3 -c \"\nimport sys\nimport os\nsys.path.append('cli')\nfrom mcp_utils import _load_oauth_token_from_file\nimport time\n\ntry:\n token_data = _load_oauth_token_from_file()\n if token_data and 'expires_at' in token_data:\n current_time = time.time()\n expires_at = token_data['expires_at']\n # Add 60 second buffer to avoid edge cases\n if current_time < (expires_at - 60):\n print('valid')\n else:\n print('expired')\n else:\n print('missing')\nexcept Exception:\n print('missing')\n\")\n\nif [ \"$TOKEN_VALID\" = \"valid\" ]; then\n echo \"Token is still valid, skipping credential generation\"\n exit 0\nelif [ \"$TOKEN_VALID\" = \"expired\" ]; then\n echo \"Token has expired, generating fresh credentials...\"\nelse\n echo \"No valid token found, generating fresh credentials...\"\nfi\n\n# Generate fresh credentials\necho \"Running credential generation...\"\ncd \"$PROJECT_ROOT\"\n./credentials-provider/generate_creds.sh\n\necho \"Credentials refreshed successfully\"" }, { "path": "credentials-provider/entra/__init__.py", "content": "" }, { "path": "credentials-provider/entra/get_m2m_token.py", "content": "#!/usr/bin/env python3\n\"\"\"\nGenerate OAuth2 access tokens for identities using Microsoft Entra ID.\n\nReads identity credentials from an input JSON file and generates tokens\nfor each identity using the OAuth2 client credentials flow.\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nfrom datetime import (\n UTC,\n datetime,\n)\nfrom typing import (\n Any,\n)\n\nimport requests\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n# Default Entra ID login base URL\nDEFAULT_ENTRA_LOGIN_BASE_URL = \"https://login.microsoftonline.com\"\nDEFAULT_IDENTITIES_FILE = \".oauth-tokens/entra-identities.json\"\n\n\nclass Colors:\n \"\"\"ANSI color codes for console output.\"\"\"\n\n RED = \"\\033[0;31m\"\n GREEN = \"\\033[0;32m\"\n YELLOW = \"\\033[1;33m\"\n BLUE = \"\\033[0;34m\"\n NC = \"\\033[0m\"\n\n\ndef _redact_sensitive_value(\n value: str,\n show_chars: int = 8,\n) -> str:\n \"\"\"Redact sensitive value for logging.\"\"\"\n if not value or len(value) <= show_chars:\n return \"*\" * len(value) if value else \"\"\n return value[:show_chars] + \"*\" * (len(value) - show_chars)\n\n\ndef _get_token_from_entra(\n client_id: str,\n client_secret: str,\n tenant_id: str,\n scope: str | None = None,\n verbose: bool = False,\n) -> dict[str, Any] | None:\n \"\"\"Request access token from Microsoft Entra ID using client credentials.\"\"\"\n login_base_url = os.environ.get(\n \"ENTRA_LOGIN_BASE_URL\",\n DEFAULT_ENTRA_LOGIN_BASE_URL,\n )\n\n token_url = f\"{login_base_url}/{tenant_id}/oauth2/v2.0/token\"\n\n # Default scope for Entra ID M2M tokens\n if not scope:\n scope = f\"api://{client_id}/.default\"\n\n if verbose:\n print(f\"{Colors.BLUE}[DEBUG]{Colors.NC} Token URL: {token_url}\")\n print(f\"{Colors.BLUE}[DEBUG]{Colors.NC} Client ID: {client_id}\")\n print(f\"{Colors.BLUE}[DEBUG]{Colors.NC} Tenant ID: {tenant_id}\")\n print(f\"{Colors.BLUE}[DEBUG]{Colors.NC} Scope: {scope}\")\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"scope\": scope,\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n try:\n response = requests.post(token_url, data=data, headers=headers, timeout=30)\n\n # Check for error response before raise_for_status\n if response.status_code >= 400:\n try:\n error_data = response.json()\n error_msg = error_data.get(\n \"error_description\", error_data.get(\"error\", \"Unknown error\")\n )\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Entra ID error: {error_msg}\")\n if verbose:\n print(\n f\"{Colors.BLUE}[DEBUG]{Colors.NC} Full error response: {json.dumps(error_data, indent=2)}\"\n )\n except json.JSONDecodeError:\n print(\n f\"{Colors.RED}[ERROR]{Colors.NC} HTTP {response.status_code}: {response.text}\"\n )\n return None\n\n token_data = response.json()\n\n if \"error_description\" in token_data:\n print(\n f\"{Colors.RED}[ERROR]{Colors.NC} Token request failed: {token_data['error_description']}\"\n )\n return None\n\n if \"access_token\" not in token_data:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} No access token in response\")\n return None\n\n return token_data\n\n except requests.exceptions.RequestException as e:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Failed to make token request to Entra ID: {e}\")\n return None\n except json.JSONDecodeError as e:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Invalid JSON response: {e}\")\n return None\n\n\ndef _save_token_file(\n identity_name: str,\n token_data: dict[str, Any],\n client_id: str,\n tenant_id: str,\n scope: str,\n output_dir: str,\n) -> bool:\n \"\"\"Save token to JSON file.\"\"\"\n access_token = token_data[\"access_token\"]\n expires_in = token_data.get(\"expires_in\")\n\n os.makedirs(output_dir, exist_ok=True)\n\n generated_at = datetime.now(UTC).isoformat()\n expires_at = None\n if expires_in:\n expiry_timestamp = datetime.now(UTC).timestamp() + expires_in\n expires_at = datetime.fromtimestamp(\n expiry_timestamp,\n UTC,\n ).isoformat()\n\n token_json = {\n \"identity_name\": identity_name,\n \"access_token\": access_token,\n \"token_type\": \"Bearer\", # nosec B105 - OAuth2 standard token type per RFC 6750\n \"expires_in\": expires_in,\n \"generated_at\": generated_at,\n \"expires_at\": expires_at,\n \"provider\": \"entra\",\n \"tenant_id\": tenant_id,\n \"client_id\": client_id,\n \"scope\": scope,\n }\n\n json_file = os.path.join(output_dir, f\"{identity_name}.json\")\n\n try:\n with open(json_file, \"w\") as f:\n json.dump(token_json, f, indent=2)\n os.chmod(json_file, 0o600)\n except Exception as e:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Failed to save token file: {e}\")\n return False\n\n print(f\"{Colors.GREEN}[SUCCESS]{Colors.NC} Token saved to: {json_file}\")\n\n redacted_token = _redact_sensitive_value(access_token, 8)\n print(f\"\\nAccess Token: {redacted_token}\")\n if expires_in:\n print(f\"Expires in: {expires_in} seconds\")\n if expires_at:\n expiry_time = datetime.fromisoformat(expires_at.replace(\"Z\", \"+00:00\"))\n print(f\"Expires at: {expiry_time.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n print()\n\n return True\n\n\ndef _load_identities_file(\n file_path: str,\n) -> list[dict[str, Any]] | None:\n \"\"\"Load identities from JSON file.\"\"\"\n if not os.path.exists(file_path):\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Identities file not found: {file_path}\")\n return None\n\n try:\n with open(file_path) as f:\n identities = json.load(f)\n\n if not isinstance(identities, list):\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Identities file must contain a JSON array\")\n return None\n\n return identities\n\n except json.JSONDecodeError as e:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Failed to parse identities file: {e}\")\n return None\n except Exception as e:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Failed to load identities file: {e}\")\n return None\n\n\ndef generate_tokens(\n identities_file: str,\n output_dir: str,\n verbose: bool = False,\n) -> bool:\n \"\"\"Generate tokens for all identities in the input file.\"\"\"\n identities = _load_identities_file(identities_file)\n if identities is None:\n return False\n\n if not identities:\n print(f\"{Colors.YELLOW}[WARNING]{Colors.NC} No identities found in file\")\n return True\n\n print(\n f\"{Colors.GREEN}[SUCCESS]{Colors.NC} Found {len(identities)} identity(ies) in {identities_file}\"\n )\n\n success_count = 0\n total_count = len(identities)\n\n for identity in identities:\n identity_name = identity.get(\"identity_name\")\n if not identity_name:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Identity missing 'identity_name' field\")\n continue\n\n print(f\"\\n{'=' * 60}\")\n print(f\"Processing identity: {identity_name}\")\n print(\"=\" * 60)\n\n client_id = identity.get(\"client_id\")\n client_secret = identity.get(\"client_secret\")\n tenant_id = identity.get(\"tenant_id\")\n scope = identity.get(\"scope\")\n\n if not client_id:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Identity '{identity_name}' missing 'client_id'\")\n continue\n if not client_secret:\n print(\n f\"{Colors.RED}[ERROR]{Colors.NC} Identity '{identity_name}' missing 'client_secret'\"\n )\n continue\n if not tenant_id:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Identity '{identity_name}' missing 'tenant_id'\")\n continue\n\n print(f\"Requesting access token for identity: {identity_name}\")\n\n token_data = _get_token_from_entra(\n client_id,\n client_secret,\n tenant_id,\n scope,\n verbose,\n )\n\n if not token_data:\n print(\n f\"{Colors.RED}[ERROR]{Colors.NC} Failed to generate token for identity: {identity_name}\"\n )\n continue\n\n print(f\"{Colors.GREEN}[SUCCESS]{Colors.NC} Access token generated!\")\n\n if not scope:\n scope = f\"api://{client_id}/.default\"\n\n if _save_token_file(\n identity_name,\n token_data,\n client_id,\n tenant_id,\n scope,\n output_dir,\n ):\n success_count += 1\n\n print(f\"\\n{'=' * 60}\")\n print(f\"Token generation complete: {success_count}/{total_count} successful\")\n print(\"=\" * 60)\n\n return success_count == total_count\n\n\ndef main() -> None:\n \"\"\"Main function.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Generate OAuth2 access tokens using Microsoft Entra ID\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Generate tokens using default identities file\n python generate_tokens.py\n\n # Generate tokens using custom identities file\n python generate_tokens.py --identities-file /path/to/identities.json\n\n # Generate tokens with verbose output\n python generate_tokens.py --verbose\n\nIdentities File Format (JSON array):\n [\n {\n \"identity_name\": \"admin\",\n \"tenant_id\": \"your-tenant-id\",\n \"client_id\": \"your-client-id\",\n \"client_secret\": \"your-client-secret\",\n \"scope\": \"api://your-app-id/.default\" // optional\n }\n ]\n\nEnvironment Variables:\n ENTRA_LOGIN_BASE_URL - Login base URL (default: https://login.microsoftonline.com)\n \"\"\",\n )\n\n parser.add_argument(\n \"--identities-file\",\n type=str,\n default=DEFAULT_IDENTITIES_FILE,\n help=f\"Path to JSON file with identity credentials (default: {DEFAULT_IDENTITIES_FILE})\",\n )\n parser.add_argument(\n \"--output-dir\",\n type=str,\n default=\".oauth-tokens\",\n help=\"Output directory for token files (default: .oauth-tokens)\",\n )\n parser.add_argument(\n \"--verbose\",\n \"-v\",\n action=\"store_true\",\n help=\"Verbose output\",\n )\n # Keep --all-agents for backwards compatibility but ignore it\n parser.add_argument(\n \"--all-agents\",\n action=\"store_true\",\n help=argparse.SUPPRESS,\n )\n\n args = parser.parse_args()\n\n try:\n success = generate_tokens(\n identities_file=args.identities_file,\n output_dir=args.output_dir,\n verbose=args.verbose,\n )\n sys.exit(0 if success else 1)\n\n except KeyboardInterrupt:\n print(f\"\\n{Colors.YELLOW}[WARNING]{Colors.NC} Operation interrupted by user\")\n sys.exit(1)\n except Exception as e:\n print(f\"{Colors.RED}[ERROR]{Colors.NC} Unexpected error: {e}\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "credentials-provider/generate_creds.sh", "content": "#!/bin/bash\n#\n# Ingress Token Generator Script\n#\n# This script generates ingress authentication tokens using the configured\n# identity provider (Keycloak or Entra ID based on AUTH_PROVIDER).\n#\n# Usage:\n# ./generate_creds.sh # Generate ingress token\n# ./generate_creds.sh --verbose # Enable verbose logging\n# ./generate_creds.sh --force # Force new token generation\n# ./generate_creds.sh --help # Show this help\n\nset -e # Exit on error\n\n# Script directory\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\n# Load .env file if it exists\nif [ -f \"$SCRIPT_DIR/.env\" ]; then\n source \"$SCRIPT_DIR/.env\"\nfi\n\n# Also load main project .env file to get AUTH_PROVIDER\nif [ -f \"$(dirname \"$SCRIPT_DIR\")/.env\" ]; then\n source \"$(dirname \"$SCRIPT_DIR\")/.env\"\nfi\n\n# Default values (empty - require explicit configuration)\nVERBOSE=false\nFORCE=false\nIDENTITIES_FILE=\"\"\nAUTH_PROVIDER_ARG=\"\"\nKEYCLOAK_URL_ARG=\"\"\nKEYCLOAK_REALM_ARG=\"\"\nENTRA_TENANT_ID_ARG=\"\"\nENTRA_CLIENT_ID_ARG=\"\"\nENTRA_CLIENT_SECRET_ARG=\"\"\nENTRA_LOGIN_BASE_URL_ARG=\"\"\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\n# Logging functions\nlog_info() {\n echo -e \"${GREEN}[INFO]${NC} $1\"\n}\n\nlog_warn() {\n echo -e \"${YELLOW}[WARN]${NC} $1\"\n}\n\nlog_error() {\n echo -e \"${RED}[ERROR]${NC} $1\"\n}\n\nlog_debug() {\n if [ \"$VERBOSE\" = true ]; then\n echo -e \"${BLUE}[DEBUG]${NC} $1\"\n fi\n}\n\nshow_help() {\n cat << EOF\nIngress Token Generator Script\n\nThis script generates ingress authentication tokens for the MCP Gateway.\nIt automatically uses the configured AUTH_PROVIDER (keycloak or entra).\n\nUSAGE:\n ./generate_creds.sh [OPTIONS]\n\nOPTIONS:\n --auth-provider, -a PROVIDER Auth provider: 'keycloak' or 'entra' (required if AUTH_PROVIDER env not set)\n --keycloak-url, -k URL Keycloak server URL (required for keycloak if KEYCLOAK_EXTERNAL_URL env not set)\n --keycloak-realm, -r REALM Keycloak realm name (default: mcp-gateway, or KEYCLOAK_REALM env)\n --entra-tenant-id TENANT_ID Entra tenant ID (required for entra if ENTRA_TENANT_ID env not set)\n --entra-client-id CLIENT_ID Entra client ID (required for entra if ENTRA_CLIENT_ID env not set)\n --entra-client-secret SECRET Entra client secret (required for entra if ENTRA_CLIENT_SECRET env not set)\n --entra-login-url URL Entra login base URL (default: https://login.microsoftonline.com)\n --identities-file, -i FILE Custom path to identities JSON file (for entra)\n --force, -f Force new token generation, ignore existing tokens\n --verbose, -v Enable verbose debug logging\n --help, -h Show this help message\n\nEXAMPLES:\n # Keycloak with explicit URL\n ./generate_creds.sh -a keycloak -k https://kc.example.com\n\n # Keycloak using environment variables\n export KEYCLOAK_EXTERNAL_URL=https://kc.example.com\n ./generate_creds.sh -a keycloak\n\n # Entra ID with explicit parameters\n ./generate_creds.sh -a entra --entra-tenant-id \"tenant-id\" --entra-client-id \"client-id\" --entra-client-secret \"secret\"\n\n # Entra ID using identities file\n ./generate_creds.sh -a entra -i /path/to/identities.json\n\nENVIRONMENT VARIABLES:\n General:\n AUTH_PROVIDER # IdP selection: 'keycloak' or 'entra'\n\n For Keycloak (AUTH_PROVIDER=keycloak):\n KEYCLOAK_EXTERNAL_URL # Keycloak server URL (external/public URL)\n KEYCLOAK_REALM # Keycloak realm name (default: mcp-gateway)\n\n For Entra ID (AUTH_PROVIDER=entra):\n ENTRA_TENANT_ID # Azure AD tenant ID\n ENTRA_CLIENT_ID # App registration client ID\n ENTRA_CLIENT_SECRET # App registration client secret\n ENTRA_LOGIN_BASE_URL # Login base URL (default: https://login.microsoftonline.com)\n\nEOF\n}\n\n# Parse command line arguments\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --auth-provider|-a)\n AUTH_PROVIDER_ARG=\"$2\"\n shift 2\n ;;\n --keycloak-url|-k)\n KEYCLOAK_URL_ARG=\"$2\"\n shift 2\n ;;\n --keycloak-realm|-r)\n KEYCLOAK_REALM_ARG=\"$2\"\n shift 2\n ;;\n --entra-tenant-id)\n ENTRA_TENANT_ID_ARG=\"$2\"\n shift 2\n ;;\n --entra-client-id)\n ENTRA_CLIENT_ID_ARG=\"$2\"\n shift 2\n ;;\n --entra-client-secret)\n ENTRA_CLIENT_SECRET_ARG=\"$2\"\n shift 2\n ;;\n --entra-login-url)\n ENTRA_LOGIN_BASE_URL_ARG=\"$2\"\n shift 2\n ;;\n --force|-f)\n FORCE=true\n shift\n ;;\n --verbose|-v)\n VERBOSE=true\n shift\n ;;\n --identities-file|-i)\n IDENTITIES_FILE=\"$2\"\n shift 2\n ;;\n --help|-h)\n show_help\n exit 0\n ;;\n *)\n log_error \"Unknown option: $1\"\n show_help\n exit 1\n ;;\n esac\ndone\n\n# Function to run Keycloak token generation\nrun_keycloak_auth() {\n log_info \"Running Keycloak M2M token generation...\"\n\n # Determine Keycloak URL (CLI arg > env var)\n local keycloak_url=\"\"\n if [ -n \"$KEYCLOAK_URL_ARG\" ]; then\n keycloak_url=\"$KEYCLOAK_URL_ARG\"\n elif [ -n \"$KEYCLOAK_EXTERNAL_URL\" ]; then\n keycloak_url=\"$KEYCLOAK_EXTERNAL_URL\"\n fi\n\n # Determine Keycloak realm (CLI arg > env var > default)\n local keycloak_realm=\"\"\n if [ -n \"$KEYCLOAK_REALM_ARG\" ]; then\n keycloak_realm=\"$KEYCLOAK_REALM_ARG\"\n elif [ -n \"$KEYCLOAK_REALM\" ]; then\n keycloak_realm=\"$KEYCLOAK_REALM\"\n else\n keycloak_realm=\"mcp-gateway\"\n fi\n\n # Validate required parameters\n if [ -z \"$keycloak_url\" ]; then\n log_error \"Keycloak URL is required. Provide via --keycloak-url or KEYCLOAK_EXTERNAL_URL environment variable.\"\n return 1\n fi\n\n log_info \"Keycloak URL: $keycloak_url\"\n log_info \"Keycloak Realm: $keycloak_realm\"\n\n local cmd=\"uv run '$SCRIPT_DIR/keycloak/get_m2m_token.py' --all-agents\"\n cmd=\"$cmd --keycloak-url '$keycloak_url'\"\n cmd=\"$cmd --realm '$keycloak_realm'\"\n\n if [ \"$VERBOSE\" = true ]; then\n cmd=\"$cmd --verbose\"\n fi\n\n log_debug \"Executing: $cmd\"\n\n if eval \"$cmd\"; then\n log_info \"Keycloak token generation completed successfully\"\n return 0\n else\n log_error \"Keycloak token generation failed\"\n return 1\n fi\n}\n\n# Function to run Entra ID token generation\nrun_entra_auth() {\n log_info \"Running Entra ID token generation...\"\n\n # Export Entra environment variables (CLI args override env vars)\n if [ -n \"$ENTRA_TENANT_ID_ARG\" ]; then\n export ENTRA_TENANT_ID=\"$ENTRA_TENANT_ID_ARG\"\n fi\n if [ -n \"$ENTRA_CLIENT_ID_ARG\" ]; then\n export ENTRA_CLIENT_ID=\"$ENTRA_CLIENT_ID_ARG\"\n fi\n if [ -n \"$ENTRA_CLIENT_SECRET_ARG\" ]; then\n export ENTRA_CLIENT_SECRET=\"$ENTRA_CLIENT_SECRET_ARG\"\n fi\n if [ -n \"$ENTRA_LOGIN_BASE_URL_ARG\" ]; then\n export ENTRA_LOGIN_BASE_URL=\"$ENTRA_LOGIN_BASE_URL_ARG\"\n fi\n\n local cmd=\"uv run '$SCRIPT_DIR/entra/get_m2m_token.py' --all-agents\"\n\n if [ -n \"$IDENTITIES_FILE\" ]; then\n cmd=\"$cmd --identities-file '$IDENTITIES_FILE'\"\n fi\n\n if [ \"$VERBOSE\" = true ]; then\n cmd=\"$cmd --verbose\"\n fi\n\n log_debug \"Executing: $cmd\"\n\n if eval \"$cmd\"; then\n log_info \"Entra ID token generation completed successfully\"\n return 0\n else\n log_error \"Entra ID token generation failed\"\n return 1\n fi\n}\n\n# Main execution\nmain() {\n # CLI argument takes precedence over environment variable\n local auth_provider\n if [ -n \"$AUTH_PROVIDER_ARG\" ]; then\n auth_provider=\"$AUTH_PROVIDER_ARG\"\n elif [ -n \"$AUTH_PROVIDER\" ]; then\n auth_provider=\"$AUTH_PROVIDER\"\n else\n log_error \"Auth provider is required. Provide via --auth-provider or AUTH_PROVIDER environment variable.\"\n log_error \"Valid values: 'keycloak' or 'entra'\"\n exit 1\n fi\n\n # Validate auth provider value\n if [ \"$auth_provider\" != \"keycloak\" ] && [ \"$auth_provider\" != \"entra\" ]; then\n log_error \"Invalid auth provider: $auth_provider (must be 'keycloak' or 'entra')\"\n exit 1\n fi\n\n log_info \"Starting Ingress Token Generator\"\n log_info \"AUTH_PROVIDER: $auth_provider\"\n\n local success=false\n\n if [ \"$auth_provider\" = \"entra\" ]; then\n if run_entra_auth; then\n success=true\n fi\n else\n if run_keycloak_auth; then\n success=true\n fi\n fi\n\n # Summary\n echo \"\"\n log_info \"Summary:\"\n if [ \"$success\" = true ]; then\n log_info \" Token generation: SUCCESS\"\n else\n log_info \" Token generation: FAILED\"\n fi\n\n log_info \"Check ./.oauth-tokens/ for generated token files\"\n\n if [ \"$success\" = false ]; then\n exit 1\n fi\n}\n\n# Run main function\nmain \"$@\"\n" }, { "path": "credentials-provider/keycloak/get_m2m_token.py", "content": "#!/usr/bin/env python3\n\"\"\"\nGenerate OAuth2 access tokens for MCP agents using Keycloak\nPython version of generate-agent-token.sh with batch processing capabilities\n\"\"\"\n\nimport argparse\nimport glob\nimport json\nimport logging\nimport os\nimport sys\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nimport requests\n\n\nclass Colors:\n \"\"\"ANSI color codes for console output\"\"\"\n\n RED = \"\\033[0;31m\"\n GREEN = \"\\033[0;32m\"\n YELLOW = \"\\033[1;33m\"\n BLUE = \"\\033[0;34m\"\n NC = \"\\033[0m\" # No Color\n\n\nclass TokenGenerator:\n \"\"\"Generate tokens for MCP agents using Keycloak OAuth2\"\"\"\n\n def __init__(self, verbose: bool = False):\n self.verbose = verbose\n self.setup_logging()\n\n def setup_logging(self):\n \"\"\"Setup logging configuration\"\"\"\n level = logging.DEBUG if self.verbose else logging.INFO\n logging.basicConfig(level=level, format=\"%(asctime)s - %(levelname)s - %(message)s\")\n self.logger = logging.getLogger(__name__)\n\n def log(self, message: str):\n \"\"\"Log info message if verbose mode is enabled\"\"\"\n if self.verbose:\n self.logger.debug(message)\n\n def error(self, message: str):\n \"\"\"Print error message\"\"\"\n self.logger.error(message)\n\n def success(self, message: str):\n \"\"\"Print success message\"\"\"\n self.logger.info(message)\n\n def warning(self, message: str):\n \"\"\"Print warning message\"\"\"\n self.logger.warning(message)\n\n def load_agent_config(self, agent_name: str, oauth_tokens_dir: str) -> dict[str, Any] | None:\n \"\"\"Load agent configuration from JSON file\"\"\"\n config_file = os.path.join(oauth_tokens_dir, f\"{agent_name}.json\")\n\n if not os.path.exists(config_file):\n self.error(f\"Config file not found: {config_file}\")\n return None\n\n self.log(f\"Loading config from: {config_file}\")\n\n try:\n with open(config_file) as f:\n config = json.load(f)\n return config\n except json.JSONDecodeError as e:\n self.error(f\"Failed to parse JSON config file: {e}\")\n return None\n except Exception as e:\n self.error(f\"Failed to load config file: {e}\")\n return None\n\n def get_token_from_keycloak(\n self, client_id: str, client_secret: str, keycloak_url: str, realm: str\n ) -> dict[str, Any] | None:\n \"\"\"Request access token from Keycloak\"\"\"\n token_url = f\"{keycloak_url}/realms/{realm}/protocol/openid-connect/token\"\n\n self.log(f\"Token URL: {token_url}\")\n self.log(f\"Client ID: {client_id}\")\n self.log(f\"Realm: {realm}\")\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"scope\": \"openid email profile\",\n }\n\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n try:\n response = requests.post(token_url, data=data, headers=headers, timeout=30)\n response.raise_for_status()\n\n token_data = response.json()\n\n # Check for error in response\n if \"error_description\" in token_data:\n self.error(f\"Token request failed: {token_data['error_description']}\")\n return None\n\n # Validate access token exists\n if \"access_token\" not in token_data:\n self.error(\"No access token in response\")\n self.log(f\"Response keys: {list(token_data.keys())}\")\n return None\n\n return token_data\n\n except requests.exceptions.RequestException as e:\n self.error(f\"Failed to make token request to Keycloak: {e}\")\n return None\n except json.JSONDecodeError as e:\n self.error(f\"Invalid JSON response: {e}\")\n return None\n\n def save_token_files(\n self,\n agent_name: str,\n token_data: dict[str, Any],\n client_id: str,\n client_secret: str,\n keycloak_url: str,\n realm: str,\n oauth_tokens_dir: str,\n ) -> bool:\n \"\"\"Save token to both .env and .json files\"\"\"\n access_token = token_data[\"access_token\"]\n expires_in = token_data.get(\"expires_in\")\n\n # Create output directory\n os.makedirs(oauth_tokens_dir, exist_ok=True)\n\n # Generate timestamps\n generated_at = datetime.now(UTC).isoformat()\n expires_at = None\n if expires_in:\n expiry_timestamp = datetime.now(UTC).timestamp() + expires_in\n expires_at = datetime.fromtimestamp(expiry_timestamp, UTC).isoformat()\n\n # Save .env file with restricted permissions (contains secrets)\n env_file = os.path.join(oauth_tokens_dir, f\"{agent_name}.env\")\n try:\n with open(env_file, \"w\") as f: # nosec - intentional credential storage for CLI token cache\n f.write(f\"# Generated access token for {agent_name}\\n\")\n f.write(f\"# Generated at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\\n\")\n f.write(f'export ACCESS_TOKEN=\"{access_token}\"\\n') # nosec - intentional token storage in secured file\n f.write(f'export CLIENT_ID=\"{client_id}\"\\n')\n f.write(f'export CLIENT_SECRET=\"{client_secret}\"\\n') # nosec - intentional credential storage in secured file\n f.write(f'export KEYCLOAK_URL=\"{keycloak_url}\"\\n')\n f.write(f'export KEYCLOAK_REALM=\"{realm}\"\\n')\n f.write('export AUTH_PROVIDER=\"keycloak\"\\n')\n os.chmod(env_file, 0o600) # Restrict file permissions to owner only\n except Exception as e:\n self.error(f\"Failed to save .env file: {e}\")\n return False\n\n # Save .json file with metadata\n json_file = os.path.join(oauth_tokens_dir, f\"{agent_name}-token.json\")\n token_json = {\n \"agent_name\": agent_name,\n \"access_token\": access_token,\n \"token_type\": \"Bearer\", # nosec B105 - OAuth2 standard token type per RFC 6750\n \"expires_in\": expires_in,\n \"generated_at\": generated_at,\n \"expires_at\": expires_at,\n \"provider\": \"keycloak\",\n \"keycloak_url\": keycloak_url,\n \"keycloak_realm\": realm,\n \"client_id\": client_id,\n \"scope\": \"openid email profile\",\n \"metadata\": {\n \"generated_by\": \"generate_tokens.py\",\n \"script_version\": \"1.0\",\n \"token_format\": \"JWT\", # nosec B105 - Standard token format identifier, not a password\n \"auth_method\": \"client_credentials\",\n },\n }\n\n try:\n with open(json_file, \"w\") as f:\n json.dump(token_json, f, indent=2)\n os.chmod(json_file, 0o600) # Restrict file permissions to owner only\n except Exception as e:\n self.error(f\"Failed to save JSON file: {e}\")\n return False\n\n self.success(f\"Token saved to: {env_file}\")\n self.success(f\"Token metadata saved to: {json_file}\")\n\n # Display token info (redacted for security)\n try:\n from ..utils import redact_sensitive_value\n except ImportError:\n # Fallback for when running as standalone script\n import sys\n from pathlib import Path\n\n utils_path = Path(__file__).parent.parent / \"utils.py\"\n if utils_path.exists():\n sys.path.insert(0, str(utils_path.parent))\n from utils import redact_sensitive_value\n else:\n # Simple fallback redaction function\n def redact_sensitive_value(value: str, show_chars: int = 8) -> str:\n if not value or len(value) <= show_chars:\n return \"*\" * len(value) if value else \"\"\n return value[:show_chars] + \"*\" * (len(value) - show_chars)\n\n redacted_token = redact_sensitive_value(access_token, 8)\n self.logger.info(f\"Access Token: {redacted_token}\")\n if expires_in:\n self.logger.info(f\"Expires in: {expires_in} seconds\")\n if expires_at:\n expiry_time = datetime.fromisoformat(expires_at.replace(\"Z\", \"+00:00\"))\n self.logger.info(f\"Expires at: {expiry_time.strftime('%Y-%m-%d %H:%M:%S UTC')}\")\n\n return True\n\n def generate_token_for_agent(\n self,\n agent_name: str,\n client_id: str = None,\n client_secret: str = None,\n keycloak_url: str = None,\n realm: str = \"mcp-gateway\",\n oauth_tokens_dir: str = None,\n ) -> bool:\n \"\"\"Generate token for a single agent\"\"\"\n if oauth_tokens_dir is None:\n oauth_tokens_dir = os.path.join(\n os.path.dirname(os.path.dirname(os.path.dirname(__file__))), \".oauth-tokens\"\n )\n\n # Load config from JSON if parameters not provided\n config = None\n if not all([client_id, client_secret, keycloak_url]):\n config = self.load_agent_config(agent_name, oauth_tokens_dir)\n if not config:\n return False\n\n # Use provided parameters or fall back to config\n if not client_id:\n client_id = config.get(\"client_id\")\n if not client_secret:\n client_secret = config.get(\"client_secret\")\n if not keycloak_url:\n keycloak_url = (\n config.get(\"keycloak_url\") or config.get(\"gateway_url\", \"\").split(\"/realms/\")[0]\n )\n\n # Also try to get realm from config\n if config and realm == \"mcp-gateway\":\n config_realm = config.get(\"keycloak_realm\") or config.get(\"realm\")\n if config_realm:\n realm = config_realm\n\n # Validate required parameters\n if not client_id:\n self.error(\"CLIENT_ID is required. Provide via --client-id or in config file.\")\n return False\n if not client_secret:\n self.error(\"CLIENT_SECRET is required. Provide via --client-secret or in config file.\")\n return False\n if not keycloak_url:\n self.error(\"KEYCLOAK_URL is required. Provide via --keycloak-url or in config file.\")\n return False\n\n self.logger.info(f\"Requesting access token for agent: {agent_name}\")\n\n # Get token from Keycloak\n token_data = self.get_token_from_keycloak(client_id, client_secret, keycloak_url, realm)\n if not token_data:\n return False\n\n self.success(\"Access token generated successfully!\")\n\n # Save token files\n return self.save_token_files(\n agent_name, token_data, client_id, client_secret, keycloak_url, realm, oauth_tokens_dir\n )\n\n def find_agent_configs(self, oauth_tokens_dir: str) -> list[str]:\n \"\"\"Find all agent-{}.json files, excluding agent-{}-token.json files\"\"\"\n if not os.path.exists(oauth_tokens_dir):\n self.warning(f\"OAuth tokens directory not found: {oauth_tokens_dir}\")\n return []\n\n # Find all agent-*.json files\n pattern = os.path.join(oauth_tokens_dir, \"agent-*.json\")\n all_files = glob.glob(pattern)\n\n # Filter out token files (agent-*-token.json)\n agent_configs = []\n for file_path in all_files:\n filename = os.path.basename(file_path)\n if not filename.endswith(\"-token.json\"):\n # Use the full filename without extension as agent name\n agent_name = filename[:-5] # Remove '.json' (5 chars)\n agent_configs.append(agent_name)\n\n return sorted(agent_configs)\n\n def generate_tokens_for_all_agents(\n self, oauth_tokens_dir: str = None, keycloak_url: str = None, realm: str = \"mcp-gateway\"\n ) -> bool:\n \"\"\"Generate tokens for all agents found in .oauth-tokens directory\"\"\"\n if oauth_tokens_dir is None:\n oauth_tokens_dir = os.path.join(\n os.path.dirname(os.path.dirname(os.path.dirname(__file__))), \".oauth-tokens\"\n )\n\n self.log(f\"Searching for agent configs in: {oauth_tokens_dir}\")\n\n agent_configs = self.find_agent_configs(oauth_tokens_dir)\n\n if not agent_configs:\n self.warning(\"No agent configuration files found\")\n return True\n\n self.success(\n f\"Found {len(agent_configs)} agent configuration(s): {', '.join(agent_configs)}\"\n )\n\n success_count = 0\n total_count = len(agent_configs)\n\n for agent_name in agent_configs:\n self.logger.info(\"=\" * 60)\n self.logger.info(f\"Processing agent: {agent_name}\")\n self.logger.info(\"=\" * 60)\n\n try:\n if self.generate_token_for_agent(\n agent_name,\n keycloak_url=keycloak_url,\n realm=realm,\n oauth_tokens_dir=oauth_tokens_dir,\n ):\n success_count += 1\n else:\n self.error(f\"Failed to generate token for agent: {agent_name}\")\n except Exception as e:\n self.error(f\"Exception while processing agent {agent_name}: {e}\")\n\n self.logger.info(\"=\" * 60)\n self.logger.info(f\"Token generation complete: {success_count}/{total_count} successful\")\n self.logger.info(\"=\" * 60)\n\n return success_count == total_count\n\n\ndef main():\n \"\"\"Main function\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Generate OAuth2 access tokens for MCP agents using Keycloak\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Generate tokens for all agents in .oauth-tokens directory\n python generate_tokens.py --all-agents\n\n # Generate token for specific agent\n python generate_tokens.py --agent-name my-agent\n\n # Generate token with custom parameters\n python generate_tokens.py --agent-name my-agent --client-id custom-client --keycloak-url http://localhost:8080\n\n # Generate tokens for all agents with custom Keycloak URL\n python generate_tokens.py --all-agents --keycloak-url http://localhost:8080\n \"\"\",\n )\n\n parser.add_argument(\"--agent-name\", type=str, help=\"Specific agent name to generate token for\")\n parser.add_argument(\n \"--all-agents\",\n action=\"store_true\",\n help=\"Generate tokens for all agents found in .oauth-tokens directory\",\n )\n parser.add_argument(\"--client-id\", type=str, help=\"OAuth2 client ID (overrides config file)\")\n parser.add_argument(\n \"--client-secret\", type=str, help=\"OAuth2 client secret (overrides config file)\"\n )\n parser.add_argument(\n \"--keycloak-url\", type=str, help=\"Keycloak server URL (overrides config file)\"\n )\n parser.add_argument(\n \"--realm\", type=str, default=\"mcp-gateway\", help=\"Keycloak realm (default: mcp-gateway)\"\n )\n parser.add_argument(\n \"--oauth-dir\", type=str, help=\"OAuth tokens directory (default: ../../.oauth-tokens)\"\n )\n parser.add_argument(\"--verbose\", \"-v\", action=\"store_true\", help=\"Verbose output\")\n\n args = parser.parse_args()\n\n # Validate arguments\n if not args.all_agents and not args.agent_name:\n parser.error(\"Must specify either --all-agents or --agent-name\")\n\n if args.all_agents and args.agent_name:\n parser.error(\"Cannot specify both --all-agents and --agent-name\")\n\n # Initialize token generator\n generator = TokenGenerator(verbose=args.verbose)\n\n # Determine oauth tokens directory\n oauth_tokens_dir = args.oauth_dir\n if oauth_tokens_dir is None:\n oauth_tokens_dir = os.path.join(\n os.path.dirname(os.path.dirname(os.path.dirname(__file__))), \".oauth-tokens\"\n )\n\n try:\n if args.all_agents:\n # Generate tokens for all agents\n success = generator.generate_tokens_for_all_agents(\n oauth_tokens_dir=oauth_tokens_dir, keycloak_url=args.keycloak_url, realm=args.realm\n )\n else:\n # Generate token for specific agent\n success = generator.generate_token_for_agent(\n agent_name=args.agent_name,\n client_id=args.client_id,\n client_secret=args.client_secret,\n keycloak_url=args.keycloak_url,\n realm=args.realm,\n oauth_tokens_dir=oauth_tokens_dir,\n )\n\n sys.exit(0 if success else 1)\n\n except KeyboardInterrupt:\n generator.warning(\"Operation interrupted by user\")\n sys.exit(1)\n except Exception as e:\n generator.error(f\"Unexpected error: {e}\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "credentials-provider/oauth/.env.example", "content": "# =============================================================================\n# MCP Gateway Registry - OAuth Environment Configuration\n# =============================================================================\n# Copy this file to .env and update with your actual OAuth provider credentials\n# This file contains credentials for both ingress and egress OAuth flows\n\n# =============================================================================\n# REGISTRY CONFIGURATION\n# =============================================================================\n\n# Public URL where the MCP Gateway Registry is accessible\nREGISTRY_URL=https://your-domain.com\n\n# Registry URL (can be same as main .env)\n# Authentication is handled via Keycloak OAuth2 (no local admin password)\n\n# =============================================================================\n# AUTH SERVER CONFIGURATION\n# =============================================================================\n\n# Internal and external auth server URLs\nAUTH_SERVER_URL=http://auth-server:8888\nAUTH_SERVER_EXTERNAL_URL=https://your-domain.com\n\n# =============================================================================\n# AUTHENTICATION PROVIDER SELECTION\n# =============================================================================\n# Choose authentication provider: cognito or keycloak\nAUTH_PROVIDER=keycloak\n\n# =============================================================================\n# AWS COGNITO OAUTH2 CONFIGURATION\n# =============================================================================\n# AWS Configuration\nAWS_REGION=us-east-1\n\nINGRESS_OAUTH_USER_POOL_ID=us-east-1_XXXXXXXXX\n#INGRESS_OAUTH_USER_POOL_ID=us-east-1_YRy6fCXkS\n\n# Ingress OAuth App Client ID (copied from .env.agent working credentials)\nINGRESS_OAUTH_CLIENT_ID=your_ingress_client_id_here #alternative_client_id\n#INGRESS_OAUTH_CLIENT_ID=alternative_client_id_2\n\n# Ingress OAuth App Client Secret (copied from .env.agent working credentials)\nINGRESS_OAUTH_CLIENT_SECRET=your_ingress_client_secret_here #alternative_secret\n#INGRESS_OAUTH_CLIENT_SECRET=alternative_secret_2\n\n# =============================================================================\n# KEYCLOAK OAUTH2 CONFIGURATION (if AUTH_PROVIDER=keycloak)\n# =============================================================================\n# Keycloak server configuration\nKEYCLOAK_URL=https://your-domain.com/keycloak\nKEYCLOAK_REALM=mcp-gateway\n\n# Keycloak M2M Client Credentials (for ingress authentication)\nKEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_M2M_CLIENT_SECRET=your_keycloak_m2m_client_secret_here\n\n# =============================================================================\n# EGRESS OAUTH CONFIGURATION (Optional - for external services)\n# =============================================================================\n# Configure multiple external OAuth providers using numbered suffixes\n# Supports configurations _1, _2, _3, etc. (up to _100)\n\n# Configuration Set 1 - Example: Atlassian\nEGRESS_OAUTH_CLIENT_ID_1=your_atlassian_client_id_here\nEGRESS_OAUTH_CLIENT_SECRET_1=your_atlassian_client_secret_here\nEGRESS_OAUTH_REDIRECT_URI_1=http://localhost:9999/callback\n# IMPORTANT: This redirect URI MUST match exactly what you configure in your Atlassian OAuth app settings\n# EGRESS_OAUTH_SCOPE_1=read:confluence-content.all,write:confluence-content\nEGRESS_PROVIDER_NAME_1=atlassian\nEGRESS_MCP_SERVER_NAME_1=atlassian\n\n# Configuration Set 2 - Example: Google\n# EGRESS_OAUTH_CLIENT_ID_2=your_google_client_id_here\n# EGRESS_OAUTH_CLIENT_SECRET_2=your_google_client_secret_here\n# EGRESS_OAUTH_REDIRECT_URI_2=http://localhost:9999/callback\n# EGRESS_OAUTH_SCOPE_2=https://www.googleapis.com/auth/drive.readonly\n# EGRESS_PROVIDER_NAME_2=google\n# EGRESS_MCP_SERVER_NAME_2=google-drive\n\n# Configuration Set 3 - Example: GitHub\n# EGRESS_OAUTH_CLIENT_ID_3=your_github_client_id_here\n# EGRESS_OAUTH_CLIENT_SECRET_3=your_github_client_secret_here\n# EGRESS_OAUTH_REDIRECT_URI_3=http://localhost:9999/callback\n# EGRESS_OAUTH_SCOPE_3=repo,read:user\n# EGRESS_PROVIDER_NAME_3=github\n# EGRESS_MCP_SERVER_NAME_3=github-repos\n\n# Configuration Set 4 - Example: Microsoft\n# EGRESS_OAUTH_CLIENT_ID_4=your_microsoft_client_id_here\n# EGRESS_OAUTH_CLIENT_SECRET_4=your_microsoft_client_secret_here\n# EGRESS_OAUTH_REDIRECT_URI_4=http://localhost:9999/callback\n# EGRESS_OAUTH_SCOPE_4=https://graph.microsoft.com/mail.read\n# EGRESS_PROVIDER_NAME_4=microsoft\n# EGRESS_MCP_SERVER_NAME_4=outlook\n\n# =============================================================================\n# CONFIGURATION NOTES\n# =============================================================================\n\n# Provider Names Supported:\n# - atlassian: Atlassian Cloud (Confluence, Jira)\n# - google: Google services (Drive, Gmail, Calendar)\n# - github: GitHub repositories and issues\n# - microsoft: Microsoft 365 services\n# - bedrock-agentcore: Amazon Bedrock AgentCore services\n\n# Redirect URI Notes:\n# - CRITICAL: The redirect URI in this file MUST match exactly what you configure in your OAuth provider settings\n# - For local development: http://localhost:9999/callback (changed from 8080 to avoid Keycloak port conflicts)\n# - For production: https://your-domain.com/oauth/callback\n# - If URLs don't match exactly, OAuth flow will fail with \"redirect_uri not registered\" error\n\n# Scope Notes:\n# - If EGRESS_OAUTH_SCOPE_N is not specified, provider defaults will be used\n# - Each provider has different scope formats and requirements\n# - Consult provider documentation for available scopes\n\n# Security Notes:\n# - Keep this file secure and never commit real credentials\n# - Use environment-specific values for different deployments\n# - Rotate credentials regularly for production environments" }, { "path": "credentials-provider/oauth/egress_oauth.py", "content": "#!/usr/bin/env python3\n\"\"\"\nEgress OAuth Authentication Script\n\nThis script handles OAuth authentication for egress (outbound) connections to external services.\nIt supports multiple OAuth providers with Atlassian as the default.\n\nThe script:\n1. Validates required EGRESS OAuth environment variables\n2. Performs OAuth authentication flow for external providers (Atlassian, Google, GitHub, etc.)\n3. Saves tokens to {provider}-egress.json in the OAuth tokens directory\n4. Does not generate MCP configuration files (handled by oauth_creds.sh)\n\nEnvironment Variables Required (with numbered configuration sets):\n- EGRESS_OAUTH_CLIENT_ID_N: OAuth Client ID for external provider\n- EGRESS_OAUTH_CLIENT_SECRET_N: OAuth Client Secret for external provider\n- EGRESS_OAUTH_REDIRECT_URI_N: OAuth Redirect URI (defaults to localhost:8080/callback)\n- EGRESS_OAUTH_SCOPE_N: OAuth scopes (optional, uses provider defaults)\n- EGRESS_PROVIDER_NAME_N: Provider name (atlassian, google, github, etc.)\n- EGRESS_MCP_SERVER_NAME_N: MCP server name for token file naming\n\nWhere N is a configuration number from 1 to 100.\n\nUsage:\n python egress_oauth.py # Use Atlassian (default)\n python egress_oauth.py --provider google # Use Google\n python egress_oauth.py --provider atlassian --verbose # Atlassian with debug\n python egress_oauth.py --force # Force new token generation\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nimport time\nfrom pathlib import Path\nfrom typing import Any\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n# Try to load .env file if python-dotenv is available\ntry:\n from dotenv import load_dotenv\n\n # Load .env from the same directory as this script\n env_file = Path(__file__).parent / \".env\"\n if env_file.exists():\n load_dotenv(env_file)\n logger.debug(f\"Loaded environment variables from {env_file}\")\n else:\n # Fallback: try parent directory (project root)\n env_file_parent = Path(__file__).parent.parent / \".env\"\n if env_file_parent.exists():\n load_dotenv(env_file_parent)\n logger.debug(f\"Loaded environment variables from {env_file_parent}\")\n else:\n # Final fallback: try current working directory\n load_dotenv()\n logger.debug(\"Tried to load .env from current working directory\")\nexcept ImportError:\n logger.debug(\"python-dotenv not available, skipping .env loading\")\n\n\ndef _find_available_configurations() -> list[int]:\n \"\"\"Find all available configuration sets (1-100) based on environment variables.\"\"\"\n available_configs = []\n\n for i in range(1, 101): # Check configurations 1-100\n required_vars = [\n f\"EGRESS_OAUTH_CLIENT_ID_{i}\",\n f\"EGRESS_OAUTH_CLIENT_SECRET_{i}\",\n f\"EGRESS_OAUTH_REDIRECT_URI_{i}\",\n ]\n\n # Check if all required variables for this config set exist\n if all(os.getenv(var) for var in required_vars):\n available_configs.append(i)\n\n return available_configs\n\n\ndef _validate_environment_variables() -> None:\n \"\"\"Validate that at least one complete EGRESS OAuth configuration set is available.\"\"\"\n available_configs = _find_available_configurations()\n\n if not available_configs:\n logger.error(\"No complete EGRESS OAuth configuration sets found!\")\n logger.error(\"Please set at least one complete configuration set with variables like:\")\n logger.error(\" EGRESS_OAUTH_CLIENT_ID_1=\")\n logger.error(\" EGRESS_OAUTH_CLIENT_SECRET_1=\")\n logger.error(\" EGRESS_OAUTH_REDIRECT_URI_1=\")\n logger.error(\" EGRESS_PROVIDER_NAME_1=\")\n logger.error(\" EGRESS_MCP_SERVER_NAME_1=\")\n logger.error(\"\\nConfiguration sets can be numbered from _1 to _100\")\n raise SystemExit(1)\n\n logger.debug(f\"Found {len(available_configs)} complete configuration sets: {available_configs}\")\n\n\ndef _run_generic_oauth_flow_for_config(\n config_num: int, provider: str, force_new: bool = False, verbose: bool = False\n) -> dict[str, Any]:\n \"\"\"Run the generic OAuth flow using a specific configuration set.\"\"\"\n import subprocess # nosec B404\n\n # Get configuration-specific environment variables\n client_id = os.getenv(f\"EGRESS_OAUTH_CLIENT_ID_{config_num}\")\n client_secret = os.getenv(f\"EGRESS_OAUTH_CLIENT_SECRET_{config_num}\")\n redirect_uri = os.getenv(f\"EGRESS_OAUTH_REDIRECT_URI_{config_num}\")\n scope = os.getenv(f\"EGRESS_OAUTH_SCOPE_{config_num}\")\n\n if not all([client_id, client_secret, redirect_uri]):\n raise ValueError(f\"Missing required OAuth configuration for set {config_num}\")\n\n # Build command with configuration-specific parameters\n cmd = [\n \"python\",\n str(Path(__file__).parent / \"generic_oauth_flow.py\"),\n \"--provider\",\n provider,\n \"--client-id\",\n client_id,\n \"--client-secret\",\n client_secret,\n \"--redirect-uri\",\n redirect_uri,\n ]\n\n if scope:\n cmd.extend([\"--scope\", scope])\n\n if force_new:\n cmd.append(\"--force\")\n\n if verbose:\n cmd.append(\"--verbose\")\n\n logger.info(f\"Running OAuth flow for provider: {provider} (config set {config_num})\")\n logger.debug(f\"Command: {cmd[0]} {cmd[1]} --provider {provider} [credentials redacted]\")\n\n try:\n # Run the generic OAuth flow\n result = subprocess.run( # nosec B603 - internal script path, args from validated env vars\n cmd,\n capture_output=True,\n text=True,\n timeout=300, # 5 minute timeout\n )\n\n if result.returncode != 0:\n logger.error(f\"OAuth flow failed with exit code {result.returncode}\")\n logger.error(f\"stdout: {result.stdout}\")\n logger.error(f\"stderr: {result.stderr}\")\n raise RuntimeError(f\"Generic OAuth flow failed for {provider}\")\n\n logger.debug(\"OAuth flow completed successfully\")\n logger.debug(f\"stdout: {result.stdout}\")\n\n # Parse the JSON output from the OAuth flow\n import json\n\n # Extract JSON from stdout (last line should be the JSON output)\n output_lines = result.stdout.strip().split(\"\\n\")\n json_output = None\n\n for line in reversed(output_lines):\n try:\n json_output = json.loads(line)\n break\n except json.JSONDecodeError:\n continue\n\n if not json_output:\n raise RuntimeError(\"Could not parse JSON output from OAuth flow\")\n\n return json_output\n\n except subprocess.TimeoutExpired:\n logger.error(\"OAuth flow timed out after 5 minutes\")\n raise RuntimeError(f\"OAuth flow timed out for {provider}\")\n except Exception as e:\n logger.error(f\"Error running OAuth flow: {e}\")\n raise\n\n\ndef _run_generic_oauth_flow(\n provider: str, force_new: bool = False, verbose: bool = False\n) -> dict[str, Any]:\n \"\"\"Run the generic OAuth flow using the existing script.\"\"\"\n import subprocess # nosec B404\n\n # Build command\n cmd = [\"python\", str(Path(__file__).parent / \"generic_oauth_flow.py\"), \"--provider\", provider]\n\n if force_new:\n cmd.append(\"--force\")\n\n if verbose:\n cmd.append(\"--verbose\")\n\n logger.info(f\"Running OAuth flow for provider: {provider}\")\n logger.debug(f\"Command: {' '.join(cmd)}\")\n\n try:\n # Run the generic OAuth flow\n result = subprocess.run( # nosec B603 - internal script path, args from validated env vars\n cmd,\n capture_output=True,\n text=True,\n timeout=300, # 5 minute timeout\n )\n\n if result.returncode != 0:\n logger.error(f\"OAuth flow failed for {provider}\")\n logger.error(f\"STDOUT: {result.stdout}\")\n logger.error(f\"STDERR: {result.stderr}\")\n raise RuntimeError(f\"OAuth flow failed with return code {result.returncode}\")\n\n logger.info(f\"✅ OAuth flow completed successfully for {provider}\")\n if verbose:\n logger.debug(f\"OAuth flow output: {result.stdout}\")\n\n # Parse the output to extract token information\n # The generic_oauth_flow.py saves tokens to ~/.oauth-tokens/\n return _load_provider_tokens(provider)\n\n except subprocess.TimeoutExpired:\n logger.error(f\"OAuth flow timed out for {provider}\")\n raise\n except Exception as e:\n logger.error(f\"Failed to run OAuth flow for {provider}: {e}\")\n raise\n\n\ndef _load_provider_tokens(provider: str) -> dict[str, Any]:\n \"\"\"Load tokens for the specified provider from the OAuth tokens directory.\"\"\"\n try:\n token_dir = Path.cwd() / \".oauth-tokens\"\n\n # Look for provider-specific token files\n pattern = f\"oauth-{provider}-*.json\"\n token_files = list(token_dir.glob(pattern))\n\n if not token_files:\n raise FileNotFoundError(f\"No token files found for provider {provider}\")\n\n # Use the most recent token file\n latest_file = max(token_files, key=lambda f: f.stat().st_mtime)\n\n with open(latest_file) as f:\n token_data = json.load(f)\n\n logger.debug(f\"Loaded tokens from: {latest_file}\")\n return token_data\n\n except Exception as e:\n logger.error(f\"Failed to load provider tokens for {provider}: {e}\")\n raise\n\n\ndef _save_egress_tokens(\n token_data: dict[str, Any], provider: str, mcp_server_name: str | None = None\n) -> str:\n \"\"\"Save egress tokens to provider-specific egress file.\"\"\"\n try:\n # Create .oauth-tokens directory in current working directory\n token_dir = Path.cwd() / \".oauth-tokens\"\n token_dir.mkdir(exist_ok=True, mode=0o700)\n\n # Save to {provider}-{server_name}-egress.json if server name provided\n if mcp_server_name:\n egress_path = token_dir / f\"{provider}-{mcp_server_name}-egress.json\"\n else:\n # Save to {provider}-egress.json\n egress_path = token_dir / f\"{provider}-egress.json\"\n\n # Prepare token data for storage\n save_data = {\n \"provider\": provider,\n \"access_token\": token_data.get(\"access_token\"),\n \"refresh_token\": token_data.get(\"refresh_token\"),\n \"expires_at\": token_data.get(\"expires_at\"),\n \"expires_at_human\": time.strftime(\n \"%Y-%m-%d %H:%M:%S UTC\", time.gmtime(token_data[\"expires_at\"])\n )\n if token_data.get(\"expires_at\")\n else None,\n \"cloud_id\": token_data.get(\"cloud_id\"), # For Atlassian\n \"scopes\": token_data.get(\"scopes\", []),\n \"saved_at\": time.strftime(\"%Y-%m-%d %H:%M:%S UTC\", time.gmtime()),\n \"usage_notes\": f\"This token is for EGRESS authentication to {provider} external services\",\n }\n\n with open(egress_path, \"w\") as f:\n json.dump(save_data, f, indent=2)\n\n # Secure the file\n egress_path.chmod(0o600)\n logger.info(f\"📁 Saved egress tokens to: {egress_path}\")\n\n return str(egress_path)\n\n except Exception as e:\n logger.error(f\"Failed to save egress tokens: {e}\")\n raise\n\n\ndef _load_existing_tokens(\n provider: str = None, mcp_server_name: str | None = None\n) -> dict[str, Any] | None:\n \"\"\"Load existing egress tokens if they exist and are valid.\"\"\"\n try:\n # If provider specified, look for provider-specific file\n if provider:\n # Try provider-server specific file first if server name provided\n if mcp_server_name:\n egress_path = (\n Path.cwd() / \".oauth-tokens\" / f\"{provider}-{mcp_server_name}-egress.json\"\n )\n if not egress_path.exists():\n # Fallback to provider-only file\n egress_path = Path.cwd() / \".oauth-tokens\" / f\"{provider}-egress.json\"\n else:\n egress_path = Path.cwd() / \".oauth-tokens\" / f\"{provider}-egress.json\"\n else:\n # Fallback to generic egress.json for backward compatibility\n egress_path = Path.cwd() / \".oauth-tokens\" / \"egress.json\"\n\n if not egress_path.exists():\n return None\n\n with open(egress_path) as f:\n token_data = json.load(f)\n\n # Check if token is expired\n if token_data.get(\"expires_at\"):\n expires_at = token_data[\"expires_at\"]\n # Add 5 minute margin\n if time.time() + 300 >= expires_at:\n logger.info(\"Existing egress token is expired or will expire soon\")\n return None\n\n logger.info(\"Found valid existing egress token\")\n return token_data\n\n except Exception as e:\n logger.debug(f\"Failed to load existing tokens: {e}\")\n return None\n\n\ndef _get_supported_providers() -> list[str]:\n \"\"\"Get list of supported external providers (exclude cognito providers).\"\"\"\n try:\n import yaml\n\n yaml_path = Path(__file__).parent / \"oauth_providers.yaml\"\n\n if not yaml_path.exists():\n # Fallback to known external providers\n return [\n \"atlassian\",\n \"google\",\n \"github\",\n \"microsoft\",\n \"slack\",\n \"discord\",\n \"linkedin\",\n \"spotify\",\n \"twitter\",\n ]\n\n with open(yaml_path) as f:\n config = yaml.safe_load(f)\n providers = config.get(\"providers\", {})\n\n # Filter out cognito providers (those are for ingress)\n external_providers = [\n name for name, config in providers.items() if not name.startswith(\"cognito\")\n ]\n\n return external_providers\n\n except Exception as e:\n logger.debug(f\"Failed to load providers list: {e}\")\n # Fallback to known external providers\n return [\n \"atlassian\",\n \"google\",\n \"github\",\n \"microsoft\",\n \"slack\",\n \"discord\",\n \"linkedin\",\n \"spotify\",\n \"twitter\",\n ]\n\n\ndef main() -> int:\n \"\"\"Main entry point.\"\"\"\n supported_providers = _get_supported_providers()\n\n parser = argparse.ArgumentParser(\n description=\"Egress OAuth Authentication for External Services\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=f\"\"\"\nExamples:\n python egress_oauth.py # Use Atlassian (default)\n python egress_oauth.py --provider google # Use Google\n python egress_oauth.py --provider github --verbose # GitHub with debug\n python egress_oauth.py --force # Force new token generation\n\nSupported Providers:\n {\", \".join(supported_providers)}\n\nEnvironment Variables Required (numbered configuration sets 1-100):\n EGRESS_OAUTH_CLIENT_ID_N # OAuth Client ID for external provider\n EGRESS_OAUTH_CLIENT_SECRET_N # OAuth Client Secret for external provider\n EGRESS_OAUTH_REDIRECT_URI_N # OAuth Redirect URI (defaults to localhost:8080/callback)\n EGRESS_OAUTH_SCOPE_N # OAuth scopes (optional, uses provider defaults)\n EGRESS_PROVIDER_NAME_N # Provider name (atlassian, google, github, etc.)\n EGRESS_MCP_SERVER_NAME_N # MCP server name for token file naming\n \n Where N is a number from 1 to 100 (e.g., EGRESS_OAUTH_CLIENT_ID_1)\n\"\"\",\n )\n\n parser.add_argument(\n \"--provider\",\n choices=supported_providers,\n default=None,\n help=\"External OAuth provider (if not specified, processes all available configurations)\",\n )\n parser.add_argument(\n \"--mcp-server-name\",\n type=str,\n default=None,\n help=\"MCP server name (e.g., jira, confluence) for provider-specific configs\",\n )\n parser.add_argument(\n \"--config-set\",\n type=int,\n default=None,\n help=\"Specific configuration set number (1-100) to process\",\n )\n parser.add_argument(\"--verbose\", \"-v\", action=\"store_true\", help=\"Enable verbose debug logging\")\n parser.add_argument(\n \"--force\",\n \"-f\",\n action=\"store_true\",\n help=\"Force new token generation, ignore existing valid tokens\",\n )\n\n args = parser.parse_args()\n\n if args.verbose:\n logging.getLogger().setLevel(logging.DEBUG)\n logger.setLevel(logging.DEBUG)\n\n try:\n # Validate environment variables\n _validate_environment_variables()\n\n # Get available configurations\n available_configs = _find_available_configurations()\n\n # Determine which configurations to process\n if args.config_set:\n # Process specific configuration set\n if args.config_set not in available_configs:\n logger.error(f\"Configuration set {args.config_set} not found or incomplete\")\n return 1\n configs_to_process = [args.config_set]\n elif args.provider:\n # Find configurations for specific provider\n configs_to_process = []\n for config_num in available_configs:\n provider_name = os.getenv(f\"EGRESS_PROVIDER_NAME_{config_num}\")\n if provider_name == args.provider:\n configs_to_process.append(config_num)\n\n if not configs_to_process:\n logger.error(f\"No configurations found for provider: {args.provider}\")\n return 1\n else:\n # Process all available configurations\n configs_to_process = available_configs\n\n logger.info(\n f\"🔐 Processing {len(configs_to_process)} configuration(s): {configs_to_process}\"\n )\n\n success_count = 0\n failure_count = 0\n\n for config_num in configs_to_process:\n try:\n # Get configuration details\n provider = os.getenv(f\"EGRESS_PROVIDER_NAME_{config_num}\")\n server_name = os.getenv(f\"EGRESS_MCP_SERVER_NAME_{config_num}\")\n\n if not provider:\n logger.warning(\n f\"Skipping config {config_num}: EGRESS_PROVIDER_NAME_{config_num} not set\"\n )\n continue\n\n logger.info(\n f\"\\n📋 Processing configuration {config_num}: {provider}\"\n + (f\" ({server_name})\" if server_name else \"\")\n )\n\n # Check for existing valid tokens (unless force is specified)\n if not args.force:\n existing_tokens = _load_existing_tokens(provider, server_name)\n if existing_tokens and existing_tokens.get(\"provider\") == provider:\n server_info = f\" ({server_name})\" if server_name else \"\"\n logger.info(\n f\"✅ Using existing valid egress token for {provider}{server_info}\"\n )\n logger.info(\n f\"Token expires at: {existing_tokens.get('expires_at_human', 'Unknown')}\"\n )\n success_count += 1\n continue\n\n # Run OAuth flow for this configuration\n token_data = _run_generic_oauth_flow_for_config(\n config_num=config_num,\n provider=provider,\n force_new=args.force,\n verbose=args.verbose,\n )\n\n # Save tokens to {provider}-egress.json or {provider}-{server_name}-egress.json\n saved_path = _save_egress_tokens(token_data, provider, server_name)\n\n logger.info(f\"✅ EGRESS OAuth authentication completed for {provider}!\")\n logger.info(f\"Tokens saved to: {saved_path}\")\n success_count += 1\n\n except Exception as e:\n logger.error(f\"❌ Failed to process configuration {config_num}: {e}\")\n if args.verbose:\n import traceback\n\n logger.error(traceback.format_exc())\n failure_count += 1\n\n # Summary\n logger.info(f\"\\n📊 Summary: {success_count} successful, {failure_count} failed\")\n\n return 0 if failure_count == 0 else 1\n\n except Exception as e:\n logger.error(f\"❌ EGRESS OAuth authentication failed: {e}\")\n if args.verbose:\n import traceback\n\n logger.error(traceback.format_exc())\n return 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "credentials-provider/oauth/generic_oauth_flow.py", "content": "#!/usr/bin/env python3\n\"\"\"\nGeneric OAuth 2.0 Authorization Flow Script\n\nA standalone, generic OAuth 2.0 authorization script that can work with multiple providers\nincluding Atlassian, Google, GitHub, and others. Now powered by FastAPI for reliable callback handling.\n\nThis script provides:\n1. Multi-provider OAuth 2.0 support with configurable providers\n2. FastAPI-based local callback server for reliable authorization code handling\n3. Secure file-based token storage\n4. Automatic token refresh functionality\n5. PKCE support for enhanced security\n6. Beautiful browser callback pages with auto-close functionality\n7. Immediate token exchange during callback for better user experience\n8. Comprehensive logging and error handling\n\nUsage:\n # Interactive mode (recommended for first-time users)\n python generic_oauth_flow.py\n\n # Command line mode\n python generic_oauth_flow.py --provider atlassian --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n python generic_oauth_flow.py --provider google --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n python generic_oauth_flow.py --config-file oauth_config.json\n\n # Force interactive mode even with partial args\n python generic_oauth_flow.py --interactive\n\nEnvironment variables are also supported:\n- EGRESS_OAUTH_CLIENT_ID\n- EGRESS_OAUTH_CLIENT_SECRET\n- EGRESS_OAUTH_REDIRECT_URI\n- EGRESS_OAUTH_SCOPE\n\nDependencies:\n pip install requests pyyaml\n\"\"\"\n\nimport argparse\nimport base64\nimport hashlib\nimport http.server\nimport json\nimport logging\nimport os\nimport secrets\nimport socketserver\nimport sys\nimport threading\nimport time\nimport urllib.parse\nimport webbrowser\nfrom dataclasses import dataclass\nfrom pathlib import Path\nfrom typing import Any\n\n# Removed keyring dependency - using file-based storage only\nimport requests\nimport yaml\n\n# Configure logging first\nlogging.basicConfig(\n level=logging.INFO, format=\"%(asctime)s - %(levelname)s - %(name)s - %(message)s\"\n)\nlogger = logging.getLogger(\"generic-oauth\")\n\n# Try to load .env file if python-dotenv is available\ntry:\n from dotenv import load_dotenv\n\n # Load .env from the same directory as this script\n env_file = Path(__file__).parent / \".env\"\n if env_file.exists():\n load_dotenv(env_file)\n logger.debug(f\"Loaded environment variables from {env_file}\")\n else:\n # Fallback: try parent directory (project root)\n env_file_parent = Path(__file__).parent.parent / \".env\"\n if env_file_parent.exists():\n load_dotenv(env_file_parent)\n logger.debug(f\"Loaded environment variables from {env_file_parent}\")\n else:\n # Final fallback: try current working directory\n load_dotenv()\n logger.debug(\"Tried to load .env from current working directory\")\nexcept ImportError:\n logger.debug(\"python-dotenv not available, skipping .env loading\")\n\n\ndef _validate_environment_variables() -> None:\n \"\"\"Validate that all required INGRESS and EGRESS OAuth environment variables are set.\"\"\"\n required_ingress_vars = [\n \"INGRESS_OAUTH_USER_POOL_ID\",\n \"INGRESS_OAUTH_CLIENT_ID\",\n \"INGRESS_OAUTH_CLIENT_SECRET\",\n ]\n\n required_egress_vars = [\n \"EGRESS_OAUTH_CLIENT_ID\",\n \"EGRESS_OAUTH_CLIENT_SECRET\",\n \"EGRESS_OAUTH_REDIRECT_URI\",\n ]\n\n missing_vars = []\n\n # Check INGRESS variables\n for var in required_ingress_vars:\n if not os.getenv(var):\n missing_vars.append(var)\n\n # Check EGRESS variables\n for var in required_egress_vars:\n if not os.getenv(var):\n missing_vars.append(var)\n\n if missing_vars:\n logger.error(\"Missing required environment variables:\")\n for var in missing_vars:\n logger.error(f\" - {var}\")\n logger.error(\"\\nPlease set the following environment variables:\")\n logger.error(\"INGRESS OAuth variables (for MCP Gateway authentication):\")\n for var in required_ingress_vars:\n if var in missing_vars:\n logger.error(f\" export {var}=\")\n logger.error(\"\\nEGRESS OAuth variables (for external OAuth providers):\")\n for var in required_egress_vars:\n if var in missing_vars:\n logger.error(f\" export {var}=\")\n logger.error(\"\\nOr add them to your .env file\")\n raise SystemExit(1)\n\n logger.debug(\"All required INGRESS and EGRESS OAuth environment variables are set\")\n\n\n# Environment variable validation will be done conditionally in main()\n\n# Constants\nTOKEN_EXPIRY_MARGIN = 300 # 5 minutes in seconds\n# Removed keyring service name - using file-based storage only\nDEFAULT_REDIRECT_PORT = 8080\n\n\n# Load OAuth provider configurations from YAML file\ndef _load_oauth_providers() -> dict[str, Any]:\n \"\"\"Load OAuth provider configurations from YAML file.\"\"\"\n yaml_path = Path(__file__).parent / \"oauth_providers.yaml\"\n\n # Fallback to embedded minimal config if YAML file doesn't exist\n if not yaml_path.exists():\n logger.warning(f\"OAuth providers YAML file not found at {yaml_path}\")\n logger.warning(\"Using minimal embedded configuration\")\n return {\n \"atlassian\": {\n \"display_name\": \"Atlassian Cloud\",\n \"auth_url\": \"https://auth.atlassian.com/authorize\",\n \"token_url\": \"https://auth.atlassian.com/oauth/token\",\n \"user_info_url\": \"https://api.atlassian.com/oauth/token/accessible-resources\",\n \"scopes\": [\"read:jira-work\", \"write:jira-work\", \"offline_access\"],\n \"response_type\": \"code\",\n \"grant_type\": \"authorization_code\",\n \"audience\": \"api.atlassian.com\",\n \"requires_pkce\": False,\n \"additional_params\": {\"prompt\": \"consent\"},\n }\n }\n\n try:\n with open(yaml_path) as f:\n config = yaml.safe_load(f)\n providers = config.get(\"providers\", {})\n logger.debug(f\"Loaded {len(providers)} OAuth providers from {yaml_path}\")\n return providers\n except Exception as e:\n logger.error(f\"Failed to load OAuth providers from YAML: {e}\")\n return {}\n\n\n# Load OAuth provider configurations\nOAUTH_PROVIDERS = _load_oauth_providers()\n\n# Global variables for callback handling\nauthorization_code = None\nreceived_state = None\ncallback_received = False\ncallback_error = None\npkce_verifier = None\noauth_config_global = None\n\n\n@dataclass\nclass OAuthConfig:\n \"\"\"OAuth 2.0 configuration for any provider.\"\"\"\n\n provider: str\n client_id: str\n client_secret: str\n redirect_uri: str\n scopes: list[str]\n provider_config: dict[str, Any]\n cloud_id: str | None = None\n refresh_token: str | None = None\n access_token: str | None = None\n expires_at: float | None = None\n additional_params: dict[str, str] | None = None\n\n @property\n def is_token_expired(self) -> bool:\n \"\"\"Check if the access token is expired or will expire soon.\"\"\"\n if not self.access_token or not self.expires_at:\n return True\n return time.time() + TOKEN_EXPIRY_MARGIN >= self.expires_at\n\n def get_authorization_url(self, state: str, pkce_challenge: str | None = None) -> str:\n \"\"\"Get the authorization URL for the OAuth 2.0 flow.\"\"\"\n params = {\n \"client_id\": self.client_id,\n \"scope\": \" \".join(self.scopes),\n \"redirect_uri\": self.redirect_uri,\n \"response_type\": self.provider_config[\"response_type\"],\n \"state\": state,\n }\n\n # Add provider-specific parameters\n if \"audience\" in self.provider_config:\n params[\"audience\"] = self.provider_config[\"audience\"]\n\n # Add PKCE challenge if required\n if pkce_challenge and self.provider_config.get(\"requires_pkce\", False):\n params[\"code_challenge\"] = pkce_challenge\n params[\"code_challenge_method\"] = \"S256\"\n\n # Add any additional parameters\n if self.additional_params:\n params.update(self.additional_params)\n if \"additional_params\" in self.provider_config:\n params.update(self.provider_config[\"additional_params\"])\n\n return f\"{self.provider_config['auth_url']}?{urllib.parse.urlencode(params)}\"\n\n def exchange_code_for_tokens(self, code: str, pkce_verifier: str | None = None) -> bool:\n \"\"\"Exchange the authorization code for access and refresh tokens.\"\"\"\n try:\n payload = {\n \"grant_type\": self.provider_config[\"grant_type\"],\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n \"code\": code,\n \"redirect_uri\": self.redirect_uri,\n }\n\n # Add PKCE verifier if required\n if pkce_verifier and self.provider_config.get(\"requires_pkce\", False):\n payload[\"code_verifier\"] = pkce_verifier\n\n headers = {\"Accept\": \"application/json\"}\n\n # Apply provider-specific headers if configured\n if \"token_headers\" in self.provider_config:\n headers.update(self.provider_config[\"token_headers\"])\n\n logger.info(\n f\"Exchanging authorization code for tokens at {self.provider_config['token_url']}\"\n )\n\n response = requests.post(\n self.provider_config[\"token_url\"], data=payload, headers=headers, timeout=30\n )\n\n logger.debug(f\"Token exchange response status: {response.status_code}\")\n\n if not response.ok:\n logger.error(\n f\"Token exchange failed with status {response.status_code}. Response: {response.text}\"\n )\n return False\n\n token_data = response.json()\n\n if \"access_token\" not in token_data:\n logger.error(\n f\"Access token not found in response. Keys found: {list(token_data.keys())}\"\n )\n return False\n\n self.access_token = token_data[\"access_token\"]\n\n # Handle refresh token (not all providers support it)\n if \"refresh_token\" in token_data:\n self.refresh_token = token_data[\"refresh_token\"]\n elif \"offline_access\" in self.scopes:\n logger.warning(\n \"Refresh token not found despite 'offline_access' scope being included.\"\n )\n\n # Set token expiry\n if \"expires_in\" in token_data:\n self.expires_at = time.time() + token_data[\"expires_in\"]\n\n # Get provider-specific info (like cloud ID for Atlassian)\n self._get_provider_info()\n\n # Save the tokens\n self._save_tokens()\n\n logger.info(\"🎉 OAuth authorization flow completed successfully!\")\n if self.expires_at:\n expires_in = int(self.expires_at - time.time())\n logger.info(f\"Access token expires in {expires_in} seconds\")\n\n if self.cloud_id:\n logger.info(f\"Retrieved Cloud ID: {self.cloud_id}\")\n\n return True\n\n except requests.exceptions.RequestException as e:\n logger.error(f\"Network error during token exchange: {e}\")\n return False\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to decode JSON response: {e}\")\n return False\n except Exception as e:\n logger.error(f\"Failed to exchange code for tokens: {e}\")\n return False\n\n def refresh_access_token(self) -> bool:\n \"\"\"Refresh the access token using the refresh token.\"\"\"\n if not self.refresh_token:\n logger.error(\"No refresh token available\")\n return False\n\n try:\n payload = {\n \"grant_type\": \"refresh_token\",\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n \"refresh_token\": self.refresh_token,\n }\n\n logger.debug(\"Refreshing access token...\")\n response = requests.post(self.provider_config[\"token_url\"], data=payload, timeout=30)\n response.raise_for_status()\n\n token_data = response.json()\n self.access_token = token_data[\"access_token\"]\n\n # Refresh token might be rotated\n if \"refresh_token\" in token_data:\n self.refresh_token = token_data[\"refresh_token\"]\n\n if \"expires_in\" in token_data:\n self.expires_at = time.time() + token_data[\"expires_in\"]\n\n self._save_tokens()\n logger.info(\"Successfully refreshed access token\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to refresh access token: {e}\")\n return False\n\n def ensure_valid_token(self) -> bool:\n \"\"\"Ensure the access token is valid, refreshing if necessary.\"\"\"\n if not self.is_token_expired:\n return True\n return self.refresh_access_token()\n\n def _get_provider_info(self) -> None:\n \"\"\"Get provider-specific information (e.g., cloud ID for Atlassian).\"\"\"\n # Check if provider requires cloud ID from user info\n if (\n self.provider_config.get(\"requires_cloud_id\")\n and self.provider_config.get(\"cloud_id_from_user_info\")\n and self.access_token\n ):\n try:\n headers = {\"Authorization\": f\"Bearer {self.access_token}\"}\n response = requests.get(\n self.provider_config[\"user_info_url\"], headers=headers, timeout=30\n )\n response.raise_for_status()\n\n resources = response.json()\n if resources and len(resources) > 0:\n # Generic handling - assumes first resource has an 'id' field\n self.cloud_id = resources[0].get(\"id\")\n if self.cloud_id:\n logger.debug(f\"Found cloud ID for {self.provider}: {self.cloud_id}\")\n else:\n logger.warning(f\"No resources found for {self.provider}\")\n except Exception as e:\n logger.error(f\"Failed to get cloud ID for {self.provider}: {e}\")\n\n # Removed keyring username method - using file-based storage only\n\n def _save_tokens(self) -> None:\n \"\"\"Save the tokens securely using file-based storage.\"\"\"\n try:\n token_data = {\n \"provider\": self.provider,\n \"refresh_token\": self.refresh_token,\n \"access_token\": self.access_token,\n \"expires_at\": self.expires_at,\n \"cloud_id\": self.cloud_id,\n \"scopes\": self.scopes,\n }\n\n # Save to file\n self._save_tokens_to_file(token_data)\n\n except Exception as e:\n logger.error(f\"Failed to save tokens: {e}\")\n\n def _save_tokens_to_file(self, token_data: dict) -> None:\n \"\"\"Save tokens to a file as fallback storage.\"\"\"\n try:\n # Create provider-specific directory structure (with backwards compatibility)\n primary_token_dir = Path.cwd() / \".oauth-tokens\"\n primary_token_dir.mkdir(exist_ok=True, mode=0o700)\n\n # Primary token file with provider in name\n token_path = primary_token_dir / f\"oauth-{self.provider}-{self.client_id}.json\"\n\n # Save essential token data\n essential_token_data = {\n \"provider\": self.provider,\n \"refresh_token\": self.refresh_token,\n \"access_token\": self.access_token,\n \"expires_at\": self.expires_at,\n \"cloud_id\": self.cloud_id,\n }\n\n with open(token_path, \"w\") as f:\n json.dump(essential_token_data, f, indent=2)\n\n # Secure the file\n token_path.chmod(0o600)\n logger.info(f\"📁 Saved OAuth tokens to: {token_path}\")\n\n # Save a readable version with usage examples\n readable_token_path = (\n primary_token_dir / f\"oauth-{self.provider}-{self.client_id}-readable.json\"\n )\n readable_data = {\n \"provider\": self.provider,\n \"provider_display_name\": self.provider_config.get(\"display_name\", self.provider),\n \"client_id\": self.client_id,\n \"cloud_id\": self.cloud_id,\n \"scopes\": self.scopes,\n \"access_token\": self.access_token,\n \"refresh_token\": self.refresh_token,\n \"expires_at\": self.expires_at,\n \"expires_at_human\": time.strftime(\n \"%Y-%m-%d %H:%M:%S UTC\", time.gmtime(self.expires_at)\n )\n if self.expires_at\n else None,\n \"saved_at\": time.strftime(\"%Y-%m-%d %H:%M:%S UTC\", time.gmtime()),\n \"usage_examples\": {\n \"curl_with_bearer\": f\"curl -H 'Authorization: Bearer {self.access_token}' {self.provider_config.get('user_info_url', '')}\",\n \"python_requests\": f\"headers = {{'Authorization': 'Bearer {self.access_token}'}}; requests.get('', headers=headers)\",\n \"token_file_location\": f\"The token is saved at: {token_path}\",\n \"vscode_mcp_config\": f\"VS Code MCP config saved at: {primary_token_dir}/vscode_mcp.json\",\n \"roocode_mcp_config\": f\"Roocode MCP config saved at: {primary_token_dir}/mcp.json\",\n },\n }\n\n with open(readable_token_path, \"w\") as f:\n json.dump(readable_data, f, indent=2)\n\n readable_token_path.chmod(0o600)\n logger.info(f\"📄 Saved readable token info to: {readable_token_path}\")\n\n # Create VS Code MCP configuration file for supported providers\n self._create_vscode_mcp_config(primary_token_dir)\n\n # Create Roocode MCP configuration file for supported providers\n self._create_roocode_mcp_config(primary_token_dir)\n\n except Exception as e:\n logger.error(f\"Failed to save tokens to file: {e}\")\n\n def _create_vscode_mcp_config(self, token_dir: Path) -> None:\n \"\"\"Create VS Code MCP configuration file for supported providers.\"\"\"\n try:\n # Only create MCP config for providers that have MCP gateway support\n if self.provider not in [\"atlassian\"]:\n logger.debug(f\"Skipping VS Code MCP config - {self.provider} not supported\")\n return\n\n vscode_config_path = token_dir / \"vscode_mcp.json\"\n\n # Load environment variables for MCP Gateway configuration\n registry_url = os.getenv(\"REGISTRY_URL\", \"https://mcpgateway.ddns.net\")\n aws_region = os.getenv(\"AWS_REGION\", \"us-east-1\")\n user_pool_id = os.getenv(\"INGRESS_OAUTH_USER_POOL_ID\")\n\n # Get the appropriate client ID - use the MCP Gateway client ID from env\n mcp_client_id = os.getenv(\"INGRESS_OAUTH_CLIENT_ID\")\n\n # Get MCP Gateway auth token\n mcp_auth_token = os.getenv(\"MCP_SERVER1_AUTH_TOKEN\", \"\")\n if mcp_auth_token.startswith('\"') and mcp_auth_token.endswith('\"'):\n mcp_auth_token = mcp_auth_token[1:-1] # Remove quotes\n\n # Create the VS Code MCP configuration\n mcp_config = {\"mcp\": {\"servers\": {}}}\n\n if self.provider == \"atlassian\":\n mcp_config[\"mcp\"][\"servers\"][\"atlassian\"] = {\n \"url\": f\"{registry_url}/atlassian/mcp\",\n \"headers\": {\n # MCP Gateway authentication headers\n \"X-Authorization\": f\"Bearer {mcp_auth_token}\",\n \"X-User-Pool-Id\": user_pool_id,\n \"X-Client-Id\": mcp_client_id,\n \"X-Region\": aws_region,\n # Atlassian-specific headers\n \"Authorization\": f\"Bearer {self.access_token}\",\n \"X-Atlassian-Cloud-Id\": self.cloud_id or \"\",\n },\n }\n\n # Save the VS Code MCP configuration\n with open(vscode_config_path, \"w\") as f:\n json.dump(mcp_config, f, indent=4)\n\n vscode_config_path.chmod(0o600)\n logger.info(f\"🔧 Created VS Code MCP configuration: {vscode_config_path}\")\n\n except Exception as e:\n logger.error(f\"Failed to create VS Code MCP configuration: {e}\")\n\n def _create_roocode_mcp_config(self, token_dir: Path) -> None:\n \"\"\"Create Roocode MCP configuration file for supported providers.\"\"\"\n try:\n # Only create MCP config for providers that have MCP gateway support\n if self.provider not in [\"atlassian\"]:\n logger.debug(f\"Skipping Roocode MCP config - {self.provider} not supported\")\n return\n\n roocode_config_path = token_dir / \"mcp.json\"\n\n # Load environment variables for MCP Gateway configuration\n registry_url = os.getenv(\"REGISTRY_URL\", \"https://mcpgateway.ddns.net\")\n aws_region = os.getenv(\"AWS_REGION\", \"us-east-1\")\n user_pool_id = os.getenv(\"INGRESS_OAUTH_USER_POOL_ID\")\n\n # Get the appropriate client ID - use the MCP Gateway client ID from env\n mcp_client_id = os.getenv(\"INGRESS_OAUTH_CLIENT_ID\")\n\n # Get MCP Gateway auth token\n mcp_auth_token = os.getenv(\"MCP_SERVER1_AUTH_TOKEN\", \"\")\n if mcp_auth_token.startswith('\"') and mcp_auth_token.endswith('\"'):\n mcp_auth_token = mcp_auth_token[1:-1] # Remove quotes\n\n # Create the Roocode MCP configuration\n mcp_config = {\"mcpServers\": {}}\n\n if self.provider == \"atlassian\":\n mcp_config[\"mcpServers\"][\"atlassian\"] = {\n \"type\": \"streamable-http\",\n \"url\": f\"{registry_url}/atlassian/mcp\",\n \"headers\": {\n # MCP Gateway authentication headers\n \"X-Authorization\": f\"Bearer {mcp_auth_token}\",\n \"X-User-Pool-Id\": user_pool_id,\n \"X-Client-Id\": mcp_client_id,\n \"X-Region\": aws_region,\n # Atlassian-specific headers\n \"Authorization\": f\"Bearer {self.access_token}\",\n \"X-Atlassian-Cloud-Id\": self.cloud_id or \"\",\n },\n \"disabled\": False,\n \"alwaysAllow\": [],\n }\n\n # Save the Roocode MCP configuration\n with open(roocode_config_path, \"w\") as f:\n json.dump(mcp_config, f, indent=2)\n\n roocode_config_path.chmod(0o600)\n logger.info(f\"🔧 Created Roocode MCP configuration: {roocode_config_path}\")\n\n except Exception as e:\n logger.error(f\"Failed to create Roocode MCP configuration: {e}\")\n\n @staticmethod\n def load_tokens(provider: str, client_id: str) -> dict[str, Any]:\n \"\"\"Load tokens from file storage.\"\"\"\n # Try primary token file format first\n primary_tokens = OAuthConfig._load_tokens_from_file(provider, client_id)\n if primary_tokens:\n return primary_tokens\n\n return {}\n\n @staticmethod\n def _load_tokens_from_file(provider: str, client_id: str) -> dict[str, Any]:\n \"\"\"Load tokens from primary file format.\"\"\"\n token_path = Path.cwd() / \".oauth-tokens\" / f\"oauth-{provider}-{client_id}.json\"\n\n if not token_path.exists():\n return {}\n\n try:\n with open(token_path) as f:\n token_data = json.load(f)\n logger.debug(f\"Loaded OAuth tokens from file {token_path}\")\n return token_data\n except Exception as e:\n logger.error(f\"Failed to load tokens from file: {e}\")\n return {}\n\n\ndef generate_pkce_pair() -> tuple[str, str]:\n \"\"\"Generate PKCE code verifier and challenge.\"\"\"\n # Generate code verifier (43-128 characters)\n code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode(\"utf-8\").rstrip(\"=\")\n\n # Generate code challenge\n code_challenge = (\n base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode(\"utf-8\")).digest())\n .decode(\"utf-8\")\n .rstrip(\"=\")\n )\n\n return code_verifier, code_challenge\n\n\nclass CallbackHandler(http.server.BaseHTTPRequestHandler):\n \"\"\"HTTP request handler for OAuth callback.\"\"\"\n\n def do_GET(self) -> None:\n \"\"\"Handle GET requests (OAuth callback).\"\"\"\n global \\\n authorization_code, \\\n callback_received, \\\n callback_error, \\\n received_state, \\\n oauth_config_global\n\n parsed_path = urllib.parse.urlparse(self.path)\n logger.debug(f\"CallbackHandler received GET request for: {self.path}\")\n\n # Ignore favicon requests politely\n if parsed_path.path == \"/favicon.ico\":\n self.send_error(404, \"File not found\")\n logger.debug(\"CallbackHandler: Ignored /favicon.ico request.\")\n return\n\n # Process only /callback path\n if parsed_path.path != \"/callback\":\n self.send_error(404, \"Not Found: Only /callback is supported.\")\n logger.warning(\n f\"CallbackHandler: Received request for unexpected path: {parsed_path.path}\"\n )\n return\n\n # Parse the query parameters from the URL\n query = parsed_path.query\n params = urllib.parse.parse_qs(query)\n\n if \"error\" in params:\n callback_error = params[\"error\"][0]\n callback_received = True\n logger.error(f\"Authorization error from callback: {callback_error}\")\n self._send_response(f\"Authorization failed: {callback_error}\", status=400)\n return\n\n if \"code\" in params:\n authorization_code = params[\"code\"][0]\n if \"state\" in params:\n received_state = params[\"state\"][0]\n callback_received = True\n logger.info(\"Authorization code and state received successfully via callback.\")\n\n # Try immediate token exchange if config is available\n message = \"Authorization successful! You can close this window now.\"\n if oauth_config_global:\n try:\n logger.info(\"Attempting immediate token exchange...\")\n success = oauth_config_global.exchange_code_for_tokens(\n authorization_code, pkce_verifier\n )\n\n if success:\n message = \"Authorization successful! Tokens have been saved securely. You can close this window now.\"\n logger.info(\"🎉 Token exchange completed successfully during callback!\")\n else:\n message = \"Authorization received but token exchange failed. Check the logs for details.\"\n logger.error(\"Token exchange failed during callback\")\n except Exception as e:\n logger.error(f\"Error during immediate token exchange: {e}\")\n message = \"Authorization received but token exchange encountered an error. Check the logs for details.\"\n\n self._send_response(message)\n else:\n logger.error(\"Invalid callback: 'code' or 'error' parameter missing.\")\n self._send_response(\"Invalid callback: Authorization code missing\", status=400)\n\n def _send_response(self, message: str, status: int = 200) -> None:\n \"\"\"Send response to the browser.\"\"\"\n html = f\"\"\"\n\n\n OAuth Authorization\n \n\n\n
\n
\n {\"✅\" if status == 200 else \"❌\"}\n
\n

{\"OAuth Authorization Complete!\" if status == 200 else \"OAuth Authorization Failed\"}

\n
{message}
\n
This window will close in 5 seconds...
\n
\n \n\n\"\"\"\n\n # Encode the HTML content\n content = html.encode(\"utf-8\")\n content_length = len(content)\n\n # Send HTTP response with proper headers\n self.send_response(status)\n self.send_header(\"Content-Type\", \"text/html; charset=utf-8\")\n self.send_header(\"Content-Length\", str(content_length))\n self.send_header(\"Connection\", \"close\")\n self.send_header(\"Cache-Control\", \"no-cache, no-store, must-revalidate\")\n self.send_header(\"Pragma\", \"no-cache\")\n self.send_header(\"Expires\", \"0\")\n self.end_headers()\n\n # Write content and ensure it's flushed\n self.wfile.write(content)\n self.wfile.flush()\n\n def log_message(self, format: str, *args) -> None:\n \"\"\"Override to suppress default HTTP server logging.\"\"\"\n return\n\n\ndef start_callback_server(port: int) -> socketserver.TCPServer:\n \"\"\"Start a local server to receive the OAuth callback.\"\"\"\n handler = CallbackHandler\n httpd = socketserver.TCPServer((\"localhost\", port), handler)\n server_thread = threading.Thread(target=httpd.serve_forever)\n server_thread.daemon = True\n server_thread.start()\n logger.info(f\"Started callback server on port {port}\")\n return httpd\n\n\ndef wait_for_callback(timeout: int = 300) -> bool:\n \"\"\"Wait for the callback to be received.\"\"\"\n global callback_received, callback_error, authorization_code\n\n start_time = time.time()\n while not callback_received and (time.time() - start_time) < timeout:\n time.sleep(1)\n\n if not callback_received:\n logger.error(f\"Timed out waiting for authorization callback after {timeout} seconds\")\n logger.info(\"You can still visit the authorization URL and complete the flow manually\")\n return False\n\n if callback_error:\n logger.error(f\"Authorization error: {callback_error}\")\n return False\n\n if not authorization_code:\n logger.error(\"No authorization code received\")\n return False\n\n logger.info(f\"Received authorization code: {authorization_code[:20]}...\")\n return True\n\n\ndef parse_redirect_uri(redirect_uri: str) -> tuple[str, int]:\n \"\"\"Parse the redirect URI to extract host and port.\"\"\"\n parsed = urllib.parse.urlparse(redirect_uri)\n port = parsed.port or (443 if parsed.scheme == \"https\" else 80)\n return parsed.hostname, port\n\n\ndef load_config_file(config_path: str) -> dict[str, Any]:\n \"\"\"Load OAuth configuration from a JSON file.\"\"\"\n try:\n with open(config_path) as f:\n return json.load(f)\n except Exception as e:\n logger.error(f\"Failed to load config file {config_path}: {e}\")\n return {}\n\n\ndef interactive_provider_selection() -> str:\n \"\"\"Interactive provider selection menu.\"\"\"\n print(\"\\n🔐 OAuth 2.0 Provider Selection\")\n print(\"=\" * 40)\n\n providers = list(OAUTH_PROVIDERS.keys())\n for i, provider in enumerate(providers, 1):\n display_name = OAUTH_PROVIDERS[provider][\"display_name\"]\n is_m2m = OAUTH_PROVIDERS[provider].get(\"is_m2m\", False)\n m2m_label = \" [M2M/No Browser]\" if is_m2m else \"\"\n print(f\"{i}. {display_name} ({provider}){m2m_label}\")\n\n while True:\n try:\n choice = input(f\"\\nSelect a provider (1-{len(providers)}): \").strip()\n if not choice:\n continue\n\n index = int(choice) - 1\n if 0 <= index < len(providers):\n selected_provider = providers[index]\n print(f\"✅ Selected: {OAUTH_PROVIDERS[selected_provider]['display_name']}\")\n return selected_provider\n else:\n print(f\"❌ Please enter a number between 1 and {len(providers)}\")\n except ValueError:\n print(\"❌ Please enter a valid number\")\n except KeyboardInterrupt:\n print(\"\\n\\n👋 Goodbye!\")\n sys.exit(0)\n\n\ndef interactive_input(prompt: str, required: bool = True, is_secret: bool = False) -> str:\n \"\"\"Get interactive input with validation.\"\"\"\n import getpass\n\n while True:\n try:\n if is_secret:\n value = getpass.getpass(f\"{prompt}: \").strip()\n else:\n value = input(f\"{prompt}: \").strip()\n\n if value or not required:\n return value\n\n if required:\n print(\"❌ This field is required. Please enter a value.\")\n except KeyboardInterrupt:\n print(\"\\n\\n👋 Goodbye!\")\n sys.exit(0)\n\n\ndef interactive_scopes_input(provider_config: dict[str, Any]) -> list[str]:\n \"\"\"Interactive scopes selection.\"\"\"\n default_scopes = provider_config.get(\"scopes\", [])\n\n print(\"\\nOAuth Scopes\")\n logger.info(f\"Default scopes: {', '.join(default_scopes)}\")\n\n custom_input = input(\n \"Enter custom scopes (comma or space-separated) or press Enter for defaults: \"\n ).strip()\n\n if custom_input:\n # Handle both comma-separated and space-separated scopes\n if \",\" in custom_input:\n custom_scopes = [scope.strip() for scope in custom_input.split(\",\")]\n else:\n custom_scopes = [scope.strip() for scope in custom_input.split()]\n return custom_scopes\n\n return default_scopes\n\n\ndef interactive_configuration() -> dict[str, Any]:\n \"\"\"Interactive configuration setup.\"\"\"\n print(\"\\n🚀 Generic OAuth 2.0 Flow - Interactive Setup\")\n print(\"=\" * 50)\n print(\"This will help you set up OAuth 2.0 authentication with various providers.\")\n print(\"You can press Ctrl+C at any time to exit.\\n\")\n\n # Provider selection\n provider = interactive_provider_selection()\n provider_config = OAUTH_PROVIDERS[provider]\n\n print(f\"\\n📝 Setting up {provider_config['display_name']} OAuth\")\n print(\"=\" * 40)\n\n # Client credentials\n print(\"\\n🔑 Client Credentials\")\n print(\"These can be obtained from your OAuth provider's developer console.\")\n\n # Map of known provider console URLs\n provider_consoles = {\n \"atlassian\": \"https://developer.atlassian.com/console/myapps/\",\n \"google\": \"https://console.developers.google.com/\",\n \"github\": \"https://github.com/settings/developers\",\n \"cognito\": \"https://console.aws.amazon.com/cognito/\",\n \"microsoft\": \"https://portal.azure.com/\",\n \"slack\": \"https://api.slack.com/apps\",\n \"discord\": \"https://discord.com/developers/applications\",\n \"linkedin\": \"https://www.linkedin.com/developers/apps\",\n \"spotify\": \"https://developer.spotify.com/dashboard/\",\n \"twitter\": \"https://developer.twitter.com/en/portal/dashboard\",\n }\n\n if provider in provider_consoles:\n print(f\" • {provider_config['display_name']}: {provider_consoles[provider]}\")\n\n client_id = interactive_input(\"\\nClient ID\", required=True)\n client_secret = interactive_input(\"Client Secret\", required=True, is_secret=True)\n\n # Redirect URI (skip for M2M providers)\n if not provider_config.get(\"is_m2m\", False):\n print(\"\\n🔄 Redirect URI\")\n\n # Try to get public IP for better remote access\n try:\n import subprocess # nosec B404\n\n public_ip = (\n subprocess.check_output([\"curl\", \"-s\", \"http://checkip.amazonaws.com/\"])\n .decode()\n .strip()\n )\n suggested_redirect = f\"http://{public_ip}:{DEFAULT_REDIRECT_PORT}/callback\"\n print(f\"Suggested (for remote access): {suggested_redirect}\")\n except:\n suggested_redirect = f\"http://localhost:{DEFAULT_REDIRECT_PORT}/callback\"\n print(f\"Default (localhost): {suggested_redirect}\")\n\n custom_redirect = input(\"Enter custom redirect URI or press Enter for suggested: \").strip()\n redirect_uri = custom_redirect if custom_redirect else suggested_redirect\n else:\n # M2M flow doesn't need redirect URI\n redirect_uri = \"urn:ietf:wg:oauth:2.0:oob\" # Standard placeholder for M2M\n\n # Scopes\n scopes = interactive_scopes_input(provider_config)\n\n # Provider-specific configuration for templates\n additional_config = {}\n\n # Check if provider requires template variables\n if \"requires_template_vars\" in provider_config:\n print(f\"\\n⚙️ Additional Configuration for {provider_config['display_name']}\")\n\n for var_name in provider_config[\"requires_template_vars\"]:\n # Get default value if available\n default_value = provider_config.get(\"template_var_defaults\", {}).get(var_name)\n\n # Format the prompt\n prompt = var_name.replace(\"_\", \" \").title()\n if default_value:\n prompt = f\"{prompt} (default: {default_value})\"\n\n # Get input or use default\n value = interactive_input(prompt, required=False)\n if not value and default_value:\n value = default_value\n elif not value:\n value = interactive_input(f\"{prompt} (required)\", required=True)\n\n additional_config[var_name] = value\n\n # Summary (redacted for security)\n from ..utils import redact_sensitive_value\n\n print(\"\\n📋 Configuration Summary\")\n print(\"=\" * 30)\n print(f\"Provider: {provider_config['display_name']}\")\n print(f\"Client ID: {redact_sensitive_value(client_id, 8)}\")\n print(f\"Client Secret: {redact_sensitive_value(client_secret, 8)}\")\n print(f\"Redirect URI: {redirect_uri}\")\n print(f\"Scopes: {', '.join(scopes)}\")\n\n if additional_config:\n for key, value in additional_config.items():\n # Redact sensitive values in additional config\n display_value = value\n if any(\n sensitive in key.lower() for sensitive in [\"secret\", \"password\", \"token\", \"key\"]\n ):\n display_value = redact_sensitive_value(str(value), 8)\n print(f\"{key.replace('_', ' ').title()}: {display_value}\")\n\n # Confirmation\n confirm = input(\"\\n✅ Proceed with OAuth flow? (y/N): \").strip().lower()\n if confirm != \"y\":\n print(\"❌ Cancelled by user\")\n sys.exit(0)\n\n return {\n \"provider\": provider,\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"redirect_uri\": redirect_uri,\n \"scopes\": scopes,\n **additional_config,\n }\n\n\ndef run_m2m_flow(config: OAuthConfig) -> bool:\n \"\"\"Run the M2M (client credentials) OAuth 2.0 flow.\n\n Args:\n config: OAuth configuration\n\n Returns:\n bool: True if successful, False otherwise\n \"\"\"\n try:\n # Prepare the token request\n payload = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": config.client_id,\n \"client_secret\": config.client_secret,\n }\n\n # Add scopes if specified (only if non-empty)\n if config.scopes and len(config.scopes) > 0:\n payload[\"scope\"] = \" \".join(config.scopes)\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n logger.info(f\"Requesting M2M token from {config.provider_config['token_url']}\")\n logger.debug(\n f\"Using client_id: {config.client_id[:10]}...\" if config.client_id else \"No client_id\"\n )\n logger.debug(f\"Scopes: {config.scopes}\")\n\n response = requests.post(\n config.provider_config[\"token_url\"], data=payload, headers=headers, timeout=30\n )\n\n if not response.ok:\n logger.error(\n f\"M2M token request failed with status {response.status_code}. Response: {response.text}\"\n )\n return False\n\n token_data = response.json()\n\n if \"access_token\" not in token_data:\n logger.error(\n f\"Access token not found in M2M response. Keys found: {list(token_data.keys())}\"\n )\n return False\n\n config.access_token = token_data[\"access_token\"]\n\n # M2M tokens typically don't have refresh tokens\n if \"refresh_token\" in token_data:\n config.refresh_token = token_data[\"refresh_token\"]\n\n # Set token expiry\n if \"expires_in\" in token_data:\n config.expires_at = time.time() + token_data[\"expires_in\"]\n\n # Save the tokens\n config._save_tokens()\n\n logger.info(\n f\"🎉 M2M token obtained successfully for {config.provider_config['display_name']}!\"\n )\n\n if config.expires_at:\n expires_in = int(config.expires_at - time.time())\n logger.info(f\"Token expires in: {expires_in} seconds\")\n\n return True\n\n except requests.exceptions.RequestException as e:\n logger.error(f\"Network error during M2M token request: {e}\")\n return False\n except Exception as e:\n logger.error(f\"Failed to obtain M2M token: {e}\")\n return False\n\n\ndef run_oauth_flow(config: OAuthConfig, force_new: bool = False) -> bool:\n \"\"\"Run the OAuth 2.0 authorization flow.\n\n Args:\n config: OAuth configuration\n force_new: If True, delete existing tokens and force new authorization\n \"\"\"\n # Check if this is an M2M provider\n if config.provider_config.get(\"is_m2m\", False):\n logger.info(\"Provider configured for M2M/Client Credentials flow\")\n return run_m2m_flow(config)\n\n global \\\n pkce_verifier, \\\n authorization_code, \\\n received_state, \\\n callback_received, \\\n callback_error, \\\n oauth_config_global\n\n # Reset global variables\n authorization_code = None\n received_state = None\n callback_received = False\n callback_error = None\n oauth_config_global = config # Make config available to callback handler\n\n # Handle force delete of existing tokens\n if force_new:\n logger.info(\"🗑️ Force delete requested - removing existing tokens\")\n _delete_existing_tokens(config.provider, config.client_id)\n\n # Check for existing valid tokens (skip if force_new)\n if not force_new:\n token_data = OAuthConfig.load_tokens(config.provider, config.client_id)\n if token_data:\n config.refresh_token = token_data.get(\"refresh_token\")\n config.access_token = token_data.get(\"access_token\")\n config.expires_at = token_data.get(\"expires_at\")\n config.cloud_id = token_data.get(\"cloud_id\")\n\n if config.access_token and not config.is_token_expired:\n logger.info(\"Found valid existing access token\")\n return True\n elif config.refresh_token:\n logger.info(\"Found refresh token, attempting to refresh access token\")\n if config.refresh_access_token():\n return True\n\n # Generate state for CSRF protection\n state = secrets.token_urlsafe(16)\n\n # Generate PKCE pair if required\n pkce_challenge = None\n if config.provider_config.get(\"requires_pkce\", False):\n pkce_verifier, pkce_challenge = generate_pkce_pair()\n logger.debug(\"Generated PKCE challenge for enhanced security\")\n\n # Start local callback server if using localhost\n hostname, port = parse_redirect_uri(config.redirect_uri)\n httpd = None\n\n if hostname and hostname.lower() in [\"localhost\", \"127.0.0.1\"]:\n try:\n httpd = start_callback_server(port)\n except OSError as e:\n logger.error(f\"Failed to start callback server: {e}\")\n logger.error(f\"Make sure port {port} is available\")\n return False\n\n # Get the authorization URL\n auth_url = config.get_authorization_url(state, pkce_challenge)\n\n # Open the browser for authorization\n logger.info(f\"Opening browser for {config.provider_config['display_name']} authorization\")\n logger.info(\"If the browser doesn't open automatically, visit this URL:\")\n logger.info(auth_url)\n\n webbrowser.open(auth_url)\n\n # Wait for the callback\n logger.info(\"Waiting for authorization callback...\")\n callback_success = wait_for_callback()\n\n # Clean up global config reference\n oauth_config_global = None\n\n if not callback_success:\n if httpd:\n httpd.shutdown()\n return False\n\n # Verify state to prevent CSRF attacks\n if received_state != state:\n logger.warning(f\"State mismatch! Expected: {state}, Received: {received_state}\")\n logger.warning(\"This might be from a previous authorization attempt. Continuing anyway...\")\n # Don't fail on state mismatch in case of VS Code port forwarding or browser refresh\n else:\n logger.info(\"CSRF state verified successfully\")\n\n # Check if token exchange already happened in the callback\n if config.access_token:\n logger.info(\"Token exchange was already completed during callback\")\n success = True\n else:\n # Exchange the code for tokens if not done already\n logger.info(\"Exchanging authorization code for tokens...\")\n success = config.exchange_code_for_tokens(authorization_code, pkce_verifier)\n\n if httpd:\n httpd.shutdown()\n\n if success:\n logger.info(\n f\"🎉 {config.provider_config['display_name']} OAuth authorization completed successfully!\"\n )\n\n # Display useful information\n logger.info(\"\\n📋 Configuration Summary:\")\n logger.info(f\"Provider: {config.provider_config['display_name']}\")\n logger.info(f\"Client ID: {config.client_id}\")\n logger.info(f\"Scopes: {', '.join(config.scopes)}\")\n\n if config.cloud_id:\n logger.info(f\"Cloud ID: {config.cloud_id}\")\n\n if config.expires_at:\n expires_in = int(config.expires_at - time.time())\n logger.info(f\"Token expires in: {expires_in} seconds\")\n\n logger.info(\"\\n💡 Tokens have been saved securely and can be used by other applications\")\n\n return success\n\n\ndef _delete_existing_tokens(provider: str, client_id: str) -> None:\n \"\"\"Delete existing tokens from all storage locations.\"\"\"\n deleted_files = []\n\n # Keyring deletion removed - using file-based storage only\n\n # Delete primary token file\n primary_token_path = Path.cwd() / \".oauth-tokens\" / f\"oauth-{provider}-{client_id}.json\"\n if primary_token_path.exists():\n primary_token_path.unlink()\n deleted_files.append(str(primary_token_path))\n logger.debug(f\"Deleted primary token file: {primary_token_path}\")\n\n # Delete readable token file\n readable_token_path = (\n Path.cwd() / \".oauth-tokens\" / f\"oauth-{provider}-{client_id}-readable.json\"\n )\n if readable_token_path.exists():\n readable_token_path.unlink()\n deleted_files.append(str(readable_token_path))\n logger.debug(f\"Deleted readable token file: {readable_token_path}\")\n\n if deleted_files:\n logger.info(f\"🗑️ Deleted {len(deleted_files)} existing token file(s)\")\n for file_path in deleted_files:\n logger.debug(f\" - {file_path}\")\n else:\n logger.info(\"🗑️ No existing token files found to delete\")\n\n\ndef main() -> int:\n \"\"\"Main entry point.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Generic OAuth 2.0 Authorization Flow\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n python generic_oauth_flow.py --provider atlassian --client-id YOUR_ID --client-secret YOUR_SECRET\n python generic_oauth_flow.py --provider google --client-id YOUR_ID --client-secret YOUR_SECRET\n python generic_oauth_flow.py --provider cognito_m2m --client-id YOUR_ID --client-secret YOUR_SECRET # M2M flow\n python generic_oauth_flow.py --config-file oauth_config.json\n python generic_oauth_flow.py --provider atlassian --force # Force new auth, delete existing tokens\n python generic_oauth_flow.py # Interactive mode\n\nSupported providers: \"\"\"\n + \", \".join(OAUTH_PROVIDERS.keys()),\n )\n\n parser.add_argument(\"--provider\", choices=list(OAUTH_PROVIDERS.keys()), help=\"OAuth provider\")\n parser.add_argument(\"--client-id\", help=\"OAuth Client ID\")\n parser.add_argument(\"--client-secret\", help=\"OAuth Client Secret\")\n parser.add_argument(\n \"--redirect-uri\", help=\"OAuth Redirect URI (default: http://localhost:8080/callback)\"\n )\n parser.add_argument(\"--scope\", nargs=\"*\", help=\"OAuth Scopes (space-separated)\")\n parser.add_argument(\"--config-file\", help=\"JSON configuration file\")\n parser.add_argument(\"--verbose\", \"-v\", action=\"store_true\", help=\"Enable verbose logging\")\n parser.add_argument(\n \"--interactive\",\n \"-i\",\n action=\"store_true\",\n help=\"Force interactive mode even if some args are provided\",\n )\n parser.add_argument(\n \"--force\",\n \"-f\",\n action=\"store_true\",\n help=\"Force new OAuth flow by deleting existing tokens\",\n )\n\n args = parser.parse_args()\n\n if args.verbose:\n logging.getLogger().setLevel(logging.DEBUG)\n logger.setLevel(logging.DEBUG)\n\n # Load configuration from file if provided\n config_data = {}\n if args.config_file:\n config_data = load_config_file(args.config_file)\n\n # Check if we should use interactive mode\n use_interactive = args.interactive or (\n not args.provider and not args.client_id and not args.client_secret and not args.config_file\n )\n\n if use_interactive:\n # Show welcome message for truly interactive mode (no args at all)\n if not any([args.provider, args.client_id, args.client_secret, args.config_file]):\n print(\"🚀 Welcome to the Generic OAuth 2.0 Flow!\")\n print(\"No arguments provided, starting interactive setup...\\n\")\n\n # Interactive configuration\n try:\n interactive_config = interactive_configuration()\n config_data.update(interactive_config)\n except KeyboardInterrupt:\n print(\"\\n\\n👋 Goodbye!\")\n return 0\n\n # Get configuration from args, config file, environment, or interactive input\n provider = args.provider or config_data.get(\"provider\") or os.getenv(\"EGRESS_OAUTH_PROVIDER\")\n\n # For Cognito providers, use INGRESS credentials (for MCP Gateway auth)\n # For other providers, use EGRESS credentials (for external OAuth providers)\n if provider and provider.startswith(\"cognito\"):\n client_id = (\n args.client_id or config_data.get(\"client_id\") or os.getenv(\"INGRESS_OAUTH_CLIENT_ID\")\n )\n client_secret = (\n args.client_secret\n or config_data.get(\"client_secret\")\n or os.getenv(\"INGRESS_OAUTH_CLIENT_SECRET\")\n )\n logger.info(\"Using INGRESS OAuth credentials for Cognito provider\")\n else:\n client_id = (\n args.client_id or config_data.get(\"client_id\") or os.getenv(\"EGRESS_OAUTH_CLIENT_ID\")\n )\n client_secret = (\n args.client_secret\n or config_data.get(\"client_secret\")\n or os.getenv(\"EGRESS_OAUTH_CLIENT_SECRET\")\n )\n logger.info(\"Using EGRESS OAuth credentials for external provider\")\n\n redirect_uri = (\n args.redirect_uri\n or config_data.get(\"redirect_uri\")\n or os.getenv(\"EGRESS_OAUTH_REDIRECT_URI\")\n or f\"http://localhost:{DEFAULT_REDIRECT_PORT}/callback\"\n )\n\n # Handle scopes\n scopes = None\n if args.scope:\n scopes = args.scope\n elif config_data.get(\"scopes\"):\n scopes = config_data[\"scopes\"]\n elif os.getenv(\"EGRESS_OAUTH_SCOPE\"):\n scopes = os.getenv(\"EGRESS_OAUTH_SCOPE\").split()\n\n # Validate required arguments (only if not using interactive mode)\n if not use_interactive:\n missing = []\n if not provider:\n missing.append(\"provider\")\n if not client_id:\n missing.append(\"client-id\")\n if not client_secret:\n missing.append(\"client-secret\")\n\n if missing:\n logger.error(f\"Missing required arguments: {', '.join(missing)}\")\n logger.info(\"💡 Tip: Run without arguments for interactive mode!\")\n parser.print_help()\n return 1\n\n # Only validate environment variables if we're relying on them\n # (i.e., when not using command-line args or config file)\n if (\n not args.provider\n and not args.client_id\n and not args.client_secret\n and not args.config_file\n and not use_interactive\n ):\n _validate_environment_variables()\n\n if provider not in OAUTH_PROVIDERS:\n logger.error(f\"Unsupported provider: {provider}\")\n logger.error(f\"Supported providers: {', '.join(OAUTH_PROVIDERS.keys())}\")\n return 1\n\n # Get provider configuration\n provider_config = OAUTH_PROVIDERS[provider].copy()\n\n # Use provider default scopes if none specified\n if not scopes:\n scopes = provider_config[\"scopes\"]\n\n # Handle provider-specific URL templating\n if \"requires_template_vars\" in provider_config:\n template_vars = {}\n\n for var_name in provider_config[\"requires_template_vars\"]:\n # Try to get value from config_data or environment\n value = config_data.get(var_name) or os.getenv(var_name.upper())\n\n # Special handling for Cognito domain - derive from user pool ID if not provided\n if not value and var_name == \"domain\" and provider in [\"cognito\", \"cognito_m2m\"]:\n # Try to derive domain from INGRESS_OAUTH_USER_POOL_ID\n user_pool_id = os.getenv(\"INGRESS_OAUTH_USER_POOL_ID\")\n if user_pool_id:\n # Use user pool ID without underscores as domain (standard Cognito format)\n value = user_pool_id.replace(\"_\", \"\")\n logger.info(f\"Derived Cognito domain from user pool ID: {value}\")\n\n # Use default if available and no value found\n if not value and \"template_var_defaults\" in provider_config:\n value = provider_config[\"template_var_defaults\"].get(var_name)\n\n if not value:\n if use_interactive:\n logger.error(\n f\"'{var_name}' configuration was not completed properly for provider '{provider}'\"\n )\n else:\n display_name = str(provider_config.get(\"display_name\", provider))\n logger.error(f\"'{var_name}' is required for {display_name}\")\n logger.error(\n f\"Set {var_name.upper()} environment variable or add '{var_name}' to config file\"\n )\n # Provide helpful hint for Cognito domain\n if var_name == \"domain\" and provider in [\"cognito\", \"cognito_m2m\"]:\n logger.error(\n \"Hint: You can also set INGRESS_OAUTH_USER_POOL_ID and the domain will be derived automatically\"\n )\n return 1\n\n template_vars[var_name] = value\n\n # Update URLs with template variables\n for key in [\"auth_url\", \"token_url\", \"user_info_url\"]:\n if \"{\" in provider_config.get(key, \"\"):\n provider_config[key] = provider_config[key].format(**template_vars)\n\n # Create OAuth configuration\n oauth_config = OAuthConfig(\n provider=provider,\n client_id=client_id,\n client_secret=client_secret,\n redirect_uri=redirect_uri,\n scopes=scopes,\n provider_config=provider_config,\n additional_params=config_data.get(\"additional_params\"),\n )\n\n # Ensure scopes is a list for proper processing\n if isinstance(scopes, str):\n scopes = scopes.split()\n\n # Update OAuth configuration with corrected scopes\n oauth_config.scopes = scopes\n\n # Check for critical scopes (generic check for offline_access)\n if \"offline_access\" in provider_config.get(\"scopes\", []) and \"offline_access\" not in scopes:\n display_name = str(provider_config.get(\"display_name\", provider))\n logger.warning(f\"WARNING: 'offline_access' scope is recommended for {display_name}!\")\n logger.warning(\"Without this scope, refresh tokens may not be issued.\")\n\n if use_interactive:\n proceed = input(\"\\nDo you want to proceed anyway? (y/N): \")\n else:\n proceed = input(\"Do you want to proceed anyway? (y/n): \")\n\n if proceed.lower() != \"y\":\n return 1\n\n # Run the OAuth flow\n success = run_oauth_flow(oauth_config, force_new=args.force)\n\n # Output token data as JSON if successful (for integration with other scripts)\n # This stdout output is consumed by egress_oauth.py and other scripts in the pipeline\n if success and oauth_config.access_token:\n token_output = {\n \"provider\": oauth_config.provider,\n \"access_token\": oauth_config.access_token, # nosec - intentional stdout output for script integration\n \"refresh_token\": oauth_config.refresh_token,\n \"expires_at\": oauth_config.expires_at,\n \"cloud_id\": oauth_config.cloud_id,\n \"scopes\": oauth_config.scopes,\n }\n print(json.dumps(token_output)) # noqa: T201 - intentional stdout for script piping\n\n return 0 if success else 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "credentials-provider/oauth/ingress_oauth.py", "content": "#!/usr/bin/env python3\n\"\"\"\nIngress OAuth Authentication Script\n\nThis script handles OAuth authentication for ingress (inbound) connections to the MCP Gateway.\nIt supports Cognito, Keycloak, and Entra ID M2M (Machine-to-Machine) authentication based on AUTH_PROVIDER.\n\nThe script:\n1. Validates required INGRESS OAuth environment variables\n2. Performs M2M authentication using client_credentials grant\n3. Saves tokens to ingress.json in the OAuth tokens directory\n4. Does not generate MCP configuration files (handled by oauth_creds.sh)\n\nEnvironment Variables Required:\nFor AUTH_PROVIDER=cognito (default):\n- INGRESS_OAUTH_USER_POOL_ID: Cognito User Pool ID\n- INGRESS_OAUTH_CLIENT_ID: Cognito App Client ID for M2M\n- INGRESS_OAUTH_CLIENT_SECRET: Cognito App Client Secret for M2M\n- AWS_REGION: AWS region (defaults to us-east-1)\n\nFor AUTH_PROVIDER=keycloak:\n- KEYCLOAK_URL: Keycloak server URL\n- KEYCLOAK_REALM: Keycloak realm name\n- KEYCLOAK_M2M_CLIENT_ID: Keycloak M2M client ID\n- KEYCLOAK_M2M_CLIENT_SECRET: Keycloak M2M client secret\n\nFor AUTH_PROVIDER=entra:\n- ENTRA_TENANT_ID: Azure AD Tenant ID (GUID)\n- ENTRA_CLIENT_ID: App Registration Client ID (GUID)\n- ENTRA_CLIENT_SECRET: App Registration Client Secret\n\nUsage:\n python ingress_oauth.py\n python ingress_oauth.py --verbose\n python ingress_oauth.py --force # Force new token generation\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nimport time\nfrom pathlib import Path\nfrom typing import Any\n\nimport requests\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n# Try to load .env file if python-dotenv is available\ntry:\n from dotenv import load_dotenv\n\n # Load .env from the same directory as this script\n env_file = Path(__file__).parent / \".env\"\n if env_file.exists():\n load_dotenv(env_file)\n logger.debug(f\"Loaded environment variables from {env_file}\")\n else:\n # Fallback: try parent directory (project root)\n env_file_parent = Path(__file__).parent.parent / \".env\"\n if env_file_parent.exists():\n load_dotenv(env_file_parent)\n logger.debug(f\"Loaded environment variables from {env_file_parent}\")\n else:\n # Final fallback: try current working directory\n load_dotenv()\n logger.debug(\"Tried to load .env from current working directory\")\nexcept ImportError:\n logger.debug(\"python-dotenv not available, skipping .env loading\")\n\n\ndef _validate_environment_variables() -> None:\n \"\"\"Validate that all required INGRESS OAuth environment variables are set.\"\"\"\n auth_provider = os.getenv(\"AUTH_PROVIDER\", \"cognito\").lower()\n\n if auth_provider == \"keycloak\":\n required_vars = [\n \"KEYCLOAK_URL\",\n \"KEYCLOAK_REALM\",\n \"KEYCLOAK_M2M_CLIENT_ID\",\n \"KEYCLOAK_M2M_CLIENT_SECRET\",\n ]\n elif auth_provider == \"entra\":\n required_vars = [\"ENTRA_TENANT_ID\", \"ENTRA_CLIENT_ID\", \"ENTRA_CLIENT_SECRET\"]\n else: # cognito (default)\n required_vars = [\n \"INGRESS_OAUTH_USER_POOL_ID\",\n \"INGRESS_OAUTH_CLIENT_ID\",\n \"INGRESS_OAUTH_CLIENT_SECRET\",\n ]\n\n missing_vars = []\n for var in required_vars:\n if not os.getenv(var):\n missing_vars.append(var)\n\n if missing_vars:\n logger.error(f\"Missing required INGRESS OAuth environment variables for {auth_provider}:\")\n for var in missing_vars:\n logger.error(f\" - {var}\")\n logger.error(\"\\nPlease set the following environment variables:\")\n for var in missing_vars:\n logger.error(f\" export {var}=\")\n logger.error(\"\\nOr add them to your .env file\")\n raise SystemExit(1)\n\n logger.debug(f\"All required INGRESS OAuth environment variables are set for {auth_provider}\")\n\n\ndef _get_cognito_domain(user_pool_id: str, region: str) -> str:\n \"\"\"Generate Cognito domain from user pool ID.\"\"\"\n # Use user pool ID without underscores as domain (standard Cognito format)\n domain = user_pool_id.replace(\"_\", \"\")\n return f\"https://{domain}.auth.{region}.amazoncognito.com\"\n\n\ndef _perform_keycloak_m2m_authentication(\n client_id: str, client_secret: str, keycloak_url: str, realm: str\n) -> dict[str, Any]:\n \"\"\"Perform M2M (client credentials) OAuth 2.0 authentication with Keycloak.\"\"\"\n try:\n # Generate token URL for Keycloak\n token_url = f\"{keycloak_url}/realms/{realm}/protocol/openid-connect/token\"\n\n # Prepare the token request\n payload = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n }\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n logger.info(f\"Requesting M2M token from {token_url}\")\n logger.debug(f\"Using client_id: {client_id[:10]}...\" if client_id else \"No client_id\")\n\n response = requests.post(token_url, data=payload, headers=headers, timeout=30)\n\n if not response.ok:\n logger.error(\n f\"M2M token request failed with status {response.status_code}. Response: {response.text}\"\n )\n raise ValueError(f\"Token request failed: {response.text}\")\n\n token_data = response.json()\n\n if \"access_token\" not in token_data:\n logger.error(\n f\"Access token not found in M2M response. Keys found: {list(token_data.keys())}\"\n )\n raise ValueError(\"No access token in response\")\n\n # Calculate expiry time\n expires_at = None\n if \"expires_in\" in token_data:\n expires_at = time.time() + token_data[\"expires_in\"]\n else:\n # Fallback: assume 10800 seconds (3 hours) validity if not specified\n logger.warning(\"No expires_in in token response, assuming 10800 seconds validity\")\n expires_at = time.time() + 10800\n token_data[\"expires_in\"] = 10800\n\n # Prepare result\n result = {\n \"access_token\": token_data[\"access_token\"],\n \"refresh_token\": token_data.get(\n \"refresh_token\"\n ), # M2M typically doesn't have refresh tokens\n \"expires_at\": expires_at,\n \"token_type\": token_data.get(\"token_type\", \"Bearer\"), # nosec B105 - OAuth2 standard token type per RFC 6750\n \"provider\": \"keycloak_m2m\",\n \"client_id\": client_id,\n \"keycloak_url\": keycloak_url,\n \"realm\": realm,\n }\n\n logger.info(\"M2M token obtained successfully!\")\n\n if expires_at:\n expires_in = int(expires_at - time.time())\n logger.info(f\"Token expires in: {expires_in} seconds\")\n\n return result\n\n except requests.exceptions.RequestException as e:\n logger.error(f\"Network error during M2M token request: {e}\")\n raise\n except Exception as e:\n logger.error(f\"Failed to obtain M2M token: {e}\")\n raise\n\n\ndef _perform_entra_m2m_authentication(\n tenant_id: str, client_id: str, client_secret: str\n) -> dict[str, Any]:\n \"\"\"Perform M2M (client credentials) OAuth 2.0 authentication with Microsoft Entra ID.\"\"\"\n try:\n # Generate token URL for Entra ID\n token_url = f\"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token\"\n\n # Prepare the token request\n payload = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"scope\": f\"api://{client_id}/.default\",\n }\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n logger.info(f\"Requesting M2M token from {token_url}\")\n logger.debug(f\"Using client_id: {client_id[:10]}...\" if client_id else \"No client_id\")\n\n response = requests.post(token_url, data=payload, headers=headers, timeout=30)\n\n if not response.ok:\n logger.error(\n f\"M2M token request failed with status {response.status_code}. Response: {response.text}\"\n )\n raise ValueError(f\"Token request failed: {response.text}\")\n\n token_data = response.json()\n\n if \"access_token\" not in token_data:\n logger.error(\n f\"Access token not found in M2M response. Keys found: {list(token_data.keys())}\"\n )\n raise ValueError(\"No access token in response\")\n\n # Calculate expiry time\n expires_at = None\n if \"expires_in\" in token_data:\n expires_at = time.time() + token_data[\"expires_in\"]\n else:\n # Fallback: assume 3599 seconds (1 hour) validity if not specified\n logger.warning(\"No expires_in in token response, assuming 3599 seconds validity\")\n expires_at = time.time() + 3599\n token_data[\"expires_in\"] = 3599\n\n # Prepare result\n result = {\n \"access_token\": token_data[\"access_token\"],\n \"refresh_token\": token_data.get(\n \"refresh_token\"\n ), # M2M typically doesn't have refresh tokens\n \"expires_at\": expires_at,\n \"token_type\": token_data.get(\"token_type\", \"Bearer\"), # nosec B105 - OAuth2 standard token type per RFC 6750\n \"provider\": \"entra_m2m\",\n \"client_id\": client_id,\n \"tenant_id\": tenant_id,\n }\n\n logger.info(\"M2M token obtained successfully!\")\n\n if expires_at:\n expires_in = int(expires_at - time.time())\n logger.info(f\"Token expires in: {expires_in} seconds\")\n\n return result\n\n except requests.exceptions.RequestException as e:\n logger.error(f\"Network error during M2M token request: {e}\")\n raise\n except Exception as e:\n logger.error(f\"Failed to obtain M2M token: {e}\")\n raise\n\n\ndef _perform_m2m_authentication(\n client_id: str, client_secret: str, user_pool_id: str, region: str\n) -> dict[str, Any]:\n \"\"\"Perform M2M (client credentials) OAuth 2.0 authentication with Cognito.\"\"\"\n try:\n # Generate token URL\n cognito_domain = _get_cognito_domain(user_pool_id, region)\n token_url = f\"{cognito_domain}/oauth2/token\"\n\n # Prepare the token request\n payload = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n }\n\n # Note: For Cognito M2M tokens, the expiry time is controlled by the\n # User Pool Resource Server settings, not the client request.\n # The token validity period should be configured in the AWS Console\n # under Cognito User Pool > App Integration > Resource Servers\n # to set the desired 10800 seconds (3 hours) validity.\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n logger.info(f\"Requesting M2M token from {token_url}\")\n logger.debug(f\"Using client_id: {client_id[:10]}...\" if client_id else \"No client_id\")\n\n response = requests.post(token_url, data=payload, headers=headers, timeout=30)\n\n if not response.ok:\n logger.error(\n f\"M2M token request failed with status {response.status_code}. Response: {response.text}\"\n )\n raise ValueError(f\"Token request failed: {response.text}\")\n\n token_data = response.json()\n\n if \"access_token\" not in token_data:\n logger.error(\n f\"Access token not found in M2M response. Keys found: {list(token_data.keys())}\"\n )\n raise ValueError(\"No access token in response\")\n\n # Calculate expiry time\n expires_at = None\n if \"expires_in\" in token_data:\n expires_at = time.time() + token_data[\"expires_in\"]\n else:\n # Fallback: assume 10800 seconds (3 hours) validity if not specified\n logger.warning(\"No expires_in in token response, assuming 10800 seconds validity\")\n expires_at = time.time() + 10800\n token_data[\"expires_in\"] = 10800\n\n # Prepare result\n result = {\n \"access_token\": token_data[\"access_token\"],\n \"refresh_token\": token_data.get(\n \"refresh_token\"\n ), # M2M typically doesn't have refresh tokens\n \"expires_at\": expires_at,\n \"token_type\": token_data.get(\"token_type\", \"Bearer\"), # nosec B105 - OAuth2 standard token type per RFC 6750\n \"provider\": \"cognito_m2m\",\n \"client_id\": client_id,\n \"user_pool_id\": user_pool_id,\n \"region\": region,\n }\n\n logger.info(\"M2M token obtained successfully!\")\n\n if expires_at:\n expires_in = int(expires_at - time.time())\n logger.info(f\"Token expires in: {expires_in} seconds\")\n\n return result\n\n except requests.exceptions.RequestException as e:\n logger.error(f\"Network error during M2M token request: {e}\")\n raise\n except Exception as e:\n logger.error(f\"Failed to obtain M2M token: {e}\")\n raise\n\n\ndef _save_ingress_tokens(token_data: dict[str, Any]) -> str:\n \"\"\"Save ingress tokens to ingress.json file.\"\"\"\n try:\n # Create .oauth-tokens directory in current working directory\n token_dir = Path.cwd() / \".oauth-tokens\"\n token_dir.mkdir(exist_ok=True, mode=0o700)\n\n # Save to ingress.json\n ingress_path = token_dir / \"ingress.json\"\n\n # Prepare token data for storage based on provider\n provider = token_data.get(\"provider\", \"cognito_m2m\")\n\n save_data = {\n \"provider\": provider,\n \"access_token\": token_data[\"access_token\"],\n \"refresh_token\": token_data.get(\"refresh_token\"),\n \"expires_at\": token_data.get(\"expires_at\"),\n \"expires_at_human\": time.strftime(\n \"%Y-%m-%d %H:%M:%S UTC\", time.gmtime(token_data[\"expires_at\"])\n )\n if token_data.get(\"expires_at\")\n else None,\n \"token_type\": token_data.get(\"token_type\", \"Bearer\"), # nosec B105 - OAuth2 standard token type per RFC 6750\n \"client_id\": token_data[\"client_id\"],\n \"saved_at\": time.strftime(\"%Y-%m-%d %H:%M:%S UTC\", time.gmtime()),\n }\n\n # Add provider-specific fields\n if provider == \"keycloak_m2m\":\n save_data.update(\n {\n \"keycloak_url\": token_data[\"keycloak_url\"],\n \"realm\": token_data[\"realm\"],\n \"usage_notes\": \"This token is for INGRESS authentication to the MCP Gateway (Keycloak M2M)\",\n }\n )\n elif provider == \"entra_m2m\":\n save_data.update(\n {\n \"tenant_id\": token_data[\"tenant_id\"],\n \"usage_notes\": \"This token is for INGRESS authentication to the MCP Gateway (Entra ID M2M)\",\n }\n )\n else: # cognito_m2m\n save_data.update(\n {\n \"user_pool_id\": token_data[\"user_pool_id\"],\n \"region\": token_data[\"region\"],\n \"usage_notes\": \"This token is for INGRESS authentication to the MCP Gateway (Cognito M2M)\",\n }\n )\n\n with open(ingress_path, \"w\") as f:\n json.dump(save_data, f, indent=2)\n\n # Secure the file\n ingress_path.chmod(0o600)\n logger.info(f\"Saved ingress tokens to: {ingress_path}\")\n\n return str(ingress_path)\n\n except Exception as e:\n logger.error(f\"Failed to save ingress tokens: {e}\")\n raise\n\n\ndef _load_existing_tokens() -> dict[str, Any] | None:\n \"\"\"Load existing ingress tokens if they exist and are valid.\"\"\"\n try:\n ingress_path = Path.cwd() / \".oauth-tokens\" / \"ingress.json\"\n\n if not ingress_path.exists():\n return None\n\n with open(ingress_path) as f:\n token_data = json.load(f)\n\n # Check if token is expired\n if token_data.get(\"expires_at\"):\n expires_at = token_data[\"expires_at\"]\n # Add 5 minute margin\n if time.time() + 300 >= expires_at:\n logger.info(\"Existing ingress token is expired or will expire soon\")\n return None\n\n logger.info(\"Found valid existing ingress token\")\n return token_data\n\n except Exception as e:\n logger.debug(f\"Failed to load existing tokens: {e}\")\n return None\n\n\ndef main() -> int:\n \"\"\"Main entry point.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Ingress OAuth Authentication for MCP Gateway (Cognito, Keycloak, or Entra ID M2M)\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n python ingress_oauth.py # Generate ingress token\n python ingress_oauth.py --verbose # With debug logging\n python ingress_oauth.py --force # Force new token generation\n\nEnvironment Variables Required:\nFor AUTH_PROVIDER=cognito (default):\n INGRESS_OAUTH_USER_POOL_ID # Cognito User Pool ID\n INGRESS_OAUTH_CLIENT_ID # Cognito Client ID for M2M\n INGRESS_OAUTH_CLIENT_SECRET # Cognito Client Secret for M2M\n AWS_REGION # AWS region (optional, defaults to us-east-1)\n\nFor AUTH_PROVIDER=keycloak:\n KEYCLOAK_URL # Keycloak server URL\n KEYCLOAK_REALM # Keycloak realm name\n KEYCLOAK_M2M_CLIENT_ID # Keycloak M2M client ID\n KEYCLOAK_M2M_CLIENT_SECRET # Keycloak M2M client secret\n\nFor AUTH_PROVIDER=entra:\n ENTRA_TENANT_ID # Azure AD Tenant ID (GUID)\n ENTRA_CLIENT_ID # App Registration Client ID (GUID)\n ENTRA_CLIENT_SECRET # App Registration Client Secret\n\"\"\",\n )\n\n parser.add_argument(\"--verbose\", \"-v\", action=\"store_true\", help=\"Enable verbose debug logging\")\n parser.add_argument(\n \"--force\",\n \"-f\",\n action=\"store_true\",\n help=\"Force new token generation, ignore existing valid tokens\",\n )\n\n args = parser.parse_args()\n\n if args.verbose:\n logging.getLogger().setLevel(logging.DEBUG)\n logger.setLevel(logging.DEBUG)\n\n try:\n # Validate environment variables\n _validate_environment_variables()\n\n # Determine authentication provider\n auth_provider = os.getenv(\"AUTH_PROVIDER\", \"cognito\").lower()\n\n logger.info(f\"Starting INGRESS OAuth authentication ({auth_provider} M2M)\")\n\n # Check for existing valid tokens (unless force is specified)\n if not args.force:\n existing_tokens = _load_existing_tokens()\n if existing_tokens:\n logger.info(\"Using existing valid ingress token\")\n logger.info(\n f\"Token expires at: {existing_tokens.get('expires_at_human', 'Unknown')}\"\n )\n return 0\n\n # Perform M2M authentication based on provider\n if auth_provider == \"keycloak\":\n # Get Keycloak configuration from environment\n client_id = os.getenv(\"KEYCLOAK_M2M_CLIENT_ID\")\n client_secret = os.getenv(\"KEYCLOAK_M2M_CLIENT_SECRET\")\n keycloak_url = (\n os.getenv(\"KEYCLOAK_ADMIN_URL\")\n or os.getenv(\"KEYCLOAK_EXTERNAL_URL\")\n or os.getenv(\"KEYCLOAK_URL\")\n )\n realm = os.getenv(\"KEYCLOAK_REALM\")\n\n logger.info(f\"Keycloak URL: {keycloak_url}\")\n logger.info(f\"Realm: {realm}\")\n logger.info(f\"Client ID: {client_id[:10]}...\")\n\n token_data = _perform_keycloak_m2m_authentication(\n client_id=client_id,\n client_secret=client_secret,\n keycloak_url=keycloak_url,\n realm=realm,\n )\n elif auth_provider == \"entra\":\n # Get Entra ID configuration from environment\n tenant_id = os.getenv(\"ENTRA_TENANT_ID\")\n client_id = os.getenv(\"ENTRA_CLIENT_ID\")\n client_secret = os.getenv(\"ENTRA_CLIENT_SECRET\")\n\n logger.info(f\"Tenant ID: {tenant_id}\")\n logger.info(f\"Client ID: {client_id[:10]}...\")\n\n token_data = _perform_entra_m2m_authentication(\n tenant_id=tenant_id, client_id=client_id, client_secret=client_secret\n )\n else: # cognito (default)\n # Get Cognito configuration from environment\n client_id = os.getenv(\"INGRESS_OAUTH_CLIENT_ID\")\n client_secret = os.getenv(\"INGRESS_OAUTH_CLIENT_SECRET\")\n user_pool_id = os.getenv(\"INGRESS_OAUTH_USER_POOL_ID\")\n region = os.getenv(\"AWS_REGION\", \"us-east-1\")\n\n logger.info(f\"User Pool ID: {user_pool_id}\")\n logger.info(f\"Client ID: {client_id[:10]}...\")\n logger.info(f\"Region: {region}\")\n\n token_data = _perform_m2m_authentication(\n client_id=client_id,\n client_secret=client_secret,\n user_pool_id=user_pool_id,\n region=region,\n )\n\n # Save tokens\n saved_path = _save_ingress_tokens(token_data)\n\n logger.info(\"INGRESS OAuth authentication completed successfully!\")\n logger.info(f\"Tokens saved to: {saved_path}\")\n\n return 0\n\n except Exception as e:\n logger.error(f\"ERROR: INGRESS OAuth authentication failed: {e}\")\n if args.verbose:\n import traceback\n\n logger.error(traceback.format_exc())\n return 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "credentials-provider/oauth/oauth_providers.yaml", "content": "# OAuth 2.0 Provider Configurations\n# This file contains OAuth provider configurations for various services\n# Each provider has required fields and optional fields\n\nproviders:\n atlassian:\n display_name: \"Atlassian Cloud\"\n auth_url: \"https://auth.atlassian.com/authorize\"\n token_url: \"https://auth.atlassian.com/oauth/token\"\n user_info_url: \"https://api.atlassian.com/oauth/token/accessible-resources\"\n scopes:\n # Original minimal scopes (commented for fallback)\n # - \"read:jira-work\"\n # - \"write:jira-work\"\n # - \"read:confluence-space.summary\"\n # - \"offline_access\"\n \n # Expanded comprehensive scopes for full Atlassian access\n - \"offline_access\"\n - \"write:confluence-content\"\n - \"read:confluence-space.summary\"\n - \"write:confluence-space\"\n - \"write:confluence-file\"\n - \"read:confluence-props\"\n - \"write:confluence-props\"\n - \"manage:confluence-configuration\"\n - \"read:confluence-content.all\"\n - \"read:confluence-content.summary\"\n - \"search:confluence\"\n - \"read:confluence-content.permission\"\n - \"read:confluence-user\"\n - \"read:confluence-groups\"\n - \"write:confluence-groups\"\n - \"readonly:content.attachment:confluence\"\n - \"read:jira-work\"\n - \"manage:jira-project\"\n - \"manage:jira-configuration\"\n - \"read:jira-user\"\n - \"write:jira-work\"\n - \"manage:jira-webhook\"\n - \"manage:jira-data-provider\"\n - \"read:servicedesk-request\"\n - \"manage:servicedesk-customer\"\n - \"write:servicedesk-request\"\n - \"read:servicemanagement-insight-objects\"\n - \"read:me\"\n - \"read:account\"\n - \"report:personal-data\"\n - \"write:component:compass\"\n - \"read:scorecard:compass\"\n - \"write:scorecard:compass\"\n - \"read:component:compass\"\n - \"read:event:compass\"\n - \"write:event:compass\"\n - \"read:metric:compass\"\n - \"write:metric:compass\"\n - \"read:backup:brie\"\n - \"write:backup:brie\"\n - \"read:restore:brie\"\n - \"write:restore:brie\"\n - \"read:account:brie\"\n - \"write:storage:brie\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n audience: \"api.atlassian.com\"\n requires_pkce: false\n additional_params:\n prompt: \"consent\"\n # Provider-specific fields\n requires_cloud_id: true\n cloud_id_from_user_info: true\n\n google:\n display_name: \"Google\"\n auth_url: \"https://accounts.google.com/o/oauth2/v2/auth\"\n token_url: \"https://oauth2.googleapis.com/token\"\n user_info_url: \"https://www.googleapis.com/oauth2/v2/userinfo\"\n scopes:\n - \"openid\"\n - \"email\"\n - \"profile\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: true\n additional_params:\n access_type: \"offline\"\n approval_prompt: \"force\"\n\n github:\n display_name: \"GitHub\"\n auth_url: \"https://github.com/login/oauth/authorize\"\n token_url: \"https://github.com/login/oauth/access_token\"\n user_info_url: \"https://api.github.com/user\"\n scopes:\n - \"read:user\"\n - \"user:email\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: false\n additional_params: {}\n # Provider-specific headers\n token_headers:\n Accept: \"application/json\"\n\n cognito:\n display_name: \"Amazon Cognito\"\n # These URLs use templates that will be filled in at runtime\n auth_url: \"https://{domain}.auth.{region}.amazoncognito.com/oauth2/authorize\"\n token_url: \"https://{domain}.auth.{region}.amazoncognito.com/oauth2/token\"\n user_info_url: \"https://{domain}.auth.{region}.amazoncognito.com/oauth2/userInfo\"\n scopes:\n - \"openid\"\n - \"email\"\n - \"profile\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: true\n additional_params: {}\n # Template variables required for this provider\n requires_template_vars:\n - domain\n - region\n template_var_defaults:\n region: \"us-east-1\"\n \n cognito_m2m:\n display_name: \"Amazon Cognito (M2M/Client Credentials)\"\n # M2M flow doesn't use authorization URL\n auth_url: \"\"\n token_url: \"https://{domain}.auth.{region}.amazoncognito.com/oauth2/token\"\n user_info_url: \"\" # M2M tokens don't have user info\n scopes: [] # M2M scopes are defined per client in Cognito - leave empty to use client defaults\n response_type: \"\" # Not used in M2M flow\n grant_type: \"client_credentials\"\n requires_pkce: false\n additional_params: {}\n # Template variables required for this provider\n requires_template_vars:\n - domain\n - region\n template_var_defaults:\n region: \"us-east-1\"\n # M2M specific configuration\n is_m2m: true\n supports_browser_flow: false\n\n microsoft:\n display_name: \"Microsoft\"\n auth_url: \"https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize\"\n token_url: \"https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token\"\n user_info_url: \"https://graph.microsoft.com/v1.0/me\"\n scopes:\n - \"openid\"\n - \"email\"\n - \"profile\"\n - \"offline_access\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: true\n additional_params: {}\n requires_template_vars:\n - tenant\n template_var_defaults:\n tenant: \"common\"\n\n slack:\n display_name: \"Slack\"\n auth_url: \"https://slack.com/oauth/v2/authorize\"\n token_url: \"https://slack.com/api/oauth.v2.access\"\n user_info_url: \"https://slack.com/api/users.identity\"\n scopes:\n - \"identity.basic\"\n - \"identity.email\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: false\n additional_params: {}\n\n discord:\n display_name: \"Discord\"\n auth_url: \"https://discord.com/oauth2/authorize\"\n token_url: \"https://discord.com/api/oauth2/token\"\n user_info_url: \"https://discord.com/api/users/@me\"\n scopes:\n - \"identify\"\n - \"email\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: false\n additional_params: {}\n\n linkedin:\n display_name: \"LinkedIn\"\n auth_url: \"https://www.linkedin.com/oauth/v2/authorization\"\n token_url: \"https://www.linkedin.com/oauth/v2/accessToken\"\n user_info_url: \"https://api.linkedin.com/v2/me\"\n scopes:\n - \"r_liteprofile\"\n - \"r_emailaddress\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: false\n additional_params: {}\n\n spotify:\n display_name: \"Spotify\"\n auth_url: \"https://accounts.spotify.com/authorize\"\n token_url: \"https://accounts.spotify.com/api/token\"\n user_info_url: \"https://api.spotify.com/v1/me\"\n scopes:\n - \"user-read-email\"\n - \"user-read-private\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: true\n additional_params: {}\n\n twitter:\n display_name: \"Twitter/X\"\n auth_url: \"https://twitter.com/i/oauth2/authorize\"\n token_url: \"https://api.twitter.com/2/oauth2/token\"\n user_info_url: \"https://api.twitter.com/2/users/me\"\n scopes:\n - \"tweet.read\"\n - \"users.read\"\n - \"offline.access\"\n response_type: \"code\"\n grant_type: \"authorization_code\"\n requires_pkce: true\n additional_params:\n code_challenge_method: \"S256\"\n\n# Configuration metadata\nmetadata:\n version: \"1.0\"\n description: \"OAuth 2.0 provider configurations for multiple services\"\n last_updated: \"2025-08-12\"" }, { "path": "credentials-provider/okta/__init__.py", "content": "\"\"\"Okta credential provider utilities.\"\"\"\n" }, { "path": "credentials-provider/okta/get_m2m_token.py", "content": "\"\"\"Get Okta M2M token using client credentials flow.\n\nThis script obtains a JWT token from Okta using OAuth2 client credentials grant.\nThe token is saved to a temporary file and the file path is printed.\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport sys\nimport tempfile\n\nimport jwt\nimport requests\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _get_okta_domain() -> str:\n \"\"\"Get Okta domain from CLI arg or environment variable.\n\n Returns:\n Okta domain (e.g., integrator-9917255.okta.com)\n\n Raises:\n ValueError: If domain not provided\n \"\"\"\n domain = os.getenv(\"OKTA_DOMAIN\")\n if domain:\n return domain.replace(\"https://\", \"\").rstrip(\"/\")\n\n raise ValueError(\"Okta domain must be provided via --okta-domain or OKTA_DOMAIN env var\")\n\n\ndef _get_client_id() -> str:\n \"\"\"Get client ID from CLI arg or environment variable.\n\n Returns:\n Okta client ID\n\n Raises:\n ValueError: If client ID not provided\n \"\"\"\n client_id = os.getenv(\"OKTA_CLIENT_ID\")\n if client_id:\n return client_id\n\n raise ValueError(\"Client ID must be provided via --client-id or OKTA_CLIENT_ID env var\")\n\n\ndef _get_client_secret() -> str:\n \"\"\"Get client secret from CLI arg or environment variable.\n\n Returns:\n Okta client secret\n\n Raises:\n ValueError: If client secret not provided\n \"\"\"\n client_secret = os.getenv(\"OKTA_CLIENT_SECRET\")\n if client_secret:\n return client_secret\n\n raise ValueError(\n \"Client secret must be provided via --client-secret or OKTA_CLIENT_SECRET env var\"\n )\n\n\ndef _request_m2m_token(\n okta_domain: str,\n client_id: str,\n client_secret: str,\n scope: str,\n auth_server_id: str | None = None,\n) -> dict[str, str]:\n \"\"\"Request M2M token from Okta using client credentials.\n\n Args:\n okta_domain: Okta domain (e.g., integrator-9917255.okta.com)\n client_id: OAuth2 client ID\n client_secret: OAuth2 client secret\n scope: OAuth2 scopes (space-separated)\n auth_server_id: Optional custom authorization server ID (e.g., aus1108sx6pwGzb8T698)\n\n Returns:\n Token response dictionary with access_token, token_type, expires_in\n\n Raises:\n ValueError: If token request fails\n \"\"\"\n # Use custom auth server if provided, otherwise use org auth server\n if auth_server_id:\n token_url = f\"https://{okta_domain}/oauth2/{auth_server_id}/v1/token\"\n else:\n token_url = f\"https://{okta_domain}/oauth2/v1/token\"\n\n logger.info(f\"Requesting M2M token from {token_url}\")\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n \"scope\": scope,\n }\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n try:\n response = requests.post(\n token_url,\n data=data,\n headers=headers,\n timeout=30,\n )\n\n # Log response details for debugging\n if response.status_code != 200:\n try:\n error_data = response.json()\n logger.error(f\"Okta error response: {json.dumps(error_data, indent=2)}\")\n except Exception:\n logger.error(f\"Okta error response (non-JSON): {response.text}\")\n\n response.raise_for_status()\n\n token_data = response.json()\n logger.info(\n f\"Successfully obtained M2M token, expires in {token_data.get('expires_in', 'unknown')} seconds\"\n )\n\n return token_data\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get M2M token: {e}\")\n raise ValueError(f\"M2M token request failed: {e}\")\n\n\ndef _decode_token(access_token: str) -> dict[str, str]:\n \"\"\"Decode JWT token without verification to display claims.\n\n Args:\n access_token: JWT access token string\n\n Returns:\n Dictionary of decoded token claims\n \"\"\"\n try:\n claims = jwt.decode(access_token, options={\"verify_signature\": False})\n return claims\n except Exception as e:\n logger.warning(f\"Failed to decode token: {e}\")\n return {}\n\n\ndef _display_decoded_token(claims: dict[str, str]) -> None:\n \"\"\"Display decoded token claims in a readable format.\n\n Args:\n claims: Dictionary of decoded JWT claims\n \"\"\"\n if not claims:\n return\n\n print(\"\\n\" + \"=\" * 60)\n print(\"DECODED JWT TOKEN CLAIMS\")\n print(\"=\" * 60)\n print(json.dumps(claims, indent=2))\n print(\"\\n\" + \"=\" * 60)\n print(\"KEY INFORMATION\")\n print(\"=\" * 60)\n print(f\"Client ID (cid): {claims.get('cid', 'N/A')}\")\n print(f\"Subject (sub): {claims.get('sub', 'N/A')}\")\n print(f\"Issuer (iss): {claims.get('iss', 'N/A')}\")\n print(f\"Audience (aud): {claims.get('aud', 'N/A')}\")\n print(f\"Scopes (scp): {claims.get('scp', [])}\")\n print(f\"Groups: {claims.get('groups', [])}\")\n\n # Display expiration info\n if \"exp\" in claims and \"iat\" in claims:\n from datetime import datetime\n\n exp_time = datetime.fromtimestamp(claims[\"exp\"])\n iat_time = datetime.fromtimestamp(claims[\"iat\"])\n lifetime_hours = (claims[\"exp\"] - claims[\"iat\"]) / 3600\n print(f\"\\nIssued at: {iat_time} UTC\")\n print(f\"Expires at: {exp_time} UTC\")\n print(f\"Lifetime: {lifetime_hours:.1f} hours\")\n print(\"=\" * 60 + \"\\n\")\n\n\ndef _save_token_to_file(token_data: dict[str, str]) -> str:\n \"\"\"Save token data to temporary file.\n\n Args:\n token_data: Token response dictionary\n\n Returns:\n Path to temporary file containing token\n \"\"\"\n # Create temporary file with secure permissions (0600)\n fd, temp_path = tempfile.mkstemp(\n prefix=\"okta_m2m_token_\",\n suffix=\".json\",\n dir=\"/tmp\",\n )\n\n try:\n # Write token data as JSON\n with os.fdopen(fd, \"w\") as f:\n json.dump(token_data, f, indent=2)\n\n # Ensure file has restrictive permissions\n os.chmod(temp_path, 0o600)\n\n logger.info(f\"Token saved to {temp_path}\")\n return temp_path\n\n except Exception as e:\n # Clean up on error\n try:\n os.unlink(temp_path)\n except Exception:\n pass\n raise ValueError(f\"Failed to save token to file: {e}\")\n\n\ndef main() -> None:\n \"\"\"Main function to get Okta M2M token and save to file.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Get Okta M2M token using client credentials flow\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExample usage:\n # Using environment variables\n export OKTA_DOMAIN=integrator-9917255.okta.com\n export OKTA_CLIENT_ID=0oa1100req1AzfKaY698\n export OKTA_CLIENT_SECRET=EiZC6S2dyaWJ_qKmuToJ1KuZooVwOpGH4qF3N4Eao6YTFueAShId595ot9AyYCC6\n uv run python -m credentials-provider.okta.get_m2m_token\n\n # Using CLI arguments\n uv run python -m credentials-provider.okta.get_m2m_token \\\\\n --okta-domain integrator-9917255.okta.com \\\\\n --client-id 0oa1100req1AzfKaY698 \\\\\n --client-secret EiZC6S2dyaWJ_qKmuToJ1KuZooVwOpGH4qF3N4Eao6YTFueAShId595ot9AyYCC6 \\\\\n --scope \"openid email profile\"\n\"\"\",\n )\n\n parser.add_argument(\n \"--okta-domain\",\n type=str,\n help=\"Okta domain (e.g., integrator-9917255.okta.com). Can also use OKTA_DOMAIN env var.\",\n )\n\n parser.add_argument(\n \"--client-id\",\n type=str,\n help=\"OAuth2 client ID. Can also use OKTA_CLIENT_ID env var.\",\n )\n\n parser.add_argument(\n \"--client-secret\",\n type=str,\n help=\"OAuth2 client secret. Can also use OKTA_CLIENT_SECRET env var.\",\n )\n\n parser.add_argument(\n \"--scope\",\n type=str,\n default=\"openid\",\n help=\"OAuth2 scopes (space-separated). Default: openid\",\n )\n\n parser.add_argument(\n \"--auth-server-id\",\n type=str,\n help=\"Custom authorization server ID (e.g., aus1108sx6pwGzb8T698). If not provided, uses org auth server.\",\n )\n\n parser.add_argument(\n \"--show-token\",\n action=\"store_true\",\n help=\"Display decoded token claims (default: True)\",\n default=True,\n )\n\n parser.add_argument(\n \"--no-show-token\",\n action=\"store_true\",\n help=\"Do not display decoded token claims\",\n )\n\n parser.add_argument(\n \"--debug\",\n action=\"store_true\",\n help=\"Enable debug logging\",\n )\n\n args = parser.parse_args()\n\n # Set debug logging if requested\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n try:\n # Get configuration from CLI args or environment variables\n okta_domain = args.okta_domain or _get_okta_domain()\n client_id = args.client_id or _get_client_id()\n client_secret = args.client_secret or _get_client_secret()\n\n # Request M2M token from Okta\n token_data = _request_m2m_token(\n okta_domain=okta_domain,\n client_id=client_id,\n client_secret=client_secret,\n scope=args.scope,\n auth_server_id=args.auth_server_id,\n )\n\n # Decode and display token if requested\n show_token = args.show_token and not args.no_show_token\n if show_token and \"access_token\" in token_data:\n claims = _decode_token(token_data[\"access_token\"])\n _display_decoded_token(claims)\n\n # Save token to temporary file\n token_file_path = _save_token_to_file(token_data)\n\n # Print the file path\n print(f\"Token saved to: {token_file_path}\")\n\n except ValueError as e:\n logger.error(f\"Error: {e}\")\n sys.exit(1)\n except Exception as e:\n logger.exception(f\"Unexpected error: {e}\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "credentials-provider/token_refresher.py", "content": "#!/usr/bin/env python3\n\"\"\"\nOAuth Token Refresher Service\n\nThis service monitors OAuth tokens in the .oauth-tokens directory and automatically\nrefreshes them before they expire. It runs continuously in the background, checking\ntokens every configurable interval (default 5 minutes).\n\nUsage:\n uv run python credentials-provider/token_refresher.py # Run with defaults\n uv run python credentials-provider/token_refresher.py --interval 300 # Check every 5 minutes\n uv run python credentials-provider/token_refresher.py --buffer 3600 # Refresh 1 hour before expiry\n uv run python credentials-provider/token_refresher.py --once # Run once and exit\n uv run python credentials-provider/token_refresher.py --once --force # Force refresh all tokens once and exit\n nohup uv run python credentials-provider/token_refresher.py > token_refresher.log 2>&1 & # Run in background\n\"\"\"\n\nimport argparse\nimport json\nimport logging\nimport os\nimport signal\nimport subprocess # nosec B404\nimport sys\nimport tempfile\nimport time\nfrom pathlib import Path\n\nimport psutil\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _load_env_file() -> None:\n \"\"\"Load environment variables from .env file in project root.\"\"\"\n # Get the project root directory (parent of credentials-provider)\n script_dir = Path(__file__).parent\n project_root = script_dir.parent\n env_file = project_root / \".env\"\n\n if env_file.exists():\n try:\n with open(env_file) as f:\n for line in f:\n line = line.strip()\n if line and not line.startswith(\"#\") and \"=\" in line:\n key, value = line.split(\"=\", 1)\n # Remove quotes if present\n value = value.strip('\"').strip(\"'\")\n os.environ[key] = value\n logger.debug(f\"Loaded environment variables from {env_file}\")\n except Exception as e:\n logger.warning(f\"Failed to load .env file: {e}\")\n else:\n logger.debug(f\"No .env file found at {env_file}\")\n\n\n# Configuration constants\nDEFAULT_CHECK_INTERVAL = 300 # 5 minutes in seconds\nDEFAULT_EXPIRY_BUFFER = 3600 # 1 hour buffer before expiry\n\n# Process management\nPIDFILE_NAME = \"token_refresher.pid\"\n\n# Dynamically determine paths relative to this script's location\nSCRIPT_DIR = Path(__file__).parent\nPROJECT_ROOT = SCRIPT_DIR.parent\nOAUTH_TOKENS_DIR = PROJECT_ROOT / \".oauth-tokens\"\nCREDENTIALS_PROVIDER_DIR = SCRIPT_DIR\n\n# Files to ignore during token refresh (derived files that get regenerated)\nIGNORED_FILES = {\n \"mcp.json\",\n \"vscode_mcp.json\",\n \"*readable*\", # Any file with \"readable\" in the name\n}\n\n\ndef _should_ignore_file(filename: str) -> bool:\n \"\"\"\n Check if a token file should be ignored.\n\n Args:\n filename: Name of the token file\n\n Returns:\n True if file should be ignored, False otherwise\n \"\"\"\n # Check exact matches\n if filename in {\"mcp.json\", \"vscode_mcp.json\"}:\n return True\n\n # Check for \"readable\" in filename\n if \"readable\" in filename.lower():\n return True\n\n return False\n\n\ndef _parse_token_file(filepath: Path) -> dict | None:\n \"\"\"\n Parse a token JSON file and extract relevant information.\n\n Args:\n filepath: Path to the token file\n\n Returns:\n Token data dict or None if file cannot be parsed\n \"\"\"\n try:\n with open(filepath) as f:\n data = json.load(f)\n\n # Validate required fields\n if \"expires_at\" not in data:\n logger.debug(f\"No expires_at field in {filepath.name}\")\n return None\n\n return data\n except (OSError, json.JSONDecodeError) as e:\n logger.warning(f\"Failed to parse {filepath.name}: {e}\")\n return None\n\n\ndef _get_all_tokens() -> list[tuple[Path, dict]]:\n \"\"\"\n Get all valid token files regardless of expiration status.\n\n Returns:\n List of (filepath, token_data) tuples for all valid tokens\n \"\"\"\n if not OAUTH_TOKENS_DIR.exists():\n logger.error(\"OAuth tokens directory not found\")\n return []\n\n all_tokens = []\n\n for filepath in OAUTH_TOKENS_DIR.glob(\"*.json\"):\n # Skip ignored files\n if _should_ignore_file(filepath.name):\n logger.debug(f\"Ignoring file: {filepath.name}\")\n continue\n\n # Parse token file\n token_data = _parse_token_file(filepath)\n if not token_data:\n continue\n\n logger.info(f\"Found token file: {filepath.name}\")\n logger.debug(f\"Reading token from: {filepath.absolute()}\")\n all_tokens.append((filepath, token_data))\n\n return all_tokens\n\n\ndef _get_expiring_tokens(buffer_seconds: int = DEFAULT_EXPIRY_BUFFER) -> list[tuple[Path, dict]]:\n \"\"\"\n Find all tokens that are expired or will expire within the buffer period.\n\n Args:\n buffer_seconds: Number of seconds before expiry to trigger refresh\n\n Returns:\n List of (filepath, token_data) tuples for expiring tokens\n \"\"\"\n if not OAUTH_TOKENS_DIR.exists():\n logger.error(f\"OAuth tokens directory not found: {OAUTH_TOKENS_DIR}\")\n return []\n\n current_time = time.time()\n expiring_tokens = []\n\n for filepath in OAUTH_TOKENS_DIR.glob(\"*.json\"):\n # Skip ignored files\n if _should_ignore_file(filepath.name):\n logger.debug(f\"Ignoring file: {filepath.name}\")\n continue\n\n # Parse token file\n token_data = _parse_token_file(filepath)\n if not token_data:\n continue\n\n logger.debug(f\"Reading token from: {filepath.absolute()}\")\n\n # Check expiration\n expires_at = token_data.get(\"expires_at\", 0)\n\n # Convert ISO timestamp to Unix timestamp if needed\n if isinstance(expires_at, str):\n try:\n from datetime import datetime\n\n # Parse ISO timestamp and convert to Unix timestamp\n expires_at_dt = datetime.fromisoformat(expires_at.replace(\"Z\", \"+00:00\"))\n expires_at = expires_at_dt.timestamp()\n except (ValueError, AttributeError) as e:\n logger.warning(\n f\"Could not parse expires_at timestamp '{expires_at}' in {filepath.name}: {e}\"\n )\n continue\n\n time_until_expiry = expires_at - current_time\n\n if time_until_expiry <= buffer_seconds:\n hours_until_expiry = time_until_expiry / 3600\n if time_until_expiry <= 0:\n logger.warning(\n f\"Token EXPIRED: {filepath.name} (expired {-hours_until_expiry:.1f} hours ago)\"\n )\n else:\n logger.info(\n f\"Token expiring soon: {filepath.name} (expires in {hours_until_expiry:.1f} hours)\"\n )\n logger.debug(f\"Will refresh token at: {filepath.absolute()}\")\n expiring_tokens.append((filepath, token_data))\n\n return expiring_tokens\n\n\ndef _determine_refresh_method(token_data: dict, filename: str) -> str | None:\n \"\"\"\n Determine which refresh method to use based on token data.\n\n Args:\n token_data: Parsed token data\n filename: Token filename\n\n Returns:\n Refresh method ('agentcore' or 'oauth') or None if cannot determine\n \"\"\"\n provider = token_data.get(\"provider\", \"\").lower()\n\n # Check for AgentCore/Bedrock tokens\n if \"bedrock\" in provider or \"agentcore\" in provider:\n return \"agentcore\"\n\n # Check for OAuth providers (including Keycloak and Cognito M2M)\n oauth_providers = [\"atlassian\", \"google\", \"github\", \"microsoft\", \"oauth\", \"keycloak\", \"cognito\"]\n if any(p in provider for p in oauth_providers):\n return \"oauth\"\n\n # Try to infer from filename\n if \"bedrock\" in filename.lower() or \"agentcore\" in filename.lower():\n return \"agentcore\"\n\n if \"egress\" in filename.lower() or \"ingress\" in filename.lower():\n return \"oauth\"\n\n logger.warning(f\"Cannot determine refresh method for {filename} with provider '{provider}'\")\n return None\n\n\ndef _refresh_agentcore_token(token_data: dict, filename: str) -> bool:\n \"\"\"\n Refresh a Bedrock AgentCore token using generate_access_token.py.\n\n Args:\n token_data: Current token data\n filename: Token filename\n\n Returns:\n True if refresh successful, False otherwise\n \"\"\"\n script_path = CREDENTIALS_PROVIDER_DIR / \"agentcore-auth\" / \"generate_access_token.py\"\n\n if not script_path.exists():\n logger.error(f\"AgentCore refresh script not found: {script_path}\")\n return False\n\n try:\n # Extract server name from filename if possible\n # Format: bedrock-agentcore-{server_name}-egress.json\n server_name = None\n if filename.startswith(\"bedrock-agentcore-\") and filename.endswith(\"-egress.json\"):\n server_name = filename.replace(\"bedrock-agentcore-\", \"\").replace(\"-egress.json\", \"\")\n\n logger.info(f\"Refreshing AgentCore token for: {server_name or 'default'}\")\n\n # Run the refresh script using uv run\n cmd = [\"uv\", \"run\", \"python\", str(script_path)]\n if server_name:\n # The script might accept server-specific parameters\n # Check the script for available options\n pass\n\n logger.debug(f\"Running AgentCore refresh command: {' '.join(cmd)}\")\n logger.debug(f\"Working directory: {PROJECT_ROOT.absolute()}\")\n\n result = subprocess.run( # nosec B603 - internal script path via uv run, no user input\n cmd, cwd=PROJECT_ROOT, capture_output=True, text=True, timeout=30\n )\n\n if result.returncode == 0:\n logger.info(f\"Successfully refreshed AgentCore token: {filename}\")\n return True\n else:\n logger.error(f\"Failed to refresh AgentCore token: {result.stderr}\")\n return False\n\n except subprocess.TimeoutExpired:\n logger.error(f\"Timeout refreshing AgentCore token: {filename}\")\n return False\n except Exception as e:\n logger.error(f\"Error refreshing AgentCore token {filename}: {e}\")\n return False\n\n\ndef _refresh_oauth_token(token_data: dict, filename: str) -> bool:\n \"\"\"\n Refresh a generic OAuth token using egress_oauth.py or ingress_oauth.py.\n\n Args:\n token_data: Current token data\n filename: Token filename\n\n Returns:\n True if refresh successful, False otherwise\n \"\"\"\n # Determine which OAuth script to use\n provider = token_data.get(\"provider\", \"atlassian\")\n\n if \"ingress\" in filename.lower() or provider == \"keycloak\":\n script_name = \"ingress_oauth.py\"\n # Ingress supports both Cognito and Keycloak M2M, doesn't use --provider argument\n use_provider_arg = False\n else:\n script_name = \"egress_oauth.py\" # Default to egress\n use_provider_arg = True\n\n script_path = CREDENTIALS_PROVIDER_DIR / \"oauth\" / script_name\n\n if not script_path.exists():\n logger.error(f\"OAuth refresh script not found: {script_path}\")\n return False\n\n try:\n logger.info(f\"Refreshing OAuth token for provider: {provider}\")\n\n # Build command based on script type\n cmd = [\"uv\", \"run\", \"python\", str(script_path)]\n\n # Only add --provider for egress OAuth (not ingress)\n # Ingress OAuth auto-detects Cognito vs Keycloak based on AUTH_PROVIDER env var\n if use_provider_arg:\n cmd.extend([\"--provider\", provider])\n\n logger.debug(f\"Running OAuth refresh command: {' '.join(cmd)}\")\n logger.debug(f\"Working directory: {PROJECT_ROOT.absolute()}\")\n\n # For Keycloak and Cognito M2M tokens, we don't typically have refresh tokens\n # The client_credentials flow will generate a new token\n if provider in [\"keycloak_m2m\", \"cognito_m2m\"]:\n logger.info(f\"M2M token detected ({provider}), using client_credentials flow\")\n elif \"refresh_token\" in token_data:\n logger.info(\"Refresh token available, script will handle refresh flow\")\n\n result = subprocess.run( # nosec B603 - internal script path via uv run, no user input\n cmd,\n cwd=PROJECT_ROOT,\n capture_output=True,\n text=True,\n timeout=60, # OAuth flow might take longer\n )\n\n if result.returncode == 0:\n logger.info(f\"Successfully refreshed OAuth token: {filename}\")\n return True\n else:\n logger.error(f\"Failed to refresh OAuth token: {result.stderr}\")\n return False\n\n except subprocess.TimeoutExpired:\n logger.error(f\"Timeout refreshing OAuth token: {filename}\")\n return False\n except Exception as e:\n logger.error(f\"Error refreshing OAuth token {filename}: {e}\")\n return False\n\n\ndef _refresh_token(filepath: Path, token_data: dict) -> bool:\n \"\"\"\n Refresh a single token based on its type.\n\n Args:\n filepath: Path to the token file\n token_data: Parsed token data\n\n Returns:\n True if refresh successful, False otherwise\n \"\"\"\n filename = filepath.name\n refresh_method = _determine_refresh_method(token_data, filename)\n\n if not refresh_method:\n logger.error(f\"Cannot determine how to refresh {filename}\")\n return False\n\n if refresh_method == \"agentcore\":\n return _refresh_agentcore_token(token_data, filename)\n elif refresh_method == \"oauth\":\n return _refresh_oauth_token(token_data, filename)\n else:\n logger.error(f\"Unknown refresh method: {refresh_method}\")\n return False\n\n\ndef _scan_noauth_services() -> list[dict]:\n \"\"\"\n Scan registry servers and find services with auth_scheme: none.\n\n Returns:\n List of no-auth service configurations\n \"\"\"\n registry_dir = PROJECT_ROOT / \"registry\" / \"servers\"\n noauth_services = []\n\n if not registry_dir.exists():\n logger.warning(f\"Registry servers directory not found: {registry_dir}\")\n return []\n\n logger.debug(f\"Scanning for no-auth services in: {registry_dir}\")\n\n for json_file in registry_dir.glob(\"*.json\"):\n # Skip server_state.json\n if json_file.name == \"server_state.json\":\n continue\n\n try:\n with open(json_file) as f:\n server_config = json.load(f)\n\n # Backward-compatible read: prefer auth_scheme, fall back to auth_type\n auth_scheme = server_config.get(\"auth_scheme\", server_config.get(\"auth_type\", \"none\"))\n if auth_scheme == \"none\":\n # Extract relevant service information\n service = {\n \"server_name\": server_config.get(\"server_name\", \"Unknown\"),\n \"path\": server_config.get(\"path\", \"\"),\n \"proxy_pass_url\": server_config.get(\"proxy_pass_url\", \"\"),\n \"supported_transports\": server_config.get(\n \"supported_transports\", [\"streamable-http\"]\n ),\n \"description\": server_config.get(\"description\", \"\"),\n \"file_name\": json_file.name,\n }\n noauth_services.append(service)\n logger.debug(f\"Found no-auth service: {service['server_name']} ({service['path']})\")\n except (OSError, json.JSONDecodeError) as e:\n logger.warning(f\"Failed to parse {json_file.name}: {e}\")\n continue\n\n return noauth_services\n\n\ndef _regenerate_mcp_configs() -> bool:\n \"\"\"\n Regenerate MCP configuration files (mcp.json and vscode_mcp.json) after token refresh.\n\n Returns:\n True if regeneration successful, False otherwise\n \"\"\"\n logger.info(\"Regenerating MCP configuration files...\")\n\n try:\n # Check for required files\n ingress_file = OAUTH_TOKENS_DIR / \"ingress.json\"\n has_ingress = ingress_file.exists()\n\n # Find all egress token files\n egress_files = []\n for file_path in OAUTH_TOKENS_DIR.glob(\"*-egress.json\"):\n if file_path.is_file():\n egress_files.append(file_path)\n logger.debug(f\"Found egress token file: {file_path.name}\")\n\n # Scan for no-auth services\n noauth_services = _scan_noauth_services()\n logger.info(f\"Found {len(noauth_services)} no-auth services to include\")\n\n if not has_ingress and not egress_files and not noauth_services:\n logger.warning(\n \"No token files or no-auth services found, skipping MCP configuration generation\"\n )\n return True\n\n # Generate both configurations\n vscode_success = _generate_vscode_config(\n has_ingress, ingress_file, egress_files, noauth_services\n )\n roocode_success = _generate_roocode_config(\n has_ingress, ingress_file, egress_files, noauth_services\n )\n\n if vscode_success and roocode_success:\n logger.info(\"MCP configuration files regenerated successfully\")\n return True\n else:\n logger.error(\"Failed to regenerate some MCP configuration files\")\n return False\n\n except Exception as e:\n logger.error(f\"Error regenerating MCP configs: {e}\")\n return False\n\n\ndef _get_ingress_headers(ingress_file: Path) -> dict[str, str]:\n \"\"\"\n Extract ingress authentication headers from token file.\n\n Args:\n ingress_file: Path to ingress token file\n\n Returns:\n Dictionary of ingress headers\n \"\"\"\n headers = {}\n\n # Check AUTH_PROVIDER from environment\n auth_provider = os.environ.get(\"AUTH_PROVIDER\", \"\")\n\n if auth_provider == \"keycloak\":\n # When using Keycloak, get token from agent token file\n agent_token_file = OAUTH_TOKENS_DIR / \"agent-ai-coding-assistant-m2m-token.json\"\n if agent_token_file.exists():\n try:\n with open(agent_token_file) as f:\n agent_data = json.load(f)\n\n if agent_data and agent_data.get(\"access_token\"):\n logger.debug(\"Using Keycloak agent token for ingress authentication\")\n headers = {\"X-Authorization\": f\"Bearer {agent_data.get('access_token', '')}\"}\n\n # Add Keycloak-specific headers\n headers.update(\n {\n \"X-Client-Id\": agent_data.get(\"client_id\", \"\"),\n \"X-Keycloak-Realm\": agent_data.get(\"keycloak_realm\", \"\"),\n \"X-Keycloak-URL\": agent_data.get(\"keycloak_url\", \"\"),\n }\n )\n logger.debug(\n f\"Using Keycloak agent headers: client_id={agent_data.get('client_id', '')}\"\n )\n return headers\n except (OSError, json.JSONDecodeError) as e:\n logger.warning(f\"Failed to read Keycloak agent token file: {e}\")\n\n # Fall back to ingress file if agent token not available\n logger.warning(\"Keycloak agent token not available, falling back to ingress token\")\n\n # Default behavior: use ingress file\n if ingress_file.exists():\n try:\n with open(ingress_file) as f:\n ingress_data = json.load(f)\n\n # Always include the access token\n headers[\"X-Authorization\"] = f\"Bearer {ingress_data.get('access_token', '')}\"\n\n # Add provider-specific headers\n provider = ingress_data.get(\"provider\", \"cognito_m2m\")\n logger.debug(f\"Detected ingress provider: {provider}\")\n\n if provider == \"keycloak_m2m\":\n # Keycloak-specific headers\n headers.update(\n {\n \"X-Client-Id\": ingress_data.get(\"client_id\", \"\"),\n \"X-Keycloak-Realm\": ingress_data.get(\"realm\", \"\"),\n \"X-Keycloak-URL\": ingress_data.get(\"keycloak_url\", \"\"),\n }\n )\n logger.debug(f\"Using Keycloak headers: realm={ingress_data.get('realm', '')}\")\n else: # cognito_m2m (default)\n # Cognito-specific headers\n headers.update(\n {\n \"X-User-Pool-Id\": ingress_data.get(\"user_pool_id\", \"\"),\n \"X-Client-Id\": ingress_data.get(\"client_id\", \"\"),\n \"X-Region\": ingress_data.get(\"region\", \"us-east-1\"),\n }\n )\n logger.debug(\n f\"Using Cognito headers: pool_id={ingress_data.get('user_pool_id', '')}\"\n )\n\n except (OSError, json.JSONDecodeError) as e:\n logger.warning(f\"Failed to read ingress file: {e}\")\n\n return headers\n\n\ndef _create_egress_server_config(\n egress_file: Path,\n ingress_headers: dict[str, str],\n registry_url: str,\n config_type: str = \"vscode\",\n) -> tuple[str, dict]:\n \"\"\"\n Create server configuration from egress token file.\n\n Args:\n egress_file: Path to egress token file\n ingress_headers: Ingress authentication headers\n registry_url: Base registry URL\n config_type: Either \"vscode\" or \"roocode\"\n\n Returns:\n Tuple of (server_key, server_config)\n \"\"\"\n try:\n with open(egress_file) as f:\n egress_data = json.load(f)\n except (OSError, json.JSONDecodeError) as e:\n logger.warning(f\"Failed to read egress file {egress_file.name}: {e}\")\n return None, None\n\n provider = egress_data.get(\"provider\", \"\")\n token = egress_data.get(\"access_token\", \"\")\n cloud_id = egress_data.get(\"cloud_id\", \"\")\n\n # Determine server key and URL\n if provider == \"atlassian\":\n server_key = \"atlassian\"\n headers = {\"Authorization\": f\"Bearer {token}\"}\n if cloud_id:\n headers[\"X-Atlassian-Cloud-Id\"] = cloud_id\n if ingress_headers:\n headers.update(ingress_headers)\n url = f\"{registry_url}/atlassian/mcp\"\n\n elif provider == \"bedrock-agentcore\":\n # Extract server name from filename\n filename = egress_file.name\n if filename.startswith(\"bedrock-agentcore-\") and filename.endswith(\"-egress.json\"):\n server_key = filename.replace(\"bedrock-agentcore-\", \"\").replace(\"-egress.json\", \"\")\n else:\n server_key = \"sre-gateway\"\n\n headers = {\"Authorization\": f\"Bearer {token}\"}\n if ingress_headers:\n headers.update(ingress_headers)\n url = f\"{registry_url}/{server_key}/mcp\"\n\n else:\n # Generic provider\n server_key = provider\n headers = {\"Authorization\": f\"Bearer {token}\"}\n if ingress_headers:\n headers.update(ingress_headers)\n url = f\"{registry_url}/{provider}/mcp\"\n\n # Create config based on type\n if config_type == \"vscode\":\n server_config = {\"url\": url, \"headers\": headers}\n else: # roocode\n server_config = {\n \"type\": \"streamable-http\",\n \"url\": url,\n \"headers\": headers,\n \"disabled\": False,\n \"alwaysAllow\": [],\n }\n\n return server_key, server_config\n\n\ndef _create_noauth_server_config(\n service: dict, ingress_headers: dict[str, str], registry_url: str, config_type: str = \"vscode\"\n) -> tuple[str, dict]:\n \"\"\"\n Create server configuration for no-auth service.\n\n Args:\n service: No-auth service information\n ingress_headers: Ingress authentication headers\n registry_url: Base registry URL\n config_type: Either \"vscode\" or \"roocode\"\n\n Returns:\n Tuple of (server_key, server_config)\n \"\"\"\n # Use path as server key (remove leading and trailing slashes)\n server_key = service[\"path\"].strip(\"/\")\n if not server_key:\n return None, None\n\n # Construct service URL\n path = service[\"path\"].rstrip(\"/\")\n service_url = f\"{registry_url}{path}/mcp\"\n\n # Create config based on type\n if config_type == \"vscode\":\n server_config = {\"url\": service_url}\n if ingress_headers:\n server_config[\"headers\"] = ingress_headers\n else: # roocode\n # Determine transport type\n supported_transports = service.get(\"supported_transports\", [\"streamable-http\"])\n transport_type = supported_transports[0] if supported_transports else \"streamable-http\"\n\n server_config = {\n \"type\": transport_type,\n \"url\": service_url,\n \"disabled\": False,\n \"alwaysAllow\": [],\n }\n if ingress_headers:\n server_config[\"headers\"] = ingress_headers\n\n return server_key, server_config\n\n\ndef _generate_vscode_config(\n has_ingress: bool,\n ingress_file: Path,\n egress_files: list[Path],\n noauth_services: list[dict] = None,\n) -> bool:\n \"\"\"\n Generate VS Code MCP configuration file.\n\n Args:\n has_ingress: Whether ingress token is available\n ingress_file: Path to ingress token file\n egress_files: List of egress token file paths\n noauth_services: List of no-auth service configurations\n\n Returns:\n True if generation successful, False otherwise\n \"\"\"\n config_file = OAUTH_TOKENS_DIR / \"vscode_mcp.json\"\n\n try:\n with tempfile.NamedTemporaryFile(mode=\"w\", delete=False, suffix=\".json\") as temp_file:\n temp_path = temp_file.name\n\n # Default registry URL\n registry_url = os.getenv(\"REGISTRY_URL\", \"https://mcpgateway.ddns.net\")\n\n # Initialize configuration\n config = {\"mcp\": {\"servers\": {}}}\n\n # Get ingress headers\n ingress_headers = _get_ingress_headers(ingress_file) if has_ingress else {}\n\n # Process egress files\n for egress_file in egress_files:\n server_key, server_config = _create_egress_server_config(\n egress_file, ingress_headers, registry_url, \"vscode\"\n )\n if server_key and server_config:\n config[\"mcp\"][\"servers\"][server_key] = server_config\n logger.debug(f\"Added egress service {server_key} to VS Code config\")\n\n # Process no-auth services\n if noauth_services:\n for service in noauth_services:\n server_key, server_config = _create_noauth_server_config(\n service, ingress_headers, registry_url, \"vscode\"\n )\n\n # Skip if already added or invalid\n if not server_key or server_key in config[\"mcp\"][\"servers\"]:\n continue\n\n config[\"mcp\"][\"servers\"][server_key] = server_config\n logger.debug(f\"Added no-auth service {server_key} to VS Code config\")\n\n # Write JSON to temp file\n json.dump(config, temp_file, indent=2)\n\n # Move temp file to final location and set permissions\n os.rename(temp_path, config_file)\n os.chmod(config_file, 0o600)\n\n logger.info(f\"Generated VS Code MCP config: {config_file}\")\n logger.debug(f\"VS Code config written to: {config_file.absolute()}\")\n return True\n\n except Exception as e:\n logger.error(f\"Error generating VS Code MCP config: {e}\")\n if \"temp_path\" in locals():\n try:\n os.unlink(temp_path)\n except Exception as e:\n logger.debug(f\"Failed to clean up temp file: {e}\")\n return False\n\n\ndef _generate_roocode_config(\n has_ingress: bool,\n ingress_file: Path,\n egress_files: list[Path],\n noauth_services: list[dict] = None,\n) -> bool:\n \"\"\"\n Generate Roocode MCP configuration file.\n\n Args:\n has_ingress: Whether ingress token is available\n ingress_file: Path to ingress token file\n egress_files: List of egress token file paths\n noauth_services: List of no-auth service configurations\n\n Returns:\n True if generation successful, False otherwise\n \"\"\"\n config_file = OAUTH_TOKENS_DIR / \"mcp.json\"\n\n try:\n with tempfile.NamedTemporaryFile(mode=\"w\", delete=False, suffix=\".json\") as temp_file:\n temp_path = temp_file.name\n\n # Default registry URL\n registry_url = os.getenv(\"REGISTRY_URL\", \"https://mcpgateway.ddns.net\")\n\n # Initialize configuration\n config = {\"mcpServers\": {}}\n\n # Get ingress headers\n ingress_headers = _get_ingress_headers(ingress_file) if has_ingress else {}\n\n # Process egress files\n for egress_file in egress_files:\n server_key, server_config = _create_egress_server_config(\n egress_file, ingress_headers, registry_url, \"roocode\"\n )\n if server_key and server_config:\n config[\"mcpServers\"][server_key] = server_config\n logger.debug(f\"Added egress service {server_key} to Roocode config\")\n\n # Process no-auth services\n if noauth_services:\n for service in noauth_services:\n server_key, server_config = _create_noauth_server_config(\n service, ingress_headers, registry_url, \"roocode\"\n )\n\n # Skip if already added or invalid\n if not server_key or server_key in config[\"mcpServers\"]:\n continue\n\n config[\"mcpServers\"][server_key] = server_config\n logger.debug(f\"Added no-auth service {server_key} to Roocode config\")\n\n # Write JSON to temp file\n json.dump(config, temp_file, indent=2)\n\n # Move temp file to final location and set permissions\n os.rename(temp_path, config_file)\n os.chmod(config_file, 0o600)\n\n logger.info(f\"Generated Roocode MCP config: {config_file}\")\n logger.debug(f\"Roocode config written to: {config_file.absolute()}\")\n return True\n\n except Exception as e:\n logger.error(f\"Error generating Roocode MCP config: {e}\")\n if \"temp_path\" in locals():\n try:\n os.unlink(temp_path)\n except Exception as e:\n logger.debug(f\"Failed to clean up temp file: {e}\")\n return False\n\n\ndef _run_refresh_cycle(\n buffer_seconds: int = DEFAULT_EXPIRY_BUFFER, force_refresh: bool = False\n) -> None:\n \"\"\"\n Run a single refresh cycle, checking and refreshing expiring tokens.\n\n Args:\n buffer_seconds: Number of seconds before expiry to trigger refresh\n force_refresh: If True, refresh all tokens regardless of expiration\n \"\"\"\n logger.info(\"Starting token refresh cycle...\")\n logger.debug(f\"Token directory: {OAUTH_TOKENS_DIR.absolute()}\")\n\n # Find expiring tokens\n if force_refresh:\n expiring_tokens = _get_all_tokens()\n logger.info(\"Force refresh enabled - will refresh all tokens\")\n else:\n expiring_tokens = _get_expiring_tokens(buffer_seconds)\n\n if not expiring_tokens:\n logger.info(\"No tokens need refreshing\")\n return\n\n logger.info(f\"Found {len(expiring_tokens)} token(s) needing refresh\")\n\n # Refresh each expiring token\n success_count = 0\n for filepath, token_data in expiring_tokens:\n logger.info(f\"Attempting to refresh: {filepath.name}\")\n logger.debug(f\"Processing token file: {filepath.absolute()}\")\n\n if _refresh_token(filepath, token_data):\n success_count += 1\n logger.info(f\"Token successfully updated at: {filepath.absolute()}\")\n else:\n logger.error(f\"Failed to refresh: {filepath.name}\")\n logger.error(f\"Failed token location: {filepath.absolute()}\")\n\n logger.info(\n f\"Refresh cycle complete: {success_count}/{len(expiring_tokens)} tokens refreshed successfully\"\n )\n\n # Regenerate MCP configuration files if any tokens were refreshed\n if success_count > 0:\n logger.info(\"Regenerating MCP configuration files after token refresh...\")\n if _regenerate_mcp_configs():\n logger.info(\"MCP configuration files updated successfully\")\n else:\n logger.error(\"Failed to update MCP configuration files\")\n\n\ndef _get_pidfile_path() -> Path:\n \"\"\"\n Get the path to the PID file for the token refresher service.\n\n Returns:\n Path to the PID file\n \"\"\"\n return PROJECT_ROOT / \"token_refresher.pid\"\n\n\ndef _write_pidfile() -> None:\n \"\"\"\n Write the current process PID to the PID file.\n \"\"\"\n pidfile = _get_pidfile_path()\n with open(pidfile, \"w\") as f:\n f.write(str(os.getpid()))\n logger.debug(f\"PID file written: {pidfile}\")\n\n\ndef _remove_pidfile() -> None:\n \"\"\"\n Remove the PID file if it exists.\n \"\"\"\n pidfile = _get_pidfile_path()\n try:\n if pidfile.exists():\n pidfile.unlink()\n logger.debug(f\"PID file removed: {pidfile}\")\n except Exception as e:\n logger.warning(f\"Failed to remove PID file: {e}\")\n\n\ndef _kill_existing_instance() -> bool:\n \"\"\"\n Kill any existing token refresher instance if running.\n\n Returns:\n True if an existing instance was killed, False if none was found\n \"\"\"\n pidfile = _get_pidfile_path()\n\n if not pidfile.exists():\n logger.debug(\"No PID file found, no existing instance to kill\")\n return False\n\n try:\n with open(pidfile) as f:\n old_pid = int(f.read().strip())\n\n # Check if process exists and is a token refresher\n if psutil.pid_exists(old_pid):\n try:\n process = psutil.Process(old_pid)\n cmdline = \" \".join(process.cmdline())\n\n # Check if it's actually our token refresher process\n if \"token_refresher.py\" in cmdline:\n logger.info(f\"Found existing token refresher instance (PID: {old_pid})\")\n logger.info(f\"Killing existing instance: {cmdline}\")\n\n # Try graceful shutdown first\n process.terminate()\n try:\n process.wait(timeout=5)\n logger.info(f\"Gracefully terminated existing instance (PID: {old_pid})\")\n except psutil.TimeoutExpired:\n # Force kill if graceful shutdown fails\n logger.warning(f\"Graceful shutdown failed, force killing PID: {old_pid}\")\n process.kill()\n process.wait()\n logger.info(f\"Force killed existing instance (PID: {old_pid})\")\n\n return True\n else:\n logger.debug(f\"PID {old_pid} exists but is not a token refresher process\")\n\n except (psutil.NoSuchProcess, psutil.AccessDenied) as e:\n logger.debug(f\"Could not access process {old_pid}: {e}\")\n else:\n logger.debug(f\"PID {old_pid} no longer exists\")\n\n # Clean up stale PID file\n _remove_pidfile()\n return False\n\n except (ValueError, FileNotFoundError) as e:\n logger.debug(f\"Invalid or missing PID file: {e}\")\n _remove_pidfile()\n return False\n except Exception as e:\n logger.error(f\"Error checking for existing instance: {e}\")\n return False\n\n\ndef _setup_signal_handlers() -> None:\n \"\"\"\n Set up signal handlers for graceful shutdown.\n \"\"\"\n\n def signal_handler(signum, frame):\n logger.info(f\"Received signal {signum}, shutting down gracefully...\")\n _remove_pidfile()\n sys.exit(0)\n\n signal.signal(signal.SIGTERM, signal_handler)\n signal.signal(signal.SIGINT, signal_handler)\n\n\ndef main():\n \"\"\"Main entry point for the token refresher service.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"OAuth Token Refresher Service\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n # Run with default settings (check every 5 minutes, refresh 1 hour before expiry)\n uv run python credentials-provider/token_refresher.py\n \n # Check every 10 minutes\n uv run python credentials-provider/token_refresher.py --interval 600\n \n # Refresh tokens 2 hours before expiry\n uv run python credentials-provider/token_refresher.py --buffer 7200\n \n # Run once and exit (for testing)\n uv run python credentials-provider/token_refresher.py --once\n \n # Force refresh all tokens once and exit\n uv run python credentials-provider/token_refresher.py --once --force\n \n # Run in background with logging\n nohup uv run python credentials-provider/token_refresher.py > token_refresher.log 2>&1 &\n\"\"\",\n )\n\n parser.add_argument(\n \"--interval\",\n type=int,\n default=DEFAULT_CHECK_INTERVAL,\n help=f\"Check interval in seconds (default: {DEFAULT_CHECK_INTERVAL})\",\n )\n\n parser.add_argument(\n \"--buffer\",\n type=int,\n default=DEFAULT_EXPIRY_BUFFER,\n help=f\"Refresh tokens this many seconds before expiry (default: {DEFAULT_EXPIRY_BUFFER})\",\n )\n\n parser.add_argument(\"--once\", action=\"store_true\", help=\"Run once and exit (for testing)\")\n\n parser.add_argument(\n \"--force\",\n action=\"store_true\",\n help=\"Force refresh all tokens regardless of expiration status\",\n )\n\n parser.add_argument(\"--debug\", action=\"store_true\", help=\"Enable debug logging\")\n\n parser.add_argument(\n \"--no-kill\",\n action=\"store_true\",\n help=\"Do not kill existing instance (will exit if one is running)\",\n )\n\n args = parser.parse_args()\n\n # Load environment variables from .env file\n _load_env_file()\n\n # Set debug logging if requested\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n # Handle existing instances\n if not args.once: # Only check for existing instances in continuous mode\n if args.no_kill:\n pidfile = _get_pidfile_path()\n if pidfile.exists():\n try:\n with open(pidfile) as f:\n existing_pid = int(f.read().strip())\n if psutil.pid_exists(existing_pid):\n logger.error(\n f\"Another token refresher instance is already running (PID: {existing_pid})\"\n )\n logger.error(\n \"Use --no-kill flag to prevent automatic killing, or stop the existing instance first\"\n )\n sys.exit(1)\n except Exception as e:\n logger.debug(f\"Invalid PID file, continuing: {e}\")\n else:\n # Kill existing instance if found\n killed = _kill_existing_instance()\n if killed:\n logger.info(\"Existing instance terminated, starting new instance\")\n time.sleep(1) # Brief pause to ensure cleanup\n\n logger.info(\"=\" * 60)\n logger.info(\"OAuth Token Refresher Service Starting\")\n logger.info(f\"Check interval: {args.interval} seconds\")\n logger.info(f\"Expiry buffer: {args.buffer} seconds ({args.buffer / 3600:.1f} hours)\")\n logger.info(\"OAuth tokens directory is configured\")\n logger.info(\"=\" * 60)\n\n # Set up signal handlers and PID file for continuous mode\n if not args.once:\n _setup_signal_handlers()\n _write_pidfile()\n\n try:\n # Run once or continuously\n if args.once:\n logger.info(\"Running single refresh cycle...\")\n _run_refresh_cycle(args.buffer, args.force)\n else:\n logger.info(\"Starting continuous monitoring...\")\n while True:\n try:\n _run_refresh_cycle(args.buffer, args.force)\n logger.info(f\"Sleeping for {args.interval} seconds...\")\n time.sleep(args.interval)\n except KeyboardInterrupt:\n logger.info(\"Received interrupt signal, shutting down...\")\n break\n except Exception as e:\n logger.error(f\"Unexpected error in refresh cycle: {e}\")\n logger.info(f\"Continuing after error, sleeping for {args.interval} seconds...\")\n time.sleep(args.interval)\n finally:\n # Clean up PID file\n if not args.once:\n _remove_pidfile()\n\n logger.info(\"Token Refresher Service stopped\")\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "credentials-provider/utils.py", "content": "\"\"\"\nUtility functions for credential providers.\n\"\"\"\n\n\ndef redact_sensitive_value(value: str, show_chars: int = 8) -> str:\n \"\"\"\n Redact sensitive values like tokens, secrets, and passwords.\n\n Args:\n value: The sensitive value to redact\n show_chars: Number of characters to show before redacting (default: 8)\n\n Returns:\n Redacted string showing only first N characters followed by asterisks\n\n Example:\n >>> redact_sensitive_value(\"abc123xyz789\", 8)\n \"abc123xy********\"\n \"\"\"\n if not value or len(value) <= show_chars:\n return \"*\" * len(value) if value else \"\"\n\n return value[:show_chars] + \"*\" * (len(value) - show_chars)\n\n\ndef redact_credentials_in_text(text: str, show_chars: int = 8) -> str:\n \"\"\"\n Redact common credential patterns in text output.\n\n Args:\n text: Text that may contain credentials\n show_chars: Number of characters to show before redacting\n\n Returns:\n Text with credentials redacted\n \"\"\"\n import re\n\n # Patterns to redact (case insensitive)\n patterns = [\n r'(access_token[\"\\s]*[:=][\"\\s]*)([^\"\\s]+)',\n r'(client_secret[\"\\s]*[:=][\"\\s]*)([^\"\\s]+)',\n r'(secret[\"\\s]*[:=][\"\\s]*)([^\"\\s]+)',\n r'(password[\"\\s]*[:=][\"\\s]*)([^\"\\s]+)',\n r'(token[\"\\s]*[:=][\"\\s]*)([^\"\\s]+)',\n ]\n\n result = text\n for pattern in patterns:\n\n def replace_match(match):\n prefix = match.group(1)\n value = match.group(2)\n redacted = redact_sensitive_value(value, show_chars)\n return f\"{prefix}{redacted}\"\n\n result = re.sub(pattern, replace_match, result, flags=re.IGNORECASE)\n\n return result\n" }, { "path": "docker/502.html", "content": "\n\n\n \n \n \n MCP Gateway Registry - Starting Up\n \n\n\n
\n
\n \n \n \n \n
\n

MCP Gateway Registry

\n

\n The registry is starting up and will be available momentarily.\n This page will automatically refresh.\n

\n\n \n\n
\n \n Initializing services...\n
\n\n
\n

The backend services are warming up.

\n

This typically completes within 30-60 seconds.

\n
\n
\n\n \n\n\n" }, { "path": "docker/Dockerfile.auth", "content": "# Auth Dockerfile - multi-stage build for smaller image and better caching\n\n# ===== BUILD STAGE =====\nFROM python:3.14-slim AS builder\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1\n\n# Install build dependencies (only needed for compiling wheels)\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n build-essential \\\n git \\\n && rm -rf /var/lib/apt/lists/*\n\nWORKDIR /app\n\n# Install uv and create venv (rarely changes)\nRUN pip install --no-cache-dir uv && \\\n uv venv .venv --python 3.14\n\n# Copy ONLY the dependency manifest first to leverage Docker layer caching.\n# Dependencies are reinstalled only when pyproject.toml changes, not on every code change.\nCOPY auth_server/pyproject.toml /app/pyproject.toml\n\nRUN . .venv/bin/activate && \\\n uv pip install --requirement pyproject.toml\n\n# ===== RUNTIME STAGE =====\nFROM python:3.14-slim\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1\n\n# Install only runtime system dependencies\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n curl \\\n && rm -rf /var/lib/apt/lists/*\n\nWORKDIR /app\n\n# Copy the pre-built virtual environment from builder\nCOPY --from=builder /app/.venv /app/.venv\n\n# Copy entrypoint script early (rarely changes, avoids cache bust from code changes)\nCOPY docker/auth-entrypoint.sh /app/auth-entrypoint.sh\nRUN chmod +x /app/auth-entrypoint.sh\n\n# Now copy the actual application code (this layer changes frequently but deps are cached above)\nCOPY auth_server/ /app/\nCOPY registry/ /app/registry/\n\n# Create logs and certs directories\nRUN mkdir -p /app/logs && \\\n mkdir -p /app/certs\n\n# Expose port\nEXPOSE 8888\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \\\n CMD curl -f http://localhost:8888/health || exit 1\n\n# Create non-root user for security (CIS Docker Benchmark 4.1)\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\n# Set ownership of application files, venv, logs, certs, and entrypoint\nRUN chown -R appuser:appuser /app /app/.venv /app/logs /app/certs /app/auth-entrypoint.sh\n\n# Switch to non-root user\nUSER appuser\n\n# Start the auth server via entrypoint\nENTRYPOINT [\"/app/auth-entrypoint.sh\"]\n" }, { "path": "docker/Dockerfile.mcp-server", "content": "# Generic MCP Server Dockerfile for servers in the servers/ directory\n# Each server must have pyproject.toml and server.py\n# Build context can be either the server directory or repo root (for servers needing registry module)\nFROM python:3.14-slim\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1 \\\n UV_NO_CACHE=1\n\n# Install system dependencies\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n curl \\\n git \\\n build-essential \\\n netcat-openbsd \\\n && apt-get clean \\\n && rm -rf /var/lib/apt/lists/*\n\n# Create non-root user early (before creating any app files)\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\nWORKDIR /app\n\n# Install uv as root (global tool)\nRUN pip install uv\n\n# Create /app directory with correct ownership from the start\nRUN chown appuser:appuser /app\n\n# Switch to non-root user for all subsequent operations\nUSER appuser\n\n# Setup Python environment as appuser (avoids need to chown .venv later)\nRUN uv venv .venv --python 3.14\n\n# Install CPU-only PyTorch first to avoid GPU dependencies (for sentence-transformers)\nRUN . .venv/bin/activate && \\\n uv pip install --index-url https://download.pytorch.org/whl/cpu \\\n \"torch>=2.0.0\" \\\n \"torchvision\"\n\n# Build arg for server directory (when building from repo root)\nARG SERVER_DIR\n\n# Switch back to root temporarily for COPY operations (Docker requires root for COPY)\nUSER root\n\n# Copy server files - handle both build contexts\n# If SERVER_DIR is set (building from root), copy from that directory\n# Otherwise copy from current context (building from server directory)\nCOPY --chown=appuser:appuser ${SERVER_DIR:-.}/ /app/\n\n# Copy registry module for embeddings support (only when building from root with SERVER_DIR set)\n# This is required for servers that use the embeddings client (like mcpgw)\n# Use a conditional copy that won't fail if registry doesn't exist\nCOPY --chown=root:root . /tmp/build-context/\nRUN if [ -d /tmp/build-context/registry ]; then \\\n cp -r /tmp/build-context/registry /app/registry && \\\n chown -R appuser:appuser /app/registry && \\\n echo \"Registry module copied successfully\"; \\\n else \\\n echo \"Registry module not found in build context (expected for non-mcpgw servers)\"; \\\n fi && \\\n rm -rf /tmp/build-context\n\n# Switch back to appuser for package installation\nUSER appuser\n\n# Install dependencies from pyproject.toml (copied from SERVER_PATH)\nRUN . .venv/bin/activate && \\\n if [ -f /app/pyproject.toml ]; then \\\n uv pip install --requirement /app/pyproject.toml; \\\n fi\n\n# Expose default port (can be overridden by environment variable)\nEXPOSE 8000\n\n# Health check (generic for all MCP servers)\nHEALTHCHECK --interval=500s --timeout=10s --start-period=30s --retries=3 \\\n CMD nc -z localhost ${PORT:-8000} || exit 1\n\n# Switch to root to create entrypoint script\nUSER root\n\n# Create entrypoint script that handles environment setup and runs server.py\nRUN echo '#!/bin/bash\\n\\\nset -e\\n\\\n\\n\\\n# Set default port\\n\\\nSERVER_PORT=${PORT:-8000}\\n\\\n\\n\\\n# Create .env file if needed (for servers that require it)\\n\\\nif [ ! -z \"$POLYGON_API_KEY\" ]; then\\n\\\n echo \"POLYGON_API_KEY=$POLYGON_API_KEY\" > /app/.env\\n\\\nfi\\n\\\n\\n\\\nif [ ! -z \"$REGISTRY_BASE_URL\" ]; then\\n\\\n echo \"REGISTRY_BASE_URL=$REGISTRY_BASE_URL\" > /app/.env\\n\\\nfi\\n\\\n\\n\\\n# Activate virtual environment and run the server\\n\\\nsource .venv/bin/activate\\n\\\nexec python server.py --port $SERVER_PORT' > /entrypoint.sh && \\\n chmod +x /entrypoint.sh && \\\n chown appuser:appuser /entrypoint.sh\n\n# Switch to non-root user for runtime (no chown needed - files already owned by appuser)\nUSER appuser\n\nENTRYPOINT [\"/entrypoint.sh\"] " }, { "path": "docker/Dockerfile.mcp-server-cpu", "content": "# Generic MCP Server Dockerfile - CPU-only PyTorch variant for smaller image size\n# For servers that need sentence-transformers (like mcpgw)\n# Using ECR Public Gallery to avoid Docker Hub rate limits\nFROM public.ecr.aws/docker/library/python:3.14-slim\n\n# Build arg for server directory (when building from repo root)\nARG SERVER_DIR\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1 \\\n UV_NO_CACHE=1\n\n# Install system dependencies\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n curl \\\n git \\\n build-essential \\\n netcat-openbsd \\\n && apt-get clean \\\n && rm -rf /var/lib/apt/lists/*\n\n# Create non-root user early (before creating any app files)\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\nWORKDIR /app\n\n# Install uv as root (global tool)\nRUN pip install uv\n\n# Create /app with correct ownership\nRUN chown appuser:appuser /app\n\n# Switch to appuser for venv creation (avoids need to chown .venv later)\nUSER appuser\n\n# Setup Python environment as appuser\n# Install CPU-only PyTorch FIRST from the CPU wheel index\nRUN uv venv .venv --python 3.14 && \\\n . .venv/bin/activate && \\\n uv pip install torch --index-url https://download.pytorch.org/whl/cpu\n\n# Switch back to root for COPY operations\nUSER root\n\n# Copy server files with correct ownership\nCOPY --chown=appuser:appuser ${SERVER_DIR:-.}/ /app/\n\n# Copy registry module for embeddings support (only when building from root with SERVER_DIR set)\nCOPY --chown=root:root . /tmp/build-context/\nRUN if [ -d /tmp/build-context/registry ]; then \\\n cp -r /tmp/build-context/registry /app/registry && \\\n chown -R appuser:appuser /app/registry && \\\n echo \"Registry module copied successfully\"; \\\n else \\\n echo \"Registry module not found in build context (expected for non-mcpgw servers)\"; \\\n fi && \\\n rm -rf /tmp/build-context\n\n# Switch to appuser for package installation\nUSER appuser\n\n# Install remaining dependencies from pyproject.toml\nRUN . .venv/bin/activate && \\\n if [ -f /app/pyproject.toml ]; then \\\n uv pip install --requirement /app/pyproject.toml; \\\n fi\n\n# Expose default port (can be overridden by environment variable)\nEXPOSE 8000\n\n# Health check (generic for all MCP servers)\nHEALTHCHECK --interval=500s --timeout=10s --start-period=30s --retries=3 \\\n CMD nc -z localhost ${PORT:-8000} || exit 1\n\n# Switch to root to create entrypoint script\nUSER root\n\n# Create entrypoint script\nRUN echo '#!/bin/bash\\n\\\nset -e\\n\\\nSERVER_PORT=${PORT:-8000}\\n\\\nif [ ! -z \"$POLYGON_API_KEY\" ]; then\\n\\\n echo \"POLYGON_API_KEY=$POLYGON_API_KEY\" > /app/.env\\n\\\nfi\\n\\\nif [ ! -z \"$REGISTRY_BASE_URL\" ]; then\\n\\\n echo \"REGISTRY_BASE_URL=$REGISTRY_BASE_URL\" > /app/.env\\n\\\n echo \"REGISTRY_USERNAME=$REGISTRY_USERNAME\" >> /app/.env\\n\\\n echo \"REGISTRY_PASSWORD=$REGISTRY_PASSWORD\" >> /app/.env\\n\\\nfi\\n\\\nsource .venv/bin/activate\\n\\\nexec python server.py --port $SERVER_PORT' > /entrypoint.sh && \\\n chmod +x /entrypoint.sh && \\\n chown appuser:appuser /entrypoint.sh\n\n# Switch to non-root user for runtime (no chown needed - files already owned by appuser)\nUSER appuser\n\nENTRYPOINT [\"/entrypoint.sh\"]\n" }, { "path": "docker/Dockerfile.mcp-server-light", "content": "# Lightweight MCP Server Dockerfile for simple servers in the servers/ directory\n# Each server must have pyproject.toml and server.py\n# Use this for servers that don't need PyTorch or the registry module (e.g., currenttime, fininfo)\n# For servers needing embeddings/sentence-transformers, use Dockerfile.mcp-server instead\nFROM python:3.14-slim\n\n# Build arg for server directory (when building from repo root)\nARG SERVER_DIR\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1 \\\n UV_NO_CACHE=1\n\n# Install minimal system dependencies\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n curl \\\n netcat-openbsd \\\n && apt-get clean \\\n && rm -rf /var/lib/apt/lists/*\n\n# Create non-root user early (before creating any app files)\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\nWORKDIR /app\n\n# Install uv as root (global tool)\nRUN pip install uv\n\n# Create /app with correct ownership\nRUN chown appuser:appuser /app\n\n# Switch to appuser for venv creation (avoids need to chown .venv later)\nUSER appuser\n\n# Setup Python environment as appuser\nRUN uv venv .venv --python 3.14\n\n# Switch back to root for COPY operations\nUSER root\n\n# Copy server files with correct ownership\nCOPY --chown=appuser:appuser ${SERVER_DIR:-.}/ /app/\n\n# Switch to appuser for package installation\nUSER appuser\n\n# Install dependencies from pyproject.toml\nRUN . .venv/bin/activate && \\\n if [ -f /app/pyproject.toml ]; then \\\n uv pip install --requirement /app/pyproject.toml; \\\n fi\n\n# Expose default port (can be overridden by environment variable)\nEXPOSE 8000\n\n# Health check (generic for all MCP servers)\nHEALTHCHECK --interval=500s --timeout=10s --start-period=30s --retries=3 \\\n CMD nc -z localhost ${PORT:-8000} || exit 1\n\n# Switch to root to create entrypoint script\nUSER root\n\n# Create entrypoint script that handles environment setup and runs server.py\nRUN echo '#!/bin/bash\\n\\\nset -e\\n\\\n\\n\\\n# Set default port\\n\\\nSERVER_PORT=${PORT:-8000}\\n\\\n\\n\\\n# Create .env file if needed (for servers that require it)\\n\\\nif [ ! -z \"$POLYGON_API_KEY\" ]; then\\n\\\n echo \"POLYGON_API_KEY=$POLYGON_API_KEY\" > /app/.env\\n\\\nfi\\n\\\n\\n\\\n# Activate virtual environment and run the server\\n\\\nsource .venv/bin/activate\\n\\\nexec python server.py --port $SERVER_PORT' > /entrypoint.sh && \\\n chmod +x /entrypoint.sh && \\\n chown appuser:appuser /entrypoint.sh\n\n# Switch to non-root user for runtime (no chown needed - files already owned by appuser)\nUSER appuser\n\nENTRYPOINT [\"/entrypoint.sh\"]\n" }, { "path": "docker/Dockerfile.metrics-db", "content": "# Pin to specific version for reproducibility\nFROM public.ecr.aws/docker/library/alpine:3.19\n\nENV SQLITE_DB_PATH=/var/lib/sqlite/metrics.db\n\n# Install SQLite as root\nRUN apk add --no-cache sqlite\n\n# Create database directory\nRUN mkdir -p /var/lib/sqlite\n\n# Create non-root user for security (alpine syntax)\nRUN adduser -D -u 1000 appuser && \\\n chown -R appuser:appuser /var/lib/sqlite\n\n# Switch to non-root user\nUSER appuser\n\n# Health check: Verify SQLite database is accessible and functional\nHEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \\\n CMD sqlite3 ${SQLITE_DB_PATH} 'SELECT 1;' || exit 1\n\n# Initialize database and keep container running\nCMD [\"sh\", \"-c\", \"sqlite3 ${SQLITE_DB_PATH} 'CREATE TABLE IF NOT EXISTS _health (id INTEGER);' && tail -f /dev/null\"]\n" }, { "path": "docker/Dockerfile.registry", "content": "# Registry Dockerfile - Multi-stage build with frontend and backend stages\n\n# ===== FRONTEND BUILD STAGE =====\nFROM node:20-slim AS frontend-builder\n\nWORKDIR /app/frontend\n\n# Copy package files and install dependencies (cached unless package files change)\nCOPY frontend/package.json frontend/package-lock.json* ./\nRUN npm install --legacy-peer-deps\n\n# Copy frontend source and build\nCOPY frontend/ ./\nRUN npm run build\n\n# ===== BACKEND BUILD STAGE =====\nFROM python:3.14-slim AS backend-builder\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1 \\\n DEBIAN_FRONTEND=noninteractive\n\n# Install build dependencies\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n build-essential \\\n git \\\n ca-certificates \\\n && rm -rf /var/lib/apt/lists/*\n\nWORKDIR /app\n\n# Install uv and create venv (rarely changes)\nRUN pip install --no-cache-dir uv && \\\n uv venv .venv --python 3.14\n\n# Install CPU-only PyTorch first from the dedicated index (large, rarely changes)\nRUN . .venv/bin/activate && \\\n uv pip install --index-url https://download.pytorch.org/whl/cpu \\\n \"torch>=2.0.0\" \\\n \"torchvision\"\n\n# Copy ONLY the dependency manifest to leverage Docker layer caching.\n# This layer only rebuilds when pyproject.toml changes.\nCOPY pyproject.toml /app/pyproject.toml\n\n# Install all remaining deps from pyproject.toml in one step (no duplicate inline list)\nRUN . .venv/bin/activate && \\\n uv pip install --requirement pyproject.toml\n\n# Copy only the application source directories needed (NOT the entire repo)\nCOPY registry/ /app/registry/\nCOPY auth_server/ /app/auth_server/\nCOPY api/ /app/api/\nCOPY scripts/ /app/scripts/\nCOPY cli/examples/ /app/cli/examples/\n\n# Install the registry package in editable mode\nRUN . .venv/bin/activate && uv pip install -e .\n\n# Copy scopes.yml to /app/config/ to avoid EFS mount overwriting it\nRUN mkdir -p /app/config && cp /app/auth_server/scopes.yml /app/config/scopes.yml\n\n# ===== FINAL RUNTIME STAGE =====\nFROM python:3.14-slim AS runtime\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1 \\\n DEBIAN_FRONTEND=noninteractive\n\n# Build argument for version\nARG BUILD_VERSION=\"1.0.0\"\n\n# Install runtime dependencies including nginx with lua module\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n nginx \\\n nginx-extras \\\n lua-cjson \\\n curl \\\n procps \\\n openssl \\\n ca-certificates \\\n && rm -rf /var/lib/apt/lists/*\n\nWORKDIR /app\n\n# Create non-root user EARLY for security (CIS Docker Benchmark 4.1)\n# This allows us to use --chown in COPY commands, avoiding slow chown -R later\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\n# Copy Python virtual environment from backend builder (large but stable layer)\n# Use --chown to set ownership during copy (much faster than chown -R afterward)\nCOPY --from=backend-builder --chown=appuser:appuser /app/.venv /app/.venv\n\n# Copy pyproject.toml (needed for editable install metadata)\nCOPY --from=backend-builder --chown=appuser:appuser /app/pyproject.toml /app/pyproject.toml\n\n# Copy static config/scripts directly from build context (not via backend-builder)\n# These rarely change and don't depend on the Python build\nCOPY --chown=appuser:appuser docker/nginx_rev_proxy_http_only.conf /app/docker/nginx_rev_proxy_http_only.conf\nCOPY --chown=appuser:appuser docker/nginx_rev_proxy_http_and_https.conf /app/docker/nginx_rev_proxy_http_and_https.conf\nCOPY --chown=appuser:appuser docker/lua/ /app/docker/lua/\n\n# Copy entrypoint early (rarely changes)\nCOPY --chown=appuser:appuser docker/registry-entrypoint.sh /app/registry-entrypoint.sh\nRUN chmod +x /app/registry-entrypoint.sh\n\n# Copy application code from backend builder\nCOPY --from=backend-builder --chown=appuser:appuser /app/registry /app/registry\nCOPY --from=backend-builder --chown=appuser:appuser /app/auth_server /app/auth_server\nCOPY --from=backend-builder --chown=appuser:appuser /app/api /app/api\nCOPY --from=backend-builder --chown=appuser:appuser /app/config /app/config\nCOPY --from=backend-builder --chown=appuser:appuser /app/scripts /app/scripts\nCOPY --from=backend-builder --chown=appuser:appuser /app/cli/examples /app/cli/examples\n\n# Copy built frontend from frontend builder\nCOPY --from=frontend-builder --chown=appuser:appuser /app/frontend/build /app/frontend/build\n\n# Create directories and set ownership\n# Note: /app files already have correct ownership via --chown on COPY commands above.\n# Only chown directories that are created here (not covered by COPY --chown).\nRUN mkdir -p /app/logs && \\\n mkdir -p /app/certs && \\\n mkdir -p /app/security_scans /app/skill_security_scans /app/agent_security_scans && \\\n mkdir -p /etc/nginx/lua/virtual_mappings && \\\n rm -f /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default && \\\n mkdir -p /var/lib/nginx/body /var/lib/nginx/proxy /var/lib/nginx/fastcgi /var/lib/nginx/uwsgi /var/lib/nginx/scgi && \\\n mkdir -p /var/log/nginx && \\\n mkdir -p /run/nginx && \\\n chown -R appuser:appuser /app/logs /app/certs /app/security_scans /app/skill_security_scans /app/agent_security_scans /etc/nginx /var/log/nginx /var/lib/nginx /run/nginx\n\n# Expose ports for nginx (HTTP/HTTPS on high ports for non-root) and registry\nEXPOSE 8080 8443 7860\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \\\n CMD curl -f http://localhost:7860/health || exit 1\n\nARG BUILD_VERSION=\"1.0.0\"\nENV BUILD_VERSION=$BUILD_VERSION\n\n# Switch to non-root user\nUSER appuser\n\nENTRYPOINT [\"/app/registry-entrypoint.sh\"]\n" }, { "path": "docker/Dockerfile.registry-cpu", "content": "# Registry Dockerfile - CPU-only PyTorch variant for smaller image size\n# Using ECR Public Gallery to avoid Docker Hub rate limits\nFROM public.ecr.aws/docker/library/python:3.14-slim\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1 \\\n DEBIAN_FRONTEND=noninteractive\n\n# Install system dependencies including nginx with lua module and Node.js\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n nginx \\\n nginx-extras \\\n lua-cjson \\\n curl \\\n procps \\\n openssl \\\n git \\\n build-essential \\\n ca-certificates \\\n && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \\\n && apt-get install -y nodejs \\\n && apt-get clean \\\n && rm -rf /var/lib/apt/lists/*\n\nWORKDIR /app\n\n# Build argument for version (will be set at build time from git)\nARG BUILD_VERSION=\"1.0.0\"\nENV BUILD_VERSION=$BUILD_VERSION\n\n# Install CPU-only PyTorch first from the CPU wheel index\nRUN pip install uv && \\\n uv venv .venv --python 3.14 && \\\n . .venv/bin/activate && \\\n uv pip install torch --index-url https://download.pytorch.org/whl/cpu && \\\n uv pip install \\\n \"fastapi>=0.115.12\" \\\n \"itsdangerous>=2.2.0\" \\\n \"jinja2>=3.1.6\" \\\n \"mcp>=1.6.0\" \\\n \"pydantic>=2.11.3\" \\\n \"httpx>=0.27.0\" \\\n \"python-dotenv>=1.1.0\" \\\n \"python-multipart>=0.0.20\" \\\n \"uvicorn[standard]>=0.34.2\" \\\n \"faiss-cpu>=1.7.4\" \\\n \"sentence-transformers>=2.2.2\" \\\n \"websockets>=15.0.1\" \\\n \"scikit-learn>=1.3.0\" \\\n \"huggingface-hub[cli,hf_xet]>=0.31.1\" \\\n \"hf_xet>=0.1.0\" \\\n \"cisco-ai-mcp-scanner==3.2.3\" \\\n \"cryptography>=40.0.0\"\n\n# Copy the application code\nCOPY . /app/\n\n# Copy nginx configurations (both HTTP-only and HTTP+HTTPS versions)\nCOPY docker/nginx_rev_proxy_http_only.conf /app/docker/nginx_rev_proxy_http_only.conf\nCOPY docker/nginx_rev_proxy_http_and_https.conf /app/docker/nginx_rev_proxy_http_and_https.conf\n\n# Build React frontend\nWORKDIR /app/frontend\nCOPY frontend/package.json ./\nRUN npm install --legacy-peer-deps\nCOPY frontend/ ./\nRUN npm run build\n\n# Return to app directory\nWORKDIR /app\n\n# Install the registry package\nRUN . .venv/bin/activate && uv pip install -e .\n\n# Download the sentence-transformers embeddings model during build\n# This adds ~90MB to the image but eliminates runtime download requirement\nRUN mkdir -p /app/registry/models && \\\n . .venv/bin/activate && \\\n python -c \"from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2').save('/app/registry/models/all-MiniLM-L6-v2')\"\n\n# Create logs and certs directories\nRUN mkdir -p /app/logs && \\\n mkdir -p /app/certs && \\\n mkdir -p /app/security_scans\n\n# Create nginx lua directories and remove default sites (needed by entrypoint script)\nRUN mkdir -p /etc/nginx/lua/virtual_mappings && \\\n rm -f /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default && \\\n mkdir -p /var/lib/nginx/body /var/lib/nginx/proxy /var/lib/nginx/fastcgi /var/lib/nginx/uwsgi /var/lib/nginx/scgi && \\\n mkdir -p /var/log/nginx && \\\n mkdir -p /run/nginx\n\n# Expose ports for nginx (HTTP/HTTPS on high ports for non-root) and registry\nEXPOSE 8080 8443 7860\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \\\n CMD curl -f http://localhost:7860/health || exit 1\n\n# Entrypoint script\nCOPY docker/registry-entrypoint.sh /app/registry-entrypoint.sh\nRUN chmod +x /app/registry-entrypoint.sh\n\n# Create non-root user for security (CIS Docker Benchmark 4.1)\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\n# Set ownership for runtime-writable directories and entrypoint\n# Note: Use targeted chown instead of chown -R /app to avoid slow recursive\n# ownership change on .venv (thousands of files that don't need write access)\nRUN chown -R appuser:appuser /app/logs /app/certs /app/security_scans /app/registry /etc/nginx /var/log/nginx /var/lib/nginx /run/nginx && \\\n chown appuser:appuser /app /app/registry-entrypoint.sh\n\n# Switch to non-root user\nUSER appuser\n\nENTRYPOINT [\"/app/registry-entrypoint.sh\"]\n" }, { "path": "docker/Dockerfile.scopes-init", "content": "# Pin to specific version for reproducibility (Security best practice)\nFROM public.ecr.aws/docker/library/busybox:1.36\n\n# Copy scopes.yml into the container\nCOPY auth_server/scopes.yml /scopes.yml\n\n# Create a script to copy the file to the mount point\nRUN printf '#!/bin/sh\\nset -e\\n\\necho \"Starting scopes.yml initialization...\"\\necho \"Source file: /scopes.yml\"\\necho \"Destination: /mnt/scopes.yml\"\\n\\nif [ ! -f /scopes.yml ]; then\\n echo \"ERROR: /scopes.yml not found!\"\\n exit 1\\nfi\\n\\nif [ ! -w /mnt ]; then\\n echo \"ERROR: /mnt is not writable!\"\\n ls -la /mnt\\n exit 1\\nfi\\n\\ncp /scopes.yml /mnt/scopes.yml\\n\\nif [ ! -f /mnt/scopes.yml ]; then\\n echo \"ERROR: Failed to copy scopes.yml to /mnt/\"\\n exit 1\\nfi\\n\\nchmod 644 /mnt/scopes.yml\\n\\necho \"Successfully copied scopes.yml to EFS mount\"\\necho \"File size: $(wc -c < /mnt/scopes.yml) bytes\"\\necho \"Scopes initialization complete!\"\\n' > /copy-scopes.sh && chmod +x /copy-scopes.sh\n\n# Create non-root user for security (busybox syntax)\nRUN adduser -D -u 1000 appuser && \\\n chown appuser:appuser /scopes.yml /copy-scopes.sh\n\nWORKDIR /\n\n# Switch to non-root user\nUSER appuser\n\nENTRYPOINT [\"/copy-scopes.sh\"]\n" }, { "path": "docker/auth-entrypoint.sh", "content": "#!/bin/bash\nset -e # Exit immediately if a command exits with a non-zero status.\n\necho \"Starting Auth Server Setup...\"\n\n# --- DocumentDB CA Bundle Download ---\nif [[ \"${DOCUMENTDB_HOST}\" == *\"docdb-elastic.amazonaws.com\"* ]]; then\n echo \"Detected DocumentDB Elastic cluster\"\n echo \"Downloading DocumentDB Elastic CA bundle...\"\n CA_BUNDLE_URL=\"https://www.amazontrust.com/repository/SFSRootCAG2.pem\"\n CA_BUNDLE_PATH=\"/app/certs/global-bundle.pem\"\n if [ ! -f \"$CA_BUNDLE_PATH\" ]; then\n curl -fsSL \"$CA_BUNDLE_URL\" -o \"$CA_BUNDLE_PATH\"\n echo \"DocumentDB Elastic CA bundle (SFSRootCAG2.pem) downloaded successfully to $CA_BUNDLE_PATH\"\n fi\nelif [[ \"${DOCUMENTDB_HOST}\" == *\"docdb.amazonaws.com\"* ]]; then\n echo \"Detected regular DocumentDB cluster\"\n echo \"Downloading regular DocumentDB CA bundle...\"\n CA_BUNDLE_URL=\"https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem\"\n CA_BUNDLE_PATH=\"/app/certs/global-bundle.pem\"\n if [ ! -f \"$CA_BUNDLE_PATH\" ]; then\n curl -fsSL \"$CA_BUNDLE_URL\" -o \"$CA_BUNDLE_PATH\"\n echo \"DocumentDB CA bundle (global-bundle.pem) downloaded successfully to $CA_BUNDLE_PATH\"\n fi\nelse\n echo \"No DocumentDB host detected or DOCUMENTDB_HOST is empty - skipping CA bundle download\"\nfi\n\n# --- Wait for MongoDB Replica Set ---\nif [ -n \"$DOCUMENTDB_HOST\" ]; then\n echo \"Waiting for MongoDB replica set at ${DOCUMENTDB_HOST}:${DOCUMENTDB_PORT:-27017}...\"\n source /app/.venv/bin/activate\n python3 -c \"\nimport pymongo, os, time, sys\nhost = os.getenv('DOCUMENTDB_HOST', 'mongodb')\nport = int(os.getenv('DOCUMENTDB_PORT', '27017'))\nuser = os.getenv('DOCUMENTDB_USERNAME', '')\npwd = os.getenv('DOCUMENTDB_PASSWORD', '')\nbackend = os.getenv('STORAGE_BACKEND', 'mongodb-ce')\nuse_tls = os.getenv('DOCUMENTDB_USE_TLS', 'true').lower() == 'true'\nca_file = os.getenv('DOCUMENTDB_TLS_CA_FILE', '/app/certs/global-bundle.pem')\nauth = 'SCRAM-SHA-256' if backend == 'mongodb-ce' else 'SCRAM-SHA-1'\nif user and pwd:\n uri = f'mongodb://{user}:{pwd}@{host}:{port}/?authMechanism={auth}&authSource=admin'\nelse:\n uri = f'mongodb://{host}:{port}/'\n# Prepare TLS options\ntls_options = {}\nif use_tls:\n tls_options['tls'] = True\n tls_options['tlsCAFile'] = ca_file\nwhile True:\n try:\n c = pymongo.MongoClient(uri, serverSelectionTimeoutMS=5000, connectTimeoutMS=5000, **tls_options)\n c.admin.command('ping')\n try:\n st = c.admin.command('replSetGetStatus')\n ready = [m for m in st['members'] if m['state'] in [1, 2]]\n total = len(st['members'])\n if st['ok'] == 1 and len(ready) == total:\n print(f'MongoDB replica set ready ({len(ready)}/{total} members)')\n c.close()\n break\n print(f'Waiting for replica set: {len(ready)}/{total} ready')\n except pymongo.errors.OperationFailure:\n # Standalone mode (no replica set) - ping succeeded so we're good\n print('MongoDB is ready (standalone mode)')\n c.close()\n break\n except Exception as e:\n print(f'MongoDB not ready yet: {e}')\n time.sleep(5)\n\"\n deactivate\n echo \"MongoDB is ready.\"\nfi\n\necho \"Starting Auth Server...\"\ncd /app\nsource .venv/bin/activate\nexec uvicorn server:app --host 0.0.0.0 --port 8888 --proxy-headers --forwarded-allow-ips='*'\n" }, { "path": "docker/keycloak/Dockerfile", "content": "FROM quay.io/keycloak/keycloak:23.0 as builder\n\nENV KC_HEALTH_ENABLED=true\nENV KC_METRICS_ENABLED=true\nENV KC_FEATURES=token-exchange\nENV KC_DB=mysql\n\nWORKDIR /opt/keycloak\n\nRUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname \"CN=server\" -alias server -ext \"SAN:c=DNS:localhost,IP:127.0.0.1\" -keystore conf/server.keystore\nRUN /opt/keycloak/bin/kc.sh build\n\nFROM quay.io/keycloak/keycloak:23.0\n\nCOPY --from=builder /opt/keycloak/ /opt/keycloak/\n\nWORKDIR /opt/keycloak\n\n# Health check for keycloak ready endpoint\nHEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \\\n CMD curl -f http://localhost:8080/health/ready || exit 1\n\n# Switch to keycloak user (provided by base image, UID 1000)\nUSER keycloak\n\n# configuring email listener to send emails for specific events\nENTRYPOINT [\"/opt/keycloak/bin/kc.sh\", \"start\", \"--optimized\"]" }, { "path": "docker/lua/capture_body.lua", "content": "-- capture_body.lua: Read request body and encode it in X-Body header for auth_request\nlocal cjson = require \"cjson\"\n\n-- Read the request body\nngx.req.read_body()\nlocal body_data = ngx.req.get_body_data()\n\nif body_data then\n -- Strip newlines to prevent breaking HTTP header format\n -- (JSON whitespace is insignificant per RFC 8259, so this is safe)\n local clean_body = body_data:gsub(\"[\\r\\n]+\", \" \")\n -- Set the X-Body header with the cleaned body data\n ngx.req.set_header(\"X-Body\", clean_body)\n ngx.log(ngx.INFO, \"Captured request body (\" .. string.len(body_data) .. \" bytes) for auth validation\")\nelse\n ngx.log(ngx.INFO, \"No request body found\")\nend\n" }, { "path": "docker/lua/emit_metrics.lua", "content": "-- emit_metrics.lua: Capture MCP request metrics in log_by_lua phase (no network I/O)\nlocal ok, cjson = pcall(require, \"cjson\")\nif not ok then return end\n\nlocal metrics = ngx.shared.metrics_buffer\nif not metrics then return end\n\n-- Skip buffering when no collector is configured (avoids pointless writes that TTL-expire)\nlocal metrics_url = os.getenv(\"METRICS_SERVICE_URL\") or \"\"\nif metrics_url == \"\" then return end\n\n-- Extract server name from first URI path segment: //...\nlocal server_name = ngx.var.uri:match(\"^/([^/]+)/\")\nif not server_name then return end\n\n-- Parse JSON-RPC body from X-Body header (set by capture_body.lua in rewrite phase)\nlocal method = \"unknown\"\nlocal tool_name = \"\"\nlocal body = ngx.req.get_headers()[\"X-Body\"]\nif body then\n local dok, parsed = pcall(cjson.decode, body)\n if dok and parsed.method then\n method = parsed.method\n if method == \"tools/call\" and parsed.params and parsed.params.name then\n tool_name = parsed.params.name\n end\n end\nend\n\nlocal entry = cjson.encode({\n m = method,\n s = server_name,\n t = tool_name,\n c = ngx.req.get_headers()[\"X-Client-Name\"] or \"unknown\",\n ok = ngx.status < 400,\n d = (tonumber(ngx.var.upstream_header_time) or tonumber(ngx.var.request_time) or 0) * 1000,\n})\n\nlocal key = \"m:\" .. ngx.now() .. \":\" .. ngx.worker.pid() .. \":\" .. math.random(1, 999999)\nlocal set_ok, set_err = metrics:set(key, entry, 300)\nif not set_ok then\n ngx.log(ngx.ERR, \"metrics emit: shared dict full, dropping metric: \", set_err)\nend\n" }, { "path": "docker/lua/flush_metrics.lua", "content": "-- flush_metrics.lua: Background timer flushes shared dict buffer to collector endpoint\nlocal ok, cjson = pcall(require, \"cjson\")\nif not ok then return end\n\nlocal api_key = os.getenv(\"METRICS_API_KEY\") or \"\"\nlocal metrics_url = os.getenv(\"METRICS_SERVICE_URL\") or \"\"\n\nif metrics_url == \"\" then\n ngx.log(ngx.WARN, \"metrics flush: DISABLED (METRICS_SERVICE_URL not set)\")\n return\nend\n\n-- Only http:// is supported (raw TCP cosocket, no TLS)\nif metrics_url:sub(1, 8) == \"https://\" then\n ngx.log(ngx.ERR, \"metrics flush: DISABLED -- METRICS_SERVICE_URL uses https:// which is not supported (use http:// for internal service-to-service)\")\n return\nend\n\nif api_key == \"\" then\n ngx.log(ngx.WARN, \"metrics flush: METRICS_API_KEY not set, requests may be rejected by metrics-service\")\nend\n\nlocal host, port = metrics_url:match(\"http://([^:/]+):?(%d*)\")\nport = tonumber(port) or 80\n\nlocal function flush()\n local buf = ngx.shared.metrics_buffer\n if not buf then return end\n\n local keys = buf:get_keys(1024)\n if #keys == 0 then return end\n if #keys == 1024 then\n ngx.log(ngx.WARN, \"metrics flush: buffer at capacity (1024 keys), some metrics may be lost\")\n end\n\n local batch = {}\n local to_delete = {}\n for _, key in ipairs(keys) do\n if key:sub(1, 2) == \"m:\" then\n local val = buf:get(key)\n if val then\n local dok, e = pcall(cjson.decode, val)\n if dok then\n batch[#batch + 1] = {\n type = \"tool_execution\",\n value = 1.0,\n duration_ms = e.d,\n dimensions = {\n method = e.m,\n server_name = e.s,\n tool_name = e.t,\n client_name = e.c,\n success = tostring(e.ok),\n },\n metadata = {},\n }\n to_delete[#to_delete + 1] = key\n end\n end\n end\n end\n\n if #batch == 0 then return end\n\n local payload = cjson.encode({\n service = \"nginx\",\n version = \"1.0.0\",\n metrics = batch,\n })\n\n local sock = ngx.socket.tcp()\n sock:settimeout(5000)\n local conn_ok, err = sock:connect(host, port)\n if not conn_ok then\n ngx.log(ngx.ERR, \"metrics flush: connect failed: \", err)\n return\n end\n\n local req = \"POST /metrics HTTP/1.1\\r\\n\"\n .. \"Host: \" .. host .. \"\\r\\n\"\n .. \"Content-Type: application/json\\r\\n\"\n .. \"X-API-Key: \" .. api_key .. \"\\r\\n\"\n .. \"Content-Length: \" .. #payload .. \"\\r\\n\"\n .. \"Connection: close\\r\\n\\r\\n\"\n .. payload\n\n local send_ok, err = sock:send(req)\n if not send_ok then\n ngx.log(ngx.ERR, \"metrics flush: send failed: \", err)\n sock:close()\n return\n end\n\n local line = sock:receive(\"*l\")\n sock:close()\n\n if line and line:match(\"200\") then\n for _, key in ipairs(to_delete) do\n buf:delete(key)\n end\n if #batch > 1 then\n ngx.log(ngx.INFO, \"metrics flush: sent \", #batch, \" metrics\")\n end\n else\n ngx.log(ngx.ERR, \"metrics flush: bad response: \", line or \"nil\")\n end\nend\n\nlocal function schedule()\n local ok, err = ngx.timer.every(5, function(premature)\n if premature then return end\n local pok, perr = pcall(flush)\n if not pok then\n ngx.log(ngx.ERR, \"metrics flush error: \", perr)\n end\n end)\n if not ok then\n ngx.log(ngx.ERR, \"metrics flush: failed to create timer: \", err)\n end\nend\n\nif ngx.worker.id() == 0 then\n ngx.log(ngx.WARN, \"metrics flush: starting on worker 0, host=\", host, \" port=\", port, \" api_key_len=\", #api_key)\n schedule()\nend\n" }, { "path": "docker/lua/virtual_router.lua", "content": "-- virtual_router.lua: JSON-RPC router for Virtual MCP Servers\n-- Routes tools/list, tools/call, resources/list, resources/read,\n-- prompts/list, prompts/get, ping, and initialize requests to the correct backend.\n-- Implements per-client session management with two-tier cache:\n-- L1: ngx.shared.virtual_server_map (30s TTL, per-worker fast path)\n-- L2: MongoDB via /_internal/sessions/ FastAPI endpoints\nlocal cjson = require \"cjson\"\n\n-- Ensure empty Lua tables serialize as JSON arrays [] not objects {}\nlocal empty_array_mt = cjson.empty_array_mt\n\n-- Extract JSON from an SSE-formatted response body.\n-- SSE format: \"event: message\\ndata: {json}\\n\\n\"\n-- If the body is already raw JSON, return it as-is.\nlocal function _parse_sse_body(body)\n if not body or body == \"\" then\n return nil\n end\n -- If it starts with '{' or '[', it's already raw JSON\n local first_char = string.sub(body, 1, 1)\n if first_char == \"{\" or first_char == \"[\" then\n return body\n end\n -- Extract the last \"data: \" line (SSE format)\n local json_data = nil\n for line in string.gmatch(body, \"[^\\r\\n]+\") do\n local data = string.match(line, \"^data:%s*(.+)\")\n if data then\n json_data = data\n end\n end\n return json_data\nend\n\n\n-- Force a table to serialize as a JSON array (handles empty tables -> [] not {})\nlocal function _as_json_array(t)\n if type(t) ~= \"table\" then\n if cjson.empty_array then return cjson.empty_array end\n return setmetatable({}, empty_array_mt)\n end\n if next(t) == nil then\n if cjson.empty_array then return cjson.empty_array end\n end\n return setmetatable(t, empty_array_mt)\nend\n\nlocal _M = {}\n\n-- Shared dict for L1 session cache and mapping cache\nlocal session_cache = ngx.shared.virtual_server_map\n\n-- Cache TTL constants\nlocal MAPPING_CACHE_TTL = 10\nlocal SESSION_CACHE_TTL = 30\nlocal ENRICHED_CACHE_TTL = 60\n\n-- Supported MCP protocol versions (newest first for negotiation)\nlocal SUPPORTED_PROTOCOL_VERSIONS = {\n [\"2025-11-25\"] = true,\n [\"2025-06-18\"] = true,\n [\"2025-03-26\"] = true,\n [\"2024-11-05\"] = true,\n}\nlocal LATEST_PROTOCOL_VERSION = \"2025-11-25\"\n\n\n-- Ensure inputSchema has \"type\": \"object\" as required by MCP spec\nlocal function _ensure_mcp_schema(schema)\n if not schema or type(schema) ~= \"table\" then\n return { type = \"object\", properties = {} }\n end\n if schema.type == \"object\" then\n return schema\n end\n if not schema.type then\n schema.type = \"object\"\n return schema\n end\n -- Non-object type: wrap it\n return { type = \"object\", properties = { value = schema } }\nend\n\n\n-- Read and cache virtual server mapping from JSON file\nlocal function _get_mapping(server_id)\n local cache_key = \"mapping:\" .. server_id\n local cached = session_cache:get(cache_key)\n if cached then\n local ok, mapping = pcall(cjson.decode, cached)\n if ok then\n return mapping\n end\n ngx.log(ngx.WARN, \"Failed to decode cached mapping for server_id=\", server_id)\n end\n\n -- Read from file\n local path = \"/etc/nginx/lua/virtual_mappings/\" .. server_id .. \".json\"\n local f, err = io.open(path, \"r\")\n if not f then\n ngx.log(ngx.ERR, \"Could not open mapping file: \", path, \" error: \", tostring(err))\n return nil\n end\n\n local content = f:read(\"*a\")\n f:close()\n\n local ok, mapping = pcall(cjson.decode, content)\n if not ok then\n ngx.log(ngx.ERR, \"Failed to parse mapping JSON for server_id=\", server_id)\n return nil\n end\n\n -- Cache in shared dict (TTL 10 seconds to reduce stale data after reload)\n session_cache:set(cache_key, content, MAPPING_CACHE_TTL)\n\n return mapping\nend\n\n\n-- Build a JSON-RPC error response\nlocal function _jsonrpc_error(id, code, message)\n return cjson.encode({\n jsonrpc = \"2.0\",\n id = id,\n error = {\n code = code,\n message = message,\n },\n })\nend\n\n\n-- Build a JSON-RPC success response\nlocal function _jsonrpc_result(id, result)\n return cjson.encode({\n jsonrpc = \"2.0\",\n id = id,\n result = result,\n })\nend\n\n\n-- Check if user scopes satisfy required scopes\nlocal function _has_scopes(user_scopes_str, required_scopes)\n if not required_scopes or #required_scopes == 0 then\n return true\n end\n if not user_scopes_str or user_scopes_str == \"\" then\n return false\n end\n\n -- Parse space-separated scopes into a set\n local user_scopes = {}\n for scope in string.gmatch(user_scopes_str, \"%S+\") do\n user_scopes[scope] = true\n end\n\n -- Check all required scopes are present\n for _, required in ipairs(required_scopes) do\n if not user_scopes[required] then\n return false\n end\n end\n return true\nend\n\n\n-- Initialize a backend MCP server and extract its session ID\nlocal function _initialize_backend(backend_location)\n local init_body = cjson.encode({\n jsonrpc = \"2.0\",\n id = \"init-\" .. (ngx.var.request_id or \"0\"),\n method = \"initialize\",\n params = {\n protocolVersion = LATEST_PROTOCOL_VERSION,\n capabilities = {},\n clientInfo = {\n name = \"mcp-gateway-virtual-router\",\n version = \"1.0.0\",\n },\n },\n })\n\n -- Clear the client's Mcp-Session-Id so the backend sees a fresh\n -- initialize request instead of trying to resume a vs-* session.\n ngx.req.set_header(\"Mcp-Session-Id\", \"\")\n -- MCP spec requires Accept header listing both content types\n ngx.req.set_header(\"Accept\", \"application/json, text/event-stream\")\n\n local res = ngx.location.capture(backend_location, {\n method = ngx.HTTP_POST,\n body = init_body,\n })\n\n if not res or res.status ~= 200 then\n ngx.log(ngx.ERR, \"Backend initialize failed for \", backend_location,\n \" status=\", res and res.status or \"nil\")\n return nil\n end\n\n -- Extract Mcp-Session-Id from backend response headers\n local backend_session_id = nil\n if res.header then\n backend_session_id = res.header[\"Mcp-Session-Id\"] or res.header[\"mcp-session-id\"]\n end\n\n return backend_session_id\nend\n\n\n-- Get or create a backend session for a given client session + backend location.\n-- Two-tier cache: L1 shared dict (30s) -> L2 MongoDB -> initialize backend\nlocal function _get_backend_session(client_session_id, backend_location, server_id)\n local session_key = client_session_id .. \":\" .. backend_location\n local cache_key = \"bsess:\" .. session_key\n\n -- L1: shared dict fast path\n local session_id = session_cache:get(cache_key)\n if session_id then\n return session_id\n end\n\n -- L2: MongoDB via internal FastAPI API\n local res = ngx.location.capture(\"/_internal/sessions/backend/\" .. session_key, {\n method = ngx.HTTP_GET,\n })\n if res and res.status == 200 then\n local ok, data = pcall(cjson.decode, res.body)\n if ok and data.backend_session_id then\n -- Populate L1 cache\n session_cache:set(cache_key, data.backend_session_id, SESSION_CACHE_TTL)\n return data.backend_session_id\n end\n end\n\n -- L2 miss: initialize the backend to get a session\n ngx.log(ngx.INFO, \"Initializing backend session for \", session_key)\n session_id = _initialize_backend(backend_location)\n\n if session_id then\n -- Store in L2 (MongoDB)\n local user_id = ngx.var.auth_user or ngx.var.auth_username or \"anonymous\"\n local store_body = cjson.encode({\n backend_session_id = session_id,\n client_session_id = client_session_id,\n user_id = user_id,\n virtual_server_path = \"/virtual/\" .. server_id,\n })\n ngx.location.capture(\"/_internal/sessions/backend/\" .. session_key, {\n method = ngx.HTTP_PUT,\n body = store_body,\n })\n -- Populate L1 cache\n session_cache:set(cache_key, session_id, SESSION_CACHE_TTL)\n end\n\n return session_id\nend\n\n\n-- Invalidate a backend session from both L1 and L2 caches\nlocal function _invalidate_backend_session(client_session_id, backend_location)\n local session_key = client_session_id .. \":\" .. backend_location\n local cache_key = \"bsess:\" .. session_key\n\n -- Remove from L1\n session_cache:delete(cache_key)\n\n -- Remove from L2\n ngx.location.capture(\"/_internal/sessions/backend/\" .. session_key, {\n method = ngx.HTTP_DELETE,\n })\nend\n\n\n-- Collect unique backend locations from a mapping's tools array\nlocal function _collect_backend_locations(mapping)\n local locations = {}\n local seen = {}\n\n if mapping.tools then\n for _, tool in ipairs(mapping.tools) do\n local loc = tool.backend_location\n if loc and not seen[loc] then\n seen[loc] = true\n locations[#locations + 1] = loc\n end\n end\n end\n\n return locations\nend\n\n\n-- Fetch tools/list from a single backend via ngx.location.capture.\n-- Returns the tools array from the backend, or empty table on failure.\n-- On stale session error (status >= 400), invalidates and retries once.\nlocal function _fetch_backend_tools_list(backend_location, client_session_id, server_id)\n local req_body = cjson.encode({\n jsonrpc = \"2.0\",\n id = \"tl-\" .. (ngx.var.request_id or \"0\"),\n method = \"tools/list\",\n params = {},\n })\n\n -- Get backend session\n local backend_session_id = nil\n if client_session_id then\n backend_session_id = _get_backend_session(client_session_id, backend_location, server_id)\n end\n\n if backend_session_id then\n ngx.req.set_header(\"Mcp-Session-Id\", backend_session_id)\n else\n ngx.req.set_header(\"Mcp-Session-Id\", \"\")\n end\n\n local res = ngx.location.capture(backend_location, {\n method = ngx.HTTP_POST,\n body = req_body,\n })\n\n -- Stale session retry\n if res and res.status >= 400 and client_session_id and backend_session_id then\n ngx.log(ngx.WARN, \"Backend tools/list returned \", res.status,\n \" for \", backend_location, \" -- retrying with fresh session\")\n _invalidate_backend_session(client_session_id, backend_location)\n local new_session_id = _get_backend_session(client_session_id, backend_location, server_id)\n if new_session_id then\n ngx.req.set_header(\"Mcp-Session-Id\", new_session_id)\n else\n ngx.req.set_header(\"Mcp-Session-Id\", \"\")\n end\n res = ngx.location.capture(backend_location, {\n method = ngx.HTTP_POST,\n body = req_body,\n })\n end\n\n if not res or res.status ~= 200 then\n ngx.log(ngx.ERR, \"Failed to fetch tools/list from \", backend_location,\n \" status=\", res and res.status or \"nil\")\n return {}\n end\n\n -- Backend may respond with SSE format (text/event-stream) or raw JSON\n local json_body = _parse_sse_body(res.body)\n if not json_body then\n ngx.log(ngx.ERR, \"Empty or unparseable tools/list response from \", backend_location)\n return {}\n end\n\n local ok, data = pcall(cjson.decode, json_body)\n if not ok then\n ngx.log(ngx.ERR, \"Failed to parse tools/list response from \", backend_location)\n return {}\n end\n\n if data.result and data.result.tools then\n return data.result.tools\n end\n\n return {}\nend\n\n\n-- Handle tools/list method - proxy to backends for full metadata, with cache\nlocal function _handle_tools_list(request_id, mapping, user_scopes_str, client_session_id, server_id)\n -- Enforce server-level required_scopes before processing\n if not _has_scopes(user_scopes_str, mapping.required_scopes) then\n return _jsonrpc_error(request_id, -32603, \"Access denied: missing required server scopes\")\n end\n\n -- Build a set of allowed tools from the mapping (display_name -> mapping entry)\n local allowed_tools = {}\n if mapping.tools then\n for _, tool in ipairs(mapping.tools) do\n allowed_tools[tool.original_name or tool.name] = tool\n end\n end\n\n -- L1 cache check: enriched tools for this server\n local enriched_tools = nil\n local enriched_cache_key = \"tools_enriched:\" .. (server_id or \"unknown\")\n local cached_enriched = session_cache:get(enriched_cache_key)\n if cached_enriched then\n local ok, cached = pcall(cjson.decode, cached_enriched)\n if ok then\n enriched_tools = cached\n end\n end\n\n -- On cache miss, fetch from backends\n if not enriched_tools then\n enriched_tools = {}\n local backend_locations = _collect_backend_locations(mapping)\n local fetch_ok = false\n\n for _, backend_loc in ipairs(backend_locations) do\n local backend_tools = _fetch_backend_tools_list(backend_loc, client_session_id, server_id)\n if #backend_tools > 0 then\n fetch_ok = true\n end\n\n for _, bt in ipairs(backend_tools) do\n local mapping_entry = allowed_tools[bt.name]\n if mapping_entry then\n -- Use the mapping's display name (alias) instead of original name\n local display_name = mapping_entry.name\n -- Use mapping's description if non-empty (override), else backend's\n local desc = mapping_entry.description\n if not desc or desc == \"\" then\n desc = bt.description or \"\"\n end\n enriched_tools[#enriched_tools + 1] = {\n name = display_name,\n description = desc,\n inputSchema = _ensure_mcp_schema(bt.inputSchema or bt.input_schema),\n required_scopes = mapping_entry.required_scopes,\n }\n end\n end\n end\n\n -- Fallback: if all backend fetches failed, use mapping file metadata\n if not fetch_ok then\n ngx.log(ngx.WARN, \"All backend tools/list fetches failed for server=\", server_id,\n \" -- falling back to mapping file metadata\")\n enriched_tools = {}\n if mapping.tools then\n for _, tool in ipairs(mapping.tools) do\n enriched_tools[#enriched_tools + 1] = {\n name = tool.name,\n description = tool.description or \"\",\n inputSchema = _ensure_mcp_schema(tool.inputSchema),\n required_scopes = tool.required_scopes,\n }\n end\n end\n end\n\n -- Cache enriched tools (pre-scope-filtered, 60s TTL)\n local ok_enc, encoded = pcall(cjson.encode, enriched_tools)\n if ok_enc then\n session_cache:set(enriched_cache_key, encoded, ENRICHED_CACHE_TTL)\n end\n end\n\n -- Scope filter: filter cached tools by user's scopes at request time\n local tools = setmetatable({}, empty_array_mt)\n for _, tool in ipairs(enriched_tools) do\n if _has_scopes(user_scopes_str, tool.required_scopes) then\n tools[#tools + 1] = {\n name = tool.name,\n description = tool.description or \"\",\n inputSchema = _ensure_mcp_schema(tool.inputSchema),\n }\n end\n end\n\n return _jsonrpc_result(request_id, { tools = _as_json_array(tools) })\nend\n\n\n-- Generic helper to proxy list methods (resources/list, prompts/list) to all backends.\n-- Aggregates results from all backends into a single array.\n-- Caches with key \"{method}:{server_id}\", 60s TTL.\n-- Returns the aggregated array and a lookup map (item_key_value -> backend_location).\nlocal function _proxy_list_to_backends(method_name, result_key, mapping, client_session_id, server_id)\n -- Cache check\n local cache_key = method_name .. \":\" .. (server_id or \"unknown\")\n local cached = session_cache:get(cache_key)\n if cached then\n local ok, data = pcall(cjson.decode, cached)\n if ok then\n -- Ensure decoded items is always a JSON array (empty table from cache loses metatable)\n if data.items and #data.items == 0 then\n data.items = setmetatable({}, empty_array_mt)\n end\n return data.items, data.lookup\n end\n end\n\n local aggregated = setmetatable({}, empty_array_mt)\n local lookup = {}\n local backend_locations = _collect_backend_locations(mapping)\n\n for _, backend_loc in ipairs(backend_locations) do\n local req_body = cjson.encode({\n jsonrpc = \"2.0\",\n id = \"pl-\" .. (ngx.var.request_id or \"0\"),\n method = method_name,\n params = {},\n })\n\n -- Get backend session\n local backend_session_id = nil\n if client_session_id then\n backend_session_id = _get_backend_session(client_session_id, backend_loc, server_id)\n end\n\n if backend_session_id then\n ngx.req.set_header(\"Mcp-Session-Id\", backend_session_id)\n else\n ngx.req.set_header(\"Mcp-Session-Id\", \"\")\n end\n\n local res = ngx.location.capture(backend_loc, {\n method = ngx.HTTP_POST,\n body = req_body,\n })\n\n -- Stale session retry\n if res and res.status >= 400 and client_session_id and backend_session_id then\n ngx.log(ngx.WARN, \"Backend \", method_name, \" returned \", res.status,\n \" for \", backend_loc, \" -- retrying with fresh session\")\n _invalidate_backend_session(client_session_id, backend_loc)\n local new_session_id = _get_backend_session(client_session_id, backend_loc, server_id)\n if new_session_id then\n ngx.req.set_header(\"Mcp-Session-Id\", new_session_id)\n else\n ngx.req.set_header(\"Mcp-Session-Id\", \"\")\n end\n res = ngx.location.capture(backend_loc, {\n method = ngx.HTTP_POST,\n body = req_body,\n })\n end\n\n if res and res.status == 200 then\n local json_body = _parse_sse_body(res.body)\n local ok, data = pcall(cjson.decode, json_body or \"\")\n if ok and data.result and data.result[result_key] then\n for _, item in ipairs(data.result[result_key]) do\n aggregated[#aggregated + 1] = item\n -- Build lookup: for resources, key on \"uri\"; for prompts, key on \"name\"\n local lookup_key = nil\n if result_key == \"resources\" and item.uri then\n lookup_key = item.uri\n elseif result_key == \"prompts\" and item.name then\n lookup_key = item.name\n end\n if lookup_key then\n lookup[lookup_key] = backend_loc\n end\n end\n end\n else\n ngx.log(ngx.WARN, \"Backend \", method_name, \" failed for \", backend_loc,\n \" status=\", res and res.status or \"nil\")\n end\n end\n\n -- Cache aggregated results and lookup map\n local cache_data = { items = aggregated, lookup = lookup }\n local ok_enc, encoded = pcall(cjson.encode, cache_data)\n if ok_enc then\n session_cache:set(cache_key, encoded, ENRICHED_CACHE_TTL)\n end\n\n return aggregated, lookup\nend\n\n\n-- Proxy a single request to a specific backend with session management and stale retry.\n-- Returns the response body directly. Used for tools/call, resources/read, prompts/get.\nlocal function _proxy_to_backend(request_id, method_name, proxied_params,\n backend_location, client_session_id, server_id,\n backend_version, label)\n local proxied_body = cjson.encode({\n jsonrpc = \"2.0\",\n id = request_id,\n method = method_name,\n params = proxied_params,\n })\n\n -- Get or create backend session\n local backend_session_id = nil\n if client_session_id then\n backend_session_id = _get_backend_session(client_session_id, backend_location, server_id)\n end\n\n -- Set version header if pinned\n if backend_version then\n ngx.req.set_header(\"X-MCP-Server-Version\", backend_version)\n end\n\n -- Set the backend session header for the subrequest proxy\n if backend_session_id then\n ngx.req.set_header(\"Mcp-Session-Id\", backend_session_id)\n else\n ngx.req.set_header(\"Mcp-Session-Id\", \"\")\n end\n\n local res = ngx.location.capture(backend_location, {\n method = ngx.HTTP_POST,\n body = proxied_body,\n })\n\n if not res then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603,\n \"Backend request failed for \" .. (label or method_name)))\n return\n end\n\n -- Stale session retry: if backend returns an error that looks like a session issue,\n -- invalidate the session and retry once\n if res.status >= 400 and client_session_id and backend_session_id then\n ngx.log(ngx.WARN, \"Backend returned \", res.status, \" for \", label or method_name,\n \" session=\", backend_session_id, \" -- retrying with fresh session\")\n\n -- Invalidate stale session\n _invalidate_backend_session(client_session_id, backend_location)\n\n -- Get a fresh session (will re-initialize the backend)\n local new_session_id = _get_backend_session(client_session_id, backend_location, server_id)\n if new_session_id then\n ngx.req.set_header(\"Mcp-Session-Id\", new_session_id)\n else\n ngx.req.set_header(\"Mcp-Session-Id\", \"\")\n end\n\n -- Retry the request\n res = ngx.location.capture(backend_location, {\n method = ngx.HTTP_POST,\n body = proxied_body,\n })\n\n if not res then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603,\n \"Backend request failed after retry for \" .. (label or method_name)))\n return\n end\n end\n\n -- Forward backend response\n ngx.status = res.status\n if res.header and res.header[\"Content-Type\"] then\n ngx.header[\"Content-Type\"] = res.header[\"Content-Type\"]\n else\n ngx.header[\"Content-Type\"] = \"application/json\"\n end\n ngx.print(res.body)\nend\n\n\n-- Validate a client session ID against MongoDB (L2).\n-- Uses L1 cache to avoid repeated DB lookups.\n-- Returns true if valid, false otherwise.\nlocal function _validate_client_session(client_session_id)\n if not client_session_id or client_session_id == \"\" then\n return false\n end\n\n -- L1: fast path check (cache valid sessions for SESSION_CACHE_TTL)\n local cache_key = \"csess_valid:\" .. client_session_id\n local cached = session_cache:get(cache_key)\n if cached == \"1\" then\n return true\n end\n\n -- L2: validate via internal FastAPI endpoint\n local res = ngx.location.capture(\n \"/_internal/sessions/client/\" .. client_session_id,\n { method = ngx.HTTP_GET }\n )\n\n if res and res.status == 200 then\n session_cache:set(cache_key, \"1\", SESSION_CACHE_TTL)\n return true\n end\n\n return false\nend\n\n\n-- Negotiate protocol version: if client's version is supported, echo it back;\n-- otherwise respond with our latest supported version.\nlocal function _negotiate_protocol_version(client_version)\n if client_version and SUPPORTED_PROTOCOL_VERSIONS[client_version] then\n return client_version\n end\n return LATEST_PROTOCOL_VERSION\nend\n\n\n-- Handle initialize method - create client session, return MCP capabilities\nlocal function _handle_initialize(request_id, server_id, params)\n local user_id = ngx.var.auth_user or ngx.var.auth_username or \"anonymous\"\n local virtual_path = \"/virtual/\" .. server_id\n\n -- Create client session in MongoDB via internal API\n local body = cjson.encode({\n user_id = user_id,\n virtual_server_path = virtual_path,\n })\n local res = ngx.location.capture(\"/_internal/sessions/client\", {\n method = ngx.HTTP_POST,\n body = body,\n })\n\n local client_session_id = nil\n if res and res.status == 201 then\n local ok, data = pcall(cjson.decode, res.body)\n if ok then\n client_session_id = data.client_session_id\n end\n end\n\n -- Set Mcp-Session-Id response header so client includes it in future requests\n if client_session_id then\n ngx.header[\"Mcp-Session-Id\"] = client_session_id\n ngx.log(ngx.INFO, \"Created client session \", client_session_id,\n \" for user=\", user_id, \" server=\", server_id)\n else\n ngx.log(ngx.WARN, \"Failed to create client session for server=\", server_id)\n end\n\n -- Negotiate protocol version with client\n local client_version = params and params.protocolVersion\n local negotiated_version = _negotiate_protocol_version(client_version)\n\n local result = {\n protocolVersion = negotiated_version,\n capabilities = {\n tools = {\n listChanged = false,\n },\n },\n serverInfo = {\n name = \"mcp-gateway-virtual-server\",\n version = \"1.0.0\",\n },\n }\n return _jsonrpc_result(request_id, result)\nend\n\n\n-- Handle tools/call method - proxy to the correct backend with session management\nlocal function _handle_tools_call(request_id, mapping, params, user_scopes_str, client_session_id, server_id)\n -- Enforce server-level required_scopes before processing\n if not _has_scopes(user_scopes_str, mapping.required_scopes) then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603, \"Access denied: missing required server scopes\"))\n return\n end\n\n local tool_name = params and params.name\n if not tool_name then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32602, \"Missing tool name in params\"))\n return\n end\n\n -- Look up tool in backend map\n local tool_info = mapping.tool_backend_map and mapping.tool_backend_map[tool_name]\n if not tool_info then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32601, \"Tool not found: \" .. tool_name))\n return\n end\n\n -- Enforce per-tool scopes\n if mapping.tools then\n for _, tool_entry in ipairs(mapping.tools) do\n if tool_entry.name == tool_name then\n if not _has_scopes(user_scopes_str, tool_entry.required_scopes) then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603,\n \"Access denied: missing required scopes for tool: \" .. tool_name))\n return\n end\n break\n end\n end\n end\n\n -- Rewrite tool name to original if aliased\n local original_name = tool_info.original_name or tool_name\n local backend_location = tool_info.backend_location\n\n if not backend_location then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603, \"No backend location for tool: \" .. tool_name))\n return\n end\n\n -- Build the proxied params with original tool name\n local proxied_params = {}\n if params then\n for k, v in pairs(params) do\n proxied_params[k] = v\n end\n end\n proxied_params.name = original_name\n\n -- Proxy to backend with session management\n _proxy_to_backend(\n request_id, \"tools/call\", proxied_params,\n backend_location, client_session_id, server_id,\n tool_info.backend_version, \"tool:\" .. tool_name\n )\nend\n\n\n-- Handle resources/read - proxy to the backend that owns the resource\nlocal function _handle_resources_read(request_id, params, mapping, client_session_id, server_id)\n local uri = params and params.uri\n if not uri then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32602, \"Missing resource uri in params\"))\n return\n end\n\n -- Look up which backend owns this resource from cached resources/list\n local _, lookup = _proxy_list_to_backends(\"resources/list\", \"resources\",\n mapping, client_session_id, server_id)\n\n local backend_loc = lookup and lookup[uri]\n if not backend_loc then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32601, \"Resource not found: \" .. uri))\n return\n end\n\n _proxy_to_backend(\n request_id, \"resources/read\", params,\n backend_loc, client_session_id, server_id,\n nil, \"resource:\" .. uri\n )\nend\n\n\n-- Handle prompts/get - proxy to the backend that owns the prompt\nlocal function _handle_prompts_get(request_id, params, mapping, client_session_id, server_id)\n local name = params and params.name\n if not name then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32602, \"Missing prompt name in params\"))\n return\n end\n\n -- Look up which backend owns this prompt from cached prompts/list\n local _, lookup = _proxy_list_to_backends(\"prompts/list\", \"prompts\",\n mapping, client_session_id, server_id)\n\n local backend_loc = lookup and lookup[name]\n if not backend_loc then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32601, \"Prompt not found: \" .. name))\n return\n end\n\n _proxy_to_backend(\n request_id, \"prompts/get\", params,\n backend_loc, client_session_id, server_id,\n nil, \"prompt:\" .. name\n )\nend\n\n\n-- Main entry point\nfunction _M.route()\n -- Per MCP Streamable HTTP 2025-11-25 spec, the client MUST include Accept header\n -- listing both application/json and text/event-stream. Set this on the request so\n -- all ngx.location.capture subrequests to backends inherit it.\n ngx.req.set_header(\"Accept\", \"application/json, text/event-stream\")\n\n local request_method = ngx.var.request_method\n\n -- Handle HTTP GET: per MCP Streamable HTTP 2025-11-25 spec section 3.3,\n -- the server MUST either return Content-Type: text/event-stream or HTTP 405.\n -- We do not support server-initiated SSE streams.\n if request_method == \"GET\" then\n ngx.status = 405\n ngx.header[\"Allow\"] = \"POST\"\n return\n end\n\n -- Handle HTTP DELETE: session termination per MCP spec.\n -- Return 405 Method Not Allowed to indicate we don't support client-initiated termination.\n if request_method == \"DELETE\" then\n ngx.status = 405\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.header[\"Allow\"] = \"POST, GET\"\n return\n end\n\n -- Only POST is accepted for JSON-RPC messages\n if request_method ~= \"POST\" then\n ngx.status = 405\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.header[\"Allow\"] = \"POST, GET, DELETE\"\n return\n end\n\n -- Read request body\n ngx.req.read_body()\n local body = ngx.req.get_body_data()\n\n if not body then\n ngx.status = 400\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.say(_jsonrpc_error(nil, -32700, \"Empty request body\"))\n return\n end\n\n -- Parse JSON-RPC message\n local ok, request = pcall(cjson.decode, body)\n if not ok then\n ngx.status = 400\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.say(_jsonrpc_error(nil, -32700, \"Parse error\"))\n return\n end\n\n local request_id = request.id\n local method = request.method\n local params = request.params\n\n -- Get virtual server ID from nginx variable\n local server_id = ngx.var.virtual_server_id\n if not server_id or server_id == \"\" then\n ngx.status = 500\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.say(_jsonrpc_error(request_id, -32603, \"Virtual server ID not configured\"))\n return\n end\n\n -- Detect JSON-RPC notifications (no \"id\" field) vs requests (have \"id\" field).\n -- Per MCP Streamable HTTP spec, notifications and responses MUST get HTTP 202 Accepted\n -- with no body. Only JSON-RPC requests get a JSON-RPC response.\n local is_notification = (request_id == nil) and (method ~= nil)\n\n -- Handle notifications: return 202 Accepted with no body per MCP spec\n if is_notification then\n if method == \"notifications/initialized\" then\n ngx.log(ngx.INFO, \"Received initialized notification for server=\", server_id)\n elseif method == \"notifications/cancelled\" then\n ngx.log(ngx.INFO, \"Received cancelled notification for server=\", server_id)\n else\n ngx.log(ngx.INFO, \"Received notification method=\", method, \" for server=\", server_id)\n end\n ngx.status = 202\n return\n end\n\n -- Handle initialize: generate a client session and return capabilities\n if method == \"initialize\" then\n ngx.status = 200\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.say(_handle_initialize(request_id, server_id, params))\n return\n end\n\n -- Handle ping: simple echo (no mapping needed)\n if method == \"ping\" then\n ngx.status = 200\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.say(_jsonrpc_result(request_id, {}))\n return\n end\n\n -- Get client session ID from request header (set during initialize)\n local client_session_id = ngx.var.http_mcp_session_id\n\n -- Validate client session: per MCP spec, servers that require a session ID\n -- SHOULD respond with 400 Bad Request to requests without a valid Mcp-Session-Id.\n -- Initialize and ping are exempt; notifications already handled above with 202.\n if not _validate_client_session(client_session_id) then\n ngx.status = 400\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.say(_jsonrpc_error(request_id, -32600,\n \"Missing or invalid Mcp-Session-Id. Send an initialize request first.\"))\n return\n end\n\n -- Load mapping for all other methods\n local mapping = _get_mapping(server_id)\n if not mapping then\n ngx.status = 500\n ngx.header[\"Content-Type\"] = \"application/json\"\n ngx.say(_jsonrpc_error(request_id, -32603, \"Virtual server mapping not found\"))\n return\n end\n\n -- Get user scopes from auth\n local user_scopes_str = ngx.var.auth_scopes or \"\"\n\n -- Route based on method\n ngx.header[\"Content-Type\"] = \"application/json\"\n\n if method == \"tools/list\" then\n ngx.status = 200\n ngx.say(_handle_tools_list(request_id, mapping, user_scopes_str, client_session_id, server_id))\n\n elseif method == \"tools/call\" then\n _handle_tools_call(request_id, mapping, params, user_scopes_str, client_session_id, server_id)\n\n elseif method == \"resources/list\" then\n -- Enforce server-level required_scopes\n if not _has_scopes(user_scopes_str, mapping.required_scopes) then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603, \"Access denied: missing required server scopes\"))\n return\n end\n local resources = _proxy_list_to_backends(\"resources/list\", \"resources\",\n mapping, client_session_id, server_id)\n ngx.status = 200\n ngx.say(_jsonrpc_result(request_id, { resources = _as_json_array(resources) }))\n\n elseif method == \"resources/read\" then\n -- Enforce server-level required_scopes\n if not _has_scopes(user_scopes_str, mapping.required_scopes) then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603, \"Access denied: missing required server scopes\"))\n return\n end\n _handle_resources_read(request_id, params, mapping, client_session_id, server_id)\n\n elseif method == \"prompts/list\" then\n -- Enforce server-level required_scopes\n if not _has_scopes(user_scopes_str, mapping.required_scopes) then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603, \"Access denied: missing required server scopes\"))\n return\n end\n local prompts = _proxy_list_to_backends(\"prompts/list\", \"prompts\",\n mapping, client_session_id, server_id)\n ngx.status = 200\n ngx.say(_jsonrpc_result(request_id, { prompts = _as_json_array(prompts) }))\n\n elseif method == \"prompts/get\" then\n -- Enforce server-level required_scopes\n if not _has_scopes(user_scopes_str, mapping.required_scopes) then\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32603, \"Access denied: missing required server scopes\"))\n return\n end\n _handle_prompts_get(request_id, params, mapping, client_session_id, server_id)\n\n else\n ngx.status = 200\n ngx.say(_jsonrpc_error(request_id, -32601, \"Method not found: \" .. tostring(method)))\n end\nend\n\n-- Execute routing\n_M.route()\n" }, { "path": "docker/nginx_rev_proxy_http_and_https.conf", "content": "# Nginx configuration directive for handling long server names\nserver_names_hash_bucket_size 128;\n\n# Increase header buffer sizes for large OAuth tokens (Auth0, Entra ID)\nlarge_client_header_buffers 4 32k;\nproxy_buffer_size 16k;\nproxy_buffers 4 16k;\n\n# Variables hash configuration - needed for large number of auth_request_set variables\n# With multiple location blocks each setting 5+ variables, we need larger hash tables\nvariables_hash_max_size 2048;\nvariables_hash_bucket_size 128;\n\n# Lua shared dictionary for metrics collection (10MB)\nlua_shared_dict metrics_buffer 10m;\n\n# Lua shared dictionary for virtual server routing mappings (2MB)\nlua_shared_dict virtual_server_map 2m;\n\n# Background flush of metrics buffer to metrics-service\ninit_worker_by_lua_file /etc/nginx/lua/flush_metrics.lua;\n\n# Map to determine the real client scheme\n# Uses X-Forwarded-Proto from ALB/load balancer if present, otherwise falls back to $scheme\n# This is critical for OAuth2 redirect URIs when HTTPS termination happens at the ALB\nmap $http_x_forwarded_proto $real_scheme {\n default $scheme;\n https https;\n http http;\n}\n\n# Map to determine the real client port\n# Uses X-Forwarded-Port from ALB/load balancer if present, otherwise maps internal\n# container ports (8080/8443) to their standard external equivalents (80/443)\n# This is critical for Keycloak URL generation when running behind a reverse proxy\nmap $http_x_forwarded_port $real_port {\n default $http_x_forwarded_port;\n \"\" $standard_port;\n}\n\n# Map internal container listen ports to standard external ports\nmap $server_port $standard_port {\n 8080 80;\n 8443 443;\n default $server_port;\n}\n\n{{VERSION_MAP}}\n# First server block now directly handles HTTP requests instead of redirecting\nserver {\n listen 8080;\n # {{ADDITIONAL_SERVER_NAMES}} is replaced with custom domains/IPs for gateway access\n server_name localhost {{ADDITIONAL_SERVER_NAMES}};\n\n # Custom error page for 502 Bad Gateway (shown during backend startup)\n error_page 502 /502.html;\n location = /502.html {\n root /usr/share/nginx/html;\n internal;\n }\n\n # Add this to trigger the named location for 403 errors\n error_page 403 = @forbidden_error;\n\n # Registered MCP server locations (generated dynamically)\n{{LOCATION_BLOCKS}}\n\n{{REGISTRY_ONLY_BLOCK}}\n\n # Internal session management for virtual MCP server router\n location /_internal/sessions/ {\n internal;\n proxy_pass http://127.0.0.1:7860/api/internal/sessions/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header Content-Type application/json;\n }\n\n # Virtual MCP server locations (generated dynamically)\n{{VIRTUAL_SERVER_BLOCKS}}\n\n # Serve static files directly from nginx (more efficient than proxying)\n location /static/ {\n alias /app/frontend/build/static/;\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n }\n\n location = /favicon.ico {\n alias /app/frontend/build/favicon.ico;\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n }\n\n # Route for Cost Explorer service\n location / {\n proxy_pass http://127.0.0.1:7860/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n }\n\n # Auth validation endpoint - passes entire request to auth server\n location = /validate {\n internal;\n \n proxy_pass http://auth-server:8888/validate;\n \n # Pass original request info\n proxy_set_header X-Original-URI $request_uri;\n proxy_set_header X-Original-Method $request_method;\n proxy_set_header X-Original-URL $scheme://$host$request_uri;\n\n # Extract and pass Cognito config headers from original request\n proxy_set_header X-User-Pool-Id $http_x_user_pool_id;\n proxy_set_header X-Client-Id $http_x_client_id;\n proxy_set_header X-Region $http_x_region;\n proxy_set_header X-Authorization $http_x_authorization; \n\n \n # Pass all original headers (including Authorization and X-Body from Lua)\n proxy_pass_request_headers on;\n \n # Short timeouts for auth validation\n proxy_connect_timeout 10s;\n proxy_read_timeout 10s;\n proxy_send_timeout 10s;\n }\n\n # OAuth2 Cognito callback endpoint\n location /oauth2/callback/cognito {\n proxy_pass http://auth-server:8888/oauth2/callback/cognito;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Cognito login endpoint \n location /oauth2/login/cognito {\n proxy_pass http://auth-server:8888/oauth2/login/cognito;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Cognito logout endpoint\n location /oauth2/logout/ {\n proxy_pass http://auth-server:8888/oauth2/logout/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Entra ID callback endpoint\n location /oauth2/callback/entra {\n proxy_pass http://auth-server:8888/oauth2/callback/entra;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through cookies, query parameters, and headers\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Entra ID login endpoint\n location /oauth2/login/entra {\n proxy_pass http://auth-server:8888/oauth2/login/entra;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Okta callback endpoint\n location /oauth2/callback/okta {\n proxy_pass http://auth-server:8888/oauth2/callback/okta;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through cookies, query parameters, and headers\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Okta login endpoint\n location /oauth2/login/okta {\n proxy_pass http://auth-server:8888/oauth2/login/okta;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 GitHub callback endpoint\n location /oauth2/callback/github {\n proxy_pass http://auth-server:8888/oauth2/callback/github;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 GitHub login endpoint\n location /oauth2/login/github {\n proxy_pass http://auth-server:8888/oauth2/login/github;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Google callback endpoint\n location /oauth2/callback/google {\n proxy_pass http://auth-server:8888/oauth2/callback/google;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Google login endpoint\n location /oauth2/login/google {\n proxy_pass http://auth-server:8888/oauth2/login/google;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Auth0 callback endpoint\n location /oauth2/callback/auth0 {\n proxy_pass http://auth-server:8888/oauth2/callback/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Auth0 login endpoint\n location /oauth2/login/auth0 {\n proxy_pass http://auth-server:8888/oauth2/login/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # Anthropic MCP Registry API - Public REST API with JWT authentication\n location {{ROOT_PATH}}/{{ANTHROPIC_API_VERSION}}/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to registry service\n proxy_pass http://127.0.0.1:7860/{{ANTHROPIC_API_VERSION}}/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Buffering\n proxy_buffering on;\n proxy_buffer_size 4k;\n proxy_buffers 8 4k;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n\n # CORS headers (for browser clients)\n add_header 'Access-Control-Allow-Origin' '*' always;\n add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;\n add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-User-Pool-Id, X-Client-Id, X-Region, X-Authorization' always;\n add_header 'Access-Control-Allow-Credentials' 'true' always;\n\n # Handle preflight OPTIONS requests\n if ($request_method = OPTIONS) {\n add_header 'Access-Control-Max-Age' 1728000;\n add_header 'Content-Type' 'text/plain; charset=utf-8';\n add_header 'Content-Length' 0;\n return 204;\n }\n }\n\n # A2A Agent API - Internal API with JWT authentication\n # Public API endpoints (no authentication required)\n\n # /api/auth/me requires authentication (exact match takes precedence over prefix)\n location = {{ROOT_PATH}}/api/auth/me {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/auth/me;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n }\n\n # Public auth endpoints - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/auth {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Public health endpoint - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/health {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Public version endpoint - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/version {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n location {{ROOT_PATH}}/api/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Buffering\n proxy_buffering on;\n proxy_buffer_size 4k;\n proxy_buffers 8 4k;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n }\n\n # {{KEYCLOAK_LOCATIONS_START}}\n # Keycloak proxy\n location /keycloak/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Keycloak specific headers\n proxy_set_header X-Forwarded-Port $real_port;\n proxy_buffer_size 128k;\n proxy_buffers 4 256k;\n proxy_busy_buffers_size 256k;\n }\n\n # Keycloak realms proxy (for authentication endpoints)\n location /realms/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/realms/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Keycloak specific headers\n proxy_set_header X-Forwarded-Port $real_port;\n proxy_buffer_size 128k;\n proxy_buffers 4 256k;\n proxy_busy_buffers_size 256k;\n }\n\n # Keycloak resources proxy (for CSS, JS, images)\n location /resources/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/resources/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Static resource caching\n expires 1h;\n add_header Cache-Control \"public, immutable\";\n }\n\n # OAuth2 Keycloak callback endpoint\n location /oauth2/callback/keycloak {\n proxy_pass http://auth-server:8888/oauth2/callback/keycloak;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Keycloak login endpoint \n location /oauth2/login/keycloak {\n proxy_pass http://auth-server:8888/oauth2/login/keycloak;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n # {{KEYCLOAK_LOCATIONS_END}}\n\n # Error handlers for authentication failures\n location @auth_error {\n return 401 '{\"error\": \"Authentication required\"}';\n add_header Content-Type application/json;\n add_header Connection close;\n }\n \n location @forbidden_error {\n default_type application/json;\n return 403 '{\"error\": \"Access forbidden\"}';\n add_header Content-Type application/json always;\n add_header Connection close always;\n }\n\n error_log /var/log/nginx/error.log debug;\n}\n\n# Keep the HTTPS server for clients that prefer it\nserver {\n listen 8443 ssl;\n # {{ADDITIONAL_SERVER_NAMES}} is replaced with custom domains/IPs for gateway access\n server_name localhost {{ADDITIONAL_SERVER_NAMES}};\n\n # SSL Configuration - requires user-provided certificates\n # Mount certificates to /etc/ssl/certs/fullchain.pem and /etc/ssl/private/privkey.pem\n ssl_certificate /etc/ssl/certs/fullchain.pem;\n ssl_certificate_key /etc/ssl/private/privkey.pem;\n ssl_protocols TLSv1.2 TLSv1.3;\n ssl_prefer_server_ciphers off;\n # Stronger cipher suite\n ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;\n\n # Custom error page for 502 Bad Gateway (shown during backend startup)\n error_page 502 /502.html;\n location = /502.html {\n root /usr/share/nginx/html;\n internal;\n }\n\n # Add this to trigger the named location for 403 errors\n error_page 403 = @forbidden_error;\n\n # Auth validation endpoint - passes entire request to auth server\n location = /validate {\n internal;\n \n proxy_pass http://auth-server:8888/validate;\n \n # Pass original request info\n proxy_set_header X-Original-URI $request_uri;\n proxy_set_header X-Original-Method $request_method;\n proxy_set_header X-Original-URL $scheme://$host$request_uri;\n\n # Extract and pass Cognito config headers from original request\n proxy_set_header X-User-Pool-Id $http_x_user_pool_id;\n proxy_set_header X-Client-Id $http_x_client_id;\n proxy_set_header X-Region $http_x_region;\n proxy_set_header X-Authorization $http_x_authorization; \n \n # Pass all original headers (including Authorization and X-Body from Lua)\n proxy_pass_request_headers on;\n \n # Short timeouts for auth validation\n proxy_connect_timeout 10s;\n proxy_read_timeout 10s;\n proxy_send_timeout 10s;\n }\n \n # OAuth2 Cognito callback endpoint\n location /oauth2/callback/cognito {\n proxy_pass http://auth-server:8888/oauth2/callback/cognito;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Cognito login endpoint \n location /oauth2/login/cognito {\n proxy_pass http://auth-server:8888/oauth2/login/cognito;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Cognito logout endpoint\n location /oauth2/logout/ {\n proxy_pass http://auth-server:8888/oauth2/logout/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Entra ID callback endpoint (HTTPS)\n location /oauth2/callback/entra {\n proxy_pass http://auth-server:8888/oauth2/callback/entra;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through cookies, query parameters, and headers\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Entra ID login endpoint (HTTPS)\n location /oauth2/login/entra {\n proxy_pass http://auth-server:8888/oauth2/login/entra;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Okta callback endpoint (HTTPS)\n location /oauth2/callback/okta {\n proxy_pass http://auth-server:8888/oauth2/callback/okta;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through cookies, query parameters, and headers\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Okta login endpoint (HTTPS)\n location /oauth2/login/okta {\n proxy_pass http://auth-server:8888/oauth2/login/okta;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 GitHub callback endpoint (HTTPS)\n location /oauth2/callback/github {\n proxy_pass http://auth-server:8888/oauth2/callback/github;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 GitHub login endpoint (HTTPS)\n location /oauth2/login/github {\n proxy_pass http://auth-server:8888/oauth2/login/github;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Google callback endpoint (HTTPS)\n location /oauth2/callback/google {\n proxy_pass http://auth-server:8888/oauth2/callback/google;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Google login endpoint (HTTPS)\n location /oauth2/login/google {\n proxy_pass http://auth-server:8888/oauth2/login/google;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Auth0 callback endpoint (HTTPS)\n location /oauth2/callback/auth0 {\n proxy_pass http://auth-server:8888/oauth2/callback/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Auth0 login endpoint (HTTPS)\n location /oauth2/login/auth0 {\n proxy_pass http://auth-server:8888/oauth2/login/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # {{KEYCLOAK_LOCATIONS_START}}\n # Keycloak proxy (HTTPS)\n location /keycloak/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Keycloak specific headers\n proxy_set_header X-Forwarded-Port $real_port;\n proxy_buffer_size 128k;\n proxy_buffers 4 256k;\n proxy_busy_buffers_size 256k;\n }\n\n # Keycloak realms proxy (HTTPS - for authentication endpoints)\n location /realms/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/realms/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Keycloak specific headers\n proxy_set_header X-Forwarded-Port $real_port;\n proxy_buffer_size 128k;\n proxy_buffers 4 256k;\n proxy_busy_buffers_size 256k;\n }\n\n # Keycloak resources proxy (HTTPS - for CSS, JS, images)\n location /resources/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/resources/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Static resource caching\n expires 1h;\n add_header Cache-Control \"public, immutable\";\n }\n\n # OAuth2 Keycloak callback endpoint (HTTPS)\n location /oauth2/callback/keycloak {\n proxy_pass http://auth-server:8888/oauth2/callback/keycloak;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n \n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Keycloak login endpoint (HTTPS)\n location /oauth2/login/keycloak {\n proxy_pass http://auth-server:8888/oauth2/login/keycloak;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n # {{KEYCLOAK_LOCATIONS_END}}\n\n # Anthropic MCP Registry API {{ANTHROPIC_API_VERSION}} - Public REST API with JWT authentication (HTTPS)\n location {{ROOT_PATH}}/{{ANTHROPIC_API_VERSION}}/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to registry service\n proxy_pass http://127.0.0.1:7860/{{ANTHROPIC_API_VERSION}}/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Buffering\n proxy_buffering on;\n proxy_buffer_size 4k;\n proxy_buffers 8 4k;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n\n # CORS headers (for browser clients)\n add_header 'Access-Control-Allow-Origin' '*' always;\n add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;\n add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-User-Pool-Id, X-Client-Id, X-Region, X-Authorization' always;\n add_header 'Access-Control-Allow-Credentials' 'true' always;\n\n # Handle preflight OPTIONS requests\n if ($request_method = OPTIONS) {\n add_header 'Access-Control-Max-Age' 1728000;\n add_header 'Content-Type' 'text/plain; charset=utf-8';\n add_header 'Content-Length' 0;\n return 204;\n }\n }\n\n # A2A Agent API - Internal API with JWT authentication (HTTPS)\n # Public API endpoints (no authentication required)\n\n # /api/auth/me requires authentication (exact match takes precedence over prefix)\n location = {{ROOT_PATH}}/api/auth/me {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/auth/me;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n }\n\n # Public auth endpoints - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/auth {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Public health endpoint - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/health {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Public version endpoint - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/version {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n location {{ROOT_PATH}}/api/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Buffering\n proxy_buffering on;\n proxy_buffer_size 4k;\n proxy_buffers 8 4k;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n }\n\n # Registered MCP server locations (generated dynamically)\n{{LOCATION_BLOCKS}}\n\n{{REGISTRY_ONLY_BLOCK}}\n\n # Internal session management for virtual MCP server router\n location /_internal/sessions/ {\n internal;\n proxy_pass http://127.0.0.1:7860/api/internal/sessions/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header Content-Type application/json;\n }\n\n # Virtual MCP server locations (generated dynamically)\n{{VIRTUAL_SERVER_BLOCKS}}\n\n # Serve static files directly from nginx (more efficient than proxying)\n location /static/ {\n alias /app/frontend/build/static/;\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n }\n\n location = /favicon.ico {\n alias /app/frontend/build/favicon.ico;\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n }\n\n # Catch-all: proxy to registry FastAPI\n location / {\n proxy_pass http://127.0.0.1:7860/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n }\n\n # Error handlers for authentication failures\n location @auth_error {\n return 401 '{\"error\": \"Authentication required\"}';\n add_header Content-Type application/json;\n add_header Connection close;\n }\n \n location @forbidden_error {\n default_type application/json;\n return 403 '{\"error\": \"Access forbidden\"}';\n add_header Content-Type application/json always;\n add_header Connection close always;\n }\n \n error_log /var/log/nginx/error.log debug;\n}" }, { "path": "docker/nginx_rev_proxy_http_only.conf", "content": "# Nginx configuration directive for handling long server names\nserver_names_hash_bucket_size 128;\n\n# Increase header buffer sizes for large OAuth tokens (Auth0, Entra ID)\nlarge_client_header_buffers 4 32k;\nproxy_buffer_size 16k;\nproxy_buffers 4 16k;\n\n# Variables hash configuration - needed for large number of auth_request_set variables\n# With multiple location blocks each setting 5+ variables, we need larger hash tables\nvariables_hash_max_size 2048;\nvariables_hash_bucket_size 128;\n\n# Lua shared dictionary for metrics collection (10MB)\nlua_shared_dict metrics_buffer 10m;\n\n# Lua shared dictionary for virtual server routing mappings (2MB)\nlua_shared_dict virtual_server_map 2m;\n\n# Background flush of metrics buffer to metrics-service\ninit_worker_by_lua_file /etc/nginx/lua/flush_metrics.lua;\n\n# DNS resolver for ECS Cloud Map service discovery\n# Uses AWS VPC DNS resolver for dynamic service resolution\n# This enables runtime DNS resolution for upstream services\nresolver 169.254.169.253 valid=10s ipv6=off;\n\n# Map to preserve X-Forwarded-Proto from upstream (ALB/CloudFront) or use $scheme as fallback\n# This is critical for HTTPS detection when behind ALB/CloudFront\nmap $http_x_forwarded_proto $forwarded_proto {\n default $http_x_forwarded_proto;\n \"\" $scheme;\n}\n\n# Map to determine the real client port\n# Uses X-Forwarded-Port from ALB/load balancer if present, otherwise maps internal\n# container ports (8080/8443) to their standard external equivalents (80/443)\n# This is critical for Keycloak URL generation when running behind a reverse proxy\nmap $http_x_forwarded_port $real_port {\n default $http_x_forwarded_port;\n \"\" $standard_port;\n}\n\n# Map internal container listen ports to standard external ports\nmap $server_port $standard_port {\n 8080 80;\n 8443 443;\n default $server_port;\n}\n\n{{VERSION_MAP}}\n# First server block now directly handles HTTP requests instead of redirecting\nserver {\n listen 8080;\n # {{ADDITIONAL_SERVER_NAMES}} is replaced with custom domains/IPs for gateway access\n server_name localhost {{ADDITIONAL_SERVER_NAMES}};\n\n # Custom error page for 502 Bad Gateway (shown during backend startup)\n error_page 502 /502.html;\n location = /502.html {\n root /usr/share/nginx/html;\n internal;\n }\n\n # Add this to trigger the named location for 403 errors\n error_page 403 = @forbidden_error;\n\n # /api/auth/me requires authentication (exact match takes precedence over prefix)\n location = {{ROOT_PATH}}/api/auth/me {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/auth/me;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n }\n\n # Public auth endpoints - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/auth {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n proxy_pass_request_headers on;\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Public health endpoint - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/health {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n proxy_pass_request_headers on;\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Public version endpoint - no authentication required (priority prefix match)\n location ^~ {{ROOT_PATH}}/api/version {\n proxy_pass http://127.0.0.1:7860;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n proxy_pass_request_headers on;\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Protected API endpoints - require authentication\n location {{ROOT_PATH}}/api/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_groups $upstream_http_x_groups;\n\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\n\n # Registered MCP server locations (generated dynamically)\n{{LOCATION_BLOCKS}}\n\n{{REGISTRY_ONLY_BLOCK}}\n\n # Internal session management for virtual MCP server router\n location /_internal/sessions/ {\n internal;\n proxy_pass http://127.0.0.1:7860/api/internal/sessions/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header Content-Type application/json;\n }\n\n # Virtual MCP server locations (generated dynamically)\n{{VIRTUAL_SERVER_BLOCKS}}\n\n # Serve static files directly from nginx (more efficient than proxying)\n location /static/ {\n alias /app/frontend/build/static/;\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n }\n\n location = /favicon.ico {\n alias /app/frontend/build/favicon.ico;\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n }\n\n # Catch-all: proxy to registry FastAPI\n location / {\n proxy_pass http://127.0.0.1:7860/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n }\n\n # Auth validation endpoint - passes entire request to auth server\n location = /validate {\n internal;\n \n proxy_pass http://auth-server:8888/validate;\n \n # Pass original request info\n proxy_set_header X-Original-URI $request_uri;\n proxy_set_header X-Original-Method $request_method;\n proxy_set_header X-Original-URL $scheme://$host$request_uri;\n\n # Extract and pass Cognito config headers from original request\n proxy_set_header X-User-Pool-Id $http_x_user_pool_id;\n proxy_set_header X-Client-Id $http_x_client_id;\n proxy_set_header X-Region $http_x_region;\n # Forward Authorization header as X-Authorization (auth-server expects this)\n proxy_set_header X-Authorization $http_x_authorization; \n\n \n # Pass all original headers (including Authorization and X-Body from Lua)\n proxy_pass_request_headers on;\n \n # Short timeouts for auth validation\n proxy_connect_timeout 10s;\n proxy_read_timeout 10s;\n proxy_send_timeout 10s;\n }\n\n # OAuth2 Cognito callback endpoint\n location /oauth2/callback/cognito {\n proxy_pass http://auth-server:8888/oauth2/callback/cognito;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n \n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Cognito login endpoint \n location /oauth2/login/cognito {\n proxy_pass http://auth-server:8888/oauth2/login/cognito;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n \n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Cognito logout endpoint\n location /oauth2/logout/ {\n proxy_pass http://auth-server:8888/oauth2/logout/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Entra ID callback endpoint\n location /oauth2/callback/entra {\n proxy_pass http://auth-server:8888/oauth2/callback/entra;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through cookies, query parameters, and headers\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Entra ID login endpoint\n location /oauth2/login/entra {\n proxy_pass http://auth-server:8888/oauth2/login/entra;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Okta callback endpoint\n location /oauth2/callback/okta {\n proxy_pass http://auth-server:8888/oauth2/callback/okta;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through cookies, query parameters, and headers\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Okta login endpoint\n location /oauth2/login/okta {\n proxy_pass http://auth-server:8888/oauth2/login/okta;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 GitHub callback endpoint\n location /oauth2/callback/github {\n proxy_pass http://auth-server:8888/oauth2/callback/github;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 GitHub login endpoint\n location /oauth2/login/github {\n proxy_pass http://auth-server:8888/oauth2/login/github;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Google callback endpoint\n location /oauth2/callback/google {\n proxy_pass http://auth-server:8888/oauth2/callback/google;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Google login endpoint\n location /oauth2/login/google {\n proxy_pass http://auth-server:8888/oauth2/login/google;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # OAuth2 Auth0 callback endpoint\n location /oauth2/callback/auth0 {\n proxy_pass http://auth-server:8888/oauth2/callback/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Auth0 login endpoint\n location /oauth2/login/auth0 {\n proxy_pass http://auth-server:8888/oauth2/login/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n\n # Anthropic MCP Registry API - Public REST API with JWT authentication\n location {{ROOT_PATH}}/{{ANTHROPIC_API_VERSION}}/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n\n # Proxy to registry service\n proxy_pass http://127.0.0.1:7860/{{ANTHROPIC_API_VERSION}}/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Buffering\n proxy_buffering on;\n proxy_buffer_size 4k;\n proxy_buffers 8 4k;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n\n # CORS headers (for browser clients)\n add_header 'Access-Control-Allow-Origin' '*' always;\n add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;\n add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-User-Pool-Id, X-Client-Id, X-Region, X-Authorization' always;\n add_header 'Access-Control-Allow-Credentials' 'true' always;\n\n # Handle preflight OPTIONS requests\n if ($request_method = OPTIONS) {\n add_header 'Access-Control-Max-Age' 1728000;\n add_header 'Content-Type' 'text/plain; charset=utf-8';\n add_header 'Content-Length' 0;\n return 204;\n }\n }\n\n # A2A Agent API - Public REST API with JWT authentication\n # This mirrors the Anthropic API pattern for agent discovery and management\n location {{ROOT_PATH}}/v0.1/agents/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n\n # Proxy to registry service (FastAPI backend)\n proxy_pass http://127.0.0.1:7860/v0.1/agents/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Groups $auth_groups;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n\n # Buffering\n proxy_buffering on;\n proxy_buffer_size 4k;\n proxy_buffers 8 4k;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;\n\n # CORS headers (for browser clients)\n add_header 'Access-Control-Allow-Origin' '*' always;\n add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;\n add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-User-Pool-Id, X-Client-Id, X-Region, X-Authorization' always;\n add_header 'Access-Control-Allow-Credentials' 'true' always;\n\n # Handle preflight OPTIONS requests\n if ($request_method = OPTIONS) {\n add_header 'Access-Control-Max-Age' 1728000;\n add_header 'Content-Type' 'text/plain; charset=utf-8';\n add_header 'Content-Length' 0;\n return 204;\n }\n }\n\n # {{KEYCLOAK_LOCATIONS_START}}\n # Keycloak proxy\n location /keycloak/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Keycloak specific headers\n proxy_set_header X-Forwarded-Port $real_port;\n proxy_buffer_size 128k;\n proxy_buffers 4 256k;\n proxy_busy_buffers_size 256k;\n }\n\n # Keycloak realms proxy (for authentication endpoints)\n location /realms/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/realms/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Keycloak specific headers\n proxy_set_header X-Forwarded-Port $real_port;\n proxy_buffer_size 128k;\n proxy_buffers 4 256k;\n proxy_busy_buffers_size 256k;\n }\n\n # Keycloak resources proxy (for CSS, JS, images)\n location /resources/ {\n proxy_pass {{KEYCLOAK_SCHEME}}://{{KEYCLOAK_HOST}}:{{KEYCLOAK_PORT}}/resources/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n\n # Static resource caching\n expires 1h;\n add_header Cache-Control \"public, immutable\";\n }\n\n # OAuth2 Keycloak callback endpoint\n location /oauth2/callback/keycloak {\n proxy_pass http://auth-server:8888/oauth2/callback/keycloak;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n \n # Pass through all headers for OAuth2 flow\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n }\n\n # OAuth2 Keycloak login endpoint \n location /oauth2/login/keycloak {\n proxy_pass http://auth-server:8888/oauth2/login/keycloak;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $forwarded_proto;\n \n # Pass through query parameters and headers\n proxy_pass_request_headers on;\n }\n # {{KEYCLOAK_LOCATIONS_END}}\n\n # Error handlers for authentication failures\n location @auth_error {\n return 401 '{\"error\": \"Authentication required\"}';\n add_header Content-Type application/json;\n add_header Connection close;\n }\n \n location @forbidden_error {\n default_type application/json;\n return 403 '{\"error\": \"Access forbidden\"}';\n add_header Content-Type application/json always;\n add_header Connection close always;\n }\n\n error_log /var/log/nginx/error.log debug;\n}\n" }, { "path": "docker/registry-entrypoint.sh", "content": "#!/bin/bash\nset -e # Exit immediately if a command exits with a non-zero status.\n\necho \"Starting Registry Service Setup...\"\n\n# --- DocumentDB CA Bundle Download (needed for both init mode and normal mode) ---\nif [[ \"${DOCUMENTDB_HOST}\" == *\"docdb-elastic.amazonaws.com\"* ]]; then\n echo \"Detected DocumentDB Elastic cluster\"\n echo \"Downloading DocumentDB Elastic CA bundle...\"\n CA_BUNDLE_URL=\"https://www.amazontrust.com/repository/SFSRootCAG2.pem\"\n CA_BUNDLE_PATH=\"/app/certs/global-bundle.pem\"\n if [ ! -f \"$CA_BUNDLE_PATH\" ]; then\n curl -fsSL \"$CA_BUNDLE_URL\" -o \"$CA_BUNDLE_PATH\"\n echo \"DocumentDB Elastic CA bundle (SFSRootCAG2.pem) downloaded successfully to $CA_BUNDLE_PATH\"\n fi\nelif [[ \"${DOCUMENTDB_HOST}\" == *\"docdb.amazonaws.com\"* ]]; then\n echo \"Detected regular DocumentDB cluster\"\n echo \"Downloading regular DocumentDB CA bundle...\"\n CA_BUNDLE_URL=\"https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem\"\n CA_BUNDLE_PATH=\"/app/certs/global-bundle.pem\"\n if [ ! -f \"$CA_BUNDLE_PATH\" ]; then\n curl -fsSL \"$CA_BUNDLE_URL\" -o \"$CA_BUNDLE_PATH\"\n echo \"DocumentDB CA bundle (global-bundle.pem) downloaded successfully to $CA_BUNDLE_PATH\"\n fi\nfi\n\n# Check if we're in init mode (for running DocumentDB initialization scripts)\nif [ \"$RUN_INIT_SCRIPTS\" = \"true\" ]; then\n echo \"Running in init mode - executing initialization scripts...\"\n exec \"$@\"\nfi\n\n# --- Wait for MongoDB Replica Set ---\nif [ -n \"$DOCUMENTDB_HOST\" ]; then\n echo \"Waiting for MongoDB replica set at ${DOCUMENTDB_HOST}:${DOCUMENTDB_PORT:-27017}...\"\n source /app/.venv/bin/activate\n python3 -c \"\nimport pymongo, os, time, sys\nhost = os.getenv('DOCUMENTDB_HOST', 'mongodb')\nport = int(os.getenv('DOCUMENTDB_PORT', '27017'))\nuser = os.getenv('DOCUMENTDB_USERNAME', '')\npwd = os.getenv('DOCUMENTDB_PASSWORD', '')\nbackend = os.getenv('STORAGE_BACKEND', 'mongodb-ce')\nuse_tls = os.getenv('DOCUMENTDB_USE_TLS', 'true').lower() == 'true'\nca_file = os.getenv('DOCUMENTDB_TLS_CA_FILE', '/app/certs/global-bundle.pem')\nauth = 'SCRAM-SHA-256' if backend == 'mongodb-ce' else 'SCRAM-SHA-1'\nif user and pwd:\n uri = f'mongodb://{user}:{pwd}@{host}:{port}/?authMechanism={auth}&authSource=admin'\nelse:\n uri = f'mongodb://{host}:{port}/'\n# Prepare TLS options\ntls_options = {}\nif use_tls:\n tls_options['tls'] = True\n tls_options['tlsCAFile'] = ca_file\nwhile True:\n try:\n c = pymongo.MongoClient(uri, serverSelectionTimeoutMS=5000, connectTimeoutMS=5000, **tls_options)\n c.admin.command('ping')\n try:\n st = c.admin.command('replSetGetStatus')\n ready = [m for m in st['members'] if m['state'] in [1, 2]]\n total = len(st['members'])\n if st['ok'] == 1 and len(ready) == total:\n print(f'MongoDB replica set ready ({len(ready)}/{total} members)')\n c.close()\n break\n print(f'Waiting for replica set: {len(ready)}/{total} ready')\n except pymongo.errors.OperationFailure:\n # Standalone mode (no replica set) - ping succeeded so we're good\n print('MongoDB is ready (standalone mode)')\n c.close()\n break\n except Exception as e:\n print(f'MongoDB not ready yet: {e}')\n time.sleep(5)\n\"\n deactivate\n echo \"MongoDB is ready.\"\nfi\n\n# --- Environment Variable Setup ---\necho \"Setting up environment variables...\"\n\n# Get deployment mode (default: with-gateway)\nDEPLOYMENT_MODE=\"${DEPLOYMENT_MODE:-with-gateway}\"\nREGISTRY_MODE=\"${REGISTRY_MODE:-full}\"\n\necho \"============================================================\"\necho \"Starting MCP Gateway Registry\"\necho \" DEPLOYMENT_MODE: ${DEPLOYMENT_MODE}\"\necho \" REGISTRY_MODE: ${REGISTRY_MODE}\"\nif [ \"$DEPLOYMENT_MODE\" = \"registry-only\" ]; then\n echo \" Note: Dynamic MCP server location blocks will NOT be generated\"\nfi\necho \"============================================================\"\n\n# Generate secret key if not provided\nif [ -z \"$SECRET_KEY\" ]; then\n SECRET_KEY=$(python -c 'import secrets; print(secrets.token_hex(32))')\nfi\n\n# Create .env file for registry\nREGISTRY_ENV_FILE=\"/app/registry/.env\"\necho \"Creating Registry .env file...\"\necho \"SECRET_KEY=${SECRET_KEY}\" > \"$REGISTRY_ENV_FILE\"\necho \"Registry .env created.\"\n\n# DocumentDB CA Bundle already downloaded at the beginning of this script\n\n# --- SSL Certificate Check ---\n# These paths match REGISTRY_CONSTANTS.SSL_CERT_PATH and SSL_KEY_PATH in registry/constants.py\nSSL_CERT_PATH=\"/etc/ssl/certs/fullchain.pem\"\nSSL_KEY_PATH=\"/etc/ssl/private/privkey.pem\"\n\necho \"Checking for SSL certificates...\"\nif [ ! -f \"$SSL_CERT_PATH\" ] || [ ! -f \"$SSL_KEY_PATH\" ]; then\n echo \"==========================================\"\n echo \"SSL certificates not found - HTTPS will not be available\"\n echo \"==========================================\"\n echo \"\"\n echo \"To enable HTTPS, mount your certificates to:\"\n echo \" - $SSL_CERT_PATH\"\n echo \" - $SSL_KEY_PATH\"\n echo \"\"\n echo \"Example for docker-compose.yml:\"\n echo \" volumes:\"\n echo \" - /path/to/fullchain.pem:/etc/ssl/certs/fullchain.pem:ro\"\n echo \" - /path/to/privkey.pem:/etc/ssl/private/privkey.pem:ro\"\n echo \"\"\n echo \"HTTP server will be available on port 80\"\n echo \"==========================================\"\nelse\n echo \"==========================================\"\n echo \"SSL certificates found - HTTPS enabled\"\n echo \"==========================================\"\n echo \"Certificate: $SSL_CERT_PATH\"\n echo \"Private key: $SSL_KEY_PATH\"\n echo \"HTTPS server will be available on port 443\"\n echo \"==========================================\"\nfi\n\n# --- Lua Module Setup ---\necho \"Setting up Lua support for nginx...\"\nLUA_SCRIPTS_DIR=\"/etc/nginx/lua\"\nmkdir -p \"$LUA_SCRIPTS_DIR\"\nmkdir -p \"$LUA_SCRIPTS_DIR/virtual_mappings\"\n\n# Copy Lua scripts from the docker/lua directory (standalone files, not heredocs)\nLUA_SOURCE_DIR=\"/app/docker/lua\"\ncp \"$LUA_SOURCE_DIR/capture_body.lua\" \"$LUA_SCRIPTS_DIR/capture_body.lua\"\ncp \"$LUA_SOURCE_DIR/virtual_router.lua\" \"$LUA_SCRIPTS_DIR/virtual_router.lua\"\n\ncp \"$LUA_SOURCE_DIR/emit_metrics.lua\" \"$LUA_SCRIPTS_DIR/emit_metrics.lua\"\ncp \"$LUA_SOURCE_DIR/flush_metrics.lua\" \"$LUA_SCRIPTS_DIR/flush_metrics.lua\"\n\necho \"Lua scripts copied from $LUA_SOURCE_DIR to $LUA_SCRIPTS_DIR.\"\n\n# --- Nginx Configuration ---\necho \"Preparing Nginx configuration...\"\n\n# Pass environment variables through to Lua workers (nginx strips them by default)\nfor envvar in METRICS_API_KEY METRICS_SERVICE_URL; do\n grep -q \"^env ${envvar};\" /etc/nginx/nginx.conf 2>/dev/null || \\\n sed -i \"1i env ${envvar};\" /etc/nginx/nginx.conf\ndone\n\n# Raise main-context error_log to 'warn' so Lua init_worker/timer messages\n# (e.g. flush_metrics.lua startup confirmation and connection errors) are visible.\n# The default nginx.conf ships with 'error' level which suppresses WARN/INFO.\nsed -i 's|error_log /var/log/nginx/error.log;|error_log /var/log/nginx/error.log warn;|' /etc/nginx/nginx.conf\n\n# Remove default nginx site to prevent conflicts with our config\necho \"Removing default nginx site configuration...\"\nrm -f /etc/nginx/sites-enabled/default\nrm -f /etc/nginx/sites-available/default\n\n# Template paths matching REGISTRY_CONSTANTS in registry/constants.py\nNGINX_TEMPLATE_HTTP_ONLY=\"/app/docker/nginx_rev_proxy_http_only.conf\"\nNGINX_TEMPLATE_HTTP_AND_HTTPS=\"/app/docker/nginx_rev_proxy_http_and_https.conf\"\nNGINX_CONFIG_PATH=\"/etc/nginx/conf.d/nginx_rev_proxy.conf\"\n\n# Check if SSL certificates exist and use appropriate config\nif [ ! -f \"$SSL_CERT_PATH\" ] || [ ! -f \"$SSL_KEY_PATH\" ]; then\n echo \"Using HTTP-only Nginx configuration (no SSL certificates)...\"\n cp \"$NGINX_TEMPLATE_HTTP_ONLY\" \"$NGINX_CONFIG_PATH\"\n echo \"HTTP-only Nginx configuration installed.\"\nelse\n echo \"Using HTTP + HTTPS Nginx configuration (SSL certificates found)...\"\n cp \"$NGINX_TEMPLATE_HTTP_AND_HTTPS\" \"$NGINX_CONFIG_PATH\"\n echo \"HTTP + HTTPS Nginx configuration installed.\"\nfi\n\n# --- Embeddings Configuration ---\n# Get embeddings configuration from environment or use defaults\nEMBEDDINGS_PROVIDER=\"${EMBEDDINGS_PROVIDER:-sentence-transformers}\"\nEMBEDDINGS_MODEL_NAME=\"${EMBEDDINGS_MODEL_NAME:-all-MiniLM-L6-v2}\"\nEMBEDDINGS_MODEL_DIMENSIONS=\"${EMBEDDINGS_MODEL_DIMENSIONS:-384}\"\n\necho \"Embeddings Configuration:\"\necho \" Provider: $EMBEDDINGS_PROVIDER\"\necho \" Model: $EMBEDDINGS_MODEL_NAME\"\necho \" Dimensions: $EMBEDDINGS_MODEL_DIMENSIONS\"\n\n# Only check for local model if using sentence-transformers\nif [ \"$EMBEDDINGS_PROVIDER\" = \"sentence-transformers\" ]; then\n EMBEDDINGS_MODEL_DIR=\"/app/registry/models/$EMBEDDINGS_MODEL_NAME\"\n\n echo \"Checking for sentence-transformers model...\"\n if [ ! -d \"$EMBEDDINGS_MODEL_DIR\" ] || [ -z \"$(ls -A \"$EMBEDDINGS_MODEL_DIR\")\" ]; then\n echo \"==========================================\"\n echo \"WARNING: Embeddings model not found!\"\n echo \"==========================================\"\n echo \"\"\n echo \"The registry requires the sentence-transformers model to function properly.\"\n echo \"Please download the model to: $EMBEDDINGS_MODEL_DIR\"\n echo \"\"\n echo \"Run this command to download the model:\"\n echo \" docker run --rm -v \\$(pwd)/models:/models huggingface/transformers-pytorch-cpu python -c \\\"from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/$EMBEDDINGS_MODEL_NAME').save('/models/$EMBEDDINGS_MODEL_NAME')\\\"\"\n echo \"\"\n echo \"Or see the README for alternative download methods.\"\n echo \"==========================================\"\n else\n echo \"Embeddings model found at $EMBEDDINGS_MODEL_DIR\"\n fi\nelif [ \"$EMBEDDINGS_PROVIDER\" = \"litellm\" ]; then\n echo \"Using LiteLLM provider - no local model download required\"\n echo \"Model: $EMBEDDINGS_MODEL_NAME\"\n if [[ \"$EMBEDDINGS_MODEL_NAME\" == bedrock/* ]]; then\n echo \"Bedrock model will use AWS credential chain for authentication\"\n elif [ ! -z \"$EMBEDDINGS_API_KEY\" ]; then\n echo \"API key configured for cloud embeddings\"\n else\n echo \"WARNING: No EMBEDDINGS_API_KEY set for cloud provider\"\n fi\nfi\n\n# --- Environment Variable Substitution for MCP Server Auth Tokens ---\necho \"Processing MCP Server configuration files...\"\nfor i in $(seq 1 99); do\n env_var_name=\"MCP_SERVER${i}_AUTH_TOKEN\"\n env_var_value=$(eval echo \\$$env_var_name)\n \n if [ ! -z \"$env_var_value\" ]; then\n echo \"Found $env_var_name, substituting in server JSON files...\"\n # Replace the literal environment variable name with its value in all JSON files\n find /app/registry/servers -name \"*.json\" -type f -exec sed -i \"s|$env_var_name|$env_var_value|g\" {} \\;\n fi\ndone\necho \"MCP Server configuration processing completed.\"\n\n# --- Start Background Services ---\n# Export embeddings configuration for the registry service\nexport EMBEDDINGS_PROVIDER=$EMBEDDINGS_PROVIDER\nexport EMBEDDINGS_MODEL_NAME=$EMBEDDINGS_MODEL_NAME\nexport EMBEDDINGS_MODEL_DIMENSIONS=$EMBEDDINGS_MODEL_DIMENSIONS\n\necho \"Starting MCP Registry in the background...\"\ncd /app\nsource /app/.venv/bin/activate\nuvicorn registry.main:app --host 0.0.0.0 --port 7860 --proxy-headers --forwarded-allow-ips='*' &\necho \"MCP Registry started.\"\n\n# Wait for nginx config to be generated (check that placeholders are replaced)\necho \"Waiting for nginx configuration to be generated...\"\nWAIT_TIME=0\nMAX_WAIT=120\nwhile [ $WAIT_TIME -lt $MAX_WAIT ]; do\n if [ -f \"/etc/nginx/conf.d/nginx_rev_proxy.conf\" ]; then\n # Check if placeholders have been replaced\n if ! grep -q \"{{ADDITIONAL_SERVER_NAMES}}\" \"/etc/nginx/conf.d/nginx_rev_proxy.conf\" && \\\n ! grep -q \"{{ANTHROPIC_API_VERSION}}\" \"/etc/nginx/conf.d/nginx_rev_proxy.conf\" && \\\n ! grep -q \"{{LOCATION_BLOCKS}}\" \"/etc/nginx/conf.d/nginx_rev_proxy.conf\" && \\\n ! grep -q \"{{VIRTUAL_SERVER_BLOCKS}}\" \"/etc/nginx/conf.d/nginx_rev_proxy.conf\"; then\n echo \"Nginx configuration generated successfully\"\n break\n fi\n fi\n sleep 2\n WAIT_TIME=$((WAIT_TIME + 2))\ndone\n\nif [ $WAIT_TIME -ge $MAX_WAIT ]; then\n echo \"WARNING: Timeout waiting for nginx configuration. Starting nginx anyway...\"\nfi\n\n# Resolve METRICS_SERVICE_URL hostname to IPv4 before nginx starts.\n# Lua cosockets use the nginx resolver (VPC DNS 169.254.169.253), which cannot\n# resolve Service Connect names (only the Envoy sidecar can). By substituting\n# the hostname with its IPv4 Service Connect VIP (127.255.0.x) in the env var,\n# flush_metrics.lua connects directly to the IP, bypassing DNS entirely.\nif [ -n \"$METRICS_SERVICE_URL\" ]; then\n metrics_host=$(echo \"$METRICS_SERVICE_URL\" | sed 's|http://||;s|:.*||')\n if ! echo \"$metrics_host\" | grep -qE '^[0-9]+\\.[0-9]+\\.[0-9]+\\.[0-9]+$'; then\n resolved=$(getent ahostsv4 \"$metrics_host\" 2>/dev/null | head -1 | awk '{print $1}')\n if [ -n \"$resolved\" ]; then\n export METRICS_SERVICE_URL=$(echo \"$METRICS_SERVICE_URL\" | sed \"s|$metrics_host|$resolved|\")\n echo \"Resolved METRICS_SERVICE_URL: $metrics_host -> $resolved ($METRICS_SERVICE_URL)\"\n else\n echo \"WARNING: Could not resolve $metrics_host to IPv4 -- metrics flush may fail\"\n fi\n fi\nfi\n\n# Add FQDN aliases for Service Connect entries in /etc/hosts.\n# Service Connect only registers short names (e.g., \"auth-server\"), but servers\n# may be registered with Cloud Map FQDNs (e.g., \"auth-server.mcp-gateway.local\").\n# The Python health checker resolves proxy_pass_url hostnames via system DNS,\n# which only finds /etc/hosts entries. Adding FQDN aliases ensures both short\n# names and FQDNs resolve to the IPv4 Service Connect VIP.\n# Gated on SERVICE_CONNECT_NAMESPACE -- only set in ECS Terraform deployments.\nif [ -n \"${SERVICE_CONNECT_NAMESPACE:-}\" ]; then\n if [ -w /etc/hosts ]; then\n fqdn_count=0\n grep '^127\\.255\\.0\\.' /etc/hosts | while read -r ip name _rest; do\n echo \"$ip ${name}.${SERVICE_CONNECT_NAMESPACE}\" >> /etc/hosts\n fqdn_count=$((fqdn_count + 1))\n done\n echo \"Added FQDN aliases for Service Connect entries (namespace: ${SERVICE_CONNECT_NAMESPACE})\"\n else\n echo \"INFO: /etc/hosts not writable (ECS Fargate), FQDN aliases skipped\"\n echo \" Short names and IPs will still work via Service Connect\"\n fi\nfi\n\necho \"Starting Nginx...\"\n# Create /run/nginx directory for pid file (tmpfs mount overwrites Dockerfile creation)\nmkdir -p /run/nginx\n# Change pid file location to writable directory for non-root user\nsed -i 's|pid /run/nginx.pid;|pid /run/nginx/nginx.pid;|' /etc/nginx/nginx.conf\nnginx\n\necho \"Registry service fully started. Keeping container alive...\"\n# Keep the container running indefinitely\ntail -f /dev/null \n" }, { "path": "docker-compose.dhi.yml", "content": "# Docker Hardened Images (DHI) Override\n#\n# This file overrides the default docker-compose.yml to use Docker Hardened\n# Images from dhi.io for improved security posture. DHI images are hardened\n# versions of standard Docker Hub images with reduced attack surface.\n#\n# Prerequisites:\n# - Access to dhi.io registry\n# - Authenticated via: docker login dhi.io\n#\n# Usage:\n# docker compose -f docker-compose.yml -f docker-compose.dhi.yml up -d\n#\n# Note: The default docker-compose.yml uses standard public Docker Hub images\n# and works without any registry authentication.\n\nservices:\n mongodb:\n image: dhi.io/mongodb:8-debian13-dev\n command: [\"--replSet\", \"rs0\", \"--bind_ip\", \"127.0.0.1,mongodb\"]\n\n prometheus:\n image: dhi.io/prometheus:3.9\n user: \"nobody\"\n\n grafana:\n image: dhi.io/grafana:12\n user: \"472\"\n\n # Note: Keycloak DHI image (dhi.io/keycloak:26) has a read-only filesystem\n # and only supports 'start --optimized'. It is not compatible with the\n # start-dev mode or dynamic KC_ environment variables used in this compose\n # setup. Use the standard quay.io/keycloak image for local development.\n\n keycloak-db:\n image: dhi.io/postgres:16-alpine3.22\n" }, { "path": "docker-compose.podman.yml", "content": "version: '3.8'\n\nservices:\n # Registry service (includes nginx, SSL, FAISS, models)\n # PODMAN VERSION: Uses non-privileged ports for rootless operation\n registry:\n build:\n context: .\n dockerfile: docker/Dockerfile.registry\n args:\n BUILD_VERSION: ${BUILD_VERSION:-1.0.0}\n environment:\n # Deployment Mode Configuration\n - DEPLOYMENT_MODE=${DEPLOYMENT_MODE:-with-gateway}\n - REGISTRY_MODE=${REGISTRY_MODE:-full}\n # Tab visibility overrides (AND-ed with REGISTRY_MODE)\n - SHOW_SERVERS_TAB=${SHOW_SERVERS_TAB:-true}\n - SHOW_VIRTUAL_SERVERS_TAB=${SHOW_VIRTUAL_SERVERS_TAB:-true}\n - SHOW_SKILLS_TAB=${SHOW_SKILLS_TAB:-true}\n - SHOW_AGENTS_TAB=${SHOW_AGENTS_TAB:-true}\n - GATEWAY_ADDITIONAL_SERVER_NAMES=${GATEWAY_ADDITIONAL_SERVER_NAMES:-}\n # Registry Card Configuration\n - REGISTRY_URL=${REGISTRY_URL:-http://localhost}\n - REGISTRY_NAME=${REGISTRY_NAME:-AI Registry}\n - REGISTRY_ORGANIZATION_NAME=${REGISTRY_ORGANIZATION_NAME:-ACME Inc.}\n - REGISTRY_DESCRIPTION=${REGISTRY_DESCRIPTION:-}\n - REGISTRY_CONTACT_EMAIL=${REGISTRY_CONTACT_EMAIL:-}\n - REGISTRY_CONTACT_URL=${REGISTRY_CONTACT_URL:-}\n - SECRET_KEY=${SECRET_KEY}\n - AUTH_SERVER_URL=${AUTH_SERVER_URL}\n - AUTH_SERVER_EXTERNAL_URL=${AUTH_SERVER_EXTERNAL_URL}\n - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}\n - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}\n - GITHUB_ENABLED=${GITHUB_ENABLED:-false}\n - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}\n - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}\n - GOOGLE_ENABLED=${GOOGLE_ENABLED:-false}\n - COGNITO_CLIENT_ID=${COGNITO_CLIENT_ID}\n - COGNITO_CLIENT_SECRET=${COGNITO_CLIENT_SECRET}\n - COGNITO_USER_POOL_ID=${COGNITO_USER_POOL_ID}\n - COGNITO_ENABLED=${COGNITO_ENABLED:-false}\n - AWS_REGION=${AWS_REGION:-us-east-1}\n - HEALTH_CHECK_INTERVAL_SECONDS=${HEALTH_CHECK_INTERVAL_SECONDS:-30}\n - SRE_GATEWAY_AUTH_TOKEN=${SRE_GATEWAY_AUTH_TOKEN}\n - ATLASSIAN_AUTH_TOKEN=${ATLASSIAN_AUTH_TOKEN}\n # Metrics configuration\n - METRICS_SERVICE_URL=http://metrics-service:8890\n - METRICS_API_KEY=${METRICS_API_KEY_REGISTRY}\n - METRICS_API_KEY_NGINX=${METRICS_API_KEY_REGISTRY}\n # Keycloak configuration\n - AUTH_PROVIDER=${AUTH_PROVIDER:-cognito}\n - KEYCLOAK_ENABLED=${KEYCLOAK_ENABLED:-false}\n - KEYCLOAK_URL=${KEYCLOAK_URL:-http://keycloak:8080}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-mcp-gateway}\n - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID:-mcp-gateway-web}\n - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}\n - KEYCLOAK_ADMIN=${KEYCLOAK_ADMIN:-admin}\n - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_ADMIN_PASSWORD}\n - KEYCLOAK_M2M_CLIENT_ID=${KEYCLOAK_M2M_CLIENT_ID}\n - KEYCLOAK_M2M_CLIENT_SECRET=${KEYCLOAK_M2M_CLIENT_SECRET}\n # Entra ID configuration\n - ENTRA_TENANT_ID=${ENTRA_TENANT_ID}\n - ENTRA_CLIENT_ID=${ENTRA_CLIENT_ID}\n - ENTRA_CLIENT_SECRET=${ENTRA_CLIENT_SECRET}\n - ENTRA_ENABLED=${ENTRA_ENABLED:-false}\n # External Registry Configuration\n - EXTERNAL_REGISTRY_TAGS=${EXTERNAL_REGISTRY_TAGS:-anthropic-registry,workday-asor}\n - ASOR_ACCESS_TOKEN=${ASOR_ACCESS_TOKEN}\n - ASOR_CLIENT_CREDENTIALS=${ASOR_CLIENT_CREDENTIALS}\n # Security Scanning Configuration\n - SECURITY_SCAN_ENABLED=${SECURITY_SCAN_ENABLED:-true}\n - SECURITY_SCAN_ON_REGISTRATION=${SECURITY_SCAN_ON_REGISTRATION:-true}\n - SECURITY_BLOCK_UNSAFE_SERVERS=${SECURITY_BLOCK_UNSAFE_SERVERS:-true}\n - SECURITY_ANALYZERS=${SECURITY_ANALYZERS:-yara}\n - SECURITY_SCAN_TIMEOUT=${SECURITY_SCAN_TIMEOUT:-60}\n - SECURITY_ADD_PENDING_TAG=${SECURITY_ADD_PENDING_TAG:-true}\n - MCP_SCANNER_LLM_API_KEY=${MCP_SCANNER_LLM_API_KEY}\n # GitHub Private Repository Access (SKILL.md fetching)\n - GITHUB_PAT=${GITHUB_PAT:-}\n - GITHUB_APP_ID=${GITHUB_APP_ID:-}\n - GITHUB_APP_INSTALLATION_ID=${GITHUB_APP_INSTALLATION_ID:-}\n - GITHUB_APP_PRIVATE_KEY=${GITHUB_APP_PRIVATE_KEY:-}\n - GITHUB_EXTRA_HOSTS=${GITHUB_EXTRA_HOSTS:-}\n - GITHUB_API_BASE_URL=${GITHUB_API_BASE_URL:-https://api.github.com}\n # Storage Backend Configuration\n - STORAGE_BACKEND=${STORAGE_BACKEND:-file}\n # DocumentDB/MongoDB Configuration (when STORAGE_BACKEND=documentdb)\n - DOCUMENTDB_HOST=${DOCUMENTDB_HOST:-mongodb}\n - DOCUMENTDB_PORT=${DOCUMENTDB_PORT:-27017}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD}\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - DOCUMENTDB_USE_TLS=${DOCUMENTDB_USE_TLS:-false}\n - DOCUMENTDB_TLS_CA_FILE=${DOCUMENTDB_TLS_CA_FILE:-}\n - DOCUMENTDB_USE_IAM=${DOCUMENTDB_USE_IAM:-false}\n - DOCUMENTDB_REPLICA_SET=${DOCUMENTDB_REPLICA_SET:-rs0}\n - DOCUMENTDB_READ_PREFERENCE=${DOCUMENTDB_READ_PREFERENCE:-secondaryPreferred}\n # Embeddings Configuration\n - EMBEDDINGS_PROVIDER=${EMBEDDINGS_PROVIDER:-sentence-transformers}\n - EMBEDDINGS_MODEL_NAME=${EMBEDDINGS_MODEL_NAME:-all-MiniLM-L6-v2}\n - EMBEDDINGS_MODEL_DIMENSIONS=${EMBEDDINGS_MODEL_DIMENSIONS:-384}\n - EMBEDDINGS_API_KEY=${EMBEDDINGS_API_KEY}\n - EMBEDDINGS_API_BASE=${EMBEDDINGS_API_BASE}\n - EMBEDDINGS_AWS_REGION=${EMBEDDINGS_AWS_REGION:-us-east-1}\n # ANS (Agent Name Service) Configuration\n - ANS_INTEGRATION_ENABLED=${ANS_INTEGRATION_ENABLED:-false}\n - ANS_API_ENDPOINT=${ANS_API_ENDPOINT:-https://api.godaddy.com}\n - ANS_API_KEY=${ANS_API_KEY:-}\n - ANS_API_SECRET=${ANS_API_SECRET:-}\n - ANS_API_TIMEOUT_SECONDS=${ANS_API_TIMEOUT_SECONDS:-30}\n - ANS_SYNC_INTERVAL_HOURS=${ANS_SYNC_INTERVAL_HOURS:-6}\n - ANS_VERIFICATION_CACHE_TTL_SECONDS=${ANS_VERIFICATION_CACHE_TTL_SECONDS:-3600}\n # Podman/local: allow the dashboard to call /api/* using the session cookie\n # (disables nginx auth_request for /api/*; FastAPI still enforces auth)\n - NGINX_DISABLE_API_AUTH_REQUEST=${NGINX_DISABLE_API_AUTH_REQUEST:-true}\n # Federation static token auth\n - FEDERATION_STATIC_TOKEN_AUTH_ENABLED=${FEDERATION_STATIC_TOKEN_AUTH_ENABLED:-false}\n - FEDERATION_STATIC_TOKEN=${FEDERATION_STATIC_TOKEN:-}\n # Auth server config (mirrored for config panel visibility)\n - OAUTH_STORE_TOKENS_IN_SESSION=${OAUTH_STORE_TOKENS_IN_SESSION:-false}\n - REGISTRY_STATIC_TOKEN_AUTH_ENABLED=${REGISTRY_STATIC_TOKEN_AUTH_ENABLED:-false}\n - REGISTRY_API_TOKEN=${REGISTRY_API_TOKEN:-}\n - REGISTRY_API_KEYS=${REGISTRY_API_KEYS:-}\n # Registration Webhook\n - REGISTRATION_WEBHOOK_URL=${REGISTRATION_WEBHOOK_URL:-}\n - REGISTRATION_WEBHOOK_AUTH_HEADER=${REGISTRATION_WEBHOOK_AUTH_HEADER:-Authorization}\n - REGISTRATION_WEBHOOK_AUTH_TOKEN=${REGISTRATION_WEBHOOK_AUTH_TOKEN:-}\n - REGISTRATION_WEBHOOK_TIMEOUT_SECONDS=${REGISTRATION_WEBHOOK_TIMEOUT_SECONDS:-10}\n # Registration Gate (Admission Control)\n - REGISTRATION_GATE_ENABLED=${REGISTRATION_GATE_ENABLED:-false}\n - REGISTRATION_GATE_URL=${REGISTRATION_GATE_URL:-}\n - REGISTRATION_GATE_AUTH_TYPE=${REGISTRATION_GATE_AUTH_TYPE:-none}\n - REGISTRATION_GATE_AUTH_CREDENTIAL=${REGISTRATION_GATE_AUTH_CREDENTIAL:-}\n - REGISTRATION_GATE_AUTH_HEADER_NAME=${REGISTRATION_GATE_AUTH_HEADER_NAME:-X-Api-Key}\n - REGISTRATION_GATE_TIMEOUT_SECONDS=${REGISTRATION_GATE_TIMEOUT_SECONDS:-5}\n - REGISTRATION_GATE_MAX_RETRIES=${REGISTRATION_GATE_MAX_RETRIES:-2}\n # M2M Direct Registration\n - M2M_DIRECT_REGISTRATION_ENABLED=${M2M_DIRECT_REGISTRATION_ENABLED:-true}\n - MAX_TOKENS_PER_USER_PER_HOUR=${MAX_TOKENS_PER_USER_PER_HOUR:-100}\n # Telemetry Configuration\n # Disable all: set MCP_TELEMETRY_DISABLED=1 to disable all telemetry (startup ping + heartbeat)\n # Heartbeat opt-out: set MCP_TELEMETRY_OPT_OUT=1 to disable daily heartbeat only\n # Heartbeat interval: set MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=1440 (default: 1440 = 24h)\n # Endpoint: set TELEMETRY_ENDPOINT= to use a self-hosted collector\n # Debug: set TELEMETRY_DEBUG=true to log payloads without sending\n - MCP_TELEMETRY_DISABLED=${MCP_TELEMETRY_DISABLED:-}\n - MCP_TELEMETRY_OPT_OUT=${MCP_TELEMETRY_OPT_OUT:-}\n - MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=${MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES:-1440}\n - TELEMETRY_DEBUG=${TELEMETRY_DEBUG:-false}\n # Application Log Configuration\n - APP_LOG_MAX_BYTES=${APP_LOG_MAX_BYTES:-52428800}\n - APP_LOG_BACKUP_COUNT=${APP_LOG_BACKUP_COUNT:-5}\n - APP_LOG_CENTRALIZED_ENABLED=${APP_LOG_CENTRALIZED_ENABLED:-true}\n - APP_LOG_CENTRALIZED_TTL_DAYS=${APP_LOG_CENTRALIZED_TTL_DAYS:-1}\n - APP_LOG_MONGODB_BUFFER_SIZE=${APP_LOG_MONGODB_BUFFER_SIZE:-50}\n - APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=${APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS:-5.0}\n - APP_LOG_LEVEL=${APP_LOG_LEVEL:-INFO}\n - APP_LOG_EXCLUDED_LOGGERS=${APP_LOG_EXCLUDED_LOGGERS:-uvicorn.access,httpx,pymongo,motor}\n ports:\n - \"80:8080\" # Map host 80 to container 8080 (non-root nginx)\n - \"443:8443\" # Map host 443 to container 8443 (non-root nginx)\n - \"7860:7860\"\n volumes:\n - ${HOME}/mcp-gateway/servers:/app/registry/servers\n - ${HOME}/mcp-gateway/agents:/app/registry/agents\n - ${HOME}/mcp-gateway/models:/app/registry/models\n - ${HOME}/mcp-gateway/logs:/app/logs\n - ${HOME}/mcp-gateway/security_scans:/app/security_scans\n - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml\n - ${HOME}/mcp-gateway/federation.json:/app/config/federation.json\n - ${HOME}/mcp-gateway/ssl:/etc/ssl:ro\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n auth-server:\n condition: service_started\n metrics-service:\n condition: service_healthy\n mongodb-init:\n condition: service_completed_successfully\n restart: unless-stopped\n\n # Metrics Collection Service\n metrics-service:\n build:\n context: metrics-service\n dockerfile: Dockerfile\n environment:\n - METRICS_SERVICE_PORT=8890\n - METRICS_SERVICE_HOST=0.0.0.0\n - SQLITE_DB_PATH=/var/lib/sqlite/metrics.db\n - METRICS_RETENTION_DAYS=90\n - METRICS_API_KEY_AUTH=${METRICS_API_KEY_AUTH_SERVER}\n - METRICS_API_KEY_REGISTRY=${METRICS_API_KEY_REGISTRY}\n - METRICS_API_KEY_MCPGW=${METRICS_API_KEY_MCPGW_SERVER}\n - OTEL_SERVICE_NAME=mcp-metrics-service\n - OTEL_PROMETHEUS_ENABLED=true\n - OTEL_PROMETHEUS_PORT=9465\n - OTEL_OTLP_ENDPOINT=${OTEL_OTLP_ENDPOINT:-}\n - OTEL_EXPORTER_OTLP_HEADERS=${OTEL_EXPORTER_OTLP_HEADERS:-}\n - OTEL_OTLP_EXPORT_INTERVAL_MS=${OTEL_OTLP_EXPORT_INTERVAL_MS:-30000}\n - OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=${OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:-cumulative}\n - METRICS_RATE_LIMIT=1000\n ports:\n - \"8890:8890\"\n - \"9465:9465\" # Prometheus metrics endpoint\n volumes:\n - metrics-db-data:/var/lib/sqlite\n - ${HOME}/mcp-gateway/logs:/app/logs\n depends_on:\n - metrics-db\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8890/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n # Auth service (separate and scalable)\n auth-server:\n build:\n context: .\n dockerfile: docker/Dockerfile.auth\n environment:\n - REGISTRY_URL=${REGISTRY_URL}\n - SECRET_KEY=${SECRET_KEY}\n - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}\n - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}\n - GITHUB_ENABLED=${GITHUB_ENABLED:-false}\n - COGNITO_CLIENT_ID=${COGNITO_CLIENT_ID}\n - COGNITO_CLIENT_SECRET=${COGNITO_CLIENT_SECRET}\n - COGNITO_USER_POOL_ID=${COGNITO_USER_POOL_ID}\n - COGNITO_DOMAIN=${COGNITO_DOMAIN:-auto}\n - COGNITO_ENABLED=${COGNITO_ENABLED:-false}\n - AWS_REGION=${AWS_REGION:-us-east-1}\n - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}\n - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}\n - GOOGLE_ENABLED=${GOOGLE_ENABLED:-false}\n # Metrics configuration\n - METRICS_SERVICE_URL=http://metrics-service:8890\n - METRICS_API_KEY=${METRICS_API_KEY_AUTH_SERVER}\n # Keycloak configuration\n - AUTH_PROVIDER=${AUTH_PROVIDER:-cognito} # 'cognito' or 'keycloak'\n - KEYCLOAK_ENABLED=${KEYCLOAK_ENABLED:-true} # Enable Keycloak by default\n - KEYCLOAK_URL=${KEYCLOAK_URL:-http://keycloak:8080}\n # Podman note: host port 8080 is used by the registry UI (8080->80),\n # so Keycloak is exposed on 18080->8080 by default in this Podman compose.\n - KEYCLOAK_EXTERNAL_URL=${KEYCLOAK_EXTERNAL_URL:-http://localhost:18080}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-mcp-gateway}\n - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID:-mcp-gateway-web}\n - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}\n - KEYCLOAK_M2M_CLIENT_ID=${KEYCLOAK_M2M_CLIENT_ID:-mcp-gateway-m2m}\n - KEYCLOAK_M2M_CLIENT_SECRET=${KEYCLOAK_M2M_CLIENT_SECRET}\n # Entra ID configuration\n - ENTRA_TENANT_ID=${ENTRA_TENANT_ID}\n - ENTRA_CLIENT_ID=${ENTRA_CLIENT_ID}\n - ENTRA_CLIENT_SECRET=${ENTRA_CLIENT_SECRET}\n - ENTRA_ENABLED=${ENTRA_ENABLED:-false}\n # Okta configuration\n - OKTA_DOMAIN=${OKTA_DOMAIN:-}\n - OKTA_CLIENT_ID=${OKTA_CLIENT_ID:-}\n - OKTA_CLIENT_SECRET=${OKTA_CLIENT_SECRET:-}\n - OKTA_M2M_CLIENT_ID=${OKTA_M2M_CLIENT_ID:-}\n - OKTA_M2M_CLIENT_SECRET=${OKTA_M2M_CLIENT_SECRET:-}\n - OKTA_API_TOKEN=${OKTA_API_TOKEN:-}\n - OKTA_AUTH_SERVER_ID=${OKTA_AUTH_SERVER_ID:-}\n # Storage Backend Configuration\n - STORAGE_BACKEND=${STORAGE_BACKEND:-file}\n # DocumentDB/MongoDB Configuration (when STORAGE_BACKEND=documentdb or mongodb-ce)\n - DOCUMENTDB_HOST=${DOCUMENTDB_HOST:-mongodb}\n - DOCUMENTDB_PORT=${DOCUMENTDB_PORT:-27017}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD}\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - DOCUMENTDB_USE_TLS=${DOCUMENTDB_USE_TLS:-false}\n - DOCUMENTDB_TLS_CA_FILE=${DOCUMENTDB_TLS_CA_FILE}\n - DOCUMENTDB_USE_IAM=${DOCUMENTDB_USE_IAM:-false}\n - DOCUMENTDB_REPLICA_SET=${DOCUMENTDB_REPLICA_SET:-rs0}\n - DOCUMENTDB_READ_PREFERENCE=${DOCUMENTDB_READ_PREFERENCE:-secondaryPreferred}\n # Registry API static token auth\n - REGISTRY_STATIC_TOKEN_AUTH_ENABLED=${REGISTRY_STATIC_TOKEN_AUTH_ENABLED:-false}\n - REGISTRY_API_TOKEN=${REGISTRY_API_TOKEN:-}\n - REGISTRY_API_KEYS=${REGISTRY_API_KEYS:-}\n # OAuth token storage in session (set to false for Entra ID large tokens)\n - OAUTH_STORE_TOKENS_IN_SESSION=${OAUTH_STORE_TOKENS_IN_SESSION:-false}\n # Application Log Configuration\n - APP_LOG_MAX_BYTES=${APP_LOG_MAX_BYTES:-52428800}\n - APP_LOG_BACKUP_COUNT=${APP_LOG_BACKUP_COUNT:-5}\n - APP_LOG_CENTRALIZED_ENABLED=${APP_LOG_CENTRALIZED_ENABLED:-true}\n - APP_LOG_CENTRALIZED_TTL_DAYS=${APP_LOG_CENTRALIZED_TTL_DAYS:-1}\n - APP_LOG_MONGODB_BUFFER_SIZE=${APP_LOG_MONGODB_BUFFER_SIZE:-50}\n - APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=${APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS:-5.0}\n - APP_LOG_LEVEL=${APP_LOG_LEVEL:-INFO}\n - APP_LOG_EXCLUDED_LOGGERS=${APP_LOG_EXCLUDED_LOGGERS:-uvicorn.access,httpx,pymongo,motor}\n ports:\n - \"8888:8888\"\n volumes:\n - ${HOME}/mcp-gateway/logs:/app/logs\n # - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/scopes.yml\n depends_on:\n metrics-service:\n condition: service_healthy\n mongodb-init:\n condition: service_completed_successfully\n restart: unless-stopped\n\n # Current Time MCP Server\n currenttime-server:\n build:\n context: servers/currenttime\n dockerfile: ../../docker/Dockerfile.mcp-server\n environment:\n - PORT=8000\n - MCP_TRANSPORT=streamable-http\n ports:\n - \"8000:8000\"\n restart: unless-stopped\n\n # Financial Info MCP Server\n fininfo-server:\n build:\n context: servers/fininfo\n dockerfile: ../../docker/Dockerfile.mcp-server\n environment:\n - PORT=8001\n - SECRET_KEY=${SECRET_KEY}\n volumes:\n - ${HOME}/mcp-gateway/secrets/fininfo/:/app/fininfo/\n ports:\n - \"8001:8001\"\n restart: unless-stopped\n\n # MCP Gateway Server\n mcpgw-server:\n build:\n context: .\n dockerfile: docker/Dockerfile.mcp-server\n args:\n SERVER_DIR: servers/mcpgw\n environment:\n - HOST=0.0.0.0\n - PORT=8003\n - REGISTRY_BASE_URL=http://registry:8080\n volumes:\n - ${HOME}/mcp-gateway/servers:/app/registry/servers\n - ${HOME}/mcp-gateway/models:/app/registry/models\n - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml\n ports:\n - \"8003:8003\"\n depends_on:\n - registry\n restart: unless-stopped\n\n # Real Server Fake Tools MCP Server\n realserverfaketools-server:\n build:\n context: servers/realserverfaketools\n dockerfile: ../../docker/Dockerfile.mcp-server\n environment:\n - PORT=8002\n ports:\n - \"8002:8002\"\n restart: unless-stopped\n\n\n # SQLite container for metrics database\n metrics-db:\n image: alpine:latest\n volumes:\n - metrics-db-data:/var/lib/sqlite\n command: [\"sh\", \"-c\", \"apk add --no-cache sqlite && mkdir -p /var/lib/sqlite && sqlite3 /var/lib/sqlite/metrics.db 'CREATE TABLE IF NOT EXISTS _health (id INTEGER);' && tail -f /dev/null\"]\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"sqlite3\", \"/var/lib/sqlite/metrics.db\", \".tables\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n # Prometheus for metrics collection\n prometheus:\n image: prom/prometheus:latest\n ports:\n - \"9090:9090\"\n volumes:\n - ./config/prometheus.yml:/etc/prometheus/prometheus.yml\n - prometheus-data:/prometheus\n command:\n - '--config.file=/etc/prometheus/prometheus.yml'\n - '--storage.tsdb.path=/prometheus'\n - '--web.console.libraries=/etc/prometheus/console_libraries'\n - '--web.console.templates=/etc/prometheus/consoles'\n - '--storage.tsdb.retention.time=200h'\n - '--web.enable-lifecycle'\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n restart: unless-stopped\n\n # Grafana for metrics visualization\n grafana:\n image: grafana/grafana:12.3.1\n ports:\n - \"3000:3000\"\n environment:\n - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:?Set GRAFANA_ADMIN_PASSWORD in .env}\n - GF_USERS_ALLOW_SIGN_UP=false\n - GF_AUTH_ANONYMOUS_ENABLED=false\n volumes:\n - grafana-data:/var/lib/grafana\n - ./config/grafana/dashboards:/etc/grafana/provisioning/dashboards\n - ./config/grafana/datasources:/etc/grafana/provisioning/datasources\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n - prometheus\n restart: unless-stopped\n\n # PostgreSQL database for Keycloak\n keycloak-db:\n image: postgres:16-alpine\n environment:\n POSTGRES_DB: keycloak\n POSTGRES_USER: keycloak\n POSTGRES_PASSWORD: ${KEYCLOAK_DB_PASSWORD:-keycloak}\n volumes:\n - keycloak_db_data:/var/lib/postgresql/data\n restart: unless-stopped\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U keycloak\"]\n interval: 10s\n timeout: 5s\n retries: 5\n\n # Keycloak Identity Provider\n keycloak:\n image: quay.io/keycloak/keycloak:25.0\n command: start-dev # Use 'start' for production with proper SSL\n environment:\n # Database configuration\n KC_DB: postgres\n KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak\n KC_DB_USERNAME: keycloak\n KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD:-keycloak}\n\n # Admin credentials\n KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN:-admin}\n KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}\n\n # HTTP configuration\n KC_HTTP_ENABLED: 'true'\n KC_HTTP_PORT: 8080\n KC_HOSTNAME_STRICT: 'false'\n KC_HOSTNAME_STRICT_HTTPS: 'false'\n KC_PROXY: edge # Running behind nginx\n\n # Frontend URL for external JWT issuer\n # Podman note: host port 8080 is used by the registry UI (8080->80),\n # so Keycloak is exposed on 18080->8080 by default in this Podman compose.\n KC_FRONTEND_URL: ${KEYCLOAK_EXTERNAL_URL:-http://localhost:18080}\n\n # Features\n KC_FEATURES: token-exchange,admin-api\n\n # Logging\n KC_LOG_LEVEL: INFO\n\n # Health endpoints (required for /health/ready)\n KC_HEALTH_ENABLED: 'true'\n \n ports:\n - \"18080:8080\"\n depends_on:\n keycloak-db:\n condition: service_healthy\n volumes:\n - ./keycloak/themes:/opt/keycloak/themes\n - ./keycloak/providers:/opt/keycloak/providers\n - ./keycloak/import:/opt/keycloak/data/import\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health/ready\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 60s\n\n # MongoDB Community Edition 8.2 (alternative to DocumentDB for local development)\n # Vector search is implemented in application code (see search_repository.py)\n # Running without authentication for local development simplicity\n mongodb:\n image: mongo:8.2\n container_name: mcp-mongodb\n command: mongod --replSet rs0 --bind_ip 127.0.0.1,mongodb\n ports:\n - \"27017:27017\"\n volumes:\n - mongodb-data:/data/db\n - mongodb-config:/data/configdb\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n cap_add:\n - SETUID # Required by gosu to switch to mongodb user at startup\n - SETGID # Required by gosu to switch to mongodb group at startup\n - CHOWN # Required by entrypoint to fix /data/db ownership\n - DAC_OVERRIDE # Required by entrypoint to read /data/db before chown\n healthcheck:\n test: [\"CMD\", \"mongosh\", \"--eval\", \"db.adminCommand('ping')\"]\n interval: 60s\n timeout: 5s\n retries: 5\n start_period: 20s\n restart: unless-stopped\n\n # MongoDB initialization (creates replica set, indexes, and loads admin scope)\n mongodb-init:\n image: python:3.14-slim\n container_name: mcp-mongodb-init\n depends_on:\n mongodb:\n condition: service_healthy\n environment:\n - DOCUMENTDB_HOST=mongodb\n - DOCUMENTDB_PORT=27017\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME:-admin}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD:-admin}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - ENTRA_GROUP_ADMIN_ID=${ENTRA_GROUP_ADMIN_ID:-}\n volumes:\n - ./scripts/init-mongodb-ce.py:/app/scripts/init-mongodb-ce.py:ro\n - ./scripts/registry-admins.json:/app/scripts/registry-admins.json:ro\n command: >\n sh -c \"\n pip install --quiet motor pymongo &&\n python /app/scripts/init-mongodb-ce.py\n \"\n restart: \"no\"\n\nvolumes:\n ssl_data:\n keycloak_db_data:\n metrics-db-data:\n prometheus-data:\n grafana-data:\n mongodb-data:\n mongodb-config:\n" }, { "path": "docker-compose.prebuilt.yml", "content": "version: '3.8'\n\n# DocumentDB Initialization:\n# For AWS DocumentDB Elastic Cluster setup, run the initialization script:\n# export DOCUMENTDB_HOST=your-cluster.docdb.amazonaws.com\n# export DOCUMENTDB_USERNAME=admin\n# export DOCUMENTDB_PASSWORD=yourpassword\n# ./scripts/init-documentdb.sh\n#\n# Then set STORAGE_BACKEND=documentdb in your environment and restart services.\n# Note: DocumentDB is a managed AWS service and runs outside of Docker.\n\nservices:\n # Registry service (includes nginx, SSL, FAISS, models) - using pre-built image\n registry:\n image: ${DOCKERHUB_ORG:-mcpgateway}/registry:${REGISTRY_VERSION:-latest}\n environment:\n # Deployment Mode Configuration\n - DEPLOYMENT_MODE=${DEPLOYMENT_MODE:-with-gateway}\n - REGISTRY_MODE=${REGISTRY_MODE:-full}\n # Tab visibility overrides (AND-ed with REGISTRY_MODE)\n - SHOW_SERVERS_TAB=${SHOW_SERVERS_TAB:-true}\n - SHOW_VIRTUAL_SERVERS_TAB=${SHOW_VIRTUAL_SERVERS_TAB:-true}\n - SHOW_SKILLS_TAB=${SHOW_SKILLS_TAB:-true}\n - SHOW_AGENTS_TAB=${SHOW_AGENTS_TAB:-true}\n - GATEWAY_ADDITIONAL_SERVER_NAMES=${GATEWAY_ADDITIONAL_SERVER_NAMES:-}\n # Registry Card Configuration\n - REGISTRY_URL=${REGISTRY_URL:-http://localhost}\n - REGISTRY_NAME=${REGISTRY_NAME:-AI Registry}\n - REGISTRY_ORGANIZATION_NAME=${REGISTRY_ORGANIZATION_NAME:-ACME Inc.}\n - REGISTRY_DESCRIPTION=${REGISTRY_DESCRIPTION:-}\n - REGISTRY_CONTACT_EMAIL=${REGISTRY_CONTACT_EMAIL:-}\n - REGISTRY_CONTACT_URL=${REGISTRY_CONTACT_URL:-}\n - BUILD_VERSION=${BUILD_VERSION:-1.0.0}\n - SECRET_KEY=${SECRET_KEY}\n - AUTH_SERVER_URL=${AUTH_SERVER_URL}\n - AUTH_SERVER_EXTERNAL_URL=${AUTH_SERVER_EXTERNAL_URL}\n - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}\n - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}\n - GITHUB_ENABLED=${GITHUB_ENABLED:-false}\n - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}\n - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}\n - GOOGLE_ENABLED=${GOOGLE_ENABLED:-false}\n - COGNITO_CLIENT_ID=${COGNITO_CLIENT_ID}\n - COGNITO_CLIENT_SECRET=${COGNITO_CLIENT_SECRET}\n - COGNITO_USER_POOL_ID=${COGNITO_USER_POOL_ID}\n - COGNITO_ENABLED=${COGNITO_ENABLED:-false}\n - AWS_REGION=${AWS_REGION:-us-east-1}\n - HEALTH_CHECK_INTERVAL_SECONDS=${HEALTH_CHECK_INTERVAL_SECONDS:-30}\n - SRE_GATEWAY_AUTH_TOKEN=${SRE_GATEWAY_AUTH_TOKEN}\n - ATLASSIAN_AUTH_TOKEN=${ATLASSIAN_AUTH_TOKEN}\n # Metrics configuration\n - METRICS_SERVICE_URL=http://metrics-service:8890\n - METRICS_API_KEY=${METRICS_API_KEY_REGISTRY}\n - METRICS_API_KEY_NGINX=${METRICS_API_KEY_REGISTRY}\n # Keycloak configuration\n - AUTH_PROVIDER=${AUTH_PROVIDER:-cognito}\n - KEYCLOAK_ENABLED=${KEYCLOAK_ENABLED:-false}\n - KEYCLOAK_URL=${KEYCLOAK_URL:-http://keycloak:8080}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-mcp-gateway}\n - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID:-mcp-gateway-web}\n - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}\n - KEYCLOAK_ADMIN=${KEYCLOAK_ADMIN:-admin}\n - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_ADMIN_PASSWORD}\n - KEYCLOAK_M2M_CLIENT_ID=${KEYCLOAK_M2M_CLIENT_ID}\n - KEYCLOAK_M2M_CLIENT_SECRET=${KEYCLOAK_M2M_CLIENT_SECRET}\n # Entra ID configuration\n - ENTRA_TENANT_ID=${ENTRA_TENANT_ID}\n - ENTRA_CLIENT_ID=${ENTRA_CLIENT_ID}\n - ENTRA_CLIENT_SECRET=${ENTRA_CLIENT_SECRET}\n - ENTRA_ENABLED=${ENTRA_ENABLED:-false}\n # External Registry Configuration\n - EXTERNAL_REGISTRY_TAGS=${EXTERNAL_REGISTRY_TAGS:-anthropic-registry,workday-asor}\n - ASOR_ACCESS_TOKEN=${ASOR_ACCESS_TOKEN}\n - ASOR_CLIENT_CREDENTIALS=${ASOR_CLIENT_CREDENTIALS}\n # Security Scanning Configuration\n - SECURITY_SCAN_ENABLED=${SECURITY_SCAN_ENABLED:-true}\n - SECURITY_SCAN_ON_REGISTRATION=${SECURITY_SCAN_ON_REGISTRATION:-true}\n - SECURITY_BLOCK_UNSAFE_SERVERS=${SECURITY_BLOCK_UNSAFE_SERVERS:-true}\n - SECURITY_ANALYZERS=${SECURITY_ANALYZERS:-yara}\n - SECURITY_SCAN_TIMEOUT=${SECURITY_SCAN_TIMEOUT:-60}\n - SECURITY_ADD_PENDING_TAG=${SECURITY_ADD_PENDING_TAG:-true}\n - MCP_SCANNER_LLM_API_KEY=${MCP_SCANNER_LLM_API_KEY}\n # GitHub Private Repository Access (SKILL.md fetching)\n - GITHUB_PAT=${GITHUB_PAT:-}\n - GITHUB_APP_ID=${GITHUB_APP_ID:-}\n - GITHUB_APP_INSTALLATION_ID=${GITHUB_APP_INSTALLATION_ID:-}\n - GITHUB_APP_PRIVATE_KEY=${GITHUB_APP_PRIVATE_KEY:-}\n - GITHUB_EXTRA_HOSTS=${GITHUB_EXTRA_HOSTS:-}\n - GITHUB_API_BASE_URL=${GITHUB_API_BASE_URL:-https://api.github.com}\n # Storage Backend Configuration\n - STORAGE_BACKEND=${STORAGE_BACKEND:-file}\n # DocumentDB/MongoDB Configuration (when STORAGE_BACKEND=documentdb)\n - DOCUMENTDB_HOST=${DOCUMENTDB_HOST:-mongodb}\n - DOCUMENTDB_PORT=${DOCUMENTDB_PORT:-27017}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD}\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - DOCUMENTDB_USE_TLS=${DOCUMENTDB_USE_TLS:-false}\n - DOCUMENTDB_TLS_CA_FILE=${DOCUMENTDB_TLS_CA_FILE:-}\n - DOCUMENTDB_USE_IAM=${DOCUMENTDB_USE_IAM:-false}\n - DOCUMENTDB_REPLICA_SET=${DOCUMENTDB_REPLICA_SET:-rs0}\n - DOCUMENTDB_READ_PREFERENCE=${DOCUMENTDB_READ_PREFERENCE:-secondaryPreferred}\n # Embeddings Configuration\n - EMBEDDINGS_PROVIDER=${EMBEDDINGS_PROVIDER:-sentence-transformers}\n - EMBEDDINGS_MODEL_NAME=${EMBEDDINGS_MODEL_NAME:-all-MiniLM-L6-v2}\n - EMBEDDINGS_MODEL_DIMENSIONS=${EMBEDDINGS_MODEL_DIMENSIONS:-384}\n - EMBEDDINGS_API_KEY=${EMBEDDINGS_API_KEY}\n - EMBEDDINGS_API_BASE=${EMBEDDINGS_API_BASE}\n - EMBEDDINGS_AWS_REGION=${EMBEDDINGS_AWS_REGION:-us-east-1}\n # ANS (Agent Name Service) Configuration\n - ANS_INTEGRATION_ENABLED=${ANS_INTEGRATION_ENABLED:-false}\n - ANS_API_ENDPOINT=${ANS_API_ENDPOINT:-https://api.godaddy.com}\n - ANS_API_KEY=${ANS_API_KEY:-}\n - ANS_API_SECRET=${ANS_API_SECRET:-}\n - ANS_API_TIMEOUT_SECONDS=${ANS_API_TIMEOUT_SECONDS:-30}\n - ANS_SYNC_INTERVAL_HOURS=${ANS_SYNC_INTERVAL_HOURS:-6}\n - ANS_VERIFICATION_CACHE_TTL_SECONDS=${ANS_VERIFICATION_CACHE_TTL_SECONDS:-3600}\n # Federation static token auth\n - FEDERATION_STATIC_TOKEN_AUTH_ENABLED=${FEDERATION_STATIC_TOKEN_AUTH_ENABLED:-false}\n - FEDERATION_STATIC_TOKEN=${FEDERATION_STATIC_TOKEN:-}\n # Auth server config (mirrored for config panel visibility)\n - OAUTH_STORE_TOKENS_IN_SESSION=${OAUTH_STORE_TOKENS_IN_SESSION:-false}\n - REGISTRY_STATIC_TOKEN_AUTH_ENABLED=${REGISTRY_STATIC_TOKEN_AUTH_ENABLED:-false}\n - REGISTRY_API_TOKEN=${REGISTRY_API_TOKEN:-}\n - REGISTRY_API_KEYS=${REGISTRY_API_KEYS:-}\n # Registration Webhook\n - REGISTRATION_WEBHOOK_URL=${REGISTRATION_WEBHOOK_URL:-}\n - REGISTRATION_WEBHOOK_AUTH_HEADER=${REGISTRATION_WEBHOOK_AUTH_HEADER:-Authorization}\n - REGISTRATION_WEBHOOK_AUTH_TOKEN=${REGISTRATION_WEBHOOK_AUTH_TOKEN:-}\n - REGISTRATION_WEBHOOK_TIMEOUT_SECONDS=${REGISTRATION_WEBHOOK_TIMEOUT_SECONDS:-10}\n # Registration Gate (Admission Control)\n - REGISTRATION_GATE_ENABLED=${REGISTRATION_GATE_ENABLED:-false}\n - REGISTRATION_GATE_URL=${REGISTRATION_GATE_URL:-}\n - REGISTRATION_GATE_AUTH_TYPE=${REGISTRATION_GATE_AUTH_TYPE:-none}\n - REGISTRATION_GATE_AUTH_CREDENTIAL=${REGISTRATION_GATE_AUTH_CREDENTIAL:-}\n - REGISTRATION_GATE_AUTH_HEADER_NAME=${REGISTRATION_GATE_AUTH_HEADER_NAME:-X-Api-Key}\n - REGISTRATION_GATE_TIMEOUT_SECONDS=${REGISTRATION_GATE_TIMEOUT_SECONDS:-5}\n - REGISTRATION_GATE_MAX_RETRIES=${REGISTRATION_GATE_MAX_RETRIES:-2}\n # M2M Direct Registration\n - M2M_DIRECT_REGISTRATION_ENABLED=${M2M_DIRECT_REGISTRATION_ENABLED:-true}\n - MAX_TOKENS_PER_USER_PER_HOUR=${MAX_TOKENS_PER_USER_PER_HOUR:-100}\n # Telemetry Configuration\n # Disable all: set MCP_TELEMETRY_DISABLED=1 to disable all telemetry (startup ping + heartbeat)\n # Heartbeat opt-out: set MCP_TELEMETRY_OPT_OUT=1 to disable daily heartbeat only\n # Heartbeat interval: set MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=1440 (default: 1440 = 24h)\n # Endpoint: set TELEMETRY_ENDPOINT= to use a self-hosted collector\n # Debug: set TELEMETRY_DEBUG=true to log payloads without sending\n - MCP_TELEMETRY_DISABLED=${MCP_TELEMETRY_DISABLED:-}\n - MCP_TELEMETRY_OPT_OUT=${MCP_TELEMETRY_OPT_OUT:-}\n - MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=${MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES:-1440}\n - TELEMETRY_DEBUG=${TELEMETRY_DEBUG:-false}\n # Application Log Configuration\n - APP_LOG_MAX_BYTES=${APP_LOG_MAX_BYTES:-52428800}\n - APP_LOG_BACKUP_COUNT=${APP_LOG_BACKUP_COUNT:-5}\n - APP_LOG_CENTRALIZED_ENABLED=${APP_LOG_CENTRALIZED_ENABLED:-true}\n - APP_LOG_CENTRALIZED_TTL_DAYS=${APP_LOG_CENTRALIZED_TTL_DAYS:-1}\n - APP_LOG_MONGODB_BUFFER_SIZE=${APP_LOG_MONGODB_BUFFER_SIZE:-50}\n - APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=${APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS:-5.0}\n - APP_LOG_LEVEL=${APP_LOG_LEVEL:-INFO}\n - APP_LOG_EXCLUDED_LOGGERS=${APP_LOG_EXCLUDED_LOGGERS:-uvicorn.access,httpx,pymongo,motor}\n ports:\n - \"80:8080\" # Map host 80 to container 8080 (non-root nginx)\n - \"443:8443\" # Map host 443 to container 8443 (non-root nginx)\n - \"7860:7860\"\n volumes:\n - ${HOME}/mcp-gateway/servers:/app/registry/servers\n - ${HOME}/mcp-gateway/agents:/app/registry/agents\n - ${HOME}/mcp-gateway/models:/app/registry/models\n - ${HOME}/mcp-gateway/logs:/app/logs\n - ${HOME}/mcp-gateway/security_scans:/app/security_scans\n - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml\n - ${HOME}/mcp-gateway/federation.json:/app/config/federation.json\n - ${HOME}/mcp-gateway/ssl:/etc/ssl:ro\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n auth-server:\n condition: service_started\n metrics-service:\n condition: service_healthy\n mongodb-init:\n condition: service_completed_successfully\n restart: unless-stopped\n\n # Metrics Collection Service - using pre-built image\n metrics-service:\n image: ${DOCKERHUB_ORG:-mcpgateway}/metrics-service:${METRICS_VERSION:-latest}\n environment:\n - METRICS_SERVICE_PORT=8890\n - METRICS_SERVICE_HOST=0.0.0.0\n - SQLITE_DB_PATH=/var/lib/sqlite/metrics.db\n - METRICS_RETENTION_DAYS=90\n - METRICS_API_KEY_AUTH=${METRICS_API_KEY_AUTH_SERVER}\n - METRICS_API_KEY_REGISTRY=${METRICS_API_KEY_REGISTRY}\n - METRICS_API_KEY_MCPGW=${METRICS_API_KEY_MCPGW_SERVER}\n - OTEL_SERVICE_NAME=mcp-metrics-service\n - OTEL_PROMETHEUS_ENABLED=true\n - OTEL_PROMETHEUS_PORT=9465\n - OTEL_OTLP_ENDPOINT=${OTEL_OTLP_ENDPOINT:-}\n - OTEL_EXPORTER_OTLP_HEADERS=${OTEL_EXPORTER_OTLP_HEADERS:-}\n - OTEL_OTLP_EXPORT_INTERVAL_MS=${OTEL_OTLP_EXPORT_INTERVAL_MS:-30000}\n - OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=${OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:-cumulative}\n - METRICS_RATE_LIMIT=1000\n ports:\n - \"8890:8890\"\n - \"9465:9465\" # Prometheus metrics endpoint\n volumes:\n - metrics-db-data:/var/lib/sqlite\n - ${HOME}/mcp-gateway/logs:/app/logs\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n - metrics-db\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8890/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n # Auth service (separate and scalable) - using pre-built image\n auth-server:\n image: ${DOCKERHUB_ORG:-mcpgateway}/auth-server:${AUTH_SERVER_VERSION:-latest}\n environment:\n - REGISTRY_URL=${REGISTRY_URL}\n - SECRET_KEY=${SECRET_KEY}\n - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}\n - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}\n - GITHUB_ENABLED=${GITHUB_ENABLED:-false}\n - COGNITO_CLIENT_ID=${COGNITO_CLIENT_ID}\n - COGNITO_CLIENT_SECRET=${COGNITO_CLIENT_SECRET}\n - COGNITO_USER_POOL_ID=${COGNITO_USER_POOL_ID}\n - COGNITO_DOMAIN=${COGNITO_DOMAIN:-auto}\n - COGNITO_ENABLED=${COGNITO_ENABLED:-false}\n - AWS_REGION=${AWS_REGION:-us-east-1}\n - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}\n - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}\n - GOOGLE_ENABLED=${GOOGLE_ENABLED:-false}\n # Metrics configuration\n - METRICS_SERVICE_URL=http://metrics-service:8890\n - METRICS_API_KEY=${METRICS_API_KEY_AUTH_SERVER}\n # Keycloak configuration\n - AUTH_PROVIDER=${AUTH_PROVIDER:-cognito} # 'cognito' or 'keycloak'\n - KEYCLOAK_ENABLED=${KEYCLOAK_ENABLED:-false}\n - KEYCLOAK_URL=${KEYCLOAK_URL:-http://keycloak:8080}\n - KEYCLOAK_EXTERNAL_URL=${KEYCLOAK_EXTERNAL_URL:-http://localhost:8080}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-mcp-gateway}\n - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID:-mcp-gateway-web}\n - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}\n - KEYCLOAK_M2M_CLIENT_ID=${KEYCLOAK_M2M_CLIENT_ID:-mcp-gateway-m2m}\n - KEYCLOAK_M2M_CLIENT_SECRET=${KEYCLOAK_M2M_CLIENT_SECRET}\n # Entra ID configuration\n - ENTRA_TENANT_ID=${ENTRA_TENANT_ID}\n - ENTRA_CLIENT_ID=${ENTRA_CLIENT_ID}\n - ENTRA_CLIENT_SECRET=${ENTRA_CLIENT_SECRET}\n - ENTRA_ENABLED=${ENTRA_ENABLED:-false}\n # Okta configuration\n - OKTA_DOMAIN=${OKTA_DOMAIN:-}\n - OKTA_CLIENT_ID=${OKTA_CLIENT_ID:-}\n - OKTA_CLIENT_SECRET=${OKTA_CLIENT_SECRET:-}\n - OKTA_M2M_CLIENT_ID=${OKTA_M2M_CLIENT_ID:-}\n - OKTA_M2M_CLIENT_SECRET=${OKTA_M2M_CLIENT_SECRET:-}\n - OKTA_API_TOKEN=${OKTA_API_TOKEN:-}\n - OKTA_AUTH_SERVER_ID=${OKTA_AUTH_SERVER_ID:-}\n # Storage Backend Configuration\n - STORAGE_BACKEND=${STORAGE_BACKEND:-file}\n # DocumentDB/MongoDB Configuration (when STORAGE_BACKEND=documentdb or mongodb-ce)\n - DOCUMENTDB_HOST=${DOCUMENTDB_HOST:-mongodb}\n - DOCUMENTDB_PORT=${DOCUMENTDB_PORT:-27017}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD}\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - DOCUMENTDB_USE_TLS=${DOCUMENTDB_USE_TLS:-false}\n - DOCUMENTDB_TLS_CA_FILE=${DOCUMENTDB_TLS_CA_FILE}\n - DOCUMENTDB_USE_IAM=${DOCUMENTDB_USE_IAM:-false}\n - DOCUMENTDB_REPLICA_SET=${DOCUMENTDB_REPLICA_SET:-rs0}\n - DOCUMENTDB_READ_PREFERENCE=${DOCUMENTDB_READ_PREFERENCE:-secondaryPreferred}\n # Registry API static token auth\n - REGISTRY_STATIC_TOKEN_AUTH_ENABLED=${REGISTRY_STATIC_TOKEN_AUTH_ENABLED:-false}\n - REGISTRY_API_TOKEN=${REGISTRY_API_TOKEN:-}\n - REGISTRY_API_KEYS=${REGISTRY_API_KEYS:-}\n # OAuth token storage in session (set to false for Entra ID large tokens)\n - OAUTH_STORE_TOKENS_IN_SESSION=${OAUTH_STORE_TOKENS_IN_SESSION:-false}\n # Application Log Configuration\n - APP_LOG_MAX_BYTES=${APP_LOG_MAX_BYTES:-52428800}\n - APP_LOG_BACKUP_COUNT=${APP_LOG_BACKUP_COUNT:-5}\n - APP_LOG_CENTRALIZED_ENABLED=${APP_LOG_CENTRALIZED_ENABLED:-true}\n - APP_LOG_CENTRALIZED_TTL_DAYS=${APP_LOG_CENTRALIZED_TTL_DAYS:-1}\n - APP_LOG_MONGODB_BUFFER_SIZE=${APP_LOG_MONGODB_BUFFER_SIZE:-50}\n - APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=${APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS:-5.0}\n - APP_LOG_LEVEL=${APP_LOG_LEVEL:-INFO}\n - APP_LOG_EXCLUDED_LOGGERS=${APP_LOG_EXCLUDED_LOGGERS:-uvicorn.access,httpx,pymongo,motor}\n ports:\n - \"8888:8888\"\n volumes:\n - ${HOME}/mcp-gateway/logs:/app/logs\n # - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/scopes.yml\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n metrics-service:\n condition: service_healthy\n mongodb-init:\n condition: service_completed_successfully\n restart: unless-stopped\n\n # Current Time MCP Server - using pre-built image\n currenttime-server:\n image: ${DOCKERHUB_ORG:-mcpgateway}/currenttime-server:${CURRENTTIME_VERSION:-latest}\n environment:\n - PORT=8000\n - MCP_TRANSPORT=streamable-http\n ports:\n - \"8000:8000\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n restart: unless-stopped\n\n # Financial Info MCP Server - using pre-built image\n fininfo-server:\n image: ${DOCKERHUB_ORG:-mcpgateway}/fininfo-server:${FININFO_VERSION:-latest}\n environment:\n - PORT=8001\n - SECRET_KEY=${SECRET_KEY}\n volumes:\n - ${HOME}/mcp-gateway/secrets/fininfo/:/app/fininfo/\n ports:\n - \"8001:8001\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n restart: unless-stopped\n\n # MCP Gateway Server - using pre-built image\n mcpgw-server:\n image: ${DOCKERHUB_ORG:-mcpgateway}/mcpgw-server:${MCPGW_VERSION:-latest}\n environment:\n - HOST=0.0.0.0\n - PORT=8003\n - REGISTRY_BASE_URL=http://registry:8080\n volumes:\n - ${HOME}/mcp-gateway/servers:/app/registry/servers\n - ${HOME}/mcp-gateway/models:/app/registry/models\n - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml\n ports:\n - \"8003:8003\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n - registry\n restart: unless-stopped\n\n # Real Server Fake Tools MCP Server - using pre-built image\n realserverfaketools-server:\n image: ${DOCKERHUB_ORG:-mcpgateway}/realserverfaketools-server:${REALSERVERFAKETOOLS_VERSION:-latest}\n environment:\n - PORT=8002\n ports:\n - \"8002:8002\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n restart: unless-stopped\n\n # SQLite container for metrics database - using mirrored pre-built image\n metrics-db:\n image: ${DOCKERHUB_ORG:-mcpgateway}/alpine:${ALPINE_VERSION:-latest}\n volumes:\n - metrics-db-data:/var/lib/sqlite\n command: [\"sh\", \"-c\", \"apk add --no-cache sqlite && mkdir -p /var/lib/sqlite && sqlite3 /var/lib/sqlite/metrics.db 'CREATE TABLE IF NOT EXISTS _health (id INTEGER);' && tail -f /dev/null\"]\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"sqlite3\", \"/var/lib/sqlite/metrics.db\", \".tables\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n # Prometheus for metrics collection - using mirrored pre-built image\n prometheus:\n image: ${DOCKERHUB_ORG:-mcpgateway}/prometheus:${PROMETHEUS_VERSION:-latest}\n ports:\n - \"9090:9090\"\n volumes:\n - ./config/prometheus.yml:/etc/prometheus/prometheus.yml\n - prometheus-data:/prometheus\n command:\n - '--config.file=/etc/prometheus/prometheus.yml'\n - '--storage.tsdb.path=/prometheus'\n - '--web.console.libraries=/etc/prometheus/console_libraries'\n - '--web.console.templates=/etc/prometheus/consoles'\n - '--storage.tsdb.retention.time=200h'\n - '--web.enable-lifecycle'\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n restart: unless-stopped\n\n # Grafana for metrics visualization - using mirrored pre-built image\n grafana:\n image: ${DOCKERHUB_ORG:-mcpgateway}/grafana:${GRAFANA_VERSION:-latest}\n ports:\n - \"3000:3000\"\n environment:\n - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:?Set GRAFANA_ADMIN_PASSWORD in .env}\n - GF_USERS_ALLOW_SIGN_UP=false\n - GF_AUTH_ANONYMOUS_ENABLED=false\n volumes:\n - grafana-data:/var/lib/grafana\n - ./config/grafana/dashboards:/etc/grafana/provisioning/dashboards\n - ./config/grafana/datasources:/etc/grafana/provisioning/datasources\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n - prometheus\n restart: unless-stopped\n\n # PostgreSQL database for Keycloak - using mirrored pre-built image\n keycloak-db:\n image: ${DOCKERHUB_ORG:-mcpgateway}/postgres:${POSTGRES_VERSION:-latest}\n environment:\n POSTGRES_DB: keycloak\n POSTGRES_USER: keycloak\n POSTGRES_PASSWORD: ${KEYCLOAK_DB_PASSWORD:-keycloak}\n volumes:\n - keycloak_db_data:/var/lib/postgresql/data\n restart: unless-stopped\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U keycloak\"]\n interval: 10s\n timeout: 5s\n retries: 5\n\n # Keycloak Identity Provider - using mirrored pre-built image\n keycloak:\n image: ${DOCKERHUB_ORG:-mcpgateway}/keycloak:${KEYCLOAK_VERSION:-latest}\n command: start-dev # Use 'start' for production with proper SSL\n environment:\n # Database configuration\n KC_DB: postgres\n KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak\n KC_DB_USERNAME: keycloak\n KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD:-keycloak}\n\n # Admin credentials\n KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN:-admin}\n KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}\n\n # HTTP configuration\n KC_HTTP_ENABLED: 'true'\n KC_HTTP_PORT: 8080\n KC_HOSTNAME_STRICT: 'false'\n KC_HOSTNAME_STRICT_HTTPS: 'false'\n KC_PROXY: edge # Running behind nginx\n\n # Frontend URL for external JWT issuer\n KC_FRONTEND_URL: ${KEYCLOAK_EXTERNAL_URL:-http://localhost:8080}\n\n # Features\n KC_FEATURES: token-exchange,admin-api\n\n # Logging\n KC_LOG_LEVEL: INFO\n\n ports:\n - \"8080:8080\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n keycloak-db:\n condition: service_healthy\n volumes:\n - ./keycloak/themes:/opt/keycloak/themes\n - ./keycloak/providers:/opt/keycloak/providers\n - ./keycloak/import:/opt/keycloak/data/import\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health/ready\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 60s\n\n # MongoDB keyfile initialization (generates keyfile for replica set authentication)\n # This runs once before MongoDB starts to create the keyfile with correct permissions\n mongodb-keyfile-init:\n image: alpine:latest\n container_name: mcp-mongodb-keyfile-init\n volumes:\n - mongodb-keyfile:/keyfile\n command: >\n sh -c \"\n if [ ! -f /keyfile/replica.key ]; then\n echo 'Generating MongoDB keyfile...';\n apk add --no-cache openssl;\n openssl rand -base64 756 > /keyfile/replica.key;\n chmod 400 /keyfile/replica.key;\n chown 999:999 /keyfile/replica.key;\n echo 'Keyfile generated successfully';\n else\n echo 'Keyfile already exists, skipping generation';\n fi\n \"\n restart: \"no\"\n\n # MongoDB Community Edition 8.2 (alternative to DocumentDB for local development)\n # Vector search is implemented in application code (see search_repository.py)\n # Running with authentication enabled for security\n mongodb:\n image: ${DOCKERHUB_ORG:-mcpgateway}/mongo:${MONGODB_VERSION:-latest}\n container_name: mcp-mongodb\n command: mongod --replSet rs0 --bind_ip 127.0.0.1,mongodb --auth --keyFile /keyfile/replica.key\n environment:\n - MONGO_INITDB_ROOT_USERNAME=${DOCUMENTDB_USERNAME:-admin}\n - MONGO_INITDB_ROOT_PASSWORD=${DOCUMENTDB_PASSWORD:-admin}\n ports:\n - \"27017:27017\"\n volumes:\n - mongodb-data:/data/db\n - mongodb-config:/data/configdb\n - mongodb-keyfile:/keyfile:ro\n cap_drop:\n - ALL\n cap_add:\n - SETUID\n - SETGID\n - CHOWN\n - DAC_OVERRIDE\n depends_on:\n mongodb-keyfile-init:\n condition: service_completed_successfully\n healthcheck:\n test: [\"CMD\", \"mongosh\", \"-u\", \"${DOCUMENTDB_USERNAME:-admin}\", \"-p\", \"${DOCUMENTDB_PASSWORD:-admin}\", \"--authenticationDatabase\", \"admin\", \"--eval\", \"db.adminCommand('ping')\"]\n interval: 60s\n timeout: 5s\n retries: 5\n start_period: 30s\n restart: unless-stopped\n\n # MongoDB initialization (creates replica set, indexes, and loads admin scope)\n mongodb-init:\n image: python:3.14-slim\n container_name: mcp-mongodb-init\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n mongodb:\n condition: service_healthy\n environment:\n - DOCUMENTDB_HOST=mongodb\n - DOCUMENTDB_PORT=27017\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME:-admin}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD:-admin}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - ENTRA_GROUP_ADMIN_ID=${ENTRA_GROUP_ADMIN_ID:-}\n volumes:\n - ./scripts/init-mongodb-ce.py:/app/scripts/init-mongodb-ce.py:ro\n - ./scripts/registry-admins.json:/app/scripts/registry-admins.json:ro\n - ./scripts/mcp-registry-admin.json:/app/scripts/mcp-registry-admin.json:ro\n - ./scripts/mcp-servers-unrestricted-read.json:/app/scripts/mcp-servers-unrestricted-read.json:ro\n - ./scripts/mcp-servers-unrestricted-execute.json:/app/scripts/mcp-servers-unrestricted-execute.json:ro\n command: >\n sh -c \"\n pip install --quiet motor pymongo &&\n python /app/scripts/init-mongodb-ce.py\n \"\n restart: \"no\"\n\nvolumes:\n ssl_data:\n keycloak_db_data:\n metrics-db-data:\n prometheus-data:\n grafana-data:\n mongodb-data:\n mongodb-config:\n mongodb-keyfile:\n" }, { "path": "docker-compose.yml", "content": "version: '3.8'\n\n# DocumentDB Initialization:\n# For AWS DocumentDB Elastic Cluster setup, run the initialization script:\n# export DOCUMENTDB_HOST=your-cluster.docdb.amazonaws.com\n# export DOCUMENTDB_USERNAME=admin\n# export DOCUMENTDB_PASSWORD=yourpassword\n# ./scripts/init-documentdb.sh\n#\n# Then set STORAGE_BACKEND=documentdb in your environment and restart services.\n# Note: DocumentDB is a managed AWS service and runs outside of Docker.\n\nservices:\n # MongoDB Community Edition 8.2 (alternative to DocumentDB for local development)\n # Vector search is implemented in application code (see search_repository.py)\n # Running without authentication for local development simplicity\n mongodb:\n image: mongo:8.2\n container_name: mcp-mongodb\n command: mongod --replSet rs0 --bind_ip 127.0.0.1,mongodb\n ports:\n - \"27017:27017\"\n volumes:\n - mongodb-data:/data/db\n - mongodb-config:/data/configdb\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n cap_add:\n - SETUID # Required by gosu to switch to mongodb user at startup\n - SETGID # Required by gosu to switch to mongodb group at startup\n - CHOWN # Required by entrypoint to fix /data/db ownership\n - DAC_OVERRIDE # Required by entrypoint to read /data/db before chown\n healthcheck:\n test: [\"CMD\", \"mongosh\", \"--eval\", \"db.adminCommand('ping')\"]\n interval: 60s\n timeout: 5s\n retries: 5\n start_period: 20s\n restart: unless-stopped\n\n # MongoDB initialization (creates replica set, indexes, and loads admin scope)\n mongodb-init:\n image: python:3.14-slim\n container_name: mcp-mongodb-init\n depends_on:\n mongodb:\n condition: service_healthy\n environment:\n - DOCUMENTDB_HOST=mongodb\n - DOCUMENTDB_PORT=27017\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME:-}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD:-}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - ENTRA_GROUP_ADMIN_ID=${ENTRA_GROUP_ADMIN_ID:-}\n volumes:\n - ./scripts/init-mongodb-ce.py:/app/scripts/init-mongodb-ce.py:ro\n - ./scripts/registry-admins.json:/app/scripts/registry-admins.json:ro\n - ./scripts/mcp-registry-admin.json:/app/scripts/mcp-registry-admin.json:ro\n - ./scripts/mcp-servers-unrestricted-read.json:/app/scripts/mcp-servers-unrestricted-read.json:ro\n - ./scripts/mcp-servers-unrestricted-execute.json:/app/scripts/mcp-servers-unrestricted-execute.json:ro\n command: >\n sh -c \"\n pip install --quiet motor pymongo &&\n python /app/scripts/init-mongodb-ce.py\n \"\n restart: \"no\"\n\n # Registry service (includes nginx, SSL, FAISS, models)\n registry:\n build:\n context: .\n dockerfile: docker/Dockerfile.registry\n args:\n BUILD_VERSION: ${BUILD_VERSION:-1.0.0}\n environment:\n # Deployment Mode Configuration\n - DEPLOYMENT_MODE=${DEPLOYMENT_MODE:-with-gateway}\n - REGISTRY_MODE=${REGISTRY_MODE:-full}\n # Tab visibility overrides (AND-ed with REGISTRY_MODE)\n - SHOW_SERVERS_TAB=${SHOW_SERVERS_TAB:-true}\n - SHOW_VIRTUAL_SERVERS_TAB=${SHOW_VIRTUAL_SERVERS_TAB:-true}\n - SHOW_SKILLS_TAB=${SHOW_SKILLS_TAB:-true}\n - SHOW_AGENTS_TAB=${SHOW_AGENTS_TAB:-true}\n - GATEWAY_ADDITIONAL_SERVER_NAMES=${GATEWAY_ADDITIONAL_SERVER_NAMES:-}\n # Registry Card Configuration\n - REGISTRY_URL=${REGISTRY_URL:-http://localhost}\n - REGISTRY_NAME=${REGISTRY_NAME:-AI Registry}\n - REGISTRY_ORGANIZATION_NAME=${REGISTRY_ORGANIZATION_NAME:-ACME Inc.}\n - REGISTRY_DESCRIPTION=${REGISTRY_DESCRIPTION:-}\n - REGISTRY_CONTACT_EMAIL=${REGISTRY_CONTACT_EMAIL:-}\n - REGISTRY_CONTACT_URL=${REGISTRY_CONTACT_URL:-}\n - SECRET_KEY=${SECRET_KEY}\n - AUTH_SERVER_URL=${AUTH_SERVER_URL}\n - AUTH_SERVER_EXTERNAL_URL=${AUTH_SERVER_EXTERNAL_URL}\n - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}\n - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}\n - GITHUB_ENABLED=${GITHUB_ENABLED:-false}\n - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}\n - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}\n - GOOGLE_ENABLED=${GOOGLE_ENABLED:-false}\n - COGNITO_CLIENT_ID=${COGNITO_CLIENT_ID}\n - COGNITO_CLIENT_SECRET=${COGNITO_CLIENT_SECRET}\n - COGNITO_USER_POOL_ID=${COGNITO_USER_POOL_ID}\n - COGNITO_ENABLED=${COGNITO_ENABLED:-false}\n - AWS_REGION=${AWS_REGION:-us-east-1}\n - HEALTH_CHECK_INTERVAL_SECONDS=${HEALTH_CHECK_INTERVAL_SECONDS:-30}\n - SRE_GATEWAY_AUTH_TOKEN=${SRE_GATEWAY_AUTH_TOKEN}\n - ATLASSIAN_AUTH_TOKEN=${ATLASSIAN_AUTH_TOKEN}\n # Metrics configuration\n - METRICS_SERVICE_URL=http://metrics-service:8890\n - METRICS_API_KEY=${METRICS_API_KEY_REGISTRY}\n - METRICS_API_KEY_NGINX=${METRICS_API_KEY_REGISTRY}\n # Keycloak configuration\n - AUTH_PROVIDER=${AUTH_PROVIDER:-cognito}\n - KEYCLOAK_ENABLED=${KEYCLOAK_ENABLED:-false}\n - KEYCLOAK_URL=${KEYCLOAK_URL:-http://keycloak:8080}\n - KEYCLOAK_EXTERNAL_URL=${KEYCLOAK_EXTERNAL_URL:-http://localhost:8080}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-mcp-gateway}\n - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID:-mcp-gateway-web}\n - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}\n - KEYCLOAK_ADMIN=${KEYCLOAK_ADMIN:-admin}\n - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_ADMIN_PASSWORD}\n - KEYCLOAK_M2M_CLIENT_ID=${KEYCLOAK_M2M_CLIENT_ID}\n - KEYCLOAK_M2M_CLIENT_SECRET=${KEYCLOAK_M2M_CLIENT_SECRET}\n # Entra ID configuration\n - ENTRA_TENANT_ID=${ENTRA_TENANT_ID}\n - ENTRA_CLIENT_ID=${ENTRA_CLIENT_ID}\n - ENTRA_CLIENT_SECRET=${ENTRA_CLIENT_SECRET}\n - ENTRA_ENABLED=${ENTRA_ENABLED:-false}\n # IdP group filtering (applies to all identity providers)\n - IDP_GROUP_FILTER_PREFIX=${IDP_GROUP_FILTER_PREFIX:-}\n # Okta configuration\n - OKTA_DOMAIN=${OKTA_DOMAIN:-}\n - OKTA_CLIENT_ID=${OKTA_CLIENT_ID:-}\n - OKTA_CLIENT_SECRET=${OKTA_CLIENT_SECRET:-}\n - OKTA_M2M_CLIENT_ID=${OKTA_M2M_CLIENT_ID:-}\n - OKTA_M2M_CLIENT_SECRET=${OKTA_M2M_CLIENT_SECRET:-}\n - OKTA_API_TOKEN=${OKTA_API_TOKEN:-}\n - OKTA_AUTH_SERVER_ID=${OKTA_AUTH_SERVER_ID:-}\n # Auth0 configuration\n - AUTH0_DOMAIN=${AUTH0_DOMAIN}\n - AUTH0_CLIENT_ID=${AUTH0_CLIENT_ID}\n - AUTH0_CLIENT_SECRET=${AUTH0_CLIENT_SECRET}\n - AUTH0_AUDIENCE=${AUTH0_AUDIENCE:-}\n - AUTH0_GROUPS_CLAIM=${AUTH0_GROUPS_CLAIM:-https://mcp-gateway/groups}\n - AUTH0_ENABLED=${AUTH0_ENABLED:-false}\n - AUTH0_M2M_CLIENT_ID=${AUTH0_M2M_CLIENT_ID:-}\n - AUTH0_M2M_CLIENT_SECRET=${AUTH0_M2M_CLIENT_SECRET:-}\n # External Registry Configuration\n - EXTERNAL_REGISTRY_TAGS=${EXTERNAL_REGISTRY_TAGS:-anthropic-registry,workday-asor}\n - ASOR_ACCESS_TOKEN=${ASOR_ACCESS_TOKEN}\n - ASOR_CLIENT_CREDENTIALS=${ASOR_CLIENT_CREDENTIALS}\n # Security Scanning Configuration\n - SECURITY_SCAN_ENABLED=${SECURITY_SCAN_ENABLED:-true}\n - SECURITY_SCAN_ON_REGISTRATION=${SECURITY_SCAN_ON_REGISTRATION:-true}\n - SECURITY_BLOCK_UNSAFE_SERVERS=${SECURITY_BLOCK_UNSAFE_SERVERS:-true}\n - SECURITY_ANALYZERS=${SECURITY_ANALYZERS:-yara}\n - SECURITY_SCAN_TIMEOUT=${SECURITY_SCAN_TIMEOUT:-60}\n - SECURITY_ADD_PENDING_TAG=${SECURITY_ADD_PENDING_TAG:-true}\n - MCP_SCANNER_LLM_API_KEY=${MCP_SCANNER_LLM_API_KEY}\n # GitHub Private Repository Access (SKILL.md fetching)\n - GITHUB_PAT=${GITHUB_PAT:-}\n - GITHUB_APP_ID=${GITHUB_APP_ID:-}\n - GITHUB_APP_INSTALLATION_ID=${GITHUB_APP_INSTALLATION_ID:-}\n - GITHUB_APP_PRIVATE_KEY=${GITHUB_APP_PRIVATE_KEY:-}\n - GITHUB_EXTRA_HOSTS=${GITHUB_EXTRA_HOSTS:-}\n - GITHUB_API_BASE_URL=${GITHUB_API_BASE_URL:-https://api.github.com}\n # Storage Backend Configuration\n - STORAGE_BACKEND=${STORAGE_BACKEND:-file}\n # DocumentDB/MongoDB Configuration (when STORAGE_BACKEND=documentdb)\n - DOCUMENTDB_HOST=${DOCUMENTDB_HOST:-mongodb}\n - DOCUMENTDB_PORT=${DOCUMENTDB_PORT:-27017}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD}\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - DOCUMENTDB_USE_TLS=${DOCUMENTDB_USE_TLS:-false}\n - DOCUMENTDB_TLS_CA_FILE=${DOCUMENTDB_TLS_CA_FILE:-}\n - DOCUMENTDB_USE_IAM=${DOCUMENTDB_USE_IAM:-false}\n - DOCUMENTDB_REPLICA_SET=${DOCUMENTDB_REPLICA_SET:-rs0}\n - DOCUMENTDB_READ_PREFERENCE=${DOCUMENTDB_READ_PREFERENCE:-secondaryPreferred}\n # Embeddings Configuration\n - EMBEDDINGS_PROVIDER=${EMBEDDINGS_PROVIDER:-sentence-transformers}\n - EMBEDDINGS_MODEL_NAME=${EMBEDDINGS_MODEL_NAME:-all-MiniLM-L6-v2}\n - EMBEDDINGS_MODEL_DIMENSIONS=${EMBEDDINGS_MODEL_DIMENSIONS:-384}\n - EMBEDDINGS_API_KEY=${EMBEDDINGS_API_KEY}\n - EMBEDDINGS_API_BASE=${EMBEDDINGS_API_BASE}\n - EMBEDDINGS_AWS_REGION=${EMBEDDINGS_AWS_REGION:-us-east-1}\n # ANS (Agent Name Service) Configuration\n - ANS_INTEGRATION_ENABLED=${ANS_INTEGRATION_ENABLED:-false}\n - ANS_API_ENDPOINT=${ANS_API_ENDPOINT:-https://api.godaddy.com}\n - ANS_API_KEY=${ANS_API_KEY:-}\n - ANS_API_SECRET=${ANS_API_SECRET:-}\n - ANS_API_TIMEOUT_SECONDS=${ANS_API_TIMEOUT_SECONDS:-30}\n - ANS_SYNC_INTERVAL_HOURS=${ANS_SYNC_INTERVAL_HOURS:-6}\n - ANS_VERIFICATION_CACHE_TTL_SECONDS=${ANS_VERIFICATION_CACHE_TTL_SECONDS:-3600}\n # Federation Peer Sync Configuration\n - FEDERATION_TOKEN_ENDPOINT=${FEDERATION_TOKEN_ENDPOINT}\n - FEDERATION_CLIENT_ID=${FEDERATION_CLIENT_ID}\n - FEDERATION_CLIENT_SECRET=${FEDERATION_CLIENT_SECRET}\n # Federation Token Encryption (for encrypting federation_token before storage)\n - FEDERATION_ENCRYPTION_KEY=${FEDERATION_ENCRYPTION_KEY:-}\n # Federation static token auth\n - FEDERATION_STATIC_TOKEN_AUTH_ENABLED=${FEDERATION_STATIC_TOKEN_AUTH_ENABLED:-false}\n - FEDERATION_STATIC_TOKEN=${FEDERATION_STATIC_TOKEN:-}\n # Auth server config (mirrored for config panel visibility)\n - OAUTH_STORE_TOKENS_IN_SESSION=${OAUTH_STORE_TOKENS_IN_SESSION:-false}\n - REGISTRY_STATIC_TOKEN_AUTH_ENABLED=${REGISTRY_STATIC_TOKEN_AUTH_ENABLED:-false}\n - REGISTRY_API_TOKEN=${REGISTRY_API_TOKEN:-}\n - REGISTRY_API_KEYS=${REGISTRY_API_KEYS:-}\n # Registration Webhook\n - REGISTRATION_WEBHOOK_URL=${REGISTRATION_WEBHOOK_URL:-}\n - REGISTRATION_WEBHOOK_AUTH_HEADER=${REGISTRATION_WEBHOOK_AUTH_HEADER:-Authorization}\n - REGISTRATION_WEBHOOK_AUTH_TOKEN=${REGISTRATION_WEBHOOK_AUTH_TOKEN:-}\n - REGISTRATION_WEBHOOK_TIMEOUT_SECONDS=${REGISTRATION_WEBHOOK_TIMEOUT_SECONDS:-10}\n # Registration Gate (Admission Control)\n - REGISTRATION_GATE_ENABLED=${REGISTRATION_GATE_ENABLED:-false}\n - REGISTRATION_GATE_URL=${REGISTRATION_GATE_URL:-}\n - REGISTRATION_GATE_AUTH_TYPE=${REGISTRATION_GATE_AUTH_TYPE:-none}\n - REGISTRATION_GATE_AUTH_CREDENTIAL=${REGISTRATION_GATE_AUTH_CREDENTIAL:-}\n - REGISTRATION_GATE_AUTH_HEADER_NAME=${REGISTRATION_GATE_AUTH_HEADER_NAME:-X-Api-Key}\n - REGISTRATION_GATE_TIMEOUT_SECONDS=${REGISTRATION_GATE_TIMEOUT_SECONDS:-5}\n - REGISTRATION_GATE_MAX_RETRIES=${REGISTRATION_GATE_MAX_RETRIES:-2}\n # M2M Direct Registration\n - M2M_DIRECT_REGISTRATION_ENABLED=${M2M_DIRECT_REGISTRATION_ENABLED:-true}\n - MAX_TOKENS_PER_USER_PER_HOUR=${MAX_TOKENS_PER_USER_PER_HOUR:-100}\n # OpenTelemetry / OTLP (mirrored for config panel visibility)\n - OTEL_OTLP_ENDPOINT=${OTEL_OTLP_ENDPOINT:-}\n - OTEL_OTLP_EXPORT_INTERVAL_MS=${OTEL_OTLP_EXPORT_INTERVAL_MS:-30000}\n - OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=${OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:-cumulative}\n # Telemetry Configuration\n # Disable all: set MCP_TELEMETRY_DISABLED=1 to disable all telemetry (startup ping + heartbeat)\n # Heartbeat opt-out: set MCP_TELEMETRY_OPT_OUT=1 to disable daily heartbeat only\n # Heartbeat interval: set MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=1440 (default: 1440 = 24h)\n # Endpoint: set TELEMETRY_ENDPOINT= to use a self-hosted collector\n # Debug: set TELEMETRY_DEBUG=true to log payloads without sending\n - MCP_TELEMETRY_DISABLED=${MCP_TELEMETRY_DISABLED:-}\n - MCP_TELEMETRY_OPT_OUT=${MCP_TELEMETRY_OPT_OUT:-}\n - MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=${MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES:-1440}\n - TELEMETRY_DEBUG=${TELEMETRY_DEBUG:-false}\n - DISABLE_AI_REGISTRY_TOOLS_SERVER=${DISABLE_AI_REGISTRY_TOOLS_SERVER:-false}\n # Application Log Configuration (Issue #886)\n - APP_LOG_MAX_BYTES=${APP_LOG_MAX_BYTES:-52428800}\n - APP_LOG_BACKUP_COUNT=${APP_LOG_BACKUP_COUNT:-5}\n - APP_LOG_CENTRALIZED_ENABLED=${APP_LOG_CENTRALIZED_ENABLED:-true}\n - APP_LOG_CENTRALIZED_TTL_DAYS=${APP_LOG_CENTRALIZED_TTL_DAYS:-1}\n - APP_LOG_MONGODB_BUFFER_SIZE=${APP_LOG_MONGODB_BUFFER_SIZE:-50}\n - APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=${APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS:-5.0}\n - APP_LOG_LEVEL=${APP_LOG_LEVEL:-INFO}\n - APP_LOG_EXCLUDED_LOGGERS=${APP_LOG_EXCLUDED_LOGGERS:-uvicorn.access,httpx,pymongo,motor}\n ports:\n - \"80:8080\" # Map host 80 to container 8080 (non-root nginx)\n - \"443:8443\" # Map host 443 to container 8443 (non-root nginx)\n - \"7860:7860\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n volumes:\n # User-managed content (bind mounts)\n - ${HOME}/mcp-gateway/servers:/app/registry/servers\n - ${HOME}/mcp-gateway/agents:/app/registry/agents\n - ${HOME}/mcp-gateway/models:/app/registry/models\n - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml\n - ${HOME}/mcp-gateway/federation.json:/app/config/federation.json\n - ${HOME}/mcp-gateway/ssl:/etc/ssl:ro\n - ${HOME}/.aws:/root/.aws:ro\n # Application-managed (named volumes with proper permissions)\n - registry-logs:/app/logs\n - registry-scans:/app/security_scans\n depends_on:\n auth-server:\n condition: service_started\n metrics-service:\n condition: service_healthy\n mongodb-init:\n condition: service_completed_successfully\n restart: unless-stopped\n\n # Metrics Collection Service\n metrics-service:\n build:\n context: metrics-service\n dockerfile: Dockerfile\n environment:\n - METRICS_SERVICE_PORT=8890\n - METRICS_SERVICE_HOST=0.0.0.0\n - SQLITE_DB_PATH=/var/lib/sqlite/metrics.db\n - METRICS_RETENTION_DAYS=90\n - METRICS_API_KEY_AUTH=${METRICS_API_KEY_AUTH_SERVER}\n - METRICS_API_KEY_REGISTRY=${METRICS_API_KEY_REGISTRY}\n - METRICS_API_KEY_MCPGW=${METRICS_API_KEY_MCPGW_SERVER}\n - OTEL_SERVICE_NAME=mcp-metrics-service\n - OTEL_PROMETHEUS_ENABLED=true\n - OTEL_PROMETHEUS_PORT=9465\n - METRICS_RATE_LIMIT=1000\n - OTEL_OTLP_ENDPOINT=${OTEL_OTLP_ENDPOINT:-}\n - OTEL_EXPORTER_OTLP_HEADERS=${OTEL_EXPORTER_OTLP_HEADERS:-}\n - OTEL_OTLP_EXPORT_INTERVAL_MS=${OTEL_OTLP_EXPORT_INTERVAL_MS:-30000}\n - OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=${OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:-cumulative}\n ports:\n - \"8890:8890\"\n - \"9465:9465\" # Prometheus metrics endpoint\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n volumes:\n - metrics-db-data:/var/lib/sqlite\n # Application-managed (named volume with proper permissions)\n - metrics-logs:/app/logs\n depends_on:\n - metrics-db\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8890/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n # Auth service (separate and scalable)\n auth-server:\n build:\n context: .\n dockerfile: docker/Dockerfile.auth\n environment:\n # Registry Configuration\n - REGISTRY_URL=${REGISTRY_URL:-http://localhost}\n - REGISTRY_NAME=${REGISTRY_NAME:-AI Registry}\n - REGISTRY_ORGANIZATION_NAME=${REGISTRY_ORGANIZATION_NAME:-ACME Inc.}\n - AUTH_SERVER_EXTERNAL_URL=${AUTH_SERVER_EXTERNAL_URL:-http://localhost:8888}\n - SECRET_KEY=${SECRET_KEY}\n - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}\n - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}\n - GITHUB_ENABLED=${GITHUB_ENABLED:-false}\n - COGNITO_CLIENT_ID=${COGNITO_CLIENT_ID}\n - COGNITO_CLIENT_SECRET=${COGNITO_CLIENT_SECRET}\n - COGNITO_USER_POOL_ID=${COGNITO_USER_POOL_ID}\n - COGNITO_DOMAIN=${COGNITO_DOMAIN:-auto}\n - COGNITO_ENABLED=${COGNITO_ENABLED:-false}\n - AWS_REGION=${AWS_REGION:-us-east-1}\n - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}\n - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}\n - GOOGLE_ENABLED=${GOOGLE_ENABLED:-false}\n # Metrics configuration\n - METRICS_SERVICE_URL=http://metrics-service:8890\n - METRICS_API_KEY=${METRICS_API_KEY_AUTH_SERVER}\n # Keycloak configuration\n - AUTH_PROVIDER=${AUTH_PROVIDER:-cognito} # 'cognito' or 'keycloak'\n - KEYCLOAK_ENABLED=${KEYCLOAK_ENABLED:-true} # Enable Keycloak by default\n - KEYCLOAK_URL=${KEYCLOAK_URL:-http://keycloak:8080}\n - KEYCLOAK_EXTERNAL_URL=${KEYCLOAK_EXTERNAL_URL:-http://localhost:8080}\n - KEYCLOAK_REALM=${KEYCLOAK_REALM:-mcp-gateway}\n - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID:-mcp-gateway-web}\n - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}\n - KEYCLOAK_M2M_CLIENT_ID=${KEYCLOAK_M2M_CLIENT_ID:-mcp-gateway-m2m}\n - KEYCLOAK_M2M_CLIENT_SECRET=${KEYCLOAK_M2M_CLIENT_SECRET}\n # Entra ID configuration\n - ENTRA_TENANT_ID=${ENTRA_TENANT_ID}\n - ENTRA_CLIENT_ID=${ENTRA_CLIENT_ID}\n - ENTRA_CLIENT_SECRET=${ENTRA_CLIENT_SECRET}\n - ENTRA_ENABLED=${ENTRA_ENABLED:-false}\n # IdP group filtering (applies to all identity providers)\n - IDP_GROUP_FILTER_PREFIX=${IDP_GROUP_FILTER_PREFIX:-}\n # Okta configuration\n - OKTA_DOMAIN=${OKTA_DOMAIN:-}\n - OKTA_CLIENT_ID=${OKTA_CLIENT_ID:-}\n - OKTA_CLIENT_SECRET=${OKTA_CLIENT_SECRET:-}\n - OKTA_M2M_CLIENT_ID=${OKTA_M2M_CLIENT_ID:-}\n - OKTA_M2M_CLIENT_SECRET=${OKTA_M2M_CLIENT_SECRET:-}\n - OKTA_API_TOKEN=${OKTA_API_TOKEN:-}\n - OKTA_AUTH_SERVER_ID=${OKTA_AUTH_SERVER_ID:-}\n # Auth0 configuration\n - AUTH0_DOMAIN=${AUTH0_DOMAIN}\n - AUTH0_CLIENT_ID=${AUTH0_CLIENT_ID}\n - AUTH0_CLIENT_SECRET=${AUTH0_CLIENT_SECRET}\n - AUTH0_AUDIENCE=${AUTH0_AUDIENCE:-}\n - AUTH0_GROUPS_CLAIM=${AUTH0_GROUPS_CLAIM:-https://mcp-gateway/groups}\n - AUTH0_ENABLED=${AUTH0_ENABLED:-false}\n - AUTH0_M2M_CLIENT_ID=${AUTH0_M2M_CLIENT_ID:-}\n - AUTH0_M2M_CLIENT_SECRET=${AUTH0_M2M_CLIENT_SECRET:-}\n # Storage Backend Configuration\n - STORAGE_BACKEND=${STORAGE_BACKEND:-file}\n # DocumentDB/MongoDB Configuration (when STORAGE_BACKEND=documentdb or mongodb-ce)\n - DOCUMENTDB_HOST=${DOCUMENTDB_HOST:-mongodb}\n - DOCUMENTDB_PORT=${DOCUMENTDB_PORT:-27017}\n - DOCUMENTDB_USERNAME=${DOCUMENTDB_USERNAME}\n - DOCUMENTDB_PASSWORD=${DOCUMENTDB_PASSWORD}\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n - DOCUMENTDB_USE_TLS=${DOCUMENTDB_USE_TLS:-false}\n - DOCUMENTDB_TLS_CA_FILE=${DOCUMENTDB_TLS_CA_FILE}\n - DOCUMENTDB_USE_IAM=${DOCUMENTDB_USE_IAM:-false}\n - DOCUMENTDB_REPLICA_SET=${DOCUMENTDB_REPLICA_SET:-rs0}\n - DOCUMENTDB_READ_PREFERENCE=${DOCUMENTDB_READ_PREFERENCE:-secondaryPreferred}\n # Registry API static token auth (IdP-independent access)\n - REGISTRY_STATIC_TOKEN_AUTH_ENABLED=${REGISTRY_STATIC_TOKEN_AUTH_ENABLED:-false}\n - REGISTRY_API_TOKEN=${REGISTRY_API_TOKEN:-}\n - REGISTRY_API_KEYS=${REGISTRY_API_KEYS:-}\n # Federation static token auth (scoped access for peer registries)\n - FEDERATION_STATIC_TOKEN_AUTH_ENABLED=${FEDERATION_STATIC_TOKEN_AUTH_ENABLED:-false}\n - FEDERATION_STATIC_TOKEN=${FEDERATION_STATIC_TOKEN:-}\n # OAuth token storage in session (set to false for Entra ID large tokens)\n - OAUTH_STORE_TOKENS_IN_SESSION=${OAUTH_STORE_TOKENS_IN_SESSION:-false}\n # Application Log Configuration (Issue #886)\n - APP_LOG_MAX_BYTES=${APP_LOG_MAX_BYTES:-52428800}\n - APP_LOG_BACKUP_COUNT=${APP_LOG_BACKUP_COUNT:-5}\n - APP_LOG_CENTRALIZED_ENABLED=${APP_LOG_CENTRALIZED_ENABLED:-true}\n - APP_LOG_CENTRALIZED_TTL_DAYS=${APP_LOG_CENTRALIZED_TTL_DAYS:-1}\n - APP_LOG_MONGODB_BUFFER_SIZE=${APP_LOG_MONGODB_BUFFER_SIZE:-50}\n - APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=${APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS:-5.0}\n - APP_LOG_LEVEL=${APP_LOG_LEVEL:-INFO}\n - APP_LOG_EXCLUDED_LOGGERS=${APP_LOG_EXCLUDED_LOGGERS:-uvicorn.access,httpx,pymongo,motor}\n ports:\n - \"8888:8888\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n volumes:\n # Application-managed (named volume with proper permissions)\n - auth-logs:/app/logs\n # - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/scopes.yml\n depends_on:\n metrics-service:\n condition: service_healthy\n mongodb-init:\n condition: service_completed_successfully\n restart: unless-stopped\n\n # Current Time MCP Server\n currenttime-server:\n build:\n context: .\n dockerfile: docker/Dockerfile.mcp-server-light\n args:\n SERVER_DIR: servers/currenttime\n environment:\n - HOST=0.0.0.0\n - PORT=8000\n - MCP_TRANSPORT=streamable-http\n ports:\n - \"8000:8000\"\n restart: unless-stopped\n\n # Financial Info MCP Server\n fininfo-server:\n build:\n context: .\n dockerfile: docker/Dockerfile.mcp-server-light\n args:\n SERVER_DIR: servers/fininfo\n environment:\n - PORT=8001\n - SECRET_KEY=${SECRET_KEY}\n volumes:\n - ${HOME}/mcp-gateway/secrets/fininfo/:/app/fininfo/\n ports:\n - \"8001:8001\"\n restart: unless-stopped\n\n # MCP Gateway Server\n mcpgw-server:\n build:\n context: .\n dockerfile: docker/Dockerfile.mcp-server\n args:\n SERVER_DIR: servers/mcpgw\n environment:\n - HOST=0.0.0.0\n - PORT=8003\n - REGISTRY_BASE_URL=http://registry:8080\n volumes:\n - ${HOME}/mcp-gateway/servers:/app/registry/servers\n - ${HOME}/mcp-gateway/models:/app/registry/models\n - ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml\n ports:\n - \"8003:8003\"\n depends_on:\n - registry\n restart: unless-stopped\n\n # Real Server Fake Tools MCP Server\n realserverfaketools-server:\n build:\n context: .\n dockerfile: docker/Dockerfile.mcp-server-light\n args:\n SERVER_DIR: servers/realserverfaketools\n environment:\n - PORT=8002\n ports:\n - \"8002:8002\"\n restart: unless-stopped\n\n # SQLite container for metrics database\n metrics-db:\n build:\n context: .\n dockerfile: docker/Dockerfile.metrics-db\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n volumes:\n - metrics-db-data:/var/lib/sqlite\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"sqlite3\", \"/var/lib/sqlite/metrics.db\", \".tables\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n # Prometheus for metrics collection\n prometheus:\n image: prom/prometheus:latest\n ports:\n - \"9090:9090\"\n volumes:\n - ./config/prometheus.yml:/etc/prometheus/prometheus.yml\n - prometheus-data:/prometheus\n command:\n - '--config.file=/etc/prometheus/prometheus.yml'\n - '--storage.tsdb.path=/prometheus'\n - '--web.console.libraries=/etc/prometheus/console_libraries'\n - '--web.console.templates=/etc/prometheus/consoles'\n - '--storage.tsdb.retention.time=200h'\n - '--web.enable-lifecycle'\n restart: unless-stopped\n\n # Grafana for metrics visualization\n grafana:\n image: grafana/grafana:12.3.1\n ports:\n - \"3000:3000\"\n environment:\n - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:?Set GRAFANA_ADMIN_PASSWORD in .env}\n - GF_USERS_ALLOW_SIGN_UP=false\n - GF_AUTH_ANONYMOUS_ENABLED=false\n volumes:\n - grafana-data:/var/lib/grafana\n - ./config/grafana/dashboards:/etc/grafana/provisioning/dashboards\n - ./config/grafana/datasources:/etc/grafana/provisioning/datasources\n depends_on:\n - prometheus\n restart: unless-stopped\n\n # PostgreSQL database for Keycloak\n keycloak-db:\n image: postgres:16-alpine\n environment:\n POSTGRES_DB: keycloak\n POSTGRES_USER: keycloak\n POSTGRES_PASSWORD: ${KEYCLOAK_DB_PASSWORD:-keycloak}\n volumes:\n - keycloak_db_data:/var/lib/postgresql/data\n restart: unless-stopped\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U keycloak\"]\n interval: 10s\n timeout: 5s\n retries: 5\n\n # Keycloak Identity Provider\n keycloak:\n image: quay.io/keycloak/keycloak:25.0\n command: start-dev # Use 'start' for production with proper SSL\n environment:\n # Database configuration\n KC_DB: postgres\n KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak\n KC_DB_USERNAME: keycloak\n KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD:-keycloak}\n\n # Admin credentials\n KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN:-admin}\n KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}\n\n # HTTP configuration\n KC_HTTP_ENABLED: 'true'\n KC_HTTP_PORT: 8080\n KC_HOSTNAME_STRICT: 'false'\n KC_HOSTNAME_STRICT_HTTPS: 'false'\n KC_PROXY: edge # Running behind nginx\n\n # Frontend URL for external JWT issuer\n KC_FRONTEND_URL: ${KEYCLOAK_EXTERNAL_URL:-http://localhost:8080}\n\n # Features\n KC_FEATURES: token-exchange,admin-api\n\n # Logging\n KC_LOG_LEVEL: INFO\n \n ports:\n - \"8080:8080\"\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n depends_on:\n keycloak-db:\n condition: service_healthy\n volumes:\n - ./keycloak/themes:/opt/keycloak/themes\n - ./keycloak/providers:/opt/keycloak/providers\n - ./keycloak/import:/opt/keycloak/data/import\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health/ready\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 60s\n\nvolumes:\n ssl_data:\n keycloak_db_data:\n metrics-db-data:\n prometheus-data:\n grafana-data:\n mongodb-data:\n mongodb-config:\n # Application logs and scans (managed by containers, proper permissions)\n registry-logs:\n registry-scans:\n auth-logs:\n metrics-logs:\n" }, { "path": "docs/FEATURES.md", "content": "# MCP Gateway & Registry - Feature Overview\n\nThis document provides a comprehensive overview of the MCP Gateway & Registry solution capabilities, designed for stakeholder presentations, marketing materials, and solution demonstrations.\n\n## Core Problem Solved\n- **Multi-Platform AI Tool Integration**: Unified gateway for accessing tools across different MCP servers, eliminating the need to manage multiple connections and authentication schemes\n- **Centralized Tool Catalog**: Registry acts as a comprehensive catalog of available tools for developers, AI agents, and knowledge workers\n- **Dynamic Tool Discovery**: Intelligent routing based on natural language queries and semantic matching, reducing configuration overhead\n\n## Registry & Management\n- **Centralized Server Registry**: MongoDB/DocumentDB-backed configuration for all MCP servers and their capabilities\n- **Dynamic Tool Catalog**: Real-time discovery of available tools across registered servers\n- **MCP Server Version Routing**: Run multiple versions of the same server behind a single gateway endpoint with instant rollback, version pinning, and deprecation lifecycle\n- **Custom Metadata**: Add rich custom metadata to servers and agents for organization, compliance, and integration tracking, fully searchable via semantic search\n- **Server & Agent Rating System**: 5-star rating widget with aggregate scoring, one rating per user, and rotating buffer\n- **Health Monitoring**: Built-in health checks and status monitoring for all registered services\n- **Scalable Architecture**: Docker-based deployment with horizontal scaling support\n\n## Agent Registry & A2A Communication\n- **A2A Protocol Support**: Agent registration, discovery, and direct agent-to-agent communication\n- **Agent Security Scanning**: Integrated scanning using Cisco AI Defense A2A Scanner with YARA pattern matching and heuristic threat detection\n- **Agent Discovery API**: Semantic search API for dynamic agent composition at runtime\n- **Agent Cards & Metadata**: Rich metadata for agent capabilities, skills, and authentication schemes\n\n## Authentication & Security\n- **Multi-Provider OAuth 2.0/OIDC Support**: Keycloak, Microsoft Entra ID, AWS Cognito integration\n- **Multi-Provider IAM**: Harmonized API for user and group management across identity providers\n- **Static Token Auth**: IdP-independent API access for Registry endpoints using static API keys, designed for CI/CD pipelines and trusted network environments\n- **Enterprise SSO Ready**: Seamless integration with existing identity providers including Microsoft Entra ID\n- **Service Principal Support**: M2M service accounts with OAuth2 Client Credentials flow for AI agent identity\n- **Fine-Grained Access Control**: Scopes define which MCP servers, methods, tools, and agents each user can access\n- **Self-Signed JWT Tokens**: Human users can generate tokens for CLI tools and AI coding assistants\n- **Secure Token Management**: OAuth token refresh and validation with centralized session management\n- **MCP Server Security Scanning**: Integrated vulnerability scanning with Cisco AI Defense MCP Scanner\n- **Compliance Audit Logging**: Comprehensive audit logs for all API and MCP access events with TTL-based retention, credential masking, and admin UI for compliance monitoring\n\n## Intelligent Tool Discovery\n- **Hybrid Search**: Combined vector similarity with tokenized keyword matching for servers, tools, and agents\n- **Semantic Search**: HNSW vector search using sentence transformers or LiteLLM-supported providers\n- **Unified Search**: Single endpoint searches across MCP servers, tools, and A2A agents\n- **Tag-Based Filtering**: Multi-tag filtering with AND logic for precise tool selection\n- **Flexible Embeddings**: Local sentence-transformers, OpenAI, Amazon Bedrock Titan, or any LiteLLM-supported provider\n- **Performance Optimized**: Configurable result limits and caching for fast response times\n\n## Developer Experience\n- **MCP Registry CLI**: Claude Code-like conversational interface for registry management with real-time token status and cost tracking\n- **Registry Management API**: Programmatic API for managing servers, groups, and users with Python client\n- **Multiple Client Libraries**: Python agent with extensible authentication\n- **Comprehensive Documentation**: Setup guides, API documentation, and integration examples\n- **Testing Framework**: 850+ pytest tests (unit, integration, E2E) with GitHub Actions CI\n- **Development Tools**: Docker Compose for local development and testing\n\n## Federation & External Registries\n- **Peer-to-Peer Registry Federation**: Connect MCP Gateway Registry instances for bidirectional server and agent sync with static token or OAuth2 authentication\n- **Federation UI**: VS Code-style Settings page for managing peer registries, sync modes (all, whitelist, tag filter), and monitoring sync status\n- **Federated Registry**: Import servers and agents from external registries\n- **Anthropic MCP Registry**: Import curated MCP servers with API compatibility\n- **Workday ASOR**: Import AI agents from Agent System of Record\n- **Automatic Sync**: Scheduled synchronization with external registries and peer registries\n- **Amazon Bedrock AgentCore**: Gateway support with dual authentication\n\n## Enterprise Integration\n- **Container-Ready Deployment**: Docker Hub images with pre-built containers\n- **AWS ECS Production Deployment**: Multi-AZ Fargate deployment with ALB, auto-scaling, CloudWatch, and Terraform\n- **Flexible Deployment Modes**: CloudFront Only, Custom Domain with Route53/ACM, or CloudFront + Custom Domain\n- **Reverse Proxy Architecture**: Nginx-based ingress with SSL termination\n- **DocumentDB & MongoDB CE Storage**: Distributed storage with HNSW vector search\n- **Real-Time Metrics & Observability**: Grafana dashboards with SQLite and OpenTelemetry integration\n- **Configuration Management**: Environment-based configuration with validation\n\n## Technical Specifications\n- **Protocol Compliance**: Full MCP (Model Context Protocol) specification support\n- **A2A Protocol**: Agent-to-Agent protocol support for autonomous agent ecosystems\n- **High Performance**: Async/await architecture with concurrent request handling\n- **Extensible Design**: Plugin architecture for custom authentication providers\n- **Cross-Platform**: Linux, macOS, Windows support with consistent APIs\n\n## Deployment Options\n- **Pre-built Images**: Deploy instantly with Docker Hub images\n- **Quick Start**: Docker Compose setup in minutes\n- **AWS ECS Fargate**: Production deployment with Terraform\n- **Cloud Native**: Kubernetes manifests and cloud deployment guides\n- **Local Development**: MongoDB CE with full-featured local development\n- **Podman Support**: Rootless container deployment for macOS and Linux\n\n## Use Cases Supported\n- **AI Agent Orchestration**: Centralized tool access for autonomous agents\n- **Agent-to-Agent Communication**: Direct peer-to-peer agent communication through unified registry\n- **CI/CD Integration**: Static token auth for automated pipelines without IdP dependency\n- **Enterprise Tool Consolidation**: Single gateway for diverse internal tools\n- **Development Team Productivity**: Unified interface for developer tools and services\n- **Research & Analytics**: Streamlined access to data processing and analysis tools\n- **Customer Support**: Integrated access to support tools and knowledge bases\n\n## Competitive Advantages\n- **Zero Vendor Lock-in**: Open architecture supporting any MCP-compliant server\n- **Unified Agent & Server Registry**: Single control plane for both MCP servers and AI agents\n- **Minimal Configuration**: Automatic tool discovery reduces setup complexity\n- **Enterprise Security**: Authentication and authorization with multiple IdP support\n- **Developer Friendly**: Clear APIs, CLI tools, and comprehensive documentation\n- **Cost Effective**: Reduces integration overhead and maintenance complexity\n" }, { "path": "docs/OBSERVABILITY.md", "content": "# MCP Gateway Observability Guide\n\nThis guide covers how to access and query metrics collected by the MCP Gateway metrics service.\n\n## Table of Contents\n\n- [Architecture Overview](#architecture-overview)\n- [Accessing Metrics](#accessing-metrics)\n- [SQLite Database Queries](#sqlite-database-queries)\n- [OpenTelemetry Metrics](#opentelemetry-metrics)\n- [Configuring OpenTelemetry Collector](#configuring-opentelemetry-collector)\n- [Grafana Dashboards](#grafana-dashboards)\n\n## Architecture Overview\n\nThe MCP Gateway collects comprehensive metrics through a dual-path observability system:\n\n1. **SQLite Storage**: All metrics are stored in specialized database tables for detailed querying and analysis\n2. **OpenTelemetry Export**: Metrics are simultaneously exported to OpenTelemetry for real-time monitoring via Prometheus and Grafana\n\n### Metrics Collection Flow\n\n```\nAuth Server Middleware → Metrics Service API → Dual Path:\n ├─> SQLite Database (detailed storage)\n └─> OpenTelemetry (Prometheus/Grafana)\n```\n\n### Database Tables\n\n- **`auth_metrics`**: Authentication requests and validation\n- **`tool_metrics`**: Tool execution details (calls, methods, client info)\n- **`discovery_metrics`**: Tool discovery/search queries\n- **`metrics`**: Raw metrics data (all types)\n- **`api_keys`**: API key management for metrics service\n\n## Accessing Metrics\n\n### Access SQLite Database\n\nThe metrics database is stored in a Docker volume and accessed via the `metrics-db` container:\n\n```bash\n# Connect to the metrics-db container\ndocker compose exec metrics-db sh\n\n# Access SQLite database\nsqlite3 /var/lib/sqlite/metrics.db\n\n# Enable better formatting\n.mode column\n.headers on\n```\n\n### Alternative: Copy Database Locally\n\n```bash\n# Copy database from container to host\ndocker compose cp metrics-db:/var/lib/sqlite/metrics.db ./metrics.db\n\n# Install sqlite3 locally if needed\nsudo apt-get install -y sqlite3\n\n# Query locally\nsqlite3 ./metrics.db\n```\n\n## SQLite Database Queries\n\n### Database Overview\n\n#### List All Tables\n\n```sql\n.tables\n```\n\n**Output:**\n```\n_health auth_metrics metrics\napi_keys discovery_metrics tool_metrics\n```\n\n#### Count Metrics by Table\n\n```sql\nSELECT 'auth_metrics' as table_name, COUNT(*) as count FROM auth_metrics\nUNION ALL\nSELECT 'tool_metrics', COUNT(*) FROM tool_metrics\nUNION ALL\nSELECT 'discovery_metrics', COUNT(*) FROM discovery_metrics\nUNION ALL\nSELECT 'metrics', COUNT(*) FROM metrics;\n```\n\n**Sample Output:**\n```\ntable_name count\n----------------- -----\nauth_metrics 212\ntool_metrics 183\ndiscovery_metrics 0\nmetrics 475\n```\n\n### Authentication Metrics\n\n#### Recent Auth Requests\n\n```sql\nSELECT\n datetime(timestamp) as time,\n server,\n success,\n method,\n duration_ms,\n user_hash,\n error_code\nFROM auth_metrics\nORDER BY timestamp DESC\nLIMIT 20;\n```\n\n**Sample Output:**\n```\ntime server success method duration_ms user_hash error_code\n------------------- ------------------- ------- ------- ---------------- --------- ----------\n2025-10-02 04:43:22 mcpgw 0 unknown 14.0132130181883 500\n2025-10-02 04:43:22 currenttime 0 unknown 13.9779029996134 500\n2025-10-02 04:43:22 realserverfaketools 0 unknown 12.8724499954842 500\n2025-10-02 04:43:22 sre-gateway 0 unknown 8.54846101719886 500\n```\n\n#### Auth Success Rate by Server\n\n```sql\nSELECT\n server,\n COUNT(*) as total,\n SUM(success) as successful,\n ROUND(100.0 * SUM(success) / COUNT(*), 2) as success_pct,\n ROUND(AVG(duration_ms), 2) as avg_ms\nFROM auth_metrics\nGROUP BY server\nORDER BY total DESC;\n```\n\n#### Hourly Request Volume (Last 24 Hours)\n\n```sql\nSELECT\n strftime('%Y-%m-%d %H:00', timestamp) as hour,\n COUNT(*) as requests\nFROM auth_metrics\nWHERE timestamp > datetime('now', '-24 hours')\nGROUP BY hour\nORDER BY hour DESC;\n```\n\n### Tool Execution Metrics\n\n#### Recent Tool Executions\n\n```sql\nSELECT\n datetime(timestamp) as time,\n tool_name,\n server_name,\n success,\n ROUND(duration_ms, 2) as dur_ms,\n method,\n client_name\nFROM tool_metrics\nORDER BY timestamp DESC\nLIMIT 20;\n```\n\n**Sample Output:**\n```\ntime tool_name server_name success dur_ms method client_name\n------------------- ---------- ------------------- ------- ------ ---------- -----------\n2025-10-02 04:43:22 initialize mcpgw 0 14.01 initialize claude-code\n2025-10-02 04:43:22 initialize currenttime 0 13.98 initialize claude-code\n2025-10-02 04:43:22 initialize fininfo 0 10.47 initialize claude-code\n2025-10-02 04:42:59 initialize currenttime 0 7.61 initialize Roo Code\n2025-10-02 04:42:59 initialize mcpgw 0 10.24 initialize Roo Code\n```\n\n#### Tool Usage Summary\n\n```sql\nSELECT\n tool_name,\n COUNT(*) as calls,\n SUM(success) as successful,\n ROUND(AVG(duration_ms), 2) as avg_ms,\n COUNT(DISTINCT client_name) as unique_clients\nFROM tool_metrics\nGROUP BY tool_name\nORDER BY calls DESC;\n```\n\n#### Client Usage Statistics\n\n```sql\nSELECT\n client_name,\n client_version,\n COUNT(*) as calls,\n COUNT(DISTINCT tool_name) as unique_tools,\n COUNT(DISTINCT server_name) as unique_servers\nFROM tool_metrics\nWHERE client_name IS NOT NULL\nGROUP BY client_name, client_version\nORDER BY calls DESC;\n```\n\n#### Slowest Tool Executions\n\n```sql\nSELECT\n tool_name,\n server_name,\n ROUND(duration_ms, 2) as duration_ms,\n datetime(timestamp) as time,\n success\nFROM tool_metrics\nORDER BY duration_ms DESC\nLIMIT 20;\n```\n\n**Sample Output:**\n```\ntool_name server_name duration_ms time success\n------------------------- ------------------- ----------- ------------------- -------\ninitialize mcpgw 637.67 2025-10-02 03:32:51 0\ninitialize fininfo 73.62 2025-10-02 03:08:40 0\ninitialize sre-gateway 45.2 2025-10-02 03:15:49 0\ninitialize sre-gateway 39.86 2025-10-02 03:42:27 0\ninitialize realserverfaketools 36.31 2025-10-02 03:42:27 0\n```\n\n#### Error Analysis\n\n```sql\nSELECT\n error_code,\n COUNT(*) as count,\n GROUP_CONCAT(DISTINCT tool_name) as affected_tools\nFROM tool_metrics\nWHERE success = 0 AND error_code IS NOT NULL\nGROUP BY error_code\nORDER BY count DESC;\n```\n\n### Tool Discovery Metrics\n\n#### Recent Discovery Queries\n\n```sql\nSELECT\n datetime(timestamp) as time,\n query,\n results_count,\n ROUND(duration_ms, 2) as dur_ms,\n ROUND(embedding_time_ms, 2) as embed_ms,\n ROUND(faiss_search_time_ms, 2) as search_ms\nFROM discovery_metrics\nORDER BY timestamp DESC\nLIMIT 20;\n```\n\n#### Discovery Performance Analysis\n\n```sql\nSELECT\n COUNT(*) as total_queries,\n ROUND(AVG(results_count), 2) as avg_results,\n ROUND(AVG(duration_ms), 2) as avg_duration_ms,\n ROUND(AVG(embedding_time_ms), 2) as avg_embedding_ms,\n ROUND(AVG(faiss_search_time_ms), 2) as avg_search_ms\nFROM discovery_metrics;\n```\n\n### Advanced Queries\n\n#### Tool Method Distribution\n\n```sql\nSELECT\n method,\n COUNT(*) as count,\n COUNT(DISTINCT server_name) as servers_using,\n ROUND(AVG(duration_ms), 2) as avg_ms\nFROM tool_metrics\nWHERE method IS NOT NULL\nGROUP BY method\nORDER BY count DESC;\n```\n\n#### Daily Active Clients\n\n```sql\nSELECT\n DATE(timestamp) as date,\n COUNT(DISTINCT client_name) as unique_clients,\n COUNT(*) as total_calls\nFROM tool_metrics\nWHERE client_name IS NOT NULL\nGROUP BY DATE(timestamp)\nORDER BY date DESC;\n```\n\n#### Server Performance Comparison\n\n```sql\nSELECT\n server_name,\n COUNT(*) as total_calls,\n SUM(success) as successful,\n ROUND(100.0 * SUM(success) / COUNT(*), 2) as success_rate,\n ROUND(AVG(duration_ms), 2) as avg_duration_ms,\n ROUND(MIN(duration_ms), 2) as min_ms,\n ROUND(MAX(duration_ms), 2) as max_ms\nFROM tool_metrics\nGROUP BY server_name\nORDER BY total_calls DESC;\n```\n\n#### Time-Based Performance Analysis\n\n```sql\nSELECT\n strftime('%H', timestamp) as hour_of_day,\n COUNT(*) as requests,\n ROUND(AVG(duration_ms), 2) as avg_duration_ms,\n ROUND(100.0 * SUM(success) / COUNT(*), 2) as success_rate\nFROM tool_metrics\nGROUP BY hour_of_day\nORDER BY hour_of_day;\n```\n\n## OpenTelemetry Metrics\n\nThe metrics service exports metrics to OpenTelemetry in two formats:\n\n### Prometheus Endpoint\n\nAccess raw Prometheus metrics:\n\n```bash\ncurl http://localhost:9465/metrics\n```\n\n**Available Metrics:**\n- `mcp_auth_requests_total` - Counter of authentication requests\n- `mcp_auth_request_duration_seconds` - Histogram of auth request durations\n- `mcp_tool_executions_total` - Counter of tool executions\n- `mcp_tool_execution_duration_seconds` - Histogram of tool execution durations\n- `mcp_tool_discovery_total` - Counter of discovery requests\n- `mcp_tool_discovery_duration_seconds` - Histogram of discovery durations\n- `mcp_protocol_latency_seconds` - Histogram of protocol flow latencies\n- `mcp_health_checks_total` - Counter of health checks\n- `mcp_health_check_duration_seconds` - Histogram of health check durations\n\n### OTLP Export\n\nIf configured, metrics are also exported to an OTLP endpoint (e.g., OpenTelemetry Collector).\n\nConfiguration in `.env`:\n```bash\nOTEL_OTLP_ENDPOINT=http://otel-collector:4318\n```\n\n## Configuring OpenTelemetry Collector\n\nThe OpenTelemetry Collector is a vendor-agnostic proxy that can receive, process, and export telemetry data to multiple backends (AWS CloudWatch, Datadog, New Relic, etc.).\n\n### Step 1: Add OTel Collector to Docker Compose\n\nAdd this service to your `docker-compose.yml`:\n\n```yaml\n # OpenTelemetry Collector\n otel-collector:\n image: otel/opentelemetry-collector-contrib:latest\n command: [\"--config=/etc/otel-collector-config.yaml\"]\n volumes:\n - ./config/otel-collector-config.yaml:/etc/otel-collector-config.yaml\n ports:\n - \"4318:4318\" # OTLP HTTP receiver\n - \"4317:4317\" # OTLP gRPC receiver\n - \"8888:8888\" # Prometheus metrics exposed by the collector\n - \"8889:8889\" # Prometheus exporter metrics\n restart: unless-stopped\n```\n\n### Step 2: Create OTel Collector Configuration\n\nCreate `config/otel-collector-config.yaml`:\n\n#### Basic Configuration (Prometheus Export)\n\n```yaml\nreceivers:\n otlp:\n protocols:\n http:\n endpoint: 0.0.0.0:4318\n grpc:\n endpoint: 0.0.0.0:4317\n\nprocessors:\n batch:\n timeout: 10s\n send_batch_size: 1024\n\nexporters:\n prometheus:\n endpoint: \"0.0.0.0:8889\"\n namespace: mcp_gateway\n\n logging:\n loglevel: info\n\nservice:\n pipelines:\n metrics:\n receivers: [otlp]\n processors: [batch]\n exporters: [prometheus, logging]\n```\n\n#### Advanced Configuration (Multiple Backends)\n\n```yaml\nreceivers:\n otlp:\n protocols:\n http:\n endpoint: 0.0.0.0:4318\n grpc:\n endpoint: 0.0.0.0:4317\n\nprocessors:\n batch:\n timeout: 10s\n send_batch_size: 1024\n\n # Add resource attributes\n resource:\n attributes:\n - key: environment\n value: production\n action: insert\n - key: service.namespace\n value: mcp-gateway\n action: insert\n\n # Filter metrics if needed\n filter:\n metrics:\n include:\n match_type: regexp\n metric_names:\n - mcp_.*\n\nexporters:\n # Export to Prometheus\n prometheus:\n endpoint: \"0.0.0.0:8889\"\n namespace: mcp_gateway\n\n # Export to AWS CloudWatch\n awscloudwatch:\n region: us-east-1\n namespace: MCP/Gateway\n endpoint: https://monitoring.us-east-1.amazonaws.com\n\n # Export to Datadog\n datadog:\n api:\n key: ${DATADOG_API_KEY}\n site: datadoghq.com\n\n # Export to New Relic\n otlphttp/newrelic:\n endpoint: https://otlp.nr-data.net:4318\n headers:\n api-key: ${NEW_RELIC_API_KEY}\n\n # Export to Grafana Cloud\n otlphttp/grafanacloud:\n endpoint: ${GRAFANA_CLOUD_OTLP_ENDPOINT}\n headers:\n authorization: Basic ${GRAFANA_CLOUD_AUTH}\n\n # Export to Honeycomb\n otlphttp/honeycomb:\n endpoint: https://api.honeycomb.io\n headers:\n x-honeycomb-team: ${HONEYCOMB_API_KEY}\n\n # Logging for debugging\n logging:\n loglevel: info\n\nservice:\n pipelines:\n metrics:\n receivers: [otlp]\n processors: [batch, resource, filter]\n exporters: [prometheus, awscloudwatch, logging]\n # Add other exporters as needed: datadog, otlphttp/newrelic, etc.\n```\n\n### Step 3: Update Metrics Service Configuration\n\nUpdate your `.env` file:\n\n```bash\n# Enable OTLP export to collector\nOTEL_OTLP_ENDPOINT=http://otel-collector:4318\n```\n\nUpdate `docker-compose.yml` metrics-service environment:\n\n```yaml\n metrics-service:\n environment:\n - OTEL_OTLP_ENDPOINT=http://otel-collector:4318\n # ... other env vars\n depends_on:\n - metrics-db\n - otel-collector # Add dependency\n```\n\n### Step 4: Configure Prometheus to Scrape OTel Collector\n\nUpdate `config/prometheus.yml`:\n\n```yaml\nglobal:\n scrape_interval: 15s\n evaluation_interval: 15s\n\nscrape_configs:\n # Scrape metrics directly from metrics-service\n - job_name: 'mcp-metrics-service'\n static_configs:\n - targets: ['metrics-service:9465']\n\n # Scrape metrics from OTel Collector\n - job_name: 'otel-collector'\n static_configs:\n - targets: ['otel-collector:8889']\n```\n\n### Step 5: Deploy and Verify\n\n```bash\n# Restart services\ndocker compose down\ndocker compose up -d\n\n# Check OTel Collector logs\ndocker compose logs -f otel-collector\n\n# Verify metrics are being received\ncurl http://localhost:8889/metrics | grep mcp_\n\n# Check Prometheus targets\ncurl http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | select(.labels.job == \"otel-collector\")'\n```\n\n### Cloud Provider Specific Configurations\n\n#### AWS CloudWatch\n\n```yaml\nexporters:\n awscloudwatch:\n region: us-east-1\n namespace: MCP/Gateway\n dimension_rollup_option: NoDimensionRollup\n metric_declarations:\n - dimensions: [[service, metric_type]]\n metric_name_selectors:\n - mcp_.*\n```\n\n**Required IAM Permissions:**\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"cloudwatch:PutMetricData\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n**Environment Variables:**\n```bash\nAWS_REGION=us-east-1\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\n```\n\n#### Datadog\n\n```yaml\nexporters:\n datadog:\n api:\n key: ${DATADOG_API_KEY}\n site: datadoghq.com # or datadoghq.eu for EU\n host_metadata:\n enabled: true\n hostname_source: config_or_system\n```\n\n**Environment Variables:**\n```bash\nDATADOG_API_KEY=your-datadog-api-key\n```\n\n#### Grafana Cloud\n\n```yaml\nexporters:\n otlphttp/grafanacloud:\n endpoint: ${GRAFANA_CLOUD_OTLP_ENDPOINT}\n headers:\n authorization: Basic ${GRAFANA_CLOUD_AUTH}\n```\n\n**Setup:**\n1. Get OTLP endpoint from Grafana Cloud console\n2. Create service account and get API key\n3. Base64 encode: `echo -n \"instance_id:api_key\" | base64`\n\n**Environment Variables:**\n```bash\nGRAFANA_CLOUD_OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp\nGRAFANA_CLOUD_AUTH=base64_encoded_credentials\n```\n\n#### New Relic\n\n```yaml\nexporters:\n otlphttp/newrelic:\n endpoint: https://otlp.nr-data.net:4318\n headers:\n api-key: ${NEW_RELIC_API_KEY}\n```\n\n**Environment Variables:**\n```bash\nNEW_RELIC_API_KEY=your-new-relic-license-key\n```\n\n### Troubleshooting OTel Collector\n\n#### Check Collector Health\n\n```bash\n# View collector logs\ndocker compose logs otel-collector\n\n# Check internal metrics\ncurl http://localhost:8888/metrics\n\n# Verify receivers are active\ndocker compose exec otel-collector wget -qO- http://localhost:13133/\n```\n\n#### Common Issues\n\n**Metrics not flowing to backend:**\n```bash\n# Enable debug logging in collector config\nexporters:\n logging:\n loglevel: debug\n\n# Check for export errors in logs\ndocker compose logs otel-collector | grep -i error\n```\n\n**Connection refused to OTLP endpoint:**\n```bash\n# Verify collector is reachable from metrics-service\ndocker compose exec metrics-service ping otel-collector\n\n# Check port is open\ndocker compose exec metrics-service nc -zv otel-collector 4318\n```\n\n**Authentication failures:**\n```bash\n# Verify API keys are set\ndocker compose exec otel-collector env | grep -i key\n\n# Test exporter authentication separately\n```\n\n### Best Practices\n\n1. **Use Batch Processor**: Reduces network overhead\n ```yaml\n processors:\n batch:\n timeout: 10s\n send_batch_size: 1024\n ```\n\n2. **Add Resource Attributes**: Tag metrics with environment/deployment info\n ```yaml\n processors:\n resource:\n attributes:\n - key: environment\n value: ${ENVIRONMENT}\n action: insert\n ```\n\n3. **Filter Metrics**: Only export what you need\n ```yaml\n processors:\n filter:\n metrics:\n include:\n match_type: regexp\n metric_names:\n - mcp_auth_.*\n - mcp_tool_.*\n ```\n\n4. **Enable Health Check**: Monitor collector itself\n ```yaml\n extensions:\n health_check:\n endpoint: 0.0.0.0:13133\n\n service:\n extensions: [health_check]\n ```\n\n5. **Set Retention Policies**: Configure backend retention based on use case\n - Real-time alerts: 7-30 days\n - Compliance/auditing: 1-2 years\n - General monitoring: 90 days\n\n### Example Complete Setup\n\nSee `config/otel-collector-config.example.yaml` for a complete configuration template.\n\n## Grafana Dashboards\n\nAccess Grafana dashboards at: `http://localhost:3000`\n\n**Credentials:**\n- Username: `admin`\n- Password: The value of `GRAFANA_ADMIN_PASSWORD` from your `.env` file\n\n**Important:** You must set a strong, random password for `GRAFANA_ADMIN_PASSWORD` in your `.env` file before starting Grafana. Generate one with:\n```bash\npython3 -c \"import secrets; print(secrets.token_urlsafe(24))\"\n```\n\nFor ECS deployments, the Grafana dashboard is available at `https:///grafana/` and the password is configured via `grafana_admin_password` in `terraform.tfvars`.\n\n### Pre-configured Dashboards\n\nThe MCP Gateway includes pre-configured Grafana dashboards for:\n\n1. **Authentication Metrics**\n - Success rates by server\n - Request volume over time\n - Error code distribution\n - Average response times\n\n2. **Tool Execution Metrics**\n - Most used tools\n - Client distribution\n - Success rates\n - Performance trends\n\n3. **Discovery Metrics**\n - Search query volume\n - Result counts\n - Performance breakdown (embedding vs. FAISS search)\n\n4. **System Health**\n - Overall request volume\n - Error rates\n - Performance percentiles (p50, p95, p99)\n\n### Prometheus Queries\n\nAccess Prometheus at: `http://localhost:9090`\n\n**Sample PromQL Queries:**\n\n```promql\n# Authentication success rate\nrate(mcp_auth_requests_total{success=\"true\"}[5m]) / rate(mcp_auth_requests_total[5m])\n\n# Average tool execution duration by server\nrate(mcp_tool_execution_duration_seconds_sum[5m]) / rate(mcp_tool_execution_duration_seconds_count[5m])\n\n# Top 5 most used tools\ntopk(5, sum by (tool_name) (rate(mcp_tool_executions_total[5m])))\n\n# 95th percentile request duration\nhistogram_quantile(0.95, rate(mcp_auth_request_duration_seconds_bucket[5m]))\n```\n\n## Monitoring Best Practices\n\n### Key Metrics to Monitor\n\n1. **Authentication Success Rate**: Should be >95%\n2. **Tool Execution Success Rate**: Should be >90%\n3. **Average Response Time**: Should be <100ms for auth, <500ms for tools\n4. **Error Rate**: Should be <5%\n5. **Discovery Query Performance**: Embedding time should be <50ms\n\n### Setting Up Alerts\n\nConfigure alerts in Grafana or Prometheus for:\n\n- Authentication failure rate >10%\n- Tool execution errors >5%\n- Response time p95 >1000ms\n- Discovery query failures\n\n### Data Retention\n\n- SQLite database: 90 days (configurable via `METRICS_RETENTION_DAYS`)\n- Prometheus: 200 hours (configurable in `prometheus.yml`)\n- Adjust retention based on storage capacity and compliance requirements\n\n## Troubleshooting\n\n### No Metrics Being Collected\n\n1. Check metrics service is running:\n ```bash\n docker compose ps metrics-service\n ```\n\n2. Verify API keys are configured:\n ```bash\n docker compose logs metrics-service | grep \"API key\"\n ```\n\n3. Check middleware is enabled in auth-server logs:\n ```bash\n docker compose logs auth-server | grep \"metrics\"\n ```\n\n### Database Connection Issues\n\n```bash\n# Check database volume\ndocker volume inspect mcp-gateway-registry_metrics-db-data\n\n# Check database file permissions\ndocker compose exec metrics-db ls -la /var/lib/sqlite/\n\n# Test database connectivity\ndocker compose exec metrics-db sqlite3 /var/lib/sqlite/metrics.db \"SELECT COUNT(*) FROM metrics;\"\n```\n\n### OpenTelemetry Export Issues\n\n```bash\n# Check Prometheus targets\ncurl http://localhost:9090/api/v1/targets\n\n# Check metrics-service OTEL configuration\ndocker compose logs metrics-service | grep -i otel\n```\n\n## Schema Reference\n\n### auth_metrics Table\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER | Primary key |\n| request_id | TEXT | Unique request identifier |\n| timestamp | TEXT | ISO 8601 timestamp |\n| service | TEXT | Service name (e.g., \"auth-server\") |\n| duration_ms | REAL | Request duration in milliseconds |\n| success | BOOLEAN | Whether auth was successful |\n| method | TEXT | Auth method used |\n| server | TEXT | MCP server name |\n| user_hash | TEXT | Hashed user identifier |\n| error_code | TEXT | Error code if failed |\n| created_at | TEXT | Record creation time |\n\n### tool_metrics Table\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER | Primary key |\n| request_id | TEXT | Unique request identifier |\n| timestamp | TEXT | ISO 8601 timestamp |\n| service | TEXT | Service name |\n| duration_ms | REAL | Execution duration in milliseconds |\n| tool_name | TEXT | Tool or method name |\n| server_path | TEXT | Server path |\n| server_name | TEXT | MCP server name |\n| success | BOOLEAN | Whether execution succeeded |\n| error_code | TEXT | Error code if failed |\n| input_size_bytes | INTEGER | Request payload size |\n| output_size_bytes | INTEGER | Response payload size |\n| client_name | TEXT | Client application name |\n| client_version | TEXT | Client version |\n| method | TEXT | MCP protocol method |\n| user_hash | TEXT | Hashed user identifier |\n| created_at | TEXT | Record creation time |\n\n### discovery_metrics Table\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER | Primary key |\n| request_id | TEXT | Unique request identifier |\n| timestamp | TEXT | ISO 8601 timestamp |\n| service | TEXT | Service name |\n| duration_ms | REAL | Total query duration |\n| query | TEXT | Search query text |\n| results_count | INTEGER | Number of results returned |\n| top_k_services | INTEGER | Number of services requested |\n| top_n_tools | INTEGER | Number of tools requested |\n| embedding_time_ms | REAL | Time to generate embeddings |\n| faiss_search_time_ms | REAL | Time for FAISS search |\n| created_at | TEXT | Record creation time |\n\n## Additional Resources\n\n- [Prometheus Documentation](https://prometheus.io/docs/)\n- [Grafana Documentation](https://grafana.com/docs/)\n- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)\n- [SQLite Documentation](https://www.sqlite.org/docs.html)\n" }, { "path": "docs/README.md", "content": "# Documentation\n\nThis directory contains the MkDocs-based documentation for the MCP Gateway & Registry.\n\n## Building Documentation Locally\n\n### Prerequisites\n\n```bash\n# Using uv (recommended)\nuv pip install -e \".[docs]\"\n\n# Or using pip\npip install -e \".[docs]\"\n```\n\n### Development Server\n\n```bash\n# Start development server with live reload\nmkdocs serve\n\n# The documentation will be available at http://127.0.0.1:8000\n```\n\n### Building Static Site\n\n```bash\n# Build static site\nmkdocs build\n\n# The built site will be in the `site/` directory\n```\n\n## Documentation Structure\n\n- `index.md` - Main landing page (generated from README.md)\n- `complete-setup-guide.md` - Step-by-step setup from scratch\n- `installation.md` - Complete installation guide\n- `auth.md` - Authentication and OAuth setup\n- `cognito.md` - Amazon Cognito configuration\n- `keycloak-integration.md` - Keycloak integration guide\n- `scopes.md` - Access control and permissions\n- `registry_api.md` - API reference\n- `dynamic-tool-discovery.md` - AI agent tool discovery\n- `ai-coding-assistants-setup.md` - IDE integration guide\n- `faq/index.md` - Frequently asked questions\n\n## Deployment\n\nThe documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch via GitHub Actions.\n\n### Manual Deployment\n\n```bash\n# Deploy to GitHub Pages\nmkdocs gh-deploy\n```\n\n## Theme and Configuration\n\nThe documentation uses the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme with:\n\n- Light/dark mode toggle\n- Navigation tabs and sections\n- Search functionality\n- Code syntax highlighting\n- Mermaid diagram support\n- Git revision dates\n\n## Contributing\n\nWhen adding new documentation:\n\n1. Create markdown files in the appropriate directory\n2. Update `mkdocs.yml` navigation structure\n3. Use proper markdown formatting and admonitions\n4. Include code examples where relevant\n5. Test locally with `mkdocs serve` before committing\n\n## Plugins Used\n\n- **search** - Full-text search functionality\n- **git-revision-date-localized** - Shows last update dates\n- **minify** - Minifies HTML output for production\n- **pymdown-extensions** - Enhanced markdown features" }, { "path": "docs/TELEMETRY.md", "content": "# Telemetry Documentation\n\n## Overview\n\nThe MCP Gateway Registry collects anonymous usage telemetry to understand adoption patterns and improve the product. This document describes what data is collected, how to opt-out, and our privacy commitments.\n\n## What Data is Collected\n\n### Tier 1: Startup Ping (Opt-Out, Default ON)\n\nSent once at startup:\n\n| Field | Example | Description |\n|-------|---------|-------------|\n| `registry_id` | `c546a650-...` | Registry Card UUID (public, not PII) |\n| `v` | `1.0.16` | Registry version |\n| `py` | `3.12` | Python version (major.minor) |\n| `os` | `linux` | Operating system (linux, darwin, windows) |\n| `arch` | `x86_64` | CPU architecture |\n| `cloud` | `aws` | Cloud provider (aws, gcp, azure, unknown) |\n| `compute` | `ecs` | Compute platform (ecs, eks, kubernetes, docker, ec2, unknown) |\n| `mode` | `with-gateway` | Deployment mode |\n| `registry_mode` | `full` | Registry operating mode |\n| `storage` | `documentdb` | Storage backend (file, documentdb, mongodb-ce) |\n| `auth` | `keycloak` | Auth provider |\n| `federation` | `true` | Whether federation is enabled |\n| `search_queries_total` | `150` | Lifetime semantic search query count |\n| `search_queries_24h` | `12` | Search queries in the last 24 hours |\n| `search_queries_1h` | `3` | Search queries in the last hour |\n| `ts` | `2026-03-18T00:00:00Z` | ISO 8601 timestamp |\n\n### Tier 2: Daily Heartbeat (Opt-Out, Default ON)\n\n> **Behavior change (post v1.0.18):** The daily heartbeat was previously opt-in (`MCP_TELEMETRY_OPT_IN=1`). It is now opt-out and sent by default every 24 hours. Since the heartbeat contains only aggregate counts (no PII), this aligns it with the startup ping behavior.\n\nSent at a configurable interval (default: every 24 hours). Includes all Tier 1 fields plus:\n\n| Field | Example | Description |\n|-------|---------|-------------|\n| `servers_count` | `15` | Number of registered MCP servers |\n| `agents_count` | `8` | Number of registered A2A agents |\n| `skills_count` | `23` | Number of registered skills |\n| `peers_count` | `2` | Number of federation peers |\n| `search_backend` | `documentdb` | Search backend (faiss or documentdb) |\n| `embeddings_provider` | `sentence-transformers` | Embeddings provider |\n| `uptime_hours` | `48` | Hours since server started |\n\n## Request Signing (HMAC)\n\nAll telemetry requests are signed with HMAC-SHA256 to prevent unauthorized use of the collector endpoint. The registry computes a signature over the JSON request body and sends it in the `X-Telemetry-Signature` HTTP header. The server-side Lambda collector verifies this signature before processing any event.\n\nThis is not a secret-based authentication mechanism -- the signing key is embedded in the open-source code. Its purpose is to raise the bar against casual abuse (e.g., random `curl` requests to the endpoint). Combined with IP-based rate limiting and strict Pydantic schema validation, this makes endpoint abuse impractical.\n\n### Example HTTP Request\n\nA startup event request looks like this:\n\n```http\nPOST /v1/collect HTTP/1.1\nHost: m3ijrhd020.execute-api.us-east-1.amazonaws.com\nContent-Type: application/json\nX-Telemetry-Signature: 8a3f2b...c9d1e0\n\n{\"arch\":\"x86_64\",\"auth\":\"keycloak\",\"cloud\":\"aws\",\"compute\":\"ecs\",\"event\":\"startup\",\"federation\":true,\"mode\":\"with-gateway\",\"os\":\"linux\",\"py\":\"3.12\",\"registry_id\":\"c546a650-8af9-4721-9efb-7df221b2a0d9\",\"registry_mode\":\"full\",\"schema_version\":\"1\",\"search_queries_1h\":3,\"search_queries_24h\":12,\"search_queries_total\":150,\"storage\":\"documentdb\",\"ts\":\"2026-03-18T00:00:00+00:00\",\"v\":\"1.0.16\"}\n```\n\nA heartbeat event request:\n\n```http\nPOST /v1/collect HTTP/1.1\nHost: m3ijrhd020.execute-api.us-east-1.amazonaws.com\nContent-Type: application/json\nX-Telemetry-Signature: 5b7e1a...d4f2c3\n\n{\"agents_count\":8,\"cloud\":\"aws\",\"compute\":\"ecs\",\"embeddings_provider\":\"sentence-transformers\",\"event\":\"heartbeat\",\"peers_count\":2,\"registry_id\":\"c546a650-8af9-4721-9efb-7df221b2a0d9\",\"schema_version\":\"1\",\"search_backend\":\"documentdb\",\"search_queries_1h\":3,\"search_queries_24h\":12,\"search_queries_total\":150,\"servers_count\":15,\"skills_count\":23,\"ts\":\"2026-03-18T12:00:00+00:00\",\"uptime_hours\":48,\"v\":\"1.0.16\"}\n```\n\nNotes:\n- JSON body keys are sorted alphabetically (`sort_keys=True`) and compact (`separators=(\",\",\":\")`) for deterministic HMAC computation\n- The `X-Telemetry-Signature` header is the HMAC-SHA256 hex digest of the raw JSON body\n\n## Force Telemetry (Admin API)\n\nAdmins can trigger telemetry events on demand (bypasses the distributed lock):\n\n```bash\n# Force heartbeat\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token-local telemetry-heartbeat\n\n# Force startup ping\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token-local telemetry-startup\n```\n\nAPI endpoints (require admin auth):\n- `POST /api/registry-management/telemetry/heartbeat`\n- `POST /api/registry-management/telemetry/startup`\n\n## What is NOT Collected\n\nWe never collect any personally identifiable information (PII):\n\n- ❌ IP addresses, MAC addresses, hostnames\n- ❌ Server names, URLs, file paths\n- ❌ User data, credentials, tokens\n- ❌ Query content, agent card content, skill code\n- ❌ Any data that could identify a person or organization\n\n## Startup Banner\n\nWhen telemetry is enabled (the default), you will see this banner at startup:\n\n```\n==============================================================================\n[telemetry] Anonymous usage telemetry is ON (startup ping + daily heartbeat)\n[telemetry] No PII is collected (no IPs, hostnames, or user data)\n[telemetry] Endpoint: https://m3ijrhd020.execute-api.us-east-1.amazonaws.com/v1/collect\n[telemetry] To disable all: set MCP_TELEMETRY_DISABLED=1\n[telemetry] Details: https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/TELEMETRY.md\n==============================================================================\n```\n\n## Telemetry Configuration Parameters\n\n| Environment Variable | Purpose | Default |\n|---------------------|---------|---------|\n| `MCP_TELEMETRY_DISABLED` | Set to `1` to disable all telemetry (startup ping + heartbeat) | _(not set, telemetry ON)_ |\n| `MCP_TELEMETRY_OPT_OUT` | Set to `1` to disable daily heartbeat only (startup ping still sent) | _(not set, heartbeat ON)_ |\n| `MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES` | Heartbeat send frequency in minutes | `1440` (24 hours) |\n| `MCP_TELEMETRY_ENDPOINT` | HTTPS URL for a self-hosted telemetry collector | _(built-in endpoint)_ |\n| `MCP_TELEMETRY_DEBUG` | Set to `true` to log payloads instead of sending | `false` |\n\n### Docker Compose\n\nAdd these to your `.env` file in the project root:\n\n```bash\n# .env\nMCP_TELEMETRY_DISABLED=1 # Disable all telemetry (startup ping + heartbeat)\nMCP_TELEMETRY_OPT_OUT=1 # Disable heartbeat only (startup ping still sent)\nMCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=1440 # Heartbeat interval in minutes (default: 1440 = 24h)\nMCP_TELEMETRY_ENDPOINT=https://your-collector.example.com/v1/collect # Self-hosted (optional)\nMCP_TELEMETRY_DEBUG=true # Debug mode (optional)\n```\n\nThese are automatically picked up by the `docker-compose.yml`, `docker-compose.prebuilt.yml`, and `docker-compose.podman.yml` files.\n\n### ECS (Terraform)\n\nAdd these to your `terraform.tfvars`:\n\n```hcl\n# terraform.tfvars\nmcp_telemetry_disabled = \"1\" # Disable all telemetry\nmcp_telemetry_opt_out = \"1\" # Disable heartbeat only (startup ping still sent)\nmcp_telemetry_heartbeat_interval_minutes = \"1440\" # Heartbeat interval in minutes (default: 1440 = 24h)\ntelemetry_debug = \"true\" # Debug mode (optional)\n```\n\nThe corresponding Terraform variables are defined in `terraform/aws-ecs/variables.tf`.\n\n### Kubernetes (Helm)\n\nSet these in your `values.yaml` or pass with `--set`:\n\n```yaml\n# values.yaml (standalone chart)\napp:\n mcpTelemetryDisabled: true # Disable all telemetry\n mcpTelemetryOptOut: true # Disable heartbeat only (startup ping still sent)\n telemetryHeartbeatIntervalMinutes: \"1440\" # Heartbeat interval in minutes (default: 1440 = 24h)\n telemetryDebug: true # Debug mode (optional)\n\n# -- OR for the stack chart --\n# values.yaml (mcp-gateway-registry-stack)\nregistry:\n app:\n mcpTelemetryDisabled: true\n mcpTelemetryOptOut: true\n telemetryHeartbeatIntervalMinutes: \"1440\"\n telemetryDebug: true\n```\n\nOr with `helm install`/`helm upgrade`:\n\n```bash\nhelm upgrade my-release charts/registry \\\n --set app.mcpTelemetryDisabled=true \\\n --set app.mcpTelemetryOptOut=true\n```\n\nThese values are injected as environment variables via the `registry-otel-config` ConfigMap.\n\n## How to Opt-Out\n\nSet `MCP_TELEMETRY_DISABLED=1` using the method for your deployment (see above).\n\nWhen telemetry is disabled, you'll see this message at startup:\n\n```\n[telemetry] Telemetry is disabled.\n```\n\n## How to Opt-Out of Heartbeat Only\n\nBoth startup ping and daily heartbeat are enabled by default. To disable the heartbeat while keeping the startup ping:\n\nSet `MCP_TELEMETRY_OPT_OUT=1` using the method for your deployment (see above).\n\nWhen heartbeat is opted out, you'll see:\n\n```\n[telemetry] Heartbeat scheduler not started (opted out or telemetry disabled)\n```\n\n## Debug Mode\n\nSet `MCP_TELEMETRY_DEBUG=true` using the method for your deployment (see above).\n\nThis logs the full JSON payload to stderr instead of sending it to the collector.\n\n## Privacy Commitments\n\n1. **Privacy First**: No PII is ever collected or stored\n2. **Conspicuous Disclosure**: Every startup logs a clear message about telemetry\n3. **Easy Opt-Out**: Multiple methods to disable telemetry\n4. **Fail-Silent**: Telemetry failures never impact registry operation\n5. **No Tracking**: No user identification or cross-session tracking\n6. **Open Source**: The telemetry code is open source and auditable\n\n## Multi-Replica Deployments\n\nIn multi-replica deployments (ECS, Kubernetes), telemetry uses MongoDB-based distributed locks to prevent duplicate sends. Only one replica will send telemetry within the configured interval:\n\n- **Startup ping**: At most once per 60 seconds\n- **Heartbeat**: At most once per configured interval (default: 1440 minutes = 24 hours)\n\n## Self-Hosted Telemetry Collector\n\nIf you want to run your own telemetry collector instead of using the default endpoint, you can deploy the server-side infrastructure from issue #559.\n\n### Why Self-Host?\n\n- **Data Sovereignty**: Keep telemetry data in your own AWS account\n- **Compliance**: Meet specific regulatory requirements\n- **Custom Analytics**: Run your own queries and dashboards\n- **Air-Gapped Deployments**: Collect telemetry without external network access\n\n### Quick Start\n\nThe telemetry collector infrastructure is available in `terraform/telemetry-collector/`:\n\n```bash\ncd terraform/telemetry-collector\n\n# Configure deployment\ncp terraform.tfvars.example terraform.tfvars\nvi terraform.tfvars # Set aws_region, deployment_stage, etc.\n\n# Deploy infrastructure (~15-20 minutes)\nterraform init\nterraform apply\n\n# Get your collector URL\nterraform output collector_url\n```\n\n### Point Registry to Your Collector\n\n```bash\n# Set custom endpoint\nexport MCP_TELEMETRY_ENDPOINT=https://your-collector-url.execute-api.us-east-1.amazonaws.com/v1/collect\n\n# Start registry\nuv run python -m registry\n```\n\n### Infrastructure Components\n\nThe self-hosted collector includes:\n\n- **API Gateway HTTP API**: HTTPS endpoint (`/v1/collect`)\n- **Lambda Function**: VPC-enabled, validates events with Pydantic schemas\n- **DynamoDB**: Privacy-preserving rate limiting (hashed IPs)\n- **DocumentDB**: MongoDB-compatible storage with 365-day TTL\n- **Secrets Manager**: Secure credential management\n- **CloudWatch**: Logs and alarms (production)\n\n### Cost Estimate\n\n- **Testing**: ~$85-90/month (db.t3.medium DocumentDB)\n- **Production**: ~$195-200/month (db.r5.large DocumentDB)\n\nSee `terraform/telemetry-collector/README.md` for detailed cost breakdown.\n\n### Security Features\n\n- **No IP Logging**: Source IPs are hashed (SHA-256) for rate limiting only\n- **HMAC Signed**: Requests signed with HMAC-SHA256 to reject unauthorized callers\n- **Rate Limited**: DynamoDB-based per-IP rate limiting (10 requests/minute)\n- **Schema Validated**: Strict Pydantic validation rejects malformed payloads\n- **VPC Isolated**: DocumentDB not accessible from internet\n- **TLS Everywhere**: All connections encrypted\n- **Always Returns 204**: No information leakage (same response for valid, invalid, or rejected)\n- **IAM Least Privilege**: Minimal Lambda permissions\n\n### Bastion Host Scripts\n\nThe bastion host provides scripts for querying and managing telemetry data in DocumentDB. Scripts are located in `terraform/telemetry-collector/bastion-scripts/` and should be copied to the bastion home directory.\n\n#### Interactive Shell (connect.sh)\n\nOpen an interactive mongosh session against DocumentDB:\n\n```bash\n~/connect.sh\n```\n\n#### Quick Summary (query.sh)\n\nPrint a summary of telemetry collections (counts, last 5 events, storage backend breakdown):\n\n```bash\n~/query.sh\n```\n\n#### Export to CSV (telemetry_db.py export)\n\nDump telemetry data to a CSV file:\n\n```bash\n# Export all collections to registry_metrics.csv\npython3 ~/telemetry_db.py export\n\n# Export to a custom path\npython3 ~/telemetry_db.py export --output /tmp/metrics.csv\n\n# Export only startup events\npython3 ~/telemetry_db.py export --collection startup_events\n\n# Export only heartbeat events\npython3 ~/telemetry_db.py export --collection heartbeat_events\n```\n\n#### Purge Data (telemetry_db.py purge)\n\nDelete all telemetry data from DocumentDB (with interactive confirmation):\n\n```bash\n# Purge all collections (prompts for confirmation)\npython3 ~/telemetry_db.py purge\n\n# Purge only startup events\npython3 ~/telemetry_db.py purge --collection startup_events\n\n# Purge only heartbeat events\npython3 ~/telemetry_db.py purge --collection heartbeat_events\n\n# Skip confirmation prompt\npython3 ~/telemetry_db.py purge --confirm\n```\n\n#### Deploying Scripts to Bastion\n\nCopy scripts to the bastion host after initial setup:\n\n```bash\nBASTION_IP=$(terraform output -raw bastion_public_ip)\n\nscp -i ~/.ssh/id_ed25519 \\\n bastion-scripts/connect.sh \\\n bastion-scripts/query.sh \\\n bastion-scripts/telemetry_db.py \\\n ec2-user@$BASTION_IP:~/\n\nssh -i ~/.ssh/id_ed25519 ec2-user@$BASTION_IP 'chmod +x ~/connect.sh ~/query.sh'\n```\n\n### Full Documentation\n\nSee `terraform/telemetry-collector/README.md` for:\n- Prerequisites and deployment steps\n- DocumentDB index setup\n- Testing procedures\n- Troubleshooting guide\n- Production deployment (custom domain, alarms)\n\n## Questions?\n\nFor more information or questions about telemetry:\n\n- **GitHub Issue**: https://github.com/agentic-community/mcp-gateway-registry/issues/558\n- **Telemetry Source Code**: https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/core/telemetry.py\n" }, { "path": "docs/a2a-agent-management.md", "content": "# A2A Agent Management Guide\n\nThis guide covers registering, managing, and using A2A agents through the MCP Gateway Registry using the `mcp-gateway-m2m` service account.\n\n## Quick Start\n\n### Service Account: `mcp-gateway-m2m`\n\nAll agent management operations use the **`mcp-gateway-m2m`** Keycloak M2M service account:\n\n```bash\n# Register an agent (uses mcp-gateway-m2m token automatically)\nuv run python cli/agent_mgmt.py register cli/examples/code_reviewer_agent.json\n\n# List agents\nuv run python cli/agent_mgmt.py list\n\n# Get agent details\nuv run python cli/agent_mgmt.py get /code-reviewer\n\n# Test agent (verify registry metadata and endpoint accessibility)\nuv run python cli/agent_mgmt.py test /code-reviewer\n\n# Test all agents\nuv run python cli/agent_mgmt.py test-all\n\n# Search agents (semantic search by capability)\nuv run python cli/agent_mgmt.py search \"code review agent\"\n\n# Update agent\nuv run python cli/agent_mgmt.py update /code-reviewer cli/examples/code_reviewer_agent.json\n\n# Toggle agent enabled/disabled status\nuv run python cli/agent_mgmt.py toggle /code-reviewer true # Enable\nuv run python cli/agent_mgmt.py toggle /code-reviewer false # Disable\n\n# Delete agent\nuv run python cli/agent_mgmt.py delete /code-reviewer\n```\n\n**Token Details:**\n- **File:** `.oauth-tokens/ingress.json` (auto-loaded by CLI)\n- **Generated by:** `./credentials-provider/generate_creds.sh`\n- **Keycloak Groups:** `mcp-servers-unrestricted`, `a2a-agent-admin`\n- **Permissions:** Full agent management (register, modify, delete, list)\n\n## Service Account Details\n\n### Account Identity\n| Property | Value |\n|----------|-------|\n| Keycloak Client ID | `mcp-gateway-m2m` |\n| Service Account User | `service-account-mcp-gateway-m2m` |\n| Token File | `.oauth-tokens/ingress.json` |\n| Token Generator | `./credentials-provider/generate_creds.sh` |\n\n### Keycloak Groups (Auto-Assigned)\n- **`mcp-servers-unrestricted`** - Full access to unrestricted MCP servers\n- **`a2a-agent-admin`** - Full A2A agent management permissions\n\n### Permissions\n- ✅ Register agents\n- ✅ Modify agents\n- ✅ Delete agents\n- ✅ List agents\n- ✅ Manage MCP server groups\n\n## Authentication Flow\n\n```\n1. CLI loads token from .oauth-tokens/ingress.json\n └─ JWT contains: groups: [\"mcp-servers-unrestricted\", \"a2a-agent-admin\"]\n\n2. POST /api/agents/register with Authorization: Bearer \n\n3. Nginx /api/ location intercepts request\n └─ Calls auth-server /validate endpoint\n\n4. Auth-server validates JWT and maps groups to scopes\n └─ Returns: X-Scopes: a2a-agent-admin\n\n5. Nginx forwards request to FastAPI with X-Scopes header\n\n6. FastAPI reads X-Scopes and grants permissions\n └─ Detects a2a-agent-admin → allows agent registration\n\n7. Agent is registered successfully\n```\n\n## Agent Examples\n\n### Register Code Reviewer Agent\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/code_reviewer_agent.json\n```\n\nAvailable examples:\n- `code_reviewer_agent.json` - Code quality analysis\n- `test_automation_agent.json` - Test case generation and execution\n- `data_analysis_agent.json` - Statistical analysis and visualization\n- `security_analyzer_agent.json` - Vulnerability detection\n- `documentation_agent.json` - API documentation generation\n- `devops_deployment_agent.json` - Infrastructure automation\n\n### Create Custom Agent\n\n1. Copy example file:\n```bash\ncp cli/examples/code_reviewer_agent.json cli/examples/my_agent.json\n```\n\n2. Edit JSON with your agent details:\n```json\n{\n \"name\": \"My Agent\",\n \"path\": \"/my-agent\",\n \"description\": \"What my agent does\",\n \"url\": \"http://my-domain.com/agents/my-agent\",\n \"version\": \"1.0.0\",\n \"protocol_version\": \"1.0\",\n \"visibility\": \"public\",\n \"trust_level\": \"community\",\n \"tags\": [\"custom\"],\n \"security_schemes\": {\n \"bearer\": {\n \"type\": \"bearer\"\n }\n }\n}\n```\n\n3. Register:\n```bash\nuv run python cli/agent_mgmt.py register cli/examples/my_agent.json\n```\n\n### Custom Metadata\n\nAgents support optional custom metadata for organization, compliance, and integration tracking. All metadata is fully searchable via semantic search.\n\n#### Example Agent with Metadata\n```json\n{\n \"name\": \"Data Analysis Agent\",\n \"path\": \"/data-analysis\",\n \"description\": \"Advanced data analysis agent\",\n \"url\": \"https://example.com/agents/data-analysis\",\n \"version\": \"3.2.1\",\n \"protocol_version\": \"1.0\",\n \"visibility\": \"public\",\n \"trust_level\": \"verified\",\n \"tags\": [\"analytics\", \"data-science\"],\n \"metadata\": {\n \"team\": \"data-science\",\n \"owner\": \"bob@example.com\",\n \"cost_center\": \"analytics-dept\",\n \"version\": \"3.2.1\",\n \"deployment_region\": \"us-east-1\",\n \"jira_ticket\": \"DATA-456\"\n }\n}\n```\n\n#### Metadata Use Cases\n\n**Organization & Team:**\n```json\n{\n \"team\": \"data-science\",\n \"owner\": \"bob@example.com\",\n \"department\": \"analytics\"\n}\n```\n\n**Compliance & Governance:**\n```json\n{\n \"compliance_level\": \"HIPAA\",\n \"data_classification\": \"phi\",\n \"audit_logging\": true\n}\n```\n\n**Cost & Project Tracking:**\n```json\n{\n \"cost_center\": \"analytics-dept\",\n \"project_code\": \"AI-2024-Q1\"\n}\n```\n\n**Deployment & Integration:**\n```json\n{\n \"deployment_region\": \"us-east-1\",\n \"environment\": \"production\",\n \"version\": \"3.2.1\",\n \"jira_ticket\": \"DATA-456\"\n}\n```\n\n#### Search by Metadata\n\nOnce registered, agents with metadata are searchable:\n\n```bash\n# Find agents by team\nuv run python cli/agent_mgmt.py search \"team:data-science\"\n\n# Find agents by owner\nuv run python cli/agent_mgmt.py search \"bob@example.com owned agents\"\n\n# Find agents by cost center\nuv run python cli/agent_mgmt.py search \"cost center analytics\"\n\n# Find agents in specific region\nuv run python cli/agent_mgmt.py search \"us-east-1 deployed agents\"\n```\n\n**Key Features:**\n- **Flexible Schema:** Any JSON-serializable data\n- **Fully Searchable:** Included in semantic search\n- **Optional:** Works with or without metadata\n- **Type-Safe:** Pydantic validation\n\n## Verification\n\n### Check Token Has Correct Groups\n\n```bash\npython3 << 'EOF'\nimport json, base64\nwith open('.oauth-tokens/ingress.json') as f:\n token = json.load(f)['access_token']\npayload = token.split('.')[1]\npayload += '='*(4-len(payload)%4)\ndecoded = json.loads(base64.urlsafe_b64decode(payload))\nprint(\"Service Account:\", decoded.get('client_id'))\nprint(\"Groups:\", decoded.get('groups'))\nprint(\"Expected groups: ['mcp-servers-unrestricted', 'a2a-agent-admin']\")\nEOF\n```\n\nExpected output:\n```\nService Account: mcp-gateway-m2m\nGroups: ['mcp-servers-unrestricted', 'a2a-agent-admin']\nExpected groups: ['mcp-servers-unrestricted', 'a2a-agent-admin']\n```\n\n### Check Auth Server Sees Groups\n\n```bash\nTOKEN=$(python3 -c \"import json; print(json.load(open('.oauth-tokens/ingress.json'))['access_token'])\")\ncurl -s \"http://localhost:8888/validate\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"X-Original-URL: http://localhost/agents/register\" | \\\n python3 -m json.tool | grep -E \"groups|scopes\"\n```\n\nExpected output should include:\n```\n\"groups\": [\"mcp-servers-unrestricted\", \"a2a-agent-admin\"],\n\"scopes\": [..., \"a2a-agent-admin\", ...]\n```\n\n## Troubleshooting\n\n### Issue: \"Authentication required\" Error\n\n**Check 1: Token file exists**\n```bash\n[ -f .oauth-tokens/ingress.json ] && echo \"✓ Token exists\" || echo \"✗ Token missing\"\n```\n\n**Check 2: Token has groups**\n```bash\npython3 << 'EOF'\nimport json, base64\nwith open('.oauth-tokens/ingress.json') as f:\n token = json.load(f)['access_token']\npayload = token.split('.')[1] + '='*(4-len(token.split('.')[1])%4)\ndecoded = json.loads(base64.urlsafe_b64decode(payload))\ngroups = decoded.get('groups', [])\nprint(f\"Groups in token: {groups}\")\nif 'a2a-agent-admin' not in groups:\n print(\"✗ Missing a2a-agent-admin - try refreshing token:\")\n print(\" ./credentials-provider/generate_creds.sh\")\nEOF\n```\n\n**Check 3: Auth server sees groups**\n```bash\nTOKEN=$(python3 -c \"import json; print(json.load(open('.oauth-tokens/ingress.json'))['access_token'])\")\ncurl -s \"http://localhost:8888/validate\" -H \"Authorization: Bearer $TOKEN\" | \\\n python3 -m json.tool | grep groups\n```\n\nShould show: `\"groups\": [\"mcp-servers-unrestricted\", \"a2a-agent-admin\"]`\n\n**Check 4: Nginx forwards scopes**\n```bash\ncurl -v http://localhost/api/agents/register \\\n -X POST \\\n -H \"Authorization: Bearer $(python3 -c 'import json; print(json.load(open(\\\".oauth-tokens/ingress.json\\\"))[\\\"access_token\\\"])')\" \\\n 2>&1 | grep -i x-scopes\n```\n\nShould include: `x-scopes: a2a-agent-admin` (note: uses port 80 via Nginx, not direct application port)\n\n### Solution: Refresh Token\n\nIf token is missing groups, regenerate it:\n```bash\n./credentials-provider/generate_creds.sh\n```\n\nThen verify groups reappear:\n```bash\npython3 << 'EOF'\nimport json, base64\nwith open('.oauth-tokens/ingress.json') as f:\n token = json.load(f)['access_token']\npayload = token.split('.')[1] + '='*(4-len(token.split('.')[1])%4)\ndecoded = json.loads(base64.urlsafe_b64decode(payload))\nprint(\"Groups:\", decoded.get('groups'))\nEOF\n```\n\n## JWT Token Structure\n\nThe `mcp-gateway-m2m` service account's JWT token contains:\n\n```json\n{\n \"exp\": 1761942660,\n \"iat\": 1761942360,\n \"iss\": \"http://localhost:8080/realms/mcp-gateway\",\n \"sub\": \"user-id-uuid\",\n \"typ\": \"Bearer\",\n \"azp\": \"mcp-gateway-m2m\",\n \"client_id\": \"mcp-gateway-m2m\",\n \"preferred_username\": \"service-account-mcp-gateway-m2m\",\n \"groups\": [\"mcp-servers-unrestricted\", \"a2a-agent-admin\"],\n \"scope\": \"profile email mcp-servers-restricted/execute mcp-servers-restricted/read mcp-servers-unrestricted/read mcp-servers-unrestricted/execute a2a-agent-admin\"\n}\n```\n\nKey fields:\n- **`client_id`**: `mcp-gateway-m2m` - identifies the service account\n- **`groups`**: List of Keycloak groups the account belongs to\n- **`scope`**: Space-separated list of OAuth2 scopes for authorization\n- **`a2a-agent-admin`**: The scope that grants agent management permissions\n\n## Setup (Automatic During Initialization)\n\nThe `mcp-gateway-m2m` service account is automatically configured during Keycloak initialization:\n\n1. **Keycloak Client Created** - `mcp-gateway-m2m` M2M client registered\n2. **Service Account User Created** - `service-account-mcp-gateway-m2m` user created\n3. **Groups Assigned** - User assigned to `mcp-servers-unrestricted` and `a2a-agent-admin` groups\n4. **Groups Mapper Added** - JWT tokens include groups claim\n5. **Auth Scopes Configured** - Groups mapped to OAuth2 scopes in auth_server/scopes.yml\n6. **Nginx Protected** - `/api/*` endpoints require JWT authentication\n\nNo manual configuration needed - everything is automatic!\n\n## Initialization Files\n\nThese files are involved in the automatic setup:\n\n| File | Purpose |\n|------|---------|\n| `keycloak/setup/init-keycloak.sh` | Creates groups, assigns M2M to groups, adds groups mapper |\n| `auth_server/scopes.yml` | Maps groups to scopes |\n| `docker/nginx_rev_proxy_http_only.conf` | Protects `/api/` endpoints with authentication |\n| `credentials-provider/generate_creds.sh` | Generates fresh JWT tokens |\n\n## Related Documentation\n\n- [Authentication Guide](auth.md) - General authentication and authorization\n- [CLI Reference](cli.md) - Command-line interface documentation\n- [Keycloak Integration](keycloak-integration.md) - Keycloak configuration details\n\n## Environment Variables\n\nThe token generation process uses these environment variables from `.env`:\n\n```bash\n# Keycloak Configuration\nKEYCLOAK_URL=http://localhost:8080\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_ADMIN=admin\nKEYCLOAK_ADMIN_PASSWORD=SecureKeycloakAdmin123!\n\n# M2M Client Credentials (set by init script)\nKEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_M2M_CLIENT_SECRET=\n```\n\n## Common Tasks\n\n### Register Multiple Agents\n```bash\n# Create multiple agent files\ncp cli/examples/code_reviewer_agent.json cli/examples/reviewer.json\ncp cli/examples/test_automation_agent.json cli/examples/tester.json\n\n# Register each\nuv run python cli/agent_mgmt.py register cli/examples/reviewer.json\nuv run python cli/agent_mgmt.py register cli/examples/tester.json\n\n# List all\nuv run python cli/agent_mgmt.py list\n```\n\n### Update Agent Configuration\n```bash\n# Modify the agent JSON file\nvi cli/examples/my_agent.json\n\n# Re-register to update (will overwrite)\nuv run python cli/agent_mgmt.py register cli/examples/my_agent.json\n```\n\n### Remove Agent\n```bash\nuv run python cli/agent_mgmt.py delete /my-agent\n```\n\n### Test Agent Availability\n```bash\n# Test that agent is accessible\nuv run python cli/agent_mgmt.py test /code-reviewer\n\n# If successful:\n# ✓ Agent registered\n# ✓ Endpoint is reachable\n# ✓ Agent is responding\n```\n\n## FAQ\n\n**Q: What if I get \"Agent already exists\" error?**\nA: The agent is already registered. Either delete it first or change the `path` in your JSON.\n\n**Q: Where are agents stored?**\nA: In the registry database. Agent metadata is stored at `registry/agents/` during development.\n\n**Q: Can I use a different service account?**\nA: No, `mcp-gateway-m2m` is the configured M2M account for all CLI operations. Create separate accounts only if needed for different purposes.\n\n**Q: How often should I refresh the token?**\nA: Automatically via `./credentials-provider/generate_creds.sh` which is called by the shell startup. Manual refresh only needed if token expires.\n\n**Q: What if the token expires?**\nA: Run `./credentials-provider/generate_creds.sh` to get a fresh token.\n\n**Q: Can agents be private?**\nA: Yes, set `\"visibility\": \"private\"` in agent JSON. Only registered users can access private agents.\n\n## Getting Help\n\n1. Check [Troubleshooting](#troubleshooting) section above\n2. Review JWT token contents and verify groups are present\n3. Check service is running: `docker-compose ps`\n4. View logs: `docker logs mcp-gateway-registry-auth-server-1`\n5. Verify Keycloak groups in admin UI: http://localhost:8080/admin\n\n## Summary\n\n- **Service Account:** `mcp-gateway-m2m` (auto-created during init)\n- **Token File:** `.oauth-tokens/ingress.json` (auto-loaded by CLI)\n- **Permissions:** Full agent management (register, modify, delete, list)\n- **Groups:** `mcp-servers-unrestricted`, `a2a-agent-admin` (auto-assigned)\n- **Setup:** Fully automatic - no manual configuration needed\n" }, { "path": "docs/a2a.md", "content": "# Agent-to-Agent (A2A) Protocol Support\n\nThe MCP Gateway & Registry now supports **Agent-to-Agent (A2A) communication**, enabling AI agents to securely register themselves and discover other agents within a centralized registry. This creates a self-managed agent ecosystem where agents can autonomously find, connect to, and communicate with other agents while maintaining security and access control features.\n\n## Overview\n\n### What is A2A?\n\nAgent-to-Agent (A2A) communication allows autonomous AI agents to:\n\n1. **Self-Register** - Agents register their capabilities, skills, and metadata with the central registry\n2. **Discover Other Agents** - Agents can discover and list other agents they have permission to access\n3. **Secure Communication** - All agent-to-agent communication is authenticated and authorized via Keycloak\n4. **Access Control** - Fine-grained permissions ensure agents only access agents they're authorized for\n\n### Why A2A Matters\n\nInstead of having a central orchestrator manage all agent communication:\n\n```\n❌ OLD: Orchestrator ←→ Agent A, Agent B, Agent C\n (bottleneck, single point of failure, limited scalability)\n\n✅ NEW: Agent A ←→ Registry ←→ Agent B\n Agent C discovers both via registry\n (decentralized, scalable, autonomous)\n```\n\nA2A enables:\n- **Autonomous agent networks** - Agents operate independently\n- **Dynamic discovery** - New agents join without reconfiguration\n- **Enterprise security** - Keycloak-based access control\n- **Audit trails** - Complete visibility into agent interactions\n\n## Architecture\n\n### A2A Agent Flow\n\n```\nAgent Application (AI Code)\n ↓ M2M Token (Keycloak Service Account)\n┌─────────────────────────────────────┐\n│ Agent Registry API (/api/agents) │\n│ - POST /api/agents/register │\n│ - GET /api/agents │\n│ - GET /api/agents/{path} │\n│ - PUT /api/agents/{path} │\n│ - DELETE /api/agents/{path} │\n│ - POST /api/agents/{path}/toggle │\n└─────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────┐\n│ Agent State Management │\n│ - registry/agents/agent_state.json │\n│ - registry/agents/{name}.json │\n└─────────────────────────────────────┘\n```\n\n### Three-Tier Access Control\n\nThe A2A implementation uses **three-tier access control** to ensure agents only access agents they're authorized for:\n\n1. **UI-Scopes** - What agents each group can see/access\n - `list_agents` - List agents visible to this group\n - `get_agent` - Get details of specific agents\n - `publish_agent` - Register new agents\n - `modify_agent` - Update agent metadata\n - `delete_agent` - Remove agents\n\n2. **Group Mappings** - Maps Keycloak groups to scope names\n - `mcp-registry-admin` - Full access to all agents\n - `registry-users-lob1` - Limited to LOB1 agents\n - `registry-users-lob2` - Limited to LOB2 agents\n\n3. **Individual Agent Scopes** - Detailed access per group\n - Specific agents each group can access\n - Methods each group can call on agents\n\n## Getting Started with A2A\n\n### Quick Start: Register an Agent\n\n```bash\n# 1. Ensure credentials are generated\n./credentials-provider/generate_creds.sh\n\n# 2. Register an agent\nuv run python cli/agent_mgmt.py register cli/examples/code_reviewer_agent.json\n\n# 3. Verify registration\ncurl -H \"Authorization: Bearer $(jq -r '.access_token' .oauth-tokens/admin-bot-token.json)\" \\\n http://localhost/api/agents | jq .\n```\n\n### Complete Agent Lifecycle\n\n```bash\n# Register agent\nuv run python cli/agent_mgmt.py register agent-config.json\n\n# List agents (filtered by permissions)\nuv run python cli/agent_mgmt.py list\n\n# Get agent details\nuv run python cli/agent_mgmt.py get /code-reviewer\n\n# Update agent\nuv run python cli/agent_mgmt.py update /code-reviewer agent-config.json\n\n# Disable agent (without deleting)\nuv run python cli/agent_mgmt.py toggle /code-reviewer\n\n# Re-enable agent\nuv run python cli/agent_mgmt.py toggle /code-reviewer\n\n# Delete agent\nuv run python cli/agent_mgmt.py delete /code-reviewer\n```\n\nSee [A2A Agent Management](a2a-agent-management.md) for complete CLI guide.\n\n## Agent Configuration\n\n### Agent Metadata Example\n\n```json\n{\n \"protocol_version\": \"1.0\",\n \"name\": \"Code Reviewer Agent\",\n \"description\": \"Reviews code for quality and best practices\",\n \"path\": \"/code-reviewer\",\n \"url\": \"https://agent.example.com\",\n \"skills\": [\n {\n \"id\": \"review-python\",\n \"name\": \"Python Code Review\",\n \"description\": \"Reviews Python code for style and correctness\",\n \"parameters\": {\n \"code_snippet\": {\"type\": \"string\"},\n \"max_issues\": {\"type\": \"integer\", \"default\": 10}\n }\n }\n ],\n \"security\": [\"bearer\"],\n \"tags\": [\"code-review\", \"qa\"],\n \"visibility\": \"public\",\n \"trust_level\": \"verified\",\n \"metadata\": {\n \"team\": \"qa-platform\",\n \"owner\": \"alice@example.com\",\n \"cost_center\": \"engineering\",\n \"deployment_region\": \"us-east-1\"\n }\n}\n```\n\n### Custom Metadata\n\nAgents support optional custom metadata for organization, compliance, and integration purposes. All metadata is fully searchable via semantic search.\n\n**Common Use Cases:**\n\n```json\n{\n \"metadata\": {\n \"team\": \"data-science\",\n \"owner\": \"bob@example.com\",\n \"compliance_level\": \"HIPAA\",\n \"cost_center\": \"analytics-dept\",\n \"deployment_region\": \"us-east-1\",\n \"environment\": \"production\",\n \"version\": \"3.2.1\",\n \"jira_ticket\": \"AI-456\"\n }\n}\n```\n\n**Search by Metadata:**\n- `\"team:data-science agents\"` - Find agents by team\n- `\"HIPAA compliant agents\"` - Find by compliance level\n- `\"alice@example.com owned\"` - Find by owner\n- `\"us-east-1 deployed\"` - Find by region\n\n**Key Features:**\n- Flexible JSON schema (any serializable data)\n- Fully searchable via semantic search\n- Optional field (backward compatible)\n- Type-safe validation\n\nSee [A2A Agent Management Guide](a2a-agent-management.md#custom-metadata) for detailed examples.\n\n## Testing A2A Features\n\n### Agent CRUD Test Script\n\nSimple script to test all agent operations:\n\n```bash\n# Generate fresh credentials\n./credentials-provider/generate_creds.sh\n\n# Run CRUD tests\nbash tests/agent_crud_test.sh\n\n# With custom token\nbash tests/agent_crud_test.sh /path/to/token.json\n\n# With environment variable\nTOKEN_FILE=/path/to/token.json bash tests/agent_crud_test.sh\n```\n\nTests all 9 CRUD operations:\n1. CREATE - Register new agent\n2. READ - Retrieve agent details\n3. UPDATE - Modify agent metadata\n4. LIST - List all agents\n5. TOGGLE - Disable agent\n6. TOGGLE - Re-enable agent\n7. DELETE - Remove agent\n8. VERIFY - Confirm deletion\n9. RE-CREATE - Restore agent\n\nSee [Test Quick Reference](../tests/TEST_QUICK_REFERENCE.md) for details.\n\n### Access Control Testing\n\nTest that agents only access agents they're authorized for:\n\n```bash\n# Generate tokens for all bots\n./keycloak/setup/generate-agent-token.sh admin-bot\n./keycloak/setup/generate-agent-token.sh lob1-bot\n./keycloak/setup/generate-agent-token.sh lob2-bot\n\n# Run 14 comprehensive access control tests\nbash tests/run-lob-bot-tests.sh\n```\n\nTests include:\n- **MCP Service Access** (Tests 1-6) - Verify service permissions\n- **Agent Registry API** (Tests 7-14) - Verify agent visibility and access\n\nSee [LOB Bot Access Control Testing](../tests/lob-bot-access-control-testing.md) for detailed test documentation.\n\n## Implementation Details\n\n### Core Components\n\n**CLI Module** (`cli/agent_mgmt.py`)\n- Agent registration and lifecycle management\n- CRUD operations on agent metadata\n- Argument validation and error handling\n- Structured logging and status reporting\n\n**API Routes** (`registry/api/agent_routes.py`)\n- Implements Agent Registry REST API endpoints\n- Access control enforcement via scopes\n- Token validation and authentication\n- Agent state persistence and management\n\n**Data Models** (`registry/models/`)\n- Agent schema validation\n- Skill/capability definitions\n- Security configuration models\n- State tracking models\n\n**Services** (`registry/services/agent_service.py`)\n- Agent business logic\n- State file management\n- Permission checking\n- Validation\n\n### Key Features\n\n- **JWT Token Validation** - 5-minute token TTL with expiration checks\n- **Base64 Padding** - Proper JWT payload decoding\n- **HTTP Status Codes** - Correct semantics (200, 201, 204, 400, 403, 404)\n- **Error Messages** - Comprehensive debugging information\n- **File-Based Persistence** - Simple, reliable agent state storage\n- **Keycloak Integration** - Enterprise authentication and authorization\n\n### Token Management\n\nAll A2A operations use **machine-to-machine (M2M) authentication**:\n\n```bash\n# Tokens expire in 5 minutes and must be regenerated\n./credentials-provider/generate_creds.sh\n\n# Generate specific bot tokens for testing\n./keycloak/setup/generate-agent-token.sh admin-bot\n./keycloak/setup/generate-agent-token.sh lob1-bot\n./keycloak/setup/generate-agent-token.sh lob2-bot\n```\n\nToken validation includes:\n- JWT payload decoding with base64 padding\n- Expiration time checking\n- Bearer token authentication\n- Group-based access control\n\n## Use Cases\n\n### Multi-Agent System Coordination\n\nMultiple specialized agents register themselves and discover each other:\n\n```\nCode Analyzer Agent ──┐\n │\nData Processor Agent ─├──→ Agent Registry\n │\nReport Generator Agent└──→ All agents can discover and coordinate\n```\n\n### Team Isolation with A2A\n\nDifferent teams' agents only see their team's agents:\n\n```\nLOB1 Agents (Code Reviewer, Test Automation)\n ↓\n Registry (with access control)\n ↓\nLOB1 agents can discover each other, but not LOB2 agents\n\nLOB2 Agents (Data Analysis, Security Analyzer)\n ↓\n Registry (with access control)\n ↓\nLOB2 agents can discover each other, but not LOB1 agents\n```\n\n### Autonomous Tool Discovery\n\nAgents can discover other agents providing specialized tools:\n\n```\nGeneral Agent needs to perform code review\n ↓\nQueries registry for agents with \"code-review\" capability\n ↓\nDiscovers Code Reviewer Agent, requests review\n ↓\nContinues with confidence in code quality\n```\n\n## Documentation\n\n- **[A2A Agent Management](a2a-agent-management.md)** - Complete CLI guide and examples\n- **[Agent CRUD Test](../tests/TEST_QUICK_REFERENCE.md#agent-crud-test)** - Testing CRUD operations\n- **[LOB Bot Access Control Testing](../tests/lob-bot-access-control-testing.md)** - Testing access control\n- **[Scopes Configuration](../auth_server/scopes.yml)** - Permission definitions\n- **[LLM Navigation Guide](llms.txt#section-45)** - For AI systems understanding implementation\n\n## Support\n\nFor issues or questions:\n\n1. **Review Documentation** - Check [A2A Agent Management](a2a-agent-management.md)\n2. **Run Tests** - Verify setup with `bash tests/agent_crud_test.sh`\n3. **Check Access Control** - Run `bash tests/run-lob-bot-tests.sh`\n4. **Review Logs** - Check `/tmp/*_*.log` for error details\n5. **Create Issue** - Include test output and logs\n\n---\n\n**Part of the [Agentic Community](https://github.com/agentic-community) - Building the future of AI agent ecosystems.**\n" }, { "path": "docs/agent-skills-operational-guide.md", "content": "# Agent Skills Operational Guide\n\n## Demo Video\n\nhttps://github.com/user-attachments/assets/5d1f227a-25f8-480d-9ff9-acba2498844b\n\n---\n\nThis guide covers registering, managing, and using Agent Skills in MCP Gateway Registry.\n\n## Overview\n\nAgent Skills are reusable instruction sets that enhance AI coding assistants with specialized workflows and behaviors. Skills are defined in SKILL.md files hosted on GitHub, GitLab, or Bitbucket, and registered in the MCP Gateway Registry for discovery and access control.\n\n## Quick Start\n\n### Prerequisites\n\n- MCP Gateway Registry instance running\n- Authenticated user account\n- SKILL.md file hosted on GitHub, GitLab, or Bitbucket\n\n### Step 1: Create a SKILL.md File\n\nCreate a SKILL.md file in your repository following the [agentskills.io](https://agentskills.io) specification:\n\n```markdown\n---\nname: pdf-processing\ndescription: Convert and manipulate PDF documents using various tools\n---\n\n# PDF Processing Skill\n\nThis skill helps you work with PDF documents including conversion, extraction, and manipulation.\n\n## When to Use This Skill\n\n- Converting documents to PDF format\n- Extracting text or images from PDFs\n- Merging or splitting PDF files\n- Adding watermarks or annotations\n\n## Workflow\n\n1. Identify the PDF operation needed\n2. Check for required tools (pdftk, poppler-utils)\n3. Execute the appropriate command\n4. Verify the output\n\n## Examples\n\n### Convert HTML to PDF\n```bash\nwkhtmltopdf input.html output.pdf\n```\n\n### Extract text from PDF\n```bash\npdftotext document.pdf output.txt\n```\n```\n\n### Step 2: Register the Skill\n\n**Using the UI:**\n\n1. Navigate to the Skills section in the dashboard\n2. Click \"Register Skill\"\n3. Enter the SKILL.md URL (e.g., `https://github.com/org/repo/blob/main/skills/pdf-processing/SKILL.md`)\n4. Fill in additional details:\n - Name: Auto-populated from SKILL.md or enter manually\n - Description: Brief description of the skill\n - Visibility: Public, Private, or Group\n - Tags: Add relevant tags for discovery\n5. Click \"Register\"\n\n**Using the API:**\n\nFor API details, see the OpenAPI specification at [api/openapi.json](../api/openapi.json). Use the `registry_management.py` CLI for Python-based commands (see [CLI Commands](#cli-commands) section below).\n\n### Step 3: Verify Registration\n\nCheck that the skill is registered and healthy using the CLI:\n\n```bash\n# Get skill details\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-get --path pdf-processing\n\n# Check skill health\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-health --path pdf-processing\n```\n\n## Managing Skills\n\n### List All Skills\n\n**UI:** Navigate to the Skills section in the dashboard.\n\n**CLI:**\n```bash\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-list\n```\n\nFor custom curl commands with query parameters (e.g., `include_disabled`, `tag`), see [api/openapi.json](../api/openapi.json).\n\n### Update a Skill\n\n**UI:** Click the edit (pencil) icon on a skill card.\n\n**API:** For update endpoints, see the OpenAPI specification at [api/openapi.json](../api/openapi.json).\n\n### Enable/Disable Skills\n\n**UI:** Use the toggle switch on the skill card.\n\n**CLI:**\n```bash\n# Disable a skill\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-toggle --path pdf-processing --enabled false\n\n# Enable a skill\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-toggle --path pdf-processing --enabled true\n```\n\n### Delete a Skill\n\n**UI:** Click the delete (trash) icon on a skill card.\n\n**CLI:**\n```bash\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-delete --path pdf-processing\n```\n\n## Health Monitoring\n\n### Check Skill Health\n\nThe registry verifies that SKILL.md files are accessible:\n\n**UI:** Click the refresh icon on a skill card to check health.\n\n**CLI:**\n```bash\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-health --path pdf-processing\n```\n\nResponse example:\n```json\n{\n \"healthy\": true,\n \"status_code\": 200,\n \"checked_at\": \"2025-02-07T15:30:00Z\"\n}\n```\n\n### Health Status Indicators\n\n| Status | Meaning |\n|--------|---------|\n| Healthy (green) | SKILL.md is accessible |\n| Unhealthy (red) | SKILL.md fetch failed |\n| Unknown (yellow) | Not yet checked |\n\n## Rating Skills\n\n### Submit a Rating\n\n**UI:** Click the star rating widget on a skill card.\n\n**CLI:**\n```bash\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-rate --path pdf-processing --rating 5\n```\n\n### View Ratings\n\n**UI:** Rating is displayed on the skill card.\n\n**CLI:**\n```bash\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-rating --path pdf-processing\n```\n\nResponse example:\n```json\n{\n \"num_stars\": 4.5,\n \"rating_details\": [\n {\"user\": \"alice\", \"rating\": 5},\n {\"user\": \"bob\", \"rating\": 4}\n ]\n}\n```\n\n## Viewing Skill Content\n\n### View SKILL.md Content\n\n**UI:** Click the info (i) icon on a skill card to open the content modal.\n\nThe modal displays:\n- YAML frontmatter in a table format\n- Formatted markdown content\n- Links to GitHub source\n- Copy and download buttons\n\n**CLI:**\n```bash\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-content --path pdf-processing\n```\n\nResponse example:\n```json\n{\n \"content\": \"---\\nname: pdf-processing\\n...\",\n \"url\": \"https://raw.githubusercontent.com/org/repo/main/skills/pdf-processing/SKILL.md\"\n}\n```\n\n## Tool Validation\n\nSkills can reference required MCP server tools. Validate tool availability:\n\n**UI:** Click the wrench icon on a skill card.\n\n**API:** For tool validation endpoints, see [api/openapi.json](../api/openapi.json).\n\nResponse example:\n```json\n{\n \"all_available\": true,\n \"tool_results\": [\n {\n \"tool_name\": \"Bash\",\n \"server_path\": \"/servers/claude-tools\",\n \"available\": true\n }\n ],\n \"missing_tools\": []\n}\n```\n\n## Access Control\n\n### Visibility Levels\n\n| Level | Description |\n|-------|-------------|\n| Public | Visible to all authenticated users |\n| Private | Visible only to the owner |\n| Group | Visible to specified groups |\n\n### Set Visibility\n\nFor visibility update endpoints, see [api/openapi.json](../api/openapi.json). Visibility options are:\n- `public` - Visible to all authenticated users\n- `private` - Visible only to the owner\n- `group` - Visible to specified groups (requires `allowed_groups` parameter)\n\n## Search and Discovery\n\n### Search Skills\n\n**UI:** Use the search bar in the Skills section.\n\n**CLI:**\n```bash\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-search --query \"pdf\"\n```\n\nFor advanced search with multiple filters, see [api/openapi.json](../api/openapi.json).\n\n## Integration with AI Assistants\n\n### Claude Code Integration\n\nSkills in Claude Code are stored as SKILL.md files in skill directories. To use a skill from the registry:\n\n1. **Download the skill content** to your local skills directory:\n\n```bash\n# Global skills directory\nmkdir -p ~/.claude/skills/pdf-processing\ncurl -H \"Authorization: Bearer \" \\\n https://your-registry.com/api/skills/pdf-processing/content \\\n | jq -r '.content' > ~/.claude/skills/pdf-processing/SKILL.md\n\n# Or project-level skills\nmkdir -p .claude/skills/pdf-processing\ncurl -H \"Authorization: Bearer \" \\\n https://your-registry.com/api/skills/pdf-processing/content \\\n | jq -r '.content' > .claude/skills/pdf-processing/SKILL.md\n```\n\n2. **Invoke the skill** using the slash command (folder name becomes the command):\n\n```\n/pdf-processing\n```\n\nSee [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) for more details.\n\n### Cursor Integration\n\nCursor uses Agent Skills stored in `.agents/skills/` directories. To use a skill from the registry:\n\n1. **Download the skill content** to your project's skills directory:\n\n```bash\nmkdir -p .agents/skills/pdf-processing\ncurl -H \"Authorization: Bearer \" \\\n https://your-registry.com/api/skills/pdf-processing/content \\\n | jq -r '.content' > .agents/skills/pdf-processing/SKILL.md\n```\n\n2. **Regenerate AGENTS.md** if using custom rules (required after adding new skills)\n\nSee [Cursor Agent Skills Documentation](https://cursor.com/docs/context/skills) for more details.\n\n## Troubleshooting\n\n### Skill Registration Fails\n\n1. **Invalid URL**: Ensure the URL points to a valid SKILL.md file\n2. **Name conflict**: Skill names must be unique\n3. **Invalid name format**: Names must be lowercase alphanumeric with hyphens\n\n### Skill Shows as Unhealthy\n\n1. **Check URL**: Verify the SKILL.md file is accessible in a browser\n2. **Repository access**: Ensure the repository is public or accessible\n3. **Raw URL**: The registry uses raw URLs; verify raw content is accessible\n\n### Rating Not Saved\n\n1. **Authentication**: Ensure you're authenticated\n2. **Valid range**: Ratings must be between 1 and 5\n3. **Refresh**: Try refreshing the page after rating\n\n### Content Not Loading\n\n1. **CORS**: The registry proxies content to avoid CORS issues\n2. **Health check**: Verify the skill is healthy first\n3. **Network**: Check network connectivity to the source\n\n## Best Practices\n\n### Skill Naming\n\n- Use lowercase letters and hyphens only\n- Choose descriptive, specific names\n- Avoid generic names like \"helper\" or \"utils\"\n\n### SKILL.md Content\n\n- Include clear trigger conditions\n- Provide step-by-step workflows\n- Add practical examples\n- Document required tools\n\n### Tagging\n\n- Use consistent tag conventions\n- Include category tags (e.g., \"documents\", \"automation\")\n- Add technology tags (e.g., \"pdf\", \"python\")\n\n### Visibility\n\n- Start with private for testing\n- Use group visibility for team-specific skills\n- Make public for community sharing\n\n## CLI Commands\n\nThe `registry_management.py` CLI provides commands for managing skills from the command line.\n\n### Common Parameters\n\nGlobal parameters must come **before** the subcommand:\n\n| Parameter | Description |\n|-----------|-------------|\n| `--registry-url` | Registry base URL (default: http://localhost:8000) |\n| `--token-file` | Path to JSON file containing access token |\n\n### Register Skills from Anthropic Skills Repository\n\nRegister coding, documentation, and spreadsheet skills from the official [anthropics/skills](https://github.com/anthropics/skills) repository:\n\n```bash\n# Set common variables\nREGISTRY_URL=\"https://your-registry.com\"\nTOKEN_FILE=\"/path/to/.token\"\n\n# Register doc-coauthoring skill (collaborative documentation)\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-register \\\n --name doc-coauthoring \\\n --url \"https://github.com/anthropics/skills/blob/main/skills/doc-coauthoring/SKILL.md\" \\\n --description \"Guide users through structured workflow for co-authoring documentation\" \\\n --tags docs,authoring,collaboration \\\n --visibility public\n\n# Register docx skill (Word document handling)\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-register \\\n --name docx \\\n --url \"https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md\" \\\n --description \"Create and manipulate Microsoft Word documents\" \\\n --tags docs,word,docx,documents \\\n --visibility public\n\n# Register xlsx skill (Excel spreadsheet handling)\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-register \\\n --name xlsx \\\n --url \"https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md\" \\\n --description \"Create and manipulate Excel spreadsheets\" \\\n --tags spreadsheet,excel,xlsx,data \\\n --visibility public\n\n# Register pdf skill (PDF document handling)\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-register \\\n --name pdf \\\n --url \"https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md\" \\\n --description \"Create and manipulate PDF documents\" \\\n --tags pdf,documents,conversion \\\n --visibility public\n\n# Register mcp-builder skill (MCP server development)\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-register \\\n --name mcp-builder \\\n --url \"https://github.com/anthropics/skills/blob/main/skills/mcp-builder/SKILL.md\" \\\n --description \"Build MCP servers and tools for AI assistant integrations\" \\\n --tags mcp,coding,development,servers \\\n --visibility public\n```\n\n### Other Skill CLI Commands\n\n```bash\n# List all skills\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-list\n\n# Get skill details\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-get --path doc-coauthoring\n\n# Check skill health\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-health --path doc-coauthoring\n\n# Get SKILL.md content\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-content --path doc-coauthoring\n\n# Search for skills\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-search --query \"document\"\n\n# Toggle skill enabled/disabled\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-toggle --path doc-coauthoring --enabled false\n\n# Rate a skill (1-5 stars)\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-rate --path doc-coauthoring --rating 5\n\n# Get skill rating\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-rating --path doc-coauthoring\n\n# Delete a skill\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" \\\n --token-file \"$TOKEN_FILE\" \\\n skill-delete --path doc-coauthoring\n```\n\n### Token File Format\n\nThe token file should be a JSON file with the following structure:\n\n```json\n{\n \"tokens\": {\n \"access_token\": \"eyJ...\"\n }\n}\n```\n\nOr the simpler format:\n\n```json\n{\n \"access_token\": \"eyJ...\"\n}\n```\n\n## API Reference\n\nFor complete API endpoint documentation, see:\n- **OpenAPI Specification**: [api/openapi.json](../api/openapi.json) - Full API spec for writing custom curl commands\n- **API Reference**: [API Reference](api-reference.md) - Human-readable endpoint documentation\n\n## Related Documentation\n\n- [Agent Skills Architecture](design/agent-skills-architecture.md)\n- [Authentication](auth.md)\n- [Federation](federation.md)\n" }, { "path": "docs/agent-visibility-and-group-access.md", "content": "# Agent Visibility and Group-Based Access Control\n\nThis document explains how the MCP Gateway Registry controls who can see and use agents using two layers: **group scope configs** (admin-managed) and **agent-level allowed_groups** (publisher-managed).\n\n## How Group Scopes Work Today\n\nAn admin creates a group scope that defines exactly which agents a group can access. Group scopes can be created through:\n\n- The **UI** (IAM group management page)\n- The **CLI** (`registry_management.py scope-create`)\n- The **API** directly (see [openapi.json](https://github.com/agentic-community/mcp-gateway-registry/blob/main/api/openapi.json))\n\nThe scope is synced to the identity provider (Keycloak, Entra, Cognito, Okta).\n\n### Narrow Scope Example: public-mcp-users\n\nUsers in the `public-mcp-users` group can only see the `/flight-booking` agent:\n\n```json\n{\n \"scope_name\": \"public-mcp-users\",\n \"group_mappings\": [\"public-mcp-users\"],\n \"ui_permissions\": {\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n }\n}\n```\n\nThis is a **narrow scope**: the admin explicitly lists which agents the group can access.\n\n### Broad Scope Example: registry-admins\n\nAdmin users can see all agents:\n\n```json\n{\n \"_id\": \"registry-admins\",\n \"group_mappings\": [\"registry-admins\"],\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"get_agent\": [\"all\"],\n \"publish_agent\": [\"all\"],\n \"modify_agent\": [\"all\"],\n \"delete_agent\": [\"all\"]\n }\n}\n```\n\nThis is a **broad scope**: `\"list_agents\": [\"all\"]` means the group can see every agent in the registry.\n\n## The Problem with Broad Scopes\n\nBroad scopes are convenient for large teams. An admin might configure an `engineering` group with `\"list_agents\": [\"all\"]` so engineers can discover and use any agent without filing a request each time.\n\nBut what happens when someone publishes a sensitive agent? Say the HR team publishes a `/salary-calculator` agent. With a broad scope, every engineer can see it. The HR team lead does not want that, but they cannot change the group scope config because that requires an admin.\n\nThis is where `allowed_groups` comes in.\n\n## What allowed_groups Does\n\nWhen registering or editing an agent, the publisher can set `visibility: \"group-restricted\"` and specify `allowed_groups`. This acts as a second filter **on top of** the IAM group scope.\n\nThe two layers work as an AND:\n\n1. **IAM scope check**: Is the agent in the user's `accessible_agents` list (from their group scope config)?\n2. **allowed_groups check**: If the agent is `group-restricted`, do the user's JWT groups intersect with the agent's `allowed_groups`?\n\nA user must pass **both** checks to see the agent.\n\n## Concrete Scenario\n\n### Setup\n\nAn enterprise has three groups configured in the identity provider:\n\n| Group | Scope Type | Agent Access |\n|-------|-----------|--------------|\n| `engineering` | Broad | `\"list_agents\": [\"all\"]` |\n| `hr-team` | Broad | `\"list_agents\": [\"all\"]` |\n| `public-mcp-users` | Narrow | `\"list_agents\": [\"/flight-booking\"]` |\n\nThe registry has three agents:\n\n| Agent | Visibility | allowed_groups |\n|-------|-----------|----------------|\n| `/flight-booking` | `public` | `[]` |\n| `/code-reviewer` | `public` | `[]` |\n| `/salary-calculator` | `group-restricted` | `[\"hr-team\"]` |\n\n### Who Sees What\n\n**Alice (in `engineering` group):**\n- `/flight-booking`: IAM scope = `[\"all\"]`, so passes. Visibility = `public`, no group check. **Sees it.**\n- `/code-reviewer`: Same logic. **Sees it.**\n- `/salary-calculator`: IAM scope = `[\"all\"]`, so passes. But visibility = `group-restricted` and Alice's groups (`engineering`) do not intersect with `allowed_groups` (`hr-team`). **Does NOT see it.**\n\n**Bob (in `hr-team` group):**\n- `/flight-booking`: IAM scope = `[\"all\"]`, passes. Visibility = `public`. **Sees it.**\n- `/code-reviewer`: Same. **Sees it.**\n- `/salary-calculator`: IAM scope = `[\"all\"]`, passes. Visibility = `group-restricted` and Bob's groups (`hr-team`) intersect with `allowed_groups` (`hr-team`). **Sees it.**\n\n**Carol (in `public-mcp-users` group):**\n- `/flight-booking`: IAM scope = `[\"/flight-booking\"]`, passes. Visibility = `public`. **Sees it.**\n- `/code-reviewer`: IAM scope = `[\"/flight-booking\"]`, does NOT include `/code-reviewer`. **Does NOT see it.** (Filtered at IAM layer, `allowed_groups` is never checked.)\n- `/salary-calculator`: IAM scope does NOT include `/salary-calculator`. **Does NOT see it.**\n\n### The Key Takeaway\n\n- For **narrow-scoped groups** like `public-mcp-users`, the IAM scope already controls per-agent access. The `allowed_groups` field has no effect because the IAM layer filters first.\n- For **broad-scoped groups** like `engineering`, the IAM scope grants access to everything. The `allowed_groups` field is the publisher's mechanism to restrict visibility within that broad grant, without needing to ask an admin to create a narrower scope.\n\n## When to Use allowed_groups\n\n| Your group scope config | Use allowed_groups? | Why |\n|------------------------|---------------------|-----|\n| Narrow (`[\"/agent-a\", \"/agent-b\"]`) | No benefit | IAM already controls per-agent access |\n| Broad (`[\"all\"]`) | Yes, for sensitive agents | Lets the publisher restrict who sees their agent |\n| Mix of narrow and broad groups | Yes, for agents that broad groups should not all see | Narrows access for broad groups while narrow groups are unaffected (filtered at IAM layer first) |\n\n## Visibility Modes\n\n| Visibility | IAM Check | allowed_groups Check | Who Can See |\n|------------|-----------|---------------------|-------------|\n| `public` | Must have IAM scope | No | All users with IAM access |\n| `group-restricted` | Must have IAM scope | Must be in allowed_groups | Users with IAM access AND in allowed groups |\n| `private` | Must have IAM scope | No | Only the agent owner |\n| `unlisted` | Must have IAM scope | No | Users with the direct URL |\n\n## API Examples\n\n### Register a Group-Restricted Agent\n\nThe HR team lead publishes a salary calculator that only `hr-team` can see:\n\n```bash\ncurl -s -X POST \"https://your-registry/api/agents/register\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Salary Calculator\",\n \"path\": \"/salary-calculator\",\n \"version\": \"1.0.0\",\n \"url\": \"https://example.com/salary-calculator\",\n \"supportedProtocol\": \"a2a\",\n \"description\": \"Calculate salary projections and tax estimates\",\n \"visibility\": \"group-restricted\",\n \"allowedGroups\": [\"hr-team\"],\n \"skills\": [\n {\n \"id\": \"calculate-salary\",\n \"name\": \"Calculate Salary\",\n \"description\": \"Calculate salary projections\",\n \"tags\": [\"hr\", \"finance\"],\n \"inputSchema\": {}\n }\n ]\n }'\n```\n\n### Register a Public Agent (No Group Restriction)\n\nA general-purpose agent visible to anyone with IAM access:\n\n```bash\ncurl -s -X POST \"https://your-registry/api/agents/register\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Flight Booking\",\n \"path\": \"/flight-booking\",\n \"version\": \"1.0.0\",\n \"url\": \"https://example.com/flight-booking\",\n \"supportedProtocol\": \"a2a\",\n \"description\": \"Book flights for business travel\",\n \"visibility\": \"public\",\n \"skills\": [\n {\n \"id\": \"book-flight\",\n \"name\": \"Book Flight\",\n \"description\": \"Search and book flights\",\n \"tags\": [\"travel\"],\n \"inputSchema\": {}\n }\n ]\n }'\n```\n\n### Update allowed_groups\n\nExpand access to include the `finance-team`:\n\n```bash\ncurl -s -X PUT \"https://your-registry/api/agents/salary-calculator\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Salary Calculator\",\n \"path\": \"/salary-calculator\",\n \"version\": \"1.0.0\",\n \"url\": \"https://example.com/salary-calculator\",\n \"supportedProtocol\": \"a2a\",\n \"description\": \"Calculate salary projections and tax estimates\",\n \"visibility\": \"group-restricted\",\n \"allowedGroups\": [\"hr-team\", \"finance-team\"],\n \"skills\": [\n {\n \"id\": \"calculate-salary\",\n \"name\": \"Calculate Salary\",\n \"description\": \"Calculate salary projections\",\n \"tags\": [\"hr\", \"finance\"],\n \"inputSchema\": {}\n }\n ]\n }'\n```\n\n### List Agents Filtered by allowed_groups\n\n```bash\n# Show only agents shared with hr-team\ncurl -s \"https://your-registry/api/agents?allowed_groups=hr-team\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq .\n\n# Show agents shared with either hr-team or finance-team\ncurl -s \"https://your-registry/api/agents?allowed_groups=hr-team,finance-team\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq .\n```\n\n### Group Scope Config for a Broad-Access Team\n\nTo create an `engineering` group with broad agent access (where `allowed_groups` becomes useful):\n\n```json\n{\n \"scope_name\": \"engineering\",\n \"description\": \"Engineering team with broad agent access\",\n \"group_mappings\": [\"engineering\"],\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"get_agent\": [\"all\"],\n \"list_service\": [\"all\"]\n },\n \"create_in_idp\": true\n}\n```\n\nUpload via CLI:\n\n```bash\npython api/registry_management.py --registry-url https://your-registry \\\n --token-file .token-admin import-group --file engineering.json\n```\n\nOr via curl:\n\n```bash\ncurl -s -X POST \"https://your-registry/api/servers/groups/import\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d @engineering.json\n```\n\nWith this config, all engineers see every `public` agent but cannot see `group-restricted` agents unless their group is in the agent's `allowed_groups`.\n" }, { "path": "docs/agentcore-auto-registration-prerequisites.md", "content": "# AgentCore Auto-Registration Prerequisites\n\nThis guide covers the setup required before using the AgentCore auto-registration CLI (`python -m cli.agentcore sync`). The prerequisites depend on the **authorizer type** configured on each AgentCore Gateway.\n\n| Authorizer Type | What You Need |\n|-----------------|---------------|\n| `CUSTOM_JWT` | OAuth2 M2M client credentials from your identity provider (Cognito, Auth0, Okta, etc.) |\n| `AWS_IAM` | AWS credentials with appropriate IAM permissions |\n| `NONE` | No setup required |\n\n> The auto-registration CLI discovers the authorizer type from each gateway automatically. You only need to prepare credentials for the authorizer types your gateways use.\n\n---\n\n## IAM Permissions for Discovery\n\nRegardless of gateway authorizer type, the CLI needs AWS credentials with permissions to call the Bedrock AgentCore control-plane APIs for resource discovery.\n\n### Required IAM Policy\n\nAttach the following policy to the IAM user or role running the CLI:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"AgentCoreDiscovery\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"bedrock-agent:ListAgentGateways\",\n \"bedrock-agent:GetAgentGateway\",\n \"bedrock-agent:ListAgentRuntimes\",\n \"bedrock-agent:GetAgentRuntime\",\n \"bedrock-agent:ListTargets\",\n \"sts:GetCallerIdentity\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n- `bedrock-agent:ListAgentGateways` / `GetAgentGateway` — discover gateways and their details\n- `bedrock-agent:ListAgentRuntimes` / `GetAgentRuntime` — discover runtimes and their protocol configuration\n- `bedrock-agent:ListTargets` — enumerate targets behind each gateway\n- `sts:GetCallerIdentity` — verify AWS credentials are valid (also used for `AWS_IAM` authorizer verification)\n\n### AWS Credential Setup\n\nThe CLI uses the standard boto3 credential chain. Configure credentials using any of these methods:\n\n**Option A: Environment variables**\n\n```bash\nexport AWS_ACCESS_KEY_ID=AKIA...\nexport AWS_SECRET_ACCESS_KEY=...\nexport AWS_REGION=us-east-1\n```\n\n**Option B: AWS CLI profile**\n\n```bash\naws configure --profile agentcore-sync\nexport AWS_PROFILE=agentcore-sync\nexport AWS_REGION=us-east-1\n```\n\n**Option C: IAM role (EC2 / ECS / Lambda)**\n\nIf running on an AWS compute resource, attach the IAM policy above to the instance role or task role. No explicit credential configuration is needed.\n\n---\n\n## CUSTOM_JWT Authorizer — OAuth2 M2M Client Setup\n\nGateways with `CUSTOM_JWT` authorizer require OAuth2 machine-to-machine (M2M) client credentials. The CLI uses these credentials to generate egress tokens for authenticating with the gateway.\n\nYou need to create an M2M client in your OAuth2 provider and note the **Client ID**, **Client Secret**, and **OAuth2 domain URL**.\n\n### Amazon Cognito\n\n1. Open the [Amazon Cognito console](https://console.aws.amazon.com/cognito/) and select the User Pool associated with your AgentCore Gateway.\n\n2. Navigate to **App integration** → **App clients** and create a new app client:\n - App type: **Confidential client**\n - App client name: e.g., `agentcore-sync-m2m`\n - Generate a client secret: **Yes**\n - Authentication flows: **Client credentials** (`ALLOW_CUSTOM_AUTH` is not needed)\n\n3. Under **Hosted UI**, configure the allowed OAuth scopes for the client. Use the scope defined by your AgentCore Gateway's resource server (e.g., `default-m2m-resource-server-XXXXXXXX/read`).\n\n4. Note the following values:\n - **Client ID**: shown on the app client page\n - **Client Secret**: click \"Show client secret\"\n - **OAuth2 domain**: `https://.auth..amazoncognito.com`\n\n5. Set the environment variable:\n ```bash\n export OAUTH_DOMAIN=\"https://.auth..amazoncognito.com\"\n ```\n\n### Auth0\n\n1. Log in to the [Auth0 Dashboard](https://manage.auth0.com/) and navigate to **Applications** → **Applications**.\n\n2. Click **Create Application**:\n - Name: e.g., `agentcore-sync-m2m`\n - Application type: **Machine to Machine**\n\n3. Authorize the application for the API (audience) that your AgentCore Gateway uses. Select the required scopes.\n\n4. Note the following values from the **Settings** tab:\n - **Client ID**\n - **Client Secret**\n - **Domain**: e.g., `your-tenant.auth0.com`\n\n5. Set the environment variable:\n ```bash\n export OAUTH_DOMAIN=\"https://your-tenant.auth0.com\"\n ```\n\n### Okta\n\n1. Log in to the [Okta Admin Console](https://developer.okta.com/) and navigate to **Applications** → **Applications**.\n\n2. Click **Create App Integration**:\n - Sign-in method: **API Services** (client credentials)\n - App integration name: e.g., `agentcore-sync-m2m`\n\n3. On the app's **General** tab, note:\n - **Client ID**\n - **Client Secret**\n\n4. Under **Okta API Scopes**, grant the scopes required by your AgentCore Gateway.\n\n5. Set the environment variable using your Okta domain:\n ```bash\n export OAUTH_DOMAIN=\"https://your-org.okta.com\"\n ```\n\n### Providing Credentials to the CLI\n\nYou can provide OAuth2 credentials in two ways:\n\n**Option A: Environment variables (recommended for CI/CD)**\n\n```bash\n# Gateway 1: CUSTOM_JWT (requires OAuth2 credentials)\nexport AGENTCORE_CLIENT_ID_1=\"your-client-id\"\nexport AGENTCORE_CLIENT_SECRET_1=\"your-client-secret\"\nexport AGENTCORE_GATEWAY_ARN_1=\"arn:aws:bedrock:us-east-1:123456789012:gateway/gw-abc123\"\nexport AGENTCORE_SERVER_NAME_1=\"my-oauth-gateway\"\nexport AGENTCORE_AUTHORIZER_TYPE_1=\"CUSTOM_JWT\"\n\n# Gateway 2: AWS_IAM (no OAuth2 credentials needed)\nexport AGENTCORE_GATEWAY_ARN_2=\"arn:aws:bedrock:us-east-1:123456789012:gateway/gw-def456\"\nexport AGENTCORE_SERVER_NAME_2=\"my-iam-gateway\"\nexport AGENTCORE_AUTHORIZER_TYPE_2=\"AWS_IAM\"\n\n# Gateway 3: NONE (no credentials needed)\nexport AGENTCORE_GATEWAY_ARN_3=\"arn:aws:bedrock:us-east-1:123456789012:gateway/gw-ghi789\"\nexport AGENTCORE_SERVER_NAME_3=\"my-public-gateway\"\nexport AGENTCORE_AUTHORIZER_TYPE_3=\"NONE\"\n```\n\n> The `AGENTCORE_AUTHORIZER_TYPE_{N}` variable is optional — the CLI auto-detects the authorizer type from the gateway. Set it explicitly only if you want to override the detected type.\n\n**Option B: Interactive prompt**\n\nIf no environment variables are set, the CLI will prompt for credentials during `sync`:\n\n```\nOAuth2 credentials needed for gateway: arn:aws:bedrock:us-east-1:123456789012:gateway/gw-abc123\n(Press Enter to skip)\n Client ID: \n Client Secret: \n```\n\nThe Client Secret is entered securely (not echoed to the terminal).\n\n---\n\n## AWS_IAM Authorizer\n\nGateways with `AWS_IAM` authorizer use the standard AWS credential chain for authentication (SigV4 signing). No OAuth2 client setup is needed.\n\n### What You Need\n\n1. AWS credentials configured (see [AWS Credential Setup](#aws-credential-setup) above).\n2. The `sts:GetCallerIdentity` permission (included in the discovery policy above).\n\nThe CLI verifies your AWS credentials by calling `sts:GetCallerIdentity` during the sync process. If verification succeeds, the gateway is registered without any OAuth2 credential collection or token generation.\n\n---\n\n## NONE Authorizer\n\nGateways with `NONE` authorizer require **no setup**. The CLI registers these gateways without collecting credentials or generating tokens.\n\n---\n\n## Cross-Account Scanning\n\nTo scan AgentCore resources in other AWS accounts, you need an IAM role in each target account that the CLI can assume.\n\n### Target Account Role Setup\n\nIn each target account, create an IAM role (default name: `AgentCoreSyncRole`) with:\n\n1. **Trust policy** — allows the caller's account to assume the role:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Principal\": {\n \"AWS\": \"arn:aws:iam::CALLER_ACCOUNT_ID:root\"\n },\n \"Action\": \"sts:AssumeRole\",\n \"Condition\": {}\n }\n ]\n}\n```\n\nReplace `CALLER_ACCOUNT_ID` with the AWS account ID where the CLI runs. You can restrict the principal to a specific IAM user or role instead of `root` for tighter security.\n\n2. **Permissions policy** — the same AgentCore discovery policy from [IAM Permissions for Discovery](#iam-permissions-for-discovery):\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"AgentCoreDiscovery\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"bedrock-agent:ListAgentGateways\",\n \"bedrock-agent:GetAgentGateway\",\n \"bedrock-agent:ListAgentRuntimes\",\n \"bedrock-agent:GetAgentRuntime\",\n \"bedrock-agent:ListTargets\",\n \"sts:GetCallerIdentity\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n### Caller Account Permissions\n\nThe IAM user or role running the CLI also needs permission to assume the role in each target account:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"AssumeAgentCoreSyncRole\",\n \"Effect\": \"Allow\",\n \"Action\": \"sts:AssumeRole\",\n \"Resource\": [\n \"arn:aws:iam::111111111111:role/AgentCoreSyncRole\",\n \"arn:aws:iam::222222222222:role/AgentCoreSyncRole\"\n ]\n }\n ]\n}\n```\n\nReplace the account IDs and role name with your actual values.\n\n### Quick Setup (AWS CLI)\n\n```bash\n# In each target account, create the role:\naws iam create-role \\\n --role-name AgentCoreSyncRole \\\n --assume-role-policy-document file://trust-policy.json\n\naws iam put-role-policy \\\n --role-name AgentCoreSyncRole \\\n --policy-name AgentCoreDiscovery \\\n --policy-document file://discovery-policy.json\n```\n\n---\n\n## Verification Checklist\n\nBefore running `python -m cli.agentcore sync`, verify:\n\n- [ ] AWS credentials are configured and can call `sts:GetCallerIdentity`\n- [ ] The IAM policy includes all required `bedrock-agent:*` permissions\n- [ ] For `CUSTOM_JWT` gateways: OAuth2 M2M client is created and `OAUTH_DOMAIN` is set\n- [ ] For `AWS_IAM` gateways: AWS credentials are available in the environment\n- [ ] The MCP Gateway Registry is running and accessible at the configured `REGISTRY_URL`\n- [ ] A valid registry auth token exists at the configured `--token-file` path (default: `.oauth-tokens/ingress.json`). Generate it with: `python credentials-provider/oauth/ingress_oauth.py`\n- [ ] For cross-account scanning: `AgentCoreSyncRole` (or custom role) exists in each target account\n- [ ] For cross-account scanning: The caller has `sts:AssumeRole` permission for each target role\n\n## Next Steps\n\n- [Auto-Registration CLI Usage](agentcore.md#auto-registration) — CLI commands, environment variables, and troubleshooting\n- [AgentCore Gateway Integration Guide](agentcore.md) — Manual gateway registration walkthrough\n" }, { "path": "docs/agentcore.md", "content": "# Registering Amazon Bedrock AgentCore Assets\n\nThis guide covers how to register AgentCore Gateways and Agent Runtimes in the MCP Gateway Registry. There are two approaches: bulk auto-registration (scan an entire AWS account) or per-server manual registration (one resource at a time).\n\n## Two Ways to Register AgentCore Assets\n\n| Approach | Best For | Token Management |\n|----------|----------|-----------------|\n| **Method 1: Bulk Scanner** | Discovering and registering all resources in an AWS account at once | Automated via `token_refresher.py` |\n| **Method 2: Per-Server Registration** | Registering individual gateways or agents manually (same as any other MCP server/agent) | Manual token generation |\n\n---\n\n## Method 1: Bulk Scanner (Auto-Registration)\n\nThe AgentCore scanner CLI automates the discovery and registration of all AgentCore Gateways and Agent Runtimes in your AWS account. Instead of manually creating JSON configuration files for each resource, the CLI scans your account, builds registrations, and writes a token refresh manifest -- all in one command. A separate token refresher process then keeps egress tokens up to date.\n\nThe scanner and token refresher work with any OIDC-compliant identity provider -- Cognito, Auth0, Okta, Entra ID, Keycloak, or any custom provider. The IdP is auto-detected from the OIDC discovery URL in each gateway's configuration.\n\n> **Prerequisites:** Before using auto-registration, complete the setup steps in the [Auto-Registration Prerequisites Guide](agentcore-auto-registration-prerequisites.md).\n\n### Step 1: Scan and Register\n\n```bash\n# Discover resources without registering (preview)\nuv run python -m cli.agentcore sync --dry-run\n\n# Register all gateways and runtimes\nuv run python -m cli.agentcore sync\n\n# Overwrite existing registrations (update metadata if changed)\nuv run python -m cli.agentcore sync --overwrite\n\n# List discovered resources without registering\nuv run python -m cli.agentcore list\n```\n\nThe sync command:\n1. Discovers all READY gateways and runtimes via AWS Bedrock AgentCore API\n2. Registers each gateway as an MCP Server and each runtime as an MCP Server (protocol=MCP) or A2A Agent (protocol=HTTP/A2A)\n3. Writes `token_refresh_manifest.json` listing all CUSTOM_JWT gateways that need token refresh\n\n> **Note:** Agents imported from runtimes are registered with an empty skills array. To add skills after import, use the agent edit dialog in the UI or the `PUT /api/agents/{path}` API endpoint.\n\n### Step 2: Configure Client Secrets (for CUSTOM_JWT Gateways)\n\nCUSTOM_JWT gateways need OAuth2 client secrets to generate egress tokens. Add them to your `.env` file:\n\n```bash\n# Per-client secret (highest priority) -- use the client_id from allowed_clients\nOAUTH_CLIENT_SECRET_49ujl0b9ser72gnp6q1ph9v6vs=your-secret-here\n\n# Or vendor-level secrets (shared across all gateways for that IdP)\nAUTH0_CLIENT_SECRET=your-auth0-secret\nOKTA_CLIENT_SECRET=your-okta-secret\nENTRA_CLIENT_SECRET=your-entra-secret\nKEYCLOAK_CLIENT_SECRET=your-keycloak-secret\n```\n\n**Cognito gateways need no configuration** -- the token refresher auto-retrieves client secrets via the AWS API (`describe_user_pool_client`).\n\nSecret resolution priority:\n1. Per-client env var: `OAUTH_CLIENT_SECRET_`\n2. Cognito auto-retrieval via AWS API (Cognito only)\n3. Vendor-specific env var: `AUTH0_CLIENT_SECRET`, etc.\n\n### Step 3: Run Token Refresher\n\nThe token refresher reads the manifest, resolves secrets, fetches OAuth2 tokens, PATCHes them into the registry, and triggers a security rescan for each updated server (enabled by default, requires admin privileges on the registry token):\n\n```bash\n# One-time refresh\nuv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n# Continuous mode (sidecar -- refreshes every 45 minutes)\nuv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n --loop --interval 2700\n```\n\nOr set up a cron job:\n\n```bash\n# Refresh every 45 minutes (tokens typically expire in 60 min)\n*/45 * * * * cd /app && uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n >> /var/log/token-refresher.log 2>&1\n```\n\n### Scanner CLI Reference\n\n#### Sync -- Discover and Register\n\n```bash\n# Basic sync\nuv run python -m cli.agentcore sync\n\n# Dry-run preview\nuv run python -m cli.agentcore sync --dry-run\n\n# Overwrite existing registrations\nuv run python -m cli.agentcore sync --overwrite\n\n# Register only gateways (skip runtimes)\nuv run python -m cli.agentcore sync --gateways-only\n\n# Register only runtimes (skip gateways)\nuv run python -m cli.agentcore sync --runtimes-only\n\n# Also register individual mcpServer gateway targets as separate MCP Servers\nuv run python -m cli.agentcore sync --include-mcp-targets\n\n# Set visibility for registered resources\nuv run python -m cli.agentcore sync --visibility public\n\n# JSON output for CI/CD pipelines\nuv run python -m cli.agentcore sync --output json\n\n# Specify region and registry URL\nuv run python -m cli.agentcore sync --region us-west-2 --registry-url https://registry.example.com\n\n# Custom token file and timeout\nuv run python -m cli.agentcore sync --token-file .token --timeout 60\n\n# Enable debug logging\nuv run python -m cli.agentcore sync --debug\n```\n\n#### List -- Discover and Display\n\n```bash\n# List all discovered resources\nuv run python -m cli.agentcore list\n\n# List only gateways\nuv run python -m cli.agentcore list --gateways-only\n\n# List only runtimes\nuv run python -m cli.agentcore list --runtimes-only\n\n# JSON output\nuv run python -m cli.agentcore list --output json\n\n# Specify region\nuv run python -m cli.agentcore list --region eu-west-1\n```\n\n#### Token Refresher\n\n```bash\n# One-time refresh\nuv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n# With per-client env vars\nOAUTH_CLIENT_SECRET_49ujl0b9ser72gnp6q1ph9v6vs=secret \\\n uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n# With vendor-level env vars\nAUTH0_CLIENT_SECRET=xxx OKTA_CLIENT_SECRET=yyy \\\n uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n# Continuous mode (sidecar)\nuv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n --loop --interval 2700\n\n# Enable debug logging\nuv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --token-file .token \\\n --debug\n```\n\n### Scanner CLI Arguments\n\n| Argument | Subcommand | Default | Description |\n|----------|------------|---------|-------------|\n| `--region` | sync, list | `AWS_REGION` env or `us-east-1` | AWS region to scan |\n| `--registry-url` | sync, list | `REGISTRY_URL` env or `http://localhost` | Registry base URL |\n| `--token-file` | sync, list | `REGISTRY_TOKEN_FILE` env or `.token` | Path to registry auth token file |\n| `--timeout` | sync, list | `30` | AWS API call timeout in seconds |\n| `--gateways-only` | sync, list | `false` | Only process gateways |\n| `--runtimes-only` | sync, list | `false` | Only process runtimes |\n| `--output` | sync, list | `text` | Output format: `text` or `json` |\n| `--accounts` | sync, list | `AGENTCORE_ACCOUNTS` env or empty | Comma-separated AWS account IDs for cross-account scanning |\n| `--assume-role-name` | sync, list | `AGENTCORE_ASSUME_ROLE_NAME` env or `AgentCoreSyncRole` | IAM role name to assume in each target account |\n| `--debug` | sync, list | `false` | Enable DEBUG logging |\n| `--dry-run` | sync | `false` | Preview without registering |\n| `--overwrite` | sync | `false` | Overwrite existing registrations |\n| `--visibility` | sync | `internal` | Registration visibility: `public`, `internal`, `group-restricted` |\n| `--include-mcp-targets` | sync | `false` | Register mcpServer gateway targets as separate MCP Servers |\n| `--manifest` | sync | `token_refresh_manifest.json` | Output path for token refresh manifest |\n\n### Token Refresher Arguments\n\n| Argument | Default | Description |\n|----------|---------|-------------|\n| `--manifest` | `token_refresh_manifest.json` | Path to manifest file |\n| `--registry-url` | `REGISTRY_URL` env or `http://localhost` | Registry base URL |\n| `--token-file` | `REGISTRY_TOKEN_FILE` env or `.token` | Registry auth token file |\n| `--loop` | `false` | Run continuously |\n| `--interval` | `2700` (45 min) | Refresh interval in seconds |\n| `--scan` / `--no-scan` | `--scan` (enabled) | Trigger security rescan after each credential update. Requires admin privileges on the registry token. Use `--no-scan` to disable. |\n| `--debug` | `false` | Enable DEBUG logging |\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AWS_REGION` | `us-east-1` | AWS region to scan |\n| `REGISTRY_URL` | `http://localhost` | MCP Gateway Registry URL |\n| `REGISTRY_TOKEN_FILE` | `.token` | Path to registry auth token |\n| `OAUTH_CLIENT_SECRET_` | -- | Per-client OAuth2 secret (highest priority) |\n| `AUTH0_CLIENT_SECRET` | -- | Client secret for Auth0 gateways |\n| `OKTA_CLIENT_SECRET` | -- | Client secret for Okta gateways |\n| `ENTRA_CLIENT_SECRET` | -- | Client secret for Entra gateways |\n| `KEYCLOAK_CLIENT_SECRET` | -- | Client secret for Keycloak gateways |\n| `AGENTCORE_ACCOUNTS` | -- | Comma-separated AWS account IDs for cross-account scanning |\n| `AGENTCORE_ASSUME_ROLE_NAME` | `AgentCoreSyncRole` | IAM role name to assume in each target account |\n\n### Cross-Account Scanning\n\nThe CLI can scan multiple AWS accounts in a single run. It assumes an IAM role in each target account to discover and register resources.\n\n```bash\n# Scan two accounts\nuv run python -m cli.agentcore sync --accounts 111111111111,222222222222\n\n# Scan with a custom role name\nuv run python -m cli.agentcore sync --accounts 111111111111,222222222222 --assume-role-name MyCrossAccountRole\n\n# List resources across accounts\nuv run python -m cli.agentcore list --accounts 111111111111,222222222222\n\n# Or use environment variables\nexport AGENTCORE_ACCOUNTS=111111111111,222222222222\nexport AGENTCORE_ASSUME_ROLE_NAME=AgentCoreSyncRole\nuv run python -m cli.agentcore sync\n```\n\nHow it works:\n\n1. The CLI parses the `--accounts` flag (or `AGENTCORE_ACCOUNTS` env var) into a list of account IDs.\n2. For each account, it calls `sts:AssumeRole` on `arn:aws:iam::{account_id}:role/{role_name}` to obtain temporary credentials.\n3. A boto3 session is created with those temporary credentials and passed to the scanner and registration builder.\n4. Discovery and registration proceed as normal, scoped to each account's resources.\n5. If `--accounts` is not provided, the CLI scans only the current account (default behavior).\n\nIf `AssumeRole` fails for any account, the CLI stops and reports the error.\n\nEach target account needs an IAM role that trusts the caller's account and has AgentCore discovery permissions. See the [Cross-Account IAM Prerequisites](agentcore-auto-registration-prerequisites.md#cross-account-scanning) for setup details.\n\n### Troubleshooting Auto-Registration\n\n#### `AccessDeniedException` during discovery\n\nThe IAM user or role lacks required permissions. Attach the discovery policy from the [prerequisites guide](agentcore-auto-registration-prerequisites.md#iam-permissions-for-discovery).\n\n#### \"Already registered - skipping (use --overwrite)\"\n\nThe resource is already registered in the registry. Use `--overwrite` to update the existing registration with current metadata.\n\n#### Token refresher returns HTTP 500\n\nIf the token refresher logs `HTTP 500 from nginx -- registry token may be expired`, regenerate the registry auth token and retry:\n\n```bash\n# Regenerate the registry ingress token\npython credentials-provider/oauth/ingress_oauth.py\n\n# Retry token refresh\nuv run python -m cli.agentcore.token_refresher --manifest token_refresh_manifest.json --token-file .token\n```\n\n#### Token file not found\n\nThe registry auth token file (default: `.token`) does not exist. Generate it with:\n\n```bash\npython credentials-provider/oauth/ingress_oauth.py\n```\n\n#### Dry-run shows resources but sync registers nothing\n\nIn `--dry-run` mode, the CLI performs discovery but does not register. Remove the `--dry-run` flag to perform actual registration.\n\n#### Timeout errors on AWS API calls\n\nIncrease the timeout with `--timeout 60` (or higher). The default is 30 seconds.\n\n---\n\n## Method 2: Per-Server Manual Registration\n\nFor registering individual AgentCore gateways or agents one at a time, use the same registration process as any other MCP server or agent in the registry. This is no different from how you register any MCP server or A2A agent -- you create a JSON configuration file and use the service management CLI.\n\nThis approach is useful when:\n- You want to register a single gateway without scanning the entire account\n- You need custom configuration (specific tool lists, descriptions, tags)\n- You are integrating a specific AgentCore sample (e.g., Customer Support Assistant)\n\n### How It Works\n\n1. **Create a JSON config file** describing the gateway or agent (path, proxy URL, auth scheme, tags, tool list)\n2. **Register with the CLI**: `./cli/service_mgmt.sh add gateway-config.json`\n3. **Provide a JWT token** when calling the gateway -- the IdP does not matter, just provide a valid bearer token at call time via `--token-file`\n4. **Refresh the token** when it expires -- how you obtain the token is up to you (curl, SDK, script)\n\nThe identity provider is irrelevant for manual registration. The registry uses passthrough authentication for `auth_provider: \"bedrock-agentcore\"` -- it forwards the bearer token to the AgentCore gateway, which validates it against whatever IdP is configured.\n\n### Example JSON Configuration\n\n```json\n{\n \"server_name\": \"customer-support-assistant\",\n \"description\": \"Amazon Bedrock AgentCore Gateway for customer support operations\",\n \"path\": \"/customer-support-assistant\",\n \"proxy_pass_url\": \"https://.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp/\",\n \"auth_provider\": \"bedrock-agentcore\",\n \"auth_scheme\": \"bearer\",\n \"supported_transports\": [\"streamable-http\"],\n \"tags\": [\"bedrock\", \"agentcore\", \"customer-support\"],\n \"headers\": [\n {\n \"Authorization\": \"Bearer $CUSTOMER_SUPPORT_AUTH_TOKEN\"\n }\n ],\n \"num_tools\": 2,\n \"is_python\": false,\n \"tool_list\": [\n {\n \"name\": \"LambdaUsingSDK___check_warranty_status\",\n \"parsed_description\": {\n \"main\": \"Check the warranty status of a product using its serial number\"\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"serial_number\": {\"type\": \"string\", \"description\": \"Product serial number\"}\n },\n \"required\": [\"serial_number\"]\n }\n }\n ]\n}\n```\n\n**Key Configuration Parameters:**\n\n| Parameter | Description |\n|-----------|-------------|\n| `path` | URL path where this service is accessible through the registry |\n| `proxy_pass_url` | Backend AgentCore Gateway URL. Replace `` with your actual Gateway ID |\n| `auth_provider` | Set to `bedrock-agentcore` for passthrough authentication -- the registry forwards the bearer token without validating it |\n| `tags` | Searchable tags used by `intelligent_tool_finder` for hybrid search (semantic + tag-based) |\n| `tool_list` | Tool definitions with names, descriptions, and JSON schemas. Enables the registry to catalog tools for dynamic discovery by AI agents |\n\n### Register and Call\n\n```bash\n# Register the gateway\n./cli/service_mgmt.sh add gateway-config.json\n\n# Call a tool through the registry (provide a valid JWT from any IdP)\nuv run cli/mcp_client.py \\\n --url http://localhost/customer-support-assistant/mcp \\\n --token-file .cognito_access_token \\\n call --tool LambdaUsingSDK___check_warranty_status \\\n --args '{\"serial_number\":\"MNO33333333\"}'\n```\n\n### When to Choose Each Method\n\n| | Method 1: Bulk Scanner | Method 2: Manual Registration |\n|---|---|---|\n| **Discovery** | Automatic (scans AWS account) | Manual (you provide the config) |\n| **Token refresh** | Automated (`token_refresher.py`) | Manual (you manage token lifecycle) |\n| **Customization** | Standard metadata from AWS API; skills must be added manually after import | Full control (tool lists, descriptions, tags, skills) |\n| **Scale** | All gateways/runtimes at once | One resource at a time |\n| **IdP** | Auto-detected from discovery URL | Any -- just provide a valid JWT |\n\n---\n\n## Troubleshooting\n\n### 404 Not Found Error\n\nVerify:\n1. Service is registered: `uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call --tool list_services --args '{}'`\n2. Path matches (use trailing slash for bedrock-agentcore services)\n3. Health status is healthy in the UI\n\n### 401 Authentication Error\n\n1. Refresh your egress access token (regenerate from your IdP)\n2. Verify token file path is correct\n3. Check token has not expired (TTL varies by IdP)\n\n### Service Not Showing as Healthy\n\n1. Verify AgentCore gateway is accessible from the registry container\n2. Check network connectivity\n3. Review registry logs: `docker logs mcp-gateway-registry-registry-1`\n" }, { "path": "docs/ai-coding-assistants-setup.md", "content": "# AI Coding Assistants Setup Guide\n\nComplete guide for integrating the MCP Gateway & Registry with popular AI development tools.\n\n## Overview\n\nThe MCP Gateway automatically generates configuration files for various AI coding assistants, enabling seamless access to enterprise-curated MCP servers with proper authentication and governance.\n\n## Prerequisites\n\n- MCP Gateway & Registry deployed and running\n- Authentication credentials generated via `./credentials-provider/generate_creds.sh`\n- Access to the AI coding assistant of your choice\n\n## Supported AI Development Tools\n\n### VS Code MCP Extension\n\nMicrosoft's popular editor with native MCP support.\n\n**Setup:**\n```bash\n# Copy generated configuration\ncp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json\n\n# Alternative: Merge with existing settings\ncat .oauth-tokens/vscode-mcp.json >> ~/.vscode/settings.json\n```\n\n**Configuration Format:**\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"mcpgw\": {\n \"url\": \"https://your-gateway.com/mcpgw/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer eyJ...\",\n \"X-User-Pool-Id\": \"us-east-1_vm1115QSU\",\n \"X-Client-Id\": \"5v2rav1v93...\",\n \"X-Region\": \"us-east-1\"\n },\n \"transport\": \"streamable-http\"\n }\n }\n }\n}\n```\n\n### Roo Code Plugin - Enterprise Showcase\n\nRoo Code demonstrates the power of enterprise governance for AI development tools.\n\n**Setup:**\n```bash\n# Copy Roo Code configuration\ncp .oauth-tokens/mcp.json ~/.vscode/mcp_settings.json\n```\n\n**Alternative Setup Options:**\n```bash\n# Option 1: Direct copy (recommended)\ncp .oauth-tokens/mcp.json ~/.vscode/mcp_settings.json\n\n# Option 2: Create symbolic link for automatic updates\nln -sf \"$(pwd)/.oauth-tokens/mcp.json\" ~/.vscode/mcp_settings.json\n```\n\n**Enterprise Use Case:**\n\n\n\n\n\n\n
\n\n![Roo Code MCP Configuration](img/roo.png)\n\n**Enterprise Tool Catalog**\n- Curated MCP servers approved by IT\n- Consistent across all developer environments \n- Centralized authentication and governance\n- Real-time health monitoring\n\n\n\n![Roo Code Agent in Action](img/roo_agent.png)\n\n**AI Assistant in Action**\n- Natural language tool discovery\n- Secure execution of enterprise tools\n- Complete audit trail for compliance\n- Seamless developer experience\n\n
\n\n**Key Enterprise Benefits:**\n\n**Centralized Control**\n- IT teams manage approved MCP servers across all development environments\n- Consistent tool availability regardless of developer setup\n- Rapid deployment of new tools to entire organization\n\n**Secure Authentication** \n- All tool access routes through enterprise identity systems (Amazon Cognito)\n- No individual API key management required\n- Automatic token refresh and rotation via [Token Refresh Service](token-refresh-service.md)\n\n**Usage Analytics & Compliance**\n- Track which developers use which tools and when\n- Generate compliance reports for audit requirements\n- Monitor tool adoption and usage patterns across teams\n\n**Developer Productivity**\n- Zero configuration required for approved tools\n- Instant access to new enterprise tools as they're approved\n- Same experience across VS Code, Cursor, Claude Code, and other assistants\n\n### Claude Code\n\nAnthropic's coding assistant with standardized MCP configurations.\n\n**Setup:**\n```bash\n# Claude Code uses similar JSON format\ncp .oauth-tokens/vscode-mcp.json ~/.claude-code/mcp-config.json\n```\n\n**Features:**\n- Natural language interaction with MCP tools\n- Context-aware tool suggestions\n- Integrated code generation and tool execution\n\n### Cursor\n\nAI-first code editor with advanced MCP integration.\n\n**Setup:**\n```bash\n# Cursor configuration (similar to VS Code)\ncp .oauth-tokens/vscode-mcp.json ~/.cursor/mcp-settings.json\n```\n\n**Advanced Features:**\n- Multi-file context for tool operations\n- Predictive tool suggestions based on code context\n- Integrated diff view for tool-generated changes\n\n### Cline (formerly Claude Dev)\n\nAutonomous coding agent compatible with VS Code.\n\n**Setup:**\n```bash\n# Cline uses VS Code-style configuration\ncp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json\n```\n\n**Autonomous Capabilities:**\n- Goal-directed tool usage\n- Multi-step task execution\n- Error handling and retry logic\n\n### Custom MCP Clients\n\nFor custom applications or other MCP clients:\n\n**Use Raw Authentication:**\n```bash\n# Access authentication details directly\ncat .oauth-tokens/ingress.json\n```\n\n**Example Integration:**\n```python\nimport json\nimport mcp\nfrom mcp.client.sse import sse_client\n\n# Load authentication from generated file\nwith open('.oauth-tokens/ingress.json') as f:\n auth = json.load(f)\n\nheaders = {\n 'Authorization': f'Bearer {auth[\"access_token\"]}',\n 'X-User-Pool-Id': auth['user_pool_id'],\n 'X-Client-Id': auth['client_id'],\n 'X-Region': auth['region']\n}\n\n# Connect to MCP server\nasync with sse_client('https://gateway.com/mcpgw/sse', headers=headers) as (read, write):\n async with mcp.ClientSession(read, write) as session:\n await session.initialize()\n tools = await session.list_tools()\n```\n\n## Configuration Management\n\n### Automatic Token Refresh\n\nThe MCP Gateway includes an [Automated Token Refresh Service](token-refresh-service.md) that provides continuous token management:\n\n```bash\n# Start the token refresh service (runs in background)\n./start_token_refresher.sh\n\n# Service automatically:\n# - Monitors token expiration (1-hour buffer by default)\n# - Refreshes tokens before they expire\n# - Updates all MCP client configurations\n# - Generates fresh configs for all AI assistants\n```\n\n**Key Benefits:**\n- **Zero Downtime**: Tokens refresh automatically before expiration\n- **Continuous Operation**: AI assistants never lose access due to expired tokens\n- **Multiple Client Support**: Updates configurations for VS Code, Roo Code, Claude Code, etc.\n- **Background Operation**: Runs as a service with comprehensive logging\n\n### Manual Configuration Updates\n\nIf you need to manually regenerate configurations:\n\n```bash\n# Regenerate all configurations\n./credentials-provider/generate_creds.sh\n\n# Copy updated configurations to AI assistants\n./scripts/update-ai-assistants.sh # Custom script you can create\n```\n\n**For AI assistants using symbolic links** (recommended setup), configuration updates are automatic since they point to the live `.oauth-tokens/` files.\n\n### Environment-Specific Configurations\n\n**Development Environment:**\n```bash\n# Generate development configurations\nENVIRONMENT=dev ./credentials-provider/generate_creds.sh\ncp .oauth-tokens/dev-* ~/.vscode/\n```\n\n**Production Environment:**\n```bash\n# Generate production configurations \nENVIRONMENT=prod ./credentials-provider/generate_creds.sh\ncp .oauth-tokens/prod-* ~/.vscode/\n```\n\n## Troubleshooting\n\n### Authentication Issues\n\n**Token Expired:**\n\n*If using Token Refresh Service (recommended):*\n```bash\n# Check if token refresh service is running\nps aux | grep token_refresher\n\n# Restart token refresh service if needed\n./start_token_refresher.sh\n\n# Check service logs\ntail -f token_refresher.log\n```\n\n*Manual token refresh:*\n```bash\n# Regenerate credentials\n./credentials-provider/generate_creds.sh\n# Update AI assistant configurations\n```\n\n**Permission Denied:**\n```bash\n# Check user permissions in Cognito\naws cognito-idp admin-list-groups-for-user \\\n --user-pool-id YOUR_POOL_ID \\\n --username YOUR_USERNAME\n\n# Verify scope configuration\ncat auth_server/scopes.yml\n```\n\n### Configuration Issues\n\n**Tools Not Appearing:**\n```bash\n# Verify MCP server health\ncurl -H \"Authorization: Bearer TOKEN\" \\\n https://your-gateway.com/server-name/sse\n\n# Check AI assistant logs\ntail -f ~/.vscode/logs/mcp.log\n```\n\n**Connection Failures:**\n```bash\n# Test gateway connectivity\n./tests/mcp_cmds.sh ping\n\n# Verify SSL certificates (if using HTTPS)\nopenssl s_client -connect your-gateway.com:443\n```\n\n## Best Practices\n\n### Security\n\n1. **Credential Storage**\n - Store generated configurations in secure locations\n - Use environment-specific credentials\n - Regularly rotate authentication tokens\n\n2. **Access Control**\n - Follow principle of least privilege\n - Regularly review user permissions\n - Monitor tool usage for anomalies\n\n3. **Network Security**\n - Use HTTPS in production environments\n - Restrict network access to authorized IP ranges\n - Monitor for unauthorized access attempts\n\n### Development Workflow\n\n1. **Team Onboarding**\n ```bash\n # Create onboarding script\n #!/bin/bash\n ./credentials-provider/generate_creds.sh\n cp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json\n echo \"MCP Gateway configured successfully!\"\n ```\n\n2. **Tool Discovery**\n - Use natural language queries: \"find tools for database operations\"\n - Explore available tools through web interface\n - Share useful tool combinations with team\n\n3. **Automation**\n ```bash\n # Automate configuration updates\n crontab -e\n # Add: 0 9 * * * /path/to/update-mcp-config.sh\n ```\n\n## Enterprise Deployment Considerations\n\n### Scale Considerations\n\n- **Large Teams (100+ developers)**: Consider load balancing and caching\n- **Global Teams**: Deploy regional gateways for reduced latency\n- **High Security**: Use private networking and enhanced monitoring\n\n### Compliance & Governance\n\n- **Audit Requirements**: Enable comprehensive logging\n- **Data Residency**: Deploy in compliant regions\n- **Access Reviews**: Implement periodic permission audits\n\n### Cost Optimization\n\n- **Resource Management**: Monitor gateway resource usage\n- **Tool Usage**: Analyze tool usage patterns for optimization\n- **License Management**: Track per-developer tool usage\n\n## Backend Server Authentication\n\nWhen MCP servers require their own authentication (API keys, bearer tokens, etc.), the MCP Gateway Registry provides automatic configuration generation that includes both:\n\n1. **Gateway Authentication** - The `X-Authorization` header for authenticating with the MCP Gateway\n2. **Backend Server Authentication** - The server's own auth header (`Authorization`, custom API key headers, etc.)\n\n### Supported Authentication Schemes\n\nThe registry supports three backend authentication schemes:\n\n| Scheme | Description | Example Header |\n|--------|-------------|----------------|\n| `none` | No backend authentication required | N/A |\n| `bearer` | Bearer token authentication | `Authorization: Bearer ` |\n| `api_key` | API key with custom header | `CONTEXT7_API_KEY: ` or `X-API-Key: ` |\n\n### Example Configurations\n\n#### Example 1: API Key Authentication (Context7)\n\n**Server Details:**\n- **Display Name**: Context7\n- **Auth Scheme**: `api_key`\n- **Auth Header**: `CONTEXT7_API_KEY`\n- **Credential**: API key provided during registration\n\n**Generated MCP Configuration (VS Code):**\n```json\n{\n \"servers\": {\n \"context7\": {\n \"type\": \"http\",\n \"url\": \"https://mcpgateway.ddns.net/context7/mcp\",\n \"headers\": {\n \"X-Authorization\": \"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"CONTEXT7_API_KEY\": \"[YOUR_API_KEY]\"\n }\n }\n }\n}\n```\n\n**Generated MCP Configuration (Roo Code/Cline):**\n```json\n{\n \"mcpServers\": {\n \"context7\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcpgateway.ddns.net/context7/mcp\",\n \"disabled\": false,\n \"headers\": {\n \"X-Authorization\": \"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"CONTEXT7_API_KEY\": \"[YOUR_API_KEY]\"\n }\n }\n }\n}\n```\n\n#### Example 2: Bearer Token Authentication (Cloudflare)\n\n**Server Details:**\n- **Display Name**: Cloudflare API\n- **Auth Scheme**: `bearer`\n- **Auth Header**: `Authorization`\n- **Credential**: Bearer token provided during registration\n\n**Generated MCP Configuration (VS Code):**\n```json\n{\n \"servers\": {\n \"cloudflare-api\": {\n \"type\": \"http\",\n \"url\": \"https://mcpgateway.ddns.net/cloudflare-api/mcp\",\n \"headers\": {\n \"X-Authorization\": \"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"Authorization\": \"Bearer [YOUR_SERVER_AUTH_TOKEN]\"\n }\n }\n }\n}\n```\n\n### How It Works\n\n1. **Gateway Authentication Header** (`X-Authorization`):\n - Authenticates the AI coding assistant with the MCP Gateway\n - Automatically generated when you open the MCP Configuration modal\n - Validates user identity and permissions\n\n2. **Backend Server Authentication Header** (e.g., `Authorization`, `CONTEXT7_API_KEY`):\n - Authenticates the MCP Gateway with the backend MCP server\n - The credential is encrypted and stored in the registry during server registration\n - Automatically decrypted and included in health checks and tool fetching\n\n3. **Automatic Configuration Generation**:\n - The Registry UI automatically detects the server's auth scheme\n - Both headers are included in the generated configuration\n - Works with all supported AI coding assistants (VS Code, Cursor, Cline, Roo Code, Claude Code)\n\n### UI Workflow\n\n1. **Open Server Card** in the Registry dashboard\n2. **Click \"Get MCP Config\"** button\n3. **Select Your IDE** (VS Code, Cursor, Cline, Roo Code, or Claude Code)\n4. **Copy Configuration** - The generated config includes both gateway and backend auth headers\n5. **Paste into your IDE's MCP settings file**\n\n**Screenshot Example:**\n\n![MCP Configuration Modal showing dual authentication headers](img/mcp-config-dual-auth.png)\n\n### Registry-Only Mode\n\nIn registry-only deployment mode (catalog mode), only the backend server authentication is included:\n\n```json\n{\n \"mcpServers\": {\n \"context7\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://context7-direct-endpoint.com/mcp\",\n \"disabled\": false,\n \"headers\": {\n \"CONTEXT7_API_KEY\": \"[YOUR_API_KEY]\"\n }\n }\n }\n}\n```\n\nSee [Registry Deployment Modes](registry-deployment-modes.md) for more details on deployment configurations.\n\n## Support & Resources\n\n- [Configuration Reference](configuration.md) - Complete configuration options\n- [Authentication Guide](auth.md) - Identity provider setup and server credential management\n- [Server Registration](auth.md#server-authentication-credentials) - How to register servers with auth credentials\n- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions\n- [API Reference](registry_api.md) - Programmatic management\n- [GitHub Discussions](https://github.com/agentic-community/mcp-gateway-registry/discussions) - Community support" }, { "path": "docs/ai-registry-tools.md", "content": "# AI Registry Tools\n\nAn MCP server that provides AI agents with tools to discover and query MCP servers, tools, agents, and skills registered in the MCP Gateway Registry.\n\nSee the [What's New section](../README.md#whats-new) in the main README for the latest updates and features.\n\n## What This Server Does\n\n**AI Registry Tools** gives your AI coding assistants the ability to:\n- **Search for MCP tools** using natural language queries\n- **List all available MCP servers** in the registry\n- **Discover AI agents** that can help with specific tasks\n- **Find skills** (like Claude Code skills) available in the ecosystem\n- **Check registry health** and statistics\n\nThis server is **automatically registered** in the MCP Gateway Registry and ready to use.\n\n## Adding to Your AI Agent\n\nTo use AI Registry Tools with your coding assistant (Claude Code, Roo Code, Cline, etc.):\n\n1. **Navigate to the registry web UI** at your registry URL\n2. **Find the AI Registry Tools server card** in the servers list\n3. **Click the gear icon** on the server card\n4. **Follow the configuration instructions** to add it to your AI agent\n\nThe gear icon will provide ready-to-use configuration snippets for popular AI coding assistants.\n\n## Available Tools\n\n### intelligent_tool_finder\n\nSearch for MCP tools using natural language semantic search.\n\n**Parameters:**\n- `query` (string, required) - Natural language description of what you want to do\n- `top_n` (integer, optional) - Number of results to return (default: 5, max: 100)\n\n**Returns:**\n```typescript\n{\n results: Array<{\n tool_name: string; // Name of the tool\n server_name: string; // Server providing the tool\n description: string | null; // Tool description\n score: number | null; // Relevance score (0-1)\n path: string | null; // Server path\n }>;\n query: string; // Your search query\n total_results: number; // Number of results found\n status: \"success\" | \"failed\";\n}\n```\n\n**Example Query:** \"find tools to help me work with databases\"\n\n---\n\n### list_services\n\nList all MCP servers registered in the gateway.\n\n**Parameters:** None\n\n**Returns:**\n```typescript\n{\n services: Array<{\n server_name: string | null; // Display name of the server\n path: string; // URL path (e.g., '/weather-api')\n description: string | null; // Server description\n enabled: boolean; // Whether server is active\n tags: string[]; // Server tags\n tool_count: number | null; // Number of tools provided\n }>;\n total_count: number; // Total servers\n enabled_count: number; // Number of enabled servers\n status: \"success\" | \"failed\";\n}\n```\n\n---\n\n### list_agents\n\nList all AI agents registered in the gateway.\n\n**Parameters:** None\n\n**Returns:**\n```typescript\n{\n agents: Array<{\n name: string | null; // Agent name\n description: string | null; // Agent description\n tags: string[]; // Agent tags\n created_at: string | null; // ISO timestamp\n }>;\n total_count: number; // Total agents\n status: \"success\" | \"failed\";\n}\n```\n\n---\n\n### list_skills\n\nList all skills (Claude Code skills, etc.) registered in the gateway.\n\n**Parameters:** None\n\n**Returns:**\n```typescript\n{\n skills: Array<{\n path: string; // Skill path\n name: string | null; // Skill name\n description: string | null; // Skill description\n tags: string[]; // Skill tags\n created_at: string | null; // ISO timestamp\n }>;\n total_count: number; // Total skills\n status: \"success\" | \"failed\";\n}\n```\n\n---\n\n### healthcheck\n\nGet registry health status and statistics.\n\n**Parameters:** None\n\n**Returns:**\n```typescript\n{\n // Dynamic fields from registry health endpoint\n // May include: total_servers, enabled_servers,\n // total_tools, uptime, version, etc.\n [key: string]: any;\n status: \"success\" | \"failed\";\n}\n```\n\n## Use Cases\n\n### For AI Coding Assistants\n\n**Discover new capabilities:**\n```\nYou: \"What tools are available for working with AWS?\"\nAI: *calls intelligent_tool_finder(query=\"AWS tools\")*\nAI: \"I found 12 AWS-related tools including aws-kb for documentation,\n aws-bedrock for AI models, and cloudformation for infrastructure...\"\n```\n\n**Check what's available:**\n```\nYou: \"Show me all MCP servers in the registry\"\nAI: *calls list_services()*\nAI: \"There are 47 MCP servers registered, including weather-api,\n github-mcp, slack-tools, and more...\"\n```\n\n**Find specialized agents:**\n```\nYou: \"Are there any agents that can help with travel planning?\"\nAI: *calls list_agents()*\nAI: \"Yes, there's a travel-assistant-agent that can help with\n flight bookings, hotel searches, and itinerary planning.\"\n```\n\n### For Development Workflows\n\n- **Tool discovery during development** - Find the right MCP tool before building custom solutions\n- **Registry exploration** - Understand what's available in your organization's MCP ecosystem\n- **Integration planning** - Identify which servers and tools to integrate into your projects\n- **Capability mapping** - Map business requirements to available MCP tools\n\n## Authentication\n\nAll tools require bearer token authentication. The authentication is handled automatically when you configure the server through your AI agent's settings.\n\n**How authentication works:**\n1. Your AI agent includes an `Authorization: Bearer ` header with each request\n2. AI Registry Tools forwards this token to the registry API\n3. The registry validates your token and returns the requested data\n\n**If you see authentication errors:**\n- Verify your token is valid and not expired\n- Check that your token has appropriate permissions in the registry\n- Contact your registry administrator if issues persist\n\n## Technical Architecture\n\n```\nAI Agent → AI Registry Tools → MCP Gateway Registry\n (MCP Protocol) (HTTP/JSON API)\n Bearer Token Token Forwarding\n```\n\n**Design principles:**\n- **Lightweight** - Minimal dependencies, fast startup\n- **Stateless** - No session management, horizontally scalable\n- **Pass-through authentication** - Tokens forwarded to registry\n- **Protocol adapter** - Translates MCP tool calls to HTTP API requests\n\n## Configuration\n\nAI Registry Tools is configured via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `REGISTRY_BASE_URL` | `http://localhost` | Registry API endpoint |\n| `HOST` | `127.0.0.1` | Bind host (use `0.0.0.0` for Docker/K8s) |\n| `PORT` | `8003` | Server port |\n\nFor Docker/Kubernetes deployments, the registry automatically configures these variables.\n\n## Support\n\n- **Documentation**: See the MCP Gateway Registry docs\n- **Issues**: Report issues in the main registry repository\n- **Configuration help**: Use the gear icon on the server card for setup guidance\n\n---\n\n**Server Status**: Auto-registered and ready to use\n**Protocol**: Model Context Protocol (MCP)\n**Transport**: Streamable HTTP\n**Authentication**: Bearer token (forwarded to registry)\n" }, { "path": "docs/anthropic-registry-import.md", "content": "# Importing Servers from Anthropic MCP Registry\n\nThis guide explains how to import MCP servers from [Anthropic's official MCP Registry](https://registry.modelcontextprotocol.io/) into your MCP Gateway.\n\n## Overview\n\nThe Anthropic MCP Registry is an open, collaboratively governed directory of Model Context Protocol (MCP) servers. It is maintained by Anthropic in partnership with GitHub and the wider community through an open-source contribution model. This registry provides a curated catalog of publicly available and community-contributed MCP servers. Its API enables MCP clients and gateways to discover and import server configurations automatically, simplifying integration and discovery workflows for developers.\n\nThe import functionality allows you to quickly add these servers to your gateway without manual configuration.\n\n## Prerequisites\n\n- MCP Gateway up and running\n- Access to the registry container or CLI tools\n- Environment variables configured in `.env` file (for authenticated servers)\n\n> **Note**: The Anthropic API version is defined in `registry/constants.py` as `ANTHROPIC_API_VERSION` for easy version management.\n\n## Quick Start\n\n### Import a Single Server\n\n```bash\ncd /home/ubuntu/repos/mcp-gateway-registry\n./cli/import_from_anthropic_registry.sh ai.smithery/smithery-ai-github\n```\n\n### Import Multiple Servers from a List\n\nCreate or edit `cli/import_server_list.txt`:\n\n```text\n# Popular MCP Servers\nai.smithery/smithery-ai-github\nio.github.jgador/websharp\nai.smithery/Hint-Services-obsidian-github-mcp\n```\n\nThen import all servers in the list:\n\n```bash\n./cli/import_from_anthropic_registry.sh --import-list cli/import_server_list.txt\n```\n\n## Import Script Features\n\n### Automatic Environment Variable Substitution\n\nThe import script automatically:\n- Loads environment variables from `.env` file\n- Substitutes authentication header placeholders with actual values\n- Stores the final configuration with real credentials in JSON files\n\n**Example:**\n```json\n// Before substitution (from Anthropic registry):\n{\n \"headers\": [\n {\n \"Authorization\": \"Bearer {smithery_api_key}\"\n }\n ]\n}\n\n// After import (stored in gateway):\n{\n \"headers\": [\n {\n \"Authorization\": \"Bearer 3899299d-b7a2-471d-a185-200b9e9adcb2\"\n }\n ]\n}\n```\n\n### Server Name Transformation\n\nServer names from the Anthropic registry are automatically transformed to work with the gateway:\n\n- Slashes (`/`) are replaced with hyphens (`-`)\n- Example: `ai.smithery/github` becomes `ai.smithery-github`\n- The path is set to `/ai.smithery-github`\n\n### Automatic Configuration\n\nThe import script automatically configures:\n- **Server name** and **description** from registry\n- **Proxy URL** to the remote server\n- **Authentication type** (oauth, api-key, or none)\n- **Authentication provider** (Keycloak for oauth servers)\n- **Transport type** (streamable-http)\n- **Tags** for discovery and organization\n- **Headers** with substituted credentials\n\n## Command Reference\n\n### Basic Usage\n\n```bash\n./cli/import_from_anthropic_registry.sh [OPTIONS] [SERVER_NAME]\n```\n\n### Options\n\n- `--import-list ` - Import servers from a file (one server name per line)\n- `--dry-run` - Show what would be imported without actually importing\n- `--gateway-url ` - Override gateway URL (default: http://localhost)\n- `--base-port ` - Override base port for local servers (default: 8100)\n\n### Examples\n\n**Import with dry run:**\n```bash\n./cli/import_from_anthropic_registry.sh --dry-run ai.smithery/smithery-ai-github\n```\n\n**Import from custom list:**\n```bash\n./cli/import_from_anthropic_registry.sh --import-list my-servers.txt\n```\n\n**Import to remote gateway:**\n```bash\nGATEWAY_URL=\"https://mcpgateway.example.com\" ./cli/import_from_anthropic_registry.sh ai.smithery/smithery-ai-github\n```\n\n## Server List File Format\n\nCreate a text file with one server name per line:\n\n```text\n# Lines starting with # are comments\n# Empty lines are ignored\n\n# GitHub API access\nai.smithery/smithery-ai-github\n\n# Web search and article extraction\nio.github.jgador/websharp\n\n# Obsidian vault integration\nai.smithery/Hint-Services-obsidian-github-mcp\n```\n\n## Authentication Setup\n\n### For Servers Requiring Authentication\n\n1. **Get API Keys**: Obtain API keys from the service provider\n - Smithery servers: Visit [smithery.ai](https://smithery.ai)\n - Other services: Check their documentation\n\n2. **Add to .env file**:\n```bash\n# Smithery API Key\nSMITHERY_API_KEY=your-api-key-here\n\n# Other service keys\nOTHER_SERVICE_API_KEY=your-other-key\n```\n\n3. **Import servers**: The script automatically substitutes the keys\n\n### Supported Authentication Types\n\nThe import script recognizes and configures:\n\n- **OAuth/Bearer tokens**: `Authorization: Bearer {api_key}`\n- **API keys**: `X-API-Key: {api_key}` or `API-Key: {api_key}`\n- **Custom headers**: Other authentication header formats\n\n## Finding Servers to Import\n\n### Browse Anthropic's MCP Registry\n\nVisit [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/) to:\n- Browse available servers\n- View server capabilities and tools\n- Check authentication requirements\n- Read documentation\n\n### List Servers via API\n\n```bash\n# List all available servers\ncurl https://registry.modelcontextprotocol.io/v0.1/servers | jq '.servers[] | .name'\n\n# Get details for a specific server\ncurl https://registry.modelcontextprotocol.io/v0.1/servers/ai.smithery%2Fsmithery-ai-github/versions/latest | jq '.'\n```\n\n### Test Server Before Importing\n\nUse the test script to verify server details:\n\n```bash\n./cli/test_anthropic_api.py ai.smithery/smithery-ai-github\n```\n\n## Verifying Imported Servers\n\n### Check Server Status\n\nAfter importing, verify the server was registered:\n\n```bash\n# Via CLI\n./cli/service_mgmt.sh list\n\n# Via API\ncurl http://localhost/mcpgw/mcp -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -d '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/list\"}'\n```\n\n### View Server in UI\n\nNavigate to the gateway UI to see imported servers:\n- http://localhost/\n\n### Check Health Status\n\nThe health check service automatically monitors imported servers:\n\n```bash\ndocker compose logs registry | grep -i \"health\"\n```\n\n## Troubleshooting\n\n### Import Fails with Authentication Error\n\n**Problem**: Server requires authentication but key is missing\n\n**Solution**:\n1. Check if the server requires an API key\n2. Add the key to your `.env` file with the correct name\n3. Re-run the import\n\n### Server Shows as Unhealthy\n\n**Problem**: Imported server shows unhealthy in health checks\n\n**Possible causes**:\n- Invalid or expired API key\n- Network connectivity issues\n- Server is temporarily down\n\n**Check logs**:\n```bash\ndocker compose logs registry --tail 100 | grep -i \"server-name\"\n```\n\n### Environment Variable Not Substituted\n\n**Problem**: Server JSON still shows `${VAR_NAME}` instead of actual value\n\n**Solution**:\n1. Ensure the variable is defined in `.env`\n2. Variable names are case-sensitive\n3. Re-run the import after updating `.env`\n\n### Server Name Conflicts\n\n**Problem**: Server already exists with same path\n\n**Solution**:\n```bash\n# Delete existing server\n./cli/service_mgmt.sh delete /server-path \"server-name\"\n\n# Re-import\n./cli/import_from_anthropic_registry.sh server-name\n```\n\n## Advanced Usage\n\n### Custom Transformation\n\nTo customize how servers are imported, edit `cli/anthropic_transformer.py`:\n\n- Modify tag generation\n- Change path formatting\n- Adjust authentication handling\n- Add custom metadata\n\n### Batch Import with Filtering\n\n```bash\n# Import only servers matching a pattern\ncurl -s https://registry.modelcontextprotocol.io/v0.1/servers | \\\n jq -r '.servers[] | select(.name | contains(\"smithery\")) | .name' > smithery-servers.txt\n\n./cli/import_from_anthropic_registry.sh --import-list smithery-servers.txt\n```\n\n### Automated Imports\n\nAdd to cron or systemd timer for automatic updates:\n\n```bash\n# Daily import of curated server list\n0 2 * * * cd /path/to/repo && ./cli/import_from_anthropic_registry.sh --import-list cli/import_server_list.txt\n```\n\n## Best Practices\n\n1. **Curate your server list**: Only import servers you need and trust\n2. **Review before importing**: Use `--dry-run` to preview changes\n3. **Secure API keys**: Never commit `.env` to version control\n4. **Monitor health**: Regularly check imported server health status\n5. **Update regularly**: Re-import servers to get latest configurations\n6. **Test thoroughly**: Verify each server works after importing\n\n## Related Documentation\n\n- [Anthropic MCP Registry API](anthropic_registry_api.md)\n- [Service Management](service-management.md)\n- [Authentication Setup](../README.md#authentication)\n- [Health Monitoring](OBSERVABILITY.md)\n\n## Support\n\nFor issues or questions:\n- GitHub Issues: [mcp-gateway-registry/issues](https://github.com/agentic-community/mcp-gateway-registry/issues)\n- Anthropic Registry: [modelcontextprotocol.io](https://modelcontextprotocol.io/)\n" }, { "path": "docs/anthropic_registry_api.md", "content": "# Anthropic MCP Registry API Documentation\n\nThe MCP Gateway Registry implements the server listing and related APIs from the [Anthropic MCP Registry REST API](https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/api/openapi.yaml) specification (currently v0.1). Additional API endpoints will be added in future releases.\n\n> **Note**: The Anthropic API version is defined in `registry/constants.py` as `ANTHROPIC_API_VERSION` for easy version management.\n\n## Overview\n\nThis API provides programmatic access to the MCP server registry using standard REST endpoints with JWT authentication. The API respects user permissions - users only see servers they have access to based on their configured privileges.\n\n## Authentication\n\nThe API uses JWT Bearer token authentication. You need to obtain a JWT token from the Keycloak authentication provider first.\n\n### Generate JWT Token via UI (Admin Users)\n\n1. **Login to the Registry Web Interface**\n - Navigate to your registry instance at `https://your-registry-domain/` or `http://localhost:7860/`\n - Login with your admin credentials\n\n2. **Access Token Management**\n - After logging in, you should see the main dashboard\n - As an admin user, you have access to generate JWT tokens\n\n3. **Generate JWT Token**\n - Click the \"Generate JWT Token\" button or navigate to the token generation page\n - The system will store your JWT tokens in files like `.oauth-tokens/mcp-registry-api-tokens-YYYY-MM-DD.json`\n - **Note**: Tokens have a short lifetime (typically 5-15 minutes) for security\n\n### Token File Format\n\nThe token file typically contains:\n\n```json\n{\n \"tokens\": {\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"refresh_token\": null,\n \"token_type\": \"bearer\",\n \"expires_in\": 300\n },\n \"keycloak_url\": \"http://localhost:8080\",\n \"realm\": \"mcp-gateway\",\n \"client_id\": \"mcp-gateway-m2m\"\n}\n```\n\n**Note**: Refresh tokens are not provided for security reasons. If your token expires, generate a new one from the UI or ask your administrator to increase the access token timeout in Keycloak (Realm Settings → Tokens → Access Token Lifespan).\n\n## API Endpoints\n\nAll endpoints are prefixed with the API version (currently `/v0.1`, defined in `registry/constants.py`) and require authentication via Bearer token.\n\n### 1. List Servers\n\n**Endpoint:** `GET /v0.1/servers`\n\nLists all MCP servers that the authenticated user has access to.\n\n**Parameters:**\n- `cursor` (optional): Pagination cursor from previous response\n- `limit` (optional): Maximum number of items (1-1000, default: 100)\n\n**Response:**\n```json\n{\n \"servers\": [\n {\n \"name\": \"io.mcpgateway/fininfo\",\n \"description\": \"Financial information and market data\",\n \"version\": \"1.0.0\",\n \"vendor\": \"MCP Gateway\"\n }\n ],\n \"nextCursor\": \"eyJpZCI6ImF0bGFzc2lhbiJ9\"\n}\n```\n\n### 2. Get Server Versions\n\n**Endpoint:** `GET /v0.1/servers/{server_name}/versions`\n\nLists all available versions for a specific server.\n\n**Parameters:**\n- `server_name`: URL-encoded server name (e.g., `io.mcpgateway%2Ffininfo`)\n\n**Response:**\n```json\n{\n \"versions\": [\n {\n \"version\": \"1.0.0\",\n \"description\": \"Latest stable version\",\n \"publishedAt\": \"2024-10-13T00:00:00Z\"\n }\n ]\n}\n```\n\n### 3. Get Server Version Details\n\n**Endpoint:** `GET /v0.1/servers/{server_name}/versions/{version}`\n\nGets detailed information about a specific server version.\n\n**Parameters:**\n- `server_name`: URL-encoded server name\n- `version`: Version identifier or \"latest\"\n\n**Response:**\n```json\n{\n \"name\": \"io.mcpgateway/fininfo\",\n \"version\": \"1.0.0\",\n \"description\": \"Financial information and market data\",\n \"vendor\": \"MCP Gateway\",\n \"sourceUrl\": \"https://github.com/mcpgateway/mcp-gateway-registry\",\n \"configuration\": {\n \"mcpVersion\": \"2024-11-05\",\n \"capabilities\": {\n \"tools\": {},\n \"resources\": {}\n }\n }\n}\n```\n\n## Using curl\n\nYou can test the API directly using curl:\n\n```bash\n# First, extract the access token from your token file\nACCESS_TOKEN=$(cat /path/to/your/token-file.json | jq -r '.tokens.access_token')\n\n# List all servers you have access to\ncurl -X GET \"http://localhost/v0.1/servers?limit=10\" \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H \"Content-Type: application/json\"\n\n# Get versions for a specific server\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions\" \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H \"Content-Type: application/json\"\n\n# Get details for a specific server version\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions/latest\" \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H \"Content-Type: application/json\"\n```\n\n**Note**: Server names with slashes must be URL-encoded (e.g., `io.mcpgateway/fininfo` becomes `io.mcpgateway%2Ffininfo`).\n\n## Using the Test Script\n\nA complete test script is provided at `cli/test_anthropic_api.py` that demonstrates how to interact with the API programmatically.\n\n### Basic Usage\n\n```bash\n# Run all tests with a token file\nuv run python cli/test_anthropic_api.py --token-file /path/to/your/token-file.json\n\n# Test specific endpoint\nuv run python cli/test_anthropic_api.py \\\n --token-file /path/to/your/token-file.json \\\n --test list-servers \\\n --limit 10\n\n# Get details for a specific server\nuv run python cli/test_anthropic_api.py \\\n --token-file /path/to/your/token-file.json \\\n --test get-server \\\n --server-name io.mcpgateway/fininfo\n```\n\n### Additional Options\n\n```bash\n# Use with different registry instance\nuv run python cli/test_anthropic_api.py \\\n --token-file tokens.json \\\n --base-url https://mcpgateway.ddns.net\n\n# Enable debug logging\nuv run python cli/test_anthropic_api.py \\\n --token-file tokens.json \\\n --debug\n```\n\n### Command Line Options\n\nThe test script supports the following options:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--token-file` | Path to JWT token file (required) | - |\n| `--base-url` | Registry API base URL | `http://localhost` |\n| `--test` | Which test to run (all, list-servers, get-versions, get-server) | `all` |\n| `--server-name` | Server name for specific tests | - |\n| `--limit` | Number of servers to list | `5` |\n| `--debug` | Enable debug logging | `false` |\n\n## Example Python Code\n\nHere's a minimal example of how to build your own client (you would obviously write your own code adapted to your needs):\n\n```python\nimport requests\nimport json\nfrom typing import Dict, Any, Optional\n\nclass MCPRegistryClient:\n def __init__(self, base_url: str, access_token: str):\n self.base_url = base_url\n self.headers = {\n \"Authorization\": f\"Bearer {access_token}\",\n \"Content-Type\": \"application/json\"\n }\n\n def list_servers(self, limit: int = 100, cursor: Optional[str] = None) -> Dict[str, Any]:\n \"\"\"List all available MCP servers.\"\"\"\n params = {\"limit\": limit}\n if cursor:\n params[\"cursor\"] = cursor\n\n response = requests.get(\n f\"{self.base_url}/v0.1/servers\",\n headers=self.headers,\n params=params\n )\n response.raise_for_status()\n return response.json()\n\n def get_server_versions(self, server_name: str) -> Dict[str, Any]:\n \"\"\"Get all versions for a specific server.\"\"\"\n encoded_name = server_name.replace(\"/\", \"%2F\")\n response = requests.get(\n f\"{self.base_url}/v0.1/servers/{encoded_name}/versions\",\n headers=self.headers\n )\n response.raise_for_status()\n return response.json()\n\n def get_server_details(self, server_name: str, version: str = \"latest\") -> Dict[str, Any]:\n \"\"\"Get detailed information about a server version.\"\"\"\n encoded_name = server_name.replace(\"/\", \"%2F\")\n response = requests.get(\n f\"{self.base_url}/v0.1/servers/{encoded_name}/versions/{version}\",\n headers=self.headers\n )\n response.raise_for_status()\n return response.json()\n\n# Usage example\ndef main():\n # Load token from file\n with open('/path/to/your/token-file.json', 'r') as f:\n token_data = json.load(f)\n\n access_token = token_data[\"tokens\"][\"access_token\"]\n\n # Create client\n client = MCPRegistryClient(\"http://localhost\", access_token)\n\n # List servers\n servers = client.list_servers(limit=10)\n print(f\"Found {len(servers['servers'])} servers\")\n\n # Get details for a specific server\n if servers[\"servers\"]:\n server_name = servers[\"servers\"][0][\"name\"]\n details = client.get_server_details(server_name)\n print(f\"Server details: {json.dumps(details, indent=2)}\")\n\nif __name__ == \"__main__\":\n main()\n```\n\n## Token Lifetime Management\n\nTokens have a short lifetime (typically 5-15 minutes) for security. When your token expires:\n\n1. **Generate a new token** from the UI (recommended approach)\n2. **Or ask your administrator** to increase the access token timeout in Keycloak:\n - Navigate to: **Keycloak Admin Console → Realm Settings → Tokens → Access Token Lifespan**\n - Increase the value as needed for your automation or extended use cases\n\nThis approach is more secure than using refresh tokens and provides better audit trails.\n\n## Error Handling\n\nThe API returns standard HTTP status codes:\n\n- `200 OK`: Success\n- `401 Unauthorized`: Invalid or expired token\n- `403 Forbidden`: Insufficient permissions\n- `404 Not Found`: Server or version not found\n- `500 Internal Server Error`: Server error\n\nError responses follow this format:\n```json\n{\n \"error\": {\n \"code\": \"UNAUTHORIZED\",\n \"message\": \"Invalid or expired token\"\n }\n}\n```\n\n## Rate Limiting\n\nThe API may implement rate limiting. Check response headers for rate limit information:\n- `X-RateLimit-Limit`: Maximum requests per time window\n- `X-RateLimit-Remaining`: Remaining requests in current window\n- `X-RateLimit-Reset`: When the rate limit window resets\n\n## Security Considerations\n\n1. **Token Storage**: Store JWT tokens securely and never commit them to version control\n2. **Token Expiry**: Generate new tokens when needed or configure longer lifetimes in Keycloak\n3. **HTTPS**: Always use HTTPS in production environments\n4. **Access Control**: Tokens respect user permissions - users only see servers they have access to\n\n## Support\n\nFor issues with the Anthropic Registry API implementation:\n\n1. **Official Anthropic Registry API Specification**: [View the interactive API documentation](https://elements-demo.stoplight.io/?spec=https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/api/openapi.yaml) - This is the official Anthropic MCP Registry REST API specification that this implementation follows\n2. Review the [authentication guide](./auth.md) for authentication setup\n3. Examine the test script at `cli/test_anthropic_api.py` for working examples\n4. Check server logs for detailed error information\n\nThe API is fully compatible with Anthropic's MCP Registry specification, so any client built for the official registry should work with this implementation." }, { "path": "docs/api-reference.md", "content": "# MCP Gateway Registry - Complete API Reference\n\nThis document provides a comprehensive overview of all 49 API endpoints available in the MCP Gateway Registry, organized by category with authentication requirements, request/response specifications, and OpenAPI documentation links.\n\n## Table of Contents\n\n1. [API Categories](#api-categories)\n2. [Authentication Schemes](#authentication-schemes)\n3. [A2A Agent Management APIs](#a2a-agent-management-apis)\n4. [Anthropic MCP Registry API v0](#anthropic-mcp-registry-api-v0)\n5. [Internal Server Management APIs](#internal-server-management-apis)\n6. [JWT Server Management API](#jwt-server-management-api)\n7. [Authentication & Login APIs](#authentication--login-apis)\n8. [Health Monitoring APIs](#health-monitoring-apis)\n9. [Discovery & Well-Known Endpoints](#discovery--well-known-endpoints)\n10. [Utility Endpoints](#utility-endpoints)\n11. [Response Codes & Error Handling](#response-codes--error-handling)\n12. [OpenAPI Specifications](#openapi-specifications)\n\n---\n\n## API Categories\n\n| Category | Count | Auth Method | Purpose |\n|----------|-------|-------------|---------|\n| A2A Agent Management | 8 | JWT Bearer Token | Agent registration, discovery, and management |\n| Anthropic Registry API v0 (Servers) | 3 | JWT Bearer Token | Standard MCP server discovery via Anthropic API spec |\n| Internal Server Management (UI) | 10 | Session Cookie | Dashboard and service management |\n| Internal Server Management (Admin) | 12 | HTTP Basic Auth | Administrative operations and group management |\n| JWT Server Management | 11 | JWT Bearer Token | Programmatic server registration, auth credentials, and management |\n| Authentication & Login | 7 | OAuth2 + Session | User authentication and provider management |\n| Health Monitoring | 3 | Session Cookie / None | Real-time health updates and statistics |\n| Discovery | 1 | None (Public) | Public MCP server discovery |\n| Utility | 2 | Session Cookie / Public | Current user info and service health |\n| **TOTAL** | **46** | **Multiple** | **Full registry functionality** |\n\n---\n\n## Authentication Schemes\n\n### 1. JWT Bearer Token (Nginx-Proxied Auth)\n\n**Used by:** A2A Agent APIs, Anthropic Registry API v0\n\n**How it works:**\n- Client sends JWT token in `Authorization: Bearer ` header\n- Nginx validates token via `/validate` endpoint against auth-server\n- Auth-server validates token against Keycloak\n- Token scopes determine user permissions\n\n**Token Sources:**\n- Keycloak M2M service account (`mcp-gateway-m2m`)\n- User tokens generated via `/api/tokens/generate`\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...\" \\\n http://localhost/v0.1/agents\n```\n\n---\n\n### 2. Session Cookie (Enhanced Auth)\n\n**Used by:** UI Server Management, Health Monitoring (WebSocket), Auth status endpoints\n\n**How it works:**\n- User logs in via OAuth2 (Keycloak)\n- Auth-server sets `mcp_gateway_session` cookie\n- Browser automatically includes cookie in subsequent requests\n- Registry validates cookie against auth-server\n\n**Example:**\n```bash\ncurl -b \"mcp_gateway_session=\" \\\n http://localhost/api/servers\n```\n\n---\n\n### 3. Public (No Authentication)\n\n**Used by:** Discovery endpoints, login page, OAuth2 providers list\n\n**Endpoints:**\n- `GET /.well-known/mcp-servers`\n- `GET /api/auth/login`\n- `GET /api/auth/providers`\n- `GET /health`\n\n---\n\n## A2A Agent Management APIs\n\n**File:** `registry/api/agent_routes.py`\n**Route Prefix:** `/api`\n**Authentication:** JWT Bearer Token (nginx_proxied_auth)\n\n### 1. Register Agent\n\n**Endpoint:** `POST /api/agents/register`\n\n**Purpose:** Register a new A2A agent in the registry\n\n**Authentication:** Requires `publish_agent` scope\n\n**Request Body:**\n```json\n{\n \"name\": \"string\",\n \"description\": \"string\",\n \"path\": \"/agent-name\",\n \"url\": \"https://example.com/agent\",\n \"version\": \"1.0.0\",\n \"provider\": \"anthropic|custom|other\",\n \"security_schemes\": {\n \"scheme_name\": {\n \"type\": \"bearer|api_key|oauth2|etc\",\n \"description\": \"string\"\n }\n },\n \"skills\": [\n {\n \"name\": \"skill_name\",\n \"description\": \"string\",\n \"input_schema\": {}\n }\n ],\n \"tags\": \"string, comma, separated\",\n \"visibility\": \"public|private|internal\",\n \"license\": \"MIT|Apache-2.0|etc\"\n}\n```\n\n**Response:** `201 Created`\n```json\n{\n \"message\": \"Agent registered successfully\",\n \"agent\": {\n \"name\": \"string\",\n \"path\": \"/agent-name\",\n \"url\": \"https://example.com/agent\",\n \"num_skills\": 5,\n \"registered_at\": \"2025-11-01T04:53:56.228791+00:00\",\n \"is_enabled\": false\n }\n}\n```\n\n**Error Codes:**\n- `409 Conflict` - Agent path already exists\n- `422 Unprocessable Entity` - Validation error (invalid JSON, missing fields)\n- `403 Forbidden` - User lacks `publish_agent` permission\n\n---\n\n### 2. List Agents\n\n**Endpoint:** `GET /api/agents`\n\n**Purpose:** List all agents, optionally filtered\n\n**Authentication:** Optional (results filtered by user permissions)\n\n**Query Parameters:**\n- `query` (optional, string) - Search query string\n- `enabled_only` (optional, boolean, default: false) - Show only enabled agents\n- `visibility` (optional, string) - Filter by visibility level\n\n**Response:** `200 OK`\n```json\n{\n \"agents\": [\n {\n \"name\": \"string\",\n \"path\": \"/agent-name\",\n \"description\": \"string\",\n \"is_enabled\": true,\n \"total_count\": 5\n }\n ]\n}\n```\n\n---\n\n### 3. Get Single Agent\n\n**Endpoint:** `GET /api/agents/{path:path}`\n\n**Purpose:** Get a single agent by path\n\n**Authentication:** JWT Bearer Token required\n\n**Path Parameter:**\n- `path` - Agent path (e.g., `/code-reviewer`)\n\n**Response:** `200 OK`\n```json\n{\n \"name\": \"Code Reviewer Agent\",\n \"path\": \"/code-reviewer\",\n \"description\": \"string\",\n \"url\": \"https://example.com/agents/code-reviewer\",\n \"version\": \"1.0.0\",\n \"skills\": [\n {\n \"name\": \"review_code\",\n \"description\": \"string\"\n }\n ],\n \"is_enabled\": true\n}\n```\n\n**Error Codes:**\n- `404 Not Found` - Agent doesn't exist\n- `403 Forbidden` - User not authorized\n\n---\n\n### 4. Update Agent\n\n**Endpoint:** `PUT /api/agents/{path:path}`\n\n**Purpose:** Update an existing agent\n\n**Authentication:** Requires `modify_service` permission and ownership\n\n**Path Parameter:**\n- `path` - Agent path\n\n**Request Body:** Same as registration request\n\n**Response:** `200 OK` with updated agent card\n\n**Error Codes:**\n- `404 Not Found` - Agent doesn't exist\n- `403 Forbidden` - User lacks modify permission\n- `422 Unprocessable Entity` - Validation error\n\n---\n\n### 5. Delete Agent\n\n**Endpoint:** `DELETE /api/agents/{path:path}`\n\n**Purpose:** Delete an agent from registry\n\n**Authentication:** Requires admin permission or agent ownership\n\n**Path Parameter:**\n- `path` - Agent path\n\n**Response:** `204 No Content`\n\n**Error Codes:**\n- `404 Not Found` - Agent doesn't exist\n- `403 Forbidden` - User lacks delete permission\n\n---\n\n### 6. Toggle Agent Status\n\n**Endpoint:** `POST /api/agents/{path:path}/toggle`\n\n**Purpose:** Enable or disable an agent\n\n**Authentication:** Requires `toggle_service` permission\n\n**Path Parameter:**\n- `path` - Agent path\n\n**Query Parameter:**\n- `enabled` (boolean) - True to enable, false to disable\n\n**Response:** `200 OK`\n```json\n{\n \"path\": \"/agent-name\",\n \"is_enabled\": true,\n \"message\": \"Agent enabled successfully\"\n}\n```\n\n**Error Codes:**\n- `404 Not Found` - Agent doesn't exist\n- `403 Forbidden` - User lacks toggle permission\n\n---\n\n### 7. Discover Agents by Skills\n\n**Endpoint:** `POST /api/agents/discover`\n\n**Purpose:** Find agents that match required skills\n\n**Authentication:** Optional\n\n**Request Body:**\n```json\n{\n \"skills\": [\"skill1\", \"skill2\"],\n \"tags\": [\"optional\", \"filters\"]\n}\n```\n\n**Query Parameter:**\n- `max_results` (optional, integer, default: 10, max: 100)\n\n**Response:** `200 OK`\n```json\n{\n \"agents\": [\n {\n \"path\": \"/agent-name\",\n \"name\": \"string\",\n \"relevance_score\": 0.95,\n \"matching_skills\": [\"skill1\"]\n }\n ]\n}\n```\n\n**Error Codes:**\n- `400 Bad Request` - No skills provided\n\n---\n\n### 8. Discover Agents Semantically\n\n**Endpoint:** `POST /api/agents/discover/semantic`\n\n**Purpose:** Find agents using NLP semantic search (FAISS vector search)\n\n**Authentication:** Optional\n\n**Query Parameters:**\n- `query` (required, string) - Natural language query (e.g., \"Find agents that can analyze code\")\n- `max_results` (optional, integer, default: 10, max: 100)\n\n**Response:** `200 OK`\n```json\n{\n \"agents\": [\n {\n \"path\": \"/code-reviewer\",\n \"name\": \"Code Reviewer Agent\",\n \"relevance_score\": 0.92,\n \"description\": \"Analyzes code for issues...\"\n }\n ]\n}\n```\n\n**Error Codes:**\n- `400 Bad Request` - Empty query\n- `500 Internal Server Error` - Search error\n\n---\n\n## Anthropic MCP Registry API v0\n\nThis section implements the official [Anthropic MCP Registry API specification](https://github.com/modelcontextprotocol/registry) for standard server discovery and agent discovery using the same API patterns.\n\n### MCP Servers (v0)\n\n**File:** `registry/api/registry_routes.py`\n**Route Prefix:** `/v0` (from `REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION`)\n**Authentication:** JWT Bearer Token\n\n#### 1. List MCP Servers\n\n**Endpoint:** `GET /v0/servers`\n\n**Purpose:** List all MCP servers with cursor-based pagination\n\n**Query Parameters:**\n- `cursor` (optional, string) - Pagination cursor from previous response\n- `limit` (optional, integer, default: 100, max: 1000) - Max items per page\n\n**Response:** `200 OK`\n```json\n{\n \"servers\": [\n {\n \"id\": \"io.mcpgateway/example-server\",\n \"name\": \"Example Server\",\n \"description\": \"string\",\n \"homepage\": \"https://example.com\",\n \"resources\": [\n {\n \"uri\": \"example://resource\",\n \"mimeType\": \"text/plain\"\n }\n ]\n }\n ],\n \"_meta\": {\n \"pagination\": {\n \"hasMore\": false,\n \"nextCursor\": null\n }\n }\n}\n```\n\n---\n\n#### 2. List Server Versions\n\n**Endpoint:** `GET /v0/servers/{serverName:path}/versions`\n\n**Purpose:** List all versions for a specific server\n\n**Path Parameter:**\n- `serverName` - URL-encoded reverse-DNS name (e.g., `io.mcpgateway%2Fexample-server`)\n\n**Response:** `200 OK` with versions array (currently one version per server)\n\n**Error Codes:**\n- `404 Not Found` - Server not found or user lacks access\n\n---\n\n#### 3. Get Server Version Details\n\n**Endpoint:** `GET /v0/servers/{serverName:path}/versions/{version}`\n\n**Purpose:** Get detailed information about a specific server version\n\n**Path Parameters:**\n- `serverName` - URL-encoded server name\n- `version` - Version string or `latest`\n\n**Response:** `200 OK` with complete server details including tools\n\n**Error Codes:**\n- `404 Not Found` - Server/version not found or user lacks access\n\n---\n\n## Internal Server Management APIs\n\n### UI Management Endpoints\n\n**File:** `registry/api/server_routes.py`\n**Route Prefix:** `/api`\n**Authentication:** Session Cookie (enhanced_auth)\n\n#### 1. Dashboard/Root\n\n**Endpoint:** `GET /api/`\n\n**Purpose:** Main dashboard showing services based on user permissions\n\n**Query Parameters:**\n- `query` (optional, string) - Search services\n\n**Response:** HTML page with filtered service list\n\n---\n\n#### 2. Get Servers JSON\n\n**Endpoint:** `GET /api/servers`\n\n**Purpose:** Get servers data as JSON for React frontend\n\n**Query Parameters:**\n- `query` (optional, string)\n\n**Response:** `200 OK`\n```json\n{\n \"servers\": [\n {\n \"path\": \"/example\",\n \"name\": \"Example Server\",\n \"description\": \"string\",\n \"is_enabled\": true,\n \"health_status\": \"healthy\"\n }\n ]\n}\n```\n\n---\n\n#### 3. Toggle Service\n\n**Endpoint:** `POST /api/toggle/{service_path:path}`\n\n**Purpose:** Enable/disable a service\n\n**Authentication:** Requires `toggle_service` UI permission\n\n**Form Parameters:**\n- `enabled` (boolean)\n\n**Response:** `200 OK` with new status\n\n**Error Codes:**\n- `404 Not Found` - Service doesn't exist\n- `403 Forbidden` - User lacks toggle permission\n- `500 Internal Server Error` - Toggle operation failed\n\n---\n\n#### 4. Register Service (UI)\n\n**Endpoint:** `POST /api/register`\n\n**Purpose:** Register new service via dashboard\n\n**Authentication:** Requires `register_service` UI permission\n\n**Form Parameters:**\n- `name`, `description`, `path`, `proxy_pass_url`, `tags`, `num_tools`, `num_stars`, `is_python`, `license`\n\n**Response:** `201 Created`\n\n**Error Codes:**\n- `400 Bad Request` - Service already exists\n- `403 Forbidden` - User lacks register permission\n\n---\n\n#### 5. Edit Service Form\n\n**Endpoint:** `GET /api/edit/{service_path:path}`\n\n**Purpose:** Show edit form for service\n\n**Authentication:** Requires `modify_service` UI permission\n\n**Response:** HTML edit form\n\n---\n\n#### 6. Update Service\n\n**Endpoint:** `POST /api/edit/{service_path:path}`\n\n**Purpose:** Handle service edit submission\n\n**Authentication:** Requires `modify_service` UI permission\n\n**Form Parameters:** Same as register\n\n**Response:** `303 See Other` (redirect to home)\n\n---\n\n#### 7. Token Generation Page\n\n**Endpoint:** `GET /api/tokens`\n\n**Purpose:** Show JWT token generation form\n\n**Response:** HTML form\n\n---\n\n#### 8. Get Server Details\n\n**Endpoint:** `GET /api/server_details/{service_path:path}`\n\n**Purpose:** Get detailed server info by path or all servers\n\n**Path Parameter:**\n- `service_path` - Service path or `all`\n\n**Response:** `200 OK` with server details\n\n---\n\n#### 9. Get Service Tools\n\n**Endpoint:** `GET /api/tools/{service_path:path}`\n\n**Purpose:** Get tools list for service\n\n**Path Parameter:**\n- `service_path` - Service path or `all`\n\n**Response:** `200 OK`\n```json\n{\n \"tools\": [\n {\n \"name\": \"tool_name\",\n \"description\": \"string\",\n \"inputSchema\": {}\n }\n ]\n}\n```\n\n**Error Codes:**\n- `404 Not Found` - Service not found\n- `400 Bad Request` - Service disabled\n- `403 Forbidden` - User lacks access\n\n---\n\n#### 10. Refresh Service\n\n**Endpoint:** `POST /api/refresh/{service_path:path}`\n\n**Purpose:** Refresh service health and tools\n\n**Authentication:** Requires `health_check_service` permission\n\n**Response:** `200 OK` with refresh status\n\n---\n\n### Internal Admin Endpoints\n\n**Authentication:** HTTP Basic Auth (admin credentials)\n\n#### 11. Internal Register Service\n\n**Endpoint:** `POST /api/internal/register`\n\n**Purpose:** Internal service registration for mcpgw-server\n\n**Form Parameters:** All registration parameters + `overwrite`, `auth_provider`, `auth_type`, `supported_transports`, `headers`, `tool_list_json`\n\n**Response:** `201 Created` or `409 Conflict`\n\n**Features:** Auto-enables services, updates scopes.yml\n\n---\n\n#### 12. Internal Remove Service\n\n**Endpoint:** `POST /api/internal/remove`\n\n**Form Parameters:** `service_path`\n\n**Response:** `200 OK` or `404/500` error\n\n---\n\n#### 13. Internal Toggle Service\n\n**Endpoint:** `POST /api/internal/toggle`\n\n**Form Parameters:** `service_path`\n\n**Response:** `200 OK` with new state\n\n---\n\n#### 14. Internal Healthcheck\n\n**Endpoint:** `POST /api/internal/healthcheck`\n\n**Response:** Health status for all servers\n\n---\n\n#### 15. Add Server to Groups\n\n**Endpoint:** `POST /api/internal/add-to-groups`\n\n**Form Parameters:**\n- `server_name` - Server name\n- `group_names` - Comma-separated group names\n\n**Response:** `200 OK` with result\n\n---\n\n#### 16. Remove Server from Groups\n\n**Endpoint:** `POST /api/internal/remove-from-groups`\n\n**Form Parameters:** Same as add-to-groups\n\n**Response:** `200 OK`\n\n---\n\n#### 17. Internal List Services\n\n**Endpoint:** `GET /api/internal/list`\n\n**Response:** `200 OK` with all services and health status\n\n---\n\n#### 18. Create Group\n\n**Endpoint:** `POST /api/internal/create-group`\n\n**Form Parameters:**\n- `group_name`\n- `description` (optional)\n- `create_in_idp` (optional)\n\n**Response:** `200 OK`\n\n---\n\n#### 19. Delete Group\n\n**Endpoint:** `POST /api/internal/delete-group`\n\n**Form Parameters:**\n- `group_name`\n- `delete_from_idp` (optional)\n- `force` (optional)\n\n**Response:** `200 OK`\n\n**Note:** Prevents deletion of system groups\n\n---\n\n#### 20. List Groups\n\n**Endpoint:** `GET /api/internal/list-groups`\n\n**Query Parameters:**\n- `include_keycloak` (default: true)\n- `include_scopes` (default: true)\n\n**Response:** `200 OK` with synchronized groups info\n\n---\n\n#### 21. Generate JWT Token\n\n**Endpoint:** `POST /api/tokens/generate`\n\n**Purpose:** Generate JWT token for authenticated user\n\n**Request Body:**\n```json\n{\n \"requested_scopes\": [\"optional\", \"scopes\"],\n \"expires_in_hours\": 8,\n \"description\": \"Token description\"\n}\n```\n\n**Response:** `200 OK`\n```json\n{\n \"access_token\": \"string\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 28800,\n \"refresh_token\": \"string (if enabled)\",\n \"scope\": \"space separated scopes\"\n}\n```\n\n---\n\n#### 22. Admin Get Keycloak Token\n\n**Endpoint:** `GET /api/admin/tokens`\n\n**Purpose:** Admin-only endpoint to retrieve M2M tokens\n\n**Authentication:** Admin users only\n\n**Response:** `200 OK` with access token\n\n**Error Codes:**\n- `403 Forbidden` - Non-admin user\n- `500 Internal Server Error` - Configuration error\n\n---\n\n## JWT Server Management API\n\nModern JWT-authenticated endpoints for programmatic server management. These are the external API equivalents of the internal UI endpoints.\n\n**File:** `registry/api/server_routes.py`\n**Route Prefix:** `/api`\n**Authentication:** JWT Bearer Token (nginx_proxied_auth)\n\n#### 1. Register Server\n\n**Endpoint:** `POST /api/servers/register`\n\n**Purpose:** Register an MCP server with optional backend authentication credentials\n\n**Request body (form data):**\n- `name` (required): Service name\n- `description` (required): Service description\n- `path` (required): Service path (e.g., `/myservice`)\n- `proxy_pass_url` (required): Backend URL (e.g., `http://localhost:8000`)\n- `tags` (optional): Comma-separated tags\n- `auth_scheme` (optional): Backend auth scheme -- `none` (default), `bearer`, or `api_key`\n- `auth_credential` (optional): Plaintext credential (encrypted before storage)\n- `auth_header_name` (optional): Custom header name (default: `Authorization` for bearer, `X-API-Key` for api_key)\n- `tool_list_json` (optional): JSON array of MCP tool definitions (for manual tool registration)\n- `supported_transports` (optional): JSON array of transports\n- `headers` (optional): JSON object of custom headers\n- `mcp_endpoint` (optional): Custom MCP endpoint URL\n- `sse_endpoint` (optional): Custom SSE endpoint URL\n- `version` (optional): Server version (e.g., `v1.0.0`)\n- `status` (optional): Lifecycle status (`active`, `deprecated`, `draft`, `beta`)\n- `provider_organization` (optional): Provider organization name\n- `provider_url` (optional): Provider URL\n\n**Response:** `201 Created`\n\n**Error Codes:**\n- `400 Bad Request` - Invalid input data\n- `401 Unauthorized` - Missing or invalid JWT token\n- `409 Conflict` - Server already exists with same version\n- `500 Internal Server Error` - Server error\n\n**Example:**\n```bash\n# Register a server behind Bearer token auth\ncurl -X POST https://registry.example.com/api/servers/register \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -F \"name=My Protected Server\" \\\n -F \"description=An MCP server behind Bearer auth\" \\\n -F \"path=/my-protected-server\" \\\n -F \"proxy_pass_url=http://my-server:8000\" \\\n -F \"auth_scheme=bearer\" \\\n -F \"auth_credential=backend-server-token\"\n```\n\n---\n\n#### 2. Update Server\n\n**Endpoint:** `PUT /api/servers/{server_path:path}`\n\n**Purpose:** Update an existing server's details\n\n**Path Parameter:**\n- `server_path` - Server path (e.g., `/my-server`)\n\n**Request body (form data):** Same fields as register\n\n**Response:** `200 OK` with updated server details\n\n**Error Codes:**\n- `404 Not Found` - Server not found\n\n---\n\n#### 3. Update Auth Credential\n\n**Endpoint:** `PATCH /api/servers/{server_path:path}/auth-credential`\n\n**Purpose:** Update or rotate the authentication credential for a registered server without re-registering\n\n**Path Parameter:**\n- `server_path` - Server path (e.g., `/my-server`)\n\n**Request body (JSON):**\n- `auth_scheme` (required): `none`, `bearer`, or `api_key`\n- `auth_credential` (optional): New credential. Required if auth_scheme is not `none`.\n- `auth_header_name` (optional): Custom header name. Default: `X-API-Key` for api_key.\n\n**Response:** `200 OK`\n\n**Error Codes:**\n- `400 Bad Request` - Invalid auth_scheme or missing credential\n- `404 Not Found` - Server not found\n\n**Example:**\n```bash\n# Rotate a Bearer token\ncurl -X PATCH https://registry.example.com/api/servers/my-server/auth-credential \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"auth_scheme\": \"bearer\", \"auth_credential\": \"new-token\"}'\n```\n\n---\n\n#### 4. Delete Server\n\n**Endpoint:** `DELETE /api/servers/{server_path:path}`\n\n**Purpose:** Remove a registered server\n\n**Path Parameter:**\n- `server_path` - Server path\n\n**Response:** `200 OK`\n\n**Error Codes:**\n- `404 Not Found` - Server not found\n\n**Example:**\n```bash\ncurl -X DELETE https://registry.example.com/api/servers/my-server \\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n```\n\n---\n\n#### 5. Toggle Server\n\n**Endpoint:** `POST /api/servers/toggle`\n\n**Purpose:** Enable or disable a server\n\n**Request body (form data):**\n- `path` (required): Service path\n- `new_state` (required): `true` (enabled) or `false` (disabled)\n\n**Response:** `200 OK` with updated status\n\n---\n\n#### 6. Get Health Status\n\n**Endpoint:** `GET /api/servers/health`\n\n**Purpose:** Get health status for all registered servers\n\n**Response:** `200 OK` with health data for all servers\n\n---\n\n#### 7. Get Server Rating\n\n**Endpoint:** `GET /api/servers/{server_path:path}/rating`\n\n**Purpose:** Get the rating for a server\n\n**Response:** `200 OK` with rating data\n\n---\n\n#### 8. Submit Server Rating\n\n**Endpoint:** `POST /api/servers/{server_path:path}/rating`\n\n**Purpose:** Submit a rating for a server\n\n**Request body (JSON):**\n- `rating` (required): Rating value (1-5)\n- `comment` (optional): Review comment\n\n**Response:** `201 Created`\n\n---\n\n#### 9. List Server Versions\n\n**Endpoint:** `GET /api/servers/{server_path:path}/versions`\n\n**Purpose:** List all versions for a server\n\n**Response:** `200 OK` with versions array\n\n---\n\n#### 10. Group Management\n\n**Add to groups:** `POST /api/servers/groups/add`\n**Remove from groups:** `POST /api/servers/groups/remove`\n\n**Request body (form data):**\n- `server_name` (required): Service name\n- `group_names` (required): Comma-separated group names\n\n**Example:**\n```bash\ncurl -X POST https://registry.example.com/api/servers/groups/add \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -F \"server_name=myservice\" \\\n -F \"group_names=admin,developers\"\n```\n\n---\n\n#### 11. Get Single Server\n\n**Endpoint:** `GET /api/servers/{path:path}`\n\n**Purpose:** Get detailed information about a single MCP server by path. Mirrors the `GET /api/agents/{path}` endpoint pattern.\n\n**Path Parameter:**\n- `path` - Server path (e.g., `/my-server`)\n\n**Response:** `200 OK` with server details including tools, versions, health status\n\n**Notes:**\n- `proxy_pass_url` is stripped for non-admin users in with-gateway deployment mode\n- In registry-only deployment mode, `proxy_pass_url` is included for all users (needed to connect directly)\n- Credentials are never included in the response\n\n**Error Codes:**\n- `403 Forbidden` - User lacks access to this server\n- `404 Not Found` - Server not found at the given path\n\n**Example:**\n```bash\ncurl -X GET https://registry.example.com/api/servers/my-server \\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n```\n\n---\n\n## Authentication & Login APIs\n\n**File:** `registry/auth/routes.py`\n**Route Prefix:** `/api/auth`\n\n### 1. Login Form\n\n**Endpoint:** `GET /api/auth/login`\n\n**Purpose:** Show login form with OAuth2 providers\n\n**Query Parameters:**\n- `error` (optional) - Error message\n\n**Response:** HTML login form\n\n---\n\n### 2. OAuth2 Redirect\n\n**Endpoint:** `GET /api/auth/auth/{provider}`\n\n**Purpose:** Redirect to auth server for OAuth2 login\n\n**Path Parameter:**\n- `provider` - OAuth2 provider (e.g., `keycloak`, `cognito`)\n\n**Response:** `302 Redirect` to auth server\n\n---\n\n### 3. OAuth2 Callback\n\n**Endpoint:** `GET /api/auth/auth/callback`\n\n**Purpose:** Handle OAuth2 callback\n\n**Query Parameters:**\n- `error` (optional)\n- `details` (optional)\n\n**Response:** `302 Redirect` to home or login with error\n\n---\n\n### 4. Login Submit (Form)\n\n**Endpoint:** `POST /api/auth/login`\n\n**Purpose:** Handle login form submission\n\n**Form Parameters:**\n- `username`\n- `password`\n\n**Response:** `302 Redirect` to home on success, `401` on failure\n\n---\n\n### 5. Logout (GET)\n\n**Endpoint:** `GET /api/auth/logout`\n\n**Purpose:** Handle logout via GET\n\n**Response:** `302 Redirect` to login (clears session)\n\n---\n\n### 6. Logout (POST)\n\n**Endpoint:** `POST /api/auth/logout`\n\n**Purpose:** Handle logout via POST\n\n**Response:** `302 Redirect` to login (clears session)\n\n---\n\n### 7. OAuth2 Providers List\n\n**Endpoint:** `GET /api/auth/providers`\n\n**Purpose:** Get available OAuth2 providers\n\n**Authentication:** None (public)\n\n**Response:** `200 OK`\n```json\n{\n \"providers\": [\n {\n \"name\": \"keycloak\",\n \"display_name\": \"Keycloak\",\n \"icon\": \"keycloak\"\n }\n ]\n}\n```\n\n---\n\n## Health Monitoring APIs\n\n**File:** `registry/health/routes.py`\n**Route Prefix:** `/api/health`\n\n### 1. Health Status WebSocket\n\n**Endpoint:** `WebSocket /api/health/ws/health_status`\n\n**Purpose:** Real-time health status updates via WebSocket\n\n**Authentication:** Session cookie required\n\n**Messages:** Periodic health status broadcasts\n\n**Features:**\n- Authenticated connections only\n- Ping/pong keep-alive\n- Graceful disconnect handling\n\n---\n\n### 2. Health Status HTTP\n\n**Endpoint:** `GET /api/health/ws/health_status`\n\n**Purpose:** Get health status via HTTP (WebSocket fallback)\n\n**Authentication:** None\n\n**Response:** `200 OK` with health status JSON\n\n---\n\n### 3. WebSocket Statistics\n\n**Endpoint:** `GET /api/health/ws/stats`\n\n**Purpose:** Get WebSocket performance statistics\n\n**Response:** `200 OK`\n```json\n{\n \"active_connections\": 5,\n \"total_messages_sent\": 1234,\n \"uptime_seconds\": 86400\n}\n```\n\n---\n\n## Discovery & Well-Known Endpoints\n\n**File:** `registry/api/wellknown_routes.py`\n**Route Prefix:** `/.well-known`\n**Authentication:** None (public)\n\n### MCP Servers Discovery\n\n**Endpoint:** `GET /.well-known/mcp-servers`\n\n**Purpose:** Public MCP server discovery for client tools\n\n**Response:** `200 OK`\n```json\n{\n \"servers\": [\n {\n \"id\": \"io.mcpgateway/example\",\n \"name\": \"Example Server\",\n \"description\": \"string\",\n \"mcp\": {\n \"transport\": \"streamable-http\",\n \"url\": \"https://gateway.example.com/example/\"\n }\n }\n ],\n \"_meta\": {\n \"registry\": \"MCP Gateway Registry\",\n \"updated_at\": \"2025-11-01T04:53:56Z\"\n }\n}\n```\n\n**Features:**\n- Server filtering by enabled status\n- Authentication info included\n- Tools preview\n- Public cache headers with configurable TTL\n\n---\n\n## Utility Endpoints\n\n### 1. Current User Info\n\n**Endpoint:** `GET /api/auth/me`\n\n**Purpose:** Get current user information for React auth context\n\n**Authentication:** Session cookie (enhanced_auth)\n\n**Response:** `200 OK`\n```json\n{\n \"username\": \"admin\",\n \"email\": \"admin@example.com\",\n \"auth_method\": \"oauth2\",\n \"provider\": \"keycloak\",\n \"scopes\": [\"mcp-registry-admin\"],\n \"groups\": [\"mcp-registry-admin\", \"mcp-servers-unrestricted\"],\n \"is_admin\": true\n}\n```\n\n---\n\n### 2. Health Check\n\n**Endpoint:** `GET /health`\n\n**Purpose:** Simple health check for load balancers\n\n**Authentication:** None (public)\n\n**Response:** `200 OK`\n```json\n{\n \"status\": \"healthy\",\n \"service\": \"mcp-gateway-registry\"\n}\n```\n\n---\n\n## Response Codes & Error Handling\n\n### Success Responses\n\n| Code | Meaning | Use Case |\n|------|---------|----------|\n| `200 OK` | Successful GET/POST | Data retrieval, updates |\n| `201 Created` | Resource created | Agent/server registration |\n| `204 No Content` | Successful deletion | DELETE operations |\n| `303 See Other` | Redirect after form | Form submissions (POST) |\n\n### Client Error Responses\n\n| Code | Meaning | Example |\n|------|---------|---------|\n| `400 Bad Request` | Invalid input | Missing required fields, invalid JSON |\n| `401 Unauthorized` | Authentication failed | Missing/invalid JWT token |\n| `403 Forbidden` | Permission denied | User lacks required scope |\n| `404 Not Found` | Resource doesn't exist | Agent/server not found |\n| `409 Conflict` | Resource conflict | Agent path already registered |\n| `422 Unprocessable Entity` | Validation error | Invalid field values |\n\n### Server Error Responses\n\n| Code | Meaning | Example |\n|------|---------|---------|\n| `500 Internal Server Error` | Server error | Exception during processing |\n| `502 Bad Gateway` | Upstream error | Auth server unreachable |\n| `503 Service Unavailable` | Service down | Database unavailable |\n\n### Error Response Format\n\n```json\n{\n \"detail\": \"Human-readable error message\",\n \"error_code\": \"optional_error_code\",\n \"request_id\": \"unique_request_identifier\"\n}\n```\n\n---\n\n## OpenAPI Specifications\n\n### Access OpenAPI Specifications\n\nFastAPI automatically generates OpenAPI (Swagger) specifications:\n\n**Available Endpoints:**\n- **OpenAPI JSON:** `GET /openapi.json`\n- **Swagger UI:** `GET /docs`\n- **ReDoc:** `GET /redoc`\n\n**Local Access:**\n```bash\ncurl http://localhost:7860/openapi.json\n```\n\n**Browser Access:**\n- Swagger UI: http://localhost:7860/docs\n- ReDoc: http://localhost:7860/redoc\n\n### Generate Spec Files\n\nTo download and save OpenAPI specs:\n\n```bash\n# Get full OpenAPI spec as JSON\ncurl -s http://localhost:7860/openapi.json > openapi.json\n\n# Filter for specific tags\ncurl -s http://localhost:7860/openapi.json | \\\n jq '.paths | keys[] | select(contains(\"/agents\"))' > agents-endpoints.json\n\n# Generate Swagger YAML (requires conversion)\ncurl -s http://localhost:7860/openapi.json | \\\n python3 -c \"import sys, json, yaml; print(yaml.dump(json.load(sys.stdin)))\" > openapi.yaml\n```\n\n### Using Generated Specs\n\n1. **Code Generation:**\n ```bash\n # Generate Python client\n openapi-generator-cli generate -i openapi.json -g python -o ./python-client\n\n # Generate JavaScript client\n openapi-generator-cli generate -i openapi.json -g javascript -o ./js-client\n ```\n\n2. **API Documentation:** Import into Postman, Insomnia, or other API tools\n\n3. **Validation:** Use `openapi-spec-validator` to validate the spec\n\n---\n\n## Summary Table\n\n| Category | Endpoints | Auth | Purpose |\n|----------|-----------|------|---------|\n| A2A Agents | 8 | JWT Bearer | Agent lifecycle management |\n| Anthropic v0 (Servers) | 3 | JWT Bearer | Standard server discovery |\n| Anthropic v0 (Agents) | 3 | JWT Bearer | Standard agent discovery |\n| UI Management | 10 | Session Cookie | Dashboard operations |\n| Admin Operations | 12 | HTTP Basic Auth | Administrative tasks |\n| Authentication | 7 | OAuth2/Session | User login/logout |\n| Health Monitoring | 3 | Session/None | Real-time status |\n| Discovery | 1 | None | Public server discovery |\n| Utility | 2 | Session/None | Helper endpoints |\n| **TOTAL** | **49** | **Multiple** | **Full system coverage** |\n\n---\n\n## Quick Reference by Use Case\n\n### I want to register an agent\n- **Endpoint:** `POST /api/agents/register`\n- **Auth:** JWT Bearer Token with `publish_agent` scope\n- **Documentation:** See [A2A Agent Management APIs > Register Agent](#1-register-agent)\n\n### I want to discover agents by capability\n- **Endpoint:** `POST /api/agents/discover/semantic`\n- **Auth:** Optional\n- **Query:** Natural language query\n- **Documentation:** See [A2A Agent Management APIs > Discover Agents Semantically](#8-discover-agents-semantically)\n\n### I want to list all servers (Anthropic API format)\n- **Endpoint:** `GET /v0/servers`\n- **Auth:** JWT Bearer Token\n- **Documentation:** See [Anthropic MCP Registry API v0 > List MCP Servers](#1-list-mcp-servers)\n\n### I want to generate a JWT token\n- **Endpoint:** `POST /api/tokens/generate`\n- **Auth:** Session Cookie\n- **Documentation:** See [Internal Server Management APIs > Generate JWT Token](#21-generate-jwt-token)\n\n### I want to find servers I have access to\n- **Endpoint:** `GET /api/servers`\n- **Auth:** Session Cookie\n- **Documentation:** See [Internal Server Management APIs > Get Servers JSON](#2-get-servers-json)\n\n---\n\n## Version History\n\n| Date | Version | Changes |\n|------|---------|---------|\n| 2025-11-01 | 1.0 | Initial API reference documentation, 49 endpoints cataloged |\n\n" }, { "path": "docs/audit-logging.md", "content": "# Audit Logging\n\nMCP Gateway Registry provides comprehensive audit logging for compliance, security monitoring, and operational visibility. All API requests and MCP server access events are logged to MongoDB/DocumentDB with automatic retention management.\n\n![Audit Log Viewer](img/audit-log.png)\n\n## Overview\n\nAudit logging captures two types of events:\n\n1. **Registry API Access** - All REST API requests to the Registry (`/api/*`, `/v0.1/*`)\n2. **MCP Server Access** - All MCP protocol requests proxied through the Gateway\n\nSensitive data such as authentication tokens, session cookies, and passwords are never logged. Credentials are masked to show only the last 6 characters as a hint for debugging.\n\n## Security and Privacy\n\n### Data That Is NOT Logged\n\nThe following sensitive data is explicitly excluded from audit logs:\n\n- **Authentication tokens** (Bearer tokens, JWT tokens)\n- **Session cookies** (Cookie header values)\n- **Passwords** (form fields, query parameters)\n- **API keys** (full values)\n- **Refresh tokens**\n- **Authorization header values**\n\n### Data Masking\n\nWhen credential hints are logged for debugging purposes, they are automatically masked:\n\n- Full token: `eyJhbGciOiJSUzI1NiIsInR5...` becomes `***zI1Ni`\n- Tokens shorter than 6 characters become `***`\n\nQuery parameters with sensitive names (token, password, key, secret, api_key, etc.) are automatically masked.\n\n## Event Schemas\n\n### Registry API Access Event\n\nLogged for every REST API request to the Registry.\n\n```json\n{\n \"timestamp\": \"2026-02-06T10:30:00.000Z\",\n \"log_type\": \"registry_api_access\",\n \"version\": \"1.0\",\n \"request_id\": \"abc123-def456-...\",\n \"correlation_id\": null,\n \"identity\": {\n \"username\": \"john.doe@example.com\",\n \"auth_method\": \"oauth2\",\n \"provider\": \"keycloak\",\n \"groups\": [\"mcp-registry-admin\", \"developers\"],\n \"scopes\": [\"registry-admins\"],\n \"is_admin\": true,\n \"credential_type\": \"session_cookie\",\n \"credential_hint\": \"***abc123\"\n },\n \"request\": {\n \"method\": \"POST\",\n \"path\": \"/api/servers\",\n \"query_params\": {},\n \"client_ip\": \"192.168.1.100\",\n \"forwarded_for\": \"10.0.0.1\",\n \"user_agent\": \"Mozilla/5.0...\",\n \"content_length\": 1024\n },\n \"response\": {\n \"status_code\": 201,\n \"duration_ms\": 45.32,\n \"content_length\": 512\n },\n \"action\": {\n \"operation\": \"create\",\n \"resource_type\": \"server\",\n \"resource_id\": \"my-mcp-server\",\n \"description\": \"Create new MCP server\"\n },\n \"authorization\": {\n \"decision\": \"ALLOW\",\n \"required_permission\": \"servers:write\",\n \"evaluated_scopes\": [\"registry-admins\"]\n }\n}\n```\n\n### MCP Server Access Event\n\nLogged for every MCP protocol request proxied through the Gateway.\n\n```json\n{\n \"timestamp\": \"2026-02-06T10:30:00.000Z\",\n \"log_type\": \"mcp_server_access\",\n \"version\": \"1.0\",\n \"request_id\": \"xyz789-...\",\n \"correlation_id\": null,\n \"identity\": {\n \"username\": \"ai-agent@example.com\",\n \"auth_method\": \"jwt_bearer\",\n \"provider\": \"keycloak\",\n \"groups\": [],\n \"scopes\": [\"mcp-server-cloudflare-docs\"],\n \"is_admin\": false,\n \"credential_type\": \"bearer_token\",\n \"credential_hint\": \"***def456\"\n },\n \"mcp_server\": {\n \"name\": \"cloudflare-docs\",\n \"path\": \"/cloudflare-docs\",\n \"version\": \"1.0.0\",\n \"proxy_target\": \"http://internal-mcp-server:8080/mcp\"\n },\n \"mcp_request\": {\n \"method\": \"tools/call\",\n \"tool_name\": \"search_docs\",\n \"resource_uri\": null,\n \"mcp_session_id\": \"session-123\",\n \"transport\": \"streamable-http\",\n \"jsonrpc_id\": \"1\"\n },\n \"mcp_response\": {\n \"status\": \"success\",\n \"duration_ms\": 123.45,\n \"error_code\": null,\n \"error_message\": null\n }\n}\n```\n\n## Data Fields Reference\n\n### Identity Fields\n\n| Field | Description |\n|-------|-------------|\n| `username` | Username or identifier of the requester |\n| `auth_method` | Authentication method: `oauth2`, `traditional`, `jwt_bearer`, `anonymous` |\n| `provider` | Identity provider: `cognito`, `entra_id`, `keycloak` |\n| `groups` | Groups the user belongs to |\n| `scopes` | OAuth scopes granted to the user |\n| `is_admin` | Whether the user has admin privileges |\n| `credential_type` | Type of credential: `session_cookie`, `bearer_token`, `none` |\n| `credential_hint` | Masked hint of the credential (last 6 chars only) |\n\n### Action Fields (Registry API only)\n\n| Field | Description |\n|-------|-------------|\n| `operation` | Operation type: `create`, `read`, `update`, `delete`, `list`, `toggle`, `rate`, `login`, `logout`, `search` |\n| `resource_type` | Resource type: `server`, `agent`, `auth`, `federation`, `health`, `search` |\n| `resource_id` | Identifier of the resource being acted upon |\n| `description` | Human-readable description of the action |\n\n### MCP Request Fields (MCP Access only)\n\n| Field | Description |\n|-------|-------------|\n| `method` | JSON-RPC method name: `tools/call`, `tools/list`, `resources/read`, `resources/list`, etc. |\n| `tool_name` | Name of the tool being called (for `tools/call` method) |\n| `resource_uri` | URI of the resource being accessed (for `resources/read` method) |\n| `mcp_session_id` | MCP session identifier |\n| `transport` | Transport protocol: `streamable-http`, `sse`, `stdio` |\n| `jsonrpc_id` | JSON-RPC request ID |\n\n## Data Retention\n\nAudit logs are automatically expired using MongoDB/DocumentDB TTL (Time-To-Live) indexes.\n\n### Default Retention\n\n- **Default retention period**: 7 days\n- **TTL index field**: `timestamp`\n\n### Configuring Retention\n\nSet the `AUDIT_LOG_MONGODB_TTL_DAYS` environment variable to customize retention:\n\n```bash\n# Keep logs for 30 days\nexport AUDIT_LOG_MONGODB_TTL_DAYS=30\n\n# Keep logs for 90 days (compliance requirement)\nexport AUDIT_LOG_MONGODB_TTL_DAYS=90\n```\n\nThe TTL index is created when running the DocumentDB initialization script:\n\n```bash\n./scripts/init-documentdb.sh\n```\n\n### Important Notes\n\n- TTL indexes run approximately once per minute in MongoDB/DocumentDB\n- Documents may persist slightly longer than the TTL value\n- Changing the TTL requires dropping and recreating the index with `--recreate` flag\n- For compliance requirements, consider also streaming logs to a long-term archive\n\n## Storage\n\n### MongoDB Collection\n\nAudit events are stored in the `audit_events_{namespace}` collection with the following indexes:\n\n| Index | Purpose |\n|-------|---------|\n| `request_id` (unique) | Fast lookup by request ID |\n| `identity.username` + `timestamp` | Query by user over time range |\n| `action.operation` + `timestamp` | Query by operation type over time range |\n| `action.resource_type` + `timestamp` | Query by resource type over time range |\n| `timestamp` (TTL) | Automatic expiration after configured days |\n\n### Storage Sizing\n\nTypical event sizes:\n- Registry API event: ~1-2 KB\n- MCP Server Access event: ~1-2 KB\n\nEstimated storage (without compression):\n- 1,000 requests/day for 7 days: ~14 MB\n- 10,000 requests/day for 30 days: ~600 MB\n- 100,000 requests/day for 90 days: ~18 GB\n\n## Viewing Audit Logs\n\n### Admin UI\n\nAdministrators can view audit logs in the Registry UI:\n\n1. Navigate to **Settings** > **Audit** > **Audit Logs**\n2. Select log stream: **Registry API** or **MCP Access**\n3. Apply filters (time range, username, operation, status)\n4. Click any row to view full event details\n5. Export filtered results as JSONL or CSV\n\n### API Access\n\nQuery audit events programmatically:\n\n```bash\n# Get recent Registry API events\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n \"https://registry.example.com/api/audit/events?stream=registry_api&limit=50\"\n\n# Get MCP access events for a specific user\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n \"https://registry.example.com/api/audit/events?stream=mcp_access&username=john.doe\"\n\n# Export events as JSONL\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n \"https://registry.example.com/api/audit/export?stream=registry_api&format=jsonl\"\n```\n\n### MongoDB/DocumentDB Direct Query\n\n```javascript\n// Find all events for a user in the last 24 hours\ndb.audit_events_default.find({\n \"identity.username\": \"john.doe@example.com\",\n \"timestamp\": { $gte: new Date(Date.now() - 24*60*60*1000) }\n}).sort({ timestamp: -1 })\n\n// Count events by operation type\ndb.audit_events_default.aggregate([\n { $match: { log_type: \"registry_api_access\" } },\n { $group: { _id: \"$action.operation\", count: { $sum: 1 } } },\n { $sort: { count: -1 } }\n])\n\n// Find failed MCP requests\ndb.audit_events_default.find({\n \"log_type\": \"mcp_server_access\",\n \"mcp_response.status\": \"error\"\n})\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AUDIT_LOG_ENABLED` | `true` | Enable/disable audit logging |\n| `AUDIT_LOG_MONGODB_TTL_DAYS` | `7` | Log retention period in days |\n\n### Non-Blocking Design\n\nAudit logging is designed to never impact request processing:\n\n- Logging happens asynchronously after the response is sent\n- Failures in audit logging are logged as warnings but don't fail requests\n- High-volume scenarios use batched writes (if enabled)\n\n## Compliance Considerations\n\n### SOC 2 / ISO 27001\n\nAudit logs support compliance requirements by capturing:\n\n- **Who**: User identity with auth method and provider\n- **What**: Operation performed with resource details\n- **When**: Precise UTC timestamp\n- **Where**: Client IP and forwarded-for headers\n- **Outcome**: Success/failure status with error details\n\n### GDPR\n\n- User identifiers (usernames) are logged for accountability\n- No PII beyond usernames is captured\n- Logs can be exported and deleted per data subject requests\n- TTL-based retention supports data minimization\n\n### Additional Recommendations\n\nFor production compliance deployments:\n\n1. Stream audit logs to a SIEM (Splunk, Datadog, etc.) for long-term retention\n2. Set up alerts for suspicious patterns (failed auths, privilege escalation)\n3. Regularly review admin actions in the audit log\n4. Document your retention policy and ensure TTL matches it\n\n## Troubleshooting\n\n### Logs Not Appearing\n\n1. Verify audit logging is enabled: `AUDIT_LOG_ENABLED=true`\n2. Check MongoDB connection: ensure the Registry can write to the database\n3. Look for warnings in Registry logs: `grep \"audit\" registry.log`\n\n### TTL Not Working\n\n1. Verify the TTL index exists: `db.audit_events_default.getIndexes()`\n2. Note that MongoDB TTL runs approximately every 60 seconds\n3. Documents may persist up to 60 seconds beyond their expiration time\n\n### Missing Events\n\n1. Check if the request completed (cancelled requests may not be logged)\n2. Verify the log stream filter matches the event type\n3. For MCP access, ensure the path is not an API path (starts with `/api/`)\n" }, { "path": "docs/auth-mgmt.md", "content": "# Authentication and User Management Guide\n\nThis guide describes how to manage groups, users, and M2M (machine-to-machine) service accounts in the MCP Gateway Registry, and how to generate JWT tokens for authentication.\n\n> **SECURITY WARNING**\n>\n> The examples in this document use placeholder credentials for demonstration purposes only.\n> **NEVER use these example values in production.**\n>\n> Always generate unique, secure credentials and store them in:\n> - AWS Secrets Manager (production)\n> - Environment variables (development)\n> - `.env` files (local only, never commit)\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Bootstrap State](#bootstrap-state)\n3. [Creating Groups](#creating-groups)\n4. [Creating Human Users](#creating-human-users)\n5. [Creating M2M Service Accounts](#creating-m2m-service-accounts)\n6. [Generating JWT Tokens](#generating-jwt-tokens)\n - [For Human Users (via UI)](#for-human-users-via-ui)\n - [For M2M Accounts (via generate_creds.sh)](#for-m2m-accounts-via-generate_credssh)\n7. [Provider-Specific Notes](#provider-specific-notes)\n\n---\n\n## Overview\n\nThe MCP Gateway Registry supports two identity providers:\n- **Keycloak** - Self-hosted identity provider with full automation support\n- **Microsoft Entra ID** - Enterprise Azure AD integration\n\nBoth providers use the same CLI interface (`registry_management.py`) for user and group management, with minor differences in configuration.\n\n---\n\n## Bootstrap State\n\nWhen the system is first deployed, it is bootstrapped with **minimal configuration**:\n\n### Initial Bootstrap (Both Providers)\n\n| Component | Description |\n|-----------|-------------|\n| **registry-admins** group | Administrative group with full registry access |\n| **Admin user** | Initial administrator account |\n| **Admin scopes** | `registry-admins` scope mapped to the admin group |\n\n### Keycloak Bootstrap\n\nFor Keycloak deployments, the `init-keycloak.sh` script automatically creates:\n- The `mcp-gateway` realm\n- `mcp-gateway-web` client (for web UI)\n- `mcp-gateway-m2m` client (for M2M authentication)\n- Initial admin user and `registry-admins` group\n\n### Entra ID Bootstrap\n\nFor Entra ID deployments:\n- The `registry-admins` group **must be created manually** in Azure Portal\n- The Group Object ID is required when running the DocumentDB initialization script:\n ```bash\n ./terraform/aws-ecs/scripts/run-documentdb-init.sh --entra-group-id \"your-group-object-id\"\n ```\n\nSee [Entra ID Setup Guide](./entra-id-setup.md) for detailed Entra ID configuration instructions.\n\n**All additional groups, users, and M2M accounts must be created as described below.**\n\n---\n\n## Creating Groups\n\nGroups control access to MCP servers and registry resources. Users and M2M accounts are assigned to groups to receive their permissions.\n\n### Prerequisites\n\nYou need an admin token to create groups. You can obtain one by:\n- **UI Method**: Log in to the registry web UI and click the **\"Get JWT Token\"** button in the top-left sidebar. Save the token to `api/.token`.\n- **M2M Method**: Create an M2M account with admin permissions and generate a token using `generate_creds.sh` (see [Generating JWT Tokens](#generating-jwt-tokens)).\n\n### Create a Group Definition File\n\nCreate a JSON file defining the group (e.g., `my-group.json`):\n\n```json\n{\n \"scope_name\": \"public-mcp-users\",\n \"description\": \"Users with access to public MCP servers\",\n \"servers\": [\n {\n \"server_name\": \"currenttime\",\n \"tools\": [\"get_current_time\"],\n \"access_level\": \"execute\"\n },\n {\n \"server_name\": \"mcpgw\",\n \"tools\": [\"*\"],\n \"access_level\": \"execute\"\n }\n ],\n \"create_in_idp\": true\n}\n```\n\n**Key fields:**\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `scope_name` | Yes | Unique identifier for the group/scope |\n| `description` | Yes | Human-readable description |\n| `servers` | Yes | List of server access configurations |\n| `create_in_idp` | No | If `true`, creates the group in the identity provider (Keycloak/Entra ID) |\n\n### Import the Group\n\n```bash\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n import-group --file my-group.json\n```\n\n### Example Group Definitions\n\nSee the [cli/examples/](../cli/examples/) directory for sample group definitions:\n- [public-mcp-users.json](../cli/examples/public-mcp-users.json) - Public access group with access to context7, cloudflare-docs servers and flight-booking agent\n- `currenttime-users.json` - Access to currenttime server only\n\n### Bootstrap Admin Scope\n\nThe `registry-admins` scope is automatically loaded during database initialization from [scripts/registry-admins.json](../scripts/registry-admins.json). This file defines full administrative access:\n\n```json\n{\n \"_id\": \"registry-admins\",\n \"group_mappings\": [\"registry-admins\"],\n \"server_access\": [\n {\n \"server\": \"*\",\n \"methods\": [\"all\"],\n \"tools\": [\"all\"]\n }\n ]\n}\n```\n\nThis is loaded by the database initialization scripts:\n- **Local (MongoDB CE)**: `docker compose up mongodb-init` runs `scripts/init-mongodb-ce.py`\n- **Production (DocumentDB)**: `./terraform/aws-ecs/scripts/run-documentdb-init.sh` runs `scripts/init-documentdb-indexes.py`\n- **Entra ID**: `./terraform/aws-ecs/scripts/run-documentdb-init.sh --entra-group-id \"your-group-object-id\"`\n\nFor Entra ID, the `--entra-group-id` parameter adds the Entra ID Group Object ID to the `group_mappings` array so that members of that Azure AD group receive admin permissions.\n\n---\n\n## Creating Human Users\n\nHuman users can log in via the web UI using OAuth2 authentication (Keycloak or Entra ID).\n\n### Create a Human User\n\n```bash\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n user-create-human \\\n --username jsmith \\\n --email jsmith@example.com \\\n --first-name John \\\n --last-name Smith \\\n --groups public-mcp-users \\\n --password \"SecurePassword123!\"\n```\n\n**Parameters:**\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `--username` | Yes | Unique username for the user |\n| `--email` | Yes | Email address |\n| `--first-name` | Yes | First name |\n| `--last-name` | Yes | Last name |\n| `--groups` | Yes | Comma-separated list of groups to assign |\n| `--password` | Yes | Initial password (user should change on first login) |\n\n### Multiple Groups\n\nTo assign a user to multiple groups:\n\n```bash\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n user-create-human \\\n --username analyst \\\n --email analyst@example.com \\\n --first-name Data \\\n --last-name Analyst \\\n --groups \"public-mcp-users,analytics-team\" \\\n --password \"SecurePassword123!\"\n```\n\n---\n\n## Creating M2M Service Accounts\n\nM2M (machine-to-machine) accounts are used for programmatic API access by AI coding assistants, agents, and automated systems.\n\n### Create an M2M Service Account\n\n```bash\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n user-create-m2m \\\n --name my-ai-agent \\\n --groups public-mcp-users \\\n --description \"AI coding assistant service account\"\n```\n\n**Output:**\n\n```\nClient ID: my-ai-agent\nClient Secret: sqFaOkF8un1tAfKXjlgm2xjGQBfLlNS3\nGroups: public-mcp-users\n\nIMPORTANT: Save the client secret securely - it cannot be retrieved later.\n```\n\n**Parameters:**\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `--name` | Yes | Unique name for the M2M account (becomes the Client ID) |\n| `--groups` | Yes | Comma-separated list of groups to assign |\n| `--description` | No | Description of the service account's purpose |\n\n### Save the Credentials\n\n**The client secret is only displayed once.** Save it immediately to a secure location:\n\n```bash\n# Create an agent configuration file for use with generate_creds.sh\ncat > .oauth-tokens/agent-my-ai-agent.json << 'EOF'\n{\n \"client_id\": \"my-ai-agent\",\n \"client_secret\": \"sqFaOkF8un1tAfKXjlgm2xjGQBfLlNS3\",\n \"keycloak_url\": \"https://kc.us-east-1.example.com\",\n \"keycloak_realm\": \"mcp-gateway\",\n \"auth_provider\": \"keycloak\"\n}\nEOF\n```\n\nFor Entra ID, add the identity to `.oauth-tokens/entra-identities.json`:\n\n```json\n[\n {\n \"identity_name\": \"my-ai-agent\",\n \"tenant_id\": \"your-tenant-id\",\n \"client_id\": \"client-id-from-output\",\n \"client_secret\": \"client-secret-from-output\",\n \"scope\": \"api://your-app-client-id/.default\"\n }\n]\n```\n\n---\n\n## Generating JWT Tokens\n\n### For Human Users (via UI)\n\nHuman users generate JWT tokens through the MCP Gateway Registry web interface:\n\n1. **Log in** to the registry at `https://registry.us-east-1.example.com`\n2. Click the **\"Get JWT Token\"** button in the top-left sidebar\n3. **Copy the generated token**\n\nThese self-signed tokens:\n- Are signed with HS256 using the server's `SECRET_KEY`\n- Include the user's groups and scopes\n- Can be used for programmatic API access\n- Have a configurable expiration time\n\n**Using the token:**\n\n```bash\n# Save to a token file\necho '{\"access_token\": \"eyJhbGciOi...\"}' > api/.token\n\n# Use with registry_management.py\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://registry.us-east-1.example.com \\\n list\n```\n\n### For M2M Accounts (via generate_creds.sh)\n\nM2M accounts generate tokens using the OAuth2 client credentials flow via the `generate_creds.sh` script.\n\n#### Step 1: Configure the Agent\n\nCreate an agent configuration file in `.oauth-tokens/`:\n\n**For Keycloak:**\n\n```json\n{\n \"client_id\": \"my-ai-agent\",\n \"client_secret\": \"sqFaOkF8un1tAfKXjlgm2xjGQBfLlNS3\",\n \"keycloak_url\": \"https://kc.us-east-1.example.com\",\n \"keycloak_realm\": \"mcp-gateway\",\n \"auth_provider\": \"keycloak\"\n}\n```\n\nSave as `.oauth-tokens/agent-my-ai-agent.json`\n\n**For Entra ID:**\n\nEdit `.oauth-tokens/entra-identities.json`:\n\n```json\n[\n {\n \"identity_name\": \"my-ai-agent\",\n \"tenant_id\": \"6e6ee81b-6bf3-495d-a7fc-d363a551f765\",\n \"client_id\": \"your-client-id\",\n \"client_secret\": \"your-client-secret\",\n \"scope\": \"api://1bd17ba1-aad3-447f-be0b-26f8f9ee859f/.default\"\n }\n]\n```\n\n#### Step 2: Generate the Token\n\n**For Keycloak:**\n\n```bash\n./credentials-provider/generate_creds.sh \\\n -a keycloak \\\n -k https://kc.us-east-1.example.com\n```\n\n**For Entra ID:**\n\n```bash\n./credentials-provider/generate_creds.sh \\\n -a entra \\\n -i .oauth-tokens/entra-identities.json\n```\n\n#### Step 3: Use the Generated Token\n\nThe script saves tokens to `.oauth-tokens/agent--token.json`:\n\n```bash\n# List servers using the generated token\nuv run python api/registry_management.py \\\n --token-file .oauth-tokens/agent-my-ai-agent-token.json \\\n --registry-url https://registry.us-east-1.example.com \\\n list\n```\n\n### generate_creds.sh Options\n\n```\n./credentials-provider/generate_creds.sh [OPTIONS]\n\nOPTIONS:\n --auth-provider, -a PROVIDER Auth provider: 'keycloak' or 'entra' (required)\n --keycloak-url, -k URL Keycloak server URL (required for keycloak)\n --keycloak-realm, -r REALM Keycloak realm name (default: mcp-gateway)\n --entra-tenant-id TENANT_ID Entra tenant ID\n --entra-client-id CLIENT_ID Entra client ID\n --entra-client-secret SECRET Entra client secret\n --entra-login-url URL Entra login base URL (default: https://login.microsoftonline.com)\n --identities-file, -i FILE Custom path to identities JSON file (for entra)\n --verbose, -v Enable verbose debug logging\n --help, -h Show help message\n\nEXAMPLES:\n # Keycloak\n ./generate_creds.sh -a keycloak -k https://kc.example.com\n\n # Entra ID with identities file\n ./generate_creds.sh -a entra -i .oauth-tokens/entra-identities.json\n\n # Keycloak with verbose output\n ./generate_creds.sh -a keycloak -k https://kc.example.com -v\n```\n\n### Manual Token Generation (curl)\n\nYou can also generate tokens directly using curl:\n\n**Keycloak:**\n\n```bash\ncurl -s -X POST \"https://kc.us-east-1.example.com/realms/mcp-gateway/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id=my-ai-agent\" \\\n -d \"client_secret=sqFaOkF8un1tAfKXjlgm2xjGQBfLlNS3\" \\\n -d \"grant_type=client_credentials\"\n```\n\n**Entra ID:**\n\n```bash\ncurl -s -X POST \"https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id={M2M_CLIENT_ID}\" \\\n -d \"client_secret={M2M_CLIENT_SECRET}\" \\\n -d \"scope=api://{APP_CLIENT_ID}/.default\" \\\n -d \"grant_type=client_credentials\"\n```\n\n---\n\n## Provider-Specific Notes\n\n### Keycloak\n\n- Groups are identified by **name** (e.g., `registry-admins`)\n- M2M accounts are created as Keycloak clients with service accounts\n- Token lifetime is configurable in Keycloak realm settings (default: 5 minutes)\n- Supports automatic group and user creation via API\n\n### Entra ID\n\n- Groups are identified by **Object ID** (UUID, e.g., `16c7e67e-e8ae-498c-ba2e-0593c0159e43`)\n- M2M accounts are Azure App Registrations with client credentials\n- Token lifetime is typically 1 hour\n- Groups must be created manually in Azure Portal before use\n- Group Object IDs are required for scope mappings in `scopes.yml`\n\n### Token Comparison\n\n| Aspect | Human User Token | M2M Token |\n|--------|------------------|-----------|\n| **Generation** | UI \"Get JWT Token\" button | `generate_creds.sh` or curl |\n| **Algorithm** | HS256 (self-signed) | RS256 (IdP-signed) |\n| **Validation** | Server SECRET_KEY | JWKS from IdP |\n| **Use Case** | Interactive/programmatic access | Automated systems, AI agents |\n| **Refresh** | Generate new via UI | Use client credentials flow |\n\n---\n\n## See Also\n\n- [Entra ID Setup Guide](./entra-id-setup.md) - Complete Entra ID configuration\n- [Complete Setup Guide](./complete-setup-guide.md) - Initial system setup\n- [Terraform AWS ECS README](../terraform/aws-ecs/README.md) - Production deployment\n" }, { "path": "docs/auth.md", "content": "# Authentication and Authorization\n\nThe MCP Gateway Registry provides authentication and authorization using industry-standard OAuth 2.0 flows with fine-grained access control.\n\n## Overview\n\nThe authentication system supports three distinct identity scenarios:\n\n1. **Human Users** - Interactive users accessing the Registry UI via browser\n2. **Programmatic Access** - Self-signed JWT tokens for CLI tools and AI coding assistants\n3. **Workload Identity (M2M)** - Service accounts for AI agents and automated systems\n\n## Related Documentation\n\n### Design Documents\n\nFor architectural details and design decisions:\n\n- [Authentication Design](design/authentication-design.md) - Detailed auth flows for human users, programmatic access, and M2M workloads\n- [Multi-Provider IdP Support](design/idp-provider-support.md) - Architecture for supporting multiple identity providers (Keycloak, Entra ID)\n\n### Configuration Guides\n\nFor setup and configuration:\n\n- [Scopes Management](scopes-mgmt.md) - Scope configuration file format and fine-grained access control\n- [Authentication Management](auth-mgmt.md) - Managing users, groups, and scopes via CLI\n- [Microsoft Entra ID Setup](entra-id-setup.md) - Entra ID-specific setup and configuration\n- [Complete Setup Guide](complete-setup-guide.md) - End-to-end deployment instructions\n\n---\n\n## Authentication Architecture\n\n### Identity Types\n\nThe system distinguishes between three types of identities, each with different authentication flows:\n\n| Identity Type | Use Case | Auth Method | Token Signing | Lifetime |\n|--------------|----------|-------------|---------------|----------|\n| Human Users | Browser UI | OAuth2 Authorization Code | RS256 (IdP) | Session-based |\n| Programmatic | CLI, AI assistants | Self-signed JWT | HS256 (SECRET_KEY) | 8 hours |\n| M2M Workloads | AI agents, automation | OAuth2 Client Credentials | RS256 (IdP) | 1 hour |\n\n### Supported Identity Providers\n\nThe registry supports multiple identity providers through a pluggable architecture:\n\n- **Keycloak** - Open-source identity management\n- **Microsoft Entra ID** - Enterprise Azure AD integration\n\nProvider selection is controlled by the `AUTH_PROVIDER` environment variable:\n\n```bash\nAUTH_PROVIDER=keycloak # Use Keycloak (default)\nAUTH_PROVIDER=entra # Use Microsoft Entra ID\n```\n\n---\n\n## High-Level Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant User as User/Developer\n participant Agent as AI Agent\n participant Auth as Keycloak/Entra ID
(Identity Provider)\n participant Gateway as NGINX Gateway\n participant AuthServer as Auth Server\n participant Registry as Registry API\n\n Note over User,Registry: Human User Flow (Browser)\n\n User->>Gateway: 1. Access Registry UI\n Gateway->>Auth: 2. Redirect to IdP login\n Auth->>User: 3. Login page\n User->>Auth: 4. Authenticate\n Auth->>Gateway: 5. Authorization code\n Gateway->>AuthServer: 6. Exchange code for tokens\n AuthServer->>Auth: 7. Validate & get user info\n AuthServer->>User: 8. Set session cookie\n User->>Registry: 9. Access API with session\n\n Note over User,Registry: Programmatic Access (JWT Token)\n\n User->>AuthServer: 10. Request JWT token (via UI)\n AuthServer->>User: 11. Self-signed JWT (HS256)\n User->>Agent: 12. Configure agent with token\n Agent->>Gateway: 13. API request with Bearer token\n Gateway->>AuthServer: 14. Validate token (/validate)\n AuthServer->>Gateway: 15. User context + permissions\n Gateway->>Registry: 16. Proxied request\n```\n\n---\n\n## Authorization Model\n\n### Scope-Based Access Control\n\nAuthorization is based on **scopes** that define:\n\n1. **Server Access** - Which MCP servers and methods users can access\n2. **Agent Actions** - Which agent operations users can perform\n3. **UI Permissions** - Which UI features are available\n\n### Group-to-Scope Mapping\n\nUser permissions are determined by mapping IdP groups to scopes stored in MongoDB/DocumentDB:\n\n```mermaid\nflowchart LR\n subgraph IdP[\"Identity Provider\"]\n KC[\"Keycloak Group
registry-admins\"]\n EA[\"Entra ID Group
4c46ec66-a4f7-...\"]\n end\n\n subgraph DB[\"MongoDB/DocumentDB\"]\n SM[\"Scope: registry-admins
group_mappings:
- registry-admins
- 4c46ec66-a4f7-...\"]\n end\n\n subgraph Perms[\"Permissions\"]\n SA[\"server_access:
server: *
methods: [all]
tools: [all]\"]\n UI[\"ui_permissions:
list_agents: [all]
publish_agent: [all]
...\"]\n end\n\n KC --> SM\n EA --> SM\n SM --> SA\n SM --> UI\n```\n\n### Scope Configuration\n\nScopes are defined in JSON files and loaded into MongoDB. See [Scopes Management](scopes-mgmt.md) for the complete file format.\n\n**Example: Admin Scope**\n\n```json\n{\n \"_id\": \"registry-admins\",\n \"group_mappings\": [\"registry-admins\", \"4c46ec66-a4f7-4b62-9095-b7958662f4b6\"],\n \"server_access\": [\n {\"server\": \"*\", \"methods\": [\"all\"], \"tools\": [\"all\"]}\n ],\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"publish_agent\": [\"all\"],\n \"list_service\": [\"all\"],\n \"toggle_service\": [\"all\"]\n }\n}\n```\n\n**Example: Limited User Scope**\n\n```json\n{\n \"_id\": \"public-mcp-users\",\n \"group_mappings\": [\"public-mcp-users\", \"5f605d68-06bc-4208-b992-bb378eee12c5\"],\n \"server_access\": [\n {\"server\": \"context7\", \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"], \"tools\": [\"*\"]}\n ],\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n }\n}\n```\n\n---\n\n## Token Validation Flow\n\nAll API requests are validated by the auth server through NGINX's `auth_request` directive:\n\n```mermaid\nsequenceDiagram\n participant Client as CLI/Agent\n participant NGINX as NGINX Gateway\n participant Auth as Auth Server\n participant IdP as Identity Provider\n participant API as Registry API\n\n Client->>NGINX: 1. API Request
Authorization: Bearer \n NGINX->>Auth: 2. auth_request /validate\n\n alt Self-Signed Token (iss: mcp-auth-server)\n Auth->>Auth: 3a. Validate with SECRET_KEY (HS256)\n else IdP Token (iss: Keycloak/Entra)\n Auth->>IdP: 3b. Fetch JWKS\n IdP-->>Auth: Public keys\n Auth->>Auth: 3c. Validate signature (RS256)\n end\n\n Auth->>Auth: 4. Extract groups from token\n Auth->>Auth: 5. Map groups to scopes\n Auth->>Auth: 6. Check server/tool access\n\n alt Access Granted\n Auth-->>NGINX: 7a. 200 OK + X-User headers\n NGINX->>API: 8. Proxy request\n API-->>Client: 9. Response\n else Access Denied\n Auth-->>NGINX: 7b. 403 Forbidden\n NGINX-->>Client: 403 Forbidden\n end\n```\n\n---\n\n## Key Security Layers\n\n### Layer 1: Gateway Authentication\n\nThe NGINX gateway validates all incoming requests:\n\n- Extracts JWT from `Authorization` header\n- Calls auth server `/validate` endpoint\n- Sets user context headers for downstream services\n\n### Layer 2: Token Validation\n\nThe auth server supports multiple token types:\n\n| Token Type | Issuer | Algorithm | Validation Method |\n|------------|--------|-----------|-------------------|\n| Self-signed | `mcp-auth-server` | HS256 | SECRET_KEY |\n| Keycloak | `{keycloak_url}/realms/{realm}` | RS256 | JWKS endpoint |\n| Entra ID | `https://sts.windows.net/{tenant}/` | RS256 | JWKS endpoint |\n\n### Layer 3: Scope-Based Authorization\n\nAfter token validation, the auth server:\n\n1. Extracts `groups` claim from token\n2. Queries MongoDB for matching scopes (via `group_mappings`)\n3. Validates requested server/method/tool against `server_access` rules\n4. Returns user context with permissions\n\n---\n\n## Permission Types\n\n### MCP Server Permissions\n\nControl access to MCP servers and their tools:\n\n| Permission | Description |\n|------------|-------------|\n| `server` | Server name or `*` for all |\n| `methods` | Allowed MCP methods (initialize, tools/list, tools/call, etc.) |\n| `tools` | Allowed tool names or `*` for all |\n\n### Agent Permissions\n\nControl operations on A2A agents:\n\n| Permission | Description |\n|------------|-------------|\n| `list_agents` | View agents in listings |\n| `get_agent` | View agent details |\n| `publish_agent` | Register new agents |\n| `modify_agent` | Update existing agents |\n| `delete_agent` | Remove agents |\n\n### UI Permissions\n\nControl access to UI features:\n\n| Permission | Description |\n|------------|-------------|\n| `list_service` | View MCP servers in dashboard |\n| `register_service` | Register new MCP servers |\n| `health_check_service` | Run health checks |\n| `toggle_service` | Enable/disable servers |\n| `modify_service` | Edit server configurations |\n\n---\n\n## Entra ID Group Mapping\n\nWhen using Microsoft Entra ID, group identifiers are Object IDs (GUIDs), not names:\n\n```json\n{\n \"group_mappings\": [\n \"public-mcp-users\",\n \"5f605d68-06bc-4208-b992-bb378eee12c5\"\n ]\n}\n```\n\nThis allows the same scope to work with both Keycloak (group names) and Entra ID (Object IDs).\n\n**Finding Entra ID Group Object IDs:**\n\n1. Azure Portal > Azure Active Directory > Groups\n2. Select the group\n3. Copy the \"Object ID\" from the Overview page\n\n---\n\n## Session Management\n\n### Human User Sessions\n\nBrowser sessions use signed cookies:\n\n- Created after successful OAuth2 login\n- Contains: username, groups, provider, scopes\n- Validated using `SECRET_KEY` (HS256)\n- Default expiry: 8 hours (configurable)\n\n### Programmatic Tokens\n\nSelf-signed JWT tokens for CLI/API access:\n\n- Generated via \"Get JWT Token\" in UI\n- Contains: username, groups, scopes, permissions\n- Signed with `SECRET_KEY` (HS256)\n- Default expiry: 8 hours\n\n### M2M Tokens\n\nService account tokens from IdP:\n\n- Obtained via OAuth2 Client Credentials flow\n- Signed by IdP (RS256)\n- Default expiry: 1 hour\n- Must be refreshed periodically\n\n---\n\n## Security Best Practices\n\n1. **Use HTTPS** - All production deployments should use TLS\n2. **Rotate Secrets** - Regularly rotate SECRET_KEY and client secrets\n3. **Least Privilege** - Assign minimal required permissions to users/agents\n4. **Audit Logging** - Monitor authentication events and access patterns\n5. **Token Expiry** - Use short-lived tokens and implement refresh flows\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**Token validation fails:**\n- Check token issuer matches expected provider\n- Verify JWKS endpoint is accessible\n- Ensure SECRET_KEY matches between auth server instances\n\n**Permission denied:**\n- Verify user's groups in IdP\n- Check group_mappings in scope configuration\n- Ensure scope includes required server/method access\n\n**Group not recognized:**\n- For Entra ID: Use Object ID, not group name\n- Verify group exists in group_mappings array\n- Reload scopes after configuration changes\n\n### Debug Endpoints\n\n```bash\n# Check user context\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n https://registry.example.com/api/debug/user-context\n\n# List available scopes\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n https://registry.example.com/api/scopes\n```\n\n---\n\n## Server Authentication Credentials\n\nThe MCP Gateway Registry supports backend server authentication, allowing MCP servers that require their own authentication (API keys, bearer tokens, etc.) to be registered with encrypted credentials.\n\n### Overview\n\nWhen an MCP server requires authentication, you can provide the credentials during registration. The registry:\n\n1. **Encrypts** the credential using Fernet symmetric encryption\n2. **Stores** the encrypted credential in MongoDB/DocumentDB\n3. **Automatically decrypts** and uses the credential for:\n - Health checks\n - Tool discovery and fetching\n - MCP client connections\n\n### Supported Authentication Schemes\n\n| Scheme | Description | Example Use Case |\n|--------|-------------|------------------|\n| `none` | No authentication required | Public MCP servers |\n| `bearer` | Bearer token in `Authorization` header | OAuth2-protected services |\n| `api_key` | API key with custom header name | Services requiring API keys (e.g., `X-API-Key`, `CONTEXT7_API_KEY`) |\n\n### Credential Encryption\n\nAll credentials are encrypted before storage using the Fernet encryption scheme:\n\n- **Algorithm**: Fernet (symmetric encryption based on AES-128-CBC)\n- **Key**: Derived from `ENCRYPTION_KEY` environment variable\n- **Storage**: Encrypted credential stored as `auth_credential_encrypted` in MongoDB\n- **Decryption**: Automatic during health checks and MCP client initialization\n\n**Configuration** (`.env` file):\n```bash\n# Encryption key for server credentials (base64-encoded Fernet key)\nENCRYPTION_KEY=your-base64-encoded-fernet-key-here\n\n# Generate a new key with: python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"\n```\n\n### Registering Servers with Authentication\n\n#### Method 1: Registry UI\n\n1. Navigate to **Register Server** in the Registry UI\n2. Fill in server details (name, path, proxy URL, etc.)\n3. Select **Authentication Scheme**:\n - `none` - No authentication\n - `bearer` - Bearer token\n - `api_key` - API key\n4. If `bearer` or `api_key`:\n - Enter the **credential** (API key or bearer token)\n - For `api_key`: Specify the **header name** (e.g., `CONTEXT7_API_KEY`, `X-API-Key`)\n5. Click **Register**\n\n![Server Registration with Authentication Scheme](img/auth-scheme.gif)\n\nThe credential is automatically encrypted and stored securely.\n\n#### Method 2: REST API\n\n**Register server with bearer token:**\n\n```bash\ncurl -X POST https://registry.example.com/api/servers/register \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -F \"server_name=My Protected Server\" \\\n -F \"path=/my-server\" \\\n -F \"proxy_pass_url=http://backend:8000/\" \\\n -F \"auth_scheme=bearer\" \\\n -F \"auth_credential=my-bearer-token-value\" \\\n -F \"description=A server requiring bearer auth\"\n```\n\n**Register server with API key:**\n\n```bash\ncurl -X POST https://registry.example.com/api/servers/register \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -F \"server_name=Context7\" \\\n -F \"path=/context7\" \\\n -F \"proxy_pass_url=http://context7:8000/\" \\\n -F \"auth_scheme=api_key\" \\\n -F \"auth_credential=ctx7sk-6dd75bd4-80ef-486e-99ef-b5493df4e578\" \\\n -F \"auth_header_name=CONTEXT7_API_KEY\" \\\n -F \"description=Context7 LLM context service\"\n```\n\n**Response:**\n```json\n{\n \"message\": \"Server registered successfully\",\n \"path\": \"/context7\",\n \"server_name\": \"Context7\",\n \"auth_scheme\": \"api_key\",\n \"auth_header_name\": \"CONTEXT7_API_KEY\",\n \"auth_credential_encrypted\": true\n}\n```\n\n#### Method 3: CLI Tool (`registry_management.py`)\n\n**Register server with credentials:**\n\n```bash\n# Set up authentication\nexport REGISTRY_URL=https://registry.example.com\nexport REGISTRY_TOKEN=$(cat .token)\n\n# Register with API key\npython3 api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --token $REGISTRY_TOKEN \\\n server-register \\\n --name \"Context7\" \\\n --path \"/context7\" \\\n --proxy-pass-url \"http://context7:8000/\" \\\n --auth-scheme api_key \\\n --auth-credential \"ctx7sk-6dd75bd4-80ef-486e-99ef-b5493df4e578\" \\\n --auth-header-name \"CONTEXT7_API_KEY\" \\\n --description \"Context7 LLM context service\"\n\n# Register with bearer token\npython3 api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --token $REGISTRY_TOKEN \\\n server-register \\\n --name \"Cloudflare API\" \\\n --path \"/cloudflare-api\" \\\n --proxy-pass-url \"http://cloudflare-mcp:8000/\" \\\n --auth-scheme bearer \\\n --auth-credential \"my-cloudflare-bearer-token\" \\\n --description \"Cloudflare MCP Server\"\n```\n\n### Updating Server Credentials\n\nCredentials can be updated without re-registering the entire server.\n\n#### Method 1: REST API\n\n**Update credential endpoint:**\n\n```bash\ncurl -X PUT https://registry.example.com/api/servers/context7/credentials \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"auth_scheme\": \"api_key\",\n \"auth_credential\": \"new-api-key-value\",\n \"auth_header_name\": \"CONTEXT7_API_KEY\"\n }'\n```\n\n**Switch to bearer token:**\n\n```bash\ncurl -X PUT https://registry.example.com/api/servers/my-server/credentials \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"auth_scheme\": \"bearer\",\n \"auth_credential\": \"new-bearer-token\"\n }'\n```\n\n**Remove authentication:**\n\n```bash\ncurl -X PUT https://registry.example.com/api/servers/my-server/credentials \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"auth_scheme\": \"none\"\n }'\n```\n\n**Response:**\n```json\n{\n \"message\": \"Auth credentials updated successfully\",\n \"path\": \"/context7\",\n \"auth_scheme\": \"api_key\",\n \"auth_header_name\": \"CONTEXT7_API_KEY\"\n}\n```\n\n#### Method 2: CLI Tool\n\n**Update server credential:**\n\n```bash\npython3 api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --token $REGISTRY_TOKEN \\\n server-update-credential \\\n --path \"/context7\" \\\n --auth-scheme api_key \\\n --credential \"new-api-key-value\" \\\n --auth-header-name \"CONTEXT7_API_KEY\"\n```\n\n**Update to bearer token:**\n\n```bash\npython3 api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --token $REGISTRY_TOKEN \\\n server-update-credential \\\n --path \"/cloudflare-api\" \\\n --auth-scheme bearer \\\n --credential \"new-bearer-token-value\"\n```\n\n**Remove authentication:**\n\n```bash\npython3 api/registry_management.py \\\n --registry-url $REGISTRY_URL \\\n --token $REGISTRY_TOKEN \\\n server-update-credential \\\n --path \"/my-server\" \\\n --auth-scheme none\n```\n\n**Output:**\n```\nSuccessfully updated credentials for server '/context7'\nNew auth scheme: api_key\nAuth header name: CONTEXT7_API_KEY\n```\n\n### How Credentials Are Used\n\n#### 1. Health Checks\n\nWhen the health check service performs periodic checks, it:\n\n1. Retrieves the server's `auth_credential_encrypted` from MongoDB\n2. Decrypts the credential using the `ENCRYPTION_KEY`\n3. Includes the appropriate header in the MCP initialize request:\n - Bearer: `Authorization: Bearer `\n - API Key: `: `\n\n**Example health check with auth:**\n\n```python\n# Health check service automatically decrypts and uses credentials\nheaders = {}\nif server.auth_scheme == \"bearer\":\n headers[\"Authorization\"] = f\"Bearer {decrypt_credential(server.auth_credential_encrypted)}\"\nelif server.auth_scheme == \"api_key\":\n header_name = server.auth_header_name or \"X-API-Key\"\n headers[header_name] = decrypt_credential(server.auth_credential_encrypted)\n\n# MCP initialize request with auth headers\nresponse = await mcp_client.initialize(url=server.proxy_pass_url, headers=headers)\n```\n\n#### 2. Tool Discovery\n\nWhen fetching tools from a server:\n\n1. Registry decrypts the credential\n2. Includes auth headers in the MCP `tools/list` request\n3. Stores the fetched tools in the database\n\n#### 3. MCP Client Connections\n\nWhen AI coding assistants connect to a server through the gateway:\n\n1. User provides gateway auth token (`X-Authorization` header)\n2. Gateway validates user permissions\n3. Gateway retrieves and decrypts server credential\n4. Gateway proxies the request with the server's auth header\n\n**Example MCP client configuration:**\n\n```json\n{\n \"mcpServers\": {\n \"context7\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcpgateway.ddns.net/context7/mcp\",\n \"disabled\": false,\n \"headers\": {\n \"X-Authorization\": \"Bearer \",\n \"CONTEXT7_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Security Considerations\n\n1. **Encryption at Rest**:\n - All credentials are encrypted in MongoDB using Fernet\n - Never store plaintext credentials in the database\n\n2. **Key Management**:\n - Store `ENCRYPTION_KEY` securely (AWS Secrets Manager, Vault, etc.)\n - Never commit encryption keys to version control\n - Rotate encryption keys periodically\n\n3. **Access Control**:\n - Only users with `register_service` or `modify_service` permissions can set/update credentials\n - Credentials are never returned in API responses (only `auth_credential_encrypted` flag)\n\n4. **Audit Logging**:\n - All credential updates are logged with username and timestamp\n - Review audit logs regularly for unauthorized changes\n\n### Best Practices\n\n1. **Use Environment-Specific Credentials**:\n - Development: Use test credentials with limited access\n - Production: Use production credentials with full access\n\n2. **Rotate Credentials Regularly**:\n - Use the credential update API/CLI to rotate without downtime\n - Update credentials before they expire\n\n3. **Monitor Health Checks**:\n - Watch for \"auth-expired\" health status\n - Set up alerts for authentication failures\n\n4. **Document Custom Headers**:\n - For `api_key` auth, document the required header name\n - Ensure consistency across environments\n\n### Troubleshooting\n\n**Credential Update Fails:**\n```bash\n# Verify server exists\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n https://registry.example.com/api/servers\n\n# Check auth scheme is valid\n# Valid values: none, bearer, api_key\n```\n\n**Health Check Shows \"auth-expired\":**\n```bash\n# Update the credential\npython3 api/registry_management.py \\\n server-update-credential \\\n --path \"/my-server\" \\\n --auth-scheme bearer \\\n --credential \"new-valid-token\"\n\n# Force immediate health check\ncurl -X POST -H \"Authorization: Bearer $TOKEN\" \\\n https://registry.example.com/api/servers/my-server/refresh\n```\n\n**MCP Client Connection Fails:**\n- Verify both gateway auth (`X-Authorization`) and server auth headers are present\n- Check credential hasn't expired\n- Ensure `auth_header_name` matches server's expectation\n\n---\n\n## Additional Resources\n\n- [Authentication Design](design/authentication-design.md) - Detailed auth flow diagrams\n- [IdP Provider Support](design/idp-provider-support.md) - Provider architecture\n- [Scopes Management](scopes-mgmt.md) - Scope file format reference\n- [Auth Management](auth-mgmt.md) - CLI operations guide\n- [AI Coding Assistants Setup](ai-coding-assistants-setup.md) - Complete setup with backend auth examples\n" }, { "path": "docs/auth0-m2m-setup.md", "content": "# Auth0 M2M Client Management\n\nThis guide explains how to manage Auth0 Machine-to-Machine (M2M) client applications and their group mappings in the MCP Gateway Registry.\n\n## Overview\n\nAuth0 M2M tokens do not include groups in the JWT payload (similar to Okta). The MCP Gateway Registry solves this by:\n\n1. **Syncing M2M clients** from Auth0 Management API to MongoDB\n2. **Storing group mappings** in the `idp_m2m_clients` collection\n3. **Enriching tokens** with groups during authentication\n\nThis enables group-based authorization for Auth0 M2M clients without modifying Auth0 configuration.\n\n## Architecture\n\n### Collections\n\n**`auth0_m2m_clients`** (Auth0-specific):\n- Stores Auth0 M2M application metadata\n- Synced via Auth0 Management API\n- Used for listing and managing Auth0 clients\n\n**`idp_m2m_clients`** (Provider-agnostic):\n- Generic collection for all IdP providers (Keycloak, Okta, Entra, Auth0)\n- Used by auth-server for groups enrichment\n- Schema: `{client_id, name, groups, provider, enabled, ...}`\n\n### Flow\n\n```\n┌─────────────────┐\n│ Auth0 M2M App │\n│ (no groups) │\n└────────┬────────┘\n │ 1. M2M Token (JWT)\n │ - iss: https://domain.auth0.com/\n │ - sub: client_id@clients\n │ - aud: https://domain.auth0.com/api/v2/\n │ - groups: [] (empty)\n │\n v\n┌─────────────────────────┐\n│ Auth Server │\n│ (validate_token) │\n└────────┬────────────────┘\n │ 2. Groups enrichment\n │ - Query: db.idp_m2m_clients.find_one({client_id})\n │ - Return: [\"registry-admins\"]\n │\n v\n┌─────────────────────────┐\n│ Authorization │\n│ (with groups) │\n└─────────────────────────┘\n```\n\n## Prerequisites\n\n### 1. Auth0 M2M Application\n\nCreate a Machine-to-Machine application in Auth0:\n\n1. Navigate to **Applications** > **Applications** > **Create Application**\n2. Select **Machine to Machine Applications**\n3. Name it (e.g., \"MCP Gateway M2M Sync\")\n4. Authorize for **Auth0 Management API**\n5. Grant required scopes:\n - `read:clients` - Read client applications\n - `read:client_grants` - Read client grants (optional)\n\n### 2. Environment Variables\n\nConfigure the following in `.env`:\n\n```bash\n# Auth0 M2M credentials for Management API access\nAUTH0_DOMAIN=dev-abc123.us.auth0.com\nAUTH0_M2M_CLIENT_ID=your_m2m_client_id\nAUTH0_M2M_CLIENT_SECRET=your_m2m_client_secret\n```\n\nThese credentials are used by the sync service to query the Auth0 Management API.\n\n## API Endpoints\n\n### Sync M2M Clients\n\nFetch all M2M applications from Auth0 and store in MongoDB.\n\n**Request:**\n```http\nPOST /api/iam/auth0/m2m/sync\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"force_full_sync\": false\n}\n```\n\n**Response:**\n```json\n{\n \"synced_count\": 3,\n \"added_count\": 2,\n \"updated_count\": 1,\n \"removed_count\": 0,\n \"errors\": []\n}\n```\n\n### List M2M Clients\n\nGet all synced Auth0 M2M clients.\n\n**Request:**\n```http\nGET /api/iam/auth0/m2m/clients\nAuthorization: Bearer \n```\n\n**Response:**\n```json\n[\n {\n \"client_id\": \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\",\n \"name\": \"MCP Gateway M2M\",\n \"description\": \"M2M client for registry access\",\n \"groups\": [\"registry-admins\"],\n \"enabled\": true,\n \"provider\": \"auth0\",\n \"created_at\": \"2026-03-29T00:00:00Z\",\n \"updated_at\": \"2026-03-29T00:00:00Z\"\n }\n]\n```\n\n### Get Client Groups\n\nGet groups for a specific M2M client.\n\n**Request:**\n```http\nGET /api/iam/auth0/m2m/clients/{client_id}/groups\nAuthorization: Bearer \n```\n\n**Response:**\n```json\n[\"registry-admins\", \"public-mcp-users\"]\n```\n\n### Update Client Groups\n\nUpdate groups for an M2M client (admin only).\n\n**Request:**\n```http\nPATCH /api/iam/auth0/m2m/clients/{client_id}/groups\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"groups\": [\"registry-admins\", \"developers\"]\n}\n```\n\n**Response:**\n```json\n{\n \"client_id\": \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\",\n \"groups\": [\"registry-admins\", \"developers\"],\n \"message\": \"Groups updated successfully\"\n}\n```\n\n## Usage\n\n### 1. Initial Sync\n\nAfter configuring Auth0 credentials, perform an initial sync:\n\n```bash\ncurl -X POST https://registry.example.com/api/iam/auth0/m2m/sync \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"force_full_sync\": true}'\n```\n\nThis will:\n1. Fetch all M2M applications from Auth0\n2. Store them in `auth0_m2m_clients` collection\n3. Write to `idp_m2m_clients` collection for groups enrichment\n\n### 2. Assign Groups\n\nUpdate groups for M2M clients:\n\n```bash\ncurl -X PATCH https://registry.example.com/api/iam/auth0/m2m/clients/{client_id}/groups \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"groups\": [\"registry-admins\"]}'\n```\n\n### 3. Verify Groups Enrichment\n\nTest an M2M token:\n\n```bash\n# Get M2M token from Auth0\nTOKEN=$(curl -X POST https://dev-abc123.us.auth0.com/oauth/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=${CLIENT_ID}\" \\\n -d \"client_secret=${CLIENT_SECRET}\" \\\n -d \"audience=https://dev-abc123.us.auth0.com/api/v2/\" \\\n | jq -r '.access_token')\n\n# Use token to access registry\ncurl https://registry.example.com/api/servers \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nThe auth-server will:\n1. Validate the JWT signature\n2. Detect empty groups claim\n3. Query `idp_m2m_clients` for the client ID\n4. Enrich with groups from database\n5. Apply group-based authorization\n\n## Default Groups\n\nYou can configure default groups for specific client IDs in `registry/services/auth0_m2m_sync.py`:\n\n```python\nDEFAULT_CLIENT_GROUPS = {\n \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\": [\"registry-admins\"],\n \"another_client_id\": [\"public-mcp-users\"],\n}\n```\n\nThese groups are assigned during sync and can be overridden via the API.\n\n## Troubleshooting\n\n### Sync Returns Empty List\n\n**Problem:** No M2M clients found\n\n**Solutions:**\n1. Verify Auth0 has M2M applications (app_type: \"non_interactive\")\n2. Check Management API credentials have `read:clients` scope\n3. Review logs: `docker logs mcp-gateway-registry 2>&1 | grep \"Auth0 M2M\"`\n\n### Token Has No Groups\n\n**Problem:** M2M token works but has no authorization\n\n**Solutions:**\n1. Verify client is synced: `GET /api/iam/auth0/m2m/clients`\n2. Check `idp_m2m_clients` collection in MongoDB:\n ```javascript\n db.idp_m2m_clients.find({ client_id: \"your_client_id\" })\n ```\n3. Assign groups via API: `PATCH /api/iam/auth0/m2m/clients/{id}/groups`\n4. Check auth-server logs for groups enrichment messages\n\n### Permission Denied\n\n**Problem:** 403 Forbidden despite having correct groups\n\n**Solutions:**\n1. Verify groups are mapped to scopes in `group_to_scope_mappings` collection\n2. Check auth-server includes \"auth0\" in provider list (line 1557 in server.py)\n3. Ensure `AUTH_PROVIDER=auth0` in environment variables\n\n## MongoDB Queries\n\n### Check M2M Client\n\n```javascript\ndb.idp_m2m_clients.find({\n provider: \"auth0\",\n client_id: \"your_client_id\"\n}).pretty()\n```\n\n### Update Groups Manually\n\n```javascript\ndb.idp_m2m_clients.updateOne(\n { client_id: \"your_client_id\" },\n {\n $set: {\n groups: [\"registry-admins\"],\n updated_at: new Date()\n }\n }\n)\n```\n\n### List All Auth0 M2M Clients\n\n```javascript\ndb.idp_m2m_clients.find({ provider: \"auth0\" }).pretty()\n```\n\n## Related Documentation\n\n- [Auth0 Management API](https://auth0.com/docs/api/management/v2)\n- [Auth0 M2M Applications](https://auth0.com/docs/get-started/applications/application-types#machine-to-machine-applications)\n- [Groups Enrichment](../auth_server/mongodb_groups_enrichment.py)\n- [Okta M2M Setup](okta-setup.md) - Similar pattern for Okta\n" }, { "path": "docs/auth0.md", "content": "# Auth0 Integration for MCP Gateway Registry\n\n> **⚠️ IMPORTANT DISCLAIMER**\n>\n> This documentation is a **reference guide based on our testing and development experience**, not an official Auth0 configuration manual. Auth0's interface, features, and best practices evolve over time.\n>\n> **Always consult the [official Auth0 documentation](https://auth0.com/docs) for:**\n> - Current UI layouts and navigation paths\n> - Latest security recommendations\n> - Production-grade configuration guidance\n> - Detailed API references\n>\n> **Purpose of this guide:**\n> - Document the specific configuration steps we used during development\n> - Provide a working reference for MCP Gateway Registry integration\n> - Share lessons learned and troubleshooting tips\n>\n> If you encounter differences between this guide and your Auth0 console, refer to Auth0's official documentation as the authoritative source.\n\nThis document provides instructions for integrating Auth0 as the authentication provider for the MCP Gateway Registry, including user management and group-based authorization.\n\n## Overview\n\nThe MCP Gateway Registry supports Auth0 as an OAuth2/OIDC identity provider. Users authenticate via Auth0 and receive JWT tokens for programmatic access to gateway APIs (CLI tools, coding assistants, etc.).\n\n**Key Concepts:**\n- **Users**: People who log in to the registry\n- **Roles**: Auth0's term for groups (e.g., `registry-admins`, `registry-users`)\n- **Groups**: The MCP Gateway converts Auth0 roles → groups for authorization\n- **M2M (Machine-to-Machine)**: Service accounts for CLI tools and scripts (no human login)\n\n## Architecture\n\n### Authentication Flow\n\n```\n┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n│ Browser │ │ Registry │ │ Auth Server │ │ Auth0 │\n│ (User) │ │ Frontend │ │ │ │ Tenant │\n└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘\n │ │ │ │\n │ 1. Click Login │ │ │\n │──────────────────>│ │ │\n │ │ │ │\n │ 2. Redirect to Auth Server │ │\n │<──────────────────│ │ │\n │ │ │ │\n │ 3. /oauth2/login/auth0 │ │\n │──────────────────────────────────────>│ │\n │ │ │ │\n │ 4. Redirect to Auth0 /authorize endpoint │\n │<─────────────────────────────────────────────────────────>│\n │ │ │ │\n │ 5. User authenticates with Auth0 │ │\n │<─────────────────────────────────────────────────────────>│\n │ │ │ │\n │ 6. Redirect with auth code │ │\n │──────────────────────────────────────>│ │\n │ │ │ │\n │ │ 7. Exchange code │ │\n │ │ for tokens │ │\n │ │ │──────────────────>│\n │ │ │<──────────────────│\n │ │ │ (ID token + │\n │ │ │ access token) │\n │ │ │ │\n │ 8. Set session cookie + redirect │ │\n │<──────────────────────────────────────│ │\n │ │ │ │\n │ 9. Access Registry with session │ │\n │──────────────────>│ │ │\n │ │ │ │\n```\n\n### Group Extraction\n\nUser groups are extracted from the Auth0 ID token using a **custom namespaced claim**. Auth0 does not include group memberships in tokens by default -- you must configure an Auth0 Action (or legacy Rule) to add them.\n\n**Claim lookup order:**\n\n1. Custom namespaced claim (default: `https://mcp-gateway/groups`)\n2. Fallback: `permissions` claim from Auth0 RBAC\n\nIf neither claim contains data, the user will have an empty groups list and no permissions.\n\n---\n\n## Complete Setup Guide\n\n### Prerequisites\n\n- Auth0 account (free tier works fine for testing)\n- MCP Gateway Registry deployed and accessible via HTTPS\n- Access to modify nginx configuration and environment variables\n\n### Step 1: Create an Auth0 Application\n\n1. **Log in to Auth0 Dashboard** at https://manage.auth0.com/\n2. Navigate to **Applications > Applications** (left sidebar)\n3. Click **Create Application**\n4. Configure the application:\n - **Name**: `AI Registry` (or your preferred name)\n - **Application Type**: Select **Regular Web Application**\n - Click **Create**\n\n5. **Copy your credentials** from the Settings tab:\n - **Domain**: e.g., `dev-abc123xyz.us.auth0.com` (without `https://`)\n - **Client ID**: Long alphanumeric string\n - **Client Secret**: Click the eye icon to reveal and copy\n\n**Important:** Keep these credentials secure. You'll need them for environment configuration.\n\n### Step 2: Configure Application URLs\n\nScroll down to **Application URIs** section and configure:\n\n**Allowed Callback URLs:**\n```\nhttps://your-registry-domain.com/oauth2/callback/auth0\n```\n\n**Allowed Logout URLs:**\n```\nhttps://your-registry-domain.com\n```\n\n**Allowed Web Origins:**\n```\nhttps://your-registry-domain.com\n```\n\n**Example for local testing:**\n```\nhttp://localhost/oauth2/callback/auth0\nhttp://localhost\n```\n\nClick **Save Changes** at the bottom.\n\n### Step 3: Create an Auth0 Action (Required for Groups)\n\nAuth0 Actions are custom code that runs during authentication to add groups to tokens.\n\n1. Navigate to **Actions > Triggers** (left sidebar)\n2. Click on the **post-login** trigger box\n3. You'll see the Login Flow diagram with Start → Complete\n4. Click **Create Action** (bottom right)\n5. Configure the Action:\n - **Name**: `Add Groups to Tokens`\n - **Trigger**: `Login / Post Login` (already selected)\n - **Runtime**: `Node 18` (or latest)\n - Click **Create**\n\n6. **Paste this code** in the editor:\n\n```javascript\nexports.onExecutePostLogin = async (event, api) => {\n const namespace = \"https://mcp-gateway/\";\n\n // Add user's roles as groups\n if (event.authorization && event.authorization.roles) {\n api.idToken.setCustomClaim(namespace + \"groups\", event.authorization.roles);\n api.accessToken.setCustomClaim(namespace + \"groups\", event.authorization.roles);\n }\n\n // Fallback to permissions if no roles\n if (event.authorization && event.authorization.permissions) {\n if (!event.authorization.roles || event.authorization.roles.length === 0) {\n api.idToken.setCustomClaim(namespace + \"groups\", event.authorization.permissions);\n api.accessToken.setCustomClaim(namespace + \"groups\", event.authorization.permissions);\n }\n }\n\n // Optional: Add organization info if using Auth0 Organizations\n if (event.organization) {\n api.idToken.setCustomClaim(namespace + \"org_id\", event.organization.id);\n api.idToken.setCustomClaim(namespace + \"org_name\", event.organization.name);\n }\n};\n```\n\n7. Click **Deploy** (top-right corner)\n8. Go back to the Post Login flow (click the back arrow)\n9. **Add the Action to the flow**:\n - On the right panel, click the **Custom** tab\n - Find your \"Add Groups to Tokens\" Action\n - **Drag and drop** it between \"Start\" and \"Complete\" in the flow diagram\n10. Click **Apply** (top-right)\n\n**Note:** The namespace `https://mcp-gateway/` must match your `AUTH0_GROUPS_CLAIM` environment variable.\n\n### Step 4: Create Roles (Groups)\n\nAuth0 uses \"Roles\" for authorization. The MCP Gateway maps these to \"groups\".\n\n1. Navigate to **User Management > Roles** (left sidebar)\n2. Click **Create Role**\n3. Create the administrator role:\n - **Name**: `registry-admins`\n - **Description**: `Registry administrators with full access`\n - Click **Create**\n\n4. **Optional:** Create additional roles as needed:\n - `registry-users` - Regular users\n - `registry-viewers` - Read-only access\n - `developers` - Developer access\n\n**Important:** Role names must match the groups configured in your `scopes.yml` file.\n\n### Step 5: Create Users\n\n1. Navigate to **User Management > Users** (left sidebar)\n2. Click **Create User**\n3. Fill in user details:\n - **Email**: User's email address\n - **Password**: Set a strong password (or send password reset email)\n - **Connection**: `Username-Password-Authentication` (default database)\n4. Click **Create**\n\n**Repeat** for additional users.\n\n### Step 6: Assign Roles to Users\n\n1. Go to **User Management > Users**\n2. Click on a user you just created\n3. Go to the **Roles** tab\n4. Click **Assign Roles**\n5. Select `registry-admins` (or other roles)\n6. Click **Assign**\n\n**Verification:** The user should now have roles listed in their profile.\n\n### Step 7: Configure Environment Variables\n\n#### Option A: Update Existing .env File\n\nEdit your `.env` file and update these variables:\n\n```bash\n# Authentication Provider\nAUTH_PROVIDER=auth0\n\n# Auth0 Configuration\nAUTH0_DOMAIN=dev-abc123xyz.us.auth0.com\nAUTH0_CLIENT_ID=your-client-id-here\nAUTH0_CLIENT_SECRET=your-client-secret-here\nAUTH0_GROUPS_CLAIM=https://mcp-gateway/groups\nAUTH0_ENABLED=true\n\n# Disable other providers\nKEYCLOAK_ENABLED=false\nENTRA_ENABLED=false\nCOGNITO_ENABLED=false\n```\n\n#### Option B: Create Provider-Specific Files\n\nFor easy switching between providers:\n\n```bash\n# Backup current configuration\ncp .env .env.keycloak\n\n# Create Auth0 configuration\ncp .env .env.auth0\n\n# Edit .env.auth0 with Auth0 credentials (as shown above)\n\n# Activate Auth0\ncp .env.auth0 .env\n```\n\n#### Complete Environment Variables\n\n| Variable | Required | Description | Example |\n|----------|----------|-------------|---------|\n| `AUTH_PROVIDER` | Yes | Set to `auth0` | `auth0` |\n| `AUTH0_DOMAIN` | Yes | Auth0 tenant domain (no https://) | `dev-abc123xyz.us.auth0.com` |\n| `AUTH0_CLIENT_ID` | Yes | Application client ID | `eYNHy8GXBHH1s60Po9J0SLGcsLGsNPoA` |\n| `AUTH0_CLIENT_SECRET` | Yes | Application client secret | `q-9A_nlgypKAOfwLmTvv0k...` |\n| `AUTH0_GROUPS_CLAIM` | No | Custom claim name for groups | `https://mcp-gateway/groups` (default) |\n| `AUTH0_ENABLED` | Yes | Enable Auth0 provider | `true` |\n| `AUTH0_AUDIENCE` | No | API identifier (M2M only) | `https://api.example.com` |\n| `AUTH0_M2M_CLIENT_ID` | No | M2M client ID (M2M only) | `xyz789...` |\n| `AUTH0_M2M_CLIENT_SECRET` | No | M2M client secret (M2M only) | `abc456...` |\n\n### Step 8: Verify Nginx Configuration\n\nThe nginx reverse proxy needs Auth0 route configuration. Check that these location blocks exist in your nginx config file:\n\n**File:** `docker/nginx_rev_proxy_http_and_https.conf`\n\n```nginx\n# OAuth2 Auth0 callback endpoint\nlocation /oauth2/callback/auth0 {\n proxy_pass http://auth-server:8888/oauth2/callback/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n proxy_pass_request_body on;\n}\n\n# OAuth2 Auth0 login endpoint\nlocation /oauth2/login/auth0 {\n proxy_pass http://auth-server:8888/oauth2/login/auth0;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $real_scheme;\n proxy_pass_request_headers on;\n}\n```\n\n**If these blocks are missing**, add them to both the HTTP (port 8080) and HTTPS (port 8443) server blocks. Place them after the Google OAuth endpoints and before the Keycloak section.\n\n### Step 9: Restart Services\n\nRestart the registry and auth-server containers to apply the new configuration:\n\n```bash\n# If using docker-compose\ndocker-compose restart registry auth-server\n\n# Or rebuild and restart all services\ndocker-compose down\ndocker-compose up -d\n```\n\nWait for services to become healthy:\n```bash\ndocker-compose ps\n```\n\n### Step 10: Test Authentication\n\n1. **Open the registry** in your browser: `https://your-registry-domain.com`\n2. **Click \"Login\"** or navigate to the login page\n3. **Select \"Auth0\"** from the provider list\n4. You should be **redirected to Auth0 login page**\n5. **Enter credentials** for the user you created\n6. After successful login, you should be **redirected back to the registry**\n7. **Verify your session**:\n - Check that your username appears in the UI\n - Admin users should see admin panels/options\n\n**Check logs if login fails:**\n```bash\n# Auth server logs\ndocker-compose logs --tail=50 auth-server\n\n# Registry logs\ndocker-compose logs --tail=50 registry\n```\n\n---\n\n## Machine-to-Machine (M2M) Authentication\n\nM2M authentication allows non-human clients (CLI tools, scripts, cron jobs) to authenticate and access the registry API programmatically using OAuth2 client credentials flow.\n\n### When to Use M2M\n\n- CLI tools that need to access the registry without browser login\n- Automated scripts (CI/CD pipelines)\n- Service-to-service authentication\n- Cron jobs that sync or update registry data\n- Federation between registry instances\n\n### How M2M Authentication Works\n\n1. An M2M application requests an access token from Auth0 using client credentials\n2. Auth0 validates the credentials and returns a JWT access token\n3. The client sends the token in the `Authorization: Bearer` header to the registry API\n4. The registry validates the token against Auth0's JWKS endpoint\n5. The registry looks up the client's groups from MongoDB (since M2M tokens do not contain group claims from Auth0 Actions)\n\n**Important:** M2M tokens do NOT go through Auth0's Post Login Actions, so group claims like `https://mcp-gateway/groups` are not included in the JWT. The registry resolves groups by looking up the client ID in the `idp_m2m_clients` MongoDB collection. You must sync M2M clients and assign groups via the registry's IAM API.\n\n### M2M Setup\n\n#### Step 1: Identify the API Audience\n\nThe `AUTH0_AUDIENCE` is the identifier of the API your M2M client will request tokens for. For the MCP Gateway Registry, you can use:\n\n- **Auth0 Management API** (default): `https://your-tenant.auth0.com/api/v2/`\n- **Custom API**: Create your own API identifier (see \"Create a Custom API\" below)\n\nThe audience value must match exactly between:\n- The `AUTH0_AUDIENCE` environment variable in your registry deployment\n- The `audience` parameter in your token request\n\n#### Step 2: Create an M2M Application in Auth0\n\n1. Log in to the **Auth0 Dashboard** (https://manage.auth0.com)\n2. Navigate to **Applications > Applications** in the left sidebar\n3. Click **+ Create Application** (top right)\n4. Configure the application:\n - **Name**: Give it a descriptive name (e.g., `Registry CLI Client`, `CI/CD Pipeline`)\n - **Application Type**: Select **Machine to Machine Applications**\n5. Click **Create**\n6. On the next screen, you will be asked to authorize the application for an API:\n - Select the API matching your `AUTH0_AUDIENCE` (e.g., **Auth0 Management API**)\n - Select the required scopes/permissions (e.g., `read:clients` for basic access)\n - Click **Authorize**\n7. You will be taken to the application's **Settings** tab\n8. Copy the **Client ID** and **Client Secret** -- you will need these to generate tokens\n\n#### Step 3: Authorize the M2M Application for the API\n\nThis is a critical step that is often missed. Each M2M application must be explicitly authorized to request tokens for a specific API.\n\n**If you skipped authorization during creation, or need to authorize for a different API:**\n\n1. Navigate to **Applications > APIs** in the left sidebar\n2. Click on the API you want to authorize against (e.g., **Auth0 Management API**)\n3. Click the **Machine to Machine Applications** tab (also called **Application Access**)\n4. You will see a list of all M2M applications in your tenant\n5. Find your application in the list\n6. **Toggle the switch ON** next to the application name to authorize it\n7. After toggling ON, a permissions dropdown appears\n8. Select the scopes/permissions the application needs:\n - For basic registry API access: `read:clients` is sufficient\n - For management operations: add `read:users`, `read:roles`, etc.\n9. Click **Update** to save\n\n**If the toggle is OFF**, the M2M application will receive an `access_denied` error when requesting tokens for that API audience.\n\n#### Step 4: (Optional) Create a Custom API\n\nIf you prefer a dedicated API for registry access instead of using the Auth0 Management API:\n\n1. Navigate to **Applications > APIs** in the left sidebar\n2. Click **+ Create API** (top right)\n3. Configure the API:\n - **Name**: `MCP Registry API`\n - **Identifier**: `https://api.your-domain.com` (this becomes your `AUTH0_AUDIENCE`)\n - **Signing Algorithm**: `RS256`\n4. Click **Create**\n5. Go to the **Machine to Machine Applications** tab\n6. Authorize your M2M applications as described in Step 3\n\n#### Step 5: Configure Environment Variables\n\nAdd the following to your `.env` file:\n\n```bash\n# Auth0 domain (no https:// prefix)\nAUTH0_DOMAIN=your-tenant.us.auth0.com\n\n# API audience - must match the API identifier in Auth0\n# Use Management API URL or your custom API identifier\nAUTH0_AUDIENCE=https://your-tenant.us.auth0.com/api/v2/\n\n# M2M client credentials (for the registry's own Management API access)\nAUTH0_M2M_CLIENT_ID=your-m2m-client-id\nAUTH0_M2M_CLIENT_SECRET=your-m2m-client-secret\n```\n\nFor Terraform deployments, set in `terraform.tfvars`:\n\n```hcl\nauth0_audience = \"https://your-tenant.us.auth0.com/api/v2/\"\nauth0_m2m_client_id = \"your-m2m-client-id\"\nauth0_m2m_client_secret = \"your-m2m-client-secret\"\n```\n\n#### Step 6: Generate an M2M Token\n\n**Option A: Using the helper script (recommended)**\n\n```bash\npython3 credentials-provider/auth0/get_m2m_token.py \\\n --auth0-domain your-tenant.us.auth0.com \\\n --client-id YOUR_CLIENT_ID \\\n --client-secret YOUR_CLIENT_SECRET \\\n --audience \"https://your-tenant.us.auth0.com/api/v2/\" \\\n --output-file /tmp/m2m_token.json\n```\n\n**Option B: Using curl**\n\n```bash\ncurl --request POST \\\n --url https://your-tenant.us.auth0.com/oauth/token \\\n --header 'content-type: application/json' \\\n --data '{\n \"client_id\": \"YOUR_CLIENT_ID\",\n \"client_secret\": \"YOUR_CLIENT_SECRET\",\n \"audience\": \"https://your-tenant.us.auth0.com/api/v2/\",\n \"grant_type\": \"client_credentials\"\n }'\n```\n\nThe response contains an `access_token` field with your JWT bearer token.\n\n#### Step 7: Test M2M Token with the Registry API\n\n```bash\n# Using the registry management CLI tool\npython3 api/registry_management.py \\\n --registry-url https://your-registry-domain.com \\\n --token-file /tmp/m2m_token.json \\\n --action list-servers\n\n# Or using curl directly\nTOKEN=$(cat /tmp/m2m_token.json | python3 -c \"import sys,json; print(json.load(sys.stdin)['access_token'])\")\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n https://your-registry-domain.com/api/servers\n```\n\n#### Step 8: Assign Groups to M2M Clients\n\nSince M2M tokens do not include group claims from Auth0 Actions, you must manage groups for M2M clients through the registry's IAM API:\n\n1. **Sync M2M clients** from Auth0 to the registry database:\n ```bash\n curl -X POST \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n https://your-registry-domain.com/api/iam/auth0/m2m/sync\n ```\n\n2. **List synced M2M clients:**\n ```bash\n curl -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n https://your-registry-domain.com/api/iam/auth0/m2m/clients\n ```\n\n3. **Assign groups to an M2M client:**\n ```bash\n curl -X PATCH \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"groups\": [\"registry-admins\", \"registry-users\"]}' \\\n https://your-registry-domain.com/api/iam/auth0/m2m/clients/CLIENT_ID/groups\n ```\n\nThe registry will use these stored groups when validating API requests from M2M clients.\n\n### M2M Troubleshooting\n\n#### \"access_denied\" Error When Requesting Token\n\n**Cause:** The M2M application is not authorized for the requested API audience.\n\n**Fix:**\n1. Go to **Applications > APIs** in Auth0 Dashboard\n2. Click on the API matching your audience\n3. Click the **Machine to Machine Applications** tab\n4. Find your application and **toggle the switch ON**\n5. Select the required scopes and click **Update**\n\n#### \"Audience doesn't match\" Error from Registry\n\n**Cause:** The `AUTH0_AUDIENCE` in your `.env` does not match the audience in the token.\n\n**Fix:**\n1. Check what audience is in your token: `echo $TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool | grep aud`\n2. Set `AUTH0_AUDIENCE` in `.env` to match exactly\n3. Restart the registry: `docker-compose restart registry auth-server`\n\n#### M2M Client Has No Permissions (403 Forbidden)\n\n**Cause:** The M2M client has no groups assigned in the registry database.\n\n**Fix:**\n1. Sync M2M clients: `POST /api/iam/auth0/m2m/sync`\n2. Assign groups: `PATCH /api/iam/auth0/m2m/clients/{client_id}/groups`\n3. Verify groups: `GET /api/iam/auth0/m2m/clients/{client_id}/groups`\n\n---\n\n## User and Role Management\n\n### Creating Additional Roles\n\n1. Go to **User Management > Roles**\n2. Click **Create Role**\n3. Enter role name (e.g., `developers`, `viewers`)\n4. Click **Create**\n5. **Map roles to MCP Gateway groups** in your `scopes.yml` file\n\n### Assigning Roles in Bulk\n\n1. Go to **User Management > Roles**\n2. Click on a role (e.g., `registry-users`)\n3. Go to the **Users** tab\n4. Click **Add Users**\n5. Search and select multiple users\n6. Click **Assign**\n\n### Removing Roles from Users\n\n1. Go to **User Management > Users**\n2. Click on a user\n3. Go to the **Roles** tab\n4. Click the `...` menu next to a role\n5. Click **Remove**\n\n### Creating Users Programmatically\n\nUse the Auth0 Management API to automate user creation:\n\n```bash\n# Get Management API token\ncurl --request POST \\\n --url https://your-tenant.auth0.com/oauth/token \\\n --header 'content-type: application/json' \\\n --data '{\n \"client_id\": \"your-management-api-client-id\",\n \"client_secret\": \"your-management-api-client-secret\",\n \"audience\": \"https://your-tenant.auth0.com/api/v2/\",\n \"grant_type\": \"client_credentials\"\n }'\n\n# Create a user\ncurl --request POST \\\n --url https://your-tenant.auth0.com/api/v2/users \\\n --header 'authorization: Bearer ' \\\n --header 'content-type: application/json' \\\n --data '{\n \"email\": \"newuser@example.com\",\n \"password\": \"SecurePassword123!\",\n \"connection\": \"Username-Password-Authentication\"\n }'\n```\n\n### IAM Management (Settings > IAM > Groups/Users)\n\nThe MCP Gateway Registry provides a web UI for managing users and roles via **Settings > IAM**. This requires Auth0 Management API access.\n\n**Important:** This is separate from M2M authentication for registry API access. The Management API allows the registry to:\n- List users and roles\n- Create/delete users\n- Assign roles to users\n- Manage role (group) definitions\n\n#### Option 1: M2M Application for Management API (Recommended)\n\nCreate a dedicated M2M application with Management API permissions:\n\n1. **Navigate to Applications > Applications** in Auth0 Dashboard\n2. Click **Create Application**\n3. Configure:\n - **Name**: `Registry Management Client`\n - **Application Type**: Select **Machine to Machine Applications**\n4. **Select API**: Choose **Auth0 Management API** (this is pre-created by Auth0)\n5. Click **Authorize**\n6. **Grant Permissions**: Select the following scopes:\n - `read:users`\n - `update:users`\n - `create:users`\n - `delete:users`\n - `read:roles`\n - `update:roles`\n - `create:roles`\n - `delete:roles`\n - `read:users_app_metadata`\n - `update:users_app_metadata`\n7. Click **Authorize** to confirm\n8. Copy the **Client ID** and **Client Secret**\n\n**Add to .env file:**\n\n```bash\nAUTH0_M2M_CLIENT_ID=your-management-client-id\nAUTH0_M2M_CLIENT_SECRET=your-management-client-secret\n```\n\n#### Option 2: Static Management API Token\n\nAlternatively, use a static token (less secure, expires):\n\n1. Go to **Applications > APIs > Auth0 Management API**\n2. Click **API Explorer** tab\n3. Click **Create & Authorize Test Application**\n4. Copy the generated token\n\n**Add to .env file:**\n\n```bash\nAUTH0_MANAGEMENT_API_TOKEN=your-static-token\n```\n\n**⚠️ Warning:** Static tokens expire after 24 hours by default. M2M credentials (Option 1) are recommended for production.\n\n#### Testing IAM Management\n\nAfter configuring Management API access:\n\n1. Restart the registry: `docker-compose restart registry auth-server`\n2. Open the web UI: `https://your-registry-domain.com`\n3. Navigate to **Settings > IAM > Groups**\n4. You should see your Auth0 roles listed (e.g., `registry-admins`, `registry-users`)\n5. Navigate to **Settings > IAM > Users**\n6. You should see all Auth0 users with their role assignments\n\n**Troubleshooting:**\n- If you see an empty list or errors, check auth server logs: `docker-compose logs auth-server | grep Management`\n- Verify M2M credentials are correct: `grep AUTH0_M2M .env`\n- Ensure Management API permissions are granted in Auth0 Dashboard\n\n---\n\n## Group-to-Scope Mapping\n\nThe MCP Gateway uses a `scopes.yml` file to map Auth0 roles to registry permissions.\n\n### Example scopes.yml Configuration\n\n```yaml\ngroup_mappings:\n registry-admins:\n - admin:*\n - servers:*\n - agents:*\n - scopes:manage\n\n registry-users:\n - servers:read\n - servers:write\n - agents:read\n - tools:*\n\n registry-viewers:\n - servers:read\n - agents:read\n - tools:read\n```\n\n**Location:** This file should be in your registry configuration directory and loaded at startup.\n\n---\n\n## Troubleshooting\n\n### Empty Page or No Redirect to Auth0\n\n**Symptom:** Clicking login shows an empty page at `/oauth2/login/auth0`\n\n**Causes:**\n1. Missing nginx configuration for Auth0 routes\n2. Auth server not receiving the request\n\n**Solution:**\n1. Verify nginx has Auth0 location blocks (Step 8)\n2. Restart the registry container: `docker-compose restart registry`\n3. Check nginx error logs: `docker-compose exec registry cat /var/log/nginx/error.log`\n\n### Users Have No Groups After Login\n\n**Symptom:** User logs in successfully but has no permissions\n\n**Causes:**\n1. Auth0 Action not deployed or not in the flow\n2. User has no roles assigned\n3. `AUTH0_GROUPS_CLAIM` mismatch\n\n**Solution:**\n1. Go to **Actions > Triggers > Post Login** and verify the Action is in the flow\n2. Check user has roles: **User Management > Users > [User] > Roles tab**\n3. Verify environment variable: `grep AUTH0_GROUPS_CLAIM .env`\n4. Check auth server logs: `docker-compose logs auth-server | grep \"Auth0 ID token claims\"`\n\n### Callback URL Mismatch Error\n\n**Symptom:** Auth0 shows \"Callback URL mismatch\" error after login\n\n**Solution:**\n1. Go to Auth0 Dashboard > Applications > Your App > Settings\n2. Verify **Allowed Callback URLs** exactly matches:\n ```\n https://your-domain.com/oauth2/callback/auth0\n ```\n3. Click **Save Changes**\n4. Try logging in again\n\n### Token Validation Errors\n\n**Symptom:** \"Invalid token\" or \"Token validation failed\" errors\n\n**Causes:**\n1. `AUTH0_DOMAIN` has `https://` prefix\n2. Wrong Client ID or Client Secret\n3. Token expired\n\n**Solution:**\n1. Verify domain has no protocol:\n ```bash\n # Correct\n AUTH0_DOMAIN=dev-abc123xyz.us.auth0.com\n\n # Wrong\n AUTH0_DOMAIN=https://dev-abc123xyz.us.auth0.com\n ```\n2. Verify credentials match Auth0 Dashboard\n3. Check auth server logs for specific error messages\n\n### M2M Token Failures\n\n**Symptom:** M2M authentication returns 401 or 403\n\n**Causes:**\n1. M2M application not authorized for the API\n2. Wrong audience parameter\n3. Missing API in Auth0\n\n**Solution:**\n1. Go to Auth0 Dashboard > Applications > APIs > [Your API]\n2. Go to the **Machine to Machine Applications** tab\n3. Ensure your M2M app is listed and **Authorized**\n4. Verify `AUTH0_AUDIENCE` matches the API **Identifier** exactly\n\n### CORS Errors\n\n**Symptom:** Browser console shows CORS errors\n\n**Solution:**\n1. Verify **Allowed Web Origins** in Auth0 includes your domain\n2. Check nginx is setting correct CORS headers\n3. Ensure `AUTH_SERVER_EXTERNAL_URL` matches your public domain\n\n---\n\n## Security Best Practices\n\n### 1. Use Strong Secrets\n\n- Generate strong, random client secrets (Auth0 does this automatically)\n- Never commit secrets to version control\n- Rotate secrets periodically\n\n### 2. Restrict Callback URLs\n\nOnly add legitimate callback URLs to Auth0:\n```\n# Good - specific domains\nhttps://registry.example.com/oauth2/callback/auth0\nhttps://registry-staging.example.com/oauth2/callback/auth0\n\n# Bad - wildcards allow any subdomain\nhttps://*.example.com/oauth2/callback/auth0\n```\n\n### 3. Enable Multi-Factor Authentication (MFA)\n\n1. Go to **Security > Multi-factor Auth** in Auth0 Dashboard\n2. Enable **One-time Password** or **SMS**\n3. Configure policies (e.g., require MFA for admins)\n\n### 4. Monitor Login Activity\n\n1. Go to **Monitoring > Logs** in Auth0 Dashboard\n2. Review failed login attempts\n3. Set up alerts for suspicious activity\n\n### 5. Implement Principle of Least Privilege\n\n- Create specific roles with minimal permissions\n- Don't assign `registry-admins` to regular users\n- Regularly audit user roles\n\n---\n\n## Additional Resources\n\n- **Auth0 Documentation**: https://auth0.com/docs\n- **Auth0 Actions**: https://auth0.com/docs/customize/actions\n- **Auth0 Roles & Permissions**: https://auth0.com/docs/manage-users/access-control\n- **MCP Gateway Registry Docs**: https://github.com/agentic-community/mcp-gateway-registry/docs\n\n---\n\n## Summary Checklist\n\nUse this checklist to verify your Auth0 integration is complete:\n\n- [ ] Auth0 Application created (Regular Web Application)\n- [ ] Domain, Client ID, and Client Secret copied\n- [ ] Allowed Callback URLs configured\n- [ ] Allowed Logout URLs configured\n- [ ] Allowed Web Origins configured\n- [ ] Auth0 Action created and deployed\n- [ ] Action added to Post Login flow\n- [ ] Roles created (e.g., `registry-admins`)\n- [ ] Users created in Auth0\n- [ ] Roles assigned to users\n- [ ] Environment variables configured in `.env`\n- [ ] Nginx configuration includes Auth0 routes\n- [ ] Services restarted to apply configuration\n- [ ] Login tested successfully\n- [ ] User groups appear correctly in registry\n- [ ] Admin permissions verified (if applicable)\n- [ ] M2M application created (Machine to Machine type)\n- [ ] M2M application authorized for the correct API audience\n- [ ] `AUTH0_AUDIENCE` configured in `.env` and deployment configs\n- [ ] M2M token generation tested successfully\n- [ ] M2M clients synced to registry database\n- [ ] Groups assigned to M2M clients in registry\n\nOnce all items are checked, your Auth0 integration is complete!\n" }, { "path": "docs/aws-agent-registry-federation.md", "content": "# AWS Agent Registry Federation\n\nThis guide covers how to federate MCP servers, A2A agents, and agent skills from [Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry.html) registries into the MCP Gateway Registry. Once federated, AgentCore records appear alongside locally registered assets and can be discovered, searched, and invoked through the gateway.\n\n[Demo Video](https://app.vidcast.io/share/6d2e0a43-4a68-477e-b5b9-2b3e2aa59f83?playerMode=vidcast)\n\n## Overview\n\nAWS Agent Registry Federation connects MCP Gateway Registry to one or more Amazon Bedrock AgentCore registries. The gateway periodically syncs records from each configured registry, transforming AgentCore descriptors (MCP, A2A, CUSTOM, AGENT_SKILLS) into native MCP Gateway assets. Cross-account and cross-region access is supported via IAM role assumption.\n\n### What Gets Synced\n\n| AgentCore Descriptor Type | MCP Gateway Asset Type | Stored In |\n|---------------------------|----------------------|-----------|\n| MCP | MCP Server | `mcp_servers` collection |\n| A2A | A2A Agent | `mcp_agents` collection |\n| CUSTOM | A2A Agent | `mcp_agents` collection |\n| AGENT_SKILLS | Agent Skill | `agent_skills` collection |\n\n### Key Capabilities\n\n- **Multi-registry**: Add multiple AgentCore registries (same or different AWS accounts/regions)\n- **Cross-account**: Assume an IAM role in another account to read its registry\n- **Selective sync**: Choose which descriptor types to sync per registry\n- **Status filtering**: Sync only APPROVED, PENDING, or REJECTED records\n- **Cascade cleanup**: Removing a registry automatically deregisters all its synced assets\n- **Startup sync**: Optionally sync records when the gateway starts\n\n## Prerequisites\n\n- MCP Gateway Registry up and running (Docker Compose or ECS)\n- AWS credentials with Amazon Bedrock AgentCore permissions (see [IAM Setup](#iam-setup))\n- At least one AgentCore registry with published records\n\n## Step 1: Enable AWS Agent Registry Federation\n\n### Option A: Environment Variable (Recommended for ECS/Terraform)\n\nSet the environment variable in your `.env` file or ECS task definition:\n\n```bash\nAWS_REGISTRY_FEDERATION_ENABLED=true\n```\n\nThis overrides the `aws_registry.enabled` flag in the federation config on every startup. For Terraform deployments, set in `terraform.tfvars`:\n\n```hcl\naws_registry_federation_enabled = true\n```\n\n### Option B: API\n\nEnable via the federation config API:\n\n```bash\ncurl -X PUT https://your-registry.com/api/federation/config/default \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"aws_registry\": {\n \"enabled\": true,\n \"aws_region\": \"us-east-1\",\n \"sync_on_startup\": true\n }\n }'\n```\n\n### Option C: Settings UI\n\nNavigate to **Settings > Federation > External Registries**. The AWS Agent Registry card will show \"Enabled\" or \"Disabled\" based on the current configuration.\n\n![External Registries page showing AWS Agent Registry enabled with Anthropic and ASOR sources](img/aws-agent-reg-federation-1.png)\n\n## Step 2: Add a Registry\n\n### Using the UI\n\n1. Navigate to **Settings > Federation > External Registries**\n2. On the **AWS Agent Registry** card, click the **+** (Add) button\n\n3. In the Add AWS Agent Registry modal, enter the **Registry ID** (ARN or plain ID)\n - If you paste a full ARN (`arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rXXXXXXXX`), the **AWS Region** and **AWS Account ID** fields auto-populate from the ARN\n\n4. (Optional) Fill in additional fields:\n - **AWS Account ID**: Auto-populated from ARN, or enter manually\n - **AWS Region**: Auto-populated from ARN, or enter manually (leave empty to use global region)\n - **Assume Role ARN**: Only needed if adding a registry from a different AWS account\n - **Descriptor Types**: Select which types to sync (MCP, A2A, CUSTOM, AGENT_SKILLS)\n - **Sync Status Filter**: Choose APPROVED (default), PENDING, or REJECTED\n\n5. Click **Add**\n\n![Add AWS Agent Registry modal with ARN auto-populating region and account ID](img/aws-agent-reg-federation-2.png)\n\n### Using the API\n\n```bash\ncurl -X POST https://your-registry.com/api/federation/config/default/aws_registry/registries \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"registry_id\": \"arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rCu9kFIgrbNOpEsF\",\n \"aws_account_id\": \"123456789012\",\n \"aws_region\": \"us-east-1\",\n \"descriptor_types\": [\"MCP\", \"A2A\", \"CUSTOM\", \"AGENT_SKILLS\"],\n \"sync_status_filter\": \"APPROVED\"\n }'\n```\n\n### Using the CLI\n\n```bash\n# Save a federation config with AWS Agent Registry enabled\nuv run python registry_management.py federation-save \\\n --config cli/examples/federation-config-agentcore-example.json\n\n# Or get existing config, edit, and save back\nuv run python registry_management.py federation-get --json > federation-config.json\n# Edit federation-config.json to add registry entries under aws_registry.registries\nuv run python registry_management.py federation-save --config federation-config.json\n```\n\n## Step 3: Sync Records\n\n### Manual Sync (UI)\n\nAfter adding, the registry entry appears on the card showing the ARN, account ID, status filter, and descriptor type tags.\n\n![Registry entry added showing ARN, tags for MCP, A2A, CUSTOM, AGENT_SKILLS](img/aws-agent-reg-federation-3.png)\n\nClick the **Sync** button on the AWS Agent Registry card to trigger an immediate sync of all configured registries.\n\n### Manual Sync (API)\n\n```bash\n# Sync only AWS Agent Registry source\ncurl -X POST https://your-registry.com/api/federation/sync?source=aws_registry \\\n -H \"Authorization: Bearer \"\n\n# Sync all federation sources\ncurl -X POST https://your-registry.com/api/federation/sync \\\n -H \"Authorization: Bearer \"\n```\n\n### Manual Sync (CLI)\n\n```bash\n# Sync only AWS Agent Registry source\nuv run python registry_management.py federation-sync --source aws_registry\n\n# Sync all federation sources\nuv run python registry_management.py federation-sync\n```\n\n### Automatic Sync on Startup\n\nSet `sync_on_startup: true` in the federation config (via API or UI) to sync automatically when the gateway starts.\n\n## Step 4: Verify Synced Assets\n\nAfter syncing, the card shows the sync result with a breakdown of synced items and a toast notification confirming the count.\n\n![Sync completed showing 6 items: 2 Servers, 3 Agents, 1 Skill](img/aws-agent-reg-federation-4.png)\n\nFederated assets appear in the main registry views under the **External Registries** tab:\n\n- **MCP Servers**: Synced servers appear with `source: agentcore` and an `agentcore` tag\n- **A2A Agents**: Synced agents appear with `agentcore` tag and metadata containing the source registry ID\n- **Agent Skills**: Synced skills appear with `agentcore` tag and serve inline content\n\n![External Registries tab showing synced servers, agents, and skills from AgentCore](img/aws-agent-reg-federation-5.png)\n\n## Removing a Registry\n\n### Using the UI\n\n1. On the AWS Agent Registry card, click the **X** (remove) button next to the registry entry\n\n![Registry entry with X remove button](img/aws-agent-reg-federation-6.png)\n\n2. Confirm the deletion in the modal dialog. The modal warns that all servers, agents, and skills synced from this source will also be deregistered.\n\n![Confirm removal modal with cascade cleanup warning](img/aws-agent-reg-federation-7.png)\n\n\n### Using the API\n\n```bash\n# URL-encode the registry ID (ARNs contain colons and slashes)\ncurl -X DELETE \"https://your-registry.com/api/federation/config/default/aws_registry/registries/arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A123456789012%3Aregistry%2FrCu9kFIgrbNOpEsF\" \\\n -H \"Authorization: Bearer \"\n```\n\n### Cascade Cleanup\n\nWhen a registry is removed, all assets that were synced from it are automatically deregistered:\n- MCP servers with `source: agentcore` and matching `metadata.agentcore_registry_id`\n- A2A agents with matching `metadata.agentcore_registry_id` or `agentcore` tag + path prefix\n- Agent skills with matching metadata or `agentcore` tag + path prefix\n\nThe API response includes counts of deregistered assets:\n\n```json\n{\n \"message\": \"Registry removed and 3 server(s), 2 agent(s), 1 skill(s) deregistered\",\n \"deregistered\": {\n \"servers\": [\"/agentcore-my-server\"],\n \"agents\": [\"/agents/agentcore-my-agent-1\", \"/agents/agentcore-my-agent-2\"],\n \"skills\": [\"/skills/agentcore-my-skill\"]\n }\n}\n```\n\n## Cross-Account Federation\n\nTo sync from a registry in a different AWS account:\n\n1. In the remote account, create an IAM role with AgentCore read permissions and a trust policy allowing your gateway's task role to assume it\n2. Tag the role with `Purpose: agentcore-federation` (required by the STS condition policy)\n3. When adding the registry, provide the **Assume Role ARN** field\n\n```bash\ncurl -X POST https://your-registry.com/api/federation/config/default/aws_registry/registries \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"registry_id\": \"arn:aws:bedrock-agentcore:us-west-2:999888777666:registry/rRemoteReg\",\n \"aws_account_id\": \"999888777666\",\n \"aws_region\": \"us-west-2\",\n \"assume_role_arn\": \"arn:aws:iam::999888777666:role/AgentCoreFederationReadOnly\"\n }'\n```\n\n## IAM Setup\n\n### ECS Deployment (Terraform)\n\nWhen `aws_registry_federation_enabled = true` in `terraform.tfvars`, Terraform automatically creates and attaches a `bedrock_agentcore_access` IAM policy to the registry ECS task role with:\n\n- `bedrock-agentcore:*` -- Full access to AgentCore APIs\n- `sts:AssumeRole` -- For cross-account federation (scoped to roles tagged `Purpose: agentcore-federation`)\n\n### Docker Compose / Local\n\nFor local deployments, ensure the AWS credentials available to the container have the following permissions:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"bedrock-agentcore:ListRegistries\",\n \"bedrock-agentcore:ListRegistryRecords\",\n \"bedrock-agentcore:GetRegistryRecord\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n## Configuration Reference\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AWS_REGISTRY_FEDERATION_ENABLED` | Override `aws_registry.enabled` in federation config | (not set) |\n\n### Federation Config Fields (`aws_registry` section)\n\n| Field | Type | Description | Default |\n|-------|------|-------------|---------|\n| `enabled` | bool | Enable/disable AWS Agent Registry federation | `false` |\n| `aws_region` | string | Default AWS region for AgentCore API calls | `us-east-1` |\n| `sync_on_startup` | bool | Sync records when the gateway starts | `false` |\n| `sync_interval_minutes` | int | Interval between automatic syncs | `60` |\n| `sync_timeout_seconds` | int | Timeout for sync operations | `300` |\n| `max_concurrent_fetches` | int | Max parallel registry fetches | `5` |\n| `registries` | list | List of registry configurations (see below) | `[]` |\n\n### Per-Registry Config Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `registry_id` | string | Yes | Registry ID or full ARN |\n| `aws_account_id` | string | No | AWS account ID (auto-extracted from ARN) |\n| `aws_region` | string | No | Override region for this registry |\n| `assume_role_arn` | string | No | IAM role ARN for cross-account access |\n| `descriptor_types` | list[string] | No | Types to sync: MCP, A2A, CUSTOM, AGENT_SKILLS |\n| `sync_status_filter` | string | No | Record status to sync: APPROVED, PENDING, REJECTED |\n\n## Troubleshooting\n\n### AWS Agent Registry shows \"Disabled\"\n\n- Verify `AWS_REGISTRY_FEDERATION_ENABLED=true` is set in the environment\n- Check the registry container logs for `AWS_REGISTRY_FEDERATION_ENABLED=true (from env var)`\n- If using ECS, verify the env var is present in the task definition\n\n### Sync returns no records\n\n- Verify IAM permissions (see [IAM Setup](#iam-setup))\n- Check that the registry has records with the configured `sync_status_filter` (default: APPROVED)\n- Check container logs for API errors: `Failed to sync AgentCore server`\n\n### Cross-account sync fails\n\n- Verify the remote IAM role trust policy allows your task role to assume it\n- Verify the role is tagged with `Purpose: agentcore-federation`\n- Check that `assume_role_arn` is set correctly on the registry entry\n\n### Assets not cleaned up after registry removal\n\n- Older records synced before metadata tracking may only have tag-based matching\n- Check container logs for `Deregistered X server(s), Y agent(s), Z skill(s)`\n- Manually remove orphaned assets if needed via the MCP Servers or Agents UI\n" }, { "path": "docs/cli.md", "content": "# MCP Client CLI Guide\n\nThis guide documents how to interact with MCP servers and manage A2A agents using the command-line interface.\n\n## Table of Contents\n- [Overview](#overview)\n- [A2A Agent Management](#a2a-agent-management)\n- [MCP Client Authentication](#mcp-client-authentication)\n- [Basic Commands](#basic-commands)\n- [Server Management Commands](#server-management-commands)\n- [Tool Discovery](#tool-discovery)\n- [Direct Server Access](#direct-server-access)\n\n## Overview\n\nTwo CLI tools are available:\n1. **`agent_mgmt.py`** - A2A agent management (register, modify, delete, list)\n2. **`mcp_client.py`** - MCP server interaction (list tools, call tools, etc.)\n\n## A2A Agent Management\n\nFor complete A2A agent management documentation, see: [A2A Agent Management Guide](a2a-agent-management.md)\n\nQuick start with the `mcp-gateway-m2m` service account:\n```bash\n# Register an agent\nuv run python cli/agent_mgmt.py register cli/examples/code_reviewer_agent.json\n\n# List all agents\nuv run python cli/agent_mgmt.py list\n\n# Test agent\nuv run python cli/agent_mgmt.py test /code-reviewer\n```\n\n## MCP Client Authentication\n\nThe client supports two authentication methods:\n\n### 1. M2M (Machine-to-Machine) Authentication with `mcp-gateway-m2m`\nThe primary M2M account `mcp-gateway-m2m` is auto-configured. Set environment variables:\n```bash\nexport CLIENT_ID=mcp-gateway-m2m\nexport CLIENT_SECRET=\nexport KEYCLOAK_URL=http://localhost:8080\nexport KEYCLOAK_REALM=mcp-gateway\n```\n\nOr use the auto-generated token from `mcp-gateway-m2m`:\n```bash\nsource <(python3 -c \"import json; d=json.load(open('.oauth-tokens/ingress.json')); print('TOKEN=' + d['access_token'])\")\n```\n\n### 2. Ingress Token Authentication\nThe client will automatically load ingress tokens from `.oauth-tokens/ingress.json` if M2M credentials are not available. This token comes from the `mcp-gateway-m2m` service account.\n\n## Basic Commands\n\n### Test Connectivity (Ping)\n```bash\n# Ping the default gateway\nuv run cli/mcp_client.py ping\n\n# Ping a specific endpoint\nuv run cli/mcp_client.py --url http://localhost/currenttime/mcp ping\n```\n\n### List Available Tools\n```bash\n# List tools from the default gateway\nuv run cli/mcp_client.py list\n\n# List tools from a specific server\nuv run cli/mcp_client.py --url http://localhost/currenttime/mcp list\n```\n\n## Server Management Commands\n\n### List All Registered Services\n```bash\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool list_services \\\n --args '{}'\n```\n\nReturns a dictionary containing:\n- `services`: List of service information with details like name, path, status\n- `total_count`: Total number of registered services\n\n### Register a New Service\n```bash\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool register_service \\\n --args '{\n \"server_name\": \"Minimal Server\",\n \"path\": \"/minimal-server\",\n \"proxy_pass_url\": \"http://minimal-server:8000\",\n \"description\": \"A minimal MCP server example\",\n \"tags\": [\"example\", \"minimal\"],\n \"num_tools\": 2,\n \"num_stars\": 0,\n \"is_python\": true,\n \"license\": \"MIT\"\n }'\n```\n\n**Register from a JSON file:**\n```bash\n# Register a service using configuration from a JSON file\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool register_service \\\n --args \"$(cat cli/examples/server-config.json)\"\n```\n\n**Required parameters:**\n- `server_name`: Display name for the server\n- `path`: Unique URL path prefix (must start with '/')\n- `proxy_pass_url`: Internal URL where the MCP server is running\n\n**Optional parameters:**\n- `description`: Description of the server (default: \"\")\n- `tags`: List of tags for categorization (default: null)\n- `num_tools`: Number of tools provided (default: 0)\n- `num_stars`: Star rating for the server (default: 0)\n- `is_python`: Whether implemented in Python (default: false)\n- `license`: License information (default: \"N/A\")\n\n### Remove a Service\n```bash\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool remove_service \\\n --args '{\"service_path\": \"/my-service\"}'\n```\n\n**Example:**\n```bash\n# Remove minimal-server\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool remove_service \\\n --args '{\"service_path\": \"/minimal-server\"}'\n```\n\n### Toggle Service State (Enable/Disable)\n```bash\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool toggle_service \\\n --args '{\"service_path\": \"/my-service\"}'\n```\n\n### Health Check\nGet health status for all registered servers:\n```bash\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool healthcheck \\\n --args '{}'\n```\n\n## Tool Discovery\n\n### Find Tools Using Natural Language\nUse the intelligent tool finder to discover tools based on natural language queries:\n\n```bash\n# Find tools for getting current time\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool intelligent_tool_finder \\\n --args '{\"natural_language_query\": \"get current time in New York\", \"top_n_tools\": 3}'\n\n# Find tools by tags only\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool intelligent_tool_finder \\\n --args '{\"tags\": [\"time\", \"timezone\"], \"top_n_tools\": 5}'\n\n# Combine natural language and tags\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool intelligent_tool_finder \\\n --args '{\n \"natural_language_query\": \"get current time\",\n \"tags\": [\"time\"],\n \"top_k_services\": 3,\n \"top_n_tools\": 5\n }'\n```\n\n**Parameters:**\n- `natural_language_query`: Natural language description (optional if tags provided)\n- `tags`: List of tags to filter by (optional)\n- `top_k_services`: Number of top services to consider (default: 3)\n- `top_n_tools`: Number of best tools to return (default: 1)\n\n## Direct Server Access\n\n### Call Tools on Specific Servers\n\n#### Current Time Service\n```bash\n# Get current time in a specific timezone\nuv run cli/mcp_client.py --url http://localhost/currenttime/mcp call \\\n --tool current_time_by_timezone \\\n --args '{\"tz_name\": \"America/New_York\"}'\n\n# Use default timezone (America/New_York)\nuv run cli/mcp_client.py --url http://localhost/currenttime/mcp call \\\n --tool current_time_by_timezone \\\n --args '{}'\n```\n\n## Command Structure\n\n### General Format\n```bash\nuv run cli/mcp_client.py [--url URL] COMMAND [--tool TOOL_NAME] [--args JSON_ARGS]\n```\n\n### Parameters\n- `--url`: Gateway or server URL (default: `http://localhost/mcpgw/mcp`)\n- `command`: One of `ping`, `list`, or `call`\n- `--tool`: Tool name (required for `call` command)\n- `--args`: Tool arguments as JSON string (for `call` command)\n\n## Examples Summary\n\n### Quick Server Management\n```bash\n# List all services\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call --tool list_services --args '{}'\n\n# Register a new service\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool register_service \\\n --args '{\"server_name\": \"Minimal Server\", \"path\": \"/minimal-server\", \"proxy_pass_url\": \"http://minimal-server:8000\"}'\n\n# Remove a service\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool remove_service \\\n --args '{\"service_path\": \"/minimal-server\"}'\n\n# Toggle service state\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool toggle_service \\\n --args '{\"service_path\": \"/minimal-server\"}'\n\n# Health check all services\nuv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call --tool healthcheck --args '{}'\n```\n\n### Tool Discovery and Invocation\n```bash\n# Find relevant tools\nuv run cli/mcp_client.py call --tool intelligent_tool_finder \\\n --args '{\"natural_language_query\": \"get current time\"}'\n\n# Call a specific tool directly\nuv run cli/mcp_client.py --url http://localhost/currenttime/mcp call \\\n --tool current_time_by_timezone \\\n --args '{\"tz_name\": \"Europe/London\"}'\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **HTTP 403: Access forbidden**\n - Check if your token has the required permissions\n - Verify the scopes.yml configuration includes the tool you're trying to access\n\n2. **HTTP 405: Method Not Allowed**\n - Ensure the server path is correct\n - Verify the server is registered and running\n\n3. **Token Expired**\n - Refresh your authentication token\n - For ingress tokens: Run the token refresh script\n - For M2M: Re-authenticate with credentials\n\n4. **Connection Refused**\n - Check if the target server is running\n - Verify the proxy_pass_url in the service registration\n\n## Notes\n\n- All service paths must start with '/'\n- Tool arguments must be valid JSON\n- The gateway URL defaults to `http://localhost/mcpgw/mcp`\n- Direct server access bypasses the gateway and connects directly to the service" }, { "path": "docs/cognito.md", "content": "# Amazon Cognito Setup Guide for MCP Gateway Registry\n\nThis comprehensive guide covers setting up Amazon Cognito for both user identity and agent identity authentication modes with the MCP Gateway Registry system.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Amazon Cognito Setup](#amazon-cognito-setup)\n3. [Agent Uses User Identity Mode](#agent-uses-user-identity-mode)\n4. [Agent Uses Its Own Identity Mode](#agent-uses-its-own-identity-mode)\n5. [Environment Configuration Examples](#environment-configuration-examples)\n6. [Testing and Troubleshooting](#testing-and-troubleshooting)\n\n## Overview\n\nThe MCP Gateway Registry supports two distinct authentication modes:\n\n- **Agent Uses User Identity Mode**: Agents act on behalf of users using OAuth 2.0 PKCE flow with session cookies\n- **Agent Uses Its Own Identity Mode**: Agents have their own identity using Machine-to-Machine (M2M) authentication with JWT tokens\n\nBoth modes integrate with Amazon Cognito as the Identity Provider (IdP) and use the same scope-based authorization system defined in [`auth_server/scopes.yml`](../auth_server/scopes.yml).\n\n## Amazon Cognito Setup\n\nThis section covers setting up Amazon Cognito for two distinct authentication modes used by the MCP Gateway Registry system.\n\n### User Group Setup (For Users and Agents Using User Identity)\n\nThis setup is for users who will authenticate through the web interface and for agents that act on behalf of users using their identity and permissions.\n\n#### Step 1: Create User Pool\n\n1. **Navigate to Amazon Cognito Console**\n - Go to [Amazon Cognito Console](https://console.aws.amazon.com/cognito/)\n - Select your desired AWS region (e.g., `us-east-1`)\n - Click the **\"Create User pool\"** button\n\n2. **Configure Application Type**\n - Select **\"Traditional Web App\"** for application type\n - Name your application **\"MCP Gateway\"**\n\n3. **Configure Sign-in Options**\n - Under \"Options for sign-in identifiers\", select:\n - **Email**\n - **Username**\n - **Phone number**\n\n4. **Set Required Attributes**\n - Under \"Required attributes for sign-up\", select:\n - **Email** (required)\n\n5. **Create User Directory**\n - Click on **\"Create User Directory\"**\n - Once created, click on **\"Go to overview\"** (typically on the bottom right corner of the page)\n\n#### Step 2: Configure App Client for Users\n\n1. **Access App Clients**\n - Click on **\"App Clients\"** in the left navigation\n - Click on **\"MCP Gateway\"** from the App Client list\n\n2. **Copy Client Credentials**\n - Copy and paste the **Client ID** and **Client Secret**\n - Note them separately - you'll need them later for `.env` files for the MCP Gateway and agent. \n\n3. **Configure Login Pages**\n - Click on **\"Login Pages\"** and then **\"Edit\"**\n\n4. **Set Callback URLs**\n - For the allowed callback URLs, add the following 4 URLs:\n - `http://localhost:9090/callback` - for creating a session cookie for auth flow where the agent uses a user's identity\n - `http://localhost/oauth2/callback/cognito` - for testing without an https endpoint and cert\n - `http://localhost:8888/oauth2/callback/cognito` - for local development and testing with frontend\n - `https://your_mcp_gateway_domain_name/oauth2/callback/cognito` - for https with SSL cert (replace mcpgateway.ddns.net with your_secure_domain)\n\n5. **Configure OpenID Connect Scopes**\n - From OpenID Connect Scopes section:\n - **Email**, **openid**, **phone** would already be there\n - **Remove** phone\n - **Add** profile\n - **Add** aws.cognito.signin.user.admin\n\n#### Step 3: Create Users and Groups\n\n1. **Create a User**\n - Click on **\"Users\"** in the main menu\n - Create a new user with the following settings:\n - Select **email** as identifier\n - **Don't send invitation**\n - Provide **username** and **email address**\n - Mark **email address as verified** (check the checkbox)\n - Choose a desired **username** and set a **password**\n\n2. **Create Admin Group**\n - Create a group called **\"mcp-registry-admin\"**\n - Leave everything as default\n\n3. **Add User to Group**\n - Once the group is created, click on the **group name**\n - Click on **\"Add user to group\"**\n - Add the user you created in the previous step to this group\n\n### Machine-to-Machine (M2M) Setup (For Agents Using Their Own Identity)\n\nThis setup is for agents that have their own identity and authenticate using client credentials flow without user interaction.\n\n#### Step 1: Create M2M App Client\n\n1. **Create Machine-to-Machine App Client**\n - In your user pool, go to \"App integration\" tab\n - Click **\"Create app client\"**\n - **App type**: Select \"Machine to Machine\"\n - **App client name**: Enter `Agent` (or `My AI Assistant` or any name that reflects what the agent will do)\n - **Client secret**: Select \"Generate a client secret\"\n - **Copy and save** the **Client ID** and **Client Secret** - you'll need these for the [`agents/.env.agent`](../agents/.env.agent) file\n\n#### Step 2: Create Resource Server and Custom Scopes\n\n1. **Navigate to Domain Settings**\n - In the sidebar, click on **\"Branding\"**\n - Under Branding, click on **\"Domain\"**\n\n2. **Create Resource Server**\n - Click **\"Create resource server\"**\n - **Name**: `mcp-servers-unrestricted`\n - **Identifier**: `mcp-servers-unrestricted` (use the same name as identifier)\n\n3. **Add Custom Scopes**\n - Add two custom scopes:\n - `read`: \"Read access to all MCP servers\"\n - `execute`: \"Execute access to all MCP servers\"\n - This group gives your agent access to all MCP servers and tools accessible via the MCP Gateway\n - See [`auth_server/scopes.yml`](../auth_server/scopes.yml) file for more details on scope configuration\n\n#### Step 3: Assign Scopes to Agent App Client\n\n1. **Configure Agent Client Scopes**\n - Go back to **\"App Clients\"**\n - Select your **Agent** app client\n - Click on **\"Login Pages\"** → **\"Edit\"**\n\n2. **Select Custom Scopes**\n - Under \"Custom scopes\" section, select:\n - `mcp-servers-unrestricted/read`\n - `mcp-servers-unrestricted/execute`\n - Click **\"Save changes\"**\n\n\n## Agent Uses User Identity Mode\n\nThis mode enables agents to act on behalf of users, using their Cognito identity and group memberships for authorization.\n\n### Configuration Steps\n\n#### 1. Cognito User Pool Configuration\n\nEnsure your Cognito User Pool is configured with:\n- **PKCE-enabled app client** (public client without secret)\n- **Hosted UI enabled** with appropriate callback URLs\n- **User groups** mapped to MCP scopes via [`scopes.yml`](../auth_server/scopes.yml)\n\n#### 2. OAuth 2.0 PKCE Flow Setup\n\nThe PKCE (Proof Key for Code Exchange) flow is implemented in [`agents/cli_user_auth.py`](../agents/cli_user_auth.py):\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as CLI Auth Tool\n participant Browser\n participant Cognito as Amazon Cognito\n participant Agent as MCP Agent\n\n User->>CLI: Run cli_user_auth.py\n CLI->>CLI: Generate PKCE verifier/challenge\n CLI->>Browser: Open Cognito hosted UI\n Browser->>Cognito: User login\n Cognito->>Browser: Authorization code\n Browser->>CLI: Callback with code\n CLI->>Cognito: Exchange code for tokens\n Cognito->>CLI: Access token + user info\n CLI->>CLI: Create session cookie\n CLI->>User: Save cookie to ~/.mcp/session_cookie\n User->>Agent: Run agent with --use-session-cookie\n Agent->>Agent: Read session cookie\n Agent->>Gateway: MCP requests with cookie header\n```\n\n#### 3. Session Cookie Authentication\n\nThe session cookie contains:\n- **Username**: Cognito username\n- **Groups**: User's Cognito group memberships\n- **Expiration**: 8-hour validity (configurable)\n- **Signature**: Signed with `SECRET_KEY` for security\n\n#### 4. Required Environment Variables\n\nCreate `.env.user` file in the `agents/` directory:\n\n```bash\n# Cognito Configuration\nCOGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX\nCOGNITO_CLIENT_ID=your-public-client-id\nCOGNITO_CLIENT_SECRET=your-client-secret\nSECRET_KEY=your-secret-key-matching-registry\n\n# Optional: Custom domain\nCOGNITO_DOMAIN=your-custom-domain\n\n# AWS Region\nAWS_REGION=us-east-1\n\n# Registry URL (for callback configuration)\nREGISTRY_URL=http://localhost:7860\n```\n\n#### 5. CLI Authentication Tool Usage\n\nRun the CLI authentication tool to obtain a session cookie:\n\n```bash\n# Navigate to agents directory\ncd agents/\n\n# Run CLI authentication\npython cli_user_auth.py\n\n# This will:\n# 1. Open your browser to Cognito hosted UI\n# 2. After login, capture the authorization code\n# 3. Exchange code for user information\n# 4. Create and save session cookie to ~/.mcp/session_cookie\n```\n\n#### 6. Agent Usage with Session Cookie\n\n```bash\n# Use agent with session cookie authentication\npython agent.py \\\n --use-session-cookie \\\n --message \"What time is it in Tokyo?\" \\\n --mcp-registry-url http://localhost/mcpgw/sse\n```\n\n## Agent Uses Its Own Identity Mode\n\nThis mode enables agents to have their own identity using Machine-to-Machine (M2M) authentication.\n\n### Configuration Steps\n\n#### 1. Machine-to-Machine Authentication Setup\n\nM2M authentication uses the OAuth 2.0 Client Credentials flow:\n\n```mermaid\nsequenceDiagram\n participant Agent as MCP Agent\n participant Cognito as Amazon Cognito\n participant Gateway as MCP Gateway\n\n Agent->>Cognito: Client credentials request\n Note over Agent,Cognito: client_id + client_secret + scopes\n Cognito->>Agent: JWT access token\n Agent->>Gateway: MCP requests with JWT token\n Gateway->>Cognito: Validate JWT token\n Cognito->>Gateway: Token valid + scopes\n Gateway->>Agent: MCP response\n```\n\n#### 2. Client Credentials Flow Configuration\n\nThe M2M flow is implemented in [`auth_server/cognito_utils.py`](../auth_server/cognito_utils.py):\n\n1. **Token Request**: Agent requests token using client credentials\n2. **JWT Token**: Cognito issues JWT token with embedded scopes\n3. **Token Validation**: Auth server validates JWT signature and claims\n4. **Scope Enforcement**: Access granted based on token scopes\n\n#### 3. JWT Token Handling\n\nJWT tokens contain:\n- **Issuer**: Cognito User Pool issuer URL\n- **Client ID**: M2M app client identifier\n- **Scopes**: Granted scopes for MCP server access\n- **Expiration**: Token validity period (typically 1 hour)\n\n#### 4. Required Environment Variables\n\nCreate `.env.agent` file in the `agents/` directory:\n\n```bash\n# Cognito M2M Configuration\nCOGNITO_CLIENT_ID=your-confidential-client-id\nCOGNITO_CLIENT_SECRET=your-client-secret\nCOGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX\n\n# AWS Region\nAWS_REGION=us-east-1\n\n# MCP Registry URL\nMCP_REGISTRY_URL=http://localhost/mcpgw/sse\n```\n\n#### 5. Agent Usage with M2M Authentication\n\n```bash\n# Use agent with M2M authentication (default mode)\npython agent.py \\\n --message \"What time is it in Tokyo?\" \\\n --mcp-registry-url http://localhost/mcpgw/sse\n```\n\n### Common Configuration Pitfalls and Solutions\n\n#### 1. Callback URL Mismatch\n\n**Problem**: `redirect_uri_mismatch` error during OAuth flow\n\n**Solution**: Ensure all 4 callback URLs are present in your Cognito configuration:\n- `http://localhost:9090/callback` - for creating a session cookie for auth flow where the agent uses a user's identity\n- `http://localhost/oauth2/callback/cognito` - for testing without an https endpoint and cert\n- `http://localhost:8888/oauth2/callback/cognito` - for local development and testing with frontend\n- `https://mcpgateway.ddns.net/oauth2/callback/cognito` - for https with SSL cert (replace mcpgateway.ddns.net with your_secure_domain)\n\n#### 2. Secret Key Mismatch\n\n**Problem**: Session cookie validation fails\n\n**Solution**: Ensure `SECRET_KEY` in `.env.user` matches the registry's `SECRET_KEY` in `.env` in the project root directory:\n```bash\n# Generate a new secret key\npython -c 'import secrets; print(secrets.token_hex(32))'\n\n# Use the same key in both .env and registry configuration\n```\n\n#### 3. Scope Configuration Issues\n\n**Problem**: Access denied errors despite valid authentication\n\n**Solution**: Verify scope mappings in [`scopes.yml`](../auth_server/scopes.yml):\n- Check group mappings match Cognito groups\n- Ensure server/tool permissions are correctly defined\n- Verify M2M client has required custom scopes\n\n#### 4. JWT Token Validation Errors\n\n**Problem**: M2M authentication fails with token validation errors\n\n**Solution**: Check the following:\n- Client ID and secret are correct\n- User Pool ID format is correct (e.g., `us-east-1_ABC123DEF`)\n- AWS region matches User Pool region\n- Custom scopes are properly configured in resource server\n\n## Testing and Troubleshooting\n\n### How to Verify Cognito Configuration\n\n#### 1. Test User Authentication Flow\n\n```bash\n# Test CLI authentication\ncd agents/\npython cli_user_auth.py\n\n# Expected output:\n# - Browser opens to Cognito hosted UI\n# - After login, callback succeeds\n# - Session cookie saved to ~/.mcp/session_cookie\n```\n\n#### 2. Test M2M Authentication Flow\n\n```bash\n# Test M2M token generation\ncd auth_server/\npython -c \"\nfrom cognito_utils import generate_token\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv('../agents/.env.agent')\ntoken = generate_token(\n os.environ['COGNITO_CLIENT_ID'],\n os.environ['COGNITO_CLIENT_SECRET'],\n os.environ['COGNITO_USER_POOL_ID'],\n os.environ['AWS_REGION']\n)\nprint('Token generated successfully:', token[:50] + '...')\n\"\n```\n\n#### 3. Test Agent Authentication\n\n```bash\n# Test user identity mode\npython agent.py --use-session-cookie --message \"test message\"\n\n# Test agent identity mode\npython agent.py --message \"test message\"\n```\n\n### Common Authentication Errors and Solutions\n\n#### Error: `Invalid redirect URI`\n\n**Cause**: Callback URL not registered in Cognito app client\n\n**Solution**:\n1. Go to Cognito console → App integration → App clients\n2. Edit your app client\n3. Add the correct callback URL to \"Allowed callback URLs\"\n\n#### Error: `Session cookie has expired`\n\n**Cause**: Session cookie is older than 8 hours\n\n**Solution**:\n```bash\n# Re-authenticate to get fresh session cookie\npython cli_user_auth.py\n```\n\n#### Error: `Access denied for server/tool`\n\n**Cause**: User/agent lacks required scopes for the requested resource\n\n**Solution**:\n1. Check user's group membership in Cognito\n2. Verify group mappings in [`scopes.yml`](../auth_server/scopes.yml)\n3. For M2M, check client's assigned scopes in Cognito\n\n#### Error: `JWT token validation failed`\n\n**Cause**: Token signature validation or claims validation failed\n\n**Solution**:\n1. Verify client credentials are correct\n2. Check User Pool ID format and region\n3. Ensure token hasn't expired\n4. Verify JWKS endpoint is accessible\n\n### Testing Both Authentication Modes\n\n#### User Identity Mode Test\n\n```bash\n# 1. Authenticate user\npython cli_user_auth.py\n\n# 2. Test with session cookie\npython agent.py \\\n --use-session-cookie \\\n --message \"What MCP servers are available?\" \\\n --mcp-registry-url http://localhost/mcpgw/sse\n\n# Expected: Agent uses user's permissions based on Cognito groups\n```\n\n#### Agent Identity Mode Test\n\n```bash\n# Test with M2M authentication\ncd agents\npython agent.py \\\n --message \"What MCP tools are available?\" \\\n --mcp-registry-url http://localhost/mcpgw/sse\n\n# Expected: Agent uses its own permissions based on assigned scopes\n```\n\n### Debugging Authentication Flows\n\n#### Enable Debug Logging\n\n```bash\n# Run agent with debug logging\npython agent.py --message \"test\" --mcp-registry-url http://localhost/mcpgw/sse\n```\n\n#### Check Auth Server Logs\n\n```bash\n# View auth server logs for validation details\ndocker-compose logs -f auth-server\n\n# Look for:\n# - Token validation attempts\n# - Scope mapping results\n# - Access control decisions\n```\n\n#### Verify Scope Mappings\n\n```bash\n# Test scope mapping logic\ncd auth_server/\npython -c \"\nimport yaml\nfrom server import map_cognito_groups_to_scopes\n\n# Load scopes config\nwith open('scopes.yml', 'r') as f:\n config = yaml.safe_load(f)\n\n# Test group mapping\ngroups = ['mcp-registry-user']\nscopes = map_cognito_groups_to_scopes(groups)\nprint(f'Groups {groups} mapped to scopes: {scopes}')\n\"\n```\n\n## Related Documentation\n\n- [Main Authentication Guide](auth.md) - Overview of the authentication architecture\n- [Scopes Configuration](../auth_server/scopes.yml) - Detailed scope and permission definitions\n- [Environment Template](../.env.template) - Complete environment configuration template\n- [Agent Implementation](../agents/agent.py) - Reference agent implementation\n- [CLI Authentication Tool](../agents/cli_user_auth.py) - User authentication utility\n\n## Support and Troubleshooting\n\nFor additional support:\n\n1. **Check Logs**: Review auth server and agent logs for detailed error messages\n2. **Verify Configuration**: Ensure all environment variables are correctly set\n3. **Test Components**: Use the testing procedures above to isolate issues\n4. **Review Scopes**: Verify scope mappings match your intended access control\n\nThis guide provides comprehensive coverage of Amazon Cognito setup for both authentication modes. Follow the step-by-step instructions and use the troubleshooting section to resolve common issues.\n\n## Saving Client Credentials to Agent Environment Files\n\nAfter completing the Cognito setup and obtaining your client ID and secret, you need to configure the agent environment files to use these credentials.\n\n### Step 1: Copy Template to Environment File\n\nNavigate to the `agents/` directory and copy the template file:\n\n```bash\ncd agents/\ncp .env.template .env.user\n```\n\n### Step 2: Configure Client Credentials\n\nEdit the [`agents/.env.user`](../agents/.env.user) file with your Cognito credentials obtained from the [User Group Setup](#user-group-setup-for-users-and-agents-using-user-identity) section:\n\n```bash\n# Cognito Authentication Configuration\n# Copy this file to .env and fill in your actual values\n\n# Cognito App Client ID (from Step 2 of User Group Setup)\nCOGNITO_CLIENT_ID=your_actual_cognito_client_id_here\n\n# Cognito App Client Secret (from Step 2 of User Group Setup)\nCOGNITO_CLIENT_SECRET=your_actual_cognito_client_secret_here\n\n# Cognito User Pool ID (from Step 1 of User Group Setup)\nCOGNITO_USER_POOL_ID=your_actual_cognito_user_pool_id_here\n\n# AWS Region for Cognito\nAWS_REGION=us-east-1\n\n# Cognito Domain (without https:// prefix, just the domain name)\n# Example: mcp-gateway or your-custom-domain\n# COGNITO_DOMAIN=\n\n# Secret key for session cookie signing (must match registry SECRET_KEY), string of hex characters\n# To generate: python -c 'import secrets; print(secrets.token_hex(32))'\nSECRET_KEY=your-secret-key-here\n\n# Either http://localhost:8000 or the HTTPS URL of your deployed MCP Gateway\nREGISTRY_URL=your_registry_url_here\n```\n\n### Step 3: Replace Placeholder Values\n\nReplace the following placeholder values with your actual Cognito configuration:\n\n1. **COGNITO_CLIENT_ID**: The Client ID copied from Step 2 of the [User Group Setup](#step-2-configure-app-client-for-users)\n2. **COGNITO_CLIENT_SECRET**: The Client Secret copied from Step 2 of the [User Group Setup](#step-2-configure-app-client-for-users)\n3. **COGNITO_USER_POOL_ID**: Your User Pool ID from Step 1 of the [User Group Setup](#step-1-create-user-pool)\n4. **AWS_REGION**: The AWS region where your Cognito User Pool is located (e.g., `us-east-1`)\n5. **SECRET_KEY**: Generate a secure secret key using: `python -c 'import secrets; print(secrets.token_hex(32))'`\n6. **REGISTRY_URL**: Your MCP Gateway URL (e.g., `http://localhost:7860` for local development)\n\n### Step 4: Verify Configuration\n\nAfter saving the file, verify your configuration by testing the authentication flow:\n\n```bash\n# Test user authentication\npython cli_user_auth.py\n\n# Test agent with session cookie\npython agent.py --use-session-cookie --message \"test authentication\"\n```\n\n### Important Notes\n\n- **Security**: Keep your `.env.user` file secure and never commit it to version control\n- **Secret Key Matching**: Ensure the `SECRET_KEY` in `agents/.env.user` matches the `SECRET_KEY` in your main registry `.env` file\n- **Multiple Agents**: If you have multiple agent instances, each can use the same `.env.user` file or have separate configuration files\n- **Environment Separation**: Use different `.env.user` files for different environments (development, staging, production)\n\nThis completes the client credential configuration for your MCP Gateway agents using Amazon Cognito authentication." }, { "path": "docs/complete-setup-guide.md", "content": "# Complete Setup Guide: MCP Gateway & Registry from Scratch\n\nThis guide provides a comprehensive, step-by-step walkthrough for setting up the MCP Gateway & Registry on a fresh AWS EC2 instance. Perfect for first-time users who want to get the system running from zero.\n\n> **SECURITY WARNING**\n>\n> The examples in this document use placeholder credentials for demonstration purposes only.\n> **NEVER use these example values in production.**\n>\n> Always generate unique, secure credentials and store them in:\n> - AWS Secrets Manager (production)\n> - Environment variables (development)\n> - `.env` files (local only, never commit)\n\n## Table of Contents\n1. [AWS EC2 Instance Setup](#1-aws-ec2-instance-setup)\n2. [Initial System Configuration](#2-initial-system-configuration)\n3. [Installing Prerequisites](#3-installing-prerequisites)\n4. [Cloning and Configuring the Project](#4-cloning-and-configuring-the-project)\n5. [Setting Up Keycloak Identity Provider](#5-setting-up-keycloak-identity-provider)\n6. [Starting the MCP Gateway Services](#6-starting-the-mcp-gateway-services)\n7. [Storage Backend Setup](#7-storage-backend-setup-optional)\n - [MongoDB CE Setup (Recommended)](#mongodb-ce-setup-recommended-for-local-development)\n8. [Verification and Testing](#8-verification-and-testing)\n9. [Configuring AI Agents and Coding Assistants](#9-configuring-ai-agents-and-coding-assistants)\n10. [Troubleshooting](#10-troubleshooting)\n11. [Next Steps](#11-next-steps)\n\n---\n\n## 1. AWS EC2 Instance Setup\n\n### Launch EC2 Instance\n\n1. **Log into AWS Console** and navigate to EC2\n2. **Click \"Launch Instance\"** and configure:\n - **Name**: `mcp-gateway-server`\n - **AMI**: Ubuntu Server 24.04 LTS (or latest Ubuntu LTS)\n - **Instance Type**: `t3.2xlarge` (8 vCPU, 32GB RAM)\n - **Key Pair**: Create new or select existing SSH key\n - **Storage**: 100GB gp3 SSD\n\n3. **Network Settings**:\n - VPC: Default or your custom VPC\n - Subnet: Public subnet with auto-assign public IP\n - **Security Group**: Create new with following rules:\n ```\n Inbound Rules:\n - SSH (22): Your IP address\n - HTTP (80): 0.0.0.0/0 (or restrict as needed)\n - HTTPS (443): 0.0.0.0/0 (or restrict as needed)\n - Custom TCP (7860): 0.0.0.0/0 (Registry UI)\n - Custom TCP (8080): 0.0.0.0/0 (Keycloak Admin)\n - Custom TCP (8000): 0.0.0.0/0 (Auth Server)\n ```\n\n4. **Launch the instance** and wait for it to be running\n\n### Connect to Your Instance\n\n```bash\n# From your local terminal\nssh -i your-key.pem ubuntu@your-instance-public-ip\n\n# Example:\nssh -i ~/.ssh/mcp-gateway-key.pem ubuntu@ec2-54-123-456-789.compute-1.amazonaws.com\n```\n\n---\n\n## 2. Initial System Configuration\n\nOnce connected to your EC2 instance:\n\n```bash\n# Update system packages\nsudo apt-get update && sudo apt-get upgrade -y\n\n# Set timezone (optional but recommended)\nsudo timedatectl set-timezone America/New_York # Change to your timezone\n\n# Create a working directory\nmkdir -p ~/workspace\ncd ~/workspace\n```\n\n---\n\n## 3. Installing Prerequisites\n\n### Install Docker and Docker Compose\n\n```bash\n# Install Docker\nsudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common\n\n# Add Docker's official GPG key\ncurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg\n\n# Add Docker repository (for Ubuntu 24.04 Noble and later)\necho \"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable\" | sudo tee /etc/apt/sources.list.d/docker.list\n\n# Update package list\nsudo apt-get update\n\n# Install Docker Engine and CLI\nsudo apt-get install -y docker-ce docker-ce-cli containerd.io\n\n# Add user to docker group\nsudo usermod -aG docker $USER\n\n# Apply the group change immediately for current shell\nnewgrp docker\n\n# Verify Docker works without sudo\ndocker --version\n# Expected output: Docker version 27.x.x or higher\n\n# Test Docker permissions (MUST work without sudo)\ndocker run hello-world\n# Should show \"Hello from Docker!\" message\n\n# Install Docker Compose V2 Plugin (REQUIRED)\nsudo apt-get install -y docker-compose-plugin\n\n# Verify Docker Compose V2 installation\ndocker compose version\n# Expected output: Docker Compose version v2.x.x or higher\n\n# Note: The build_and_run.sh script requires Docker Compose V2 (docker compose)\n# Do NOT use the old standalone docker-compose v1\n```\n\n### Install Node.js and npm\n\n```bash\n# Install Node.js 20.x (LTS)\ncurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -\nsudo apt-get install -y nodejs\n\n# Verify installations\nnode --version # Should show v20.x.x\nnpm --version # Should show 10.x.x\n```\n\n### Install Python and UV (Python Package Manager)\n\n```bash\n# Install Python 3.14\nsudo apt-get install -y python3.14 python3.14-venv python3-pip\n\n# Install UV package manager\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Add UV to PATH\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\nsource ~/.bashrc\n\n# Verify UV installation\nuv --version\n# Expected output: uv 0.x.x\n```\n\n### Install Additional Tools\n\n```bash\n# Install Git (should already be installed, but just in case)\nsudo apt-get install -y git\n\n# Install jq for JSON processing\nsudo apt-get install -y jq\n\n# Install curl and wget\nsudo apt-get install -y curl wget\n\n# Install net-tools for network debugging\nsudo apt-get install -y net-tools\n```\n\n---\n\n## 4. Cloning and Configuring the Project\n\n### Clone the Repository\n\n```bash\ncd ~/workspace\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\n\n# Verify you're in the right directory\nls -la\n# You should see files like docker-compose.yml, .env.example, README.md, etc.\n```\n\n### Setup Python Virtual Environment\n\n```bash\n# Create and activate Python virtual environment\nuv sync\nsource .venv/bin/activate\n\n# Verify the virtual environment is active\nwhich python\n# Should show: /home/ubuntu/workspace/mcp-gateway-registry/.venv/bin/python\n```\n\n### Initial Environment Configuration\n\n```bash\n# Copy the example environment file\ncp .env.example .env\n\n# Generate a secure SECRET_KEY and set it in the .env file\nSECRET_KEY=$(python3 -c \"import secrets; print(secrets.token_urlsafe(64))\")\n# Replace SECRET_KEY whether it's commented (#) or not\nsed -i \"s/^#*\\s*SECRET_KEY=.*/SECRET_KEY=$SECRET_KEY/\" .env\n\n# Verify the SECRET_KEY was set correctly\necho \"Generated SECRET_KEY: $SECRET_KEY\"\n\n# Open the file for editing\nnano .env\n```\n\nThe SECRET_KEY has been automatically generated and added to your `.env` file. This key is essential for session security between the auth-server and registry services.\n\nFor now, make these additional essential changes in the `.env` file:\n\n```bash\n# Set authentication provider to Keycloak\nAUTH_PROVIDER=keycloak #Do not change\n\n# Set a secure admin password (change this!)\n# This is used for Keycloak API authentication during setup\nKEYCLOAK_ADMIN_PASSWORD=YourSecureAdminPassword123! # change me\n\n# CRITICAL: Set INITIAL_ADMIN_PASSWORD to the SAME VALUE as KEYCLOAK_ADMIN_PASSWORD\n# This is used to set the password for the initial admin user in the realm\n# THESE MUST MATCH - see Step 5 for details\nINITIAL_ADMIN_PASSWORD=YourSecureAdminPassword123! # change me\n\n# Set Keycloak database password (change this!)\nKEYCLOAK_DB_PASSWORD=SecureKeycloakDB123! # change me\n\n# Leave other Keycloak settings as default for now\nKEYCLOAK_URL=http://localhost:8080\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_CLIENT_ID=mcp-gateway-client\n\n# Session Cookie Security Configuration\n# CRITICAL: These settings must match your deployment environment\n\n# For LOCAL DEVELOPMENT (accessing via http://localhost):\nSESSION_COOKIE_SECURE=false # MUST be false for HTTP access\n\n# For PRODUCTION with HTTPS (accessing via https://your-domain.com):\n# SESSION_COOKIE_SECURE=true # Uncomment and set to true\n\n# Cookie domain (leave empty for most deployments)\nSESSION_COOKIE_DOMAIN= # Empty = cookie scoped to exact host only\n\n# Save and exit (Ctrl+X, then Y, then Enter)\n```\n\n**Important**:\n- Remember the passwords you set here - you'll need to use the same ones in Step 5!\n- **CRITICAL**: `KEYCLOAK_ADMIN_PASSWORD` and `INITIAL_ADMIN_PASSWORD` MUST be set to the same value. See Step 5 for details about why this is important.\n- **SESSION_COOKIE_SECURE**: For local development (HTTP), this MUST be `false`. Setting it to `true` will cause login to fail because cookies with `secure=true` are only sent over HTTPS connections.\n- For production deployments with HTTPS, change `SESSION_COOKIE_SECURE=true` before starting services.\n\n### Download Required Embeddings Model\n\nThe MCP Gateway requires a sentence-transformers model for intelligent tool discovery. Download it to the shared models directory:\n\n```bash\n# Download the embeddings model (this may take a few minutes)\nhf download sentence-transformers/all-MiniLM-L6-v2 --local-dir ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2\n\n# Verify the model was downloaded\nls -la ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2/\n# You should see model files like model.safetensors, config.json, etc.\n```\n\n**Note**: This command automatically creates the necessary directory structure and downloads all required model files (~90MB).\n\n---\n\n## 5. Setting Up Keycloak Identity Provider\n\nKeycloak provides authentication with support for both human users and AI agents.\n\n### Set Keycloak Passwords\n\n**Important**: These environment variables will override the values in your `.env` file. Use the SAME passwords you configured in Step 4!\n\n```bash\n# Use the SAME passwords you set in the .env file in Step 4!\n# Replace these with your actual passwords from Step 4\nexport KEYCLOAK_ADMIN_PASSWORD=\"YourSecureAdminPassword123!\"\nexport KEYCLOAK_DB_PASSWORD=\"SecureKeycloakDB123!\"\n\n# Verify they're set correctly\necho \"Admin Password: $KEYCLOAK_ADMIN_PASSWORD\"\necho \"DB Password: $KEYCLOAK_DB_PASSWORD\"\n```\n\n**Critical**: These passwords MUST match what you set in the `.env` file in Step 4. If they don't match, Keycloak initialization will fail!\n\n### Important: Admin Password Configuration\n\nWhen you set up Keycloak, you need to configure TWO admin password variables in your `.env` file:\n\n1. **`KEYCLOAK_ADMIN_PASSWORD`** - Used to authenticate with the Keycloak admin API during initialization\n2. **`INITIAL_ADMIN_PASSWORD`** - Used to set the password for the initial admin user created in the mcp-gateway realm\n\n**These MUST be set to the SAME VALUE** for proper Keycloak initialization:\n\n```bash\n# In your .env file (Step 4), set these to the SAME password:\nKEYCLOAK_ADMIN_PASSWORD=YourSecureAdminPassword123!\nINITIAL_ADMIN_PASSWORD=YourSecureAdminPassword123! # MUST match KEYCLOAK_ADMIN_PASSWORD\n```\n\nIf these passwords don't match:\n- The Keycloak admin user will be created with `INITIAL_ADMIN_PASSWORD`\n- But API authentication during setup uses `KEYCLOAK_ADMIN_PASSWORD`\n- This mismatch will cause authentication failures during realm initialization\n\n**Best Practice**: Use the same secure password for both variables during setup.\n\n### Start Keycloak and PostgreSQL\n\nFirst, ensure Docker is installed by following the [Installing Prerequisites](#3-installing-prerequisites) section.\n\n**Fresh Install Recommended**: If you've previously run the stack with different credentials, you should remove the old database volume to avoid password mismatch errors:\n```bash\n# Remove any existing keycloak database volume (skip if this is a fresh install)\ndocker compose down keycloak keycloak-db\ndocker volume rm mcp-gateway-registry_keycloak_db_data 2>/dev/null || true\n```\n\n```bash\n# Start only the database and Keycloak services first\ndocker compose up -d keycloak-db keycloak\n\n# Check if services are starting\ndocker compose ps\n\n# Monitor logs to see when Keycloak is ready\ndocker compose logs -f keycloak\n# Wait for message: \"Keycloak 25.x.x started in xxxms\"\n# Press Ctrl+C to exit logs when you see this message\n```\n\n**Important**: Wait at least 2-3 minutes for Keycloak to fully initialize before proceeding.\n\n**Note about Health Status**: The Keycloak container may show as \"unhealthy\" in `docker ps` output when running in development mode. This is normal and won't affect functionality. You can verify Keycloak is working by running:\n```bash\ncurl http://localhost:8080/realms/master\n# Should return JSON with realm information\n```\n\n### Disable SSL Requirement for Master Realm\n```bash\n# Note: KEYCLOAK_ADMIN defaults to \"admin\" - ensure KEYCLOAK_ADMIN_PASSWORD is set\nexport KEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\n\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:8080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | \\\n jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:8080/admin/realms/master\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n```\n\n### Initialize Keycloak Configuration\n\n**Important**: This is a two-step process. The initialization script creates the realm and clients but does NOT save the credentials to files.\n\n```bash\n# Make the setup script executable\nchmod +x keycloak/setup/init-keycloak.sh\n\n# Step 1: Run the Keycloak initialization\n./keycloak/setup/init-keycloak.sh\n\n# Expected output:\n# ✓ Waiting for Keycloak to be ready...\n# ✓ Keycloak is ready!\n# ✓ Logged in to Keycloak\n# ✓ Created realm: mcp-gateway\n# ✓ Created clients: mcp-gateway-web and mcp-gateway-m2m\n# ... more success messages ...\n# ✓ Client secrets generated!\n#\n# IMPORTANT: The script will tell you to run get-all-client-credentials.sh\n# to retrieve and save the credentials. This is the next required step!\n\n# Step 2: Disable SSL for Application Realm\n# Note: KEYCLOAK_ADMIN defaults to \"admin\" - ensure KEYCLOAK_ADMIN_PASSWORD is set\nexport KEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\n\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:8080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | \\\n jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:8080/admin/realms/mcp-gateway\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n\n# Step 3: Retrieve and save all client credentials (REQUIRED)\nchmod +x keycloak/setup/get-all-client-credentials.sh\n./keycloak/setup/get-all-client-credentials.sh\n\n# This will:\n# - Connect to Keycloak and retrieve all client secrets\n# - Save credentials to .oauth-tokens/keycloak-client-secrets.txt\n# - Create individual JSON files: .oauth-tokens/.json\n# - Create individual env files: .oauth-tokens/.env\n# - Display a summary of all saved credentials\n\n# Expected output:\n# ✓ Admin token obtained\n# ✓ Found and saved: mcp-gateway-web\n# ✓ Found and saved: mcp-gateway-m2m\n# Files created in: .oauth-tokens/\n```\n\n### Set Up Users and Service Accounts\n\nAfter initializing Keycloak, run the bootstrap script to create default users and M2M service accounts for testing and management:\n\n```bash\n# Make the bootstrap script executable\nchmod +x ./cli/bootstrap_user_and_m2m_setup.sh\n\n# Run the bootstrap script\n./cli/bootstrap_user_and_m2m_setup.sh\n```\n\nThis script creates:\n- **3 Keycloak groups**: `registry-users-lob1`, `registry-users-lob2`, `registry-admins`\n- **6 users for different roles**:\n - **LOB1 users**: `lob1-bot` (M2M service account) and `lob1-user` (human user)\n - **LOB2 users**: `lob2-bot` (M2M service account) and `lob2-user` (human user)\n - **Admin users**: `admin-bot` (M2M service account) and `admin-user` (human user)\n\nAll credentials are automatically generated and saved to the `.oauth-tokens/` directory. User passwords default to the `INITIAL_USER_PASSWORD` value from your `.env` file.\n\n**Next steps**:\n- Review the generated credentials in `.oauth-tokens/`\n- Configure appropriate access scopes in your `scopes.yml` file\n- Use these credentials for testing M2M client flows and human user authentication\n- Log in to the dashboard with human user accounts to verify access\n\n### Create Your First AI Agent Account\n\n```bash\n# Make the agent setup script executable\nchmod +x keycloak/setup/setup-agent-service-account.sh\n\n# Create a test agent with full access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id test-agent \\\n --group mcp-servers-unrestricted\n\n# Create an agent for AI coding assistants (VS Code, cursor, etc.)\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id ai-coding-assistant \\\n --group mcp-servers-unrestricted\n\n# Create an agent with restricted access for registry operations\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id registry-operator \\\n --group mcp-servers-restricted\n\n# Note: The script does not display the credentials at the end.\n# Your Client ID is: agent-test-agent-m2m\n\n# Retrieve and save ALL client credentials (recommended):\n./keycloak/setup/get-all-client-credentials.sh\n\n# This will:\n# - Retrieve credentials for ALL clients in the realm\n# - Save all credentials to .oauth-tokens/keycloak-client-secrets.txt\n# - Create individual JSON files: .oauth-tokens/.json\n# - Create individual env files: .oauth-tokens/.env\n# - Display a summary of all credentials saved\n\n# Or to get just one specific client:\n./keycloak/setup/get-agent-credentials.sh agent-test-agent-m2m\n```\n\n**Important**: Save the Client ID and Client Secret shown in the output. You'll need these to authenticate your AI agents.\n\n### Update .env File with Client Secrets\n\n**Critical Step**: After running `get-all-client-credentials.sh`, you MUST update your `.env` file with the retrieved client secrets:\n\n```bash\n# View the retrieved client secrets\ncat .oauth-tokens/keycloak-client-secrets.txt\n\n# You'll see output like:\n# KEYCLOAK_CLIENT_ID=mcp-gateway-web\n# KEYCLOAK_CLIENT_SECRET=JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv\n#\n# KEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\n# KEYCLOAK_M2M_CLIENT_SECRET=iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo\n\n# Update your .env file with these exact secret values\nnano .env\n\n# Find and update these lines with the actual secret values from above:\n# KEYCLOAK_CLIENT_SECRET=JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv\n# KEYCLOAK_M2M_CLIENT_SECRET=iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo\n\n# Save and exit (Ctrl+X, then Y, then Enter)\n```\n\n**Note**: These secrets are auto-generated by Keycloak and are different each time you run `init-keycloak.sh`. Always use the latest values from `.oauth-tokens/keycloak-client-secrets.txt`.\n\n### Generate Access Tokens for All Keycloak Users and Agents\n\nGenerate access tokens for all configured agents and users:\n\n```bash\n# Generate access tokens for all agents\n./credentials-provider/keycloak/get_m2m_token.py --all-agents\n```\n\nThis will create access token files (both `.json` and `.env` formats) for all Keycloak service accounts in the `.oauth-tokens/` directory.\n\n**Note**: If you want tokens to last longer than the default 5 minutes, see [Configure Token Lifetime](#configure-token-lifetime) before generating tokens.\n\n### Verify Keycloak is Running\n\nOpen a web browser and navigate to:\n```\nhttp://localhost:8080\n```\n\nYou should see the Keycloak login page. You can log in with:\n- Username: `admin`\n- Password: The `KEYCLOAK_ADMIN_PASSWORD` you set earlier\n\n---\n\n## 6. Starting the MCP Gateway Services\n\n### Build and Start All Services\n\n**Important**: After starting services, you MUST complete [Section 7: Storage Backend Setup](#7-storage-backend-setup-optional) before using JWT token generation from the UI. The MongoDB initialization loads required scopes that enable JWT token creation.\n\n```bash\n# Return to project directory\ncd ~/workspace/mcp-gateway-registry\n\n# Activate the virtual environment if not already active\nsource .venv/bin/activate\n\n# Make the build script executable\nchmod +x build_and_run.sh\n\n# Build frontend and start all services using the build script\n./build_and_run.sh\n\n# This script will:\n# - Check for Node.js and npm installation\n# - Build the React frontend in the frontend/ directory\n# - Create necessary local directories\n# - Build Docker images\n# - Start all services with docker-compose\n\n# After the script completes, check all services are running\ndocker-compose ps\n\n# Expected output should show all services as \"Up\":\n# - keycloak-db\n# - keycloak\n# - auth-server\n# - registry\n# - nginx\n# - Various MCP servers (mcp-weather, mcp-time, etc.)\n```\n\n### Monitor Service Logs\n\n```bash\n# View all logs\ndocker-compose logs -f\n\n# Or view specific service logs\ndocker-compose logs -f auth-server\ndocker-compose logs -f registry\ndocker-compose logs -f nginx\n\n# Press Ctrl+C to exit log viewing\n```\n\n### Wait for Services to Initialize\n\n```bash\n# Check if registry is ready\ncurl http://localhost:7860/health\n\n# Expected output:\n# {\"status\":\"healthy\",\"timestamp\":\"...\"}\n```\n\n---\n\n## 7. Storage Backend Setup\n\nThe MCP Gateway Registry supports multiple storage backends for production and development use.\n\n**DEPRECATION WARNING**: The file-based storage backend is deprecated and will be removed in a future release. MongoDB CE is now the recommended approach for local development.\n\n**Storage Backend Options:**\n- **MongoDB CE**: Recommended for local development (see below)\n- **DocumentDB**: Used automatically in production (AWS ECS/EKS deployments)\n- **File-based**: Deprecated - will be removed in future releases\n\n### MongoDB CE Setup (Recommended for Local Development)\n\n**Note**: This section is for local Docker Compose installations using MongoDB Community Edition 8.2. For AWS ECS deployments, DocumentDB is used and initialized automatically.\n\nMongoDB CE provides a production-like environment for local development with replica set support and application-level vector search capabilities.\n\n**Why use MongoDB CE (Recommended):**\n- Production-like environment for local development\n- Testing production workflows locally\n- Multi-instance development environments\n- Feature development requiring database operations\n- Compatibility with DocumentDB for seamless cloud migration\n\n**Setup MongoDB CE:**\n\n```bash\n# 1. Set storage backend in .env\necho \"STORAGE_BACKEND=mongodb-ce\" >> .env\necho \"DOCUMENTDB_HOST=mongodb\" >> .env\necho \"DOCUMENTDB_PORT=27017\" >> .env\necho \"DOCUMENTDB_DATABASE=mcp_registry\" >> .env\necho \"DOCUMENTDB_NAMESPACE=default\" >> .env\necho \"DOCUMENTDB_USE_TLS=false\" >> .env\n\n# 2. Start MongoDB container\ndocker compose up -d mongodb\n\n# 3. Wait for MongoDB to be ready (about 30 seconds for replica set initialization)\nsleep 30\n\n# 4. Initialize collections and indexes\ndocker compose up mongodb-init\n\n# 5. Verify MongoDB setup\ndocker exec mcp-mongodb mongosh --eval \"use mcp_registry; show collections\"\n\n# Expected output should show:\n# - mcp_servers_default\n# - mcp_agents_default\n# - mcp_scopes_default\n# - mcp_embeddings_1536_default\n# - mcp_security_scans_default\n# - mcp_federation_config_default\n\n# 6. Restart auth-server and registry to load scopes and use MongoDB backend\ndocker compose restart auth-server registry\n```\n\n**Important**: The auth-server must be restarted after mongodb-init to load the JWT token scopes from MongoDB. Without this step, JWT token generation from the UI will fail with \"no scopes configured\" error.\n\n**MongoDB CE Features:**\n- Replica set configuration for production-like testing\n- Automatic collection and index management\n- Application-level vector search for semantic queries\n- Multi-namespace support for tenant isolation\n- Compatible with DocumentDB API for seamless cloud migration\n\nFor detailed MongoDB CE architecture and configuration options, see [Storage Architecture Documentation](design/storage-architecture-mongodb-documentdb.md).\n\n---\n\n## 8. Verification and Testing\n\n### Test the Registry Web Interface\n\n1. Open your web browser and navigate to:\n ```bash\n # On macOS:\n open http://localhost:7860\n\n # On Linux (install xdg-utils if the xdg-open command is not available):\n # sudo apt install xdg-utils\n xdg-open http://localhost:7860\n\n # Or simply open http://localhost:7860 in your browser\n ```\n\n2. You should see the MCP Gateway Registry login page\n\n3. Click \"Login with Keycloak\" and use these test credentials:\n - Username: `admin`\n - Password: The `KEYCLOAK_ADMIN_PASSWORD` you set\n\n### Test with Python MCP Client\n\n```bash\n# Navigate to project root directory\ncd ~/workspace/mcp-gateway-registry\n\n# Activate the virtual environment if not already active\nsource .venv/bin/activate\n\n# Source the agent credentials from the saved file\nsource .oauth-tokens/agent-test-agent-m2m.env\n\n# Option 2: Or manually set the environment variables\n# export CLIENT_ID=\"agent-test-agent-m2m\"\n# export CLIENT_SECRET=\"\"\n# export KEYCLOAK_URL=\"http://localhost:8080\"\n# export KEYCLOAK_REALM=\"mcp-gateway\"\n\n# Test basic connectivity\nuv run python cli/mcp_client.py ping\n\n# Expected output:\n# ✓ M2M authentication successful\n# Session established: 277bf44c7d474d9b9674e7cc8a5122c8\n# {\n# \"jsonrpc\": \"2.0\",\n# \"id\": 2,\n# \"result\": {}\n# }\n\n# List available tools\nuv run python cli/mcp_client.py list\n# Expected: List of available MCP tools\n\n# Test calling a simple tool to get current time\n# Note: current_time_by_timezone is on the 'currenttime' server, not 'mcpgw'\nuv run python cli/mcp_client.py --url http://localhost/currenttime/mcp call --tool current_time_by_timezone --args '{\"tz_name\":\"America/New_York\"}'\n# Expected: Current time in JSON format\n\n# Alternative: Use intelligent_tool_finder on mcpgw to find and call tools dynamically\nuv run python cli/mcp_client.py call --tool intelligent_tool_finder --args '{\"natural_language_query\":\"get current time in New York\"}'\n# This will automatically find and route to the correct server\n```\n\n### Refreshing Credentials\n\nIf your access tokens have expired or you need to regenerate credentials, you can use the credential generation script:\n\n```bash\n# Navigate to project root directory\ncd ~/workspace/mcp-gateway-registry\n\n# Regenerate all credentials\n./credentials-provider/generate_creds.sh\n```\n\n**Note**: You may see errors related to \"egress token\" during credential generation. These errors can be safely ignored as they refer to external identity providers (IdPs) that are not yet configured. The local Keycloak credentials will be generated successfully.\n\n### Test Intelligent Agent Demo\n\n```bash\n# Use the intelligent tool finder to discover tools with natural language\nuv run python cli/mcp_client.py call --tool intelligent_tool_finder --args '{\"natural_language_query\":\"What is the current time?\"}'\n# Expected: Tool discovery results with time-related tools\n\n# You can also run a full agent with the comprehensive agent script\n# Note: Use --mcp-registry-url to point to your local gateway\nuv run python agents/agent.py --agent-name agent-test-agent-m2m --mcp-registry-url http://localhost/mcpgw/mcp --prompt \"What's the current time in New York?\" \n# Expected: Natural language response with current time\n```\n\n---\n\n### Accessing the Web UI\n\nBefore configuring AI agents, you'll want to access the MCP Gateway web interface to verify everything is working and test the Keycloak login flow.\n\n
\nRemote Access Options (click to expand)\n\nThe method to access the web UI depends on where you're running the MCP Gateway:\n\n#### Option A: Local Machine (Linux/macOS)\n\nIf you're running on your local machine, simply open a browser and navigate to:\n- **Registry UI**: http://localhost:7860\n- **Keycloak Admin**: http://localhost:8080\n\nNo additional setup required - you're already on localhost.\n\n#### Option B: AWS EC2 with Port Forwarding\n\nIf you're running on EC2 and want to access from your local machine via SSH port forwarding:\n\n```bash\n# From your local machine, create SSH tunnels\nssh -i your-key.pem -L 7860:localhost:7860 -L 8080:localhost:8080 -L 8888:localhost:8888 -L 80:localhost:80 ubuntu@your-ec2-ip\n\n# Then access in your local browser:\n# - Registry UI: http://localhost:7860\n# - Keycloak Admin: http://localhost:8080\n```\n\n#### Option C: AWS EC2 with Remote Desktop (GUI Access)\n\nIf you prefer a full desktop environment on your EC2 instance:\n\n```bash\n# Update system\nsudo apt update && sudo apt upgrade -y\n\n# Install XFCE desktop environment (lightweight)\nsudo apt install -y xfce4 xfce4-goodies\n\n# Install XRDP server\nsudo apt install -y xrdp\n\n# Configure XRDP to use XFCE\necho \"xfce4-session\" > ~/.xsession\n\n# Start and enable XRDP service\nsudo systemctl enable xrdp\nsudo systemctl start xrdp\n\n# Set password for ubuntu user\nsudo passwd ubuntu\n\n# Install Firefox browser for testing\nsudo apt install -y firefox\n```\n\n**AWS Security Group**: Add inbound rule for port 3389 (RDP) from your IP.\n\n**Connect from Windows**: Use Remote Desktop Connection (mstsc.exe) with:\n- Computer: `your-ec2-public-ip:3389`\n- Username: `ubuntu`\n- Password: The password you set above\n\n**Connect from macOS**: Use Microsoft Remote Desktop app from the App Store.\n\nOnce connected via remote desktop, open Firefox and navigate to http://localhost:7860 to access the Registry UI.\n\n
\n\n---\n\n## 9. Configuring AI Agents and Coding Assistants\n\n### Configure OAuth Credentials\n\nBefore generating tokens, you need to configure your OAuth credentials. Follow the [Configuration Reference](configuration.md) for detailed parameter documentation.\n\n```bash\ncd ~/workspace/mcp-gateway-registry\n\n# Configure OAuth credentials for external services (if needed)\ncp credentials-provider/oauth/.env.example credentials-provider/oauth/.env\n# Edit credentials-provider/oauth/.env with your provider credentials\n\n# Configure AgentCore credentials (if using Amazon Bedrock AgentCore)\ncp credentials-provider/agentcore-auth/.env.example credentials-provider/agentcore-auth/.env\n# Edit credentials-provider/agentcore-auth/.env with your AgentCore credentials\n```\n\n### Generate Authentication Tokens and MCP Configurations\n\n```bash\n# Generate all authentication tokens and MCP configurations\n./credentials-provider/generate_creds.sh\n\n# This script will:\n# 1. Generate Keycloak agent tokens for ingress authentication\n# 2. Generate external provider tokens for egress authentication (if configured)\n# 3. Generate AgentCore tokens (if configured)\n# 4. Create MCP configuration files for AI coding assistants\n# 5. Add no-auth services to the configurations\n```\n\n### Start Automatic Token Refresh Service\n\nFor production use, start the token refresh service to automatically maintain valid tokens. See the [Authentication Guide](auth.md) for detailed information about token lifecycle management.\n\n```bash\n# Start the background token refresh service\n./start_token_refresher.sh\n\n# Monitor the token refresh process\ntail -f token_refresher.log\n```\n\n**Example Token Refresh Output:**\n```\n2025-09-17 03:09:43,391,p455210,{token_refresher.py:370},INFO,Successfully refreshed OAuth token: agent-test-agent-m2m-token.json\n2025-09-17 03:09:43,391,p455210,{token_refresher.py:898},INFO,Token successfully updated at: /home/ubuntu/repos/mcp-gateway-registry/.oauth-tokens/agent-test-agent-m2m-token.json\n2025-09-17 03:09:43,631,p455210,{token_refresher.py:341},INFO,Refreshing OAuth token for provider: keycloak\n2025-09-17 03:09:43,778,p455210,{token_refresher.py:903},INFO,Refresh cycle complete: 8/8 tokens refreshed successfully\n2025-09-17 03:09:43,778,p455210,{token_refresher.py:907},INFO,Regenerating MCP configuration files after token refresh...\n2025-09-17 03:09:43,781,p455210,{token_refresher.py:490},INFO,MCP configuration files regenerated successfully\n```\n\n### Generated Token Files and Configurations\n\nAfter running `generate_creds.sh`, check the `.oauth-tokens/` directory for generated files:\n\n```bash\n# List all generated token files and configurations\nls -la .oauth-tokens/\n```\n\n**Key Files Generated:**\n- **Agent Tokens**: `agent-*-m2m-token.json` and `agent-*-m2m.env` files for each Keycloak agent\n- **External Service Tokens**: `*-egress.json` files for external providers (GitHub, etc.)\n- **AI Coding Assistant Configurations**:\n - `mcp.json` - Configuration for Claude Code/Roocode format\n - `vscode_mcp.json` - Configuration for VS Code format\n- **Raw Token Files**: `ingress.json`, individual service token files\n\n**Example AI Coding Assistant Configuration (mcp.json):**\n```json\n{\n \"mcpServers\": {\n \"mcpgw\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcpgateway.ddns.net/mcpgw/mcp\",\n \"headers\": {\n \"X-Authorization\": \"Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"X-Client-Id\": \"agent-ai-coding-assistant-m2m\",\n \"X-Keycloak-Realm\": \"mcp-gateway\",\n \"X-Keycloak-URL\": \"http://localhost:8080\"\n },\n \"disabled\": false,\n \"alwaysAllow\": []\n }\n }\n}\n```\n\n### Configure VS Code / Cursor / Claude Code\n\nFor VS Code or similar editors, you'll need to:\n\n1. Copy the configuration to your local machine:\n ```bash\n # From your local machine (not the EC2 instance)\n scp -i your-key.pem ubuntu@your-instance-ip:~/workspace/mcp-gateway-registry/.oauth-tokens/mcp.json ~/\n ```\n\n2. Add to your editor's MCP settings:\n - VS Code: Add to `.vscode/settings.json`\n - Cursor: Add to cursor settings\n - Claude Code: Add to claude settings\n\n### Create a Python Test Agent\n\n```bash\ncd ~/workspace/mcp-gateway-registry/agents\n\n# Create a test configuration\ncat > agent_config.json <\",\n \"gateway_url\": \"http://localhost:8000\"\n}\nEOF\n\n# Install Python dependencies\nuv venv\nsource .venv/bin/activate\nuv pip install -r requirements.txt\n\n# Run the test agent\nuv run python agent.py --config agent_config.json\n```\n\n---\n\n## 10. Troubleshooting\n\n### Common Issues and Solutions\n\n#### Services Won't Start\n```bash\n# Check Docker daemon\nsudo systemctl status docker\n\n# Restart Docker if needed\nsudo systemctl restart docker\n\n# Check for port conflicts\nsudo netstat -tlnp | grep -E ':(80|443|7860|8080|8000)'\n\n# Stop conflicting services if found\nsudo systemctl stop apache2 # If Apache is running\n```\n\n#### Keycloak Initialization Fails\n```bash\n# Check Keycloak logs\ndocker-compose logs keycloak | tail -50\n\n# Restart Keycloak\ndocker-compose restart keycloak\n\n# Wait 2-3 minutes and retry initialization\n./keycloak/setup/init-keycloak.sh\n```\n\n**Password Mismatch Issue**: If you see authentication failures during initialization:\n1. Verify that `KEYCLOAK_ADMIN_PASSWORD` and `INITIAL_ADMIN_PASSWORD` are set to the SAME VALUE in your `.env` file\n2. If they don't match, fix them:\n ```bash\n # Edit your .env file and ensure these match:\n nano .env\n # KEYCLOAK_ADMIN_PASSWORD=your-password\n # INITIAL_ADMIN_PASSWORD=your-password (MUST be identical)\n ```\n3. Restart Keycloak and try initialization again:\n ```bash\n docker-compose restart keycloak\n # Wait 2-3 minutes, then:\n ./keycloak/setup/init-keycloak.sh\n ```\n\n#### Login Redirects Back to Login Page\n\n**Most Common Cause**: Incorrect `SESSION_COOKIE_SECURE` setting\n\n**Symptoms**:\n- You enter username/password\n- Page redirects back to login page without error message\n- No session cookie is stored in browser\n\n**Solution**:\n1. Check your `.env` file:\n ```bash\n grep SESSION_COOKIE_SECURE .env\n ```\n\n2. **For localhost (HTTP) access**:\n ```bash\n # MUST be false\n SESSION_COOKIE_SECURE=false\n ```\n\n3. **For HTTPS access**:\n ```bash\n # MUST be true\n SESSION_COOKIE_SECURE=true\n ```\n\n4. **Verify in browser dev tools**:\n - Open browser dev tools (F12)\n - Go to Application → Cookies → Your domain\n - Check if `mcp_gateway_session` cookie exists\n - For HTTP: `Secure` flag should be UNCHECKED\n - For HTTPS: `Secure` flag should be CHECKED\n\n5. **After fixing, rebuild and restart**:\n ```bash\n docker compose down\n docker compose build --no-cache auth-server registry\n docker compose up -d\n ```\n\n**Why this happens**: Cookies with `secure=true` are ONLY sent over HTTPS connections. If you access via HTTP (like `http://localhost:7860`), the browser will reject the cookie and login will fail.\n\n#### Authentication Issues\n```bash\n# Verify Keycloak is accessible\ncurl http://localhost:8080/realms/mcp-gateway\n\n# Check auth server logs\ndocker-compose logs auth-server | tail -50\n\n# Regenerate agent credentials\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id new-test-agent \\\n --group mcp-servers-unrestricted\n```\n\n#### Login Redirects Back to Login Page\nThis usually indicates a session cookie issue between auth-server and registry:\n\n```bash\n# Check for SECRET_KEY mismatch\ndocker-compose logs auth-server | grep \"SECRET_KEY\"\ndocker-compose logs registry | grep -E \"(session|cookie|Invalid)\"\n\n# If you see \"No SECRET_KEY environment variable found\", regenerate and restart:\nSECRET_KEY=$(python3 -c \"import secrets; print(secrets.token_urlsafe(64))\")\nsed -i \"s/SECRET_KEY=.*/SECRET_KEY=$SECRET_KEY/\" .env\n\n# Recreate containers to pick up new SECRET_KEY\ndocker-compose stop auth-server registry\ndocker-compose rm -f auth-server registry\ndocker-compose up -d auth-server registry\n\n# Test login again - should work now\n```\n\n#### Configure Token Lifetime\nBy default, Keycloak generates tokens with a 5-minute (300 seconds) lifetime. To change this for longer-lived tokens:\n\n**Method 1: Via Keycloak Admin Console**\n1. Go to `http://localhost:8080/admin` (or your Keycloak URL)\n2. Login with admin credentials\n3. Select the `mcp-gateway` realm\n4. Go to **Realm Settings** → **Tokens** → **Access Token Lifespan**\n5. Change from `5 Minutes` to desired value (e.g., `1 Hour`)\n6. Click **Save**\n\n**Method 2: Via Keycloak Admin API**\n```bash\n# Get admin token\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:8080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=password&client_id=admin-cli&username=admin&password=your-keycloak-admin-password\" | \\\n jq -r '.access_token')\n\n# Update access token lifespan to 1 hour (3600 seconds)\n# Note: By default, Keycloak access tokens expire after 5 minutes\n# Only increase this timeout if it's consistent with your organization's security policy\ncurl -X PUT \"http://localhost:8080/admin/realms/mcp-gateway\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"accessTokenLifespan\": 3600}'\n\n# Verify the change\ncurl -X GET \"http://localhost:8080/admin/realms/mcp-gateway\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" | jq '.accessTokenLifespan'\n```\n\n**Note**: New tokens generated after this change will use the updated lifetime. Existing tokens retain their original expiration time.\n\n#### OAuth2 Callback Failed\nIf you see \"oauth2_callback_failed\" error:\n\n```bash\n# Check Keycloak external URL configuration\ndocker-compose exec -T auth-server env | grep KEYCLOAK_EXTERNAL_URL\n# Should show: KEYCLOAK_EXTERNAL_URL=http://localhost:8080\n\n# If missing, add to .env file:\necho \"KEYCLOAK_EXTERNAL_URL=http://localhost:8080\" >> .env\ndocker-compose restart auth-server\n\n# Check auth-server can reach Keycloak internally\ndocker-compose exec auth-server curl -f http://keycloak:8080/health/ready\n```\n\n#### Registry Not Loading\n```bash\n# Check registry logs\ndocker-compose logs registry | tail -50\n\n# Rebuild registry frontend\ncd ~/workspace/mcp-gateway-registry/registry\nnpm install\nnpm run build\ncd ..\ndocker-compose restart registry\n```\n\n### View Real-time Logs\n```bash\n# All services\ndocker-compose logs -f\n\n# Specific service\ndocker-compose logs -f \n\n# Last 100 lines\ndocker-compose logs --tail=100 \n```\n\n### Stopping Services\n\n```bash\n# Graceful shutdown (keeps data)\ndocker-compose down\n\n# Complete cleanup (removes all data)\ndocker-compose down -v\n\n# Just stop services (to restart later)\ndocker-compose stop\n```\n\n### Reset Everything\nIf you need to start over completely:\n```bash\n# Stop all services and remove volumes\ndocker-compose down -v\n\n# Remove all Docker images (optional)\ndocker system prune -a\n\n# Start fresh\ndocker-compose up -d keycloak-db keycloak\n# Then follow setup steps again from Step 5\n```\n\n---\n\n## 11. Custom HTTPS Domain Configuration\n\nIf you're running this setup with a custom HTTPS domain (e.g., `https://mcpgateway.mycorp.com`) instead of localhost, you'll need to update the following parameters in your `.env` file:\n\n### Parameters to Update for Custom HTTPS Domain\n\n```bash\n# Update these parameters in your .env file:\n\n# 1. Registry URL - Replace with your custom domain\nREGISTRY_URL=https://mcpgateway.mycorp.com\n\n# 2. Auth Server External URL - Replace with your custom domain\nAUTH_SERVER_EXTERNAL_URL=https://mcpgateway.mycorp.com\n\n# 3. Keycloak External URL - Replace with your custom domain\nKEYCLOAK_EXTERNAL_URL=https://mcpgateway.mycorp.com\n\n# 4. Keycloak Admin URL - Replace with your custom domain\nKEYCLOAK_ADMIN_URL=https://mcpgateway.mycorp.com\n```\n\n### Parameters to KEEP UNCHANGED\n\nThese parameters should remain as localhost/Docker network addresses for internal communication:\n\n```bash\n# DO NOT CHANGE - These are for internal Docker network communication:\nAUTH_SERVER_URL=http://auth-server:8888\nKEYCLOAK_URL=http://keycloak:8080\n```\n\n### Additional Considerations for Custom Domains\n\n1. **SSL/TLS Certificates**: Ensure you have valid SSL certificates for your domain\n2. **Firewall Rules**: Update security groups/firewall rules for your custom domain\n3. **DNS Configuration**: Ensure your domain points to your server's public IP address\n\n### Testing Custom Domain Setup\n\nAfter updating your `.env` file with custom domain values:\n\n```bash\n# Restart services to pick up new configuration\ndocker-compose restart auth-server registry\n\n# Test the custom domain\ncurl -f https://mcpgateway.mycorp.com/health\n\n# Test Keycloak access\ncurl -f https://mcpgateway.mycorp.com/realms/mcp-gateway\n```\n\n---\n\n## 12. Next Steps\n\n### Secure Your Installation\n\n1. **Update Security Groups**: Restrict IP access to only necessary addresses\n2. **Enable HTTPS**: Set up SSL certificates for production use\n3. **Change Default Passwords**: Update all default passwords in production\n4. **Set up Monitoring**: Configure CloudWatch or similar monitoring\n\n### Add More MCP Servers\n\n1. Check available MCP servers:\n ```bash\n ls ~/workspace/mcp-gateway-registry/registry/servers/\n ```\n\n2. Edit `docker-compose.yml` to enable additional servers\n\n3. Restart services:\n ```bash\n docker-compose up -d\n ```\n\n### Configure Production Settings\n\n1. **Domain Name**: Set up a domain name and update configurations\n2. **Load Balancer**: Add an Application Load Balancer for redundancy and load distribution\n3. **Backup Strategy**: Implement regular backups of PostgreSQL database\n4. **Scaling**: Consider EKS deployment for auto-scaling capabilities\n\n### Explore Advanced Features\n\n- **Fine-grained Access Control**: Configure `scopes.yml` for detailed permissions\n- **Custom MCP Servers**: Add your own MCP server implementations\n- **OAuth Integration**: Connect with external services (GitHub, Google, etc.)\n- **Monitoring Dashboard**: Set up Grafana for metrics visualization\n\n### Documentation Resources\n\n- [Authentication Guide](auth.md) - Deep dive into authentication options\n- [Keycloak Advanced Configuration](keycloak-integration.md) - Enterprise features\n- [API Reference](registry_api.md) - Programmatic registry management\n- [Dynamic Tool Discovery](dynamic-tool-discovery.md) - AI agent capabilities\n- [AWS ECS Deployment](../terraform/aws-ecs/README.md) - Deployment best practices\n\n### Getting Help\n\n- **GitHub Issues**: https://github.com/agentic-community/mcp-gateway-registry/issues\n- **Discussions**: https://github.com/agentic-community/mcp-gateway-registry/discussions\n- **Documentation**: Check the `/docs` folder for detailed guides\n\n---\n\n## Container Publishing for Production Deployment\n\nFor production environments or to contribute pre-built images, you can publish the containers to Docker Hub and GitHub Container Registry.\n\n### Publishing Script Overview\n\nThe `scripts/publish_containers.sh` script automates building and publishing all 6 container components:\n\n- `registry` - Main registry service with nginx and web UI\n- `auth-server` - Authentication service\n- `currenttime-server` - Current time MCP server\n- `realserverfaketools-server` - Example tools MCP server\n- `fininfo-server` - Financial information MCP server\n- `mcpgw-server` - MCP Gateway proxy server\n\n### Publishing Commands\n\n**Test build locally (no push):**\n```bash\n./scripts/publish_containers.sh --local\n```\n\n**Publish to Docker Hub:**\n```bash\n./scripts/publish_containers.sh --dockerhub\n```\n\n**Publish to GitHub Container Registry:**\n```bash\n./scripts/publish_containers.sh --ghcr\n```\n\n**Publish to both registries:**\n```bash\n./scripts/publish_containers.sh --dockerhub --ghcr\n```\n\n**Build specific component:**\n```bash\n./scripts/publish_containers.sh --dockerhub --component registry\n```\n\n### Required Environment Variables\n\nAdd these to your `.env` file for publishing:\n\n```bash\n# Container Registry Credentials\nDOCKERHUB_USERNAME=aarora79\nDOCKERHUB_TOKEN=your_docker_hub_token\nGITHUB_TOKEN=your_github_token\n\n# Organization names for publishing\nDOCKERHUB_ORG=mcpgateway\nGITHUB_ORG=agentic-community\n```\n\n### Generated Image Names\n\n**Docker Hub (Organization Account):**\n- `mcpgateway/registry:latest`\n- `mcpgateway/auth-server:latest`\n- `mcpgateway/currenttime-server:latest`\n- `mcpgateway/realserverfaketools-server:latest`\n- `mcpgateway/fininfo-server:latest`\n- `mcpgateway/mcpgw-server:latest`\n\n**GitHub Container Registry:**\n- `ghcr.io/agentic-community/mcp-registry:latest`\n- `ghcr.io/agentic-community/mcp-auth-server:latest`\n- `ghcr.io/agentic-community/mcp-currenttime-server:latest`\n- `ghcr.io/agentic-community/mcp-realserverfaketools-server:latest`\n- `ghcr.io/agentic-community/mcp-fininfo-server:latest`\n- `ghcr.io/agentic-community/mcp-mcpgw-server:latest`\n\n### Using Pre-built Images\n\nOnce published, anyone can use the pre-built images with:\n\n```bash\n# Use the pre-built deployment option\n./build_and_run.sh --prebuilt\n```\n\nThis deployment method:\n- Skips the build process entirely\n- Pulls pre-built images from container registries\n- Starts services in under 2 minutes\n- Requires no Node.js or build dependencies\n\n---\n\n## Summary\n\nYou now have a fully functional MCP Gateway & Registry running on your AWS EC2 instance! The system is ready to:\n\n- Authenticate AI agents and human users through Keycloak\n- Provide centralized access to MCP servers\n- Enable dynamic tool discovery for AI assistants\n- Offer a web-based registry for managing configurations\n\nRemember to:\n- Save all generated credentials securely\n- Monitor service logs regularly\n- Keep the system updated with latest releases\n- Follow security best practices for production use\n\nCongratulations on completing the setup! Your enterprise MCP gateway is now operational and ready to serve both AI agents and development teams.\n" }, { "path": "docs/configuration.md", "content": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration files in the MCP Gateway Registry project. Each configuration file serves a specific purpose in the authentication and operation of the system.\n\n## Configuration Files Overview\n\n| File | Purpose | Type | Location | Example File | User Modification |\n|------|---------|------|----------|--------------|-------------------|\n| [`.env`](#main-environment-configuration) | Main project environment variables | Environment | Project root | `.env.example` | **Yes** - Required |\n| [`.env` (OAuth)](#oauth-environment-configuration) | OAuth provider credentials | Environment | `credentials-provider/oauth/` | `.env.example` | **Yes** - Required |\n| [`.env` (AgentCore)](#agentcore-environment-configuration) | AgentCore authentication config | Environment | `credentials-provider/agentcore-auth/` | `.env.example` | **Optional** - Only if using AgentCore |\n| [`oauth2_providers.yml`](#oauth2-providers-configuration) | OAuth2 provider definitions | YAML | `auth_server/` | - | **No** - Pre-configured |\n| [`oauth_providers.yaml`](#oauth-providers-mapping) | Provider-specific OAuth configurations | YAML | `credentials-provider/oauth/` | - | **No** - Pre-configured |\n| [`docker-compose.yml`](#docker-compose-configuration) | Container orchestration | YAML | Project root | - | **Rarely** - Only for custom deployments |\n\n---\n\n## Main Environment Configuration\n\n**File:** `.env` (Project root)\n**Purpose:** Core project settings, registry URLs, and primary authentication credentials.\n\n### Authentication Provider Selection\n\nThe MCP Gateway Registry supports multiple authentication providers. Choose one by setting the `AUTH_PROVIDER` environment variable:\n\n- **`keycloak`**: Open-source identity and access management with individual agent audit trails\n- **`cognito`**: Amazon managed authentication service\n\nBased on your selection, configure the corresponding provider-specific variables below.\n\n### Core Variables\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `REGISTRY_URL` | Public URL of the MCP Gateway Registry | `https://mcpgateway.ddns.net` | ✅ |\n| `AUTH_PROVIDER` | Authentication provider (`cognito` or `keycloak`) | `keycloak` | ✅ |\n| `AWS_REGION` | AWS region for services | `us-east-1` | ✅ |\n\n### Deployment Mode Configuration\n\nControls how the registry operates and which UI tabs are visible.\n\n| Variable | Description | Values | Default |\n|----------|-------------|--------|---------|\n| `DEPLOYMENT_MODE` | How registry integrates with the gateway | `with-gateway`, `registry-only` | `with-gateway` |\n| `REGISTRY_MODE` | Which feature categories are enabled | `full`, `mcp-servers-only`, `agents-only`, `skills-only` | `full` |\n\n**Deployment Mode Options:**\n\n- **`with-gateway`**: Full integration with nginx reverse proxy. Nginx config is regenerated when servers are registered or deleted.\n- **`registry-only`**: Registry operates as a catalog/discovery service only. Nginx config is not updated on server changes.\n\n**Registry Mode Options:**\n\n- **`full`**: All features enabled (MCP servers, agents, skills, federation)\n- **`mcp-servers-only`**: Only MCP server and virtual server features enabled\n- **`agents-only`**: Only A2A agent features enabled\n- **`skills-only`**: Only skills features enabled\n\n**Note:** `with-gateway` + `skills-only` is an invalid combination and auto-corrects to `registry-only` + `skills-only` at startup.\n\n### Tab Visibility Overrides\n\nThese variables allow hiding specific UI tabs independently of `REGISTRY_MODE`. The visibility formula is:\n\n```\ntab_visible = REGISTRY_MODE enables the feature AND SHOW_*_TAB is true\n```\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SHOW_SERVERS_TAB` | Show the MCP Servers tab in the UI | `true` |\n| `SHOW_VIRTUAL_SERVERS_TAB` | Show the Virtual MCP Servers tab in the UI | `true` |\n| `SHOW_SKILLS_TAB` | Show the Skills tab in the UI | `true` |\n| `SHOW_AGENTS_TAB` | Show the Agents tab in the UI | `true` |\n\n**Precedence Matrix:**\n\n| Scenario | Result |\n|----------|--------|\n| `REGISTRY_MODE=full` + `SHOW_AGENTS_TAB=true` | Agents tab shown |\n| `REGISTRY_MODE=full` + `SHOW_AGENTS_TAB=false` | Agents tab hidden (backend APIs still work) |\n| `REGISTRY_MODE=mcp-servers-only` + `SHOW_AGENTS_TAB=true` | Agents tab hidden (mode blocks it) |\n| `REGISTRY_MODE=mcp-servers-only` + `SHOW_AGENTS_TAB=false` | Agents tab hidden |\n\n**Important:**\n- Setting `SHOW_*_TAB=false` only hides the UI tab. Backend APIs remain fully functional.\n- If a `SHOW_*_TAB` is set to `true` but `REGISTRY_MODE` does not enable that feature, a warning is logged at startup.\n- All defaults are `true` for backward compatibility.\n- These settings are visible in the **Settings > System Config** page under the \"Deployment Mode\" group.\n\n### Keycloak Configuration (if AUTH_PROVIDER=keycloak)\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `KEYCLOAK_URL` | Keycloak server URL (internal/Docker network) | `http://keycloak:8080` | ✅ |\n| `KEYCLOAK_EXTERNAL_URL` | Keycloak server URL (external/browser access) | `https://mcpgateway.ddns.net` (production)
`http://localhost:8080` (local development) | ✅ |\n| `KEYCLOAK_ADMIN_URL` | Keycloak admin URL (for setup scripts) | `http://localhost:8080` | ✅ |\n| `KEYCLOAK_REALM` | Keycloak realm name | `mcp-gateway` | ✅ |\n| `KEYCLOAK_ADMIN` | Keycloak admin username | `admin` | ✅ |\n| `KEYCLOAK_ADMIN_PASSWORD` | Keycloak admin password | `SecureKeycloakAdmin123!` | ✅ |\n| `KEYCLOAK_DB_PASSWORD` | Keycloak database password | `SecureKeycloakDB123!` | ✅ |\n| `KEYCLOAK_CLIENT_ID` | Keycloak web client ID (see note below) | `mcp-gateway-web` | ✅ |\n| `KEYCLOAK_CLIENT_SECRET` | Keycloak web client secret (auto-generated) | `0tiBtgQFcaBiwHXIxDws...` | ✅ |\n| `KEYCLOAK_M2M_CLIENT_ID` | Keycloak M2M client ID (see note below) | `mcp-gateway-m2m` | ✅ |\n| `KEYCLOAK_M2M_CLIENT_SECRET` | Keycloak M2M client secret (auto-generated) | `ZJqbsamnQs79hbUbkJLB...` | ✅ |\n| `KEYCLOAK_ENABLED` | Enable Keycloak in OAuth2 providers | `true` | ✅ |\n| `INITIAL_ADMIN_PASSWORD` | Initial admin user password | `changeme` | For setup |\n| `INITIAL_USER_PASSWORD` | Initial test user password | `testpass` | For setup |\n\n**Note: Getting Keycloak Client IDs and Secrets**\n\nThe client IDs and secrets are automatically generated when you run the Keycloak initialization script:\n\n```bash\ncd keycloak/setup\n./init-keycloak.sh\n```\n\nThe script will:\n1. Create the clients with the IDs you specify (`mcp-gateway-web` and `mcp-gateway-m2m`)\n2. Generate secure random secrets for each client\n3. Display the generated secrets at the end of the script output\n4. Save them to a file for your reference\n\n**To retrieve existing client secrets from a running Keycloak instance:**\n\n```bash\n# Method 1: Use the helper script (Recommended)\ncd keycloak/setup\nexport KEYCLOAK_ADMIN_PASSWORD=\"your-admin-password\"\n./get-all-client-credentials.sh\n# This will display the secrets and save them to .oauth-tokens/keycloak-client-secrets.txt\n\n# Method 2: Using Keycloak Admin Console (Web UI)\n# 1. Navigate to https://your-keycloak-url/admin\n# 2. Login with admin credentials\n# 3. Select your realm (mcp-gateway)\n# 4. Go to Clients → Select your client\n# 5. Go to Credentials tab\n# 6. Copy the Secret value\n\n# Method 3: Check the original initialization output\n# The init-keycloak.sh script saves secrets to keycloak-client-secrets.txt\ncat keycloak/setup/keycloak-client-secrets.txt\n```\n\n### Amazon Cognito Configuration (if AUTH_PROVIDER=cognito)\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `COGNITO_USER_POOL_ID` | Amazon Cognito User Pool ID | `us-east-1_vm1115QSU` | ✅ |\n| `COGNITO_CLIENT_ID` | Amazon Cognito App Client ID | `3aju04s66t...` | ✅ |\n| `COGNITO_CLIENT_SECRET` | Amazon Cognito App Client Secret | `85ps32t55df39hm61k966fqjurj...` | ✅ |\n| `COGNITO_DOMAIN` | Cognito domain (optional) | `auto` | Optional |\n\n### Session Cookie Security Configuration\n\n**CRITICAL:** These settings control how session cookies are transmitted and shared. Incorrect configuration will cause login failures.\n\n| Variable | Description | Example | Required | Default |\n|----------|-------------|---------|----------|---------|\n| `SESSION_COOKIE_SECURE` | Enable HTTPS-only cookie transmission | `false` (localhost)
`true` (production) | ✅ | `false` |\n| `SESSION_COOKIE_DOMAIN` | Cookie domain for cross-subdomain sharing | `\"\"` (single domain)
`.example.com` (cross-subdomain) | ❌ | Empty |\n\n#### SESSION_COOKIE_SECURE - Critical for Your Environment\n\n**YOU MUST SET THIS CORRECTLY OR LOGIN WILL FAIL:**\n\n**For Local Development (localhost via HTTP):**\n```bash\nSESSION_COOKIE_SECURE=false # MUST be false\n```\n- Localhost runs over HTTP (not HTTPS)\n- Cookies with `secure=true` are ONLY sent over HTTPS\n- Setting this to `true` on localhost = **login will fail**\n\n**For Production with HTTPS:**\n```bash\nSESSION_COOKIE_SECURE=true # MUST be true\n```\n- Production deployments use HTTPS\n- Cookies must have `secure=true` to prevent session hijacking\n- Setting this to `false` in production = **security vulnerability** ❌\n\n#### SESSION_COOKIE_DOMAIN - When to Set This\n\n**Most deployments should leave this EMPTY** (default behavior = safest):\n\n```bash\nSESSION_COOKIE_DOMAIN= # Empty string or unset\n```\n\n**Only set this if you need cross-subdomain authentication:**\n\n| Deployment Type | Example Domains | SESSION_COOKIE_DOMAIN |\n|----------------|-----------------|----------------------|\n| **Single domain** | `mcpgateway.ddns.net` | `\"\"` (empty) |\n| **Cross-subdomain** | `auth.example.com`
`registry.example.com` | `.example.com` |\n| **Multi-level domains** | `registry.region-1.corp.company.internal` | `.corp.company.internal` |\n\n**Important Security Notes:**\n- Empty domain = cookie scoped to exact host only (safest)\n- Set domain only when you control ALL subdomains\n- Never set to public suffixes (`.com`, `.net`, `.ddns.net`)\n- Domain must start with a dot (`.example.com`)\n\n**See Also:** [Cookie Security Design Documentation](design/cookie-security-design.md) for detailed security analysis and deployment scenarios.\n\n### Optional Variables\n\n| Variable | Description | Example | Default |\n|----------|-------------|---------|---------|\n| `AUTH_SERVER_URL` | Internal auth server URL | `http://auth-server:8888` | - |\n| `AUTH_SERVER_EXTERNAL_URL` | External auth server URL | `https://mcpgateway.ddns.net` | - |\n| `SECRET_KEY` | Application secret key | Auto-generated if not provided | Auto-generated |\n| `SRE_GATEWAY_AUTH_TOKEN` | SRE Gateway auth token | Auto-populated from credentials | - |\n| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models | `sk-ant-api03-...` | For AI functionality |\n\n### GitHub Private Repository Access\n\nEnable authenticated access to SKILL.md files hosted in private GitHub repositories. Two authentication methods are supported: Personal Access Token (simple) or GitHub App (recommended for organizations). If both are configured, GitHub App takes priority.\n\n#### Environment Variables\n\n| Variable | Description | Example | Default |\n|----------|-------------|---------|---------|\n| `GITHUB_PAT` | Personal Access Token with `repo` scope (or fine-grained PAT with `contents: read`) | `ghp_your_token_here` | Empty (disabled) |\n| `GITHUB_APP_ID` | GitHub App ID | `123456` | Empty |\n| `GITHUB_APP_INSTALLATION_ID` | GitHub App Installation ID | `78901234` | Empty |\n| `GITHUB_APP_PRIVATE_KEY` | GitHub App private key in PEM format (newlines as `\\n`) | `-----BEGIN RSA PRIVATE KEY-----\\n...` | Empty |\n| `GITHUB_EXTRA_HOSTS` | Comma-separated extra GitHub hosts for auth header injection | `github.mycompany.com,raw.github.mycompany.com` | Empty |\n| `GITHUB_API_BASE_URL` | GitHub API base URL (for GHES token exchange) | `https://github.mycompany.com/api/v3` | `https://api.github.com` |\n\n**Security:** Auth headers are only sent to `github.com`, `raw.githubusercontent.com`, and hosts explicitly listed in `GITHUB_EXTRA_HOSTS`.\n\n#### Terraform/ECS Configuration\n\n```hcl\n# Option 1: Personal Access Token\n# github_pat = \"ghp_your_token_here\"\n\n# Option 2: GitHub App authentication\n# github_app_id = \"123456\"\n# github_app_installation_id = \"78901234\"\n# github_app_private_key = \"-----BEGIN RSA PRIVATE KEY-----\\\\n...\\\\n-----END RSA PRIVATE KEY-----\"\n\n# GitHub Enterprise Server support\n# github_extra_hosts = \"github.mycompany.com,raw.github.mycompany.com\"\n# github_api_base_url = \"https://github.mycompany.com/api/v3\"\n```\n\n#### Helm Configuration\n\n```yaml\napp:\n # Option 1: PAT (plain value or Kubernetes secret)\n githubPat: \"\"\n githubPatExistingSecret: \"\" # K8s secret name\n githubPatExistingSecretKey: \"GITHUB_PAT\"\n\n # Option 2: GitHub App\n githubAppId: \"\"\n githubAppInstallationId: \"\"\n githubAppPrivateKey: \"\"\n githubAppPrivateKeyExistingSecret: \"\" # K8s secret name\n githubAppPrivateKeyExistingSecretKey: \"GITHUB_APP_PRIVATE_KEY\"\n\n # GitHub Enterprise Server\n githubExtraHosts: \"\"\n githubApiBaseUrl: \"https://api.github.com\"\n```\n\nFor Helm deployments, use `ExistingSecret` fields to inject credentials from Kubernetes secrets rather than plain values.\n\n### Storage Backend Configuration\n\nThe MCP Gateway Registry supports three storage backends for servers, agents, and scopes management.\n\n| Variable | Description | Values | Default |\n|----------|-------------|--------|---------|\n| `STORAGE_BACKEND` | Storage backend for registry data | `file`, `mongodb-ce`, or `documentdb` | `file` |\n\n> **⚠️ DEPRECATION WARNING:** File-based storage is deprecated and will be removed in a future release. MongoDB CE is now the recommended backend for local development and testing.\n\n**Backend Options:**\n\n#### File Backend (Deprecated)\n- **Status**: **DEPRECATED** - Will be removed in a future release\n- **Migration Path**: Switch to MongoDB CE for local development or DocumentDB for production\n- **Pros**: Simple, no external dependencies, human-readable JSON files\n- **Cons**: Limited concurrent writes, no distributed access, FAISS-based vector search, **deprecated**\n\n```bash\nSTORAGE_BACKEND=file # DEPRECATED - Use mongodb-ce instead\n```\n\n**Data stored in:**\n- Servers: `~/mcp-gateway/servers/*.json`\n- Agents: `~/mcp-gateway/agents/*.json`\n- Security scans: `~/mcp-gateway/security_scans/*.json`\n\n#### MongoDB CE Backend (Recommended for Local Development)\n- **Status**: **RECOMMENDED** for all local development and testing\n- **Best for**: Local development, feature development, testing, CI/CD pipelines\n- **Pros**: Docker-based, no cloud dependencies, replica set support, application-level vector search, production-like environment\n- **Cons**: Limited to ~10,000 documents, O(n) vector search performance (acceptable for development)\n\n```bash\nSTORAGE_BACKEND=mongodb-ce\nDOCUMENTDB_HOST=mongodb # Docker service name\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=default\nDOCUMENTDB_USE_TLS=false # No TLS for local dev\n```\n\n**MongoDB Collections Created:**\n- `mcp_servers_{namespace}` - Server definitions\n- `mcp_agents_{namespace}` - A2A agent cards\n- `mcp_scopes_{namespace}` - Authorization scopes\n- `mcp_embeddings_1536_{namespace}` - Vector embeddings (1536 dimensions)\n- `mcp_security_scans_{namespace}` - Security scan results\n- `mcp_federation_config_{namespace}` - Federation configuration\n\n**First-Time MongoDB CE Setup:**\n\n```bash\n# 1. Start MongoDB container\ndocker-compose up -d mongodb\nsleep 5\n\n# 2. Initialize collections and indexes\ndocker-compose up mongodb-init\n\n# 3. Verify setup\ndocker exec mcp-mongodb mongosh --eval \"use mcp_registry; show collections\"\n\n# 4. Switch backend and restart\nexport STORAGE_BACKEND=mongodb-ce\ndocker-compose restart registry\n```\n\n#### DocumentDB Backend (Production, Recommended)\n- **Best for**: Production deployments, high concurrency, large-scale systems\n- **Pros**: Native HNSW vector search, distributed storage, AWS-managed, clustering support\n- **Cons**: Requires AWS infrastructure, uses AWS pricing\n\n```bash\nSTORAGE_BACKEND=documentdb\nDOCUMENTDB_HOST=cluster.docdb.amazonaws.com\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=production\nDOCUMENTDB_USERNAME=admin\nDOCUMENTDB_PASSWORD=\nDOCUMENTDB_USE_TLS=true\nDOCUMENTDB_TLS_CA_FILE=global-bundle.pem\nDOCUMENTDB_REPLICA_SET=rs0\n```\n\n**DocumentDB Collections Created:**\nSame as MongoDB CE (above), but with native HNSW vector indexes for sub-100ms semantic search.\n\n**First-Time DocumentDB Setup:**\n\n```bash\n# 1. Deploy DocumentDB cluster via Terraform\ncd terraform/aws-ecs\nterraform apply\n\n# 2. Collections and indexes are created automatically on first application startup\n\n# 3. Verify setup (from bastion host or EC2 with access)\nmongosh --host \\\n --username admin \\\n --password \\\n --tls \\\n --tlsCAFile global-bundle.pem \\\n --eval \"use mcp_registry; show collections\"\n```\n\n**Important Notes:**\n- MongoDB CE uses application-level vector search (Python cosine similarity)\n- DocumentDB uses native HNSW vector indexes for production performance\n- Both backends use the same repository code (`DocumentDBServerRepository`, etc.)\n- Scopes are stored in MongoDB (collection `mcp_scopes_{namespace}`) and managed via the API\n\n**Switching Between Backends:**\n\nYou can switch between backends at any time by changing `STORAGE_BACKEND`:\n\n```bash\n# Switch to file backend\nexport STORAGE_BACKEND=file\ndocker-compose restart registry\n\n# Switch to MongoDB CE backend\nexport STORAGE_BACKEND=mongodb-ce\ndocker-compose restart registry\n\n# Switch to DocumentDB backend\nexport STORAGE_BACKEND=documentdb\ndocker-compose restart registry\n```\n\n**For AWS ECS Deployments:** See [terraform/aws-ecs/README.md](../terraform/aws-ecs/README.md) for automated Terraform deployment with DocumentDB.\n\n**For Detailed Architecture:** See [Storage Architecture: MongoDB CE & AWS DocumentDB](design/storage-architecture-mongodb-documentdb.md) for comprehensive implementation details.\n\n### Container Registry Configuration (Optional - for CI/CD and local builds)\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `DOCKERHUB_USERNAME` | Docker Hub username for publishing containers | `your_dockerhub_username` | **Optional** |\n| `DOCKERHUB_TOKEN` | Docker Hub access token | `your_dockerhub_access_token` | **Optional** |\n| `GITHUB_USERNAME` | GitHub username for GHCR publishing | `your_github_username` | **Optional** |\n| `GITHUB_TOKEN` | GitHub Personal Access Token with packages:write scope | `ghp_your_token_here` | **Optional** |\n| `DOCKERHUB_ORG` | Docker Hub organization name (leave empty for personal account) | `mcpgateway` or empty | **Optional** |\n| `GITHUB_ORG` | GitHub organization name (leave empty for personal account) | `agentic-community` or empty | **Optional** |\n\n**Note: Container Registry Credentials (Completely Optional)**\n\nThese credentials are **entirely optional** and only needed if you want to:\n- **Publish container images**: Automatically via GitHub Actions or manually via scripts\n- **Contribute pre-built containers**: For easier deployment by other users\n\n**What happens if these are not configured:**\n- ✅ **The MCP Gateway Registry will work perfectly** - all core functionality remains intact\n- ✅ **GitHub Actions will succeed** - builds will complete successfully, just without publishing to Docker Hub\n- ✅ **Local development is unaffected** - no scripts will fail or produce errors\n- ✅ **Only container publishing is skipped** - everything else continues normally\n\n**When you might want to configure these:**\n- **Contributing to the project**: Publishing official container images\n- **Custom deployments**: Creating your own container registry for internal use\n- **Development workflow**: Testing container builds locally\n\n**How to obtain credentials (only if needed):**\n- **Docker Hub**: Get access token from [Docker Hub Security Settings](https://hub.docker.com/settings/security)\n- **GitHub Container Registry**: Generate Personal Access Token with `packages:write` scope from [GitHub Token Settings](https://github.com/settings/tokens)\n\n**Setup instructions (only if publishing containers):**\n- **In GitHub Actions**: Add `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` as repository secrets\n- **For local builds**: Add credentials to your `.env` file and use `scripts/publish_containers.sh`\n- **GITHUB_TOKEN**: Automatically provided in GitHub Actions, manually generated for local use\n\n**Organization vs Personal Account Publishing:**\n- **Personal Account** (Free): Leave `DOCKERHUB_ORG` and `GITHUB_ORG` empty\n - Images published as: `username/image-name`\n - Example: `aarora79/registry:latest`\n- **Organization Account** (Paid for Docker Hub): Set organization names\n - Images published as: `organization/image-name`\n - Example: `mcpgateway/registry:latest`\n\n---\n\n### Federation Configuration\n\n#### WORKDAY_TOKEN_URL (Optional)\n\nConfiguration for Workday ASOR (Agent Service Orchestrator) federation integration.\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `WORKDAY_TOKEN_URL` | Workday OAuth2 token endpoint URL | `https://services.wd101.myworkday.com/ccx/oauth2/production_instance/token` | **Optional** |\n\n**Required only if using Workday ASOR federation**\n\n- **Default**: `https://your-tenant.workday.com/ccx/oauth2/your_instance/token` (placeholder)\n- **Format**: `https://.workday.com/ccx/oauth2//token`\n- **Example**: `https://services.wd101.myworkday.com/ccx/oauth2/production_instance/token`\n- **Security**: Must use HTTPS in production environments\n- **Behavior**: If not configured with a valid URL, ASOR federation will be automatically disabled with a warning logged\n\n**Getting your Workday token URL:**\n\nReplace the placeholder values with your actual Workday tenant identifiers:\n- ``: Your Workday tenant domain (e.g., `services.wd101.myworkday.com`)\n- ``: Your Workday instance name (e.g., `production_instance`, `sandbox_instance`)\n\n**Configuration example:**\n\n```bash\n# For production Workday instance\nWORKDAY_TOKEN_URL=https://services.wd101.myworkday.com/ccx/oauth2/production_instance/token\n\n# For sandbox/testing instance\nWORKDAY_TOKEN_URL=https://services.wd101.myworkday.com/ccx/oauth2/sandbox_instance/token\n```\n\n**Troubleshooting:**\n\n- If ASOR federation is not working, check the registry logs for warnings about WORKDAY_TOKEN_URL\n- Ensure the URL uses HTTPS (HTTP will fail in production)\n- Verify your Workday tenant and instance names are correct\n- Contact your Workday administrator if you're unsure about your instance configuration\n\n---\n\n## Keycloak Setup and Configuration\n\nWhen using Keycloak as your authentication provider, the system provides comprehensive setup scripts and configuration options:\n\n### Initial Setup\n\nRun the Keycloak initialization script to set up the realm, clients, and groups:\n\n```bash\ncd keycloak/setup\n./init-keycloak.sh\n```\n\nThis script will:\n1. Create the `mcp-gateway` realm\n2. Set up web and M2M clients with proper configurations\n3. Create necessary groups (`mcp-servers-unrestricted`, `mcp-servers-restricted`)\n4. Configure group mappers for JWT token claims\n5. Create initial admin and test users\n\n### Service Account Management\n\nFor individual AI agent audit trails, create service accounts:\n\n```bash\n# Create individual agent service account\n./setup-agent-service-account.sh --agent-id sre-agent --group mcp-servers-unrestricted\n\n# Create shared M2M service account\n./setup-m2m-service-account.sh\n```\n\n### Token Generation\n\nGenerate tokens for Keycloak authentication:\n\n```bash\n# Generate M2M token for ingress\nuv run python credentials-provider/token_refresher.py\n\n# Generate agent-specific token\nuv run python credentials-provider/token_refresher.py --agent-id sre-agent\n```\n\nFor detailed Keycloak integration documentation, see [Keycloak Integration Guide](keycloak-integration.md).\n\n---\n\n## OAuth Environment Configuration\n\n**File:** `credentials-provider/oauth/.env`\n**Purpose:** OAuth provider credentials for ingress and egress authentication flows.\n\n### Ingress Authentication\n\n#### For Keycloak (if AUTH_PROVIDER=keycloak)\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `KEYCLOAK_URL` | Keycloak server URL | `https://mcpgateway.ddns.net` | ✅ |\n| `KEYCLOAK_REALM` | Keycloak realm | `mcp-gateway` | ✅ |\n| `KEYCLOAK_M2M_CLIENT_ID` | M2M client ID | `mcp-gateway-m2m` | ✅ |\n| `KEYCLOAK_M2M_CLIENT_SECRET` | M2M client secret | `ZJqbsamnQs79hbUbkJLB...` | ✅ |\n\n#### For Cognito (if AUTH_PROVIDER=cognito)\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `INGRESS_OAUTH_USER_POOL_ID` | Cognito User Pool for ingress auth | `us-east-1_vm1115QSU` | ✅ |\n| `INGRESS_OAUTH_CLIENT_ID` | Cognito client ID for ingress | `5v2rav1v93...` | ✅ |\n| `INGRESS_OAUTH_CLIENT_SECRET` | Cognito client secret for ingress | `1i888fnolv6k5sa1b8s5k839pdm...` | ✅ |\n\n### Egress Authentication (Optional)\n\nSupport for multiple OAuth provider configurations using numbered suffixes (`_1`, `_2`, `_3`, etc.):\n\n| Variable Pattern | Description | Example | Required |\n|------------------|-------------|---------|----------|\n| `EGRESS_OAUTH_CLIENT_ID_N` | OAuth client ID for provider N | `cNYWTFwyZB...` | For each provider |\n| `EGRESS_OAUTH_CLIENT_SECRET_N` | OAuth client secret for provider N | `ATOAubT-N-lAzpT05RDFq9dxcVr...` | For each provider |\n| `EGRESS_OAUTH_REDIRECT_URI_N` | OAuth redirect URI for provider N | `http://localhost:8080/callback` | For each provider |\n| `EGRESS_OAUTH_SCOPE_N` | OAuth scopes for provider N | Uses provider defaults if not set | Optional |\n| `EGRESS_PROVIDER_NAME_N` | Provider name (google, github, etc.) | `google` | For each provider |\n| `EGRESS_MCP_SERVER_NAME_N` | MCP server name for provider N | `google` | For each provider |\n\n### Supported Providers\n\n- **Google**: Gmail, Drive, Calendar services\n- **GitHub**: Repository and issue management\n- **Microsoft**: Office 365, Teams integration\n- **Bedrock AgentCore**: AWS AgentCore services\n\n---\n\n## AgentCore Environment Configuration\n\n**File:** `credentials-provider/agentcore-auth/.env`\n**Purpose:** Amazon Bedrock AgentCore authentication configuration with support for multiple gateways.\n\n### Shared Configuration\n\n| Variable | Description | Example | Required |\n|----------|-------------|---------|----------|\n| `COGNITO_DOMAIN` | AgentCore Cognito domain URL | `https://your-cognito-domain.auth.region.amazoncognito.com` | ✅ |\n| `COGNITO_USER_POOL_ID` | Cognito User Pool ID | `region_your_pool_id` | ✅ |\n\n### Gateway-Specific Configurations\n\nSupport for multiple gateways using numbered suffixes (`_1`, `_2`, `_3`, etc., up to `_100`). Each configuration set requires all four parameters:\n\n| Variable Pattern | Description | Example | Required |\n|------------------|-------------|---------|----------|\n| `AGENTCORE_CLIENT_ID_N` | AgentCore Cognito client ID for gateway N | `your_client_id_here` | ✅ |\n| `AGENTCORE_CLIENT_SECRET_N` | AgentCore Cognito client secret for gateway N | `your_client_secret_here` | ✅ |\n| `AGENTCORE_GATEWAY_ARN_N` | Amazon Bedrock AgentCore Gateway ARN for gateway N | `arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-1` | ✅ |\n| `AGENTCORE_SERVER_NAME_N` | MCP server name for AgentCore gateway N | `my-gateway-1` | ✅ |\n\n**Example Configuration:**\n```bash\n# Configuration Set 1\nAGENTCORE_CLIENT_ID_1=your_client_id_here\nAGENTCORE_CLIENT_SECRET_1=your_client_secret_here\nAGENTCORE_GATEWAY_ARN_1=arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-1\nAGENTCORE_SERVER_NAME_1=my-gateway-1\n\n# Configuration Set 2\nAGENTCORE_CLIENT_ID_2=your_client_id_here\nAGENTCORE_CLIENT_SECRET_2=your_client_secret_here\nAGENTCORE_GATEWAY_ARN_2=arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-2\nAGENTCORE_SERVER_NAME_2=my-gateway-2\n```\n\n---\n\n## OAuth2 Providers Configuration\n\n**File:** `auth_server/oauth2_providers.yml`\n**Purpose:** OAuth2 provider definitions for web-based authentication flows.\n\n### Keycloak Provider Configuration\n\nWhen using Keycloak as the authentication provider, the following configuration is used:\n\n| Field | Description | Required | Example |\n|-------|-------------|----------|---------|\n| `display_name` | Human-readable name | ✅ | `\"Keycloak\"` |\n| `client_id` | OAuth client ID | ✅ | `\"${KEYCLOAK_CLIENT_ID}\"` |\n| `client_secret` | OAuth client secret | ✅ | `\"${KEYCLOAK_CLIENT_SECRET}\"` |\n| `auth_url` | Authorization endpoint | ✅ | `\"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/auth\"` |\n| `token_url` | Token endpoint | ✅ | `\"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token\"` |\n| `user_info_url` | User info endpoint | ✅ | `\"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/userinfo\"` |\n| `logout_url` | Logout endpoint | ✅ | `\"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/logout\"` |\n| `scopes` | OAuth scopes | ✅ | `[\"openid\", \"email\", \"profile\"]` |\n| `groups_claim` | JWT claim for groups | ✅ | `\"groups\"` |\n| `enabled` | Provider enabled | ✅ | `true` |\n\n### General Provider Configuration Fields\n\n| Field | Description | Required | Example |\n|-------|-------------|----------|---------|\n| `display_name` | Human-readable provider name | ✅ | `\"Amazon Cognito\"` |\n| `client_id` | OAuth client ID (can use env vars) | ✅ | `\"${COGNITO_CLIENT_ID}\"` |\n| `client_secret` | OAuth client secret (can use env vars) | ✅ | `\"${COGNITO_CLIENT_SECRET}\"` |\n| `auth_url` | Authorization endpoint URL | ✅ | `\"https://domain.auth.region.amazoncognito.com/oauth2/authorize\"` |\n| `token_url` | Token endpoint URL | ✅ | `\"https://domain.auth.region.amazoncognito.com/oauth2/token\"` |\n| `user_info_url` | User info endpoint URL | ✅ | `\"https://domain.auth.region.amazoncognito.com/oauth2/userInfo\"` |\n| `logout_url` | Logout endpoint URL | ✅ | `\"https://domain.auth.region.amazoncognito.com/logout\"` |\n| `scopes` | OAuth scopes array | ✅ | `[\"openid\", \"email\", \"profile\"]` |\n| `response_type` | OAuth response type | ✅ | `\"code\"` |\n| `grant_type` | OAuth grant type | ✅ | `\"authorization_code\"` |\n| `username_claim` | JWT claim for username | ✅ | `\"email\"` |\n| `groups_claim` | JWT claim for groups | ❌ | `\"cognito:groups\"` |\n| `email_claim` | JWT claim for email | ✅ | `\"email\"` |\n| `name_claim` | JWT claim for name | ✅ | `\"name\"` |\n| `enabled` | Whether provider is enabled | ✅ | `true` |\n\n### Supported Providers\n\n- **Keycloak**: Open-source identity and access management\n- **Amazon Cognito**: Amazon managed authentication service\n- **GitHub**: Repository and development services (planned)\n- **Google**: Google Workspace and consumer services (planned)\n\n---\n\n## OAuth Providers Mapping\n\n**File:** `credentials-provider/oauth/oauth_providers.yaml`\n**Purpose:** Provider-specific OAuth endpoint configurations and metadata.\n\n### Provider Fields\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `auth_url` | OAuth authorization URL | `https://accounts.google.com/o/oauth2/v2/auth` |\n| `token_url` | OAuth token exchange URL | `https://oauth2.googleapis.com/token` |\n| `scopes` | Default OAuth scopes | `[\"https://www.googleapis.com/auth/drive.readonly\"]` |\n| `client_credentials_supported` | Whether provider supports client credentials flow | `false` |\n\n---\n\n## Docker Compose Configuration\n\n**File:** `docker-compose.yml`\n**Purpose:** Container orchestration for development and deployment.\n\n### Services\n\n- **registry**: Main MCP Gateway Registry service\n- **auth-server**: OAuth2 authentication server\n- **frontend**: Web interface (React application)\n\n### Key Configuration\n\n- Environment variable injection from `.env` files\n- Port mappings for local development\n- Volume mounts for persistent data\n- Health checks and restart policies\n\n---\n\n## Configuration Security\n\n### Best Practices\n\n1. **Never commit real credentials** to version control\n2. **Use environment variables** for sensitive data\n3. **Rotate credentials regularly** especially for production\n4. **Limit scope permissions** to minimum required access\n5. **Monitor credential usage** through logging and audit trails\n\n### File Permissions\n\n- `.env` files should have `600` permissions (readable only by owner)\n- Configuration directories should have `700` permissions\n- Generated token files are automatically secured with `600` permissions\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Login redirects back to login page**\n - **Most Common Cause:** `SESSION_COOKIE_SECURE=true` but accessing via HTTP\n - **Solution for localhost:** Set `SESSION_COOKIE_SECURE=false` in `.env`\n - **Solution for production:** Ensure HTTPS is properly configured\n - **Check:** Browser dev tools → Application → Cookies (cookie should be present)\n - **Check:** Server logs for `Auth server setting session cookie: secure=...`\n\n2. **Missing environment variables**: Check that all required variables are set in the appropriate `.env` files\n\n3. **Invalid credentials**: Verify OAuth client IDs and secrets with providers\n\n4. **Network connectivity**: Ensure firewall rules allow OAuth callback URLs\n\n5. **Token expiration**: Use the credential refresh scripts to update expired tokens\n\n6. **Scope mismatches**: Verify requested OAuth scopes match provider configurations\n\n7. **Session cookie not being sent by browser**\n - Check cookie domain matches your hostname\n - Verify `SESSION_COOKIE_DOMAIN` is empty for single-domain deployments\n - Check browser third-party cookie settings\n - Inspect cookie attributes in browser dev tools\n\n### Validation Commands\n\n```bash\n# Validate OAuth configuration\ncd credentials-provider\n./generate_creds.sh --verbose\n\n# Test MCP gateway connectivity\ncd tests\n./tests/mcp_cmds.sh ping\n\n# Check configuration files\npython -c \"import yaml; yaml.safe_load(open('file.yml'))\" # YAML validation\n```\n\n### Log Files\n\n- **OAuth flows**: `.oauth-tokens/` directory contains generated tokens and logs\n- **Registry operations**: Check `registry.log` for service-level issues\n- **Authentication**: Check `auth.log` for OAuth and FGAC issues\n\n---\n\n## Viewing Configuration via UI\n\nAdministrators can view and export the current system configuration through the web interface.\n\n### Accessing the Configuration Viewer\n\n1. Navigate to **Settings** from the main dashboard\n2. Select **System Config** > **Configuration** from the sidebar\n\n![System Configuration Viewer](img/system-config.png)\n\n### Features\n\nThe Configuration Viewer provides:\n\n- **Grouped View**: Configuration parameters organized into categories:\n - Deployment Mode (includes tab visibility overrides)\n - Storage Backend\n - Authentication\n - Embeddings / Vector Search\n - Health Checks\n - WebSocket Settings\n - Security Scanning (MCP Servers)\n - Security Scanning (Agents)\n - Audit Logging\n - Federation\n - Well-Known Discovery\n\n- **Search**: Filter configuration parameters by name or value\n- **Expand/Collapse**: View all groups or focus on specific categories\n- **Sensitive Value Masking**: Passwords, API keys, and secrets are automatically masked\n- **Statistics**: Quick overview showing total, enabled, disabled, and issue counts\n\n### Export Options\n\nClick the **Export** button to download configuration in multiple formats:\n\n| Format | Description | Use Case |\n|--------|-------------|----------|\n| ENV | Shell environment variables | Docker/shell deployment |\n| JSON | Structured JSON format | Programmatic access |\n| TFVARS | Terraform variables | Infrastructure as Code |\n| YAML | YAML format | Kubernetes ConfigMaps |\n\n**Note**: Sensitive values are masked by default in exports. Use `include_sensitive=true` with caution.\n\n---\n\n## Configuration API\n\nThe registry provides REST API endpoints for programmatic configuration access.\n\n### GET /api/config\n\nReturns basic configuration information (public endpoint).\n\n```bash\ncurl -X GET \"https://your-registry/api/config\"\n```\n\n**Response:**\n```json\n{\n \"deployment_mode\": \"with-gateway\",\n \"registry_mode\": \"full\",\n \"nginx_updates_enabled\": true,\n \"asset_lifecycle_statuses\": [\"active\", \"deprecated\", \"experimental\"],\n \"features\": {\n \"mcp_servers\": true,\n \"agents\": true,\n \"skills\": true,\n \"virtual_servers\": true,\n \"federation\": true,\n \"gateway_proxy\": true\n }\n}\n```\n\n### GET /api/config/full\n\nReturns complete configuration grouped by category (admin only).\n\n```bash\ncurl -X GET \"https://your-registry/api/config/full\" \\\n -H \"Cookie: session=\"\n```\n\n**Response:**\n```json\n{\n \"groups\": {\n \"deployment\": {\n \"title\": \"Deployment Mode\",\n \"order\": 1,\n \"fields\": {\n \"deployment_mode\": {\n \"label\": \"Deployment Mode\",\n \"value\": { \"raw\": \"with-gateway\", \"display\": \"with-gateway\", \"is_masked\": false }\n }\n }\n }\n },\n \"generated_at\": \"2025-01-15T10:30:00Z\"\n}\n```\n\n### GET /api/config/export\n\nExport configuration in various formats (admin only).\n\n```bash\n# Export as ENV format\ncurl -X GET \"https://your-registry/api/config/export?format=env\" \\\n -H \"Cookie: session=\"\n\n# Export as JSON with sensitive values\ncurl -X GET \"https://your-registry/api/config/export?format=json&include_sensitive=true\" \\\n -H \"Cookie: session=\"\n```\n\n**Query Parameters:**\n\n| Parameter | Values | Default | Description |\n|-----------|--------|---------|-------------|\n| `format` | `env`, `json`, `tfvars`, `yaml` | `env` | Export format |\n| `include_sensitive` | `true`, `false` | `false` | Include sensitive values (use with caution) |\n\n**Rate Limiting**: These endpoints are rate-limited to 10 requests per minute per user." }, { "path": "docs/custom-metadata.md", "content": "# Custom Metadata for Servers & Agents\n\nEnrich your MCP servers and agents with custom metadata for organization, compliance tracking, and integration purposes. All metadata is fully searchable via semantic search.\n\n## Use Cases\n\n### Organization & Team Management\n\n```json\n{\n \"team\": \"data-platform\",\n \"owner\": \"alice@example.com\",\n \"department\": \"engineering\"\n}\n```\n*Search by: \"team:data-platform servers\", \"alice@example.com owned services\"*\n\n### Compliance & Governance\n\n```json\n{\n \"compliance_level\": \"PCI-DSS\",\n \"data_classification\": \"confidential\",\n \"regulatory_requirements\": [\"GDPR\", \"HIPAA\"],\n \"audit_logging\": true\n}\n```\n*Search by: \"PCI-DSS compliant servers\", \"HIPAA regulated services\"*\n\n### Cost & Project Tracking\n\n```json\n{\n \"cost_center\": \"analytics-dept\",\n \"project_code\": \"AI-2024-Q1\",\n \"budget_allocation\": \"R&D\"\n}\n```\n*Search by: \"cost center analytics\", \"project AI-2024-Q1\"*\n\n### Deployment & Integration\n\n```json\n{\n \"deployment_region\": \"us-east-1\",\n \"environment\": \"production\",\n \"jira_ticket\": \"MCPGW-123\",\n \"version\": \"2.1.0\"\n}\n```\n*Search by: \"us-east-1 deployed services\", \"JIRA MCPGW-123\", \"version 2.1.0\"*\n\n## API Usage\n\n### Register MCP Server with Metadata\n\n```bash\ncurl -X POST https://registry.example.com/api/services/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"payment-processor\",\n \"description\": \"Payment processing service\",\n \"path\": \"/payment-processor\",\n \"proxy_pass_url\": \"http://payment:8080\",\n \"metadata\": {\n \"team\": \"finance-platform\",\n \"owner\": \"alice@example.com\",\n \"compliance_level\": \"PCI-DSS\",\n \"cost_center\": \"finance-ops\",\n \"deployment_region\": \"us-east-1\"\n }\n }'\n```\n\n### Register A2A Agent with Metadata\n\n```bash\ncurl -X POST https://registry.example.com/api/agents/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"analytics-agent\",\n \"description\": \"Data analytics agent\",\n \"metadata\": {\n \"team\": \"data-science\",\n \"owner\": \"bob@example.com\",\n \"version\": \"3.2.1\",\n \"cost_center\": \"analytics-dept\"\n }\n }'\n```\n\n### Search by Metadata\n\n```bash\n# Find servers by team\ncurl \"https://registry.example.com/api/search?q=team:finance-platform\"\n\n# Find PCI-DSS compliant services\ncurl \"https://registry.example.com/api/search?q=PCI-DSS compliant services\"\n\n# Find services by owner\ncurl \"https://registry.example.com/api/search?q=alice@example.com owned\"\n\n# Find services in specific region\ncurl \"https://registry.example.com/api/search?q=us-east-1 deployed\"\n```\n\n## Key Features\n\n- **Flexible Schema:** Store any JSON-serializable data (strings, numbers, booleans, nested objects, arrays)\n- **Fully Searchable:** All metadata included in semantic search embeddings\n- **Backward Compatible:** Optional field - existing registrations work without modification\n- **Type-Safe:** Pydantic validation ensures data integrity\n- **REST API:** Full CRUD support via standard API endpoints\n\n## Related Documentation\n\n- [Service Management Guide](service-management.md)\n- [A2A Agent Guide](a2a.md)\n- [Semantic Search](design/hybrid-search-architecture.md)\n" }, { "path": "docs/database-design.md", "content": "# Database Design - MCP Gateway Registry\n\n## Overview\n\nThe MCP Gateway Registry supports three storage backends for data persistence:\n\n1. **File-Based Backend** (Legacy, Backwards Compatible)\n - JSON file storage in the local filesystem\n - Maintained for backwards compatibility\n - Single-node deployments only\n - FAISS-based vector search\n\n2. **MongoDB CE** (Local Development)\n - MongoDB Community Edition 8.2\n - Docker-based local deployment\n - Application-level vector search\n - Development and testing environments\n\n3. **AWS DocumentDB** (Production, Recommended)\n - MongoDB-compatible managed service\n - Supports clustering configuration\n - Native vector search with HNSW indexes\n - Multi-tenancy support via namespaces\n - Recommended for all production deployments\n\nThe default configuration for local development uses **MongoDB CE**, while production deployments use **AWS DocumentDB**.\n\n---\n\n## Quick Architecture Reference\n\n```\nApplication Services\n │\n ▼\nRepository Factory (factory.py)\n │\n ├─> File Backend (legacy)\n │ └─> Local JSON files + FAISS\n │\n ├─> MongoDB CE (local dev)\n │ └─> Docker container + app-level vector search\n │\n └─> AWS DocumentDB (production)\n └─> Managed service + native vector search\n```\n\n---\n\n## Storage Backend Comparison\n\n| Feature | File | MongoDB CE | AWS DocumentDB |\n|---------|------|------------|----------------|\n| **Use Case** | Legacy/Testing | Local Development | Production |\n| **Setup** | None | Docker Compose | Terraform |\n| **Scalability** | ~1,000 entities | ~10,000 | Millions |\n| **Vector Search** | FAISS (local) | Python (app-level) | HNSW (native) |\n| **Query Latency** | 50-100ms | 50-200ms | 10-50ms |\n| **Concurrency** | Limited | Good | Excellent |\n| **HA/Clustering** | No | Manual | Automatic |\n| **Multi-tenancy** | No | Via namespace | Via namespace |\n| **Cost** | Free | Free | AWS pricing |\n| **Best For** | Quick start | Feature development | Production |\n\n---\n\n## MongoDB CE & DocumentDB Architecture\n\nFor detailed information about the MongoDB and DocumentDB backends, see:\n\n**[Storage Architecture: MongoDB CE & AWS DocumentDB](./design/storage-architecture-mongodb-documentdb.md)**\n\nThis comprehensive guide covers:\n- MongoDB CE local development setup\n- AWS DocumentDB production deployment\n- Vector search implementation (app-level vs. native)\n- Build and run process with `build_and_run.sh`\n- Collection schemas and indexes\n- Migration strategies\n- Performance characteristics\n\n### Quick Summary\n\n**Collections (both MongoDB CE and DocumentDB):**\n\nAll collections are suffixed with the configured namespace (e.g., `_default`, `_production`):\n\n1. **mcp_servers_{namespace}** - Server definitions\n2. **mcp_agents_{namespace}** - Agent cards\n3. **mcp_scopes_{namespace}** - Authorization scopes\n4. **mcp_embeddings_1536_{namespace}** - Vector embeddings\n5. **mcp_security_scans_{namespace}** - Security scan results\n6. **mcp_federation_config_{namespace}** - Federation configuration\n\n**Key Differences:**\n\n| Aspect | MongoDB CE | AWS DocumentDB |\n|--------|------------|----------------|\n| Vector Search | Python cosine similarity | HNSW index |\n| Connection | `mongodb://mongodb:27017` | `mongodb://cluster.docdb.amazonaws.com:27017` |\n| Authentication | None (local) | Username/Password or IAM |\n| TLS | Disabled | Required |\n| Deployment | Docker Compose | Terraform |\n\n---\n\n## Collection Schemas\n\n### 1. MCP Servers\n\n**Collection:** `mcp_servers_{namespace}`\n\nStores MCP server definitions and metadata.\n\n**Document Structure:**\n\n```json\n{\n \"_id\": \"/servers/financial-data\",\n \"server_name\": \"Financial Data Server\",\n \"description\": \"Provides stock market data and analysis\",\n \"path\": \"/servers/financial-data\",\n \"proxy_pass_url\": \"http://financial-server:8000\",\n \"supported_transports\": [\"stdio\", \"sse\"],\n \"auth_type\": \"oauth\",\n \"tags\": [\"finance\", \"data\", \"stocks\"],\n \"num_tools\": 15,\n \"tool_list\": [\n {\n \"name\": \"get_stock_price\",\n \"description\": \"Get current stock price\",\n \"schema\": { /* JSON schema */ }\n }\n ],\n \"is_enabled\": true,\n \"registered_at\": \"2026-01-03T10:00:00Z\",\n \"updated_at\": \"2026-01-03T12:30:00Z\",\n \"ans_metadata\": null\n}\n```\n\nThe `ans_metadata` field follows the same structure as in the agents collection (see below). It is `null` when no ANS link is configured.\n\n**Indexes:**\n\n- `path` (unique) - Primary key\n- `is_enabled` - Filter active servers\n- `tags` - Tag-based filtering\n- `server_name` - Text search\n\n---\n\n### 2. A2A Agents\n\n**Collection:** `mcp_agents_{namespace}`\n\nStores Agent-to-Agent (A2A) agent cards and capabilities.\n\n**Document Structure:**\n\n```json\n{\n \"_id\": \"/agents/financial-analyst\",\n \"protocol_version\": \"1.0\",\n \"name\": \"Financial Analysis Agent\",\n \"description\": \"Analyzes financial data and provides insights\",\n \"path\": \"/agents/financial-analyst\",\n \"url\": \"https://registry.example.com/agents/financial-analyst\",\n \"version\": \"2.1.0\",\n \"capabilities\": [\"analysis\", \"reporting\", \"forecasting\"],\n \"tags\": [\"finance\", \"analysis\"],\n \"is_enabled\": true,\n \"visibility\": \"public\",\n \"trust_level\": \"high\",\n \"registered_at\": \"2026-01-02T09:00:00Z\",\n \"updated_at\": \"2026-01-03T11:00:00Z\",\n \"ans_metadata\": {\n \"ans_agent_id\": \"ans://v1.0.0.agent.example.com\",\n \"linked_at\": \"2026-01-02T09:00:00Z\",\n \"last_verified\": \"2026-01-02T09:00:00Z\",\n \"status\": \"verified\",\n \"domain\": \"agent.example.com\",\n \"organization\": null,\n \"ans_name\": \"ans://v1.0.0.agent.example.com\",\n \"ans_display_name\": \"Financial Analysis Agent\",\n \"ans_version\": \"1.0.0\",\n \"registered_with_ans_at\": \"2026-01-01T12:00:00Z\",\n \"certificate\": null,\n \"endpoints\": [\n { \"type\": \"http\", \"url\": \"https://agent.example.com/a2a\", \"protocol\": \"A2A\", \"transports\": [\"STREAMABLE-HTTP\"], \"functions\": [] }\n ],\n \"links\": [\n { \"rel\": \"self\", \"href\": \"https://api.godaddy.com/v1/agents/uuid\" },\n { \"rel\": \"server-certificates\", \"href\": \"https://api.godaddy.com/v1/agents/uuid/certificates/server\" },\n { \"rel\": \"identity-certificates\", \"href\": \"https://api.godaddy.com/v1/agents/uuid/certificates/identity\" }\n ],\n \"raw_ans_response\": {}\n }\n}\n```\n\nThe `ans_metadata` field is `null` when no ANS Agent ID is linked. It is populated when an agent is linked to the GoDaddy Agent Name Service (ANS) for PKI-based identity verification.\n\n**Indexes:**\n\n- `path` (unique) - Primary key\n- `is_enabled` - Filter active agents\n- `tags` - Tag-based filtering\n- `name` - Text search\n- `visibility` - Access control\n- `ans_metadata.status` - Filter by ANS verification status\n\n---\n\n### 3. Authorization Scopes\n\n**Collection:** `mcp_scopes_{namespace}`\n\nStores authorization scopes, permission mappings, and UI access control.\n\n**Document Types:**\n\nThe scopes collection stores three document types, distinguished by `scope_type`:\n\n#### Server Scope Document\n\n```json\n{\n \"_id\": \"scope:admin_access\",\n \"scope_type\": \"server_scope\",\n \"scope_name\": \"admin_access\",\n \"server_access\": [\n {\n \"server\": \"financial_server\",\n \"methods\": [\"GET\", \"POST\", \"PUT\"],\n \"tools\": [\"analyze_data\", \"generate_report\"]\n }\n ],\n \"description\": \"Full access to financial servers\",\n \"created_at\": \"2026-01-01T08:00:00Z\",\n \"updated_at\": \"2026-01-03T10:00:00Z\"\n}\n```\n\n#### Group Mapping Document\n\n```json\n{\n \"_id\": \"group:finance_team\",\n \"scope_type\": \"group_mapping\",\n \"group_name\": \"finance_team\",\n \"group_mappings\": [\"admin_access\", \"read_only_access\"],\n \"created_at\": \"2026-01-01T08:00:00Z\",\n \"updated_at\": \"2026-01-03T10:00:00Z\"\n}\n```\n\n#### UI Scope Document\n\n```json\n{\n \"_id\": \"ui:finance_team\",\n \"scope_type\": \"ui_scope\",\n \"scope_name\": \"finance_team\",\n \"ui_permissions\": {\n \"list_service\": [\"financial_server\", \"analytics_server\"]\n },\n \"created_at\": \"2026-01-01T08:00:00Z\",\n \"updated_at\": \"2026-01-03T10:00:00Z\"\n}\n```\n\n**Indexes:**\n\n- `_id` (unique) - Primary key\n- `scope_type` - Document type filter\n- `scope_name` - Scope lookup\n- `group_name` - Group lookup\n\n---\n\n### 4. Vector Embeddings\n\n**Collection:** `mcp_embeddings_{dimensions}_{namespace}`\n\nExample: `mcp_embeddings_1536_default` for 1536-dimensional embeddings\n\nStores vector embeddings for semantic search across servers and agents.\n\n**Document Structure:**\n\n```json\n{\n \"_id\": \"/servers/financial-data\",\n \"entity_type\": \"mcp_server\",\n \"path\": \"/servers/financial-data\",\n \"name\": \"Financial Data Server\",\n \"description\": \"Provides stock market data and analysis\",\n \"tags\": [\"finance\", \"data\"],\n \"is_enabled\": true,\n \"text_for_embedding\": \"Financial Data Server. Provides stock market data and analysis. Tools: get_stock_price, analyze_portfolio\",\n \"embedding\": [0.125, -0.342, 0.098, ...], // 1536 floats\n \"embedding_metadata\": {\n \"model\": \"amazon.titan-embed-text-v1\",\n \"provider\": \"litellm\",\n \"dimensions\": 1536,\n \"created_at\": \"2026-01-03T10:30:00Z\"\n },\n \"tools\": [\n {\"name\": \"get_stock_price\", \"description\": \"Get current stock price\"}\n ],\n \"metadata\": { /* full server info */ },\n \"indexed_at\": \"2026-01-03T10:30:00Z\"\n}\n```\n\n**Indexes:**\n\n- `path` (unique) - Primary key\n- `entity_type` - Filter by entity type\n- `embedding` (vector) - **DocumentDB only:** HNSW vector index for fast similarity search\n ```javascript\n // HNSW index configuration (DocumentDB)\n {\n \"type\": \"hnsw\",\n \"similarity\": \"cosine\",\n \"dimensions\": 1536,\n \"m\": 16,\n \"efConstruction\": 128\n }\n ```\n\n**Vector Search:**\n\n- **MongoDB CE:** Application-level cosine similarity in Python\n- **DocumentDB:** Native HNSW index for sub-100ms queries\n\n---\n\n### 5. Security Scans\n\n**Collection:** `mcp_security_scans_{namespace}`\n\nStores security vulnerability scan results.\n\n**Document Structure:**\n\n```json\n{\n \"_id\": \"scan:financial_server:2026-01-03\",\n \"server_path\": \"/servers/financial-data\",\n \"scan_timestamp\": \"2026-01-03T14:00:00Z\",\n \"scan_status\": \"unsafe\",\n \"vulnerabilities\": [\n {\n \"severity\": \"high\",\n \"title\": \"SQL Injection vulnerability\",\n \"description\": \"User input not sanitized\",\n \"cve_id\": \"CVE-2024-12345\",\n \"package_name\": \"db-connector\",\n \"package_version\": \"2.1.0\",\n \"fixed_version\": \"2.1.5\"\n }\n ],\n \"risk_score\": 0.75,\n \"total_vulnerabilities\": 2,\n \"critical_count\": 0,\n \"high_count\": 1,\n \"medium_count\": 1,\n \"low_count\": 0\n}\n```\n\n**Indexes:**\n\n- `server_path` - Lookup scans by server\n- `scan_status` - Filter by status\n- `scan_timestamp` (descending) - Get latest scans\n\n---\n\n### 6. Federation Config\n\n**Collection:** `mcp_federation_config_{namespace}`\n\nStores federation configuration for external registries (Anthropic, ASOR).\n\n**Document Structure:**\n\n```json\n{\n \"_id\": \"federation-config\",\n \"anthropic\": {\n \"enabled\": true,\n \"endpoint\": \"https://registry.modelcontextprotocol.io\",\n \"sync_on_startup\": true,\n \"servers\": [\n {\"name\": \"weather-service\"},\n {\"name\": \"news-aggregator\"}\n ]\n },\n \"asor\": {\n \"enabled\": false,\n \"endpoint\": \"https://asor-registry.example.com\",\n \"auth_env_var\": \"ASOR_AUTH_TOKEN\",\n \"sync_on_startup\": false,\n \"agents\": []\n },\n \"updated_at\": \"2026-01-03T12:00:00Z\"\n}\n```\n\n**Indexes:**\n\n- `_id` (unique) - Single config per namespace\n\n---\n\n## Vector Search Architecture\n\n### Embedding Generation\n\n**Module:** `registry/embeddings/`\n\n**Supported Providers:**\n\n1. **Sentence Transformers** (Default, Local)\n - Model: `all-MiniLM-L6-v2` (384 dimensions)\n - Runs locally, no API costs\n - Good for development\n\n2. **OpenAI** (Cloud)\n - Model: `text-embedding-ada-002` (1536 dimensions)\n - Requires API key\n - High quality embeddings\n\n3. **Amazon Bedrock Titan** (Cloud)\n - Model: `amazon.titan-embed-text-v1` (1536 dimensions)\n - Uses IAM authentication\n - AWS-native integration\n\n### Search Implementation\n\n**See:** [Storage Architecture: MongoDB CE & AWS DocumentDB](./design/storage-architecture-mongodb-documentdb.md) for detailed search implementation.\n\n**Summary:**\n\n| Backend | Algorithm | Complexity | Latency |\n|---------|-----------|------------|---------|\n| MongoDB CE | Python cosine similarity | O(n) | 50-200ms |\n| DocumentDB | HNSW index | O(log n) | 10-50ms |\n\n### Hybrid Search\n\nBoth backends combine:\n- **Vector similarity** (semantic matching) - Primary ranking\n- **Text matching** (keyword boosting) - Secondary bonus\n\n**Formula:**\n\n```\nfinal_score = vector_score + (text_boost * 0.03)\n\nWhere:\n vector_score = cosine_similarity(query_embedding, doc_embedding) // 0-1\n text_boost = 3.0 (name match) + 2.0 (description match) // 0-5\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n**File:** `.env`\n\n```bash\n# Storage Backend Selection\n# Options:\n# \"file\" - JSON files (legacy)\n# \"mongodb-ce\" - MongoDB Community Edition (local dev)\n# \"documentdb\" - AWS DocumentDB (production)\nSTORAGE_BACKEND=mongodb-ce\n\n# MongoDB/DocumentDB Connection\nDOCUMENTDB_HOST=mongodb # Local: \"mongodb\", Prod: \"cluster.docdb.amazonaws.com\"\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=default # Multi-tenancy: dev, staging, production\n\n# Authentication (not needed for MongoDB CE)\nDOCUMENTDB_USERNAME=admin\nDOCUMENTDB_PASSWORD=secure_password\n\n# TLS (MongoDB CE: false, DocumentDB: true)\nDOCUMENTDB_USE_TLS=false\nDOCUMENTDB_TLS_CA_FILE=global-bundle.pem\nDOCUMENTDB_USE_IAM=false\n\n# Replica Set\nDOCUMENTDB_REPLICA_SET=rs0\nDOCUMENTDB_READ_PREFERENCE=secondaryPreferred\n\n# Embeddings Configuration\nEMBEDDINGS_PROVIDER=sentence-transformers # Or: litellm\nEMBEDDINGS_MODEL_NAME=all-MiniLM-L6-v2 # Or: openai/text-embedding-ada-002\nEMBEDDINGS_MODEL_DIMENSIONS=384 # Or: 1536\n```\n\n### Initialization\n\n**MongoDB CE:**\n\n```bash\n# Start MongoDB and initialize\ndocker compose up -d mongodb\ndocker compose up mongodb-init\n\n# Verify\ndocker exec mcp-mongodb mongosh --eval \"use mcp_registry; show collections\"\n```\n\n**AWS DocumentDB:**\n\n```bash\n# Deploy with Terraform\ncd terraform/aws-ecs\nterraform apply\n\n# Collections and indexes created automatically on first application startup\n```\n\n---\n\n## Repository Layer\n\nAll database operations go through repository interfaces defined in [`registry/repositories/interfaces.py`](../registry/repositories/interfaces.py):\n\n- **ServerRepositoryBase:** Server CRUD operations\n- **AgentRepositoryBase:** Agent card CRUD operations\n- **ScopeRepositoryBase:** Authorization scope management\n- **SecurityScanRepositoryBase:** Vulnerability scan storage\n- **FederationConfigRepositoryBase:** Federation configuration\n- **SearchRepositoryBase:** Vector search operations\n\n**Factory:** `registry/repositories/factory.py`\n\nThe repository factory automatically selects the correct implementation based on `STORAGE_BACKEND`:\n\n```python\nif backend in [\"documentdb\", \"mongodb-ce\"]:\n from .documentdb.server_repository import DocumentDBServerRepository\n return DocumentDBServerRepository()\nelse:\n from .file.server_repository import FileServerRepository\n return FileServerRepository()\n```\n\n**Key Point:** `mongodb-ce` and `documentdb` use the **same repository code**. The only difference is the connection configuration.\n\n---\n\n## Migration from File Backend\n\n### To MongoDB CE (Local Development)\n\n1. **Update configuration:**\n ```bash\n # In .env\n STORAGE_BACKEND=mongodb-ce\n ```\n\n2. **Start MongoDB:**\n ```bash\n docker compose up -d mongodb\n docker compose up mongodb-init\n ```\n\n3. **Re-register servers and agents:**\n ```bash\n # Use API to register from backup files\n for file in backup/*.json; do\n curl -X POST http://localhost:7860/servers \\\n -H \"Content-Type: application/json\" \\\n -d @\"$file\"\n done\n ```\n\n### To AWS DocumentDB (Production)\n\n1. **Deploy infrastructure:**\n ```bash\n cd terraform/aws-ecs\n terraform apply\n ```\n\n2. **Update configuration:**\n ```bash\n STORAGE_BACKEND=documentdb\n DOCUMENTDB_HOST=\n DOCUMENTDB_USERNAME=\n DOCUMENTDB_PASSWORD=\n DOCUMENTDB_USE_TLS=true\n ```\n\n3. **Import data:**\n ```bash\n # Use mongodump/mongorestore or API\n mongorestore --host= --ssl --db=mcp_registry ./backup\n ```\n\n---\n\n## Performance Considerations\n\n### MongoDB CE (Local Development)\n\n- **Good for:** <10,000 documents\n- **Search latency:** 50-200ms (O(n) scan)\n- **Indexing:** Fast document insertion\n- **Scaling:** Limited to single container resources\n\n### AWS DocumentDB (Production)\n\n- **Good for:** Millions of documents\n- **Search latency:** 10-50ms (O(log n) HNSW)\n- **Indexing:** Distributed across cluster\n- **Scaling:** Horizontal (add read replicas), vertical (instance size)\n\n### Optimization Tips\n\n1. **Use appropriate instance sizes** (DocumentDB)\n - `db.r5.large` for development\n - `db.r5.xlarge` or larger for production\n\n2. **Enable read replicas** for high read throughput\n\n3. **Tune HNSW parameters** (DocumentDB)\n - `m=16, efConstruction=128` balances accuracy and speed\n - Increase for higher accuracy (slower)\n - Decrease for faster search (lower accuracy)\n\n4. **Monitor query patterns** and create additional indexes as needed\n\n---\n\n## See Also\n\n- **[Storage Architecture: MongoDB CE & AWS DocumentDB](./design/storage-architecture-mongodb-documentdb.md)** - Comprehensive guide\n- **[Database Abstraction Layer Design](./design/database-abstraction-layer.md)** - Repository pattern details\n- **[Embeddings Configuration](./embeddings.md)** - Vector embedding setup\n- **[Configuration Guide](./configuration.md)** - Full configuration reference\n- [MongoDB Documentation](https://www.mongodb.com/docs/manual/)\n- [AWS DocumentDB Documentation](https://docs.aws.amazon.com/documentdb/)\n" }, { "path": "docs/datastore-management.md", "content": "# Datastore Management Guide\n\n**Last Updated:** January 3, 2026\n**Applies to:** All storage backends (MongoDB CE, AWS DocumentDB)\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Local Development - MongoDB CE](#local-development---mongodb-ce)\n3. [Production - AWS DocumentDB via ECS](#production---aws-documentdb-via-ecs)\n4. [Common Operations](#common-operations)\n5. [Troubleshooting](#troubleshooting)\n\n---\n\n## Overview\n\nThe MCP Gateway Registry uses MongoDB-compatible datastores for storage:\n\n- **Local Development:** MongoDB Community Edition 8.2 in Docker\n- **Production:** AWS DocumentDB (MongoDB-compatible managed service)\n\nThis guide explains how to access and manage datastores in both environments.\n\n---\n\n## Local Development - MongoDB CE\n\n### Prerequisites\n\n- MongoDB container running: `docker compose ps mongodb` shows \"healthy\"\n- No authentication required (configured for local dev simplicity)\n\n### Accessing the Datastore (mongosh)\n\n#### Method 1: Direct Docker Exec (Recommended)\n\n```bash\n# Connect to MongoDB shell\ndocker exec -it mcp-mongodb mongosh\n\n# You should see:\n# Current Mongosh Log ID: ...\n# Connecting to: mongodb://127.0.0.1:27017/?directConnection=true\n# ...\n# rs0 [direct: primary] test>\n```\n\n#### Method 2: Connect from Host Machine\n\nIf you have `mongosh` installed locally:\n\n```bash\nmongosh mongodb://localhost:27017/mcp_registry\n```\n\n### Basic Datastore Operations\n\nOnce connected to mongosh:\n\n```javascript\n// Switch to the registry database\nuse mcp_registry\n\n// List all collections\nshow collections\n// Expected output:\n// mcp_agents_default\n// mcp_embeddings_1536_default\n// mcp_federation_config_default\n// mcp_scopes_default\n// mcp_security_scans_default\n// mcp_servers_default\n\n// Check replica set status\nrs.status()\n\n// View database statistics\ndb.stats()\n```\n\n### Viewing Collection Contents\n\n#### List All Servers\n\n```javascript\n// Count total servers\ndb.mcp_servers_default.countDocuments()\n\n// View all servers (formatted)\ndb.mcp_servers_default.find().pretty()\n\n// View specific server by path\ndb.mcp_servers_default.findOne({ path: \"/servers/financial-data\" })\n\n// List only server names and paths\ndb.mcp_servers_default.find(\n {},\n { \"manifest.serverInfo.name\": 1, path: 1, _id: 0 }\n)\n```\n\n#### List All Agents\n\n```javascript\n// Count total agents\ndb.mcp_agents_default.countDocuments()\n\n// View all agents\ndb.mcp_agents_default.find().pretty()\n\n// Find agents by tag\ndb.mcp_agents_default.find({ tags: \"finance\" }).pretty()\n```\n\n#### View Vector Embeddings\n\n```javascript\n// Count embeddings\ndb.mcp_embeddings_1536_default.countDocuments()\n\n// View embedding metadata (without the large vector array)\ndb.mcp_embeddings_1536_default.find(\n {},\n {\n path: 1,\n entity_type: 1,\n name: 1,\n embedding_metadata: 1,\n indexed_at: 1,\n _id: 0\n }\n).pretty()\n\n// Check specific embedding\ndb.mcp_embeddings_1536_default.findOne({ path: \"/servers/financial-data\" })\n```\n\n#### View Scopes\n\n```javascript\n// List all scopes\ndb.mcp_scopes_default.find().pretty()\n\n// Find server scopes\ndb.mcp_scopes_default.find({ scope_type: \"server_scope\" }).pretty()\n\n// Find group mappings\ndb.mcp_scopes_default.find({ scope_type: \"group_mapping\" }).pretty()\n```\n\n#### View Security Scans\n\n```javascript\n// Count security scans\ndb.mcp_security_scans_default.countDocuments()\n\n// View latest scans\ndb.mcp_security_scans_default.find().sort({ scan_timestamp: -1 }).limit(5).pretty()\n\n// Find scans for specific server\ndb.mcp_security_scans_default.find({ server_path: \"/servers/financial-data\" }).pretty()\n```\n\n### Collection Indexes\n\n```javascript\n// View indexes on servers collection\ndb.mcp_servers_default.getIndexes()\n\n// View indexes on embeddings collection\ndb.mcp_embeddings_1536_default.getIndexes()\n\n// Check index usage stats\ndb.mcp_servers_default.aggregate([{ $indexStats: {} }])\n```\n\n### Query Performance Analysis\n\n```javascript\n// Explain query execution plan\ndb.mcp_servers_default.find({ path: \"/servers/financial-data\" }).explain(\"executionStats\")\n\n// Find slow operations (if profiling enabled)\ndb.system.profile.find({ millis: { $gt: 100 } }).sort({ ts: -1 }).limit(5).pretty()\n```\n\n### Exiting mongosh\n\n```javascript\n// Exit the shell\nexit\n```\n\nOr press `Ctrl+D`\n\n---\n\n## Production - AWS DocumentDB via ECS\n\n### Prerequisites\n\n- AWS ECS cluster running with DocumentDB\n- ECS exec permissions configured\n- `manage-documentdb.py` script available in registry container\n\n### Accessing DocumentDB via ECS Exec\n\n#### Step 1: SSH into Registry Container\n\n```bash\n# From your local machine\n# Use the ecs-ssh helper script\ncd terraform/aws-ecs\n./scripts/ecs-ssh.sh registry\n\n# Or manually with AWS CLI\naws ecs execute-command \\\n --cluster mcp-gateway-ecs-cluster \\\n --task \\\n --container registry \\\n --interactive \\\n --command \"/bin/bash\"\n```\n\n#### Step 2: Activate Python Virtual Environment\n\n```bash\n# Inside the ECS container\nsource .venv/bin/activate\n\n# Verify Python environment\nwhich python\n# Should show: /app/.venv/bin/python\n```\n\n#### Step 3: Run DocumentDB Management Script\n\nThe `manage-documentdb.py` script provides commands for managing collections and querying data.\n\n##### List All Collections\n\n```bash\npython scripts/manage-documentdb.py list\n```\n\n##### Inspect a Collection\n\n```bash\n# Show collection schema and indexes\npython scripts/manage-documentdb.py inspect --collection mcp_servers_default\n```\n\n##### Count Documents\n\n```bash\n# Count all documents in collection\npython scripts/manage-documentdb.py count --collection mcp_servers_default\n```\n\n##### Search Documents\n\n```bash\n# List documents with optional limit\npython scripts/manage-documentdb.py search --collection mcp_servers_default --limit 5\n\n# Search specific collection\npython scripts/manage-documentdb.py search --collection mcp_agents_default --limit 10\n```\n\n##### View Sample Document\n\n```bash\n# Show one sample document from collection\npython scripts/manage-documentdb.py sample --collection mcp_servers_default\n```\n\n##### Query with Filter\n\n```bash\n# Query with MongoDB filter syntax\npython scripts/manage-documentdb.py query \\\n --collection mcp_servers_default \\\n --filter '{\"path\": \"/servers/financial-data\"}'\n\n# Query enabled servers\npython scripts/manage-documentdb.py query \\\n --collection mcp_servers_default \\\n --filter '{\"enabled\": true}'\n\n# Query by tags\npython scripts/manage-documentdb.py query \\\n --collection mcp_servers_default \\\n --filter '{\"tags\": \"finance\"}'\n```\n\n##### View Embeddings\n\n```bash\n# Sample embedding document (shows structure without large vector array)\npython scripts/manage-documentdb.py sample --collection mcp_embeddings_1536_default\n\n# Count total embeddings\npython scripts/manage-documentdb.py count --collection mcp_embeddings_1536_default\n```\n\n**Note:** The script automatically reads connection parameters from environment variables in the ECS container (`DOCUMENTDB_HOST`, `DOCUMENTDB_USERNAME`, `DOCUMENTDB_PASSWORD`, etc.).\n\n---\n\n## Common Operations\n\n### Checking Datastore Health\n\n#### Local (MongoDB CE)\n\n```javascript\n// In mongosh\ndb.serverStatus()\ndb.stats()\nrs.status()\n```\n\n#### Production (DocumentDB)\n\n```bash\n# Use count command to verify connection and check collections\npython scripts/manage-documentdb.py list\n\n# Check specific collection\npython scripts/manage-documentdb.py count --collection mcp_servers_default\n```\n\n### Searching for Specific Documents\n\n#### Local (MongoDB CE)\n\n```javascript\n// Search servers by tag\ndb.mcp_servers_default.find({ tags: \"finance\" })\n\n// Search by partial name match\ndb.mcp_servers_default.find({\n \"manifest.serverInfo.name\": /financial/i\n})\n\n// Complex query with multiple conditions\ndb.mcp_servers_default.find({\n enabled: true,\n tags: { $in: [\"finance\", \"data\"] }\n})\n```\n\n#### Production (DocumentDB)\n\n```bash\n# Search by tags\npython scripts/manage-documentdb.py query \\\n --collection mcp_servers_default \\\n --filter '{\"tags\": \"finance\"}'\n\n# Query enabled servers\npython scripts/manage-documentdb.py query \\\n --collection mcp_servers_default \\\n --filter '{\"enabled\": true}'\n```\n\n### Viewing Recent Activity\n\n#### Local (MongoDB CE)\n\n```javascript\n// Recent server registrations\ndb.mcp_servers_default.find().sort({ registered_at: -1 }).limit(5)\n\n// Recent embeddings\ndb.mcp_embeddings_1536_default.find().sort({ indexed_at: -1 }).limit(5)\n\n// Recent security scans\ndb.mcp_security_scans_default.find().sort({ scan_timestamp: -1 }).limit(5)\n```\n\n#### Production (DocumentDB)\n\n```bash\n# View recent servers (sorted by registration)\npython scripts/manage-documentdb.py search \\\n --collection mcp_servers_default \\\n --limit 5\n\n# View recent embeddings\npython scripts/manage-documentdb.py search \\\n --collection mcp_embeddings_1536_default \\\n --limit 5\n```\n\n### Backup and Export\n\n#### Local (MongoDB CE)\n\n##### Option 1: Binary Backup (mongodump) - Recommended for Full Backups\n\n```bash\n# Export entire database (BSON format - preserves data types)\ndocker exec mcp-mongodb mongodump \\\n --db=mcp_registry \\\n --out=/tmp/mongodb-backup\n\n# Copy backup from container to host\ndocker cp mcp-mongodb:/tmp/mongodb-backup ./mongodb-backup-$(date +%Y%m%d)\n\n# Restore from backup (if needed)\ndocker cp ./mongodb-backup-20260103 mcp-mongodb:/tmp/restore-backup\ndocker exec mcp-mongodb mongorestore \\\n --db=mcp_registry \\\n /tmp/restore-backup/mcp_registry\n```\n\n##### Option 2: JSON Export (mongoexport) - Human-Readable, Portable\n\n```bash\n# Export specific collection to JSON (one document per line)\ndocker exec mcp-mongodb mongoexport \\\n --db=mcp_registry \\\n --collection=mcp_servers_default \\\n --out=/tmp/servers.json\n\n# Copy to host\ndocker cp mcp-mongodb:/tmp/servers.json ./servers-backup-$(date +%Y%m%d).json\n\n# Pretty-print JSON (optional, for readability)\ndocker exec mcp-mongodb mongoexport \\\n --db=mcp_registry \\\n --collection=mcp_servers_default \\\n --jsonArray \\\n --pretty \\\n --out=/tmp/servers-pretty.json\n\n# Import from JSON (if needed)\ndocker cp ./servers-backup-20260103.json mcp-mongodb:/tmp/import-servers.json\ndocker exec mcp-mongodb mongoimport \\\n --db=mcp_registry \\\n --collection=mcp_servers_default \\\n --file=/tmp/import-servers.json\n```\n\n##### Export All Collections\n\n```bash\n# Export all collections to JSON\nCOLLECTIONS=\"mcp_servers_default mcp_agents_default mcp_scopes_default mcp_embeddings_1536_default mcp_security_scans_default mcp_federation_config_default\"\n\nfor collection in $COLLECTIONS; do\n echo \"Exporting $collection...\"\n docker exec mcp-mongodb mongoexport \\\n --db=mcp_registry \\\n --collection=$collection \\\n --out=/tmp/${collection}.json\n docker cp mcp-mongodb:/tmp/${collection}.json ./${collection}-$(date +%Y%m%d).json\ndone\n```\n\n#### Production (DocumentDB)\n\n##### Option 1: AWS Automated Backups (Recommended)\n\nAWS DocumentDB provides automated continuous backups with point-in-time recovery:\n\n```bash\n# Create manual snapshot (from local machine with AWS CLI)\naws docdb create-db-cluster-snapshot \\\n --db-cluster-snapshot-identifier mcp-registry-manual-$(date +%Y%m%d) \\\n --db-cluster-identifier mcp-registry-prod\n\n# List available snapshots\naws docdb describe-db-cluster-snapshots \\\n --db-cluster-identifier mcp-registry-prod\n\n# Restore from snapshot (creates new cluster)\naws docdb restore-db-cluster-from-snapshot \\\n --db-cluster-identifier mcp-registry-restored \\\n --snapshot-identifier mcp-registry-manual-20260103 \\\n --engine docdb\n```\n\n##### Option 2: Binary Backup with mongodump (from ECS Container)\n\n```bash\n# SSH into ECS container\ncd terraform/aws-ecs\n./scripts/ecs-ssh.sh registry\nsource .venv/bin/activate\n\n# Export entire database to BSON\nmongodump \\\n --host=$DOCUMENTDB_HOST \\\n --port=27017 \\\n --username=$DOCUMENTDB_USERNAME \\\n --password=$DOCUMENTDB_PASSWORD \\\n --ssl \\\n --sslCAFile=/app/global-bundle.pem \\\n --db=mcp_registry \\\n --out=/tmp/documentdb-backup\n\n# Upload to S3\nBACKUP_DATE=$(date +%Y%m%d-%H%M%S)\naws s3 cp /tmp/documentdb-backup \\\n s3://mcp-gateway-backups/documentdb-backup-${BACKUP_DATE}/ \\\n --recursive\n\n# Cleanup temporary files\nrm -rf /tmp/documentdb-backup\n\necho \"Backup uploaded to: s3://mcp-gateway-backups/documentdb-backup-${BACKUP_DATE}/\"\n```\n\n##### Option 3: JSON Export of Specific Collections (from ECS Container)\n\n```bash\n# SSH into ECS container\ncd terraform/aws-ecs\n./scripts/ecs-ssh.sh registry\nsource .venv/bin/activate\n\n# Export specific collection to JSON\nmongoexport \\\n --host=$DOCUMENTDB_HOST \\\n --port=27017 \\\n --username=$DOCUMENTDB_USERNAME \\\n --password=$DOCUMENTDB_PASSWORD \\\n --ssl \\\n --sslCAFile=/app/global-bundle.pem \\\n --db=mcp_registry \\\n --collection=mcp_servers_default \\\n --out=/tmp/servers-export.json\n\n# Upload to S3\naws s3 cp /tmp/servers-export.json \\\n s3://mcp-gateway-backups/exports/servers-$(date +%Y%m%d).json\n\n# Cleanup\nrm /tmp/servers-export.json\n```\n\n##### Restore from S3 Backup\n\n```bash\n# SSH into ECS container\ncd terraform/aws-ecs\n./scripts/ecs-ssh.sh registry\nsource .venv/bin/activate\n\n# Download backup from S3\naws s3 cp s3://mcp-gateway-backups/documentdb-backup-20260103-120000/ \\\n /tmp/restore-backup/ \\\n --recursive\n\n# Restore using mongorestore\nmongorestore \\\n --host=$DOCUMENTDB_HOST \\\n --port=27017 \\\n --username=$DOCUMENTDB_USERNAME \\\n --password=$DOCUMENTDB_PASSWORD \\\n --ssl \\\n --sslCAFile=/app/global-bundle.pem \\\n --db=mcp_registry \\\n /tmp/restore-backup/mcp_registry\n\n# Cleanup\nrm -rf /tmp/restore-backup\n```\n\n**Important Notes:**\n\n- **mongodump/mongorestore**: Binary format (BSON), preserves all data types including binary data and dates\n- **mongoexport/mongoimport**: JSON format, human-readable but may lose type information\n- **For production**: Use AWS automated backups for disaster recovery, manual exports for data migration\n- **S3 bucket**: Replace `mcp-gateway-backups` with your actual S3 bucket name\n- **Embeddings**: Vector embeddings are large; consider excluding from exports if not needed:\n ```bash\n mongodump --excludeCollection=mcp_embeddings_1536_default ...\n ```\n\n---\n\n## Troubleshooting\n\n### Cannot Connect to MongoDB (Local)\n\n**Problem:** `docker exec -it mcp-mongodb mongosh` fails\n\n**Solutions:**\n\n```bash\n# Check if container is running\ndocker compose ps mongodb\n\n# Check container logs\ndocker compose logs mongodb\n\n# Restart MongoDB\ndocker compose restart mongodb\n\n# If needed, recreate container\ndocker compose up -d mongodb\n```\n\n### Cannot Connect to DocumentDB (Production)\n\n**Problem:** `manage-documentdb.py` commands fail with connection errors\n\n**Solutions:**\n\n```bash\n# 1. Verify you're in the ECS container with activated venv\nsource .venv/bin/activate\n\n# 2. Check environment variables are set\nenv | grep DOCUMENTDB\n\n# 3. Test connection with simple list command\npython scripts/manage-documentdb.py list\n\n# 4. Check security group allows access from ECS tasks (from local machine)\naws ec2 describe-security-groups --group-ids \n\n# 5. Verify DocumentDB endpoint (from local machine)\naws docdb describe-db-clusters --db-cluster-identifier mcp-registry-prod\n```\n\n### Replica Set Not Initialized (Local)\n\n**Problem:** `rs.status()` shows \"not initialized\"\n\n**Solutions:**\n\n```bash\n# Re-run initialization\ndocker compose up mongodb-init\n\n# Or manually initialize\ndocker exec -it mcp-mongodb mongosh --eval 'rs.initiate({_id: \"rs0\", members: [{_id: 0, host: \"mongodb:27017\"}]})'\n```\n\n### Collections Not Found\n\n**Problem:** `show collections` returns empty\n\n**Solutions:**\n\n```bash\n# Verify you're in correct database\n# In mongosh:\ndb.getName() // Should show \"mcp_registry\"\n\n# Re-run initialization\ndocker compose up mongodb-init\n\n# Check if data is in different namespace\ndb.getCollectionNames()\n```\n\n### Slow Queries\n\n**Problem:** Queries taking too long\n\n**Solutions (Local MongoDB CE):**\n\n```javascript\n// In mongosh - Check if indexes exist\ndb.mcp_servers_default.getIndexes()\n\n// Analyze query plan\ndb.mcp_servers_default.find({ path: \"...\" }).explain(\"executionStats\")\n\n// Check embeddings indexes\ndb.mcp_embeddings_1536_default.getIndexes()\n```\n\n**Solutions (Production DocumentDB):**\n\n```bash\n# Use inspect command to check indexes\npython scripts/manage-documentdb.py inspect --collection mcp_servers_default\n\n# Check embeddings collection indexes\npython scripts/manage-documentdb.py inspect --collection mcp_embeddings_1536_default\n```\n\n---\n\n## Quick Reference\n\n### Connection Strings\n\n**Local MongoDB CE:**\n```\nmongodb://localhost:27017/mcp_registry\n```\n\n**Production DocumentDB:**\n```\nmongodb://:@:27017/mcp_registry?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0\n```\n\n### Common mongosh Commands\n\n| Command | Description |\n|---------|-------------|\n| `show dbs` | List all databases |\n| `use mcp_registry` | Switch to mcp_registry database |\n| `show collections` | List all collections |\n| `db.stats()` | Database statistics |\n| `rs.status()` | Replica set status |\n| `db.mcp_servers_default.find()` | List all servers |\n| `db.mcp_servers_default.countDocuments()` | Count documents |\n| `.pretty()` | Format output nicely |\n| `exit` | Exit mongosh |\n\n### Environment Variables Reference\n\n**Local (.env):**\n```bash\nSTORAGE_BACKEND=mongodb-ce\nDOCUMENTDB_HOST=mongodb\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=default\nDOCUMENTDB_USE_TLS=false\n```\n\n**Production (ECS Task Definition):**\n```bash\nSTORAGE_BACKEND=documentdb\nDOCUMENTDB_HOST=\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=production\nDOCUMENTDB_USERNAME=\nDOCUMENTDB_PASSWORD=\nDOCUMENTDB_USE_TLS=true\nDOCUMENTDB_TLS_CA_FILE=/app/global-bundle.pem\nDOCUMENTDB_REPLICA_SET=rs0\n```\n\n---\n\n## See Also\n\n- [Storage Architecture: MongoDB CE & AWS DocumentDB](design/storage-architecture-mongodb-documentdb.md)\n- [Datastore Schema Design](database-design.md)\n- [Configuration Guide](configuration.md)\n- [MongoDB Documentation](https://www.mongodb.com/docs/manual/)\n- [AWS DocumentDB Documentation](https://docs.aws.amazon.com/documentdb/)\n" }, { "path": "docs/deployment-modes.md", "content": "# MCP Gateway Deployment Modes\n\nThis guide describes the three deployment modes available for MCP Gateway Registry on AWS ECS.\n\n## Deployment Mode Decision Matrix\n\n| Scenario | Recommended Mode | `enable_cloudfront` | `enable_route53_dns` |\n|----------|------------------|---------------------|----------------------|\n| Custom domain with Route53/ACM | Custom Domain | `false` | `true` |\n| HTTPS without custom domain | CloudFront | `true` | `false` |\n| Local development/testing | Development | `false` | `false` |\n| Both access paths needed | Dual Ingress | `true` | `true` |\n\n## Terraform Output: `deployment_mode`\n\nThe `deployment_mode` output indicates the active configuration:\n\n| Mode | `enable_cloudfront` | `enable_route53_dns` | Output Value |\n|------|---------------------|----------------------|--------------|\n| CloudFront | `true` | `false` | `cloudfront` |\n| Custom Domain | `false` | `true` | `custom-domain` |\n| Dual Ingress | `true` | `true` | `custom-domain` |\n| Development | `false` | `false` | `development` |\n\n> **Note:** Dual Ingress reports as `custom-domain` since Route53 DNS is the primary access path.\n\n## Architecture Overview\n\n```mermaid\nflowchart TB\n subgraph \"Custom Domain Mode\"\n U1[Users] -->|HTTPS| R53[Route53 DNS]\n R53 --> ACM1[ACM Certificate]\n ACM1 --> ALB1[ALB with HTTPS]\n ALB1 --> ECS1[ECS Services]\n end\n\n subgraph \"CloudFront Mode\"\n U2[Users] -->|HTTPS| CF[CloudFront]\n CF -->|HTTP + Custom Header| ALB2[ALB]\n ALB2 --> ECS2[ECS Services]\n end\n\n subgraph \"Development Mode\"\n U3[Users] -->|HTTP| ALB3[ALB DNS]\n ALB3 --> ECS3[ECS Services]\n end\n```\n\n## Mode 1: Custom Domain (Route53/ACM)\n\n**Use when:** You have a Route53 hosted zone and want custom domain URLs.\n\n**Configuration:**\n```hcl\nenable_cloudfront = false\nenable_route53_dns = true\nbase_domain = \"mycorp.click\"\n```\n\n**URLs:**\n- Registry: `https://registry.us-west-2.mycorp.click`\n- Keycloak: `https://kc.us-west-2.mycorp.click`\n\n**Features:**\n- ACM certificates for HTTPS\n- Custom domain names\n- Route53 DNS records\n\n## Mode 2: CloudFront (No Custom Domain)\n\n**Use when:** You need HTTPS but don't have a custom domain or Route53 hosted zone. Ideal for workshops, demos, evaluations, or any deployment where custom DNS isn't available.\n\n**Configuration:**\n```hcl\nenable_cloudfront = true\nenable_route53_dns = false\n```\n\n**URLs:**\n- Registry: `https://d1234abcd.cloudfront.net`\n- Keycloak: `https://d5678efgh.cloudfront.net`\n\n**Features:**\n- Default CloudFront certificates (`*.cloudfront.net`)\n- No custom domain required\n- HTTPS via CloudFront TLS termination\n- Custom `X-Cloudfront-Forwarded-Proto` header for correct HTTPS detection\n\n## Mode 3: Development (HTTP Only)\n\n**Use when:** Testing locally or in non-production environments.\n\n**Configuration:**\n```hcl\nenable_cloudfront = false\nenable_route53_dns = false\n```\n\n**URLs:**\n- Registry: `http://`\n- Keycloak: `http://`\n\n**Features:**\n- HTTP only (no HTTPS)\n- Direct ALB access\n- Simplest configuration\n\n## Mode 4: Dual Ingress (Both)\n\n**Use when:** You need both CloudFront and custom domain access paths.\n\n**Configuration:**\n```hcl\nenable_cloudfront = true\nenable_route53_dns = true\nbase_domain = \"mycorp.click\"\n```\n\n**URLs:**\n- Registry (CloudFront): `https://d1234abcd.cloudfront.net`\n- Registry (Custom): `https://registry.us-west-2.mycorp.click`\n- Keycloak (CloudFront): `https://d5678efgh.cloudfront.net`\n- Keycloak (Custom): `https://kc.us-west-2.mycorp.click`\n\n> **Note:** This is NOT a security risk, but may cause user confusion. A warning is displayed during `terraform apply`.\n\n## Environment Variables\n\n| Variable | Description | Required For |\n|----------|-------------|--------------|\n| `enable_cloudfront` | Enable CloudFront distributions | CloudFront mode |\n| `enable_route53_dns` | Enable Route53 DNS and ACM certificates | Custom Domain mode |\n| `base_domain` | Base domain for regional URLs | Custom Domain mode |\n| `keycloak_domain` | Full Keycloak domain (non-regional) | Custom Domain mode |\n| `root_domain` | Root domain (non-regional) | Custom Domain mode |\n\n## HTTPS Detection\n\nThe application detects HTTPS using the following header priority:\n\n1. `X-Forwarded-Proto: https` (CloudFront and ALB deployments)\n2. Request URL scheme (direct access)\n\nCloudFront is configured to send `X-Forwarded-Proto: https` as a custom origin header. This is the same header that ALB uses, so the application code works consistently across deployment modes.\n\n> **Note:** We use `X-Forwarded-Proto` (not a custom header like `X-Cloudfront-Forwarded-Proto`) because Keycloak natively recognizes this header for HTTPS detection.\n\n## Troubleshooting\n\n### Session cookies not working with CloudFront\n\n**Symptom:** Login succeeds but user is immediately logged out.\n\n**Cause:** The `Secure` flag on cookies requires HTTPS detection to work correctly.\n\n**Solution:** Verify the `X-Forwarded-Proto` header is being set by CloudFront. Check CloudFront distribution origin settings.\n\n### OAuth2 redirect fails with \"Invalid parameter: redirect_uri\"\n\n**Symptom:** After clicking login, Keycloak shows \"Invalid parameter: redirect_uri\" error.\n\n**Cause:** The CloudFront URL is not in Keycloak's allowed redirect URIs for the `mcp-gateway-web` client.\n\n**Solution:** \n1. Re-run `init-keycloak.sh` after generating fresh terraform outputs:\n ```bash\n cd terraform/aws-ecs\n terraform output -json > scripts/terraform-outputs.json\n export INITIAL_ADMIN_PASSWORD=\"your-password\"\n ./scripts/init-keycloak.sh\n ```\n2. Or manually add the CloudFront URL to Keycloak:\n - Go to Keycloak Admin → mcp-gateway realm → Clients → mcp-gateway-web\n - Add `https:///*` and `https:///oauth2/callback/keycloak` to Valid Redirect URIs\n - Add `https://` to Web Origins\n\n### OAuth2 redirect_uri is malformed (missing hostname)\n\n**Symptom:** The redirect_uri in the OAuth2 request looks like `https:/oauth2/callback/keycloak` (missing hostname).\n\n**Cause:** The MCP Gateway ECS task doesn't have the correct `REGISTRY_URL` environment variable set.\n\n**Solution:** Ensure `domain_name` is passed to the MCP Gateway module in `main.tf`:\n```hcl\ndomain_name = var.enable_route53_dns ? \"registry.${local.root_domain}\" : (\n var.enable_cloudfront ? aws_cloudfront_distribution.mcp_gateway[0].domain_name : \"\"\n)\n```\nThen run `terraform apply` to update the ECS task definition.\n\n### Keycloak shows \"HTTPS required\" error\n\n**Symptom:** Keycloak returns an error about HTTPS being required.\n\n**Cause:** Keycloak doesn't recognize it's behind HTTPS when accessed via CloudFront.\n\n**Solution:** Ensure CloudFront is sending `X-Forwarded-Proto: https` header (not a custom header name). In `cloudfront.tf`:\n```hcl\ncustom_header {\n name = \"X-Forwarded-Proto\"\n value = \"https\"\n}\n```\nAlso ensure Keycloak is configured with `KC_HOSTNAME_URL` (full URL with `https://`) instead of just `KC_HOSTNAME`.\n\n### API returns 403 Forbidden after login\n\n**Symptom:** Login succeeds but API calls return 403 \"Access forbidden\".\n\n**Cause:** Either the user doesn't have required group memberships, or the MCP scopes haven't been initialized on EFS.\n\n**Solution:**\n1. Check user groups in Keycloak Admin → mcp-gateway realm → Users → select user → Groups\n2. Ensure user is in `mcp-registry-admin` or `mcp-registry-user` group\n3. Run the scopes init task:\n ```bash\n ./scripts/run-scopes-init-task.sh --skip-build\n ```\n4. Restart the registry and auth services:\n ```bash\n aws ecs update-service --cluster mcp-gateway-ecs-cluster --service mcp-gateway-v2-registry --force-new-deployment --region us-west-2\n aws ecs update-service --cluster mcp-gateway-ecs-cluster --service mcp-gateway-v2-auth --force-new-deployment --region us-west-2\n ```\n\n### Nginx returns default page instead of registry\n\n**Symptom:** Accessing the registry URL shows the default nginx welcome page.\n\n**Cause:** The nginx default site configuration is intercepting requests before they reach the registry.\n\n**Solution:** The `docker/registry-entrypoint.sh` should remove the default site:\n```bash\nrm -f /etc/nginx/sites-enabled/default\n```\nRebuild and redeploy the registry container.\n\n### Certificate validation timeout\n\n**Symptom:** `terraform apply` hangs on ACM certificate validation.\n\n**Cause:** Route53 hosted zone doesn't exist or DNS propagation is slow.\n\n**Solution:** \n1. Verify the hosted zone exists: `aws route53 list-hosted-zones`\n2. Check the `base_domain` matches your hosted zone\n3. Wait for DNS propagation (up to 5 minutes)\n\n### CloudFront 502 errors\n\n**Symptom:** CloudFront returns 502 Bad Gateway.\n\n**Cause:** ALB is not responding or security group blocks CloudFront.\n\n**Solution:**\n1. Verify ALB health checks are passing\n2. Ensure ALB security group allows inbound from CloudFront (via prefix list or `0.0.0.0/0`)\n3. Check ECS service is running and healthy\n\n## Custom Domain with CloudFront\n\nWhile out of scope for automation, you can manually configure a custom domain in front of CloudFront:\n\n1. Create an ACM certificate in `us-east-1` (required for CloudFront)\n2. Add the custom domain as an alternate domain name (CNAME) in CloudFront\n3. Create a Route53 ALIAS record pointing to the CloudFront distribution\n4. Update Keycloak `KC_HOSTNAME` to use the custom domain\n\nRefer to [AWS CloudFront documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html) for detailed instructions.\n" }, { "path": "docs/design/a2a-protocol-integration.md", "content": "# A2A Protocol Integration: Comprehensive Developer Guide\n\nThis guide documents the Agent-to-Agent (A2A) protocol implementation in the MCP Gateway Registry. Rather than a specification, this is a practical guide to understanding how the system works today, how agents register themselves, how discovery works, and how access control is enforced across the entire stack.\n\n## Table of Contents\n\n1. [What We Built](#what-we-built)\n2. [The Big Picture: Request Flow](#the-big-picture-request-flow)\n3. [How Requests Get Authenticated](#how-requests-get-authenticated)\n4. [The Agent Card: Machine-Readable Profile](#the-agent-card-machine-readable-profile)\n5. [CRUD Operations: Agents Registering Themselves](#crud-operations-agents-registering-themselves)\n6. [Discovery: How Agents Find Other Agents](#discovery-how-agents-find-other-agents)\n7. [Access Control: Three-Tier Permission System](#access-control-three-tier-permission-system)\n8. [The Code: Where Everything Lives](#the-code-where-everything-lives)\n\n---\n\n## What We Built\n\nThe MCP Gateway Registry now supports Agent-to-Agent (A2A) communication through a **registry-only design**. This means:\n\n- Agents can register their capabilities and metadata with the registry\n- Agents can discover other agents they have permission to access\n- Agents communicate directly with each other using URLs returned by the registry\n- **The registry itself is NOT involved in agent-to-agent communication**\n\nThis is fundamentally different from how the MCP Gateway works. The gateway proxies MCP server requests, but for A2A agents, it simply acts as a discovery and validation service. Once agents find each other through the registry, they communicate peer-to-peer with no registry intermediation.\n\n### Why This Matters\n\nBuilding an autonomous agent ecosystem requires that agents be able to find each other without a central orchestrator. This architecture enables:\n\n- **Decentralized coordination**: Agents discover and contact each other directly\n- **Scalability**: No bottleneck at the registry for agent-to-agent communication\n- **Security**: Each agent maintains its own authentication and authorization\n- **Autonomy**: Agents can operate independently after discovery\n\n---\n\n## The Big Picture: Request Flow\n\nWhen an agent wants to register or discover other agents, here's the complete journey of a request:\n\n```\nAgent (AI Code)\n ↓\nM2M Token (from Keycloak Service Account)\n ↓\n[Port 80 - Nginx Reverse Proxy]\n ↓\n[Auth Validation]\nNginx calls auth-server:/validate\nReturns groups and scopes\n ↓\n[FastAPI Routes]\n/api/agents/register\n/api/agents\n/api/agents/{path}\n/api/agents/discover/semantic\netc.\n ↓\n[Authorization Enforcement]\nCheck if user has permission for requested action\nFilter results based on access control\n ↓\n[Business Logic]\nRegistry Services (agent_service.py)\nFile-based persistence (agent_state.json)\nFAISS semantic search\n ↓\n[Response]\nAgent cards, discovery results, or error\n```\n\n### The Key Difference from MCP\n\n```\nMCP Request Flow:\nAgent → Nginx → Auth → FastAPI → Gateway Proxy → MCP Server → Agent\n\nA2A Request Flow:\nAgent → Nginx → Auth → FastAPI → Registry Service\n ↓ Returns: Agent Card + Direct URL\nAgent ← [Agents now communicate directly, registry is done] → Other Agent\n```\n\n---\n\n## How Requests Get Authenticated\n\nEvery request to the A2A agent API must include a valid JWT token from Keycloak. Here's the authentication journey:\n\n### 1. Token Generation (M2M Service Account)\n\nThe `mcp-gateway-m2m` Keycloak service account generates tokens that are used for all A2A operations:\n\n```bash\n# Service Account Details\nClient ID: mcp-gateway-m2m\nService User: service-account-mcp-gateway-m2m\nToken File: .oauth-tokens/ingress.json (generated by credentials-provider/generate_creds.sh)\nTTL: 5 minutes (expiration is critical)\n```\n\nWhen a token is generated, it contains:\n\n```json\n{\n \"exp\": 1761942660,\n \"iat\": 1761942360,\n \"iss\": \"http://localhost:8080/realms/mcp-gateway\",\n \"sub\": \"user-id-uuid\",\n \"typ\": \"Bearer\",\n \"azp\": \"mcp-gateway-m2m\",\n \"client_id\": \"mcp-gateway-m2m\",\n \"preferred_username\": \"service-account-mcp-gateway-m2m\",\n \"groups\": [\n \"mcp-servers-unrestricted\",\n \"a2a-agent-admin\"\n ],\n \"scope\": \"profile email mcp-servers-unrestricted/read mcp-servers-unrestricted/execute a2a-agent-admin\"\n}\n```\n\nThe critical fields are:\n- `groups`: List of Keycloak groups the account belongs to (controls what agents it can access)\n- `exp`: Expiration timestamp (checked for token validity)\n\n### 2. Nginx Reverse Proxy Intercepts Request\n\nNginx runs on port 80 and intercepts all requests to `/api/` paths. It extracts the JWT and calls the auth-server to validate it:\n\n```\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n http://localhost/api/agents/register\n\nNginx intercepts → Calls auth-server:/validate\n```\n\nThe auth-server validates the JWT and maps the groups in the token to internal scope names.\n\n### 3. Auth-Server Validates and Maps Groups\n\nThe auth-server decodes the JWT, extracts the groups, and looks them up in `auth_server/scopes.yml`:\n\n```yaml\n# Example from scopes.yml\nmcp-registry-admin:\n- mcp-registry-admin\n- mcp-servers-unrestricted/read\n- mcp-servers-unrestricted/execute\n\na2a-agent-admin:\n- a2a-agent-admin # Implicit (service accounts have special mapping)\n```\n\nThe auth-server returns:\n```json\n{\n \"groups\": [\"mcp-servers-unrestricted\", \"a2a-agent-admin\"],\n \"scopes\": [\"mcp-servers-unrestricted/read\", \"mcp-servers-unrestricted/execute\", \"a2a-agent-admin\"],\n \"username\": \"service-account-mcp-gateway-m2m\"\n}\n```\n\n### 4. Nginx Forwards to FastAPI with Scopes\n\nNginx adds a header with the scopes and forwards the request:\n\n```\nX-Scopes: a2a-agent-admin, mcp-servers-unrestricted/read, mcp-servers-unrestricted/execute\nAuthorization: Bearer $TOKEN\n```\n\n### 5. FastAPI Endpoint Checks Permissions\n\nThe FastAPI endpoint reads the scopes and enforces permissions:\n\n```python\n@router.post(\"/agents/register\")\nasync def register_agent(\n request: Request,\n agent_card: AgentCard,\n user_context: dict = Depends(enhanced_auth)\n):\n # Check if user has a2a-agent-admin scope\n if \"a2a-agent-admin\" not in user_context.get(\"scopes\", []):\n raise HTTPException(status_code=403, detail=\"Not authorized\")\n\n # Proceed with registration\n```\n\n### 6. Agent State Persisted\n\nThe registered agent is saved to `registry/agents/agent_state.json` in the format:\n\n```json\n{\n \"agents\": {\n \"/code-reviewer\": {\n \"name\": \"Code Reviewer Agent\",\n \"path\": \"/code-reviewer\",\n \"url\": \"https://agent.example.com/code-reviewer\",\n \"protocol_version\": \"1.0\",\n \"is_enabled\": true,\n \"registered_at\": \"2025-11-09T10:30:00Z\",\n \"registered_by\": \"service-account-mcp-gateway-m2m\",\n \"visibility\": \"public\"\n }\n }\n}\n```\n\n### Token Validation in CLI\n\nThe CLI (`cli/agent_mgmt.py`) validates tokens before making requests. It checks:\n\n1. **Token exists**: `.oauth-tokens/ingress.json` file is present\n2. **Token is not expired**: Decodes JWT payload, checks `exp` claim against current timestamp\n3. **Token has correct groups**: Verifies `groups` claim includes required groups\n\nThis ensures requests fail fast with clear messages if credentials are stale (tokens expire in 5 minutes).\n\n---\n\n## The Agent Card: Machine-Readable Profile\n\nAn agent card is a JSON document that describes what an agent does, how to reach it, and what capabilities it offers. The registry stores these cards and returns them during discovery.\n\n### Complete Agent Card Structure\n\n```json\n{\n \"protocol_version\": \"1.0\",\n \"name\": \"Code Reviewer Agent\",\n \"description\": \"Analyzes Python and JavaScript code for bugs, style issues, and security vulnerabilities\",\n \"url\": \"https://agents.example.com/code-reviewer\",\n \"version\": \"2.1.0\",\n \"provider\": \"Acme Corp\",\n\n \"skills\": [\n {\n \"id\": \"review-python-code\",\n \"name\": \"Review Python Code\",\n \"description\": \"Performs static analysis on Python source code\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"code\": {\n \"type\": \"string\",\n \"description\": \"Python source code to review\"\n },\n \"strict_mode\": {\n \"type\": \"boolean\",\n \"default\": false,\n \"description\": \"Enable strict analysis rules\"\n }\n },\n \"required\": [\"code\"]\n },\n \"tags\": [\"python\", \"code-review\", \"security\"]\n },\n {\n \"id\": \"review-javascript-code\",\n \"name\": \"Review JavaScript Code\",\n \"description\": \"Performs static analysis on JavaScript source code\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"code\": { \"type\": \"string\" },\n \"strict_mode\": { \"type\": \"boolean\", \"default\": false }\n },\n \"required\": [\"code\"]\n },\n \"tags\": [\"javascript\", \"code-review\", \"security\"]\n }\n ],\n\n \"security_schemes\": {\n \"bearer\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\",\n \"bearer_format\": \"JWT\"\n }\n },\n \"security\": [{\"bearer\": []}],\n\n \"streaming\": false,\n \"path\": \"/code-reviewer\",\n \"tags\": [\n \"code-review\",\n \"security\",\n \"static-analysis\"\n ],\n \"is_enabled\": true,\n \"num_stars\": 0,\n \"license\": \"MIT\",\n \"visibility\": \"public\",\n \"allowed_groups\": [],\n \"trust_level\": \"community\",\n \"registered_at\": \"2025-11-09T10:30:00Z\",\n \"registered_by\": \"service-account-mcp-gateway-m2m\",\n \"updated_at\": \"2025-11-09T10:35:00Z\"\n}\n```\n\n### Field Descriptions\n\n**Core A2A Fields** (required):\n- `protocol_version`: A2A protocol version (currently \"1.0\")\n- `name`: Human-readable agent name\n- `description`: What the agent does\n- `url`: Direct URL to reach the agent (used by other agents after discovery)\n\n**Capabilities**:\n- `skills`: List of capabilities the agent offers. Each skill has:\n - `id`: Unique identifier within the agent\n - `name`: Human-readable name\n - `description`: What the skill does\n - `parameters`: JSON Schema defining input parameters\n - `tags`: Categorization for discovery\n\n**Security**:\n- `security_schemes`: How to authenticate with the agent (bearer, OAuth2, etc.)\n- `security`: Which schemes are required\n- `trust_level`: Verification status (unverified, community, verified, trusted)\n\n**Registry Metadata**:\n- `path`: Registry path (like `/code-reviewer`)\n- `visibility`: Who can see it (public, private, group-restricted)\n- `is_enabled`: Whether it's active in the registry\n- `registered_at`: When it was registered\n- `registered_by`: Which service account registered it\n\n### Why the Agent Card Matters\n\nThe agent card is the contract between agents. When Agent B discovers Agent A, it gets the agent card which tells it:\n- How to reach Agent A (`url`)\n- What Agent A can do (`skills`)\n- How to authenticate with Agent A (`security_schemes`)\n- Whether it should trust Agent A (`trust_level`)\n\n---\n\n## CRUD Operations: Agents Registering Themselves\n\nAll CRUD (Create, Read, Update, Delete) operations happen through REST API endpoints. Every operation requires authentication and goes through the permission check.\n\n### Creating: POST /api/agents/register\n\nAn agent registers itself by POSTing a card to the registry:\n\n```bash\ncurl -X POST http://localhost/api/agents/register \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d @agent-card.json\n```\n\n**What Happens**:\n\n1. **Nginx** receives request, validates JWT, calls auth-server\n2. **Auth-server** maps groups to scopes, returns `a2a-agent-admin` scope\n3. **Nginx** forwards request with `X-Scopes: a2a-agent-admin` header\n4. **FastAPI endpoint** checks if scopes include `a2a-agent-admin`\n5. **agent_routes.py** validates the agent card using `agent_validator.py`:\n - Schema validation (Pydantic)\n - Unique path check\n - Skills have unique IDs\n - Security schemes are properly configured\n6. **agent_service.py** saves to `agent_state.json`\n7. **FAISS service** indexes the agent for semantic search\n8. **Response**: 201 Created with registered agent info\n\n**Success Response**:\n```json\n{\n \"message\": \"Agent registered successfully\",\n \"agent\": {\n \"name\": \"Code Reviewer Agent\",\n \"path\": \"/code-reviewer\",\n \"url\": \"https://agents.example.com/code-reviewer\",\n \"num_skills\": 2,\n \"registered_at\": \"2025-11-09T10:30:00Z\",\n \"is_enabled\": false\n }\n}\n```\n\n**Error Responses**:\n- 400 Bad Request: Invalid agent card format\n- 409 Conflict: Agent path already exists\n- 403 Forbidden: User lacks `a2a-agent-admin` scope\n- 422 Unprocessable Entity: Validation failed\n\n### Reading: GET /api/agents/{path} and GET /api/agents\n\n**Get Single Agent**:\n```bash\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n http://localhost/api/agents/code-reviewer\n```\n\nReturns the complete agent card (if user has permission).\n\n**List All Agents**:\n```bash\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n http://localhost/api/agents\n```\n\n**What Happens**:\n1. Auth checks what groups the user belongs to\n2. Loads all agents from `agent_state.json`\n3. **Filters by access control**: Only returns agents the user is authorized to see\n4. Returns list with summaries\n\nExample: If user is in `registry-users-lob1` group, they only see agents in their scope (`/code-reviewer`, `/test-automation`).\n\n### Updating: PUT /api/agents/{path}\n\nAn agent can update its own card:\n\n```bash\ncurl -X PUT http://localhost/api/agents/code-reviewer \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d @updated-card.json\n```\n\n**What Happens**:\n1. **Check permissions**: User must have `modify_agent` scope for this path\n2. **Validate new card**: Same validation as registration\n3. **Update in storage**: Modify `agent_state.json`\n4. **Re-index in FAISS**: Update semantic search index\n5. **Update timestamp**: Set `updated_at` to current time\n6. **Return**: Updated agent card\n\n### Deleting: DELETE /api/agents/{path}\n\nRemove an agent from the registry:\n\n```bash\ncurl -X DELETE http://localhost/api/agents/code-reviewer \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n**What Happens**:\n1. **Check permissions**: User must have `delete_agent` scope\n2. **Remove from storage**: Delete from `agent_state.json`\n3. **Remove from FAISS**: Delete from semantic search index\n4. **Return**: 204 No Content or success message\n\n### Toggling: POST /api/agents/{path}/toggle\n\nEnable or disable an agent without deleting it:\n\n```bash\ncurl -X POST http://localhost/api/agents/code-reviewer/toggle?enabled=true \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n**What Happens**:\n1. **Check permissions**: User must have modify permissions\n2. **Toggle state**: Set `is_enabled` to true or false\n3. **Update FAISS**: Enabled status affects search results\n4. **Return**: Updated agent info\n\n---\n\n## Discovery: How Agents Find Other Agents\n\nOnce agents are registered, other agents can discover them through two mechanisms: semantic search and direct queries.\n\n### Semantic Search: POST /api/agents/discover/semantic\n\nAn agent asks a natural language question to find other agents:\n\n```bash\ncurl -X POST http://localhost/api/agents/discover/semantic \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"I need an agent that can review Python code for security vulnerabilities\",\n \"max_results\": 5,\n \"entity_types\": [\"a2a_agent\"]\n }'\n```\n\n**How It Works**:\n\n1. **Query Embedding**: The natural language query is converted to a vector using an embedding model\n2. **FAISS Search**: The vector is compared against all agent cards stored in the FAISS index\n3. **Ranking**: Results ranked by similarity score\n4. **Filtering**: Only agents visible to this user (based on groups and visibility)\n5. **Return**: Agents with `relevance_score`\n\n**Response**:\n```json\n{\n \"entities\": [\n {\n \"entity_type\": \"a2a_agent\",\n \"name\": \"Code Reviewer Agent\",\n \"path\": \"/code-reviewer\",\n \"description\": \"Analyzes Python and JavaScript code...\",\n \"url\": \"https://agents.example.com/code-reviewer\",\n \"relevance_score\": 0.92,\n \"skills\": [\"review-python-code\", \"review-javascript-code\"],\n \"trust_level\": \"community\"\n }\n ],\n \"query\": \"I need an agent that can review Python code...\"\n}\n```\n\n### How FAISS Indexing Works\n\nWhen an agent is registered, the registry creates an embedding for it:\n\n```python\n# From agent_service.py\ndef _get_agent_text_for_embedding(agent_card):\n \"\"\"Prepare agent card for semantic search\"\"\"\n name = agent_card[\"name\"]\n description = agent_card[\"description\"]\n\n # Extract skill information\n skills_text = \"\\n\".join([\n f\"{s['name']}: {s['description']}\"\n for s in agent_card.get(\"skills\", [])\n ])\n\n # Combine all searchable text\n text = f\"\"\"\n Name: {name}\n Description: {description}\n Skills: {skills_text}\n Tags: {', '.join(agent_card.get('tags', []))}\n \"\"\"\n\n return text.strip()\n\n# This text is embedded and stored in FAISS\n# When someone searches, their query is embedded and compared\n```\n\nThe FAISS index maintains metadata about each entity:\n\n```json\n{\n \"id\": 42,\n \"entity_type\": \"a2a_agent\",\n \"path\": \"/code-reviewer\",\n \"text_for_embedding\": \"Name: Code Reviewer...\",\n \"full_entity_info\": { /* complete agent card */ },\n \"is_enabled\": true\n}\n```\n\n### Direct API Queries\n\nFor more precise queries, agents can also search using filters:\n\n```bash\ncurl -X POST http://localhost/api/agents/discover \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"skills\": [\"review-python-code\"],\n \"tags\": [\"security\", \"python\"],\n \"max_results\": 10\n }'\n```\n\n---\n\n## Access Control: Three-Tier Permission System\n\nAccess control is enforced at three levels: UI scopes, group mappings, and individual agent permissions. All three work together to determine what an authenticated user can do.\n\n### Tier 1: UI-Scopes (High-Level Actions)\n\nThe `UI-Scopes` section in `auth_server/scopes.yml` defines what high-level actions each group can perform:\n\n```yaml\nUI-Scopes:\n mcp-registry-admin:\n list_agents: [all]\n get_agent: [all]\n publish_agent: [all]\n modify_agent: [all]\n delete_agent: [all]\n\n registry-users-lob1:\n list_agents:\n - /code-reviewer\n - /test-automation\n get_agent:\n - /code-reviewer\n - /test-automation\n publish_agent:\n - /code-reviewer\n - /test-automation\n modify_agent:\n - /code-reviewer\n - /test-automation\n delete_agent:\n - /code-reviewer\n - /test-automation\n```\n\nThis says:\n- `mcp-registry-admin` can list ALL agents\n- `registry-users-lob1` can ONLY list `/code-reviewer` and `/test-automation`\n\n### Tier 2: Group Mappings (Keycloak to Internal Scopes)\n\nThe `group_mappings` section maps Keycloak groups to internal scope names:\n\n```yaml\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n\n registry-users-lob1:\n - registry-users-lob1\n```\n\nWhen a user authenticates with Keycloak, their JWT includes groups. The auth-server uses this mapping to determine which internal scopes apply.\n\n### Tier 3: Individual Group Scopes (Detailed Permissions)\n\nThe bottom of `scopes.yml` defines detailed permissions for each group:\n\n```yaml\nregistry-users-lob1:\n- server: currenttime\n methods:\n - initialize\n - tools/list\n - tools/call\n- agents:\n actions:\n - action: list_agents\n resources:\n - /code-reviewer\n - /test-automation\n - action: get_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: publish_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: modify_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: delete_agent\n resources:\n - /code-reviewer\n - /test-automation\n```\n\nThis defines:\n- Which MCP servers the group can access (currenttime, mcpgw)\n- Which agent actions are allowed (list, get, publish, modify, delete)\n- Which agent paths apply (only /code-reviewer and /test-automation)\n\n### How Permission Checking Works in Code\n\nWhen a request comes in to list agents:\n\n```python\n@router.get(\"/agents\")\nasync def list_agents(\n request: Request,\n user_context: dict = Depends(enhanced_auth)\n):\n # user_context contains:\n # {\n # \"username\": \"service-account-mcp-gateway-m2m\",\n # \"groups\": [\"mcp-registry-admin\"],\n # \"scopes\": [\"mcp-registry-admin\", \"mcp-servers-unrestricted/read\", ...]\n # }\n\n # Load all agents\n agents = agent_service.load_agents()\n\n # Filter based on scopes\n accessible_agents = _filter_agents_by_access(\n agents,\n user_context\n )\n\n return {\"agents\": accessible_agents}\n\ndef _filter_agents_by_access(agents, user_context):\n \"\"\"Filter agents based on user's access permissions\"\"\"\n\n groups = user_context.get(\"groups\", [])\n scopes = user_context.get(\"scopes\", [])\n\n # Admin can see all\n if \"mcp-registry-admin\" in groups:\n return agents\n\n # LOB1 can only see LOB1 agents\n if \"registry-users-lob1\" in groups:\n return [a for a in agents if a[\"path\"] in [\n \"/code-reviewer\",\n \"/test-automation\"\n ]]\n\n # LOB2 can only see LOB2 agents\n if \"registry-users-lob2\" in groups:\n return [a for a in agents if a[\"path\"] in [\n \"/data-analysis\",\n \"/security-analyzer\"\n ]]\n\n # Unknown group sees nothing\n return []\n```\n\n### Agent Visibility Levels\n\nBeyond group-based access, agents also have visibility settings:\n\n- **public**: Visible to all authenticated users\n- **private**: Only visible to owner and admins\n- **group-restricted**: Only visible to specific groups\n\nThe filtering considers both the user's groups and the agent's visibility setting.\n\n---\n\n## The Code: Where Everything Lives\n\nThis section maps the implementation to actual files and shows how the pieces fit together.\n\n### API Routes (registry/api/agent_routes.py - 838 lines)\n\nThis file defines 8 REST API endpoints:\n\n```python\n@router.post(\"/agents/register\")\nasync def register_agent(request: Request, agent_card: AgentCard):\n \"\"\"Register a new agent (requires a2a-agent-admin scope)\"\"\"\n # 1. Check user has a2a-agent-admin scope\n # 2. Validate agent card using agent_validator\n # 3. Check path is unique\n # 4. Save to agent_state.json\n # 5. Index in FAISS\n # 6. Return 201 Created\n\n@router.get(\"/agents\")\nasync def list_agents(request: Request):\n \"\"\"List agents (filtered by user permissions)\"\"\"\n # 1. Load all agents\n # 2. Filter by user's groups and visibility\n # 3. Return summary list\n\n@router.get(\"/agents/{path}\")\nasync def get_agent(request: Request, path: str):\n \"\"\"Get complete agent card by path\"\"\"\n # 1. Check user has permission for this agent\n # 2. Load from agent_state.json\n # 3. Return full agent card\n\n@router.put(\"/agents/{path}\")\nasync def update_agent(request: Request, path: str, agent_card: AgentCard):\n \"\"\"Update agent card (requires modify_agent scope for this path)\"\"\"\n # 1. Check user has modify_agent scope\n # 2. Validate new card\n # 3. Update agent_state.json\n # 4. Re-index in FAISS\n # 5. Return updated card\n\n@router.delete(\"/agents/{path}\")\nasync def delete_agent(request: Request, path: str):\n \"\"\"Delete agent (requires delete_agent scope for this path)\"\"\"\n # 1. Check user has delete_agent scope\n # 2. Remove from agent_state.json\n # 3. Remove from FAISS index\n # 4. Return 204 No Content\n\n@router.post(\"/agents/{path}/toggle\")\nasync def toggle_agent(request: Request, path: str, enabled: bool):\n \"\"\"Enable or disable agent\"\"\"\n # 1. Check user has modify_agent scope\n # 2. Update is_enabled flag\n # 3. Return updated agent info\n\n@router.post(\"/agents/discover/semantic\")\nasync def discover_agents_semantic(request: Request, query: DiscoveryQuery):\n \"\"\"Semantic search for agents\"\"\"\n # 1. Embed the natural language query\n # 2. Search FAISS index\n # 3. Filter results by user permissions\n # 4. Return ranked results\n```\n\n### Business Logic (registry/services/agent_service.py - 695 lines)\n\nThis file handles all agent operations:\n\n```python\nclass AgentService:\n \"\"\"CRUD operations for agents\"\"\"\n\n def load_agents_and_state(self) -> dict:\n \"\"\"Load all agents from agent_state.json\"\"\"\n # Returns: {\"agents\": {\"/code-reviewer\": {...}, ...}}\n\n def register_agent(self, agent_card: AgentCard) -> AgentCard:\n \"\"\"Register a new agent\"\"\"\n # 1. Validate path is unique\n # 2. Generate registered_at timestamp\n # 3. Add to agent_state.json\n # 4. Return registered card\n\n def get_agent(self, path: str) -> AgentCard:\n \"\"\"Get agent by path\"\"\"\n # Returns agent card or raises HTTPException(404)\n\n def update_agent(self, path: str, card: AgentCard) -> AgentCard:\n \"\"\"Update existing agent\"\"\"\n # 1. Load current agent\n # 2. Merge updates\n # 3. Update agent_state.json\n # 4. Return updated card\n\n def delete_agent(self, path: str) -> None:\n \"\"\"Delete agent by path\"\"\"\n # Remove from agent_state.json\n\n def toggle_agent(self, path: str, enabled: bool) -> AgentCard:\n \"\"\"Enable or disable agent\"\"\"\n # Update is_enabled flag in agent_state.json\n\n def list_agents(self) -> List[AgentInfo]:\n \"\"\"Get all agents as summaries\"\"\"\n # Returns list of simplified agent info\n```\n\n### Data Models (registry/schemas/agent_models.py - 603 lines)\n\nPydantic models for validation:\n\n```python\nclass SecurityScheme(BaseModel):\n \"\"\"How to authenticate with an agent\"\"\"\n type: str # \"apiKey\", \"http\", \"oauth2\", \"openIdConnect\"\n scheme: Optional[str] = None\n in_: Optional[str] = None\n name: Optional[str] = None\n\nclass Skill(BaseModel):\n \"\"\"A capability an agent offers\"\"\"\n id: str\n name: str\n description: str\n parameters: Optional[Dict[str, Any]] = None\n tags: List[str] = []\n\nclass AgentCard(BaseModel):\n \"\"\"Complete agent profile\"\"\"\n protocol_version: str\n name: str\n description: str\n url: str # Direct URL for peer-to-peer communication\n\n skills: List[Skill] = []\n security_schemes: Dict[str, SecurityScheme] = {}\n security: Optional[List[Dict[str, List[str]]]] = None\n\n path: str # Registry path: /agents/code-reviewer\n visibility: str = \"public\"\n is_enabled: bool = False\n trust_level: str = \"unverified\"\n\n registered_at: Optional[datetime] = None\n registered_by: Optional[str] = None\n updated_at: Optional[datetime] = None\n```\n\n### Validation (registry/utils/agent_validator.py - 343 lines)\n\nEnsures agent cards are valid:\n\n```python\nclass AgentValidator:\n \"\"\"Validate agent cards\"\"\"\n\n async def validate_agent_card(\n self,\n card: AgentCard,\n verify_endpoint: bool = True\n ) -> ValidationResult:\n \"\"\"\n Validate agent card:\n - Schema validation (Pydantic)\n - Unique skill IDs\n - Valid security schemes\n - Endpoint reachability (optional)\n \"\"\"\n```\n\n### Storage (registry/agents/agent_state.json)\n\nCentral file tracking all registered agents:\n\n```json\n{\n \"agents\": {\n \"/code-reviewer\": {\n \"name\": \"Code Reviewer Agent\",\n \"path\": \"/code-reviewer\",\n \"url\": \"https://agents.example.com/code-reviewer\",\n \"protocol_version\": \"1.0\",\n \"is_enabled\": true,\n \"registered_at\": \"2025-11-09T10:30:00Z\",\n \"registered_by\": \"service-account-mcp-gateway-m2m\"\n },\n \"/test-automation\": {\n \"name\": \"Test Automation Agent\",\n \"path\": \"/test-automation\",\n \"url\": \"https://agents.example.com/test-automation\",\n \"protocol_version\": \"1.0\",\n \"is_enabled\": true,\n \"registered_at\": \"2025-11-09T10:31:00Z\",\n \"registered_by\": \"service-account-mcp-gateway-m2m\"\n }\n }\n}\n```\n\n### FAISS Search Integration (registry/search/service.py)\n\nThe FAISS service indexes both MCP servers and agents:\n\n```python\nclass FaissService:\n \"\"\"Semantic search for MCP servers and A2A agents\"\"\"\n\n async def add_or_update_entity(\n self,\n entity_path: str,\n entity_info: Dict[str, Any],\n entity_type: str # \"mcp_server\" or \"a2a_agent\"\n ):\n \"\"\"Add or update entity in FAISS index\"\"\"\n\n # Generate text for embedding\n if entity_type == \"a2a_agent\":\n text = self._get_agent_text_for_embedding(entity_info)\n else:\n text = self._get_server_text_for_embedding(entity_info)\n\n # Create embedding and add to index\n embedding = self.embedding_model.embed(text)\n self.faiss_index.add(embedding)\n\n # Store metadata\n metadata = {\n \"entity_type\": entity_type,\n \"path\": entity_path,\n \"text_for_embedding\": text,\n \"full_entity_info\": entity_info\n }\n```\n\n### Authentication (Keycloak + Auth Server)\n\nThe M2M service account `mcp-gateway-m2m` has:\n\n```yaml\n# Auto-assigned Keycloak groups (from keycloak/setup/init-keycloak.sh):\n- mcp-servers-unrestricted # Full MCP server access\n- a2a-agent-admin # Full agent management\n\n# Mapped scopes (from auth_server/scopes.yml):\n- mcp-servers-unrestricted/read\n- mcp-servers-unrestricted/execute\n- a2a-agent-admin\n```\n\nThe token is generated every 5 minutes and stored in `.oauth-tokens/ingress.json`.\n\n---\n\n## Putting It All Together: Complete Request Example\n\nHere's what happens when an agent registers itself:\n\n**1. Agent Prepares Card**\n```json\n{\n \"name\": \"Code Reviewer Agent\",\n \"description\": \"Reviews Python code\",\n \"url\": \"https://agents.example.com/code-reviewer\",\n \"path\": \"/code-reviewer\",\n \"protocol_version\": \"1.0\",\n \"skills\": [\n {\n \"id\": \"review-python\",\n \"name\": \"Review Python Code\",\n \"description\": \"Analyzes Python source code\",\n \"parameters\": {\"type\": \"object\", \"properties\": {\"code\": {\"type\": \"string\"}}},\n \"tags\": [\"python\", \"review\"]\n }\n ],\n \"security_schemes\": {\n \"bearer\": {\"type\": \"http\", \"scheme\": \"bearer\", \"bearer_format\": \"JWT\"}\n },\n \"security\": [{\"bearer\": []}],\n \"tags\": \"code-review,security\"\n}\n```\n\n**2. Agent Gets JWT Token**\n```bash\n$ ./credentials-provider/generate_creds.sh\n# Generates .oauth-tokens/ingress.json with 5-minute TTL\n```\n\n**3. Agent POSTs to Registry**\n```bash\ncurl -X POST http://localhost/api/agents/register \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d @agent-card.json\n```\n\n**4. Nginx Intercepts**\n- Extracts JWT from Authorization header\n- Calls auth-server:/validate with the token\n- Auth-server decodes JWT and returns scopes\n\n**5. Auth-Server Returns**\n```json\n{\n \"username\": \"service-account-mcp-gateway-m2m\",\n \"groups\": [\"mcp-servers-unrestricted\", \"a2a-agent-admin\"],\n \"scopes\": [\"mcp-servers-unrestricted/read\", \"mcp-servers-unrestricted/execute\", \"a2a-agent-admin\"]\n}\n```\n\n**6. Nginx Forwards to FastAPI**\n```\nPOST /api/agents/register HTTP/1.1\nAuthorization: Bearer $TOKEN\nX-Scopes: mcp-servers-unrestricted/read,mcp-servers-unrestricted/execute,a2a-agent-admin\n```\n\n**7. FastAPI Endpoint Executes**\n- Checks `a2a-agent-admin` in scopes ✓\n- Validates agent card with Pydantic ✓\n- Checks path `/code-reviewer` doesn't exist ✓\n- Calls agent_service.register_agent()\n\n**8. Agent Service Saves**\n- Loads current agent_state.json\n- Adds `/code-reviewer` entry\n- Saves back to disk\n- Returns registered agent\n\n**9. FAISS Indexing**\n- Generates embedding text from agent card\n- Converts to vector using embedding model\n- Adds to FAISS index with metadata\n\n**10. Response to Agent**\n```json\n{\n \"message\": \"Agent registered successfully\",\n \"agent\": {\n \"name\": \"Code Reviewer Agent\",\n \"path\": \"/code-reviewer\",\n \"url\": \"https://agents.example.com/code-reviewer\",\n \"num_skills\": 1,\n \"registered_at\": \"2025-11-09T10:30:00Z\",\n \"is_enabled\": false\n }\n}\n```\n\n**11. Agent Enables Itself (Optional)**\n```bash\ncurl -X POST http://localhost/api/agents/code-reviewer/toggle?enabled=true \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nNow the agent is discoverable by other agents and will appear in semantic searches.\n\n---\n\n## Summary: The Key Concepts\n\n**Registry-Only Design**: The registry handles discovery and validation, not communication. Once agents find each other, they talk directly.\n\n**Authentication Layer**: All requests require a valid JWT token from a Keycloak service account. Tokens are validated at three points: Nginx, Auth-Server, and FastAPI.\n\n**Three-Tier Access Control**:\n1. UI-Scopes define high-level actions\n2. Group Mappings connect Keycloak groups to scopes\n3. Individual Group Scopes define detailed permissions\n\n**Agent Card**: The machine-readable profile that agents register. Contains name, description, URL, skills, security requirements, and metadata.\n\n**CRUD Operations**: Agents can register, read, update, delete, and toggle themselves through REST APIs.\n\n**Discovery**: Agents discover other agents using semantic search (natural language) or direct queries (by skill/tag).\n\n**File-Based Persistence**: Agent state is stored in `agent_state.json` with simple JSON format.\n\n**FAISS Indexing**: Agents are automatically indexed for semantic search alongside MCP servers.\n\nThis design enables autonomous agent ecosystems where agents discover and coordinate with each other while maintaining security and access control features.\n" }, { "path": "docs/design/agent-skills-architecture.md", "content": "# Agent Skills Architecture Design\n\nThis document describes the architecture and data model for the Agent Skills feature in MCP Gateway Registry.\n\n## Overview\n\nAgent Skills are reusable, shareable instruction sets that augment AI coding assistants with specialized capabilities. Unlike MCP servers (which provide tools), skills provide context, workflows, and behavioral guidance that help AI assistants perform specific tasks more effectively.\n\nThe Agent Skills feature follows the [agentskills.io](https://agentskills.io) specification, providing a standardized way to discover, share, and manage skills across AI coding environments.\n\n## Design Principles\n\n### Separation of Concerns\n\nSkills and Servers serve different purposes:\n\n| Aspect | MCP Servers | Agent Skills |\n|--------|------------|--------------|\n| Primary Function | Provide executable tools | Provide behavioral guidance |\n| Content Type | Code, APIs, integrations | Markdown instructions, workflows |\n| Execution | Server-side execution | Client-side interpretation |\n| State | Stateful (running processes) | Stateless (document-based) |\n\n### URL-Based Discovery\n\nSkills are referenced by a single URL pointing to a `SKILL.md` file:\n\n```\nhttps://github.com/org/repo/blob/main/skills/pdf-processing/SKILL.md\n```\n\nThe registry:\n1. Accepts the user-provided URL (blob URL for GitHub)\n2. Auto-translates to raw content URL for fetching\n3. Stores both URLs for different use cases\n\n### Progressive Disclosure\n\nSkills support multiple detail tiers to avoid overwhelming AI assistants:\n\n1. **Card View**: Name, description, tags (for discovery)\n2. **Summary View**: Plus requirements, tools, target agents\n3. **Full View**: Complete SKILL.md content with all details\n\n## Data Model\n\n### SkillCard Entity\n\nThe primary entity representing a registered skill:\n\n```\nSkillCard\n├── Identification\n│ ├── path: /skills/{name} # Unique, immutable path\n│ ├── name: string # Lowercase alphanumeric with hyphens\n│ └── description: string # What the skill does\n│\n├── URLs\n│ ├── skill_md_url: HttpUrl # User-provided URL (e.g., GitHub blob)\n│ ├── skill_md_raw_url: HttpUrl # Auto-translated raw content URL\n│ └── repository_url: HttpUrl # Optional git repository\n│\n├── Metadata\n│ ├── version: string # Skill version\n│ ├── author: string # Skill author\n│ ├── license: string # License identifier\n│ ├── compatibility: string # Human-readable requirements\n│ └── tags: string[] # Categorization tags\n│\n├── Requirements\n│ ├── requirements: CompatibilityRequirement[] # Machine-readable\n│ ├── target_agents: string[] # Target AI assistants\n│ └── allowed_tools: ToolReference[] # Required MCP tools\n│\n├── Access Control\n│ ├── visibility: public|private|group\n│ ├── allowed_groups: string[] # For group visibility\n│ └── owner: string # For private visibility\n│\n├── State\n│ ├── is_enabled: boolean # Enable/disable toggle\n│ ├── registry_name: string # Source registry (for federation)\n│ ├── health_status: healthy|unhealthy|unknown\n│ └── last_checked_time: datetime # Last health check\n│\n├── Ratings\n│ ├── num_stars: float # Average rating (0-5)\n│ └── rating_details: RatingDetail[] # Individual ratings\n│\n└── Timestamps\n ├── created_at: datetime\n └── updated_at: datetime\n```\n\n### ToolReference\n\nLinks skills to required MCP server tools:\n\n```python\nclass ToolReference:\n tool_name: str # Tool name (e.g., \"Read\", \"Bash\")\n server_path: str | None # MCP server path (e.g., \"/servers/claude-tools\")\n version: str | None # Optional version constraint\n capabilities: list[str] # Capability filters (e.g., [\"git:*\"])\n```\n\n### CompatibilityRequirement\n\nMachine-readable compatibility constraints:\n\n```python\nclass CompatibilityRequirement:\n type: \"product\" | \"tool\" | \"api\" | \"environment\"\n target: str # Target identifier\n min_version: str | None # Minimum version\n max_version: str | None # Maximum version\n required: bool # False = optional enhancement\n```\n\n## URL Translation\n\nThe registry automatically translates user-friendly URLs to raw content URLs:\n\n### GitHub Translation\n\n```\nInput: https://github.com/org/repo/blob/main/skills/name/SKILL.md\nOutput: https://raw.githubusercontent.com/org/repo/main/skills/name/SKILL.md\n```\n\n### GitLab Translation\n\n```\nInput: https://gitlab.com/org/repo/-/blob/main/skills/name/SKILL.md\nOutput: https://gitlab.com/org/repo/-/raw/main/skills/name/SKILL.md\n```\n\n### Bitbucket Translation\n\n```\nInput: https://bitbucket.org/org/repo/src/main/skills/name/SKILL.md\nOutput: https://bitbucket.org/org/repo/raw/main/skills/name/SKILL.md\n```\n\n## Access Control\n\nSkills support three visibility levels:\n\n### Public Skills\n- Visible to all authenticated users\n- Discoverable via search and listing\n- Exportable via federation\n\n### Private Skills\n- Visible only to the owner\n- Not discoverable by others\n- Not exportable via federation\n\n### Group Skills\n- Visible to members of specified groups\n- Groups are managed via IdP integration (Entra ID, Cognito, etc.)\n- Requires `allowed_groups` to be specified\n\n## Health Checking\n\nSkills are health-checked by verifying SKILL.md accessibility:\n\n1. **HEAD Request**: Verify the raw URL is accessible\n2. **Status Codes**: 2xx = healthy, others = unhealthy\n3. **Trusted Domains**: Only allowed domains are checked (SSRF protection)\n4. **Caching**: Results cached with `last_checked_time`\n\n### Trusted Domains\n\n```python\nTRUSTED_DOMAINS = [\n \"raw.githubusercontent.com\",\n \"gitlab.com\",\n \"bitbucket.org\",\n \"gist.githubusercontent.com\",\n]\n```\n\n## Rating System\n\nSkills use the same rating system as servers and agents:\n\n1. **Star Rating**: 1-5 stars\n2. **Per-User**: One rating per user per skill\n3. **Updates**: Users can update their rating\n4. **Average**: Displayed as average of all ratings\n\n## Tool Validation\n\nSkills can reference MCP server tools. The registry validates tool availability:\n\n1. **Check Registration**: Verify referenced servers exist\n2. **Check Tools**: Verify tools are exposed by servers\n3. **Report Status**: Return availability status per tool\n\n## API Endpoints\n\n### Skill Management\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/skills` | List skills (with visibility filtering) |\n| GET | `/api/skills/{path}` | Get skill details |\n| POST | `/api/skills` | Register new skill |\n| PUT | `/api/skills/{path}` | Update skill |\n| DELETE | `/api/skills/{path}` | Delete skill |\n\n### Skill State\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| PUT | `/api/skills/{path}/enable` | Enable skill |\n| PUT | `/api/skills/{path}/disable` | Disable skill |\n| GET | `/api/skills/{path}/health` | Check skill health |\n\n### Skill Content\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/skills/{path}/content` | Fetch SKILL.md content |\n| GET | `/api/skills/{path}/tools` | Check tool availability |\n\n### Ratings\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/skills/{path}/rating` | Get rating info |\n| POST | `/api/skills/{path}/rate` | Submit/update rating |\n\n## Database Schema\n\nSkills are stored in MongoDB/DocumentDB with the following indexes:\n\n```javascript\n// Unique index on name\ndb.agent_skills.createIndex({ \"name\": 1 }, { unique: true })\n\n// Tags for filtering\ndb.agent_skills.createIndex({ \"tags\": 1 })\n\n// Visibility for access control\ndb.agent_skills.createIndex({ \"visibility\": 1 })\n\n// Registry name for federation\ndb.agent_skills.createIndex({ \"registry_name\": 1 })\n\n// Owner for private skills\ndb.agent_skills.createIndex({ \"owner\": 1 })\n\n// Compound index for common queries\ndb.agent_skills.createIndex({\n \"visibility\": 1,\n \"is_enabled\": 1,\n \"registry_name\": 1\n})\n```\n\n## Federation Support\n\nSkills participate in peer-to-peer federation:\n\n1. **Export**: Public skills are exported to peer registries\n2. **Import**: Skills from peers are imported with `registry_name` set\n3. **Sync Modes**: All, whitelist, or tag-based filtering\n4. **Ownership**: Federated skills retain original registry attribution\n\n## Future Considerations\n\n### Content Caching\n- Cache SKILL.md content to reduce external fetches\n- Use `content_version` hash for cache invalidation\n- Track `content_updated_at` for freshness\n\n### Skill Bundles\n- Group related skills into bundles\n- Enable/disable bundles atomically\n- Share bundle configurations\n\n### Usage Analytics\n- Track skill usage across clients\n- Surface popular skills in discovery\n- Enable skill recommendations\n\n### Versioning\n- Track skill version history\n- Support rollback to previous versions\n- Version-aware federation sync\n" }, { "path": "docs/design/agentcore-scanner-design.md", "content": "# AgentCore Auto-Registration -- Low-Level Design\n\n*Created: 2026-04-03*\n*Updated: 2026-04-04*\n\n## Purpose\n\nDiscover AWS Bedrock AgentCore Gateways and Agent Runtimes in one or more AWS accounts and register them with the MCP Gateway Registry. Auth tokens for CUSTOM_JWT gateways are managed by a separate token refresher process that runs as a cron job or sidecar.\n\n## Components\n\n| Component | File | Runs |\n|-----------|------|------|\n| **Scanner + Registrar** | `cli/agentcore/` | On-demand or scheduled |\n| **Token Refresher** | `cli/agentcore/token_refresher.py` | Cron every 45 min or sidecar |\n\n```\n Phase 1: Registration Phase 2: Token Refresh\n (on-demand) (cron every 45 min)\n\n +----------------+ +--------------------+ +--------------------+\n | AgentCore API |---->| Scanner+Registrar |--register--> | MCP Gateway |\n | (AWS) | | cli/agentcore/ | | Registry |\n +----------------+ +--------------------+ +--------------------+\n | ^\n | writes | PATCH auth_credential\n v |\n +-------------------------+ +--------------------+\n | token_refresh_manifest |--read------->| Token Refresher |\n | .json (gitignored) | | token_refresher.py |\n +-------------------------+ +--------------------+\n |\n +------+------+\n | |\n GET OIDC POST token\n discovery endpoint\n | |\n +----v-------------v----+\n | IdP (Cognito, Auth0, |\n | Okta, Entra, etc.) |\n +-----------------------+\n```\n\n---\n\n## Background: What AgentCore Returns\n\nEvery CUSTOM_JWT gateway from the AgentCore API includes OIDC metadata:\n\n```json\n{\n \"name\": \"customersupport-gw\",\n \"gatewayUrl\": \"https://gateway.example.com\",\n \"authorizerType\": \"CUSTOM_JWT\",\n \"authorizerConfiguration\": {\n \"customJWTAuthorizer\": {\n \"discoveryUrl\": \"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_pnikLWYzO/.well-known/openid-configuration\",\n \"allowedClients\": [\"7kqi2l0n47mnfmhfapsf29ch4h\"]\n }\n }\n}\n```\n\nThe `discoveryUrl` is an OIDC Discovery endpoint (standard across all providers). GETting it returns:\n\n```json\n{\n \"issuer\": \"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_pnikLWYzO\",\n \"token_endpoint\": \"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_pnikLWYzO/oauth2/token\",\n \"jwks_uri\": \"...\"\n}\n```\n\nThe `token_endpoint` works for standard OAuth2 `client_credentials` grant. This is identical across Cognito, Auth0, Okta, Entra, Keycloak -- no provider-specific code needed for token generation.\n\nThe IdP vendor is always identifiable from the `discoveryUrl`:\n\n| IdP | Pattern in discoveryUrl |\n|-----|------------------------|\n| Cognito | `cognito-idp` |\n| Auth0 | `auth0.com` |\n| Okta | `okta.com` |\n| Entra | `microsoftonline.com` |\n| Keycloak | `/realms/` |\n\nThis matters because Cognito allows auto-retrieval of `client_secret` via the AWS API (`describe_user_pool_client`), while other providers require the secret to be configured as an environment variable.\n\n---\n\n## Phase 1: Scanner + Registrar\n\n### CLI Interface\n\n```bash\n# List resources (discovery only, no registration)\nuv run python -m cli.agentcore list \\\n --region us-east-1 \\\n --output json\n\n# Dry run\nuv run python -m cli.agentcore sync \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n --region us-east-1 \\\n --dry-run\n\n# Register\nuv run python -m cli.agentcore sync \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n --region us-east-1\n\n# Cross-account\nuv run python -m cli.agentcore sync \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n --region us-east-1 \\\n --accounts 111122223333,444455556666\n```\n\n**Flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--registry-url` | `REGISTRY_URL` env or `http://localhost` | Registry base URL |\n| `--token-file` | `REGISTRY_TOKEN_FILE` env or `.token` | Path to registry auth token file |\n| `--region` | `AWS_REGION` env or `us-east-1` | AWS region |\n| `--timeout` | `30` | AWS API call timeout (seconds) |\n| `--dry-run` | false | Preview without registering |\n| `--overwrite` | false | Overwrite existing registrations |\n| `--gateways-only` | false | Skip runtimes |\n| `--runtimes-only` | false | Skip gateways |\n| `--include-mcp-targets` | false | Register mcpServer gateway targets as separate servers |\n| `--accounts` | current account | Comma-separated account IDs for cross-account |\n| `--assume-role-name` | `AgentCoreSyncRole` | IAM role to assume in target accounts |\n| `--output` | `text` | Output format: `text` or `json` |\n| `--manifest` | `token_refresh_manifest.json` | Output path for token refresh manifest |\n| `--visibility` | `internal` | Registration visibility |\n| `--debug` | false | Enable DEBUG logging |\n\n### Sequence Diagram\n\n```\nUser cmd_sync Scanner AgentCore API RegistryClient\n | | | | |\n |-- sync ---------->| | | |\n | | | | |\n | |-- scan_gateways() | |\n | |---------------->| | |\n | | |-- list_gateways->| |\n | | |<-- gw summaries -| |\n | | |-- get_gateway() ->| |\n | | |<-- full gateway --| |\n | | | (includes authorizerConfiguration)|\n | | |-- list_targets() ->| |\n | | |<-- targets --------| |\n | |<-- gateways ----| | |\n | | | |\n | | For each gateway: | |\n | | | |\n | | 1. Build registration model | |\n | | - proxy_pass_url = gatewayUrl | |\n | | - auth_scheme = \"bearer\" | |\n | | (for CUSTOM_JWT and AWS_IAM) | |\n | | - auth_credential = null | |\n | | - metadata includes: | |\n | | discovery_url | |\n | | allowed_clients | |\n | | idp_vendor | |\n | | | |\n | | 2. Register with registry | |\n | |-- POST /internal/services ----------------------> |\n | |<-- 201 Created ----------------------------------| |\n | | | |\n | | 3. If CUSTOM_JWT: add to manifest entries |\n | | | |\n | |-- scan_runtimes() | |\n | |---------------->| | |\n | | |-- list_runtimes->| |\n | | |<-- runtimes -----| |\n | |<-- runtimes ----| | |\n | | | |\n | | For each runtime: | |\n | | - MCP protocol -> register as MCP Server |\n | | - HTTP/A2A -> register as Agent |\n | | (no token needed, health check | |\n | | falls back to ping) | |\n | | | |\n | |-- write token_refresh_manifest.json| |\n | |-- print summary | |\n | | | |\n |<-- summary -------| | |\n```\n\n### Files\n\n| File | Lines (approx) | Responsibility |\n|------|----------------|----------------|\n| `cli/agentcore/__init__.py` | 10 | Package init |\n| `cli/agentcore/__main__.py` | 7 | `python -m cli.agentcore` entry point |\n| `cli/agentcore/sync.py` | ~300 | CLI parsing (`argparse`), `cmd_sync()`, `cmd_list()` |\n| `cli/agentcore/discovery.py` | ~200 | `AgentCoreScanner` -- paginated AWS API calls |\n| `cli/agentcore/registration.py` | ~500 | `RegistrationBuilder`, `SyncOrchestrator` |\n| `cli/agentcore/models.py` | ~200 | Pydantic models, helper functions |\n\n### Key Data Structures\n\n#### AgentCoreScanner\n\n```python\nclass AgentCoreScanner:\n \"\"\"Scans AgentCore resources via boto3 bedrock-agentcore-control client.\"\"\"\n\n def __init__(\n self,\n region: str,\n timeout: int = 30,\n session: boto3.Session | None = None,\n ) -> None: ...\n\n def scan_gateways(self) -> list[dict[str, Any]]:\n \"\"\"List gateways, filter to READY, get details + targets.\"\"\"\n ...\n\n def scan_runtimes(self) -> list[dict[str, Any]]:\n \"\"\"List runtimes, filter to READY, get details + endpoints.\"\"\"\n ...\n```\n\nBoth methods paginate via `nextToken` and only return resources with `status == \"READY\"`.\n\n#### RegistrationBuilder\n\nConverts raw AWS dicts into registry registration models.\n\n```python\nclass RegistrationBuilder:\n\n def __init__(\n self,\n region: str,\n visibility: str = \"internal\",\n session: boto3.Session | None = None,\n ) -> None:\n self.region = region\n self.visibility = visibility\n self.account_id = self._get_account_id()\n\n def build_gateway_registration(\n self,\n gateway: dict[str, Any],\n ) -> InternalServiceRegistration:\n \"\"\"Build MCP Server registration from a gateway.\n\n Extracts OIDC metadata (discovery_url, allowed_clients, idp_vendor)\n from authorizerConfiguration and stores in metadata field.\n \"\"\"\n name = gateway.get(\"name\", gateway[\"gatewayId\"])\n gateway_url = gateway.get(\"gatewayUrl\", \"\")\n authorizer_type = gateway.get(\"authorizerType\", \"NONE\")\n\n # Extract OIDC metadata for CUSTOM_JWT gateways\n authorizer_config = gateway.get(\"authorizerConfiguration\", {})\n jwt_config = authorizer_config.get(\"customJWTAuthorizer\", {})\n discovery_url = jwt_config.get(\"discoveryUrl\", \"\")\n allowed_clients = jwt_config.get(\"allowedClients\", [])\n idp_vendor = _detect_idp_vendor(discovery_url) if discovery_url else \"\"\n\n metadata = {\n \"source\": \"agentcore-sync\",\n \"gateway_arn\": gateway.get(\"gatewayArn\"),\n \"gateway_id\": gateway.get(\"gatewayId\"),\n \"authorizer_type\": authorizer_type,\n \"region\": self.region,\n \"account_id\": self.account_id,\n }\n\n if authorizer_type == \"CUSTOM_JWT\" and discovery_url:\n metadata[\"discovery_url\"] = discovery_url\n metadata[\"allowed_clients\"] = allowed_clients\n metadata[\"idp_vendor\"] = idp_vendor\n\n return InternalServiceRegistration(\n path=f\"/{_slugify(name)}\",\n name=name,\n description=gateway.get(\"description\", f\"AgentCore Gateway: {name}\"),\n proxy_pass_url=gateway_url,\n mcp_endpoint=gateway_url,\n auth_provider=\"bedrock-agentcore\",\n auth_scheme=_get_auth_scheme(authorizer_type),\n supported_transports=[\"streamable-http\"],\n tags=[\"agentcore\", \"gateway\", \"auto-registered\"],\n overwrite=False,\n metadata=metadata,\n )\n\n def build_runtime_mcp_registration(\n self,\n runtime: dict[str, Any],\n ) -> InternalServiceRegistration:\n \"\"\"Build MCP Server registration from a MCP-protocol runtime.\"\"\"\n ...\n\n def build_runtime_agent_registration(\n self,\n runtime: dict[str, Any],\n ) -> AgentRegistration:\n \"\"\"Build A2A Agent registration from an HTTP/A2A-protocol runtime.\"\"\"\n ...\n```\n\n#### SyncOrchestrator\n\nCoordinates scan, build, register, and manifest output.\n\n```python\nclass SyncOrchestrator:\n \"\"\"Orchestrates discovery, registration, and manifest generation.\n\n 1. Scan gateways / runtimes via AgentCoreScanner\n 2. Build registrations via RegistrationBuilder\n 3. Register with the registry via RegistryClient\n 4. Write token_refresh_manifest.json for CUSTOM_JWT gateways\n \"\"\"\n\n def __init__(\n self,\n scanner: AgentCoreScanner,\n builder: RegistrationBuilder,\n registry_client: RegistryClient,\n dry_run: bool = False,\n overwrite: bool = False,\n include_mcp_targets: bool = False,\n output_format: str = \"text\",\n manifest_path: str = \"token_refresh_manifest.json\",\n ) -> None:\n self.scanner = scanner\n self.builder = builder\n self.registry = registry_client\n self.dry_run = dry_run\n self.overwrite = overwrite\n self.include_mcp_targets = include_mcp_targets\n self.output_format = output_format\n self.manifest_path = manifest_path\n self.results: list[dict[str, Any]] = []\n self._manifest_entries: list[dict[str, Any]] = []\n\n def sync_gateways(self) -> None:\n \"\"\"Scan and register all gateways.\"\"\"\n gateways = self.scanner.scan_gateways()\n for gateway in gateways:\n self._register_gateway(gateway)\n if self.include_mcp_targets:\n for target in gateway.get(\"targets\", []):\n self._register_target(gateway, target)\n\n def sync_runtimes(self) -> None:\n \"\"\"Scan and register all runtimes.\"\"\"\n runtimes = self.scanner.scan_runtimes()\n for runtime in runtimes:\n self._register_runtime(runtime)\n\n def write_manifest(self) -> None:\n \"\"\"Write token_refresh_manifest.json for CUSTOM_JWT gateways.\"\"\"\n if self.dry_run:\n logger.info(\n f\"[DRY-RUN] Would write manifest with \"\n f\"{len(self._manifest_entries)} entries\"\n )\n return\n\n if not self._manifest_entries:\n logger.info(\"No CUSTOM_JWT gateways -- skipping manifest\")\n return\n\n with open(self.manifest_path, \"w\") as f:\n json.dump(self._manifest_entries, f, indent=2)\n\n logger.info(\n f\"Wrote {len(self._manifest_entries)} entries \"\n f\"to {self.manifest_path}\"\n )\n\n def print_summary(self) -> None:\n \"\"\"Print sync summary in text or JSON format.\"\"\"\n ...\n```\n\n#### `_register_gateway()` -- core registration logic\n\n```python\ndef _register_gateway(\n self,\n gateway: dict[str, Any],\n) -> None:\n \"\"\"Register a single gateway with the registry.\"\"\"\n gateway_name = gateway.get(\"name\", gateway[\"gatewayId\"])\n gateway_url = gateway.get(\"gatewayUrl\", \"\")\n gateway_arn = gateway.get(\"gatewayArn\", \"\")\n\n if not _validate_https_url(gateway_url, gateway_name):\n self.results.append({\n \"resource_type\": \"gateway\",\n \"resource_name\": gateway_name,\n \"resource_arn\": gateway_arn,\n \"registration_type\": \"mcp_server\",\n \"path\": f\"/{_slugify(gateway_name)}\",\n \"status\": \"skipped\",\n \"message\": \"Invalid URL (must be HTTPS)\",\n })\n return\n\n registration = self.builder.build_gateway_registration(gateway)\n registration.overwrite = self.overwrite\n\n result: dict[str, Any] = {\n \"resource_type\": \"gateway\",\n \"resource_name\": gateway_name,\n \"resource_arn\": gateway_arn,\n \"registration_type\": \"mcp_server\",\n \"path\": registration.service_path,\n }\n\n if self.dry_run:\n result[\"status\"] = \"dry_run\"\n result[\"message\"] = \"Would register as MCP Server\"\n self.results.append(result)\n self._collect_manifest_entry(gateway, registration.service_path)\n return\n\n try:\n self._register_service_with_retry(registration)\n result[\"status\"] = \"registered\"\n result[\"message\"] = \"Successfully registered\"\n except Exception as e:\n if _is_conflict_error(e) and not self.overwrite:\n result[\"status\"] = \"skipped\"\n result[\"message\"] = \"Already registered (use --overwrite)\"\n else:\n result[\"status\"] = \"failed\"\n result[\"message\"] = str(e)\n logger.error(f\"Failed to register gateway: {e}\")\n self.results.append(result)\n return\n\n self.results.append(result)\n self._collect_manifest_entry(gateway, registration.service_path)\n\n\ndef _collect_manifest_entry(\n self,\n gateway: dict[str, Any],\n server_path: str,\n) -> None:\n \"\"\"Add a CUSTOM_JWT gateway to the token refresh manifest.\"\"\"\n if gateway.get(\"authorizerType\") != \"CUSTOM_JWT\":\n return\n\n jwt_config = gateway.get(\"authorizerConfiguration\", {}).get(\n \"customJWTAuthorizer\", {}\n )\n discovery_url = jwt_config.get(\"discoveryUrl\", \"\")\n if not discovery_url:\n return\n\n self._manifest_entries.append({\n \"server_path\": server_path,\n \"gateway_arn\": gateway.get(\"gatewayArn\", \"\"),\n \"discovery_url\": discovery_url,\n \"allowed_clients\": jwt_config.get(\"allowedClients\", []),\n \"idp_vendor\": _detect_idp_vendor(discovery_url),\n })\n```\n\n### Helper Functions\n\n```python\nIDP_PATTERNS: dict[str, str] = {\n \"cognito-idp\": \"cognito\",\n \"auth0.com\": \"auth0\",\n \"okta.com\": \"okta\",\n \"microsoftonline.com\": \"entra\",\n \"/realms/\": \"keycloak\",\n}\n\n\ndef _detect_idp_vendor(\n discovery_url: str,\n) -> str:\n \"\"\"Detect IdP vendor from OIDC discovery URL.\"\"\"\n for pattern, vendor in IDP_PATTERNS.items():\n if pattern in discovery_url:\n return vendor\n return \"unknown\"\n\n\ndef _slugify(name: str) -> str:\n \"\"\"Convert name to URL-safe slug.\"\"\"\n ...\n\n\ndef _validate_https_url(url: str, resource_name: str) -> bool:\n \"\"\"Validate that URL uses HTTPS.\"\"\"\n ...\n\n\ndef _get_auth_scheme(authorizer_type: str) -> str:\n \"\"\"Map AgentCore authorizer type to registry auth scheme.\n CUSTOM_JWT -> bearer, AWS_IAM -> bearer, NONE -> none.\n \"\"\"\n ...\n```\n\n### Manifest File Format\n\nOutput: `token_refresh_manifest.json` (add to `.gitignore`)\n\n```json\n[\n {\n \"server_path\": \"/customersupport-gw\",\n \"gateway_arn\": \"arn:aws:bedrock:us-east-1:123456789012:gateway/gw-abc\",\n \"discovery_url\": \"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_pnikLWYzO/.well-known/openid-configuration\",\n \"allowed_clients\": [\"7kqi2l0n47mnfmhfapsf29ch4h\"],\n \"idp_vendor\": \"cognito\"\n },\n {\n \"server_path\": \"/enterprise-gw\",\n \"gateway_arn\": \"arn:aws:bedrock:us-east-1:123456789012:gateway/gw-def\",\n \"discovery_url\": \"https://myorg.okta.com/.well-known/openid-configuration\",\n \"allowed_clients\": [\"0oa1234567abcdefg\"],\n \"idp_vendor\": \"okta\"\n }\n]\n```\n\n### Runtime Registration\n\nRuntimes are registered without tokens. The registry health check falls back to a ping for servers without `auth_credential`.\n\n- **MCP protocol runtime** -> registered as MCP Server (via `InternalServiceRegistration`)\n- **HTTP/A2A protocol runtime** -> registered as A2A Agent (via `AgentRegistration` with SigV4 security scheme)\n\nNo manifest entry is created for runtimes.\n\n> **Note:** Agents imported from runtimes are registered with an empty skills array. To add skills, use the agent edit dialog in the UI or the `PUT /api/agents/{path}` API endpoint. Updating skills triggers a security rescan of the agent.\n\n#### Agent Overwrite Handling\n\n`AgentRegistration` does not have an `overwrite` field (unlike `InternalServiceRegistration`). When `--overwrite` is used and an agent already exists (409 Conflict), the orchestrator catches the conflict and calls `update_agent()` (PUT) to update the existing registration:\n\n1. Attempt `register_agent()` (POST)\n2. If 409 Conflict and `--overwrite` is set -> call `update_agent()` (PUT)\n3. If 409 Conflict without `--overwrite` -> mark as \"skipped\"\n\n### Cross-Account Support\n\nFor multi-account scanning, the CLI accepts `--accounts 111122223333,444455556666`. For each account:\n\n1. `sts:AssumeRole` into `arn:aws:iam::{account}:role/{assume_role_name}`\n2. Create a boto3 Session from the assumed role credentials\n3. Pass that session to `AgentCoreScanner` and `RegistrationBuilder`\n4. Register all discovered resources into the same registry\n\n---\n\n## Phase 2: Token Refresher\n\n### File: `cli/agentcore/token_refresher.py`\n\nStandalone script (~250 lines) that reads the manifest, resolves client secrets, fetches tokens, and updates the registry.\n\n### CLI Interface\n\n```bash\n# One-time refresh (Cognito auto-retrieval needs no env vars)\nuv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n# With per-client env vars (highest priority)\nOAUTH_CLIENT_SECRET_49ujl0b9ser72gnp6q1ph9v6vs=mysecret \\\n uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n# With vendor-level env vars (fallback for non-Cognito IdPs)\nAUTH0_CLIENT_SECRET=xxx OKTA_CLIENT_SECRET=yyy \\\n uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token\n\n# Continuous mode (run as sidecar)\nuv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n --loop --interval 2700\n```\n\n**Flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--manifest` | `token_refresh_manifest.json` | Path to manifest file |\n| `--registry-url` | `REGISTRY_URL` env or `http://localhost` | Registry base URL |\n| `--token-file` | `REGISTRY_TOKEN_FILE` env or `.token` | Registry auth token file |\n| `--loop` | false | Run continuously |\n| `--interval` | `2700` (45 min) | Refresh interval in seconds |\n| `--scan` / `--no-scan` | `--scan` (enabled) | Trigger security rescan after each credential update |\n| `--debug` | false | Enable DEBUG logging |\n\n### Sequence Diagram\n\n```\ntoken_refresher.py Manifest Env Vars Cognito API OIDC Discovery Registry\n | | | | | |\n |-- read -------->| | | | |\n |<-- entries[] ---| | | | |\n | | | | |\n | For each entry: | | | |\n | | | | |\n | 1. Resolve client_secret (3-tier priority) | | |\n | [Priority 1: per-client] | | | |\n |-- check OAUTH_CLIENT_SECRET_| | | |\n | if found -> use it | | | |\n | | | | |\n | [Priority 2: cognito auto] | | | |\n | (if cognito + no per-client)---------------->| | |\n | describe_user_pool_client() | | | |\n | <-- ClientSecret -----------|---------------| | |\n | | | | |\n | [Priority 3: vendor env] | | | |\n |-- check AUTH0_/OKTA_/etc ------>| | | |\n | | | | |\n | 2. Get token_endpoint | | | |\n |-- GET discovery_url ------------------------------------------>| |\n |<-- {token_endpoint: \"...\"} ------------------------------------| |\n | | | | |\n | 3. Get token (OAuth2 client_credentials) | | |\n |-- POST token_endpoint ---------------------------------------->| |\n | {grant_type: client_credentials, | | |\n | client_id: allowed_clients[0], | | |\n | client_secret: from step 1} | | |\n |<-- {access_token: \"eyJ...\"} -----------------------------------| |\n | | | | |\n | 4. Update registry | | | |\n |-- PATCH /api/servers/{path}/auth-credential ---------------------------> |\n | {auth_scheme: \"bearer\", auth_credential: \"eyJ...\"} |\n |<-- 200 OK --------------------------------------------------------------------|\n | | | | |\n | 5. Trigger security rescan | | | |\n |-- POST /api/servers/{path}/rescan ----------------------------------------> |\n |<-- scan results (is_safe, severity counts) ------------------------------------|\n | | | | |\n | Write last_refreshed timestamp to manifest | | |\n```\n\n### Client Secret Resolution (3-Tier Priority)\n\nFor each manifest entry, the token refresher resolves the client secret using this priority order:\n\n| Priority | Method | Env Var / Mechanism | When Used |\n|----------|--------|---------------------|-----------|\n| **1** | Per-client env var | `OAUTH_CLIENT_SECRET_=` | Any IdP -- overrides all other methods |\n| **2** | Cognito auto-retrieval | `boto3.describe_user_pool_client()` | `cognito` only -- parses pool_id/region from discovery URL |\n| **3** | Vendor-specific env var | `AUTH0_CLIENT_SECRET`, `OKTA_CLIENT_SECRET`, `ENTRA_CLIENT_SECRET`, `KEYCLOAK_CLIENT_SECRET` | Non-Cognito IdPs -- one secret shared across all gateways for that vendor |\n\nIf none of the tiers produce a secret, the entry is skipped with a warning.\n\n**Per-client env var** (Priority 1) is useful when multiple gateways use the same IdP but have different client secrets. The env var name is `OAUTH_CLIENT_SECRET_` followed by the `client_id` (from `allowed_clients[0]` in the manifest).\n\n**Cognito auto-retrieval** (Priority 2) parses region and pool_id from the discovery URL:\n```\nhttps://cognito-idp.us-east-1.amazonaws.com/us-east-1_pnikLWYzO/.well-known/openid-configuration\n ^^^^^^^^^ ^^^^^^^^^^^^^^^^^\n region user_pool_id\n```\nThen calls `describe_user_pool_client(UserPoolId=pool_id, ClientId=client_id)` to auto-retrieve the secret. Requires IAM permissions for `cognito-idp:DescribeUserPoolClient`.\n\n**Vendor env vars** (Priority 3) are shared across all gateways for a given IdP. One secret per vendor.\n\n| IdP Vendor | Env Var |\n|------------|---------|\n| `auth0` | `AUTH0_CLIENT_SECRET` |\n| `okta` | `OKTA_CLIENT_SECRET` |\n| `entra` | `ENTRA_CLIENT_SECRET` |\n| `keycloak` | `KEYCLOAK_CLIENT_SECRET` |\n| `unknown` | Skipped with warning |\n\n### Code Structure\n\nAll private functions at the top, public functions below. One parameter per line. Modular functions (30-50 lines max).\n\n#### Constants\n\n```python\nOIDC_DISCOVERY_TIMEOUT: int = 10\nTOKEN_REQUEST_TIMEOUT: int = 15\nREGISTRY_REQUEST_TIMEOUT: int = 15\n\nIDP_PATTERNS: dict[str, str] = {\n \"cognito-idp\": \"cognito\",\n \"auth0.com\": \"auth0\",\n \"okta.com\": \"okta\",\n \"microsoftonline.com\": \"entra\",\n \"/realms/\": \"keycloak\",\n}\n\nIDP_SECRET_ENV_VARS: dict[str, str] = {\n \"auth0\": \"AUTH0_CLIENT_SECRET\",\n \"okta\": \"OKTA_CLIENT_SECRET\",\n \"entra\": \"ENTRA_CLIENT_SECRET\",\n \"keycloak\": \"KEYCLOAK_CLIENT_SECRET\",\n}\n\nENV_VAR_PREFIX: str = \"OAUTH_CLIENT_SECRET_\"\n```\n\n#### Private Functions\n\n```python\ndef _read_manifest(\n manifest_path: str,\n) -> list[dict[str, Any]]:\n \"\"\"Read token refresh manifest from JSON file.\"\"\"\n ...\n\n\ndef _detect_idp_vendor(\n discovery_url: str,\n) -> str:\n \"\"\"Detect IdP vendor from OIDC discovery URL.\n Matches known patterns in the URL string.\n \"\"\"\n for pattern, vendor in IDP_PATTERNS.items():\n if pattern in discovery_url:\n return vendor\n return \"unknown\"\n\n\ndef _get_cognito_client_secret(\n discovery_url: str,\n client_id: str,\n) -> str | None:\n \"\"\"Auto-retrieve client secret from Cognito.\n\n Parses user_pool_id and region from the discoveryUrl,\n calls describe_user_pool_client() via boto3.\n \"\"\"\n # Parse: https://cognito-idp.{region}.amazonaws.com/{pool_id}/...\n region = discovery_url.split(\"cognito-idp.\")[1].split(\".amazonaws\")[0]\n pool_id = discovery_url.split(\"amazonaws.com/\")[1].split(\"/\")[0]\n\n client = boto3.client(\"cognito-idp\", region_name=region)\n response = client.describe_user_pool_client(\n UserPoolId=pool_id,\n ClientId=client_id,\n )\n return response[\"UserPoolClient\"].get(\"ClientSecret\")\n\n\ndef _get_client_secret(\n idp_vendor: str,\n discovery_url: str,\n client_id: str,\n) -> str | None:\n \"\"\"Resolve client secret using 3-tier priority:\n\n 1. Per-client env var: OAUTH_CLIENT_SECRET_\n 2. Cognito auto-retrieval via AWS API (cognito only)\n 3. Vendor env var: AUTH0_CLIENT_SECRET, OKTA_CLIENT_SECRET, etc.\n \"\"\"\n # Priority 1: per-client env var (OAUTH_CLIENT_SECRET_)\n env_var_name = f\"{ENV_VAR_PREFIX}{client_id}\"\n secret = os.environ.get(env_var_name)\n if secret:\n logger.info(f\"Using client secret from env var {env_var_name}\")\n return secret\n\n # Priority 2: Cognito auto-retrieval via AWS API\n if idp_vendor == \"cognito\":\n return _get_cognito_client_secret(discovery_url, client_id)\n\n # Priority 3: vendor-specific env var\n vendor_env_var = IDP_SECRET_ENV_VARS.get(idp_vendor)\n if not vendor_env_var:\n logger.warning(f\"No env var mapping for IdP vendor: {idp_vendor}\")\n return None\n\n secret = os.environ.get(vendor_env_var)\n if not secret:\n logger.warning(f\"Env var {vendor_env_var} not set for {idp_vendor}\")\n return secret\n\n\ndef _get_token_endpoint(\n discovery_url: str,\n) -> str | None:\n \"\"\"Fetch token_endpoint from OIDC discovery document.\n\n GETs the discoveryUrl and extracts the token_endpoint field.\n Standard OIDC -- works for all providers.\n \"\"\"\n response = requests.get(discovery_url, timeout=OIDC_DISCOVERY_TIMEOUT)\n response.raise_for_status()\n return response.json().get(\"token_endpoint\")\n\n\ndef _request_token(\n token_endpoint: str,\n client_id: str,\n client_secret: str,\n) -> str | None:\n \"\"\"Request access token via OAuth2 client_credentials grant.\"\"\"\n response = requests.post(\n token_endpoint,\n headers={\"Content-Type\": \"application/x-www-form-urlencoded\"},\n data={\n \"grant_type\": \"client_credentials\",\n \"client_id\": client_id,\n \"client_secret\": client_secret,\n },\n timeout=TOKEN_REQUEST_TIMEOUT,\n )\n response.raise_for_status()\n return response.json().get(\"access_token\")\n\n\ndef _update_registry_credential(\n registry_url: str,\n registry_token: str,\n server_path: str,\n auth_credential: str,\n) -> bool:\n \"\"\"PATCH auth_credential for a server in the registry.\"\"\"\n url = f\"{registry_url.rstrip('/')}/api/servers{server_path}/auth-credential\"\n response = requests.patch(\n url,\n headers={\n \"Authorization\": f\"Bearer {registry_token}\",\n \"Content-Type\": \"application/json\",\n },\n json={\n \"auth_scheme\": \"bearer\",\n \"auth_credential\": auth_credential,\n },\n timeout=REGISTRY_REQUEST_TIMEOUT,\n )\n response.raise_for_status()\n return True\n\n\ndef _load_registry_token(\n token_file: str,\n) -> str:\n \"\"\"Load registry auth token from JSON file.\n\n Supports two formats:\n - Flat: {\"access_token\": \"...\"} or {\"token\": \"...\"}\n - Nested: {\"tokens\": {\"access_token\": \"...\"}}\n \"\"\"\n ...\n```\n\n#### Public Function\n\n```python\ndef refresh_all(\n manifest_path: str,\n registry_url: str,\n registry_token: str,\n run_scan: bool = True,\n) -> dict[str, Any]:\n \"\"\"Refresh tokens for all entries in the manifest.\n\n For each CUSTOM_JWT gateway:\n 1. Resolve client_secret (per-client env -> Cognito auto -> vendor env)\n 2. GET discoveryUrl -> extract token_endpoint\n 3. POST client_credentials grant -> get access_token\n 4. PATCH auth_credential in the registry\n 5. Trigger security rescan (if run_scan is True)\n\n Returns summary dict with success/failure/skipped/scan counts.\n \"\"\"\n entries = _read_manifest(manifest_path)\n start_time = time.time()\n\n success_count = 0\n failure_count = 0\n skipped_count = 0\n\n for entry in entries:\n server_path = entry[\"server_path\"]\n discovery_url = entry[\"discovery_url\"]\n allowed_clients = entry.get(\"allowed_clients\", [])\n idp_vendor = entry.get(\"idp_vendor\") or _detect_idp_vendor(discovery_url)\n\n if not allowed_clients:\n logger.warning(f\"No allowed_clients for {server_path} -- skipping\")\n skipped_count += 1\n continue\n\n client_id = allowed_clients[0]\n\n # Step 1: Resolve client_secret\n client_secret = _get_client_secret(idp_vendor, discovery_url, client_id)\n if not client_secret:\n skipped_count += 1\n continue\n\n # Step 2: Get token_endpoint via OIDC discovery\n token_endpoint = _get_token_endpoint(discovery_url)\n if not token_endpoint:\n failure_count += 1\n continue\n\n # Step 3: Request token\n token = _request_token(token_endpoint, client_id, client_secret)\n if not token:\n failure_count += 1\n continue\n\n # Step 4: Update registry\n updated = _update_registry_credential(\n registry_url, registry_token, server_path, token\n )\n if updated:\n success_count += 1\n entry[\"last_refreshed\"] = datetime.now(timezone.utc).isoformat()\n else:\n failure_count += 1\n\n # Update manifest with timestamps\n with open(manifest_path, \"w\") as f:\n json.dump(entries, f, indent=2)\n\n elapsed = time.time() - start_time\n summary = {\n \"total\": len(entries),\n \"success\": success_count,\n \"failed\": failure_count,\n \"skipped\": skipped_count,\n \"elapsed_seconds\": round(elapsed, 1),\n }\n logger.info(f\"Token refresh complete: {json.dumps(summary)}\")\n return summary\n```\n\n#### Main Function\n\n```python\ndef main() -> None:\n \"\"\"Parse arguments and run token refresh.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Refresh auth tokens for AgentCore CUSTOM_JWT gateways\",\n )\n parser.add_argument(\"--manifest\", default=\"token_refresh_manifest.json\")\n parser.add_argument(\"--registry-url\", default=os.environ.get(\"REGISTRY_URL\", \"http://localhost\"))\n parser.add_argument(\"--token-file\", default=os.environ.get(\"REGISTRY_TOKEN_FILE\", \".token\"))\n parser.add_argument(\"--loop\", action=\"store_true\")\n parser.add_argument(\"--interval\", type=int, default=2700)\n parser.add_argument(\"--debug\", action=\"store_true\")\n args = parser.parse_args()\n\n if args.debug:\n logging.getLogger().setLevel(logging.DEBUG)\n\n registry_token = _load_registry_token(args.token_file)\n\n if args.loop:\n while True:\n refresh_all(args.manifest, args.registry_url, registry_token)\n time.sleep(args.interval)\n else:\n refresh_all(args.manifest, args.registry_url, registry_token)\n```\n\n### Cron Setup\n\n```bash\n# Refresh every 45 minutes (tokens typically expire in 60 min)\n*/45 * * * * cd /app && uv run python -m cli.agentcore.token_refresher \\\n --manifest token_refresh_manifest.json \\\n --registry-url https://registry.example.com \\\n --token-file .token \\\n >> /var/log/token-refresher.log 2>&1\n```\n\nOr run as a sidecar with `--loop --interval 2700`.\n\n### Registry API Requirement\n\nThe token refresher uses the PATCH endpoint:\n\n```\nPATCH /api/servers/{path}/auth-credential\nAuthorization: Bearer {registry_token}\nContent-Type: application/json\n\n{\"auth_scheme\": \"bearer\", \"auth_credential\": \"eyJhbGciOiJSUzI1NiIs...\"}\n```\n\nThe registry encrypts the credential before storing (existing behavior for `auth_credential` on POST).\n\n**Note:** If the registry token has expired, the PATCH will fail with an HTTP 500 from nginx (HTML response, not JSON). The token refresher detects this and logs a diagnostic message suggesting token regeneration.\n\n---\n\n## Example: 12 Gateways Across 3 IdPs\n\n```\nGateways 1-5: Cognito (discoveryUrl contains \"cognito-idp\")\nGateways 6-8: Auth0 (discoveryUrl contains \"auth0.com\")\nGateways 9-12: Entra (discoveryUrl contains \"microsoftonline.com\")\n```\n\n**Phase 1** -- `sync` registers all 12 gateways without tokens. Outputs manifest with 12 entries.\n\n**Phase 2** -- `token_refresher` processes the manifest using 3-tier secret resolution:\n- Gateways 1-5: detects `cognito`, auto-retrieves secret via `describe_user_pool_client()` (zero config)\n- Gateways 6-8: detects `auth0`, reads `AUTH0_CLIENT_SECRET` from env (one secret for all 3)\n- Gateways 9-12: detects `entra`, reads `ENTRA_CLIENT_SECRET` from env (one secret for all 4)\n- For all 12: GETs discoveryUrl -> token_endpoint, POSTs client_credentials, PATCHes registry\n\n**Total config needed**: two env vars (`AUTH0_CLIENT_SECRET`, `ENTRA_CLIENT_SECRET`). Cognito needs nothing.\n\n**Override example**: If Auth0 gateway #7 uses a different client secret than gateways #6 and #8:\n```bash\n# Per-client override takes priority over AUTH0_CLIENT_SECRET\nOAUTH_CLIENT_SECRET_gw7clientid=different-secret AUTH0_CLIENT_SECRET=shared-secret \\\n uv run python -m cli.agentcore.token_refresher --manifest token_refresh_manifest.json\n```\n\n---\n\n## Test Plan\n\n| Test | What It Validates |\n|------|-------------------|\n| `test_detect_idp_vendor_cognito` | `_detect_idp_vendor()` returns `\"cognito\"` for cognito-idp URLs |\n| `test_detect_idp_vendor_auth0` | Returns `\"auth0\"` for auth0.com URLs |\n| `test_detect_idp_vendor_unknown` | Returns `\"unknown\"` for unrecognized URLs |\n| `test_build_gateway_registration_custom_jwt` | Metadata includes `discovery_url`, `allowed_clients`, `idp_vendor` |\n| `test_build_gateway_registration_none_auth` | Metadata does not include OIDC fields |\n| `test_register_gateway_collects_manifest` | `_manifest_entries` populated for CUSTOM_JWT gateways |\n| `test_register_gateway_no_manifest_for_iam` | `_manifest_entries` empty for AWS_IAM gateways |\n| `test_write_manifest_creates_file` | JSON file written with correct structure |\n| `test_write_manifest_dry_run_skips` | No file written in dry-run mode |\n| `test_sync_gateways_end_to_end` | Full flow: scan -> register -> manifest (mocked AWS + registry) |\n| `test_per_client_env_var_takes_priority` | `OAUTH_CLIENT_SECRET_` takes priority over Cognito auto and vendor env |\n| `test_get_cognito_client_secret` | Parses pool_id/region from URL, calls describe_user_pool_client |\n| `test_get_client_secret_auth0_from_env` | Reads AUTH0_CLIENT_SECRET |\n| `test_get_client_secret_missing_env` | Returns None, logs warning |\n| `test_get_token_endpoint_from_discovery` | GETs discovery URL, extracts token_endpoint |\n| `test_request_token_success` | Standard client_credentials grant |\n| `test_update_registry_credential` | PATCHes auth_credential via `/api/servers/{path}/auth-credential` |\n| `test_refresh_all_mixed_idps` | End-to-end: Cognito auto + Auth0 env + skip unknown |\n| `test_refresh_all_writes_timestamps` | Manifest updated with last_refreshed |\n| `test_runtime_no_manifest_entry` | Runtimes do not appear in manifest |\n| `test_agent_conflict_with_overwrite_calls_update` | Agent `--overwrite` uses `update_agent()` PUT on conflict |\n| `test_agent_conflict_without_overwrite_skips` | Agent conflict without `--overwrite` shows \"skipped\" |\n" }, { "path": "docs/design/ans-integration.md", "content": "# ANS (Agent Name Service) Integration\n\n**Demo Video:** [ANS Integration Walkthrough](https://app.vidcast.io/share/c2240a78-8899-46ad-9375-6fb0cc1345f3?playerMode=vidcast)\n\nThis document describes the ANS integration architecture, configuration, API usage, and operational procedures for the MCP Gateway Registry.\n\n## Overview\n\nANS (Agent Name Service) is a PKI-based trust verification service operated by GoDaddy that provides cryptographic identity verification for AI agents. The MCP Gateway Registry integrates with ANS using a **read-only \"Bring Your Own ANS ID\"** approach -- the registry never manages PKI certificates or identities directly. Instead, agent owners register with ANS independently and then link their ANS Agent ID to their registry entry for trust verification.\n\n### What ANS Provides\n\n- Cryptographic identity verification for AI agents\n- Domain ownership proof via PKI certificates\n- Agent identity metadata (name, description, version, organization)\n- Endpoint and protocol registration (A2A, MCP, HTTP-API)\n- Certificate lifecycle management (issuance, expiration, revocation)\n\n### What the Registry Does\n\n- Stores ANS verification metadata on agent and server records\n- Displays trust badges on agent/server cards in the UI\n- Periodically re-verifies ANS status via background sync\n- Provides admin visibility into ANS integration health\n\n```\nIntegration Architecture:\n\n Agent Owner AI Registry GoDaddy ANS API\n ----------- ----------- ---------------\n | | |\n | 1. Register with ANS | |\n | (out-of-band) ========================> |\n | | |\n | 2. Link ANS ID | |\n | POST /agents/{p}/ans/link |\n | ======================> | |\n | | 3. Verify with ANS API |\n | | ========================> |\n | | <== ANS Metadata ====== |\n | | |\n | 4. Trust badge shown | |\n | <===================== | |\n | | |\n | | 5. Background re-verify |\n | | (every 6 hours) |\n | | ========================> |\n```\n\n## Configuration\n\nAll ANS configuration is managed via environment variables that map to Pydantic Settings fields in `registry/core/config.py`.\n\n### Required Configuration\n\n| Parameter | Environment Variable | Description | Default |\n|-----------|---------------------|-------------|---------|\n| `ans_integration_enabled` | `ANS_INTEGRATION_ENABLED` | Master switch for ANS integration | `false` |\n| `ans_api_key` | `ANS_API_KEY` | GoDaddy API key for authentication | `\"\"` |\n| `ans_api_secret` | `ANS_API_SECRET` | GoDaddy API secret for authentication | `\"\"` |\n\n### Optional Configuration\n\n| Parameter | Environment Variable | Description | Default |\n|-----------|---------------------|-------------|---------|\n| `ans_api_endpoint` | `ANS_API_ENDPOINT` | ANS API base URL | `https://api.godaddy.com` |\n| `ans_api_timeout_seconds` | `ANS_API_TIMEOUT_SECONDS` | HTTP request timeout for ANS calls | `30` |\n| `ans_sync_interval_hours` | `ANS_SYNC_INTERVAL_HOURS` | Background verification sync interval | `6` |\n| `ans_verification_cache_ttl_seconds` | `ANS_VERIFICATION_CACHE_TTL_SECONDS` | Cache TTL for verification results | `3600` |\n\n### Environment File Example\n\n```bash\n# ANS Integration\nANS_INTEGRATION_ENABLED=true\nANS_API_ENDPOINT=https://api.godaddy.com\nANS_API_KEY=your-godaddy-api-key\nANS_API_SECRET=your-godaddy-api-secret\nANS_API_TIMEOUT_SECONDS=30\nANS_SYNC_INTERVAL_HOURS=6\n```\n\n### Terraform Configuration\n\nFor ECS deployments, set these in `terraform/aws-ecs/terraform.tfvars`:\n\n```hcl\nans_integration_enabled = true\nans_api_endpoint = \"https://api.godaddy.com\"\nans_api_key = \"your-api-key\"\nans_api_secret = \"your-api-secret\"\n```\n\n### System Configuration Page\n\nANS configuration is visible in the admin System Configuration page under the \"ANS Integration\" group. Navigate to the registry UI and open the system configuration panel to view and export current ANS settings.\n\n## API Endpoints\n\n### Agent ANS Endpoints\n\n#### Link ANS ID to Agent\n\nLinks an ANS Agent ID to a registered agent. The registry calls the ANS API to verify the identity and stores the metadata.\n\n```bash\nPOST /api/agents/{agent_path}/ans/link\nContent-Type: application/json\nAuthorization: Bearer \nX-CSRF-Token: \n\n{\n \"ans_agent_id\": \"ans://v1.0.0.myagent.example.com\"\n}\n```\n\n**Response (200):**\n```json\n{\n \"success\": true,\n \"message\": \"ANS identity linked and verified\",\n \"ans_metadata\": {\n \"ans_agent_id\": \"89a5061b-4f89-452b-9b66-dd9ca8baad7f\",\n \"status\": \"verified\",\n \"domain\": \"example.com\",\n \"organization\": \"Example Corp\",\n \"ans_name\": \"myagent.example.com\",\n \"ans_display_name\": \"My Agent\",\n \"certificate\": {\n \"not_before\": \"2025-01-01T00:00:00Z\",\n \"not_after\": \"2026-01-01T00:00:00Z\",\n \"subject_dn\": \"CN=myagent.example.com\",\n \"issuer_dn\": \"CN=ANS CA\"\n },\n \"endpoints\": [],\n \"linked_at\": \"2026-03-26T12:00:00Z\",\n \"last_verified\": \"2026-03-26T12:00:00Z\"\n }\n}\n```\n\n**Requirements:**\n- User must be authenticated\n- User must own the agent (`registered_by` field matches username)\n- Rate limited: 10 link operations per user per hour\n- CSRF token required\n\n#### Get ANS Status\n\n```bash\nGET /api/agents/{agent_path}/ans/status\nAuthorization: Bearer \n```\n\n**Response (200):** Returns full ANS metadata for the agent.\n**Response (404):** Agent has no ANS link.\n\n#### Unlink ANS from Agent\n\n```bash\nDELETE /api/agents/{agent_path}/ans/link\nAuthorization: Bearer \nX-CSRF-Token: \n```\n\n**Response (200):**\n```json\n{\n \"success\": true,\n \"message\": \"ANS identity unlinked\"\n}\n```\n\n### Server ANS Endpoints\n\nServers follow the same pattern as agents:\n\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | `/api/servers/{path}/ans/link` | Link ANS ID to server |\n| GET | `/api/servers/{path}/ans/status` | Get server ANS status |\n| DELETE | `/api/servers/{path}/ans/link` | Unlink ANS from server |\n\n### Admin Endpoints\n\n#### Trigger Manual Sync\n\nForces an immediate re-verification of all linked ANS identities.\n\n```bash\nPOST /api/admin/ans/sync\nAuthorization: Bearer \nX-CSRF-Token: \n```\n\n**Response (200):**\n```json\n{\n \"total\": 15,\n \"updated\": 12,\n \"errors\": 1,\n \"duration_seconds\": 4.2\n}\n```\n\n**Requires:** Admin group membership or `ans-admin/manage` scope.\n\n#### Get ANS Metrics\n\n```bash\nGET /api/admin/ans/metrics\nAuthorization: Bearer \n```\n\n**Response (200):**\n```json\n{\n \"total_linked\": 15,\n \"by_status\": {\n \"verified\": 12,\n \"expired\": 2,\n \"not_found\": 1\n },\n \"by_asset_type\": {\n \"agent\": 10,\n \"server\": 5\n },\n \"sync_history\": [\n {\n \"timestamp\": \"2026-03-26T06:00:00Z\",\n \"total\": 15,\n \"updated\": 2,\n \"errors\": 0,\n \"duration_seconds\": 3.8\n }\n ]\n}\n```\n\n#### Check ANS API Health\n\n```bash\nGET /api/admin/ans/health\nAuthorization: Bearer \n```\n\n**Response (200):**\n```json\n{\n \"status\": \"healthy\",\n \"api_reachable\": true,\n \"api_status_code\": 200\n}\n```\n\nPossible status values: `healthy`, `degraded`, `unhealthy`.\n\n## CLI Usage\n\nThe registry management CLI can be used to interact with ANS endpoints.\n\n### Link an Agent to ANS\n\n```bash\n# Using curl with token file\nTOKEN=$(cat .token)\nREGISTRY_URL=\"https://your-registry.example.com\"\n\n# Link ANS identity\ncurl -X POST \"${REGISTRY_URL}/api/agents/my-agent/ans/link\" \\\n -H \"Authorization: Bearer ${TOKEN}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ans_agent_id\": \"ans://v1.0.0.myagent.example.com\"}'\n```\n\n### Check ANS Status\n\n```bash\ncurl -s \"${REGISTRY_URL}/api/agents/my-agent/ans/status\" \\\n -H \"Authorization: Bearer ${TOKEN}\" | python -m json.tool\n```\n\n### Admin: Trigger Manual Sync\n\n```bash\ncurl -X POST \"${REGISTRY_URL}/api/admin/ans/sync\" \\\n -H \"Authorization: Bearer ${TOKEN}\"\n```\n\n### Admin: View Metrics\n\n```bash\ncurl -s \"${REGISTRY_URL}/api/admin/ans/metrics\" \\\n -H \"Authorization: Bearer ${TOKEN}\" | python -m json.tool\n```\n\n### Admin: Check API Health\n\n```bash\ncurl -s \"${REGISTRY_URL}/api/admin/ans/health\" \\\n -H \"Authorization: Bearer ${TOKEN}\" | python -m json.tool\n```\n\n### Verify Agent Has ANS Data\n\nList an agent and check the `ans_metadata` field:\n\n```bash\ncurl -s \"${REGISTRY_URL}/api/agents/my-agent\" \\\n -H \"Authorization: Bearer ${TOKEN}\" | python -m json.tool | grep -A 20 ans_metadata\n```\n\n## ANS Agent ID Format\n\nANS Agent IDs follow the URI format:\n\n```\nans://v1.0.0.agentname.domain.com\n```\n\nComponents:\n- `ans://` - Protocol scheme\n- `v1.0.0` - Version identifier\n- `agentname` - Agent name within the domain\n- `domain.com` - Verified domain\n\nThe registry also accepts raw UUIDs (e.g., `89a5061b-4f89-452b-9b66-dd9ca8baad7f`). When an `ans://` URI is provided, the client resolves it to a UUID by searching the ANS API.\n\n## Verification Status Values\n\n| Status | Meaning | Badge Color |\n|--------|---------|-------------|\n| `verified` | Agent identity is valid and certificate is current | Green |\n| `expired` | Certificate has passed its `notAfter` date | Yellow |\n| `revoked` | Agent or certificate has been explicitly revoked | Red |\n| `not_found` | ANS Agent ID no longer exists in ANS | Gray |\n| `pending` | Verification is in progress | Blue |\n\n## Architecture Components\n\n### Service Layer\n\n| File | Purpose |\n|------|---------|\n| `registry/services/ans_client.py` | Low-level HTTP client for GoDaddy ANS API |\n| `registry/services/ans_service.py` | Business logic for link/unlink/sync operations |\n| `registry/services/ans_sync_scheduler.py` | Background task that re-verifies all linked identities |\n\n### API Layer\n\n| File | Purpose |\n|------|---------|\n| `registry/api/ans_routes.py` | FastAPI router with all ANS endpoints |\n\n### Data Models\n\n| File | Purpose |\n|------|---------|\n| `registry/schemas/ans_models.py` | Pydantic models for ANS metadata, certificates, endpoints |\n| `registry/schemas/agent_models.py` | Agent model with `ans_metadata` field |\n| `registry/core/schemas.py` | Server model with `ans_metadata` field |\n\n### Frontend\n\n| File | Purpose |\n|------|---------|\n| `frontend/src/components/ANSBadge.tsx` | Badge component and certificate detail modal |\n| `frontend/src/components/AgentCard.tsx` | Displays ANS badge on agent cards |\n| `frontend/src/components/ServerCard.tsx` | Displays ANS badge on server cards |\n\n## Background Sync\n\nThe ANS sync scheduler runs as an async background task within the FastAPI application lifecycle.\n\n### How It Works\n\n1. On application startup, if `ans_integration_enabled=True`, the scheduler starts\n2. Every `ans_sync_interval_hours` (default 6), it runs `sync_all_ans_status()`\n3. The sync queries all agents and servers with non-null `ans_metadata`\n4. For each linked asset, it calls the ANS API to re-verify the identity\n5. Updates `ans_metadata.status` and `ans_metadata.last_verified` timestamp\n6. Stores sync results in memory (last 20 runs), viewable via admin metrics endpoint\n\n### Sync Lifecycle\n\n```\nApplication Start\n |\n v\n [ANS Enabled?] --No--> Skip\n |\n Yes\n v\n Start Scheduler Loop\n |\n v\n Sleep(sync_interval_hours)\n |\n v\n sync_all_ans_status()\n |\n +---> For each agent with ans_metadata:\n | verify_ans_agent(ans_agent_id)\n | Update status + last_verified\n |\n v\n Store sync stats\n |\n v\n Loop back to Sleep\n```\n\n## Resilience Features\n\n### Circuit Breaker\n\nThe ANS client implements a circuit breaker to prevent cascading failures when the ANS API is unavailable.\n\n| Parameter | Value |\n|-----------|-------|\n| Failure threshold | 5 consecutive failures |\n| Reset timeout | 3600 seconds (1 hour) |\n| Behavior when open | Returns `None` immediately without calling API |\n\n### Retry Logic\n\nEach ANS API call includes automatic retries:\n\n| Parameter | Value |\n|-----------|-------|\n| Max retries | 3 |\n| Backoff strategy | Exponential (1s, 2s, 4s) |\n| Timeout per request | `ans_api_timeout_seconds` (default 30s) |\n\n### Rate Limiting\n\nPer-user rate limiting on link operations prevents abuse:\n\n| Parameter | Value |\n|-----------|-------|\n| Max requests | 10 per user |\n| Window | 3600 seconds (1 hour) |\n\n## Authentication with ANS API\n\nThe registry authenticates with GoDaddy's ANS API using SSO-key authentication:\n\n```\nAuthorization: sso-key {ans_api_key}:{ans_api_secret}\n```\n\nThis is a GoDaddy-specific authentication scheme. API keys are obtained from the GoDaddy developer portal.\n\n### API Endpoints Used\n\n| Method | ANS API Path | Purpose |\n|--------|-------------|---------|\n| GET | `/v1/agents/{uuid}` | Fetch agent details and certificate info |\n| GET | `/v1/agents?name={name}` | Resolve `ans://` URI to UUID |\n\n## Data Storage\n\nANS metadata is stored as a `dict[str, Any]` field on both agent and server MongoDB documents. This allows schema evolution without database migrations.\n\n### MongoDB Field\n\n```json\n{\n \"path\": \"/my-agent\",\n \"name\": \"My Agent\",\n \"ans_metadata\": {\n \"ans_agent_id\": \"89a5061b-4f89-452b-9b66-dd9ca8baad7f\",\n \"status\": \"verified\",\n \"domain\": \"example.com\",\n \"organization\": \"Example Corp\",\n \"ans_name\": \"myagent.example.com\",\n \"certificate\": { ... },\n \"endpoints\": [ ... ],\n \"linked_at\": \"2026-03-26T12:00:00Z\",\n \"last_verified\": \"2026-03-26T12:00:00Z\"\n }\n}\n```\n\n### ANS Metadata in Agent and Server List APIs\n\nThe agent list (`GET /api/agents`) and server list (`GET /api/servers`) API responses now include `ans_metadata` for each entry. This is reflected in the OpenAPI spec (`openapi.json`). When an agent or server has a linked ANS identity, the full metadata object is returned inline, allowing API consumers to display trust information without making additional calls.\n\n```bash\n# List agents - each entry includes ans_metadata when linked\ncurl -s \"${REGISTRY_URL}/api/agents\" \\\n -H \"Authorization: Bearer ${TOKEN}\" | python -m json.tool\n```\n\nExample agent entry in the list response:\n\n```json\n{\n \"path\": \"/jewel-homes-support-agent\",\n \"name\": \"Jewel Homes Support Agent\",\n \"description\": \"Real estate support agent\",\n \"ans_metadata\": {\n \"ans_agent_id\": \"89a5061b-4f89-452b-9b66-dd9ca8baad7f\",\n \"status\": \"verified\",\n \"domain\": \"helpagent.club\",\n \"organization\": \"Jewel Homes\",\n \"last_verified\": \"2026-03-26T12:00:00Z\"\n }\n}\n```\n\nWhen no ANS identity is linked, `ans_metadata` is `null`.\n\n### ANS Trust Verified in Semantic Search Results\n\nThe semantic search API (`GET /api/search`) now returns a `trust_verified` boolean field in each result. This field is derived from `ans_metadata.status == \"verified\"` and provides a simple flag for consumers to identify agents with valid ANS verification without needing to parse the full metadata.\n\n```bash\n# Semantic search - results include trust_verified field\ncurl -s \"${REGISTRY_URL}/api/search?q=real+estate+support\" \\\n -H \"Authorization: Bearer ${TOKEN}\" | python -m json.tool\n```\n\nExample search result:\n\n```json\n{\n \"results\": [\n {\n \"path\": \"/jewel-homes-support-agent\",\n \"name\": \"Jewel Homes Support Agent\",\n \"description\": \"Real estate support agent\",\n \"score\": 0.92,\n \"trust_verified\": true\n },\n {\n \"path\": \"/generic-helper\",\n \"name\": \"Generic Helper\",\n \"description\": \"General purpose helper\",\n \"score\": 0.78,\n \"trust_verified\": false\n }\n ]\n}\n```\n\nThis allows search consumers to prioritize or filter results by trust status. Agents with `trust_verified: true` have a valid, non-expired, non-revoked ANS identity.\n\n## Linking During Agent Registration\n\nWhen registering a new agent, an optional `ans_agent_id` field can be included in the request body. If provided and ANS integration is enabled, the registry will attempt to link and verify the ANS identity as part of registration. This is a best-effort operation -- if ANS verification fails, the agent is still registered and can be linked later via the dedicated endpoint.\n\n```bash\ncurl -X POST \"${REGISTRY_URL}/api/agents\" \\\n -H \"Authorization: Bearer ${TOKEN}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My Agent\",\n \"path\": \"/my-agent\",\n \"description\": \"An example agent\",\n \"ans_agent_id\": \"ans://v1.0.0.myagent.example.com\"\n }'\n```\n\n## Route Ordering\n\nANS routes must be registered in `registry/main.py` **before** the agent router because the agent router contains a catch-all `{path:path}` route that would otherwise consume ANS-specific paths like `/agents/{path}/ans/status`.\n\n```python\n# In registry/main.py - order matters\napp.include_router(ans_router, prefix=\"/api\", tags=[\"ANS Integration\"]) # BEFORE agent_router\napp.include_router(agent_router, prefix=\"/api\", tags=[\"Agent Management\"]) # catch-all {path:path} here\n```\n\n## Troubleshooting\n\n### ANS Badge Not Showing\n\n1. **Check ANS is enabled:** Verify `ANS_INTEGRATION_ENABLED=true` in environment\n2. **Check API credentials:** Verify `ANS_API_KEY` and `ANS_API_SECRET` are set\n3. **Check route ordering:** ANS router must be registered before agent router in `main.py`\n4. **Check agent has metadata:** `GET /api/agents/{path}` should show `ans_metadata` field\n5. **Check API health:** `GET /api/admin/ans/health` should return `healthy`\n\n### ANS API Returning Errors\n\n1. **Check circuit breaker:** If 5+ consecutive failures, circuit opens for 1 hour\n2. **Check API endpoint:** Verify `ANS_API_ENDPOINT` points to correct URL\n3. **Check credentials:** Test with `GET /api/admin/ans/health`\n4. **Check timeout:** Increase `ANS_API_TIMEOUT_SECONDS` if requests are timing out\n\n### Verification Status Stuck on \"pending\"\n\nThis typically means the initial verification call failed or timed out. Try:\n\n1. Unlink: `DELETE /api/agents/{path}/ans/link`\n2. Re-link: `POST /api/agents/{path}/ans/link` with the ANS Agent ID\n3. Or trigger manual sync: `POST /api/admin/ans/sync`\n\n### Security Scan Routes Returning 404\n\nSimilar to ANS routes, security scan routes (`/agents/{path}/security-scan`) must be defined before the catch-all `{path:path}` route in `agent_routes.py`. If these return 404, check route ordering.\n" }, { "path": "docs/design/anthropic-api-implementation.md", "content": "# Anthropic MCP Registry API - Implementation Guide\n\n> **Note**: The Anthropic API version (v0.1) is defined as a constant `ANTHROPIC_API_VERSION` in `registry/constants.py`. All code references this constant rather than hardcoding the version string.\n\n---\n\n## Overview\n\nThis implementation provides full compatibility with the [Anthropic MCP Registry REST API v0.1 specification](https://github.com/modelcontextprotocol/registry), enabling seamless integration with MCP ecosystem tools and downstream applications.\n\n### Key Features\n\n- ✅ **3 REST API endpoints** for server discovery\n- ✅ **JWT Bearer token authentication** via Keycloak\n- ✅ **Cursor-based pagination** for server lists\n- ✅ **Permission-based filtering** using MCP scopes\n- ✅ **Complete Pydantic models** matching Anthropic spec\n- ✅ **Automatic data transformation** from internal format\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Client (Authorization: Bearer ) │\n└────────────────────┬────────────────────────────────────────┘\n │ HTTP Request\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Nginx (:80/:443) │\n│ └─ /v0.1/* location │\n│ └─ auth_request /validate ────────────────┐ │\n└────────────────────┬───────────────────────────┼────────────┘\n │ │\n │ ▼\n │ ┌─────────────────────────┐\n │ │ Auth Server (:8888) │\n │ │ - Validates JWT │\n │ │ - Checks Keycloak │\n │ │ - Returns headers │\n │ └─────────────┬───────────┘\n │ │\n │ ◄──────────────────────────┘\n │ X-User, X-Scopes, X-Username\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Registry FastAPI (:7860) │\n│ ├─ nginx_proxied_auth() - Reads headers │\n│ ├─ registry_routes.py - API endpoints │\n│ ├─ server_service - Data access │\n│ └─ transform_service - Format conversion │\n└────────────────────┬────────────────────────────────────────┘\n │\n ▼\n Anthropic Schema Response\n```\n\n---\n\n## File Structure\n\n### New Files\n\n| File | Purpose |\n|------|---------|\n| `registry/constants.py` | Anthropic API constants (`ANTHROPIC_SERVER_NAMESPACE`, limits) |\n| `registry/schemas/anthropic_schema.py` | 9 Pydantic models for Anthropic spec |\n| `registry/services/transform_service.py` | Data transformation between formats |\n| `registry/api/registry_routes.py` | 3 REST endpoints with JWT auth |\n| `tests/unit/api/test_registry_routes.py` | API endpoint tests |\n| `tests/unit/services/test_transform_service.py` | Transformation tests |\n| `docs/design/anthropic-api-test-commands.md` | 20 test scenarios with curl |\n\n### Modified Files\n\n| File | Changes |\n|------|---------|\n| `registry/main.py` | Registered v0.1 router |\n| `registry/auth/dependencies.py` | Added `nginx_proxied_auth()` function |\n| `docker/nginx_rev_proxy_*.conf` | Added `/v0.1/` location with auth validation |\n| `.gitignore` | Added `tests/reports/` |\n\n---\n\n## Constants Configuration\n\nAll hardcoded values are centralized in `registry/constants.py`:\n\n```python\nclass RegistryConstants(BaseModel):\n # Anthropic Registry API v0.1 constants\n ANTHROPIC_SERVER_NAMESPACE: str = \"io.mcpgateway\"\n ANTHROPIC_API_DEFAULT_LIMIT: int = 100\n ANTHROPIC_API_MAX_LIMIT: int = 1000\n```\n\n**Usage**: Import with `from ..constants import REGISTRY_CONSTANTS`\n\n---\n\n## API Endpoints\n\n### 1. List Servers\n\n```\nGET /v0.1/servers?cursor={cursor}&limit={limit}\n```\n\n**Purpose**: List all MCP servers the authenticated user can access.\n\n**Query Parameters**:\n- `cursor` (optional): Pagination cursor from previous response\n- `limit` (optional): Results per page (1-1000, default 100)\n\n**Response**: `ServerList` with pagination metadata\n\n**Example**:\n```bash\ncurl \"http://localhost/v0.1/servers?limit=5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### 2. List Server Versions\n\n```\nGET /v0.1/servers/{serverName:path}/versions\n```\n\n**Purpose**: List all available versions for a specific server.\n\n**URL Parameters**:\n- `serverName`: URL-encoded name (e.g., `io.mcpgateway%2Ffininfo`)\n\n**Response**: `ServerList` (currently single version per server)\n\n**Important**: Note `:path` route converter to handle `/` in server names.\n\n**Example**:\n```bash\ncurl \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### 3. Get Server Version Details\n\n```\nGET /v0.1/servers/{serverName:path}/versions/{version}\n```\n\n**Purpose**: Get detailed information for a specific server version.\n\n**URL Parameters**:\n- `serverName`: URL-encoded name (e.g., `io.mcpgateway%2Ffininfo`)\n- `version`: Version string (use `latest` for current version)\n\n**Response**: `ServerResponse` with full server details\n\n**Example**:\n```bash\ncurl \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions/latest\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n---\n\n## Authentication Flow\n\n### 1. JWT Bearer Token Validation\n\n**Client → Nginx**:\n```\nGET /v0.1/servers\nAuthorization: Bearer eyJhbGci...\n```\n\n**Nginx → Auth Server** (`/validate` endpoint):\n```\nGET /validate\nX-Authorization: Bearer eyJhbGci...\nX-Original-URL: http://localhost/v0.1/servers\n```\n\n**Auth Server Processing**:\n1. Validates JWT signature using Keycloak JWKS\n2. Checks expiration, issuer (3-tier validation), audience\n - Tries external URL: `https://mcpgateway.ddns.net/realms/mcp-gateway`\n - Tries internal URL: `http://keycloak:8080/realms/mcp-gateway`\n - Tries localhost URL: `http://localhost:8080/realms/mcp-gateway`\n3. Extracts user info: `preferred_username`, `groups`, `scope`\n4. Maps Keycloak groups to MCP scopes\n\n**Auth Server → Nginx** (response headers):\n```\nX-User: service-account-mcp-gateway-m2m\nX-Username: service-account-mcp-gateway-m2m\nX-Scopes: mcp-servers-unrestricted/read mcp-servers-unrestricted/execute\nX-Auth-Method: keycloak\n```\n\n**Nginx → FastAPI**:\n```\nGET /v0.1/servers\nX-User: service-account-mcp-gateway-m2m\nX-Scopes: mcp-servers-unrestricted/read mcp-servers-unrestricted/execute\nAuthorization: Bearer eyJhbGci...\n```\n\n### 2. nginx Configuration\n\n**Critical Setup** in `/v0.1/` location block:\n\n```nginx\nlocation /v0.1/ {\n # Authenticate via auth-server\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n\n # Forward to FastAPI with auth context\n proxy_pass http://127.0.0.1:7860/v0.1/;\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header Authorization $http_authorization;\n}\n```\n\n**Key Fix**: `/validate` endpoint must forward `Authorization` as `X-Authorization`:\n```nginx\nlocation = /validate {\n proxy_pass http://auth-server:8888/validate;\n # CRITICAL: Read from $http_authorization (client's Authorization header)\n proxy_set_header X-Authorization $http_authorization;\n}\n```\n\n### 3. FastAPI Authentication Dependency\n\n**Function**: `nginx_proxied_auth()` in `registry/auth/dependencies.py`\n\n**Supports Two Modes**:\n1. **JWT Flow** (primary): Reads nginx headers from auth validation\n2. **Cookie Flow** (fallback): Reads session cookies for backward compatibility\n\n```python\ndef nginx_proxied_auth(\n request: Request,\n session: Cookie = None,\n x_user: Header = None,\n x_username: Header = None,\n x_scopes: Header = None,\n x_auth_method: Header = None,\n) -> Dict[str, Any]:\n # Try nginx headers first (JWT Bearer token)\n if x_user or x_username:\n username = x_username or x_user\n scopes = x_scopes.split() if x_scopes else []\n\n # Map scopes to groups\n if 'mcp-servers-unrestricted/read' in scopes:\n groups = ['mcp-registry-admin']\n else:\n groups = ['mcp-registry-user']\n\n # Get accessible servers from scopes\n accessible_servers = get_user_accessible_servers(scopes)\n\n return {\n 'username': username,\n 'groups': groups,\n 'scopes': scopes,\n 'accessible_servers': accessible_servers,\n 'is_admin': 'mcp-registry-admin' in groups,\n # ... more fields\n }\n\n # Fallback to session cookie\n return enhanced_auth(session)\n```\n\n---\n\n## Permission Checks\n\n### Scope-Based Access Control\n\n**IMPORTANT**: v0.1 API uses `accessible_servers` (MCP scopes), NOT `accessible_services` (UI scopes).\n\n```python\n# CORRECT - Check against accessible_servers\naccessible_servers = user_context.get(\"accessible_servers\", [])\nif server_name not in accessible_servers:\n raise HTTPException(404, \"Server not found\")\n```\n\n**Why**:\n- `accessible_services` = UI-level services (\"auth_server\", \"mcpgw\")\n- `accessible_servers` = MCP server names (\"fininfo\", \"currenttime\")\n- M2M tokens have MCP scopes but no UI scopes\n\n### User Context Structure\n\n```python\n{\n \"username\": \"service-account-mcp-gateway-m2m\",\n \"groups\": [\"mcp-registry-admin\"],\n \"scopes\": [\n \"mcp-servers-unrestricted/read\",\n \"mcp-servers-unrestricted/execute\",\n \"mcp-servers-restricted/read\",\n \"mcp-servers-restricted/execute\"\n ],\n \"auth_method\": \"keycloak\",\n \"provider\": \"keycloak\",\n \"accessible_servers\": [\n \"currenttime\", \"fininfo\",\n \"mcpgw\", \"realserverfaketools\", \"sre-gateway\"\n ],\n \"accessible_services\": [], # Empty for M2M tokens\n \"is_admin\": True,\n \"can_modify_servers\": False\n}\n```\n\n---\n\n## Data Transformation\n\n### Namespace Convention\n\n**Internal Format**: `/fininfo`, `/currenttime/`\n**Anthropic Format**: `io.mcpgateway/fininfo`, `io.mcpgateway/currenttime`\n\n**Implementation** (`transform_service.py`):\n\n```python\ndef _create_server_name(server_info: Dict[str, Any]) -> str:\n path = server_info.get(\"path\", \"\")\n clean_path = path.strip(\"/\")\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n return f\"{namespace}/{clean_path}\"\n```\n\n### Server Detail Transformation\n\n```python\ndef transform_to_server_detail(server_info: Dict[str, Any]) -> ServerDetail:\n # Create Anthropic-format name\n name = _create_server_name(server_info)\n\n # Build package with transport config\n transport = _create_transport_config(server_info)\n package = Package(\n registryType=\"mcpb\",\n identifier=name,\n version=\"1.0.0\",\n transport=transport,\n runtimeHint=\"docker\"\n )\n\n # Add internal metadata\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n meta = {\n f\"{namespace}/internal\": {\n \"path\": server_info.get(\"path\"),\n \"is_enabled\": server_info.get(\"is_enabled\"),\n \"health_status\": server_info.get(\"health_status\"),\n \"num_tools\": server_info.get(\"num_tools\"),\n \"tags\": server_info.get(\"tags\", []),\n \"license\": server_info.get(\"license\", \"N/A\")\n }\n }\n\n return ServerDetail(name=name, packages=[package], meta=meta, ...)\n```\n\n### Response Structure\n\n```json\n{\n \"server\": {\n \"name\": \"io.mcpgateway/fininfo\",\n \"description\": \"Financial Information\",\n \"version\": \"1.0.0\",\n \"title\": \"Financial Info\",\n \"packages\": [\n {\n \"registryType\": \"mcpb\",\n \"identifier\": \"io.mcpgateway/fininfo\",\n \"version\": \"1.0.0\",\n \"transport\": {\n \"type\": \"streamable-http\",\n \"url\": \"http://fininfo-server:8001/mcp/\"\n },\n \"runtimeHint\": \"docker\"\n }\n ],\n \"_meta\": {\n \"io.mcpgateway/internal\": {\n \"path\": \"/fininfo\",\n \"is_enabled\": true,\n \"health_status\": \"healthy\",\n \"num_tools\": 5,\n \"tags\": [\"Finance\", \"Stocks\", \"Market\"],\n \"license\": \"MIT\"\n }\n }\n },\n \"_meta\": {\n \"io.mcpgateway/registry\": {\n \"last_checked\": \"2025-10-12T19:25:09.378358+00:00\",\n \"health_status\": \"healthy\"\n }\n }\n}\n```\n\n---\n\n## Pagination\n\n### Cursor-Based Implementation\n\n**Algorithm** (`transform_service.py`):\n\n```python\ndef transform_to_server_list(\n servers_data: List[Dict[str, Any]],\n cursor: Optional[str] = None,\n limit: Optional[int] = None\n) -> ServerList:\n # Apply defaults\n limit = limit or REGISTRY_CONSTANTS.ANTHROPIC_API_DEFAULT_LIMIT\n limit = min(limit, REGISTRY_CONSTANTS.ANTHROPIC_API_MAX_LIMIT)\n\n # Sort alphabetically for consistency\n sorted_servers = sorted(servers_data, key=lambda s: _create_server_name(s))\n\n # Find cursor position\n start_index = 0\n if cursor:\n for idx, server in enumerate(sorted_servers):\n if _create_server_name(server) == cursor:\n start_index = idx + 1\n break\n\n # Slice page\n end_index = start_index + limit\n page_servers = sorted_servers[start_index:end_index]\n\n # Determine next cursor\n has_more = end_index < len(sorted_servers)\n next_cursor = _create_server_name(sorted_servers[end_index - 1]) if has_more else None\n\n # Transform and return\n return ServerList(\n servers=[transform_to_server_response(s) for s in page_servers],\n metadata=PaginationMetadata(nextCursor=next_cursor, count=len(page_servers))\n )\n```\n\n**Example Flow**:\n```\nPage 1: GET /v0.1/servers?limit=3\n← Returns: servers A, B, C with nextCursor=\"C\"\n\nPage 2: GET /v0.1/servers?cursor=C&limit=3\n← Returns: servers D, E, F with nextCursor=\"F\"\n\nPage 3: GET /v0.1/servers?cursor=F&limit=3\n← Returns: servers G, H with nextCursor=null (end)\n```\n\n---\n\n## Critical Implementation Details\n\n### 1. Route Path Parameters\n\n**Problem**: Server names contain `/` which breaks FastAPI routing.\n\n**Solution**: Use `:path` converter in route definition.\n\n```python\n# WRONG - Returns 404 for io.mcpgateway/fininfo\n@router.get(\"/servers/{serverName}/versions\")\n\n# CORRECT - Captures full path including /\n@router.get(\"/servers/{serverName:path}/versions\")\n```\n\n**Why**: FastAPI URL-decodes before routing. `io.mcpgateway%2Ffininfo` becomes `io.mcpgateway/fininfo`, which looks like extra path segments without `:path`.\n\n### 2. Trailing Slash Handling\n\n**Problem**: Some servers have trailing slashes (`/currenttime/`), some don't (`/fininfo`).\n\n**Solution**: Try both forms when looking up servers.\n\n```python\n# Construct path from server name\nlookup_path = \"/\" + decoded_name.replace(expected_prefix, \"\")\n\n# Try with and without trailing slash\nserver_info = server_service.get_server_info(lookup_path)\nif not server_info:\n server_info = server_service.get_server_info(lookup_path + \"/\")\n\n# Use actual path from server_info for health checks\npath = server_info.get(\"path\", lookup_path) # Has correct trailing slash\nhealth_data = health_service._get_service_health_data(path)\n```\n\n**Why**: Health data is indexed by exact path. Wrong path returns `\"unknown\"` status.\n\n### 3. Namespace Constant Usage\n\n**All occurrences** of hardcoded `\"io.mcpgateway\"` replaced with constant:\n\n```python\nfrom ..constants import REGISTRY_CONSTANTS\n\nnamespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\nexpected_prefix = f\"{namespace}/\" # \"io.mcpgateway/\"\n```\n\n**Files using constant**:\n- `registry/api/registry_routes.py` - Validates server name format\n- `registry/services/transform_service.py` - Creates names and metadata keys\n\n---\n\n## Testing\n\n### Generate Token\n\n```bash\n# Generate fresh credentials (tokens expire after 5 minutes)\n./generate_creds.sh\n\n# Load token\nexport TOKEN=$(jq -r '.access_token' .oauth-tokens/ingress.json)\n\n# Verify token loaded\necho \"Token: ${TOKEN:0:50}...\"\n```\n\n### Test Endpoints\n\n```bash\n# 1. List servers with pagination\ncurl \"http://localhost/v0.1/servers?limit=5\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq\n\n# 2. List versions for a server (note %2F = /)\ncurl \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq\n\n# 3. Get specific version details\ncurl \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions/latest\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq\n\n# 4. Test pagination\ncurl \"http://localhost/v0.1/servers?limit=2\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.metadata'\n# Get nextCursor and use it:\ncurl \"http://localhost/v0.1/servers?cursor=io.mcpgateway%2Fcurrenttime&limit=2\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq\n```\n\n### Comprehensive Test Suite\n\nSee [docs/design/anthropic-api-test-commands.md](anthropic-api-test-commands.md) for 20 test scenarios.\n\n---\n\n## Common Issues & Solutions\n\n### Issue: 404 on versions endpoint\n\n**Symptom**: `GET /v0.1/servers/io.mcpgateway%2Ffininfo/versions` returns 404\n\n**Cause**: Missing `:path` in route parameter\n\n**Solution**: Ensure route uses `{serverName:path}` not `{serverName}`\n\n### Issue: Health data shows \"unknown\"\n\n**Symptom**: `health_status: \"unknown\"`, `last_checked: null`\n\n**Cause**: Trailing slash mismatch in path lookup\n\n**Solution**: Use `server_info.get(\"path\")` for health checks, not constructed path\n\n### Issue: Empty server list\n\n**Symptom**: `{\"servers\": [], \"metadata\": {\"count\": 0}}`\n\n**Cause**: Checking `accessible_services` instead of `accessible_servers`\n\n**Solution**: Use `user_context[\"accessible_servers\"]` for permission checks\n\n### Issue: 401 Unauthorized\n\n**Symptom**: `{\"detail\": \"Token has expired\"}`\n\n**Cause**: JWT token expired (5 minute lifetime)\n\n**Solution**: Run `./generate_creds.sh` to get fresh token\n\n### Issue: Token not forwarded\n\n**Symptom**: Auth server logs show `Authorization=False`\n\n**Cause**: nginx using `$http_x_authorization` instead of `$http_authorization`\n\n**Solution**: Update `/validate` location to use `$http_authorization`\n\n---\n\n## Schema Compliance\n\n**OpenAPI Spec**: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/openapi.yaml\n\n**Pydantic Models** (`registry/schemas/anthropic_schema.py`):\n- ✅ `ServerList` - Paginated server list\n- ✅ `ServerResponse` - Single server with metadata\n- ✅ `ServerDetail` - Complete server information\n- ✅ `Package` - Distribution package details\n- ✅ `Transport` - Union of transport types\n- ✅ `Repository` - Source code repository info\n- ✅ `PaginationMetadata` - Cursor and count\n- ✅ `ErrorResponse` - Error details\n\n**Field Aliases**: Pydantic handles `_meta` fields with `Field(alias=\"_meta\")`\n\n---\n\n## Next Steps\n\n1. ✅ **JWT Authentication** - Fully implemented\n2. ✅ **Permission Filtering** - Uses MCP scopes\n3. ✅ **Health Data** - Includes status and last checked\n4. ✅ **Pagination** - Cursor-based with configurable limits\n5. 🔄 **Read-Only API Access** - Optional: Create dedicated M2M client with minimal scopes (see `.scratchpad/registry-api-readonly-access.md`)\n6. 🔄 **Rate Limiting** - Future: Add per-client rate limits\n7. 🔄 **Caching** - Future: Cache server list responses\n\n---\n\n## References\n\n- **Issue**: [#175 - Support Anthropic MCP Registry REST API v0](https://github.com/agentic-community/mcp-gateway-registry/issues/175)\n- **OpenAPI Spec**: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/openapi.yaml\n- **API Guide**: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/consuming/use-rest-api.md\n- **Test Commands**: [anthropic-api-test-commands.md](anthropic-api-test-commands.md)\n- **Progress Notes**: [.scratchpad/anthropic-api-v0-jwt-auth-progress.md](../../.scratchpad/anthropic-api-v0-jwt-auth-progress.md)\n" }, { "path": "docs/design/anthropic-api-test-commands.md", "content": "# Anthropic Registry API Test Commands\n\n> **Note**: The Anthropic API version is defined in `registry/constants.py` as `ANTHROPIC_API_VERSION` for easy version management.\n\n## Overview\n\nThis document provides comprehensive curl commands to test all three endpoints of the Anthropic Registry API v0.1 implementation:\n\n1. `GET /v0.1/servers` - List all MCP servers with pagination\n2. `GET /v0.1/servers/{serverName}/versions` - List versions for a specific server\n3. `GET /v0.1/servers/{serverName}/versions/{version}` - Get detailed info for a specific version\n\n## Prerequisites\n\n### 1. Start the MCP Gateway Registry\n\n```bash\n# Build and start all services\n./build_and_run.sh\n\n# Wait for services to be ready (check logs)\ndocker compose logs -f registry\n```\n\n### 2. Authentication Setup\n\nThe v0.1 API requires JWT authentication via Keycloak.\n\n**Generate Fresh Token (Required)**\n\nThe ingress token expires regularly, so you must generate a new one before testing:\n\n```bash\n# Step 1: Generate fresh Keycloak credentials\ncredentials-provider/generate_creds.sh\n\n# Step 2: Load the token from ingress.json\nexport TOKEN=$(jq -r '.access_token' .oauth-tokens/ingress.json)\n\n# Step 3: Verify token was loaded\necho \"Token loaded: ${TOKEN:0:50}...\"\n```\n\n**Important Notes**:\n- Tokens expire after 5 minutes - if you get authentication errors, regenerate with `./credentials-provider/generate_creds.sh`\n- The `generate_creds.sh` script creates a new M2M token in `.oauth-tokens/ingress.json`\n- This token has full access to all MCP servers (unrestricted + restricted scopes)\n- **Other bot tokens** (like `bot-008`, `agent-finance-bot`) may have limited or no access to MCP servers depending on their Keycloak configuration. Use `ingress.json` for testing.\n\n### 3. Base URL\n\nThe v0.1 API is accessible at:\n\n- **API Endpoint**: `http://localhost/v0.1` or `https://localhost/v0.1`\n\n**Authentication**: All endpoints require JWT Bearer token authentication via the `Authorization` header.\n\n## Test Commands\n\n### Test 1: List All Servers (Basic)\n\n**Description**: Get the first page of servers with default pagination (100 items)\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"servers\": [\n {\n \"server\": {\n \"name\": \"io.mcpgateway/fininfo\",\n \"description\": \"...\",\n \"version\": \"1.0.0\",\n \"title\": \"Financial Info Server\",\n \"packages\": [...],\n \"_meta\": {...}\n },\n \"_meta\": {...}\n },\n ...\n ],\n \"metadata\": {\n \"nextCursor\": \"io.mcpgateway/some-server\",\n \"count\": 100\n }\n}\n```\n\n### Test 2: List Servers with Limit\n\n**Description**: Get first 5 servers only\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers?limit=5\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**: ServerList with 5 items and pagination metadata\n\n### Test 3: List Servers with Pagination\n\n**Description**: Get the next page using cursor from previous response\n\n```bash\n# First, get the first page and extract the cursor\nCURSOR=$(curl -s -X GET \"http://localhost/v0.1/servers?limit=5\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq -r '.metadata.nextCursor')\n\n# Then fetch the next page\ncurl -X GET \"http://localhost/v0.1/servers?cursor=$CURSOR&limit=5\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**: ServerList starting after the cursor position\n\n### Test 4: List Servers with Maximum Limit\n\n**Description**: Test the maximum limit (1000 items)\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers?limit=1000\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**: ServerList with up to 1000 items\n\n### Test 5: List Server Versions\n\n**Description**: Get all versions for the Financial Info server\n\n```bash\n# Note: Server name must be URL-encoded\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"servers\": [\n {\n \"server\": {\n \"name\": \"io.mcpgateway/fininfo\",\n \"description\": \"...\",\n \"version\": \"1.0.0\",\n ...\n },\n \"_meta\": {...}\n }\n ],\n \"metadata\": {\n \"nextCursor\": null,\n \"count\": 1\n }\n}\n```\n\n### Test 6: List Versions for Different Server\n\n**Description**: Try with a different server (e.g., currenttime)\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Fcurrenttime/versions\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n### Test 7: Get Specific Version (latest)\n\n**Description**: Get detailed information for the latest version of Financial Info server\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions/latest\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"server\": {\n \"name\": \"io.mcpgateway/fininfo\",\n \"description\": \"...\",\n \"version\": \"1.0.0\",\n \"title\": \"Financial Info Server\",\n \"repository\": null,\n \"websiteUrl\": null,\n \"packages\": [\n {\n \"registryType\": \"mcpb\",\n \"identifier\": \"io.mcpgateway/fininfo\",\n \"version\": \"1.0.0\",\n \"transport\": {\n \"type\": \"streamable-http\",\n \"url\": \"http://fininfo:8001\"\n },\n \"runtimeHint\": \"docker\"\n }\n ],\n \"_meta\": {\n \"io.mcpgateway/internal\": {\n \"path\": \"/fininfo\",\n \"is_enabled\": true,\n \"health_status\": \"healthy\",\n \"num_tools\": 5,\n \"tags\": [\"fininfo\", \"jira\", \"confluence\"],\n \"license\": \"MIT\"\n }\n }\n },\n \"_meta\": {\n \"io.mcpgateway/registry\": {\n \"last_checked\": \"2025-10-12T18:00:00Z\",\n \"health_status\": \"healthy\"\n }\n }\n}\n```\n\n### Test 8: Get Specific Version (1.0.0)\n\n**Description**: Get detailed information using explicit version number\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions/1.0.0\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**: Same as Test 7 (we only support version 1.0.0 currently)\n\n### Test 9: Invalid Version\n\n**Description**: Try to access a non-existent version\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions/2.0.0\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"detail\": \"Version 2.0.0 not found\"\n}\n```\n\n**Expected Status Code**: 404\n\n### Test 10: Non-existent Server\n\n**Description**: Try to access a server that doesn't exist\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Fnon-existent/versions\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"detail\": \"Server not found\"\n}\n```\n\n**Expected Status Code**: 404\n\n### Test 11: Invalid Server Name Format\n\n**Description**: Try to access a server with wrong namespace\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers/com.example%2Fserver/versions\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"detail\": \"Server not found\"\n}\n```\n\n**Expected Status Code**: 404\n\n### Test 12: Unauthorized Access\n\n**Description**: Try to access API without authentication\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"detail\": \"Not authenticated\"\n}\n```\n\n**Expected Status Code**: 401\n\n### Test 13: Invalid Token\n\n**Description**: Try to access API with invalid token\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers\" \\\n -H \"Authorization: Bearer invalid_token_here\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**:\n```json\n{\n \"detail\": \"Could not validate credentials\"\n}\n```\n\n**Expected Status Code**: 401\n\n### Test 14: Permission-based Filtering (Non-admin User)\n\n**Description**: Test that non-admin users only see servers they have access to\n\nFirst, create a test user with limited permissions via the auth service, then:\n\n```bash\n# Get token for non-admin user\nexport USER_TOKEN=$(curl -s -X POST http://localhost:8888/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=testuser&password=testpass\" | jq -r '.access_token')\n\n# List servers as non-admin user\ncurl -X GET \"http://localhost/v0.1/servers\" \\\n -H \"Authorization: Bearer $USER_TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**: Only servers the user has access to (based on scopes.yml configuration)\n\n### Test 15: Via Nginx Proxy (Production Path)\n\n**Description**: Test the API through Nginx reverse proxy\n\n```bash\ncurl -X GET \"http://localhost/v0.1/servers?limit=5\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq\n```\n\n**Expected Response**: Same as Test 2, but routed through Nginx\n\n### Test 16: Verbose Output with Headers\n\n**Description**: See full HTTP response including headers\n\n```bash\ncurl -v -X GET \"http://localhost/v0.1/servers?limit=5\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" 2>&1 | grep -E \"(< HTTP|< Content-Type|< X-)\"\n```\n\n**Expected Headers**:\n- `HTTP/1.1 200 OK`\n- `Content-Type: application/json`\n\n### Test 17: Test All Registered Servers\n\n**Description**: Iterate through all servers and test version endpoint for each\n\n```bash\n# Get list of all servers\nSERVERS=$(curl -s -X GET \"http://localhost/v0.1/servers?limit=100\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq -r '.servers[].server.name')\n\n# Test each server\nfor server in $SERVERS; do\n echo \"Testing server: $server\"\n encoded_name=$(echo \"$server\" | sed 's/\\//%2F/g')\n curl -s -X GET \"http://localhost/v0.1/servers/$encoded_name/versions/latest\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq -c '{name: .server.name, version: .server.version, status: \"ok\"}'\ndone\n```\n\n### Test 18: Performance Test - Large Pagination\n\n**Description**: Test pagination performance with large result sets\n\n```bash\n# Time the request\ntime curl -s -X GET \"http://localhost/v0.1/servers?limit=500\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" | jq '.metadata.count'\n```\n\n**Expected**: Response should complete in < 2 seconds\n\n### Test 19: Concurrent Requests\n\n**Description**: Test API under concurrent load\n\n```bash\n# Run 10 concurrent requests\nfor i in {1..10}; do\n curl -s -X GET \"http://localhost/v0.1/servers?limit=10\" \\\n -H \"Authorization: Bearer $TOKEN\" &\ndone\nwait\necho \"All concurrent requests completed\"\n```\n\n### Test 20: Pretty Print Server Details\n\n**Description**: Get nicely formatted output for a specific server\n\n```bash\ncurl -s -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Ffininfo/versions/latest\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq '{\n name: .server.name,\n title: .server.title,\n description: .server.description,\n version: .server.version,\n transport_url: .server.packages[0].transport.url,\n num_tools: .server._meta.\"io.mcpgateway/internal\".num_tools,\n health: ._meta.\"io.mcpgateway/registry\".health_status\n }'\n```\n\n### Test 21: Permission-Based Filtering (Restricted vs Full Access)\n\n**Description**: Verify that users with restricted permissions only see authorized servers\n\n**Setup**: Create restricted bot account if it doesn't exist\n```bash\n# Check if test-restricted-bot already exists\nif [ ! -f .oauth-tokens/test-restricted-bot.json ]; then\n echo \"Creating test-restricted-bot...\"\n\n # Load Keycloak admin password from .env\n export $(grep KEYCLOAK_ADMIN_PASSWORD .env | xargs)\n\n # Create restricted bot (only has access to restricted servers)\n ./cli/user_mgmt.sh create-m2m \\\n --name test-restricted-bot \\\n --groups 'mcp-servers-restricted'\nelse\n echo \"test-restricted-bot already exists, skipping creation\"\nfi\n```\n\n**Test Commands**:\n```bash\n# Step 1: Refresh the restricted bot's token\n./scripts/refresh_m2m_token.sh test-restricted-bot\n\n# Step 2: Load the restricted bot's token\nexport TOKEN_RESTRICTED=$(jq -r '.access_token' .oauth-tokens/test-restricted-bot-token.json)\n\n# Step 3: Test v0.1 API with restricted token - should see only ~3 servers\necho \"=== Testing with RESTRICTED token ===\"\ncurl -s \"http://localhost/v0.1/servers\" \\\n -H \"Authorization: Bearer $TOKEN_RESTRICTED\" | jq '{\n total_servers: (.servers | length),\n server_names: [.servers[].server.name]\n }'\n\n# Step 4: Load the full access token for comparison\nexport TOKEN_FULL=$(jq -r '.access_token' .oauth-tokens/ingress.json)\n\n# Step 5: Test v0.1 API with full access token - should see all servers\necho \"\"\necho \"=== Testing with FULL ACCESS token ===\"\ncurl -s \"http://localhost/v0.1/servers\" \\\n -H \"Authorization: Bearer $TOKEN_FULL\" | jq '{\n total_servers: (.servers | length),\n server_names: [.servers[].server.name]\n }'\n\n# Step 6: Compare the difference\necho \"\"\necho \"=== COMPARISON ===\"\necho \"Restricted bot sees: $(curl -s \"http://localhost/v0.1/servers\" -H \"Authorization: Bearer $TOKEN_RESTRICTED\" | jq '.servers | length') servers\"\necho \"Full access sees: $(curl -s \"http://localhost/v0.1/servers\" -H \"Authorization: Bearer $TOKEN_FULL\" | jq '.servers | length') servers\"\n```\n\n**Expected Results**:\n- **Restricted bot** (`mcp-servers-restricted` group): ~3 servers (currenttime, auth_server, mcpgw)\n- **Full access** (`ingress.json` token): ~7+ servers (all servers including fininfo, fininfo, sre-gateway)\n\nThis demonstrates that the v0.1 API correctly enforces permission-based filtering based on Keycloak groups and MCP scopes!\n\n---\n\n## Verification Checklist\n\nAfter running the tests, verify:\n\n- [ ] All successful requests return 200 status code\n- [ ] Pagination works correctly (cursor-based)\n- [ ] Server name format follows `io.mcpgateway/{path}` convention\n- [ ] All responses conform to Anthropic schema\n- [ ] Authentication is required for all endpoints\n- [ ] Non-admin users only see authorized servers (Test 21)\n- [ ] Restricted users see only restricted servers (Test 21)\n- [ ] Error responses include proper status codes (404, 401)\n- [ ] Version \"latest\" and \"1.0.0\" both work\n- [ ] Transport configuration includes correct proxy URLs\n- [ ] Metadata includes health status and internal info\n- [ ] URL encoding works for server names with special characters\n\n## Schema Validation\n\nTo validate responses against the Anthropic OpenAPI specification:\n\n```bash\n# Download the official OpenAPI spec\ncurl -o /tmp/anthropic-openapi.yaml \\\n https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/api/openapi.yaml\n\n# Use a tool like openapi-spec-validator or similar\n# (Requires installation: pip install openapi-spec-validator)\n```\n\n## Common Issues\n\n### Issue 1: Token Expired\n\n**Symptom**: 401 Unauthorized or \"Token has expired\" error\n\n**Solution**: Generate fresh credentials and reload token\n```bash\n# Step 1: Generate new token\n./generate_creds.sh\n\n# Step 2: Reload the token\nexport TOKEN=$(jq -r '.access_token' .oauth-tokens/ingress.json)\n\n# Step 3: Verify it works\ncurl -s -X GET \"http://localhost/v0.1/servers?limit=1\" \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.servers[0].server.name'\n```\n\n### Issue 2: URL Encoding\n\n**Symptom**: 404 errors when server name contains `/`\n\n**Solution**: Always URL-encode the server name\n```bash\n# Wrong: io.mcpgateway/server-name\n# Correct: io.mcpgateway%2Fserver-name\n```\n\n### Issue 3: Empty Response\n\n**Symptom**: `{\"servers\": [], \"metadata\": {\"count\": 0}}`\n\n**Solution**: Check if servers are registered and enabled\n```bash\n# List server files\nls ~/mcp-gateway/servers/*.json\n\n# Check registry logs\ndocker compose logs registry | grep -i \"loading servers\"\n```\n\n## Integration with Anthropic Tools\n\nThese endpoints are compatible with Anthropic MCP client tools. Example:\n\n```python\nimport httpx\n\n# Configure client\nclient = httpx.Client(\n base_url=\"http://localhost:7860\",\n headers={\"Authorization\": f\"Bearer {token}\"}\n)\n\n# List servers\nresponse = client.get(\"/v0.1/servers\", params={\"limit\": 10})\nservers = response.json()\n\n# Get server details\nserver_name = servers[\"servers\"][0][\"server\"][\"name\"]\nencoded_name = server_name.replace(\"/\", \"%2F\")\ndetails = client.get(f\"/v0.1/servers/{encoded_name}/versions/latest\")\n```\n\n## Next Steps\n\nAfter testing:\n\n1. Document any issues found\n2. Test with real MCP clients (Claude Desktop, etc.)\n3. Verify compatibility with Anthropic's official registry clients\n4. Performance testing with larger datasets\n5. Security testing (SQL injection, XSS, etc.)\n\n## References\n\n- Issue #175: Support Anthropic MCP Registry REST API v0.1\n- OpenAPI Spec: https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/api/openapi.yaml\n- API Guide: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/consuming/use-rest-api.md\n" }, { "path": "docs/design/architectural-decision-reverse-proxy-vs-application-layer-gateway.md", "content": "# Core Architectural Decision: Reverse Proxy vs Application-Layer Gateway\n\n## Executive Summary\n\nThis document discusses two potential architectures that were considered during the design phase of this solution: a **reverse proxy architecture** and an alternative **tools gateway architecture**. We analyze both approaches from multiple perspectives: performance, security, long-term maintainability, scaling, and operational complexity, and explain why the reverse proxy approach was selected.\n\nThe reverse proxy approach provides better performance, protocol independence, and allows continued Python development while leveraging Nginx for message routing. The tools gateway approach offers better developer experience and enterprise integration but requires Go/Rust implementation for enterprise performance requirements.\n\nThese recommendations are not universal but represent the architectural choices we made while building this system.\n\n## Architecture Overview\n\n### Reverse Proxy Pattern (Current)\n\n```\nAI Agent/Coding Assistant\n |\n | Multiple Endpoints\n v\n ┌─────────────────┐\n │ Nginx Gateway │\n │ /fininfo/ │ ──auth_request──> Auth Server\n │ /mcpgw/ │ │\n │ /currenttime/ │ <──auth_headers───────┘\n └─────────────────┘\n │ │ │\n │ │ └─── localhost:8003 (currenttime)\n │ └───── localhost:8002 (mcpgw)\n └─────── localhost:8001 (fininfo)\n │\n v\n Individual MCP Servers\n```\n\n**Key Characteristics:**\n- Path-based routing (`/fininfo/`, `/mcpgw/`, etc.)\n- Nginx handles auth validation and proxying\n- Direct streaming connections to backend servers\n- Protocol-agnostic (HTTP, WebSocket, SSE, etc.)\n\n### Tools Gateway Pattern (Alternative)\n\n```\nAI Agent/Coding Assistant\n |\n | Single Endpoint\n v\n ┌─────────────────┐\n │ Tools Gateway │ ──auth_request──> Auth Server\n │ /mcp │ │\n │ (aggregates │ <──auth_headers───────┘\n │ all tools) │\n └─────────────────┘\n │\n | Tool routing logic\n v\n ┌─────────────────┐\n │ MCP Client Pool │\n │ fininfo_* │ ──> localhost:8001 (fininfo)\n │ mcpgw_* │ ──> localhost:8002 (mcpgw)\n │ currenttime_* │ ──> localhost:8003 (currenttime)\n └─────────────────┘\n```\n\n**Key Characteristics:**\n- Single endpoint with tool aggregation\n- Gateway implements MCP protocol parsing\n- Connection termination and re-establishment\n- Tool name prefixing for disambiguation\n\n## Architectural Comparison\n\n### Performance\n\n| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |\n|--------|-------------------------|---------------|-------------------|\n| Latency | Direct proxy routing = minimal overhead (~1-2ms) | Additional hop through gateway logic (~5-10ms minimum) | Reverse Proxy |\n| Throughput | Each connection directly streams to target server | Gateway becomes bottleneck for all tool calls | Reverse Proxy |\n| Network Efficiency | Client maintains persistent connections to specific servers | Gateway must proxy all request/response payloads | Reverse Proxy |\n| CPU Usage | [Nginx](https://Nginx.org/) handles routing, minimal Python involvement | Gateway must parse, route, and proxy every MCP message | Reverse Proxy |\n| Memory | Low gateway memory usage, servers handle their own state | Gateway must buffer requests/responses, maintain backend connections | Reverse Proxy |\n| **Protocol Independence** | **Nginx passes through any protocol - not MCP-specific** | **Gateway must understand MCP protocol specifics** | **Reverse Proxy** |\n| Implementation Language | Python suitable due to Nginx handling message routing | **Requires Go/Rust for enterprise performance requirements** | Reverse Proxy |\n| **Implementation Complexity** | **Nginx handles protocol details, minimal state management needed** | **Requires elaborate state management, protocol awareness, connection lifecycle management** | **Reverse Proxy** |\n\n### Security\n\n| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |\n|--------|-------------------------|---------------|-------------------|\n| Authentication | Nginx auth_request pattern = proven, well-documented | Gateway must implement auth validation | Equivalent |\n| Authorization | Fine-grained scope validation per server/tool before routing | Can implement same fine-grained scopes | Equivalent |\n| Audit Trail | Complete Nginx access logs + auth server logs + IdP logs | Gateway logs all tool calls | Equivalent |\n| Attack Surface | Direct server access blocked, only authenticated routes exposed | Single endpoint, easier to monitor but single point of failure | Equivalent |\n| Token Validation | Centralized in auth server, cached for performance | Must implement JWT/session validation | Equivalent |\n\n### Maintainability\n\n| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |\n|--------|-------------------------|---------------|-------------------|\n| Service Registration & Configuration | Dynamic Nginx config generation and reload for new servers | Dynamic tool registration without infrastructure changes | Tools Gateway |\n| Debugging | Multi-component debugging (Nginx + auth server + target server) | Centralized logging and error handling | Tools Gateway |\n| Transport Support | Must handle SSE/HTTP variations per server | Must implement transport variations in gateway code | Equivalent |\n| Error Handling | Error propagation through multiple layers | Must implement error translation from backends | Equivalent |\n\n### Scaling\n\n| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |\n|--------|-------------------------|---------------|-------------------|\n| Horizontal Scaling | Can load balance multiple gateway instances easily | Gateway must maintain backend connection pools | Reverse Proxy |\n| **Backend Scaling** | **Each MCP server scales independently** | **Gateway must implement backend load balancing** | **Reverse Proxy** |\n| **Resource Isolation** | **Both handle backend failures via health checks, but Nginx transparently proxies data plane traffic end-to-end** | **Gateway must maintain both data plane MCP connections AND separate health checks to backends** | **Reverse Proxy** |\n| Connection Pooling | Direct client connections to needed servers only | Gateway must manage M×N connection pools | Reverse Proxy |\n| Geographic Distribution | Can proxy to servers in different regions | Complex backend routing required | Reverse Proxy |\n| **Protocol Extensibility** | **Same architecture works for Agent-to-Agent (A2A) or other protocols** | **MCP-specific implementation limits future protocol support** | **Reverse Proxy** |\n\n### Operational Complexity\n\n| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |\n|--------|-------------------------|---------------|-------------------|\n| Monitoring | Must monitor Nginx + auth server + N backend servers | Monitor gateway + auth server + N backend servers (simpler) | Tools Gateway |\n| Service Discovery | Complex Nginx config regeneration | Dynamic tool registration | Tools Gateway |\n| Health Checking | Health status triggers Nginx config regeneration and reload | Gateway makes runtime routing decisions based on health | Equivalent |\n| Certificate Management | Single domain cert for gateway endpoint | Only gateway needs external certs | Equivalent |\n| Log Aggregation | Focused logs per component (Nginx, auth, individual MCP servers) | All tool calls centralized in gateway logs | Equivalent |\n\n### Enterprise Integration & User Experience\n\n| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |\n|--------|-------------------------|---------------|-------------------|\n| **Client Configuration & Mental Model** | **Must configure N server endpoints, understand Nginx routing + auth + backend servers** | **Single endpoint configuration, simple \"one gateway, many tools\" concept** | **Tools Gateway** |\n| Network Policies | Must allowlist N different paths | Single path to allowlist | Tools Gateway |\n| Change Management | Adding new server requires client reconfiguration | New tools appear automatically via discovery | Tools Gateway |\n| Vendor Integration | Each vendor needs separate endpoint configuration | Vendors configure single endpoint | Tools Gateway |\n| Tool Discovery | Discovery via Registry UI or MCPGW MCP server | Automatic through tools/list call | Equivalent |\n| Error Messages | May be confusing due to multiple layers | Clearer, centralized error formatting | Tools Gateway |\n| Testing | Must test each server endpoint individually | Single endpoint for all testing | Tools Gateway |\n\n## Implementation Considerations\n\n### Protocol Independence Benefits\nThe reverse proxy architecture provides protocol independence:\n- **Future Protocols**: Can support Agent-to-Agent (A2A), custom protocols without gateway changes\n- **Protocol Evolution**: MCP protocol changes don't require gateway modifications\n- **Mixed Environments**: Can proxy HTTP, WebSocket, gRPC, or custom protocols simultaneously\n\n### Tools Gateway Implementation Challenges\nA tools gateway requires:\n- **Language Choice**: Python insufficient for performance; requires Go/Rust implementation\n- **MCP Client Library**: Must embed full MCP client for backend communication and keep client updated with evolving MCP specification changes\n- **Protocol Parsing**: Must understand and parse all MCP message types\n- **Connection Handling**: Complex connection lifecycle management\n- **Error Translation**: Convert backend MCP errors to client-readable format\n\n\n\n## Conclusion\n\nBoth architectures have merits:\n\n- **Reverse Proxy**: Better performance, proven scalability, protocol independence, established Nginx foundation, allows Python implementation due to Nginx handling message routing\n- **Tools Gateway**: Better developer experience, easier enterprise adoption, simpler operations, requires Go/Rust implementation for enterprise performance requirements\n\nThe choice depends on organizational priorities:\n\n- **Performance-first organizations** (high-frequency trading, real-time systems): Stay with reverse proxy\n- **Protocol-diverse environments** (supporting A2A, custom protocols): Reverse proxy provides flexibility\n- **Python-preferred development teams**: Reverse proxy allows continued Python development while Nginx handles performance-critical routing\n- **Developer experience-first organizations** (internal tooling, enterprise IT): Consider tools gateway but must invest in Go/Rust development expertise\n- **Hybrid organizations**: Implement both patterns and let teams choose\n\nThe current implementation is suitable for deployment and protocol-independent. The reverse proxy approach provides more architectural flexibility for future protocol support while allowing the team to continue developing in Python." }, { "path": "docs/design/authentication-design.md", "content": "# Authentication and Authorization Design\n\n**Version:** 1.0\n**Last Updated:** 2026-01-18\n\n## Related Documentation\n\n- [Multi-Provider IdP Support](./idp-provider-support.md) - Architecture for supporting multiple identity providers\n- [Authentication & Authorization Guide](../auth.md) - Operational guide with setup instructions\n- [Microsoft Entra ID Integration](../entra.md) - Entra ID-specific setup and configuration\n\n## Overview\n\nThe MCP Gateway Registry implements a comprehensive authentication and authorization system supporting three distinct identity scenarios:\n\n1. **Human Users** - Interactive users accessing the Registry UI and generating API tokens\n2. **Programmatic Access (API Tokens)** - Self-signed JWT tokens for CLI tools and AI coding assistants\n3. **Workload Identity (M2M)** - Service accounts for AI agents and automated systems\n\n## Identity Types\n\n```\n+------------------+------------------+------------------+\n| Human Users | Programmatic | Workload |\n| | Access | Identity (M2M) |\n+------------------+------------------+------------------+\n| | | |\n| - Interactive | - CLI tools | - AI Agents |\n| browser login | - AI coding | - Automated |\n| - OAuth2 flow | assistants | pipelines |\n| - Session-based | - Scripts | - Service-to- |\n| | | service |\n+------------------+------------------+------------------+\n| | | |\n| Auth Method: | Auth Method: | Auth Method: |\n| Authorization | Self-signed | OAuth2 Client |\n| Code Flow | JWT (HS256) | Credentials Flow |\n| | | (RS256) |\n+------------------+------------------+------------------+\n```\n\n---\n\n## Part 1: Human User Authentication\n\n### 1.1 OAuth2 Authorization Code Flow\n\nHuman users authenticate via the configured identity provider (Keycloak or Entra ID) using the standard OAuth2 Authorization Code flow.\n\n```\n+-------------+ +--------------+ +--------------+ +-------------+\n| Browser | | Registry | | Auth Server | | Identity |\n| (User) | | Frontend | | | | Provider |\n+------+------+ +------+-------+ +------+-------+ +------+------+\n | | | |\n | 1. Click \"Login\" | | |\n +------------------>| | |\n | | | |\n | 2. Redirect to | | |\n | Auth Server | | |\n |<------------------+ | |\n | | | |\n | 3. GET /oauth2/login/entra | |\n +--------------------------------------->| |\n | | | |\n | 4. Redirect to IdP authorize endpoint |\n |<-----------------------------------------------------------+\n | | | |\n | 5. User authenticates with IdP |\n +------------------------------------------------------------>|\n |<------------------------------------------------------------+\n | | | |\n | 6. Redirect with authorization code | |\n +--------------------------------------->| |\n | | | |\n | | 7. Exchange code | |\n | | for tokens | |\n | | +------------------->|\n | | |<-------------------+\n | | | (ID token + |\n | | | access token) |\n | | | |\n | 8. Set session cookie + redirect | |\n |<---------------------------------------+ |\n | | | |\n | 9. Access Registry with session cookie | |\n +------------------>| | |\n | | | |\n```\n\n### 1.2 Session Data\n\nAfter successful authentication, the auth server creates a session containing:\n\n```json\n{\n \"user_id\": \"user@example.onmicrosoft.com\",\n \"email\": \"user@example.com\",\n \"groups\": [\"5f605d68-06bc-4208-b992-bb378eee12c5\"],\n \"provider\": \"entra\",\n \"scopes\": [\"public-mcp-users\"],\n \"is_admin\": false,\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n }\n}\n```\n\n### 1.3 UI Permission Enforcement\n\nThe Registry UI enforces feature access based on `ui_permissions` from the user's mapped scopes.\n\n#### Example: `public-mcp-users` Scope\n\nFrom `cli/examples/public-mcp-users.json`:\n\n```json\n{\n \"scope_name\": \"public-mcp-users\",\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n }\n}\n```\n\n**What this user CAN do:**\n- View all MCP servers in the dashboard (`list_service: [\"all\"]`)\n- View the flight-booking agent details (`list_agents`, `get_agent` for `/flight-booking`)\n- Access public MCP servers: context7, cloudflare-docs (via `server_access` rules)\n\n**What this user CANNOT do:**\n- Publish, modify, or delete agents\n- Register or modify MCP servers\n- Toggle services on/off\n- Access health check for all servers (only context7, cloudflare-docs)\n- Access IAM management features\n\n#### Example: `registry-admins` Scope\n\nAdmins have unrestricted access to all UI features:\n\n```yaml\n# From scopes.yml\nUI-Scopes:\n registry-admins:\n list_agents: [all]\n get_agent: [all]\n publish_agent: [all]\n modify_agent: [all]\n delete_agent: [all]\n list_service: [all]\n register_service: [all]\n health_check_service: [all]\n toggle_service: [all]\n modify_service: [all]\n```\n\n### 1.4 Frontend Permission Checks\n\nThe frontend checks `ui_permissions` before rendering features:\n\n```typescript\n// From Dashboard.tsx\nconst hasUiPermission = useCallback((permission: string, servicePath: string): boolean => {\n const permissions = user?.ui_permissions?.[permission];\n if (!permissions) return false;\n\n const serviceName = servicePath.replace(/^\\//, '');\n return permissions.includes('all') || permissions.includes(serviceName);\n}, [user?.ui_permissions]);\n\n// Usage in JSX\n\n```\n\n---\n\n## Part 2: Programmatic Access (Self-Signed JWT Tokens)\n\nHuman users can generate API tokens for programmatic access (CLI tools, AI coding assistants) via the \"Get JWT Token\" button in the UI.\n\n### 2.1 Token Generation Flow\n\n```\n+-------------+ +--------------+ +--------------+ +-------------+\n| Browser | | Registry | | Auth Server | | MongoDB |\n| (User) | | Backend | | | | (Scopes) |\n+------+------+ +------+-------+ +------+-------+ +------+------+\n | | | |\n | 1. Click \"Get JWT Token\" | |\n +------------------>| | |\n | | | |\n | | 2. POST /api/tokens/generate |\n | | (with session cookie) |\n | +------------------->| |\n | | | |\n | | 3. Validate session |\n | | Extract: username, groups, provider |\n | | | |\n | | | 4. Query group |\n | | | mappings |\n | | +------------------->|\n | | |<-------------------+\n | | | (scopes for |\n | | | user's groups) |\n | | | |\n | | 5. Build JWT claims: |\n | | - iss: mcp-auth-server |\n | | - aud: mcp-registry |\n | | - sub: username |\n | | - groups: [group IDs] |\n | | - scope: mapped scopes |\n | | - exp: 8 hours |\n | | | |\n | | 6. Sign JWT with SECRET_KEY (HS256) |\n | | | |\n | | 7. Return JWT | |\n | |<-------------------+ |\n | | | |\n | 8. Display token | | |\n |<------------------+ | |\n```\n\n### 2.2 Self-Signed JWT Structure\n\n```json\n{\n \"iss\": \"mcp-auth-server\",\n \"aud\": \"mcp-registry\",\n \"sub\": \"user@example.onmicrosoft.com\",\n \"preferred_username\": \"user@example.onmicrosoft.com\",\n \"email\": \"user@example.com\",\n \"groups\": [\"5f605d68-06bc-4208-b992-bb378eee12c5\"],\n \"scope\": \"public-mcp-users\",\n \"token_use\": \"access\",\n \"auth_method\": \"oauth2\",\n \"provider\": \"entra\",\n \"iat\": 1768685565,\n \"exp\": 1768714365,\n \"description\": \"Generated via sidebar\"\n}\n```\n\n### 2.3 Using the Token with CLI Tools\n\n```bash\n# Save token to file\necho \"eyJhbGciOiJIUzI1NiIs...\" > .token\n\n# Use with registry_management.py\nuv run python api/registry_management.py \\\n --token-file .token \\\n --registry-url http://localhost \\\n server-search --query \"documentation\"\n\n# Use with curl\ncurl -H \"Authorization: Bearer $(cat .token)\" \\\n http://localhost/api/servers\n```\n\n### 2.4 Token Validation Flow (API Usage)\n\n```\n+-------------+ +--------------+ +--------------+ +-------------+\n| CLI / | | NGINX | | Auth Server | | MCP Server |\n| Client | | Gateway | | | | |\n+------+------+ +------+-------+ +------+-------+ +------+------+\n | | | |\n | 1. API Request | | |\n | Authorization: Bearer | |\n +------------------>| | |\n | | | |\n | | 2. auth_request /validate |\n | +------------------->| |\n | | | |\n | | 3. Check token issuer |\n | | iss == \"mcp-auth-server\"? |\n | | | |\n | | 4. If yes: validate with |\n | | SECRET_KEY (HS256) |\n | | | |\n | | 5. If no: try IdP JWKS |\n | | validation (RS256) |\n | | | |\n | | 6. Extract scopes, validate |\n | | server/tool access |\n | | | |\n | | 7. 200 OK + X-User headers |\n | |<-------------------+ |\n | | | |\n | | 8. Proxy request | |\n | +--------------------------------------->|\n | | | |\n | 9. Response | | |\n |<------------------+ | |\n```\n\n---\n\n## Part 3: Workload Identity (M2M / Service Accounts)\n\nAI agents and automated systems use service accounts with client credentials for authentication.\n\n### 3.1 M2M Identity in Identity Providers\n\n```\n+---------------------------+---------------------------+\n| Keycloak | Microsoft Entra ID |\n+---------------------------+---------------------------+\n| | |\n| Service Account Client: | App Registration: |\n| - Client ID | - Application (client) ID |\n| - Client Secret | - Client Secret |\n| - Service Account User | - Service Principal |\n| - Group Memberships | - Group Memberships |\n| | |\n+---------------------------+---------------------------+\n```\n\n### 3.2 M2M Account Creation Flow (Entra ID)\n\n```\n+-------------+ +--------------+ +--------------+ +-------------+\n| Admin | | Registry | | Entra ID | | MongoDB |\n| CLI | | Backend | | Graph API | | |\n+------+------+ +------+-------+ +------+-------+ +------+------+\n | | | |\n | 1. user-create-m2m --name pub-m2m-bot --groups public-mcp-users\n +------------------>| | |\n | | | |\n | | 2. Create App Registration |\n | +------------------->| |\n | |<-------------------+ |\n | | (app_id, object_id) |\n | | | |\n | | 3. Create Service Principal |\n | +------------------->| |\n | |<-------------------+ |\n | | (service_principal_id) |\n | | | |\n | | 4. Create Client Secret |\n | +------------------->| |\n | |<-------------------+ |\n | | (client_secret) |\n | | | |\n | | 5. Add SP to group (with retry) |\n | +------------------->| |\n | |<-------------------+ |\n | | | |\n | 6. Return credentials | |\n | client_id, client_secret | |\n |<------------------+ | |\n```\n\n### 3.3 M2M Token Request Flow\n\nAI agents use OAuth2 Client Credentials flow to obtain access tokens:\n\n```\n+-------------+ +--------------+ +--------------+\n| AI Agent | | Identity | | Registry |\n| (M2M) | | Provider | | API |\n+------+------+ +------+-------+ +------+-------+\n | | |\n | 1. POST /oauth2/v2.0/token |\n | grant_type=client_credentials |\n | client_id=... |\n | client_secret=... |\n | scope=api://.../.default |\n +------------------>| |\n | | |\n | 2. Access Token (RS256, 1 hour) |\n |<------------------+ |\n | | |\n | 3. API Request with token |\n +--------------------------------------->|\n | | |\n | | 4. Validate via |\n | | IdP JWKS |\n | | |\n | 5. Response | |\n |<--------------------------------------+\n```\n\n### 3.4 Generating M2M Tokens\n\nUse the credentials provider script to generate tokens:\n\n**Identities File** (`.oauth-tokens/entra-identities.json`):\n\n```json\n[\n {\n \"identity_name\": \"pub-m2m-bot\",\n \"tenant_id\": \"6e6ee81b-6bf3-495d-a7fc-d363a551f765\",\n \"client_id\": \"c50b03cf-6f7b-4fae-846e-7910a4100020\",\n \"client_secret\": \"your-client-secret\",\n \"scope\": \"api://1bd17ba1-aad3-447f-be0b-26f8f9ee859f/.default\"\n }\n]\n```\n\n**Generate Token:**\n\n```bash\ncd credentials-provider\nuv run python entra/generate_tokens.py \\\n --identities-file ../.oauth-tokens/entra-identities.json \\\n --output-dir ../.oauth-tokens\n```\n\n**Output** (`.oauth-tokens/pub-m2m-bot.json`):\n\n```json\n{\n \"identity_name\": \"pub-m2m-bot\",\n \"access_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3599,\n \"generated_at\": \"2026-01-18T02:30:56.123456+00:00\",\n \"expires_at\": \"2026-01-18T03:30:55.123456+00:00\",\n \"provider\": \"entra\",\n \"tenant_id\": \"6e6ee81b-6bf3-495d-a7fc-d363a551f765\",\n \"client_id\": \"c50b03cf-6f7b-4fae-846e-7910a4100020\",\n \"scope\": \"api://1bd17ba1-aad3-447f-be0b-26f8f9ee859f/.default\"\n}\n```\n\n### 3.5 M2M Token Structure (from Entra ID)\n\n```json\n{\n \"aud\": \"api://1bd17ba1-aad3-447f-be0b-26f8f9ee859f\",\n \"iss\": \"https://sts.windows.net/6e6ee81b-6bf3-495d-a7fc-d363a551f765/\",\n \"iat\": 1768703056,\n \"nbf\": 1768703056,\n \"exp\": 1768706956,\n \"appid\": \"c50b03cf-6f7b-4fae-846e-7910a4100020\",\n \"appidacr\": \"1\",\n \"groups\": [\"5f605d68-06bc-4208-b992-bb378eee12c5\"],\n \"idp\": \"https://sts.windows.net/6e6ee81b-6bf3-495d-a7fc-d363a551f765/\",\n \"oid\": \"5d3d562c-4449-413a-9791-86920d4bf75f\",\n \"sub\": \"5d3d562c-4449-413a-9791-86920d4bf75f\",\n \"tid\": \"6e6ee81b-6bf3-495d-a7fc-d363a551f765\",\n \"ver\": \"1.0\"\n}\n```\n\n**Key Differences from Self-Signed Tokens:**\n\n| Aspect | Self-Signed (Human) | IdP Token (M2M) |\n|--------|---------------------|-----------------|\n| Issuer | `mcp-auth-server` | `https://sts.windows.net/{tenant}/` |\n| Algorithm | HS256 (symmetric) | RS256 (asymmetric) |\n| Validation | SECRET_KEY | IdP JWKS endpoint |\n| Expiry | 8 hours | 1 hour |\n| Subject | username/email | Service principal object ID |\n\n---\n\n## Part 4: Authorization - Scope-Based Access Control\n\n### 4.1 Scope Storage in MongoDB-CE/Amazon DocumentDB\n\nScopes are stored in the `mcp_scopes_default` collection:\n\n```\n+-----------------------------------------------------------------------+\n| mcp_scopes_default collection |\n+-----------------------------------------------------------------------+\n| { |\n| \"_id\": \"public-mcp-users\", |\n| \"group_mappings\": [ |\n| \"public-mcp-users\", <-- Keycloak group |\n| \"5f605d68-06bc-4208-b992-bb378eee12c5\" <-- Entra ID Object ID |\n| ], |\n| \"server_access\": [ |\n| { |\n| \"server\": \"context7\", |\n| \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"], |\n| \"tools\": [\"*\"] |\n| }, |\n| { |\n| \"server\": \"api\", |\n| \"methods\": [\"initialize\", \"GET\", \"POST\", \"servers\", ...], |\n| \"tools\": [] |\n| } |\n| ], |\n| \"ui_permissions\": { |\n| \"list_service\": [\"all\"], |\n| \"list_agents\": [\"/flight-booking\"], |\n| \"get_agent\": [\"/flight-booking\"] |\n| } |\n| } |\n+-----------------------------------------------------------------------+\n```\n\n### 4.2 Group-to-Scope Mapping Query\n\nThe auth server queries MongoDB-CE/Amazon DocumentDB to find scopes for a given group:\n\n```python\n# From scope_repository.py\nasync def get_group_mappings(self, keycloak_group: str) -> List[str]:\n \"\"\"Find all scopes where group_mappings array contains this group.\"\"\"\n collection = await self._get_collection()\n cursor = collection.find({\"group_mappings\": keycloak_group})\n scope_names = [doc[\"_id\"] async for doc in cursor]\n return scope_names\n```\n\n### 4.3 Server/Tool Access Validation\n\n```\n+------------------+ +------------------+ +------------------+\n| | | | | |\n| Request: | | User Scopes: | | Access |\n| POST /context7 | | [public-mcp- | | Decision: |\n| tools/call | | users] | | GRANTED |\n| | | | | |\n+--------+---------+ +--------+---------+ +--------+---------+\n | | |\n | 1. Extract server | |\n | and method | |\n +----------------------->| |\n | | |\n | 2. For each scope, | |\n | check server_ | |\n | access rules | |\n | +----------------------->|\n | | |\n | 3. public-mcp-users | |\n | allows context7 | |\n | with tools/call | |\n | | |\n```\n\n**Validation Logic** (from `server.py`):\n\n```python\ndef validate_server_tool_access(\n server_name: str,\n method: str,\n tool_name: Optional[str],\n user_scopes: List[str]\n) -> bool:\n \"\"\"Check if user has access to server/method/tool.\"\"\"\n for scope_name in user_scopes:\n scope_config = get_scope_config(scope_name)\n for server_rule in scope_config.get(\"server_access\", []):\n # Check server name match (exact or wildcard)\n if server_rule[\"server\"] in (server_name, \"*\"):\n # Check method is allowed\n if method in server_rule[\"methods\"] or \"all\" in server_rule[\"methods\"]:\n # Check tool access if specified\n if tool_name is None or server_rule[\"tools\"] == \"*\":\n return True\n if tool_name in server_rule[\"tools\"]:\n return True\n return False\n```\n\n---\n\n## Summary Comparison\n\n| Aspect | Human User | Programmatic (API Token) | M2M (Workload) |\n|--------|------------|--------------------------|----------------|\n| **Use Case** | Browser UI | CLI, AI assistants | AI agents, automation |\n| **Auth Flow** | OAuth2 Authorization Code | N/A (derived from session) | OAuth2 Client Credentials |\n| **Token Issuer** | IdP (Keycloak/Entra) | `mcp-auth-server` | IdP (Keycloak/Entra) |\n| **Token Signing** | RS256 (IdP) | HS256 (SECRET_KEY) | RS256 (IdP) |\n| **Token Lifetime** | Session-based | 8 hours | 1 hour |\n| **Validation** | Session cookie | SECRET_KEY | IdP JWKS |\n| **Groups Source** | IdP groups claim | Copied from session | IdP groups claim |\n| **Scope Mapping** | Groups -> Datastore scopes | Embedded in token | Groups -> Datastore scopes |\n| **Credential Storage** | Browser session | Token file | Client ID/Secret |\n\n---\n\n## Related Documentation\n\n- [Multi-Provider IdP Support](./idp-provider-support.md)\n- [Microsoft Entra ID Integration](../entra.md)\n- [Management API Testing Guide](../../api/test-management-api-e2e.md)\n" }, { "path": "docs/design/aws-agent-registry-federation.md", "content": "# AWS Agent Registry Federation -- Design\n\nThis document describes the architecture and design decisions for federating Amazon Bedrock AgentCore registries into MCP Gateway Registry.\n\n## Problem Statement\n\nOrganizations using Amazon Bedrock AgentCore publish MCP servers, A2A agents, and agent skills into AgentCore registries. These assets need to be discoverable alongside locally registered assets in the MCP Gateway Registry. The federation must support:\n\n- Multiple registries (same account, cross-account, cross-region)\n- Four descriptor types (MCP, A2A, CUSTOM, AGENT_SKILLS)\n- Automatic sync with stale record cleanup\n- Granular add/remove of individual registries from the UI\n- Cascade cleanup when a registry is removed\n\n## Architecture\n\n### Component Overview\n\n```\n+-------------------------------+\n| MCP Gateway Registry |\n| |\n| +-------------------------+ | +---------------------------+\n| | Federation Config (Mongo)| <---->| Settings UI |\n| | aws_registry: | | | (ExternalRegistries.tsx) |\n| | enabled: true | | +---------------------------+\n| | registries: [...] | |\n| +-------------------------+ |\n| | |\n| v |\n| +-------------------------+ | +---------------------------+\n| | AgentCoreFederation | ----->| AWS Bedrock AgentCore |\n| | Client (boto3) | | | bedrock-agentcore-control |\n| +-------------------------+ | +---------------------------+\n| | | | |\n| v | +---------+ +---------+\n| +-------------------------+ | | Registry| | Registry|\n| | Server/Agent/Skill | | | Acct A | | Acct B |\n| | Repositories (Mongo) | | +---------+ +---------+\n| +-------------------------+ |\n+-------------------------------+\n```\n\n### Data Flow\n\n```\n1. Startup / Manual Sync / Scheduled Sync\n |\n v\n2. Load FederationConfig from MongoDB\n |\n v\n3. For each registry in config.aws_registry.registries:\n |\n +---> 3a. Create boto3 client (optionally STS AssumeRole for cross-account)\n |\n +---> 3b. Paginate ListRegistryRecords (filtered by descriptor_types, sync_status_filter)\n |\n +---> 3c. Transform each record into MCP Gateway format\n |\n v\n4. Register/update assets in MongoDB\n |\n v\n5. Reconcile stale records (remove assets no longer in source)\n```\n\n## Data Model\n\n### Federation Config (MongoDB: `mcp_federation_config_default`)\n\nThe federation config is a single document with `_id: \"default\"`. The `aws_registry` section stores all AgentCore federation settings:\n\n```json\n{\n \"_id\": \"default\",\n \"aws_registry\": {\n \"enabled\": true,\n \"aws_region\": \"us-east-1\",\n \"sync_on_startup\": true,\n \"sync_interval_minutes\": 60,\n \"sync_timeout_seconds\": 300,\n \"max_concurrent_fetches\": 5,\n \"registries\": [\n {\n \"registry_id\": \"arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rXXX\",\n \"aws_account_id\": \"123456789012\",\n \"aws_region\": \"us-east-1\",\n \"assume_role_arn\": null,\n \"descriptor_types\": [\"MCP\", \"A2A\", \"CUSTOM\", \"AGENT_SKILLS\"],\n \"sync_status_filter\": \"APPROVED\"\n }\n ]\n },\n \"anthropic\": { ... },\n \"asor\": { ... },\n \"created_at\": \"2026-04-10T...\",\n \"updated_at\": \"2026-04-11T...\"\n}\n```\n\n### Synced Asset Tracking\n\nEach synced asset carries metadata that links it back to its source registry. This enables cascade cleanup and prevents orphaned records.\n\n**MCP Servers** (`mcp_servers_default`):\n```json\n{\n \"path\": \"/agentcore-my-server\",\n \"source\": \"agentcore\",\n \"tags\": [\"agentcore\", \"bedrock\", \"federated\", \"mcp\"],\n \"metadata\": {\n \"agentcore_registry_id\": \"arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rXXX\",\n \"agentcore_record_id\": \"record-abc123\",\n \"agentcore_descriptor_type\": \"MCP\"\n }\n}\n```\n\n**A2A Agents** (`mcp_agents_default`):\n```json\n{\n \"path\": \"/agents/agentcore-my-agent\",\n \"tags\": [\"agentcore\", \"bedrock\", \"federated\", \"a2a\"],\n \"metadata\": {\n \"agentcore_registry_id\": \"arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rXXX\",\n \"agentcore_record_id\": \"record-def456\",\n \"agentcore_descriptor_type\": \"A2A\"\n }\n}\n```\n\n**Agent Skills** (`agent_skills_default`):\n```json\n{\n \"path\": \"/skills/agentcore-my-skill\",\n \"tags\": [\"agentcore\", \"bedrock\", \"federated\", \"skill\"],\n \"metadata\": {\n \"agentcore_registry_id\": \"arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rXXX\",\n \"agentcore_record_id\": \"record-ghi789\",\n \"agentcore_descriptor_type\": \"AGENT_SKILLS\"\n }\n}\n```\n\n## Key Design Decisions\n\n### 1. Single Enable Flag via Environment Variable\n\n**Decision**: Only `AWS_REGISTRY_FEDERATION_ENABLED` is an environment variable. All other settings (region, registries, sync behavior) are managed via the API/UI and stored in MongoDB.\n\n**Rationale**:\n- The enable flag is a deployment-level concern (should this instance support AgentCore federation at all?)\n- Registry IDs, regions, and descriptor types are operational concerns that change at runtime\n- Reduces env var sprawl -- previous design had 7 env vars, most of which were unused by the application\n\n**Implementation**: `_apply_aws_registry_env_vars()` in `registry/main.py` reads the env var on startup and updates the MongoDB federation config before any sync runs.\n\n### 2. Path-Based Naming Convention\n\n**Decision**: Synced assets use a `agentcore-` prefix in their path.\n\n| Asset Type | Path Pattern | Example |\n|-----------|-------------|---------|\n| MCP Server | `/agentcore-{name}` | `/agentcore-my-mcp-server` |\n| A2A Agent | `/agents/agentcore-{name}` | `/agents/agentcore-travel-bot` |\n| Agent Skill | `/skills/agentcore-{name}` | `/skills/agentcore-booking-skill` |\n\n**Rationale**:\n- Makes federated assets visually distinct in the UI and API\n- Enables tag-based fallback matching for cascade cleanup (older records without metadata)\n- Avoids path collisions with locally registered assets\n\n### 3. Dual Matching Strategy for Cascade Cleanup\n\n**Decision**: When a registry is removed, the cleanup logic uses two matching strategies:\n\n1. **Primary**: Match by `metadata.agentcore_registry_id` (exact, reliable)\n2. **Fallback**: Match by `\"agentcore\" in tags AND path.startswith(\"/type/agentcore-\")` (for older records)\n\n**Rationale**: Records synced before metadata tracking was added only have tags and path conventions. The fallback ensures these are cleaned up too. The fallback is conservative -- it requires both the tag and the path prefix to match.\n\n### 4. Conditional IAM Policy Creation\n\n**Decision**: The `bedrock_agentcore_access` IAM policy is only created when `aws_registry_federation_enabled = true` in Terraform.\n\n```hcl\nresource \"aws_iam_policy\" \"bedrock_agentcore_access\" {\n count = var.aws_registry_federation_enabled ? 1 : 0\n ...\n}\n```\n\n**Rationale**: Follows the principle of least privilege. Deployments that don't use AgentCore federation don't get AgentCore IAM permissions. The policy uses `bedrock-agentcore:*` for simplicity since AgentCore is a new service with a limited action set, and all actions may be needed as the feature evolves.\n\n### 5. Cross-Account Access via Per-Registry Role Assumption\n\n**Decision**: Cross-account access is configured per-registry via `assume_role_arn`, not globally.\n\n**Rationale**: Different registries may be in different accounts, each requiring a different IAM role. The STS AssumeRole call is scoped by a condition requiring `Purpose: agentcore-federation` tag on the target role, preventing the gateway from assuming arbitrary roles.\n\n### 6. Backward Compatibility via Model Validator\n\n**Decision**: A Pydantic `model_validator` transparently renames the old `agentcore` key to `aws_registry` when loading federation config from MongoDB.\n\n```python\n@model_validator(mode=\"before\")\n@classmethod\ndef _migrate_agentcore_key(cls, data: Any) -> Any:\n if isinstance(data, dict) and \"agentcore\" in data and \"aws_registry\" not in data:\n data[\"aws_registry\"] = data.pop(\"agentcore\")\n return data\n```\n\n**Rationale**: Avoids requiring a MongoDB migration script. Existing documents with the old key name deserialize correctly. New saves use the new key name, so documents are gradually migrated.\n\n## API Endpoints\n\n### Federation Config Management\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/federation/config/{config_id}` | Get full federation config |\n| PUT | `/api/federation/config/{config_id}` | Update full federation config |\n| POST | `/api/federation/config/{config_id}/aws_registry/registries` | Add a single registry |\n| DELETE | `/api/federation/config/{config_id}/aws_registry/registries/{registry_id}` | Remove a registry (with cascade cleanup) |\n\n### Sync\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/federation/sync` | Sync all enabled sources |\n| POST | `/api/federation/sync?source=aws_registry` | Sync only AWS Agent Registry |\n\n### Add Registry Request Body\n\n```json\n{\n \"registry_id\": \"arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/rXXX\",\n \"aws_account_id\": \"123456789012\",\n \"aws_region\": \"us-east-1\",\n \"assume_role_arn\": \"arn:aws:iam::999888777666:role/FederationReadOnly\",\n \"descriptor_types\": [\"MCP\", \"A2A\", \"CUSTOM\", \"AGENT_SKILLS\"],\n \"sync_status_filter\": \"APPROVED\"\n}\n```\n\nOnly `registry_id` is required. All other fields are optional.\n\n### Delete Registry Response\n\n```json\n{\n \"message\": \"Registry removed and 3 server(s), 2 agent(s), 1 skill(s) deregistered\",\n \"deregistered\": {\n \"servers\": [\"/agentcore-my-server\"],\n \"agents\": [\"/agents/agentcore-my-agent\"],\n \"skills\": [\"/skills/agentcore-my-skill\"]\n }\n}\n```\n\n## Frontend Design\n\n### External Registries Page\n\nThe External Registries settings page shows a card for each federation source (AWS Agent Registry, Anthropic, ASOR). Each card has:\n\n- **Header**: Source name, enabled/disabled badge, Sync button, Add (+) button\n- **Body**: List of configured entries with remove (X) buttons\n- **Empty state**: \"No registries configured\" with an Add button\n\n### Add Registry Modal\n\nThe `AddRegistryEntryModal` component renders different forms based on `sourceType`:\n\n- `aws_registry`: Multi-field form (registry ID, account, region, role ARN, descriptor types, status filter)\n- `anthropic`: Single field (server name)\n- `asor`: Single field (agent ID)\n\nARN auto-population: When the user types or pastes a full ARN into the Registry ID field, the region and account ID fields are automatically populated by parsing the ARN structure (`arn:aws:bedrock-agentcore:::registry/...`).\n\n### Confirm Delete Modal\n\nA styled `ConfirmModal` replaces the native browser `window.confirm()` dialog. It supports:\n- Destructive (red) and normal (purple) button styles\n- Loading state with \"Removing...\" text\n- Warning icon with contextual coloring\n\n## Reconciliation\n\n### Stale Record Cleanup\n\nAfter each sync, a reconciliation pass removes records that exist locally but are no longer present in the source registry:\n\n1. Collect all paths synced in this run (`synced_paths`)\n2. Query local repos for all agentcore-sourced records\n3. Delete any record whose path is not in `synced_paths`\n\nThis ensures that records deleted from AgentCore are eventually removed from the gateway.\n\n### Timing\n\n- **On startup**: Runs after startup sync if `sync_on_startup: true`\n- **On manual sync**: Runs after each sync triggered via API or UI\n- **On registry removal**: Cascade cleanup runs immediately (does not wait for sync)\n\n## Security Considerations\n\n### IAM Permissions\n\nThe minimum IAM permissions for read-only federation:\n\n```json\n{\n \"Action\": [\n \"bedrock-agentcore:ListRegistries\",\n \"bedrock-agentcore:ListRegistryRecords\",\n \"bedrock-agentcore:GetRegistryRecord\"\n ],\n \"Resource\": \"*\"\n}\n```\n\nThe Terraform module uses `bedrock-agentcore:*` for operational flexibility.\n\n### Cross-Account STS\n\nThe `sts:AssumeRole` permission is scoped by a condition:\n\n```json\n{\n \"Condition\": {\n \"StringLike\": {\n \"iam:ResourceTag/Purpose\": \"agentcore-federation\"\n }\n }\n}\n```\n\nThis prevents the gateway from assuming arbitrary IAM roles. Remote accounts must explicitly tag their federation role with `Purpose: agentcore-federation`.\n\n### Authentication Chain\n\n1. ECS task role provides base AWS credentials\n2. For same-account registries: direct API calls using task role credentials\n3. For cross-account registries: STS AssumeRole to get temporary credentials, then API calls\n\n## File Map\n\n| File | Purpose |\n|------|---------|\n| `registry/schemas/federation_schema.py` | Pydantic models for federation config |\n| `registry/services/federation/agentcore_client.py` | boto3 client for AgentCore API |\n| `registry/services/federation_reconciliation.py` | Stale record cleanup |\n| `registry/api/federation_routes.py` | API endpoints (add/remove/sync) |\n| `registry/main.py` | Startup sync and env var override |\n| `frontend/src/components/ExternalRegistries.tsx` | Settings page UI |\n| `frontend/src/components/AddRegistryEntryModal.tsx` | Add registry modal |\n| `frontend/src/components/ConfirmModal.tsx` | Styled confirm dialog |\n| `terraform/aws-ecs/modules/mcp-gateway/iam.tf` | AgentCore IAM policy |\n| `terraform/aws-ecs/modules/mcp-gateway/ecs-services.tf` | ECS task definition env vars |\n" }, { "path": "docs/design/cookie-security-design.md", "content": "# Cookie Security Design\n\n## Overview\n\nThis document explains the design decisions behind the session cookie security implementation in the MCP Gateway Registry, particularly regarding the use of domain cookies for cross-subdomain authentication.\n\n## Background\n\nThe MCP Gateway Registry supports authentication through both traditional username/password and OAuth2 providers. In deployments where the auth server and registry are on different subdomains (e.g., `auth.example.com` and `registry.example.com`), session cookies must be shared across these subdomains for seamless authentication.\n\n## Design Decision: Single-Tenant Architecture\n\nThis implementation is designed for **single-tenant deployments** where:\n- All subdomains are owned and controlled by a single organization\n- Cross-subdomain cookie sharing is a desired feature, not a security risk\n- Users authenticate once and access multiple services on different subdomains\n\n## Cookie Security Configuration\n\n### Environment Variables\n\nTwo key environment variables control cookie security behavior:\n\n1. **`SESSION_COOKIE_SECURE`** (default: `false`)\n - Set to `true` in production deployments with HTTPS\n - When `true`, cookies are only transmitted over HTTPS connections\n - Prevents man-in-the-middle (MITM) attacks and session hijacking\n - **Production Requirement:** MUST be set to `true` when deployed with HTTPS\n\n2. **`SESSION_COOKIE_DOMAIN`** (default: `None` or empty string)\n - **MUST be explicitly configured** - no automatic domain inference\n - When set (e.g., `.example.com`), enables cross-subdomain cookie sharing\n - Must start with a dot (`.`) to match all subdomains\n - When `None` or empty, cookies are scoped to the exact host that sets them\n - **Format:** `.example.com` (note the leading dot)\n - **Important:** Set to empty string `\"\"` for single-domain deployments\n - **Examples:**\n - Single domain (`mcpgateway.ddns.net`): Leave unset or set to `\"\"`\n - Cross-subdomain (`auth.example.com`, `registry.example.com`): Set to `.example.com`\n - Multi-level domains (`registry.region-1.corp.company.internal`): Set to `.corp.company.internal` if cross-subdomain sharing needed\n\n### HTTPS Termination Detection\n\n**Critical Implementation Detail**: The auth server intelligently handles HTTPS termination at load balancers (ALB, nginx, etc.):\n\n- **Backend sees HTTP** but **load balancer terminates HTTPS** → Common in AWS ALB, nginx reverse proxy\n- **Solution**: Auth server checks `X-Forwarded-Proto` header to detect original protocol\n- **Behavior**: Cookie `secure` flag is set based on **original request protocol**, not backend protocol\n\n**Code Logic** ([`auth_server/server.py:1797-1803`](../auth_server/server.py)):\n```python\nx_forwarded_proto = request.headers.get(\"x-forwarded-proto\", \"\")\nis_https = x_forwarded_proto == \"https\" or request.url.scheme == \"https\"\n\n# Only set secure=True if the original request was HTTPS\ncookie_secure_config = OAUTH2_CONFIG.get(\"session\", {}).get(\"secure\", False)\ncookie_secure = cookie_secure_config and is_https\n```\n\n**Important**:\n- If `SESSION_COOKIE_SECURE=true` but `is_https=False`, the secure flag will NOT be set\n- This prevents login failures when HTTPS termination is misconfigured\n- Check server logs for `is_https=True` in production to verify HTTPS detection is working\n\n### Cookie Security Flags\n\nThe implementation sets the following security flags on all session cookies:\n\n| Flag | Value | Purpose |\n|------|-------|---------|\n| `httponly` | `True` | Prevents JavaScript access, mitigating XSS attacks |\n| `samesite` | `\"lax\"` | Provides CSRF protection while allowing cross-site navigation |\n| `secure` | Configurable | Ensures HTTPS-only transmission in production |\n| `path` | `\"/\"` | Explicitly scopes cookie to entire domain |\n| `domain` | Configurable | Enables cross-subdomain sharing when needed |\n\n## Security Considerations\n\n### ✅ Safe Deployment Scenarios\n\nThis design is **SAFE** for:\n\n1. **Single-Tenant Production Deployments**\n - Example: `auth.company.com` and `registry.company.com`\n - All subdomains owned by the same organization\n - Configuration:\n ```bash\n SESSION_COOKIE_SECURE=true\n SESSION_COOKIE_DOMAIN=.company.com\n ```\n\n2. **Local Development (localhost)**\n - Local development on `localhost` via HTTP\n - Configuration:\n ```bash\n SESSION_COOKIE_SECURE=false # MUST be false for HTTP\n SESSION_COOKIE_DOMAIN= # Leave unset/empty\n ```\n - **Important:** Setting `SESSION_COOKIE_SECURE=true` on localhost will cause login to fail because cookies with `secure=true` are only sent over HTTPS, and localhost typically runs over HTTP.\n\n### ⚠️ Unsafe Deployment Scenarios\n\nThis design is **NOT SAFE** for:\n\n1. **Multi-Tenant SaaS Deployments**\n - Example: `customer1.saas-platform.com` and `customer2.saas-platform.com`\n - **Risk:** Setting `SESSION_COOKIE_DOMAIN=.saas-platform.com` would allow:\n - Customer A to access Customer B's sessions\n - Cross-tenant authentication bypass\n - Serious data breach potential\n\n2. **Shared Hosting Environments**\n - Multiple organizations sharing the same root domain\n - **Risk:** Similar to multi-tenant scenario\n\n### Alternative Solutions for Multi-Tenant\n\nIf you need multi-tenant deployment, consider these alternatives:\n\n1. **Token-Based Authentication**\n - Use JWT tokens passed via headers instead of cookies\n - Tokens explicitly scoped to each tenant\n - No domain-sharing concerns\n\n2. **Separate Auth Domains per Tenant**\n - `customer1-auth.platform.com` and `customer1-app.platform.com`\n - Different root domains prevent cookie sharing between tenants\n\n3. **Reverse Proxy with Path-Based Routing**\n - Single domain with path-based service routing\n - Example: `platform.com/auth` and `platform.com/registry`\n - No cross-subdomain cookie requirements\n\n4. **Centralized OAuth Flow**\n - OAuth server on separate domain\n - Token exchange instead of session cookies\n - Better tenant isolation\n\n## Attack Scenarios Mitigated\n\n### 1. Session Hijacking (MITM)\n- **Threat:** Attacker intercepts session cookies over unencrypted HTTP\n- **Mitigation:** `secure=True` flag in production\n- **Status:** ✅ Mitigated when `SESSION_COOKIE_SECURE=true`\n\n### 2. Cross-Site Scripting (XSS)\n- **Threat:** Malicious JavaScript reads session cookies\n- **Mitigation:** `httponly=True` flag\n- **Status:** ✅ Always mitigated\n\n### 3. Cross-Site Request Forgery (CSRF)\n- **Threat:** Malicious site triggers authenticated requests\n- **Mitigation:** `samesite=\"lax\"` flag\n- **Status:** ✅ Always mitigated\n\n### 4. Subdomain Cookie Theft (Single-Tenant)\n- **Threat:** Attacker controls a subdomain and steals cookies\n- **Mitigation:** Only valid in trusted single-tenant environments\n- **Status:** ⚠️ Acceptable risk for single-tenant deployments\n\n## Production Deployment Checklist\n\nBefore deploying to production:\n\n- [ ] Set `SESSION_COOKIE_SECURE=true` in environment (REQUIRED for HTTPS)\n- [ ] Verify HTTPS is properly configured and enforced\n- [ ] **IMPORTANT**: If using load balancer with HTTPS termination, ensure `X-Forwarded-Proto` header is set\n- [ ] Set `SESSION_COOKIE_DOMAIN` appropriately:\n - **Empty string or unset** for single-domain deployments (RECOMMENDED - safest)\n - **`.example.com`** only if you need cross-subdomain authentication\n- [ ] Confirm you are deploying in a single-tenant architecture (NOT multi-tenant SaaS)\n- [ ] Test cross-subdomain authentication between auth and registry services (if using domain cookies)\n- [ ] Verify cookies are NOT transmitted over HTTP in production\n- [ ] Review server logs for cookie configuration at startup:\n - Check for `Auth server setting session cookie: secure=True`\n - Verify `domain` setting matches your configuration\n - Confirm `is_https=True` in production\n\n### Example Production Configurations\n\n**Single-Domain Deployment (RECOMMENDED - Most Secure):**\n```bash\n# .env for production - single domain (e.g., mcpgateway.example.com)\nSESSION_COOKIE_SECURE=true # REQUIRED for HTTPS\nSESSION_COOKIE_DOMAIN= # Empty = exact host only (safest)\nSESSION_COOKIE_NAME=mcp_gateway_session\nSESSION_MAX_AGE_SECONDS=28800 # 8 hours\nAUTH_SERVER_URL=http://auth-server:8888 # Internal URL\nAUTH_SERVER_EXTERNAL_URL=https://mcpgateway.example.com # External URL\n```\n\n**Cross-Subdomain Deployment:**\n```bash\n# .env for production - cross-subdomain (e.g., auth.example.com + registry.example.com)\nSESSION_COOKIE_SECURE=true # REQUIRED for HTTPS\nSESSION_COOKIE_DOMAIN=.example.com # Note the leading dot\nSESSION_COOKIE_NAME=mcp_gateway_session\nSESSION_MAX_AGE_SECONDS=28800 # 8 hours\nAUTH_SERVER_URL=http://auth-server:8888 # Internal URL\nAUTH_SERVER_EXTERNAL_URL=https://auth.example.com # External URL\n```\n\n## Code Implementation\n\nThe cookie security implementation is found in:\n\n- **Configuration:** [`registry/core/config.py`](../registry/core/config.py)\n - `session_cookie_secure`: Controls HTTPS-only flag\n - `session_cookie_domain`: Controls cross-subdomain sharing\n\n- **Auth Server Cookie Setting:** [`auth_server/server.py`](../auth_server/server.py) (lines 1800-1831)\n - X-Forwarded-Proto detection for HTTPS termination at load balancer\n - Explicit configuration only - no automatic domain inference\n - Conditional secure flag based on both config AND actual protocol\n - All security flags properly set\n\n- **Registry Cookie Setting:** [`registry/auth/routes.py`](../registry/auth/routes.py) (lines 139-158)\n - Comprehensive security comments explaining single-tenant model\n - Conditional domain attribute application\n - All security flags properly set\n\n## Monitoring and Validation\n\n### Runtime Validation\n\nThe auth server logs detailed cookie configuration for debugging:\n\n```python\nlogger.info(f\"Auth server setting session cookie: secure={cookie_secure} (config={cookie_secure_config}, is_https={is_https}), samesite={cookie_samesite}, domain={cookie_domain or 'not set'}, x-forwarded-proto={x_forwarded_proto}, request_scheme={request.url.scheme}\")\n```\n\nKey logging details:\n- **secure**: Final secure flag value (after protocol detection)\n- **config**: Configured SESSION_COOKIE_SECURE value\n- **is_https**: Whether the original request was HTTPS (based on X-Forwarded-Proto or request scheme)\n- **domain**: Configured domain or \"not set\"\n- **x-forwarded-proto**: Load balancer protocol header\n- **request_scheme**: Direct request protocol\n\nThe registry logs successful login events:\n\n```python\nlogger.info(f\"User '{username}' logged in successfully.\")\n```\n\n### Security Auditing\n\nPeriodically review:\n1. Cookie flags are properly set in browser developer tools\n2. Cookies are NOT transmitted over HTTP in production\n3. `secure` flag is enabled in production environments\n4. Domain scope matches your deployment architecture\n\n### Browser Developer Tools Verification\n\nIn your browser's developer tools (Application/Storage → Cookies), verify:\n\n| Property | Expected Value | Notes |\n|----------|---------------|-------|\n| `Secure` | ✓ (checked) | Production only |\n| `HttpOnly` | ✓ (checked) | Always |\n| `SameSite` | `Lax` | Always |\n| `Domain` | `.example.com` | If configured |\n| `Path` | `/` | Always |\n\n## References\n\n- [OWASP Session Management Cheat Sheet](https://cheatsheetsecurity.org/cheatsheets/session-management-cheat-sheet)\n- [MDN: Set-Cookie HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie)\n- [RFC 6265: HTTP State Management Mechanism](https://datatracker.ietf.org/doc/html/rfc6265)\n\n## Contact\n\nFor questions or security concerns regarding this implementation, please:\n- Open an issue in the GitHub repository\n- Tag the issue with `security` label\n- Provide details about your deployment scenario\n" }, { "path": "docs/design/database-abstraction-layer.md", "content": "# Database Abstraction Layer Design\n\n**Status:** Current Implementation\n**Last Updated:** January 5, 2026\n**Target Audience:** Senior/Staff Engineers, Architecture Review\n\n## Table of Contents\n\n1. [Architecture Overview](#architecture-overview)\n2. [Design Patterns](#design-patterns)\n3. [Abstract Base Classes](#abstract-base-classes)\n4. [Implementations](#implementations)\n5. [Factory Pattern](#factory-pattern)\n6. [Design Rationale](#design-rationale)\n7. [Code Organization](#code-organization)\n\n## Architecture Overview\n\nThe MCP Gateway Registry implements a **repository pattern with abstract base classes** to provide a clean separation between business logic and data storage. This design enables seamless switching between file-based storage (legacy, backwards compatible) and DocumentDB/MongoDB (recommended) without modifying application code.\n\n### System Diagram\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ Application Layer │\n│ (Services, API Endpoints, Business Logic) │\n└────────────────────┬────────────────────────────────────────────┘\n │ depends on\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ Repository Factory Layer │\n│ get_server_repository() │\n│ get_agent_repository() │\n│ get_scope_repository() │\n│ get_security_scan_repository() │\n│ get_search_repository() │\n│ get_federation_config_repository() │\n└────────┬──────────────────────────────┬────────────────────────┘\n │ │\n │ creates (based on │ creates (based on\n │ STORAGE_BACKEND) │ STORAGE_BACKEND)\n ▼ ▼\n┌──────────────────────┐ ┌──────────────────────────┐\n│ File-Based Impl │ │ DocumentDB Impl │\n├──────────────────────┤ ├──────────────────────────┤\n│ FileServerRepo │ │ DocumentDBServerRepo │\n│ FileAgentRepo │ │ DocumentDBAgentRepo │\n│ FileScopeRepo │ │ DocumentDBScopeRepo │\n│ FileSecurityScanRepo │ │ DocumentDBSecurityRepo │\n│ FaissSearchRepo │ │ DocumentDBSearchRepo │\n│ FileFederationRepo │ │ DocumentDBFederationRepo │\n└──────────┬───────────┘ └──────────┬───────────────┘\n │ │\n ▼ ▼\n Local File System DocumentDB/MongoDB Cluster\n (JSON files, FAISS) (Collections, Vector Search)\n```\n\n### Key Principles\n\n1. **Abstraction**: All repositories implement abstract base classes defining strict contracts\n2. **Polymorphism**: Multiple storage backend implementations (file, DocumentDB/MongoDB)\n3. **Dependency Injection**: Factory pattern provides single point of repository creation\n4. **Consistency**: All implementations provide identical behavior regardless of backend\n5. **Testability**: Mock implementations easy to create; reset_repositories() enables test isolation\n\n## Design Patterns\n\n### Repository Pattern\n\nThe repository pattern provides a **data access abstraction** layer that:\n\n- Isolates business logic from storage implementation details\n- Defines clear, intent-driven interfaces (e.g., `get()`, `create()`, `update()`, `delete()`)\n- Makes switching storage backends transparent to consuming code\n- Enables comprehensive testing without actual storage dependencies\n\n### Factory Pattern\n\nThe factory pattern manages **repository instantiation** by:\n\n- Creating repositories lazily on first access (singleton pattern)\n- Selecting implementation based on environment configuration (`STORAGE_BACKEND` setting)\n- Centralizing backend selection logic in one place (`factory.py`)\n- Providing `reset_repositories()` for test isolation\n\n### Strategy Pattern\n\nDifferent storage backends are **strategies** implementing the same interface:\n\n- **File Strategy**: YAML/JSON files + FAISS for search\n- **DocumentDB/MongoDB Strategy**: Distributed document database with vector search and aggregation pipelines\n\n## Abstract Base Classes\n\nAll repository implementations inherit from abstract base classes defined in [`registry/repositories/interfaces.py`](../../registry/repositories/interfaces.py). These define the contract that ALL implementations must follow.\n\n### ServerRepositoryBase\n\n**Location:** [`registry/repositories/interfaces.py` (lines 14-76)](../../registry/repositories/interfaces.py#L14-L76)\n\n**Purpose:** Data access for MCP server definitions and lifecycle management\n\n**Key Methods:**\n\n```python\n# Lifecycle operations\nasync def get(path: str) -> Optional[Dict[str, Any]]\nasync def list_all() -> Dict[str, Dict[str, Any]]\nasync def create(server_info: Dict[str, Any]) -> bool\nasync def update(path: str, server_info: Dict[str, Any]) -> bool\nasync def delete(path: str) -> bool\n\n# State management (enabled/disabled)\nasync def get_state(path: str) -> bool\nasync def set_state(path: str, enabled: bool) -> bool\n\n# Lifecycle\nasync def load_all() -> None # Load/reload from storage at startup\n```\n\n**Implementations:**\n- [`registry/repositories/file/server_repository.py`](../../registry/repositories/file/server_repository.py) - File-based\n- [`registry/repositories/documentdb/server_repository.py`](../../registry/repositories/documentdb/server_repository.py) - DocumentDB/MongoDB\n\n---\n\n### AgentRepositoryBase\n\n**Location:** [`registry/repositories/interfaces.py` (lines 78-140)](../../registry/repositories/interfaces.py#L78-L140)\n\n**Purpose:** Data access for A2A (Agent-to-Agent) agent definitions\n\n**Key Methods:**\n\n```python\nasync def get(path: str) -> Optional[AgentCard]\nasync def list_all() -> List[AgentCard]\nasync def create(agent: AgentCard) -> AgentCard\nasync def update(path: str, updates: Dict[str, Any]) -> AgentCard\nasync def delete(path: str) -> bool\n\nasync def get_state(path: str) -> bool\nasync def set_state(path: str, enabled: bool) -> bool\n\nasync def load_all() -> None # Load/reload from storage\n```\n\n**Implementations:**\n- [`registry/repositories/file/agent_repository.py`](../../registry/repositories/file/agent_repository.py) - File-based\n- [`registry/repositories/documentdb/agent_repository.py`](../../registry/repositories/documentdb/agent_repository.py) - DocumentDB/MongoDB\n\n---\n\n### ScopeRepositoryBase\n\n**Location:** [`registry/repositories/interfaces.py` (lines 142-506)](../../registry/repositories/interfaces.py#L142-L506)\n\n**Purpose:** Data access for authorization scopes (RBAC - Role-Based Access Control)\n\n**Overview:**\n\nThe Scope Repository manages a complex authorization model with three primary data structures:\n\n1. **UI-Scopes** - Permissions for UI features grouped by Keycloak group\n2. **Server Scopes** - Server access rules (which servers, methods, tools)\n3. **Group Mappings** - Mapping between Keycloak groups and scopes\n\n**Key Methods:**\n\n```python\n# UI permission queries\nasync def get_ui_scopes(group_name: str) -> Dict[str, Any]\nasync def get_group_mappings(keycloak_group: str) -> List[str]\n\n# Server access rules\nasync def get_server_scopes(scope_name: str) -> List[Dict[str, Any]]\n\n# Group management\nasync def get_group(group_name: str) -> Dict[str, Any]\nasync def list_groups() -> Dict[str, Any]\nasync def group_exists(group_name: str) -> bool\nasync def create_group(group_name: str, description: str = \"\") -> bool\nasync def delete_group(group_name: str, remove_from_mappings: bool = True) -> bool\n\n# Server scope assignment\nasync def add_server_scope(\n server_path: str,\n scope_name: str,\n methods: List[str],\n tools: Optional[List[str]] = None\n) -> bool\nasync def remove_server_scope(server_path: str, scope_name: str) -> bool\nasync def remove_server_from_all_scopes(server_path: str) -> bool\n\n# UI visibility management\nasync def add_server_to_ui_scopes(group_name: str, server_name: str) -> bool\nasync def remove_server_from_ui_scopes(group_name: str, server_name: str) -> bool\n\n# Scope mapping management\nasync def add_group_mapping(group_name: str, scope_name: str) -> bool\nasync def remove_group_mapping(group_name: str, scope_name: str) -> bool\nasync def get_all_group_mappings() -> Dict[str, List[str]]\n\n# Bulk operations\nasync def add_server_to_multiple_scopes(\n server_path: str,\n scope_names: List[str],\n methods: List[str],\n tools: List[str]\n) -> bool\n\nasync def load_all() -> None # Load/reload from storage\n```\n\n**Implementations:**\n- [`registry/repositories/file/scope_repository.py`](../../registry/repositories/file/scope_repository.py) - File-based (YAML)\n- [`registry/repositories/documentdb/scope_repository.py`](../../registry/repositories/documentdb/scope_repository.py) - DocumentDB/MongoDB\n\n---\n\n### SecurityScanRepositoryBase\n\n**Location:** [`registry/repositories/interfaces.py` (lines 508-598)](../../registry/repositories/interfaces.py#L508-L598)\n\n**Purpose:** Data access for security scanning results (both MCP servers and agents)\n\n**Key Methods:**\n\n```python\n# CRUD operations\nasync def get(server_path: str) -> Optional[Dict[str, Any]]\nasync def list_all() -> List[Dict[str, Any]]\nasync def create(scan_result: Dict[str, Any]) -> bool\n\n# Querying\nasync def get_latest(server_path: str) -> Optional[Dict[str, Any]]\nasync def query_by_status(status: str) -> List[Dict[str, Any]]\n\nasync def load_all() -> None # Load/reload from storage\n```\n\n**Implementations:**\n- [`registry/repositories/file/security_scan_repository.py`](../../registry/repositories/file/security_scan_repository.py) - File-based\n- [`registry/repositories/documentdb/security_scan_repository.py`](../../registry/repositories/documentdb/security_scan_repository.py) - DocumentDB/MongoDB\n\n---\n\n### SearchRepositoryBase\n\n**Location:** [`registry/repositories/interfaces.py` (lines 600-645)](../../registry/repositories/interfaces.py#L600-L645)\n\n**Purpose:** Data access for semantic/hybrid search functionality\n\n**Key Methods:**\n\n```python\nasync def initialize() -> None # Initialize search service\n\n# Indexing\nasync def index_server(\n path: str,\n server_info: Dict[str, Any],\n is_enabled: bool = False\n) -> None\n\nasync def index_agent(\n path: str,\n agent_card: AgentCard,\n is_enabled: bool = False\n) -> None\n\n# Query\nasync def search(\n query: str,\n entity_types: Optional[List[str]] = None,\n max_results: int = 10\n) -> Dict[str, List[Dict[str, Any]]]\n\nasync def remove_entity(path: str) -> None\n```\n\n**Implementations:**\n- [`registry/repositories/file/search_repository.py`](../../registry/repositories/file/search_repository.py) - FAISS (Facebook AI Similarity Search)\n- [`registry/repositories/documentdb/search_repository.py`](../../registry/repositories/documentdb/search_repository.py) - DocumentDB/MongoDB Hybrid Search (BM25 + k-NN)\n\n---\n\n### FederationConfigRepositoryBase\n\n**Location:** [`registry/repositories/interfaces.py` (lines 647-709)](../../registry/repositories/interfaces.py#L647-L709)\n\n**Purpose:** Data access for federation configuration (multi-registry federation)\n\n**Key Methods:**\n\n```python\n# CRUD operations\nasync def get_config(config_id: str = \"default\") -> Optional[FederationConfig]\nasync def save_config(\n config: FederationConfig,\n config_id: str = \"default\"\n) -> FederationConfig\n\nasync def delete_config(config_id: str = \"default\") -> bool\nasync def list_configs() -> List[Dict[str, Any]]\n```\n\n**Implementations:**\n- [`registry/repositories/file/federation_config_repository.py`](../../registry/repositories/file/federation_config_repository.py) - File-based (JSON)\n- [`registry/repositories/documentdb/federation_config_repository.py`](../../registry/repositories/documentdb/federation_config_repository.py) - DocumentDB/MongoDB\n\n---\n\n## Implementations\n\n### File-Based Backend (Legacy, Backwards Compatible)\n\n**Purpose:** Local file system storage for development, testing, and backwards compatibility\n\n**Characteristics:**\n- **Simplicity**: JSON/YAML files, no external dependencies (except FAISS for search)\n- **Isolation**: No network calls required\n- **State Management**: Separate state files for enabled/disabled status\n- **Search**: FAISS (Facebook AI Similarity Search) for vector similarity\n\n**Storage Structure:**\n```\nregistry/\n├── servers/\n│ ├── server1.json\n│ ├── server2.json\n│ └── server_state.json # Persistence for enabled/disabled state\n├── agents/\n│ ├── agent1_agent.json\n│ ├── agent2_agent.json\n│ └── agent_state.json\n├── config/\n│ ├── scopes.yml # Authorization scopes configuration\n│ └── federation/\n│ └── default.json # Federation configuration\n├── security_scans/\n│ ├── scan_result_1.json\n│ └── scan_result_2.json\n├── models/\n│ └── all-MiniLM-L6-v2/ # Embedding model weights\n└── service_index.faiss # FAISS vector index\n```\n\n**Implementation Classes:**\n- [`FileServerRepository`](../../registry/repositories/file/server_repository.py)\n- [`FileAgentRepository`](../../registry/repositories/file/agent_repository.py)\n- [`FileScopeRepository`](../../registry/repositories/file/scope_repository.py)\n- [`FileSecurityScanRepository`](../../registry/repositories/file/security_scan_repository.py)\n- [`FaissSearchRepository`](../../registry/repositories/file/search_repository.py)\n- [`FileFederationConfigRepository`](../../registry/repositories/file/federation_config_repository.py)\n\n**Advantages:**\n- No infrastructure setup needed\n- Good for development and testing\n- Human-readable file formats\n- Git-friendly for version control\n\n**Limitations:**\n- Single-node only (no distributed deployment)\n- Limited query capabilities\n- File locking issues in concurrent scenarios\n- Not suitable for production at scale\n- FAISS requires model file storage\n\n---\n\n### DocumentDB/MongoDB Backend (Recommended for Production)\n\n**Purpose:** Distributed document database for production deployments\n\n**Characteristics:**\n- **Scalability**: Clustered deployment for redundancy (DocumentDB) or replica sets (MongoDB)\n- **Query Capabilities**: Rich aggregation pipelines, complex filtering, projections\n- **Vector Search**: Native vector search (DocumentDB) or application-level (MongoDB CE)\n- **Collection Management**: Automatic index creation with proper field mappings\n- **Async Support**: Full async/await implementation for non-blocking I/O\n- **Strong Consistency**: ACID transactions and strong consistency guarantees\n\n**Collection Structure:**\n```\nDocumentDB/MongoDB Cluster\n├── mcp_servers_{namespace} # Server definitions\n├── mcp_agents_{namespace} # Agent definitions\n├── mcp_scopes_{namespace} # Authorization scopes\n├── mcp_security_scans_{namespace} # Security scan results\n├── mcp_embeddings_1536_{namespace} # Vector embeddings\n└── mcp_federation_config_{namespace} # Federation configurations\n```\n\n**Implementation Classes:**\n- [`DocumentDBServerRepository`](../../registry/repositories/documentdb/server_repository.py)\n- [`DocumentDBAgentRepository`](../../registry/repositories/documentdb/agent_repository.py)\n- [`DocumentDBScopeRepository`](../../registry/repositories/documentdb/scope_repository.py)\n- [`DocumentDBSecurityScanRepository`](../../registry/repositories/documentdb/security_scan_repository.py)\n- [`DocumentDBSearchRepository`](../../registry/repositories/documentdb/search_repository.py)\n- [`DocumentDBFederationConfigRepository`](../../registry/repositories/documentdb/federation_config_repository.py)\n\n**DocumentDB Client:** [`registry/repositories/documentdb/client.py`](../../registry/repositories/documentdb/client.py)\n\nProvides:\n- Async MongoDB client singleton\n- Connection pooling and authentication\n- Index name management with namespace support\n- Client lifecycle management (initialization and cleanup)\n\n**Advantages:**\n- Distributed, highly available\n- Rich query capabilities\n- Hybrid search (BM25 + k-NN) for semantic understanding\n- Native vector support for embeddings\n- Scales to millions of documents\n- Recommended for deployment\n\n**Limitations:**\n- Requires DocumentDB cluster or MongoDB CE instance\n- Higher operational complexity\n- More network I/O\n- Requires proper index tuning for performance\n\n**Hybrid Search Explanation:**\n\nDocumentDB/MongoDB vector search provides semantic similarity:\n\n1. **BM25 (Best Matching 25)**: Full-text relevance scoring based on term frequency\n - Good for exact keyword matches\n - Fast and traditional IR approach\n - Default web search behavior\n\n2. **k-NN (k-Nearest Neighbors)**: Vector similarity search\n - Semantic understanding\n - Captures meaning, not just keywords\n - Uses neural embeddings (sentence-transformers or Bedrock Titan)\n\n**Default Weighting:**\n```python\n# Legacy - removed: float = 0.4\n# Legacy - removed: float = 0.6\n```\n\nThis gives 60% weight to semantic search (vector similarity) and 40% to keyword matching, optimized for finding semantically relevant servers/agents.\n\n---\n\n## Factory Pattern\n\n### Factory Implementation\n\n**Location:** [`registry/repositories/factory.py`](../../registry/repositories/factory.py)\n\nThe factory provides singleton repository instances with lazy initialization:\n\n```python\ndef get_server_repository() -> ServerRepositoryBase:\n \"\"\"Get server repository singleton.\"\"\"\n global _server_repo\n\n if _server_repo is not None:\n return _server_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating server repository with backend: {backend}\")\n\n if backend == \"documentdb\":\n from .documentdb.server_repository import DocumentDBServerRepository\n _server_repo = DocumentDBServerRepository()\n else:\n from .file.server_repository import FileServerRepository\n _server_repo = FileServerRepository()\n\n return _server_repo\n```\n\n**Similar factory functions exist for:**\n- `get_agent_repository()`\n- `get_scope_repository()`\n- `get_security_scan_repository()`\n- `get_search_repository()`\n- `get_federation_config_repository()`\n\n### Backend Selection Logic\n\nBackend selection is controlled by the `storage_backend` setting in [`registry/core/config.py`](../../registry/core/config.py):\n\n```python\nstorage_backend: str = \"file\" # Options: \"file\", \"documentdb\"\n```\n\n**How it works:**\n\n1. **At startup**: Application reads `STORAGE_BACKEND` environment variable (or defaults to \"file\")\n2. **On first access**: Factory function checks backend setting\n3. **Instance creation**: Creates appropriate implementation (file vs DocumentDB/MongoDB)\n4. **Caching**: Returns cached singleton on subsequent calls\n\n### Dependency Injection Pattern\n\nServices consume repositories through factory functions:\n\n```python\n# In any service module\nfrom registry.repositories.factory import get_server_repository\n\nasync def list_servers():\n repo = get_server_repository() # Gets file or DocumentDB/MongoDB impl\n servers = await repo.list_all()\n return servers\n```\n\n**Benefits:**\n- No hardcoded dependencies\n- Easy to swap implementations\n- Test isolation via `reset_repositories()`\n\n### Test Isolation\n\nFor testing, repositories can be reset:\n\n```python\nfrom registry.repositories.factory import reset_repositories\n\nasync def test_server_creation():\n reset_repositories() # Clear all singletons\n # Now fresh repositories are created\n repo = get_server_repository()\n # ... test code ...\n```\n\n---\n\n## Design Rationale\n\n### Why Repository Pattern?\n\nThe repository pattern addresses several critical concerns:\n\n1. **Separation of Concerns**: Business logic doesn't know about storage details\n - Controllers/services call `repo.get()`, not filesystem or database directly\n - Easier to test services in isolation\n\n2. **Multiple Storage Backends**: Single interface, multiple implementations\n - Same code works with file or DocumentDB/MongoDB backend\n - Switching backends requires only env var change\n - No code changes needed\n\n3. **Consistency**: All implementations follow same contract\n - Same method signatures and behavior\n - Predictable error handling\n - Consistent data transformations\n\n4. **Abstraction**: Storage complexity hidden behind simple interface\n - `repo.get(path)` is simple whether backed by files or DocumentDB/MongoDB\n - Consumers don't care about implementation details\n\n### Benefits of Repository Abstraction\n\n**For Development:**\n- Develop with file backend (fast, no setup)\n- Test with mocks (no I/O overhead)\n- Easy to add new storage backends\n\n**For Deployment:**\n- Production uses DocumentDB/MongoDB (scalable)\n- Backwards compatible with file storage\n- Can migrate gradually\n\n**For Testing:**\n- Mock repositories easily\n- Test services without actual storage\n- Test data isolation via `reset_repositories()`\n\n**For Maintenance:**\n- Storage logic centralized in repository classes\n- Changes to storage don't affect business logic\n- Clear interfaces make code changes safer\n\n### Interface Consistency\n\nAll repositories implement abstract base classes with:\n\n```python\n# All repos have these patterns\nasync def load_all() -> None # Startup initialization\nasync def get(id: str) -> Optional # Single entity retrieval\nasync def list_all() -> List/Dict # Bulk retrieval\nasync def create(entity) -> bool/Entity # Create new entity\nasync def update(id, updates) -> bool/Entity # Modify existing\nasync def delete(id) -> bool # Remove entity\n```\n\nThis consistent interface means:\n- Easier onboarding for engineers\n- Less mental overhead switching between repositories\n- Standardized error handling\n\n### Data Consistency Strategy\n\n**File Backend:**\n- Atomic file operations\n- Separate state file for enabled/disabled status\n- No transactions (file-by-file consistency)\n- Best effort on concurrent writes\n\n**DocumentDB/MongoDB Backend:**\n- Document-level consistency\n- Index operations with refresh flags\n- No distributed transactions\n- Eventual consistency model\n- Suitable for high concurrency\n\n---\n\n## Code Organization\n\n### Directory Structure\n\n```\nregistry/repositories/\n├── __init__.py # Package initialization\n├── interfaces.py # Abstract base classes (6 repos)\n├── factory.py # Repository factory\n│\n├── file/ # File-based implementations\n│ ├── __init__.py\n│ ├── server_repository.py\n│ ├── agent_repository.py\n│ ├── scope_repository.py\n│ ├── security_scan_repository.py\n│ ├── search_repository.py # FAISS-based\n│ └── federation_config_repository.py\n│\n└── documentdb/ # DocumentDB/MongoDB implementations\n ├── __init__.py\n ├── client.py # MongoDB client management\n ├── server_repository.py\n ├── agent_repository.py\n ├── scope_repository.py\n ├── security_scan_repository.py\n ├── search_repository.py # Vector search (native or app-level)\n └── federation_config_repository.py\n```\n\n### Naming Conventions\n\n**Abstract Base Classes** (in `interfaces.py`):\n- `ServerRepositoryBase`\n- `AgentRepositoryBase`\n- `ScopeRepositoryBase`\n- `SecurityScanRepositoryBase`\n- `SearchRepositoryBase`\n- `FederationConfigRepositoryBase`\n\n**File Implementations** (in `file/`):\n- `FileServerRepository`\n- `FileAgentRepository`\n- `FileScopeRepository`\n- `FileSecurityScanRepository`\n- `FaissSearchRepository` (special: uses FAISS, not files)\n- `FileFederationConfigRepository`\n\n**DocumentDB/MongoDB Implementations** (in `documentdb/`):\n- `DocumentDBServerRepository`\n- `DocumentDBAgentRepository`\n- `DocumentDBScopeRepository`\n- `DocumentDBSecurityScanRepository`\n- `DocumentDBSearchRepository`\n- `DocumentDBFederationConfigRepository`\n\n### Configuration\n\nBackend selection and DocumentDB/MongoDB settings in [`registry/core/config.py`](../../registry/core/config.py):\n\n```python\n# Backend selection\nstorage_backend: str = \"file\" # \"file\", \"mongodb\", or \"documentdb\"\n\n# DocumentDB/MongoDB connection\ndocumentdb_endpoint: str = \"localhost\"\ndocumentdb_port: int = 27017\ndocumentdb_username: Optional[str] = None\ndocumentdb_password: Optional[str] = None\ndocumentdb_database: str = \"mcp_gateway\"\ndocumentdb_use_tls: bool = False\ndocumentdb_tls_ca_file: Optional[str] = None\n\n# Multi-tenancy support\ndocumentdb_namespace: str = \"default\"\n\n# Collection names (with namespace suffix)\ndocumentdb_collection_servers: str = \"mcp_servers\"\ndocumentdb_collection_agents: str = \"mcp_agents\"\ndocumentdb_collection_scopes: str = \"mcp_scopes\"\ndocumentdb_collection_embeddings: str = \"mcp_embeddings_1536\"\ndocumentdb_collection_security_scans: str = \"mcp_security_scans\"\ndocumentdb_collection_federation_config: str = \"mcp_federation_config\"\n\n# Vector search configuration\ndocumentdb_vector_dimension: int = 1536 # For embeddings\n```\n\n---\n\n## Advanced Topics\n\n### Namespace Support (Multi-Tenancy)\n\nDocumentDB/MongoDB implementation supports multi-tenancy via namespaces:\n\n```python\n# In config.py\ndocumentdb_namespace: str = \"default\"\n\n# Collection names are automatically namespaced\n# mcp_servers_{namespace}\n# mcp_agents_{namespace}\n# etc.\n```\n\n**Use Cases:**\n- Multiple registry instances on shared DocumentDB/MongoDB cluster\n- Isolated test environments\n- Customer separation in SaaS deployments\n\n**Implementation:** [`registry/repositories/documentdb/client.py`](../../registry/repositories/documentdb/client.py)\n\n```python\ndef get_index_name(base_name: str) -> str:\n \"\"\"Get full index name with namespace.\"\"\"\n return f\"{base_name}-{settings.documentdb_namespace}\"\n```\n\n### Error Handling\n\nBoth implementations handle errors gracefully:\n\n**File Backend:**\n- Missing files → return None or empty list\n- Parse errors → log and skip\n- I/O errors → raised to caller\n\n**DocumentDB/MongoDB Backend:**\n- Connection errors → log and attempt retry\n- Index not found → initialize index\n- Query errors → log and raise\n\n### Performance Considerations\n\n**File Backend:**\n- Fast for small datasets (<1000 entities)\n- No network latency\n- FAISS search: O(n) linear scan (not scalable)\n- Not suitable for high concurrency\n\n**DocumentDB/MongoDB Backend:**\n- Scalable to millions of entities\n- Network latency (typically <100ms)\n- BM25 + k-NN: O(log n) with proper indexing\n- Built for high concurrency (lock-free reads)\n\n**Recommendations:**\n- Use file backend for development only\n- Use DocumentDB/MongoDB for production\n- Monitor DocumentDB/MongoDB query latency\n- Tune index refresh intervals for throughput vs. latency tradeoff\n\n---\n\n## Testing Strategy\n\n### Unit Tests\n\nMock repositories for unit testing:\n\n```python\nclass MockServerRepository(ServerRepositoryBase):\n \"\"\"Mock implementation for testing.\"\"\"\n\n def __init__(self):\n self.servers = {}\n\n async def get(self, path: str) -> Optional[Dict]:\n return self.servers.get(path)\n\n async def list_all(self) -> Dict:\n return self.servers.copy()\n\n # ... implement other methods ...\n```\n\n### Integration Tests\n\nUse file backend for integration tests:\n\n```python\n@pytest.fixture\ndef reset_repos():\n \"\"\"Reset repositories between tests.\"\"\"\n yield\n reset_repositories()\n\nasync def test_server_lifecycle(reset_repos):\n repo = get_server_repository()\n\n # File backend used by default\n server = {\"path\": \"/test\", \"name\": \"test_server\"}\n await repo.create(server)\n\n result = await repo.get(\"/test\")\n assert result is not None\n```\n\n### End-to-End Tests\n\nTest against MongoDB CE in Docker:\n\n```yaml\n# docker-compose.yml\nservices:\n mongodb:\n image: mongo:8.2\n command: [\"--replSet\", \"rs0\", \"--bind_ip_all\"]\n ports:\n - \"27017:27017\"\n```\n\nSet `STORAGE_BACKEND=mongodb` and run full integration tests.\n\n---\n\n## Summary\n\nThe database abstraction layer provides a **clean, extensible architecture** for data storage in the MCP Gateway Registry:\n\n| Aspect | File | DocumentDB/MongoDB |\n|--------|------|-------------------|\n| **Use Case** | Development, testing | Production |\n| **Scalability** | ~1000 entities | Millions |\n| **Dependencies** | None (+ FAISS) | DocumentDB/MongoDB cluster |\n| **Query Power** | Basic | Advanced (aggregation pipelines) |\n| **Concurrency** | Limited | High |\n| **Setup Complexity** | None | Moderate |\n| **Cost** | Free | Infrastructure cost |\n\nThe **repository pattern** with factory ensures:\n- Clean separation of concerns\n- Easy backend switching\n- Comprehensive testability\n- Consistent interfaces\n- Future extensibility\n\nAll implementations maintain **identical behavior**, making backend selection purely an operational decision rather than a code architecture choice.\n\n" }, { "path": "docs/design/federation-architecture.md", "content": "# Federation Architecture Design\n\nThis document describes the peer-to-peer federation architecture for MCP Gateway Registry instances.\n\n## Overview\n\nFederation enables multiple MCP Gateway Registry instances to share servers and agents across organizational boundaries. Unlike external registry integration (Anthropic, ASOR), peer-to-peer federation connects registry instances that run the same codebase, enabling bidirectional synchronization with fine-grained control.\n\n## Architecture Principles\n\n### Peer-to-Peer Symmetric Design\n\nThe codebase has **no concept of \"hub\" or \"spoke\"**. Every registry instance runs identical code with identical capabilities:\n\n- Any registry can be both an exporter and an importer simultaneously\n- There is no role flag, no hierarchy, no hardcoded topology\n- Terms like \"Hub\" and \"LOB\" are purely organizational labels describing deployment choices\n\n```\nSymmetric Architecture:\n\n Registry A <------> Registry B\n | |\n v v\n Registry C <------> Registry D\n\nAny registry can pull from any other registry.\nAny registry can export to any other registry.\n```\n\n### Common Deployment Patterns\n\n**Hub Pulls from LOBs (Centralized Visibility)**\n\nA central IT team maintains a Hub Registry. Each Line of Business (LOB) maintains their own registry. The Hub pulls from LOBs to provide centralized visibility.\n\n```\n LOB-A Registry LOB-B Registry LOB-C Registry\n \\ | /\n \\ | /\n Hub Registry (Central IT)\n \"Show me everything across all LOBs\"\n```\n\n**LOBs Pull from Hub (Inheritance)**\n\nLOBs inherit shared tools and agents from a central Hub.\n\n```\n Hub Registry (Central IT)\n / | \\\n / | \\\n LOB-A Registry LOB-B Registry LOB-C Registry\n \"Inherit shared tools from central\"\n```\n\n**Mesh Topology**\n\nFor organizations with peer relationships between registries.\n\n```\n Registry A <------> Registry B\n ^ ^\n | |\n v v\n Registry C <------> Registry D\n```\n\n## Data Model\n\n### Peer Registry Configuration\n\nEach peer is configured with the following attributes:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `peer_id` | string | Unique identifier for the peer (e.g., \"lob-a\", \"hub\") |\n| `name` | string | Human-readable name (e.g., \"LOB-A Registry\") |\n| `endpoint` | string | Base URL of the peer registry |\n| `enabled` | boolean | Whether sync is enabled for this peer |\n| `sync_mode` | enum | `all`, `whitelist`, or `tag_filter` |\n| `whitelist_servers` | string[] | Server paths to include (if sync_mode=whitelist) |\n| `whitelist_agents` | string[] | Agent paths to include (if sync_mode=whitelist) |\n| `tag_filters` | string[] | Tags to filter by (if sync_mode=tag_filter) |\n| `sync_interval_minutes` | int | Interval for scheduled sync (0 = manual only) |\n| `federation_token` | string | Static token for authenticating to this peer (encrypted) |\n| `expected_client_id` | string | OAuth2 client ID expected from this peer (for peer identification) |\n\n### Sync Modes\n\n**All Mode**\n```json\n{\n \"peer_id\": \"lob-a\",\n \"sync_mode\": \"all\"\n}\n```\nImports all public servers and agents from the peer.\n\n**Whitelist Mode**\n```json\n{\n \"peer_id\": \"lob-a\",\n \"sync_mode\": \"whitelist\",\n \"whitelist_servers\": [\"/critical-tool\", \"/shared-service\"],\n \"whitelist_agents\": [\"/data-analyst-agent\"]\n}\n```\nImports only the specified servers and agents.\n\n**Tag Filter Mode**\n```json\n{\n \"peer_id\": \"lob-a\",\n \"sync_mode\": \"tag_filter\",\n \"tag_filters\": [\"production\", \"shared\"]\n}\n```\nImports servers and agents that have any of the specified tags.\n\n### Visibility Control\n\nServers and agents have a `visibility` field that controls federation export:\n\n| Visibility | Behavior |\n|------------|----------|\n| `internal` | Not exported via federation (default) |\n| `public` | Exported to all authenticated peers |\n| `group-restricted` | Exported only to peers in specified groups |\n\n## Authentication\n\n### Static Token Authentication (Recommended)\n\nThe primary authentication method for federation uses static tokens. This is IdP-agnostic and works regardless of whether registries use Keycloak, Entra ID, Cognito, or no identity provider at all.\n\n**On the Exporting Registry:**\n\n```bash\n# .env on the exporting registry\nFEDERATION_STATIC_TOKEN_AUTH_ENABLED=true\nFEDERATION_STATIC_TOKEN=\n```\n\n**On the Importing Registry:**\n\n```json\n{\n \"peer_id\": \"lob-a\",\n \"endpoint\": \"https://lob-a-registry.corp.com\",\n \"federation_token\": \"\"\n}\n```\n\nThe token is encrypted using Fernet symmetric encryption before storage in MongoDB/DocumentDB.\n\n### Encryption at Rest\n\nSecrets stored in peer configurations (federation tokens, OAuth client secrets) are encrypted using Fernet (AES-128-CBC):\n\n```bash\n# Generate encryption key (one-time)\npython -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"\n\n# Set in environment\nFEDERATION_ENCRYPTION_KEY=\n```\n\nThis approach is:\n- Database-agnostic (same code for MongoDB CE and DocumentDB)\n- Simple (one env var holds the symmetric key)\n- No extra dependencies on database side\n\n### OAuth2 Client Credentials (Alternative)\n\nFor organizations requiring short-lived tokens and JWT audit trails, OAuth2 client credentials flow is supported as an alternative:\n\n```json\n{\n \"peer_id\": \"lob-external\",\n \"endpoint\": \"https://external-registry.example.com\",\n \"auth_config\": {\n \"token_endpoint\": \"https://keycloak.example.com/realms/mcp-gateway/protocol/openid-connect/token\",\n \"client_id\": \"federation-hub-m2m\",\n \"client_secret\": \"\",\n \"scope\": null\n }\n}\n```\n\nThis works with any OAuth2-compliant provider (Keycloak, Entra ID, Cognito).\n\n## Sync Process\n\n### Sync Triggers\n\nSync can be triggered in three ways:\n\n1. **Manual via API**: `POST /api/peers/{peer_id}/sync`\n2. **Manual via UI**: Click \"Sync Now\" in the Settings UI\n3. **Scheduled**: Background scheduler checks every 60 seconds and triggers sync for peers where `sync_interval_minutes > 0` and the interval has elapsed\n\n### Sync Flow\n\n```\n1. Load peer configuration from MongoDB\n2. Decrypt authentication credentials\n3. Authenticate to peer's federation export API\n4. Fetch servers and agents based on sync_mode filters\n5. Apply visibility filtering on the exporting side\n6. Store synced items with federation metadata:\n - is_federated: true\n - source_peer_id: \"lob-a\"\n - upstream_path: \"/original/path\"\n - is_read_only: true\n7. Update sync status (last_sync, generation number)\n8. Mark items not present in sync as orphaned\n```\n\n### Federation Metadata\n\nSynced servers and agents carry metadata indicating their federated origin:\n\n```json\n{\n \"name\": \"External Tool\",\n \"path\": \"/lob-a/external-tool\",\n \"sync_metadata\": {\n \"is_federated\": true,\n \"source_peer_id\": \"lob-a\",\n \"upstream_path\": \"/external-tool\",\n \"last_synced_at\": \"2026-02-05T10:30:00Z\",\n \"is_read_only\": true\n }\n}\n```\n\n### Path Namespacing\n\nSynced items are namespaced under their peer ID to prevent collisions:\n\n| Original Path (on peer) | Synced Path (on importer) |\n|------------------------|---------------------------|\n| `/my-tool` | `/lob-a/my-tool` |\n| `/data-agent` | `/lob-a/data-agent` |\n\n### Orphan Detection\n\nWhen a server or agent is removed from the upstream peer, the sync process:\n\n1. Detects the item is no longer present in the export\n2. Increments the generation number\n3. Items from previous generations are marked as orphaned\n4. Admins can review orphaned items before removal\n\n## API Endpoints\n\n### Federation Export API\n\nEndpoints exposed by registries for peers to pull data:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v1/federation/health` | GET | Health check (unauthenticated) |\n| `/api/v1/federation/servers` | GET | Export servers for sync |\n| `/api/v1/federation/agents` | GET | Export agents for sync |\n\n### Peer Management API\n\nEndpoints for managing peer configurations:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/peers` | GET | List all configured peers |\n| `/api/peers` | POST | Add a new peer |\n| `/api/peers/{peer_id}` | GET | Get peer configuration |\n| `/api/peers/{peer_id}` | PUT | Update peer configuration |\n| `/api/peers/{peer_id}` | DELETE | Remove a peer |\n| `/api/peers/{peer_id}/sync` | POST | Trigger sync for a peer |\n| `/api/peers/{peer_id}/status` | GET | Get sync status |\n| `/api/peers/{peer_id}/enable` | POST | Enable a peer |\n| `/api/peers/{peer_id}/disable` | POST | Disable a peer |\n| `/api/peers/sync` | POST | Sync all enabled peers |\n\n## Security Considerations\n\n### Principle of Least Privilege\n\nThe `FEDERATION_STATIC_TOKEN` grants access only to federation-scoped endpoints:\n\n| Accessible | Not Accessible |\n|------------|----------------|\n| `/api/v1/federation/*` | `/api/servers/*` |\n| `/api/peers/*` | `/api/agents/*` |\n| | `/api/admin/*` |\n| | `/v0.1/*` |\n\n### Token Security\n\n1. **Encryption at rest**: Tokens are Fernet-encrypted in MongoDB\n2. **Transport security**: All federation traffic uses HTTPS\n3. **Token rotation**: Admin API available for rotating tokens without restart\n4. **Revocation**: Immediate revocation via admin endpoint\n\n### Read-Only Federated Items\n\nSynced servers and agents are marked as read-only:\n- Cannot be modified through the local registry API\n- Cannot be deleted (controlled by upstream)\n- Must be managed at the source registry\n\n## Comparison with External Registry Federation\n\n| Aspect | Peer-to-Peer Federation | External Registry (Anthropic, ASOR) |\n|--------|------------------------|-------------------------------------|\n| Protocol | Same codebase, symmetric | Third-party APIs |\n| Direction | Bidirectional | Import only |\n| Authentication | Static token or OAuth2 | Provider-specific |\n| Sync control | Fine-grained (whitelist, tags) | Configuration-based |\n| Visibility | Configurable per item | All-or-nothing |\n| Path handling | Namespaced by peer_id | Tagged by source |\n\n## Related Documentation\n\n- [Federation Operational Guide](../federation-operational-guide.md) - Setup and operations\n- [Federation Guide](../federation.md) - External registry integration (Anthropic, ASOR)\n- [Static Token Auth](../static-token-auth.md) - Static token authentication\n- [Storage Architecture](storage-architecture-mongodb-documentdb.md) - Database design\n" }, { "path": "docs/design/hybrid-search-architecture.md", "content": "# Hybrid Search Architecture\n\nThis document describes the hybrid search design for MCP servers and A2A agents in the registry.\n\n## Overview\n\nThe registry implements hybrid search that combines semantic (vector) search with lexical (keyword) matching. This approach provides both conceptual understanding of queries and precise matching when users reference entities by name.\n\n## Architecture Diagram\n\n```\n +-------------------+\n | Search Query |\n | \"context7 docs\" |\n +--------+----------+\n |\n +-----------------+-----------------+\n | |\n v v\n +------------------+ +-------------------+\n | Query Embedding | | Query Tokenizer |\n | (Vector Model) | | (Keyword Extract)|\n +--------+---------+ +---------+---------+\n | |\n | [0.12, -0.34, ...] | [\"context7\", \"docs\"]\n | |\n v v\n +------------------+ +-------------------+\n | Vector Search | | Keyword Match |\n | (Cosine Sim) | | (Regex on path, |\n | | | name, desc, |\n | | | tags, metadata, |\n | | | tools) |\n +--------+---------+ +---------+---------+\n | |\n | semantic_score | text_boost\n | |\n +----------------+------------------+\n |\n v\n +---------------------+\n | Score Combination |\n | relevance_score = |\n | semantic + boost |\n +----------+----------+\n |\n v\n +---------------------+\n | Result Distribution|\n | Global ranking |\n | with competitive |\n | soft caps (60%) |\n | up to max_results |\n +----------+----------+\n |\n v\n +---------------------+\n | Result Grouping |\n | - servers |\n | - agents |\n | - virtual_servers |\n | - skills |\n +----------+----------+\n |\n v\n +---------------------+\n | Tool Extraction |\n | Extract matching |\n | tools from servers |\n | -> tools[] |\n +---------------------+\n```\n\n## Search Flow\n\n### 1. Query Processing\n\nWhen a search query arrives:\n\n1. **Embedding Generation**: Query is converted to a vector embedding using the configured model (Amazon Bedrock, OpenAI, or local sentence-transformers)\n\n2. **Tokenization**: Query is split into meaningful keywords\n - Non-word characters are removed\n - Stopwords filtered (a, the, is, are, etc.)\n - Tokens shorter than 3 characters removed\n\n### 2. Dual Search Strategy\n\n**Vector Search (Semantic)**\n- Uses HNSW index on DocumentDB (production) or application-level cosine similarity on MongoDB CE\n- Finds conceptually similar content even with different wording\n- Returns results sorted by cosine similarity\n- DocumentDB uses configurable `efSearch` parameter (default 100) for HNSW recall quality\n- Minimum `k=50` ensures small collections are fully covered\n\n**Keyword Search (Lexical)**\n- Regex matching on path, name, description, tags, metadata_text, and tool names/descriptions\n- Catches explicit references that semantic search might miss\n- Runs as separate query due to DocumentDB limitations (no `$unionWith` support)\n- Each query keyword is matched independently using case-insensitive regex\n- Keyword matches from both vector results and separate keyword query are merged, with the highest boost per document kept\n\n### 3. Score Combination\n\nThe final relevance score combines both approaches:\n\n```\nnormalized_vector_score = (cosine_similarity + 1.0) / 2.0 # Map [-1,1] to [0,1]\ntext_boost_contribution = text_boost * 0.1 # Scale boost down\nrelevance_score = normalized_vector_score + text_boost_contribution\nrelevance_score = clamp(relevance_score, 0.0, 1.0)\n```\n\nThe multiplier `0.1` is consistent across both DocumentDB and MongoDB CE search paths.\n\nText boost values (cumulative per keyword match):\n| Match Location | Boost Value |\n|----------------|-------------|\n| Path | +5.0 |\n| Name | +3.0 |\n| Description | +2.0 |\n| Tags | +1.5 |\n| Metadata | +1.0 |\n| Tool (each) | +1.0 |\n\n### 4. Score-Before-Filter Pattern\n\nAll candidate results are scored before applying the distribution filter. This ensures the highest-scoring documents are selected:\n\n1. Vector search returns candidates (up to `k` results)\n2. Keyword search returns additional matches (merged by highest boost per document)\n3. Every candidate receives a hybrid score (vector + text boost)\n4. All candidates are sorted by hybrid score descending\n5. The `_distribute_results()` function selects up to `max_results` items using global ranking with competitive soft caps (see [Result Distribution](#result-distribution) below)\n\nThis prevents lower-scoring documents from consuming a slot before higher-scoring documents are evaluated.\n\n### 5. Diagnostic Logging\n\nBoth search paths emit a `Score for` log line for every candidate, enabling search quality debugging:\n\n```\nScore for 'Context7' (type=mcp_server): vector=0.3412, normalized_vector=0.6706,\n text_boost=8.0, boost_contrib=0.8000, final=1.0000\n```\n\n### 6. Result Distribution\n\nThe `max_results` parameter (range 1-50, default 10) controls how many total results are returned. Results are distributed across entity types using **global ranking with competitive soft caps**.\n\n#### Algorithm\n\nThe `_distribute_results()` function in `search_repository.py` implements a two-pass approach:\n\n**Pass 1 -- Pick with soft caps:**\n1. Sort all scored candidates by `relevance_score` descending (all entity types on the same 0-1 scale)\n2. Walk the sorted list, picking items up to `max_results`\n3. If a type reaches its soft cap (`ceil(max_results * 0.6)`), check whether other entity types still have results remaining below in the ranking\n4. If other types are waiting: skip this item (enforce cap for diversity)\n5. If no other types remain: lift the cap (no point leaving slots empty)\n\n**Pass 2 -- Backfill:**\n6. If pass 1 didn't fill all `max_results` slots (because some items were skipped), backfill from the skipped items in score order\n\n#### Constants\n\n| Constant | Value | Description |\n|----------|-------|-------------|\n| `SOFT_CAP_RATIO` | `0.6` | No single entity type can claim more than 60% of slots when other types are competing |\n| Tool extraction limit | `max(3, ceil(max_results * 0.6))` | Scales tool extraction with `max_results`, minimum 3 for backward compatibility |\n| Pipeline candidate limit | `max(max_results * 3, 50)` | Fetch enough candidates for global ranking |\n\n#### Examples\n\n**Example 1: Only servers exist (max_results=10)**\n\nA registry with 20 MCP servers and no agents, tools, or skills.\n\n```\nCandidates (sorted by relevance_score):\n S(0.95), S(0.93), S(0.91), S(0.89), S(0.87), S(0.85),\n S(0.83), S(0.81), S(0.79), S(0.77), S(0.75), ...\n\nsoft_cap = ceil(10 * 0.6) = 6\n\nPass 1:\n Pick S(0.95) ... S(0.85) -> 6 servers (cap reached)\n S(0.83): cap hit, check remaining types -> only mcp_server left\n -> no competition, cap lifted\n Pick S(0.83) ... S(0.77) -> 4 more servers\n\nResult: 10 servers (no artificial limit when only one type exists)\n```\n\n**Example 2: Mixed types (max_results=10)**\n\nA registry with servers, agents, and tools.\n\n```\nCandidates (sorted by relevance_score):\n S(0.95), S(0.93), S(0.91), A(0.88), S(0.87), T(0.85),\n S(0.83), A(0.80), S(0.78), T(0.75), A(0.72), S(0.70)\n\nsoft_cap = ceil(10 * 0.6) = 6\n\nPass 1:\n Pick S(0.95), S(0.93), S(0.91) -> 3 servers\n Pick A(0.88) -> 1 agent\n Pick S(0.87), T(0.85), S(0.83), A(0.80) -> 2 more servers, 1 tool, 1 agent\n Pick S(0.78) -> 6th server (cap reached)\n T(0.75): pick -> 2nd tool\n A(0.72): pick -> 10th total (done)\n\nResult: 6 servers, 3 agents, 1 tool = 10 total\n (diverse results, highest relevance wins, cap prevents server dominance)\n```\n\n**Example 3: Small max_results (max_results=5)**\n\n```\nsoft_cap = ceil(5 * 0.6) = 3\n\nWith mixed types, the dominant type gets at most 3 slots,\nleaving 2 for other types. Similar diversity to the previous\ndefault behavior of 3 per type.\n```\n\n**Example 4: Large max_results with one dominant type (max_results=50)**\n\nA registry with 40 servers, 3 agents, and 2 tools.\n\n```\nsoft_cap = ceil(50 * 0.6) = 30\n\nPass 1:\n Servers fill 30 slots (cap reached while agents/tools still available)\n 3 agents and 2 tools fill 5 slots\n Cap lifted for servers (no more agents/tools)\n 12 more servers fill remaining slots\n\nResult: 42 servers, 3 agents, 2 tools = 47 total\n (all available entities returned, servers got the rest)\n```\n\n#### Backward Compatibility\n\nWith the default `max_results=10`, the soft cap is 6. In a typical registry with multiple entity types, results look similar to the previous 3-per-type behavior: the dominant type gets 5-6 results, others share the rest. The key difference is that `max_results=50` now actually returns up to 50 results instead of being capped at 15 (3 per type * 5 types).\n\n#### Applies to All Search Paths\n\nThe same `_distribute_results()` function is used by all three search code paths:\n\n| Search Path | When Used | Integration |\n|-------------|-----------|-------------|\n| Hybrid (DocumentDB) | Production with vector index | Scored tuples fed directly to `_distribute_results()` |\n| Client-side (MongoDB CE) | Local dev without vector search | Dict results converted to tuples, then distributed |\n| Lexical-only | When embedding model unavailable | Scores computed from `text_boost / MAX_LEXICAL_BOOST`, then distributed |\n\n### 7. Result Structure\n\nSearch returns grouped results (up to `max_results` total, distributed across entity types):\n\n```json\n{\n \"servers\": [\n {\n \"path\": \"/context7\",\n \"server_name\": \"Context7 MCP Server\",\n \"relevance_score\": 1.0,\n \"matching_tools\": [\n {\"tool_name\": \"query-docs\", \"description\": \"...\"}\n ]\n }\n ],\n \"tools\": [\n {\n \"server_path\": \"/context7\",\n \"tool_name\": \"query-docs\",\n \"inputSchema\": {...}\n }\n ],\n \"agents\": [...],\n \"virtual_servers\": [\n {\n \"path\": \"/virtual/dev-tools\",\n \"server_name\": \"Dev Tools\",\n \"relevance_score\": 0.85,\n \"backend_paths\": [\"/github\", \"/jira\"],\n \"tool_count\": 5\n }\n ],\n \"skills\": [...]\n}\n```\n\n## Entity Types\n\n### MCP Servers\n\n**What's included in the embedding:**\n- Server name\n- Server description\n- Tags (prefixed with \"Tags: \")\n- Metadata text (flattened key-value pairs from server metadata)\n- Tool names (each tool's name)\n- Tool descriptions (each tool's description)\n\n**What's NOT included in the embedding:**\n- Tool inputSchema (JSON schema is stored but not embedded)\n- Server path\n\n**Stored document fields:**\n- `path`, `name`, `description`, `tags`, `is_enabled`\n- `metadata_text` (flattened metadata for keyword search)\n- `tools[]` array with `name`, `description`, `inputSchema` per tool\n- `embedding` vector\n- `metadata` (full server info for reference)\n\n### A2A Agents\n\n**What's included in the embedding:**\n- Agent name\n- Agent description\n- Tags (prefixed with \"Tags: \")\n- Capabilities (prefixed with \"Capabilities: \")\n- Metadata text (flattened key-value pairs from agent card metadata)\n- Skill names (each skill's name)\n- Skill descriptions (each skill's description)\n\n**What's NOT included in the embedding:**\n- Agent path\n- Skill IDs, tags, and examples\n\n**Stored document fields:**\n- `path`, `name`, `description`, `tags`, `is_enabled`\n- `metadata_text` (flattened metadata for keyword search)\n- `capabilities[]` array\n- `embedding` vector\n- `metadata` (full agent card for reference)\n\n### Agent Skills\n\n**What's included in the embedding:**\n- Skill name\n- Skill description\n- Tags (prefixed with \"Tags: \")\n- Metadata text (author, version, custom extra key-value pairs)\n\n**Stored document fields:**\n- `path`, `name`, `description`, `tags`, `is_enabled`\n- `metadata_text` (author, version, flattened `extra` dict, registry_name for keyword search)\n- `embedding` vector\n- `metadata` (skill metadata for reference)\n\n### Tools\n\n- Not indexed separately - extracted from parent server documents\n- When a server matches, its tools are checked for keyword matches\n- Top-level `tools[]` array contains full schema (inputSchema)\n- `matching_tools` in server results is a lightweight reference (no schema)\n\n### Virtual MCP Servers\n\nVirtual MCP Servers are indexed in the unified `mcp_embeddings_{dimensions}` collection (e.g., `mcp_embeddings_384` for 384-dimension models) alongside regular servers and agents, distinguished by `entity_type: \"virtual_server\"`.\n\n**What's included in the embedding:**\n- Server name\n- Server description\n- Tags (prefixed with \"Tags: \")\n- Tool names (alias or original name from each tool mapping)\n- Tool description overrides (if specified in mappings)\n\n**What's NOT included in the embedding:**\n- Virtual server path\n- Backend server paths\n- Required scopes\n- Tool input schemas\n\n**Stored document fields:**\n- `path`, `name`, `description`, `tags`, `is_enabled`\n- `entity_type`: `\"virtual_server\"`\n- `metadata_text` (created_by for keyword search)\n- `tools[]` array with `name` (alias or original) per tool mapping\n- `embedding` vector\n- `metadata` object containing:\n - `server_name`, `num_tools`, `backend_count`\n - `backend_paths[]` (list of backend server paths)\n - `required_scopes[]`, `supported_transports[]`\n - `created_by`\n\n**Search result structure:**\n```json\n{\n \"virtual_servers\": [\n {\n \"entity_type\": \"virtual_server\",\n \"path\": \"/virtual/dev-tools\",\n \"server_name\": \"Dev Tools\",\n \"description\": \"Aggregated development tools\",\n \"relevance_score\": 0.85,\n \"tags\": [\"development\", \"tools\"],\n \"backend_paths\": [\"/github\", \"/jira\"],\n \"tool_count\": 5,\n \"matching_tools\": [\n {\"tool_name\": \"github_search\"}\n ]\n }\n ]\n}\n```\n\n## Metadata in Search\n\nCustom metadata from servers, agents, skills, and virtual servers is included in semantic embeddings, hybrid/keyword search, and the REST API list endpoint keyword filters. Metadata is flattened to a text string using `flatten_metadata_to_text()` (defined in `registry/utils/metadata.py`):\n\n- Each key name is included as a token\n- Scalar values are converted to strings\n- List values have each item converted to a string\n- Nested dict values have each value converted to a string\n\nFor example, a server with metadata `{\"source\": \"agentcore-sync\", \"region\": \"us-east-1\"}` produces the metadata text: `source agentcore-sync region us-east-1`.\n\n### Hybrid / DocumentDB Search\n\nThe flattened metadata text is:\n1. Appended to `text_for_embedding` so semantic search captures metadata meaning\n2. Stored in `metadata_text` field for keyword/regex matching\n3. Matched in the `$or` keyword filter alongside path, name, description, tags, and tools\n4. Scored with +1.0 text boost when matched in the `_build_text_boost_stage` pipeline\n\n### REST API List Endpoint Keyword Search (Pure Lexical, No Vectors)\n\nThe REST API list endpoints below are **pure lexical search**. They do not use embeddings, vector similarity, or the DocumentDB search index. They load all items from storage, build a searchable text string per item in Python, and perform a case-insensitive substring match. No hybrid or semantic search is involved.\n\nThe same `flatten_metadata_to_text()` utility is used to include metadata in these filters:\n\n| Endpoint | Parameter | Search Type | Metadata Handling |\n|----------|-----------|-------------|-------------------|\n| `GET /api/agents?query=` | `query` | Substring match (lexical only) | Metadata appended to `searchable_text` |\n| `GET /api/servers?query=` | `query` | Substring match (lexical only) | Metadata appended to `searchable_text` |\n| `GET /api/skills/search?q=` | `q` | Scored substring match (lexical only) | Metadata matched with +0.1 relevance score (author, version, extra) |\n\nFor hybrid (vector + keyword) search, use `POST /api/search/semantic` instead.\n\n### Metadata Sources\n\n| Entity Type | Metadata Source |\n|----------------|-----------------|\n| MCP Server | `server_info.get(\"metadata\", {})` |\n| A2A Agent | `agent_card.metadata` |\n| Agent Skill | Author, version, `extra` dict (custom key-value pairs), registry_name |\n| Virtual Server | `created_by` field |\n\n## Backend Implementations\n\n### DocumentDB (Production)\n- Native HNSW vector index with `$search` aggregation pipeline\n- Keyword query runs separately and merges results (no `$unionWith` support)\n- Text boost calculated in aggregation pipeline using `$regexMatch`\n\n### MongoDB CE (Development/Local)\n- No native vector search support (`$vectorSearch` not available)\n- Falls back to application-level search (in Python backend, not the calling agent):\n 1. Fetch all documents with embeddings from collection\n 2. Calculate cosine similarity in Python code\n 3. Apply keyword matching and text boost in application\n 4. Sort and limit results\n- Same API contract as DocumentDB implementation\n\n## Lexical Fallback Mode\n\nWhen the embedding model is unavailable (misconfigured, network issues, API key expired, model not found), the search system automatically degrades to **lexical-only mode** instead of failing entirely.\n\n### How It Works\n\n1. **Detection**: On the first search request, if the embedding model fails to generate a query vector, the `_embedding_unavailable` flag is set in `DocumentDBSearchRepository`\n2. **Fallback**: All subsequent searches skip embedding generation and use `_lexical_only_search()` instead\n3. **Error Caching**: The `SentenceTransformersClient` caches load errors in `_load_error` to avoid repeated download attempts (e.g., hitting HuggingFace on every call)\n4. **Indexing**: When the model is unavailable during startup, servers and agents are indexed without embeddings. Documents are stored with empty embedding vectors\n5. **Response**: The API response includes a `search_mode` field set to `\"lexical-only\"` (instead of the normal `\"hybrid\"`) so callers know the search quality is reduced\n\n### Lexical-Only Search Flow\n\n```\n +-------------------+\n | Search Query |\n | \"context7 docs\" |\n +--------+----------+\n |\n v\n +-----------------------+\n | Embedding Model Check |\n | _embedding_unavailable|\n | == True? |\n +-----------+-----------+\n |\n Yes (fallback)\n |\n v\n +-----------------------+\n | Keyword Tokenization |\n | [\"context7\", \"docs\"] |\n +-----------+-----------+\n |\n v\n +-----------------------+\n | MongoDB Aggregation |\n | $regexMatch on path, |\n | name, description, |\n | tags, metadata, |\n | tools |\n +-----------+-----------+\n |\n v\n +-----------------------+\n | Text Boost Scoring |\n | Normalized by |\n | MAX_LEXICAL_BOOST |\n | (12.5) |\n +-----------+-----------+\n |\n v\n +-----------------------+\n | Result Grouping |\n | search_mode: |\n | \"lexical-only\" |\n +-----------------------+\n```\n\n### Scoring in Lexical-Only Mode\n\nIn lexical-only mode, the text boost score is normalized to a 0-1 range using a fixed denominator (`MAX_LEXICAL_BOOST = 13.5`):\n\n```\nrelevance_score = text_boost / MAX_LEXICAL_BOOST\n```\n\nThe same boost weights from hybrid mode apply:\n\n| Match Location | Boost Value |\n|----------------|-------------|\n| Path | +5.0 |\n| Name | +3.0 |\n| Description | +2.0 |\n| Tags | +1.5 |\n| Metadata | +1.0 |\n| Tool (each) | +1.0 |\n\n### Recovery\n\nWhen the embedding model becomes available again (e.g., after a restart with correct configuration), the system automatically returns to full hybrid search mode. The `_embedding_unavailable` flag and `_load_error` cache are per-process and reset on restart.\n\n## HNSW Tuning (DocumentDB)\n\nThe DocumentDB `$search` pipeline includes two tunable parameters:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `k` | `max(max_results * 3, 50)` | Number of nearest neighbors to retrieve. Minimum 50 ensures small collections are fully covered. |\n| `efSearch` | `100` (configurable via `VECTOR_SEARCH_EF_SEARCH`) | Controls HNSW recall quality. Higher values improve recall at the cost of query latency. Default DocumentDB value is ~40, which can miss documents in small collections. |\n\nThe `efSearch` setting is configured in `registry/core/config.py` as `vector_search_ef_search`.\n\n## Lifecycle Status Filtering\n\nSearch results respect the lifecycle status of assets (servers, agents, skills). By default, **deprecated** and **draft** assets are excluded from search results. Only **active** and **beta** assets appear.\n\n### How It Works\n\n1. **Index-Time**: When an asset is indexed for search, its `status` field is stored in the search document alongside other fields (`path`, `name`, `description`, `tags`, `is_enabled`, etc.)\n\n2. **Query-Time**: The `_build_status_filter()` function constructs a MongoDB `$match` filter that excludes assets by lifecycle status:\n\n```python\n# Default behavior: exclude deprecated and draft\n{\n \"$or\": [\n {\"status\": {\"$nin\": [\"deprecated\", \"draft\"]}},\n {\"status\": {\"$exists\": False}} # Treat missing field as active\n ]\n}\n```\n\n3. **Opt-In Inclusion**: Callers can include filtered assets using request parameters:\n - `include_deprecated: true` -- Include deprecated assets in results\n - `include_draft: true` -- Include draft assets in results\n - `include_disabled: true` -- Include disabled assets (is_enabled=False) in results\n\n### Search Request Example\n\n```json\n{\n \"query\": \"feature flags\",\n \"entity_types\": [\"skill\"],\n \"max_results\": 10,\n \"include_deprecated\": true,\n \"include_draft\": false\n}\n```\n\n### Status Values\n\n| Status | Default in Search | Description |\n|--------|-------------------|-------------|\n| `active` | Included | Asset is active and ready for use |\n| `beta` | Included | Asset is in beta testing phase |\n| `deprecated` | **Excluded** | Asset is deprecated and may be removed |\n| `draft` | **Excluded** | Asset is in draft mode, not ready for production |\n\n### Indexed Document Fields\n\nThe `status` field is stored in the search document for all entity types:\n\n| Entity Type | Status Source |\n|-------------|--------------|\n| MCP Server | `server_info.get(\"status\", \"active\")` |\n| A2A Agent | `agent_card.status` (default: `\"active\"`) |\n| Agent Skill | `skill.status` (default: `\"active\"`) |\n| Virtual Server | Not applicable (always active) |\n\nDocuments indexed before this feature (without a `status` field) are treated as `active` by the `$exists: False` fallback in the filter.\n\n### Filter Application\n\nThe status filter is applied consistently across all three search code paths:\n\n| Search Path | Filter Location |\n|-------------|-----------------|\n| Hybrid (DocumentDB) | Pre-filter in `$search` pipeline via `_build_status_filter()` |\n| Client-side (MongoDB CE) | Query filter in `collection.find()` |\n| Lexical-only | Aggregation `$match` stage |\n\n### Re-indexing\n\nWhen an asset's lifecycle status changes (e.g., from `active` to `deprecated`), the asset is re-indexed via the normal update flow. The search document's `status` field is updated, and subsequent searches will respect the new status.\n\n## Performance Considerations\n\n1. **Result Distribution**: Global ranking with competitive soft caps limits results to `max_results` (default 10, max 50). The distribution algorithm is O(n) where n is the candidate set size (at most 150 documents).\n2. **Score-Before-Filter**: All candidates scored and sorted before applying the distribution filter\n3. **Index Reuse**: HNSW index parameters (m=16, efConstruction=128) optimized for recall\n4. **efSearch Tuning**: Set to 100 for near-exact recall in typical deployments\n5. **Embedding Caching**: Lazy-loaded model with singleton pattern\n6. **Keyword Fallback**: Separate query ensures explicit matches are not missed\n7. **Error Caching**: Failed model loads are cached to avoid repeated download/API attempts\n\n## Example: Why Hybrid Matters\n\nQuery: \"context7\"\n\n- **Vector-only**: Might return documentation servers with similar semantic content\n- **Keyword-only**: Finds exact match but misses related servers\n- **Hybrid**: Ranks /context7 at top (keyword boost) while including semantically similar alternatives\n" }, { "path": "docs/design/idp-provider-support.md", "content": "# Multi-Provider Identity Provider (IdP) Support\n\n**Version:** 1.0\n**Last Updated:** 2026-01-18\n\n## Related Documentation\n\n- [Authentication Design](./authentication-design.md) - Auth flows for human users, programmatic access, and M2M workloads\n- [Authentication & Authorization Guide](../auth.md) - Operational guide with setup instructions\n- [Microsoft Entra ID Integration](../entra.md) - Entra ID-specific setup and configuration\n- [Okta Integration](../okta-setup.md) - Okta-specific setup and configuration\n\n## Overview\n\nThe MCP Gateway Registry supports multiple identity providers (IdPs) through a pluggable architecture. This design enables organizations to use their existing enterprise identity infrastructure (Keycloak, Microsoft Entra ID, Okta) for authentication and authorization.\n\n## Architecture\n\n### High-Level Component Diagram\n\n```\n+------------------+ +------------------+ +------------------+\n| | | | | |\n| Registry UI | | CLI Tools | | AI Agents |\n| (Frontend) | | (registry_mgmt) | | (M2M Clients) |\n| | | | | |\n+--------+---------+ +--------+---------+ +--------+---------+\n | | |\n | HTTP + JWT Token | HTTP + JWT Token |\n | | |\n v v v\n+--------+------------------------+------------------------+---------+\n| |\n| NGINX Gateway |\n| (auth_request /validate) |\n| |\n+--------+-----------------------------------------------------------+\n |\n | /validate\n v\n+--------+-----------------------------------------------------------+\n| |\n| Auth Server |\n| |\n| +----------------+ +------------------+ +----------------+ |\n| | | | | | | |\n| | AuthProvider | | AuthProvider | | AuthProvider | |\n| | Factory +--->+ Protocol +--->+ Implementations| |\n| | | | (Base Class) | | | |\n| +----------------+ +------------------+ +----------------+ |\n| | |\n| +----------------+---------+--------+ |\n| | | | |\n| v v v |\n| +------+------+ +------+------+ +--------+-+ |\n| | | | | | | |\n| | Keycloak | | Entra ID | | Okta | |\n| | Provider | | Provider | | Provider | |\n| | | | | | | |\n| +-------------+ +-------------+ +-----------+ |\n| |\n+--------------------------------------------------------------------+\n |\n | Group-to-Scope Mapping\n v\n+--------+-----------------------------------------------------------+\n| |\n| MongoDB-CE / Amazon DocumentDB |\n| |\n| +---------------------------+ +---------------------------+ |\n| | mcp_scopes_default | | mcp_servers_default | |\n| | | | | |\n| | - scope definitions | | - server configurations | |\n| | - group_mappings | | - tool definitions | |\n| | - server_access rules | | | |\n| | - ui_permissions | | | |\n| +---------------------------+ +---------------------------+ |\n| |\n+--------------------------------------------------------------------+\n```\n\n## Provider Selection\n\nThe active identity provider is determined by the `AUTH_PROVIDER` environment variable:\n\n```\nAUTH_PROVIDER=keycloak # Use Keycloak\nAUTH_PROVIDER=entra # Use Microsoft Entra ID\nAUTH_PROVIDER=okta # Use Okta\n```\n\n### Provider Factory Pattern\n\n```\n+-------------------+ +--------------------------+\n| | | |\n| AUTH_PROVIDER env +---->+ AuthProviderFactory |\n| | | |\n+-------------------+ +------------+-------------+\n |\n +----------------------+----------------------+\n | | |\n v v v\n +-------------------+ +-----------------------+ +-----------------------+\n | | | | | |\n | KeycloakProvider | | EntraIdProvider | | OktaProvider |\n | | | | | |\n | - OIDC endpoints | | - Microsoft Graph API | | - Okta OAuth2/OIDC |\n | - JWKS validation | | - JWKS validation | | - JWKS validation |\n | - Realm-based | | - Tenant-based | | - Domain-based |\n | | | | | |\n +-------------------+ +-----------------------+ +-----------------------+\n```\n\n## IAM Manager Interface\n\nFor administrative operations (user/group CRUD), the system uses the IAM Manager abstraction:\n\n```python\n@runtime_checkable\nclass IAMManager(Protocol):\n \"\"\"Protocol defining the IAM manager interface.\"\"\"\n\n async def list_users(\n self,\n search: str | None = None,\n max_results: int = 500,\n include_groups: bool = True\n ) -> list[dict[str, Any]]: ...\n\n async def create_human_user(\n self,\n username: str,\n email: str,\n first_name: str,\n last_name: str,\n groups: list[str],\n password: str | None = None,\n ) -> dict[str, Any]: ...\n\n async def delete_user(self, username: str) -> bool: ...\n\n async def list_groups(self) -> list[dict[str, Any]]: ...\n\n async def create_group(\n self,\n group_name: str,\n description: str = \"\"\n ) -> dict[str, Any]: ...\n\n async def delete_group(self, group_name: str) -> bool: ...\n\n async def create_service_account(\n self,\n client_id: str,\n groups: list[str],\n description: str | None = None\n ) -> dict[str, Any]: ...\n```\n\n### Implementation Classes\n\n```\n+------------------+ +------------------+ +------------------+\n| | | | | |\n| KeycloakIAM | | EntraIAM | | OktaIAM |\n| Manager | | Manager | | Manager |\n| | | | | |\n+--------+---------+ +--------+---------+ +--------+---------+\n | | |\n | Delegates to | Delegates to | Delegates to\n v v v\n+--------+---------+ +--------+---------+ +--------+---------+\n| | | | | |\n| keycloak_manager | | entra_manager | | okta_manager |\n| .py | | .py | | .py |\n| | | | | |\n| - Keycloak Admin | | - Microsoft | | - Okta Admin |\n| REST API | | Graph API | | REST API |\n| - Realm mgmt | | - App registr. | | - SSWS auth |\n| - Client mgmt | | - Service | | - OIDC service |\n| | | principals | | apps |\n+------------------+ +------------------+ +------------------+\n```\n\n## Provider-Specific Details\n\n### Keycloak Provider\n\n**Authentication Flow:**\n- Uses OIDC Authorization Code flow\n- Tokens issued by Keycloak realm\n- JWKS endpoint: `{keycloak_url}/realms/{realm}/protocol/openid-connect/certs`\n\n**Group Identifier in Tokens:**\n- Group names (e.g., `registry-admins`, `public-mcp-users`)\n- Stored in `groups` claim of JWT\n\n**IAM Operations:**\n- Uses Keycloak Admin REST API\n- Requires admin credentials or service account with realm-admin role\n\n### Microsoft Entra ID Provider\n\n**Authentication Flow:**\n- Uses OAuth2 Authorization Code flow (users)\n- Uses OAuth2 Client Credentials flow (M2M)\n- Tokens issued by Microsoft STS\n- JWKS endpoint: `https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys`\n\n**Group Identifier in Tokens:**\n- Group Object IDs (GUIDs) like `5f605d68-06bc-4208-b992-bb378eee12c5`\n- Stored in `groups` claim of JWT\n- Object IDs must be mapped to scope names in MongoDB\n\n**IAM Operations:**\n- Uses Microsoft Graph API\n- Requires App Registration with appropriate permissions:\n - `Application.ReadWrite.All`\n - `Directory.ReadWrite.All`\n - `Group.ReadWrite.All`\n - `User.ReadWrite.All`\n\n### Okta Provider\n\n**Authentication Flow:**\n- Uses OAuth2 Authorization Code flow (users)\n- Uses OAuth2 Client Credentials flow (M2M)\n- Tokens issued by Okta org authorization server\n- JWKS endpoint: `https://{okta_domain}/oauth2/v1/keys`\n\n**Group Identifier in Tokens:**\n- Group names (e.g., `mcp-admin`, `mcp-user`) — similar to Keycloak\n- Stored in `groups` claim of JWT\n- Requires groups claim to be configured in the Okta Authorization Server\n\n**Key Differences from Other Providers:**\n- Single issuer format: `https://{okta_domain}` (unlike Entra ID's dual v1.0/v2.0)\n- Uses `scp` claim for scopes in access tokens (fallback to `scope`)\n- Uses `cid` claim for client ID\n- Admin API uses a separate API token (`SSWS` scheme), not OAuth2 credentials\n\n**IAM Operations:**\n- Uses Okta Admin REST API (`/api/v1/*`)\n- Requires dedicated API token (`OKTA_API_TOKEN`) with `SSWS` authorization\n- User deletion requires deactivate-then-delete two-step flow\n- See [Okta Setup Guide](../okta-setup.md) for configuration details\n\n## Group-to-Scope Mapping\n\nThe mapping between IdP groups and registry scopes is stored in MongoDB-CE/Amazon DocumentDB (`mcp_scopes_default` collection):\n\n```\n+---------------------------------------------------+\n| MongoDB-CE/Amazon DocumentDB: mcp_scopes_default |\n+---------------------------------------------------+\n| Document Structure: |\n| |\n| { |\n| \"_id\": \"registry-admins\", | <-- Scope name\n| \"group_mappings\": [ |\n| \"registry-admins\", | <-- Keycloak group name\n| \"4c46ec66-a4f7-4b62-9095-...\" | <-- Entra ID group Object ID\n| ], |\n| \"server_access\": [ ... ], | <-- MCP server permissions\n| \"ui_permissions\": { ... } | <-- UI feature access\n| } |\n+-------------------------------------------+\n```\n\n### Mapping Flow\n\n```\n+------------------+ +------------------+ +------------------+\n| | | | | |\n| JWT Token | | Scope | | Access |\n| from IdP +---->+ Repository +---->+ Decision |\n| | | | | |\n+------------------+ +------------------+ +------------------+\n | | |\n | groups claim: | Query: | Result:\n | [\"5f605d68-...\"] | Find scopes where | scopes=[\"public-\n | | group_mappings | mcp-users\"]\n | | contains \"5f605d68-\" |\n v v v\n\nKeycloak example: Entra ID example:\ngroups: [\"public-mcp-users\"] groups: [\"5f605d68-06bc-4208-b992-bb378eee12c5\"]\n | |\n +------------------------------+\n |\n v\n +-------+-------+\n | |\n | Mapped to: |\n | public-mcp- |\n | users scope |\n | |\n +---------------+\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Provider Selection\nAUTH_PROVIDER=entra # or \"keycloak\" or \"okta\"\n\n# Keycloak Configuration\nKEYCLOAK_URL=https://keycloak.example.com\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_CLIENT_ID=mcp-registry\nKEYCLOAK_CLIENT_SECRET=...\n\n# Entra ID Configuration\nENTRA_TENANT_ID=6e6ee81b-6bf3-495d-a7fc-d363a551f765\nENTRA_CLIENT_ID=1bd17ba1-aad3-447f-be0b-26f8f9ee859f\nENTRA_CLIENT_SECRET=...\n\n# Okta Configuration\nOKTA_DOMAIN=dev-123456.okta.com\nOKTA_CLIENT_ID=0oa1234567890abcdef\nOKTA_CLIENT_SECRET=...\n# OKTA_M2M_CLIENT_ID=... # Optional separate M2M credentials\n# OKTA_M2M_CLIENT_SECRET=...\n# OKTA_API_TOKEN=... # Optional, for IAM operations\n\n# Token Validation\nSECRET_KEY=... # For self-signed tokens\nJWT_ISSUER=mcp-auth-server\nJWT_AUDIENCE=mcp-registry\n```\n\n### Scopes Configuration (scopes.yml or MongoDB)\n\n```yaml\n# Group mappings - maps IdP group identifiers to scope names\ngroup_mappings:\n # Entra ID uses Object IDs (GUIDs)\n \"4c46ec66-a4f7-4b62-9095-b7958662f4b6\":\n - registry-admins\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n\n \"5f605d68-06bc-4208-b992-bb378eee12c5\":\n - public-mcp-users\n\n # Keycloak uses group names\n \"registry-admins\":\n - registry-admins\n\n \"public-mcp-users\":\n - public-mcp-users\n\n # Okta also uses group names (same format as Keycloak)\n \"mcp-admin\":\n - registry-admins\n\n \"mcp-user\":\n - public-mcp-users\n```\n\n## Adding a New Provider\n\nTo add support for a new identity provider:\n\n1. **Create Provider Class** (`auth_server/providers/new_provider.py`):\n - Implement `AuthProvider` base class\n - Handle OIDC/OAuth2 flows\n - Implement token validation via JWKS\n\n2. **Create IAM Manager** (`registry/utils/new_provider_manager.py`):\n - Implement user/group CRUD operations\n - Handle provider-specific API calls\n\n3. **Update Factory** (`registry/utils/iam_manager.py`):\n - Add new provider case to `get_iam_manager()`\n\n4. **Update Auth Factory** (`auth_server/providers/factory.py`):\n - Add new provider case to factory function\n\n5. **Configure Group Mappings**:\n - Add group identifiers to `scopes.yml` or MongoDB-CE/Amazon DocumentDB\n - Document group identifier format (names vs IDs)\n\n## Security Considerations\n\n1. **Token Validation**: Always validate JWT signatures against provider JWKS\n2. **Admin Credentials**: Store IdP admin credentials securely (environment variables, secrets manager)\n3. **Principle of Least Privilege**: Request minimal permissions for IAM operations\n4. **Eventual Consistency**: Handle Entra ID's eventual consistency with retry logic\n5. **Token Expiry**: Respect token expiration times; implement refresh where needed\n" }, { "path": "docs/design/server-versioning.md", "content": "# MCP Server Version Routing - Design Document\n\n**Date**: 2026-01-29\n**Status**: Implemented\n**Issue**: [#370](https://github.com/agentic-community/mcp-gateway-registry/issues/370)\n\n---\n\n## 1. Overview\n\nMCP Server Version Routing enables **multiple versions of the same MCP server** to run simultaneously behind a single gateway endpoint. Traffic routes to the active (default) version unless a client explicitly requests a specific version via the `X-MCP-Server-Version` HTTP header.\n\n### Use Cases\n\n- **Canary deployments**: Register a new version as inactive, test it with the version header, then promote it to active\n- **Version pinning**: Clients that depend on a specific server version can pin to it with a header\n- **Instant rollback**: Switch the active version back to a previous one without redeployment\n- **Deprecation lifecycle**: Mark old versions as deprecated with sunset dates before removal\n\n### Example\n\n```bash\n# Request to active version (default behavior, no header needed)\ncurl -X POST https://gateway.example.com/context7 \\\n -d '{\"method\": \"tools/list\"}'\n# Routes to v2.0.0 (current active version)\n\n# Request to a specific inactive version\ncurl -X POST https://gateway.example.com/context7 \\\n -H \"X-MCP-Server-Version: v1.5.0\" \\\n -d '{\"method\": \"tools/list\"}'\n# Routes to v1.5.0 (legacy version)\n```\n\n---\n\n## 2. Two Version Concepts\n\nThe registry tracks **two independent version values** for each server. They serve different purposes and are determined differently.\n\n| Aspect | User-Provided Version (Routing Label) | MCP Server Version (Software Identity) |\n|--------|---------------------------------------|----------------------------------------|\n| **Purpose** | Traffic routing between backend deployments | Identifies the actual software running at the backend |\n| **Who controls it** | Platform admin / operator | MCP server developer (set in server code) |\n| **When it is set** | At registration time via API or CLI | Discovered at runtime during health checks |\n| **How it is determined** | Admin provides it explicitly (e.g., `v1.0.0`, `v2.0.0`) | Read from the MCP `initialize` response `serverInfo.version` field |\n| **Mutability** | Changes only via explicit admin action (register, switch default) | Changes whenever the upstream server deploys a new build |\n| **Stored as** | `version` field on the server document | `mcp_server_version` field on the server document |\n| **Example values** | `v1.0.0`, `v2.0.0`, `beta-3` | `2.14.4`, `1.25.0`, `0.9.1` |\n| **Multiple can coexist** | Yes, each version is a separate document with its own backend URL | No, only the active version is health-checked |\n\n### Why Two Versions Exist\n\nThese are fundamentally **different things at different conceptual levels**:\n\n- The **user-provided version** is an operational label. It answers: \"Which backend deployment should receive traffic for this path?\" An admin registers `/context7` with version `v1.0.0` pointing to `https://mcp.context7.com/mcp`, and later registers `v2.0.0` pointing to `https://mcp-v2.context7.com/mcp`. The two versions can run simultaneously with independent backend URLs.\n\n- The **MCP server version** is a software fact. It answers: \"What version of the code is running at this backend URL right now?\" The server at `https://mcp.context7.com/mcp` may report itself as `2.14.4` today and `2.14.5` tomorrow after a deployment. The admin's routing label (`v1.0.0`) does not change.\n\nThey are **never merged or conflated**. An MCP server version change is an informational event, not a routing change. If the upstream server silently upgrades, the registry detects it during health checks and stores the previous/current values for observability.\n\n### MCP Server Version Change Detection\n\nWhen a health check detects that `mcp_server_version` has changed:\n\n| Field | Purpose |\n|-------|---------|\n| `mcp_server_version` | Current version reported by the running server |\n| `mcp_server_version_previous` | The version before the most recent change |\n| `mcp_server_version_updated_at` | ISO timestamp of when the change was detected |\n\nThe frontend shows a subtle green dot indicator next to the MCP server version badge when the version changed within the last 24 hours. No acknowledgement workflow is required -- this is informational only.\n\n---\n\n## 3. Storage Design: Separate Documents per Version\n\nEach version of a server is stored as a **separate document** in MongoDB/DocumentDB. The active version uses the original path as its `_id` (backward compatible), and inactive versions use a compound `path:version` ID.\n\n### Active Version Document\n\nThis document appears in all listings, search results, health checks, and the dashboard.\n\n```json\n{\n \"_id\": \"/context7\",\n \"server_name\": \"Context7 MCP Server\",\n \"version\": \"v2.0.0\",\n \"proxy_pass_url\": \"https://mcp.context7.com/mcp\",\n\n \"is_active\": true,\n \"version_group\": \"context7\",\n \"other_version_ids\": [\"/context7:v1.5.0\"],\n\n \"description\": \"Up-to-date Docs for LLMs and AI code editors\",\n \"tags\": [\"documentation\", \"search\", \"libraries\"],\n \"supported_transports\": [\"streamable-http\"],\n \"num_tools\": 12,\n \"num_stars\": 4.5,\n \"is_enabled\": true,\n \"registered_at\": \"2026-01-10T00:00:00Z\",\n \"updated_at\": \"2026-01-14T00:00:00Z\",\n\n \"mcp_server_version\": \"2.14.5\",\n \"mcp_server_version_previous\": \"2.14.4\",\n \"mcp_server_version_updated_at\": \"2026-01-28T15:30:00Z\"\n}\n```\n\n### Inactive Version Document\n\nThis document is hidden from listings and search. It is accessible only via the version management API.\n\n```json\n{\n \"_id\": \"/context7:v1.5.0\",\n \"server_name\": \"Context7 MCP Server\",\n \"version\": \"v1.5.0\",\n \"proxy_pass_url\": \"https://v1.mcp.context7.com/mcp\",\n\n \"is_active\": false,\n \"version_group\": \"context7\",\n \"active_version_id\": \"/context7\",\n \"status\": \"deprecated\",\n \"sunset_date\": \"2026-06-01\",\n\n \"description\": \"Legacy version for backward compatibility\",\n \"tags\": [\"documentation\", \"search\", \"libraries\"],\n \"supported_transports\": [\"streamable-http\"],\n \"num_tools\": 10,\n \"is_enabled\": true,\n \"registered_at\": \"2025-11-15T00:00:00Z\",\n \"updated_at\": \"2026-01-14T00:00:00Z\"\n}\n```\n\n### Version-Specific Fields\n\nThese fields are added to the standard server document schema to support versioning:\n\n| Field | Type | Present On | Description |\n|-------|------|-----------|-------------|\n| `version` | `str` | Both | The user-provided version label (e.g., `v2.0.0`) |\n| `is_active` | `bool` | Both | `true` for the active version, `false` for inactive |\n| `version_group` | `str` | Both | Groups all versions of the same server (derived from path) |\n| `other_version_ids` | `list[str]` | Active only | Array of `_id` values for all inactive versions |\n| `active_version_id` | `str` | Inactive only | The `_id` of the currently active version document |\n| `status` | `str` | Inactive | Version lifecycle status: `stable`, `beta`, `deprecated` |\n| `sunset_date` | `str` | Inactive | ISO date after which this version will be removed |\n\n### Design Decisions\n\n| Decision | Rationale |\n|----------|-----------|\n| Active version keeps original path as `_id` | Backward compatibility -- existing nginx location blocks, health checks, and API references continue to work unchanged |\n| Inactive versions use `path:version` compound `_id` | Guarantees uniqueness within the collection and is easy to parse |\n| `is_active` field for filtering | All listing and dashboard queries add `is_active: true`, keeping inactive versions out of normal views |\n| `version_group` for linking | Enables efficient queries to populate the version selector modal without scanning the full collection |\n| Each version is a complete document | Versions can have different descriptions, tool counts, ratings, and backend URLs |\n\n### Why Separate Documents Instead of Embedded Array\n\nTwo storage approaches were evaluated:\n\n| Criteria | Embedded Array | Separate Documents (chosen) |\n|----------|---------------|----------------------------|\n| Search pre-filtering | Requires `$elemMatch` or application logic | Simple `is_active: true` filter |\n| Each version as independent entity | Awkward -- tools, ratings, descriptions nested in array | Natural -- each doc has full metadata |\n| Document size | Grows with versions | Fixed size per document |\n| Version swap complexity | Array element update | Document insert/delete (more complex, but infrequent) |\n| Listing queries | Need to exclude inactive array items | Simple query filter |\n\nThe separate-documents design was chosen because **search filtering is critical** (see Section 5) and each version is a complete entity with its own tools, ratings, and metadata.\n\n---\n\n## 4. Nginx Version Routing\n\n### Map Directive\n\nThe nginx configuration uses a `map` directive for O(1) version lookup based on the URI path and the `X-MCP-Server-Version` request header. The map is auto-generated whenever servers are registered, updated, or versions are changed.\n\n```nginx\nmap \"$uri:$http_x_mcp_server_version\" $versioned_backend {\n default \"\";\n\n # context7 versions\n \"~^/context7(/.*)?:$\" \"https://mcp.context7.com/mcp\";\n \"~^/context7(/.*)?:latest$\" \"https://mcp.context7.com/mcp\";\n \"~^/context7(/.*)?:v2.0.0$\" \"https://mcp.context7.com/mcp\";\n \"~^/context7(/.*)?:v1.5.0$\" \"https://v1.mcp.context7.com/mcp\";\n}\n```\n\nEach entry maps a `path:version` combination to a backend URL. Three entries exist for the active version: empty header (no version specified), `latest` keyword, and the explicit version string.\n\n### Location Block\n\nFor multi-version servers, the location block uses a variable-based `proxy_pass` instead of a hardcoded URL:\n\n```nginx\nlocation /context7 {\n # ... existing auth_request, headers, transport config ...\n\n set $backend_url \"https://mcp.context7.com/mcp\"; # Default fallback\n if ($versioned_backend != \"\") {\n set $backend_url $versioned_backend;\n }\n\n proxy_pass $backend_url;\n add_header X-MCP-Version-Routing \"enabled\" always;\n}\n```\n\nSingle-version servers continue to use direct `proxy_pass` with no map entries (fully backward compatible).\n\n### Has-Versions Detection\n\nThe nginx config generator checks `server_info.get(\"other_version_ids\", [])` to determine whether a server has multiple versions. If the array is non-empty, the location block uses the variable-based pattern. This check uses `other_version_ids` (the actual MongoDB field), not a `versions` field.\n\n### Request Flow\n\n```\nClient Request\n POST /context7\n X-MCP-Server-Version: v1.5.0 (optional)\n |\n v\n Nginx Map Lookup\n Key: \"/context7:v1.5.0\"\n Result: \"https://v1.mcp.context7.com/mcp\"\n |\n v\n Location /context7\n $backend_url = map result (or default fallback)\n proxy_pass $backend_url\n |\n v\n Backend: https://v1.mcp.context7.com/mcp\n```\n\n### Request/Response Headers\n\n| Header | Direction | Required | Description |\n|--------|-----------|----------|-------------|\n| `X-MCP-Server-Version` | Request | No | Target version (`v1.0.0`, `v2.0.0`, `latest`, or omit for default) |\n| `X-MCP-Version-Routing` | Response | Auto | Indicates version routing is active for this server (`enabled`) |\n\n---\n\n## 5. Search and Listing Integration\n\n### Dashboard Listings\n\nAll listing queries filter by `is_active: true`, ensuring only the active version of each server appears in the dashboard:\n\n```python\ncursor = collection.find({\"is_active\": True})\n```\n\nInactive versions are invisible in normal listings and only accessible via the version management API.\n\n### Semantic Search\n\nThe registry uses hybrid semantic search combining vector similarity with tokenized keyword matching. The search backend is either **MongoDB-CE** (client-side cosine similarity) or **AWS DocumentDB** (native `$vectorSearch` pipeline with HNSW index). Both backends use the same indexing strategy for versioning.\n\n#### Search Index Structure\n\nServer embeddings are stored in a separate collection (`mcp_embeddings_{dimension}_{namespace}`) with this document structure:\n\n```json\n{\n \"_id\": \"/context7\",\n \"entity_type\": \"mcp_server\",\n \"path\": \"/context7\",\n \"name\": \"Context7 MCP Server\",\n \"description\": \"Up-to-date Docs for LLMs...\",\n \"tags\": [\"documentation\", \"search\"],\n \"is_enabled\": true,\n \"text_for_embedding\": \"Context7 MCP Server Up-to-date Docs... Tags: documentation, search...\",\n \"embedding\": [0.042, -0.018, ...],\n \"metadata\": { ... },\n \"indexed_at\": \"2026-01-28T12:00:00Z\"\n}\n```\n\nThe embedding text is built from the server's name, description, tags, and tool names/descriptions.\n\n#### How Inactive Versions Are Excluded\n\nThere is always **exactly one search document per server path** in the embeddings collection. That document always contains the active version's metadata. Inactive versions never get their own search documents.\n\nThis is enforced by which code paths call `index_server()`:\n\n| Operation | Calls `index_server()`? | What happens in the embeddings collection |\n|-----------|------------------------|-------------------------------------------|\n| `register_server()` (first registration) | Yes | Creates search document at `_id: /context7` with this version's data |\n| `register_server()` (new version of existing server) | No (calls `add_server_version()` internally) | No change -- the existing search document stays as-is with the active version |\n| `update_server()` | Yes | Overwrites the search document with updated metadata |\n| `set_default_version()` | Yes | Overwrites the search document with the **new** active version's data |\n| `add_server_version()` | No | No change -- inactive versions are not indexed |\n\nEvery call to `index_server()` **recomputes the embedding vector from scratch**. It rebuilds the embedding text by concatenating the provided version's `server_name`, `description`, `tags`, and `tool_list` (tool names and descriptions), then generates a fresh embedding vector from that text. The resulting document is written via `replace_one({\"_id\": path}, doc, upsert=True)`, which overwrites whatever was previously stored at that path. There is no separate removal step -- the old active version's embedding data is simply replaced by the new active version's embedding data.\n\nThis means that if `v2.0.0` has 15 tools and a different description than `v1.0.0`'s 10 tools, switching the active version causes the search document to reflect `v2.0.0`'s content with a new embedding vector that captures its tools and description.\n\nInactive version documents (stored in the server collection at compound IDs like `/context7:v1.0.0`) have **no corresponding entry** in the embeddings collection. They were never added there.\n\n**Example**: Context7 has three versions (`v1.0.0`, `v1.5.0`, `v2.0.0`) with `v2.0.0` active. The embeddings collection contains exactly one document at `_id: /context7` with `v2.0.0`'s name, description, tags, and tools as the embedding text. When `set_default_version()` switches to `v1.5.0`, `index_server()` rebuilds the embedding text from `v1.5.0`'s metadata (which may have different tools, description, and tags), generates a new embedding vector, and overwrites the search document. A search for \"documentation tools\" can only ever match this single document -- the two inactive versions have no search presence.\n\nThis means inactive versions never consume search result slots, which is the critical requirement for search quality.\n\n#### MongoDB-CE vs AWS DocumentDB Search Behavior\n\n| Aspect | MongoDB-CE | AWS DocumentDB |\n|--------|-----------|----------------|\n| Vector index | Regular B-tree index (no native vector support) | HNSW vector index (cosine similarity, M=16, efConstruction=128) |\n| Search method | Client-side: fetches all embeddings, computes cosine similarity in Python | Native: `$vectorSearch` aggregation pipeline |\n| Keyword matching | Tokenized matching in Python (stopwords removed, tokens > 2 chars) | Aggregation pipeline with `$addFields` for text boost scoring |\n| Re-ranking | `relevance = normalized_vector_score + (text_boost * 0.05)` | `relevance = normalized_vector_score + (text_boost * 0.1)` |\n| Pre-filtering of inactive versions | Same -- inactive versions are not in the search collection | Same -- inactive versions are not in the search collection |\n\nBoth backends produce the same result: only active versions appear in search results.\n\n#### Keyword Boost Scoring\n\nThe hybrid search applies keyword boosts on top of vector similarity scores:\n\n| Match Location | Boost Points |\n|---------------|-------------|\n| Path match | 5.0 |\n| Name match | 3.0 |\n| Description match | 2.0 |\n| Tags match | 1.5 |\n| Tool name/description match | 1.0 per tool |\n\nThe boost is multiplied by a factor (0.05 for MongoDB-CE, 0.1 for DocumentDB) and added to the normalized vector score. This ensures exact name matches rank higher than semantically similar but differently-named servers.\n\n### Summary of Filtering Strategy\n\n| Filter | When Applied | Mechanism |\n|--------|-------------|-----------|\n| Active vs. inactive version | **Index time** (pre-filter) | Only active version is written to search collection |\n| Enabled vs. disabled server | **Query time** (post-filter) | `is_enabled` metadata returned with results |\n| User access control | **Query time** (post-filter) | API layer checks user permissions |\n\nThis design ensures that inactive versions never waste search result slots, which is the critical requirement for search quality.\n\n### Removal from Search\n\nWhen a server is deleted via `remove_server()`, the search index entry is also removed via `search_repo.remove_entity(path)`. The `delete_with_versions()` repository method handles cascade deletion of all version documents (active + inactive) from MongoDB/DocumentDB.\n\n---\n\n## 6. Health Check Integration\n\nOnly the **active version** of each server is health-checked. The health check service filters out inactive versions:\n\n```python\nasync def get_enabled_services(self) -> list[str]:\n for path, server_info in all_servers.items():\n if not server_info.get(\"is_enabled\", False):\n continue\n # Skip inactive versions\n if server_info.get(\"version_group\") and not server_info.get(\"is_active\", True):\n continue\n enabled_paths.append(path)\n```\n\nWhen the active version is switched via `set_default_version()`, an immediate background health check is triggered for the newly active version:\n\n```python\nasyncio.create_task(health_service.perform_immediate_health_check(path))\n```\n\nThis ensures the dashboard reflects the health status of the new active version promptly after a switch.\n\n---\n\n## 7. API Endpoints\n\nAll version management endpoints are under `/api/servers/{path}/versions`:\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/servers/{path}/versions` | List all versions of a server |\n| `DELETE` | `/api/servers/{path}/versions/{version}` | Remove an inactive version |\n| `PUT` | `/api/servers/{path}/versions/default` | Switch the active (default) version |\n\nNew versions are created by registering a server with the same path but a different `version` field. The `register_server()` method detects this and creates an inactive version document automatically.\n\n### Version Creation via Registration\n\n```bash\n# First registration creates the server\nPOST /api/servers/register\n{\n \"server_name\": \"Context7\",\n \"path\": \"/context7\",\n \"version\": \"v1.0.0\",\n \"proxy_pass_url\": \"https://mcp.context7.com/mcp\"\n}\n\n# Second registration with same path but different version creates an inactive version\nPOST /api/servers/register\n{\n \"server_name\": \"Context7\",\n \"path\": \"/context7\",\n \"version\": \"v2.0.0\",\n \"proxy_pass_url\": \"https://mcp-v2.context7.com/mcp\"\n}\n```\n\nThe second call returns `is_new_version: true` to indicate a new version was added rather than a new server being created.\n\n---\n\n## 8. Version Swap Operation\n\nSwitching the active version (`set_default_version`) is the most complex operation in the versioning system. It performs a document swap:\n\n1. Read the current active document at path `_id` (e.g., `/context7`)\n2. Read the target inactive version document (e.g., `/context7:v2.0.0`)\n3. Build a new active document from the target, assigning it the original path `_id`\n4. Build a new inactive document from the current active, assigning it a compound `_id`\n5. Delete the old active and target inactive documents\n6. Insert the new active and new inactive documents\n7. Update the `other_version_ids` array (remove target, add old active)\n8. Re-index the FAISS search entry with the new active version's data\n9. Regenerate nginx configuration and reload\n10. Trigger an immediate background health check for the newly active version\n\nThis is an infrequent admin operation. The trade-off of complexity here versus simpler listing/search queries is acceptable.\n\n---\n\n## 9. Cascade Deletion\n\nWhen a server is deleted via `remove_server()`, all version documents are deleted together using `delete_with_versions()`:\n\n```python\nfilter_query = {\n \"$or\": [\n {\"_id\": path}, # Active document\n {\"_id\": {\"$regex\": f\"^{path}:\"}}, # All inactive version documents\n ]\n}\nresult = await collection.delete_many(filter_query)\n```\n\nThis prevents orphaned version documents from remaining in the database after a server is removed.\n\n---\n\n## 10. Frontend Components\n\n### Version Badge\n\nA clickable badge on the ServerCard that shows the current active version (e.g., `v2.0.0`). Only visible when the server has multiple versions (`versions.length > 1`). Single-version servers show no badge.\n\n### Version Selector Modal\n\nOpened by clicking the version badge. Displays all versions as individual cards with:\n\n- Version number and status badge (`ACTIVE`, `stable`, `beta`, `deprecated`)\n- Backend URL\n- Release and sunset dates\n- \"Set Active\" button (disabled for the already-active version)\n\nAn info footer explains the `X-MCP-Server-Version` header usage for clients that want to pin to a specific version.\n\n### MCP Server Version Display\n\nA separate, smaller badge below the routing version badge shows the MCP server-reported version (e.g., `srv 2.14.5`). If the version changed within the last 24 hours, a small green dot indicator appears. Hovering shows the previous version in a tooltip.\n\n---\n\n## 11. Backward Compatibility\n\n| Scenario | Behavior |\n|----------|----------|\n| Existing single-version servers | Work unchanged. No `version_group`, no map entries, direct `proxy_pass` |\n| No `X-MCP-Server-Version` header | Routes to active version (same as before versioning existed) |\n| `version` field missing on legacy document | Defaults to `v1.0.0` |\n| Client sends header for single-version server | Map returns empty string, falls back to default `proxy_pass` |\n\n---\n\n## 12. Index Strategy\n\n```javascript\n// Primary filter for all listing operations\ndb.mcp_servers.createIndex({ \"is_active\": 1 })\n\n// For version group lookups (modal population)\ndb.mcp_servers.createIndex({ \"version_group\": 1 })\n\n// Compound index for dashboard queries\ndb.mcp_servers.createIndex({ \"is_active\": 1, \"is_enabled\": 1 })\n```\n\n---\n\n## 13. Future: Traffic Splitting (Phase 2)\n\nNot yet implemented. Phase 2 will use nginx `split_clients` directive to route a percentage of traffic to different versions for gradual rollouts:\n\n```nginx\nsplit_clients \"${remote_addr}${request_uri}\" $canary_backend {\n 10% \"http://server-v2:8000/\";\n * \"http://server-v1:8000/\";\n}\n```\n\n| Condition | Routing |\n|-----------|---------|\n| `X-MCP-Server-Version: v2.0.0` | Force v2.0.0 (explicit header takes precedence) |\n| No header + traffic split enabled | Percentage-based routing |\n| No header + no traffic split | Route to active version |\n" }, { "path": "docs/design/storage-architecture-mongodb-documentdb.md", "content": "# Storage Architecture: MongoDB CE & AWS DocumentDB\n\n**Status:** Current Implementation\n**Last Updated:** January 30, 2026\n**Target Audience:** Developers, DevOps Engineers, System Architects\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Storage Backend Options](#storage-backend-options)\n3. [MongoDB CE Local Development](#mongodb-ce-local-development)\n4. [AWS DocumentDB Production](#aws-documentdb-production)\n5. [Vector Search Implementation](#vector-search-implementation)\n6. [Build and Run Process](#build-and-run-process)\n7. [Repository Architecture](#repository-architecture)\n8. [Configuration](#configuration)\n9. [Migration Strategy](#migration-strategy)\n\n## Overview\n\nThe MCP Gateway Registry supports three storage backends for data persistence:\n\n1. **File-Based Backend** (Legacy) - JSON/YAML files with FAISS\n2. **MongoDB CE** (Local Development) - MongoDB Community Edition 8.2 with application-level vector search\n3. **AWS DocumentDB** (Production) - MongoDB-compatible service with native vector search\n\nThis document focuses on the MongoDB and DocumentDB backends, which provide distributed storage with semantic search capabilities.\n\n### Architecture Diagram\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Application Layer │\n│ (Services, API Endpoints) │\n└────────────────────┬────────────────────────────────────────┘\n │ depends on\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Repository Factory Layer │\n│ get_server_repository() │\n│ get_search_repository() │\n│ etc. │\n└────────┬──────────────────────┬──────────────┬─────────────┘\n │ │ │\n │ STORAGE_BACKEND= │ │\n │ file / mongodb-ce / │ │\n │ documentdb │ │\n ▼ ▼ ▼\n┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐\n│ File Backend │ │ MongoDB CE │ │ AWS DocumentDB │\n├──────────────────┤ ├─────────────────┤ ├──────────────────┤\n│ FileServerRepo │ │ DocumentDBRepo │ │ DocumentDBRepo │\n│ FaissSearch │ │ + App-level │ │ + Native │\n│ │ │ vector search │ │ vector search │\n└──────────────────┘ └─────────────────┘ └──────────────────┘\n │ │ │\n ▼ ▼ ▼\n Local Files Local MongoDB CE AWS DocumentDB\n (JSON + FAISS) (Docker) (Managed Service)\n```\n\n---\n\n## Storage Backend Options\n\n### Comparison Matrix\n\n| Aspect | File | MongoDB CE | AWS DocumentDB |\n|--------|------|------------|----------------|\n| **Use Case** | Dev/Testing | Local Development | Production |\n| **Scalability** | ~1000 entities | 10,000s | Millions |\n| **Vector Search** | FAISS (app-level) | App-level (Python) | Native (HNSW) |\n| **Setup Complexity** | None | Docker Compose | Terraform/AWS |\n| **Concurrency** | Limited | Good | Excellent |\n| **HA/Clustering** | No | Manual | Automatic |\n| **Cost** | Free | Free | AWS Pricing |\n| **Best For** | Quick start | Feature development | Production deployments |\n\n---\n\n## MongoDB CE Local Development\n\n### Architecture\n\nMongoDB Community Edition 8.2 provides a local development environment that mimics production DocumentDB behavior without requiring AWS infrastructure.\n\n#### Key Components\n\n1. **MongoDB 8.2 Container** (`mongo:8.2`)\n - Runs in Docker Compose\n - Configured as replica set (`rs0`) for transaction support\n - No authentication for local development simplicity\n - Bind address: `127.0.0.1,mongodb`\n\n2. **Application-Level Vector Search**\n - Python-based cosine similarity computation\n - Embeddings stored in `mcp_embeddings_1536_default` collection\n - Full scan with in-memory ranking for search queries\n - Isolated in `DocumentDBSearchRepository` class\n\n3. **Collections**\n - `mcp_servers_{namespace}` - Server definitions\n - `mcp_agents_{namespace}` - Agent cards\n - `mcp_scopes_{namespace}` - Authorization scopes\n - `mcp_embeddings_1536_{namespace}` - Vector embeddings\n - `mcp_security_scans_{namespace}` - Security scan results\n - `mcp_federation_config_{namespace}` - Federation settings\n\n### Vector Search Implementation (MongoDB CE)\n\nSince MongoDB CE 8.2 doesn't include the separate `mongot` search component needed for native vector search, we implement semantic search at the application layer.\n\n#### Search Flow\n\n```python\n# 1. Query arrives\nquery = \"financial analysis tools\"\n\n# 2. Generate query embedding\nmodel = create_embeddings_client(...)\nquery_embedding = model.encode([query])[0] # [1536 dimensions]\n\n# 3. Retrieve all embeddings from MongoDB\ndocs = await collection.find({\"entity_type\": \"mcp_server\"}).to_list(length=1000)\n\n# 4. Calculate cosine similarity in Python\nfor doc in docs:\n doc_embedding = doc[\"embedding\"] # [1536 dimensions]\n score = cosine_similarity(query_embedding, doc_embedding)\n doc[\"relevance_score\"] = score\n\n# 5. Rank results by similarity\nresults = sorted(docs, key=lambda x: x[\"relevance_score\"], reverse=True)\n\n# 6. Apply text-based boosting (hybrid search)\n# If query appears in name or description, add bonus points\nfor result in results:\n if query.lower() in result[\"name\"].lower():\n result[\"relevance_score\"] += 0.1 # Name match bonus\n if query.lower() in result[\"description\"].lower():\n result[\"relevance_score\"] += 0.05 # Description match bonus\n\n# 7. Return top-k results\nreturn results[:max_results]\n```\n\n#### Code Location\n\n**File:** `registry/repositories/documentdb/search_repository.py`\n\n**Key Methods:**\n\n```python\nclass DocumentDBSearchRepository:\n async def search(\n self,\n query: str,\n entity_types: Optional[List[str]] = None,\n max_results: int = 10,\n ) -> Dict[str, List[Dict[str, Any]]]:\n \"\"\"Hybrid search with application-level vector similarity.\"\"\"\n # Lines 240-385: Full implementation\n\n def _calculate_cosine_similarity(\n self,\n vec1: List[float],\n vec2: List[float]\n ) -> float:\n \"\"\"Calculate cosine similarity between two vectors.\"\"\"\n # Lines 199-220: Pure Python implementation\n # Returns value between 0 and 1 (1 = identical)\n```\n\n#### Performance Characteristics\n\n- **Pros:**\n - No dependency on external search services\n - Works identically to production DocumentDB (same code path)\n - Full control over ranking algorithm\n - No additional containers needed\n\n- **Cons:**\n - O(n) full collection scan for every search query\n - All embeddings loaded into memory for comparison\n - Not suitable for >10,000 entities\n - No index optimization (brute force)\n\n- **Optimization:**\n - For local dev with <1,000 entities, performance is acceptable (<100ms)\n - Production workloads should use AWS DocumentDB with native vector search\n\n### Docker Compose Configuration\n\n**File:** `docker-compose.yml` (lines 59-77)\n\n```yaml\nmongodb:\n image: mongo:8.2\n container_name: mcp-mongodb\n command: mongod --replSet rs0 --bind_ip 127.0.0.1,mongodb\n ports:\n - \"27017:27017\"\n volumes:\n - mongodb-data:/data/db\n - mongodb-config:/data/configdb\n healthcheck:\n test: [\"CMD\", \"mongosh\", \"--eval\", \"db.adminCommand('ping')\"]\n interval: 10s\n timeout: 5s\n retries: 5\n start_period: 20s\n restart: unless-stopped\n```\n\n**Key Settings:**\n\n- **Replica Set:** `--replSet rs0` enables transactions (required for DocumentDB compatibility)\n- **Bind Address:** `127.0.0.1,mongodb` - listens on localhost and container network\n- **No Authentication:** Simplifies local development (not for production!)\n- **Healthcheck:** Ensures container is ready before dependent services start\n\n### Initialization\n\n**Script:** `scripts/init-mongodb-ce.py`\n\n**What It Does:**\n\n1. **Initializes Replica Set**\n ```python\n # Initialize rs0 replica set (required for transactions)\n config = {\n \"_id\": \"rs0\",\n \"members\": [{\"_id\": 0, \"host\": \"mongodb:27017\"}]\n }\n client.admin.command(\"replSetInitiate\", config)\n ```\n\n2. **Creates Collections**\n - Server registry (`mcp_servers_default`)\n - Agent registry (`mcp_agents_default`)\n - Authorization scopes (`mcp_scopes_default`)\n - Vector embeddings (`mcp_embeddings_1536_default` - 1536 dimensions for OpenAI/Titan)\n - Security scans (`mcp_security_scans_default`)\n - Federation config (`mcp_federation_config_default`)\n\n3. **Creates Indexes** for query performance\n ```python\n # Server indexes\n await collection.create_index([(\"path\", ASCENDING)], unique=True)\n await collection.create_index([(\"enabled\", ASCENDING)])\n await collection.create_index([(\"tags\", ASCENDING)])\n\n # Embeddings indexes\n await collection.create_index([(\"path\", ASCENDING)], unique=True)\n await collection.create_index([(\"entity_type\", ASCENDING)])\n ```\n\n4. **Loads OAuth Scopes** from `auth_server/scopes.yml`\n ```python\n # Reads scopes.yml and populates mcp_scopes_default collection\n # Includes server scopes and group mappings\n await _load_scopes_from_yaml(db, namespace, scopes_file)\n ```\n\n5. **Note on Vector Index**\n - MongoDB CE 8.2 does not include native vector search (requires `mongot` component)\n - Vector search is implemented at application level using Python cosine similarity\n - See `registry/repositories/documentdb/search_repository.py` for implementation\n\n### Environment Variables\n\n**File:** `.env.example` (lines 360-386)\n\n```bash\n# Storage backend selection\nSTORAGE_BACKEND=mongodb-ce # Use MongoDB CE local instance\n\n# DocumentDB Configuration (reused for MongoDB CE)\nDOCUMENTDB_HOST=mongodb # Docker Compose service name\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=default\n\n# No authentication needed for local MongoDB CE\n# DOCUMENTDB_USERNAME and DOCUMENTDB_PASSWORD not required\n# DOCUMENTDB_USE_TLS=false (disabled for local)\n```\n\n---\n\n## AWS DocumentDB Production\n\n### Architecture\n\nAWS DocumentDB is a MongoDB-compatible managed database service optimized for cloud deployments with native vector search support.\n\n#### Key Components\n\n1. **DocumentDB Cluster**\n - Managed by AWS\n - Multi-AZ deployment for redundancy\n - Auto-scaling read replicas\n - Automated backups and point-in-time recovery\n\n2. **Native Vector Search**\n - HNSW (Hierarchical Navigable Small World) algorithm\n - Index-based approximate nearest neighbor (ANN)\n - Sub-100ms query times even with millions of vectors\n - Cosine similarity metric\n\n3. **Network Architecture**\n - Private VPC deployment\n - TLS encryption in transit\n - VPC security groups for access control\n\n### Vector Search Implementation (DocumentDB)\n\nAWS DocumentDB provides native vector search using optimized indexes, eliminating the need for application-level computation.\n\n#### Search Flow\n\n```python\n# 1. Query arrives\nquery = \"financial analysis tools\"\n\n# 2. Generate query embedding (same as MongoDB CE)\nquery_embedding = model.encode([query])[0]\n\n# 3. DocumentDB performs indexed vector search with tuned parameters\nef_search = settings.vector_search_ef_search # Default: 100\nk_value = max(max_results * 3, 50) # At least 50 for small collections\npipeline = [\n {\n \"$search\": {\n \"vectorSearch\": {\n \"vector\": query_embedding,\n \"path\": \"embedding\",\n \"similarity\": \"cosine\",\n \"k\": k_value,\n \"efSearch\": ef_search,\n }\n }\n }\n]\n\n# 4. DocumentDB returns sorted results (FAST - uses HNSW index)\n# Results are already ranked by vector similarity\n\n# 5. Apply text-based boosting in aggregation pipeline\n# Each query keyword is matched independently against path, name,\n# description, tags, and tool names/descriptions\npipeline.append({\n \"$addFields\": {\n \"text_boost\": {\n \"$add\": [\n # Per keyword: path(+5), name(+3), description(+2), tags(+1.5)\n {\"$cond\": [{\"$regexMatch\": {\"input\": \"$path\", \"regex\": keyword, \"options\": \"i\"}}, 5.0, 0.0]},\n {\"$cond\": [{\"$regexMatch\": {\"input\": \"$name\", \"regex\": keyword, \"options\": \"i\"}}, 3.0, 0.0]},\n {\"$cond\": [{\"$regexMatch\": {\"input\": \"$description\", \"regex\": keyword, \"options\": \"i\"}}, 2.0, 0.0]},\n # ... plus tags (+1.5) and each tool (+1.0)\n ]\n }\n }\n})\n\n# 6. Score combination: normalized_vector + (text_boost * 0.1)\n# All candidates scored, sorted by hybrid score, then top-3 per entity type\n\n# 7. Execute aggregation pipeline\nresults = await collection.aggregate(pipeline).to_list(k_value)\n```\n\n#### Code Location\n\n**File:** `registry/repositories/documentdb/search_repository.py`\n\n**The same code works for both MongoDB CE and AWS DocumentDB!**\n\nThe key difference:\n- **MongoDB CE:** No vector index → slow full scan\n- **DocumentDB:** HNSW vector index → fast indexed search\n\nThe application code is identical, but DocumentDB executes it much faster.\n\n#### Performance Characteristics\n\n- **Pros:**\n - O(log n) indexed search via HNSW\n - Handles millions of vectors efficiently\n - Sub-100ms latency even with large datasets\n - Native database operation (no network round trips)\n - Automatic index optimization\n\n- **Cons:**\n - Requires AWS infrastructure\n - Additional cost for managed service\n - Network latency to AWS region\n\n- **Optimization:**\n - HNSW parameters tuned for accuracy vs. speed tradeoff\n - `m=16, efConstruction=128` provides good balance for index construction\n - `efSearch=100` (configurable) provides near-exact recall for typical deployments\n - Minimum `k=50` ensures small collections are fully covered\n - Can adjust via `VECTOR_SEARCH_EF_SEARCH` environment variable\n\n### Terraform Configuration\n\n**Directory:** `terraform/aws-ecs/`\n\n**Key Resources:**\n\n1. **DocumentDB Cluster** (`modules/documentdb/main.tf`)\n ```hcl\n resource \"aws_docdb_cluster\" \"main\" {\n cluster_identifier = \"mcp-registry-${var.environment}\"\n engine = \"docdb\"\n master_username = var.master_username\n master_password = var.master_password\n\n # Redundancy\n backup_retention_period = 7\n preferred_backup_window = \"03:00-04:00\"\n\n # Security\n storage_encrypted = true\n kms_key_id = aws_kms_key.docdb.arn\n\n # Network\n db_subnet_group_name = aws_docdb_subnet_group.main.name\n vpc_security_group_ids = [aws_security_group.docdb.id]\n }\n ```\n\n2. **DocumentDB Instance(s)** (read/write nodes)\n ```hcl\n resource \"aws_docdb_cluster_instance\" \"main\" {\n count = var.instance_count\n identifier = \"mcp-registry-${var.environment}-${count.index}\"\n cluster_identifier = aws_docdb_cluster.main.id\n instance_class = var.instance_class # db.r5.large, db.r6g.xlarge, etc.\n }\n ```\n\n3. **Vector Search Configuration**\n - Automatically enabled on DocumentDB 5.0+\n - No additional configuration needed\n - HNSW index created via application init script\n\n### Environment Variables (Production)\n\n**File:** `.env` (not in git)\n\n```bash\n# Storage backend\nSTORAGE_BACKEND=documentdb # Use AWS DocumentDB\n\n# DocumentDB connection\nDOCUMENTDB_HOST=mcp-registry-prod.cluster-xxxxx.us-east-1.docdb.amazonaws.com\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_USERNAME=mcp_admin\nDOCUMENTDB_PASSWORD=\n\n# Security settings\nDOCUMENTDB_USE_TLS=true\nDOCUMENTDB_TLS_CA_FILE=/app/global-bundle.pem # AWS DocumentDB CA bundle\nDOCUMENTDB_USE_IAM=false # Set to true for IAM authentication\n\n# Replica set configuration\nDOCUMENTDB_REPLICA_SET=rs0\nDOCUMENTDB_READ_PREFERENCE=secondaryPreferred # Distribute read load\n\n# Namespace for multi-tenancy\nDOCUMENTDB_NAMESPACE=production\n```\n\n---\n\n## Vector Search Implementation\n\n### Overview\n\nVector search enables semantic search - finding conceptually similar servers and agents even when exact keywords don't match.\n\n**Example:**\n\n```\nQuery: \"financial analytics\"\nMatches:\n ✓ \"Stock market analysis tools\" (85% similarity)\n ✓ \"Portfolio management assistant\" (78% similarity)\n ✗ \"Weather forecast service\" (12% similarity)\n```\n\n### Embedding Generation\n\n**Module:** `registry/embeddings/`\n\n**Providers:**\n\n1. **Sentence Transformers** (Default, Local)\n - Model: `all-MiniLM-L6-v2`\n - Dimensions: 384\n - Runs locally, no API costs\n\n2. **LiteLLM** (Cloud, via API)\n - OpenAI: `text-embedding-ada-002` (1536 dims)\n - Amazon Bedrock Titan: `amazon.titan-embed-text-v1` (1536 dims)\n - Cohere: `embed-english-v3.0` (1024 dims)\n\n**Configuration:**\n\n```bash\n# Local embeddings\nEMBEDDINGS_PROVIDER=sentence-transformers\nEMBEDDINGS_MODEL_NAME=all-MiniLM-L6-v2\nEMBEDDINGS_MODEL_DIMENSIONS=384\n\n# OR Cloud embeddings (OpenAI)\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=openai/text-embedding-ada-002\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_API_KEY=sk-...\n\n# OR Amazon Bedrock\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=bedrock/amazon.titan-embed-text-v1\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_AWS_REGION=us-east-1\n```\n\n### Embedding Storage\n\n**Collection:** `mcp_embeddings_{dimensions}_{namespace}`\n\n**Document Structure:**\n\n```json\n{\n \"_id\": \"/servers/financial-data\",\n \"entity_type\": \"mcp_server\",\n \"path\": \"/servers/financial-data\",\n \"name\": \"Financial Data Server\",\n \"description\": \"Provides stock market data and analysis tools\",\n \"tags\": [\"finance\", \"data\", \"stocks\"],\n \"is_enabled\": true,\n \"text_for_embedding\": \"Financial Data Server. Provides stock market data and analysis tools. Tools: get_stock_price, analyze_portfolio, market_trends\",\n \"embedding\": [0.125, -0.342, 0.098, ...], // 1536 floats\n \"embedding_metadata\": {\n \"model\": \"amazon.titan-embed-text-v1\",\n \"provider\": \"litellm\",\n \"dimensions\": 1536,\n \"created_at\": \"2026-01-03T10:30:00Z\"\n },\n \"tools\": [\n {\"name\": \"get_stock_price\", \"description\": \"Get current stock price\"},\n {\"name\": \"analyze_portfolio\", \"description\": \"Analyze investment portfolio\"}\n ],\n \"metadata\": { /* full server info */ },\n \"indexed_at\": \"2026-01-03T10:30:00Z\"\n}\n```\n\n### Search Algorithm Comparison\n\n#### MongoDB CE (Application-Level)\n\n```python\n# File: registry/repositories/documentdb/search_repository.py\n\nasync def search(self, query: str, max_results: int = 10):\n # 1. Generate query embedding\n query_embedding = model.encode([query])[0]\n\n # 2. Fetch ALL documents (full scan)\n docs = await collection.find({}).to_list(length=10000)\n\n # 3. Calculate similarity for each document\n for doc in docs:\n doc[\"score\"] = cosine_similarity(query_embedding, doc[\"embedding\"])\n\n # 4. Sort by score (in Python)\n ranked = sorted(docs, key=lambda x: x[\"score\"], reverse=True)\n\n # 5. Return top-k\n return ranked[:max_results]\n```\n\n**Time Complexity:** O(n) - must compare against every document\n**Latency:** ~50-200ms for 1,000 documents\n**Scalability:** Limited to ~10,000 documents\n\n#### DocumentDB (Native Vector Search)\n\n```python\n# File: registry/repositories/documentdb/search_repository.py\n\nasync def search(self, query: str, max_results: int = 10):\n # 1. Generate query embedding\n query_embedding = model.encode([query])[0]\n\n # 2. DocumentDB HNSW index search with tuned parameters\n ef_search = settings.vector_search_ef_search # Default: 100\n k_value = max(max_results * 3, 50)\n pipeline = [{\n \"$search\": {\n \"vectorSearch\": {\n \"vector\": query_embedding,\n \"path\": \"embedding\",\n \"similarity\": \"cosine\",\n \"k\": k_value,\n \"efSearch\": ef_search,\n }\n }\n }]\n\n # 3. DocumentDB returns sorted results (FAST!)\n results = await collection.aggregate(pipeline).to_list(k_value)\n\n # 4. Score all results, sort by hybrid score, pick top-3 per entity type\n return results\n```\n\n**Time Complexity:** O(log n) - HNSW index lookup\n**Latency:** ~10-50ms for millions of documents\n**Scalability:** Millions of documents\n\n### Search Resilience: Lexical Fallback\n\nBoth backends support automatic fallback to lexical-only search when the embedding model is unavailable. This ensures search remains operational even during embedding provider outages, misconfiguration, or API key expiration.\n\n**Behavior when embeddings are unavailable:**\n\n- Servers and agents are indexed without embeddings (empty vectors)\n- DocumentDB rejects 0-dimension vectors, so documents are stored without vector data\n- Search uses MongoDB aggregation with `$regexMatch` for keyword matching on path, name, description, tags, and tools\n- The `_load_error` cache in `SentenceTransformersClient` prevents repeated model download attempts\n- API response includes `\"search_mode\": \"lexical-only\"` to indicate degraded mode\n\n**Recovery:** Restart the service with correct embedding configuration. The error cache resets on restart and search returns to full hybrid mode.\n\nSee [Hybrid Search Architecture](hybrid-search-architecture.md) for detailed fallback flow and scoring.\n\n### Hybrid Search (Text + Vector)\n\nBoth backends support hybrid search combining:\n- **Vector similarity** (semantic matching)\n- **Text matching** (keyword boosting)\n\n**Example:**\n\n```python\n# Query: \"stock market\"\nresults = [\n {\n \"name\": \"Financial Analysis Server\",\n \"vector_score\": 0.85, # Cosine similarity\n \"normalized_vector\": 0.925, # (0.85 + 1.0) / 2.0\n \"text_boost\": 3.0, # \"market\" found in name\n \"boost_contrib\": 0.30, # 3.0 * 0.1\n \"final_score\": 1.0 # clamped to 1.0\n },\n {\n \"name\": \"Investment Tools\",\n \"vector_score\": 0.75, # Cosine similarity\n \"normalized_vector\": 0.875, # (0.75 + 1.0) / 2.0\n \"text_boost\": 0.0, # No keyword match\n \"boost_contrib\": 0.0,\n \"final_score\": 0.875\n }\n]\n```\n\n**Formula:**\n\n```\nnormalized_vector = (cosine_similarity + 1.0) / 2.0 # Map [-1,1] to [0,1]\nboost_contribution = text_boost * 0.1 # Scale boost down\nfinal_score = clamp(normalized_vector + boost_contribution, 0.0, 1.0)\n```\n\nThe `0.1` multiplier is consistent across both DocumentDB and MongoDB CE search paths. Semantic relevance is primary (normalized vector score dominates) while keyword matches provide a meaningful boost for exact references.\n\n---\n\n## Build and Run Process\n\n### Local Development with MongoDB CE\n\n**Script:** `build_and_run.sh`\n\n#### Flow\n\n```\n1. Load .env file\n └─> Check STORAGE_BACKEND variable\n\n2. If STORAGE_BACKEND = mongodb-ce or documentdb:\n └─> Create empty directories for Docker mounts\n └─> (Data stored in MongoDB, not local files)\n\n3. Start Docker Compose\n ├─> Start MongoDB container\n │ └─> Wait for healthcheck to pass\n ├─> Run mongodb-init container\n │ ├─> Initialize replica set\n │ ├─> Create collections\n │ └─> Create indexes\n └─> Start application services\n\n4. Application startup\n ├─> Repository factory creates DocumentDBRepository instances\n ├─> Search repository initializes\n │ └─> Creates vector index if not exists (DocumentDB only)\n └─> Services load data from MongoDB\n```\n\n#### Key Script Logic\n\n**File:** `build_and_run.sh` (lines 180-298)\n\n```bash\n# Build and run script always creates mount directories\n# and copies JSON files for all backends\n# (MongoDB/DocumentDB stores data in database, files are for initial seeding)\n\n# Create mount directories\nmkdir -p \"$MCPGATEWAY_SERVERS_DIR\"\nmkdir -p \"${HOME}/mcp-gateway/agents\"\nmkdir -p \"${HOME}/mcp-gateway/auth_server\"\nmkdir -p \"${HOME}/mcp-gateway/security_scans\"\ntouch \"${HOME}/mcp-gateway/federation.json\"\n\n# Copy server definitions from registry/servers/*.json\n# Copy agent cards from cli/examples/*agent*.json\n# Copy scopes.yml\n# (These provide initial data that can be imported via API)\n```\n\n### Starting the Stack\n\n```bash\n# 1. Ensure .env is configured\ncat .env | grep STORAGE_BACKEND\n# Should show: STORAGE_BACKEND=mongodb-ce\n\n# 2. Run build and run script\n./build_and_run.sh\n\n# What happens:\n# - MongoDB container starts\n# - Waits for healthcheck (ping succeeds)\n# - Runs init script (replica set + collections)\n# - Starts application services\n# - Registry connects to MongoDB\n# - Search repository creates vector index (if DocumentDB)\n```\n\n### Verifying MongoDB CE Setup\n\n```bash\n# 1. Check MongoDB is running\ndocker compose ps mongodb\n# Should show: Status = healthy\n\n# 2. Check collections were created\ndocker exec -it mcp-mongodb mongosh --eval \"use mcp_registry; show collections\"\n# Expected output:\n# mcp_agents_default\n# mcp_embeddings_1536_default\n# mcp_federation_config_default\n# mcp_scopes_default\n# mcp_security_scans_default\n# mcp_servers_default\n\n# 3. Check replica set status\ndocker exec -it mcp-mongodb mongosh --eval \"rs.status()\"\n# Should show: rs0 with 1 member (primary)\n\n# 4. Verify application can connect\ncurl http://localhost:7860/health\n# Should return: {\"status\": \"healthy\"}\n```\n\n### Data Flow\n\n```\nUser Action → API Endpoint → Service Layer → Repository\n───────────────────────────────────────────────────────────────────────\nRegister Server → POST /servers → server_service → DocumentDBServerRepository\n └─> MongoDB: mcp_servers_default\n\nSearch \"finance\" → GET /search → search_service → DocumentDBSearchRepository\n └─> MongoDB: mcp_embeddings_1536_default\n └─> Vector search (app-level)\n\nList Agents → GET /agents → agent_service → DocumentDBAgentRepository\n └─> MongoDB: mcp_agents_default\n```\n\n---\n\n## Repository Architecture\n\n### Abstract Base Classes\n\n**File:** `registry/repositories/interfaces.py`\n\nAll storage backends implement the same interfaces:\n\n```python\nclass ServerRepositoryBase(ABC):\n @abstractmethod\n async def get(self, path: str) -> Optional[Dict[str, Any]]: ...\n\n @abstractmethod\n async def list_all(self) -> Dict[str, Dict[str, Any]]: ...\n\n @abstractmethod\n async def create(self, server_info: Dict[str, Any]) -> bool: ...\n```\n\n### Factory Pattern\n\n**File:** `registry/repositories/factory.py`\n\n```python\ndef get_server_repository() -> ServerRepositoryBase:\n backend = settings.storage_backend\n\n if backend in [\"documentdb\", \"mongodb-ce\"]:\n from .documentdb.server_repository import DocumentDBServerRepository\n return DocumentDBServerRepository()\n else:\n from .file.server_repository import FileServerRepository\n return FileServerRepository()\n```\n\n**Key Point:** `mongodb-ce` and `documentdb` use the **same repository implementation**. The only difference is:\n- **mongodb-ce:** Connects to local MongoDB container\n- **documentdb:** Connects to AWS DocumentDB cluster\n\nThe repository code is identical - only the connection string changes!\n\n### Implementation Files\n\n**Directory:** `registry/repositories/documentdb/`\n\n```\ndocumentdb/\n├── __init__.py\n├── client.py # MongoDB/DocumentDB client management\n├── server_repository.py # Server CRUD operations\n├── agent_repository.py # Agent CRUD operations\n├── scope_repository.py # Authorization scopes\n├── search_repository.py # Vector search (app-level OR native)\n├── security_scan_repository.py # Security scan results\n└── federation_config_repository.py # Federation configuration\n```\n\n### Client Management\n\n**File:** `registry/repositories/documentdb/client.py`\n\n```python\nasync def get_documentdb_client() -> AsyncIOMotorDatabase:\n \"\"\"Get DocumentDB/MongoDB database client.\n\n Works with both:\n - MongoDB CE (local Docker)\n - AWS DocumentDB (production)\n\n Configuration via environment variables.\n \"\"\"\n if _client is None:\n connection_string = _build_connection_string()\n # Example (MongoDB CE):\n # mongodb://mongodb:27017/mcp_registry?replicaSet=rs0\n\n # Example (DocumentDB):\n # mongodb://user:pass@docdb-cluster.us-east-1.docdb.amazonaws.com:27017/\n # ?tls=true&tlsCAFile=/app/global-bundle.pem&replicaSet=rs0\n\n motor_client = AsyncIOMotorClient(connection_string)\n _client = motor_client[settings.documentdb_database]\n\n return _client\n\ndef get_collection_name(base_name: str) -> str:\n \"\"\"Add namespace suffix to collection name.\"\"\"\n return f\"{base_name}_{settings.documentdb_namespace}\"\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n**File:** `.env`\n\n```bash\n# ============================================================================\n# STORAGE BACKEND CONFIGURATION\n# ============================================================================\n\n# Backend selection\nSTORAGE_BACKEND=mongodb-ce # Options: file, mongodb-ce, documentdb\n\n# MongoDB/DocumentDB connection\nDOCUMENTDB_HOST=mongodb # MongoDB CE: \"mongodb\"\n # DocumentDB: \"cluster.us-east-1.docdb.amazonaws.com\"\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=default # Multi-tenancy: dev, staging, production\n\n# Authentication (not needed for MongoDB CE local)\nDOCUMENTDB_USERNAME=admin # DocumentDB: actual username\nDOCUMENTDB_PASSWORD=secure_password # DocumentDB: from Secrets Manager\n\n# TLS/Security (MongoDB CE: disabled, DocumentDB: enabled)\nDOCUMENTDB_USE_TLS=false # MongoDB CE: false\n # DocumentDB: true\nDOCUMENTDB_TLS_CA_FILE=global-bundle.pem # DocumentDB CA bundle\nDOCUMENTDB_USE_IAM=false # DocumentDB: set true for IAM auth\n\n# Replica set configuration\nDOCUMENTDB_REPLICA_SET=rs0\nDOCUMENTDB_READ_PREFERENCE=secondaryPreferred # Load balance reads\n\n# ============================================================================\n# EMBEDDINGS CONFIGURATION\n# ============================================================================\n\n# Embedding provider\nEMBEDDINGS_PROVIDER=sentence-transformers # Options: sentence-transformers, litellm\nEMBEDDINGS_MODEL_NAME=all-MiniLM-L6-v2 # Or: openai/text-embedding-ada-002\nEMBEDDINGS_MODEL_DIMENSIONS=384 # Or: 1536 for OpenAI/Titan\n\n# For cloud embeddings\nEMBEDDINGS_API_KEY= # OpenAI: sk-...\n # Bedrock: uses IAM (leave empty)\nEMBEDDINGS_AWS_REGION=us-east-1 # For Amazon Bedrock\n```\n\n### Docker Compose\n\n**File:** `docker-compose.yml`\n\n```yaml\nservices:\n # MongoDB CE 8.2\n mongodb:\n image: mongo:8.2\n container_name: mcp-mongodb\n command: mongod --replSet rs0 --bind_ip 127.0.0.1,mongodb\n ports:\n - \"27017:27017\"\n volumes:\n - mongodb-data:/data/db\n - mongodb-config:/data/configdb\n healthcheck:\n test: [\"CMD\", \"mongosh\", \"--eval\", \"db.adminCommand('ping')\"]\n interval: 10s\n timeout: 5s\n retries: 5\n start_period: 20s\n restart: unless-stopped\n\n # MongoDB initialization (runs once)\n mongodb-init:\n image: mongo:8.2\n container_name: mcp-mongodb-init\n depends_on:\n mongodb:\n condition: service_healthy\n environment:\n - DOCUMENTDB_HOST=mongodb\n - DOCUMENTDB_PORT=27017\n - DOCUMENTDB_DATABASE=${DOCUMENTDB_DATABASE:-mcp_registry}\n - DOCUMENTDB_NAMESPACE=${DOCUMENTDB_NAMESPACE:-default}\n volumes:\n - ./scripts/init-mongodb.sh:/init-mongodb.sh:ro\n entrypoint: [\"/bin/bash\", \"/init-mongodb.sh\"]\n restart: \"no\"\n\nvolumes:\n mongodb-data:\n mongodb-config:\n```\n\n### Terraform (DocumentDB)\n\n**File:** `terraform/aws-ecs/modules/documentdb/variables.tf`\n\n```hcl\nvariable \"cluster_name\" {\n description = \"DocumentDB cluster name\"\n type = string\n}\n\nvariable \"instance_class\" {\n description = \"Instance class (e.g., db.r5.large)\"\n type = string\n default = \"db.r5.large\"\n}\n\nvariable \"instance_count\" {\n description = \"Number of instances (1 writer + N readers)\"\n type = number\n default = 3 # 1 writer + 2 readers\n}\n\nvariable \"master_username\" {\n description = \"Master username\"\n type = string\n sensitive = true\n}\n\nvariable \"master_password\" {\n description = \"Master password\"\n type = string\n sensitive = true\n}\n\nvariable \"backup_retention_period\" {\n description = \"Backup retention in days\"\n type = number\n default = 7\n}\n```\n\n---\n\n## Migration Strategy\n\n### From File Backend to MongoDB CE\n\n**Scenario:** Moving from JSON files to MongoDB for local development\n\n**Steps:**\n\n1. **Export existing data**\n ```bash\n # Servers\n cp ~/mcp-gateway/servers/*.json /tmp/servers-backup/\n\n # Agents\n cp ~/mcp-gateway/agents/*.json /tmp/agents-backup/\n ```\n\n2. **Update configuration**\n ```bash\n # In .env\n sed -i 's/STORAGE_BACKEND=file/STORAGE_BACKEND=mongodb-ce/' .env\n ```\n\n3. **Start MongoDB**\n ```bash\n docker compose up -d mongodb\n docker compose up mongodb-init\n ```\n\n4. **Import data via API**\n ```bash\n # Re-register servers\n for file in /tmp/servers-backup/*.json; do\n curl -X POST http://localhost:7860/servers \\\n -H \"Content-Type: application/json\" \\\n -d @\"$file\"\n done\n\n # Re-register agents\n for file in /tmp/agents-backup/*.json; do\n curl -X POST http://localhost:7860/agents \\\n -H \"Content-Type: application/json\" \\\n -d @\"$file\"\n done\n ```\n\n5. **Verify**\n ```bash\n # Check server count\n curl http://localhost:7860/servers | jq 'length'\n\n # Test search\n curl \"http://localhost:7860/search?q=financial\" | jq '.servers | length'\n ```\n\n### From MongoDB CE to AWS DocumentDB\n\n**Scenario:** Moving from local development to production\n\n**Steps:**\n\n1. **Export from MongoDB CE**\n ```bash\n # Dump all collections\n docker exec mcp-mongodb mongodump \\\n --db=mcp_registry \\\n --out=/tmp/mongodb-backup\n\n # Copy backup from container\n docker cp mcp-mongodb:/tmp/mongodb-backup ./mongodb-backup\n ```\n\n2. **Deploy DocumentDB with Terraform**\n ```bash\n cd terraform/aws-ecs\n terraform apply\n\n # Get DocumentDB endpoint\n terraform output documentdb_endpoint\n ```\n\n3. **Import to DocumentDB**\n ```bash\n # From bastion host or ECS task\n mongorestore \\\n --host=mcp-registry.cluster-xxxxx.us-east-1.docdb.amazonaws.com:27017 \\\n --ssl \\\n --sslCAFile=/app/global-bundle.pem \\\n --username=mcp_admin \\\n --password= \\\n --db=mcp_registry \\\n ./mongodb-backup/mcp_registry\n ```\n\n4. **Update application configuration**\n ```bash\n # In .env\n STORAGE_BACKEND=documentdb\n DOCUMENTDB_HOST=mcp-registry.cluster-xxxxx.us-east-1.docdb.amazonaws.com\n DOCUMENTDB_USERNAME=mcp_admin\n DOCUMENTDB_PASSWORD=\n DOCUMENTDB_USE_TLS=true\n DOCUMENTDB_TLS_CA_FILE=/app/global-bundle.pem\n ```\n\n5. **Deploy application**\n ```bash\n terraform apply\n ```\n\n6. **Verify vector search**\n ```bash\n # Test search endpoint\n curl \"https://api.example.com/search?q=financial\" | jq '.servers'\n\n # Should return results with relevance_score\n # DocumentDB will use native HNSW index (faster!)\n ```\n\n---\n\n## Summary\n\n### Architecture Highlights\n\n| Component | MongoDB CE | AWS DocumentDB |\n|-----------|------------|----------------|\n| **Container** | mongo:8.2 | Managed Service |\n| **Connection** | mongodb://mongodb:27017 | mongodb://cluster.docdb.amazonaws.com:27017 |\n| **Authentication** | None (local) | Username/Password or IAM |\n| **TLS** | Disabled | Required |\n| **Vector Search** | App-level (Python) | Native (HNSW) |\n| **Latency** | 50-200ms | 10-50ms |\n| **Max Scale** | ~10,000 docs | Millions |\n| **Cost** | Free | AWS pricing |\n\n### Key Takeaways\n\n1. **Same Code, Different Backends**\n - Identical repository implementation\n - Only connection configuration differs\n - Seamless migration path\n\n2. **Vector Search Strategy**\n - MongoDB CE: Application-level for dev simplicity\n - DocumentDB: Native HNSW for production performance\n - Both use cosine similarity metric\n\n3. **Development Workflow**\n - Local dev: `STORAGE_BACKEND=mongodb-ce`\n - Production: `STORAGE_BACKEND=documentdb`\n - Terraform handles infrastructure\n\n4. **No Terraform Changes**\n - AWS DocumentDB infrastructure deployed via Terraform\n - Local MongoDB CE runs in Docker Compose\n - Terraform only manages AWS resources\n\n---\n\n## See Also\n\n- [Database Abstraction Layer Design](./database-abstraction-layer.md)\n- [Embeddings Configuration](../embeddings.md)\n- [Configuration Guide](../configuration.md)\n- [MongoDB Documentation](https://www.mongodb.com/docs/manual/)\n- [AWS DocumentDB Documentation](https://docs.aws.amazon.com/documentdb/)\n" }, { "path": "docs/design/virtual-mcp-server-explained.md", "content": "# Virtual MCP Server - How It Works\n\nThis document explains how Virtual MCP Servers work using diagrams and examples. For detailed implementation specifics, see [virtual-mcp-server.md](virtual-mcp-server.md).\n\n---\n\n## What Problem Are We Solving?\n\nConsider a typical development setup: you have separate MCP servers for GitHub (code search, PRs), Slack (messaging), and Jira (issue tracking). Your AI agent needs tools from all three, which means:\n\n- Managing three separate connections\n- Handling three different sessions\n- Dealing with tool name conflicts (both GitHub and Jira have a `search` tool)\n\nA Virtual MCP Server solves this by providing a **single endpoint** that aggregates tools from multiple backends. Your agent connects once and gets access to all the tools it needs.\n\n```\nWITHOUT Virtual Server: WITH Virtual Server:\n\n You You\n | |\n +---> GitHub Server |\n | |-> search v\n | |-> create_pr +------------+\n | | Virtual |\n +---> Slack Server | Server |\n | |-> send_message +-----+------+\n | |-> list_channels |\n | +-----+-----+-----+\n +---> Jira Server | | |\n |-> create_issue v v v\n |-> search_issues GitHub Slack Jira\n Server Server Server\n```\n\n**Benefits:**\n- Your app only connects to ONE server instead of many\n- You can pick exactly which tools you want from each backend\n- You can rename tools to avoid confusion (like \"github_search\" vs \"jira_search\")\n- You can control who has access to which tools\n\n---\n\n## The Big Picture\n\nRequest flow when a client connects to a Virtual MCP Server:\n\n```\n+----------------+ +------------------+\n| Your App | | MCP Gateway |\n| | | |\n| \"I want to | ---(1) Request --> | Nginx receives |\n| search on | | your request |\n| GitHub\" | +--------+---------+\n| | |\n| | v\n| | +------------------+\n| | | Lua Router |\n| | | (the brain) |\n| | | |\n| | | \"Ah, this tool |\n| | | belongs to |\n| | | GitHub backend\"|\n| | +--------+---------+\n| | |\n| | v\n| | +------------------+\n| | | GitHub Backend |\n| | | |\n| | <--(4) Response -- | (does the |\n| | | actual work) |\n+----------------+ +------------------+\n```\n\nEach component is described below.\n\n---\n\n## The Three Key Players\n\n### 1. Nginx (Reverse Proxy)\n\nNginx receives incoming requests and handles:\n\n- JWT authentication via `auth_request` subrequest\n- Path-based routing to determine which virtual server\n- Invoking the Lua content handler for MCP protocol processing\n\n```\nRequest arrives at /virtual/dev-tools\n |\n v\n +---------------+\n | Nginx |\n | |\n | 1. Check JWT | <-- \"Is this token valid?\"\n | 2. Read path | <-- \"Which virtual server?\"\n | 3. Call Lua | <-- \"Hand off to the router\"\n +---------------+\n```\n\n### 2. Lua Router (Content Handler)\n\nThe Lua router (`virtual_router.lua`) runs as an nginx content handler. It:\n\n- Reads tool-to-backend mappings from JSON config files\n- Translates tool aliases back to original names\n- Manages session multiplexing across backends\n- Issues concurrent subrequests for aggregation methods\n\n### 3. Backend Servers\n\nThe actual MCP servers (GitHub, Slack, Jira, etc.) that execute tool calls. The virtual server coordinates requests but delegates all execution to backends.\n\n---\n\n## How Tool Mapping Works\n\nThis is the core mechanism. The process works as follows:\n\n### Step 1: Configuration is Created\n\nWhen someone creates a virtual server, they specify which tools to include:\n\n```\nVirtual Server: \"dev-tools\"\nPath: /virtual/dev-tools\n\nTool Mappings:\n +------------------+------------------+------------------+\n | Tool Name | Backend Server | Alias |\n +------------------+------------------+------------------+\n | search | /github | github_search |\n | search | /jira | jira_search |\n | send_message | /slack | (none - use as-is)|\n +------------------+------------------+------------------+\n```\n\nBoth GitHub and Jira have a tool called \"search\". Aliases resolve this naming conflict.\n\n### Step 2: Mapping File is Generated\n\nThe system writes a JSON file that the Lua router will read:\n\n```\nFile: /etc/nginx/lua/virtual_mappings/dev-tools.json\n\n{\n \"tool_backend_map\": {\n \"github_search\": {\n \"original_name\": \"search\",\n \"backend_location\": \"/_backend/github\"\n },\n \"jira_search\": {\n \"original_name\": \"search\",\n \"backend_location\": \"/_backend/jira\"\n },\n \"send_message\": {\n \"original_name\": \"send_message\",\n \"backend_location\": \"/_backend/slack\"\n }\n }\n}\n```\n\nThis file is a lookup table mapping tool names to their backend locations.\n\n### Step 3: Request Comes In\n\nWhen your app calls a tool:\n\n```\nYour app sends:\n{\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"github_search\", <-- The alias you see\n \"arguments\": { \"query\": \"bug fixes\" }\n }\n}\n```\n\n### Step 4: Lua Router Translates\n\nThe Lua router:\n1. Reads the mapping file\n2. Looks up \"github_search\"\n3. Finds: backend is \"/_backend/github\", original name is \"search\"\n4. Rewrites the request:\n\n```\nForwarded to /_backend/github:\n{\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"search\", <-- Original name the backend knows\n \"arguments\": { \"query\": \"bug fixes\" }\n }\n}\n```\n\n### Step 5: Response Goes Back\n\nThe GitHub backend responds. The Lua router passes it back to your app unchanged.\n\n---\n\n## The Complete Request Flow (Sequence Diagram)\n\nSequence diagram for a `tools/call` request:\n\n```\nYour App Nginx Lua Router Backend\n | | | |\n | POST /virtual/dev-tools | |\n | tools/call: github_search | |\n |--------------->| | |\n | | | |\n | | auth_request | |\n | | (check JWT) | |\n | |----------------->| |\n | | OK + scopes | |\n | |<-----------------| |\n | | | |\n | | content_by_lua | |\n | |----------------->| |\n | | | |\n | | Read mapping file |\n | | \"github_search\" -> |\n | | backend: /_backend/github |\n | | original: search |\n | | | |\n | | Check session cache |\n | | (do we have a session |\n | | with this backend?) |\n | | | |\n | | Rewrite tool name |\n | | github_search -> search |\n | | | |\n | | | POST to |\n | | | /_backend/github\n | | |-------------->|\n | | | |\n | | | Response |\n | | |<--------------|\n | | | |\n |<----------------------------------| |\n | Response | |\n```\n\n---\n\n## Session Management (The Tricky Part)\n\nEach backend server requires its own session.\n\nWhen your app connects to the virtual server, it gets ONE session ID:\n\n```\nYour app <---> Virtual Server (session: vs-abc123)\n```\n\nBut behind the scenes, the virtual server maintains SEPARATE sessions with each backend:\n\n```\nVirtual Server:\n +-- Session with GitHub: sess-gh-001\n +-- Session with Slack: sess-sl-002\n +-- Session with Jira: sess-jr-003\n```\n\nThe Lua router keeps track of this mapping so you don't have to.\n\n### The Two-Tier Cache\n\nLooking up sessions from the database on every request would be slow. So we use two levels of caching:\n\n```\nRequest: \"What's the GitHub session for client vs-abc123?\"\n\n +-------------------+\n | Level 1 Cache | <-- Super fast (in nginx memory)\n | (Shared Dict) | TTL: 30 seconds\n | |\n | \"Do I have it?\" |\n +--------+----------+\n |\n MISS |\n v\n +-------------------+\n | Level 2 Cache | <-- Fast (MongoDB lookup)\n | (MongoDB) | TTL: 1 hour\n | |\n | \"Check database\" |\n +--------+----------+\n |\n MISS |\n v\n +-------------------+\n | Create New | <-- Send \"initialize\" to backend\n | Session | Store in both caches\n +-------------------+\n```\n\n**Why two levels?**\n- Level 1 is in memory - no network call, extremely fast\n- Level 2 is in MongoDB - survives server restarts\n- If the server restarts, we lose Level 1 but Level 2 still has sessions\n\n---\n\n## Listing Tools (Aggregation)\n\nWhen your app asks \"what tools do you have?\", the virtual server needs to ask ALL backends:\n\n```\nYour app asks: tools/list\n\nLua Router:\n +-- Ask GitHub: \"What tools do you have?\"\n | Response: [search, create_pr, list_repos]\n |\n +-- Ask Slack: \"What tools do you have?\"\n | Response: [send_message, list_channels]\n |\n +-- Ask Jira: \"What tools do you have?\"\n Response: [create_issue, search_issues]\n\nLua Router combines them:\n [github_search, create_pr, list_repos, <-- Applied aliases\n send_message, list_channels,\n jira_search, create_issue] <-- Renamed \"search\" to \"jira_search\"\n```\n\n**Important optimization:** These backend calls happen IN PARALLEL, not one after another. This makes the aggregation fast.\n\n```\nTime ------>\n\nSequential (slow):\n [GitHub call]---[Slack call]---[Jira call]---Done\n\nParallel (fast):\n [GitHub call]-----\n [Slack call]------+---Done\n [Jira call]-------\n```\n\n---\n\n## What the Nginx Config Looks Like\n\nWhen a virtual server is enabled, the system generates two things:\n\n### 1. A Location Block (for routing)\n\n```nginx\nlocation /virtual/dev-tools {\n # Tell Lua which virtual server this is\n set $virtual_server_id \"dev-tools\";\n\n # Check authentication first\n auth_request /validate;\n\n # Run the Lua router\n content_by_lua_file /etc/nginx/lua/virtual_router.lua;\n}\n```\n\n### 2. Internal Backend Locations\n\n```nginx\n# These are marked \"internal\" - only Lua can use them\n# Regular users can't access them directly\n\nlocation /_backend/github {\n internal;\n proxy_pass https://github-mcp.example.com/mcp;\n}\n\nlocation /_backend/slack {\n internal;\n proxy_pass https://slack-mcp.example.com/mcp;\n}\n```\n\nThe Lua router uses these internal locations to talk to backends.\n\n---\n\n## Error Handling\n\nWhat happens when things go wrong?\n\n### Backend is Down\n\n```\nLua Router tries to call /_backend/github\n |\n v\nConnection fails or returns error\n |\n v\nLua Router returns error to your app:\n{\n \"error\": {\n \"code\": -32000,\n \"message\": \"Backend server unreachable: /github\"\n }\n}\n```\n\n### Session Expired\n\n```\nLua Router uses cached session sess-gh-001\n |\n v\nGitHub returns: \"400 Bad Request - Invalid session\"\n |\n v\nLua Router:\n 1. Delete sess-gh-001 from both caches\n 2. Send new \"initialize\" to GitHub\n 3. Get new session: sess-gh-002\n 4. Cache it in both levels\n 5. Retry the original request with new session\n```\n\n### User Lacks Permission\n\n```\nUser has scopes: [\"mcp-access\"]\nTool \"create_pr\" requires: [\"github-write\"]\n |\n v\nLua Router checks scopes... DENIED\n |\n v\nResponse: 403 Forbidden\n{\n \"error\": \"Missing required scope: github-write\"\n}\n```\n\n---\n\n## Access Control in Simple Terms\n\nAccess control works at two levels:\n\n### Level 1: Server Access\n\nTo use the virtual server at all, you need certain scopes:\n\n```\nVirtual Server: /virtual/dev-tools\nRequired Scopes: [\"mcp-access\"]\n\nUser with scopes [\"mcp-access\"] -> Allowed in\nUser with scopes [\"other-stuff\"] -> Blocked at the door\n```\n\n### Level 2: Tool Access\n\nIndividual tools can require additional scopes:\n\n```\nTool: create_pr\nRequired Scopes: [\"github-write\"]\n\nUser with [\"mcp-access\", \"github-read\"] -> Can't use this tool\nUser with [\"mcp-access\", \"github-write\"] -> Can use this tool\n```\n\nWhen listing tools, the Lua router hides tools the user can't access:\n\n```\nFull tool list: [search, create_pr, delete_repo]\nUser scopes: [\"mcp-access\", \"github-read\"]\n\nFiltered list: [search] <-- Only shows tools user can actually use\n```\n\n---\n\n## How Changes Are Applied\n\nWhen you create or update a virtual server:\n\n```\n1. You call the API: POST /api/virtual-servers\n |\n v\n2. Service validates the configuration\n - Does each backend server exist?\n - Does each tool exist on its backend?\n - Are all alias names unique?\n |\n v\n3. Configuration saved to MongoDB\n |\n v\n4. Nginx config regenerated\n - New location block written\n - New mapping JSON file written\n |\n v\n5. Nginx reloaded\n - nginx -s reload\n - New config takes effect immediately\n |\n v\n6. Virtual server is live!\n```\n\n---\n\n## Quick Reference\n\n### Files You Should Know\n\n| File | What It Does |\n|------|-------------|\n| `virtual_router.lua` | The Lua brain that routes requests |\n| `nginx_service.py` | Generates nginx config + mapping files |\n| `virtual_server_service.py` | Business logic and validation |\n| `virtual_server_routes.py` | REST API endpoints |\n| `/etc/nginx/lua/virtual_mappings/*.json` | Tool mapping files read by Lua |\n\n### Key Concepts\n\n| Term | Plain English |\n|------|--------------|\n| Virtual Server | A fake server that coordinates real servers |\n| Tool Mapping | \"This tool comes from that backend\" |\n| Alias | A renamed tool to avoid confusion |\n| Backend Location | Where to forward requests (internal nginx path) |\n| Session Multiplexing | One client session, many backend sessions |\n| Scope | A permission string that controls access |\n\n### Common Operations\n\n| What You Want | What Happens |\n|---------------|--------------|\n| List tools | Asks all backends in parallel, combines results |\n| Call a tool | Looks up backend, translates name, forwards request |\n| Initialize | Creates client session, backend sessions are lazy |\n| Ping | Responds immediately, no backend calls |\n\n---\n\n## Summary\n\n1. **Virtual servers aggregate tools** from multiple backends into one endpoint\n2. **Nginx routes requests** to the Lua router based on path\n3. **Lua router reads mapping files** to know which tool goes where\n4. **Aliases solve naming conflicts** when two backends have same tool names\n5. **Sessions are cached in two levels** for speed and reliability\n6. **Access control works at server and tool level** using scopes\n7. **Backend calls happen in parallel** when listing tools\n\nThe virtual server acts as a coordinator - all tool execution happens on the backend servers. The virtual server's role is to present a unified endpoint to clients.\n" }, { "path": "docs/design/virtual-mcp-server.md", "content": "# Virtual MCP Server - Design Document\n\n**Date**: 2026-02-10\n**Status**: Implemented\n**PR**: [#459](https://github.com/agentic-community/mcp-gateway-registry/pull/459)\n**Issue**: [#129](https://github.com/agentic-community/mcp-gateway-registry/issues/129)\n\n---\n\n## 1. Overview\n\nA Virtual MCP Server is a gateway-level construct that aggregates tools, resources, and prompts from multiple backend MCP servers into a single unified endpoint. Instead of connecting to individual MCP servers, clients connect to a virtual server that presents a curated, access-controlled view of capabilities drawn from any combination of registered backends.\n\n### Problem Statement\n\nOrganizations deploying multiple MCP servers face several operational challenges:\n\n- **Client complexity**: Each client must discover, connect to, and manage sessions with every individual MCP server it needs\n- **Tool sprawl**: Teams cannot curate role-specific or project-specific tool bundles from existing servers\n- **Naming conflicts**: Two backend servers may expose tools with the same name (e.g., both GitHub and GitLab expose a `search` tool)\n- **Version drift**: No mechanism to pin a client to a specific backend server version while allowing others to upgrade\n- **Access control gaps**: Authorization is all-or-nothing per server, with no per-tool granularity\n\n### Solution\n\nVirtual MCP Servers solve these problems by introducing a composition layer at the gateway:\n\n```\n +-----------------------+\n | Virtual MCP Server |\n | /virtual/dev-tools |\n +-----------+-----------+\n |\n +-----------------+-----------------+\n | | |\n +-----+-----+ +-----+-----+ +-----+-----+\n | /github | | /slack | | /jira |\n | Backend | | Backend | | Backend |\n +-----+-----+ +-----+-----+ +-----+-----+\n | | |\n search-repo post-message create-ticket\n create-pr list-channels search-issues\n```\n\nA client connecting to `/virtual/dev-tools` sees `search-repo`, `post-message`, `create-ticket`, `list-channels`, `create-pr`, and `search-issues` as a single flat tool list, regardless of which backend provides each tool.\n\n### Key Capabilities\n\n| Capability | Description |\n|------------|-------------|\n| Tool aggregation | Merge tools from multiple backends into one endpoint |\n| Tool aliasing | Rename tools to resolve conflicts or improve clarity |\n| Version pinning | Lock a tool mapping to a specific backend server version |\n| Scope-based access control | Server-level and per-tool scope requirements |\n| Session multiplexing | One client session maps to N backend sessions transparently |\n| Resource and prompt aggregation | Aggregate `resources/list` and `prompts/list` across backends |\n\n---\n\n## 2. Architecture\n\n### System Context\n\n```\n+------------------------------------------------------------+\n| MCP Gateway |\n| |\n| +------------------+ +---------------------------+ |\n| | FastAPI Registry | | Nginx Reverse Proxy | |\n| | (Port 7860) | | (Port 80/443) | |\n| | | | | |\n| | - CRUD API |<----->| - Auth validation | |\n| | - Tool catalog | | - Location routing | |\n| | - Session store | | - Lua router execution | |\n| +------------------+ +-------------+-------------+ |\n| | |\n| +------------+------------+ |\n| | virtual_router.lua | |\n| | - JSON-RPC dispatch | |\n| | - Session multiplexing | |\n| | - Tool aggregation | |\n| | - Alias translation | |\n| +------------+------------+ |\n| | |\n+-------------------------------------------|----------------+\n |\n +----------+----------+----------+\n | | | |\n Backend Backend Backend Backend\n Server A Server B Server C Server D\n```\n\n### Request Lifecycle\n\n1. Client sends an MCP JSON-RPC request to `/virtual/{server-slug}`\n2. Nginx matches the location block and issues an `auth_request` to validate the JWT\n3. The auth subrequest returns user scopes in response headers\n4. Nginx invokes `virtual_router.lua` as the content handler\n5. Lua loads the virtual server mapping file from disk (`/etc/nginx/lua/virtual_mappings/{id}.json`)\n6. Lua validates user scopes against server-level `required_scopes`\n7. Lua dispatches the request based on JSON-RPC method:\n - **`initialize`**: Creates a client session in MongoDB, returns MCP capabilities\n - **`tools/list`**: Fetches tools from each distinct backend (concurrent subrequests), applies aliases and scope filtering, returns merged list\n - **`tools/call`**: Looks up the tool in the mapping, translates alias back to original name, routes to the correct backend with the appropriate backend session\n - **`resources/list`** / **`prompts/list`**: Aggregates from all backends, builds a lookup map for subsequent read/get calls\n - **`resources/read`** / **`prompts/get`**: Uses the lookup map to route to the owning backend\n - **`ping`**: Responds directly without contacting backends\n\n### Component Responsibilities\n\n| Component | Responsibility |\n|-----------|---------------|\n| `virtual_server_models.py` | Pydantic data models for configuration, requests, and responses |\n| `virtual_server_repository.py` | MongoDB persistence (CRUD on `virtual_servers` collection) |\n| `virtual_server_service.py` | Business logic: validation, tool resolution, nginx reload coordination |\n| `tool_catalog_service.py` | Aggregates available tools across all enabled backend servers |\n| `virtual_server_routes.py` | REST API endpoints for management |\n| `nginx_service.py` | Generates nginx location blocks, backend proxies, and Lua mapping files |\n| `virtual_router.lua` | Runtime JSON-RPC routing, session management, tool aggregation |\n| `backend_session_repository.py` | MongoDB persistence for backend session tracking |\n| Frontend components | React management UI with multi-step wizard |\n\n---\n\n## 3. Data Model\n\n### Virtual Server Configuration\n\nThe primary configuration document stored in MongoDB:\n\n```python\nclass VirtualServerConfig:\n path: str # e.g., \"/virtual/dev-tools\"\n server_name: str # e.g., \"Dev Tools\"\n description: Optional[str]\n tool_mappings: List[ToolMapping] # At least one required\n required_scopes: List[str] # Server-level scope requirements\n tool_scope_overrides: List[ToolScopeOverride]\n tags: List[str]\n supported_transports: List[str] # Default: [\"streamable-http\"]\n is_enabled: bool # Controls nginx routing\n num_stars: float # Average rating (0.0-5.0)\n rating_details: List[dict] # Individual ratings [{user, rating}]\n created_by: Optional[str]\n created_at: datetime\n updated_at: datetime\n```\n\n### Tool Mapping\n\nEach tool mapping connects a tool from a backend server to the virtual server:\n\n```python\nclass ToolMapping:\n tool_name: str # Original tool name on backend\n alias: Optional[str] # Renamed tool in virtual server\n backend_server_path: str # e.g., \"/github\"\n backend_version: Optional[str] # Pin to specific version\n description_override: Optional[str]\n```\n\nThe effective tool name exposed to clients is `alias` if set, otherwise `tool_name`. This enables conflict resolution when two backends expose tools with the same name.\n\n### Tool Scope Override\n\nPer-tool access control layered on top of server-level scopes:\n\n```python\nclass ToolScopeOverride:\n tool_alias: str # Matches alias or tool_name\n required_scopes: List[str] # Additional scopes for this tool\n```\n\n### Backend Session\n\nTracks the session mapping between a client session and each backend:\n\n```python\nclass BackendSession:\n client_session_id: str\n backend_location: str # e.g., \"/_backend/github\"\n backend_session_id: str\n created_at: datetime\n expires_at: datetime # TTL-based expiry\n```\n\n### Storage Design\n\n| Collection | `_id` | Purpose |\n|------------|-------|---------|\n| `virtual_servers` | path (e.g., `/virtual/dev-tools`) | Virtual server configuration |\n| `backend_sessions` | `{client_session_id}:{backend_location}` | Session mapping with TTL index |\n| `client_sessions` | `{session_id}` | Client session metadata for audit |\n\nIndexes on `virtual_servers`:\n- `is_enabled` (for listing active servers)\n- `tags` (for filtering)\n- `server_name` (for search)\n- Compound: `is_enabled` + `tags`\n\n---\n\n## 4. Session Management\n\n### Two-Tier Caching\n\nThe Lua router uses a two-tier cache to minimize latency for session lookups:\n\n```\nRequest arrives\n |\n v\n+-------------------+\n| L1: Shared Dict | nginx shared memory (lua_shared_dict)\n| TTL: 30 seconds | Key: \"bsess:{client_session}:{backend_location}\"\n+--------+----------+\n | miss\n v\n+-------------------+\n| L2: MongoDB | via internal API subrequest\n| TTL: 1 hour | GET /_internal/sessions/{client_session}/{backend}\n+--------+----------+\n | miss\n v\n+-------------------+\n| Initialize | POST to backend with MCP initialize\n| Backend Session | Store result in L1 + L2\n+-------------------+\n```\n\n**L1 Cache (Nginx Shared Dictionary)**:\n- In-worker memory, no network calls\n- 30-second TTL keeps sessions warm for burst traffic\n- 2 MB allocation (`lua_shared_dict virtual_server_map 2m`)\n\n**L2 Cache (MongoDB)**:\n- Survives nginx reloads and worker restarts\n- 1-hour TTL with MongoDB TTL index on `expires_at`\n- Accessed via FastAPI internal endpoints (`/_internal/sessions/*`)\n\n### Session Lifecycle\n\n1. Client calls `initialize` on the virtual server endpoint\n2. Lua generates a client session ID (`vs-{uuid}`) and stores it in MongoDB\n3. Lua returns `Mcp-Session-Id` header to the client\n4. On subsequent requests, client includes `Mcp-Session-Id`\n5. For each backend involved in the request:\n - Check L1 cache for existing backend session\n - On miss, check L2 (MongoDB)\n - On miss, send `initialize` to the backend, store the returned session ID in both L1 and L2\n6. If a backend returns HTTP 400+, Lua invalidates the stale session in both tiers and retries with a fresh session\n\n---\n\n## 5. Nginx Configuration Generation\n\nWhen a virtual server is created, updated, toggled, or deleted, the registry regenerates the nginx configuration. This process is serialized with an `asyncio.Lock` to prevent concurrent reloads.\n\n### Generated Artifacts\n\nFor each enabled virtual server, three artifacts are produced:\n\n**1. Location Block** (in `nginx.conf`):\n\n```nginx\n# Virtual MCP Server: Dev Tools\nlocation /virtual/dev-tools {\n set $virtual_server_id \"dev-tools\";\n auth_request /validate;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_user $upstream_http_x_user;\n\n rewrite_by_lua_file /etc/nginx/lua/capture_body.lua;\n content_by_lua_file /etc/nginx/lua/virtual_router.lua;\n}\n```\n\n**2. Internal Backend Locations** (one per unique backend referenced by any virtual server):\n\n```nginx\nlocation /_backend/github {\n internal;\n proxy_pass https://github-mcp.example.com;\n proxy_set_header Host github-mcp.example.com;\n # ... standard proxy headers\n}\n```\n\n**3. JSON Mapping File** (`/etc/nginx/lua/virtual_mappings/dev-tools.json`):\n\n```json\n{\n \"required_scopes\": [\"mcp-access\"],\n \"tools\": [\n {\n \"name\": \"search-repo\",\n \"original_name\": \"search\",\n \"backend_location\": \"/_backend/github\",\n \"backend_version\": null,\n \"description\": \"Search repositories\",\n \"required_scopes\": [\"github-access\"],\n \"inputSchema\": { \"type\": \"object\", \"properties\": { \"query\": { \"type\": \"string\" } } }\n }\n ],\n \"tool_backend_map\": {\n \"search-repo\": {\n \"original_name\": \"search\",\n \"backend_location\": \"/_backend/github\",\n \"backend_version\": null,\n \"required_scopes\": [\"github-access\"]\n }\n }\n}\n```\n\nThe mapping file is read by the Lua router at request time. It provides pre-computed lookup tables so the router does not need to query the registry API for tool metadata on every request.\n\n---\n\n## 6. Tool Aliasing and Version Pinning\n\n### Tool Aliasing\n\nTool aliasing solves naming conflicts and improves tool discoverability:\n\n```\nBackend /github exposes: search, create_pr, list_repos\nBackend /gitlab exposes: search, create_mr, list_projects\n```\n\nWithout aliasing, both `search` tools would collide. With aliasing:\n\n```json\n{\n \"tool_mappings\": [\n { \"tool_name\": \"search\", \"alias\": \"github-search\", \"backend_server_path\": \"/github\" },\n { \"tool_name\": \"search\", \"alias\": \"gitlab-search\", \"backend_server_path\": \"/gitlab\" }\n ]\n}\n```\n\nThe client sees `github-search` and `gitlab-search`. When the client calls `github-search`, the Lua router translates it back to `search` before proxying to the `/github` backend.\n\n### Version Pinning\n\nVersion pinning locks a tool mapping to a specific backend server version:\n\n```json\n{\n \"tool_name\": \"search\",\n \"alias\": \"search-repo\",\n \"backend_server_path\": \"/github\",\n \"backend_version\": \"v1.5.0\"\n}\n```\n\nWhen proxying to the backend, the Lua router sets the `X-MCP-Server-Version: v1.5.0` header. The nginx configuration for versioned backends uses separate internal locations:\n\n```nginx\nlocation /_backend/github:v1.5.0 {\n internal;\n proxy_pass https://github-mcp.example.com;\n proxy_set_header X-MCP-Server-Version v1.5.0;\n}\n```\n\nThis enables scenarios where one virtual server pins to a stable version while another uses the latest.\n\n---\n\n## 7. Access Control\n\n### Scope Validation Flow\n\n```\nJWT Token --> auth_request --> Extract scopes --> Lua validation\n |\n v\n +---------------------------+\n | 1. Server-level scopes |\n | required_scopes: [A,B] |\n | User must have A AND B |\n +---------------------------+\n |\n v\n +---------------------------+\n | 2. Tool-level scopes |\n | (on tools/call only) |\n | tool.required_scopes |\n +---------------------------+\n |\n v\n +---------------------------+\n | 3. tools/list filtering |\n | Tools the user cannot |\n | access are excluded |\n +---------------------------+\n```\n\n**Server-level scopes** are checked on every request. If the user lacks any required scope, the request is rejected with HTTP 403.\n\n**Tool-level scopes** are checked on `tools/call` and used as a filter on `tools/list`. A user who has server-level access but lacks a specific tool scope will not see that tool in listings and cannot invoke it.\n\n### Example\n\n```json\n{\n \"required_scopes\": [\"mcp-access\"],\n \"tool_scope_overrides\": [\n { \"tool_alias\": \"search-repo\", \"required_scopes\": [\"github-read\"] },\n { \"tool_alias\": \"create-pr\", \"required_scopes\": [\"github-write\"] }\n ]\n}\n```\n\n| User Scopes | Visible Tools | Can Call |\n|-------------|--------------|---------|\n| `mcp-access` | (none with extra scopes, any without) | Tools without scope overrides |\n| `mcp-access`, `github-read` | `search-repo` + unscoped tools | `search-repo` |\n| `mcp-access`, `github-read`, `github-write` | All tools | All tools |\n| `github-read` (missing `mcp-access`) | HTTP 403 | Nothing |\n\n---\n\n## 8. JSON-RPC Method Routing\n\nThe Lua router (`virtual_router.lua`) implements the full MCP protocol for virtual endpoints:\n\n### Method Dispatch Table\n\n| Method | Backend Calls | Caching | Session Required | Notes |\n|--------|--------------|---------|-----------------|-------|\n| `initialize` | None | No | Creates session | Returns virtual server capabilities |\n| `ping` | None | No | No | Responds directly |\n| `notifications/initialized` | None | No | No | Returns HTTP 202 Accepted per MCP spec |\n| `notifications/cancelled` | None | No | No | Returns HTTP 202 Accepted per MCP spec |\n| `tools/list` | All distinct backends | 60s TTL | Yes | Aggregated and scope-filtered |\n| `tools/call` | Single backend | No | Yes | Alias translated, routed to owner backend |\n| `resources/list` | All distinct backends | 60s TTL | Yes | Aggregated with lookup map |\n| `resources/read` | Single backend | No | Yes | Routed via lookup map |\n| `prompts/list` | All distinct backends | 60s TTL | Yes | Aggregated with lookup map |\n| `prompts/get` | Single backend | No | Yes | Routed via lookup map |\n\n**HTTP Method Handling:**\n- `POST` - JSON-RPC requests and notifications\n- `GET` - Returns HTTP 405 (server-initiated SSE streams not supported)\n- `DELETE` - Returns HTTP 405 (client-initiated session termination not supported)\n\n### Concurrent Backend Requests\n\nFor aggregation methods (`tools/list`, `resources/list`, `prompts/list`), the Lua router issues concurrent subrequests to all distinct backend locations using `ngx.location.capture_multi()`. This parallelizes backend calls and minimizes latency.\n\n```lua\n-- Pseudocode for concurrent tool aggregation\nlocal requests = {}\nfor _, location in ipairs(distinct_backends) do\n table.insert(requests, { location, { method = ngx.HTTP_POST, body = tools_list_body } })\nend\nlocal responses = { ngx.location.capture_multi(unpack(requests)) }\n-- Merge tools from all responses, apply aliases, filter by scope\n```\n\n---\n\n## 9. API Endpoints\n\n### Management API\n\nAll management endpoints are served by FastAPI on the registry port.\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `POST` | `/api/virtual-servers` | Admin | Create a new virtual server |\n| `GET` | `/api/virtual-servers` | User | List all virtual servers |\n| `GET` | `/api/virtual-servers/{path}` | User | Get a specific virtual server |\n| `PUT` | `/api/virtual-servers/{path}` | Admin | Update a virtual server |\n| `DELETE` | `/api/virtual-servers/{path}` | Admin | Delete a virtual server |\n| `POST` | `/api/virtual-servers/{path}/toggle` | Admin | Enable or disable a virtual server |\n| `GET` | `/api/virtual-servers/{path}/tools` | User | Get resolved tools with full metadata |\n| `GET` | `/api/tool-catalog` | User | Browse all available tools across backends |\n\n### Internal API (Lua Router <-> FastAPI)\n\nThese endpoints are marked `internal` in nginx and are only accessible from Lua subrequests:\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/_internal/sessions/{client_id}/{backend}` | Get backend session ID |\n| `PUT` | `/_internal/sessions/{client_id}/{backend}` | Store backend session ID |\n| `DELETE` | `/_internal/sessions/{client_id}/{backend}` | Invalidate backend session |\n| `POST` | `/_internal/sessions` | Create client session record |\n\n### Path Validation\n\nVirtual server paths must match the pattern `/virtual/{slug}` where `slug` is lowercase alphanumeric with hyphens. Path traversal attacks are prevented by normalizing and validating paths before any database or filesystem operation.\n\n### Rating Endpoints\n\nVirtual servers support user ratings (1-5 stars):\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `POST` | `/api/virtual-servers/{path}/rate` | User | Submit or update a rating |\n| `GET` | `/api/virtual-servers/{path}/rating` | User | Get rating info for a virtual server |\n\n**Rating Request:**\n```json\n{\n \"rating\": 4\n}\n```\n\n**Rating Response:**\n```json\n{\n \"average_rating\": 4.2,\n \"message\": \"Rating submitted successfully\"\n}\n```\n\n**Get Rating Response:**\n```json\n{\n \"num_stars\": 4.2,\n \"rating_details\": [\n {\"user\": \"alice\", \"rating\": 5},\n {\"user\": \"bob\", \"rating\": 4}\n ]\n}\n```\n\n---\n\n## 10. Search and Discovery\n\nVirtual servers are indexed for semantic search alongside regular MCP servers and A2A agents.\n\n### Indexed Fields\n\nThe following fields are included in the vector embedding for semantic search:\n\n- Server name\n- Description\n- Tags (prefixed with \"Tags: \")\n- Tool names (alias or original name from each tool mapping)\n- Tool description overrides\n\n### Search Collection\n\nVirtual servers are stored in the unified `mcp_embeddings_{dimensions}` collection (e.g., `mcp_embeddings_384` for 384-dimension models) with `entity_type: \"virtual_server\"`. This enables cross-entity search queries that return servers, agents, and virtual servers in a single response. The dimension suffix matches the configured embedding model (384 for sentence-transformers, 1536 for OpenAI/Bedrock Titan).\n\n### Search Document Structure\n\n```json\n{\n \"_id\": \"/virtual/dev-tools\",\n \"entity_type\": \"virtual_server\",\n \"path\": \"/virtual/dev-tools\",\n \"name\": \"Dev Tools\",\n \"description\": \"Aggregated development tools\",\n \"tags\": [\"development\", \"tools\"],\n \"is_enabled\": true,\n \"tools\": [\n {\"name\": \"github_search\"},\n {\"name\": \"jira_search\"}\n ],\n \"embedding\": [0.12, -0.34, ...],\n \"metadata\": {\n \"server_name\": \"Dev Tools\",\n \"num_tools\": 5,\n \"backend_count\": 2,\n \"backend_paths\": [\"/github\", \"/jira\"],\n \"required_scopes\": [\"mcp-access\"],\n \"supported_transports\": [\"streamable-http\"],\n \"created_by\": \"admin\"\n }\n}\n```\n\n### Search Result Format\n\nWhen virtual servers match a search query, they appear in the `virtual_servers` array:\n\n```json\n{\n \"servers\": [...],\n \"agents\": [...],\n \"virtual_servers\": [\n {\n \"entity_type\": \"virtual_server\",\n \"path\": \"/virtual/dev-tools\",\n \"server_name\": \"Dev Tools\",\n \"description\": \"Aggregated development tools\",\n \"relevance_score\": 0.85,\n \"tags\": [\"development\", \"tools\"],\n \"backend_paths\": [\"/github\", \"/jira\"],\n \"tool_count\": 5,\n \"matching_tools\": [\n {\"tool_name\": \"github_search\"}\n ]\n }\n ],\n \"tools\": [...],\n \"skills\": [...]\n}\n```\n\n### Indexing Lifecycle\n\nVirtual servers are indexed/re-indexed when:\n- Created via `POST /api/virtual-servers`\n- Updated via `PUT /api/virtual-servers/{path}`\n- Toggled via `POST /api/virtual-servers/{path}/toggle`\n- Deleted (removed from search index)\n\n---\n\n## 11. Frontend Management UI\n\nThe management UI provides a multi-step wizard for creating and editing virtual servers:\n\n### Wizard Steps\n\n1. **Basics**: Server name (auto-generates path slug), description, tags, transport selection\n2. **Tool Selection**: Interactive picker showing all available tools grouped by backend server, with search filtering\n3. **Configuration**: Per-tool alias assignment, version pinning, scope overrides, description overrides\n4. **Review**: Summary of the complete configuration before submission\n\n### Dashboard Integration\n\nVirtual servers appear on the main dashboard alongside regular MCP servers. They are visually distinguished with a different color scheme and a \"Virtual\" badge. A dedicated \"Virtual MCP\" filter tab in the dashboard allows viewing only virtual servers.\n\n### Key Components\n\n| Component | Purpose |\n|-----------|---------|\n| `VirtualServerList` | Table view with search, toggle, edit, delete |\n| `VirtualServerCard` | Dashboard card with status, tool count, backend count |\n| `VirtualServerForm` | 4-step creation/edit wizard |\n| `ToolSelector` | Searchable tool picker grouped by backend |\n| `useVirtualServers` | React hook for CRUD with optimistic updates |\n\n---\n\n## 12. Validation and Error Handling\n\n### Creation-Time Validation\n\nWhen a virtual server is created or updated, the service layer performs the following validations:\n\n1. **Path format**: Must match `/virtual/[a-z0-9-]+`\n2. **Path uniqueness**: No existing virtual server with the same path\n3. **Backend existence**: Each `backend_server_path` must reference a registered, enabled server\n4. **Tool existence**: Each `tool_name` must exist in the referenced backend's tool list\n5. **Alias uniqueness**: No two tool mappings may produce the same effective name\n6. **Scope override validity**: Each `tool_alias` in scope overrides must match an existing tool mapping\n\n### Runtime Error Handling\n\n| Error Condition | Lua Router Behavior |\n|----------------|---------------------|\n| Missing `Mcp-Session-Id` header | Returns JSON-RPC error: \"Missing session\" |\n| Invalid/expired client session | Returns JSON-RPC error: \"Invalid session\" |\n| Backend returns HTTP 400+ | Invalidates cached session, retries with fresh `initialize` |\n| Backend unreachable | Returns JSON-RPC error with backend details |\n| User lacks required scope | Returns HTTP 403 with scope details |\n| Unknown tool name in `tools/call` | Returns JSON-RPC error: \"Tool not found\" |\n| Unknown JSON-RPC method | Returns JSON-RPC error: \"Method not found\" |\n\n---\n\n## 13. Performance Characteristics\n\n### Caching Strategy\n\n| Data | Cache Location | TTL | Invalidation |\n|------|---------------|-----|--------------|\n| Backend sessions | L1 (shared dict) | 30s | On 400+ response |\n| Backend sessions | L2 (MongoDB) | 1 hour | On 400+ response |\n| Enriched tool list | L1 (shared dict) | 60s | On nginx reload |\n| Resource/prompt lookup maps | L1 (shared dict) | 60s | On nginx reload |\n| Mapping files | Disk | Until regenerated | On CRUD mutation |\n\n### Stress Test Results\n\nTesting with a production-representative configuration:\n\n| Scenario | Requests | Throughput | Error Rate |\n|----------|----------|------------|------------|\n| Concurrent `tools/list` | 1,000 | 68.9 req/s | 0% |\n| Concurrent `tools/call` | 1,000 | 57.9 req/s | 0% |\n| Mixed workload | 1,000 | 5.2 req/s | 0% |\n| Session storm (100 concurrent inits) | 100 | 43.7 req/s | 0% |\n\n### Latency Overhead\n\nVirtual server routing adds overhead compared to direct backend access due to session lookup, tool mapping resolution, and (for aggregation methods) concurrent subrequests. The latency benchmarks measure 20 iterations per method to characterize this overhead under realistic conditions.\n\n---\n\n## 14. Deployment Considerations\n\n### Multi-Instance Behavior\n\n- Each nginx worker maintains its own L1 shared dict cache\n- L2 (MongoDB) provides cross-instance session consistency\n- Nginx config regeneration is triggered by the registry instance that receives the mutation\n- In multi-registry deployments, a mechanism for cross-instance nginx reload propagation would be needed (not currently implemented)\n\n### Configuration Reload\n\nWhen a virtual server is mutated:\n\n1. The service acquires a global `asyncio.Lock` to serialize reload operations\n2. Full nginx configuration is regenerated (including all virtual and non-virtual servers)\n3. Mapping JSON files are written to disk\n4. `nginx -s reload` is issued\n5. The lock is released\n\nThis approach is simple and correct but means all virtual server mutations are serialized. For typical management workloads (infrequent CRUD), this is not a bottleneck.\n\n### Resource Sizing\n\n| Resource | Sizing Guidance |\n|----------|----------------|\n| Shared dict memory | 2 MB covers ~10K cached entries |\n| MongoDB `backend_sessions` | TTL-indexed, self-cleaning |\n| Mapping files on disk | ~1-10 KB per virtual server |\n| Nginx location blocks | One per virtual server + one per unique backend |\n\n---\n\n## 15. Limitations and Future Work\n\n### Current Limitations\n\n- **No resource subscriptions**: `listChanged` notifications from backends are not propagated through virtual servers\n- **No per-backend load balancing**: Each backend location maps to a single upstream; horizontal scaling of a backend requires external load balancing\n- **No streaming support**: The current Lua router buffers full request/response bodies; SSE streaming through virtual servers is not implemented\n- **Single-instance nginx reload**: Config regeneration assumes a single nginx instance; multi-instance coordination is not built in\n\n### Future Enhancements\n\n- **Dynamic tool routing**: Route a single tool to different backends based on request parameters or user attributes\n- **Weighted backend selection**: Load balance across multiple instances of the same backend\n- **SSE pass-through**: Support streaming transports for long-running tool calls\n- **Cross-instance reload coordination**: Notify peer registry instances when nginx config changes\n- **Tool usage analytics**: Track per-tool invocation counts, latency, and error rates at the virtual server level\n- **Template virtual servers**: Pre-defined virtual server templates for common tool bundles\n\n---\n\n## 16. File Reference\n\n```\nregistry/\n schemas/\n virtual_server_models.py # Pydantic data models\n backend_session_models.py # Session tracking models\n services/\n virtual_server_service.py # Business logic and validation\n tool_catalog_service.py # Cross-backend tool aggregation\n repositories/\n interfaces.py # Repository interfaces\n documentdb/\n virtual_server_repository.py # MongoDB persistence\n backend_session_repository.py # Session persistence with TTL\n api/\n virtual_server_routes.py # REST API endpoints\n core/\n nginx_service.py # Nginx config + mapping generation\n\ndocker/\n lua/\n virtual_router.lua # Lua JSON-RPC router\n\nfrontend/\n src/\n types/virtualServer.ts # TypeScript type definitions\n hooks/useVirtualServers.ts # React data hooks\n components/\n VirtualServerList.tsx # List/table view\n VirtualServerCard.tsx # Dashboard card\n VirtualServerForm.tsx # Multi-step wizard\n ToolSelector.tsx # Interactive tool picker\n\ntests/\n unit/\n test_virtual_server_models.py # Model validation tests\n test_virtual_server_service.py # Service layer tests\n test_virtual_server_nginx.py # Nginx generation tests\n test_backend_session_repository.py # Session repository tests\n integration/\n test_virtual_server_api.py # API endpoint tests\n e2e/\n test_virtual_mcp_protocol.py # MCP protocol E2E tests\n test_virtual_mcp_latency.py # Latency benchmarks\n test_virtual_mcp_stress.py # Stress tests\n```\n" }, { "path": "docs/dynamic-tool-discovery.md", "content": "# Dynamic Tool Discovery and Invocation\n\nThe MCP Gateway & Registry provides a powerful **Dynamic Tool Discovery and Invocation** feature that enables AI agents to autonomously discover and execute tools beyond their initial capabilities. This feature uses advanced semantic search with FAISS indexing and sentence transformers to intelligently match natural language queries to the most relevant MCP tools across all registered servers.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [How It Works](#how-it-works)\n- [Architecture](#architecture)\n- [Usage Examples](#usage-examples)\n- [Agent Integration](#agent-integration)\n- [API Reference](#api-reference)\n- [Technical Implementation](#technical-implementation)\n- [Demo](#demo)\n\n## Overview\n\nTraditional AI agents are limited to the tools they were initially configured with. The Dynamic Tool Discovery feature breaks this limitation by allowing agents to:\n\n1. **Discover new tools** through natural language queries\n2. **Automatically find** the most relevant tools from hundreds of available MCP servers\n3. **Dynamically invoke** discovered tools without prior configuration\n4. **Expand capabilities** on-demand based on user requests\n\nThis enables agents to handle tasks they weren't originally designed for, making them truly adaptive and extensible.\n\n## How It Works\n\nThe dynamic tool discovery process follows these steps:\n\n1. **Natural Language Query**: Agent receives a user request requiring specialized capabilities\n2. **Semantic Search**: The `intelligent_tool_finder` tool processes the query using sentence transformers\n3. **FAISS Index Search**: Searches through embeddings of all registered MCP tools\n4. **Relevance Ranking**: Returns tools ranked by semantic similarity to the query\n5. **Tool Invocation**: Agent uses the discovered tool information to invoke the appropriate MCP tool\n\n![Dynamic Tool Discovery Flow](img/dynamic-tool-discovery-demo.gif)\n\n## Architecture\n\n### Components\n\n```mermaid\ngraph TB\n subgraph \"Agent Layer\"\n A[AI Agent] --> B[Natural Language Query]\n A --> H[invoke_mcp_tool]\n end\n \n subgraph \"Discovery Layer\"\n B --> C[intelligent_tool_finder]\n C --> D[Sentence Transformer]\n C --> E[FAISS Index]\n E --> F[Tool Metadata]\n F --> G[Server Information]\n G --> K[Tool Discovery Results]\n K --> A\n end\n \n subgraph \"Execution Layer\"\n H --> I[Target MCP Server]\n I --> J[Tool Result]\n J --> A\n end\n```\n\n### Key Technologies\n\n- **FAISS (Facebook AI Similarity Search)**: High-performance vector similarity search\n- **Sentence Transformers**: Neural network models for semantic text understanding\n- **Cosine Similarity**: Mathematical measure of semantic similarity between queries and tools\n- **MCP Protocol**: Standardized communication with tool servers\n\n## Usage Examples\n\nDynamic tool discovery can be used in two primary ways:\n\n### 1. Direct Developer Usage\n\nAgent developers can directly call the `intelligent_tool_finder` in their code to discover tools, then use the results with the `invoke_mcp_tool` function to call the discovered tool.\n\n#### Basic Discovery\n\n```python\n# Basic usage with session cookie\ntools = await intelligent_tool_finder(\n natural_language_query=\"what time is it in Tokyo\",\n session_cookie=\"your_session_cookie_here\"\n)\n\n# Returns information about relevant tools:\n# [\n# {\n# \"tool_name\": \"current_time_by_timezone\",\n# \"service_path\": \"/currenttime\",\n# \"service_name\": \"Current Time Server\",\n# \"tool_schema\": {...},\n# \"overall_similarity_score\": 0.89\n# }\n# ]\n```\n\n#### Advanced Discovery\n\n```python\n# Advanced usage with multiple results\ntools = await intelligent_tool_finder(\n natural_language_query=\"stock market information and financial data\",\n session_cookie=\"your_session_cookie\",\n top_k_services=5,\n top_n_tools=3\n)\n```\n\n#### Complete Workflow\n\n```python\n# 1. Discover tools for weather information\nweather_tools = await intelligent_tool_finder(\n natural_language_query=\"weather forecast for tomorrow\",\n session_cookie=\"your_session_cookie\"\n)\n\n# 2. Use the discovered tool\nif weather_tools:\n tool_info = weather_tools[0] # Get the best match\n \n result = await invoke_mcp_tool(\n mcp_registry_url=\"https://your-registry.com/mcpgw/sse\",\n server_name=tool_info[\"service_path\"], # e.g., \"/weather\"\n tool_name=tool_info[\"tool_name\"], # e.g., \"get_forecast\"\n arguments={\"location\": \"New York\", \"days\": 1},\n auth_token=auth_token,\n user_pool_id=user_pool_id,\n client_id=client_id,\n region=region,\n auth_method=\"m2m\"\n )\n```\n\n### 2. Agent Integration\n\nThe more powerful approach is when AI agents themselves use dynamic tool discovery autonomously. The agent has access to both `intelligent_tool_finder` and `invoke_mcp_tool` as available tools, allowing it to discover and execute new capabilities on-demand.\n\n**Demo Video**: [Watch the agent integration in action](https://github.com/user-attachments/assets/cee1847d-ecc1-406b-a83e-ebc80768430d)\n\n#### System Prompt Configuration\n\nAgents are configured with instructions on how to use dynamic tool discovery:\n\n```text\n\nWhen a user requests something that requires a specialized tool you don't have direct access to, use the intelligent_tool_finder tool.\n\nHow to use intelligent_tool_finder:\n1. When you identify that a task requires a specialized tool (e.g., weather forecast, time information, etc.)\n2. Call the tool with a description of what you need: `intelligent_tool_finder(\"description of needed capability\")`.\n3. The tool will return the most appropriate specialized tool along with usage instructions\n4. You can then use the invoke_mcp_tool to invoke this discovered tool by providing the MCP Registry URL, server name, tool name, and required arguments\n\nExample workflow:\n1. Discover a tool: result = intelligent_tool_finder(\"current time timezone\")\n2. The result provides details about a time tool on the \"currenttime\" MCP server.\n3. Always use the \"service_path\" path field for the server name while creating the arguments for the invoke_mcp_tool in the next step.\n4. Use invoke_mcp_tool to call it with ALL required auth parameters\n\n```\n\n#### Agent Implementation\n\nThe agent implementation in [`agents/agent.py`](../agents/agent.py) shows how to:\n\n1. **Load MCP tools** from the registry\n2. **Combine built-in and discovered tools**\n3. **Handle authentication** for both session cookie and M2M methods\n4. **Process tool discovery results**\n\nKey code snippet:\n\n```python\n# Get available tools from MCP and display them\nmcp_tools = await client.get_tools()\nlogger.info(f\"Available MCP tools: {[tool.name for tool in mcp_tools]}\")\n\n# Add the calculator and invoke_mcp_tool to the tools array\n# The invoke_mcp_tool function already supports authentication parameters\nall_tools = [calculator, invoke_mcp_tool] + mcp_tools\nlogger.info(f\"All available tools: {[tool.name if hasattr(tool, 'name') else tool.__name__ for tool in all_tools]}\")\n\n# Create the agent with the model and all tools\nagent = create_react_agent(model, all_tools)\n```\n\nThis integration enables agents to have **limitless capabilities** - they can handle any task for which there's an appropriate MCP tool registered in the system, even if they weren't originally programmed with knowledge of that tool.\n\n## API Reference\n\n### intelligent_tool_finder\n\nFinds the most relevant MCP tool(s) across all registered and enabled services based on a natural language query.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `natural_language_query` | `str` | Yes | Your query in natural language describing the task you want to perform |\n| `username` | `str` | No* | Username for mcpgw server authentication |\n| `password` | `str` | No* | Password for mcpgw server authentication |\n| `session_cookie` | `str` | No* | Session cookie for registry authentication |\n| `top_k_services` | `int` | No | Number of top services to consider from initial FAISS search (default: 3) |\n| `top_n_tools` | `int` | No | Number of best matching tools to return (default: 1) |\n\n*Either `session_cookie` OR (`username` AND `password`) must be provided for authentication.\n\n#### Returns\n\n```python\nList[Dict[str, Any]]\n```\n\nA list of dictionaries, each describing a recommended tool:\n\n```python\n[\n {\n \"tool_name\": \"current_time_by_timezone\",\n \"tool_parsed_description\": {\n \"main\": \"Get current time for a specific timezone\",\n \"parameters\": {...}\n },\n \"tool_schema\": {\n \"type\": \"object\",\n \"properties\": {...}\n },\n \"service_path\": \"/currenttime\",\n \"service_name\": \"Current Time Server\",\n \"overall_similarity_score\": 0.89\n }\n]\n```\n\n#### Example Usage\n\n```python\n# Basic usage with session cookie\ntools = await intelligent_tool_finder(\n natural_language_query=\"what time is it in Tokyo\",\n session_cookie=\"your_session_cookie_here\"\n)\n\n# Advanced usage with multiple results\ntools = await intelligent_tool_finder(\n natural_language_query=\"stock market information and financial data\",\n session_cookie=\"your_session_cookie\",\n top_k_services=5,\n top_n_tools=3\n)\n```\n\n## Technical Implementation\n\n### FAISS Index Creation\n\nThe registry automatically creates and maintains a FAISS index of all registered MCP tools:\n\n1. **Tool Metadata Collection**: Gathers tool descriptions, schemas, and server information\n2. **Text Embedding**: Uses sentence transformers to create vector embeddings\n3. **Index Building**: Constructs FAISS index for fast similarity search\n4. **Automatic Updates**: Refreshes index when servers are added/modified\n\n### Semantic Search Process\n\n```python\n# 1. Embed the natural language query\nquery_embedding = await asyncio.to_thread(_embedding_model_mcpgw.encode, [natural_language_query])\nquery_embedding_np = np.array(query_embedding, dtype=np.float32)\n\n# 2. Search FAISS for top_k_services\ndistances, faiss_ids = await asyncio.to_thread(_faiss_index_mcpgw.search, query_embedding_np, top_k_services)\n\n# 3. Collect tools from top services\ncandidate_tools = []\nfor service in top_services:\n for tool in service.tools:\n tool_text = f\"Service: {service.name}. Tool: {tool.name}. Description: {tool.description}\"\n candidate_tools.append({\n \"text_for_embedding\": tool_text,\n \"tool_name\": tool.name,\n \"service_path\": service.path,\n # ... other metadata\n })\n\n# 4. Embed all candidate tool descriptions\ntool_embeddings = await asyncio.to_thread(_embedding_model_mcpgw.encode, tool_texts)\n\n# 5. Calculate cosine similarity and rank\nsimilarities = cosine_similarity(query_embedding_np, tool_embeddings_np)[0]\nranked_tools = sorted(tools_with_scores, key=lambda x: x[\"similarity_score\"], reverse=True)\n```\n\n### Performance Optimizations\n\n- **Lazy Loading**: FAISS index and models are loaded on-demand\n- **Caching**: Embeddings and metadata are cached and reloaded only when files change\n- **Async Processing**: All embedding operations run in separate threads\n- **Memory Efficiency**: Uses float32 precision for embeddings to reduce memory usage\n\n### Model Configuration\n\nThe system uses configurable sentence transformer models:\n\n```python\n# Default model (lightweight, fast)\nEMBEDDINGS_MODEL_NAME = 'all-MiniLM-L6-v2' # 384 dimensions\n\n# Model loading with caching\nmodel_cache_path = _registry_server_data_path.parent / \".cache\"\n_embedding_model_mcpgw = SentenceTransformer(EMBEDDINGS_MODEL_NAME, cache_folder=model_cache_path)\n```\n\n## Demo\n\n**Demo Video**: [Dynamic Tool Discovery and Invocation](https://github.com/user-attachments/assets/cee1847d-ecc1-406b-a83e-ebc80768430d)\n\n### Example Interaction\n\n**User Query**: \"What's the current time in Tokyo?\"\n\n**Agent Process**:\n1. Agent recognizes need for time information\n2. Calls `intelligent_tool_finder(\"current time in Tokyo\")`\n3. Discovers `current_time_by_timezone` tool from `/currenttime` server\n4. Invokes tool with `{\"tz_name\": \"Asia/Tokyo\"}`\n5. Returns formatted time result\n\n**Result**: \"The current time in Tokyo is 2024-01-15 14:30:45 JST\"\n\n### Performance Metrics\n\n_Coming soon._\n\n## Best Practices\n\n### For Tool Developers\n\n1. **Descriptive Names**: Use clear, descriptive tool names\n2. **Rich Descriptions**: Provide detailed tool descriptions with use cases\n3. **Proper Schemas**: Include comprehensive parameter schemas\n4. **Consistent Naming**: Follow naming conventions for better discoverability\n\n### For Agent Developers\n\n1. **Specific Queries**: Use specific, descriptive queries for better matches\n2. **Fallback Handling**: Implement fallbacks when no suitable tools are found\n3. **Authentication**: Always include proper authentication parameters\n4. **Error Handling**: Handle tool discovery and invocation errors gracefully\n\n### For System Administrators\n\n1. **Index Maintenance**: Monitor FAISS index updates and performance\n2. **Model Updates**: Consider updating sentence transformer models periodically\n3. **Server Health**: Ensure registered servers are healthy and responsive\n4. **Access Control**: Configure proper authentication and authorization" }, { "path": "docs/embeddings.md", "content": "# Embeddings Configuration\n\nFlexible, vendor-agnostic embeddings generation for MCP Gateway Registry's semantic search functionality.\n\n## Overview\n\nThe MCP Gateway Registry provides semantic search capabilities across MCP servers, tools, and AI agents. You can choose from three embedding provider options to power this search:\n\n1. **Sentence Transformers** (Default) - Local models\n2. **OpenAI** - Cloud embeddings via API\n3. **Any LiteLLM-supported provider** - Amazon Bedrock Titan, Cohere, and 100+ other models\n\nSwitch between providers with simple configuration changes - no code modifications required.\n\n## Features\n\n- **Vendor-agnostic**: Switch between embeddings providers with configuration changes\n- **Local & Cloud Support**: Use local models or cloud APIs (OpenAI, Cohere, Amazon Bedrock, etc.)\n- **Backward Compatible**: Works seamlessly with existing FAISS indices\n- **Easy Configuration**: Simple environment variable setup\n- **Extensible**: Easy to add new providers\n- **AWS Deployable**: Terraform support for AWS deployments\n\n## Quick Start\n\n### Option 1: Sentence Transformers (Default)\n\nLocal embedding models that run on your infrastructure.\n\n```bash\n# In .env\nEMBEDDINGS_PROVIDER=sentence-transformers\nEMBEDDINGS_MODEL_NAME=all-MiniLM-L6-v2\nEMBEDDINGS_MODEL_DIMENSIONS=384\n```\n\n**Characteristics:**\n- Runs locally on your infrastructure\n- No API costs\n- No external network calls required\n- Requires CPU/GPU resources\n- Model files stored locally\n- Data stays within your infrastructure\n\n### Option 2: OpenAI\n\nCloud-based embedding service via OpenAI API.\n\n```bash\n# In .env\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=openai/text-embedding-ada-002\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_API_KEY=sk-your-openai-api-key\n```\n\n**Characteristics:**\n- Cloud-based service\n- Requires API key\n- API costs per 1K tokens\n- No local compute resources needed\n- Network dependency\n- Data sent to OpenAI\n\n### Option 3: Amazon Bedrock Titan\n\nCloud-based embedding service via AWS Bedrock.\n\n```bash\n# In .env\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=bedrock/amazon.titan-embed-text-v1\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_AWS_REGION=us-east-1\n# No API key needed - uses IAM\n```\n\n**Characteristics:**\n- Cloud-based service\n- Uses IAM authentication (no API key required)\n- Integrates with AWS security model\n- API costs apply\n- Requires AWS credentials\n- Available in select AWS regions\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `EMBEDDINGS_PROVIDER` | Provider type: `sentence-transformers` or `litellm` | `sentence-transformers` | No |\n| `EMBEDDINGS_MODEL_NAME` | Model identifier | `all-MiniLM-L6-v2` | Yes |\n| `EMBEDDINGS_MODEL_DIMENSIONS` | Embedding dimension | `384` | Yes |\n| `EMBEDDINGS_API_KEY` | API key for cloud provider (OpenAI, Cohere, etc.) | - | For cloud* |\n| `EMBEDDINGS_API_BASE` | Custom API endpoint (LiteLLM only) | - | No |\n| `EMBEDDINGS_AWS_REGION` | AWS region for Bedrock (LiteLLM only) | - | For Bedrock |\n\n*Not required for AWS Bedrock - use standard AWS credential chain (IAM roles, environment variables, ~/.aws/credentials)\n\n### Terraform Configuration\n\nFor AWS ECS deployments, configure embeddings in your `terraform.tfvars`:\n\n#### Using Sentence Transformers (Default)\n\n```hcl\n# Local embeddings - no additional configuration needed\n# Uses defaults: sentence-transformers with all-MiniLM-L6-v2\n```\n\n#### Using OpenAI\n\n```hcl\nembeddings_provider = \"litellm\"\nembeddings_model_name = \"openai/text-embedding-ada-002\"\nembeddings_model_dimensions = 1536\nembeddings_api_key = \"sk-proj-YOUR-OPENAI-API-KEY\"\n```\n\n#### Using Amazon Bedrock\n\n```hcl\nembeddings_provider = \"litellm\"\nembeddings_model_name = \"bedrock/amazon.titan-embed-text-v1\"\nembeddings_model_dimensions = 1536\nembeddings_aws_region = \"us-east-1\"\nembeddings_api_key = \"\" # Empty for Bedrock (uses IAM)\n```\n\nSee [terraform/aws-ecs/terraform.tfvars.example](../terraform/aws-ecs/terraform.tfvars.example) for complete examples.\n\n## Supported Models\n\n### Sentence Transformers (Local)\n\n| Model | Dimensions | Description |\n|-------|------------|-------------|\n| `all-MiniLM-L6-v2` | 384 | Fast, lightweight (default) |\n| `all-mpnet-base-v2` | 768 | High quality |\n| `paraphrase-multilingual-MiniLM-L12-v2` | 384 | Multilingual |\n\nAny model from [Hugging Face sentence-transformers](https://huggingface.co/models?library=sentence-transformers) is supported.\n\n### LiteLLM (Cloud-based)\n\nLiteLLM supports 100+ embedding models from various providers:\n\n#### OpenAI\n- `openai/text-embedding-3-small` (1536 dimensions)\n- `openai/text-embedding-3-large` (3072 dimensions)\n- `openai/text-embedding-ada-002` (1536 dimensions)\n\n#### Cohere\n- `cohere/embed-english-v3.0` (1024 dimensions)\n- `cohere/embed-multilingual-v3.0` (1024 dimensions)\n\n#### Amazon Bedrock\n- `bedrock/amazon.titan-embed-text-v1` (1536 dimensions)\n- `bedrock/cohere.embed-english-v3` (1024 dimensions)\n- `bedrock/cohere.embed-multilingual-v3` (1024 dimensions)\n\n#### Other Providers\n- Azure OpenAI\n- Anthropic (Claude)\n- Google Vertex AI\n- Hugging Face Inference API\n- And 100+ more via [LiteLLM](https://docs.litellm.ai/docs/embedding/supported_embedding)\n\n## Migration Between Providers\n\n### Switching Providers\n\nWhen you switch embedding providers or models with different dimensions, the registry automatically:\n\n1. Detects dimension mismatch\n2. Rebuilds the FAISS index\n3. Regenerates embeddings for all registered items\n\nExample logs when switching from sentence-transformers (384) to OpenAI (1536):\n\n```\nWARNING: Embedding dimension mismatch detected\n Expected: 384 (from existing index)\n Got: 1536 (from current model)\nRebuilding FAISS index with new dimensions...\nRegenerating embeddings for all items...\nIndex rebuild complete\n```\n\n### No Code Changes Required\n\nJust update your environment variables or Terraform configuration:\n\n```bash\n# From\nEMBEDDINGS_PROVIDER=sentence-transformers\nEMBEDDINGS_MODEL_NAME=all-MiniLM-L6-v2\nEMBEDDINGS_MODEL_DIMENSIONS=384\n\n# To\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=openai/text-embedding-ada-002\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_API_KEY=sk-your-key\n```\n\nRestart the service and the index will be automatically rebuilt.\n\n## AWS Bedrock Setup\n\n### IAM Permissions\n\nFor Amazon Bedrock embeddings, ensure your ECS task role has the following permissions:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"bedrock:InvokeModel\"\n ],\n \"Resource\": [\n \"arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v1\"\n ]\n }\n ]\n}\n```\n\n### Authentication Methods\n\n**IAM Roles (Recommended for ECS/EC2/EKS)**\n```bash\n# No additional configuration needed\n# ECS task, EC2 instance, or EKS pod automatically uses attached IAM role\n```\n\n## Architecture\n\n### Embeddings Module Design\n\n```\nEmbeddingsClient (Abstract Base Class)\n├── SentenceTransformersClient (Local models)\n└── LiteLLMClient (Cloud APIs via LiteLLM)\n```\n\n### Integration with FAISS Search\n\nThe embeddings module integrates seamlessly with the FAISS search service:\n\n```python\n# In registry/search/service.py\nfrom registry.embeddings import create_embeddings_client\n\nclass FaissService:\n async def _load_embedding_model(self):\n self.embedding_model = create_embeddings_client(\n provider=settings.embeddings_provider,\n model_name=settings.embeddings_model_name,\n api_key=settings.embeddings_api_key,\n aws_region=settings.embeddings_aws_region,\n embedding_dimension=settings.embeddings_model_dimensions,\n )\n```\n\n## Performance Considerations\n\n### Local Models (Sentence Transformers)\n- Runs on your infrastructure (CPU/GPU)\n- No external API calls\n- No per-request costs\n- Model files stored locally\n- Network-independent operation\n\n### Cloud APIs (LiteLLM)\n- Runs on provider infrastructure\n- Requires network connectivity\n- API costs apply (varies by provider)\n- No local compute requirements\n- Data transmitted to provider\n\n## Graceful Degradation\n\n### Lexical Fallback When Model Unavailable\n\nIf the embedding model fails to load or is unreachable (e.g., invalid model name, expired API key, network failure), the search system automatically falls back to **lexical-only search** instead of returning errors.\n\n**What happens:**\n\n1. The embeddings client caches the load error (`_load_error`) to avoid repeated download/API attempts\n2. The search repository detects the failure and sets `_embedding_unavailable = True`\n3. All subsequent searches use keyword matching (regex on path, name, description, tags, tools) instead of vector similarity\n4. Servers and agents are still indexed, but without embeddings (stored with empty vectors)\n5. The API response includes `\"search_mode\": \"lexical-only\"` to indicate reduced search quality\n\n**How to detect:**\n\n- Check the API response `search_mode` field: `\"hybrid\"` (normal) vs. `\"lexical-only\"` (fallback)\n- Look for log warnings: `\"Embedding model unavailable, falling back to lexical-only search\"`\n- During indexing: `\"Embedding model unavailable, indexing '' without embeddings\"`\n\n**How to recover:**\n\nFix the embedding configuration and restart the service. On restart, the error cache is cleared and the system will attempt to load the model again. If successful, search returns to full hybrid mode automatically.\n\nSee [Hybrid Search Architecture](design/hybrid-search-architecture.md) for details on lexical-only scoring.\n\n## Troubleshooting\n\n### Embedding Model Not Found\n\n```\nFailed to load SentenceTransformer model: sentence-transformers/my-model is not a local folder\nand is not a valid model identifier listed on 'https://huggingface.co/models'\n```\n\n**Solution:** Verify the model name in `EMBEDDINGS_MODEL_NAME` is correct. Check the [Hugging Face model hub](https://huggingface.co/models?library=sentence-transformers) for valid names. The system will continue operating with lexical-only search until the model is fixed.\n\n### LiteLLM Not Installed\n\n```\nRuntimeError: LiteLLM is not installed. Install it with: uv add litellm\n```\n\n**Solution:**\n```bash\nuv add litellm\n```\n\n### Dimension Mismatch\n\n```\nWARNING: Embedding dimension mismatch: expected 384, got 1536\n```\n\n**Solution:** Update `EMBEDDINGS_MODEL_DIMENSIONS` to match your model's actual output dimension. The system will automatically rebuild the index.\n\n### API Authentication Errors\n\n**OpenAI:**\n```bash\n# Verify API key is set correctly\necho $EMBEDDINGS_API_KEY\n# Should start with sk-\n```\n\n**Bedrock:**\n```bash\n# Verify AWS credentials\naws sts get-caller-identity\n\n# Check Bedrock access\naws bedrock list-foundation-models --region us-east-1\n```\n\n### Missing IAM Permissions\n\nIf using AWS ECS and Bedrock, ensure the task execution role has access to the embeddings API key secret:\n\n```bash\n# Check IAM policy in terraform/aws-ecs/modules/mcp-gateway/iam.tf\n# Should include: aws_secretsmanager_secret.embeddings_api_key.arn\n```\n\n## API Reference\n\n### Factory Function\n\n```python\nfrom registry.embeddings import create_embeddings_client\n\nclient = create_embeddings_client(\n provider: str, # \"sentence-transformers\" or \"litellm\"\n model_name: str, # Model identifier\n api_key: Optional[str] = None, # API key (litellm only)\n aws_region: Optional[str] = None, # AWS region (Bedrock only)\n embedding_dimension: Optional[int] = None,\n)\n```\n\n### Client Methods\n\n**Generate Embeddings:**\n```python\nembeddings = client.encode([\"text1\", \"text2\"])\n# Returns: numpy array of shape (n_texts, embedding_dim)\n```\n\n**Get Dimension:**\n```python\ndim = client.get_embedding_dimension()\n# Returns: int (e.g., 384, 1536)\n```\n\n## Best Practices\n\n1. Choose the provider that matches your deployment requirements\n2. Consider IAM authentication if deploying on AWS\n3. Monitor costs when using cloud APIs - implement caching if needed\n4. Keep dimension consistent - changing models requires index rebuild\n5. Test search results after switching providers to ensure they meet your requirements\n\n## Further Reading\n\n- [LiteLLM Documentation](https://docs.litellm.ai/docs/)\n- [OpenAI Embeddings Guide](https://platform.openai.com/docs/guides/embeddings)\n- [Amazon Bedrock Embeddings](https://docs.aws.amazon.com/bedrock/latest/userguide/embeddings.html)\n- [Sentence Transformers Models](https://www.sbert.net/docs/pretrained_models.html)\n- [FAISS Search Implementation](../registry/search/service.py)\n\n## Contributing\n\nTo add a new embeddings provider:\n\n1. Create a new client class inheriting from `EmbeddingsClient`\n2. Implement `encode()` and `get_embedding_dimension()` methods\n3. Update `create_embeddings_client()` factory function\n4. Add configuration options to `registry/core/config.py`\n5. Update this documentation\n\n## License\n\nApache 2.0 - See [LICENSE](../LICENSE) file for details\n" }, { "path": "docs/entra-id-setup.md", "content": "# Microsoft Entra ID Setup Guide\n\nThis guide provides step-by-step instructions for setting up Microsoft Entra ID (formerly Azure Active Directory) authentication for the MCP Gateway Registry.\n\n## Table of Contents\n\n1. [Prerequisites](#prerequisites)\n2. [Azure Portal Configuration](#azure-portal-configuration)\n3. [Environment Configuration](#environment-configuration)\n4. [Group Configuration](#group-configuration)\n5. [Testing the Setup](#testing-the-setup)\n6. [Troubleshooting](#troubleshooting)\n7. [Using the IAM API to Manage Groups, Users, and M2M Accounts](#using-the-iam-api-to-manage-groups-users-and-m2m-accounts)\n8. [Generating JWT Tokens for M2M Accounts](#generating-jwt-tokens-for-m2m-accounts)\n\n---\n\n## Prerequisites\n\nBefore you begin, ensure you have:\n\n- Access to an Azure account with permissions to create App Registrations\n- Azure Active Directory (Entra ID) tenant\n- Admin rights to configure App Registrations and assign users to groups\n- The MCP Gateway Registry codebase\n\n---\n\n## Azure Portal Configuration\n\n### Step 1: Create an App Registration\n\n1. Navigate to the [Azure Portal](https://portal.azure.com)\n2. Go to **Azure Active Directory** → **App registrations**\n3. Click **New registration**\n4. Configure the app registration:\n - **Name**: `mcp-gateway-web` (or your preferred name)\n - **Supported account types**: Select the appropriate option:\n - **Single tenant** (recommended): Only users in your organization\n - **Multi-tenant**: Users from any Azure AD tenant\n - **Redirect URI**:\n - Platform: **Web**\n - URI: `http://localhost/auth/callback` (for local development)\n - For production, use: `https://your-domain.com/auth/callback`\n5. Click **Register**\n\n### Step 2: Note Your Application IDs\n\nAfter creating the app registration, note the following values (you'll need them later):\n\n1. From the app registration **Overview** page:\n - **Application (client) ID**: This is your `ENTRA_CLIENT_ID`\n - **Directory (tenant) ID**: This is your `ENTRA_TENANT_ID`\n\n### Step 3: Create a Client Secret\n\n1. In your app registration, click **Certificates & secrets** in the left menu\n2. Click **New client secret**\n3. Configure the secret:\n - **Description**: `mcp-gateway-auth` (or your preferred description)\n - **Expires**: Choose an appropriate expiration period (recommended: 24 months)\n4. Click **Add**\n5. **IMPORTANT**: Copy the **Value** immediately (not the Secret ID)\n - This is your `ENTRA_CLIENT_SECRET`\n - You cannot retrieve this value later - if you lose it, you'll need to create a new secret\n\n### Step 4: Configure Redirect URIs\n\n1. In your app registration, click **Authentication** in the left menu\n2. Under **Platform configurations** → **Web**, add redirect URIs:\n - For local development: `http://localhost/auth/callback`\n - For production: `https://your-domain.com/auth/callback`\n3. Under **Implicit grant and hybrid flows**, ensure nothing is checked (not needed for authorization code flow)\n4. Click **Save**\n\n### Step 5: Add API Permissions\n\nTo get user email and group information, you need to configure API permissions:\n\n1. Click **API permissions** in the left menu\n2. Click **Add a permission**\n3. Select **Microsoft Graph**\n4. Select **Delegated permissions**\n5. Search for and add the following permissions:\n - `User.Read` (should already be present)\n - `email` - Read user's email address\n - `profile` - Read user's basic profile\n - `GroupMember.Read.All` - Read groups user belongs to\n6. Click **Add permissions**\n\n#### Application Permissions (Required for IAM Management)\n\nIf you plan to use the IAM management UI (Settings -> Users/Groups) or the IAM API to manage users, groups, and M2M accounts, you must also add **Application permissions**. These are used by the server-side client credentials flow to call the Microsoft Graph API.\n\n1. Click **Add a permission**\n2. Select **Microsoft Graph**\n3. Select **Application permissions**\n4. Search for and add the following permissions:\n\n **Read-only access (minimum for IAM UI to list users and groups):**\n - `User.Read.All` - Read all users' full profiles\n - `Group.Read.All` - Read all groups\n - `GroupMember.Read.All` - Read all group memberships\n\n **Read-write access (required to create/delete users, groups, and M2M accounts):**\n - `User.ReadWrite.All` - Create, update, and delete users\n - `Group.ReadWrite.All` - Create, update, and delete groups\n - `GroupMember.ReadWrite.All` - Manage group memberships\n - `Application.ReadWrite.All` - Create and manage M2M service principal accounts\n\n5. Click **Add permissions**\n\n**CRITICAL**: Click **Grant admin consent for [Your Tenant]**\n - This step is required for **both** Delegated and Application permissions to work\n - You need admin privileges to grant consent\n - Without admin consent for Application permissions, the IAM management features will return `403 Forbidden` errors\n\n### Step 6: Configure Optional Claims\n\nTo include email, username, and groups in the ID token:\n\n1. Click **Token configuration** in the left menu\n2. Click **Add optional claim**\n3. Select **ID** token type\n4. Add these claims:\n - `email` - User's email address\n - `preferred_username` - User's UPN (User Principal Name)\n - `groups` - Security group Object IDs\n5. Click **Add**\n6. When prompted \"Turn on the Microsoft Graph email, profile permission\", click **Add**\n\n### Step 7: Configure Group Claims\n\n1. Still in **Token configuration**\n2. Click **Add groups claim**\n3. Select **Security groups**\n4. Under \"Customize token properties by type\":\n - **ID**: Check \"Group ID\"\n - **Access**: Check \"Group ID\"\n5. Click **Add**\n\n### Step 8: Create Security Groups\n\nCreate Azure AD security groups for authorization:\n\n1. Go to **Azure Active Directory** → **Groups**\n2. Click **New group**\n3. Create an admin group:\n - **Group type**: Security\n - **Group name**: `Mcp-test-admin` (or your preferred name)\n - **Group description**: MCP Gateway administrators\n - **Membership type**: Assigned\n4. Click **Create**\n5. Repeat for a users group:\n - **Group name**: `mcp-test-users` (or your preferred name)\n - **Group description**: MCP Gateway users\n\n### Step 9: Note Group Object IDs\n\nFor each group you created:\n\n1. Click on the group name\n2. From the **Overview** page, copy the **Object Id**\n3. Note these IDs - you'll need them for `scopes.yml` configuration\n\n### Step 10: Add Users to Groups\n\n1. For each group, click on the group name\n2. Click **Members** in the left menu\n3. Click **Add members**\n4. Search for and select users\n5. Click **Select**\n\n### Step 11: Configure App for API Access (Optional)\n\nIf you plan to use machine-to-machine (M2M) authentication:\n\n1. Click **Expose an API** in the left menu\n2. Click **Add** next to \"Application ID URI\"\n3. Accept the default (`api://{client-id}`) or customize it\n4. Click **Save**\n5. Click **Add a scope**\n6. Configure the scope:\n - **Scope name**: `.default`\n - **Who can consent**: Admins only\n - **Admin consent display name**: Access MCP Gateway\n - **Admin consent description**: Allow the application to access MCP Gateway\n - **State**: Enabled\n7. Click **Add scope**\n\n---\n\n## Environment Configuration\n\n### Step 1: Update .env File\n\n1. Copy `.env.example` to `.env` if you haven't already:\n ```bash\n cp .env.example .env\n ```\n\n2. Edit the `.env` file and configure Entra ID settings:\n\n```bash\n# =============================================================================\n# AUTHENTICATION PROVIDER CONFIGURATION\n# =============================================================================\n# Choose authentication provider: 'cognito', 'keycloak', or 'entra'\nAUTH_PROVIDER=entra\n\n# =============================================================================\n# MICROSOFT ENTRA ID CONFIGURATION\n# =============================================================================\n\n# Azure AD Tenant ID (from Azure Portal → App registration → Overview)\nENTRA_TENANT_ID=12345678-1234-1234-1234-123456789012\n\n# Entra ID Application (client) ID (from Azure Portal → App registration → Overview)\nENTRA_CLIENT_ID=87654321-4321-4321-4321-210987654321\n\n# Entra ID Client Secret (from Azure Portal → App registration → Certificates & secrets)\nENTRA_CLIENT_SECRET=your-secret-value-here\n\n# Enable Entra ID in OAuth2 providers\nENTRA_ENABLED=true\n\n# Azure AD Group Object IDs (from Azure Portal → Groups → Overview)\n# IMPORTANT: ENTRA_GROUP_ADMIN_ID is required for admin access to persist across restarts.\n# This group ID is added to the registry-admins scope in MongoDB during initialization.\n# Users in this Entra group will have full admin access to the MCP Gateway.\nENTRA_GROUP_ADMIN_ID=16c7e67e-e8ae-498c-ba2e-0593c0159e43\nENTRA_GROUP_USERS_ID=62c07ac1-03d0-4924-90c7-a0255f23bd1d\n```\n\n3. Update other required settings:\n\n```bash\n# =============================================================================\n# REGISTRY CONFIGURATION\n# =============================================================================\n# For local development\nREGISTRY_URL=http://localhost\n\n# For production with custom domain\n# REGISTRY_URL=https://mcpgateway.mycorp.com\n\n# =============================================================================\n# AUTH SERVER CONFIGURATION\n# =============================================================================\n# For local development\nAUTH_SERVER_EXTERNAL_URL=http://localhost\n\n# For production with custom domain\n# AUTH_SERVER_EXTERNAL_URL=https://mcpgateway.mycorp.com\n\n# =============================================================================\n# APPLICATION SECURITY\n# =============================================================================\n# CRITICAL: CHANGE THIS SECRET KEY IMMEDIATELY!\nSECRET_KEY=your-super-secure-random-64-character-string-here\n```\n\n---\n\n## Group Configuration\n\n### Configure scopes.yml\n\nThe `auth_server/scopes.yml` file maps Azure AD groups to MCP Gateway scopes and permissions.\n\n1. Open `auth_server/scopes.yml`\n\n2. Update the Entra ID group mappings section with your group Object IDs:\n\n```yaml\ngroup_mappings:\n # Entra ID group mappings (by Azure AD Group Object IDs)\n # Admin group\n \"object_id\":\n - mcp-registry-admin\n - registry-admins\n\n```\n\n3. Replace the group Object IDs with your actual group IDs from Azure Portal\n\n### Understanding Scope Mappings\n\n- **mcp-registry-admin**: Full administrative access to the registry\n - Can list, register, modify, and toggle services\n - Has unrestricted read and execute access to MCP servers\n\n- **mcp-registry-user**: Limited user access\n - Can list and view specific services\n - Has restricted read access to MCP servers\n\n- **mcp-registry-developer**: Development access\n - Can list, register, and health check services\n - Has restricted read and execute access\n\n- **mcp-registry-operator**: Operations access\n - Can list, health check, and toggle services\n - Has restricted read and execute access\n\n---\n\n## Testing the Setup\n\n### Step 1: Start the Services\n\n1. Build and start the Docker containers:\n ```bash\n docker-compose up -d --build\n ```\n\n2. Check that services are running:\n ```bash\n docker-compose ps\n ```\n\n### Step 2: Test User Authentication\n\n1. Open your browser and navigate to:\n ```\n http://localhost\n ```\n\n2. You should see the MCP Gateway Registry login page\n\n3. Click the **Sign in with Microsoft Entra ID** button\n\n4. You will be redirected to Microsoft's login page\n\n5. Sign in with a user account that belongs to one of your configured groups\n\n6. After successful authentication, you should be redirected back to the registry\n\n### Step 3: Verify User Information\n\n1. Check the auth server logs to verify user information is being received:\n ```bash\n docker-compose logs auth-server | grep \"Raw user info\"\n ```\n\n2. You should see output similar to:\n ```\n Raw user info from entra: {\n 'sub': 'abc123...',\n 'email': 'user@yourdomain.onmicrosoft.com',\n 'preferred_username': 'user@yourdomain.onmicrosoft.com',\n 'groups': ['16c7e67e-...', '62c07ac1-...'],\n 'name': 'First Last'\n }\n ```\n\n3. Verify the mapped scopes:\n ```bash\n docker-compose logs auth-server | grep \"Mapped user info\"\n ```\n\n4. You should see:\n ```\n Mapped user info: {\n 'username': 'user@yourdomain.onmicrosoft.com',\n 'email': 'user@yourdomain.onmicrosoft.com',\n 'name': 'First Last',\n 'groups': ['mcp-registry-admin', 'mcp-servers-unrestricted/read', ...]\n }\n ```\n\n### Step 4: Test Authorization\n\n1. Log in with an admin user (member of the admin group)\n\n2. Verify you can access admin functions:\n - Register new services\n - Modify service configurations\n - Toggle services on/off\n\n3. Log in with a regular user (member of the users group)\n\n4. Verify restricted access:\n - Can view services\n - Cannot register or modify services\n\n### Step 5: Test Machine-to-Machine (M2M) Authentication\n\nIf you configured API access for M2M authentication:\n\n1. Create a service principal for your AI agent:\n ```bash\n # This is done in Azure Portal → App registrations\n # Create a new app registration for the AI agent\n ```\n\n2. Test M2M token generation:\n ```bash\n curl -X POST \"https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id={agent-client-id}\" \\\n -d \"client_secret={agent-client-secret}\" \\\n -d \"scope=api://{mcp-gateway-client-id}/.default\"\n ```\n\n3. Use the access token to call MCP Gateway APIs\n\n---\n\n## Troubleshooting\n\n### Issue: 403 Forbidden when using IAM management UI\n\n**Symptoms:**\n```\nClient error '403 Forbidden' for url 'https://graph.microsoft.com/v1.0/users?...'\n```\n\n**Cause:**\nThe IAM management features (listing users, creating users/groups, managing M2M accounts) use the OAuth2 client credentials flow to call the Microsoft Graph API. This flow requires **Application permissions**, not Delegated permissions. If only Delegated permissions are configured, the Graph API will return 403 Forbidden.\n\n**Solution:**\n1. Go to Azure Portal -> App registrations -> Your app -> **API permissions**\n2. Click **Add a permission** -> **Microsoft Graph** -> **Application permissions**\n3. Add the required Application permissions (see [Step 5: Application Permissions](#application-permissions-required-for-iam-management))\n4. Click **Grant admin consent for [Your Tenant]**\n5. Wait 5-10 minutes for Azure AD to propagate changes\n6. Restart the registry service\n\n### Issue: Missing email and groups claims\n\n**Symptoms:**\n```\nRaw user info from entra: {'sub': '...', 'name': 'User Name', 'family_name': '...', 'given_name': '...'}\nMapped user info: {'username': None, 'email': None, 'groups': []}\n```\n\n**Solution:**\n1. Verify you completed [Step 5: Add API Permissions](#step-5-add-api-permissions)\n2. Ensure you clicked **Grant admin consent**\n3. Complete [Step 6: Configure Optional Claims](#step-6-configure-optional-claims)\n4. Complete [Step 7: Configure Group Claims](#step-7-configure-group-claims)\n5. Wait 5-10 minutes for Azure AD to propagate changes\n6. Clear browser cookies and try logging in again\n\n### Issue: Token validation fails with \"Invalid issuer\"\n\n**Symptoms:**\n```\nToken validation failed: Invalid issuer: https://sts.windows.net/{tenant}/\n```\n\n**Solution:**\nThe Entra ID provider supports both v1.0 and v2.0 token formats. This error should not occur with the current implementation. If you see this:\n\n1. Check that `ENTRA_TENANT_ID` in `.env` matches your actual tenant ID\n2. Verify the token is being issued by Microsoft Entra ID\n3. Check auth server logs for more details\n\n### Issue: User cannot access any resources\n\n**Symptoms:**\nUser can log in but sees \"Access Denied\" or \"Insufficient Permissions\"\n\n**Solution:**\n1. Verify the user is added to at least one security group in Azure AD\n2. Check that group Object IDs in `scopes.yml` match the groups in Azure Portal\n3. Verify the group mappings include the necessary scopes\n4. Check auth server logs to see what groups are being received:\n ```bash\n docker-compose logs auth-server | grep \"groups\"\n ```\n\n### Issue: Redirect URI mismatch error\n\n**Symptoms:**\n```\nAADSTS50011: The redirect URI 'http://localhost/auth/callback' does not match the redirect URIs configured for the application\n```\n\n**Solution:**\n1. Go to Azure Portal → App registrations → Your app → Authentication\n2. Verify the redirect URI exactly matches what's in the error message\n3. Add any missing redirect URIs\n4. Ensure `AUTH_SERVER_EXTERNAL_URL` in `.env` matches the base URL\n\n### Issue: \"Groups overage\" claim\n\n**Symptoms:**\nGroups claim contains `_claim_names` and `_claim_sources` instead of group IDs\n\n**Solution:**\nThis occurs when a user is a member of more than 200 groups. You need to:\n\n1. Modify the auth provider to fetch groups via Microsoft Graph API\n2. See the alternative implementation in `docs/ENTRA-ID-APP-CONFIGURATION.md` Step 5\n\n### Issue: Client secret expired\n\n**Symptoms:**\n```\nAADSTS7000215: Invalid client secret provided\n```\n\n**Solution:**\n1. Go to Azure Portal → App registrations → Your app → Certificates & secrets\n2. Create a new client secret\n3. Update `ENTRA_CLIENT_SECRET` in `.env`\n4. Restart the services:\n ```bash\n docker-compose restart auth-server\n ```\n\n### Issue: Cannot grant admin consent\n\n**Symptoms:**\nYou don't see the \"Grant admin consent\" button or get an error when clicking it\n\n**Solution:**\n1. You need Global Administrator, Application Administrator, or Cloud Application Administrator role\n2. Contact your Azure AD administrator to grant the permissions\n3. Alternatively, users can consent individually (not recommended for production)\n\n---\n\n## Additional Resources\n\n- [Microsoft Entra ID Documentation](https://learn.microsoft.com/en-us/entra/)\n- [OAuth 2.0 Authorization Code Flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow)\n- [Optional Claims Configuration](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims)\n- [Configure Group Claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims#configure-groups-optional-claims)\n- [Microsoft Graph Permissions Reference](https://learn.microsoft.com/en-us/graph/permissions-reference)\n\n---\n\n## Production Deployment\n\n### Update Redirect URIs\n\nFor production, update redirect URIs:\n```\nhttps://your-domain.com/oauth2/callback/entra\n```\n\n### Environment Variables\n\nUpdate production `.env`:\n```bash\nENTRA_REDIRECT_URI=https://your-domain.com/oauth2/callback/entra\nAUTH_SERVER_EXTERNAL_URL=https://your-domain.com:8888\n```\n\n### SSL/TLS Configuration\n\nEnsure your production deployment uses HTTPS for all OAuth flows.\n\n---\n\n## Advanced Configuration\n\n### Custom Claims\n\nTo add custom claims to tokens:\n1. Go to **Token configuration**\n2. Click **Add optional claim**\n3. Select token type and claims\n4. Configure claim conditions\n\n### Group Filtering\n\nTo limit which groups are included in tokens:\n1. Go to **Token configuration** \n2. Click **Add groups claim**\n3. Configure **Groups assigned to the application**\n\n### Enterprise Applications\n\nFor advanced management:\n1. Go to **Enterprise applications**\n2. Find your app registration\n3. Configure:\n - User assignment required\n - Visibility settings\n - Provisioning (if needed)\n\n---\n\n## Adding New Users\n\n### Option 1: Add User to Existing Group (Recommended)\n\n**In Azure Portal:**\n1. Go to **Microsoft Entra ID** → **Groups**\n2. Click on **MCP Registry Admins** (or appropriate group)\n3. Click **Members** → **Add members**\n4. Search and select the new user\n5. Click **Select**\n\n**Access will be immediate** - user can login and see servers/agents.\n\n### Option 2: Create New Group for User\n\n**If you need different permissions:**\n\n1. **Create new group in Azure:**\n - **Group name**: `MCP Registry LOB3 Users`\n - **Members**: Add the new user\n\n2. **Get the group Object ID** from the group overview page\n\n3. **Add to scopes.yml:**\n```yaml\ngroup_mappings:\n # Add new group mapping\n \"new-group-object-id-here\":\n - registry-users-lob1 # or whatever permission level needed\n```\n\n4. **Restart auth server:**\n```bash\ncp auth_server/scopes.yml ~/mcp-gateway/auth_server/scopes.yml\ndocker-compose restart auth-server\n```\n\n---\n\n## API Reference\n\n### Token Endpoint\n```\nPOST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token\n```\n\n### Authorization Endpoint\n```\nGET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize\n```\n\n### User Info Endpoint\n```\nGET https://graph.microsoft.com/v1.0/me\n```\n\n---\n\n## Security Best Practices\n\n1. **Client Secret Management**\n - Store client secrets securely (use Azure Key Vault in production)\n - Rotate secrets regularly (set expiration and create new secrets)\n - Never commit secrets to version control\n\n2. **Token Configuration**\n - Keep token expiration times reasonable (default: 1 hour for access tokens)\n - Use refresh tokens for long-running sessions\n - Implement proper token revocation\n\n3. **Group Management**\n - Use security groups (not distribution lists or Microsoft 365 groups)\n - Apply principle of least privilege\n - Regularly audit group memberships\n\n4. **HTTPS in Production**\n - Always use HTTPS in production environments\n - Configure proper SSL/TLS certificates\n - Update redirect URIs to use HTTPS\n\n5. **Monitoring and Logging**\n - Enable Azure AD audit logs\n - Monitor sign-in logs for suspicious activity\n - Set up alerts for authentication failures\n\n6. **Multi-Factor Authentication**\n - Enable MFA for all users (configured in Azure AD)\n - Use conditional access policies\n - Enforce MFA for admin accounts\n\n---\n\n## Using the IAM API to Manage Groups, Users, and M2M Accounts\n\nThe MCP Gateway Registry provides an IAM API for managing groups, human users, and M2M (machine-to-machine) service accounts programmatically. This section covers how to use the `registry_management.py` CLI to perform these operations.\n\n### Prerequisites\n\nBefore using the IAM API commands, you need:\n\n1. **An admin access token**: Either a self-signed token from the UI sidebar or a Keycloak/Entra ID token for an admin user\n2. **Registry URL**: The URL of your MCP Gateway Registry deployment\n3. **Admin group membership**: Your user must be in the `registry-admins` group\n\nSave your token to a file for CLI usage:\n```bash\n# Save token from UI sidebar to a file\necho \"eyJhbGci...\" > api/.token\n```\n\n### Creating a Group (Scope)\n\nGroups define access permissions for users and M2M accounts. Create a group definition JSON file:\n\n**Example: `cli/examples/public-mcp-users.json`**\n```json\n{\n \"scope_name\": \"public-mcp-users\",\n \"description\": \"Users with access to public MCP servers\",\n \"server_access\": [\n {\n \"server\": \"context7\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"initialize\", \"GET\", \"POST\", \"servers\", \"agents\"],\n \"tools\": []\n },\n {\n \"agents\": {\n \"actions\": [\n {\"action\": \"list_agents\", \"resources\": [\"/flight-booking\"]},\n {\"action\": \"get_agent\", \"resources\": [\"/flight-booking\"]}\n ]\n }\n }\n ],\n \"group_mappings\": [\"public-mcp-users\"],\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n },\n \"create_in_idp\": true\n}\n```\n\n**Import the group:**\n```bash\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://your-registry-url.example.com \\\n import-group --file cli/examples/public-mcp-users.json\n```\n\n**Key fields in group definition:**\n\n| Field | Description |\n|-------|-------------|\n| `scope_name` | Unique identifier for the scope/group |\n| `description` | Human-readable description |\n| `server_access` | Array of server access rules |\n| `group_mappings` | List of IdP group names/IDs that map to this scope |\n| `ui_permissions` | Permissions for the web UI |\n| `create_in_idp` | If `true`, creates corresponding group in Entra ID |\n\n### Creating a Human User\n\nHuman users can log in via the web UI using Entra ID authentication.\n\n```bash\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://your-registry-url.example.com \\\n user-create-human \\\n --username jsmith \\\n --email jsmith@example.com \\\n --first-name John \\\n --last-name Smith \\\n --groups public-mcp-users \\\n --password \"SecurePassword123!\"\n```\n\n**Parameters:**\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `--username` | Yes | Username for the account |\n| `--email` | Yes | Email address |\n| `--first-name` | Yes | User's first name |\n| `--last-name` | Yes | User's last name |\n| `--groups` | Yes | Comma-separated list of groups |\n| `--password` | No | Initial password (auto-generated if not provided) |\n\n### Creating an M2M Service Account\n\nM2M (machine-to-machine) accounts are used for programmatic API access, AI coding assistants, and agent identities.\n\n```bash\nuv run python api/registry_management.py \\\n --token-file api/.token \\\n --registry-url https://your-registry-url.example.com \\\n user-create-m2m \\\n --name my-ai-agent \\\n --groups public-mcp-users \\\n --description \"AI coding assistant service account\"\n```\n\n**Output:**\n```\nClient ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nClient Secret: xxxxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nGroups: public-mcp-users\nService Principal ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n\nIMPORTANT: Save the client secret securely - it cannot be retrieved later.\n```\n\n**Parameters:**\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `--name` | Yes | Service account name/client ID |\n| `--groups` | Yes | Comma-separated list of groups |\n| `--description` | No | Account description |\n\n### Where to Find Parameter Values\n\n| Parameter | Location |\n|-----------|----------|\n| **Tenant ID** | Azure Portal -> Microsoft Entra ID -> Overview -> Tenant ID |\n| **App Client ID** | Azure Portal -> App registrations -> [Your App] -> Application (client) ID |\n| **App Client Secret** | Azure Portal -> App registrations -> [Your App] -> Certificates & secrets |\n| **Group Object ID** | Azure Portal -> Microsoft Entra ID -> Groups -> [Group Name] -> Object Id |\n| **M2M Client ID/Secret** | Output from `user-create-m2m` command |\n\n---\n\n## Generating JWT Tokens for M2M Accounts\n\nM2M accounts use OAuth2 client credentials flow to obtain JWT tokens. These tokens can be used for:\n\n- Agent identities in A2A (Agent-to-Agent) communication\n- AI coding assistants (Cursor, VS Code, etc.)\n- Programmatic API access\n- Automated scripts and CI/CD pipelines\n\n### Method 1: Direct Token Request (curl)\n\nRequest a token directly from Microsoft Entra ID:\n\n```bash\ncurl -X POST \"https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id={M2M_CLIENT_ID}\" \\\n -d \"client_secret={M2M_CLIENT_SECRET}\" \\\n -d \"scope=api://{APP_CLIENT_ID}/.default\" \\\n -d \"grant_type=client_credentials\"\n```\n\n**Example with placeholder values:**\n```bash\ncurl -X POST \"https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id=your-m2m-client-id\" \\\n -d \"client_secret=your-m2m-client-secret\" \\\n -d \"scope=api://your-app-client-id/.default\" \\\n -d \"grant_type=client_credentials\"\n```\n\n**Response:**\n```json\n{\n \"token_type\": \"Bearer\",\n \"expires_in\": 3599,\n \"access_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOi...\"\n}\n```\n\n### Method 2: Using the Credentials Provider Script\n\nThe `generate_creds.sh` script automates token generation for multiple identities.\n\n**Step 1: Configure identities file**\n\nCreate or edit `.oauth-tokens/entra-identities.json`:\n```json\n[\n {\n \"identity_name\": \"my-ai-agent\",\n \"tenant_id\": \"your-tenant-id\",\n \"client_id\": \"your-m2m-client-id\",\n \"client_secret\": \"your-m2m-client-secret\",\n \"scope\": \"api://your-app-client-id/.default\"\n }\n]\n```\n\n**Identities File Structure:**\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `identity_name` | Yes | Unique name for this identity (used for output file naming) |\n| `tenant_id` | Yes | Azure AD Tenant ID (from Azure Portal -> Microsoft Entra ID -> Overview) |\n| `client_id` | Yes | M2M service account Client ID (from `user-create-m2m` output) |\n| `client_secret` | Yes | M2M service account Client Secret (from `user-create-m2m` output) |\n| `scope` | Yes | OAuth2 scope in format `api://{APP_CLIENT_ID}/.default` |\n\n**Multiple Identities Example:**\n```json\n[\n {\n \"identity_name\": \"cursor-assistant\",\n \"tenant_id\": \"your-tenant-id\",\n \"client_id\": \"cursor-m2m-client-id\",\n \"client_secret\": \"cursor-m2m-client-secret\",\n \"scope\": \"api://your-app-client-id/.default\"\n },\n {\n \"identity_name\": \"ci-pipeline\",\n \"tenant_id\": \"your-tenant-id\",\n \"client_id\": \"cicd-m2m-client-id\",\n \"client_secret\": \"cicd-m2m-client-secret\",\n \"scope\": \"api://your-app-client-id/.default\"\n }\n]\n```\n\n**Step 2: Set auth provider**\n\nEnsure `AUTH_PROVIDER=entra` is set in your `.env` file.\n\n**Step 3: Run the script**\n\n```bash\n./credentials-provider/generate_creds.sh\n```\n\nOr with a custom identities file:\n```bash\nuv run credentials-provider/entra/get_m2m_token.py \\\n --identities-file /path/to/my-identities.json \\\n --output-dir .oauth-tokens \\\n --verbose\n```\n\n**Output:**\n- Tokens are saved to `.oauth-tokens/{identity_name}.json`\n- Each file contains the access token, expiration time, and metadata\n\n### Token Scope Format\n\nThe scope for Entra ID M2M tokens follows this format:\n```\napi://{APP_CLIENT_ID}/.default\n```\n\nWhere:\n- `{APP_CLIENT_ID}` is the Application (client) ID of your MCP Gateway app registration\n- `.default` requests all scopes that admin consent has been granted for\n\n### Using Tokens in AI Coding Assistants\n\nOnce you have a JWT token, you can use it in AI coding assistants like Cursor or VS Code extensions:\n\n1. **Configure the MCP server connection** with the registry URL\n2. **Set the Bearer token** in the authorization header\n3. **The token** grants access based on the M2M account's group membership\n\nExample configuration for an AI assistant:\n```json\n{\n \"mcp_registry_url\": \"https://your-registry-url.example.com\",\n \"auth_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOi...\"\n}\n```\n\n### User-Generated Tokens from the UI\n\nUsers can also generate personal JWT tokens from the MCP Gateway Registry web UI:\n\n1. Log in to the registry at `https://your-registry-url.example.com`\n2. Navigate to the sidebar\n3. Click on \"Generate Token\" or similar option\n4. Copy the generated token\n\nThese self-signed tokens:\n- Are signed with HS256 using the server's secret key\n- Include the user's groups and scopes\n- Can be used for programmatic API access\n- Work with the same endpoints as M2M tokens\n\n---\n\n## Next Steps\n\nAfter completing the setup:\n\n1. **Configure Additional Services**: Add more MCP servers to the registry\n2. **Set Up Custom Domain**: Configure HTTPS and custom domain names\n3. **Configure M2M Authentication**: Set up service principals for AI agents\n4. **Implement Monitoring**: Set up observability and alerting\n5. **Production Deployment**: Deploy to your production environment\n\nFor more information, see:\n- [Complete Setup Guide](./complete-setup-guide.md)\n- [Observability Documentation](./OBSERVABILITY.md)\n- [FAQ](./faq/index.md)\n" }, { "path": "docs/entra.md", "content": "# Microsoft Entra ID Integration for MCP Gateway Registry\n\nThis document describes the integration between Microsoft Entra ID and the MCP Gateway Registry, including the JWT token generation flow for programmatic API access.\n\n## Overview\n\nThe MCP Gateway Registry supports Microsoft Entra ID as an OAuth2 identity provider. Users can authenticate via Entra ID and obtain JWT tokens for programmatic access to the gateway APIs (CLI tools, coding assistants, etc.).\n\n## Architecture\n\n### Authentication Flow\n\n```\n┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n│ Browser │ │ Registry │ │ Auth Server │ │ Entra ID │\n│ (User) │ │ Frontend │ │ │ │ (Microsoft)│\n└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘\n │ │ │ │\n │ 1. Click Login │ │ │\n │──────────────────>│ │ │\n │ │ │ │\n │ 2. Redirect to Auth Server │ │\n │<──────────────────│ │ │\n │ │ │ │\n │ 3. /oauth2/login/entra │ │\n │──────────────────────────────────────>│ │\n │ │ │ │\n │ 4. Redirect to Entra ID authorize endpoint │\n │<─────────────────────────────────────────────────────────>│\n │ │ │ │\n │ 5. User authenticates with Microsoft │ │\n │<─────────────────────────────────────────────────────────>│\n │ │ │ │\n │ 6. Redirect with auth code │ │\n │──────────────────────────────────────>│ │\n │ │ │ │\n │ │ 7. Exchange code │ │\n │ │ for tokens │ │\n │ │ │──────────────────>│\n │ │ │<──────────────────│\n │ │ │ (ID token + │\n │ │ │ access token) │\n │ │ │ │\n │ 8. Set session cookie + redirect │ │\n │<──────────────────────────────────────│ │\n │ │ │ │\n │ 9. Access Registry with session │ │\n │──────────────────>│ │ │\n │ │ │ │\n```\n\n### JWT Token Generation Flow (Get JWT Token Button)\n\nWhen an OAuth-authenticated user clicks \"Get JWT Token\" in the UI:\n\n```\n┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n│ Browser │ │ Registry │ │ Auth Server │ │ DocumentDB │\n│ (User) │ │ Backend │ │ │ │ (Scopes) │\n└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘\n │ │ │ │\n │ 1. Click \"Get JWT Token\" │ │\n │──────────────────>│ │ │\n │ │ │ │\n │ │ 2. POST /api/tokens/generate │\n │ │ (with session cookie) │\n │ │──────────────────>│ │\n │ │ │ │\n │ │ │ 3. Validate session\n │ │ │ Extract: username,\n │ │ │ groups, provider │\n │ │ │ │\n │ │ │ 4. Query group │\n │ │ │ mappings │\n │ │ │──────────────────>│\n │ │ │<──────────────────│\n │ │ │ (scopes for │\n │ │ │ user's groups) │\n │ │ │ │\n │ │ │ 5. Build JWT claims:\n │ │ │ - iss: mcp-auth-server\n │ │ │ - aud: mcp-registry\n │ │ │ - sub: username\n │ │ │ - groups: [group IDs]\n │ │ │ - scope: mapped scopes\n │ │ │ - exp: 8 hours\n │ │ │ │\n │ │ │ 6. Sign JWT with\n │ │ │ SECRET_KEY (HS256)\n │ │ │ │\n │ │ 7. Return JWT │ │\n │ │<──────────────────│ │\n │ │ │ │\n │ 8. Display token │ │ │\n │<──────────────────│ │ │\n │ │ │ │\n```\n\n### Token Validation Flow (CLI/API Usage)\n\nWhen a user uses the self-signed JWT token with the CLI or API:\n\n```\n┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n│ CLI / │ │ NGINX │ │ Auth Server │ │ MCP Server │\n│ Client │ │ Gateway │ │ │ │ │\n└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘\n │ │ │ │\n │ 1. API Request │ │ │\n │ Authorization: │ │ │\n │ Bearer │ │ │\n │──────────────────>│ │ │\n │ │ │ │\n │ │ 2. auth_request │ │\n │ │ /validate │ │\n │ │──────────────────>│ │\n │ │ │ │\n │ │ │ 3. Check token issuer\n │ │ │ iss == \"mcp-auth-server\"?\n │ │ │ │\n │ │ │ 4. If yes: validate\n │ │ │ with SECRET_KEY (HS256)\n │ │ │ │\n │ │ │ 5. If no: try Entra\n │ │ │ JWKS validation (RSA)\n │ │ │ │\n │ │ │ 6. Extract scopes,\n │ │ │ validate server/tool\n │ │ │ access permissions\n │ │ │ │\n │ │ 7. 200 OK + │ │\n │ │ X-User headers │ │\n │ │<──────────────────│ │\n │ │ │ │\n │ │ 8. Proxy request │ │\n │ │──────────────────────────────────────>│\n │ │ │ │\n │ 9. Response │ │ │\n │<──────────────────────────────────────────────────────────│\n │ │ │ │\n```\n\n## Token Types\n\n### 1. Entra ID Tokens (from Microsoft)\n\nWhen users authenticate via Entra ID, Microsoft issues:\n\n- **ID Token**: Contains user identity claims (username, email, groups)\n- **Access Token**: Scoped for Microsoft Graph API (not usable for our gateway)\n\nThese tokens are:\n- RSA-signed (RS256) with Microsoft's keys\n- Validated against Microsoft's JWKS endpoint\n- Contain group Object IDs (not group names)\n\n### 2. Self-Signed JWT Tokens (from Auth Server)\n\nWhen users click \"Get JWT Token\", the auth server generates:\n\n- **Self-Signed JWT**: Contains user identity + gateway-specific scopes\n- Signed with HS256 using `SECRET_KEY`\n- Contains: username, groups, mapped scopes, provider info\n\n## Security Analysis\n\n### Why We Use Self-Signed Tokens (Not IdP Tokens Directly)\n\n**The IdP tokens don't work for our use case:**\n\n1. **Entra Access Token is for Microsoft Graph API** - When you authenticate with Entra ID, the access token you receive is scoped for Microsoft's APIs (like Graph API for reading user profiles). It's not meant for your custom gateway.\n\n2. **IdP tokens don't contain your scopes** - Entra doesn't know about your `public-mcp-users` scope or your MCP server permissions. Those mappings exist only in your system (scopes.yml, DocumentDB).\n\n3. **Group-to-scope mapping is custom** - The translation from Entra Group Object ID (`5f605d68-06bc-4208-b992-bb378eee12c5`) to gateway scopes (`public-mcp-users`) happens in your auth server, not in Entra.\n\n### Is the Self-Signed Approach Secure?\n\n**Yes, with proper implementation.** Here's why:\n\n| Security Aspect | Implementation |\n|-----------------|----------------|\n| **Secret Management** | SECRET_KEY from environment variable, not hardcoded |\n| **Token Validation** | Every request validates signature, expiry, issuer, audience |\n| **Short Expiry** | 8-hour token lifetime limits exposure window |\n| **No Credential Storage** | Users don't store passwords; token is derived from OAuth session |\n| **Auditable Claims** | Token contains username, groups, provider - traceable |\n| **Rate Limiting** | Token generation rate-limited per user (100/hour default) |\n\n### Comparison: Self-Signed vs Direct IdP Tokens\n\n| Aspect | Self-Signed JWT | Direct IdP Token |\n|--------|-----------------|------------------|\n| **Signing** | HS256 (symmetric) | RS256 (asymmetric) |\n| **Key Management** | Single SECRET_KEY | IdP manages key rotation |\n| **Scope Mapping** | Done at generation time | Would need separate mapping layer |\n| **Token Revocation** | Expiry-based only | Could use IdP revocation |\n| **Complexity** | Simple | Requires IdP API registration |\n| **Audit Trail** | In auth server logs | In IdP audit logs |\n\n### What Would Be \"More Secure\"?\n\nGetting tokens directly from IdP would require:\n\n1. **Registering your gateway as an API in Entra** - Defining your own scopes in Azure AD\n2. **Users requesting your API scopes** - During OAuth login\n3. **Entra issuing tokens for your API** - Instead of for Graph API\n\nThis provides:\n- Tokens signed by Microsoft's keys (asymmetric RSA)\n- Centralized token revocation through Entra\n- Entra's audit logs for token issuance\n\n**However**, you'd still need to map Entra groups to your MCP permissions somewhere, so the complexity often isn't worth it for internal/enterprise use cases.\n\n### Security Best Practices\n\n1. **Rotate SECRET_KEY periodically** - Update via environment variable\n2. **Use HTTPS everywhere** - Tokens in transit must be encrypted\n3. **Monitor token usage** - Log and alert on unusual patterns\n4. **Short token lifetime** - 8 hours default, configurable\n5. **Scope minimization** - Tokens only get scopes user already has\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Auth Server\nSECRET_KEY=your-secure-random-key-here\nJWT_ISSUER=mcp-auth-server\nJWT_AUDIENCE=mcp-registry\nMAX_TOKENS_PER_USER_PER_HOUR=100\n\n# Entra ID\nENTRA_ENABLED=true\nENTRA_CLIENT_ID=your-client-id\nENTRA_CLIENT_SECRET=your-client-secret\nENTRA_TENANT_ID=your-tenant-id\n```\n\n### Group Mappings (scopes.yml or DocumentDB)\n\n```yaml\ngroup_mappings:\n # Entra ID Group Object ID -> Gateway Scopes\n \"5f605d68-06bc-4208-b992-bb378eee12c5\":\n - public-mcp-users\n\n \"4c46ec66-a4f7-4b62-9095-b7958662f4b6\":\n - registry-admins\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n```\n\n### Entra ID App Registration Requirements\n\n#### User Authentication App (OAuth Login)\n\n1. **Redirect URIs**: Add your auth server callback URLs\n - `https://your-domain.com/oauth2/callback/entra`\n\n2. **Token Configuration**:\n - Enable ID tokens\n - Add `groups` claim to ID token\n\n3. **API Permissions (Delegated)**:\n - `openid` (delegated)\n - `email` (delegated)\n - `profile` (delegated)\n\n4. **Group Claims**:\n - Configure \"Groups assigned to the application\" or \"All groups\"\n - Emit groups as Object IDs (not names)\n\n#### Admin App (IAM Management - M2M Account Creation)\n\nTo create M2M service accounts via the Management API, the admin app registration needs additional **Application permissions** (not delegated):\n\n1. **API Permissions (Application - requires admin consent)**:\n - `Application.ReadWrite.All` - Create/manage app registrations\n - `Directory.ReadWrite.All` - Create service principals and manage group memberships\n - `Group.ReadWrite.All` - Create and manage groups\n - `User.ReadWrite.All` - Create and manage users\n\n2. **Grant Admin Consent**:\n - After adding permissions, click \"Grant admin consent for [Tenant]\"\n - Requires Global Administrator or Privileged Role Administrator\n\n3. **Client Secret**:\n - Create a client secret under \"Certificates & secrets\"\n - Set as `ENTRA_CLIENT_SECRET` environment variable\n\n**Note**: The admin app is used by the registry backend for IAM operations. It's separate from the user-facing OAuth app (though they can be the same app registration with both delegated and application permissions).\n\n## JWT Token Structure\n\n### Claims in Self-Signed JWT\n\n```json\n{\n \"iss\": \"mcp-auth-server\",\n \"aud\": \"mcp-registry\",\n \"sub\": \"user@example.com\",\n \"preferred_username\": \"user@example.com\",\n \"email\": \"user@example.com\",\n \"groups\": [\"5f605d68-06bc-4208-b992-bb378eee12c5\"],\n \"scope\": \"public-mcp-users\",\n \"token_use\": \"access\",\n \"auth_method\": \"oauth2\",\n \"provider\": \"entra\",\n \"iat\": 1768685007,\n \"exp\": 1768713807,\n \"description\": \"Generated via sidebar\"\n}\n```\n\n### Token Validation Logic\n\nThe Entra provider's `validate_token` method:\n\n1. **Check issuer first**: If `iss == \"mcp-auth-server\"`, validate as self-signed\n2. **Self-signed validation**: Use HS256 with SECRET_KEY\n3. **Entra validation**: If not self-signed, use RSA with Microsoft JWKS\n\nThis ensures both token types work seamlessly with the same validation endpoint.\n\n## Usage Examples\n\n### CLI with Self-Signed Token\n\n```bash\n# Set the token from \"Get JWT Token\" button\nexport MCP_TOKEN=\"eyJhbGciOiJIUzI1NiIs...\"\n\n# Use with mcpgw CLI\nmcpgw servers list --token \"$MCP_TOKEN\"\nmcpgw tools call context7 resolve-library-id --args '{\"libraryName\": \"react\"}'\n```\n\n### Python SDK\n\n```python\nimport requests\n\ntoken = \"eyJhbGciOiJIUzI1NiIs...\"\nheaders = {\"Authorization\": f\"Bearer {token}\"}\n\nresponse = requests.get(\n \"https://your-gateway.com/api/servers\",\n headers=headers\n)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Token missing 'kid' in header\"**\n - Cause: Self-signed tokens don't have `kid`, but validation expected RSA token\n - Fix: Auth server now checks issuer before attempting JWKS validation\n\n2. **\"Invalid token issuer\"**\n - Cause: Token issuer doesn't match expected value\n - Fix: Ensure `JWT_ISSUER` env var matches on token generation and validation\n\n3. **\"Access denied - no scopes configured\"**\n - Cause: User's groups don't map to any scopes\n - Fix: Add group mapping in scopes.yml or DocumentDB\n\n4. **Groups not appearing in token**\n - Cause: Entra app not configured to emit groups\n - Fix: Configure \"Token configuration\" in Entra app registration\n" }, { "path": "docs/faq/agent-autonomous-tool-discovery.md", "content": "# How do I handle tool discovery when I don't know what tools are available?\n\nUse the Dynamic Tool Discovery feature:\n\n1. **In your agent code**:\n ```python\n # Let your agent discover tools autonomously\n tools = await intelligent_tool_finder(\n natural_language_query=\"I need to get stock market data\",\n session_cookie=session_cookie,\n top_n_tools=3\n )\n \n # Then invoke the discovered tool\n if tools:\n result = await invoke_mcp_tool(\n server_name=tools[0][\"service_path\"],\n tool_name=tools[0][\"tool_name\"],\n arguments={\"symbol\": \"AAPL\"},\n # ... auth parameters\n )\n ```\n\n2. **Configure your agent** with tool discovery capabilities as shown in the [Dynamic Tool Discovery guide](../dynamic-tool-discovery.md).\n\n## Related Documentation\n\n- [Dynamic Tool Discovery](../dynamic-tool-discovery.md) -- complete guide with configuration details\n- [AI Registry Tools](../ai-registry-tools.md) -- available registry tools for agents\n" }, { "path": "docs/faq/connecting-multiple-mcp-servers.md", "content": "# How do I connect my agent to multiple MCP servers through the gateway?\n\nThe gateway provides a single endpoint with path-based routing:\n\n```python\n# Connect to different servers via the gateway using SSE client\nfrom mcp import ClientSession\nfrom mcp.client.sse import sse_client\n\nasync def connect_to_server(server_url):\n async with sse_client(server_url) as (read, write):\n async with ClientSession(read, write) as session:\n await session.initialize()\n # Use the session for tool calls\n return session\n\n# Example server URLs through the gateway\nserver_url = f\"https://your-gateway.com/currenttime/sse\"\ntime_session = await connect_to_server(server_url)\n\n# Or use the registry's tool discovery\nregistry_url = f\"https://your-gateway.com/mcpgw/sse\"\nregistry_session = await connect_to_server(registry_url)\n```\n\nAll requests go through the same gateway with authentication handled centrally.\n\n## Related Documentation\n\n- [Authentication](../auth.md) -- authentication modes and headers\n- [Installation](../installation.md) -- gateway deployment and configuration\n" }, { "path": "docs/faq/deploying-and-registering-servers-agents.md", "content": "# How do I deploy and register MCP servers and agents?\n\nMCP servers and agents are built and deployed **out of band** -- the MCP Gateway Registry does not host or run them. You build and deploy your servers and agents using whatever framework and infrastructure you prefer, then register them in the registry so they can be discovered and accessed through the gateway.\n\n## Building and Deploying MCP Servers\n\nYou can build MCP servers using any MCP-compatible framework and deploy them on any infrastructure:\n\n**Frameworks:**\n- [FastMCP](https://github.com/PrefectHQ/fastmcp) -- Python framework for building MCP servers\n- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) -- Official TypeScript SDK\n- Any framework that implements the [MCP specification](https://modelcontextprotocol.io/specification)\n\n**Deployment options:**\n- [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) -- managed runtime for MCP servers\n- Amazon EKS or any Kubernetes cluster\n- AWS ECS, Azure Container Apps, Google Cloud Run\n- A standalone Linux instance with Docker or systemd\n- Any cloud or on-premises infrastructure that can serve HTTP endpoints\n\nYour deployed server needs to expose an MCP-compatible endpoint (typically `/mcp` for Streamable HTTP) that the gateway can reach over the network.\n\n## Building and Deploying A2A Agents\n\nSimilarly, agents are built using any agent framework and deployed independently:\n\n**Frameworks:**\n- [A2A Python SDK](https://github.com/a2aproject/a2a-python) -- reference implementation for A2A protocol\n- [LangGraph](https://github.com/langchain-ai/langgraph) with A2A adapter\n- [CrewAI](https://github.com/crewAIInc/crewAI) -- multi-agent orchestration\n- Any framework that exposes an [A2A-compatible agent card](https://a2a-protocol.org/) at `/.well-known/agent-card.json`\n\n**Deployment options:**\n- [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) -- managed runtime for A2A agents\n- Amazon EKS or any Kubernetes cluster\n- AWS Lambda behind API Gateway\n- Any cloud infrastructure that can serve HTTP endpoints\n\nYour deployed agent needs to expose its agent card at `/.well-known/agent-card.json` and handle A2A protocol requests.\n\n## Registering in the Registry\n\nOnce your server or agent is deployed and accessible, register it in the MCP Gateway Registry using one of these methods:\n\n### Option 1: Register through the Web UI\n\n1. Open the registry dashboard\n2. Click **Register** on the MCP Servers or Agents tab\n3. Fill in the form with your server/agent details (URL, name, description, etc.)\n4. Click Submit\n\n### Option 2: Generate JSON cards using Claude Code skills\n\nUse the built-in Claude Code skills to generate registration JSON by analyzing your source code:\n\n```bash\n# For MCP servers -- analyzes source code and generates a server card JSON\n/generate-server-card\n\n# For A2A agents -- analyzes source code and generates an agent card JSON\n/generate-agent-card\n```\n\nThese skills produce JSON files that can be uploaded through the UI or used with the API.\n\n### Option 3: Register programmatically via API\n\nUse the [Registry Management CLI](../../api/registry_management.py) to register from the command line.\n\nTo get a token, click the **\"Get JWT Token\"** button in the top-left corner of the registry UI, then click **\"Copy JSON\"** and save it to a `.token` file:\n\n```bash\n# Create .token file with the copied JSON from the registry UI\ncat > .token << 'EOF'\n\nEOF\n\n# Register an MCP server from a JSON config file\nuv run python api/registry_management.py \\\n --registry-url https://your-registry-url \\\n --token-file .token \\\n register --config my-server-card.json\n\n# Register an A2A agent from a JSON config file\nuv run python api/registry_management.py \\\n --registry-url https://your-registry-url \\\n --token-file .token \\\n agent-register --config my-agent-card.json\n```\n\nYou can also call the REST API directly. See the [OpenAPI specification](../../api/openapi.json) for the full API reference, available at `/openapi.json` on your running registry instance.\n\n### Example JSON files\n\nSee the [cli/examples/](../../cli/examples/) directory for complete registration examples:\n\n**MCP Servers:**\n- `currenttime.json` -- minimal server example\n- `cloudflare-docs-server-config.json` -- server with full configuration\n- `complete-server-example.json` -- all available fields documented\n\n**A2A Agents:**\n- `flight_booking_agent_card.json` -- agent with multiple skills\n- `code_reviewer_agent.json` -- agent with JWT auth and verified trust level\n- `complete-agent-example.json` -- all available fields documented\n\n## Related Documentation\n\n- [Quick Start Guide](../quickstart.md) -- getting the registry running\n- [Service Management](../service-management.md) -- managing servers, agents, users, and groups\n- [API Reference](../api-reference.md) -- REST API endpoints\n- [AI Coding Assistants Setup](../ai-coding-assistants-setup.md) -- connecting AI tools to registered servers\n" }, { "path": "docs/faq/discovering-mcp-tools.md", "content": "# How do I discover available MCP tools for my AI agent?\n\nYou can discover tools in several ways:\n\n1. **Dynamic Tool Discovery** (Recommended): Use the [`intelligent_tool_finder`](../dynamic-tool-discovery.md) tool with natural language queries:\n ```python\n tools = await intelligent_tool_finder(\n natural_language_query=\"get current time in different timezones\",\n session_cookie=\"your_session_cookie\"\n )\n ```\n\n2. **Web Interface**: Browse available tools at `https://your-gateway-url` after authentication.\n\n3. **Direct MCP Connection**: Connect to the registry MCP server at `/mcpgw/sse` and use standard MCP `tools/list` calls.\n\n## Related Documentation\n\n- [Dynamic Tool Discovery](../dynamic-tool-discovery.md) -- full guide on autonomous tool discovery\n- [API Reference](../api-reference.md) -- search and listing endpoints\n" }, { "path": "docs/faq/filtering-agents-by-tags-and-fields.md", "content": "# What filtering options are available for agents in the registry?\n\nThe registry provides several API endpoints for discovering and filtering agents, each with different filtering capabilities.\n\n## Agent List Endpoint\n\n`GET /api/agents`\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `query` | string (optional) | Substring search across agent name, description, tags, and skill names (case-insensitive) |\n| `visibility` | string (optional) | Exact match filter: `public`, `private`, or `group-restricted` |\n| `enabled_only` | boolean (optional) | When `true`, returns only enabled agents |\n\nExample:\n```bash\n# List agents matching \"internal\" in name, description, or tags\ncurl \"https://your-registry/api/agents?query=internal\" \\\n -H \"Authorization: Bearer $TOKEN\"\n\n# List only public, enabled agents\ncurl \"https://your-registry/api/agents?visibility=public&enabled_only=true\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Semantic Search Endpoint\n\n`POST /api/search/semantic`\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `query` | string (required, can be empty) | Natural language semantic + lexical search (max 512 chars) |\n| `entity_types` | list (optional) | Filter by type: `a2a_agent`, `mcp_server`, `tool`, `skill`, `virtual_server` |\n| `tags` | list (optional) | Exact tag filter with AND logic -- all specified tags must be present (case-insensitive) |\n| `max_results` | integer (optional) | Limit per entity type, 1-50 (default: 10) |\n\nTags can also be specified as `#hashtags` inside the query string. They are extracted and merged with the explicit `tags` list.\n\nExample:\n```bash\n# Search for agents tagged \"internal\"\ncurl -X POST \"https://your-registry/api/search/semantic\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"\",\n \"entity_types\": [\"a2a_agent\"],\n \"tags\": [\"internal\"]\n }'\n\n# Hashtag syntax works too -- these are equivalent\ncurl -X POST \"https://your-registry/api/search/semantic\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"#internal\",\n \"entity_types\": [\"a2a_agent\"]\n }'\n\n# Combine semantic search with tag filtering\ncurl -X POST \"https://your-registry/api/search/semantic\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"quiz generation\",\n \"entity_types\": [\"a2a_agent\"],\n \"tags\": [\"internal\", \"hr\"]\n }'\n```\n\n## Discover Agents by Skills\n\n`POST /api/agents/discover`\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `skills` | list (required) | Skill names or IDs to match (partial matching -- returns agents with at least one match) |\n| `tags` | list (optional) | Tag filter (case-insensitive) |\n| `max_results` | integer (optional) | Limit, 1-100 (default: 10) |\n\nResults are ranked by a weighted score: 60% skill match, 20% tag match, 20% trust level boost.\n\n## Semantic Agent Discovery\n\n`POST /api/agents/discover/semantic`\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `query` | string (required) | Natural language query describing needed capabilities |\n| `max_results` | integer (optional) | Limit, 1-100 (default: 10) |\n\n## Using Tags for Classification\n\nSince the registry does not have a dedicated \"agent type\" or \"classification\" field, tags are the recommended way to categorize agents for filtering. For example:\n\n- Tag internal agents with `internal` and vendor agents with `vendor`\n- Filter via the semantic search endpoint: `\"tags\": [\"internal\"]`\n- Filter via the agent list endpoint: `?query=internal` (searches tags among other fields)\n\nThe semantic search `tags` parameter provides the most precise filtering because it performs exact tag matching (all specified tags must be present). The agent list `query` parameter is a broader substring search that also matches against name, description, and skill names.\n\n## Fields Not Available as Direct Filters\n\nThe following agent fields exist but are not exposed as filter parameters on any endpoint today:\n\n- `trust_level` (used for ranking in discover endpoint, but not as a filter)\n- `status` (lifecycle: active, deprecated, draft, beta)\n- `supported_protocol` (a2a, other)\n- `provider` / `provider_organization`\n- `registered_by`\n- `health_status`\n- `metadata` keys (searchable in full-text, but no field-level filter)\n\nIf you need filtering by any of these fields, please open a feature request on [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues).\n\n## Related Documentation\n\n- [API Reference](../api-reference.md) -- full API documentation\n- [A2A Agent Management](../a2a-agent-management.md) -- agent registration and management guide\n- [Custom Metadata](../custom-metadata.md) -- using metadata fields for organization and compliance\n" }, { "path": "docs/faq/group-restricted-agent-visibility.md", "content": "# How do I restrict which agents a user can see based on their group?\n\nThe registry has two layers of access control for agents. Understanding when each layer applies helps you choose the right approach.\n\n## Quick Answer\n\n**\"I want only specific groups to see my agent.\"**\n\nSet `visibility: \"group-restricted\"` and `allowedGroups` when registering the agent:\n\n```bash\ncurl -s -X POST \"https://your-registry/api/agents/register\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Salary Calculator\",\n \"path\": \"/salary-calculator\",\n \"version\": \"1.0.0\",\n \"url\": \"https://example.com/salary-calculator\",\n \"supportedProtocol\": \"a2a\",\n \"description\": \"Calculate salary projections\",\n \"visibility\": \"group-restricted\",\n \"allowedGroups\": [\"hr-team\", \"finance-team\"],\n \"skills\": [\n {\n \"id\": \"calculate-salary\",\n \"name\": \"Calculate Salary\",\n \"description\": \"Calculate salary projections\",\n \"tags\": [\"hr\", \"finance\"],\n \"inputSchema\": {}\n }\n ]\n }'\n```\n\nOnly users whose IdP groups include `hr-team` or `finance-team` will see this agent. Admin users always see all agents.\n\n## When Does This Actually Matter?\n\nThere are two layers of access control, and `allowed_groups` only adds value depending on how your IAM group scopes are configured:\n\n| Your group scope config | Does allowed_groups help? | Why |\n|------------------------|--------------------------|-----|\n| **Narrow** (e.g., `\"list_agents\": [\"/flight-booking\"]`) | No | IAM already controls per-agent access |\n| **Broad** (e.g., `\"list_agents\": [\"all\"]`) | Yes | Publisher can restrict who sees their agent without an admin |\n| **Mix of narrow and broad** | Yes, for agents that broad groups should not all see | Narrows access for broad groups |\n\nFor a full explanation with examples, see [Agent Visibility and Group-Based Access Control](../agent-visibility-and-group-access.md).\n\n## How to Set Up Group-Restricted Access\n\n### Step 1: Make Sure Your Group Has IAM Access\n\nYour group scope config must include agent access. If it uses `\"list_agents\": [\"all\"]`, you're set. If it lists specific agents, the agent must be in that list.\n\n### Step 2: Register the Agent as Group-Restricted\n\n**Via API:**\n\n```bash\ncurl -s -X POST \"https://your-registry/api/agents/register\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Internal Finance Agent\",\n \"path\": \"/finance-agent\",\n \"version\": \"1.0.0\",\n \"url\": \"https://finance-agent.internal.example.com\",\n \"supportedProtocol\": \"a2a\",\n \"description\": \"Agent for internal finance operations\",\n \"visibility\": \"group-restricted\",\n \"allowedGroups\": [\"finance-team\", \"finance-admins\"],\n \"skills\": [\n {\n \"id\": \"run-report\",\n \"name\": \"Run Report\",\n \"description\": \"Run financial reports\",\n \"tags\": [\"finance\"],\n \"inputSchema\": {}\n }\n ]\n }'\n```\n\n**Via the Web UI:**\n\nThe agent registration and edit forms include a Visibility dropdown with the \"Group Restricted\" option. When selected, an input field appears for specifying the allowed groups.\n\n### Step 3: Update an Existing Agent\n\n```bash\ncurl -s -X PUT \"https://your-registry/api/agents/finance-agent\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Internal Finance Agent\",\n \"path\": \"/finance-agent\",\n \"version\": \"1.0.0\",\n \"url\": \"https://finance-agent.internal.example.com\",\n \"supportedProtocol\": \"a2a\",\n \"description\": \"Agent for internal finance operations\",\n \"visibility\": \"group-restricted\",\n \"allowedGroups\": [\"finance-team\", \"finance-admins\", \"executive-team\"],\n \"skills\": [\n {\n \"id\": \"run-report\",\n \"name\": \"Run Report\",\n \"description\": \"Run financial reports\",\n \"tags\": [\"finance\"],\n \"inputSchema\": {}\n }\n ]\n }'\n```\n\n## Filtering Agents by Visibility or Group\n\n```bash\n# List only group-restricted agents\ncurl -s \"https://your-registry/api/agents?visibility=group-restricted\" \\\n -H \"Authorization: Bearer $TOKEN\"\n\n# List only agents shared with hr-team\ncurl -s \"https://your-registry/api/agents?allowed_groups=hr-team\" \\\n -H \"Authorization: Bearer $TOKEN\"\n\n# List agents shared with either hr-team or finance-team\ncurl -s \"https://your-registry/api/agents?allowed_groups=hr-team,finance-team\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nThe filter still respects the caller's group membership. A non-admin user filtering by `allowed_groups=hr-team` will only see agents they have both IAM access to and group membership for.\n\n## Visibility Options\n\n| Value | Behavior |\n|-------|----------|\n| `public` | Visible to all users with IAM access (default) |\n| `group-restricted` | Visible only to users with IAM access whose groups overlap with `allowed_groups`. Admins always see all agents. |\n| `private` | Visible only to the agent owner and admin users |\n| `unlisted` | Visible only to users with the direct URL |\n\n## How Group Matching Works\n\nWhen a user calls `GET /api/agents`, two checks run in sequence:\n\n1. **IAM scope check**: The user's group scope config determines their `accessible_agents` list. Agents not in this list are filtered out.\n2. **allowed_groups check** (only for `group-restricted` agents): The user's IdP groups (from their JWT token) must intersect with the agent's `allowed_groups`. If not, the agent is filtered out.\n\nAdmin users bypass both checks and see all agents.\n\n## IdP Independence\n\nThe `allowed_groups` field works with any IdP (Keycloak, Entra ID, Cognito, Okta, Auth0) because matching is done against the groups present in the user's JWT token claims. The registry does not call any IdP API to verify group membership.\n\nFor Entra ID, the group value is typically the Group Object ID or the group display name, depending on your claims configuration.\n\n## Related Documentation\n\n- [Agent Visibility and Group-Based Access Control](../agent-visibility-and-group-access.md) -- full explanation of the two-layer model with examples\n- [Filtering Agents by Tags and Fields](filtering-agents-by-tags-and-fields.md) -- all agent filtering options\n- [Restrict Server Visibility by Entra Group](restrict-server-visibility-by-entra-group.md) -- similar setup for MCP servers\n- [Registering M2M Clients without IdP Admin Token](registering-m2m-client-without-idp-admin-token.md) -- register M2M client-id-to-group mappings locally\n" }, { "path": "docs/faq/index.md", "content": "# Frequently Asked Questions\n\nCommon questions and answers about the MCP Gateway Registry.\n\n## Getting Started\n\n- [What is MCP and why do I need a gateway?](what-is-mcp-and-gateway.md)\n- [How do I deploy and register MCP servers and agents?](deploying-and-registering-servers-agents.md)\n\n## Tool and Agent Discovery\n\n- [How do I discover available MCP tools for my AI agent?](discovering-mcp-tools.md)\n- [How do I handle tool discovery when I don't know what tools are available?](agent-autonomous-tool-discovery.md)\n- [What filtering options are available for agents in the registry?](filtering-agents-by-tags-and-fields.md)\n\n## Connecting and Integration\n\n- [How do I connect my agent to multiple MCP servers through the gateway?](connecting-multiple-mcp-servers.md)\n- [How do I test my agent's integration with the MCP Gateway locally?](local-testing-agent-integration.md)\n\n## Operations and Monitoring\n\n- [How do I monitor the health of MCP servers?](monitoring-server-health.md)\n\n## Access Control and Visibility\n\n- [How do I restrict which agents a user can see based on their group?](group-restricted-agent-visibility.md)\n- [How do I restrict which MCP servers a user can see based on their Entra ID group?](restrict-server-visibility-by-entra-group.md)\n\n## Authentication and API Access\n\n- [How do I register and manage MCP servers that require authentication?](registering-auth-protected-servers.md)\n- [Can I use an Entra ID token to call the registry API instead of the UI-generated token?](use-entra-token-for-registry-api.md)\n- [How do I register an M2M client and assign it groups without an IdP Admin API token?](registering-m2m-client-without-idp-admin-token.md)\n- [Registry API Authentication FAQ (static token, IdP JWT, coexistence)](registry-api-auth-faq.md)\n" }, { "path": "docs/faq/local-testing-agent-integration.md", "content": "# How do I test my agent's integration with the MCP Gateway locally?\n\nFollow these steps:\n\n1. **Set up local environment**:\n ```bash\n git clone https://github.com/agentic-community/mcp-gateway-registry.git\n cd mcp-gateway-registry\n cp .env.template .env\n # Configure your .env file\n ./build_and_run.sh\n ```\n\n2. **Test authentication**:\n ```bash\n # For user identity mode\n cd agents/\n python cli_user_auth.py\n python agent.py --use-session-cookie --message \"test message\"\n \n # For agent identity mode\n python agent.py --message \"test message\"\n ```\n\n3. **Access the web interface** at `http://localhost` to verify server registration and tool availability.\n\n## Related Documentation\n\n- [Quick Start Guide](../quickstart.md) -- getting started with the registry\n- [Installation Guide](../installation.md) -- detailed deployment instructions\n- [Authentication](../auth.md) -- authentication modes and configuration\n" }, { "path": "docs/faq/monitoring-server-health.md", "content": "# How do I monitor the health of MCP servers?\n\nThe registry provides built-in health monitoring:\n\n1. **Web Interface**: View server status at `https://your-gateway`\n - Green: Healthy servers\n - Red: Servers with issues\n - Gray: Disabled servers\n\n2. **Manual Health Checks**: Click the refresh icon on any server card in the dashboard\n\n3. **Logs**: Monitor service logs:\n ```bash\n # View all service logs\n docker compose logs -f\n \n # View specific service logs\n docker compose logs -f registry\n docker compose logs -f auth-server\n ```\n\n4. **API Endpoint**: Programmatic health checks via `/health` endpoints\n\n## Related Documentation\n\n- [Service Management](../service-management.md) -- managing MCP server lifecycle\n- [Observability](../OBSERVABILITY.md) -- monitoring and telemetry\n" }, { "path": "docs/faq/registering-auth-protected-servers.md", "content": "# How do I register and manage MCP servers that require authentication?\n\nThe MCP Gateway Registry fully supports registering MCP servers that are behind access control (Bearer token or API key). When a server requires authentication, the registry stores the credential securely (encrypted at rest) and automatically injects it when performing health checks, tool discovery, and proxying requests.\n\n## Registering a Server with Authentication\n\nUse the `POST /api/servers/register` endpoint with JWT Bearer authentication. Include the `auth_scheme` and `auth_credential` fields to specify how the registry should authenticate with your backend MCP server.\n\n### Bearer Token Authentication\n\n```bash\ncurl -X POST https://registry.example.com/api/servers/register \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -F \"name=My Protected Server\" \\\n -F \"description=An MCP server behind Bearer auth\" \\\n -F \"path=/my-protected-server\" \\\n -F \"proxy_pass_url=http://my-server:8000\" \\\n -F \"auth_scheme=bearer\" \\\n -F \"auth_credential=my-backend-server-token\"\n```\n\n### API Key Authentication\n\n```bash\ncurl -X POST https://registry.example.com/api/servers/register \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -F \"name=My API Key Server\" \\\n -F \"description=An MCP server behind API key auth\" \\\n -F \"path=/my-apikey-server\" \\\n -F \"proxy_pass_url=http://my-server:8000\" \\\n -F \"auth_scheme=api_key\" \\\n -F \"auth_credential=my-api-key-value\" \\\n -F \"auth_header_name=X-API-Key\"\n```\n\n### Supported `auth_scheme` Values\n\n| Value | Behavior |\n|-------|----------|\n| `none` | No authentication (default) |\n| `bearer` | Sends `Authorization: Bearer ` header |\n| `api_key` | Sends credential in a custom header (default: `X-API-Key`) |\n\n### Custom Header Name\n\nWhen using `api_key`, you can specify a custom header name via `auth_header_name`. For example, if your server expects `X-My-Custom-Key`, pass `auth_header_name=X-My-Custom-Key`.\n\n## How Tool Discovery Works with Auth\n\nOnce registered with credentials, the registry automatically:\n\n1. **Health checks** -- Injects the decrypted credential when checking if the server is reachable\n2. **Tool discovery** -- Uses the credential to call the MCP `tools/list` method on the backend server\n3. **Request proxying** -- When clients connect through the gateway, the credential is injected into proxied requests\n\nThis means tool discovery works the same way for protected servers as it does for public ones -- no additional configuration is needed beyond providing the credential at registration time.\n\n## Manually Providing Tools\n\nIf your server is behind a firewall or tool auto-discovery is not possible, you can provide tools manually at registration time using the `tool_list_json` parameter:\n\n```bash\ncurl -X POST https://registry.example.com/api/servers/register \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -F \"name=My Server\" \\\n -F \"description=Server with manually defined tools\" \\\n -F \"path=/my-server\" \\\n -F \"proxy_pass_url=http://my-server:8000\" \\\n -F 'tool_list_json=[{\"name\": \"get_weather\", \"description\": \"Get weather for a city\", \"inputSchema\": {\"type\": \"object\", \"properties\": {\"city\": {\"type\": \"string\"}}, \"required\": [\"city\"]}}]'\n```\n\nThe `tool_list_json` field accepts a JSON array of MCP tool definitions. These will be stored in the registry and returned to clients during tool discovery, even if the backend server is unreachable for live tool listing.\n\n## Updating or Rotating Credentials\n\nUse the `PATCH /api/servers/{path}/auth-credential` endpoint to update credentials without re-registering the server:\n\n```bash\n# Rotate a Bearer token\ncurl -X PATCH https://registry.example.com/api/servers/my-protected-server/auth-credential \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"auth_scheme\": \"bearer\",\n \"auth_credential\": \"new-backend-server-token\"\n }'\n```\n\n```bash\n# Switch from Bearer to API key\ncurl -X PATCH https://registry.example.com/api/servers/my-protected-server/auth-credential \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"auth_scheme\": \"api_key\",\n \"auth_credential\": \"new-api-key\",\n \"auth_header_name\": \"X-API-Key\"\n }'\n```\n\n```bash\n# Remove authentication (make server public)\ncurl -X PATCH https://registry.example.com/api/servers/my-protected-server/auth-credential \\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"auth_scheme\": \"none\"\n }'\n```\n\n## Credential Security\n\n- Credentials are **encrypted at rest** using the `SECRET_KEY` configured in your deployment\n- Credentials are **never returned** in API responses or displayed in the UI\n- Credentials are **decrypted only in memory** when needed for health checks, tool discovery, or request proxying\n\n## Getting a JWT Token\n\nTo authenticate with the registry API, you need a JWT token. Click the **Get JWT Token** button in the top-left corner of the registry UI, or use the token generation API:\n\n```bash\ncurl -X POST https://registry.example.com/api/tokens/generate \\\n -H \"Cookie: session=\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"expires_in_hours\": 8,\n \"description\": \"Server registration token\"\n }'\n```\n\n## Troubleshooting\n\n### Tools not discovered for a protected server\n\n1. Verify the credential is correct by testing it directly against your MCP server\n2. Check the server health status in the registry UI -- if unhealthy, the credential may be invalid or expired\n3. Use the credential update endpoint to provide a fresh credential\n4. As a fallback, provide tools manually via `tool_list_json` at registration time\n\n### \"Failed to fetch tools\" error\n\nThis typically means:\n- The backend server is unreachable from the registry\n- The credential is invalid or expired\n- The server does not implement the standard MCP `tools/list` method\n\nCheck the registry logs for detailed error messages about the connection failure.\n" }, { "path": "docs/faq/registering-m2m-client-without-idp-admin-token.md", "content": "# How do I register an M2M client and assign it groups without an IdP Admin API token?\n\n**Short answer**: use the direct M2M client registration API at `/api/iam/m2m-clients`. Create the M2M client in your IdP (Keycloak, Okta, Entra, Auth0) as you normally would, then register its `client_id` with the registry and assign groups. The registry writes directly to its own `idp_m2m_clients` collection -- no `OKTA_API_TOKEN` or equivalent IdP Admin API credentials required.\n\n## When to use this\n\n- Your enterprise gates IdP Admin API tokens (e.g. Okta requires approval for Admin API access) and getting one is disproportionate overhead.\n- You already know the M2M `client_id` you want to register (it lives in the IdP).\n- You want to assign groups so the registry's auth server can enrich M2M tokens with those groups during authorization.\n\nIf `OKTA_API_TOKEN` / `AUTH0_M2M_CLIENT_ID` etc. are available, the existing `/api/iam/okta/m2m/*` or `/api/iam/auth0/m2m/*` sync endpoints cover the same ground. This FAQ is for the case where those credentials are not available.\n\n## Prerequisites\n\n- A user JWT (or static API token) with **admin** scope on the registry.\n- The `client_id` of an M2M client you have already created in your IdP.\n- `M2M_DIRECT_REGISTRATION_ENABLED=true` on the registry (this is the default).\n\n## Step 1: Create the M2M client in your IdP\n\nIn Keycloak Admin UI (example; equivalent steps apply in Okta/Entra/Auth0):\n\n1. Navigate to **Clients > Create client**.\n2. Client type: **OpenID Connect**. Client ID: e.g. `my-automation-pipeline`. **Save**.\n3. Enable **Client authentication** and **Service accounts roles**. Disable standard/direct flows. **Save**.\n4. Copy the **Client Secret** from the `Credentials` tab. Your application will use this pair to request tokens from Keycloak.\n\nYou do **not** need to assign groups inside the IdP. The registry resolves groups from its own `idp_m2m_clients` collection, which you will populate in the next step.\n\n## Step 2: Register the client with the registry\n\nUsing the bundled CLI (`api/registry_management.py`):\n\n```bash\nexport REGISTRY_URL=http://localhost\nexport TOKEN_FILE=~/repos/mcp-gateway-registry/.token # admin user token\n\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL --token-file $TOKEN_FILE \\\n m2m-client-create \\\n --client-id my-automation-pipeline \\\n --client-name \"My Automation Pipeline\" \\\n --groups pipeline-operators,registry-readonly \\\n --description \"CI/CD pipeline service account\"\n```\n\nExpected output:\n\n```\nM2M client registered successfully\n\nClient ID: my-automation-pipeline\nName: My Automation Pipeline\nProvider: manual\nEnabled: True\nGroups: pipeline-operators, registry-readonly\nDescription: CI/CD pipeline service account\nCreated by: admin\nCreated at: ...\nUpdated at: ...\n```\n\n`Provider: manual` means the record was created via this API (rather than synced from an IdP). Manual records are the only ones this API can modify or delete later.\n\n## Step 3: Verify from your application\n\n1. Request an M2M access token from Keycloak using client credentials:\n\n ```bash\n curl -X POST \\\n \"http://localhost:8080/realms/mcp-gateway/protocol/openid-connect/token\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=my-automation-pipeline\" \\\n -d \"client_secret=\"\n ```\n\n2. Call the registry with that token. The registry's auth server looks up `client_id=my-automation-pipeline` in `idp_m2m_clients`, enriches the token with groups `[\"pipeline-operators\", \"registry-readonly\"]`, and authorization proceeds based on those groups.\n\n ```bash\n curl -H \"Authorization: Bearer $M2M_TOKEN\" \"$REGISTRY_URL/api/servers\"\n ```\n\n## Managing registered clients\n\nAll commands below use the same `--registry-url`/`--token-file` prefix as above.\n\n**List**:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL --token-file $TOKEN_FILE \\\n m2m-client-list --provider manual\n```\n\nSupports `--limit`, `--skip`, `--json`.\n\n**Get one**:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL --token-file $TOKEN_FILE \\\n m2m-client-get --client-id my-automation-pipeline\n```\n\n**Update** (partial -- fields you omit are left unchanged; pass `--groups \"\"` to clear groups):\n\n```bash\n# Change groups only\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL --token-file $TOKEN_FILE \\\n m2m-client-update \\\n --client-id my-automation-pipeline \\\n --groups registry-readonly\n\n# Disable the client (kill switch)\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL --token-file $TOKEN_FILE \\\n m2m-client-update \\\n --client-id my-automation-pipeline \\\n --enabled false\n```\n\n**Delete**:\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url $REGISTRY_URL --token-file $TOKEN_FILE \\\n m2m-client-delete --client-id my-automation-pipeline --force\n```\n\n## HTTP endpoints (for reference)\n\n| Method | Path | Auth |\n|--------|------|------|\n| POST | `/api/iam/m2m-clients` | admin |\n| GET | `/api/iam/m2m-clients` | any authenticated user (paginated) |\n| GET | `/api/iam/m2m-clients/{client_id}` | any authenticated user |\n| PATCH | `/api/iam/m2m-clients/{client_id}` | admin |\n| DELETE | `/api/iam/m2m-clients/{client_id}` | admin |\n\n## Things to know\n\n- **Ownership guard**: records created by this API have `provider: \"manual\"`. Records written by the existing Okta/Auth0 sync services (`provider: \"okta\"`, `provider: \"auth0\"`) are visible via `GET` but return `HTTP 403` on `PATCH` or `DELETE` from this API, to prevent conflicts with IdP sync.\n- **Duplicate `client_id`**: returns `HTTP 409 Conflict`. One `client_id` can only have one record across all providers.\n- **Admins grant privilege directly**: any admin calling this API can assign any group to any `client_id`. The audit log records every mutation with the calling admin's identity for accountability. Treat the registry admin role accordingly.\n- **Feature flag**: `M2M_DIRECT_REGISTRATION_ENABLED` (default `true`) disables the whole router if set to `false`. Surface the flag on the System Config page under **Authentication**.\n\n## Related FAQs\n\n- [How do I restrict which MCP servers a user can see based on their Entra ID group?](restrict-server-visibility-by-entra-group.md)\n- [Can I use an Entra ID token to call the registry API instead of the UI-generated token?](use-entra-token-for-registry-api.md)\n- [How do I register and manage MCP servers that require authentication?](registering-auth-protected-servers.md)\n" }, { "path": "docs/faq/registry-api-auth-faq.md", "content": "# Registry API Authentication FAQ\n\nCommon questions about authenticating against the Registry API (`/api/*`, `/v0.1/*`). For the full authentication model, see [Registry API Authentication](../registry-api-auth.md).\n\n## Can I use an IdP token and the static token on the same deployment?\n\nYes, as of [#871](https://github.com/agentic-community/mcp-gateway-registry/issues/871). When `REGISTRY_STATIC_TOKEN_AUTH_ENABLED=true`, the static token is accepted as an **additional** credential, not an exclusive gate. Valid Okta / Entra / Cognito / Keycloak JWTs, UI-issued self-signed JWTs, and session cookies all continue to work on `/api/*`. A bearer that doesn't match the static token falls through to the JWT validation pipeline.\n\nBefore #871, turning on static-token mode silently broke every non-static-token caller on `/api/*` with a 401/403 before JWT validation ran.\n\n## Do I need to seed MongoDB with `mcp-servers-unrestricted/*` scope docs for the static token to work?\n\n**After #779:** Yes, the standard scope-resolution path is used for all static-token keys (including the legacy `REGISTRY_API_TOKEN`). The auth server resolves each key's groups to scopes via `group_mappings` in MongoDB. If the group-to-scope mappings are missing, the key will authenticate but carry an empty scope set, which means the registry will treat it as a non-admin caller.\n\n**Before #779:** No. The registry hard-coded full admin access when the auth server set `X-Auth-Method == \"network-trusted\"`. Scopes returned in the `/validate` response were informational only.\n\n## Can I give a static token read-only access?\n\nYes, since [#779](https://github.com/agentic-community/mcp-gateway-registry/issues/779). Define a key in `REGISTRY_API_KEYS` whose `groups` list maps to read-only scopes (e.g., `mcp-servers-unrestricted/read`). The key will authenticate successfully but will not carry mutating scopes, so the registry treats it as a non-admin caller.\n\n```json\n{\"ci-readonly\": {\"key\": \"\", \"groups\": [\"mcp-readonly\"]}}\n```\n\nMake sure the group `mcp-readonly` is mapped to the desired read-only scopes in your `group_mappings` collection.\n\n## Why does the static token not work on `//tools/list`?\n\nBy design. The static token is only accepted on Registry API paths (`/api/*`, `/v0.1/*`). **MCP gateway tool invocations always require full IdP authentication** regardless of static-token settings. This is a deliberate boundary, not a bug: the static token grants admin-level access on registry metadata endpoints, but tool invocations — which can have real-world side effects — stay gated behind per-user identity and scopes from the IdP.\n\nA curl with `-H \"Authorization: Bearer $REGISTRY_API_TOKEN\"` against an MCP gateway path will currently return a 500 wrapping the JWT validation failure. That's a pre-existing error-code bug (separate from #871), not a sign the call should have succeeded.\n\n## What status code does a fully invalid bearer get?\n\nSince [#871](https://github.com/agentic-community/mcp-gateway-registry/issues/871): **401** from the JWT block (detail: `\"Missing or invalid Authorization header. Expected: Bearer or valid session cookie\"`).\n\nBefore #871: **403** from the static-token block (detail: `\"Invalid API token\"`).\n\nNo caller with a valid credential is affected by this change. The status-code shift only applies to bearers that were going to be rejected anyway.\n\n## Is my UI-issued JWT usable against `/api/*`?\n\nYes, since #871. Before the fix, the **Get JWT Token** sidebar in the UI produced valid HS256 JWTs that were nonetheless rejected on `/api/*` when static-token mode was on. After #871 they flow through the same `_validate_self_signed_token` path as any other UI-issued token, regardless of whether static-token mode is on.\n\n## How do I rotate a static token without downtime?\n\n**With `REGISTRY_API_KEYS` (recommended):** Zero-downtime rotation is straightforward:\n\n1. Add a new key entry to the JSON array (the old key stays).\n2. Deploy the updated config. Both keys are now valid.\n3. Migrate clients to the new key at your own pace.\n4. Remove the old key entry and redeploy.\n\n**With legacy `REGISTRY_API_TOKEN` only:** There is still a cutover window during which old clients are rejected while new clients have yet to pick up the new value. Mitigations:\n\n- Roll out the new token value to clients first, then flip the server value.\n- Or accept a brief 401/403 window and notify callers.\n- Or migrate to `REGISTRY_API_KEYS` for zero-downtime rotation.\n\n## Where do I see the current values in the UI?\n\nThe **Settings → Authentication** page shows:\n\n| Field | Label | Behavior |\n|---|---|---|\n| `registry_static_token_auth_enabled` | Static Token Auth Enabled | Displayed as `true` / `false` |\n| `registry_api_token` | Registry API Token | Masked |\n| `registry_api_keys` | Registry API Keys | Masked |\n| `m2m_direct_registration_enabled` | M2M Direct Registration Enabled | Displayed as `true` / `false` (from [#851](https://github.com/agentic-community/mcp-gateway-registry/issues/851)) |\n\nThe field registry is defined in [registry/api/config_routes.py](../../registry/api/config_routes.py).\n\n## What's the roadmap?\n\nThree improvements, landing in order on top of each other:\n\n1. **[#871](https://github.com/agentic-community/mcp-gateway-registry/issues/871) — coexistence** (shipped): static token and JWT auth work together on `/api/*`.\n2. **[#779](https://github.com/agentic-community/mcp-gateway-registry/issues/779) — multi-key static tokens** (shipped): replaces the single `REGISTRY_API_TOKEN` with a `REGISTRY_API_KEYS` JSON object, each key carrying its own groups. Lets operators give scripts the minimum privilege they need. Zero-downtime rotation is built in.\n3. **[#826](https://github.com/agentic-community/mcp-gateway-registry/issues/826) — external user access tokens**: lets a frontend application that has its own IdP integration call the Registry API on behalf of a logged-in user, either via `/userinfo` group enrichment (Solution A) or a new token-exchange endpoint (Solution B).\n\nSee the [full design in Registry API Authentication](../registry-api-auth.md#roadmap-near-term-improvements).\n\n## Related FAQs\n\n- [How do I register an M2M client and assign it groups without an IdP Admin API token?](registering-m2m-client-without-idp-admin-token.md)\n- [Can I use an Entra ID token to call the registry API instead of the UI-generated token?](use-entra-token-for-registry-api.md)\n- [How do I register and manage MCP servers that require authentication?](registering-auth-protected-servers.md)\n" }, { "path": "docs/faq/restrict-server-visibility-by-entra-group.md", "content": "# How do I restrict which MCP servers a user can see based on their Entra ID group?\n\nThe registry has a built-in IAM system that lets you control which servers/tools each group can access. You create the group in Entra ID first, then map it in the registry with the servers that group should have access to.\n\n## Option A: Via the Web UI\n\n1. **Create the group in Entra ID first** (Azure Portal > Groups)\n2. In the registry UI, go to **Settings > IAM > Groups**\n3. Click **Create Group**\n4. **Uncheck \"Create group in IdP\"** -- since the group already exists in Entra ID\n5. Enter the group name (must match the Entra ID group name or Object ID depending on your claims configuration)\n6. Under **Server Access**, select which MCP servers, methods, and tools this group should have access to\n7. Under **UI Permissions**, configure what actions group members can perform in the dashboard\n8. Save the group\n\n## Option B: Via CLI (registry_management.py)\n\nYou can import a group definition from a JSON file with the `import-group` command:\n\n```bash\npython api/registry_management.py \\\n --registry-url https://your-registry-url \\\n --token-file .token \\\n import-group \\\n --file my-group.json\n```\n\nExample JSON file (`my-group.json`) -- adapted from [`cli/examples/public-mcp-users.json`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/cli/examples/public-mcp-users.json):\n```json\n{\n \"scope_name\": \"restricted-mcp-users\",\n \"description\": \"Users with access to specific MCP servers only\",\n \"create_in_idp\": false,\n \"group_mappings\": [\"restricted-mcp-users\", \"your-entra-group-object-id-guid\"],\n \"server_access\": [\n {\n \"server\": \"your-server-1\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"/your-server-1\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"initialize\", \"GET\", \"POST\", \"servers\", \"agents\", \"search\"],\n \"tools\": []\n }\n ],\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [],\n \"get_agent\": []\n }\n}\n```\n\nSet `\"create_in_idp\": false` since the group already exists in Entra ID. The `group_mappings` array should include both the group name and the Entra ID Group Object ID (GUID).\n\nExample scope JSON files are also available in [`scripts/registry-admins.json`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/scripts/registry-admins.json) and [`cli/examples/public-mcp-users.json`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/cli/examples/public-mcp-users.json).\n\n## Related Documentation\n\n- [IAM Settings UI Guide](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/iam-settings-ui.md) -- full walkthrough of the Groups UI with server access, tools, and permissions configuration\n- [Entra ID Setup Guide](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/entra-id-setup.md) -- Steps 5-10 cover configuring group claims in Azure and mapping Entra ID Group Object IDs to registry scopes\n- [Scopes Management](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/scopes-mgmt.md) -- detailed field reference for scope/group JSON configuration\n- [Entra ID Setup - IAM API for Groups](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/entra-id-setup.md#using-the-iam-api-to-manage-groups-users-and-m2m-accounts) -- covers `import-group`, `group-create`, `group-delete` commands with full JSON examples\n" }, { "path": "docs/faq/use-entra-token-for-registry-api.md", "content": "# Can I use an Entra ID token to call the registry API instead of the UI-generated token?\n\nYes -- you can use Entra ID-based tokens directly for API authorization instead of the tokens from the registry UI. The recommended approach is to create an M2M (Machine-to-Machine) identity in Entra ID and assign it to a registry group to control its access.\n\n## Setup Steps\n\n1. **Register an App Registration** in Entra ID with client credentials (client ID + client secret)\n2. In the registry UI, go to **Settings > IAM > M2M Accounts** and create an M2M account linked to this Entra ID app\n3. **Assign the M2M account to a group** -- this restricts its access to only the servers/tools that group allows (see [How do I restrict server visibility by Entra group?](restrict-server-visibility-by-entra-group.md))\n4. **Request tokens** directly from Entra ID using the standard OAuth2 client credentials flow:\n\n```bash\ncurl -X POST \"https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id={M2M_CLIENT_ID}\" \\\n -d \"client_secret={M2M_CLIENT_SECRET}\" \\\n -d \"scope=api://{APP_CLIENT_ID}/.default\" \\\n -d \"grant_type=client_credentials\"\n```\n\nWhere:\n- `{TENANT_ID}` is your Azure AD Tenant ID\n- `{M2M_CLIENT_ID}` is the M2M service account Client ID\n- `{M2M_CLIENT_SECRET}` is the M2M service account Client Secret\n- `{APP_CLIENT_ID}` is the Application (client) ID of your MCP Gateway app registration in Entra ID\n- `.default` requests all scopes that admin consent has been granted for\n\n5. **Use the resulting token** in API calls:\n\n```bash\ncurl -H \"Authorization: Bearer {ACCESS_TOKEN}\" \\\n https://your-registry-url/api/servers\n```\n\n## How Token Validation Works\n\nThe registry validates Entra ID tokens (RS256) by:\n1. Fetching the JWKS from your Entra ID tenant\n2. Verifying the token signature, issuer, and audience claims\n3. Extracting group claims from the token\n4. Mapping group claims to registry scopes\n\nThe M2M identity will only see the servers and tools that its assigned group allows.\n\n## Related Documentation\n\n- [Entra ID Setup - M2M Token Generation](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/entra-id-setup.md#generating-jwt-tokens-for-m2m-accounts) -- covers direct token requests, credentials provider scripts, and token usage\n- [Authentication Overview](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/auth.md) -- covers all three identity types (Human, Programmatic, M2M) and how group-to-scope mapping works for each\n- [Auth Management](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/auth-mgmt.md) -- M2M account creation and token usage examples\n" }, { "path": "docs/faq/what-is-mcp-and-gateway.md", "content": "# What is the Model Context Protocol (MCP) and why do I need a gateway?\n\n**Model Context Protocol (MCP)** is an open standard that allows AI models to connect with external systems, tools, and data sources.\n\n## Why You Need a Gateway\n\n- **Service Discovery**: Find approved MCP servers in your organization\n- **Centralized Access Control**: Secure, governed access to tools\n- **Dynamic Tool Discovery**: Agents can find new tools autonomously\n- **Simplified Client Configuration**: Single endpoint for multiple servers\n- **Enterprise Security**: Authentication, authorization, and audit logging\n\n**Without Gateway**: Each agent connects directly to individual MCP servers\n**With Gateway**: All agents connect through a single, secure, managed endpoint\n\n## What's the difference between the Registry and the Gateway?\n\nThey are complementary components:\n\n**Registry**:\n- **Purpose**: Service discovery and management\n- **Features**: Web UI, server registration, health monitoring, tool catalog\n- **Users**: Platform administrators, developers\n- **Access**: Web browser at port 80 (HTTP) or 443 (HTTPS) via nginx reverse proxy\n\n**Gateway**:\n- **Purpose**: Secure proxy for MCP protocol traffic\n- **Features**: Authentication, authorization, request routing\n- **Users**: AI agents, MCP clients\n- **Access**: MCP protocol at `/server-name/sse`\n\n**Together**: Registry manages what's available, Gateway controls access to it.\n\n## Related Documentation\n\n- [Quick Start Guide](../quickstart.md) -- getting started\n- [Installation Guide](../installation.md) -- deployment options\n- [Architecture](../design/architectural-decision-reverse-proxy-vs-application-layer-gateway.md) -- architectural design decisions\n" }, { "path": "docs/federation-operational-guide.md", "content": "# Federation Operational Guide\n\nThis guide covers setting up and operating peer-to-peer federation between MCP Gateway Registry instances.\n\n## Demo\n\nhttps://github.com/user-attachments/assets/630ce847-b151-4eaa-9cc9-2ec77797f2b5\n\n## Quick Start\n\n### Prerequisites\n\n- Two or more MCP Gateway Registry instances running\n- Network connectivity between registries (HTTPS)\n- Admin access to both registries\n\n### Step 1: Generate Encryption Key (One-Time)\n\nOn the importing registry, generate a Fernet encryption key for storing peer credentials:\n\n```bash\npython -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"\n```\n\nAdd to your `.env`:\n\n```bash\nFEDERATION_ENCRYPTION_KEY=\n```\n\n### Step 2: Configure the Exporting Registry\n\nOn the registry that will export data, enable federation static token auth:\n\n```bash\n# Generate a static token\npython -c \"import secrets; print(secrets.token_urlsafe(32))\"\n\n# Add to .env\nFEDERATION_STATIC_TOKEN_AUTH_ENABLED=true\nFEDERATION_STATIC_TOKEN=\n```\n\nRestart the registry for changes to take effect.\n\n### Step 3: Add Peer Configuration\n\nOn the importing registry, add the peer using the UI or API:\n\n**Using the UI:**\n\n1. Navigate to Settings (gear icon in header)\n2. Select Federation > Peers\n3. Click \"Add Peer\"\n4. Fill in the peer details:\n - Peer ID: A unique identifier (e.g., \"lob-a\")\n - Name: Human-readable name\n - Endpoint: Base URL of the peer registry\n - Federation Token: The token from Step 2\n - Sync Mode: Select how to filter synced items\n\n**Using the API:**\n\n```bash\ncurl -X POST https://your-registry.com/api/peers \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"peer_id\": \"lob-a\",\n \"name\": \"LOB-A Registry\",\n \"endpoint\": \"https://lob-a-registry.corp.com\",\n \"enabled\": true,\n \"sync_mode\": \"all\",\n \"sync_interval_minutes\": 30,\n \"federation_token\": \"\"\n }'\n```\n\n### Step 4: Set Visibility on Exportable Items\n\nOn the exporting registry, mark servers and agents for federation export:\n\n```bash\n# Mark a server as public (exportable)\ncurl -X PUT https://lob-a-registry.corp.com/api/servers/my-tool \\\n -H \"Authorization: Bearer \" \\\n -d '{\"visibility\": \"public\"}'\n```\n\nOr use the UI to edit server/agent settings and set visibility to \"public\".\n\n### Step 5: Trigger Initial Sync\n\n**Using the UI:**\n\n1. Navigate to Settings > Federation > Peers\n2. Click the sync icon next to the peer\n3. View sync status and results\n\n**Using the API:**\n\n```bash\ncurl -X POST https://your-registry.com/api/peers/lob-a/sync \\\n -H \"Authorization: Bearer \"\n```\n\n## Common Deployment Topologies\n\n### Hub and Spoke\n\nCentral IT maintains a Hub that pulls from all LOB registries.\n\n**Hub Configuration:**\n\n```bash\n# Hub .env\nFEDERATION_ENCRYPTION_KEY=\n```\n\nAdd each LOB as a peer (UI or API).\n\n**LOB Configuration:**\n\n```bash\n# Each LOB .env\nFEDERATION_STATIC_TOKEN_AUTH_ENABLED=true\nFEDERATION_STATIC_TOKEN=\n```\n\nNo peer configuration needed on LOBs (they only export).\n\n### Bidirectional Sync\n\nTwo registries share items with each other.\n\n**Registry A:**\n\n```bash\n# .env\nFEDERATION_ENCRYPTION_KEY=\nFEDERATION_STATIC_TOKEN_AUTH_ENABLED=true\nFEDERATION_STATIC_TOKEN=\n```\n\nAdd Registry B as a peer with its token.\n\n**Registry B:**\n\n```bash\n# .env\nFEDERATION_ENCRYPTION_KEY=\nFEDERATION_STATIC_TOKEN_AUTH_ENABLED=true\nFEDERATION_STATIC_TOKEN=\n```\n\nAdd Registry A as a peer with its token.\n\n### Mesh Topology\n\nMultiple registries in a mesh where each can pull from any other.\n\nEach registry:\n1. Has its own `FEDERATION_STATIC_TOKEN` for others to pull from it\n2. Has `FEDERATION_ENCRYPTION_KEY` to store peer tokens\n3. Configures each other registry as a peer\n\n## Sync Mode Configuration\n\n### Sync All\n\nImport all public servers and agents from the peer:\n\n```json\n{\n \"peer_id\": \"lob-a\",\n \"sync_mode\": \"all\"\n}\n```\n\n### Whitelist Mode\n\nImport only specific servers and agents:\n\n```json\n{\n \"peer_id\": \"lob-a\",\n \"sync_mode\": \"whitelist\",\n \"whitelist_servers\": [\"/production-db\", \"/shared-api\"],\n \"whitelist_agents\": [\"/analytics-agent\"]\n}\n```\n\n### Tag Filter Mode\n\nImport items with specific tags:\n\n```json\n{\n \"peer_id\": \"lob-a\",\n \"sync_mode\": \"tag_filter\",\n \"tag_filters\": [\"production\", \"shared\"]\n}\n```\n\n## Scheduled Sync\n\nConfigure automatic sync at regular intervals:\n\n```json\n{\n \"peer_id\": \"lob-a\",\n \"sync_interval_minutes\": 30\n}\n```\n\nSet to `0` for manual-only sync.\n\n### How Scheduled Sync Works\n\nThe registry runs a background scheduler that:\n\n1. **Checks every 60 seconds** for peers that need syncing\n2. **Evaluates each enabled peer** with `sync_interval_minutes > 0`\n3. **Triggers sync** when the time since `last_successful_sync` exceeds the configured interval\n4. **Skips peers** that are disabled, have sync in progress, or have interval set to 0\n\nThe scheduler starts automatically when the registry starts and stops gracefully on shutdown.\n\n### Viewing Scheduled Sync Activity\n\nCheck the registry logs for scheduled sync activity:\n\n```bash\ndocker-compose logs registry | grep -i \"scheduled sync\"\n```\n\nExample log output:\n```\nScheduled sync triggered for peer 'lob-a' (interval: 30m)\nScheduled sync completed for peer 'lob-a': 15 servers, 3 agents\n```\n\n## Managing Peers\n\n### Enable/Disable a Peer\n\n**UI:** Toggle the enabled switch in the peers list.\n\n**API:**\n\n```bash\n# Enable\ncurl -X POST https://registry.com/api/peers/lob-a/enable \\\n -H \"Authorization: Bearer \"\n\n# Disable\ncurl -X POST https://registry.com/api/peers/lob-a/disable \\\n -H \"Authorization: Bearer \"\n```\n\n### Update Peer Configuration\n\n```bash\ncurl -X PUT https://registry.com/api/peers/lob-a \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sync_mode\": \"tag_filter\",\n \"tag_filters\": [\"production\"]\n }'\n```\n\n### Delete a Peer\n\n```bash\ncurl -X DELETE https://registry.com/api/peers/lob-a \\\n -H \"Authorization: Bearer \"\n```\n\nThis removes the peer configuration. Synced items are marked as orphaned.\n\n### View Sync Status\n\n**UI:** Click on a peer to view detailed status including:\n- Last successful sync\n- Total servers/agents synced\n- Current generation number\n- Health status\n\n**API:**\n\n```bash\ncurl https://registry.com/api/peers/lob-a/status \\\n -H \"Authorization: Bearer \"\n```\n\n## Token Rotation\n\n### Rotating Federation Token (Exporting Registry)\n\n1. Generate a new token:\n ```bash\n python -c \"import secrets; print(secrets.token_urlsafe(32))\"\n ```\n\n2. Update the exporting registry's `.env`:\n ```bash\n FEDERATION_STATIC_TOKEN=\n ```\n\n3. Restart the exporting registry.\n\n4. Update the peer configuration on all importing registries:\n ```bash\n curl -X PUT https://hub-registry.com/api/peers/lob-a \\\n -H \"Authorization: Bearer \" \\\n -d '{\"federation_token\": \"\"}'\n ```\n\n### Rotating Encryption Key (Importing Registry)\n\nIf you need to rotate the `FEDERATION_ENCRYPTION_KEY`:\n\n1. Export current peer configurations (tokens will be encrypted)\n2. Generate new Fernet key\n3. Run migration script to re-encrypt tokens with new key\n4. Update `.env` with new key\n5. Restart registry\n\n## Troubleshooting\n\n### Connection Refused\n\n**Symptom:** Sync fails with connection error.\n\n**Checks:**\n- Verify network connectivity: `curl https://peer-registry.com/api/v1/federation/health`\n- Check firewall rules allow HTTPS traffic\n- Verify endpoint URL is correct in peer config\n\n### Authentication Failed (401/403)\n\n**Symptom:** Sync fails with authentication error.\n\n**Checks:**\n- Verify `FEDERATION_STATIC_TOKEN_AUTH_ENABLED=true` on exporting registry\n- Verify token in peer config matches `FEDERATION_STATIC_TOKEN` on exporting registry\n- Check token was copied correctly (no extra whitespace)\n- Verify `FEDERATION_ENCRYPTION_KEY` is set on importing registry\n\n### No Items Synced\n\n**Symptom:** Sync succeeds but no servers/agents appear.\n\n**Checks:**\n- Verify items have `visibility: \"public\"` on exporting registry\n- Check sync_mode and filters are not too restrictive\n- Verify items exist on the exporting registry\n\n### Sync Reports 0 Items After Successful Authentication\n\n**Symptom:** Sync completes successfully and authentication passes, but 0 servers/agents are returned even though items exist on the peer registry.\n\n**Root Cause:** This can indicate that the federation token was lost or corrupted during a peer configuration update (issue #561, fixed in version XX.XX).\n\n**Diagnostic Steps:**\n\n1. Check if the peer had items synced previously:\n ```bash\n curl https://registry.com/api/peers/peer-id/status\n ```\n If `total_servers_synced` was > 0 before but is now 0, the token may be lost.\n\n2. Verify the peer registry is actually returning data:\n ```bash\n # Direct test to peer registry (replace with actual token)\n curl -H \"Authorization: Bearer \" \\\n https://peer-registry.com/api/v1/federation/servers\n ```\n\n**Resolution:**\n\nIf authentication is working but 0 items are returned, update the federation token using the dedicated endpoint:\n\n```bash\ncurl -X PATCH https://registry.com/api/peers/peer-id/token \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"federation_token\": \"\"\n }'\n```\n\nOr use the UI:\n1. Navigate to Settings > Federation > Peers\n2. Click the peer name\n3. Update the Federation Token field\n4. Save changes\n5. Trigger a manual sync to verify\n\n### Federation Token Lost After Peer Update (Fixed in XX.XX)\n\n**Symptom:** After updating a peer's configuration (name, endpoint, sync interval, etc.), all subsequent syncs fail with authentication errors or return 0 items.\n\n**Root Cause:** Bug in versions prior to XX.XX where the `update_peer()` operation would silently drop the encrypted federation token when updating any peer field.\n\n**Who is Affected:**\n- Anyone who updated peer configurations between version X.X and X.X\n\n**How to Identify:**\n- Sync was working before a peer update\n- Sync now returns 0 items or authentication errors\n- No changes were made to the token itself\n\n**Recovery:**\n\nUpdate the federation token using the dedicated token update endpoint:\n\n```bash\ncurl -X PATCH https://registry.com/api/peers//token \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"federation_token\": \"\"\n }'\n```\n\n**Prevention:** This issue is fixed in version XX.XX. After upgrading, peer updates will preserve the federation token correctly.\n\n### Synced Items Are Read-Only\n\n**Expected behavior:** Federated items cannot be modified locally.\n\nIf you need to modify a synced item:\n1. Modify it on the source registry\n2. Wait for next sync or trigger manual sync\n\n### Orphaned Items\n\n**Symptom:** Items show as orphaned in the UI.\n\nThis happens when items are removed from the source registry. To resolve:\n1. Confirm the items should be removed from the source\n2. Delete orphaned items manually, or\n3. Re-sync to clear orphaned status if items are restored\n\n## Monitoring\n\n### Health Check Endpoint\n\nEach registry exposes a federation health endpoint:\n\n```bash\ncurl https://registry.com/api/v1/federation/health\n```\n\nReturns:\n```json\n{\n \"status\": \"healthy\",\n \"federation_enabled\": true,\n \"peer_count\": 3\n}\n```\n\n### Sync Status Metrics\n\nMonitor sync status via the API:\n\n```bash\ncurl https://registry.com/api/peers/lob-a/status\n```\n\nReturns:\n```json\n{\n \"peer_id\": \"lob-a\",\n \"is_healthy\": true,\n \"last_successful_sync\": \"2026-02-05T10:30:00Z\",\n \"total_servers_synced\": 15,\n \"total_agents_synced\": 3,\n \"sync_in_progress\": false,\n \"consecutive_failures\": 0\n}\n```\n\n### Alerting Recommendations\n\nSet up alerts for:\n- `consecutive_failures > 3` - Sync has failed multiple times\n- `is_healthy == false` - Peer is unreachable\n- Time since `last_successful_sync > 2x sync_interval` - Sync is stale\n\n## Security Best Practices\n\n1. **Use strong tokens**: Generate tokens with `secrets.token_urlsafe(32)` or longer\n2. **Rotate tokens periodically**: Rotate federation tokens at least annually\n3. **Limit visibility**: Only set `visibility: \"public\"` on items that should be shared\n4. **Use tag filters**: Use tag-based filtering to control what gets synced\n5. **Monitor sync activity**: Review sync logs for unexpected patterns\n6. **Network isolation**: Use private networks or VPNs between registries when possible\n\n## Registry Card Configuration\n\nThe Registry Card is a discovery document that provides metadata about your registry instance, including its capabilities, authentication endpoints, and contact information. It is essential for federation discovery and is accessed via the `.well-known` endpoint:\n\n```\nGET /.well-known/registry-card\n```\n\n### Viewing and Editing the Registry Card\n\nNavigate to **Settings > Registry Card** to view and edit your registry's metadata:\n\n![Registry Card Settings](img/reg-card.png)\n\nThe Registry Card settings page shows:\n\n1. **Registry Information** (read-only):\n - Registry ID (UUID)\n - Name\n - Organization\n - Registry URL\n - Federation Endpoint\n - API Version\n\n2. **Authentication Configuration** (read-only):\n - Supported authentication schemes\n - OAuth2 issuer URL\n - OAuth2 token endpoint\n - Supported scopes\n\n3. **Editable Information**:\n - Description (up to 1000 characters)\n - Contact Email\n - Contact URL\n\n4. **Capabilities** (configured via feature flags):\n - Servers, Agents, Skills management\n - Security scans\n - Incremental sync (future)\n - Webhooks (future)\n\n### Auto-Initialization\n\nThe Registry Card is automatically initialized on first startup using environment variables. Configure these in your `.env` file:\n\n```bash\n# Registry Identity (Required)\nREGISTRY_URL=https://registry.example.com\nREGISTRY_NAME=My Registry\nREGISTRY_ORGANIZATION_NAME=ACME Corporation\n\n# Optional\nREGISTRY_DESCRIPTION=Enterprise MCP Gateway Registry\nREGISTRY_CONTACT_EMAIL=mcp-support@example.com\nREGISTRY_CONTACT_URL=https://example.com/support\n```\n\nFor a complete list of configuration options, see the [Configuration Reference](configuration.md).\n\n### Authentication Provider Examples\n\nThe Registry Card automatically configures authentication endpoints based on your `AUTH_PROVIDER` setting:\n\n- **Entra ID**: Uses Microsoft login endpoints\n- **Keycloak**: Uses your Keycloak realm endpoints\n- **Okta**: Uses your Okta domain endpoints\n- **Cognito**: Uses AWS Cognito endpoints\n\nThe authentication configuration is read-only and updates automatically when you change authentication providers.\n\n## Related Documentation\n\n- [Federation Architecture](design/federation-architecture.md) - Technical architecture\n- [Federation Guide](federation.md) - External registry integration (Anthropic, ASOR)\n- [Static Token Auth](static-token-auth.md) - Static token authentication details\n- [Configuration Reference](configuration.md) - Environment variable reference\n" }, { "path": "docs/federation.md", "content": "# Federation Guide - External Registry Integration\n\nThe MCP Gateway Registry supports federation with external registries, allowing you to import and manage servers/agents from multiple sources through a unified interface.\n\n## Supported Federation Sources\n\n| Source | Type | Description | Visual Tag |\n|--------|------|-------------|------------|\n| **Anthropic MCP Registry** | MCP Servers | Official Anthropic curated MCP servers | `ANTHROPIC` (purple) |\n| **Workday ASOR** | AI Agents | Workday Agent System of Record | `ASOR` (orange) |\n\n
\n\"Federation\n
\n\n---\n\n## Quick Setup\n\n### 1. Environment Variables\n\nAdd to your `.env` file:\n\n```bash\n# Anthropic MCP Registry (no auth required)\nANTHROPIC_REGISTRY_ENABLED=true\n\n# Workday ASOR (requires OAuth credentials and token)\nASOR_CLIENT_ID=your_client_id\nASOR_CLIENT_SECRET=your_client_secret\nASOR_TENANT_NAME=your_tenant_name\nASOR_HOSTNAME=your_host_name\n```\n\n### 2. Federation Configuration\n\nCreate or update `~/mcp-gateway/federation.json`:\n\n```json\n{\n \"anthropic\": {\n \"enabled\": true,\n \"endpoint\": \"https://registry.modelcontextprotocol.io\",\n \"servers\": []\n },\n \"asor\": {\n \"enabled\": true,\n \"endpoint\": \"https://wcpdev-services1.wd103.myworkday.com/ccx/api/asor/v1/awsasor_wcpdev1\",\n \"auth_env_var\": \"ASOR_ACCESS_TOKEN\",\n \"agents\": []\n }\n}\n```\n\n### 3. Start Services\n\n```bash\n./build_and_run.sh\n```\n\n---\n\n## Anthropic MCP Registry Integration\n\n### Configuration\n\n```json\n{\n \"anthropic\": {\n \"enabled\": true,\n \"endpoint\": \"https://registry.modelcontextprotocol.io\",\n \"servers\": [\n {\"name\": \"io.github.jgador/websharp\"},\n {\"name\": \"another-server-name\"}\n ]\n }\n}\n```\n\n### Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `enabled` | boolean | `false` | Enable Anthropic federation |\n| `endpoint` | string | `https://registry.modelcontextprotocol.io` | Anthropic registry API endpoint |\n| `servers` | array | `[]` | Specific servers to import (empty = all) |\n\n### Import Specific Servers for Anthropic\n\n**Option 1: Configuration File**\n```json\n{\n \"anthropic\": {\n \"servers\": [\n {\"name\": \"io.github.jgador/websharp\"},\n {\"name\": \"modelcontextprotocol/filesystem\"},\n {\"name\": \"modelcontextprotocol/brave-search\"}\n ]\n }\n}\n```\n\n### Import All Available Servers for Asor\n\nSet `servers` to empty array:\n```json\n{\n \"asor\": {\n \"servers\": []\n }\n}\n```\n\n---\n\n## Workday ASOR Integration\n\n### Prerequisites\n\n1. **Workday ASOR Access**: Valid Workday tenant with ASOR enabled\n2. **OAuth Credentials**: Client ID and Secret for ASOR API\n3. **Access Token**: Valid OAuth token with \"Agent System of Record\" scope\n\n### Step 1: Get OAuth Token\n\nAdd to `.env`:\n```bash\n# ASOR OAuth Credentials\nASOR_CLIENT_ID=your_client_id\nASOR_CLIENT_SECRET=your_client_secret\nASOR_TENANT_NAME=your_tenant_name\nASOR_HOSTNAME=your_host_name\n\nUse the provided token generator:\n\n```bash\npython3 get_asor_token.py\n```\n\nThis will:\n1. Generate authorization URL\n2. Guide you through OAuth flow\n3. Provide access token for `.env` file\n\n### Step 2: Environment Configuration\n\n# OAuth Access Token (generated by get_asor_token.py)\nASOR_ACCESS_TOKEN=your_oauth_token_here\n```\n\n### Step 3: Federation Configuration\n\n```json\n{\n \"asor\": {\n \"enabled\": true,\n \"endpoint\": \"https://wcpdev-services1.wd103.myworkday.com/ccx/api/asor/v1/awsasor_wcpdev1\",\n \"auth_env_var\": \"ASOR_ACCESS_TOKEN\",\n \"agents\": []\n }\n}\n```\n\n### Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `enabled` | boolean | `false` | Enable ASOR federation |\n| `endpoint` | string | Required | ASOR API endpoint URL |\n| `auth_env_var` | string | `ASOR_ACCESS_TOKEN` | Environment variable containing OAuth token |\n| `agents` | array | `[]` | Specific agents to import (empty = all) |\n\n### Token Management\n\n**Token Expiration**: ASOR tokens expire every 4 hours. You'll need to:\n\n1. **Monitor logs** for authentication errors\n2. **Regenerate tokens** using `python3 get_asor_token.py`\n3. **Update .env** with new token\n4. **Restart services** to apply new token\n\n**Automated Token Refresh** (Future Enhancement):\n```bash\n# Set up cron job for token refresh\n0 */3 * * * cd /path/to/mcp-gateway && python3 get_asor_token.py --auto-update\n```\n\n---\n\n## Visual Identification\n\nFederated servers and agents are visually tagged in the UI:\n\n### Server Cards (MCP Servers Tab)\n- **ANTHROPIC**: Purple gradient badge for Anthropic MCP Registry servers\n\n### Agent Cards (A2A Agents Tab)\n- **ASOR**: Orange gradient badge for ASOR-sourced agents\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**1. Anthropic Servers Not Importing**\n```bash\n# Check logs\ndocker-compose logs registry | grep -i anthropic\n\n# Verify connectivity\ncurl https://registry.modelcontextprotocol.io/servers\n\n# Check configuration\ncat ~/mcp-gateway/federation.json\n```\n\n**2. ASOR Authentication Errors**\n```bash\n# Check token in logs\ndocker-compose logs registry | grep -i asor\n\n# Verify token\necho $ASOR_ACCESS_TOKEN\n\n# Test token manually\ncurl -H \"Authorization: Bearer $ASOR_ACCESS_TOKEN\" \\\n https://wcpdev-services1.wd103.myworkday.com/ccx/api/asor/v1/awsasor_wcpdev1/agentDefinition\n```\n\n**3. Duplicate Entries**\n- ASOR agents should only appear in **A2A Agents** tab\n- If appearing in both tabs, check federation service logs for duplicate registration\n\n### Debug Mode\n\nEnable detailed federation logging:\n\n```bash\n# Add to .env\nFEDERATION_DEBUG=true\nLOG_LEVEL=DEBUG\n\n# Restart services\ndocker-compose restart registry\n```\n\n### Log Analysis\n\n```bash\n# Federation startup\ndocker-compose logs registry | grep -i \"federation.*enabled\"\n\n# Sync operations\ndocker-compose logs registry | grep -i \"sync.*servers\\|sync.*agents\"\n\n# Authentication\ndocker-compose logs registry | grep -i \"token\\|auth\"\n\n# Errors\ndocker-compose logs registry | grep -i \"error\\|failed\"\n```\n\n---\n\n## Advanced Configuration\n\n### Custom Endpoints\n\nFor enterprise deployments with custom registry endpoints:\n\n```json\n{\n \"anthropic\": {\n \"endpoint\": \"https://your-custom-mcp-registry.company.com\"\n },\n \"asor\": {\n \"endpoint\": \"https://your-workday-tenant.myworkday.com/ccx/api/asor/v1/your_tenant\"\n }\n}\n```\n\n### Selective Import\n\nImport only specific servers/agents:\n\n```json\n{\n \"anthropic\": {\n \"servers\": [\n {\"name\": \"modelcontextprotocol/filesystem\"},\n {\"name\": \"modelcontextprotocol/brave-search\"}\n ]\n },\n \"asor\": {\n \"agents\": [\n {\"id\": \"aws_assistant\"},\n {\"id\": \"data_analyst\"}\n ]\n }\n}\n```\n\n\n---\n\n## Security Considerations\n\n### Token Security\n\n1. **Environment Variables**: Store tokens in `.env`, never in code\n2. **Token Rotation**: Regularly rotate ASOR tokens\n3. **Access Control**: Limit federation access to admin users\n4. **Audit Logging**: Monitor federation sync operations\n\n### Network Security\n\n1. **HTTPS Only**: All federation endpoints use HTTPS\n2. **Firewall Rules**: Allow outbound HTTPS to federation endpoints\n3. **Proxy Support**: Configure HTTP proxy if required\n\n```bash\n# Proxy configuration in .env\nHTTP_PROXY=http://proxy.company.com:8080\nHTTPS_PROXY=http://proxy.company.com:8080\n```\n\n---\n\n## API Reference\n\n### Federation Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/federation/status` | Get federation configuration and status |\n| `POST` | `/api/federation/sync` | Sync all enabled federations |\n| `POST` | `/api/federation/sync/{source}` | Sync specific federation source |\n\n### Response Examples\n\n**Federation Status:**\n```json\n{\n \"enabled_federations\": [\"anthropic\", \"asor\"],\n \"anthropic\": {\n \"enabled\": true,\n \"last_sync\": \"2024-01-15T10:30:00Z\"\n },\n \"asor\": {\n \"enabled\": true,\n \"last_sync\": \"2024-01-15T10:25:00Z\"\n }\n}\n```\n\n**Sync Response:**\n```json\n{\n \"success\": true,\n \"results\": {\n \"anthropic\": {\n \"synced\": 25,\n \"errors\": 0,\n \"duration_ms\": 1250\n },\n \"asor\": {\n \"synced\": 3,\n \"errors\": 0,\n \"duration_ms\": 850\n }\n }\n}\n```\n\n### Contributing\n\n1. **New Federation Sources**: Guidelines for adding new sources\n2. **Bug Reports**: How to report federation issues\n3. **Feature Requests**: Process for requesting new federation features\n4. **Testing**: How to test federation changes\n\n---\n\n*Last Updated: November 2024*\n\n## ASOR to Agent Card Field Mapping\n\nThis section documents how ASOR agent data is mapped to the MCP Gateway Registry Agent Card format.\n\n### Field Mapping Table\n\n| ASOR Field | Agent Card Field | Mapping Logic | Status |\n|------------|------------------|---------------|---------|\n| **Required A2A Fields** |\n| N/A | `protocol_version` | Hardcoded to `\"1.0\"` | ✅ Mapped |\n| `name` | `name` | Direct mapping, fallback to `\"Unknown ASOR Agent\"` | ✅ Mapped |\n| `description` | `description` | Direct mapping, fallback to `f\"ASOR agent: {agent_name}\"` if `\"None\"` | ✅ Mapped |\n| `url` | `url` | Direct mapping, fallback to empty string | ✅ Mapped |\n| **Optional A2A Fields** |\n| `version` | `version` | Direct mapping, fallback to `\"1.0.0\"` | ✅ Mapped |\n| N/A | `provider` | Hardcoded to `\"ASOR\"` | ✅ Mapped |\n| N/A | `security_schemes` | Empty dict (default) | ❌ Missing |\n| N/A | `security` | None (default) | ❌ Missing |\n| `skills[]` | `skills` | Array mapping: `{name, description, id}` | ✅ Mapped |\n| `capabilities.streaming` | `streaming` | Direct mapping from capabilities object | ⚠️ Available but not mapped |\n| `capabilities`, `workdayConfig`, `supportsAuthenticatedExtendedCard` | `metadata` | Could map additional ASOR fields | ⚠️ Available but not mapped |\n| **Registry Extensions** |\n| N/A | `path` | Generated from name: `f\"/{agent_name.lower().replace('_', '-')}\"` | ✅ Mapped |\n| N/A | `tags` | Hardcoded to `[\"asor\", \"federated\", \"workday\"]` | ✅ Mapped |\n| N/A | `is_enabled` | False (default) | ✅ Mapped |\n| N/A | `num_stars` | 0 (default) | ✅ Mapped |\n| N/A | `license` | Hardcoded to `\"Unknown\"` | ✅ Mapped |\n| N/A | `registered_at` | Current timestamp | ✅ Mapped |\n| N/A | `updated_at` | None (default) | ✅ Mapped |\n| N/A | `registered_by` | Hardcoded to `\"asor-federation\"` | ✅ Mapped |\n\n### ASOR Data Structure\n\nBased on the actual ASOR API response, the agent data structure is:\n\n```json\n{\n \"capabilities\": {\n \"stateTransitionHistory\": false,\n \"pushNotifications\": false,\n \"streaming\": true\n },\n \"url\": \"https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/arn%3Aaws%3Abedrock-agentcore%3Aus-west-2%3A218208277580%3Aruntime%2Faws_assistant-XYx9SWFOvW/invocations?qualifier=DEFAULT\",\n \"description\": \"None\",\n \"name\": \"aws_assistant\",\n \"supportsAuthenticatedExtendedCard\": false,\n \"workdayConfig\": [\n {\n \"skillId\": \"skill_extractContent\"\n },\n {\n \"skillId\": \"skill_searchQuery\"\n }\n ],\n \"skills\": [\n {\n \"id\": \"skill_extractContent\",\n \"description\": \"Extract and parse content from up to 20 URLs simultaneously\",\n \"name\": \"extractContent\"\n },\n {\n \"id\": \"skill_searchQuery\",\n \"description\": \"Performs a search query using Tavily Search and returns comprehensive results including answer, images, and search results\",\n \"name\": \"searchQuery\"\n }\n ],\n \"version\": \"1\"\n}\n```\n\n### Available but Unmapped ASOR Fields\n\nThe following ASOR fields are available but not currently mapped:\n\n1. **`capabilities`** - Object with streaming, notifications, state history flags\n2. **`workdayConfig`** - Array of skill configurations \n3. **`supportsAuthenticatedExtendedCard`** - Boolean flag for extended card support\n\n### Missing Fields from ASOR\n\nThe following Agent Card fields are not provided by ASOR:\n\n1. **Security Configuration**\n - `security_schemes` - No authentication schemes provided\n - `security` - No security requirements specified\n\n2. **Licensing**\n - `license` - License information not available\n\n### Recommendations\n\nTo improve ASOR integration:\n\n1. **Map available fields:**\n ```python\n streaming=agent_data.get(\"capabilities\", {}).get(\"streaming\", False)\n metadata={\n \"capabilities\": agent_data.get(\"capabilities\", {}),\n \"workdayConfig\": agent_data.get(\"workdayConfig\", []),\n \"supportsAuthenticatedExtendedCard\": agent_data.get(\"supportsAuthenticatedExtendedCard\", False)\n }\n ```\n\n2. **Request additional fields from ASOR API:**\n - License information\n - Security/authentication schemes\n" }, { "path": "docs/iam-settings-ui.md", "content": "# IAM Settings UI\n\nThis document describes the Identity and Access Management (IAM) Settings UI, which provides a visual interface for managing users, groups, and machine-to-machine (M2M) service accounts directly from the MCP Gateway Registry web interface.\n\n## Overview\n\nThe IAM Settings UI is accessible to administrators via **Settings > IAM** in the left navigation panel. It provides three management sections:\n\n- **Groups** - Create and manage access control groups with fine-grained permissions\n- **Users** - Create and manage human user accounts\n- **M2M Accounts** - Create and manage machine-to-machine service accounts for AI agents and automation\n\nThe IAM UI works with both Keycloak and Microsoft Entra ID identity providers, providing a unified experience regardless of which IdP you use.\n\n![IAM Settings UI](img/iam.gif)\n\n## Prerequisites\n\n- Administrator access to the MCP Gateway Registry\n- A configured identity provider (Keycloak or Entra ID)\n- For Entra ID: Application configured with User.ReadWrite.All and GroupMember.ReadWrite.All permissions\n\n## Groups Management\n\nGroups are the primary unit of access control. Each group maps to an IdP group and defines what servers, tools, agents, and UI features members can access.\n\n### Creating a Group\n\n1. Navigate to **Settings > IAM > Groups**\n2. Click the **Create Group** button\n3. Fill in the required fields:\n - **Name**: Group identifier (will be created in the IdP)\n - **Description**: Human-readable description of the group's purpose\n\n### Configuring Server Access\n\nServer access defines which MCP servers and virtual servers the group can connect to via the MCP Gateway.\n\n1. In the **Server Access** section, click **Add Server**\n2. Select a server from the dropdown (includes both MCP servers and virtual servers)\n3. Configure access:\n - **Methods**: Select which MCP methods are allowed (initialize, tools/list, tools/call, etc.)\n - **Tools**: Select specific tools or use `*` for all tools on that server\n\n**Tip**: Virtual servers (paths starting with `/virtual/`) are automatically displayed alongside regular MCP servers in the server selector.\n\n### Configuring UI Permissions\n\nUI permissions control what users can see and do in the Registry web interface:\n\n| Permission | Description |\n|------------|-------------|\n| `list_service` | View MCP servers in the dashboard |\n| `register_service` | Register new MCP servers |\n| `health_check_service` | Trigger health checks on servers |\n| `toggle_service` | Enable/disable servers |\n| `modify_service` | Edit server configuration |\n| `delete_service` | Delete servers |\n| `list_agents` | View A2A agents in the dashboard |\n| `get_agent` | View agent details |\n| `publish_agent` | Register new agents |\n| `modify_agent` | Edit agent configuration |\n| `delete_agent` | Delete agents |\n| `list_virtual_server` | View virtual MCP servers |\n\nFor each permission, specify which resources it applies to:\n- Use `all` to grant access to all resources\n- Use specific server/agent paths for fine-grained control\n\n### Configuring Agent Access\n\nAgent access controls which A2A agents the group can interact with:\n\n1. In the **Agent Access** section, click **Add Agent**\n2. Select an agent from the dropdown\n3. Select allowed actions (list_agents, get_agent, invoke_agent, etc.)\n\n### Import/Export Scope JSON\n\nGroups can be imported and exported as JSON for version control, backup, or migration:\n\n**Export**: Click the download icon to export the current group configuration as JSON\n\n**Import**: Click the upload icon and paste a scope JSON configuration:\n\n```json\n{\n \"scope_name\": \"data-team\",\n \"description\": \"Data team with access to data processing tools\",\n \"server_access\": [\n {\n \"server\": \"data-processor\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"process_csv\", \"analyze_data\"]\n }\n ],\n \"group_mappings\": [\"data-team\"],\n \"ui_permissions\": {\n \"list_service\": [\"data-processor\"],\n \"health_check_service\": [\"data-processor\"]\n },\n \"create_in_idp\": true\n}\n```\n\n## Users Management\n\nThe Users section manages human user accounts that can log into the Registry UI and generate JWT tokens for CLI tools.\n\n### Creating a User\n\n1. Navigate to **Settings > IAM > Users**\n2. Click **Create User**\n3. Fill in the required fields:\n - **Username**: Unique identifier for the user\n - **Email**: User's email address\n - **First Name**: User's first name\n - **Last Name**: User's last name\n - **Password**: Initial password (user should change on first login)\n4. Select groups to assign the user to\n5. Click **Create**\n\n### Managing User Groups\n\nTo modify a user's group memberships:\n\n1. Find the user in the list\n2. Click the edit (pencil) icon in the Groups column\n3. Check/uncheck groups as needed\n4. Click the checkmark to save\n\n### Deleting a User\n\n1. Find the user in the list\n2. Click the delete (trash) icon\n3. Confirm the deletion\n\n**Note**: Deleting a user removes them from the IdP. This action cannot be undone.\n\n## M2M Accounts (Service Accounts)\n\nM2M (Machine-to-Machine) accounts are service accounts for AI agents, automation scripts, and other non-human clients that need to authenticate with the Registry API.\n\n### Creating an M2M Account\n\n1. Navigate to **Settings > IAM > M2M Accounts**\n2. Click **Create M2M Account**\n3. Fill in the required fields:\n - **Name**: Identifier for the service account (e.g., `my-ai-agent`)\n - **Description**: Purpose of the service account\n4. Select groups to assign (determines what the account can access)\n5. Click **Create**\n\n### Viewing Credentials\n\nAfter creating an M2M account, the client credentials are displayed **once**:\n\n- **Client ID**: The OAuth2 client identifier\n- **Client Secret**: The OAuth2 client secret\n\n**Important**: Copy and store these credentials securely. The client secret cannot be retrieved again after you navigate away.\n\n### Using M2M Credentials\n\nTo obtain a JWT token for API access:\n\n```bash\n# Get JWT token using client credentials grant\n# For local testing, use http://localhost for Keycloak\nTOKEN=$(curl -s -X POST \"https://keycloak.example.com/realms/mcp-gateway/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id=my-ai-agent\" \\\n -d \"client_secret=YOUR_CLIENT_SECRET\" \\\n -d \"grant_type=client_credentials\" | jq -r '.access_token')\n\n# Use the token to call Registry API\n# For local testing, use http://localhost\ncurl -H \"Authorization: Bearer $TOKEN\" \"https://registry.example.com/api/servers\"\n```\n\nOr use the provided helper script:\n\n```bash\n# Create credentials file\nmkdir -p .oauth-tokens\ncat > .oauth-tokens/my-ai-agent.json << EOF\n{\n \"client_id\": \"my-ai-agent\",\n \"client_secret\": \"YOUR_CLIENT_SECRET\"\n}\nEOF\n\n# Get token (uses KEYCLOAK_URL env var, defaults to http://localhost)\n./scripts/refresh_m2m_token.sh my-ai-agent\n\n# Use the token\n# For local testing, use http://localhost\nexport TOKEN=$(jq -r '.access_token' .oauth-tokens/my-ai-agent-token.json)\ncurl -H \"Authorization: Bearer $TOKEN\" \"https://registry.example.com/api/servers\"\n```\n\n### Deleting an M2M Account\n\n1. Find the account in the list\n2. Click the delete (trash) icon\n3. Confirm the deletion\n\n**Note**: Deleting an M2M account immediately invalidates all tokens issued to it.\n\n## Best Practices\n\n### Group Organization\n\n- Create groups based on team function or access level (e.g., `data-team`, `ml-engineers`, `read-only-users`)\n- Use descriptive names and descriptions\n- Apply the principle of least privilege - grant only the access needed\n\n### Server Access\n\n- Start with minimal methods and tools, expand as needed\n- Use tool-level restrictions rather than granting `*` when possible\n- For virtual servers, ensure `list_virtual_server` UI permission is granted\n\n### M2M Accounts\n\n- Create separate M2M accounts for each service or agent\n- Rotate credentials periodically\n- Store secrets in a secure vault, not in code repositories\n- Use descriptive names that identify the service (e.g., `data-pipeline-bot`, `monitoring-agent`)\n\n## Troubleshooting\n\n### User Cannot See Servers\n\n1. Check the user's group membership\n2. Verify the group has `list_service` UI permission for the server\n3. For virtual servers, verify `list_virtual_server` UI permission\n\n### User Cannot See Virtual Servers\n\nVirtual servers require the `list_virtual_server` UI permission. Add this permission to the group:\n\n```json\n{\n \"ui_permissions\": {\n \"list_virtual_server\": [\"/virtual/your-server-path\"]\n }\n}\n```\n\n### M2M Account Token Not Working\n\n1. Verify the client credentials are correct\n2. Check that the M2M account is assigned to appropriate groups\n3. Ensure the groups have the necessary `server_access` permissions\n4. Check Keycloak/Entra ID logs for authentication errors\n\n### Group Changes Not Taking Effect\n\nAfter modifying group permissions:\n1. Users may need to log out and log back in\n2. M2M accounts need to obtain a new token\n3. Changes to IdP group membership may take a few minutes to sync\n\n## Related Documentation\n\n- [Scopes Management](scopes-mgmt.md) - Detailed scope configuration format\n- [Authentication Design](design/authentication-design.md) - Architecture overview\n- [IdP Provider Architecture](design/idp-provider-support.md) - Multi-provider support details\n- [Keycloak Integration](keycloak-integration.md) - Keycloak setup guide\n- [Entra ID Setup](entra-id-setup.md) - Microsoft Entra ID configuration\n" }, { "path": "docs/img/MCPGW-Registry.drawio", "content": "\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "docs/img/architecture-with-dataplane.md", "content": "# MCP Gateway & Registry - Architecture with Data Plane\n\n```\n USERS & AI AGENTS\n |\n v\n+-----------------------------------------------------------------------------------+\n| MCP GATEWAY & REGISTRY INFRASTRUCTURE |\n+-----------------------------------------------------------------------------------+\n| |\n| +------------------------------------------------------------------------+ |\n| | NGINX REVERSE PROXY (Gateway) | |\n| | Entry Point - SSL/TLS Termination | |\n| +------------------------------------------------------------------------+ |\n| | | | |\n| | v v |\n| | +-----------------------------+ +-------------------+ |\n| | | Registry | | Auth Server | |\n| | | (FastAPI) | | (FastAPI) | |\n| | | | | | |\n| | | - Server Management | | - OAuth 2.0/OIDC | |\n| | | - Tool Discovery | | - JWT Validation | |\n| | | - Agent Registry | | - Scope Enforce | |\n| | | - Health Monitoring | | - Token Vending | |\n| | +-----------------------------+ +-------------------+ |\n| | | |\n| | v |\n| | +--------------------+ |\n| | | Identity Provider | |\n| | | (IdP) | |\n| | +--------------------+ |\n| | | - Keycloak | |\n| | | - Microsoft Entra | |\n| | | - Amazon Cognito | |\n| | | - Other OIDC/SAML | |\n| | +--------------------+ |\n| | |\n| | DATA PLANE |\n| | ========== |\n| v |\n| +------------------------------------------------------------------------+ |\n| | MCP SERVERS | |\n| +------------------------------------------------------------------------+ |\n| | | |\n| | +---------------+ +---------------+ +---------------+ | |\n| | | MCP Server | | MCP Server | | MCP Server | . . . | |\n| | | (context7) | | (github) | | (jira) | | |\n| | +---------------+ +---------------+ +---------------+ | |\n| | | |\n| | +---------------+ +---------------+ +---------------+ | |\n| | | MCP Server | | MCP Server | | MCP Server | . . . | |\n| | | (confluence) | | (slack) | | (custom) | | |\n| | +---------------+ +---------------+ +---------------+ | |\n| | | |\n| +------------------------------------------------------------------------+ |\n| |\n+-----------------------------------------------------------------------------------+\n\n\n+-----------------------------------------------------------------------------------+\n| DATASTORE |\n| MongoDB-CE | Amazon DocumentDB |\n+-----------------------------------------------------------------------------------+\n| |\n| +-------------+ +-------------+ +-------------+ +------------------+ |\n| | servers | | agents | | scopes | | security_scans | |\n| | collection | | collection | | collection | | collection | |\n| +-------------+ +-------------+ +-------------+ +------------------+ |\n| |\n| +-------------------------------------------------------------------------+ |\n| | HYBRID SEARCH SUPPORT | |\n| | Keyword Text Matching + Vector k-NN (Embeddings) | |\n| +-------------------------------------------------------------------------+ |\n| |\n+-----------------------------------------------------------------------------------+\n\n\n+-----------------------------------------------------------------------------------+\n| DEPLOYMENT INFRASTRUCTURE |\n+-----------------------------------------------------------------------------------+\n| |\n| +-------------------+ +-------------------+ +-------------------+ |\n| | Amazon EKS | | Amazon ECS | | Amazon EC2 | |\n| | (Kubernetes) | | (Fargate) | | (Local Dev) | |\n| +-------------------+ +-------------------+ +-------------------+ |\n| |\n+-----------------------------------------------------------------------------------+\n```\n" }, { "path": "docs/index.md", "content": "
\n\"MCP\n\n**Gateway for AI Development Tools**\n\n
\n\n## MCP Server & Registry\n\nA comprehensive solution for managing, securing, and accessing Model Context Protocol (MCP) servers at scale. Built for enterprises, development teams, and autonomous AI agents.\n\n### Demo Videos\n\n| Feature | Demo |\n|---------|------|\n| **Full End-to-End Functionality** | [Watch Full Demo](https://github.com/user-attachments/assets/5ffd8e81-8885-4412-a4d4-3339bbdba4fb) |\n| **OAuth 3-Legged Authentication** | [Watch 3LO Demo](https://github.com/user-attachments/assets/3c3a570b-29e6-4dd3-b213-4175884396cc) |\n| **Dynamic Tool Discovery & Invocation** | [Watch Tool Discovery](https://github.com/user-attachments/assets/cee25b31-61e4-4089-918c-c3757f84518c) |\n\n### MCP Tools in Action\n\n
\n\"MCP\n
\n\n*Experience dynamic tool discovery and intelligent MCP server integration in real-time*\n\n---\n\n## Key Features\n\n### Architecture Features\n- **Reverse Proxy**: Centralized access point for all MCP servers\n- **Service Discovery**: Automatic registration and health monitoring\n- **Load Balancing**: Intelligent request distribution across server instances\n- **Multi-Instance Support**: Deployment patterns supporting redundancy\n\n### Advanced Security & Authentication\n- **OAuth 2.0 Integration**: Amazon Cognito, Google, GitHub, and custom providers\n- **Fine-Grained Access Control**: Role-based permissions with scope management\n- **JWT Token Vending**: Secure token generation and validation\n- **Audit Logging**: Comprehensive security event tracking\n\n### AI Agent Optimization\n- **Dynamic Tool Discovery**: Runtime MCP server and tool enumeration\n- **Intelligent Tool Finder**: AI-powered tool recommendation and selection\n- **Autonomous Access Control**: Context-aware permission management\n- **Multi-Agent Coordination**: Shared resource access with conflict resolution\n\n### Developer Experience\n- **React Web Interface**: Intuitive server management and monitoring\n- **REST API**: Programmatic registry management and integration\n- **AI Coding Assistant Integration**: VS Code, Cursor, Claude Code support\n- **Real-Time Monitoring**: Live server health and performance metrics\n\n---\n\n## Quick Start\n\n!!! tip \"Prerequisites\"\n Before proceeding, ensure you have satisfied all [prerequisites](installation.md#prerequisites) including Docker, AWS account setup, and Amazon Cognito configuration.\n\nGet up and running in 5 minutes with Docker Compose:\n\n```bash\n# 1. Clone and setup\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\n\n# 2. Configure environment\ncp .env.example .env\n# Edit .env with your Amazon Cognito credentials\n\n# 3. Generate authentication credentials \n./credentials-provider/generate_creds.sh\n\n# 4. Deploy with Docker Compose\ndocker-compose up -d\n\n# 5. Access the registry\nopen http://localhost:7860\n```\n\nThe registry will be available at `http://localhost:7860` with example MCP servers pre-configured.\n\n---\n\n## Architecture Overview\n\n```mermaid\nflowchart TB\n subgraph Human_Users[\"Human Users\"]\n User1[\"Human User 1\"]\n User2[\"Human User 2\"]\n UserN[\"Human User N\"]\n end\n\n subgraph AI_Agents[\"AI Agents\"]\n Agent1[\"AI Agent 1\"]\n Agent2[\"AI Agent 2\"]\n Agent3[\"AI Agent 3\"]\n AgentN[\"AI Agent N\"]\n end\n\n subgraph EC2_Gateway[\"MCP Gateway & Registry (Amazon EC2 Instance)\"]\n subgraph NGINX[\"NGINX Reverse Proxy\"]\n RP[\"Reverse Proxy Router\"]\n end\n \n subgraph AuthRegistry[\"Authentication & Registry Services\"]\n AuthServer[\"Auth Server
(Dual Auth)\"]\n Registry[\"Registry
Web UI\"]\n RegistryMCP[\"Registry
MCP Server\"]\n end\n \n subgraph LocalMCPServers[\"Local MCP Servers\"]\n MCP_Local1[\"MCP Server 1\"]\n MCP_Local2[\"MCP Server 2\"]\n end\n end\n \n %% Identity Provider\n IdP[Identity Provider
Amazon Cognito]\n \n subgraph EKS_Cluster[\"Amazon EKS/EC2 Cluster\"]\n MCP_EKS1[\"MCP Server 3\"]\n MCP_EKS2[\"MCP Server 4\"]\n end\n \n subgraph APIGW_Lambda[\"Amazon API Gateway + AWS Lambda\"]\n API_GW[\"Amazon API Gateway\"]\n Lambda1[\"AWS Lambda Function 1\"]\n Lambda2[\"AWS Lambda Function 2\"]\n end\n \n subgraph External_Systems[\"External Data Sources & APIs\"]\n DB1[(Database 1)]\n DB2[(Database 2)]\n API1[\"External API 1\"]\n API2[\"External API 2\"]\n API3[\"External API 3\"]\n end\n \n %% Connections from Human Users\n User1 -->|Web Browser
Authentication| IdP\n User2 -->|Web Browser
Authentication| IdP\n UserN -->|Web Browser
Authentication| IdP\n User1 -->|Web Browser
HTTPS| Registry\n User2 -->|Web Browser
HTTPS| Registry\n UserN -->|Web Browser
HTTPS| Registry\n \n %% Connections from Agents to Gateway\n Agent1 -->|MCP Protocol
SSE with Auth| RP\n Agent2 -->|MCP Protocol
SSE with Auth| RP\n Agent3 -->|MCP Protocol
Streamable HTTP with Auth| RP\n AgentN -->|MCP Protocol
Streamable HTTP with Auth| RP\n \n %% Auth flow connections\n RP -->|Auth validation| AuthServer\n AuthServer -.->|Validate credentials| IdP\n Registry -.->|User authentication| IdP\n RP -->|Tool discovery| RegistryMCP\n RP -->|Web UI access| Registry\n \n %% Connections from Gateway to MCP Servers\n RP -->|SSE| MCP_Local1\n RP -->|SSE| MCP_Local2\n RP -->|SSE| MCP_EKS1\n RP -->|SSE| MCP_EKS2\n RP -->|Streamable HTTP| API_GW\n \n %% Connections within API GW + Lambda\n API_GW --> Lambda1\n API_GW --> Lambda2\n \n %% Connections to External Systems\n MCP_Local1 -->|Tool Connection| DB1\n MCP_Local2 -->|Tool Connection| DB2\n MCP_EKS1 -->|Tool Connection| API1\n MCP_EKS2 -->|Tool Connection| API2\n Lambda1 -->|Tool Connection| API3\n\n %% Style definitions\n classDef user fill:#fff9c4,stroke:#f57f17,stroke-width:2px\n classDef agent fill:#e1f5fe,stroke:#29b6f6,stroke-width:2px\n classDef gateway fill:#e8f5e9,stroke:#66bb6a,stroke-width:2px\n classDef nginx fill:#f3e5f5,stroke:#ab47bc,stroke-width:2px\n classDef mcpServer fill:#fff3e0,stroke:#ffa726,stroke-width:2px\n classDef eks fill:#ede7f6,stroke:#7e57c2,stroke-width:2px\n classDef apiGw fill:#fce4ec,stroke:#ec407a,stroke-width:2px\n classDef lambda fill:#ffebee,stroke:#ef5350,stroke-width:2px\n classDef dataSource fill:#e3f2fd,stroke:#2196f3,stroke-width:2px\n \n %% Apply styles\n class User1,User2,UserN user\n class Agent1,Agent2,Agent3,AgentN agent\n class EC2_Gateway,NGINX gateway\n class RP nginx\n class AuthServer,Registry,RegistryMCP gateway\n class IdP apiGw\n class MCP_Local1,MCP_Local2 mcpServer\n class EKS_Cluster,MCP_EKS1,MCP_EKS2 eks\n class API_GW apiGw\n class Lambda1,Lambda2 lambda\n class DB1,DB2,API1,API2,API3 dataSource\n```\n\nThe MCP Gateway & Registry acts as a centralized hub that:\n\n1. **Authenticates** users and AI agents through OAuth providers\n2. **Authorizes** access based on fine-grained scopes and permissions\n3. **Routes** requests to appropriate MCP servers\n4. **Monitors** server health and performance\n5. **Discovers** available tools and capabilities dynamically\n\n---\n\n## Use Cases\n\n### Enterprise Integration\nTransform how both autonomous AI agents and development teams access enterprise systems:\n\n- **Unified Access Point**: Single endpoint for all MCP servers across your organization\n- **Enterprise SSO**: Integration with existing identity providers (Cognito, SAML, OIDC)\n- **Compliance & Governance**: Comprehensive audit trails and access control policies\n- **Scalable Architecture**: Support for hundreds of MCP servers and thousands of concurrent users\n\n### AI Agent Workflows\nEnable sophisticated AI agent interactions with enterprise systems:\n\n- **Dynamic Tool Discovery**: Agents discover and utilize tools based on current context\n- **Intelligent Tool Selection**: AI-powered recommendations for optimal tool usage\n- **Multi-Agent Coordination**: Shared access to enterprise resources with conflict resolution\n- **Context-Aware Permissions**: Dynamic access control based on agent capabilities and current task\n\n### Development Team Productivity\nAccelerate development workflows with integrated tooling:\n\n- **IDE Integration**: Native support for VS Code, Cursor, and Claude Code\n- **Real-Time Collaboration**: Shared access to development tools and services\n- **Environment Management**: Consistent tool access across development, staging, and production\n- **API-First Design**: Programmatic access for custom integrations and automation\n\n---\n\n## Documentation\n\n| Getting Started | Authentication & Security | Architecture & Development |\n|-----------------|---------------------------|----------------------------|\n| [Complete Setup Guide](complete-setup-guide.md)
Step-by-step from scratch on AWS EC2 | [Security Posture](security-posture.md)
Comprehensive security controls and compliance | [AI Coding Assistants Setup](ai-coding-assistants-setup.md)
VS Code, Cursor, Claude Code integration |\n| [Installation Guide](installation.md)
Complete setup instructions for EC2 and EKS | [Authentication Guide](auth.md)
OAuth and identity provider integration | [API Reference](registry_api.md)
Programmatic registry management |\n| [Configuration Reference](configuration.md)
Environment variables and settings | [Amazon Cognito Setup](cognito.md)
Step-by-step IdP configuration | [Dynamic Tool Discovery](dynamic-tool-discovery.md)
Autonomous agent capabilities |\n| | [Fine-Grained Access Control](scopes.md)
Permission management and security | [Deployment Guide](installation.md)
Complete setup for deployment environments |\n| | [Security Scanner](security-scanner.md)
MCP server supply chain security | [Troubleshooting Guide](faq/index.md)
Common issues and solutions |\n\n---\n\n## Community & Support\n\n**Getting Help**\n- [FAQ & Troubleshooting](faq/index.md) - Common questions and solutions\n- [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues) - Bug reports and feature requests\n- [GitHub Discussions](https://github.com/agentic-community/mcp-gateway-registry/discussions) - Community support and ideas\n\n**Resources**\n- [Demo Videos](https://github.com/agentic-community/mcp-gateway-registry#demo-videos) - See the platform in action\n\n**Contributing**\n- [Contributing Guide](CONTRIBUTING.md) - How to contribute code and documentation\n- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines and expectations\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n*Part of the [Agentic Community](https://github.com/agentic-community) ecosystem - building the future of AI-driven development.*" }, { "path": "docs/installation.md", "content": "# Installation Guide\n\nComplete installation instructions for the MCP Gateway & Registry on various platforms.\n\n## Prerequisites\n\n- **Node.js 16+**: Required for building the React frontend (not needed with `--prebuilt` flag)\n- **Container Runtime**: Choose one:\n - **Docker & Docker Compose**: Standard container runtime\n - **Podman & Podman Compose**: Rootless alternative (recommended for macOS)\n- **Amazon Cognito or Keycloak**: Identity provider for authentication (see [Cognito Setup Guide](cognito.md) or [Keycloak Integration](keycloak-integration.md))\n- **SSL Certificate**: Optional for HTTPS deployment in production\n\n## Quick Start\n\n### Docker Installation (Default)\n\n```bash\n# 1. Clone and setup\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\ncp .env.example .env\n\n# 2. Setup Python virtual environment\nuv sync\nsource .venv/bin/activate\n\n# 3. Download embeddings model\nuv pip install -U huggingface_hub\nhf download sentence-transformers/all-MiniLM-L6-v2 --local-dir ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2\n\n# 4. Configure environment - edit .env with your passwords\nnano .env\n# Set: KEYCLOAK_ADMIN_PASSWORD, INITIAL_ADMIN_PASSWORD (must match), KEYCLOAK_DB_PASSWORD\n# Set: SESSION_COOKIE_SECURE=false (for HTTP localhost)\n\n# Generate SECRET_KEY\nSECRET_KEY=$(python3 -c \"import secrets; print(secrets.token_urlsafe(64))\")\nsed -i \"s/^#*\\s*SECRET_KEY=.*/SECRET_KEY=$SECRET_KEY/\" .env\n\n# 5. Deploy with pre-built images\nexport DOCKERHUB_ORG=mcpgateway\nsource .env\nexport KEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\n./build_and_run.sh --prebuilt\n# Press Ctrl+C when logs are streaming - containers continue running\n\n# 6. Initialize MongoDB\ndocker compose up mongodb-init\ndocker compose restart auth-server\n\n# 7. Initialize Keycloak (wait for Keycloak to start first)\n# Disable SSL for master realm\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:8080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:8080/admin/realms/master\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n\n# Initialize realm and clients\nchmod +x keycloak/setup/init-keycloak.sh\n./keycloak/setup/init-keycloak.sh\n\n# Disable SSL for application realm\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:8080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:8080/admin/realms/mcp-gateway\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n\n# Get client credentials\nchmod +x keycloak/setup/get-all-client-credentials.sh\n./keycloak/setup/get-all-client-credentials.sh\n\n# Update .env with client secrets from .oauth-tokens/keycloak-client-secrets.txt\ncat .oauth-tokens/keycloak-client-secrets.txt\nnano .env # Update KEYCLOAK_CLIENT_SECRET and KEYCLOAK_M2M_CLIENT_SECRET\n\n# Recreate containers with new credentials\n./build_and_run.sh --prebuilt\n\n# 8. Setup users and service accounts\nchmod +x ./cli/bootstrap_user_and_m2m_setup.sh\n./cli/bootstrap_user_and_m2m_setup.sh\n\n# 9. Access registry\nopen http://localhost:7860 # macOS\n# xdg-open http://localhost:7860 # Linux\n# Login: admin / \n```\n\nFor the complete step-by-step guide with detailed explanations, see the [Quick Start Guide](quickstart.md).\n\n### Podman Installation (Rootless Alternative)\n\n**Recommended for macOS and rootless Linux environments**\n\n```bash\n# 1. Clone and setup\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\ncp .env.example .env\n\n# 2. Install Podman (macOS)\nbrew install podman-desktop\n# OR download from: https://podman-desktop.io/\n\n# 3. Initialize Podman machine (macOS)\npodman machine init --cpus 4 --memory 8192 --disk-size 50\npodman machine start\n\n# 4. Setup Python virtual environment\nuv sync\nsource .venv/bin/activate\n\n# 5. Download embeddings model\nuv pip install -U huggingface_hub\nhf download sentence-transformers/all-MiniLM-L6-v2 --local-dir ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2\n\n# 6. Configure environment - edit .env with your passwords\nnano .env\n# Set: KEYCLOAK_ADMIN_PASSWORD, INITIAL_ADMIN_PASSWORD (must match), KEYCLOAK_DB_PASSWORD\n# Set: SESSION_COOKIE_SECURE=false (for HTTP localhost)\n# For Podman: Set KEYCLOAK_URL=http://localhost:18080\n\n# Generate SECRET_KEY\nSECRET_KEY=$(python3 -c \"import secrets; print(secrets.token_urlsafe(64))\")\nsed -i \"s/^#*\\s*SECRET_KEY=.*/SECRET_KEY=$SECRET_KEY/\" .env\n\n# 7. Deploy with Podman\nexport DOCKERHUB_ORG=mcpgateway\nsource .env\nexport KEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\n./build_and_run.sh --prebuilt --podman\n# Apple Silicon: Use ./build_and_run.sh --podman (without --prebuilt)\n# Press Ctrl+C when logs are streaming - containers continue running\n\n# 8. Initialize MongoDB\npodman compose up mongodb-init\npodman compose restart auth-server\n\n# 9. Initialize Keycloak (wait for Keycloak to start first)\n# Note: Podman uses port 18080 for Keycloak\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:18080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:18080/admin/realms/master\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n\n# Initialize realm and clients\nchmod +x keycloak/setup/init-keycloak.sh\nKEYCLOAK_URL=http://localhost:18080 ./keycloak/setup/init-keycloak.sh\n\n# Disable SSL for application realm\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:18080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:18080/admin/realms/mcp-gateway\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n\n# Get client credentials\nchmod +x keycloak/setup/get-all-client-credentials.sh\nKEYCLOAK_URL=http://localhost:18080 ./keycloak/setup/get-all-client-credentials.sh\n\n# Update .env with client secrets\ncat .oauth-tokens/keycloak-client-secrets.txt\nnano .env # Update KEYCLOAK_CLIENT_SECRET and KEYCLOAK_M2M_CLIENT_SECRET\n\n# Recreate containers with new credentials\n./build_and_run.sh --prebuilt --podman\n\n# 10. Setup users and service accounts\nchmod +x ./cli/bootstrap_user_and_m2m_setup.sh\nKEYCLOAK_URL=http://localhost:18080 ./cli/bootstrap_user_and_m2m_setup.sh\n\n# 11. Access registry (note the different port for Podman)\nopen http://localhost:8080 # macOS\n# xdg-open http://localhost:8080 # Linux\n# Login: admin / \n```\n\n> **Note for Apple Silicon:** Don't use `--prebuilt` with Podman on ARM64. Use `./build_and_run.sh --podman` instead. See [Podman on Apple Silicon Guide](podman-apple-silicon.md).\n\n**Podman Port Mapping:**\n- Main interface: `http://localhost:8080` (HTTP) or `https://localhost:8443` (HTTPS)\n- Registry API: `http://localhost:7860` (unchanged)\n- Keycloak: `http://localhost:18080` (instead of 8080)\n- All other internal services: unchanged ports\n\n## Installation on Amazon EC2\n\n### System Requirements\n\n**Minimum (Development)**:\n- EC2 Instance: `t3.large` (2 vCPU, 8GB RAM)\n- Storage: 20GB SSD\n- Network: Ports 80, 443, 7860, 8080 accessible\n\n**Recommended (Production)**:\n- EC2 Instance: `t3.2xlarge` (8 vCPU, 32GB RAM) \n- Storage: 50GB+ SSD\n- Network: Multi-AZ with load balancer\n\n### Detailed Setup Steps\n\n1. **Create Local Directories**\n ```bash\n mkdir -p ${HOME}/mcp-gateway/{servers,auth_server,secrets,logs}\n cp -r registry/servers ${HOME}/mcp-gateway/\n cp auth_server/scopes.yml ${HOME}/mcp-gateway/auth_server/\n ```\n\n2. **Configure Environment Variables**\n ```bash\n cp .env.example .env\n nano .env # Configure required values\n ```\n\n **Required Configuration:**\n - `KEYCLOAK_ADMIN_PASSWORD`: Keycloak admin password (if using Keycloak)\n - `COGNITO_USER_POOL_ID`: Amazon Cognito User Pool ID\n - `COGNITO_CLIENT_ID`: Cognito App Client ID\n - `COGNITO_CLIENT_SECRET`: Cognito App Client Secret\n - `AWS_REGION`: AWS region for Cognito\n\n3. **Generate Authentication Credentials**\n ```bash\n # Configure OAuth credentials\n cp credentials-provider/oauth/.env.example credentials-provider/oauth/.env\n nano credentials-provider/oauth/.env\n \n # Generate tokens and client configurations\n ./credentials-provider/generate_creds.sh\n ```\n\n4. **Install Dependencies**\n ```bash\n # Install uv (Python package manager)\n curl -LsSf https://astral.sh/uv/install.sh | sh\n source $HOME/.local/bin/env\n uv venv --python 3.14 && source .venv/bin/activate\n \n # Install Docker\n sudo apt-get update\n sudo apt-get install --reinstall docker.io -y\n sudo apt-get install -y docker-compose\n sudo usermod -a -G docker $USER\n newgrp docker\n ```\n\n5. **Deploy Services**\n ```bash\n ./build_and_run.sh\n ```\n\n## Podman Installation (Rootless Containers)\n\nPodman is a daemonless container engine that provides rootless container execution, making it ideal for macOS and environments where Docker requires privileged access.\n\n### Benefits of Podman\n\n- ✅ **Rootless Execution**: No sudo or privileged ports required\n- ✅ **macOS Native**: Works seamlessly with Podman Desktop on macOS\n- ✅ **Security**: Enhanced container isolation without root privileges\n- ✅ **Compatibility**: Drop-in replacement for Docker with similar CLI commands\n\n### Installation on macOS\n\n**Option 1: Podman Desktop (Recommended)**\n\n```bash\n# Install via Homebrew\nbrew install podman-desktop\n\n# Or download directly from:\n# https://podman-desktop.io/\n```\n\n**Option 2: Podman CLI Only**\n\n```bash\n# Install Podman\nbrew install podman\n\n# Initialize Podman machine\npodman machine init --cpus 4 --memory 8192 --disk-size 50\npodman machine start\n\n# Verify installation\npodman --version\npodman compose version\n```\n\n### Installation on Linux\n\n```bash\n# Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install -y podman podman-compose\n\n# Fedora/RHEL\nsudo dnf install -y podman podman-compose\n\n# Arch Linux\nsudo pacman -S podman podman-compose\n\n# Verify installation\npodman --version\npodman compose version\n```\n\n### Deploying with Podman\n\n```bash\n# Navigate to repository\ncd mcp-gateway-registry\n\n# Configure environment\ncp .env.example .env\nnano .env # Configure required values\n# Important: Set KEYCLOAK_URL=http://localhost:18080 for Podman\n\n# Deploy with Podman (explicit)\n./build_and_run.sh --prebuilt --podman\n\n# Apple Silicon: Use without --prebuilt\n# ./build_and_run.sh --podman\n\n# Or let the script auto-detect (will use Podman if Docker not available)\n./build_and_run.sh --prebuilt\n```\n\nAfter initial deployment, you must complete the MongoDB and Keycloak initialization steps. See the [Podman Installation Quick Start](#podman-installation-rootless-alternative) above for the complete sequence including:\n- MongoDB initialization (`podman compose up mongodb-init`)\n- Keycloak realm setup (using port 18080)\n- Client credential retrieval and .env update\n- Container recreation to apply credentials\n- User and service account setup\n\n> **Apple Silicon Warning:** Don't use `--prebuilt` with Podman on Apple Silicon Macs. Use `./build_and_run.sh --podman` instead. See [Podman on Apple Silicon Guide](podman-apple-silicon.md).\n\n### Accessing Services with Podman\n\n**Important Port Differences:**\n\nPodman uses non-privileged host ports to avoid requiring root access:\n\n| Service | Docker Port | Podman Port | Description |\n|---------|-------------|-------------|-------------|\n| Main UI (HTTP) | `http://localhost` | `http://localhost:8080` | Web interface |\n| Main UI (HTTPS) | `https://localhost` | `https://localhost:8443` | Secure web interface |\n| Registry API | `http://localhost:7860` | `http://localhost:7860` | API endpoint (unchanged) |\n| Auth Server | `http://localhost:8888` | `http://localhost:8888` | Auth service (unchanged) |\n| Keycloak | `http://localhost:8080` | `http://localhost:18080` | IdP (Podman uses 18080 because 8080 is used by the Registry UI) |\n| Prometheus | `http://localhost:9090` | `http://localhost:9090` | Metrics (unchanged) |\n| Grafana | `http://localhost:3000` | `http://localhost:3000` | Dashboards (unchanged) |\n\n**Access the registry:**\n```bash\n# With Podman\nopen http://localhost:8080\n\n# With Docker\nopen http://localhost\n```\n\n### Podman-Specific Configuration\n\nThe deployment uses `docker-compose.podman.yml` when using Podman, which:\n\n1. **Remaps privileged ports**: Maps container ports 80→8080 and 443→8443 on the host\n2. **Adds SELinux labels**: Adds `:z` mount options for SELinux compatibility (Linux)\n3. **Maintains compatibility**: All internal service-to-service communication unchanged\n\n### Troubleshooting Podman\n\n**Issue: Permission denied on volume mounts**\n\n```bash\n# Ensure directories exist with proper permissions\nmkdir -p ${HOME}/mcp-gateway/{servers,agents,models,logs,security_scans,auth_server,ssl}\nchmod -R 755 ${HOME}/mcp-gateway\n```\n\n**Issue: Podman machine not starting (macOS)**\n\n```bash\n# Reset Podman machine\npodman machine stop\npodman machine rm\npodman machine init --cpus 4 --memory 8192 --disk-size 50\npodman machine start\n```\n\n**Issue: Port conflicts**\n\n```bash\n# Check what's using ports 8080 or 8443\nlsof -i :8080\nlsof -i :8443\n\n# Stop conflicting services or use different ports by editing docker-compose.podman.yml\n```\n\n**Issue: Podman compose command not found**\n\n```bash\n# Install podman-compose separately\npip install podman-compose\n\n# Or use podman-compose wrapper\nbrew install podman-compose\n```\n\n### HTTPS Configuration\n\nBy default, MCP Gateway runs on HTTP (port 80). To enable HTTPS for production deployments:\n\n#### 1. Obtain SSL Certificates\n\n**Option A: Let's Encrypt (Recommended)**\n```bash\n# Install certbot\nsudo apt-get update\nsudo apt-get install -y certbot\n\n# Get certificate (requires domain and port 80 accessible)\nsudo certbot certonly --standalone -d your-domain.com\n```\n\n**Option B: Commercial CA**\nPurchase SSL certificate from a trusted Certificate Authority.\n\n#### 2. Copy Certificates to Expected Location\n\nMCP Gateway expects SSL certificates at `${HOME}/mcp-gateway/ssl/`. The `build_and_run.sh` script will automatically set up the proper directory structure.\n\n```bash\n# Create the ssl directory structure\nmkdir -p ${HOME}/mcp-gateway/ssl/certs\nmkdir -p ${HOME}/mcp-gateway/ssl/private\n\n# Copy your certificates to the expected location\n# Replace paths below with your actual certificate locations\ncp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/fullchain.pem\ncp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/privkey.pem\n\n# Set proper permissions\nchmod 644 ${HOME}/mcp-gateway/ssl/certs/fullchain.pem\nchmod 600 ${HOME}/mcp-gateway/ssl/private/privkey.pem\n```\n\n**Note**: If SSL certificates are not present at `${HOME}/mcp-gateway/ssl/certs/fullchain.pem` and `${HOME}/mcp-gateway/ssl/private/privkey.pem`, the MCP Gateway will automatically run in HTTP-only mode.\n\n#### 3. Configure Security Group\n\n- Enable TCP port 443 for HTTPS access\n- Restrict access to authorized IP ranges\n- Keep port 80 open for HTTP and Let's Encrypt renewals\n\n#### 4. Deploy and Verify\n\n```bash\n# Start/restart the services\n./build_and_run.sh\n\n# Check logs for SSL certificate detection\ndocker compose logs registry | grep -i ssl\n\n# Expected output:\n# \"SSL certificates found - HTTPS enabled\"\n# \"HTTPS server will be available on port 443\"\n\n# Test HTTPS access\ncurl https://your-domain.com\n```\n\n#### Certificate Renewal (Let's Encrypt)\n\nLet's Encrypt certificates expire after 90 days. Set up automatic renewal:\n\n```bash\n# Add to crontab\nsudo crontab -e\n\n# Add this line (checks twice daily, renews if needed)\n0 0,12 * * * certbot renew --quiet && cp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/fullchain.pem && cp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/privkey.pem && docker compose restart registry\n```\n\n#### Troubleshooting\n\n**HTTPS not working?**\n- Check certificate files exist: `ls -la ${HOME}/mcp-gateway/ssl/certs/ ${HOME}/mcp-gateway/ssl/private/`\n- Verify certificates are present: `${HOME}/mcp-gateway/ssl/certs/fullchain.pem` and `${HOME}/mcp-gateway/ssl/private/privkey.pem`\n- Check container logs: `docker compose logs registry | grep -i ssl`\n- Verify port 443 is accessible: `sudo netstat -tlnp | grep 443`\n- Ensure certificates are from a trusted CA\n\n## Installation on Amazon EKS\n\nFor production Kubernetes deployments, see the [EKS deployment guide](https://github.com/aws-samples/amazon-eks-machine-learning-with-terraform-and-kubeflow/tree/master/examples/agentic/mcp-gateway-microservices).\n\n### Architecture Overview\n\n```mermaid\ngraph TB\n subgraph \"EKS Cluster\"\n subgraph \"Ingress\"\n ALB[Application Load Balancer]\n IC[Ingress Controller]\n end\n \n subgraph \"Application Pods\"\n RP[Registry Pod]\n AS[Auth Server Pod]\n NG[Nginx Pod]\n end\n \n subgraph \"MCP Servers\"\n MS1[MCP Server 1]\n MS2[MCP Server 2]\n MSN[MCP Server N]\n end\n end\n \n subgraph \"AWS Services\"\n COG[Amazon Cognito]\n CW[CloudWatch]\n ECR[Amazon ECR]\n end\n \n ALB --> IC\n IC --> RP\n IC --> AS\n IC --> NG\n NG --> MS1\n NG --> MS2\n NG --> MSN\n AS --> COG\n RP --> CW\n```\n\n### Key Benefits of EKS Deployment\n\n- **Multi-AZ Support**: Pod distribution across availability zones\n- **Auto Scaling**: Horizontal pod autoscaling based on metrics\n- **Service Mesh**: Istio integration for advanced traffic management\n- **Observability**: Native integration with CloudWatch and Prometheus\n- **Security**: Pod security policies and network policies\n\n## Post-Installation\n\n### Verify Installation\n\n1. **Check Service Status**\n ```bash\n docker-compose ps\n docker-compose logs -f\n ```\n\n2. **Test Web Interface**\n - Navigate to `http://localhost:7860`\n - Login with admin credentials\n - Verify MCP server health status\n\n3. **Test Authentication**\n ```bash\n cd tests\n ./mcp_cmds.sh ping\n ```\n\n### Configure AI Coding Assistants\n\n1. **Generate Client Configurations**\n ```bash\n ./credentials-provider/generate_creds.sh\n ls .oauth-tokens/ # View generated configurations\n ```\n\n2. **Setup VS Code**\n ```bash\n cp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json\n ```\n\n3. **Setup Roo Code**\n ```bash\n cp .oauth-tokens/mcp.json ~/.vscode/mcp-settings.json\n ```\n\nFor detailed AI assistant setup, see [AI Coding Assistants Setup Guide](ai-coding-assistants-setup.md).\n\n## Troubleshooting\n\n### Common Issues\n\n**Services won't start:**\n```bash\n# Check Docker daemon\nsudo systemctl status docker\n\n# Check environment variables\ncat .env | grep -v SECRET\n\n# View detailed logs\ndocker-compose logs --tail=50\n```\n\n**Authentication failures:**\n```bash\n# Verify Cognito configuration\naws cognito-idp describe-user-pool --user-pool-id YOUR_POOL_ID\n\n# Test credential generation\ncd credentials-provider && ./generate_creds.sh --verbose\n```\n\n**Network connectivity issues:**\n```bash\n# Check port availability\nsudo netstat -tlnp | grep -E ':(80|443|7860|8080)'\n\n# Test internal services\ncurl -v http://localhost:7860/health\n```\n\nFor more troubleshooting help, see [Troubleshooting Guide](troubleshooting.md).\n\n## Next Steps\n\n- [Authentication Setup](auth.md) - Configure identity providers\n- [AI Assistant Integration](ai-coding-assistants-setup.md) - Setup development tools\n- [AWS ECS Deployment](../terraform/aws-ecs/README.md) - Multi-instance configuration\n- [API Reference](registry_api.md) - Programmatic management" }, { "path": "docs/jwt-token-vending.md", "content": "# JWT Token Vending Service for MCP Gateway\n\nThe JWT Token Vending Service provides a user-friendly mechanism for generating personal access tokens _without the use of an external IdP_ that can be used for programmatic access to MCP servers. This service bridges the gap between human authentication (web UI sessions) and machine authentication (JWT tokens), enabling users to create tokens with scoped permissions for automation, scripting, and agent access.\n\n## The Challenge with Token Management in Enterprise MCP Deployments\n\nIn enterprise scenarios, users often need to provide programmatic access to MCP servers for various automation tasks, CI/CD pipelines, and AI agents. Traditional approaches present several challenges:\n\n- **Manual Token Management**: Requiring users to manually generate M2M credentials through Amazon Cognito or other IdPs creates friction and security risks\n- **Scope Complexity**: Users need to understand complex scope configurations and may accidentally grant excessive permissions\n- **Token Lifecycle**: No centralized way to manage token expiration, renewal, or revocation\n- **Audit Trail**: Difficulty tracking which tokens were generated by whom and for what purpose\n\n## A Solution with Integrated Token Vending\n\nThe JWT Token Vending Service integrates directly with the existing MCP Gateway authentication infrastructure, allowing users to generate scoped JWT tokens through a familiar web interface.\n\nHere is an architecture diagram showing how the token vending service integrates with the existing system:\n\n```mermaid\ngraph TB\n %% Users and Token Generation Flow\n subgraph UserFlow[\"User Token Generation Flow\"]\n direction TB\n User[User
Web UI Session]\n TokenUI[Token Generation
Web Interface]\n User -->|Authenticated Session| TokenUI\n end\n \n %% Core Infrastructure\n subgraph Infrastructure[\"MCP Gateway & Registry Infrastructure\"]\n direction TB\n Nginx[\"Nginx
Reverse Proxy\"]\n AuthServer[\"Auth Server
(Enhanced with Token Vending)\"]\n Registry[\"Registry
Web UI + Token Generation\"]\n RegistryMCP[\"Registry
MCP Server\"]\n end\n \n %% Generated Token Usage\n subgraph TokenUsage[\"Token Usage\"]\n direction TB\n Agent[AI Agent
with Generated Token]\n Script[Automation Script
with Generated Token]\n Pipeline[CI/CD Pipeline
with Generated Token]\n end\n \n %% Identity Provider\n IdP[Identity Provider
Amazon Cognito]\n \n %% MCP Server Farm\n subgraph MCPFarm[\"MCP Server Farm\"]\n direction TB\n MCP1[MCP Server 1
CurrentTime]\n MCP2[MCP Server 2
FinInfo]\n MCP3[MCP Server 3
Custom]\n MCPn[MCP Server n
...]\n end\n \n %% Token Generation Flow\n TokenUI -->|POST /api/tokens/generate
with user context| Registry\n Registry -->|POST /internal/tokens
with user scopes| AuthServer\n AuthServer -->|Self-signed JWT
with HMAC-SHA256| Registry\n Registry -->|Display token
to user| TokenUI\n \n %% Token Usage Flow\n Agent -->|MCP requests
with Bearer token| Nginx\n Script -->|API calls
with Bearer token| Nginx\n Pipeline -->|Automated access
with Bearer token| Nginx\n \n %% Internal routing and validation\n Nginx -->|Route /mcpgw/*
Auth validation| AuthServer\n Nginx -->|Route /mcpgw/*
Tool discovery| RegistryMCP\n Nginx -->|Route /tokens
Token UI| Registry\n Nginx -->|Route /server1/*
Proxy to MCP servers| MCP1\n Nginx -->|Route /server2/*
Proxy to MCP servers| MCP2\n Nginx -->|Route /serverN/*
Proxy to MCP servers| MCP3\n Nginx -->|Route /serverN/*
Proxy to MCP servers| MCPn\n \n %% Auth flows\n IdP -.->|User session validation
Group/scope mapping| AuthServer\n AuthServer -.->|Self-signed JWT validation
Scope enforcement| AuthServer\n \n %% Styling\n classDef userStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px\n classDef tokenStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px\n classDef agentStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px\n classDef idpStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px\n classDef nginxStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n classDef authStyle fill:#ffebee,stroke:#c62828,stroke-width:2px\n classDef registryStyle fill:#fff8e1,stroke:#f57f17,stroke-width:2px\n classDef mcpStyle fill:#e3f2fd,stroke:#1976d2,stroke-width:2px\n \n class UserFlow userStyle\n class User userStyle\n class TokenUI tokenStyle\n class TokenUsage agentStyle\n class Agent,Script,Pipeline agentStyle\n class IdP idpStyle\n class Nginx nginxStyle\n class AuthServer authStyle\n class Registry,RegistryMCP registryStyle\n class MCP1,MCP2,MCP3,MCPn mcpStyle\n```\n\n### Architecture Components for Token Vending\n\nThe JWT Token Vending Service extends the existing MCP Gateway infrastructure with new capabilities:\n\n#### Enhanced Registry Web UI\n- **Token Generation Interface**: User-friendly form for creating JWT tokens with custom scopes and expiration\n- **Scope Validation**: Real-time validation ensuring requested scopes are subset of user's current permissions\n- **Token Display**: Secure, one-time display of generated tokens with copy functionality and usage instructions\n\n#### Enhanced Auth Server\n- **Internal Token Endpoint**: New `/internal/tokens` endpoint for generating self-signed JWT tokens\n- **Scope Validation Logic**: Ensures generated tokens cannot exceed user's current permissions\n- **Rate Limiting**: Prevents token generation abuse with configurable limits per user\n- **Self-Signed JWT Support**: Validates both Cognito tokens and internally generated tokens\n\n#### Token Security Features\n- **HMAC-SHA256 Signing**: Uses shared secret key for token signing and validation\n- **Scope Inheritance**: Generated tokens can have same or fewer permissions than user's current scopes\n- **Configurable Expiration**: Token lifetime from 1-24 hours with 8-hour default\n- **Unique Token IDs**: Each token has a unique identifier for potential tracking and revocation\n\nAt a high-level the token generation and usage flow works as follows:\n\n```mermaid\nsequenceDiagram\n participant User\n participant Browser\n participant Registry as Registry
Web UI\n participant AuthServer as Auth Server\n participant Agent\n participant Gateway as Gateway
(Nginx)\n participant MCP as MCP Server\n\n %% Token Generation Flow\n Note over User,AuthServer: Token Generation Flow\n User->>Browser: Navigate to /tokens\n Browser->>Registry: GET /tokens with session cookie\n Registry->>Registry: Validate user session + extract scopes\n Registry->>Browser: Token generation form\n\n User->>Browser: Configure token (scopes, expiration, description)\n Browser->>Registry: POST /api/tokens/generate\n Registry->>Registry: Validate requested scopes ⊆ user scopes\n Registry->>AuthServer: POST /internal/tokens with user context\n \n AuthServer->>AuthServer: Rate limit check (10/hour/user)\n AuthServer->>AuthServer: Generate JWT with HMAC-SHA256\n AuthServer->>Registry: Return signed JWT token\n Registry->>Browser: Display token with copy functionality\n Browser->>User: Show token + usage instructions\n\n %% Token Usage Flow\n Note over Agent,MCP: Token Usage Flow\n User->>Agent: Provide generated JWT token\n Agent->>Gateway: MCP request with Bearer token\n Gateway->>AuthServer: Validate token + extract scopes\n \n alt Self-Signed Token\n AuthServer->>AuthServer: Detect issuer: \"mcp-auth-server\"\n AuthServer->>AuthServer: Validate HMAC-SHA256 signature\n AuthServer->>AuthServer: Extract scopes + enforce access\n else Cognito Token (Fallback)\n AuthServer->>AuthServer: Standard Cognito validation\n end\n \n alt Sufficient Permissions\n AuthServer->>Gateway: 200 OK + allowed scopes\n Gateway->>MCP: Forward MCP request\n MCP->>Gateway: MCP response\n Gateway->>Agent: MCP response\n else Insufficient Permissions\n AuthServer->>Gateway: 403 Access Denied\n Gateway->>Agent: 403 Access Denied\n end\n```\n\n1. A **User** authenticates to the Registry web UI using their existing session (derived from Cognito OAuth or M2M flow) which contains their current scopes and permissions.\n\n2. The **User** navigates to the token generation interface at `/tokens` and configures their desired token parameters including optional custom scopes (must be subset of current scopes), expiration time (1-24 hours), and description.\n\n3. The **Registry** validates the user's session, ensures requested scopes are a subset of the user's current permissions, and calls the Auth Server's internal token generation endpoint with the user context and token parameters.\n\n4. The **Auth Server** performs security checks (rate limiting, scope validation, expiration limits) and generates a self-signed JWT token using HMAC-SHA256 with the shared secret key. The token contains standard JWT claims plus MCP-specific metadata.\n\n5. The **Registry** displays the generated token to the user with copy functionality, usage instructions, and security warnings. The token is shown only once for security.\n\n6. The **User** saves the token securely and provides it to their **Agent** or automation script for programmatic access to MCP servers.\n\n7. When the **Agent** makes MCP requests, it includes the generated JWT token in the Authorization header. The **Gateway** forwards the request to the **Auth Server** for validation.\n\n8. The **Auth Server** detects self-signed tokens by the issuer claim, validates the HMAC-SHA256 signature using the shared secret, and enforces scope-based access control using the same logic as Cognito tokens.\n\n9. If the token is valid and the requested operation is within the token's scope, the **Gateway** forwards the request to the appropriate **MCP Server**. Otherwise, it returns a 403 Access Denied response.\n\nThe above implementation provides a seamless way for users to generate programmatic access tokens without requiring direct interaction with the Identity Provider, while maintaining the same security guarantees and scope enforcement as the existing authentication system.\n\n## Agent Integration\n\nThe JWT Token Vending Service integrates seamlessly with existing agent authentication patterns through enhanced command-line support:\n\n### Enhanced Agent Command Line Interface\n\nThe agent now supports direct JWT token usage through a new `--jwt-token` parameter:\n\n```bash\n# Method 1: Direct token usage\npython agent.py \\\n --jwt-token \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\" \\\n --message \"What is the current time in New York?\"\n\n# Method 2: Environment variable\nexport JWT_TOKEN=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\npython agent.py --jwt-token \"$JWT_TOKEN\" --message \"List available servers\"\n\n# Method 3: Token from file\necho \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\" > ~/.mcp/jwt_token\npython agent.py --jwt-token \"$(cat ~/.mcp/jwt_token)\" --message \"Help me analyze data\"\n```\n\n### Token Storage Best Practices\n\n#### Secure Storage Options\n```bash\n# Option 1: Encrypted environment file\necho \"JWT_TOKEN=your_token_here\" | gpg --encrypt > ~/.mcp/token.gpg\n\n# Option 2: System keyring (macOS)\nsecurity add-generic-password -a \"$USER\" -s \"mcp-jwt-token\" -w \"your_token_here\"\n\n# Option 3: Secure file with restricted permissions\necho \"your_token_here\" > ~/.mcp/jwt_token\nchmod 600 ~/.mcp/jwt_token\n```\n\n#### CI/CD Integration\n```yaml\n# GitHub Actions example\nname: MCP Agent Workflow\non: [push]\njobs:\n run-agent:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n - name: Run MCP Agent\n env:\n JWT_TOKEN: ${{ secrets.MCP_JWT_TOKEN }}\n run: |\n python agent.py --jwt-token \"$JWT_TOKEN\" --message \"Deploy analysis\"\n```\n\n## Security Features and Considerations\n\n### Token Security Implementation\n\n#### Rate Limiting\n- **Per-User Limits**: Maximum 10 tokens per user per hour\n- **Sliding Window**: Uses hourly time slots for rate calculation\n- **Memory-Based**: Simple in-memory counter with automatic cleanup\n- **Configurable**: Limits adjustable via environment variables\n\n#### Scope Inheritance and Validation\n- **Subset Validation**: Generated tokens cannot exceed user's current permissions\n- **Real-Time Validation**: Scope checks performed at generation time\n- **Default Behavior**: Empty scope request defaults to user's full scope set\n- **JSON Validation**: Custom scope uploads validated for proper JSON format\n\n#### Token Lifecycle Management\n- **Configurable Expiration**: 1-24 hour range with 8-hour default\n- **No Refresh**: Tokens cannot be refreshed, must be regenerated\n- **Unique Identifiers**: Each token has a unique `jti` claim for tracking\n- **Self-Contained**: All authorization data embedded in token\n\n### Cryptographic Implementation\n\n#### HMAC-SHA256 Signing\n```python\n# Token generation process\npayload = {\n \"iss\": \"mcp-auth-server\",\n \"aud\": \"mcp-registry\", \n \"sub\": username,\n \"scope\": \" \".join(requested_scopes),\n \"exp\": current_time + (expires_in_hours * 3600),\n \"iat\": current_time,\n \"jti\": str(uuid.uuid4()),\n \"token_use\": \"access\",\n \"client_id\": \"user-generated\",\n \"token_type\": \"user_generated\"\n}\n\n# Sign with shared secret\naccess_token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')\n```\n\n#### Token Validation Process\n```python\n# Validation with issuer detection\ntry:\n # Quick check for self-signed tokens\n unverified_claims = jwt.decode(token, options={\"verify_signature\": False})\n if unverified_claims.get('iss') == 'mcp-auth-server':\n # Validate self-signed token\n claims = jwt.decode(token, SECRET_KEY, algorithms=['HS256'], \n issuer='mcp-auth-server', audience='mcp-registry')\n scopes = claims.get('scope', '').split()\n return {'valid': True, 'scopes': scopes, 'method': 'self_signed'}\n else:\n # Fall back to Cognito validation\n return validate_cognito_token(token)\nexcept jwt.InvalidTokenError:\n return {'valid': False, 'error': 'Invalid token'}\n```\n\n### Security Best Practices\n\n#### For Users\n1. **Minimal Scopes**: Generate tokens with only required permissions\n2. **Short Expiration**: Use shortest practical token lifetime\n3. **Secure Storage**: Store tokens in encrypted or protected locations\n4. **Regular Rotation**: Regenerate tokens periodically\n5. **Monitor Usage**: Track token usage in application logs\n\n#### For Administrators\n1. **Audit Logging**: Monitor token generation patterns and frequency\n2. **Scope Configuration**: Regularly review and update scope definitions\n3. **Rate Limit Tuning**: Adjust rate limits based on usage patterns\n4. **Key Management**: Protect the shared SECRET_KEY used for signing\n5. **Access Reviews**: Periodically review user permissions and group memberships\n\n### Threat Model and Mitigations\n\n#### Token Theft\n- **Risk**: Stolen tokens provide unauthorized access\n- **Mitigation**: Short expiration times, scope limitations, audit logging\n\n#### Scope Escalation\n- **Risk**: Users attempt to generate tokens with excessive permissions\n- **Mitigation**: Strict subset validation, real-time scope checking\n\n#### Rate Limit Bypass\n- **Risk**: Automated token generation for abuse\n- **Mitigation**: Per-user rate limiting, monitoring, account lockout policies\n\n#### Replay Attacks\n- **Risk**: Intercepted tokens used maliciously\n- **Mitigation**: HTTPS enforcement, short token lifetimes, unique token IDs\n\n## Implementation Configuration\n\n### Environment Variables\n```bash\n# Token generation settings\nMAX_TOKEN_LIFETIME_HOURS=24 # Maximum token lifetime\nDEFAULT_TOKEN_LIFETIME_HOURS=8 # Default token lifetime\nMAX_TOKENS_PER_USER_PER_HOUR=10 # Rate limiting\n\n# JWT settings\nJWT_ISSUER=\"mcp-auth-server\" # Token issuer\nJWT_AUDIENCE=\"mcp-registry\" # Token audience\nSECRET_KEY=\"your-shared-secret\" # HMAC signing key (must be shared)\n```\n\n### Scope Configuration\nGenerated tokens inherit scope validation from the existing `scopes.yml` configuration:\n\n```yaml\n# Example scope allowing read access to time servers\nmcp-servers-time/read:\n - server: \"currenttime\"\n methods: [\"initialize\", \"tools/list\", \"tools/call\"]\n tools: [\"current_time_by_timezone\", \"current_time_utc\"]\n\n# Example scope for financial data access \nmcp-servers-finance/read:\n - server: \"fininfo\"\n methods: [\"initialize\", \"tools/list\", \"tools/call\"]\n tools: [\"get_stock_price\", \"get_market_data\"]\n\n# Admin scope with full access\nmcp-registry-admin:\n - server: \"*\"\n methods: [\"*\"]\n tools: [\"*\"]\n```\n\n### User Interface Configuration\n\nThe token generation interface provides:\n\n#### Token Configuration Options\n- **Description**: Optional human-readable token description\n- **Expiration**: Dropdown with 1, 8, and 24-hour options\n- **Scope Method**: Radio buttons for \"Use current scopes\" or \"Custom JSON\"\n- **Custom Scopes**: JSON textarea for advanced users\n\n#### User Experience Features\n- **Current Permissions Display**: Shows user's active scopes as badges\n- **Real-time Validation**: Client-side validation of JSON scope format\n- **Copy Functionality**: Multiple copy methods with fallbacks for different browsers\n- **Usage Instructions**: Clear examples of how to use the generated token\n- **Security Warnings**: Prominent warnings about token storage and sharing\n\nBy implementing the JWT Token Vending Service, organizations can provide their users with a secure, user-friendly way to generate programmatic access tokens while maintaining security controls and comprehensive audit capabilities. The service seamlessly integrates with existing MCP Gateway infrastructure and provides a foundation for advanced token management features.\n\n## Integration with Token Refresh Service\n\nThe JWT Token Vending Service works seamlessly with the [Automated Token Refresh Service](token-refresh-service.md) to provide comprehensive token lifecycle management:\n\n### Automatic Token Monitoring\n\nOnce tokens are generated through the vending service, the token refresh service automatically:\n\n- **Monitors expiration times** for all generated tokens\n- **Proactively refreshes** tokens before they expire (configurable buffer time)\n- **Updates MCP client configurations** with fresh tokens\n- **Maintains continuous authentication** without user intervention\n\n### MCP Client Configuration\n\nThe token refresh service automatically generates MCP client configurations that include tokens from the vending service:\n\n- **VS Code Extensions** - Automatically configured with refreshed tokens\n- **Claude Code/Roocode** - Real-time token updates for coding assistants\n- **Custom MCP Clients** - Standard configuration format for any MCP client\n\n### Enhanced Security Model\n\nThe combination of both services provides:\n\n- **Short-lived primary tokens** from the vending service (1-24 hours)\n- **Automatic refresh capability** using secure refresh tokens\n- **Zero-downtime token rotation** for continuous service availability\n- **Centralized token lifecycle management** with comprehensive audit trails\n\n### Usage Pattern\n\n1. **Generate Initial Token** - Use the JWT Token Vending Service web interface\n2. **Automatic Refresh** - Token refresh service monitors and refreshes tokens\n3. **Client Integration** - MCP clients automatically use refreshed tokens\n4. **Continuous Operation** - No manual intervention required for token management\n\nFor detailed setup and configuration of the token refresh service, see the [Token Refresh Service Documentation](token-refresh-service.md). " }, { "path": "docs/keycloak-integration.md", "content": "# Keycloak Integration Documentation\n\n## Overview\n\nThis document provides comprehensive guidance for implementing Keycloak authentication in the MCP Gateway, including design aspects, operational procedures, configuration parameters, and management scripts.\n\n## Table of Contents\n\n1. [Architecture & Design](#architecture--design)\n2. [Environment Configuration](#environment-configuration)\n3. [Setup & Installation](#setup--installation)\n4. [Operational Procedures](#operational-procedures)\n5. [Agent Management](#agent-management)\n6. [Monitoring & Troubleshooting](#monitoring--troubleshooting)\n7. [Security Considerations](#security-considerations)\n8. [Cleanup Procedures](#cleanup-procedures)\n\n## Architecture & Design\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant Gateway as MCP Gateway\n participant Auth as Auth Server\n participant KC as Keycloak\n participant MCP as MCP Server\n\n Agent->>Gateway: Request with JWT Token\n Gateway->>Auth: Validate Token\n Auth->>KC: Verify JWT Signature & Claims\n KC-->>Auth: Token Valid + Groups\n Auth->>Auth: Map Groups to Scopes\n Auth-->>Gateway: Authorization Success\n Gateway->>MCP: Forward Request\n MCP-->>Gateway: Response\n Gateway-->>Agent: Response\n```\n\n### Service Account Architecture\n\n#### Production Architecture (Recommended)\n```\nAI Agent A → Service Account A (agent-{agent-id}-m2m) → Group: mcp-servers-restricted/unrestricted\nAI Agent B → Service Account B (agent-{agent-id}-m2m) → Group: mcp-servers-restricted/unrestricted \nAI Agent C → Service Account C (agent-{agent-id}-m2m) → Group: mcp-servers-restricted/unrestricted\n ↓\n Individual JWT Tokens per Agent\n ↓\n Group-based Authorization + Individual Tracking\n```\n\n**Benefits:**\n- ✅ Individual audit trails per AI agent\n- ✅ Security isolation between agents\n- ✅ Granular access control\n- ✅ Compliance ready (SOC2, ISO27001)\n- ✅ Per-agent metrics and monitoring\n\n\n### Keycloak Components\n\n#### Realm Configuration\n- **Realm Name**: `mcp-gateway`\n- **Purpose**: Isolated authentication domain for MCP Gateway\n- **Settings**: JWT tokens, group mappings, client configurations\n\n#### Client Configuration\n- **Client ID**: `mcp-gateway-m2m`\n- **Client Type**: Confidential (with secret)\n- **Grant Types**: `client_credentials` (Machine-to-Machine)\n- **Service Accounts**: Enabled\n- **Standard/Implicit Flow**: Disabled (security best practice)\n\n#### Group Structure\n```\nmcp-gateway (realm)\n├── mcp-servers-unrestricted (group)\n│ ├── Scopes: mcp-servers-unrestricted/read, mcp-servers-unrestricted/execute\n│ └── Access: Full access to all MCP servers\n└── mcp-servers-restricted (group)\n ├── Scopes: mcp-servers-restricted/read, mcp-servers-restricted/execute\n └── Access: Limited access to approved MCP servers\n```\n\n## Environment Configuration\n\n### Required Environment Variables\n\n#### 1. Docker Compose (.env)\n```bash\n# Keycloak Database Configuration\nKEYCLOAK_DB_VENDOR=postgres\nKEYCLOAK_DB_ADDR=postgres\nKEYCLOAK_DB_DATABASE=keycloak\nKEYCLOAK_DB_USER=keycloak\nKEYCLOAK_DB_PASSWORD=\n\n# Keycloak Admin Configuration\nKEYCLOAK_ADMIN=admin\nKEYCLOAK_ADMIN_PASSWORD=\n\n# Keycloak Runtime Configuration\nKEYCLOAK_HOSTNAME=mcpgateway.ddns.net\nKEYCLOAK_HOSTNAME_STRICT=false\nKEYCLOAK_HOSTNAME_STRICT_HTTPS=false\nKC_PROXY=edge\nKC_HTTP_ENABLED=true\n\n# PostgreSQL Database Configuration\nPOSTGRES_DB=keycloak\nPOSTGRES_USER=keycloak\nPOSTGRES_PASSWORD=\n```\n\n#### 2. Auth Server Configuration (.env or docker-compose)\n```bash\n# Authentication Provider Selection\nAUTH_PROVIDER=keycloak\n\n# Keycloak Connection Details\nKEYCLOAK_URL=https://mcpgateway.ddns.net\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_CLIENT_SECRET=\n\n# M2M Client Configuration (optional, defaults to main client)\nKEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_M2M_CLIENT_SECRET=\n\n```\n\n#### 3. Credentials Provider Configuration\n```bash\n# Token Storage Configuration\nOAUTH_TOKENS_DIR=.oauth-tokens\n\n# Keycloak M2M Token Configuration\nKEYCLOAK_URL=https://mcpgateway.ddns.net/keycloak\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_CLIENT_SECRET=\n\n# Token Refresh Settings\nTOKEN_REFRESH_THRESHOLD=60 # Refresh when less than 60 seconds remaining\nTOKEN_CACHE_TTL=300 # Cache tokens for 300 seconds (5 minutes)\n```\n\n#### 4. Agent-Specific Configuration (per agent)\n```bash\n# Agent Identification\nAGENT_ID=sre-agent\nAGENT_TYPE=claude\nAGENT_VERSION=1.0.0\n\n# Keycloak Agent Configuration\nKEYCLOAK_AGENT_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_AGENT_SERVICE_ACCOUNT=agent-sre-agent-m2m\nKEYCLOAK_AGENT_GROUP=mcp-servers-unrestricted\n\n# Token File Location\nAGENT_TOKEN_FILE=.oauth-tokens/agent-sre-agent.json\n```\n\n### Configuration File Templates\n\n#### .env.keycloak (Main Configuration)\n```bash\n# Keycloak Service Configuration\nKEYCLOAK_URL=https://mcpgateway.ddns.net\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_ADMIN=admin\nKEYCLOAK_ADMIN_PASSWORD=\n\n# Database Configuration\nKEYCLOAK_DB_VENDOR=postgres\nKEYCLOAK_DB_ADDR=postgres\nKEYCLOAK_DB_DATABASE=keycloak\nKEYCLOAK_DB_USER=keycloak\nKEYCLOAK_DB_PASSWORD=\n\n# M2M Client Configuration\nKEYCLOAK_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_CLIENT_SECRET=\nKEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_M2M_CLIENT_SECRET=\n\n# Proxy Configuration\nKC_PROXY=edge\nKC_HTTP_ENABLED=true\nKEYCLOAK_HOSTNAME_STRICT=false\nKEYCLOAK_HOSTNAME_STRICT_HTTPS=false\n```\n\n#### .env.auth-server (Auth Server Configuration)\n```bash\n# Authentication Provider\nAUTH_PROVIDER=keycloak\n\n# Keycloak Integration\nKEYCLOAK_URL=https://mcpgateway.ddns.net\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_CLIENT_SECRET=\n\n# Scopes Configuration\nSCOPES_CONFIG_PATH=scopes.yml\n\n# Logging Configuration\nLOG_LEVEL=INFO\nAUTH_LOG_FORMAT=%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\n```\n\n## Setup & Installation\n\n### Prerequisites\n\n1. **Docker & Docker Compose**\n ```bash\n docker --version\n docker-compose --version\n ```\n\n2. **Required Ports Available**\n - 8080: Keycloak HTTP\n - 8443: Keycloak HTTPS\n - 5432: PostgreSQL (internal)\n\n3. **External Dependencies**\n - Domain name with SSL certificate\n - PostgreSQL database access\n\n### Installation Steps\n\n#### 1. Initial Setup\n```bash\n# Clone repository and navigate to project\ncd /path/to/mcp-gateway-registry\n\n# Start prerequisite services\ndocker-compose up -d postgres\n\n# Wait for PostgreSQL to be ready\nsleep 10\n\n# Start Keycloak\ndocker-compose up -d keycloak\n\n# Wait for Keycloak to initialize (may take 2-3 minutes)\nsleep 120\n```\n\n#### 2. Environment Variables Setup\n```bash\n# MANDATORY: Set secure passwords before running any scripts\nexport KEYCLOAK_ADMIN_PASSWORD=\"$(openssl rand -base64 32)\"\nexport KEYCLOAK_DB_PASSWORD=\"$(openssl rand -base64 32)\"\n\n# Verify variables are set\necho \"Admin password set: ${KEYCLOAK_ADMIN_PASSWORD:+YES}\"\necho \"DB password set: ${KEYCLOAK_DB_PASSWORD:+YES}\"\n```\n\n#### 3. Keycloak Initialization\n```bash\n# Run the main initialization script\n./keycloak/setup/init-keycloak.sh\n\n# Expected output:\n# ✓ Realm 'mcp-gateway' created successfully\n# ✓ M2M client 'mcp-gateway-m2m' created successfully\n# ✓ Groups created successfully\n# ✓ Admin user setup complete\n```\n\n#### 4. Service Account Setup\n\n##### Production Setup (Individual Agents)\n```bash\n# Ensure environment variables are still set\nexport KEYCLOAK_ADMIN_PASSWORD=\"your-secure-password\"\n\n# Create service account for SRE agent with full access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id sre-agent \\\n --group mcp-servers-unrestricted\n\n# Create service account for travel assistant with restricted access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id travel-assistant \\\n --group mcp-servers-restricted\n\n# Create service account for developer productivity agent with full access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id dev-productivity \\\n --group mcp-servers-unrestricted\n```\n\n##### Development Setup (Single Account)\n```bash\n# Create single shared service account\n./keycloak/setup/setup-m2m-service-account.sh\n```\n\n#### 4. Start Complete Stack\n```bash\n# Start all services\ndocker-compose up -d\n\n# Verify all services are running\ndocker-compose ps\n\n# Check service health\ncurl -f http://localhost:8080/health/ready\n```\n\n#### 5. Generate Tokens\n\n##### Agent-Specific Tokens (Production)\n```bash\n# Generate token for SRE agent\nuv run python credentials-provider/keycloak/get_m2m_token.py --agent-id sre-agent\n\n# Generate token for Travel Assistant agent\nuv run python credentials-provider/keycloak/get_m2m_token.py --agent-id travel-assistant\n\n# Generate tokens for all agents\nuv run python credentials-provider/keycloak/get_m2m_token.py --all-agents\n\n# Verify token files created\nls -la .oauth-tokens/agent-*-m2m-token.json\n```\n\n##### Complete Credential Generation (Recommended)\n```bash\n# Generate all authentication tokens and MCP configurations\n./credentials-provider/generate_creds.sh\n\n# Start automatic token refresh service\n./start_token_refresher.sh\n\n# Verify token refresh is working\ntail -f token_refresher.log\n```\n\n#### 6. Validation & Testing\n```bash\n# Test agent-specific authentication\n./test-keycloak-mcp.sh --agent-id sre-agent\n\n# Test legacy authentication\n./test-keycloak-mcp.sh\n\n# Expected output:\n# ✓ Authentication successful\n# ✓ Session established with ID: xxx\n# ✓ Handshake completed\n# ✓ Ping successful\n# ✓ Tools list retrieved\n```\n\n## Operational Procedures\n\n### Starting Services\n\n#### Complete Stack Startup\n```bash\n# 1. Start database first\ndocker-compose up -d postgres\n\n# 2. Wait for database ready\nsleep 10\n\n# 3. Start Keycloak\ndocker-compose up -d keycloak\n\n# 4. Wait for Keycloak initialization\nsleep 120\n\n# 5. Start remaining services\ndocker-compose up -d\n\n# 6. Verify all services\ndocker-compose ps\ndocker-compose logs --tail=20\n```\n\n#### Service Health Checks\n```bash\n# Keycloak health\ncurl -f http://localhost:8080/health/ready\n\n# Auth server health\ncurl -f http://localhost:8000/health\n\n# PostgreSQL connection\ndocker-compose exec postgres pg_isready -U keycloak\n\n# Complete service status\ndocker-compose ps --format table\n```\n\n### Token Management\n\n#### Token Generation\n```bash\n# Generate new agent token\nuv run python credentials-provider/keycloak/get_m2m_token.py --agent-id \n\n# Generate tokens for all agents\nuv run python credentials-provider/keycloak/get_m2m_token.py --all-agents\n\n# Use complete credential generation workflow\n./credentials-provider/generate_creds.sh\n```\n\n#### Token Validation\n```bash\n# Check token expiration\ncat .oauth-tokens/agent--m2m-token.json | jq '.expires_at_human'\n\n# Verify token claims (decode JWT)\ncat .oauth-tokens/agent--m2m-token.json | jq -r '.access_token' | cut -d. -f2 | base64 -d | jq '.'\n\n# Test token authentication\n./test-keycloak-mcp.sh --agent-id \n\n# Check automatic token refresh status\ntail -20 token_refresher.log\n```\n\n#### Token Rotation Strategy\n```bash\n# Automatic token refresh service (recommended)\n./start_token_refresher.sh\n\n# The service will automatically:\n# - Refresh tokens every 5 minutes\n# - Regenerate MCP configuration files\n# - Handle both ingress and egress tokens\n\n# Manual token refresh if needed\nuv run python credentials-provider/keycloak/get_m2m_token.py --all-agents\n\n# Hourly health check\n0 * * * * /path/to/project/test-keycloak-mcp.sh --agent-id sre-agent --silent\n```\n\n### Configuration Updates\n\n#### Adding New Agents\n```bash\n# 1. Create new service account\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id new-agent-001 \\\n --group mcp-servers-restricted\n\n# 2. Generate initial token\nuv run python credentials-provider/keycloak/get_m2m_token.py --agent-id new-agent-001\n\n# 3. Test authentication\n./test-keycloak-mcp.sh --agent-id new-agent-001\n\n# 4. Update monitoring and rotation scripts\n```\n\n#### Modifying Agent Permissions\n```bash\n# Access Keycloak admin console\nopen https://mcpgateway.ddns.net/admin\n\n# Navigate to: \n# Realm: mcp-gateway → Users → agent--m2m → Groups\n\n# Add/remove group memberships:\n# - mcp-servers-unrestricted (full access)\n# - mcp-servers-restricted (limited access)\n\n# Generate new token to reflect changes\nuv run uv run python credentials-provider/token_refresher.py --agent-id \n```\n\n#### Updating Scopes Configuration\n```bash\n# 1. Edit scopes configuration\nnano auth_server/scopes.yml\n\n# 2. Restart auth server to pick up changes\ndocker-compose restart auth-server\n\n# 3. Verify changes took effect\ndocker-compose logs auth-server | grep -i scope\n\n# 4. Test authorization with updated scopes\n./test-keycloak-mcp.sh --agent-id \n```\n\n## Agent Management\n\n### Agent Service Account Lifecycle\n\n#### Creating New Agent\n```bash\n# Step 1: Create service account with appropriate permissions\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id \\\n --group \n\n# Step 2: Generate initial token\nuv run uv run python credentials-provider/token_refresher.py --agent-id \n\n# Step 3: Validate setup\n./test-keycloak-mcp.sh --agent-id \n\n# Step 4: Document agent in inventory\necho \",,,\" >> docs/agent-inventory.csv\n```\n\n#### Agent Permission Updates\n```bash\n# Via Keycloak Admin Console:\n# 1. Navigate to Users → agent--m2m → Groups\n# 2. Leave current group\n# 3. Join new group\n# 4. Generate new token\n\nuv run uv run python credentials-provider/token_refresher.py --agent-id \n```\n\n#### Agent Decommissioning\n```bash\n# 1. Disable service account in Keycloak\n# (Admin Console → Users → agent--m2m → Enabled: OFF)\n\n# 2. Remove token files\nrm .oauth-tokens/agent-.json\n\n# 3. Update documentation\nsed -i '//d' docs/agent-inventory.csv\n\n# 4. Optional: Delete service account entirely\n# (Admin Console → Users → agent--m2m → Delete)\n```\n\n### Bulk Agent Operations\n\n#### Creating Multiple Agents\n```bash\n#!/bin/bash\n# bulk-create-agents.sh\n\nAGENTS=(\n \"sre-agent:mcp-servers-unrestricted\"\n \"travel-assistant:mcp-servers-restricted\"\n \"dev-productivity:mcp-servers-restricted\"\n \"data-analyst:mcp-servers-restricted\"\n \"code-reviewer:mcp-servers-unrestricted\"\n)\n\nfor agent_config in \"${AGENTS[@]}\"; do\n IFS=':' read -r agent_id group <<< \"$agent_config\"\n \n echo \"Creating agent: $agent_id with group: $group\"\n ./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id \"$agent_id\" \\\n --group \"$group\"\n \n echo \"Generating token for: $agent_id\"\n uv run python credentials-provider/keycloak/get_m2m_token.py --agent-id \"$agent_id\"\ndone\n```\n\n#### Bulk Token Refresh\n```bash\n#!/bin/bash\n# bulk-refresh-tokens.sh\n\n# Use the built-in all-agents option (recommended)\nuv run python credentials-provider/keycloak/get_m2m_token.py --all-agents\n\n# Or manually refresh individual agents\nfor token_file in .oauth-tokens/agent-*-m2m-token.json; do\n if [ -f \"$token_file\" ]; then\n agent_id=$(basename \"$token_file\" -m2m-token.json | sed 's/agent-//')\n echo \"Refreshing token for agent: $agent_id\"\n uv run python credentials-provider/keycloak/get_m2m_token.py --agent-id \"$agent_id\"\n fi\ndone\n```\n\n## Monitoring & Troubleshooting\n\n### Log Monitoring\n\n#### Service Logs\n```bash\n# Keycloak logs\ndocker-compose logs -f keycloak\n\n# Auth server logs\ndocker-compose logs -f auth-server\n\n# PostgreSQL logs\ndocker-compose logs -f postgres\n\n# All services\ndocker-compose logs -f\n```\n\n#### Authentication Debugging\n```bash\n# Enable debug logging in auth server\n# Edit docker-compose.yml:\n# environment:\n# - LOG_LEVEL=DEBUG\n\n# Restart auth server\ndocker-compose restart auth-server\n\n# Monitor authentication attempts\ndocker-compose logs -f auth-server | grep -i \"keycloak\\|token\\|auth\"\n```\n\n#### Token Validation Logs\n```bash\n# Watch token validation in real-time\ndocker-compose logs -f auth-server | grep -E \"Token validation|Groups.*mapped|Access.*denied\"\n\n# Sample output:\n# ✓ Token validation successful using KeycloakProvider\n# ✓ Mapped Keycloak groups ['mcp-servers-unrestricted'] to scopes: ['mcp-servers-unrestricted/read', 'mcp-servers-unrestricted/execute']\n# ✓ Access granted for server currenttime.tools/list\n```\n\n### Common Issues & Solutions\n\n#### Issue: Token Expired\n```bash\n# Symptoms:\n# - HTTP 500 errors\n# - \"Token has expired\" in logs\n\n# Solution:\nuv run uv run python credentials-provider/token_refresher.py --agent-id \n```\n\n#### Issue: Service Account Missing\n```bash\n# Symptoms:\n# - \"Service account not found\" errors\n# - Token generation fails\n\n# Solution:\n./keycloak/setup/setup-agent-service-account.sh --agent-id --group \n```\n\n#### Issue: Groups Not in JWT\n```bash\n# Symptoms:\n# - \"Access forbidden\" errors\n# - Groups claim missing from token\n\n# Check groups mapper exists:\n# Admin Console → Clients → mcp-gateway-m2m → Mappers → groups\n\n# Fix:\n./keycloak/setup/setup-agent-service-account.sh --agent-id --group \n```\n\n#### Issue: Database Connection Failed\n```bash\n# Symptoms:\n# - Keycloak fails to start\n# - Database connection errors\n\n# Check PostgreSQL:\ndocker-compose ps postgres\ndocker-compose logs postgres\n\n# Restart database:\ndocker-compose restart postgres\nsleep 10\ndocker-compose restart keycloak\n```\n\n### Performance Monitoring\n\n#### Token Metrics\n```bash\n# Token expiration monitoring\nfind .oauth-tokens -name \"*.json\" -exec jq -r '.expires_at_human' {} \\;\n\n# Token age monitoring\nfind .oauth-tokens -name \"*.json\" -exec stat -c '%Y %n' {} \\; | sort -n\n```\n\n#### Service Health Dashboard\n```bash\n#!/bin/bash\n# health-dashboard.sh\n\necho \"=== MCP Gateway Keycloak Health Dashboard ===\"\necho \"Timestamp: $(date)\"\necho \"\"\n\necho \"--- Service Status ---\"\ndocker-compose ps --format \"table {{.Service}}\\t{{.Status}}\\t{{.Ports}}\"\necho \"\"\n\necho \"--- Token Status ---\"\nfor token_file in .oauth-tokens/*.json; do\n if [ -f \"$token_file\" ]; then\n agent=$(basename \"$token_file\" .json)\n expires=$(jq -r '.expires_at_human' \"$token_file\")\n echo \"$agent: expires $expires\"\n fi\ndone\necho \"\"\n\necho \"--- Service Health ---\"\ncurl -s -f http://localhost:8080/health/ready && echo \"Keycloak: ✓ Healthy\" || echo \"Keycloak: ✗ Unhealthy\"\ncurl -s -f http://localhost:8000/health && echo \"Auth Server: ✓ Healthy\" || echo \"Auth Server: ✗ Unhealthy\"\n```\n\n## Security Considerations\n\n### ⚠️ Critical Security Requirements\n\n**MANDATORY**: All setup scripts require environment variables to be set. Scripts will exit with an error if passwords are not provided:\n\n```bash\n# ✅ Required environment variables - scripts will fail without these\nexport KEYCLOAK_ADMIN_PASSWORD=\"$(openssl rand -base64 32)\"\nexport KEYCLOAK_DB_PASSWORD=\"$(openssl rand -base64 32)\"\n```\n\n**Security Features:**\n- ✅ No hardcoded passwords in scripts\n- ✅ Scripts exit with clear error if environment variables not set\n- ✅ Forces explicit password configuration\n- ✅ Prevents accidental use of default passwords\n\n**Before running any setup scripts:**\n1. **REQUIRED**: Set `KEYCLOAK_ADMIN_PASSWORD` environment variable\n2. **REQUIRED**: Set `KEYCLOAK_DB_PASSWORD` environment variable \n3. Never commit these to version control\n4. Use a proper secrets management system\n\n### Secret Management\n```bash\n# Environment Variables (Recommended)\nexport KEYCLOAK_CLIENT_SECRET=\"\"\nexport KEYCLOAK_ADMIN_PASSWORD=\"\"\n\n# .env Files (Development Only)\n# Ensure .env files are in .gitignore\necho \"*.env\" >> .gitignore\necho \".oauth-tokens/\" >> .gitignore\n\n# Kubernetes Secrets (Production)\nkubectl create secret generic keycloak-secrets \\\n --from-literal=client-secret=\"\" \\\n --from-literal=admin-password=\"\"\n```\n\n### Network Security\n```bash\n# Firewall Rules (Example)\n# Allow only necessary ports:\nufw allow 80/tcp # HTTP\nufw allow 443/tcp # HTTPS\nufw deny 8080/tcp # Block direct Keycloak access\nufw deny 5432/tcp # Block direct database access\n\n# Use reverse proxy (nginx) for SSL termination\n# Block direct access to Keycloak admin console from external networks\n```\n\n### Token Security\n```bash\n# Token File Permissions\nchmod 600 .oauth-tokens/*.json\nchown app:app .oauth-tokens/*.json\n\n# Token Rotation Policy\n# - Refresh tokens every 4 hours (max 5 minutes lifetime)\n# - Rotate client secrets monthly\n# - Monitor for token abuse/unusual patterns\n\n# Audit Trail\n# - All token usage logged with agent ID\n# - Failed authentication attempts monitored\n# - Suspicious activity alerts configured\n```\n\n### Access Control\n```bash\n# Service Account Principle of Least Privilege\n# - mcp-servers-restricted: Limited to approved servers only\n# - mcp-servers-unrestricted: Full access (use sparingly)\n\n# Regular Access Review\n# - Monthly review of agent permissions\n# - Quarterly audit of service accounts\n# - Annual security assessment\n```\n\n## Cleanup Procedures\n\n### Graceful Shutdown\n```bash\n# 1. Stop accepting new requests\ndocker-compose stop nginx\n\n# 2. Allow current requests to complete\nsleep 30\n\n# 3. Stop application services\ndocker-compose stop auth-server\n\n# 4. Stop Keycloak\ndocker-compose stop keycloak\n\n# 5. Stop database last\ndocker-compose stop postgres\n\n# 6. Verify all stopped\ndocker-compose ps\n```\n\n### Complete Removal\n```bash\n# Stop and remove containers\ndocker-compose down\n\n# Remove volumes (WARNING: This deletes all data)\ndocker-compose down -v\n\n# Remove images\ndocker-compose down --rmi all\n\n# Remove networks\ndocker network prune -f\n\n# Clean up token files\nrm -rf .oauth-tokens/\n\n# Remove logs\ndocker system prune -f\n```\n\n### Data Backup & Restore\n\n#### Backup Procedure\n```bash\n#!/bin/bash\n# backup-keycloak.sh\n\nBACKUP_DIR=\"backups/$(date +%Y%m%d_%H%M%S)\"\nmkdir -p \"$BACKUP_DIR\"\n\n# Backup database\ndocker-compose exec postgres pg_dump -U keycloak keycloak > \"$BACKUP_DIR/keycloak.sql\"\n\n# Backup configuration\ncp -r keycloak/setup \"$BACKUP_DIR/\"\ncp auth_server/scopes.yml \"$BACKUP_DIR/\"\ncp docker-compose.yml \"$BACKUP_DIR/\"\n\n# Backup tokens (optional)\ncp -r .oauth-tokens \"$BACKUP_DIR/\"\n\necho \"Backup completed: $BACKUP_DIR\"\n```\n\n#### Restore Procedure\n```bash\n#!/bin/bash\n# restore-keycloak.sh\n\nBACKUP_DIR=\"$1\"\n\nif [ -z \"$BACKUP_DIR\" ]; then\n echo \"Usage: $0 \"\n exit 1\nfi\n\n# Stop services\ndocker-compose down\n\n# Restore database\ndocker-compose up -d postgres\nsleep 10\ndocker-compose exec -T postgres psql -U keycloak -d keycloak < \"$BACKUP_DIR/keycloak.sql\"\n\n# Restore configuration\ncp -r \"$BACKUP_DIR/setup\" keycloak/\ncp \"$BACKUP_DIR/scopes.yml\" auth_server/\ncp \"$BACKUP_DIR/docker-compose.yml\" .\n\n# Start services\ndocker-compose up -d\n\necho \"Restore completed from: $BACKUP_DIR\"\n```\n\n### Agent Cleanup\n```bash\n#!/bin/bash\n# cleanup-agent.sh\n\nAGENT_ID=\"$1\"\n\nif [ -z \"$AGENT_ID\" ]; then\n echo \"Usage: $0 \"\n exit 1\nfi\n\n# Remove token file\nrm -f \".oauth-tokens/agent-${AGENT_ID}.json\"\n\n# Disable service account in Keycloak\n# (Manual step via Admin Console)\necho \"Manual step: Disable service account 'agent-${AGENT_ID}-m2m' in Keycloak Admin Console\"\n\n# Remove from monitoring\nsed -i \"/agent-${AGENT_ID}/d\" docs/agent-inventory.csv\n\necho \"Agent cleanup completed for: $AGENT_ID\"\n```\n\n---\n\n## Quick Reference\n\n### Key Commands\n```bash\n# Setup\n./keycloak/setup/init-keycloak.sh\n./keycloak/setup/setup-agent-service-account.sh --agent-id --group \n\n# Operations\nuv run python credentials-provider/token_refresher.py --agent-id \n./test-keycloak-mcp.sh --agent-id \ndocker-compose logs -f auth-server\n\n# Health Checks\ncurl -f http://localhost:8080/health/ready\ncurl -f http://localhost:8000/health\n\n# Troubleshooting\ndocker-compose ps\ndocker-compose logs \ncat .oauth-tokens/agent-.json | jq '.expires_at_human'\n```\n\n### Important Files\n```\nkeycloak/setup/ # Setup scripts\nauth_server/scopes.yml # Authorization configuration \n.oauth-tokens/ # Token storage\ndocs/keycloak-integration.md # This documentation\ndocker-compose.yml # Service orchestration\n.env # Environment configuration\n```\n\n### Service URLs\n- **Keycloak Admin**: https://mcpgateway.ddns.net/admin\n- **Keycloak API**: https://mcpgateway.ddns.net/realms/mcp-gateway\n- **Auth Server**: http://localhost:8000\n- **Health Checks**: http://localhost:8080/health/ready\n\n---\n\n*This documentation is maintained as part of the MCP Gateway project. For updates and issues, please refer to the project repository.*" }, { "path": "docs/llms.txt", "content": "# MCP Gateway & Registry - High-Level Summary\n\nThis project provides an enterprise-ready gateway and registry for Model Context Protocol (MCP) servers, enabling centralized management, secure access, and dynamic tool discovery for AI agents and development teams. The core goal is to transform the chaos of managing hundreds of individual MCP server connections into a unified, governed platform with comprehensive authentication, fine-grained access control, and intelligent tool discovery capabilities.\n\nThe repository provides:\n\n1. **Centralized Gateway & Registry**: A unified platform for managing and accessing MCP servers across an organization\n2. **Enterprise Authentication**: Multi-provider OAuth 2.0 support with Keycloak, Amazon Cognito, Microsoft Entra ID, and custom identity providers\n3. **Fine-Grained Access Control**: Scope-based authorization at server, method, and individual tool levels\n4. **Dynamic Tool Discovery**: AI-powered hybrid search (BM25 + vector k-NN) with flexible embedding providers (local, OpenAI, LiteLLM, Bedrock) for autonomous tool discovery\n5. **Comprehensive Observability**: Dual-path metrics collection with SQLite and OpenTelemetry for detailed analytics\n6. **Production-Ready Deployment**: Docker-based deployment with support for EC2, EKS, and container orchestration\n\nKey features include: centralized server management, OAuth 2.0/3.0 authentication flows, token vending service, automated token refresh, dynamic tool discovery and invocation, real-time health monitoring, Grafana dashboards, security scanning integration, and Anthropic MCP Registry compatibility.\n\n---\n\n# MCP Gateway & Registry\n\n## 1. Overview\n\n- **Project Name:** MCP Gateway & Registry\n- **Purpose:** Enterprise-ready platform for managing, securing, and accessing Model Context Protocol (MCP) servers at scale\n- **Core Goal:** Transform scattered MCP server connections into a centralized, governed platform with unified authentication and intelligent tool discovery\n- **Communication:** Uses MCP protocol over SSE (Server-Sent Events) and Streamable HTTP\n- **Key Components:** Gateway (Nginx reverse proxy), Registry (Web UI & API), Auth Server (OAuth/JWT), MCP Servers, Metrics Service, Token Refresh Service\n\n### 1.5. Repository Structure\n\n**Top-Level Directories:**\n\n| Directory | Purpose | Key Files |\n|-----------|---------|-----------|\n| `registry/` | **Core Registry Application** - FastAPI backend, repositories, services | `main.py` (FastAPI app), `core/config.py` (settings) |\n| `auth_server/` | **OAuth Authentication Server** - Keycloak/Cognito/Entra ID integration | `app.py` (Flask auth server), `scopes.yml` (group mappings) |\n| `frontend/` | **Web UI** - React/TypeScript admin dashboard | `src/App.tsx` (main app), `src/pages/` (UI pages) |\n| `servers/` | **Example MCP Servers** - Reference implementations | `currenttime/`, `mcpgw/` (MCP Gateway server) |\n| `terraform/` | **Infrastructure as Code** - AWS deployment automation | `aws-ecs/` (ECS Fargate), `modules/` (reusable modules) |\n| `tests/` | **Test Suite** - pytest unit, integration, E2E tests | `conftest.py`, `unit/`, `integration/` |\n| `docs/` | **Documentation** - Architecture, guides, design docs | `llms.txt` (this file), `design/` (architecture) |\n| `cli/` | **Command-Line Tools** - MCP client, service management | `mcp_client.py`, `service_mgmt.sh` |\n| `keycloak/` | **Keycloak Setup** - Docker configs, initialization scripts | `docker-compose.yml`, `setup/` (init scripts) |\n| `docker/` | **Docker Configurations** - Dockerfiles for all services | `Dockerfile.registry`, `Dockerfile.auth` |\n| `scripts/` | **Automation Scripts** - Deployment, testing, utilities | `test.py` (test runner), `publish-containers.sh` |\n| `config/` | **Configuration Templates** - Nginx, environment examples | `nginx.conf.template`, `.env.example` |\n| `metrics-service/` | **Metrics Collection** - OpenTelemetry metrics service | `app.py` (FastAPI metrics API) |\n| `charts/` | **Helm Charts** - Kubernetes deployment manifests | `mcp-gateway/` (Helm chart) |\n| `credentials-provider/` | **Credential Management** - OAuth token handling | `app.py` (credentials service) |\n| `agents/` | **A2A Agent Cards** - Agent-to-Agent protocol agent cards | JSON files for registered agents |\n| `api/` | **Legacy API** - Deprecated standalone API (use `registry/api/`) | - |\n| `release-notes/` | **Release History** - Version release notes | Markdown files per version |\n\n**Registry Application Structure (`registry/`):**\n\n| Subdirectory | Purpose | Key Files |\n|--------------|---------|-----------|\n| `api/` | **API Routes** - FastAPI endpoint definitions | `server_routes.py`, `agent_routes.py`, `search_routes.py`, `auth_routes.py` |\n| `services/` | **Business Logic** - Service layer between routes and repositories | `server_service.py`, `agent_service.py`, `search_service.py`, `rating_service.py` |\n| `repositories/` | **Data Access Layer** - Abstract repositories with multiple backends | `interfaces.py` (abstract base classes), `factory.py`, `documentdb/`, `file/` |\n| `repositories/documentdb/` | **DocumentDB Implementation** - Production storage backend | `server_repository.py`, `agent_repository.py`, `scope_repository.py`, `search_repository.py`, `client.py` |\n| `repositories/file/` | **File Implementation** - Legacy storage backend (DEPRECATED) | `server_repository.py`, `agent_repository.py` |\n| `schemas/` | **Pydantic Models** - Request/response validation | `server.py`, `agent.py`, `auth.py`, `search.py`, `security.py`, `rating.py` |\n| `auth/` | **Authentication Logic** - JWT validation, session management | `dependencies.py` (FastAPI auth dependencies), `session.py` |\n| `core/` | **Core Infrastructure** - Configuration, startup logic | `config.py` (Settings class), `logging.py` |\n| `embeddings/` | **Embedding Providers** - Multiple embedding model support | `factory.py`, `sentence_transformers.py`, `litellm_embeddings.py` |\n| `search/` | **Search Implementation** - Hybrid search (BM25 + vector) | `faiss_service.py` (legacy), `hybrid_search.py` |\n| `health/` | **Health Monitoring** - Server health checks, status tracking | `health_service.py`, `health_routes.py` |\n| `utils/` | **Utilities** - Helper functions, logging, validation | `scopes_manager.py` (scope CRUD), `nginx_service.py` |\n| `services/federation/` | **Federation** - External registry synchronization | `anthropic.py`, `asor.py` (Workday ASOR) |\n| `static/` | **Static Assets** - CSS, JavaScript, images for web UI | - |\n| `templates/` | **Jinja2 Templates** - HTML templates for web UI | `pages/`, `components/` |\n| `scripts/` | **Python Scripts** - Data migration, initialization | `migrate_to_documentdb.py`, `init_opensearch.py` |\n\n**Important Root Files:**\n\n| File | Purpose |\n|------|---------|\n| `pyproject.toml` | Python package configuration, dependencies, pytest settings |\n| `docker-compose.yml` | Local development Docker Compose configuration |\n| `docker-compose.prod.yml` | Production Docker Compose configuration |\n| `.env.example` | Environment variable template with all settings |\n| `README.md` | Project overview, quick start guide |\n| `CLAUDE.md` | Coding standards and best practices |\n| `TEAM.md` | Team roles and personas for development |\n| `MAINTENANCE.md` | Maintenance procedures and troubleshooting |\n| `WRITING_TESTS.md` | Test writing guidelines and patterns |\n\n**Test Structure (`tests/`):**\n\n| Subdirectory | Purpose | Key Files |\n|--------------|---------|-----------|\n| `unit/` | **Unit Tests** - Fast, isolated component tests | `api/`, `services/`, `repositories/`, `auth/` |\n| `integration/` | **Integration Tests** - Multi-component workflow tests | `test_server_lifecycle.py`, `test_search_integration.py`, `conftest.py` |\n| `fixtures/` | **Test Fixtures** - Mock data, factories | `factories.py` (Factory Boy), `mocks/` |\n| `reporting/` | **Test Reports** - HTML coverage reports, test results | - |\n\n**Terraform Structure (`terraform/`):**\n\n| Subdirectory | Purpose | Key Files |\n|--------------|---------|-----------|\n| `aws-ecs/` | **AWS ECS Fargate Deployment** - Production-ready IaC | `main.tf`, `variables.tf`, `outputs.tf`, `ecs.tf` |\n| `modules/` | **Reusable Terraform Modules** - Shared infrastructure components | `ecs-service/`, `alb/`, `networking/` |\n\n**Important Configuration Files:**\n\n| File/Directory | Purpose | Location |\n|----------------|---------|----------|\n| `oauth2_providers.yml` | OAuth provider configurations (Keycloak, Cognito, Entra ID) | `auth_server/` |\n| `scopes.yml` | Group-to-scope mappings, UI permissions | `auth_server/` |\n| `nginx.conf.template` | Nginx reverse proxy configuration | `config/` |\n| `global-bundle.pem` | AWS DocumentDB TLS certificate | Root directory |\n| `.env.example` | Environment variables for all services | Root directory |\n\n**Key Entry Points:**\n\n| Component | Entry Point | Purpose |\n|-----------|-------------|---------|\n| Registry API | `registry/main.py` | FastAPI application for registry and MCP gateway |\n| Auth Server | `auth_server/app.py` | Flask OAuth server for authentication |\n| Frontend | `frontend/src/App.tsx` | React web UI for administration |\n| MCP Client | `cli/mcp_client.py` | CLI tool for calling MCP servers |\n| Test Runner | `scripts/test.py` | Unified test execution script |\n| Metrics Service | `metrics-service/app.py` | OpenTelemetry metrics collection |\n\n## 2. Core Problem Solved\n\n**Transform this chaos:**\n- AI agents require separate connections to each MCP server\n- Each developer configures VS Code, Cursor, Claude Code individually\n- Developers must install and manage MCP servers locally\n- No standard authentication flow for enterprise tools\n- Scattered API keys and credentials across tools\n- No visibility into what tools teams are using\n- Security risks from unmanaged tool sprawl\n- No dynamic tool discovery for autonomous agents\n\n**Into this organized approach:**\n- AI agents connect to one gateway, access multiple MCP servers\n- Single configuration point for VS Code, Cursor, Claude Code\n- Central IT manages cloud-hosted MCP infrastructure\n- Developers use standard OAuth 2LO/3LO flows\n- Centralized credential management with secure vault integration\n- Complete visibility and audit trail for all tool usage\n- Enterprise-grade security with governed tool access\n- Dynamic tool discovery and invocation for autonomous workflows\n\n## 3. Architecture Overview\n\n### 3.1. Core Architectural Decision: Reverse Proxy Pattern\n\nThe MCP Gateway uses a **reverse proxy architecture** (Nginx-based) rather than an application-layer gateway:\n\n**Key Benefits:**\n- **Performance**: Direct proxy routing with minimal overhead (~1-2ms)\n- **Protocol Independence**: Can proxy any protocol (HTTP, WebSocket, SSE, gRPC)\n- **Scalability**: Each MCP server scales independently\n- **Implementation**: Allows Python development while Nginx handles message routing\n- **Future-Proof**: Supports A2A (Agent-to-Agent) and other protocols without gateway changes\n\n**Architecture Flow:**\n```\nAI Agent/Coding Assistant\n ↓ Multiple Endpoints\n┌─────────────────┐\n│ Nginx Gateway │\n│ /fininfo/ │ ──auth_request──> Auth Server\n│ /mcpgw/ │ │\n│ /currenttime/ │ <──auth_headers───────┘\n└─────────────────┘\n │ │ │\n │ │ └─── localhost:8003 (currenttime)\n │ └───── localhost:8002 (mcpgw)\n └─────── localhost:8001 (fininfo)\n```\n\n**Alternative Considered:**\n- Tools Gateway Pattern: Single endpoint with tool aggregation\n- Trade-offs: Better developer experience but requires Go/Rust for performance and adds complexity\n\n### 3.2. High-Level Component Architecture\n\n```\n┌─────────────────────────────────────┐\n│ Human Users / AI Agents │\n└──────────────┬──────────────────────┘\n │\n ↓\n┌──────────────────────────────────────┐\n│ Identity Provider (Keycloak/ │\n│ Cognito/Entra ID) - OAuth 2.0 │\n└──────────────┬───────────────────────┘\n │\n ↓\n┌──────────────────────────────────────┐\n│ MCP Gateway & Registry (EC2/EKS) │\n│ ┌────────────────────────────────┐ │\n│ │ NGINX Reverse Proxy Router │ │\n│ └──────┬─────────────────────────┘ │\n│ │ │\n│ ┌──────┴─────────┬────────────┐ │\n│ │ Auth Server │ Registry │ │\n│ │ (Dual Auth) │ Web UI │ │\n│ └────────────────┴────────────┘ │\n│ │\n│ ┌──────────────────────────────┐ │\n│ │ Local MCP Servers │ │\n│ │ - MCP Server 1, 2, ...N │ │\n│ └──────────────────────────────┘ │\n└──────────────┬───────────────────────┘\n │\n ↓\n┌──────────────────────────────────────┐\n│ External Systems & Data Sources │\n│ - EKS/EC2 Cluster MCP Servers │\n│ - API Gateway + Lambda Functions │\n│ - Databases, External APIs │\n└──────────────────────────────────────┘\n```\n\n### 3.3. Key Architectural Components\n\n**Gateway Layer:**\n- **Nginx Reverse Proxy**: Path-based routing, SSL termination, load balancing\n- **Auth Server**: Dual authentication (Keycloak/Cognito), token validation, scope enforcement\n- **Registry Web UI**: Server management, health monitoring, user administration\n- **Registry MCP Server**: Dynamic tool discovery, intelligent tool finder\n\n**Identity & Access:**\n- **Keycloak/Cognito/Entra ID**: Primary identity provider (choose one or multi-provider)\n- **OAuth 2.0/3.0**: User authentication and authorization\n- **JWT Tokens**: Secure, stateless authentication\n- **Fine-Grained Access Control**: Scope-based permissions at server, method, and tool levels\n- **Enterprise SSO**: SAML/OIDC integration with Microsoft Entra ID for Microsoft 365 environments\n\n**MCP Server Layer:**\n- **Local MCP Servers**: Co-located with gateway (SSE transport)\n- **Remote MCP Servers**: EKS/EC2 clusters (SSE/Streamable HTTP)\n- **Serverless MCP**: API Gateway + Lambda functions\n\n**Observability:**\n- **Metrics Service**: Dual-path collection (SQLite + OpenTelemetry)\n- **Prometheus**: Time-series metrics storage\n- **Grafana**: Real-time dashboards and alerting\n- **CloudWatch/Datadog**: Cloud-native monitoring integration\n\n### 3.4. Storage Backend Architecture\n\n**IMPORTANT:** The MCP Gateway & Registry uses a **repository pattern** with multiple storage backends. File-based storage is **LEGACY and DEPRECATED** - use DocumentDB or MongoDB for production deployments.\n\n**Repository Pattern:**\n```\nRoutes → Services → Repositories → Storage Backends\n```\n\n**Three Storage Backends:**\n\n1. **File-Based Storage (LEGACY - DEPRECATED)**\n - Status: Maintained for backward compatibility only, will be removed\n - Use Case: Local development and testing ONLY\n - Vector Search: FAISS with in-memory indexing\n - Limitations: Not suitable for production, no high availability, file corruption risks\n - Location: `registry/repositories/file/`\n\n2. **MongoDB Community Edition (Development)**\n - Status: Recommended for local development and testing\n - Use Case: Local Docker development, CI/CD testing\n - Vector Search: Application-level k-NN with BM25 hybrid search\n - Configuration: `STORAGE_BACKEND=mongodb-ce`\n - Connection: `DOCUMENTDB_HOST=localhost:27017`\n - Location: `registry/repositories/mongodb/`\n\n3. **Amazon DocumentDB (Production - RECOMMENDED)**\n - Status: Production-ready, enterprise-grade\n - Use Case: AWS production deployments with HA requirements\n - Vector Search: Native HNSW vector search with BM25 hybrid search\n - Configuration: `STORAGE_BACKEND=documentdb`\n - Features: Multi-AZ replication, automatic failover, point-in-time recovery\n - Namespace Support: Multi-tenancy via `DOCUMENTDB_NAMESPACE`\n - Location: `registry/repositories/documentdb/`\n\n**Repository Interfaces (Abstract Base Classes):**\n- `ServerRepository`: Server registration, listing, metadata management\n- `AgentRepository`: A2A agent card management\n- `ScopeRepository`: Group and scope CRUD operations\n- `SearchRepository`: Hybrid search (BM25 + vector k-NN)\n\n**Factory Pattern:**\n```python\nfrom registry.repositories.factory import (\n get_server_repository,\n get_agent_repository,\n get_scope_repository,\n get_search_repository\n)\n\n# Automatically selects backend based on STORAGE_BACKEND env var\nserver_repo = await get_server_repository()\n```\n\n**Key Architectural Principles:**\n1. **Never access repositories directly from API routes** - Always use service layer\n2. **All backends provide identical behavior** - Polymorphism via abstract base classes\n3. **Backend switching is transparent** - Factory pattern handles instantiation\n4. **Use DocumentDB for production** - File-based storage is deprecated\n\n**Configuration:**\n```bash\n# Production (DocumentDB)\nSTORAGE_BACKEND=documentdb\nDOCUMENTDB_HOST=docdb-cluster.cluster-xxx.us-east-1.docdb.amazonaws.com\nDOCUMENTDB_PORT=27017\nDOCUMENTDB_DATABASE=mcp_registry\nDOCUMENTDB_NAMESPACE=prod # For multi-tenancy\nDOCUMENTDB_USE_TLS=true\nDOCUMENTDB_USE_IAM=true\n\n# Development (MongoDB CE)\nSTORAGE_BACKEND=mongodb-ce\nDOCUMENTDB_HOST=localhost\nDOCUMENTDB_PORT=27017\n\n# Legacy (File - DEPRECATED)\nSTORAGE_BACKEND=file # NOT RECOMMENDED\n```\n\n**Vector Search Comparison:**\n- **File Backend (Legacy)**: FAISS IndexFlatIP (cosine similarity)\n- **MongoDB CE**: Application-level k-NN with score normalization\n- **DocumentDB**: Native HNSW with optimized indexing\n\n**Hybrid Search Strategy:**\nAll backends support hybrid search combining:\n1. **BM25 Text Search**: Keyword matching on server/tool names and descriptions\n2. **Vector k-NN Search**: Semantic similarity using embeddings (384-1536 dimensions)\n3. **Score Fusion**: Weighted combination (configurable weights)\n\n**References:**\n- Design Document: `docs/design/database-abstraction-layer.md`\n- Storage Architecture: `docs/design/storage-architecture-mongodb-documentdb.md`\n- Repository Interfaces: `registry/repositories/interfaces.py`\n- Factory Implementation: `registry/repositories/factory.py`\n\n## 4. Authentication & Authorization\n\n### 4.1. Three-Layer Authentication System\n\n**Layer 1: Ingress Authentication (2LO/M2M)**\n- Purpose: Controls who can access the MCP Gateway\n- Providers: Keycloak (M2M service accounts), Amazon Cognito (M2M/2LO), Microsoft Entra ID (Azure AD)\n- Headers: `X-Authorization`, `X-Client-Id`, `X-Keycloak-Realm`, `X-User-Pool-Id`, `X-Tenant-Id` (Entra ID)\n- Methods: Machine-to-Machine (JWT tokens), User sessions (OAuth PKCE), Enterprise SSO (SAML/OIDC)\n\n**Layer 2: Fine-Grained Access Control (FGAC)**\n- Purpose: Controls which tools/methods within MCP servers can be accessed\n- Based on: User/agent scopes and group memberships\n- Validation: Applied at gateway level after ingress auth\n- Granularity: Server-level, method-level, individual tool-level\n\n**Layer 3: Egress Authentication (3LO)**\n- Purpose: Allows MCP servers to act on user's behalf with external services\n- Providers: Atlassian, Google, GitHub, Microsoft, custom OAuth providers\n- Headers: `Authorization`, provider-specific headers (e.g., `X-Atlassian-Cloud-Id`)\n- Validation: MCP server validates with its IdP\n\n### 4.2. Dual Token System\n\nAI agents carry BOTH ingress and egress tokens:\n\n```json\n{\n \"headers\": {\n // Ingress Authentication (for Gateway) - Keycloak\n \"X-Authorization\": \"Bearer {keycloak_jwt_token}\",\n \"X-Client-Id\": \"{agent_client_id}\",\n \"X-Keycloak-Realm\": \"mcp-gateway\",\n \"X-Keycloak-URL\": \"http://localhost:8080\",\n\n // OR Cognito\n \"X-Authorization\": \"Bearer {cognito_jwt_token}\",\n \"X-User-Pool-Id\": \"{cognito_user_pool_id}\",\n \"X-Client-Id\": \"{cognito_client_id}\",\n \"X-Region\": \"{aws_region}\",\n\n // Egress Authentication (for MCP Server) - Example: Atlassian\n \"Authorization\": \"Bearer {atlassian_oauth_token}\",\n \"X-Atlassian-Cloud-Id\": \"{atlassian_cloud_id}\"\n }\n}\n```\n\n### 4.3. Complete Authentication Flow\n\n```\n1. One-Time Setup:\n User → Keycloak/Cognito (2LO) → Ingress Token\n User → External IdP (3LO, consent) → Egress Token\n User → Agent Configuration (both tokens)\n\n2. Runtime (Every Request):\n Agent → Gateway (dual tokens)\n Gateway → Keycloak/Cognito (validate ingress)\n Gateway → Apply FGAC (check permissions)\n Gateway → MCP Server (forward egress token)\n MCP Server → External IdP (validate egress)\n MCP Server → Response (via Gateway)\n```\n\n### 4.4. Fine-Grained Access Control (FGAC)\n\n**Scope Types:**\n- **UI Scopes**: Registry management permissions\n - `mcp-registry-admin`: Full administrative access\n - `mcp-registry-user`: Limited user access\n - `mcp-registry-developer`: Service registration and management\n - `mcp-registry-operator`: Operational access without registration\n\n- **Server Scopes**: MCP server access\n - `mcp-servers-unrestricted/read`: Read all servers\n - `mcp-servers-unrestricted/execute`: Execute all tools\n - `mcp-servers-restricted/read`: Limited read access\n - `mcp-servers-restricted/execute`: Limited execute access\n\n**Methods vs Tools:**\n- **MCP Methods**: Protocol operations (`initialize`, `tools/list`, `tools/call`)\n- **Individual Tools**: Specific functions within servers\n\n**Example Access Control:**\n```yaml\n# User can list tools but only execute specific ones\nmcp-servers-restricted/execute:\n - server: fininfo\n methods:\n - tools/list # Can list all tools\n - tools/call # Can call tools\n tools:\n - get_stock_aggregates # But only these specific tools\n - print_stock_data\n```\n\n**Validation Logic:**\n1. Input Validation: Validate server name, method, tool name, user scopes\n2. Scope Iteration: Check each user scope for matching permissions\n3. Server Matching: Find server configurations that match the requested server\n4. Method Validation: Check if the requested method is allowed\n5. Tool Validation: For `tools/call`, validate specific tool permissions\n6. Access Decision: Grant access if any scope allows the operation\n\n**Group Mappings:**\n```yaml\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin # UI permissions\n - mcp-servers-unrestricted/read # Server read access\n - mcp-servers-unrestricted/execute # Server execute access\n\n mcp-registry-user:\n - mcp-registry-user # Limited UI permissions\n - mcp-servers-restricted/read # Limited server access\n```\n\n**Note**: All group names and scope names are completely customizable by administrators. Names must be configured consistently in both the Identity Provider (IdP) and `scopes.yml` configuration file.\n\n## 4.5. Agent-to-Agent (A2A) Protocol Integration\n\nThe MCP Gateway supports Agent-to-Agent (A2A) communication, enabling AI agents to securely register themselves and their capabilities with the central registry, creating a self-managed agent ecosystem.\n\n### 4.5.1. A2A Agent Architecture\n\n```\nAgent Application (AI Code)\n ↓ M2M Token (Keycloak Service Account)\n┌─────────────────────────────────────┐\n│ Agent Registry API (/api/agents) │\n│ - POST /api/agents/register │\n│ - GET /api/agents │\n│ - GET /api/agents/{path} │\n│ - PUT /api/agents/{path} │\n│ - DELETE /api/agents/{path} │\n│ - POST /api/agents/{path}/toggle │\n└─────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────┐\n│ Agent State Management │\n│ - registry/agents/agent_state.json │\n│ - registry/agents/{name}.json │\n└─────────────────────────────────────┘\n```\n\n### 4.5.2. Agent Registration Flow\n\n**Step 1: Agent Authentication**\n- Agent obtains M2M token from Keycloak service account\n- Tokens expire in 5 minutes and must be regenerated before use\n- Token validation includes expiration checks via JWT payload decoding\n\n**Step 2: Agent Registration**\n- Agent calls POST `/api/agents/register` with:\n - Agent metadata (name, description, version)\n - Protocol version (e.g., \"1.0\")\n - Agent skills/capabilities (MCP tools provided by agent)\n - Security configuration (bearer tokens, oauth)\n - Visibility settings (public/private)\n - Trust level (verified/unverified)\n\n**Step 3: Agent Access Control**\n- Agent permissions defined in `auth_server/scopes.yml`\n- Three-tier structure:\n 1. **UI-Scopes**: Agent registry permissions (list_agents, get_agent, publish_agent, modify_agent, delete_agent)\n 2. **Group Mappings**: Maps Keycloak groups to scope names\n 3. **Individual group scopes**: Detailed agent and MCP server access\n\n**Step 4: Agent CRUD Operations**\n- CREATE: Register new agent with skills\n- READ: Retrieve agent metadata and capabilities\n- UPDATE: Modify agent description, tags, skills\n- DELETE: Remove agent from registry\n- TOGGLE: Enable/disable agent availability\n\n### 4.5.3. Agent Access Control Example\n\n**Scopes Configuration (auth_server/scopes.yml):**\n```yaml\nUI-Scopes:\n mcp-registry-admin:\n list_agents:\n - all # Admin sees all agents\n get_agent:\n - all\n publish_agent:\n - all\n modify_agent:\n - all\n delete_agent:\n - all\n\n registry-users-lob1:\n list_agents:\n - /code-reviewer # LOB1 sees specific agents\n - /test-automation\n get_agent:\n - /code-reviewer\n - /test-automation\n\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin\n registry-users-lob1:\n - registry-users-lob1\n```\n\n**Agent Permissions Table:**\n```\nAgent | Group | Can List | Can Get | Can Publish | Can Modify | Can Delete\n------|-------|----------|---------|-------------|------------|----------\nadmin | admin | all | all | all | all | all\nlob1 | lob1 | 2 agents | 2 | own agents | own | own agents\nlob2 | lob2 | 2 agents | 2 | own agents | own | own agents\n```\n\n### 4.5.4. Agent State Management\n\n**Agent State File (registry/agents/agent_state.json):**\n```json\n{\n \"agents\": {\n \"/code-reviewer\": {\n \"path\": \"/code-reviewer\",\n \"name\": \"Code Reviewer Agent\",\n \"enabled\": true,\n \"registered_at\": \"2024-11-09T14:45:00Z\",\n \"last_modified\": \"2024-11-09T14:50:00Z\"\n },\n \"/data-analysis\": {\n \"path\": \"/data-analysis\",\n \"name\": \"Data Analysis Agent\",\n \"enabled\": true,\n \"registered_at\": \"2024-11-09T15:00:00Z\"\n }\n }\n}\n```\n\n**Individual Agent File (registry/agents/code-reviewer.json):**\n```json\n{\n \"protocol_version\": \"1.0\",\n \"name\": \"Code Reviewer Agent\",\n \"description\": \"Reviews code for quality and best practices\",\n \"path\": \"/code-reviewer\",\n \"url\": \"https://agent.example.com\",\n \"skills\": [\n {\n \"id\": \"review-python\",\n \"name\": \"Python Code Review\",\n \"description\": \"Reviews Python code\",\n \"parameters\": {\n \"code_snippet\": {\"type\": \"string\"}\n }\n }\n ],\n \"security\": [\"bearer\"],\n \"tags\": [\"code-review\", \"qa\"],\n \"visibility\": \"public\",\n \"trust_level\": \"verified\"\n}\n```\n\n### 4.5.5. Agent CLI & Testing\n\n**Agent CRUD Test Script (tests/agent_crud_test.sh):**\n- Demonstrates all CRUD operations (create, read, update, delete, toggle)\n- Includes token validation with JWT expiration checking\n- Tests agent state persistence\n- Verifies agent re-registration after deletion\n- Supports custom token paths and environment variables\n\n**Usage:**\n```bash\n# Generate fresh credentials\n./credentials-provider/generate_creds.sh\n\n# Run CRUD tests with default token\nbash tests/agent_crud_test.sh\n\n# Run with custom token path\nbash tests/agent_crud_test.sh /path/to/token.json\n\n# Run with environment variable\nTOKEN_FILE=/path/to/token.json bash tests/agent_crud_test.sh\n```\n\n### 4.5.6. Access Control Testing\n\n**LOB Bot Access Control Tests (tests/run-lob-bot-tests.sh):**\n- Tests MCP service access permissions (Tests 1-6)\n- Tests agent registry API permissions (Tests 7-14)\n- Validates bot-specific agent visibility\n- Ensures agents can only access permitted agents\n- Confirms admin sees all agents\n\n**Test Coverage:**\n```\nPart 1: MCP Service Access (6 tests)\n- Tests 1-6: Verify bots can only call permitted MCP services\n\nPart 2: Agent Registry API (8 tests)\n- Tests 7-9: LOB1 agent access control\n- Tests 10-12: LOB2 agent access control\n- Tests 13-14: Admin agent access (see all)\n```\n\n**Running Access Control Tests:**\n```bash\n# Generate tokens for all bots\n./keycloak/setup/generate-agent-token.sh admin-bot\n./keycloak/setup/generate-agent-token.sh lob1-bot\n./keycloak/setup/generate-agent-token.sh lob2-bot\n\n# Run 14 comprehensive tests\nbash tests/run-lob-bot-tests.sh\n```\n\n### 4.5.7. Code Structure for A2A Agent Management\n\n**CLI Module (cli/agent_mgmt.py):**\n- Agent registration and lifecycle management\n- CRUD operations on agent metadata\n- Argument validation and error handling\n- Structured logging and status reporting\n\n**Key Functions:**\n- `register_agent()`: Register new agent in registry\n- `get_agent()`: Retrieve agent metadata\n- `update_agent()`: Modify agent settings\n- `delete_agent()`: Remove agent from registry\n- `toggle_agent()`: Enable/disable agent\n- `list_agents()`: Get agents filtered by permissions\n\n**API Routes (registry/api/agent_routes.py):**\n- Implements Agent Registry REST API endpoints\n- Access control enforcement via scopes\n- Token validation and authentication\n- Agent state persistence and management\n\n**Data Models (registry/models/):**\n- Agent schema validation\n- Skill/capability definitions\n- Security configuration models\n- State tracking models\n\n**Implementation Notes:**\n- JWT token validation with expiration checks (5-minute TTL)\n- Base64 padding for JWT payload decoding\n- Proper HTTP status codes (200, 201, 204, 400, 403, 404)\n- Comprehensive error messages for debugging\n- Agent state file updates on registration/deletion\n- File-based persistence for agent metadata\n\n## 5. Dynamic Tool Discovery\n\n### 5.1. Overview\n\nTraditional AI agents are limited to pre-configured tools. Dynamic Tool Discovery enables agents to:\n1. Discover new tools through natural language queries\n2. Automatically find relevant tools from hundreds of MCP servers\n3. Dynamically invoke discovered tools without prior configuration\n4. Expand capabilities on-demand based on user requests\n\n### 5.2. How It Works\n\n```\n1. Natural Language Query → Agent receives user request\n2. Semantic Search → intelligent_tool_finder uses sentence transformers\n3. FAISS Index Search → Searches embeddings of all registered tools\n4. Relevance Ranking → Returns tools ranked by semantic similarity\n5. Tool Invocation → Agent uses invoke_mcp_tool with discovered info\n```\n\n### 5.3. Architecture Components\n\n**IMPORTANT:** Vector search architecture depends on storage backend:\n- **File Backend (LEGACY - DEPRECATED)**: Uses FAISS IndexFlatIP\n- **MongoDB CE/DocumentDB (PRODUCTION)**: Uses hybrid search (BM25 + native vector k-NN)\n\n**Discovery Layer (Modern - DocumentDB/MongoDB):**\n- **Embedding Providers**: Flexible provider selection (sentence-transformers, OpenAI, LiteLLM with 100+ models)\n- **BM25 Text Search**: Keyword matching on server/tool names and descriptions\n- **Vector k-NN Search**: Semantic similarity using embeddings (384-1536 dimensions)\n- **Hybrid Search**: Weighted combination of BM25 and vector search results\n- **Native Vector Indexing**: DocumentDB HNSW or MongoDB application-level k-NN\n- **Tool Metadata**: Server information, tool schemas, descriptions, embeddings\n\n**Discovery Layer (Legacy - File Backend):**\n- **FAISS Index**: In-memory vector similarity search (DEPRECATED)\n- **Sentence Transformer**: all-MiniLM-L6-v2 model (384 dimensions) only\n- **Cosine Similarity**: IndexFlatIP for vector search\n- **Limitations**: File-based, no hybrid search, single embedding provider\n\n**Embedding Provider Options:**\n1. **Sentence Transformers (Local)**: Default all-MiniLM-L6-v2 (384 dimensions), runs locally\n2. **OpenAI Embeddings**: text-embedding-ada-002 (1536 dimensions), requires API key\n3. **LiteLLM**: 100+ embedding models via unified interface (OpenAI, Cohere, Bedrock, etc.)\n4. **Amazon Bedrock Titan**: titan-embed-text-v2:0 (1024 dimensions), native AWS integration\n\n**Hybrid Search Strategy (DocumentDB/MongoDB):**\n```\nFinal Score = (BM25_Weight × BM25_Score) + (Vector_Weight × Vector_Score)\n\nDefault weights: BM25_Weight=0.3, Vector_Weight=0.7\n```\n\n**Key Technologies:**\n- DocumentDB/MongoDB (native vector search with HNSW indexing)\n- BM25 algorithm for text matching\n- Multiple embedding providers (sentence-transformers, OpenAI, LiteLLM, Bedrock)\n- Hybrid scoring with configurable weights\n- MCP Protocol\n- FAISS (legacy file backend only - DEPRECATED)\n\n### 5.4. Usage Patterns\n\n**Pattern 1: Direct Developer Usage**\n```python\n# Discover tools\ntools = await intelligent_tool_finder(\n natural_language_query=\"what time is it in Tokyo\",\n session_cookie=\"your_session_cookie_here\"\n)\n\n# Use discovered tool\nresult = await invoke_mcp_tool(\n mcp_registry_url=\"https://registry.com/mcpgw/sse\",\n server_name=tools[0][\"service_path\"],\n tool_name=tools[0][\"tool_name\"],\n arguments={\"tz_name\": \"Asia/Tokyo\"},\n auth_token=auth_token,\n ...\n)\n```\n\n**Pattern 2: Agent Integration (Autonomous)**\n```python\n# Agent has access to both tools as available capabilities\n# 1. intelligent_tool_finder - discovers tools\n# 2. invoke_mcp_tool - executes discovered tools\n\n# Agent autonomously:\n# - Identifies need for specialized tool\n# - Calls intelligent_tool_finder with description\n# - Receives tool information and usage instructions\n# - Calls invoke_mcp_tool with discovered tool details\n```\n\n### 5.5. API Reference\n\n**intelligent_tool_finder**\n\nParameters:\n- `natural_language_query` (str, required): Query describing the task\n- `username` (str, optional): Username for authentication\n- `password` (str, optional): Password for authentication\n- `session_cookie` (str, optional): Session cookie for authentication\n- `top_k_services` (int, optional): Number of top services to consider (default: 3)\n- `top_n_tools` (int, optional): Number of best matching tools to return (default: 1)\n\nReturns:\n```python\n[\n {\n \"tool_name\": \"current_time_by_timezone\",\n \"tool_parsed_description\": {\n \"main\": \"Get current time for a specific timezone\",\n \"parameters\": {...}\n },\n \"tool_schema\": {...},\n \"service_path\": \"/currenttime\",\n \"service_name\": \"Current Time Server\",\n \"overall_similarity_score\": 0.89\n }\n]\n```\n\n### 5.6. Implementation Details\n\n**FAISS Index Creation:**\n1. Tool Metadata Collection: Gathers descriptions, schemas, server info\n2. Text Embedding: Creates vector embeddings using sentence transformers\n3. Index Building: Constructs FAISS index for fast similarity search\n4. Automatic Updates: Refreshes index when servers are added/modified\n\n**Semantic Search Process:**\n1. Embed the natural language query\n2. Search FAISS for top_k_services\n3. Collect tools from top services\n4. Embed all candidate tool descriptions\n5. Calculate cosine similarity and rank\n\n**Performance Optimizations:**\n- Lazy Loading: FAISS index and models loaded on-demand\n- Caching: Embeddings and metadata cached\n- Async Processing: Embedding operations in separate threads\n- Memory Efficiency: Float32 precision for embeddings\n\n## 6. Registry API & Management\n\n### 6.1. Registry REST API\n\n**Authentication Required**: Session cookie obtained via `/login` endpoint\n\n**Core Endpoints:**\n- `GET /login` - Display login form\n- `POST /login` - Authenticate user, create session cookie (required first step)\n- `POST /logout` - Invalidate session\n- `POST /register` - Register new MCP service\n- `POST /toggle/{service_path}` - Enable/disable service\n- `POST /edit/{service_path}` - Update service details\n- `GET /api/server_details/{service_path}` - Get service details\n- `GET /api/tools/{service_path}` - Get service tools\n- `POST /api/refresh/{service_path}` - Trigger health check/tool discovery\n- `WebSocket /ws/health_status` - Real-time health status updates\n\n**Registration Parameters:**\n- `name`: Display name\n- `description`: Service description\n- `path`: URL path (e.g., `/weather`)\n- `proxy_pass_url`: Backend URL\n- `tags`: Comma-separated tags\n- `num_tools`: Number of tools\n- `num_stars`: Star rating\n- `is_python`: Python-based flag\n- `license`: License information\n\n### 6.2. Anthropic MCP Registry API Compatibility\n\n**Full compatibility** with Anthropic's MCP Registry REST API specification (v0.1):\n\n**Endpoints:**\n- `GET /v0.1/servers` - List all servers (with pagination)\n- `GET /v0.1/servers/{server_name}/versions` - List server versions\n- `GET /v0.1/servers/{server_name}/versions/{version}` - Get version details\n\n**Authentication**: JWT Bearer token (short-lived, typically 5-15 minutes)\n\n**Token Generation:**\n1. Login to Registry Web Interface\n2. Generate JWT Token from UI\n3. Tokens stored in `.oauth-tokens/mcp-registry-api-tokens-YYYY-MM-DD.json`\n4. Use Bearer token in Authorization header\n\n**Example Usage:**\n```bash\nACCESS_TOKEN=$(cat token-file.json | jq -r '.tokens.access_token')\n\n# List servers\ncurl -X GET \"http://localhost/v0.1/servers?limit=10\" \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"\n\n# Get server versions\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Fatlassian/versions\" \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"\n\n# Get server details\ncurl -X GET \"http://localhost/v0.1/servers/io.mcpgateway%2Fatlassian/versions/latest\" \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"\n```\n\n**Import from Anthropic Registry:**\n```bash\n# Import curated servers from Anthropic's registry\n./cli/import_anthropic_servers.py --select\n```\n\n### 6.3. Service Management CLI\n\n**Location**: `cli/mcp_services.py`\n\n**Key Commands:**\n```bash\n# List all servers\nuv run python cli/mcp_services.py list-servers\n\n# Health check\nuv run python cli/mcp_services.py health-check --server-name atlassian\n\n# Create group\nuv run python cli/mcp_services.py create-group \\\n --group-name mcp-servers-finance \\\n --scope-suffix read\n\n# Assign server to group\nuv run python cli/mcp_services.py assign-server-to-group \\\n --server-name fininfo \\\n --group-name mcp-servers-finance\n\n# User management\nuv run python cli/mcp_services.py create-user \\\n --username john.doe \\\n --groups mcp-servers-finance\n\n# List groups\nuv run python cli/mcp_services.py list-groups\n```\n\n### 6.4. Rating System\n\n**Community-driven quality assessment** for both MCP servers and AI agents using a 5-star rating system.\n\n**Key Features:**\n- **5-Star Rating Scale**: Users rate servers/agents from 1 to 5 stars\n- **Interactive UI Widget**: Visual star rating interface in the web dashboard\n- **CLI Support**: Submit ratings via command-line tools\n- **Aggregate Ratings**: Weighted average with individual rating details\n- **One Rating Per User**: Users can update their rating, but only one rating per entity\n- **Rotating Buffer**: Maximum 100 ratings per entity (FIFO replacement)\n- **Anonymous Tracking**: Ratings linked to username but not publicly displayed\n- **Real-time Updates**: Aggregate rating updates immediately after submission\n\n**Rating API Endpoints:**\n\n```bash\n# Submit a rating for a server\nPOST /api/v2/servers/{server_path}/rating\n{\n \"rating\": 5, # 1-5 stars\n \"username\": \"john.doe\"\n}\n\n# Submit a rating for an agent\nPOST /api/v2/agents/{agent_path}/rating\n{\n \"rating\": 4,\n \"username\": \"jane.smith\"\n}\n\n# Get server with rating details\nGET /api/v2/servers/{server_path}\n# Returns:\n{\n \"server_path\": \"/example-server\",\n \"name\": \"Example Server\",\n \"aggregate_rating\": 4.5, # Weighted average\n \"rating_count\": 42,\n \"rating_details\": [\n {\"user\": \"john.doe\", \"rating\": 5},\n {\"user\": \"jane.smith\", \"rating\": 4}\n # ... up to 100 ratings\n ]\n}\n\n# Get agent with rating details\nGET /api/v2/agents/{agent_path}\n# Similar structure with aggregate_rating, rating_count, rating_details\n```\n\n**CLI Rating Submission:**\n```bash\n# Rate a server\nuv run python cli/mcp_services.py rate-server \\\n --server-path /example-server \\\n --rating 5 \\\n --username john.doe\n\n# Rate an agent\nuv run python cli/mcp_services.py rate-agent \\\n --agent-path /code-reviewer \\\n --rating 4 \\\n --username jane.smith\n```\n\n**Rating Logic:**\n- **Validation**: Ratings must be integers between 1 and 5 (inclusive)\n- **Update Behavior**: Submitting a new rating for the same user updates their existing rating\n- **Rotating Buffer**: Once 100 ratings are reached, oldest ratings are removed (FIFO)\n- **Aggregate Calculation**: Simple arithmetic mean of all ratings\n- **Service Location**: `registry/services/rating_service.py`\n\n**Web UI Integration:**\n- Interactive 5-star widget on server/agent detail pages\n- Visual feedback showing aggregate rating and count\n- Click to submit rating (requires authentication)\n- Real-time update on submission\n\n**Use Cases:**\n- **Quality Discovery**: Find highly-rated servers/agents for specific tasks\n- **Community Feedback**: Share experiences with tools and agents\n- **Filtering**: Sort search results by rating\n- **Reputation**: Build trust in community-contributed servers/agents\n\n## 7. Configuration & Setup\n\n### 7.1. Main Environment Configuration\n\n**File**: `.env` (Project root)\n\n**Core Variables:**\n- `REGISTRY_URL`: Public URL of registry\n- `AUTH_PROVIDER`: `keycloak` or `cognito`\n- `AWS_REGION`: AWS region for services\n\n**Keycloak Configuration (if AUTH_PROVIDER=keycloak):**\n- `KEYCLOAK_URL`: Internal URL (`http://keycloak:8080`)\n- `KEYCLOAK_EXTERNAL_URL`: External URL for browser access\n- `KEYCLOAK_REALM`: Realm name (`mcp-gateway`)\n- `KEYCLOAK_ADMIN`, `KEYCLOAK_ADMIN_PASSWORD`: Admin credentials\n- `KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET`: Web client credentials (auto-generated)\n- `KEYCLOAK_M2M_CLIENT_ID`, `KEYCLOAK_M2M_CLIENT_SECRET`: M2M credentials (auto-generated)\n\n**Cognito Configuration (if AUTH_PROVIDER=cognito):**\n- `COGNITO_USER_POOL_ID`: User Pool ID\n- `COGNITO_CLIENT_ID`: App Client ID\n- `COGNITO_CLIENT_SECRET`: App Client Secret\n- `COGNITO_DOMAIN`: Cognito domain (optional)\n\n**Getting Keycloak Credentials:**\n```bash\n# Initialize Keycloak and generate credentials\ncd keycloak/setup\n./init-keycloak.sh\n\n# Retrieve existing credentials\n./get-all-client-credentials.sh\n```\n\n### 7.2. OAuth Environment Configuration\n\n**File**: `credentials-provider/oauth/.env`\n\n**Ingress Authentication:**\n```bash\n# Keycloak\nKEYCLOAK_URL=https://mcpgateway.ddns.net\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\nKEYCLOAK_M2M_CLIENT_SECRET=ZJqbsamnQs79hbUbkJLB...\n\n# OR Cognito\nINGRESS_OAUTH_USER_POOL_ID=us-east-1_vm1115QSU\nINGRESS_OAUTH_CLIENT_ID=5v2rav1v93...\nINGRESS_OAUTH_CLIENT_SECRET=1i888fnolv6k5sa1b8s5k839pdm...\n```\n\n**Egress Authentication (Multiple Providers):**\n```bash\n# Pattern: EGRESS_OAUTH_CLIENT_ID_N, EGRESS_OAUTH_CLIENT_SECRET_N\nEGRESS_OAUTH_CLIENT_ID_1=your_atlassian_client_id\nEGRESS_OAUTH_CLIENT_SECRET_1=your_atlassian_client_secret\nEGRESS_OAUTH_REDIRECT_URI_1=http://localhost:8080/callback\nEGRESS_PROVIDER_NAME_1=atlassian\nEGRESS_MCP_SERVER_NAME_1=atlassian\n```\n\n### 7.3. OAuth Providers Configuration\n\n**File**: `auth_server/oauth2_providers.yml`\n\n**Keycloak Provider:**\n```yaml\nkeycloak:\n display_name: \"Keycloak\"\n client_id: \"${KEYCLOAK_CLIENT_ID}\"\n client_secret: \"${KEYCLOAK_CLIENT_SECRET}\"\n auth_url: \"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/auth\"\n token_url: \"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token\"\n user_info_url: \"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/userinfo\"\n logout_url: \"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/logout\"\n scopes: [\"openid\", \"email\", \"profile\"]\n groups_claim: \"groups\"\n enabled: true\n```\n\n**Amazon Cognito Provider:**\n```yaml\ncognito:\n display_name: \"Amazon Cognito\"\n client_id: \"${COGNITO_CLIENT_ID}\"\n client_secret: \"${COGNITO_CLIENT_SECRET}\"\n auth_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/oauth2/authorize\"\n token_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/oauth2/token\"\n user_info_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/oauth2/userInfo\"\n logout_url: \"https://${COGNITO_DOMAIN}.auth.${AWS_REGION}.amazoncognito.com/logout\"\n scopes: [\"openid\", \"email\", \"profile\"]\n groups_claim: \"cognito:groups\"\n enabled: true\n```\n\n**Microsoft Entra ID (Azure AD) Provider:**\n```yaml\nentra_id:\n display_name: \"Microsoft Entra ID\"\n client_id: \"${ENTRA_CLIENT_ID}\"\n client_secret: \"${ENTRA_CLIENT_SECRET}\"\n tenant_id: \"${ENTRA_TENANT_ID}\"\n auth_url: \"https://login.microsoftonline.com/${ENTRA_TENANT_ID}/oauth2/v2.0/authorize\"\n token_url: \"https://login.microsoftonline.com/${ENTRA_TENANT_ID}/oauth2/v2.0/token\"\n user_info_url: \"https://graph.microsoft.com/v1.0/me\"\n logout_url: \"https://login.microsoftonline.com/${ENTRA_TENANT_ID}/oauth2/v2.0/logout\"\n scopes: [\"openid\", \"email\", \"profile\", \"User.Read\"]\n groups_claim: \"groups\"\n enabled: true\n # Enterprise features\n conditional_access: true # Support for conditional access policies\n mfa_enabled: true # Multi-factor authentication\n microsoft_365_integration: true # Integration with M365 environments\n```\n\n**References:**\n- Entra ID Setup Guide: `docs/entra-id-setup.md`\n- Keycloak Setup Guide: `docs/keycloak-setup.md`\n- Cognito Setup Guide: `docs/cognito-setup.md`\n\n### 7.4. Scopes Configuration\n\n**File**: `auth_server/scopes.yml`\n\n**Group Mappings:**\n```yaml\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n\n mcp-registry-user:\n - mcp-registry-user\n - mcp-servers-restricted/read\n```\n\n**UI Scopes:**\n```yaml\nUI-Scopes:\n mcp-registry-admin:\n list_service: [all]\n register_service: [all]\n health_check_service: [all]\n toggle_service: [all]\n modify_service: [all]\n```\n\n**Server Scopes:**\n```yaml\nmcp-servers-restricted/execute:\n - server: fininfo\n methods:\n - initialize\n - tools/list\n - tools/call\n tools:\n - get_stock_aggregates\n - print_stock_data\n```\n\n### 7.5. Credential Generation\n\n**Quick Start:**\n```bash\n# Configure environment\ncp .env.example .env\ncp credentials-provider/oauth/.env.example credentials-provider/oauth/.env\n# Edit both .env files with your credentials\n\n# Generate all credentials\n./credentials-provider/generate_creds.sh\n\n# Available options:\n# --all # Run all authentication flows (default)\n# --ingress-only # Only MCP Gateway authentication\n# --egress-only # Only external provider authentication\n# --agentcore-only # Only AgentCore token generation\n# --keycloak-only # Only Keycloak token generation\n# --provider google # Specify provider for egress auth\n# --verbose # Enable debug logging\n```\n\n**Generated Configuration Files:**\n- `.oauth-tokens/vscode_mcp.json` - VS Code MCP configuration\n- `.oauth-tokens/mcp.json` - Roocode/Claude Code configuration\n- `.oauth-tokens/ingress.json` - Ingress tokens\n- `.oauth-tokens/egress.json` - Egress tokens\n- `.oauth-tokens/agent-{name}-m2m-token.json` - Agent-specific tokens\n\n### 7.6. Keycloak Setup\n\n**Initial Setup:**\n```bash\ncd keycloak/setup\n./init-keycloak.sh\n```\n\n**This creates:**\n- `mcp-gateway` realm\n- Web and M2M clients with configurations\n- Required groups (`mcp-servers-unrestricted`, `mcp-servers-restricted`)\n- Group mappers for JWT token claims\n- Initial admin and test users\n\n**Service Account Management:**\n```bash\n# Create individual agent service account\n./setup-agent-service-account.sh --agent-id sre-agent --group mcp-servers-unrestricted\n\n# Create shared M2M service account\n./setup-m2m-service-account.sh\n```\n\n**Token Generation:**\n```bash\n# Generate M2M token for ingress\nuv run python credentials-provider/token_refresher.py\n\n# Generate agent-specific token\nuv run python credentials-provider/token_refresher.py --agent-id sre-agent\n```\n\n## 8. Observability & Monitoring\n\n### 8.1. Dual-Path Metrics System\n\n**Architecture:**\n```\nAuth Server Middleware → Metrics Service API → Dual Path:\n ├─> SQLite Database (detailed storage)\n └─> OpenTelemetry (Prometheus/Grafana)\n```\n\n**Database Tables:**\n- `auth_metrics`: Authentication requests and validation\n- `tool_metrics`: Tool execution details (calls, methods, client info)\n- `discovery_metrics`: Tool discovery/search queries\n- `metrics`: Raw metrics data (all types)\n- `api_keys`: API key management for metrics service\n\n### 8.2. Accessing SQLite Metrics\n\n**Connect to Database:**\n```bash\n# Via container\ndocker compose exec metrics-db sh\nsqlite3 /var/lib/sqlite/metrics.db\n\n# Or copy locally\ndocker compose cp metrics-db:/var/lib/sqlite/metrics.db ./metrics.db\nsqlite3 ./metrics.db\n```\n\n**Sample Queries:**\n\n**Authentication Success Rate:**\n```sql\nSELECT\n server,\n COUNT(*) as total,\n SUM(success) as successful,\n ROUND(100.0 * SUM(success) / COUNT(*), 2) as success_pct,\n ROUND(AVG(duration_ms), 2) as avg_ms\nFROM auth_metrics\nGROUP BY server\nORDER BY total DESC;\n```\n\n**Tool Usage Summary:**\n```sql\nSELECT\n tool_name,\n COUNT(*) as calls,\n SUM(success) as successful,\n ROUND(AVG(duration_ms), 2) as avg_ms,\n COUNT(DISTINCT client_name) as unique_clients\nFROM tool_metrics\nGROUP BY tool_name\nORDER BY calls DESC;\n```\n\n**Slowest Tool Executions:**\n```sql\nSELECT\n tool_name,\n server_name,\n ROUND(duration_ms, 2) as duration_ms,\n datetime(timestamp) as time,\n success\nFROM tool_metrics\nORDER BY duration_ms DESC\nLIMIT 20;\n```\n\n### 8.3. OpenTelemetry Metrics\n\n**Prometheus Endpoint**: `http://localhost:9465/metrics`\n\n**Available Metrics:**\n- `mcp_auth_requests_total` - Counter of authentication requests\n- `mcp_auth_request_duration_seconds` - Histogram of auth request durations\n- `mcp_tool_executions_total` - Counter of tool executions\n- `mcp_tool_execution_duration_seconds` - Histogram of tool execution durations\n- `mcp_tool_discovery_total` - Counter of discovery requests\n- `mcp_tool_discovery_duration_seconds` - Histogram of discovery durations\n- `mcp_protocol_latency_seconds` - Histogram of protocol flow latencies\n- `mcp_health_checks_total` - Counter of health checks\n\n**OTLP Export Configuration:**\n```bash\n# In .env\nOTEL_OTLP_ENDPOINT=http://otel-collector:4318\n```\n\n### 8.4. OpenTelemetry Collector Setup\n\n**Add to docker-compose.yml:**\n```yaml\notel-collector:\n image: otel/opentelemetry-collector-contrib:latest\n command: [\"--config=/etc/otel-collector-config.yaml\"]\n volumes:\n - ./config/otel-collector-config.yaml:/etc/otel-collector-config.yaml\n ports:\n - \"4318:4318\" # OTLP HTTP receiver\n - \"4317:4317\" # OTLP gRPC receiver\n - \"8889:8889\" # Prometheus exporter metrics\n restart: unless-stopped\n```\n\n**Basic Configuration (config/otel-collector-config.yaml):**\n```yaml\nreceivers:\n otlp:\n protocols:\n http:\n endpoint: 0.0.0.0:4318\n\nprocessors:\n batch:\n timeout: 10s\n send_batch_size: 1024\n\nexporters:\n prometheus:\n endpoint: \"0.0.0.0:8889\"\n namespace: mcp_gateway\n\n logging:\n loglevel: info\n\nservice:\n pipelines:\n metrics:\n receivers: [otlp]\n processors: [batch]\n exporters: [prometheus, logging]\n```\n\n**Cloud Backends:**\n- **AWS CloudWatch**: `awscloudwatch` exporter\n- **Datadog**: `datadog` exporter with API key\n- **New Relic**: `otlphttp/newrelic` with license key\n- **Grafana Cloud**: `otlphttp/grafanacloud` with auth\n- **Honeycomb**: `otlphttp/honeycomb` with API key\n\n### 8.5. Grafana Dashboards\n\n**Access**: `http://localhost:3000` (admin/admin)\n\n**Pre-configured Dashboards:**\n1. **Authentication Metrics**: Success rates, request volume, error codes, response times\n2. **Tool Execution Metrics**: Most used tools, client distribution, success rates, performance trends\n3. **Discovery Metrics**: Search query volume, result counts, performance breakdown\n4. **System Health**: Overall request volume, error rates, performance percentiles (p50, p95, p99)\n\n**Sample PromQL Queries:**\n```promql\n# Authentication success rate\nrate(mcp_auth_requests_total{success=\"true\"}[5m]) / rate(mcp_auth_requests_total[5m])\n\n# Average tool execution duration by server\nrate(mcp_tool_execution_duration_seconds_sum[5m]) / rate(mcp_tool_execution_duration_seconds_count[5m])\n\n# Top 5 most used tools\ntopk(5, sum by (tool_name) (rate(mcp_tool_executions_total[5m])))\n\n# 95th percentile request duration\nhistogram_quantile(0.95, rate(mcp_auth_request_duration_seconds_bucket[5m]))\n```\n\n### 8.6. Monitoring Best Practices\n\n**Key Metrics to Monitor:**\n- Authentication Success Rate: >95%\n- Tool Execution Success Rate: >90%\n- Average Response Time: <100ms (auth), <500ms (tools)\n- Error Rate: <5%\n- Discovery Query Performance: <50ms (embedding time)\n\n**Alert Configuration:**\n- Authentication failure rate >10%\n- Tool execution errors >5%\n- Response time p95 >1000ms\n- Discovery query failures\n\n**Data Retention:**\n- SQLite database: 90 days (configurable via `METRICS_RETENTION_DAYS`)\n- Prometheus: 200 hours (configurable in `prometheus.yml`)\n\n## 9. Installation & Deployment\n\n### 9.1. Quick Start (5 Minutes)\n\n```bash\n# 1. Clone and setup\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\n\n# 2. Configure environment\ncp .env.example .env\n# Edit .env with your credentials\n\n# 3. Generate authentication credentials\n./credentials-provider/generate_creds.sh\n\n# 4. Install prerequisites\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsudo apt-get update && sudo apt-get install -y docker.io docker-compose\n\n# 5. Deploy\n./build_and_run.sh\n\n# 6. Access registry\nopen http://localhost:7860\n```\n\n### 9.2. Pre-built Images (Instant Setup)\n\n**Benefits:** No build time, no Node.js required, no frontend compilation, consistent tested images\n\n```bash\n# Step 1: Clone and setup\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\ncp .env.example .env\n\n# Step 2: Download embeddings model\nhf download sentence-transformers/all-MiniLM-L6-v2 --local-dir ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2\n\n# Step 3: Configure environment\n# Complete: Initial Environment Configuration guide\nexport DOCKERHUB_ORG=mcpgateway\n\n# Step 4: Deploy with pre-built images\n./build_and_run.sh --prebuilt\n\n# Step 5: Initialize Keycloak\n# Complete: Initialize Keycloak Configuration guide\n\n# Step 6: Access registry\nopen http://localhost:7860\n\n# Step 7: Create first agent account\n# Complete: Create Your First AI Agent Account guide\n\n# Step 8: Restart auth server\ndocker-compose down auth-server && docker-compose rm -f auth-server && docker-compose up -d auth-server\n\n# Step 9: Test the setup\n# Complete: Testing with mcp_client.py and agent.py guide\n```\n\n### 9.3. Amazon EC2 Deployment\n\n**System Requirements:**\n- **Minimum (Development)**: t3.large (2 vCPU, 8GB RAM), 20GB SSD\n- **Recommended (Production)**: t3.2xlarge (8 vCPU, 32GB RAM), 50GB+ SSD\n\n**Detailed Setup:**\n```bash\n# 1. Create directories\nmkdir -p ${HOME}/mcp-gateway/{servers,auth_server,secrets,logs}\ncp -r registry/servers ${HOME}/mcp-gateway/\ncp auth_server/scopes.yml ${HOME}/mcp-gateway/auth_server/\n\n# 2. Configure environment\ncp .env.example .env\nnano .env # Configure required values\n\n# 3. Generate credentials\ncp credentials-provider/oauth/.env.example credentials-provider/oauth/.env\nnano credentials-provider/oauth/.env\n./credentials-provider/generate_creds.sh\n\n# 4. Install dependencies\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource $HOME/.local/bin/env\nuv venv --python 3.14 && source .venv/bin/activate\n\nsudo apt-get update\nsudo apt-get install --reinstall docker.io -y\nsudo apt-get install -y docker-compose\nsudo usermod -a -G docker $USER\nnewgrp docker\n\n# 5. Deploy services\n./build_and_run.sh\n```\n\n### 9.4. HTTPS Configuration\n\n**Option A: Let's Encrypt**\n```bash\n# Install certbot\nsudo apt-get install -y certbot\n\n# Get certificate\nsudo certbot certonly --standalone -d your-domain.com\n\n# Copy certificates\nmkdir -p ${HOME}/mcp-gateway/ssl/{certs,private}\ncp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/\ncp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/\nchmod 644 ${HOME}/mcp-gateway/ssl/certs/fullchain.pem\nchmod 600 ${HOME}/mcp-gateway/ssl/private/privkey.pem\n\n# Deploy\n./build_and_run.sh\n```\n\n**Certificate Renewal (Cron):**\n```bash\nsudo crontab -e\n# Add:\n0 0,12 * * * certbot renew --quiet && cp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/fullchain.pem && cp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/privkey.pem && docker compose restart registry\n```\n\n### 9.5. Amazon EKS Deployment\n\nFor production Kubernetes deployments, see [EKS deployment guide](https://github.com/aws-samples/amazon-eks-machine-learning-with-terraform-and-kubeflow/tree/master/examples/agentic/mcp-gateway-microservices).\n\n**Key Benefits:**\n- High Availability: Multi-AZ pod distribution\n- Auto Scaling: Horizontal pod autoscaling based on metrics\n- Service Mesh: Istio integration for advanced traffic management\n- Observability: Native CloudWatch and Prometheus integration\n- Security: Pod security policies and network policies\n\n### 9.6. AWS ECS Deployment (RECOMMENDED FOR PRODUCTION)\n\n**Production-grade infrastructure** using AWS ECS Fargate with complete Terraform automation. This is the **most mature deployment option** for AWS production environments.\n\n**Key Benefits:**\n- **Fully Managed Compute**: ECS Fargate eliminates server management\n- **Multi-AZ High Availability**: Services deployed across multiple availability zones\n- **Auto-Scaling**: Task-level autoscaling based on CPU/memory metrics\n- **Native AWS Integration**: CloudWatch, Secrets Manager, DocumentDB, Aurora\n- **Infrastructure as Code**: Complete Terraform configuration in `terraform/aws-ecs/`\n- **SSL/TLS**: Automatic certificate provisioning via AWS Certificate Manager\n- **Cost Optimized**: Aurora Serverless v2 auto-scales from 0.5 to 2 ACUs\n\n**Architecture Components:**\n- **Compute**: ECS Fargate tasks (serverless containers)\n- **Load Balancers**:\n - Main ALB (internet-facing) for Registry and Auth Server\n - Keycloak ALB for identity management\n- **Data Layer**:\n - **Amazon DocumentDB**: Primary storage with native HNSW vector search\n - **Amazon Aurora PostgreSQL Serverless v2**: User data and sessions\n- **Networking**: VPC with public/private subnets across 2 AZs\n- **Security**: AWS Secrets Manager, SSL/TLS, security groups\n- **Observability**: CloudWatch Logs, CloudWatch Alarms, SNS notifications\n\n**Quick Start:**\n```bash\n# Prerequisites: Domain with Route53 hosted zone, AWS credentials\n\ncd terraform/aws-ecs\n\n# Step 1: Configure variables\ncp terraform.tfvars.example terraform.tfvars\nnano terraform.tfvars # Set domain_name, aws_region, etc.\n\n# Step 2: Initialize Terraform\nterraform init\n\n# Step 3: Review deployment plan\nterraform plan\n\n# Step 4: Deploy infrastructure (~60-90 minutes)\nterraform apply\n\n# Step 5: Get outputs\nterraform output -json > terraform-outputs.json\n```\n\n**Post-Deployment:**\n```bash\n# View service URLs\nterraform output registry_url\nterraform output keycloak_url\n\n# Monitor logs\n./scripts/view-cloudwatch-logs.sh registry\n./scripts/view-cloudwatch-logs.sh auth-server\n\n# Check service health\naws ecs describe-services --cluster mcp-gateway-ecs-cluster \\\n --services mcp-gateway-v2-registry\n\n# Scale services\naws ecs update-service --cluster mcp-gateway-ecs-cluster \\\n --service mcp-gateway-v2-registry --desired-count 3\n```\n\n**Configuration:**\n- **Deployment Time**: 60-90 minutes for initial deployment\n- **Prerequisites**:\n - Domain with Route53 hosted zone (any registrar supported)\n - AWS account with AdministratorAccess or specific IAM permissions\n - Terraform >= 1.5.0, AWS CLI >= 2.0, Docker >= 20.10\n- **Region Support**: All commercial AWS regions\n- **Regional Domains**: Automatic subdomain creation (e.g., `registry.us-east-1.your.domain`)\n\n**Documentation:**\n- Complete guide: `terraform/aws-ecs/README.md`\n- Architecture diagrams: `terraform/aws-ecs/img/`\n- Troubleshooting: `terraform/aws-ecs/README.md#troubleshooting`\n- Cost optimization: `terraform/aws-ecs/README.md#cost-optimization`\n\n**Comparison: ECS vs EKS vs EC2**\n\n| Feature | ECS Fargate | EKS | EC2 |\n|---------|-------------|-----|-----|\n| **Maturity** | ✅ Production-ready | ⚠️ Preview/Experimental | ✅ Stable |\n| **Management** | Fully managed | Managed control plane | Self-managed |\n| **IaC** | Complete Terraform | Partial | Docker Compose |\n| **Scaling** | Auto-scaling tasks | Horizontal pod autoscaling | Manual/script-based |\n| **Cost** | Pay-per-task | Higher (node costs) | Fixed instance costs |\n| **Setup Time** | 60-90 min | 2-4 hours | 30-60 min |\n| **Best For** | Production deployments | K8s-native workloads | Development/testing |\n\n### 9.7. Post-Installation Verification\n\n```bash\n# Check service status\ndocker-compose ps\ndocker-compose logs -f\n\n# Test web interface\nopen http://localhost:7860\n\n# Test authentication\ncd tests\n./mcp_cmds.sh ping\n\n# Configure AI assistants\n./credentials-provider/generate_creds.sh\ncp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json\n```\n\n## 10. Testing & Integration\n\n### 10.1. MCP Testing Tools\n\n**Test Script**: `tests/mcp_cmds.sh`\n\n```bash\n# Test basic connectivity\n./tests/mcp_cmds.sh basic\n\n# Test MCP connectivity with authentication\n./tests/mcp_cmds.sh ping\n\n# List available tools (filtered by permissions)\n./tests/mcp_cmds.sh list\n\n# Call specific tools\n./tests/mcp_cmds.sh call debug_auth_context '{}'\n./tests/mcp_cmds.sh call intelligent_tool_finder '{\"natural_language_query\": \"quantum\"}'\n./tests/mcp_cmds.sh call currenttime current_time_by_timezone '{\"tz_name\": \"America/New_York\"}'\n\n# Test against different gateway URLs\nGATEWAY_URL=https://your-domain.com/mcp ./tests/mcp_cmds.sh ping\n./tests/mcp_cmds.sh --url https://your-domain.com/mcp list\n```\n\n**Python MCP Client**: `cli/mcp_client.py`\n```bash\n# Core operations\nuv run python cli/mcp_client.py --operation ping\nuv run python cli/mcp_client.py --operation list\nuv run python cli/mcp_client.py --operation call --tool-name get_stock_aggregates --arguments '{\"ticker\": \"AAPL\"}'\n```\n\n**Python Agent**: `agents/agent.py`\n```bash\n# Full-featured agent with AI capabilities\nuv run python agents/agent.py --user-query \"What time is it in Tokyo?\"\n```\n\n### 10.2. Anthropic API Testing\n\n**Test Script**: `cli/test_anthropic_api.py`\n\n```bash\n# Run all tests\nuv run python cli/test_anthropic_api.py --token-file /path/to/token-file.json\n\n# Test specific endpoint\nuv run python cli/test_anthropic_api.py \\\n --token-file /path/to/token-file.json \\\n --test list-servers \\\n --limit 10\n\n# Get server details\nuv run python cli/test_anthropic_api.py \\\n --token-file /path/to/token-file.json \\\n --test get-server \\\n --server-name io.mcpgateway/atlassian\n```\n\n### 10.3. Credential Validation\n\n```bash\n# Validate all OAuth configurations\ncd credentials-provider\n./generate_creds.sh --verbose\n\n# Test specific authentication flows\n./generate_creds.sh --ingress-only --verbose # MCP Gateway auth\n./generate_creds.sh --egress-only --verbose # External provider auth\n./generate_creds.sh --agentcore-only --verbose # AgentCore auth\n```\n\n### 10.4. Testing Architecture\n\n**IMPORTANT:** The project uses **pytest as the primary testing framework**. Shell script tests in `tests/mcp_cmds.sh` are **DEPRECATED** and maintained only for backward compatibility.\n\n**Test Categories:**\n- **Unit Tests** (`tests/unit/`): Test individual functions and classes in isolation\n- **Integration Tests** (`tests/integration/`): Test multiple components working together\n- **E2E Tests** (`tests/e2e/`): End-to-end workflow tests\n\n**Running Tests:**\n```bash\n# Run all tests with parallel execution (8 workers)\nuv run pytest tests/ -n 8\n\n# Expected results (as of 2026-01-06):\n# - 701 passed\n# - 57 skipped\n# - Coverage: ~39.50%\n# - Execution time: ~30 seconds\n\n# Run tests serially (slower, less memory)\nuv run pytest tests/\n\n# Run specific test categories\nuv run pytest tests/unit/ # Unit tests only\nuv run pytest tests/integration/ # Integration tests only\nuv run pytest tests/e2e/ # E2E tests only\n\n# Run with coverage report\nuv run pytest tests/ -n 8 --cov=registry --cov-report=term-missing\n\n# Run specific test file\nuv run pytest tests/unit/test_server_service.py -v\n\n# Stop at first failure\nuv run pytest tests/ -n 8 -x\n```\n\n**Test Configuration:**\n- **Location**: `pyproject.toml` lines 78-114\n- **Minimum Coverage**: 35% (configured in pyproject.toml)\n- **Test Markers**: unit, integration, e2e, auth, servers, search, health, core, repositories, slow, requires_models\n- **Async Mode**: Auto-detected for async tests\n- **Reports**: HTML report at `tests/reports/report.html`, JSON at `tests/reports/report.json`\n\n**Test Prerequisites:**\n```bash\n# MongoDB must be running for integration tests\ndocker ps | grep mongo\n# Should show: mcp-mongodb running on 0.0.0.0:27017\n\n# Environment is auto-configured:\n# - DOCUMENTDB_HOST=localhost\n# - STORAGE_BACKEND=mongodb-ce\n# - directConnection=true (single-node MongoDB)\n```\n\n**Test Best Practices:**\n\n1. **Repository Reset Pattern** (for test isolation):\n```python\n@pytest.fixture(autouse=True)\nasync def reset_repository():\n \"\"\"Reset repository state before each test.\"\"\"\n repo = await get_server_repository()\n await repo.reset() # Clear all data\n yield\n # Cleanup handled by TestClient teardown\n```\n\n2. **Memory Management** (avoid OOM on EC2):\n```python\n# Use -n 8 for parallel tests only if you have enough memory\n# Otherwise run serially: uv run pytest tests/\n\n# For CI/CD pipelines, use moderate parallelism:\npytest tests/ -n 2\n```\n\n3. **Fixture Cleanup**:\n```python\n# Always cleanup resources in fixtures\n@pytest.fixture\nasync def test_client():\n async with AsyncClient(app=app, base_url=\"http://test\") as client:\n yield client\n # Automatic cleanup via async context manager\n```\n\n4. **Mock External Dependencies**:\n```python\n# Mock security scanner, embeddings, external APIs\n@pytest.fixture(autouse=True)\ndef mock_security_scanner():\n mock_service = MagicMock()\n mock_service.get_scan_config.return_value = SecurityScanConfig(enabled=False)\n with patch(\"registry.api.server_routes.security_scanner_service\", mock_service):\n yield mock_service\n```\n\n**Shell Script Tests (DEPRECATED):**\n```bash\n# tests/mcp_cmds.sh - Use pytest instead\n# These are maintained for backward compatibility only\n./tests/mcp_cmds.sh basic\n./tests/mcp_cmds.sh ping\n./tests/mcp_cmds.sh list\n```\n\n**Continuous Integration:**\n- Tests run automatically via GitHub Actions\n- Triggered on PR creation and pushes to main/develop\n- Configuration: `.github/workflows/registry-test.yml`\n- All unit tests must pass (no failures allowed)\n\n**Test Documentation:**\n- Comprehensive guide: `docs/testing/README.md`\n- Writing tests: `docs/testing/WRITING_TESTS.md`\n- Test maintenance: `docs/testing/MAINTENANCE.md`\n- Memory management: `docs/testing/memory-management.md`\n\n**Coverage Requirements:**\n- Minimum: 35% overall coverage (enforced)\n- Target: 80% coverage for new features\n- Coverage report: `htmlcov/index.html` (generated after test run)\n\n## 11. Security Features\n\n### 11.1. Security Scanning\n\n**IMPORTANT:** The MCP Gateway & Registry provides **TWO SEPARATE security scanning systems** - one for MCP servers and one for A2A agents.\n\n#### MCP Server Security Scanning\n\n**Integrated Vulnerability Detection** with [Cisco AI Defence MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner):\n- Automated security scanning during server registration\n- Periodic registry-wide scans\n- YARA pattern matching for malicious code detection\n- Detailed security reports with vulnerability details, severity assessments, and remediation recommendations\n- Automatic protection: Servers with security issues automatically disabled\n- Compliance ready: Security audit trails and vulnerability tracking\n\n**Configuration:**\n```bash\n# Enable MCP server scanning\nSECURITY_SCAN_ENABLED=true\nSECURITY_SCAN_ON_REGISTRATION=true\nBLOCK_UNSAFE_SERVERS=true\n```\n\n**Service Location:** `registry/services/security_scanner.py`\n**Scanner Integration:** `registry/api/server_routes.py` (automatic during registration)\n\n#### A2A Agent Security Scanning\n\n**Integrated Agent Vulnerability Detection** with [Cisco AI Defense A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner):\n- Automated security scanning during agent registration\n- Multi-analyzer support: YARA pattern matching, LLM-based analysis, static analysis\n- Agent card validation and security assessment\n- Configurable blocking policies for unsafe agents\n- Detailed scan reports with security findings and recommendations\n- Optional \"security-pending\" tagging for agents awaiting scan results\n\n**Configuration:**\n```bash\n# Enable A2A agent scanning\nAGENT_SECURITY_SCAN_ENABLED=true\nAGENT_SECURITY_SCAN_ON_REGISTRATION=true\nAGENT_SECURITY_BLOCK_UNSAFE_AGENTS=true\nAGENT_SECURITY_ANALYZERS=yara,llm # Comma-separated list\nAGENT_SECURITY_SCAN_TIMEOUT=300\nA2A_SCANNER_LLM_API_KEY=your-api-key # For LLM-based analysis\nAGENT_SECURITY_ADD_PENDING_TAG=true # Add security-pending tag during scan\n```\n\n**Service Location:** `registry/services/agent_scanner.py`\n**Scanner Integration:** `registry/api/agent_routes.py` (automatic during registration)\n**Scan Storage:** Results stored in security scan repository for audit trails\n\n**Analyzers:**\n- **YARA**: Pattern-based malicious code detection\n- **LLM**: AI-powered security analysis using Azure OpenAI\n- **Static**: Code structure and configuration analysis\n\n**Security Scan Results API:**\n```bash\n# Get agent scan results\nGET /api/v2/agents/{agent_path}/security-scan\n\n# Get server scan results\nGET /api/v2/servers/{server_path}/security-scan\n```\n\n### 11.2. Security Best Practices\n\n**Token Storage:**\n- Tokens stored with `600` permissions in `.oauth-tokens/`\n- Never commit `.env` files to version control\n- Use secure secret management for production\n\n**Network Security:**\n- HTTPS-only for production\n- PKCE where supported\n- SSL/TLS certificate management\n\n**Access Control:**\n- Follow principle of least privilege\n- Regular group membership reviews\n- Scope-based authorization at server, method, and tool levels\n\n**Token Lifecycle:**\n- Ingress tokens: 1-hour expiry, auto-refresh via client credentials\n- Egress tokens: Provider-specific, refresh tokens where available\n- Automated refresh service for continuous monitoring\n\n**Audit & Compliance:**\n- Complete audit trails (Nginx access logs + auth server logs + IdP logs)\n- Comprehensive metrics for compliance reporting\n- Security event tracking and monitoring\n\n### 11.3. Token Refresh Service\n\n**Automated Token Refresh Service** provides:\n- Continuous monitoring of all OAuth tokens for expiration\n- Proactive refresh before tokens expire (configurable 1-hour buffer)\n- Automatic MCP config generation for coding assistants\n- Service discovery for both OAuth and no-auth services\n- Background operation with comprehensive logging\n\n**Start the service:**\n```bash\n./start_token_refresher.sh\n```\n\n**Generated configurations:**\n- `.oauth-tokens/vscode_mcp.json` - VS Code extensions\n- `.oauth-tokens/mcp.json` - Claude Code/Roocode\n- Standard configuration format for custom MCP clients\n\n## 12. Enterprise Features\n\n### 12.1. AI Coding Assistants Integration\n\n**Supported Assistants:**\n- VS Code with MCP extension\n- Cursor\n- Claude Code (Roo Code)\n- Cline\n\n**Setup:**\n```bash\n# Generate configurations\n./credentials-provider/generate_creds.sh\n\n# VS Code\ncp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json\n\n# Roo Code\ncp .oauth-tokens/mcp.json ~/.vscode/mcp-settings.json\n```\n\n### 12.2. Federation with External Registries\n\n**Federation Architecture** allows you to import and manage servers/agents from multiple external registries through a unified interface with centralized authentication and access control.\n\n**Supported Federation Sources:**\n\n| Source | Type | Description | Visual Tag | Auth Required |\n|--------|------|-------------|------------|---------------|\n| **Anthropic MCP Registry** | MCP Servers | Official Anthropic curated servers | `ANTHROPIC` (purple) | No |\n| **Workday ASOR** | AI Agents | Agent System of Record | `ASOR` (orange) | Yes (OAuth) |\n\n**Key Benefits:**\n- **Centralized Management**: Single interface for all servers/agents regardless of source\n- **Unified Authentication**: Consistent auth/authz across all federated entities\n- **Visual Tagging**: Color-coded tags show federation source (purple for Anthropic, orange for ASOR)\n- **Automatic Synchronization**: Scheduled sync to keep federation up-to-date\n- **Selective Import**: Import all or specific entities from each source\n- **Audit Trail**: Complete tracking of federated entity provenance\n\n#### Anthropic MCP Registry Integration\n\n**Features:**\n- Import servers from [Anthropic's official MCP Registry](https://registry.modelcontextprotocol.io)\n- Full REST API compatibility\n- No authentication required\n- Purple `ANTHROPIC` visual tag on federated servers\n- Unified access through your gateway with centralized auth\n\n**Configuration:**\n```bash\n# Enable Anthropic federation in .env\nANTHROPIC_REGISTRY_ENABLED=true\n\n# Federation config file: ~/mcp-gateway/federation.json\n{\n \"anthropic\": {\n \"enabled\": true,\n \"endpoint\": \"https://registry.modelcontextprotocol.io\",\n \"servers\": [] # Empty = import all, or specify: [{\"name\": \"server-name\"}]\n }\n}\n```\n\n**Import Servers:**\n```bash\n# Interactive selection\n./cli/import_anthropic_servers.py --select\n\n# Import all available servers\n./cli/import_anthropic_servers.py --all\n\n# Import specific servers (via federation.json)\n{\n \"anthropic\": {\n \"servers\": [\n {\"name\": \"io.github.jgador/websharp\"},\n {\"name\": \"modelcontextprotocol/filesystem\"},\n {\"name\": \"modelcontextprotocol/brave-search\"}\n ]\n }\n}\n```\n\n**Service Location:** `registry/services/federation/anthropic.py`\n\n#### Workday ASOR Integration\n\n**Features:**\n- Import AI agents from Workday Agent System of Record\n- OAuth 2.0 authentication with token refresh\n- Orange `ASOR` visual tag on federated agents\n- Enterprise agent lifecycle management\n- Scheduled synchronization with ASOR backend\n\n**Prerequisites:**\n1. Valid Workday tenant with ASOR enabled\n2. OAuth credentials (Client ID and Secret)\n3. Access token with \"Agent System of Record\" scope\n\n**Configuration:**\n```bash\n# Add to .env\nASOR_CLIENT_ID=your_client_id\nASOR_CLIENT_SECRET=your_client_secret\nASOR_TENANT_NAME=your_tenant_name\nASOR_HOSTNAME=your_host_name\nASOR_ACCESS_TOKEN=your_oauth_token # Generated via get_asor_token.py\n\n# Federation config: ~/mcp-gateway/federation.json\n{\n \"asor\": {\n \"enabled\": true,\n \"endpoint\": \"https://wcpdev-services1.wd103.myworkday.com/ccx/api/asor/v1/awsasor_wcpdev1\",\n \"auth_env_var\": \"ASOR_ACCESS_TOKEN\",\n \"agents\": [] # Empty = import all\n }\n}\n```\n\n**Get OAuth Token:**\n```bash\n# Run token generator (interactive OAuth flow)\npython3 get_asor_token.py\n\n# Follow prompts to:\n# 1. Authorize via browser\n# 2. Complete OAuth flow\n# 3. Receive access token for .env\n```\n\n**Service Location:** `registry/services/federation/asor.py`\n\n#### Federation Synchronization\n\n**Automatic Sync:**\n- Periodic synchronization keeps federated entities up-to-date\n- Configurable sync schedule\n- Handles entity updates, additions, and removals\n- Maintains federation metadata (source, sync timestamp)\n\n**Manual Sync:**\n```bash\n# Trigger manual federation sync\nuv run python -m registry.services.federation.sync\n\n# Sync specific source\nuv run python -m registry.services.federation.sync --source anthropic\nuv run python -m registry.services.federation.sync --source asor\n```\n\n**Documentation:** Complete federation guide at `docs/federation.md`\n\n### 12.3. Token Vending Service\n\n**Capabilities:**\n- JWT token generation for M2M authentication\n- Service account provisioning\n- Automated token lifecycle management\n- Integration with identity providers\n\n**Usage:**\n```bash\n# Generate token for agent\nuv run python credentials-provider/token_refresher.py --agent-id sre-agent\n\n# Check generated token\ncat .oauth-tokens/agent-sre-agent-m2m-token.json\n```\n\n## 13. Troubleshooting\n\n### 13.1. Common Issues\n\n**Services won't start:**\n```bash\n# Check Docker daemon\nsudo systemctl status docker\n\n# Check environment variables\ncat .env | grep -v SECRET\n\n# View detailed logs\ndocker-compose logs --tail=50\n```\n\n**Authentication failures:**\n```bash\n# Verify Cognito/Keycloak configuration\naws cognito-idp describe-user-pool --user-pool-id YOUR_POOL_ID\n\n# Test credential generation\ncd credentials-provider && ./generate_creds.sh --verbose\n```\n\n**Network connectivity issues:**\n```bash\n# Check port availability\nsudo netstat -tlnp | grep -E ':(80|443|7860|8080)'\n\n# Test internal services\ncurl -v http://localhost:7860/health\n```\n\n**Permission denied errors:**\n- Check user's Cognito/Keycloak group memberships\n- Verify scope mappings in `scopes.yml`\n- Ensure tool names match exactly\n- Regenerate tokens after group changes\n\n**HTTPS not working:**\n```bash\n# Check certificate files\nls -la ${HOME}/mcp-gateway/ssl/certs/ ${HOME}/mcp-gateway/ssl/private/\n\n# Check container logs\ndocker compose logs registry | grep -i ssl\n\n# Verify port 443\nsudo netstat -tlnp | grep 443\n```\n\n### 13.2. Debugging Tools\n\n**Enable Verbose Logging:**\n```python\n# In auth_server/server.py or relevant module\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n**Authentication Event Logging:**\n```python\ndef log_auth_event(event_type: str, username: str = None, details: dict = None):\n logger.info(f\"AUTH_EVENT: {event_type}\", extra={\n 'username': username,\n 'event_type': event_type,\n 'details': details,\n 'timestamp': datetime.utcnow().isoformat()\n })\n```\n\n**Health Check:**\n```bash\ncurl http://localhost:7860/health\n```\n\n## 14. Code Organization & Patterns\n\n**CRITICAL:** The MCP Gateway & Registry follows strict architectural patterns to ensure maintainability and consistency. Follow these patterns religiously - violations will break the application architecture.\n\n### 14.1. Layered Architecture (MANDATORY)\n\n**The application MUST follow this layered architecture:**\n\n```\nAPI Routes → Services → Repositories → Storage Backends\n```\n\n**Each layer has specific responsibilities:**\n\n1. **API Routes** (`registry/api/`):\n - Handle HTTP requests and responses\n - Validate request parameters\n - Call service layer methods\n - Return HTTP status codes and responses\n - **NEVER access repositories directly**\n\n2. **Service Layer** (`registry/services/`):\n - Implement business logic\n - Coordinate between multiple repositories\n - Handle complex operations and workflows\n - Validate business rules\n - **ALWAYS use factory pattern to get repositories**\n\n3. **Repository Layer** (`registry/repositories/`):\n - Abstract data access via interfaces (`interfaces.py`)\n - Provide consistent API across all storage backends\n - Handle data persistence and retrieval\n - Implement search and querying logic\n\n4. **Storage Backends** (`registry/repositories/{backend}/`):\n - Implement repository interfaces for specific storage\n - File backend: `registry/repositories/file/` (DEPRECATED)\n - MongoDB CE: `registry/repositories/mongodb/`\n - DocumentDB: `registry/repositories/documentdb/`\n\n### 14.2. Factory Pattern (REQUIRED)\n\n**ALWAYS use the factory pattern** to obtain repository instances. NEVER instantiate repositories directly.\n\n**Correct Usage:**\n```python\nfrom registry.repositories.factory import (\n get_server_repository,\n get_agent_repository,\n get_scope_repository,\n get_search_repository,\n get_security_scan_repository\n)\n\n# In service layer\nasync def some_service_method():\n server_repo = await get_server_repository()\n servers = await server_repo.get_all_servers()\n return servers\n```\n\n**Wrong Usage (ANTIPATTERN):**\n```python\n# ❌ NEVER DO THIS - Direct instantiation\nfrom registry.repositories.documentdb.server_repository import DocumentDBServerRepository\nserver_repo = DocumentDBServerRepository() # WRONG!\n\n# ❌ NEVER DO THIS - Direct repository access from routes\nfrom registry.api.server_routes import router\n\n@router.get(\"/servers\")\nasync def list_servers():\n server_repo = await get_server_repository() # WRONG! Use service layer\n return await server_repo.get_all_servers()\n```\n\n### 14.3. Repository Abstraction\n\n**All storage backends MUST provide identical behavior** through polymorphism. Code using repositories should work with ANY backend without modification.\n\n**Abstract Base Classes:**\n- `BaseServerRepository` (registry/repositories/interfaces.py)\n- `BaseAgentRepository`\n- `BaseScopeRepository`\n- `BaseSearchRepository`\n- `BaseSecurityScanRepository`\n\n**Implementation Contract:**\n```python\n# All implementations must provide the same methods with the same signatures\nclass DocumentDBServerRepository(BaseServerRepository):\n async def get_all_servers(self, namespace: Optional[str] = None) -> List[dict]:\n # DocumentDB-specific implementation\n pass\n\nclass FileServerRepository(BaseServerRepository):\n async def get_all_servers(self, namespace: Optional[str] = None) -> List[dict]:\n # File-specific implementation (DEPRECATED)\n pass\n```\n\n### 14.4. Critical Antipatterns (DO NOT DO THIS)\n\n**❌ 1. Direct Repository Access from Routes**\n```python\n# WRONG - Route directly accessing repository\n@router.get(\"/servers/{server_path}\")\nasync def get_server(server_path: str):\n repo = await get_server_repository() # ANTIPATTERN!\n return await repo.get_server(server_path)\n\n# CORRECT - Route calls service layer\n@router.get(\"/servers/{server_path}\")\nasync def get_server(server_path: str):\n return await server_service.get_server(server_path)\n```\n\n**❌ 2. Direct Repository Instantiation**\n```python\n# WRONG - Bypasses factory pattern\nfrom registry.repositories.documentdb.server_repository import DocumentDBServerRepository\nrepo = DocumentDBServerRepository() # ANTIPATTERN!\n\n# CORRECT - Use factory\nfrom registry.repositories.factory import get_server_repository\nrepo = await get_server_repository()\n```\n\n**❌ 3. Hardcoding Storage Backend**\n```python\n# WRONG - Hardcoded backend selection\nif storage_type == \"documentdb\":\n repo = DocumentDBServerRepository()\nelif storage_type == \"file\":\n repo = FileServerRepository()\n\n# CORRECT - Factory handles backend selection\nrepo = await get_server_repository() # Uses STORAGE_BACKEND env var\n```\n\n**❌ 4. Skipping Service Layer**\n```python\n# WRONG - Route contains business logic\n@router.post(\"/servers\")\nasync def create_server(server: ServerRegistration):\n repo = await get_server_repository()\n # Business logic here - ANTIPATTERN!\n if server.status == \"active\":\n await repo.create_server(server)\n return {\"status\": \"created\"}\n\n# CORRECT - Business logic in service layer\n@router.post(\"/servers\")\nasync def create_server(server: ServerRegistration):\n return await server_service.create_server(server)\n```\n\n**❌ 5. Implementing Custom Vector Search**\n```python\n# WRONG - Custom vector search implementation\ndef custom_vector_search(query: str):\n # Don't implement your own vector search!\n pass\n\n# CORRECT - Use repository abstraction\nsearch_repo = await get_search_repository()\nresults = await search_repo.hybrid_search(query)\n```\n\n### 14.5. Code Organization Checklist\n\nBefore submitting code, verify:\n\n- [ ] **No direct repository access from routes** - All routes call service layer\n- [ ] **Factory pattern used** - No direct repository instantiation\n- [ ] **Service layer exists** - Business logic in `registry/services/`\n- [ ] **Repository interfaces** - New repositories extend abstract base classes\n- [ ] **Backend agnostic** - Code works with any storage backend\n- [ ] **No hardcoded backends** - Use `STORAGE_BACKEND` environment variable\n- [ ] **Separation of concerns** - Each layer handles only its responsibility\n- [ ] **Polymorphism** - All repository implementations provide identical APIs\n\n### 14.6. Design Documentation\n\n**Architecture References:**\n- Database Abstraction Layer: `docs/design/database-abstraction-layer.md`\n- Storage Architecture: `docs/design/storage-architecture-mongodb-documentdb.md`\n- Repository Pattern: `registry/repositories/interfaces.py` (docstrings)\n\n**When to Read Design Docs:**\n- Before implementing new repository backend\n- Before adding new data access patterns\n- When confused about layering\n- When reviewing code for architecture compliance\n\n## 15. Additional Resources\n\n### 15.1. Documentation Links\n\n- [Complete Setup Guide](docs/complete-setup-guide.md) - Step-by-step from scratch on AWS EC2\n- [Installation Guide](docs/installation.md) - Complete setup instructions for EC2 and EKS\n- [Configuration Reference](docs/configuration.md) - Environment variables and settings\n- [Authentication Guide](docs/auth.md) - OAuth and identity provider integration\n- [Keycloak Integration](docs/keycloak-integration.md) - Enterprise identity with agent audit trails\n- [Amazon Cognito Setup](docs/cognito.md) - Step-by-step IdP configuration\n- [Fine-Grained Access Control](docs/scopes.md) - Permission management and security\n- [Dynamic Tool Discovery](docs/dynamic-tool-discovery.md) - Autonomous agent capabilities\n- [AI Coding Assistants Setup](docs/ai-coding-assistants-setup.md) - VS Code, Cursor, Claude Code integration\n- [API Reference](docs/registry_api.md) - Programmatic registry management\n- [Anthropic Registry API](docs/anthropic_registry_api.md) - REST API compatibility\n- [Service Management](docs/service-management.md) - Server lifecycle and operations\n- [Token Refresh Service](docs/token-refresh-service.md) - Automated token refresh and lifecycle management\n- [Observability Guide](docs/OBSERVABILITY.md) - Metrics, monitoring, and OpenTelemetry setup\n- [Troubleshooting Guide](docs/faq/index.md) - Common issues and solutions\n- [Architectural Decision](docs/design/architectural-decision-reverse-proxy-vs-application-layer-gateway.md) - Reverse proxy vs application layer gateway\n- [Registry Auth Architecture](docs/registry-auth-architecture.md) - Internal authentication mechanisms\n\n### 14.2. Community & Support\n\n**Getting Help:**\n- [FAQ & Troubleshooting](docs/faq/index.md) - Common questions and solutions\n- [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues) - Bug reports and feature requests\n- [GitHub Discussions](https://github.com/agentic-community/mcp-gateway-registry/discussions) - Community support and ideas\n\n**Contributing:**\n- [Contributing Guide](CONTRIBUTING.md) - How to contribute code and documentation\n- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines and expectations\n- [Security Policy](SECURITY.md) - Responsible disclosure process\n\n### 14.3. License\n\nThis project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n*Part of the [Agentic Community](https://github.com/agentic-community) ecosystem - building the future of AI-driven development.*\n" }, { "path": "docs/logging.md", "content": "# Centralized Application Logging\n\nThe MCP Gateway Registry provides centralized application log collection, storage, and retrieval across all service instances. Logs from both the `registry` and `auth-server` services are written to a shared MongoDB/DocumentDB collection, enabling cross-pod log queries through the admin API and the Settings UI.\n\n## Architecture\n\n```\nregistry / auth-server\n |\n v\n RotatingFileHandler (always active, local file rotation)\n |\n v\n MongoDBLogHandler (optional, buffered writes via background thread)\n |\n v\n MongoDB / DocumentDB (application_logs collection with TTL index)\n |\n v\n Admin REST API (/api/admin/logs)\n |\n v\n Log Viewer UI (Settings > Application Logs)\n```\n\n### Components\n\n- **RotatingFileHandler**: Always active. Writes logs to local files with size-based rotation (default 50 MB, 5 backups). No external dependencies.\n- **MongoDBLogHandler**: Optional. Buffers log records in memory and flushes them to MongoDB periodically (default every 5 seconds or every 50 records). Uses a background daemon thread to avoid blocking the async event loop.\n- **TTL Index**: MongoDB automatically deletes log documents older than the configured retention period.\n- **Admin API**: Three endpoints for querying, exporting, and discovering log metadata. All require admin authentication.\n- **Log Viewer UI**: Filter by service, level, hostname, time range, and message content. Supports pagination and JSONL export.\n\n## Configuration Parameters\n\nAll parameters use the `APP_LOG_` prefix. The centralized (MongoDB) storage parameters use `APP_LOG_CENTRALIZED_`.\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `APP_LOG_CENTRALIZED_ENABLED` | Write application logs to MongoDB/DocumentDB for centralized retrieval | `true` |\n| `APP_LOG_CENTRALIZED_TTL_DAYS` | Days to retain log entries before automatic deletion | `1` |\n| `APP_LOG_MAX_BYTES` | Maximum size per log file in bytes before rotation | `52428800` (50 MB) |\n| `APP_LOG_BACKUP_COUNT` | Number of rotated backup files to keep | `5` |\n| `APP_LOG_MONGODB_BUFFER_SIZE` | Number of log records to buffer before flushing to MongoDB | `50` |\n| `APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS` | Seconds between periodic flushes to MongoDB | `5.0` |\n| `APP_LOG_LEVEL` | Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL | `INFO` |\n| `APP_LOG_EXCLUDED_LOGGERS` | Comma-separated logger names to exclude from MongoDB writes | `uvicorn.access,httpx,pymongo,motor` |\n\n## Deployment Configuration\n\n### Docker Compose\n\nSet parameters in your `.env` file:\n\n```bash\n# Enable centralized logging (default: true)\nAPP_LOG_CENTRALIZED_ENABLED=true\n\n# Retain logs for 1 day (default: 1)\nAPP_LOG_CENTRALIZED_TTL_DAYS=1\n\n# Optional overrides\nAPP_LOG_MAX_BYTES=52428800\nAPP_LOG_BACKUP_COUNT=5\nAPP_LOG_MONGODB_BUFFER_SIZE=50\nAPP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS=5.0\nAPP_LOG_LEVEL=INFO\nAPP_LOG_EXCLUDED_LOGGERS=uvicorn.access,httpx,pymongo,motor\n```\n\nAll `APP_LOG_*` variables are passed to both the `registry` and `auth-server` services in `docker-compose.yml`, `docker-compose.podman.yml`, and `docker-compose.prebuilt.yml`.\n\n### Terraform / ECS\n\nSet parameters in `terraform.tfvars`:\n\n```hcl\n# Enable centralized logging (default: true)\napp_log_centralized_enabled = true\n\n# Retain logs for 1 day (default: 1)\napp_log_centralized_ttl_days = 1\n\n# Optional overrides\napp_log_max_bytes = 52428800\napp_log_backup_count = 5\napp_log_mongodb_buffer_size = 50\napp_log_mongodb_flush_interval_seconds = 5.0\napp_log_level = \"INFO\"\napp_log_excluded_loggers = \"uvicorn.access,httpx,pymongo,motor\"\n```\n\nVariables are defined in `terraform/aws-ecs/variables.tf` and passed through to the ECS task definitions in `terraform/aws-ecs/modules/mcp-gateway/ecs-services.tf`. Both the registry and auth-server containers receive these environment variables.\n\n### Helm / EKS\n\nSet parameters in your values override file:\n\n```yaml\nregistry:\n app:\n appLogCentralizedEnabled: \"true\"\n appLogCentralizedTtlDays: \"1\"\n appLogMaxBytes: \"52428800\"\n appLogBackupCount: \"5\"\n appLogMongodbBufferSize: \"50\"\n appLogMongodbFlushIntervalSeconds: \"5.0\"\n appLogLevel: \"INFO\"\n appLogExcludedLoggers: \"uvicorn.access,httpx,pymongo,motor\"\n```\n\nConfiguration is managed via dedicated ConfigMaps (`registry-app-log-config` and `auth-server-app-log-config`), mounted using `envFrom` in the deployment templates.\n\nIn the umbrella chart (`mcp-gateway-registry-stack`), a YAML anchor (`&appLogConfig`) defines values once under the `registry.app` section and merges them into `auth-server.app` via `<<: *appLogConfig`, so you only need to set values in one place.\n\n## Admin API Endpoints\n\nAll endpoints require admin authentication and are rate-limited to 10 requests per 60 seconds per user.\n\n### Query Logs\n\n```\nGET /api/admin/logs\n```\n\nQuery parameters:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `service` | string | Filter by service name (e.g., `registry`, `auth-server`) |\n| `level` | string | Minimum log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) |\n| `hostname` | string | Filter by pod/hostname |\n| `search` | string | Substring search in message (max 200 chars, regex-escaped) |\n| `start` | datetime | Start of time range (ISO 8601) |\n| `end` | datetime | End of time range (ISO 8601) |\n| `limit` | int | Max entries to return (1-10000, default 100) |\n| `offset` | int | Number of entries to skip (default 0) |\n\n### Export Logs\n\n```\nGET /api/admin/logs/export\n```\n\nStreams logs as newline-delimited JSON (JSONL) for download. Accepts the same filter parameters as the query endpoint, with a higher limit (up to 50,000 entries).\n\n### Log Metadata\n\n```\nGET /api/admin/logs/metadata\n```\n\nReturns available filter values: service names, hostnames, and log levels.\n\n## Log Viewer UI\n\nNavigate to **Settings > Application Logs > Log Viewer** in the web UI.\n\nFeatures:\n- Filter by service, level, hostname, time range, and message content\n- Click any row to expand and view the full log message\n- Pagination (50 entries per page)\n- Download filtered results as JSONL\n\n## Observability\n\nThe `app_log_mongodb_flush_failures_total` Prometheus counter (labeled by `service`) tracks failed flush attempts. Use this metric to alert on write failures.\n\n## Disabling Centralized Logging\n\nTo disable MongoDB log storage while keeping file-based rotation active:\n\n```bash\nAPP_LOG_CENTRALIZED_ENABLED=false\n```\n\nWhen disabled, the admin API returns `503 Service Unavailable` and the Log Viewer UI shows an informational message. Local file rotation continues regardless of this setting.\n\n## Prerequisites\n\nCentralized logging requires:\n- `STORAGE_BACKEND` set to `documentdb` or `mongodb-ce`\n- A running MongoDB/DocumentDB instance accessible by both services\n" }, { "path": "docs/macos-setup-guide.md", "content": "# Complete macOS Setup Guide: MCP Gateway & Registry\n\nThis guide provides a comprehensive, step-by-step walkthrough for setting up the MCP Gateway & Registry on macOS. Perfect for local development and testing.\n\n> **SECURITY WARNING**\n>\n> The examples in this document use placeholder credentials for demonstration purposes only.\n> **NEVER use these example values in production.**\n>\n> Always generate unique, secure credentials and store them in:\n> - AWS Secrets Manager (production)\n> - Environment variables (development)\n> - `.env` files (local only, never commit)\n\n## Table of Contents\n1. [Prerequisites](#1-prerequisites)\n2. [Container Runtime Choice](#2-container-runtime-choice)\n3. [Cloning and Initial Setup](#3-cloning-and-initial-setup)\n4. [Environment Configuration](#4-environment-configuration)\n5. [Starting Keycloak Services](#5-starting-keycloak-services)\n6. [Keycloak Configuration](#6-keycloak-configuration)\n7. [Create Test Agent](#7-create-test-agent)\n8. [Starting All Services](#8-starting-all-services)\n9. [Verification and Testing](#9-verification-and-testing)\n10. [Podman Deployment](#10-podman-deployment)\n11. [Troubleshooting](#11-troubleshooting)\n\n---\n\n## 1. Prerequisites\n\n### System Requirements\n- **macOS**: 12.0 (Monterey) or later\n- **RAM**: At least 8GB (16GB recommended)\n- **Storage**: At least 10GB free space\n- **Administrator Access**: Sudo privileges required for Docker volume setup\n\n### Required Software\n\n**Container Runtime (choose one):**\n- **Docker Desktop**: Install from https://www.docker.com/products/docker-desktop/\n - Includes Docker Compose\n - Requires privileged port access\n - **Important**: Make sure Docker Desktop is running before proceeding!\n- **Podman Desktop** (Alternative, recommended for rootless): Install from https://podman-desktop.io/ or via Homebrew\n - Rootless container execution\n - No privileged port requirements\n - See [Podman Deployment](#10-podman-deployment) section below\n\n**Other Requirements:**\n- **Node.js**: Version 20.x LTS - Install from https://nodejs.org/ or via Homebrew (not needed with `--prebuilt` flag)\n- **Python**: Version 3.14+ - Install via Homebrew (`brew install python@3.14`)\n- **UV Package Manager**: Install with `curl -LsSf https://astral.sh/uv/install.sh | sh`\n- **Git**: Usually pre-installed on macOS\n- **jq**: Install via Homebrew (`brew install jq`)\n\n---\n\n## 2. Container Runtime Choice\n\nChoose between Docker and Podman based on your needs:\n\n### Docker (Default)\n✅ Best for: Standard deployment, familiar workflow \n✅ Uses privileged ports (80, 443) \n✅ Access at `http://localhost` \n⚠️ Requires Docker daemon running \n\n### Podman (Rootless Alternative)\n✅ Best for: Rootless deployment, no Docker daemon \n✅ Uses non-privileged ports (8080, 8443) \n✅ Access at `http://localhost:8080` \n✅ More secure, no root access needed \n\n**This guide uses Docker by default**. For Podman-specific instructions, see [Section 10: Podman Deployment](#10-podman-deployment).\n\n---\n\n## 3. Cloning and Initial Setup\n\n### Clone the Repository\n```bash\n# Create workspace directory\nmkdir -p ~/workspace\ncd ~/workspace\n\n# Clone the repository\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\n\n# Verify you're in the right directory\nls -la\n# Should see: docker-compose.yml, .env.example, README.md, etc.\n```\n\n### Setup Python Virtual Environment\n```bash\n# Enable native TLS for enterprise Macs with corporate proxies/custom CA certificates\n# (harmless on personal Macs -- uses macOS system certificate store)\nexport UV_NATIVE_TLS=true\n\n# Create and activate Python virtual environment\nuv sync\nsource .venv/bin/activate\n\n# Verify virtual environment is active\nwhich python\n# Should show: /Users/[username]/workspace/mcp-gateway-registry/.venv/bin/python\n```\n\n---\n\n## 4. Environment Configuration\n\n### Create Environment File\n```bash\n# Copy the example environment file\ncp .env.example .env\n\n# Generate a secure SECRET_KEY\nSECRET_KEY=$(python3 -c \"import secrets; print(secrets.token_urlsafe(64))\")\necho \"Generated SECRET_KEY: $SECRET_KEY\"\n\n# Open .env file for editing\nnano .env\n```\n\n### Configure Essential Settings\nIn the `.env` file, make these changes:\n\n```bash\n# Set authentication provider to Keycloak\nAUTH_PROVIDER=keycloak\n\n# Set auth server URL for local development\n# This URL must be accessible from your browser for OAuth redirects\nAUTH_SERVER_EXTERNAL_URL=http://localhost\n\n# Set secure passwords (CHANGE THESE!)\nKEYCLOAK_ADMIN_PASSWORD=your_secure_admin_password_here\nKEYCLOAK_DB_PASSWORD=your_secure_db_password_here\n\n# Set your generated SECRET_KEY\nSECRET_KEY=[paste-your-generated-key-here]\n\n\n# Leave other Keycloak settings as default for now\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_CLIENT_ID=mcp-gateway-web\n# Note: CLIENT_SECRET will be updated later after Keycloak initialization\n```\n\n**Important**: Choose strong, unique passwords and remember them - you'll need the admin password for Keycloak login!\n\n### Download Required Embeddings Model\n\nThe MCP Gateway requires a sentence-transformers model for intelligent tool discovery. Download it to the shared models directory:\n\n```bash\n# Download the embeddings model (this may take a few minutes)\nhuggingface-cli download sentence-transformers/all-MiniLM-L6-v2 --local-dir ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2\n\n# Verify the model was downloaded\nls -la ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2/\n# You should see model files like model.safetensors, config.json, etc.\n```\n\n**Note**: This command automatically creates the necessary directory structure and downloads all required model files (~90MB). If you don't have `hf` command installed, install it first with `pip install huggingface_hub[cli]`.\n\n---\n\n## 5. Starting Keycloak Services\n\n### Set Keycloak Passwords\n\n**Important**: These environment variables will override the values in your `.env` file. Use the SAME passwords you configured in Step 4!\n\n```bash\n# Use the SAME passwords you set in the .env file in Step 4!\n# Replace these with your actual passwords from Step 4\n# Note: Use single quotes to prevent issues with special characters\nexport KEYCLOAK_ADMIN_PASSWORD='your-admin-password-here-from-env'\nexport KEYCLOAK_DB_PASSWORD='your-db-password-here-from-env'\n\n# Verify they're set correctly\necho \"Admin Password: $KEYCLOAK_ADMIN_PASSWORD\"\necho \"DB Password: $KEYCLOAK_DB_PASSWORD\"\n```\n\n**Critical**: These passwords MUST match what you set in the `.env` file in Step 4. If they don't match, Keycloak initialization will fail!\n\n\n### Start Database and Keycloak\n\n**With Docker:**\n```bash\n# Start only the database and Keycloak services first\ndocker compose up -d keycloak-db keycloak\n\n# Check if services are starting\ndocker-compose ps\n\n# Monitor Keycloak logs until ready\ndocker-compose logs -f keycloak\n# Wait for: \"Keycloak 25.x.x started in xxxms\"\n# Press Ctrl+C when you see this message\n```\n\n**Wait Time**: Allow 2-3 minutes for Keycloak to fully initialize.\n\n### Verify Keycloak is Running\n```bash\n# Test basic connectivity\ncurl -s http://localhost:8080/realms/master | jq '.realm'\n# Should return: \"master\"\n\n# Check health status\ndocker-compose ps keycloak\n# Should show \"Up\" status (may show \"unhealthy\" - this is normal for dev mode)\n```\n\n### Fix macOS SSL Requirement (Critical Step)\n**Why this is needed on macOS**: Docker on macOS runs in a virtualized environment, which causes Keycloak to treat localhost requests as external network traffic. This triggers Keycloak's default security policy requiring HTTPS for external connections.\n\n```bash\n# Configure Keycloak admin CLI (use your actual admin password)\ndocker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password \"${KEYCLOAK_ADMIN_PASSWORD}\"\n\n# Disable SSL requirement for master realm\ndocker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE\n\n# Verify the fix worked\ncurl -s -o /dev/null -w \"%{http_code}\" \"http://localhost:8080/admin/\"\n# Should return: 302 (redirect to login - this is correct)\n```\n\n**Important**: This step MUST be completed before running the init-keycloak.sh script, or the initialization will fail.\n\n---\n\n## 5. Keycloak Configuration\n\n### Initialize Keycloak Configuration\n\n**Important**: This is a two-step process. The initialization script creates the realm and clients but does NOT save the credentials to files.\n\n```bash\n# Make the setup script executable\nchmod +x keycloak/setup/init-keycloak.sh\n\n# Step 1: Run the Keycloak initialization\n./keycloak/setup/init-keycloak.sh\n\n# Expected output:\n# ✓ Waiting for Keycloak to be ready...\n# ✓ Keycloak is ready!\n# ✓ Logged in to Keycloak\n# ✓ Created realm: mcp-gateway\n# ✓ Created clients: mcp-gateway-web and mcp-gateway-m2m\n# ... more success messages ...\n# ✓ Client secrets generated!\n#\n# IMPORTANT: The script will tell you to run get-all-client-credentials.sh\n# to retrieve and save the credentials. This is the next required step!\n\n# Step 2: Retrieve and save all client credentials (REQUIRED)\nchmod +x keycloak/setup/get-all-client-credentials.sh\n./keycloak/setup/get-all-client-credentials.sh\n\n# This will:\n# - Connect to Keycloak and retrieve all client secrets\n# - Save credentials to .oauth-tokens/keycloak-client-secrets.txt\n# - Create individual JSON files: .oauth-tokens/.json\n# - Create individual env files: .oauth-tokens/.env\n# - Display a summary of all saved credentials\n\n# Expected output:\n# ✓ Admin token obtained\n# ✓ Found and saved: mcp-gateway-web\n# ✓ Found and saved: mcp-gateway-m2m\n# Files created in: .oauth-tokens/\n```\n\n### Fix SSL Requirement for mcp-gateway Realm\n**Important**: Now that the mcp-gateway realm is created, we need to disable SSL for it as well:\n\n```bash\n# Configure Keycloak admin CLI (if session expired)\ndocker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password \"${KEYCLOAK_ADMIN_PASSWORD}\"\n\n# Disable SSL requirement for the mcp-gateway realm\ndocker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/mcp-gateway -s sslRequired=NONE\n\n# Verify both realms are accessible\ncurl -s -o /dev/null -w \"%{http_code}\" \"http://localhost:8080/admin/\"\n# Should return: 302\n\ncurl -s http://localhost:8080/realms/mcp-gateway | jq '.realm'\n# Should return: \"mcp-gateway\"\n```\n\n### Retrieve Client Credentials\n```bash\n# Make the credentials script executable\nchmod +x keycloak/setup/get-all-client-credentials.sh\n\n# Retrieve all client credentials\n./keycloak/setup/get-all-client-credentials.sh\n```\n\n**Expected Output:**\n```\nAdmin token obtained\nFound and saved: mcp-gateway-web (Secret: JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv)\nFound and saved: mcp-gateway-m2m (Secret: iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo)\nFiles created in: .oauth-tokens/\n```\n\n### Update Environment with Client Secrets\n```bash\n# View the retrieved client secrets\ncat .oauth-tokens/keycloak-client-secrets.txt\n\n# Copy the secrets and update your .env file\nnano .env\n\n# Update these lines with the actual secret values:\n# KEYCLOAK_CLIENT_SECRET=[paste-web-client-secret-here]\n# KEYCLOAK_M2M_CLIENT_SECRET=[paste-m2m-client-secret-here]\n\n# Save and exit (Ctrl+X, then Y, then Enter)\n```\n\n---\n\n## 6. Create Your First AI Agent Account\n\n```bash\n# Make the agent setup script executable\nchmod +x keycloak/setup/setup-agent-service-account.sh\n\n# Create a test agent with full access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id test-agent \\\n --group mcp-servers-unrestricted\n\n# Create an agent for AI coding assistants (VS Code, cursor, etc.)\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id ai-coding-assistant \\\n --group mcp-servers-unrestricted\n\n# Create an agent with restricted access for registry operations\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id registry-operator \\\n --group mcp-servers-restricted\n\n# Note: The script does not display the credentials at the end.\n# Your Client ID is: agent-test-agent-m2m\n\n# Retrieve and save ALL client credentials (recommended):\n./keycloak/setup/get-all-client-credentials.sh\n\n# This will:\n# - Retrieve credentials for ALL clients in the realm\n# - Save all credentials to .oauth-tokens/keycloak-client-secrets.txt\n# - Create individual JSON files: .oauth-tokens/.json\n# - Create individual env files: .oauth-tokens/.env\n# - Display a summary of all credentials saved\n\n# Or to get just one specific client:\n./keycloak/setup/get-agent-credentials.sh agent-test-agent-m2m\n```\n\n**Important**: Save the Client ID and Client Secret shown in the output. You'll need these to authenticate your AI agents.\n\n### Update .env File with Client Secrets\n\n**Critical Step**: After running `get-all-client-credentials.sh`, you MUST update your `.env` file with the retrieved client secrets:\n\n```bash\n# View the retrieved client secrets\ncat .oauth-tokens/keycloak-client-secrets.txt\n\n# You'll see output like:\n# KEYCLOAK_CLIENT_ID=mcp-gateway-web\n# KEYCLOAK_CLIENT_SECRET=JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv\n#\n# KEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m\n# KEYCLOAK_M2M_CLIENT_SECRET=iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo\n\n# Update your .env file with these exact secret values\nnano .env\n\n# Find and update these lines with the actual secret values from above:\n# KEYCLOAK_CLIENT_SECRET=JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv\n# KEYCLOAK_M2M_CLIENT_SECRET=iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo\n\n# Save and exit (Ctrl+X, then Y, then Enter)\n```\n\n**Note**: These secrets are auto-generated by Keycloak and are different each time you run `init-keycloak.sh`. Always use the latest values from `.oauth-tokens/keycloak-client-secrets.txt`.\n\n### Generate Access Tokens for All Keycloak Users and Agents\n\nGenerate access tokens for all configured agents and users:\n\n```bash\n# Generate access tokens for all agents\n./credentials-provider/keycloak/get_m2m_token.py --all-agents\n```\n\nThis will create access token files (both `.json` and `.env` formats) for all Keycloak service accounts in the `.oauth-tokens/` directory.\n\n**Note**: If you want tokens to last longer than the default 5 minutes, see [Configure Token Lifetime](#configure-token-lifetime) before generating tokens.\n\n### Verify Keycloak is Running\n\nOpen a web browser and navigate to:\n```\nhttp://localhost:8080\n```\n\nYou should see the Keycloak login page. You can log in with:\n- Username: `admin`\n- Password: The password you set in KEYCLOAK_ADMIN_PASSWORD\n\n---\n\n## 7. Starting All Services\n\n### Start Services with Pre-built Images\n\n**Important macOS Docker Volume Sharing**: On macOS, Docker Desktop only shares certain directories by default (like `/Users`, `/tmp`, `/private`). The `/opt` and `/var/log` directories we need are NOT shared by default, so we must create them with proper ownership for Docker containers to access them.\n\n**Note**: If you encounter permission issues, you may need to add `/opt` to Docker Desktop's shared directories:\n1. Open Docker Desktop\n2. Go to Settings > Resources > Virtual file shares\n3. Add `/opt` to the list of shared directories\n4. Click \"Apply & Restart\"\n\n```bash\n# Create necessary directories\n# Using ${HOME}/mcp-gateway to avoid needing sudo permissions\nmkdir -p ${HOME}/mcp-gateway/{servers,models,auth_server,secrets/fininfo,logs,ssl}\n\n# Make build script executable\nchmod +x build_and_run.sh\n\n# Start all services using pre-built images (faster, no build required)\n./build_and_run.sh --prebuilt\n\n# This will:\n# - Use pre-built container images from Docker registry\n# - Skip React frontend build (already included in images)\n# - Create necessary directories\n# - Start all services\n# - Much faster than building locally!\n```\n\n**Benefits of using `--prebuilt`:**\n- **Instant deployment**: No build time required\n- **No Node.js issues**: Pre-built frontend already included\n- **Consistent experience**: Same tested images for all users\n- **Bandwidth efficient**: Optimized, compressed images\n\n### Verify All Services are Running\n```bash\n# Check all services status\ndocker-compose ps\n\n# Expected services (all should show \"Up\"):\n# - keycloak-db\n# - keycloak\n# - auth-server\n# - registry\n# - nginx (or similar proxy)\n# - currenttime-server\n# - fininfo-server\n# - mcpgw-server\n# - realserverfaketools-server\n```\n\n### Monitor Service Logs\n```bash\n# View all logs\ndocker-compose logs -f\n\n# View specific service logs\ndocker-compose logs -f auth-server\ndocker-compose logs -f registry\n\n# Press Ctrl+C to exit log viewing\n```\n\n---\n\n## 8. Verification and Testing\n\n### Test Web Interface\n1. **Open your web browser** and navigate to:\n ```\n http://localhost\n ```\n\n2. **Login Page**: You should see the MCP Gateway Registry login page\n\n3. **Login with Keycloak**: Click \"Login with Keycloak\" and use:\n - Username: `admin`\n - Password: The password you set in KEYCLOAK_ADMIN_PASSWORD\n\n### Test API Access\n```bash\n# Test registry health\ncurl http://localhost/health\n# Expected: {\"status\":\"healthy\",\"timestamp\":\"...\"}\n\n# Test Keycloak realm\ncurl http://localhost:8080/realms/mcp-gateway | jq '.realm'\n# Expected: \"mcp-gateway\"\n```\n\n### Test Python MCP Client\n```bash\n# Activate virtual environment\nsource .venv/bin/activate\n\n# Load agent credentials\nsource .oauth-tokens/agent-test-agent-m2m.env\n\n# Test connectivity\nuv run cli/mcp_client.py ping\n\n# Expected output:\n# ✓ M2M authentication successful\n# Session established: [session-id]\n# {\"jsonrpc\": \"2.0\", \"id\": 2, \"result\": {}}\n\n# List available tools\nuv run cli/mcp_client.py list\n\n# Test a simple tool\nuv run cli/mcp_client.py --url http://localhost/currenttime/mcp call --tool current_time_by_timezone --args '{\"tz_name\":\"America/New_York\"}'\n```\n\n### Test Admin Console\n```bash\n# Access Keycloak admin console\nopen http://localhost:18080/admin/\n\n# Login with:\n# Username: admin\n# Password: The password you set in KEYCLOAK_ADMIN_PASSWORD\n\n# You should see the Keycloak admin interface\n# Navigate to: mcp-gateway realm > Clients\n# Verify: mcp-gateway-web and mcp-gateway-m2m clients exist\n```\n\n---\n\n## 10. Podman Deployment\n\nThis section provides complete instructions for deploying MCP Gateway & Registry using **Podman** instead of Docker on macOS. Podman offers rootless container execution without requiring privileged port access.\n\n### Why Podman?\n\n- ✅ **Rootless Execution**: No sudo or root access required\n- ✅ **No Privileged Ports**: Uses ports 8080/8443 instead of 80/443\n- ✅ **Enhanced Security**: Better container isolation\n- ✅ **No Daemon**: Unlike Docker, Podman doesn't require a background daemon\n- ✅ **Docker-Compatible**: Similar CLI commands and Compose support\n\n### Installation\n\n**Option 1: Podman Desktop (Recommended)**\n\n```bash\n# Install via Homebrew\nbrew install podman-desktop\n\n# Launch Podman Desktop from Applications\n# Or download from: https://podman-desktop.io/\n```\n\n**Option 2: Podman CLI Only**\n\n```bash\n# Install Podman\nbrew install podman\n\n# Install additional tools\nbrew install podman-compose\n```\n\n### Initialize Podman Machine\n\nPodman on macOS runs containers in a lightweight Linux VM:\n\n```bash\n# Initialize Podman machine with adequate resources\npodman machine init --cpus 4 --memory 8192 --disk-size 50\n\n# Start the machine\npodman machine start\n\n# Verify installation\npodman --version\npodman compose version\npodman machine list\n```\n\n**Expected output:**\n```\nNAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE\npodman-machine-default* qemu 2 hours ago Currently running 4 8GiB 50GiB\n```\n\n### Complete Setup with Podman\n\nFollow the same steps as the Docker guide (Sections 3-8), but use Podman commands:\n\n**1. Clone and Configure (same as Section 3-4)**\n\n```bash\n# Clone repository\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\n\n# Configure environment\ncp .env.example .env\nnano .env\n```\n\n**2. Start Keycloak with Podman**\n\n```bash\n# Set passwords (must match .env file)\nexport KEYCLOAK_ADMIN_PASSWORD='your-admin-password'\nexport KEYCLOAK_DB_PASSWORD='your-db-password'\n\n# Start Keycloak services\npodman compose up -d keycloak-db keycloak\n\n# Wait for services (takes ~60 seconds)\npodman compose ps\n\n# Follow logs\npodman compose logs -f keycloak\n```\n\n**3. Configure Keycloak (same as Section 5-6)**\n\n```bash\n# Disable SSL requirement\npodman exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials \\\n --server http://localhost:8080 --realm master \\\n --user admin --password \"${KEYCLOAK_ADMIN_PASSWORD}\"\n\npodman exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh \\\n update realms/master -s sslRequired=NONE\n\n# Run Keycloak setup scripts\ncd keycloak/setup\n./create-realm-and-clients.sh\n./get-all-client-credentials.sh\n\n# Create test agent\n./setup-agent-service-account.sh test-agent-1 registry-users-lob1\ncd ../..\n```\n\n**4. Deploy All Services with Podman**\n\n```bash\n# Deploy using pre-built images (recommended for Intel Macs)\n./build_and_run.sh --prebuilt --podman\n\n# For Apple Silicon, build locally instead\n./build_and_run.sh --podman\n```\n\n> **Apple Silicon Users:** Don't use `--prebuilt` with Podman on ARM64. The pre-built images are amd64 and will cause errors. Use `./build_and_run.sh --podman` to build natively. See [Podman on Apple Silicon Guide](podman-apple-silicon.md).\n\n**The script automatically:**\n- Detects Podman usage\n- Applies `docker-compose.podman.yml` overlay\n- Maps ports to non-privileged equivalents (8080/8443)\n- Configures volume mounts with proper SELinux labels\n\n### Access Services\n\n**Important**: With Podman, services use different host ports:\n\n| Service | URL (Podman) |\n|---------|-------------|\n| **Main UI** | `http://localhost:8080` |\n| **Main UI (HTTPS)** | `https://localhost:8443` |\n| Registry API | `http://localhost:7860` |\n| Keycloak Admin | `http://localhost:18080/admin` |\n| Auth Server | `http://localhost:8888` |\n| Prometheus | `http://localhost:9090` |\n| Grafana | `http://localhost:3000` |\n\n**Open in browser:**\n```bash\n# Main interface (note port 8080)\nopen http://localhost:8080\n\n# Registry API (unchanged)\nopen http://localhost:7860\n\n# Keycloak admin console\nopen http://localhost:18080/admin\n```\n\n### Podman-Specific Commands\n\n**Container Management:**\n\n```bash\n# List running containers\npodman compose ps\n# or: podman ps\n\n# View logs\npodman compose logs -f\npodman compose logs -f registry\npodman logs mcp-gateway-registry-registry-1\n\n# Stop services\npodman compose down\n\n# Restart service\npodman compose restart registry\n\n# Execute commands in container\npodman exec -it mcp-gateway-registry-registry-1 bash\n```\n\n**Resource Management:**\n\n```bash\n# View resource usage\npodman stats\n\n# Check Podman machine resources\npodman machine inspect podman-machine-default\n\n# Adjust machine resources (requires restart)\npodman machine stop\npodman machine rm\npodman machine init --cpus 8 --memory 16384 --disk-size 100\npodman machine start\n```\n\n**Volume Management:**\n\n```bash\n# List volumes\npodman volume ls\n\n# Inspect volume\npodman volume inspect mcp-gateway-registry_metrics-db-data\n\n# Remove unused volumes\npodman volume prune\n```\n\n### Testing with Podman\n\nUpdate test scripts to use Podman ports:\n\n```bash\n# Test registry health\ncurl http://localhost:7860/health\n\n# Test main interface (note port 8080)\ncurl http://localhost:8080/\n\n# Test with MCP client\ncd cli\npython mcp_client.py \\\n --url http://localhost/mcpgw/mcp \\\n --token-file ../.oauth-tokens/agent-test-agent-1-m2m.env \\\n --command ping\n```\n\n### Troubleshooting Podman\n\n**Issue: Podman machine won't start**\n\n```bash\n# Check status\npodman machine list\n\n# View machine logs\npodman machine ssh systemctl status\n\n# Reset machine\npodman machine stop\npodman machine rm\npodman machine init --cpus 4 --memory 8192\npodman machine start\n```\n\n**Issue: Port 8080 already in use**\n\n```bash\n# Check what's using the port\nlsof -i :8080\n\n# Option 1: Stop conflicting service\n# Option 2: Edit docker-compose.podman.yml to use different ports\nnano docker-compose.podman.yml\n# Change \"8080:80\" to \"8081:80\"\n```\n\n**Issue: Permission denied on volumes**\n\n```bash\n# Ensure directories exist\nmkdir -p ${HOME}/mcp-gateway/{servers,agents,models,logs}\n\n# Check permissions\nls -la ${HOME}/mcp-gateway/\n\n# Fix if needed\nchmod -R 755 ${HOME}/mcp-gateway/\n```\n\n**Issue: Containers fail to start**\n\n```bash\n# Check logs\npodman compose logs\n\n# Verify machine has enough resources\npodman machine inspect | grep -A5 \"Resources\"\n\n# Increase if needed (see Resource Management above)\n```\n\n**Issue: podman compose command not found**\n\n```bash\n# Install podman-compose\npip install podman-compose\n\n# Or install via Homebrew\nbrew install podman-compose\n\n# Verify\npodman compose version\n```\n\n### Switching Between Docker and Podman\n\nYou can switch between Docker and Podman without changing configurations:\n\n```bash\n# Stop Docker services\ndocker compose down\n\n# Start with Podman (Intel Mac)\n./build_and_run.sh --prebuilt --podman\n\n# Start with Podman (Apple Silicon - omit --prebuilt)\n# ./build_and_run.sh --podman\n\n# Or vice versa:\npodman compose down\n./build_and_run.sh --prebuilt\n```\n\n> **Apple Silicon Note:** When switching to Podman on Apple Silicon, use `./build_and_run.sh --podman` (without `--prebuilt`).\n\n**Note**: Database volumes and configurations are separate between Docker and Podman. You'll need to reconfigure Keycloak when switching.\n\n### Performance Considerations\n\n**Podman Machine on macOS:**\n- Runs in a QEMU VM (like Docker Desktop)\n- Performance similar to Docker Desktop\n- Recommended: 4+ CPUs, 8GB+ RAM\n- SSD recommended for disk operations\n\n**Tips for Better Performance:**\n1. Allocate sufficient resources to Podman machine\n2. Use `--prebuilt` flag to avoid local builds\n3. Keep Podman Desktop updated\n4. Use SSD for Podman machine storage\n\n---\n\n## 11. Troubleshooting\n\n### Common macOS Issues\n\n#### Docker/Podman Not Running\n\n**Docker:**\n```bash\n# Check if Docker is running\ndocker ps\n\n# If error, start Docker Desktop from Applications\n# Wait for whale icon to appear in menu bar\n```\n\n**Podman:**\n```bash\n# Check if Podman machine is running\npodman machine list\n\n# If not running, start it\npodman machine start\n\n# Verify\npodman ps\n```\n\n#### Port Conflicts\n```bash\n# Check what's using ports\nlsof -i :80\nlsof -i :8080\nlsof -i :7860\n\n# Kill conflicting processes if needed\nsudo lsof -ti :80 | xargs kill\n```\n\n#### Permission Issues\n```bash\n# Fix Docker permissions\nsudo chown -R $(whoami) ~/.docker\n\n# Fix file permissions\nchmod +x keycloak/setup/*.sh\nchmod +x build_and_run.sh\n\n# No additional ownership fixes needed - all directories are in user space\n```\n\n#### Keycloak \"HTTPS Required\" Error\n```bash\n# This was fixed in Section 4, but if it persists:\n\n# Re-run SSL disable commands (use your actual admin password)\ndocker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password \"${KEYCLOAK_ADMIN_PASSWORD}\"\n\ndocker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE\n\n# Also disable for the mcp-gateway realm after it's created\ndocker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/mcp-gateway -s sslRequired=NONE\n```\n\n#### Services Won't Start\n```bash\n# Check Docker memory/CPU limits in Docker Desktop preferences\n# Recommended: 4GB RAM, 2 CPUs minimum\n\n# Check disk space\ndf -h\n\n# Restart all services\ndocker-compose down\ndocker-compose up -d\n```\n\n#### Authentication Failures\n```bash\n# Check client secrets match\ncat .oauth-tokens/keycloak-client-secrets.txt\ncat .env | grep KEYCLOAK_CLIENT_SECRET\n\n# They should match! If not, update .env file\n\n# Restart auth-server after updating secrets\ndocker-compose restart auth-server\n```\n\n#### \"oauth2_callback_failed\" Error\n```bash\n# Check auth-server logs\ndocker-compose logs auth-server | tail -20\n\n# Usually caused by wrong client secret\n# Regenerate credentials:\n./keycloak/setup/get-all-client-credentials.sh\n\n# Update .env file with new secrets\nnano .env\n\n# Restart auth-server\ndocker-compose restart auth-server\n```\n\n### Reset Everything\nIf you need to start over completely:\n```bash\n# Stop and remove all containers and data\ndocker-compose down -v\n\n# Remove Docker images (optional)\ndocker system prune -a\n\n# Remove generated files\nrm -rf .oauth-tokens/\nrm .env\n\n# Start fresh from Section 3\ncp .env.example .env\n```\n\n### View Service Status\n```bash\n# Check all service status\ndocker-compose ps\n\n# Check specific service health\ndocker-compose logs [service-name] --tail 50\n\n# Check resource usage\ndocker stats\n```\n\n### macOS-Specific Logs\n```bash\n# Check Console.app for system logs\n# Check Docker Desktop logs via Docker Desktop > Troubleshoot > Get support\n\n# Check local network issues\nping localhost\ntelnet localhost 8080\n```\n\n---\n\n## Summary\n\nYou now have a fully functional MCP Gateway & Registry running on macOS! The system provides:\n\n- **Authentication**: Keycloak identity provider\n- **Registry**: Web-based interface for managing MCP servers\n- **API Gateway**: Centralized access to multiple MCP servers\n- **Agent Support**: Ready for AI coding assistants and agents\n- **Container Choice**: Works with both Docker and Podman\n\n### Key URLs:\n\n**With Docker:**\n- **Registry**: http://localhost\n- **Keycloak Admin**: http://localhost:8080/admin\n- **API Gateway**: http://localhost/mcpgw/mcp\n- **Individual Services**: http://localhost/[service-name]/mcp\n\n**With Podman:**\n- **Registry**: http://localhost:8080\n- **Keycloak Admin**: http://localhost:18080/admin\n- **API Gateway**: http://localhost:8080/mcpgw/mcp\n- **Individual Services**: http://localhost:8080/[service-name]/mcp\n\n### Key Files:\n- **Configuration**: `.env`\n- **Client Credentials**: `.oauth-tokens/keycloak-client-secrets.txt`\n- **Agent Tokens**: `.oauth-tokens/agent-*-m2m.env`\n- **Podman Overlay**: `docker-compose.podman.yml` (auto-applied with `--podman` flag)\n\n### Next Steps:\n1. **Configure your AI coding assistant** with the generated MCP configuration\n2. **Create additional agents** using the setup-agent-service-account.sh script\n3. **Add custom MCP servers** by editing docker-compose.yml\n4. **Explore the web interface** to manage servers and view metrics\n5. **Try Podman** if you want rootless container deployment (see Section 10)\n\n**Remember**: Save your credentials securely and keep Docker Desktop running when using the system!\n\n### Getting Help\n- **GitHub Issues**: https://github.com/agentic-community/mcp-gateway-registry/issues\n- **Documentation**: Check `/docs` folder for additional guides\n- **Logs**: Always check `docker-compose logs` for troubleshooting" }, { "path": "docs/mcp-registry-cli.md", "content": "# MCP Registry CLI Guide\n\nInteractive terminal interface for chatting with AI models and using MCP (Model Context Protocol) tools.\n\n![MCP Registry CLI Screenshot](img/mcp-registry-cli.png)\n\n## Table of Contents\n- [Quick Start](#quick-start)\n- [Setup](#setup)\n- [Available Commands](#available-commands)\n- [Provider Selection](#provider-selection)\n- [Available Models](#available-models)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## Quick Start\n\n### Build\n```bash\ncd cli && npm install && npm run build\n```\n\n### Configure AI provider (choose one):\n1. Bedrock via AWS profile (by default)\n2. Directly configured via execution role\n3. Set an anthropic API key\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-xxx \n```\n\n### Run (OAuth tokens auto-generated on first start)\n```bash\nnpm start\n```\nor\n```bash\nnpm link\nregistry\n```\n\n**Default model:** Claude Haiku 4.5 (fastest/cheapest)\n\n**Change model:**\n```bash\nexport BEDROCK_MODEL_ID=us.anthropic.claude-sonnet-4-5-20250929-v1:0 # Bedrock\nexport ANTHROPIC_MODEL=claude-opus-4-20250514 # Anthropic API\n```\n\n### Status Footer\n\nShows real-time status at the bottom:\n```\nToken: Valid for 5m 23s | Source: ingress-json | Last refresh: 14:32:15 | Model: us.anthropic.claude-haiku-4-5-20251001-v1:0 | Tokens: In: 1,234 | Out: 567 | Cost: $0.01\n```\n\n- **Token:** Time remaining (green > 60s, yellow < 60s, red when expired) - auto-refreshes at < 10s\n- **Source:** Token origin (`ingress-json`, `env`, `token-file`)\n- **Model:** Current AI model\n- **Tokens:** Input/output usage for session\n- **Cost:** Estimated session cost\n\n---\n\n## Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show help message |\n| `/exit` | Exit CLI (or Ctrl+C) |\n| `/ping` | Test gateway connectivity |\n| `/list` | List MCP tools |\n| `/servers` | List MCP servers |\n| `/refresh` | Manually refresh OAuth tokens |\n\n**Tip:** Type `/` for autocomplete suggestions\n---\n\n## Troubleshooting\n\n### OAuth Token Issues\n\n**Error:** \"Failed to load ingress tokens\" or authentication errors\n\n**Fix:**\n1. **Auto-generate:** Run `npm start` - tokens auto-generate on first run\n2. **Manual refresh:** Type `/refresh` in running CLI\n3. **Manual generation:** `./credentials-provider/generate_creds.sh --ingress-only`\n\n**Note:** Tokens stored in `.oauth-tokens/ingress.json` (project root). Auto-refresh at < 10s remaining.\n\n### Build Errors\n\n**Fix:**\n```bash\ncd cli && rm -rf dist/ node_modules/ && npm install && npm run build\n```\n\n### \"Agent mode is disabled\"\n\n**Cause:** No AI credentials found\n\n**Fix:**\n```bash\n# Bedrock - verify AWS credentials\naws sts get-caller-identity\n\n# Bedrock - Execution role (check IAM role attached)\ncurl http://169.254.169.254/latest/meta-data/iam/security-credentials/\n\n# Anthropic API\necho $ANTHROPIC_API_KEY # Should show key\nexport ANTHROPIC_API_KEY=sk-ant-your-key\n```\n### Anthropic API Errors\n\n**Rate limit (429):** Wait and retry, or use Bedrock\n**Auth failed (401):** Verify `ANTHROPIC_API_KEY` is valid (starts with `sk-ant-`)\n\n---" }, { "path": "docs/metrics-architecture.md", "content": "# MCP Gateway Metrics Architecture\n\nA comprehensive observability system for monitoring authentication, tool discovery, and execution across the MCP Gateway ecosystem.\n\n## Overview\n\nThe metrics system collects, processes, and visualizes telemetry data from all MCP Gateway components. It provides real-time insights into system performance, user behavior, and service health.\n\n### Key Capabilities\n\n- **Real-time Monitoring**: Sub-second metric collection and export\n- **Flexible Integration**: Native support for Prometheus, Grafana, and OpenTelemetry Collector\n- **Historical Analysis**: SQLite storage with configurable retention policies\n- **Secure & Scalable**: API key authentication with rate limiting\n- **Multiple Export Paths**: Direct Prometheus scraping or OTLP export to any observability platform\n\n## High-Level Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ Your MCP Services │\n│ │\n│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────┐ │\n│ │ Auth Server │ │ Registry │ │ MCP Servers │ │\n│ │ (middleware) │ │ (middleware) │ │ (client lib) │ │\n│ └───────┬───────┘ └───────┬───────┘ └────────┬─────────┘ │\n│ │ │ │ │\n│ └───────────────────┴────────────────────┘ │\n└──────────────────────────────┬──────────────────────────────────┘\n │\n HTTP POST /metrics\n X-API-Key: \n │\n ┌─────────────────────▼────────────────────┐\n │ Metrics Collection Service │\n │ (FastAPI + SQLite + OpenTelemetry) │\n │ │\n │ • API Key Authentication │\n │ • Rate Limiting (1000 req/min) │\n │ • Request Validation │\n │ • Buffered Processing (5s flush) │\n └────────────┬───────────────┬─────────────┘\n │ │\n ┌────────────▼──┐ ┌────▼─────────────────────────┐\n │ SQLite DB │ │ OpenTelemetry Exporters │\n │ │ │ │\n │ • Raw metrics│ │ ┌────────────────────────┐ │\n │ • Specialized│ │ │ Prometheus Exporter │ │\n │ tables │ │ │ Port: 9465 │ │\n │ • Historical │ │ │ /metrics │ │\n │ analysis │ │ └──────────┬─────────────┘ │\n │ • 90 day │ │ │ │\n │ retention │ │ ┌──────────▼─────────────┐ │\n └───────────────┘ │ │ OTLP Exporter │ │\n │ │ (Optional) │ │\n │ │ http://collector:4318 │ │\n │ └──────────┬─────────────┘ │\n └─────────────┼───────────────┘\n │\n ┌────────────────────────┴────────────────────────┐\n │ │\n ┌───────────▼──────────┐ ┌────────────▼─────────────┐\n │ Grafana │ │ OTEL Collector │\n │ Port: 3000 │ │ (Optional) │\n │ │ │ │\n │ • Prometheus queries│ │ Forwards to: │\n │ • Pre-built │ │ • Datadog │\n │ dashboards │ │ • New Relic │\n │ • Real-time alerts │ │ • Honeycomb │\n └──────────────────────┘ │ • Jaeger │\n │ • Any OTLP-compatible │\n └──────────────────────────┘\n```\n\n## How It Works\n\n### 1. Services Emit Metrics\n\nYour services automatically collect metrics using middleware or client libraries:\n\n**Example: Auth Server tracks authentication events**\n```\nWhen: User authenticates to access a tool\nCollected: Success/failure, duration, method (JWT/OAuth), user hash, server name\nSent to: http://metrics-service:8890/metrics\n```\n\n**Example: Registry tracks tool discovery**\n```\nWhen: Semantic search for tools\nCollected: Query text, results count, embedding time, search time\nSent to: http://metrics-service:8890/metrics\n```\n\n### 2. Metrics Service Processes Data\n\nThe centralized service receives, validates, and stores metrics:\n\n- **Authentication**: SHA256-hashed API keys per service\n- **Rate Limiting**: Token bucket algorithm (1000 req/min default)\n- **Validation**: Schema validation with detailed error reporting\n- **Buffering**: In-memory buffer with 5-second flush interval\n- **Storage**: Dual-path to SQLite and OpenTelemetry\n\n### 3. Data Export Options\n\n**Option A: Direct Prometheus Scraping (Default)**\n```\nPrometheus scrapes → metrics-service:9465/metrics\nGrafana queries → Prometheus\n```\n\n**Option B: OpenTelemetry Collector Pipeline**\n```\nMetrics Service → OTLP export → OTEL Collector → Your observability platform\n (Datadog, New Relic, etc.)\n```\n\n**Option C: Hybrid Approach**\n```\nMetrics Service → Both Prometheus + OTLP simultaneously\n (Real-time Grafana + Long-term storage in vendor platform)\n```\n\n## Metric Types\n\n### Authentication Metrics\nTracks all authentication requests across services:\n\n- **Dimensions**: success, method (jwt/oauth/noauth), server, user_hash\n- **Measurements**: request count, duration\n- **Use Cases**: Success rates, auth performance, user activity patterns\n\n### Tool Execution Metrics\nTracks MCP protocol method calls:\n\n- **Dimensions**: method (initialize/tools/list/tools/call), tool_name, client_name, success\n- **Measurements**: request count, duration, input/output sizes\n- **Use Cases**: Tool popularity, client usage, performance analysis\n\n### Discovery Metrics\nTracks semantic search operations:\n\n- **Dimensions**: query text, results count, top_k/top_n parameters\n- **Measurements**: embedding time, FAISS search time, total duration\n- **Use Cases**: Search performance optimization, query pattern analysis\n\n### Protocol Latency Metrics\nMeasures time between protocol steps:\n\n- **Flow Steps**:\n - initialize → tools/list (discovery latency)\n - tools/list → tools/call (selection latency)\n - initialize → tools/call (full flow latency)\n- **Use Cases**: User experience optimization, bottleneck identification\n\n## Database Schema\n\n### Specialized Tables\n\n**metrics** - Universal metrics table with JSON dimensions/metadata\n\n**auth_metrics** - Fast queries for authentication analysis\n- Indexed on: timestamp, success, user_hash\n\n**tool_metrics** - Tool usage patterns and performance\n- Indexed on: timestamp, tool_name, client_name, method\n\n**discovery_metrics** - Search performance and patterns\n- Indexed on: timestamp, results_count\n\n**api_keys** - Service authentication\n- SHA256 hashed keys with per-service rate limits\n\nAll tables include automatic retention cleanup (90 days default).\n\n## OpenTelemetry Integration\n\n### Instruments\n\nThe service creates standard OTEL instruments:\n\n**Counters** (cumulative totals):\n- `mcp_auth_requests_total` - Authentication events\n- `mcp_tool_executions_total` - Tool calls\n- `mcp_tool_discovery_total` - Discovery requests\n- `mcp_health_checks_total` - Health check operations\n\n**Histograms** (duration distributions):\n- `mcp_auth_request_duration_seconds` - Auth latency\n- `mcp_tool_execution_duration_seconds` - Tool latency\n- `mcp_tool_discovery_duration_seconds` - Discovery query latency\n- `mcp_protocol_latency_seconds` - Protocol flow timing\n- `mcp_health_check_duration_seconds` - Health check latency\n\n### Export Configuration\n\n**Environment Variables:**\n```bash\n# Prometheus export (enabled by default)\nOTEL_PROMETHEUS_ENABLED=true\nOTEL_PROMETHEUS_PORT=9465\n\n# OTLP export (optional, for external platforms)\nOTEL_OTLP_ENDPOINT=http://otel-collector:4318\n```\n\n### Using OTEL Collector\n\nTo send metrics to Datadog, New Relic, or other platforms:\n\n1. **Deploy OTEL Collector** with appropriate exporters:\n```yaml\nreceivers:\n otlp:\n protocols:\n http:\n endpoint: 0.0.0.0:4318\n\nexporters:\n datadog:\n api:\n key: ${DD_API_KEY}\n \n otlp/newrelic:\n endpoint: otlp.nr-data.net:4317\n headers:\n api-key: ${NEW_RELIC_LICENSE_KEY}\n\nservice:\n pipelines:\n metrics:\n receivers: [otlp]\n exporters: [datadog, otlp/newrelic]\n```\n\n2. **Configure metrics service** to export to collector:\n```bash\nOTEL_OTLP_ENDPOINT=http://otel-collector:4318\n```\n\n3. **Metrics flow automatically** from service → collector → your platform\n\n### Direct OTLP Push Export (Simplified Setup)\n\nFor simpler deployments, the metrics service can push OTLP metrics directly to any observability platform that supports OTLP HTTP ingestion **without requiring an intermediate OTEL Collector**. This is the easiest way to integrate with commercial observability platforms.\n\n**Supported Platforms:**\n- Datadog (US1, US3, US5, EU1, AP1, GOV)\n- New Relic\n- Honeycomb\n- Grafana Cloud\n- Any OTLP-compatible endpoint\n\n**Configuration:**\n\nSet these environment variables to enable direct OTLP push:\n\n```bash\n# Required: OTLP endpoint URL\nOTEL_OTLP_ENDPOINT=https://otlp.datadoghq.com\n\n# Required: Authentication headers (API keys, tokens)\nOTEL_EXPORTER_OTLP_HEADERS=dd-api-key=YOUR_DATADOG_API_KEY\n\n# Optional: Export interval (default: 30000ms = 30 seconds)\nOTEL_OTLP_EXPORT_INTERVAL_MS=30000\n\n# Optional: Metric temporality (Datadog requires 'delta', most others use 'cumulative')\nOTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta\n```\n\n**Platform-Specific Examples:**\n\n| Platform | Endpoint | Headers | Temporality |\n|----------|----------|---------|-------------|\n| Datadog US1 | `https://otlp.datadoghq.com` | `dd-api-key=YOUR_KEY` | `delta` |\n| Datadog EU1 | `https://otlp.datadoghq.eu` | `dd-api-key=YOUR_KEY` | `delta` |\n| New Relic | `https://otlp.nr-data.net` | `api-key=YOUR_LICENSE_KEY` | `cumulative` |\n| Honeycomb | `https://api.honeycomb.io` | `x-honeycomb-team=YOUR_API_KEY` | `cumulative` |\n| Grafana Cloud | `https://otlp-gateway-{region}.grafana.net/otlp` | `Authorization=Basic {base64}` | `cumulative` |\n\n**Docker Compose Setup:**\n\nAdd to your `.env` file:\n\n```bash\n# Datadog example\nOTEL_OTLP_ENDPOINT=https://otlp.datadoghq.com\nOTEL_EXPORTER_OTLP_HEADERS=dd-api-key=YOUR_DATADOG_API_KEY\nOTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta\nOTEL_OTLP_EXPORT_INTERVAL_MS=30000\n```\n\nThen start the metrics service:\n\n```bash\ndocker-compose up -d metrics-service\n```\n\nThe metrics service will automatically start pushing metrics to your configured endpoint every 30 seconds (or your configured interval).\n\n**Terraform/ECS Deployment:**\n\nFor AWS ECS deployments, add these variables to your `terraform.tfvars`:\n\n```hcl\n# Datadog example\notel_otlp_endpoint = \"https://otlp.datadoghq.com\"\notel_exporter_otlp_headers = \"dd-api-key=YOUR_DATADOG_API_KEY\" # Stored in AWS Secrets Manager\notel_exporter_otlp_metrics_temporality_preference = \"delta\"\notel_otlp_export_interval_ms = \"30000\"\n```\n\nFor security, `OTEL_EXPORTER_OTLP_HEADERS` is stored in AWS Secrets Manager and not exposed in the ECS task definition plaintext.\n\n**Verification:**\n\n1. Check metrics service logs for OTLP export confirmation:\n```\nINFO: OTLP metrics exporter enabled for https://otlp.datadoghq.com (interval: 30000ms)\n```\n\n2. Within 2 minutes, you should see all 9 MCP Gateway metrics appearing in your observability platform:\n - 4 counters: `mcp_auth_requests_total`, `mcp_tool_executions_total`, `mcp_tool_discovery_total`, `mcp_health_checks_total`\n - 5 histograms: `mcp_auth_request_duration_seconds`, `mcp_tool_execution_duration_seconds`, `mcp_tool_discovery_duration_seconds`, `mcp_protocol_latency_seconds`, `mcp_health_check_duration_seconds`\n\n3. All metric dimensions (service, method, tool_name, success, etc.) will appear as tags/labels in your platform\n\n**Benefits of Direct Push:**\n\n- ✅ **No OTEL Collector required** - Simpler architecture, fewer moving parts\n- ✅ **Lower latency** - Metrics go directly from service to platform\n- ✅ **Easier debugging** - Fewer components in the pipeline\n- ✅ **Lower operational overhead** - No collector to manage, scale, or monitor\n- ✅ **Secure by default** - API keys stored in Secrets Manager on ECS\n- ✅ **Works alongside Prometheus** - Both exporters run simultaneously if needed\n\n**When to Use Direct Push vs OTEL Collector:**\n\n| Use Direct Push When | Use OTEL Collector When |\n|-----------------------|--------------------------|\n| Single observability platform | Multiple downstream platforms |\n| Standard OTLP endpoint | Custom metric transformations needed |\n| Simplicity is priority | Advanced filtering/sampling required |\n| Platform-native OTLP support | Legacy/proprietary protocols |\n\n**Note:** Direct OTLP push and Prometheus export can run simultaneously. This allows you to use Grafana for real-time monitoring while also sending metrics to a commercial platform for long-term storage and advanced analytics.\n\n## Grafana Dashboards\n\nPre-built dashboard: **MCP Analytics Comprehensive**\n\n### Key Panels\n\n**Real-time Protocol Activity**\n- Shows rate of initialize, tools/list, tools/call operations\n- Visualizes the MCP protocol flow in real-time\n\n**Authentication Flow Analysis**\n- Success vs failure rates over time\n- Auth method distribution (JWT, OAuth, NoAuth)\n\n**Authentication Success Rate**\n- Single stat with color thresholds (red < 85%, orange 85-95%, green > 95%)\n\n**Tool Execution Latency**\n- P50, P95, P99 percentiles for performance analysis\n\n**Top Tools by Usage**\n- Most frequently called tools across all servers\n\n**Protocol Flow Latency**\n- Time between protocol steps (initialize → list → call)\n- Helps identify user experience bottlenecks\n\n**Dashboard Features:**\n- Auto-refresh: 30 seconds\n- Time range: Last 1 hour (configurable)\n- Variables: Filter by service, server, method\n\n## Getting Started\n\n### Quick Setup\n\n1. **Start the metrics service:**\n```bash\ndocker-compose up -d metrics-service metrics-db grafana\n```\n\n2. **Generate API keys for your services:**\n```bash\ndocker-compose exec metrics-service python create_api_key.py\n```\n\n3. **Configure your services with API keys:**\n```bash\nexport METRICS_SERVICE_URL=http://metrics-service:8890\nexport METRICS_API_KEY=\n```\n\n4. **Access Grafana:**\n```\nhttp://localhost:3000\nDefault credentials: admin/admin\n```\n\n### Integrating Your Service\n\n**Option 1: Use provided middleware (FastAPI/Python)**\n```python\nfrom auth_server.metrics_middleware import add_auth_metrics_middleware\n\napp = FastAPI()\nadd_auth_metrics_middleware(app, service_name=\"my-service\")\n```\n\n**Option 2: Send metrics directly via HTTP:**\n```python\nimport httpx\n\nawait httpx.post(\n \"http://metrics-service:8890/metrics\",\n json={\n \"service\": \"my-service\",\n \"version\": \"1.0.0\",\n \"metrics\": [{\n \"type\": \"auth_request\",\n \"value\": 1.0,\n \"duration_ms\": 45.2,\n \"dimensions\": {\"success\": True, \"method\": \"jwt\"}\n }]\n },\n headers={\"X-API-Key\": api_key}\n)\n```\n\n## Configuration\n\n### Metrics Service\n\n```bash\nSQLITE_DB_PATH=/var/lib/sqlite/metrics.db\nMETRICS_SERVICE_PORT=8890\nMETRICS_RATE_LIMIT=1000 # Requests per minute per API key\nMETRICS_RETENTION_DAYS=90 # Auto-cleanup after 90 days\n```\n\n### OpenTelemetry\n\n```bash\nOTEL_SERVICE_NAME=mcp-metrics-service\nOTEL_PROMETHEUS_ENABLED=true\nOTEL_PROMETHEUS_PORT=9465\nOTEL_OTLP_ENDPOINT= # Optional: http://otel-collector:4318\n```\n\n### Per-Service API Keys\n\n```bash\nMETRICS_API_KEY_AUTH=\nMETRICS_API_KEY_REGISTRY=\nMETRICS_API_KEY_MYSERVICE=\n```\n\nThe service automatically discovers `METRICS_API_KEY_*` environment variables and creates corresponding API keys.\n\n## Use Cases\n\n### Performance Monitoring\n- Track P95/P99 latency for authentication and tool execution\n- Identify slow tools or services\n- Monitor protocol flow timing to optimize user experience\n\n### Usage Analytics\n- Most popular tools across your MCP ecosystem\n- Client application distribution (Claude Desktop, custom clients)\n- User activity patterns (hashed for privacy)\n\n### Operational Alerts\n- Authentication failure spikes\n- Service availability issues\n- Rate limit exhaustion\n- Database growth anomalies\n\n### Capacity Planning\n- Request rate trends over time\n- Resource utilization patterns\n- Growth projection from historical data\n\n## Best Practices\n\n### Security\n- Never log API keys in plaintext\n- Use separate API keys per service for isolation\n- Rotate keys periodically\n- Monitor for unusual rate limit patterns\n\n### Performance\n- Services emit metrics asynchronously (fire-and-forget)\n- Metrics collection adds < 5ms overhead per request\n- Buffer size and flush interval tunable for high-volume deployments\n\n### Data Retention\n- Default 90 days for raw metrics\n- Configure longer retention for aggregated metrics\n- Use OTLP export for long-term storage in external platforms\n\n### Observability\n- Start with Prometheus + Grafana for simplicity\n- Add OTEL Collector when integrating with existing observability stack\n- Use hybrid approach for best of both worlds\n\n## Troubleshooting\n\n**Metrics not appearing in Grafana?**\n- Check Prometheus is scraping metrics-service:9465\n- Verify API key in service configuration\n- Check metrics service logs for validation errors\n\n**Rate limit errors?**\n- Increase `METRICS_RATE_LIMIT` environment variable\n- Check rate limit status: `GET /rate-limit` endpoint\n\n**High database growth?**\n- Verify retention policies are active: `GET /admin/retention/policies`\n- Manually trigger cleanup: `POST /admin/retention/cleanup`\n- Adjust retention days for high-volume tables\n\n## Additional Resources\n\n- **API Reference**: `metrics-service/docs/api-reference.md`\n- **Data Retention**: `metrics-service/docs/data-retention.md`\n- **Database Schema**: `metrics-service/docs/database-schema.md`\n- **Deployment Guide**: `metrics-service/docs/deployment.md`" }, { "path": "docs/mongodb-m2m-collections.md", "content": "# MongoDB Collections for M2M Accounts\n\n## Overview\n\nM2M accounts are stored in **THREE** MongoDB collections with different purposes:\n\n```\n┌─────────────────────────────────────────────────────┐\n│ M2M Account Storage Architecture │\n└─────────────────────────────────────────────────────┘\n\n1. idp_m2m_clients ← PRIMARY (used by auth-server)\n ├─ All providers: Keycloak, Okta, Entra, Auth0\n ├─ Purpose: Groups enrichment during authentication\n └─ Used by: auth_server/mongodb_groups_enrichment.py\n\n2. okta_m2m_clients ← Okta-specific metadata\n ├─ Only Okta M2M clients\n ├─ Purpose: Okta sync tracking\n └─ Used by: registry/services/okta_m2m_sync.py\n\n3. auth0_m2m_clients ← Auth0-specific metadata\n ├─ Only Auth0 M2M clients\n ├─ Purpose: Auth0 sync tracking\n └─ Used by: registry/services/auth0_m2m_sync.py\n```\n\n---\n\n## Collection Details\n\n### 1. `idp_m2m_clients` (PRIMARY - Generic)\n\n**Purpose:** Provider-agnostic collection for ALL M2M clients\n**Used by:** Auth-server for groups enrichment\n**Scope:** All IdP providers (Keycloak, Okta, Entra, Auth0)\n\n**Schema:**\n```javascript\n{\n \"_id\": ObjectId(\"...\"),\n \"client_id\": \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\",\n \"name\": \"MCP Gateway M2M\",\n \"description\": \"M2M client for registry access\",\n \"groups\": [\"registry-admins\", \"developers\"],\n \"enabled\": true,\n \"provider\": \"auth0\", // or \"okta\", \"keycloak\", \"entra\"\n \"idp_app_id\": \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\",\n \"created_at\": ISODate(\"2026-03-29T00:00:00Z\"),\n \"updated_at\": ISODate(\"2026-03-29T00:00:00Z\")\n}\n```\n\n**How it's used:**\n1. M2M token arrives with empty `groups: []`\n2. Auth-server validates JWT\n3. Queries: `db.idp_m2m_clients.find_one({client_id: \"...\"})`\n4. Returns groups: `[\"registry-admins\"]`\n5. Token is enriched with groups for authorization\n\n**Created by:**\n- Manual: `POST /api/iam/users/m2m` (management API)\n- Auto-sync: `POST /api/iam/okta/m2m/sync` (Okta)\n- Auto-sync: `POST /api/iam/auth0/m2m/sync` (Auth0)\n\n**Updated by:**\n- `PATCH /api/iam/users/{username}/groups`\n- `PATCH /api/iam/okta/m2m/clients/{id}/groups`\n- `PATCH /api/iam/auth0/m2m/clients/{id}/groups`\n\n---\n\n### 2. `okta_m2m_clients` (Okta-specific)\n\n**Purpose:** Okta-specific M2M client metadata\n**Used by:** Okta sync service\n**Scope:** Only Okta M2M clients\n\n**Schema:**\n```javascript\n{\n \"_id\": ObjectId(\"...\"),\n \"client_id\": \"0oa1100req1AzfKaY698\",\n \"name\": \"ai-agent\",\n \"description\": \"AI agent with admin access\",\n \"groups\": [\"registry-admins\"],\n \"enabled\": true,\n \"okta_app_id\": \"0oa1100req1AzfKaY698\",\n \"last_synced\": ISODate(\"2026-03-29T00:00:00Z\"),\n \"created_at\": ISODate(\"2026-03-29T00:00:00Z\"),\n \"updated_at\": ISODate(\"2026-03-29T00:00:00Z\")\n}\n```\n\n**How it's used:**\n- Sync service fetches Okta apps with `grant_type: client_credentials`\n- Stores in `okta_m2m_clients` for tracking\n- **ALSO** writes to `idp_m2m_clients` for auth enrichment\n\n**Operations:**\n- `GET /api/iam/okta/m2m/clients` - Lists from this collection\n- `POST /api/iam/okta/m2m/sync` - Syncs to this collection\n\n---\n\n### 3. `auth0_m2m_clients` (Auth0-specific)\n\n**Purpose:** Auth0-specific M2M client metadata\n**Used by:** Auth0 sync service\n**Scope:** Only Auth0 M2M clients\n\n**Schema:**\n```javascript\n{\n \"_id\": ObjectId(\"...\"),\n \"client_id\": \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\",\n \"name\": \"MCP Gateway M2M\",\n \"description\": \"M2M client for registry access\",\n \"groups\": [\"registry-admins\"],\n \"enabled\": true,\n \"auth0_client_id\": \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\",\n \"app_type\": \"non_interactive\",\n \"last_synced\": ISODate(\"2026-03-29T00:00:00Z\"),\n \"created_at\": ISODate(\"2026-03-29T00:00:00Z\"),\n \"updated_at\": ISODate(\"2026-03-29T00:00:00Z\")\n}\n```\n\n**How it's used:**\n- Sync service fetches Auth0 apps with `app_type: non_interactive`\n- Stores in `auth0_m2m_clients` for tracking\n- **ALSO** writes to `idp_m2m_clients` for auth enrichment\n\n**Operations:**\n- `GET /api/iam/auth0/m2m/clients` - Lists from this collection\n- `POST /api/iam/auth0/m2m/sync` - Syncs to this collection\n\n---\n\n## Data Flow\n\n### Creating an M2M Account\n\n#### Option 1: Manual Creation (All Providers)\n```\nPOST /api/iam/users/m2m\n ↓\nCreates in IdP (Keycloak/Okta/Entra/Auth0)\n ↓\nWrites to: idp_m2m_clients ✓\n```\n\n#### Option 2: Okta Auto-Sync\n```\nPOST /api/iam/okta/m2m/sync\n ↓\nFetches from Okta API\n ↓\nWrites to: okta_m2m_clients ✓\n ↓\nWrites to: idp_m2m_clients ✓\n```\n\n#### Option 3: Auth0 Auto-Sync\n```\nPOST /api/iam/auth0/m2m/sync\n ↓\nFetches from Auth0 API\n ↓\nWrites to: auth0_m2m_clients ✓\n ↓\nWrites to: idp_m2m_clients ✓\n```\n\n---\n\n## Authentication Flow\n\n```\n1. M2M Token arrives (groups: [])\n ├─ provider: okta/auth0/keycloak/entra\n ├─ client_id: \"abc123...\"\n └─ groups: [] (empty)\n\n2. Auth-server validates JWT\n └─ auth_server/providers/{provider}.py\n\n3. Groups enrichment triggered\n └─ mongodb_groups_enrichment.py\n └─ Queries: db.idp_m2m_clients.find_one({client_id})\n\n4. Groups found\n └─ Returns: [\"registry-admins\"]\n\n5. Authorization succeeds\n └─ Token enriched with groups\n```\n\n---\n\n## Query Examples\n\n### List ALL M2M accounts (all providers)\n```javascript\ndb.idp_m2m_clients.find().pretty()\n```\n\n### List by provider\n```javascript\n// Auth0 M2M clients\ndb.idp_m2m_clients.find({ provider: \"auth0\" }).pretty()\n\n// Okta M2M clients\ndb.idp_m2m_clients.find({ provider: \"okta\" }).pretty()\n```\n\n### Find specific M2M client\n```javascript\ndb.idp_m2m_clients.findOne({ client_id: \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\" })\n```\n\n### Check groups for client\n```javascript\ndb.idp_m2m_clients.findOne(\n { client_id: \"abc123...\" },\n { groups: 1, name: 1, provider: 1 }\n)\n```\n\n### Update groups manually\n```javascript\ndb.idp_m2m_clients.updateOne(\n { client_id: \"abc123...\" },\n {\n $set: {\n groups: [\"registry-admins\", \"developers\"],\n updated_at: new Date()\n }\n }\n)\n```\n\n---\n\n## Key Points\n\n### ✅ Every M2M account MUST be in `idp_m2m_clients`\nThis is the **ONLY** collection that auth-server queries for groups enrichment.\n\n### ✅ Provider-specific collections are optional\n`okta_m2m_clients` and `auth0_m2m_clients` are for tracking sync metadata.\n\n### ✅ Dual-write pattern\nWhen syncing, both collections are updated:\n- Provider-specific collection (okta/auth0)\n- Generic `idp_m2m_clients` collection\n\n### ✅ Groups enrichment is automatic\nAuth-server automatically queries `idp_m2m_clients` when token has empty groups.\n\n---\n\n## Summary Table\n\n| Collection | Providers | Used By | Purpose |\n|------------|-----------|---------|---------|\n| `idp_m2m_clients` | All (Keycloak, Okta, Entra, Auth0) | Auth-server | Groups enrichment |\n| `okta_m2m_clients` | Okta only | Okta sync service | Sync tracking |\n| `auth0_m2m_clients` | Auth0 only | Auth0 sync service | Sync tracking |\n\n**Bottom line:** All M2M accounts are listed in `idp_m2m_clients` regardless of provider.\n" }, { "path": "docs/okta-setup.md", "content": "# Okta Identity Provider Setup Guide\n\nThis guide walks through configuring Okta as the identity provider for the MCP Gateway Registry.\n\n> **⚠️ IMPORTANT DISCLAIMER**\n>\n> This documentation is a **reference guide based on our testing and development experience**, not an official Okta configuration manual. Okta's interface, features, and best practices evolve over time.\n>\n> **Always consult the [official Okta documentation](https://developer.okta.com/docs/) for:**\n> - Current UI layouts and navigation paths\n> - Latest security recommendations\n> - Production-grade configuration guidance\n> - Detailed API references\n>\n> **Purpose of this guide:**\n> - Document the specific configuration steps we used during development\n> - Provide a working reference for MCP Gateway Registry integration\n> - Share lessons learned and troubleshooting tips\n>\n> If you encounter differences between this guide and your Okta console, refer to Okta's official documentation as the authoritative source.\n\n## Prerequisites\n\n- An Okta developer account ([sign up free](https://developer.okta.com/signup/))\n- Your Okta domain (e.g., `dev-123456.okta.com`)\n- Understanding of OAuth2/OIDC flows (see [Okta OAuth2 documentation](https://developer.okta.com/docs/concepts/oauth-openid/))\n\n## Step 1: Create an OAuth2 Web Application\n\n1. In the Okta Admin Console, go to **Applications** → **Applications** → **Create App Integration**\n2. Select **OIDC - OpenID Connect** and **Web Application**, then click **Next**\n3. Configure the application:\n - **Name**: `MCP Gateway Registry`\n - **Grant types**: Authorization Code, Refresh Token, Client Credentials\n - **Sign-in redirect URIs**: `http://localhost:8888/oauth2/callback/okta` (dev) or `https://your-auth-server-domain/oauth2/callback/okta` (production)\n - **Sign-out redirect URIs**: `http://localhost:7860/logout` (dev) or `https://your-registry-domain/logout` (production)\n - **Controlled access**: Allow everyone in your organization\n4. Click **Save** and copy the **Client ID** and **Client Secret** immediately\n\n## Step 2: Configure Groups Claim in ID Tokens\n\nThe groups claim is configured on the application's Sign On tab using the legacy configuration. This uses the Okta Org Authorization Server (`/oauth2/v1/*`), which has a built-in `groups` scope.\n\n1. Go to **Applications** → your app → **Sign On** tab\n2. Scroll to the **Token claims (OIDC)** section and expand **Show legacy configuration**\n3. Under **Group Claims**, click **Edit**\n4. Set **Groups claim type** to **Filter**\n5. Set the name to `groups`, select **Matches regex**, and enter `.*`\n6. Click **Save**\n\n> **Note:** The Org Authorization Server and the \"default\" custom authorization server are different. This integration uses the Org Authorization Server, which natively supports the `groups` scope. Custom claims configured under Security → API → Authorization Servers → default will not apply to the Org Authorization Server.\n\n## Step 2a: Custom Authorization Server (Optional - for M2M Tokens)\n\n**When to use:** If you need M2M (machine-to-machine) service accounts with custom authorization rules, you may want to create a Custom Authorization Server instead of using the Org Authorization Server.\n\n**Key differences:**\n\n| Feature | Org Authorization Server | Custom Authorization Server |\n|---------|-------------------------|----------------------------|\n| Endpoint pattern | `/oauth2/v1/*` | `/oauth2/{authServerId}/v1/*` |\n| Built-in groups scope | ✅ Yes | ❌ No (must configure manually) |\n| Custom claims | ❌ Limited | ✅ Full control |\n| Custom access policies | ❌ No | ✅ Yes |\n| Best for | Interactive user login | M2M tokens with custom claims |\n\n**Setup steps:**\n\n1. Go to **Security** → **API** → **Authorization Servers** → **Add Authorization Server**\n2. Configure:\n - **Name**: `AI Registry` (or any descriptive name)\n - **Audience**: `api://ai-registry` (this becomes the `aud` claim in tokens)\n - **Description**: `Authorization server for MCP Gateway M2M tokens`\n3. Click **Save** and copy the **Issuer URI** (e.g., `https://dev-123456.okta.com/oauth2/aus1234567890abcdef`)\n4. Extract the authorization server ID from the URI: `aus1234567890abcdef`\n5. Configure the `groups` claim:\n - Go to **Claims** tab → **Add Claim**\n - **Name**: `groups`\n - **Include in token type**: Access Token, ID Token\n - **Value type**: Groups\n - **Filter**: Matches regex `.*`\n - **Include in**: Any scope\n6. Configure scopes (if needed):\n - Go to **Scopes** tab\n - The default scopes include `openid`, `profile`, `email`\n7. Set `OKTA_AUTH_SERVER_ID=aus1234567890abcdef` in your environment\n\n> **Important:** When using a custom authorization server, M2M tokens will have the audience set to your API identifier (e.g., `api://ai-registry`), not the client ID. The auth server automatically handles this validation.\n\n**Groups enrichment for M2M tokens:**\n\nWhen M2M tokens are issued with empty groups (common with custom authorization servers), the registry enriches them from DocumentDB/MongoDB:\n\n1. M2M token is validated successfully but has no groups claim (or empty array)\n2. Registry queries `idp_m2m_clients` collection for the client ID\n3. Groups from the database are injected into the authorization context\n4. Standard group-to-scope mapping applies\n\nThis allows scalable M2M authorization without hardcoding client IDs in authorization server expressions.\n\n## Step 3: Create Groups for Access Control\n\nOkta group names must match the group names in your registry's `scopes.yml`. The default configuration expects groups like `registry-admins` and `public-mcp-users`.\n\n1. Go to **Directory** → **Groups** → **Add Group**\n2. Create groups that match your `scopes.yml` group mappings:\n - `registry-admins` — full admin access to the registry\n - `public-mcp-users` — read-only access to public MCP servers\n3. Assign users to groups via each group's **Assign people** tab\n\n### Group-to-Scope Mapping\n\nThe registry uses `scopes.yml` to map Okta groups to authorization scopes. Example mapping:\n\n```yaml\n# scopes.yml\ngroups:\n registry-admins:\n - registry:admin:full\n - mcp:servers:read\n - mcp:servers:write\n - mcp:servers:delete\n\n public-mcp-users:\n - mcp:servers:read\n - mcp:servers:list\n```\n\n**How it works:**\n\n1. User logs in with Okta → ID token contains `groups` claim: `[\"registry-admins\"]`\n2. Registry extracts groups from token → queries DocumentDB for group-to-scope mappings\n3. Scopes are assigned based on group membership\n4. User can access resources matching their scopes\n\n**For M2M tokens:**\n\n1. M2M client authenticates with Client Credentials flow\n2. If token has empty `groups` (common with custom auth servers)\n3. Registry queries `idp_m2m_clients` collection in DocumentDB for client groups\n4. Groups are enriched and mapped to scopes using same `scopes.yml` logic\n\n## Step 3a: Create and Manage Users\n\n### Creating Users Manually (Okta Console)\n\n1. Go to **Directory** → **People** → **Add Person**\n2. Fill in user details:\n - **First name** and **Last name**\n - **Username** (email format)\n - **Primary email**\n - **Password**: Choose activation method\n3. Click **Save**\n4. Assign to groups:\n - Open the user's profile\n - Go to **Groups** tab\n - Click **Edit** → Select groups → **Save**\n\n### Creating Users via Registry IAM API\n\nIf `OKTA_API_TOKEN` is configured, you can create users through the registry:\n\n```bash\n# Create a new user\ncurl -X POST https://your-registry/api/iam/users \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"username\": \"john.doe@example.com\",\n \"email\": \"john.doe@example.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"groups\": [\"public-mcp-users\"]\n }'\n```\n\n### Creating M2M Service Accounts\n\nM2M service accounts are OAuth2 clients with Client Credentials grant:\n\n**Via Okta Console:**\n\n1. Go to **Applications** → **Applications** → **Create App Integration**\n2. Select **API Services** (not Web Application)\n3. **Name**: `ai-agent-3` (or your service name)\n4. Click **Save** → Copy **Client ID** and **Client Secret**\n5. The application is created but groups are managed separately in the registry\n\n**Via Registry IAM API:**\n\n```bash\n# Create M2M account with groups\ncurl -X POST https://your-registry/api/iam/m2m \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"ai-agent-3\",\n \"description\": \"AI Agent for autonomous operations\",\n \"groups\": [\"public-mcp-users\", \"ai-agents\"]\n }'\n\n# Response includes client_id and client_secret\n{\n \"client_id\": \"0oa9876543210fedcba\",\n \"client_secret\": \"secret-value-here\",\n \"groups\": [\"public-mcp-users\", \"ai-agents\"],\n \"okta_app_id\": \"0oa9876543210fedcba\"\n}\n```\n\nThe M2M account is stored in DocumentDB's `idp_m2m_clients` collection for groups enrichment.\n\n**Testing M2M token:**\n\n```bash\n# Get M2M token\ncurl -X POST https://dev-123456.okta.com/oauth2/v1/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials&scope=openid\" \\\n -u \"CLIENT_ID:CLIENT_SECRET\"\n\n# Use token to call registry\ncurl https://your-registry/api/servers \\\n -H \"Authorization: Bearer M2M_TOKEN\"\n```\n\n## Step 4: Create API Token (Optional)\n\nOnly required if you need IAM operations (user/group management through the registry).\n\n1. Go to **Security** → **API** → **Tokens** → **Create Token**\n2. Name it `MCP Gateway IAM` and copy the token value immediately\n3. For least-privilege access, create a custom admin role with only the permissions you need:\n\n| Operation | Required Permission |\n|-----------|-------------------|\n| List users | `okta.users.read` |\n| List groups | `okta.groups.read` |\n| Create/delete users | `okta.users.manage` |\n| Create/delete groups | `okta.groups.manage` |\n| Create service accounts | `okta.apps.manage` |\n\n## Environment Variables\n\n### Core Configuration\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `AUTH_PROVIDER` | Yes | Set to `okta` |\n| `OKTA_DOMAIN` | Yes | Your Okta org domain (e.g., `dev-123456.okta.com`) |\n| `OKTA_CLIENT_ID` | Yes | OAuth2 client ID from Step 1 |\n| `OKTA_CLIENT_SECRET` | Yes | OAuth2 client secret from Step 1 |\n\n### Optional Configuration\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OKTA_AUTH_SERVER_ID` | Optional | Custom authorization server ID from Step 2a (e.g., `aus1234567890abcdef`). If not set, uses Org Authorization Server. |\n| `OKTA_M2M_CLIENT_ID` | Optional | Separate M2M client ID (defaults to `OKTA_CLIENT_ID`) |\n| `OKTA_M2M_CLIENT_SECRET` | Optional | Separate M2M client secret (defaults to `OKTA_CLIENT_SECRET`) |\n| `OKTA_API_TOKEN` | For IAM | Admin API token from Step 4 (required for user/group management) |\n\n## Example Configuration\n\n### Basic Setup (Org Authorization Server)\n\n```bash\n# .env or docker-compose environment\nAUTH_PROVIDER=okta\nOKTA_DOMAIN=dev-123456.okta.com\nOKTA_CLIENT_ID=0oa1234567890abcdef\nOKTA_CLIENT_SECRET=your-client-secret-here\n\n# Optional: Admin API token for IAM operations\n# OKTA_API_TOKEN=your-api-token-here\n```\n\n### Advanced Setup (Custom Authorization Server for M2M)\n\n```bash\n# .env or docker-compose environment\nAUTH_PROVIDER=okta\nOKTA_DOMAIN=dev-123456.okta.com\nOKTA_CLIENT_ID=0oa1234567890abcdef\nOKTA_CLIENT_SECRET=your-client-secret-here\n\n# Custom authorization server for M2M tokens\nOKTA_AUTH_SERVER_ID=aus1234567890abcdef\n\n# Optional: Separate M2M credentials\nOKTA_M2M_CLIENT_ID=0oa0987654321fedcba\nOKTA_M2M_CLIENT_SECRET=your-m2m-secret-here\n\n# Admin API token for IAM operations\nOKTA_API_TOKEN=your-api-token-here\n```\n\n### Terraform Configuration\n\n```terraform\n# terraform.tfvars\nokta_enabled = true\nokta_domain = \"dev-123456.okta.com\"\nokta_client_id = \"0oa1234567890abcdef\"\nokta_client_secret = \"your-client-secret-here\"\nokta_m2m_client_id = \"0oa0987654321fedcba\"\nokta_m2m_client_secret = \"your-m2m-secret-here\"\nokta_api_token = \"your-api-token-here\"\nokta_auth_server_id = \"aus1234567890abcdef\" # Optional - for custom auth server\n\n# Ensure other providers are disabled\nentra_enabled = false\n```\n\n## Okta Endpoints (Auto-Derived)\n\nThe application automatically constructs OAuth2 endpoints based on your configuration:\n\n### Org Authorization Server (default, when `OKTA_AUTH_SERVER_ID` is not set)\n\n| Endpoint | URL Pattern |\n|----------|-------------|\n| Authorization | `https://{OKTA_DOMAIN}/oauth2/v1/authorize` |\n| Token | `https://{OKTA_DOMAIN}/oauth2/v1/token` |\n| UserInfo | `https://{OKTA_DOMAIN}/oauth2/v1/userinfo` |\n| JWKS | `https://{OKTA_DOMAIN}/oauth2/v1/keys` |\n| Logout | `https://{OKTA_DOMAIN}/oauth2/v1/logout` |\n| Issuer | `https://{OKTA_DOMAIN}` |\n\n### Custom Authorization Server (when `OKTA_AUTH_SERVER_ID` is set)\n\n| Endpoint | URL Pattern |\n|----------|-------------|\n| Authorization | `https://{OKTA_DOMAIN}/oauth2/{OKTA_AUTH_SERVER_ID}/v1/authorize` |\n| Token | `https://{OKTA_DOMAIN}/oauth2/{OKTA_AUTH_SERVER_ID}/v1/token` |\n| UserInfo | `https://{OKTA_DOMAIN}/oauth2/{OKTA_AUTH_SERVER_ID}/v1/userinfo` |\n| JWKS | `https://{OKTA_DOMAIN}/oauth2/{OKTA_AUTH_SERVER_ID}/v1/keys` |\n| Logout | `https://{OKTA_DOMAIN}/oauth2/{OKTA_AUTH_SERVER_ID}/v1/logout` |\n| Issuer | `https://{OKTA_DOMAIN}/oauth2/{OKTA_AUTH_SERVER_ID}` |\n\n**Example with custom auth server:**\n- `OKTA_DOMAIN=dev-123456.okta.com`\n- `OKTA_AUTH_SERVER_ID=aus1234567890abcdef`\n- JWKS URL: `https://dev-123456.okta.com/oauth2/aus1234567890abcdef/v1/keys`\n\n## Verifying Your Setup\n\nTest the JWKS endpoint:\n\n```bash\ncurl https://dev-123456.okta.com/oauth2/v1/keys\n```\n\nTest client credentials token generation:\n\n```bash\ncurl -X POST https://dev-123456.okta.com/oauth2/v1/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials&scope=openid\" \\\n -u \"CLIENT_ID:CLIENT_SECRET\"\n```\n\n## Troubleshooting\n\n**\"Permission Required\" error after login**\nYour Okta groups don't match the group names in `scopes.yml`. Create groups in Okta that match (e.g., `registry-admins`) and assign your user to them. See Step 3.\n\n**Groups not appearing in tokens**\nThe groups claim must be configured on the app's Sign On tab under \"Show legacy configuration\", not on the Authorization Server's Claims tab. See Step 2. Also verify your user is assigned to at least one group.\n\n**\"One or more scopes are not configured\" error**\nThis happens when using the default custom authorization server (`/oauth2/default/v1/*`) instead of the Org Authorization Server (`/oauth2/v1/*`). The Org Authorization Server has a built-in `groups` scope. Verify your endpoints use `/oauth2/v1/*`.\n\n**Can't find Client Secret after app creation**\nRegenerate it: App → General tab → Client Credentials → Edit → Regenerate Secret.\n\n**API token permission errors**\nCheck **Security** → **Administrators** for the role assigned to the token. Create a custom admin role with the specific scopes needed.\n\n**Non-standard domain warning in logs**\nThe provider validates domains against `*.okta.com`, `*.oktapreview.com`, and `*.okta-emea.com`. Custom domains will log a warning but still work.\n\n**\"No matching key found for kid\" error**\nThis means the JWT token was signed by a different authorization server than the one configured. Common causes:\n- Token was issued by custom auth server, but `OKTA_AUTH_SERVER_ID` is not set → Set the auth server ID\n- Token was issued by org auth server, but `OKTA_AUTH_SERVER_ID` is set → Remove or correct the auth server ID\n- Check the token's `iss` claim matches your issuer configuration\n\nVerify JWKS endpoint:\n```bash\n# For Org Authorization Server\ncurl https://dev-123456.okta.com/oauth2/v1/keys\n\n# For Custom Authorization Server\ncurl https://dev-123456.okta.com/oauth2/aus1234567890abcdef/v1/keys\n```\n\n**\"Audience doesn't match\" error for M2M tokens**\nWhen using a custom authorization server, M2M tokens have `aud` set to your API identifier (e.g., `api://ai-registry`), not the client ID. This is expected behavior. The auth server automatically handles this validation when `OKTA_AUTH_SERVER_ID` is configured.\n\n**M2M token returns 0 servers despite valid groups**\nCheck that groups are being mapped to scopes:\n1. Verify `scopes.yml` contains mappings for the M2M client's groups\n2. Check auth server logs for group enrichment messages:\n ```\n Groups enriched from MongoDB for client {client_id}: {groups}\n Mapped okta groups {groups} to scopes: {scopes}\n ```\n3. If using custom auth server, ensure `groups` claim is configured (see Step 2a)\n4. Verify the M2M client exists in `idp_m2m_clients` collection with correct groups\n\n**M2M groups not enriched from database**\nThe groups enrichment only activates when:\n- Token validation succeeds (`valid: true`)\n- Token has no groups OR empty groups array\n- Token contains a `client_id` claim (M2M tokens)\n\nCheck DocumentDB:\n```bash\n# Connect to mongo container\ndocker exec -it mcp-mongodb mongosh\n\n# Query M2M clients collection\nuse mcp_registry_default\ndb.idp_m2m_clients.find({ client_id: \"0oa9876543210fedcba\" })\n```\n\nExpected document structure:\n```json\n{\n \"client_id\": \"0oa9876543210fedcba\",\n \"name\": \"ai-agent-3\",\n \"groups\": [\"public-mcp-users\", \"ai-agents\"],\n \"provider\": \"okta\",\n \"enabled\": true,\n \"created_at\": \"2026-03-15T12:00:00Z\"\n}\n```\n" }, { "path": "docs/podman-apple-silicon.md", "content": "# Podman on Apple Silicon - Known Issues & Solutions\n\n## TL;DR - Quick Solution\n\n**Don't use `--prebuilt` with Podman on Apple Silicon. Build locally instead:**\n\n```bash\n# CORRECT - Build for ARM64\n./build_and_run.sh --podman\n\n# WRONG - Causes \"proxy already running\" error\n./build_and_run.sh --prebuilt --podman\n```\n\n## The Problem\n\n### Architecture Mismatch\n- **Pre-built images**: `linux/amd64` (Intel x86_64)\n- **Apple Silicon Macs**: `linux/arm64` (ARM64)\n- **Result**: Containers fail to start, Podman proxy gets stuck\n\n### Symptoms\n```\nWARNING: image platform (linux/amd64) does not match the expected platform (linux/arm64)\n...\nError: unable to start container \"...\": something went wrong with the request: \"proxy already running\\n\"\n```\n\n## Solutions\n\n### Option 1: Build Locally with Podman (Recommended)\n\nBuild ARM64-native images from source:\n\n```bash\n# Complete reset if proxy is stuck\npodman compose down --remove-orphans\npodman system prune -a -f\npodman machine stop\npodman machine rm -f podman-machine-default\n\n# Recreate Podman machine\npodman machine init --cpus 4 --memory 8192 --disk-size 50\npodman machine start\n\n# Build for ARM64 (takes 10-15 minutes first time)\n./build_and_run.sh --podman\n```\n\n**Pros:**\n- Native ARM64 images (better performance)\n- No architecture warnings\n- Reliable container startup\n\n**Cons:**\n- ⏱️ Slower first build (10-15 minutes)\n\n### Option 2: Use Docker Desktop (Easiest)\n\nDocker Desktop handles multi-arch images automatically:\n\n```bash\n# Stop Podman\npodman machine stop\n\n# Install Docker Desktop (if not already)\n# Download: https://www.docker.com/products/docker-desktop/\n\n# Use pre-built images with Docker\n./build_and_run.sh --prebuilt\n\n# Access at http://localhost (port 80)\n```\n\n**Pros:**\n- Fast deployment (2-3 minutes)\n- Pre-built images work reliably\n- Better multi-arch support\n\n**Cons:**\n- Requires Docker Desktop\n- Uses privileged ports (80/443)\n\n### Option 3: Fix Stuck Proxy Manually\n\nIf the proxy is stuck and reset doesn't work:\n\n```bash\n# Find stuck gvproxy processes\nps aux | grep gvproxy\n\n# Kill them (replace with actual process ID)\nkill -9 \n\n# Find stuck Podman processes\nps aux | grep podman | grep -v grep\nkill -9 \n\n# Remove socket files\nrm -rf ~/Library/Containers/com.github.containers.podman.*\n\n# Remove state files\nrm -rf ~/.config/containers/podman/machine/*\nrm -rf ~/.local/share/containers/podman/machine/*\n\n# Recreate Podman machine\npodman machine stop\npodman machine rm -f podman-machine-default\npodman machine init --cpus 4 --memory 8192 --disk-size 50\npodman machine start\n\n# Build locally (no --prebuilt!)\n./build_and_run.sh --podman\n```\n\n## Why This Happens\n\n### The Chain of Events\n\n1. **User runs**: `./build_and_run.sh --prebuilt --podman`\n2. **Script pulls**: `linux/amd64` images from Docker Hub\n3. **Podman tries**: To run amd64 images on arm64 system\n4. **Containers fail**: Due to architecture incompatibility\n5. **gvproxy stuck**: Networking proxy doesn't clean up properly\n6. **Subsequent attempts**: Fail with \"proxy already running\"\n\n### Technical Details\n\n- **Podman on macOS**: Runs in a QEMU VM (similar to Docker Desktop)\n- **Architecture emulation**: QEMU can emulate amd64 on arm64, but unreliably\n- **gvproxy networking**: Podman's networking proxy (`gvproxy`) handles port forwarding\n- **Cleanup issues**: When containers crash, proxy doesn't always terminate properly\n- **Socket conflicts**: Stuck proxy prevents new containers from binding ports\n\n## Verification\n\nAfter deployment, verify you're running ARM64 images:\n\n```bash\n# Check architecture of running containers\npodman inspect | grep Architecture\n\n# Should show: \"Architecture\": \"arm64\"\n# NOT: \"Architecture\": \"amd64\"\n```\n\n## Performance Comparison\n\n| Method | Architecture | First Deploy | Subsequent Deploys | Reliability |\n|--------|--------------|--------------|-------------------|-------------|\n| Podman + Local Build | ARM64 (native) | 10-15 min | 2-3 min | ⭐⭐⭐⭐⭐ |\n| Podman + Pre-built | AMD64 (emulated) | 2-3 min | 2-3 min | ⭐⭐ (unstable) |\n| Docker + Pre-built | AMD64 (emulated) | 2-3 min | 2-3 min | ⭐⭐⭐⭐ |\n| Docker + Local Build | ARM64 (native) | 10-15 min | 2-3 min | ⭐⭐⭐⭐⭐ |\n\n## Best Practices\n\n### ✅ DO\n\n- **Build locally** with Podman on Apple Silicon\n- **Use Docker Desktop** if you want pre-built images\n- **Check architecture** after deployment\n- **Reset Podman machine** if you encounter proxy errors\n\n### ❌ DON'T\n\n- **Don't use** `--prebuilt` with Podman on ARM64\n- **Don't mix** Docker and Podman (use one at a time)\n- **Don't ignore** architecture warnings\n- **Don't assume** emulation will work reliably\n\n## Future Improvements\n\nWe're working on:\n- [ ] ARM64 pre-built images on Docker Hub\n- [ ] Multi-arch manifest support\n- [ ] Automatic architecture detection in script\n- [ ] Better error messages for architecture mismatches\n\n## Additional Resources\n\n- [Podman Documentation](https://docs.podman.io/)\n- [Docker Multi-Platform Images](https://docs.docker.com/build/building/multi-platform/)\n- [Apple Silicon Support](https://www.docker.com/blog/apple-silicon-m1-chips-and-docker/)\n\n## Still Having Issues?\n\nIf you continue to experience problems:\n\n1. **Share full logs**: Include output from `podman machine logs`\n2. **System info**: Run `podman info` and share output\n3. **Open an issue**: [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues)\n4. **Include details**: Mac model, macOS version, Podman version\n\n## Quick Reference Commands\n\n```bash\n# Check your architecture\nuname -m # Should show: arm64\n\n# Check Podman version\npodman --version\n\n# Check container architecture\npodman inspect | grep Architecture\n\n# Full Podman reset\npodman machine stop\npodman machine rm -f podman-machine-default\npodman system reset -f\npodman machine init --cpus 4 --memory 8192 --disk-size 50\npodman machine start\n\n# Deploy correctly on Apple Silicon\n./build_and_run.sh --podman # NO --prebuilt!\n```\n\n" }, { "path": "docs/prebuilt-images.md", "content": "# Pre-built Docker Images for MCP Gateway Registry\n\nWhen using the `--prebuilt` option with `build_and_run.sh`, the following pre-built Docker images are pulled from Docker Hub. These images are published to the `mcpgateway` organization on Docker Hub.\n\n## MCP Gateway Images\n\n| Service | Image | Default Tag | Description | Port |\n|---------|-------|-------------|-------------|------|\n| Registry | `mcpgateway/registry:latest` | latest | Main registry service with nginx, SSL, FAISS, and models | 80, 443, 7860 |\n| Auth Server | `mcpgateway/auth-server:latest` | latest | Authentication service supporting Cognito, GitHub, Google, and Keycloak | 8888 |\n| Metrics Service | `mcpgateway/metrics-service:latest` | latest | Metrics collection service with SQLite storage and OTEL support | 8890, 9465 |\n| Current Time Server | `mcpgateway/currenttime-server:latest` | latest | MCP server providing current time functionality | 8000 |\n| Financial Info Server | `mcpgateway/fininfo-server:latest` | latest | MCP server for financial information | 8001 |\n| MCPGW Server | `mcpgateway/mcpgw-server:latest` | latest | MCP Gateway server for service management | 8003 |\n| Real Server Fake Tools | `mcpgateway/realserverfaketools-server:latest` | latest | Example MCP server with mock tools | 8002 |\n\n## External Images\n\nThe following external images are pulled from their original sources:\n\n| Service | Image | Source | Description | Port |\n|---------|-------|--------|-------------|------|\n| Alpine Linux | `alpine:latest` | Docker Hub Official | Lightweight Linux for metrics database initialization | N/A |\n| Prometheus | `prom/prometheus:latest` | Docker Hub Official | Metrics collection and time-series database | 9090 |\n| Grafana | `grafana/grafana:latest` | Docker Hub Official | Metrics visualization and dashboards | 3000 |\n| PostgreSQL | `postgres:16-alpine` | Docker Hub Official | Database for Keycloak | 5432 (internal) |\n| Keycloak | `quay.io/keycloak/keycloak:25.0` | Quay.io | Identity and access management service | 8080 |\n| MongoDB CE | `mongo:8.2` | Docker Hub Official | MongoDB Community Edition 8.2 with replica set support for local development | 27017 (internal) |\n\n## Manual Download Commands\n\nTo manually pull these images for Kubernetes deployment or offline use:\n\n```bash\n# MCP Gateway images from Docker Hub\ndocker pull mcpgateway/registry:latest\ndocker pull mcpgateway/auth-server:latest\ndocker pull mcpgateway/metrics-service:latest\ndocker pull mcpgateway/currenttime-server:latest\ndocker pull mcpgateway/fininfo-server:latest\ndocker pull mcpgateway/mcpgw-server:latest\ndocker pull mcpgateway/realserverfaketools-server:latest\n\n# External images\ndocker pull alpine:latest\ndocker pull prom/prometheus:latest\ndocker pull grafana/grafana:latest\ndocker pull postgres:16-alpine\ndocker pull quay.io/keycloak/keycloak:25.0\ndocker pull mongo:8.2\n```\n\n## HTTPS Configuration\n\nBy default, pre-built images run on HTTP (port 80) only. To enable HTTPS (port 443):\n\n### Option 1: Let's Encrypt Certificates\n\n```bash\n# Install certbot\nsudo apt-get update && sudo apt-get install -y certbot\n\n# Obtain certificate (requires domain and port 80)\nsudo certbot certonly --standalone -d your-domain.com\n\n# Certificate files will be at:\n# - /etc/letsencrypt/live/your-domain/fullchain.pem\n# - /etc/letsencrypt/live/your-domain/privkey.pem\n```\n\n### Option 2: Commercial CA Certificates\n\nPurchase SSL certificates from a trusted Certificate Authority.\n\n### Copy Certificates to Expected Location\n\n```bash\n# Create the ssl directory structure\nmkdir -p ${HOME}/mcp-gateway/ssl/certs\nmkdir -p ${HOME}/mcp-gateway/ssl/private\n\n# Copy your certificate files\n# Replace paths below with your actual certificate locations\ncp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/fullchain.pem\ncp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/privkey.pem\n\n# Set proper permissions\nchmod 644 ${HOME}/mcp-gateway/ssl/certs/fullchain.pem\nchmod 600 ${HOME}/mcp-gateway/ssl/private/privkey.pem\n```\n\n**Note**: If SSL certificates are not present at `${HOME}/mcp-gateway/ssl/certs/fullchain.pem` and `${HOME}/mcp-gateway/ssl/private/privkey.pem`, the MCP Gateway will automatically run in HTTP-only mode.\n\nThen restart:\n\n```bash\n./build_and_run.sh --prebuilt\n```\n\nThe registry container will detect the certificates and enable HTTPS automatically. Check logs:\n\n```bash\ndocker compose logs registry | grep -i ssl\n# Expected: \"SSL certificates found - HTTPS enabled\"\n```" }, { "path": "docs/quickstart.md", "content": "# Quick Start Guide\n\nThis guide walks you through setting up the MCP Gateway & Registry using pre-built Docker images. For other deployment options, see the [Installation Guide](installation.md).\n\n## Prerequisites\n\n
\nClick to expand: Install Docker, Node.js, Python, and UV\n\n**Install Docker and Docker Compose:**\n```bash\n# Install Docker\nsudo apt-get update\nsudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common\n\n# Add Docker's official GPG key\ncurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg\n\n# Add Docker repository\necho \"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable\" | sudo tee /etc/apt/sources.list.d/docker.list\n\n# Install Docker Engine\nsudo apt-get update\nsudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin\n\n# Add user to docker group (logout/login required, or use newgrp)\nsudo usermod -aG docker $USER\nnewgrp docker\n\n# Verify installation\ndocker --version\ndocker compose version\n```\n\n**Install Node.js 20.x:**\n```bash\ncurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -\nsudo apt-get install -y nodejs\nnode --version # Should show v20.x.x\n```\n\n**Install Python and UV:**\n```bash\nsudo apt-get install -y python3.14 python3.14-venv python3-pip\n\n# Install UV package manager\ncurl -LsSf https://astral.sh/uv/install.sh | sh\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\nsource ~/.bashrc\nuv --version\n```\n\n**Install additional tools:**\n```bash\nsudo apt-get install -y git jq curl wget\n```\n\n
\n\n---\n\n## Step 1: Clone and Setup\n\n```bash\ngit clone https://github.com/agentic-community/mcp-gateway-registry.git\ncd mcp-gateway-registry\ncp .env.example .env\n\n# Setup Python virtual environment\n# (Enterprise Macs: export UV_NATIVE_TLS=true if you hit TLS certificate errors)\nuv sync\nsource .venv/bin/activate\n```\n\n---\n\n## Step 2: Download Embeddings Model\n\nDownload the required sentence-transformers model using the [HuggingFace CLI](https://huggingface.co/docs/huggingface_hub/main/en/guides/cli):\n```bash\n# Install huggingface_hub if not already installed\nuv pip install -U huggingface_hub\n\n# Download the model\nhf download sentence-transformers/all-MiniLM-L6-v2 --local-dir ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2\n```\n\n---\n\n## Step 3: Configure Environment\n\n
\nClick to expand: Edit .env file with your settings\n\nEdit the `.env` file with your preferred editor:\n```bash\nnano .env\n```\n\n**Required changes:**\n```bash\n# Authentication provider (do not change)\nAUTH_PROVIDER=keycloak\n\n# Set secure passwords (CHANGE THESE!)\nKEYCLOAK_ADMIN_PASSWORD=YourSecureAdminPassword123!\nINITIAL_ADMIN_PASSWORD=YourSecureAdminPassword123! # MUST match KEYCLOAK_ADMIN_PASSWORD\nKEYCLOAK_DB_PASSWORD=SecureKeycloakDB123!\n\n# Session cookie security (CRITICAL for local development)\n# For HTTP access (localhost): MUST be false\nSESSION_COOKIE_SECURE=false\n\n# For HTTPS access (production): set to true\n# SESSION_COOKIE_SECURE=true\n\n# Leave these as defaults\nKEYCLOAK_URL=http://localhost:8080\nKEYCLOAK_REALM=mcp-gateway\nKEYCLOAK_CLIENT_ID=mcp-gateway-client\n```\n\n**Generate and set SECRET_KEY:**\n```bash\nSECRET_KEY=$(python3 -c \"import secrets; print(secrets.token_urlsafe(64))\")\nsed -i \"s/^#*\\s*SECRET_KEY=.*/SECRET_KEY=$SECRET_KEY/\" .env\necho \"Generated SECRET_KEY: $SECRET_KEY\"\n```\n\nSave and exit (Ctrl+X, then Y, then Enter if using nano).\n\n
\n\n**Set environment variables for deployment:**\n```bash\nexport DOCKERHUB_ORG=mcpgateway\nsource .env\nexport KEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\n```\n\n---\n\n## Step 4: Deploy with Pre-built Images\n\n```bash\n./build_and_run.sh --prebuilt\n```\n\n> **Port Differences:**\n> - **Docker**: Services run on privileged ports (`http://localhost`, `https://localhost`)\n> - **Podman**: Services run on non-privileged ports (`http://localhost:8080`, `https://localhost:8443`)\n\nOnce the build completes and you see the container logs streaming, you can press **Ctrl+C** to exit the log view and continue with the next steps. The containers will continue running in the background.\n\nWait for all services to start (2-3 minutes), then verify:\n```bash\ndocker compose ps\n# All services should show as \"Up\"\n```\n\n---\n\n## Step 5: Initialize MongoDB\n\nInitialize the MongoDB database with required collections, indexes, and default scopes:\n\n```bash\n# Run the MongoDB initialization container\ndocker compose up mongodb-init\n\n# Verify collections were created\ndocker exec mcp-mongodb mongosh --eval \"use mcp_registry; show collections\"\n# Should show: mcp_servers_default, mcp_agents_default, mcp_scopes_default, etc.\n\n# Restart auth-server to load the new scopes\ndocker compose restart auth-server\n```\n\n---\n\n## Step 6: Initialize Keycloak\n\n
\nClick to expand: Complete Keycloak setup instructions\n\n**6a. Wait for Keycloak to be ready:**\n```bash\n# Monitor logs until you see \"Keycloak started\"\ndocker compose logs -f keycloak\n# Press Ctrl+C when you see \"Keycloak 25.x.x started\"\n\n# Or check health endpoint\ncurl http://localhost:8080/realms/master\n# Should return JSON with realm information\n```\n\n**6b. Disable SSL for master realm (required for HTTP access):**\n```bash\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:8080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | \\\n jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:8080/admin/realms/master\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n```\n\n**6c. Initialize Keycloak realm and clients:**\n```bash\nchmod +x keycloak/setup/init-keycloak.sh\n./keycloak/setup/init-keycloak.sh\n```\n\n**6d. Disable SSL for application realm:**\n```bash\nADMIN_TOKEN=$(curl -s -X POST \"http://localhost:8080/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | \\\n jq -r '.access_token') && \\\ncurl -X PUT \"http://localhost:8080/admin/realms/mcp-gateway\" \\\n -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}'\n```\n\n**6e. Retrieve and save client credentials:**\n```bash\nchmod +x keycloak/setup/get-all-client-credentials.sh\n./keycloak/setup/get-all-client-credentials.sh\n```\n\n**6f. Update .env with client secrets:**\n```bash\n# View the retrieved secrets\ncat .oauth-tokens/keycloak-client-secrets.txt\n\n# Update .env with the actual secret values shown above\nnano .env\n# Find and update: KEYCLOAK_CLIENT_SECRET and KEYCLOAK_M2M_CLIENT_SECRET\n```\n\n**6g. Recreate containers to apply new credentials:**\n```bash\n# Recreate containers to pick up the updated .env values\n./build_and_run.sh --prebuilt\n```\nOnce logs are streaming, press **Ctrl+C** to exit - containers will continue running.\n\n
\n\n---\n\n## Step 7: Set Up Users and Service Accounts\n\n```bash\nchmod +x ./cli/bootstrap_user_and_m2m_setup.sh\n./cli/bootstrap_user_and_m2m_setup.sh\n```\n\nThis creates:\n- **3 groups**: `registry-users-lob1`, `registry-users-lob2`, `registry-admins`\n- **6 users**:\n - **LOB1**: `lob1-bot` (M2M) and `lob1-user` (human)\n - **LOB2**: `lob2-bot` (M2M) and `lob2-user` (human)\n - **Admin**: `admin-bot` (M2M) and `admin-user` (human)\n\nAll credentials are saved to `.oauth-tokens/` directory.\n\n---\n\n## Step 8: Create AI Agent Account (Optional)\n\n
\nClick to expand: Create additional agent accounts\n\n```bash\nchmod +x keycloak/setup/setup-agent-service-account.sh\n\n# Create a test agent with full access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id test-agent \\\n --group mcp-servers-unrestricted\n\n# Create an agent for AI coding assistants\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id ai-coding-assistant \\\n --group mcp-servers-unrestricted\n\n# Retrieve credentials for the new agents\n./keycloak/setup/get-all-client-credentials.sh\n```\n\n
\n\n---\n\n## Step 9: Access the Registry\n\n
\nClick to expand: Remote Access Options (EC2, Port Forwarding, etc.)\n\nThe method to access the web UI depends on where you're running the MCP Gateway:\n\n**Option A: Local Machine (Linux/macOS)**\n\nIf you're running on your local machine, simply open a browser - you're already on localhost.\n\n**Option B: AWS EC2 with Port Forwarding**\n\nIf you're running on EC2 and want to access from your local machine via SSH tunnels:\n\n```bash\n# From your local machine, create SSH tunnels\nssh -i your-key.pem -L 7860:localhost:7860 -L 8080:localhost:8080 -L 8888:localhost:8888 -L 80:localhost:80 ubuntu@your-ec2-ip\n\n# Then access in your local browser: http://localhost:7860\n```\n\n**Option C: AWS EC2 with Remote Desktop (GUI Access)**\n\nIf you prefer a full desktop environment on your EC2 instance:\n\n```bash\n# Install XFCE desktop and XRDP\nsudo apt update && sudo apt install -y xfce4 xfce4-goodies xrdp firefox\necho \"xfce4-session\" > ~/.xsession\nsudo systemctl enable xrdp && sudo systemctl start xrdp\nsudo passwd ubuntu # Set password for RDP login\n```\n\n**AWS Security Group**: Add inbound rule for port 3389 (RDP) from your IP.\n\n**Connect**: Use Remote Desktop Connection (Windows) or Microsoft Remote Desktop (macOS) with `your-ec2-ip:3389`, username `ubuntu`.\n\nSee [Remote Desktop Setup Guide](remote-desktop-setup.md) for detailed instructions.\n\n
\n\n```bash\n# On macOS:\nopen http://localhost:7860\n\n# On Linux (install xdg-utils if xdg-open is not available):\n# sudo apt install xdg-utils\nxdg-open http://localhost:7860\n\n# Or open http://localhost:7860 in your browser\n```\n\nLogin with:\n- **Username**: `admin` (or any user created in Step 6)\n- **Password**: The `KEYCLOAK_ADMIN_PASSWORD` you set in Step 3\n\n---\n\n## Step 10: Register Example Servers and Agents (Optional)\n\nTo register example MCP servers and A2A agents, first get a JWT token from the Registry UI:\n\n1. In the Registry UI, click the **\"Get JWT Token\"** button (top-left corner)\n2. In the popup, click **\"Copy JSON\"** to copy the full token JSON\n3. Save it to a `.token` file:\n\n```bash\n# Create .token file with the copied JSON\n# Note: .token is already in .gitignore so it won't be committed to the repo\ncat > .token << 'EOF'\n\nEOF\n```\n\nThen register servers and agents using the Registry Management CLI:\n\n> **Note:** Registration includes automatic security scanning using [Cisco AI Defense MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner) for servers and [Cisco AI Defense A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner) for agents. Each registration may take a few seconds while the security scan completes.\n\n```bash\n# Register MCP servers\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n register --config cli/examples/mcpgw.json\n\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n register --config cli/examples/cloudflare-docs-server-config.json\n\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n register --config cli/examples/context7-server-config.json\n\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n register --config cli/examples/currenttime.json\n\n# Register A2A agents\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n agent-register --config cli/examples/travel_assistant_agent_card.json\n\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n agent-register --config cli/examples/flight_booking_agent_card.json\n\n# Verify registrations\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token list\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token agent-list\n```\n\nServers and agents are registered as **disabled** by default. Refresh the Registry UI to see them, then enable them using the toggle controls on each server/agent card.\n\n---\n\n## Step 11: Test the Setup\n\nTest the registry using the Registry Management CLI:\n\n```bash\n# List registered servers\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token list\n\n# List registered agents\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token agent-list\n\n# Search for servers by natural language\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n server-search --query \"documentation tools\"\n\n# Search for agents by natural language\nuv run python api/registry_management.py --registry-url http://localhost --token-file .token \\\n agent-search --query \"travel booking\"\n\n# Invoke a tool on an MCP server (e.g., get current time)\n# This exercises the \"Gateway\" functionality - the request is routed through the\n# MCP Gateway to the backend currenttime server, demonstrating centralized access\nuv run python cli/mcp_client.py --url http://localhost/currenttime/mcp --token-file .token \\\n call --tool current_time_by_timezone --args '{\"tz_name\": \"America/New_York\"}'\n```\n\n---\n\n## Next Steps\n\n- [Authentication Setup](auth.md) - Configure OAuth and identity providers\n- [AI Coding Assistants Setup](ai-coding-assistants-setup.md) - Integrate with VS Code, Cursor, Claude Code\n- [Complete Installation Guide](installation.md) - Additional deployment options\n- [Configuration Reference](configuration.md) - Environment variables and settings\n\n## Alternative Deployment Options\n\n### Podman (Rootless)\n\nFor macOS and rootless Linux environments, see the [Installation Guide](installation.md#podman-installation) and [macOS Setup Guide](macos-setup-guide.md#podman-deployment).\n\n### Build from Source\n\nFor customization or development, see the [Complete Setup Guide](complete-setup-guide.md).\n" }, { "path": "docs/registration-webhooks.md", "content": "# Registration Webhooks and Gate\n\nMCP Gateway Registry provides two external integration points for registration lifecycle events: **notification webhooks** that fire after a registration or deletion, and a **registration gate** (admission control) that can approve or deny registrations and updates before they are persisted.\n\n## Notification Webhooks\n\nMCP Gateway Registry can send HTTP webhook notifications when servers, agents, or skills are registered (added) or deleted (removed). This enables external systems to react to registry changes in real time, for example updating a CMDB, triggering a CI/CD pipeline, sending a Slack notification, or syncing with a third-party inventory.\n\n## Overview\n\nRegistration webhooks are **fire-and-forget**: the registry sends an async POST to a configurable URL after a successful registration or deletion, logs the result, and moves on. A webhook failure never blocks or rolls back the operation that triggered it.\n\n### Supported Events\n\n| Event Type | Trigger | Asset Types |\n|------------|---------|-------------|\n| `registration` | A new asset is added to the registry | server, agent, skill |\n| `deletion` | An existing asset is removed from the registry | server, agent, skill |\n\n### Key Design Decisions\n\n| Decision | Choice | Rationale |\n|----------|--------|-----------|\n| Delivery model | Fire-and-forget | Registry availability is never affected by webhook failures |\n| Failure handling | Log at WARNING level | Operators can monitor via CloudWatch or log aggregation |\n| Auth header handling | Auto-prefix Bearer for Authorization header | Follows RFC 6750 convention without extra config |\n| HTTPS enforcement | Warn but allow HTTP | Avoids breaking dev/test setups while flagging insecure production use |\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Type | Default | Description |\n|----------|------|---------|-------------|\n| `REGISTRATION_WEBHOOK_URL` | string | `\"\"` (disabled) | Full URL to POST to. Only `http://` and `https://` schemes are accepted. Leave empty to disable. |\n| `REGISTRATION_WEBHOOK_AUTH_HEADER` | string | `Authorization` | Name of the HTTP header used for authentication. If set to `Authorization`, the token is auto-prefixed with `Bearer `. For any other header (e.g. `X-API-Key`), the token is sent as-is. |\n| `REGISTRATION_WEBHOOK_AUTH_TOKEN` | string | `\"\"` | Auth token value. Leave empty for unauthenticated webhooks. |\n| `REGISTRATION_WEBHOOK_TIMEOUT_SECONDS` | int | `10` | HTTP timeout per request in seconds. |\n\n### Example Configurations\n\n**Unauthenticated webhook (dev/test):**\n\n```bash\nREGISTRATION_WEBHOOK_URL=https://hooks.example.com/registry\nREGISTRATION_WEBHOOK_AUTH_HEADER=Authorization\nREGISTRATION_WEBHOOK_AUTH_TOKEN=\nREGISTRATION_WEBHOOK_TIMEOUT_SECONDS=10\n```\n\n**Bearer token authentication:**\n\n```bash\nREGISTRATION_WEBHOOK_URL=https://hooks.example.com/registry\nREGISTRATION_WEBHOOK_AUTH_HEADER=Authorization\nREGISTRATION_WEBHOOK_AUTH_TOKEN=my-secret-bearer-token\nREGISTRATION_WEBHOOK_TIMEOUT_SECONDS=10\n```\n\nThe request will include `Authorization: Bearer my-secret-bearer-token`.\n\n**Custom API key header:**\n\n```bash\nREGISTRATION_WEBHOOK_URL=https://hooks.example.com/registry\nREGISTRATION_WEBHOOK_AUTH_HEADER=X-API-Key\nREGISTRATION_WEBHOOK_AUTH_TOKEN=my-api-key-value\nREGISTRATION_WEBHOOK_TIMEOUT_SECONDS=5\n```\n\nThe request will include `X-API-Key: my-api-key-value`.\n\n## Webhook Payload\n\nEvery webhook POST sends a JSON body with the following structure:\n\n```json\n{\n \"event_type\": \"registration\",\n \"registration_type\": \"agent\",\n \"timestamp\": \"2026-04-23T14:30:00.000000+00:00\",\n \"performed_by\": \"admin@example.com\",\n \"card\": {\n \"name\": \"My Agent\",\n \"path\": \"/agents/my-agent\",\n \"description\": \"An example A2A agent\",\n \"...\": \"full card data as stored in the registry\"\n }\n}\n```\n\n### Payload Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `event_type` | string | `\"registration\"` (asset added) or `\"deletion\"` (asset removed) |\n| `registration_type` | string | `\"server\"`, `\"agent\"`, or `\"skill\"` |\n| `timestamp` | string | ISO 8601 timestamp in UTC |\n| `performed_by` | string or null | Username of the operator who performed the action (null if unknown) |\n| `card` | object | The full card JSON as stored in the registry |\n\n### HTTP Request Details\n\n| Aspect | Value |\n|--------|-------|\n| Method | `POST` |\n| Content-Type | `application/json` |\n| Timeout | Configurable via `REGISTRATION_WEBHOOK_TIMEOUT_SECONDS` |\n| Retries | None (fire-and-forget) |\n| TLS verification | Enabled by default (httpx default behavior) |\n\n## Deployment Configuration\n\nThe webhook environment variables must be set on the **registry** service (not the auth server).\n\n### Docker Compose\n\nAll three Compose files (`docker-compose.yml`, `docker-compose.podman.yml`, `docker-compose.prebuilt.yml`) pass the variables to the `mcp-gateway-registry` service:\n\n```yaml\nservices:\n mcp-gateway-registry:\n environment:\n - REGISTRATION_WEBHOOK_URL=${REGISTRATION_WEBHOOK_URL:-}\n - REGISTRATION_WEBHOOK_AUTH_HEADER=${REGISTRATION_WEBHOOK_AUTH_HEADER:-Authorization}\n - REGISTRATION_WEBHOOK_AUTH_TOKEN=${REGISTRATION_WEBHOOK_AUTH_TOKEN:-}\n - REGISTRATION_WEBHOOK_TIMEOUT_SECONDS=${REGISTRATION_WEBHOOK_TIMEOUT_SECONDS:-10}\n```\n\n### Terraform / ECS\n\nThe variables are defined in `terraform/aws-ecs/variables.tf` and wired into the registry ECS task definition via `terraform/aws-ecs/modules/mcp-gateway/ecs-services.tf` (inside `module \"ecs_service_registry\"`).\n\nSet values in `terraform.tfvars`:\n\n```hcl\nregistration_webhook_url = \"https://hooks.example.com/registry\"\nregistration_webhook_auth_header = \"X-API-Key\"\nregistration_webhook_auth_token = \"my-api-key\"\nregistration_webhook_timeout_seconds = 10\n```\n\nFor sensitive values (tokens), use AWS Secrets Manager references instead of plaintext in tfvars.\n\n### Helm / EKS\n\nThe variables are defined in `charts/registry/values.yaml` and mapped in the deployment template and secret:\n\n```yaml\n# charts/registry/values.yaml\nregistrationWebhook:\n url: \"\"\n authHeader: \"Authorization\"\n authToken: \"\"\n timeoutSeconds: 10\n```\n\nSensitive values (auth tokens) are stored in the Kubernetes secret (`charts/registry/templates/secret.yaml`) and injected via `secretKeyRef`.\n\n## Logging and Observability\n\nThe webhook service logs at three levels:\n\n| Level | Condition | Example Message |\n|-------|-----------|-----------------|\n| INFO | Webhook sent successfully | `Registration webhook sent: event=registration, type=agent, status=200, url=https://...` |\n| WARNING | Timeout or connection failure | `Registration webhook timed out after 10s: event=registration, type=agent, url=https://...` |\n| WARNING | HTTP (not HTTPS) URL configured | `Registration webhook URL uses HTTP (not HTTPS). Credential data may be transmitted insecurely.` |\n| ERROR | Invalid URL scheme | `Invalid webhook URL scheme: ftp://...` |\n\nIn ECS deployments, these log messages appear in the registry task's CloudWatch Log Group.\n\n## Building a Webhook Receiver\n\nA minimal webhook receiver only needs to accept a POST with a JSON body and return a 2xx status code. Here is a Python example:\n\n```python\nfrom fastapi import FastAPI, Request\n\napp = FastAPI()\n\n@app.post(\"/webhook\")\nasync def handle_webhook(request: Request):\n payload = await request.json()\n event = payload.get(\"event_type\")\n asset_type = payload.get(\"registration_type\")\n card = payload.get(\"card\", {})\n name = card.get(\"name\") or card.get(\"display_name\", \"unknown\")\n\n print(f\"Received {event} event for {asset_type}: {name}\")\n\n # Your custom logic here:\n # - Send a Slack notification\n # - Update a CMDB\n # - Trigger a CI/CD pipeline\n # - Sync with an external inventory\n\n return {\"status\": \"ok\"}\n```\n\nRun with: `uvicorn receiver:app --host 0.0.0.0 --port 6789`\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| No webhook logs at all | `REGISTRATION_WEBHOOK_URL` is empty or not set | Set the variable in the correct service |\n| Webhook env vars set but no calls | Variables on the wrong ECS service | Ensure they are on the **registry** service, not the auth server |\n| Timeout warnings | Receiver too slow or unreachable | Increase `REGISTRATION_WEBHOOK_TIMEOUT_SECONDS` or check network connectivity |\n| HTTP warning in logs | URL uses `http://` instead of `https://` | Switch to HTTPS for production |\n\n---\n\n## Registration Gate (Admission Control)\n\n![Registration Gate Configuration](img/registration-gate.png)\n\nThe **registration gate** is an admission control webhook called **before** a registration or update is persisted. Unlike the notification webhook above (which fires after the fact and cannot block the operation), the registration gate can **approve or deny** a request based on custom business logic such as naming conventions, compliance rules, or approval workflows.\n\n### How It Differs from the Notification Webhook\n\n| Aspect | Notification Webhook | Registration Gate |\n|--------|---------------------|-------------------|\n| Timing | After the registration is persisted | Before the registration is persisted |\n| Can block registration | No (fire-and-forget) | Yes (approve/deny) |\n| Failure behavior | Logged, never blocks caller | Fail-closed: blocks registration if gate is unavailable |\n| Retries | None | Configurable with exponential backoff |\n| Applies to | Registration and deletion events | Registration and update events |\n| Credential handling | Full card data sent | Credentials stripped from payload |\n\n### Capabilities\n\n- Approve or deny registrations and updates for servers, agents, and skills\n- Configurable authentication: none, API key, or Bearer token\n- Fail-closed design: if the gate is unreachable after retries, registration is blocked\n- Custom denial messages returned to the caller as HTTP 403\n- Sensitive fields (credentials, tokens, passwords) are automatically stripped from the payload sent to the gate\n- Exponential backoff retries (0.5s, 1s, 2s, ...)\n- Startup connectivity check (non-blocking, logs warnings if gate is unreachable)\n\n### Gate Protocol\n\nThe registry sends a POST request to the gate URL with the following JSON body:\n\n```json\n{\n \"asset_type\": \"agent\",\n \"operation\": \"register\",\n \"source_api\": \"/api/agents/register\",\n \"registration_payload\": { ... },\n \"request_headers\": { \"host\": \"...\", \"content-type\": \"...\" }\n}\n```\n\n**Fields:**\n\n| Field | Description |\n|-------|-------------|\n| `asset_type` | `\"agent\"`, `\"server\"`, or `\"skill\"` |\n| `operation` | `\"register\"` or `\"update\"` |\n| `source_api` | The API path that triggered the request |\n| `registration_payload` | The registration data with sensitive fields removed |\n| `request_headers` | HTTP headers from the original request (sensitive headers excluded) |\n\n**Gate Response Codes:**\n\n| Status Code | Meaning |\n|-------------|---------|\n| `200` | Registration allowed |\n| `403` | Registration denied. Response body may include `{\"error\": \"reason\"}` |\n| Any other | Triggers retry (unexpected status) |\n\n### Credential Sanitization\n\nThe following fields are automatically removed from `registration_payload` before sending to the gate:\n\n- Fields named: `auth_credential`, `auth_credential_encrypted`, `auth_header_name`\n- Fields containing: `credential`, `secret`, `token`, `password`, `api_key`\n\nSensitive request headers are also excluded: `authorization`, `cookie`, `x-csrf-token`.\n\n### Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `REGISTRATION_GATE_ENABLED` | `false` | Enable/disable the gate |\n| `REGISTRATION_GATE_URL` | (empty) | URL of the gate endpoint. Must be set when enabled |\n| `REGISTRATION_GATE_AUTH_TYPE` | `none` | Auth type: `none`, `api_key`, or `bearer` |\n| `REGISTRATION_GATE_AUTH_CREDENTIAL` | (empty) | API key or Bearer token value |\n| `REGISTRATION_GATE_AUTH_HEADER_NAME` | `X-Api-Key` | Header name for `api_key` auth type |\n| `REGISTRATION_GATE_TIMEOUT_SECONDS` | `5` | HTTP timeout per attempt (seconds) |\n| `REGISTRATION_GATE_MAX_RETRIES` | `2` | Retry attempts after first failure (exponential backoff) |\n\n### Endpoints Covered\n\nThe gate is checked on the following operations:\n\n| Asset Type | Operation | Endpoint |\n|------------|-----------|----------|\n| Agent | Register | `POST /api/agents/register` |\n| Agent | Update | `PUT /api/agents/{path}` |\n| Server | Register | `POST /servers/register`, `POST /internal/register`, `POST /api/servers/register` |\n| Server | Update | `POST /edit/{path}` |\n| Skill | Register | `POST /api/skills` |\n| Skill | Update | `PUT /api/skills/{path}` |\n\n### Example: Simple Gate Endpoint\n\nA minimal Python gate endpoint that approves all registrations:\n\n```python\nfrom fastapi import FastAPI, Request\n\napp = FastAPI()\n\n@app.post(\"/gate\")\nasync def gate(request: Request):\n body = await request.json()\n # Implement your approval logic here\n return {\"status\": \"allowed\"}\n```\n\nTo deny a registration, return HTTP 403 with an error message:\n\n```python\nfrom fastapi import FastAPI, Request\nfrom fastapi.responses import JSONResponse\n\napp = FastAPI()\n\n@app.post(\"/gate\")\nasync def gate(request: Request):\n body = await request.json()\n name = body.get(\"registration_payload\", {}).get(\"name\", \"\")\n if not name.startswith(\"prod-\"):\n return JSONResponse(\n status_code=403,\n content={\"error\": \"All production assets must start with 'prod-'\"},\n )\n return {\"status\": \"allowed\"}\n```\n\nSee [issue #809](https://github.com/agentic-community/mcp-gateway-registry/issues/809) for the full design specification.\n" }, { "path": "docs/registry-api-auth.md", "content": "# Registry API Authentication\n\nThis page is the single source of truth for how callers authenticate against the **Registry API** (`/api/*`, `/v0.1/*`) — the HTTP surface used by the UI, the `registry_management.py` CLI, and any script or service that talks to the registry.\n\n**Scope clarification.** This document covers the **Registry API** only. The **MCP Gateway** surface (`//tools/list`, `//messages`, etc.) always requires full IdP authentication and is governed by `scopes.yml` / `mcp_scope_default`. MCP gateway authn/authz is described in [auth.md](auth.md) and [scopes.md](scopes.md).\n\n## Table of contents\n\n1. [The big picture](#the-big-picture)\n2. [Accepted credentials today](#accepted-credentials-today)\n3. [Static API token (`REGISTRY_API_TOKEN`)](#static-api-token-registry_api_token)\n4. [Multi-key static tokens (`REGISTRY_API_KEYS`)](#multi-key-static-tokens-registry_api_keys)\n5. [Session cookie (browser UI)](#session-cookie-browser-ui)\n6. [IdP-issued JWT (Okta / Entra / Cognito / Keycloak)](#idp-issued-jwt)\n7. [UI-issued self-signed JWT](#ui-issued-self-signed-jwt)\n8. [Coexistence rules (who wins when)](#coexistence-rules)\n9. [Threat model for static tokens](#threat-model-for-static-tokens)\n10. [Roadmap: near-term improvements](#roadmap-near-term-improvements)\n - [#826 — external user access tokens (service-on-behalf-of-user)](#826--external-user-access-tokens)\n11. [Common operator tasks](#common-operator-tasks)\n12. [FAQ](#faq)\n13. [References](#references)\n\n## The big picture\n\nEvery call to a Registry API endpoint passes through the **auth server's `/validate` endpoint** before reaching the registry application. The auth server decides, for each incoming request, whether the caller is authenticated and what identity to stamp on the request.\n\n```\nClient nginx auth_server:/validate registry\n │ │ │ │\n │── GET /api/... ─────▶│ │ │\n │ (cookie or Bearer) │ │ │\n │ │── auth_request ─────────▶│ │\n │ │ │── 200 + X-Auth-Method, │\n │ │ │ X-Scopes, ... │\n │ │ │ OR 401/403 │\n │ │◀─────────────────────────│ │\n │ │ │ │\n │ │── proxy_pass ────────────────────────────────────────▶ │\n │ │ (with X-Auth-Method and other identity headers) │\n │ │ │\n │◀─────────────────────│◀────────────────── response ───────────────────────────│\n```\n\nThe registry reads `X-Auth-Method` and related headers to decide what the caller can do. It does **not** re-validate the credential — the auth server has the only say on identity.\n\n## Accepted credentials today\n\nOn a Registry API path the auth server checks credentials in this order (as of [issue #871](https://github.com/agentic-community/mcp-gateway-registry/issues/871)):\n\n| # | Credential | Enabled by | `X-Auth-Method` | Notes |\n|---|---|---|---|---|\n| 1 | Session cookie (`mcp_gateway_session=...`) | Always | `oauth2` / IdP-specific | UI browser flow. Short-circuits everything else. |\n| 2 | Federation static token | `FEDERATION_STATIC_TOKEN_AUTH_ENABLED=true` and the request path is `/api/federation/*` or `/api/peers/*` | `federation-static` | Peer-to-peer federation only. Narrow scope. |\n| 3 | Registry static token(s) (`REGISTRY_API_TOKEN` and/or `REGISTRY_API_KEYS`) | `REGISTRY_STATIC_TOKEN_AUTH_ENABLED=true` | `network-trusted` | Single legacy key or multiple per-key scoped keys. See sections below. |\n| 4 | IdP-issued JWT (Okta RS256, Entra, Cognito, Keycloak) | Always | `oauth2` (or IdP-specific) | Full per-user identity with groups from the ID token at login time. |\n| 5 | UI-issued self-signed JWT (HS256) | Always | `self-signed` | Tokens minted by the **Get JWT Token** sidebar button or `POST /api/tokens/generate`. |\n| — | No credential | — | — | 401 returned. |\n\n**Before [issue #871](https://github.com/agentic-community/mcp-gateway-registry/issues/871)**, turning on the registry static token made it the **only** accepted Bearer credential on `/api/*`. IdP and self-signed JWTs were rejected with 401/403 before reaching their validation blocks. After #871, a mismatched or missing bearer on the static-token path **falls through** to the JWT validators instead of terminating. This is what lets mixed-mode deployments (machine callers + per-user callers) share the same registry.\n\n## Static API token (`REGISTRY_API_TOKEN`)\n\nA single shared secret (the \"legacy\" key), validated with `hmac.compare_digest` and mapped to a full-admin identity. This is the simplest setup and is backwards-compatible with all previous releases.\n\n### Configuration\n\n| Variable | Type | Default | Notes |\n|---|---|---|---|\n| `REGISTRY_STATIC_TOKEN_AUTH_ENABLED` | bool | `false` | When `true`, static tokens are accepted on Registry API paths. |\n| `REGISTRY_API_TOKEN` | str | empty | The shared secret. At least one of `REGISTRY_API_TOKEN` or `REGISTRY_API_KEYS` must be set for the flag to take effect. |\n\nIf `REGISTRY_STATIC_TOKEN_AUTH_ENABLED=true` but neither `REGISTRY_API_TOKEN` nor `REGISTRY_API_KEYS` is set, the auth server logs an error and disables the feature at startup.\n\n### Generate a token\n\n```bash\npython3 -c \"import secrets; print(secrets.token_urlsafe(32))\"\n```\n\nTreat the result like a password: rotate periodically, never commit to git, store in a secrets manager for production.\n\n### Deployment\n\n**Docker Compose** — add to your `.env`:\n\n```bash\nREGISTRY_STATIC_TOKEN_AUTH_ENABLED=true\nREGISTRY_API_TOKEN=your-generated-token\n```\n\n**AWS ECS (terraform)** — add to `terraform.tfvars`:\n\n```hcl\nregistry_static_token_auth_enabled = true\nregistry_api_token = \"your-generated-token\"\n```\n\nOr pass via environment variable to avoid committing the value to a file:\n\n```bash\nexport TF_VAR_registry_api_token=\"your-generated-token\"\n```\n\n**Helm** — set `registry.app.registryStaticTokenAuthEnabled=true` and `registry.app.registryApiToken=` in the umbrella chart values.\n\n### Usage\n\n```bash\ncurl -sS -H \"Authorization: Bearer $REGISTRY_API_TOKEN\" \\\n \"$REGISTRY_URL/api/servers\"\n```\n\nVia CLI:\n\n```bash\necho -n \"$REGISTRY_API_TOKEN\" > /tmp/static-token\nuv run python api/registry_management.py \\\n --registry-url \"$REGISTRY_URL\" --token-file /tmp/static-token \\\n list\n```\n\n### Identity granted by the legacy static token\n\nWhen `REGISTRY_API_TOKEN` matches, the auth server returns the legacy admin identity:\n\n```json\n{\n \"valid\": true,\n \"username\": \"network-user\",\n \"client_id\": \"network-trusted\",\n \"method\": \"network-trusted\",\n \"groups\": [\"mcp-registry-admin\"],\n \"scopes\": [\"mcp-registry-admin\", \"mcp-servers-unrestricted/read\", \"mcp-servers-unrestricted/execute\"]\n}\n```\n\nThe `mcp-registry-admin` scope (a UI scope name) ensures the registry resolves this caller as a full admin through the standard permissions path. Anyone holding `REGISTRY_API_TOKEN` is effectively a registry admin. Protect the secret accordingly.\n\n### Where static tokens do NOT work\n\n- **MCP gateway paths** (`//tools/list` etc.) always require IdP auth. Static tokens are ignored there.\n- **Paths outside `/api/*` and `/v0.1/*`** (e.g. health endpoints, audit endpoints behind other prefixes) follow their own rules.\n\n## Multi-key static tokens (`REGISTRY_API_KEYS`)\n\n*Added in [issue #779](https://github.com/agentic-community/mcp-gateway-registry/issues/779).*\n\nMultiple static API keys, each with its own name and groups. Each key's groups flow through the standard `group_mappings` to scopes resolution, so a read-only key gets read-only permissions and an admin key gets admin permissions.\n\n### Configuration\n\n| Variable | Type | Default | Notes |\n|---|---|---|---|\n| `REGISTRY_API_KEYS` | JSON string | empty | Map of named keys. Format below. |\n\n`REGISTRY_API_KEYS` is only consulted when `REGISTRY_STATIC_TOKEN_AUTH_ENABLED=true`. If both `REGISTRY_API_TOKEN` and `REGISTRY_API_KEYS` are set, they are merged: the legacy token becomes an implicit entry named `legacy` with `groups=[\"mcp-registry-admin\"]`.\n\n### Format\n\n```env\nREGISTRY_API_KEYS='{\"monitoring\":{\"key\":\"\",\"groups\":[\"mcp-readonly\"]},\"deploy\":{\"key\":\"\",\"groups\":[\"mcp-registry-admin\"]}}'\n```\n\nRules:\n- **name**: must match `^[a-z0-9][a-z0-9_-]{0,63}$` (log-safe identifier)\n- **key**: minimum 32 characters (use `python3 -c \"import secrets; print(secrets.token_urlsafe(32))\"`)\n- **groups**: non-empty list of group names from your `scopes.yml` / `mcp_scope_default` group_mappings\n- Reserved names: `legacy`, `network-user`, `network-trusted` cannot be used\n- Key values must be unique across all entries\n- On any parse or validation error, the feature is disabled entirely (fail-closed)\n\n### How scopes are resolved\n\nAt startup, the auth server calls `map_groups_to_scopes(entry.groups)` for each entry to resolve groups into scopes using the same pipeline as IdP/JWT auth. The resolved scopes are cached in memory. When an operator imports or modifies group_mappings (e.g., via `registry_management.py import-group`), the registry triggers an auth server scope reload that also rebuilds the static token map, so changes propagate without a restart.\n\n### Identity for multi-key matches\n\nWhen a named key matches, the auth server returns:\n\n```json\n{\n \"valid\": true,\n \"username\": \"monitoring\",\n \"client_id\": \"monitoring\",\n \"method\": \"network-trusted\",\n \"groups\": [\"mcp-readonly\"],\n \"scopes\": [\"mcp-readonly/read\"]\n}\n```\n\nThe key **name** becomes the `username` and `client_id`, which appear in audit logs. This is how operators can answer \"which consumer made this call.\"\n\n### Registry-side authorization\n\nThe registry no longer hard-codes admin access for `network-trusted` callers. Instead, it resolves permissions from the scopes returned by the auth server, just like any other auth method. A key with `groups=[\"mcp-readonly\"]` will NOT be able to delete servers, register agents, or perform other admin actions.\n\n### Example: read-only monitoring key\n\n1. Ensure your `scopes.yml` has a group like `mcp-readonly` mapped to read-only scopes.\n2. Generate a key: `python3 -c \"import secrets; print(secrets.token_urlsafe(32))\"`\n3. Add to your config:\n\n```bash\nREGISTRY_API_KEYS='{\"monitoring\":{\"key\":\"YOUR_GENERATED_KEY\",\"groups\":[\"mcp-readonly\"]}}'\n```\n\n4. Use it:\n\n```bash\ncurl -sS -H \"Authorization: Bearer YOUR_GENERATED_KEY\" \"$REGISTRY_URL/api/servers\"\n```\n\n## Session cookie (browser UI)\n\nWhen a browser user logs in through the UI, the response sets a `mcp_gateway_session=...` cookie. On subsequent calls to `/api/*`, the auth server detects the cookie and short-circuits to session validation — **no static-token check runs**. This is the browser's primary auth path and is unaffected by any of the issues on this page.\n\n## IdP-issued JWT\n\nTokens issued by your configured IdP (`AUTH_PROVIDER=okta|entra|cognito|keycloak|...`) are validated by the provider-specific `validate_token` implementation. Groups are extracted from the token's `groups` claim (or equivalent). These tokens work on `/api/*` **regardless** of whether static-token mode is on, as of #871.\n\n## UI-issued self-signed JWT\n\nThe auth server's sidebar **Get JWT Token** button produces an HS256 JWT signed with the registry's own secret. These tokens carry the user's groups baked in at mint time and are validated by `_validate_self_signed_token`. They work on `/api/*` just like IdP JWTs.\n\n## Coexistence rules\n\nStarting with [#871](https://github.com/agentic-community/mcp-gateway-registry/issues/871), the registry-static-token block is **non-terminal**:\n\n1. If the request has a valid session cookie → session auth wins.\n2. Else if the path is a federation path and the federation static token matches → `federation-static`.\n3. Else if the path is a Registry API path AND static-token mode is on AND the bearer matches any entry in `_STATIC_TOKEN_MAP` (legacy `REGISTRY_API_TOKEN` or any `REGISTRY_API_KEYS` entry) → `network-trusted`.\n4. Else fall through to IdP JWT / self-signed JWT validation.\n5. Else 401.\n\n**Behavior change since #871**: a bearer that matches neither the static token nor any valid JWT now returns **401** from the JWT block, where it previously returned **403 \"Invalid API token\"** from the static-token block. No legitimate caller is broken by this — only one that was already sending an invalid credential.\n\n## Threat model for static tokens\n\n`REGISTRY_API_KEYS` is a sensitive secret. An attacker who obtains the raw JSON value gains access equivalent to the most privileged key in the map. Specifically:\n\n- Any entry whose groups include `mcp-registry-admin` (or any group that maps to admin UI scopes) is equivalent to full admin compromise.\n- Read-only keys limit the blast radius to data exfiltration (listing servers, reading configs) but cannot mutate.\n- Key names appear in audit logs, so a compromised key is identifiable after the fact.\n\nMitigations:\n- Store `REGISTRY_API_KEYS` in a secrets manager (AWS Secrets Manager, Vault, etc.), never in plaintext config files.\n- Terraform variables use `sensitive = true`; Helm renders the value into a Kubernetes Secret.\n- Rotate keys by adding a new key, migrating clients, then removing the old key. Restart the auth server after each config change.\n- Consider using the `existingSecret` Helm pattern to pull from an External Secrets Operator rather than templating the value.\n\n## Roadmap: near-term improvements\n\n### #826 — external user access tokens\n\nTracked at [issue #826](https://github.com/agentic-community/mcp-gateway-registry/issues/826).\n\n**Problem.** An external application (\"Frontend App\") that has its own IdP integration and wants to call the registry API **on behalf of a user** cannot do so today:\n\n- The token was issued for the external app, not the registry, so the `aud`/`cid` claim won't match the registry's own client ID.\n- Okta's org authorization server puts groups in the **ID token**, not the **access token**, so the access token arrives with empty groups.\n- There's no groups-resolution path for external user tokens today (the M2M enrichment via `idp_m2m_clients` is for client-credentials M2M, not user access tokens).\n\nResult: external user tokens get zero scopes and are effectively denied.\n\n**Proposed solutions (two options).**\n\n**Option A — userinfo group enrichment.** After validating the external user's access token's signature against JWKS, call the IdP's `/userinfo` endpoint with that token to retrieve groups. Cache with a short TTL. Requires a new config of **trusted client IDs** (whose tokens are accepted despite audience mismatch).\n\n- Pros: minimal change on the external app side; groups stay fresh; OIDC-standard approach.\n- Cons: runtime dependency on IdP `/userinfo` for every unique token; subject to IdP rate limits on cache miss.\n\n**Option B — token exchange endpoint.** The external app exchanges its ID+access tokens for a **registry-minted self-signed JWT** via a new `POST /oauth2/token-exchange` endpoint. Subsequent API calls use the self-signed token, validated locally with no IdP roundtrip.\n\n- Pros: no runtime IdP dependency; proper `aud: \"mcp-registry\"` on the minted token; delegation visible via `source_client_id` claim.\n- Cons: external app must implement the exchange + token caching; new endpoint is additional attack surface.\n\n**How it composes with #871.** Both options rely on the fall-through behavior #871 introduces — without it, external tokens would be rejected by the static-token block before ever reaching JWT validation (Option A) or `_validate_self_signed_token` (Option B). #871 does not ship either solution; it just makes them possible.\n\n**Status.** Design pending. Solution A is the recommended first cut.\n\n## Common operator tasks\n\n### Enable static-token mode\n\n```bash\n# .env\nREGISTRY_STATIC_TOKEN_AUTH_ENABLED=true\nREGISTRY_API_TOKEN=$(python3 -c \"import secrets; print(secrets.token_urlsafe(32))\")\n\n# then:\ndocker compose restart auth-server registry\n```\n\n### Rotate a static token\n\n**Legacy single-key (`REGISTRY_API_TOKEN`):**\n\n1. Generate a new token with the `secrets.token_urlsafe` command above.\n2. Update `REGISTRY_API_TOKEN` in your deployment config.\n3. Restart the auth server.\n4. Update all clients that use the token (CI/CD pipelines, scripts).\n\n**Multi-key (`REGISTRY_API_KEYS`) zero-downtime rotation:**\n\n1. Add a new entry (e.g. `deploy-v2`) with a fresh key to the JSON map.\n2. Restart the auth server. Both old and new keys now work.\n3. Migrate clients to the new key.\n4. Remove the old entry from the JSON map.\n5. Restart the auth server again.\n\nThis overlap-rotation pattern avoids any window where clients see 401.\n\n### Disable static-token mode\n\nSet `REGISTRY_STATIC_TOKEN_AUTH_ENABLED=false`. Session cookies and IdP JWTs keep working unchanged. Any client relying on the static token will start getting 401.\n\n### Verify the System Config UI\n\nThe current values appear on the **Settings → Authentication** page in the web UI. `REGISTRY_API_TOKEN` is masked. The field registry is defined in [registry/api/config_routes.py:75-76](../registry/api/config_routes.py).\n\n## FAQ\n\nSee the dedicated FAQ page: [Registry API Authentication FAQ](faq/registry-api-auth-faq.md).\n\n## References\n\n- Issue #871: [feat: allow JWT/session auth to coexist with static token auth](https://github.com/agentic-community/mcp-gateway-registry/issues/871)\n- Issue #779: [feat: Support multiple static API keys with per-key group/scope assignments](https://github.com/agentic-community/mcp-gateway-registry/issues/779)\n- Issue #826: [feat: Support External User Access Tokens (Service-to-Service on Behalf of Users)](https://github.com/agentic-community/mcp-gateway-registry/issues/826)\n- Auth server entry point: [`auth_server/server.py`](../auth_server/server.py) — `/validate` endpoint\n- Registry auth handoff: [`registry/auth/dependencies.py`](../registry/auth/dependencies.py) — consumes `X-Auth-Method` header\n- Scope configuration format: [`scopes.md`](scopes.md)\n- General authentication overview: [`auth.md`](auth.md)\n" }, { "path": "docs/registry-auth-architecture.md", "content": "# Registry Authentication Architecture\n\nThis document provides comprehensive technical documentation for the MCP Gateway Registry's authentication and authorization system. While the main [auth.md](./auth.md) covers the overall system architecture, this document focuses specifically on the **registry application's internal authentication mechanisms**, UI-based authentication flows, and technical implementation details.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Authentication Architecture](#authentication-architecture)\n3. [UI Authentication System](#ui-authentication-system)\n4. [Authorization & Permissions](#authorization--permissions)\n5. [Technical Implementation](#technical-implementation)\n6. [Configuration](#configuration)\n7. [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThe MCP Gateway Registry implements an OAuth2-based authentication system that supports:\n\n- **OAuth2/SAML integration** with enterprise identity providers (Cognito, etc.)\n- **Session-based authentication** using secure HTTP cookies\n- **Role-based access control** with groups and scopes\n- **Fine-grained permissions** for server management operations\n\n### Key Features\n\n- **Role-Based Access Control**: Admin, User, and custom roles\n- **Enterprise Integration**: Cognito, SAML, and other IdPs\n- **Secure Session Management**: Encrypted cookies with expiration\n- **Permission-Based UI**: Dynamic UI based on user permissions\n- **Audit Trail**: Comprehensive logging of authentication events\n\n## Authentication Architecture\n\n### High-Level Component Overview\n\n```mermaid\ngraph TB\n subgraph \"Browser\"\n UI[Registry Web UI]\n LoginForm[Login Form]\n end\n \n subgraph \"Registry Application\"\n AuthRoutes[Auth Routes
registry/auth/routes.py]\n AuthDeps[Auth Dependencies
registry/auth/dependencies.py]\n ServerRoutes[Protected API Routes
registry/api/server_routes.py]\n Templates[Jinja2 Templates]\n end\n \n subgraph \"Session Management\"\n Cookies[HTTP Cookies
mcp_gateway_session]\n SessionSigner[URLSafeTimedSerializer]\n Sessions[Session Data Store]\n end\n \n subgraph \"External Systems\"\n AuthServer[Auth Server
:8888]\n Cognito[Amazon Cognito]\n end\n \n UI --> AuthRoutes\n LoginForm --> AuthRoutes\n AuthRoutes --> AuthDeps\n AuthRoutes --> Templates\n ServerRoutes --> AuthDeps\n AuthDeps --> Cookies\n Cookies --> SessionSigner\n SessionSigner --> Sessions\n \n AuthRoutes -.-> AuthServer\n AuthServer -.-> Cognito\n \n classDef browser fill:#e3f2fd,stroke:#1976d2\n classDef registry fill:#f3e5f5,stroke:#7b1fa2\n classDef session fill:#fff3e0,stroke:#f57c00\n classDef external fill:#e8f5e8,stroke:#388e3c\n \n class UI,LoginForm browser\n class AuthRoutes,AuthDeps,ServerRoutes,Templates registry\n class Cookies,SessionSigner,Sessions session\n class AuthServer,Cognito external\n```\n\n### Authentication Flow Architecture\n\n```mermaid\nsequenceDiagram\n participant U as User/Browser\n participant R as Registry App\n participant AS as Auth Server\n participant IdP as Identity Provider\n \n Note over U,IdP: 1. Initial Access (Unauthenticated)\n U->>R: GET / (no session cookie)\n R->>R: Check session cookie\n R->>U: 302 Redirect to /login\n \n Note over U,IdP: 2. Authentication Method Selection\n U->>R: GET /login\n R->>AS: GET /oauth2/providers\n AS->>R: Available OAuth2 providers\n R->>U: Login form with OAuth2 options\n\n Note over U,IdP: 3. OAuth2 Authentication\n U->>R: GET /auth/{provider}\n R->>U: 302 Redirect to Auth Server\n U->>AS: OAuth2 flow initiation\n AS->>IdP: OAuth2 PKCE flow\n IdP->>AS: Auth code + user info\n AS->>AS: Map groups to scopes\n AS->>AS: Create session cookie\n AS->>U: Set mcp_gateway_session cookie\n U->>R: GET /auth/callback\n R->>R: Validate session cookie\n R->>U: 302 Redirect to /\n \n Note over U,IdP: 4. Authenticated Access\n U->>R: GET / (with session cookie)\n R->>R: enhanced_auth() dependency\n R->>R: Decode & validate session\n R->>R: Load user permissions\n R->>U: Filtered dashboard based on permissions\n```\n\n## UI Authentication System\n\n### Login Interface Components\n\nThe registry provides a modern, responsive login interface that dynamically adapts based on available authentication providers.\n\n#### Login Form Structure\n\n```mermaid\ngraph LR\n subgraph \"Login Page (/login)\"\n LoginHeader[Header with Logo]\n ErrorDisplay[Error Message Display]\n\n subgraph \"OAuth2 Providers\"\n CognitoBtn[Amazon Cognito Button]\n SAMLBtn[SAML Provider Button]\n CustomBtn[Custom Provider Button]\n end\n end\n\n LoginHeader --> ErrorDisplay\n ErrorDisplay --> CognitoBtn\n ErrorDisplay --> SAMLBtn\n ErrorDisplay --> CustomBtn\n\n classDef oauth fill:#fff3e0,stroke:#f57c00\n classDef input fill:#f3e5f5,stroke:#7b1fa2\n\n class CognitoBtn,SAMLBtn,CustomBtn oauth\n class LoginHeader,ErrorDisplay input\n```\n\n#### Dynamic Provider Loading\n\nThe login form dynamically loads available OAuth2 providers:\n\n```python\n# registry/auth/routes.py\nasync def get_oauth2_providers():\n \"\"\"Fetch available OAuth2 providers from auth server\"\"\"\n try:\n async with httpx.AsyncClient() as client:\n response = await client.get(f\"{settings.auth_server_url}/oauth2/providers\")\n if response.status_code == 200:\n return response.json().get(\"providers\", [])\n except Exception as e:\n logger.warning(f\"Failed to fetch OAuth2 providers: {e}\")\n return []\n\n@router.get(\"/login\", response_class=HTMLResponse)\nasync def login_form(request: Request, error: str | None = None):\n oauth_providers = await get_oauth2_providers()\n return templates.TemplateResponse(\"login.html\", {\n \"request\": request, \n \"error\": error,\n \"oauth_providers\": oauth_providers\n })\n```\n\n### Dashboard UI with Permission-Based Access\n\nThe main dashboard dynamically renders content based on user permissions:\n\n```mermaid\ngraph TB\n subgraph \"Dashboard Components\"\n Header[Header with User Info]\n Sidebar[Navigation Sidebar]\n MainContent[Main Content Area]\n \n subgraph \"Header Elements\"\n Logo[Registry Logo]\n UserDisplay[Username Display]\n LogoutBtn[Logout Button]\n end\n \n subgraph \"Sidebar Elements\"\n AllServers[All Servers Link]\n UserServers[Accessible Servers]\n AdminTools[Admin Tools]\n HealthStatus[Health Status]\n end\n \n subgraph \"Main Content\"\n ServiceCards[Service Cards Grid]\n SearchBar[Search & Filters]\n ToggleControls[Enable/Disable Toggles]\n EditButtons[Edit Server Buttons]\n end\n end\n \n Header --> Sidebar\n Sidebar --> MainContent\n Header --> Logo\n Header --> UserDisplay \n Header --> LogoutBtn\n Sidebar --> AllServers\n Sidebar --> UserServers\n Sidebar --> AdminTools\n Sidebar --> HealthStatus\n MainContent --> ServiceCards\n MainContent --> SearchBar\n MainContent --> ToggleControls\n MainContent --> EditButtons\n \n classDef header fill:#e8eaf6,stroke:#3f51b5\n classDef sidebar fill:#e0f2f1,stroke:#4caf50\n classDef content fill:#fff3e0,stroke:#ff9800\n classDef controls fill:#fce4ec,stroke:#e91e63\n \n class Header,Logo,UserDisplay,LogoutBtn header\n class Sidebar,AllServers,UserServers,AdminTools,HealthStatus sidebar\n class MainContent,ServiceCards,SearchBar content\n class ToggleControls,EditButtons controls\n```\n\n#### Permission-Based UI Rendering\n\nThe UI dynamically shows/hides elements based on user permissions:\n\n```html\n\n
\n
\n {{ username }}\n {% if user_context.is_admin %}\n Admin\n {% endif %}\n
\n
\n \n
\n
\n\n\n{% for service in services %}\n
\n
\n

{{ service.display_name }}

\n {% if user_context.can_modify_servers %}\n
\n Edit\n
\n {% endif %}\n
\n \n
\n {% if user_context.can_modify_servers %}\n \n
\n \n
\n {% else %}\n \n
\n \n {% if service.is_enabled %}Enabled{% else %}Disabled{% endif %}\n \n
\n {% endif %}\n
\n
\n{% endfor %}\n```\n\n### WebSocket Integration for Real-Time Updates\n\nThe UI includes real-time health status updates via WebSocket:\n\n```javascript\n// Health status WebSocket connection\nconst ws = new WebSocket('ws://localhost:7860/ws/health_status');\n\nws.onmessage = function(event) {\n const healthData = JSON.parse(event.data);\n updateHealthStatusUI(healthData);\n};\n\nfunction updateHealthStatusUI(healthData) {\n for (const [servicePath, status] of Object.entries(healthData)) {\n const card = document.querySelector(`[data-service-path=\"${servicePath}\"]`);\n if (card) {\n const statusElement = card.querySelector('.health-status');\n statusElement.textContent = status.status;\n statusElement.className = `health-status ${status.status}`;\n \n const toolCount = card.querySelector('.tool-count');\n toolCount.textContent = `${status.num_tools} tools`;\n }\n }\n}\n```\n\n## Authorization & Permissions\n\n### Permission Model Overview\n\nThe registry implements a sophisticated role-based access control (RBAC) system:\n\n```mermaid\ngraph TB\n subgraph \"User Identity\"\n User[User Account]\n Groups[User Groups]\n AuthMethod[Auth Method]\n end\n \n subgraph \"Permission Mapping\"\n Scopes[MCP Scopes]\n GroupMapping[Group → Scope Mapping]\n ServerAccess[Server Access List]\n end\n \n subgraph \"Capabilities\"\n ReadAccess[Read Access]\n ModifyAccess[Modify Access]\n AdminAccess[Admin Access]\n ServerSpecific[Server-Specific Access]\n end\n \n User --> Groups\n User --> AuthMethod\n Groups --> GroupMapping\n GroupMapping --> Scopes\n Scopes --> ServerAccess\n \n ServerAccess --> ReadAccess\n ServerAccess --> ModifyAccess\n ServerAccess --> AdminAccess\n ServerAccess --> ServerSpecific\n \n classDef identity fill:#e3f2fd,stroke:#1976d2\n classDef mapping fill:#f3e5f5,stroke:#7b1fa2\n classDef capability fill:#e8f5e8,stroke:#388e3c\n \n class User,Groups,AuthMethod identity\n class Scopes,GroupMapping,ServerAccess mapping\n class ReadAccess,ModifyAccess,AdminAccess,ServerSpecific capability\n```\n\n### Role Definitions\n\n#### 1. Admin Role (`mcp-admin` group)\n- **Full system access**: Can view, modify, create, and delete all servers\n- **User management**: Can view all user sessions and permissions\n- **System configuration**: Can modify global settings\n- **Unrestricted scopes**: `mcp-servers-unrestricted/read`, `mcp-servers-unrestricted/execute`\n\n#### 2. User Role (`mcp-user` group)\n- **Read-only access**: Can view servers and tools they have permission for\n- **No modification rights**: Cannot toggle servers or edit configurations\n- **Filtered view**: Only sees servers they have explicit access to\n- **Restricted scopes**: Based on group mappings\n\n#### 3. Server-Specific Roles (`mcp-server-{name}` groups)\n- **Targeted access**: Access to specific servers based on group name\n- **Execute permissions**: Can use tools from assigned servers\n- **Limited modification**: May have toggle permissions for specific servers\n\n### Scope Configuration System\n\nThe system uses a YAML-based scope configuration (`auth_server/scopes.yml`):\n\n```yaml\n# Example scope configuration\ngroup_mappings:\n mcp-admin:\n - \"mcp-servers-unrestricted/read\"\n - \"mcp-servers-unrestricted/execute\"\n \n mcp-user:\n - \"mcp-servers-restricted/read\"\n \n mcp-server-fininfo:\n - \"mcp-servers-fininfo/read\"\n - \"mcp-servers-fininfo/execute\"\n\n# Scope definitions\nmcp-servers-fininfo/read:\n - server: \"Financial Info Proxy\"\n permissions: [\"read\"]\n\nmcp-servers-fininfo/execute:\n - server: \"Financial Info Proxy\"\n permissions: [\"read\", \"execute\"]\n```\n\n### Permission Checking Logic\n\n```python\n# registry/auth/dependencies.py\ndef enhanced_auth(session: str = None) -> Dict[str, Any]:\n \"\"\"Enhanced authentication with full user context\"\"\"\n session_data = get_user_session_data(session)\n \n username = session_data['username']\n groups = session_data.get('groups', [])\n auth_method = session_data.get('auth_method', 'oauth2')\n\n # Map groups to scopes based on IdP group mappings\n scopes = map_cognito_groups_to_scopes(groups)\n \n # Calculate permissions\n accessible_servers = get_user_accessible_servers(scopes)\n can_modify = user_can_modify_servers(groups, scopes)\n is_admin = 'mcp-admin' in groups\n \n return {\n 'username': username,\n 'groups': groups,\n 'scopes': scopes,\n 'auth_method': auth_method,\n 'accessible_servers': accessible_servers,\n 'can_modify_servers': can_modify,\n 'is_admin': is_admin\n }\n```\n\n### Server Access Filtering\n\n```python\n# registry/services/server_service.py\ndef get_all_servers_with_permissions(self, accessible_servers: Optional[List[str]] = None) -> Dict[str, Dict[str, Any]]:\n \"\"\"Get servers filtered by user permissions\"\"\"\n all_servers = self.get_all_servers()\n \n if accessible_servers is None:\n return all_servers # Admin access\n \n filtered_servers = {}\n for path, server_info in all_servers.items():\n server_name = server_info.get(\"server_name\", \"\")\n if server_name in accessible_servers:\n filtered_servers[path] = server_info\n \n return filtered_servers\n```\n\n## Technical Implementation\n\n### Session Management Deep Dive\n\n#### Session Cookie Structure\n\nThe registry uses `itsdangerous.URLSafeTimedSerializer` for secure session management:\n\n```python\n# registry/auth/dependencies.py\nfrom itsdangerous import URLSafeTimedSerializer\n\nsigner = URLSafeTimedSerializer(settings.secret_key)\n\ndef create_session_cookie(username: str, auth_method: str = \"oauth2\",\n provider: str = \"cognito\") -> str:\n \"\"\"Create a session cookie for a user\"\"\"\n session_data = {\n \"username\": username,\n \"auth_method\": auth_method,\n \"provider\": provider,\n \"created_at\": datetime.utcnow().isoformat(),\n \"groups\": [], # Populated during OAuth2 flow\n \"scopes\": [] # Calculated from groups\n }\n return signer.dumps(session_data)\n```\n\n#### Session Validation Flow\n\n```mermaid\nsequenceDiagram\n participant R as Request\n participant D as Auth Dependency\n participant S as Session Signer\n participant C as Config/Scopes\n \n R->>D: Request with session cookie\n D->>S: Validate cookie signature\n \n alt Valid Cookie\n S->>D: Decoded session data\n D->>D: Check expiration\n D->>C: Load scope mappings\n D->>D: Calculate permissions\n D->>R: User context object\n else Invalid/Expired Cookie\n S->>D: SignatureExpired/BadSignature\n D->>R: HTTP 401 Unauthorized\n end\n```\n\n### Authentication Dependencies Architecture\n\nThe registry uses FastAPI's dependency injection for authentication:\n\n```python\n# registry/auth/dependencies.py\n\ndef get_current_user(session: str = Cookie(alias=\"mcp_gateway_session\")) -> str:\n \"\"\"Basic authentication - returns username only\"\"\"\n # Used for simple authentication checks\n \ndef get_user_session_data(session: str = Cookie(alias=\"mcp_gateway_session\")) -> Dict[str, Any]:\n \"\"\"Full session data extraction\"\"\"\n # Used when you need complete session information\n \ndef enhanced_auth(session: str = Cookie(alias=\"mcp_gateway_session\")) -> Dict[str, Any]:\n \"\"\"Enhanced authentication with permissions and context\"\"\"\n # Used for permission-based access control\n```\n\n### Route Protection Patterns\n\n```python\n# registry/api/server_routes.py\n\n@router.get(\"/\", response_class=HTMLResponse)\nasync def read_root(request: Request, \n user_context: Annotated[dict, Depends(enhanced_auth)]):\n \"\"\"Main dashboard with permission-based filtering\"\"\"\n if user_context['is_admin']:\n all_servers = server_service.get_all_servers()\n else:\n all_servers = server_service.get_all_servers_with_permissions(\n user_context['accessible_servers']\n )\n # Render dashboard...\n\n@router.post(\"/toggle/{service_path:path}\")\nasync def toggle_service_route(service_path: str,\n user_context: Annotated[dict, Depends(enhanced_auth)]):\n \"\"\"Service toggle with permission checking\"\"\"\n if not user_context['can_modify_servers']:\n raise HTTPException(status_code=403, \n detail=\"You do not have permission to modify servers\")\n \n if not user_context['is_admin']:\n if not server_service.user_can_access_server_path(\n service_path, user_context['accessible_servers']):\n raise HTTPException(status_code=403,\n detail=\"You do not have access to this server\")\n # Perform toggle...\n```\n\n### OAuth2 Integration Architecture\n\n```mermaid\ngraph LR\n subgraph \"Registry Components\"\n AuthRoutes[Auth Routes]\n AuthDeps[Auth Dependencies]\n Config[Configuration]\n end\n \n subgraph \"External Auth Server\"\n OAuth2Handler[OAuth2 Handler]\n ProviderManager[Provider Manager]\n TokenValidator[Token Validator]\n end\n \n subgraph \"Identity Providers\"\n Cognito[Amazon Cognito]\n SAML[SAML Provider]\n Custom[Custom OAuth2]\n end\n \n AuthRoutes --> OAuth2Handler\n AuthDeps --> Config\n OAuth2Handler --> ProviderManager\n ProviderManager --> Cognito\n ProviderManager --> SAML\n ProviderManager --> Custom\n TokenValidator --> Cognito\n \n classDef registry fill:#e3f2fd,stroke:#1976d2\n classDef auth fill:#f3e5f5,stroke:#7b1fa2\n classDef provider fill:#e8f5e8,stroke:#388e3c\n \n class AuthRoutes,AuthDeps,Config registry\n class OAuth2Handler,ProviderManager,TokenValidator auth\n class Cognito,SAML,Custom provider\n```\n\n### WebSocket Authentication\n\nThe registry includes real-time features via WebSocket with authentication:\n\n```python\n# registry/health/routes.py\n@router.websocket(\"/ws/health_status\")\nasync def websocket_endpoint(websocket: WebSocket):\n \"\"\"WebSocket endpoint with authentication\"\"\"\n # WebSocket authentication is handled differently\n # since cookies are automatically included in WebSocket handshake\n try:\n await health_service.add_websocket_connection(websocket)\n while True:\n await websocket.receive_text() # Keep alive\n except WebSocketDisconnect:\n await health_service.remove_websocket_connection(websocket)\n```\n\n## Configuration\n\n### Environment Variables\n\nThe registry authentication system requires several configuration parameters:\n\n```bash\n# Core authentication settings\nSECRET_KEY=your-secure-secret-key-here\nSESSION_COOKIE_NAME=mcp_gateway_session\nSESSION_MAX_AGE_SECONDS=28800 # 8 hours\n\n# OAuth2/External auth server integration\nAUTH_SERVER_URL=http://localhost:8888\nAUTH_SERVER_EXTERNAL_URL=http://localhost:8888\n\n# Database/storage paths (auto-configured for container vs local dev)\nCONTAINER_APP_DIR=/app\nCONTAINER_REGISTRY_DIR=/app/registry\nCONTAINER_LOG_DIR=/app/logs\n```\n\n### Development vs Production Configuration\n\n#### Local Development (`settings.is_local_dev = True`)\n```python\n# registry/core/config.py\n@property\ndef is_local_dev(self) -> bool:\n return not Path(\"/app\").exists()\n\n@property\ndef templates_dir(self) -> Path:\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"templates\"\n return self.container_registry_dir / \"templates\"\n```\n\n#### Container/Production (`settings.is_local_dev = False`)\n- Paths point to `/app/registry/` structure\n- Optimized logging and security settings\n- External auth server integration\n\n### Authentication Provider Configuration\n\n#### OAuth2 Provider Setup\n```python\n# External auth server integration\nasync def get_oauth2_providers():\n \"\"\"Fetch available OAuth2 providers from auth server\"\"\"\n try:\n response = await client.get(f\"{settings.auth_server_url}/oauth2/providers\")\n return response.json().get(\"providers\", [])\n except Exception:\n return [] # No providers available\n```\n\n## Troubleshooting\n\n### Common Authentication Issues\n\n#### 1. Session Cookie Problems\n\n**Issue**: User gets redirected to login page repeatedly\n```python\n# Debug session cookie validation\ntry:\n data = signer.loads(session, max_age=settings.session_max_age_seconds)\n logger.info(f\"Session data: {data}\")\nexcept SignatureExpired:\n logger.warning(\"Session expired\")\nexcept BadSignature:\n logger.warning(\"Invalid session signature\")\n```\n\n**Solutions**:\n- Check `SECRET_KEY` consistency across restarts\n- Verify cookie expiration settings\n- Ensure browser accepts cookies from the domain\n\n#### 2. OAuth2 Integration Issues\n\n**Issue**: OAuth2 login fails or redirects incorrectly\n```python\n# Debug OAuth2 callback\n@router.get(\"/auth/callback\")\nasync def oauth2_callback(request: Request, error: str = None):\n if error:\n logger.error(f\"OAuth2 error: {error}\")\n return RedirectResponse(url=f\"/login?error={error}\")\n \n # Check session cookie validity\n session_cookie = request.cookies.get(settings.session_cookie_name)\n logger.info(f\"OAuth2 callback session: {session_cookie[:20]}...\" if session_cookie else \"No session\")\n```\n\n**Solutions**:\n- Verify `AUTH_SERVER_URL` and `AUTH_SERVER_EXTERNAL_URL` settings\n- Check auth server connectivity: `curl http://localhost:8888/oauth2/providers`\n- Ensure redirect URIs match in OAuth2 provider configuration\n\n#### 3. Permission Issues\n\n**Issue**: Users can't access servers they should have permission for\n```python\n# Debug permission calculation\ndef debug_user_permissions(user_context: dict):\n logger.info(f\"User: {user_context['username']}\")\n logger.info(f\"Groups: {user_context['groups']}\")\n logger.info(f\"Scopes: {user_context['scopes']}\")\n logger.info(f\"Accessible servers: {user_context['accessible_servers']}\")\n logger.info(f\"Can modify: {user_context['can_modify_servers']}\")\n```\n\n**Solutions**:\n- Verify group mappings in `auth_server/scopes.yml`\n- Check user group assignments in identity provider\n- Ensure scope configuration matches server names exactly\n\n#### 4. WebSocket Authentication Issues\n\n**Issue**: Real-time updates not working\n```python\n# Debug WebSocket connections\n@router.websocket(\"/ws/health_status\")\nasync def websocket_endpoint(websocket: WebSocket):\n logger.info(f\"WebSocket connection from: {websocket.client}\")\n try:\n await websocket.accept()\n logger.info(\"WebSocket connection accepted\")\n except Exception as e:\n logger.error(f\"WebSocket error: {e}\")\n```\n\n**Solutions**:\n- Check browser console for WebSocket errors\n- Verify WebSocket URL scheme (ws:// vs wss://)\n- Ensure firewall/proxy allows WebSocket connections\n\n### Logging and Debugging\n\n#### Enable Debug Logging\n```python\n# registry/main.py\nlogging.basicConfig(level=logging.DEBUG)\nlogger = logging.getLogger(__name__)\n```\n\n#### Authentication Event Logging\n```python\n# Custom auth logging\ndef log_auth_event(event_type: str, username: str = None, details: dict = None):\n logger.info(f\"AUTH_EVENT: {event_type}\", extra={\n 'username': username,\n 'event_type': event_type,\n 'details': details,\n 'timestamp': datetime.utcnow().isoformat()\n })\n\n# Usage examples\nlog_auth_event('LOGIN_SUCCESS', username='admin')\nlog_auth_event('PERMISSION_DENIED', username='user', details={'resource': '/toggle/fininfo'})\nlog_auth_event('SESSION_EXPIRED', username='user')\n```\n\n#### Health Check for Auth Components\n```python\n@app.get(\"/health/auth\")\nasync def auth_health_check():\n \"\"\"Health check for authentication components\"\"\"\n health_status = {\n \"session_signer\": \"ok\",\n \"auth_server\": \"unknown\",\n \"oauth2_providers\": []\n }\n \n # Test auth server connectivity\n try:\n async with httpx.AsyncClient(timeout=5.0) as client:\n response = await client.get(f\"{settings.auth_server_url}/health\")\n if response.status_code == 200:\n health_status[\"auth_server\"] = \"ok\"\n \n # Test OAuth2 providers\n providers_response = await client.get(f\"{settings.auth_server_url}/oauth2/providers\")\n if providers_response.status_code == 200:\n health_status[\"oauth2_providers\"] = providers_response.json().get(\"providers\", [])\n except Exception as e:\n health_status[\"auth_server\"] = f\"error: {e}\"\n \n return health_status\n```\n\nThis comprehensive authentication architecture ensures secure, scalable, and maintainable access control for the MCP Gateway Registry while providing flexibility for both local development and enterprise deployments. " }, { "path": "docs/registry-auth-detailed.md", "content": "# Registry Authentication & Authorization - Technical Deep Dive\n\nThis document provides comprehensive technical documentation for the MCP Gateway Registry's internal authentication and authorization system, focusing on the UI-based authentication flows and technical implementation details.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Authentication Architecture](#authentication-architecture)\n3. [UI Authentication System](#ui-authentication-system)\n4. [Authorization & Permissions](#authorization--permissions)\n5. [Technical Implementation](#technical-implementation)\n6. [Configuration](#configuration)\n7. [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThe MCP Gateway Registry implements an OAuth2-based authentication system designed for enterprise environments:\n\n### Core Authentication Methods\n\n- **OAuth2 Integration**: Enterprise IdP integration (Amazon Cognito, SAML, etc.)\n- **Session Management**: Secure HTTP cookies with digital signatures\n- **Role-Based Access Control**: Dynamic permissions based on user groups\n\n### Key Features\n\n- **RBAC System**: Fine-grained role-based access control\n- **IdP Integration**: Integration with Cognito and SAML providers\n- **Secure Sessions**: Encrypted, signed session cookies\n- **Dynamic UI**: Permission-based interface rendering\n- **Audit Logging**: Comprehensive authentication event tracking\n\n## Authentication Architecture\n\n### System Component Overview\n\nThe registry authentication system consists of several interconnected components:\n\n```mermaid\ngraph TB\n subgraph \"Browser Layer\"\n UI[Registry Web UI]\n LoginForm[Login Interface]\n Dashboard[Dashboard UI]\n end\n \n subgraph \"Registry Application\"\n AuthRoutes[Auth Routes
registry/auth/routes.py]\n AuthDeps[Auth Dependencies
registry/auth/dependencies.py]\n ServerRoutes[Protected API Routes
registry/api/server_routes.py]\n Templates[Jinja2 Templates
registry/templates/]\n end\n \n subgraph \"Session Management\"\n Cookies[HTTP Session Cookies
mcp_gateway_session]\n SessionSigner[URLSafeTimedSerializer
itsdangerous]\n SessionStore[Session Data Store]\n end\n \n subgraph \"External Auth Systems\"\n AuthServer[Auth Server
localhost:8888]\n Cognito[Amazon Cognito]\n end\n \n UI --> AuthRoutes\n LoginForm --> AuthRoutes\n Dashboard --> ServerRoutes\n AuthRoutes --> AuthDeps\n ServerRoutes --> AuthDeps\n AuthRoutes --> Templates\n AuthDeps --> Cookies\n Cookies --> SessionSigner\n SessionSigner --> SessionStore\n \n AuthRoutes -.-> AuthServer\n AuthServer -.-> Cognito\n \n classDef browser fill:#e3f2fd,stroke:#1976d2,stroke-width:2px\n classDef registry fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n classDef session fill:#fff3e0,stroke:#f57c00,stroke-width:2px\n classDef external fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n \n class UI,LoginForm,Dashboard browser\n class AuthRoutes,AuthDeps,ServerRoutes,Templates registry\n class Cookies,SessionSigner,SessionStore session\n class AuthServer,Cognito external\n```\n\n### Authentication Flow Architecture\n\n```mermaid\nsequenceDiagram\n participant U as User Browser\n participant R as Registry App\n participant AS as Auth Server\n participant IdP as Identity Provider\n \n Note over U,IdP: Phase 1: Initial Access (Unauthenticated)\n U->>R: GET / (no session cookie)\n R->>R: enhanced_auth() dependency check\n R->>U: 302 Redirect to /login\n \n Note over U,IdP: Phase 2: Authentication Method Selection\n U->>R: GET /login\n R->>AS: GET /oauth2/providers (fetch available providers)\n AS-->>R: List of OAuth2 providers\n R->>R: Render login form with OAuth2 options\n R->>U: Login page with OAuth2 options\n\n Note over U,IdP: Phase 3: OAuth2 Authentication Flow\n U->>R: GET /auth/{provider}\n R->>U: 302 Redirect to external auth server\n U->>AS: OAuth2 PKCE flow initiation\n AS->>IdP: OAuth2 authorization request\n IdP->>AS: Authorization code + user info\n AS->>AS: Exchange code for tokens\n AS->>AS: Map Cognito groups to MCP scopes\n AS->>AS: Create compatible session cookie\n AS->>U: Set-Cookie mcp_gateway_session\n U->>R: GET /auth/callback\n R->>R: Validate existing session cookie\n R->>U: 302 Redirect to / (authenticated)\n \n Note over U,IdP: Phase 4: Authenticated Dashboard Access\n U->>R: GET / (with valid session cookie)\n R->>R: enhanced_auth() extracts & validates session\n R->>R: Calculate user permissions & accessible servers\n R->>R: Filter server list based on permissions\n R->>U: Rendered dashboard with permission-based UI\n```\n\n### Core Authentication Components\n\n#### 1. Authentication Routes (`registry/auth/routes.py`)\n\n**Purpose**: Handles all authentication-related HTTP endpoints\n\n**Key Endpoints**:\n- `GET /login` - Login form with dynamic OAuth2 provider loading\n- `GET /auth/{provider}` - OAuth2 provider redirect\n- `GET /auth/callback` - OAuth2 callback handling\n- `GET|POST /logout` - Session termination\n\n#### 2. Authentication Dependencies (`registry/auth/dependencies.py`)\n\n**Purpose**: FastAPI dependency injection for authentication and authorization\n\n**Key Functions**:\n- `get_current_user()` - Basic user identification\n- `get_user_session_data()` - Full session data extraction\n- `enhanced_auth()` - Complete user context with permissions\n- `map_cognito_groups_to_scopes()` - Group-to-permission mapping\n\n#### 3. Session Management System\n\n**Purpose**: Secure session cookie creation, validation, and management\n\n**Components**:\n- `URLSafeTimedSerializer` from `itsdangerous` library\n- Session cookie with configurable expiration\n- Automatic session validation on all protected routes\n- Cross-authentication-method compatibility\n\n### Authentication Decision Tree\n\n```mermaid\nflowchart TD\n Start([HTTP Request]) --> HasSession{Has Valid
Session Cookie?}\n \n HasSession -->|Yes| ValidateSession[Validate Session
Signature & Expiration]\n HasSession -->|No| RedirectLogin[Redirect to /login]\n \n ValidateSession --> SessionValid{Session
Valid?}\n SessionValid -->|Yes| ExtractUserContext[Extract User Context
Groups, Scopes, Permissions]\n SessionValid -->|No| RedirectLogin\n \n RedirectLogin --> LoginPage[Display Login Page
with Available Providers]\n\n LoginPage --> OAuth2Auth[Redirect to
External Provider]\n\n OAuth2Auth --> ExternalProvider[External OAuth2 Flow
User Authentication]\n ExternalProvider --> OAuth2Callback[OAuth2 Callback
with User Info]\n OAuth2Callback --> CreateOAuth2Session[Create Session Cookie
with Mapped Permissions]\n\n CreateOAuth2Session --> SetSessionCookie[Set HTTP Cookie
mcp_gateway_session]\n \n SetSessionCookie --> RedirectDashboard[Redirect to Dashboard]\n RedirectDashboard --> ExtractUserContext\n \n ExtractUserContext --> RenderUI[Render Permission-Based UI]\n \n classDef startEnd fill:#e8f5e8,stroke:#4caf50,stroke-width:2px\n classDef decision fill:#fff3e0,stroke:#ff9800,stroke-width:2px\n classDef process fill:#e3f2fd,stroke:#2196f3,stroke-width:2px\n classDef error fill:#ffebee,stroke:#f44336,stroke-width:2px\n\n class Start,RenderUI startEnd\n class HasSession,SessionValid decision\n class ValidateSession,ExtractUserContext,LoginPage,OAuth2Auth,ExternalProvider,OAuth2Callback,CreateOAuth2Session,SetSessionCookie,RedirectDashboard process\n class RedirectLogin error\n```\n\n## UI Authentication System\n\n### Login Interface Architecture\n\nThe registry provides a modern, responsive login interface that dynamically adapts based on available authentication providers.\n\n```mermaid\ngraph LR\n subgraph \"Login Page (/login)\"\n LoginHeader[Header with Logo & Branding]\n ErrorDisplay[Error Message Display]\n\n subgraph \"OAuth2 Provider Buttons\"\n ProviderButtons[Dynamic Provider Buttons]\n CognitoBtn[Amazon Cognito Button]\n SAMLBtn[SAML Provider Button]\n CustomBtn[Custom OAuth2 Button]\n end\n end\n\n LoginHeader --> ErrorDisplay\n ErrorDisplay --> ProviderButtons\n ProviderButtons --> CognitoBtn\n ProviderButtons --> SAMLBtn\n ProviderButtons --> CustomBtn\n\n classDef header fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px\n classDef oauth fill:#fff3e0,stroke:#f57c00,stroke-width:2px\n\n class LoginHeader,ErrorDisplay header\n class ProviderButtons,CognitoBtn,SAMLBtn,CustomBtn oauth\n```\n\n#### Dynamic Provider Loading Implementation\n\nThe login form dynamically loads available OAuth2 providers from the auth server:\n\n```python\n# registry/auth/routes.py\nasync def get_oauth2_providers():\n \"\"\"Fetch available OAuth2 providers from auth server\"\"\"\n try:\n async with httpx.AsyncClient() as client:\n response = await client.get(\n f\"{settings.auth_server_url}/oauth2/providers\", \n timeout=5.0\n )\n if response.status_code == 200:\n data = response.json()\n return data.get(\"providers\", [])\n except Exception as e:\n logger.warning(f\"Failed to fetch OAuth2 providers: {e}\")\n return []\n\n@router.get(\"/login\", response_class=HTMLResponse)\nasync def login_form(request: Request, error: str | None = None):\n \"\"\"Show login form with OAuth2 providers\"\"\"\n oauth_providers = await get_oauth2_providers()\n return templates.TemplateResponse(\"login.html\", {\n \"request\": request, \n \"error\": error,\n \"oauth_providers\": oauth_providers\n })\n```\n\n#### Login Template Structure\n\n```html\n\n
\n
\n \"MCP\n

MCP Gateway Registry

\n
\n\n {% if error %}\n
{{ error }}
\n {% endif %}\n\n \n {% if oauth_providers %}\n
\n

Login with:

\n {% for provider in oauth_providers %}\n \n {% if provider.icon %}\n \"{{\n {% endif %}\n Login with {{ provider.display_name }}\n \n {% endfor %}\n
\n {% endif %}\n
\n```\n\n### Dashboard UI with Permission-Based Rendering\n\nThe main dashboard dynamically renders content based on user permissions and accessible servers:\n\n```mermaid\ngraph TB\n subgraph \"Dashboard Layout\"\n HeaderSection[Header Section]\n MainContainer[Main Container]\n \n subgraph \"Header Components\"\n Logo[Registry Logo]\n UserInfo[User Information Display]\n LogoutControls[Logout Controls]\n end\n \n subgraph \"Main Content Area\"\n Sidebar[Navigation Sidebar]\n ContentArea[Primary Content Area]\n end\n \n subgraph \"Sidebar Elements\"\n ServerList[Server Navigation]\n AdminTools[Admin Tools Panel]\n HealthStatus[Health Status Display]\n end\n \n subgraph \"Content Elements\"\n ServiceGrid[Service Cards Grid]\n SearchFilters[Search & Filter Controls]\n ManagementControls[Management Actions]\n end\n \n subgraph \"Permission-Based Elements\"\n ToggleSwitches[Enable/Disable Toggles]\n EditButtons[Edit Server Buttons]\n CreateButtons[Create New Server]\n AdminPanels[Admin-Only Panels]\n end\n end\n \n HeaderSection --> Logo\n HeaderSection --> UserInfo\n HeaderSection --> LogoutControls\n MainContainer --> Sidebar\n MainContainer --> ContentArea\n Sidebar --> ServerList\n Sidebar --> AdminTools\n Sidebar --> HealthStatus\n ContentArea --> ServiceGrid\n ContentArea --> SearchFilters\n ContentArea --> ManagementControls\n ManagementControls --> ToggleSwitches\n ManagementControls --> EditButtons\n ManagementControls --> CreateButtons\n ManagementControls --> AdminPanels\n \n classDef header fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px\n classDef sidebar fill:#e0f2f1,stroke:#4caf50,stroke-width:2px\n classDef content fill:#fff3e0,stroke:#ff9800,stroke-width:2px\n classDef permissions fill:#fce4ec,stroke:#e91e63,stroke-width:2px\n \n class HeaderSection,Logo,UserInfo,LogoutControls header\n class Sidebar,ServerList,AdminTools,HealthStatus sidebar\n class ContentArea,ServiceGrid,SearchFilters,ManagementControls content\n class ToggleSwitches,EditButtons,CreateButtons,AdminPanels permissions\n```\n\n#### Permission-Based UI Rendering\n\nThe UI template conditionally renders elements based on user permissions:\n\n```html\n\n
\n
\n \"MCP\n Registry\n
\n \n
\n
\n {{ username }}\n {% if user_context.is_admin %}\n Administrator\n {% elif user_context.groups %}\n {{ user_context.groups|join(', ') }}\n {% endif %}\n
\n
\n \n
\n
\n
\n\n\n
\n {% for service in services %}\n
\n
\n

{{ service.display_name }}

\n {% if user_context.can_modify_servers %}\n
\n \n Edit Configuration\n \n
\n {% endif %}\n
\n \n
\n

{{ service.description or \"No description available.\" }}

\n \n
\n {% for tag in service.tags %}\n {{ tag }}\n {% endfor %}\n
\n \n
\n {{ service.num_tools }} tools\n \n {{ service.health_status }}\n \n {% if service.last_checked_iso %}\n \n Last checked: {{ service.last_checked_iso }}\n \n {% endif %}\n
\n
\n \n
\n {% if user_context.can_modify_servers %}\n \n
\n \n \n {% if service.is_enabled %}Enabled{% else %}Disabled{% endif %}\n \n
\n {% else %}\n \n
\n \n ●\n \n \n {% if service.is_enabled %}Enabled{% else %}Disabled{% endif %}\n \n
\n {% endif %}\n
\n
\n {% endfor %}\n
\n\n\n{% if user_context.can_modify_servers %}\n
\n \n
\n{% endif %}\n```\n\n### Real-Time WebSocket Integration\n\nThe UI includes real-time health status updates via WebSocket connections:\n\n```mermaid\nsequenceDiagram\n participant UI as Dashboard UI\n participant WS as WebSocket Connection\n participant HMS as Health Monitoring Service\n participant SS as Server Service\n \n Note over UI,SS: WebSocket Initialization\n UI->>WS: Connect to /ws/health_status\n WS->>HMS: Register new connection\n HMS->>UI: Send initial health status data\n \n Note over UI,SS: Real-Time Health Updates\n loop Background Health Checks\n HMS->>SS: Check server health status\n SS-->>HMS: Updated health data\n HMS->>HMS: Compare with previous status\n \n alt Status Changed\n HMS->>WS: Broadcast health update\n WS->>UI: Send updated status\n UI->>UI: Update service card UI\n end\n end\n \n Note over UI,SS: User-Triggered Actions\n UI->>SS: Toggle server state\n SS->>HMS: Immediate health check\n HMS->>WS: Broadcast status update\n WS->>UI: Real-time status update\n UI->>UI: Update toggle switch & status\n```\n\n#### WebSocket Client Implementation\n\n```javascript\n// Real-time health status WebSocket connection\nclass HealthStatusManager {\n constructor() {\n this.ws = null;\n this.reconnectInterval = 5000;\n this.maxReconnectAttempts = 10;\n this.reconnectAttempts = 0;\n }\n \n connect() {\n const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';\n const wsUrl = `${protocol}//${window.location.host}/ws/health_status`;\n \n this.ws = new WebSocket(wsUrl);\n \n this.ws.onopen = () => {\n console.log('Health status WebSocket connected');\n this.reconnectAttempts = 0;\n };\n \n this.ws.onmessage = (event) => {\n try {\n const healthData = JSON.parse(event.data);\n this.updateHealthStatusUI(healthData);\n } catch (error) {\n console.error('Error parsing health status data:', error);\n }\n };\n \n this.ws.onclose = () => {\n console.log('Health status WebSocket disconnected');\n this.attemptReconnect();\n };\n \n this.ws.onerror = (error) => {\n console.error('WebSocket error:', error);\n };\n }\n \n updateHealthStatusUI(healthData) {\n for (const [servicePath, status] of Object.entries(healthData)) {\n const serviceCard = document.querySelector(`[data-service-path=\"${servicePath}\"]`);\n if (serviceCard) {\n // Update health status indicator\n const statusElement = serviceCard.querySelector('.health-status');\n if (statusElement) {\n statusElement.textContent = status.status;\n statusElement.className = `health-status ${status.status.replace(/[^a-zA-Z0-9]/g, '-')}`;\n }\n \n // Update tool count\n const toolCountElement = serviceCard.querySelector('.tool-count');\n if (toolCountElement) {\n toolCountElement.textContent = `${status.num_tools} tools`;\n }\n \n // Update timestamp\n const timestampElement = serviceCard.querySelector('.timestamp');\n if (timestampElement && status.last_checked_iso) {\n timestampElement.textContent = `Last checked: ${status.last_checked_iso}`;\n }\n }\n }\n }\n \n attemptReconnect() {\n if (this.reconnectAttempts < this.maxReconnectAttempts) {\n this.reconnectAttempts++;\n console.log(`Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})...`);\n setTimeout(() => this.connect(), this.reconnectInterval);\n } else {\n console.error('Max reconnection attempts reached');\n }\n }\n}\n\n// Initialize WebSocket connection when page loads\ndocument.addEventListener('DOMContentLoaded', () => {\n const healthManager = new HealthStatusManager();\n healthManager.connect();\n});\n```\n\n### Server Management UI Workflows\n\n#### Service Toggle Workflow\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant UI as Dashboard UI\n participant R as Registry Backend\n participant HMS as Health Monitoring\n participant WS as WebSocket\n \n U->>UI: Click toggle switch\n UI->>UI: Disable toggle (show loading)\n UI->>R: POST /toggle/{service_path}\n \n R->>R: Check user permissions\n alt Insufficient Permissions\n R->>UI: 403 Forbidden\n UI->>UI: Show error message\n UI->>UI: Revert toggle state\n else Sufficient Permissions\n R->>R: Update service state\n R->>HMS: Trigger immediate health check\n HMS->>HMS: Perform health check\n R->>UI: 200 OK with new state\n UI->>UI: Update toggle state\n \n HMS->>WS: Broadcast health update\n WS->>UI: Real-time status update\n UI->>UI: Update status indicators\n end\n```\n\n#### Server Creation Workflow (Admin Only)\n\n```mermaid\nflowchart TD\n Start([User clicks \"Add Server\"]) --> CheckPerms{User has
modify permissions?}\n \n CheckPerms -->|No| ShowError[Show permission error]\n CheckPerms -->|Yes| ShowForm[Display server creation form]\n \n ShowForm --> UserFillsForm[User fills server details]\n UserFillsForm --> ValidateForm{Form validation
passes?}\n \n ValidateForm -->|No| ShowValidationErrors[Show validation errors]\n ValidateForm -->|Yes| SubmitForm[Submit form to backend]\n \n SubmitForm --> BackendValidation[Backend validates data]\n BackendValidation --> ServerExists{Server path
already exists?}\n \n ServerExists -->|Yes| ShowConflictError[Show conflict error]\n ServerExists -->|No| CreateServer[Create server entry]\n \n CreateServer --> UpdateFAISS[Update FAISS index]\n UpdateFAISS --> UpdateNginx[Regenerate Nginx config]\n UpdateNginx --> BroadcastUpdate[Broadcast health update]\n BroadcastUpdate --> Success[Redirect to dashboard]\n \n ShowError --> End([End])\n ShowValidationErrors --> ShowForm\n ShowConflictError --> ShowForm\n Success --> End\n \n classDef success fill:#e8f5e8,stroke:#4caf50,stroke-width:2px\n classDef error fill:#ffebee,stroke:#f44336,stroke-width:2px\n classDef process fill:#e3f2fd,stroke:#2196f3,stroke-width:2px\n classDef decision fill:#fff3e0,stroke:#ff9800,stroke-width:2px\n \n class Success success\n class ShowError,ShowValidationErrors,ShowConflictError error\n class ShowForm,UserFillsForm,SubmitForm,BackendValidation,CreateServer,UpdateFAISS,UpdateNginx,BroadcastUpdate process\n class CheckPerms,ValidateForm,ServerExists decision\n```\n\n## Authorization & Permissions\n\n### Permission Model Overview\n\nThe registry implements a sophisticated role-based access control (RBAC) system with multiple layers of authorization:\n\n```mermaid\ngraph TB\n subgraph \"User Identity Layer\"\n User[User Account]\n Groups[User Groups
from IdP]\n AuthMethod[Authentication Method]\n end\n \n subgraph \"Permission Mapping Layer\"\n ScopeMapping[Group → Scope Mapping
auth_server/scopes.yml]\n Scopes[MCP Scopes]\n ServerAccess[Accessible Server List]\n end\n \n subgraph \"Capability Layer\"\n ReadAccess[Read Access
View servers & tools]\n ModifyAccess[Modify Access
Toggle, edit servers]\n AdminAccess[Admin Access
Full system control]\n ServerSpecific[Server-Specific Access
Fine-grained permissions]\n end\n \n subgraph \"UI Rendering Layer\"\n AdminUI[Admin Interface Elements]\n ModifyUI[Modification Controls]\n ReadOnlyUI[Read-Only Displays]\n FilteredContent[Filtered Server Lists]\n end\n \n User --> Groups\n User --> AuthMethod\n Groups --> ScopeMapping\n ScopeMapping --> Scopes\n Scopes --> ServerAccess\n \n ServerAccess --> ReadAccess\n ServerAccess --> ModifyAccess\n ServerAccess --> AdminAccess\n ServerAccess --> ServerSpecific\n \n ReadAccess --> FilteredContent\n ModifyAccess --> ModifyUI\n AdminAccess --> AdminUI\n ServerSpecific --> FilteredContent\n \n classDef identity fill:#e3f2fd,stroke:#1976d2,stroke-width:2px\n classDef mapping fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n classDef capability fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n classDef ui fill:#fff3e0,stroke:#f57c00,stroke-width:2px\n \n class User,Groups,AuthMethod identity\n class ScopeMapping,Scopes,ServerAccess mapping\n class ReadAccess,ModifyAccess,AdminAccess,ServerSpecific capability\n class AdminUI,ModifyUI,ReadOnlyUI,FilteredContent ui\n```\n\n### Role Definitions & Capabilities\n\n#### 1. Administrator Role (`mcp-admin` group)\n\n**Full System Access**:\n- View, create, edit, and delete all servers\n- Access to all MCP tools regardless of server\n- System configuration and user management\n- Complete audit trail visibility\n\n**Granted Scopes**:\n- `mcp-servers-unrestricted/read`\n- `mcp-servers-unrestricted/execute`\n\n**UI Capabilities**:\n- All server cards visible and interactive\n- Edit buttons on all servers\n- \"Add New Server\" functionality\n- Toggle switches on all services\n- Admin-only configuration panels\n\n#### 2. Regular User Role (`mcp-user` group)\n\n**Limited Read Access**:\n- View only servers explicitly assigned to user\n- Read-only access to server information\n- Cannot modify server configurations\n- Cannot toggle server states\n\n**Granted Scopes**:\n- `mcp-servers-restricted/read` (limited scope)\n\n**UI Capabilities**:\n- Filtered server list (only accessible servers)\n- Read-only status indicators instead of toggles\n- No edit buttons or admin controls\n- Basic server information display\n\n#### 3. Server-Specific Roles (`mcp-server-{name}` groups)\n\n**Targeted Access**:\n- Access to specific servers based on group name\n- Execute permissions for assigned servers\n- May include toggle permissions for specific services\n\n**Example Scopes**:\n- `mcp-servers-fininfo/read` + `mcp-servers-fininfo/execute`\n- `mcp-servers-currenttime/read` + `mcp-servers-currenttime/execute`\n\n**UI Capabilities**:\n- Filtered view showing only assigned servers\n- Toggle functionality for assigned servers\n- Edit access may be granted for specific servers\n\n### Scope Configuration System\n\nThe authorization system uses a YAML-based configuration file (`auth_server/scopes.yml`) to map groups to permissions:\n\n```yaml\n# Group to scope mappings\ngroup_mappings:\n # Administrator - full access\n mcp-admin:\n - \"mcp-servers-unrestricted/read\"\n - \"mcp-servers-unrestricted/execute\"\n \n # Regular user - restricted read-only access\n mcp-user:\n - \"mcp-servers-restricted/read\"\n \n # Server-specific access groups\n mcp-server-fininfo:\n - \"mcp-servers-fininfo/read\"\n - \"mcp-servers-fininfo/execute\"\n \n mcp-server-currenttime:\n - \"mcp-servers-currenttime/read\"\n - \"mcp-servers-currenttime/execute\"\n\n# Scope definitions with server mappings\nmcp-servers-fininfo/read:\n - server: \"Financial Info Proxy\"\n permissions: [\"read\"]\n\nmcp-servers-fininfo/execute:\n - server: \"Financial Info Proxy\"\n permissions: [\"read\", \"execute\"]\n\nmcp-servers-currenttime/read:\n - server: \"Current Time API\"\n permissions: [\"read\"]\n\nmcp-servers-currenttime/execute:\n - server: \"Current Time API\"\n permissions: [\"read\", \"execute\"]\n\n# Unrestricted scopes (for admins)\nmcp-servers-unrestricted/read:\n # Grants access to all servers\n \nmcp-servers-unrestricted/execute:\n # Grants execute access to all servers\n```\n\n### Permission Checking Implementation\n\n#### Enhanced Authentication Dependency\n\n```python\n# registry/auth/dependencies.py\ndef enhanced_auth(session: str = Cookie(alias=\"mcp_gateway_session\")) -> Dict[str, Any]:\n \"\"\"Enhanced authentication dependency with full permission context\"\"\"\n session_data = get_user_session_data(session)\n \n username = session_data['username']\n groups = session_data.get('groups', [])\n auth_method = session_data.get('auth_method', 'oauth2')\n\n logger.info(f\"Enhanced auth for {username}: groups={groups}, auth_method={auth_method}\")\n\n # Map groups to scopes based on Cognito/IdP group mappings\n scopes = map_cognito_groups_to_scopes(groups)\n logger.info(f\"User {username} mapped to scopes: {scopes}\")\n \n # Calculate accessible servers from scopes\n accessible_servers = get_user_accessible_servers(scopes)\n \n # Determine modification permissions\n can_modify = user_can_modify_servers(groups, scopes)\n \n # Check for admin privileges\n is_admin = 'mcp-admin' in groups\n \n user_context = {\n 'username': username,\n 'groups': groups,\n 'scopes': scopes,\n 'auth_method': auth_method,\n 'provider': session_data.get('provider', 'oauth2'),\n 'accessible_servers': accessible_servers,\n 'can_modify_servers': can_modify,\n 'is_admin': is_admin\n }\n \n logger.debug(f\"Final user context for {username}: {user_context}\")\n return user_context\n```\n\n#### Group to Scope Mapping\n\n```python\n# registry/auth/dependencies.py\ndef map_cognito_groups_to_scopes(groups: List[str]) -> List[str]:\n \"\"\"Map Cognito groups to MCP scopes using scopes.yml configuration\"\"\"\n scopes = []\n group_mappings = SCOPES_CONFIG.get('group_mappings', {})\n \n for group in groups:\n if group in group_mappings:\n group_scopes = group_mappings[group]\n scopes.extend(group_scopes)\n logger.debug(f\"Mapped group '{group}' to scopes: {group_scopes}\")\n else:\n logger.debug(f\"No scope mapping found for group: {group}\")\n \n # Remove duplicates while preserving order\n unique_scopes = list(dict.fromkeys(scopes))\n logger.info(f\"Final mapped scopes: {unique_scopes}\")\n return unique_scopes\n\ndef get_user_accessible_servers(user_scopes: List[str]) -> List[str]:\n \"\"\"Get list of all servers the user has access to based on their scopes\"\"\"\n accessible_servers = set()\n \n for scope in user_scopes:\n # Check for unrestricted access\n if scope in ['mcp-servers-unrestricted/read', 'mcp-servers-unrestricted/execute']:\n return ['*'] # Special marker for all servers\n \n # Get servers for specific scopes\n server_names = get_servers_for_scope(scope)\n accessible_servers.update(server_names)\n \n return list(accessible_servers)\n\ndef user_can_modify_servers(user_groups: List[str], user_scopes: List[str]) -> bool:\n \"\"\"Check if user can modify servers (toggle, edit)\"\"\"\n # Admin users can always modify\n if 'mcp-admin' in user_groups:\n return True\n \n # Users with unrestricted execute access can modify\n if 'mcp-servers-unrestricted/execute' in user_scopes:\n return True\n \n # Check for any execute permissions\n execute_scopes = [scope for scope in user_scopes if '/execute' in scope]\n return len(execute_scopes) > 0\n```\n\n### Server Access Filtering\n\n#### Permission-Based Server Filtering\n\n```python\n# registry/services/server_service.py\ndef get_all_servers_with_permissions(self, accessible_servers: Optional[List[str]] = None) -> Dict[str, Dict[str, Any]]:\n \"\"\"Get servers filtered by user permissions\"\"\"\n all_servers = self.get_all_servers()\n \n # Admin users or users with unrestricted access see all servers\n if accessible_servers is None or '*' in accessible_servers:\n logger.info(\"User has unrestricted server access\")\n return all_servers\n \n # Filter servers based on accessible server names\n filtered_servers = {}\n for path, server_info in all_servers.items():\n server_name = server_info.get(\"server_name\", \"\")\n if server_name in accessible_servers:\n filtered_servers[path] = server_info\n logger.debug(f\"Server '{server_name}' accessible to user\")\n else:\n logger.debug(f\"Server '{server_name}' filtered out for user\")\n \n logger.info(f\"Filtered server list: {len(filtered_servers)} of {len(all_servers)} servers accessible\")\n return filtered_servers\n\ndef user_can_access_server_path(self, path: str, accessible_servers: List[str]) -> bool:\n \"\"\"Check if user can access a specific server path\"\"\"\n if '*' in accessible_servers:\n return True # Unrestricted access\n \n server_info = self.get_server_info(path)\n if not server_info:\n return False\n \n server_name = server_info.get(\"server_name\", \"\")\n return server_name in accessible_servers\n```\n\n### Route-Level Permission Enforcement\n\n#### Protected Route Examples\n\n```python\n# registry/api/server_routes.py\n\n@router.get(\"/\", response_class=HTMLResponse)\nasync def read_root(request: Request, \n user_context: Annotated[dict, Depends(enhanced_auth)]):\n \"\"\"Main dashboard with permission-based server filtering\"\"\"\n # Filter servers based on user permissions\n if user_context['is_admin']:\n all_servers = server_service.get_all_servers()\n logger.info(f\"Admin user accessing all {len(all_servers)} servers\")\n else:\n all_servers = server_service.get_all_servers_with_permissions(\n user_context['accessible_servers']\n )\n logger.info(f\"User accessing {len(all_servers)} permitted servers\")\n \n # Render dashboard with filtered content\n return templates.TemplateResponse(\"index.html\", {\n \"request\": request, \n \"services\": service_data, \n \"username\": user_context['username'],\n \"user_context\": user_context\n })\n\n@router.post(\"/toggle/{service_path:path}\")\nasync def toggle_service_route(service_path: str,\n user_context: Annotated[dict, Depends(enhanced_auth)]):\n \"\"\"Service toggle with multi-level permission checking\"\"\"\n # Check global modification permission\n if not user_context['can_modify_servers']:\n logger.warning(f\"User {user_context['username']} attempted toggle without modify permissions\")\n raise HTTPException(status_code=403, \n detail=\"You do not have permission to modify servers\")\n \n # For non-admin users, check specific server access\n if not user_context['is_admin']:\n if not server_service.user_can_access_server_path(\n service_path, user_context['accessible_servers']):\n logger.warning(f\"User {user_context['username']} attempted to access {service_path} without permission\")\n raise HTTPException(status_code=403,\n detail=\"You do not have access to this server\")\n \n # Proceed with toggle operation\n return perform_toggle_operation(service_path, user_context)\n\n@router.get(\"/api/server_details/{service_path:path}\")\nasync def get_server_details(service_path: str,\n user_context: Annotated[dict, Depends(enhanced_auth)]):\n \"\"\"Server details with permission-based filtering\"\"\"\n # Handle special '/all' endpoint for admins\n if service_path == '/all':\n if user_context['is_admin']:\n return server_service.get_all_servers()\n else:\n return server_service.get_all_servers_with_permissions(\n user_context['accessible_servers']\n )\n \n # Check individual server access\n server_info = server_service.get_server_info(service_path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service not found\")\n \n if not user_context['is_admin']:\n if not server_service.user_can_access_server_path(\n service_path, user_context['accessible_servers']):\n raise HTTPException(status_code=403, \n detail=\"Access denied to this server\")\n \n return server_info\n```\n\n### Permission Validation Flow\n\n```mermaid\nflowchart TD\n RequestStart([HTTP Request]) --> ExtractSession[Extract Session Cookie]\n ExtractSession --> ValidateSession{Session Valid?}\n \n ValidateSession -->|No| Unauthorized[Return 401 Unauthorized]\n ValidateSession -->|Yes| ExtractUserContext[Extract User Context]\n \n ExtractUserContext --> LoadGroups[Load User Groups]\n LoadGroups --> MapScopes[Map Groups to Scopes]\n MapScopes --> CalculateServers[Calculate Accessible Servers]\n CalculateServers --> CheckModifyPermission[Check Modify Permissions]\n \n CheckModifyPermission --> RouteSpecificCheck{Route Requires
Specific Permissions?}\n \n RouteSpecificCheck -->|Global Access| AllowAccess[Allow Request]\n RouteSpecificCheck -->|Server-Specific| CheckServerAccess{User Can Access
Specific Server?}\n RouteSpecificCheck -->|Modify Required| CheckModifyCapability{User Can
Modify Servers?}\n \n CheckServerAccess -->|Yes| AllowAccess\n CheckServerAccess -->|No| Forbidden[Return 403 Forbidden]\n \n CheckModifyCapability -->|Yes| CheckServerAccess\n CheckModifyCapability -->|No| Forbidden\n \n AllowAccess --> FilterContent[Filter Content by Permissions]\n FilterContent --> RenderResponse[Render Response]\n \n Unauthorized --> End([End])\n Forbidden --> End\n RenderResponse --> End\n \n classDef success fill:#e8f5e8,stroke:#4caf50,stroke-width:2px\n classDef error fill:#ffebee,stroke:#f44336,stroke-width:2px\n classDef process fill:#e3f2fd,stroke:#2196f3,stroke-width:2px\n classDef decision fill:#fff3e0,stroke:#ff9800,stroke-width:2px\n \n class AllowAccess,RenderResponse success\n class Unauthorized,Forbidden error\n class ExtractSession,ExtractUserContext,LoadGroups,MapScopes,CalculateServers,CheckModifyPermission,FilterContent process\n class ValidateSession,RouteSpecificCheck,CheckServerAccess,CheckModifyCapability decision\n```\n\n## Technical Implementation\n\n### Session Management Deep Dive\n\n#### Session Cookie Architecture\n\nThe registry uses `itsdangerous.URLSafeTimedSerializer` for secure, stateless session management:\n\n```python\n# registry/auth/dependencies.py\nfrom itsdangerous import URLSafeTimedSerializer, SignatureExpired, BadSignature\n\n# Initialize session signer with secret key\nsigner = URLSafeTimedSerializer(settings.secret_key)\n\ndef create_session_cookie(username: str, auth_method: str = \"oauth2\",\n provider: str = \"cognito\") -> str:\n \"\"\"Create a secure session cookie for a user\"\"\"\n session_data = {\n \"username\": username,\n \"auth_method\": auth_method, # 'oauth2'\n \"provider\": provider, # 'cognito', 'saml', etc.\n \"created_at\": datetime.utcnow().isoformat(),\n \"groups\": [], # Populated during OAuth2 flow\n \"scopes\": [] # Calculated from groups\n }\n \n # Create signed, time-limited cookie\n return signer.dumps(session_data)\n```\n\n#### Session Validation Implementation\n\n```python\ndef get_user_session_data(session: str = Cookie(alias=\"mcp_gateway_session\")) -> Dict[str, Any]:\n \"\"\"Extract and validate session data from cookie\"\"\"\n if not session:\n raise HTTPException(status_code=401, detail=\"Authentication required\")\n \n try:\n # Validate signature and expiration\n data = signer.loads(session, max_age=settings.session_max_age_seconds)\n \n if not data.get('username'):\n raise HTTPException(status_code=401, detail=\"Invalid session data\")\n\n return data\n \n except SignatureExpired:\n raise HTTPException(status_code=401, detail=\"Session has expired\")\n except BadSignature:\n raise HTTPException(status_code=401, detail=\"Invalid session\")\n except Exception as e:\n logger.error(f\"Session validation error: {e}\")\n raise HTTPException(status_code=401, detail=\"Authentication failed\")\n```\n\n### OAuth2 Integration Architecture\n\n#### External Auth Server Communication\n\n```mermaid\nsequenceDiagram\n participant Registry as Registry App\n participant AuthServer as Auth Server
(:8888)\n participant IdP as Identity Provider
(Cognito/SAML)\n \n Note over Registry,IdP: Provider Discovery\n Registry->>AuthServer: GET /oauth2/providers\n AuthServer->>Registry: Available provider list\n \n Note over Registry,IdP: OAuth2 Login Initiation\n Registry->>AuthServer: GET /oauth2/login/{provider}?redirect_uri=...\n AuthServer->>IdP: OAuth2 PKCE flow initiation\n IdP->>AuthServer: Authorization code\n \n Note over Registry,IdP: Token Exchange & Session Creation\n AuthServer->>IdP: Exchange code for tokens\n IdP->>AuthServer: Access token + user info\n AuthServer->>AuthServer: Extract user groups\n AuthServer->>AuthServer: Map groups to MCP scopes\n AuthServer->>AuthServer: Create registry-compatible session cookie\n AuthServer->>Registry: Set session cookie + redirect\n \n Note over Registry,IdP: Session Validation\n Registry->>Registry: Validate session cookie signature\n Registry->>Registry: Extract user context & permissions\n Registry->>Registry: Render permission-based UI\n```\n\n#### Provider Configuration Management\n\n```python\n# registry/auth/routes.py\nasync def get_oauth2_providers():\n \"\"\"Dynamically fetch available OAuth2 providers from auth server\"\"\"\n try:\n async with httpx.AsyncClient() as client:\n response = await client.get(\n f\"{settings.auth_server_url}/oauth2/providers\", \n timeout=5.0\n )\n if response.status_code == 200:\n data = response.json()\n providers = data.get(\"providers\", [])\n logger.info(f\"Loaded {len(providers)} OAuth2 providers\")\n return providers\n except httpx.TimeoutException:\n logger.warning(\"Timeout fetching OAuth2 providers from auth server\")\n except httpx.ConnectError:\n logger.warning(\"Cannot connect to auth server for provider discovery\")\n except Exception as e:\n logger.warning(f\"Failed to fetch OAuth2 providers: {e}\")\n \n return [] # No providers available\n```\n\n### Authentication Dependencies System\n\n#### Dependency Injection Hierarchy\n\n```mermaid\ngraph TB\n subgraph \"FastAPI Dependency Hierarchy\"\n BasicAuth[get_current_user
Returns: username only]\n SessionAuth[get_user_session_data
Returns: full session data]\n EnhancedAuth[enhanced_auth
Returns: permissions + context]\n end\n \n subgraph \"Usage Patterns\"\n SimpleRoutes[Simple Routes
Basic user identification]\n DataRoutes[Data Routes
Need session info]\n ProtectedRoutes[Protected Routes
Permission-based access]\n end\n \n BasicAuth --> SimpleRoutes\n SessionAuth --> DataRoutes\n EnhancedAuth --> ProtectedRoutes\n \n BasicAuth -.-> SessionAuth\n SessionAuth -.-> EnhancedAuth\n \n classDef dependency fill:#e3f2fd,stroke:#1976d2,stroke-width:2px\n classDef usage fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n \n class BasicAuth,SessionAuth,EnhancedAuth dependency\n class SimpleRoutes,DataRoutes,ProtectedRoutes usage\n```\n\n#### Implementation Examples\n\n```python\n# registry/auth/dependencies.py\n\n# Level 1: Basic Authentication\ndef get_current_user(session: str = Cookie(alias=\"mcp_gateway_session\")) -> str:\n \"\"\"Basic authentication - returns username only\"\"\"\n if not session:\n raise HTTPException(status_code=401, detail=\"Authentication required\")\n \n try:\n data = signer.loads(session, max_age=settings.session_max_age_seconds)\n username = data.get('username')\n if not username:\n raise HTTPException(status_code=401, detail=\"Invalid session data\")\n return username\n except (SignatureExpired, BadSignature):\n raise HTTPException(status_code=401, detail=\"Invalid or expired session\")\n\n# Level 2: Session Data Extraction \ndef get_user_session_data(session: str = Cookie(alias=\"mcp_gateway_session\")) -> Dict[str, Any]:\n \"\"\"Full session data extraction with validation\"\"\"\n # Implementation shown above\n pass\n\n# Level 3: Enhanced Authentication with Permissions\ndef enhanced_auth(session: str = Cookie(alias=\"mcp_gateway_session\")) -> Dict[str, Any]:\n \"\"\"Complete user context with permissions and authorization\"\"\"\n session_data = get_user_session_data(session)\n \n # Calculate permissions and accessible servers\n # Implementation shown in Authorization section\n return user_context\n```\n\n### WebSocket Authentication Handling\n\n#### WebSocket Session Validation\n\n```python\n# registry/health/routes.py\n@router.websocket(\"/ws/health_status\")\nasync def websocket_endpoint(websocket: WebSocket):\n \"\"\"WebSocket endpoint with automatic session validation\"\"\"\n connection_added = False\n try:\n # WebSocket cookies are automatically included in handshake\n # Validate session before accepting connection\n session_cookie = None\n for cookie in websocket.cookies:\n if cookie.name == settings.session_cookie_name:\n session_cookie = cookie.value\n break\n \n if session_cookie:\n try:\n # Validate session\n session_data = signer.loads(\n session_cookie, \n max_age=settings.session_max_age_seconds\n )\n username = session_data.get('username')\n if username:\n logger.info(f\"WebSocket connection from authenticated user: {username}\")\n else:\n raise ValueError(\"No username in session\")\n except Exception as e:\n logger.warning(f\"WebSocket authentication failed: {e}\")\n await websocket.close(code=1008, reason=\"Authentication failed\")\n return\n else:\n logger.warning(\"WebSocket connection without valid session cookie\")\n await websocket.close(code=1008, reason=\"Authentication required\")\n return\n \n # Accept connection after successful authentication\n connection_added = await health_service.add_websocket_connection(websocket)\n if not connection_added:\n return # Connection rejected (server at capacity)\n \n # Keep connection alive\n while True:\n try:\n await asyncio.wait_for(websocket.receive_text(), timeout=30.0)\n except asyncio.TimeoutError:\n await websocket.ping() # Keep-alive ping\n \n except WebSocketDisconnect:\n logger.debug(f\"WebSocket client disconnected\")\n except Exception as e:\n logger.warning(f\"WebSocket error: {e}\")\n finally:\n if connection_added:\n await health_service.remove_websocket_connection(websocket)\n```\n\n### Database-Free Architecture\n\nThe registry implements a **stateless, file-based architecture** that doesn't require a traditional database:\n\n#### Server Data Storage\n\n```python\n# registry/services/server_service.py\nclass ServerService:\n \"\"\"File-based server management service\"\"\"\n \n def __init__(self):\n self.servers: Dict[str, Dict[str, Any]] = {}\n self.enabled_services: Set[str] = set()\n \n def load_servers_and_state(self):\n \"\"\"Load server definitions from JSON files and state from state file\"\"\"\n # Load individual server definitions\n servers_dir = settings.servers_dir\n for json_file in servers_dir.glob(\"*.json\"):\n if json_file.name == \"server_state.json\":\n continue # Skip state file\n \n try:\n with open(json_file, \"r\") as f:\n server_data = json.load(f)\n path = server_data.get(\"path\")\n if path:\n self.servers[path] = server_data\n logger.info(f\"Loaded server definition: {path}\")\n except Exception as e:\n logger.error(f\"Error loading {json_file}: {e}\")\n \n # Load service state\n self._load_service_state()\n \n def _load_service_state(self):\n \"\"\"Load enabled/disabled state from server_state.json\"\"\"\n state_file = settings.state_file_path\n if state_file.exists():\n try:\n with open(state_file, \"r\") as f:\n state_data = json.load(f)\n for path, enabled in state_data.items():\n if enabled and path in self.servers:\n self.enabled_services.add(path)\n logger.info(f\"Loaded service state for {len(state_data)} services\")\n except Exception as e:\n logger.error(f\"Error loading service state: {e}\")\n \n def save_service_state(self):\n \"\"\"Save current enabled/disabled state to file\"\"\"\n state_data = {}\n for path in self.servers:\n state_data[path] = path in self.enabled_services\n \n try:\n with open(settings.state_file_path, \"w\") as f:\n json.dump(state_data, f, indent=2)\n logger.info(\"Service state saved successfully\")\n except Exception as e:\n logger.error(f\"Error saving service state: {e}\")\n```\n\n#### Configuration Management\n\n```python\n# registry/core/config.py\nclass Settings(BaseSettings):\n \"\"\"Centralized configuration with environment variable support\"\"\"\n \n # Development vs Production path detection\n @property\n def is_local_dev(self) -> bool:\n \"\"\"Detect if running in local development mode\"\"\"\n return not Path(\"/app\").exists()\n \n @property\n def servers_dir(self) -> Path:\n \"\"\"Dynamic path resolution for server definitions\"\"\"\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"servers\"\n return self.container_registry_dir / \"servers\"\n \n @property\n def templates_dir(self) -> Path:\n \"\"\"Dynamic path resolution for templates\"\"\"\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"templates\"\n return self.container_registry_dir / \"templates\"\n```\n\n## Configuration\n\n### Environment Variables Reference\n\n#### Core Authentication Settings\n\n```bash\n# Session Management\nSECRET_KEY=your-secure-random-secret-key-here\nSESSION_COOKIE_NAME=mcp_gateway_session\nSESSION_MAX_AGE_SECONDS=28800 # 8 hours default\n\n# External Auth Server Integration\nAUTH_SERVER_URL=http://localhost:8888\nAUTH_SERVER_EXTERNAL_URL=http://localhost:8888 # For browser redirects\n\n# Path Configuration (auto-detected in most cases)\nCONTAINER_APP_DIR=/app\nCONTAINER_REGISTRY_DIR=/app/registry\nCONTAINER_LOG_DIR=/app/logs\n```\n\n#### OAuth2 Provider Configuration\n\n```bash\n# Amazon Cognito Integration (if using Cognito directly)\nCOGNITO_DOMAIN=your-cognito-domain\nCOGNITO_CLIENT_ID=your-cognito-client-id\nCOGNITO_REGION=us-east-1\n\n# Custom OAuth2 Providers (configured in auth server)\n# These are typically configured in the auth_server application\n```\n\n### Development vs Production Configuration\n\n#### Local Development Setup\n\n```python\n# Automatic detection and configuration\n# registry/core/config.py\n\n@property\ndef is_local_dev(self) -> bool:\n \"\"\"Check if running in local development mode\"\"\"\n return not Path(\"/app\").exists()\n\n# Development paths\nif settings.is_local_dev:\n # Paths resolve to ./registry/ subdirectories\n servers_dir = Path.cwd() / \"registry\" / \"servers\"\n templates_dir = Path.cwd() / \"registry\" / \"templates\"\n static_dir = Path.cwd() / \"registry\" / \"static\"\n log_file = Path.cwd() / \"logs\" / \"registry.log\"\n```\n\n#### Container/Production Setup\n\n```python\n# Production paths (when /app exists)\nelse:\n # Paths resolve to /app/registry/ structure\n servers_dir = Path(\"/app/registry/servers\")\n templates_dir = Path(\"/app/registry/templates\")\n static_dir = Path(\"/app/registry/static\")\n log_file = Path(\"/app/logs/registry.log\")\n```\n\n### Authentication Provider Setup\n\n#### OAuth2 Integration Setup\n\n1. **Configure Auth Server** (separate application):\n ```yaml\n # auth_server/config.yml\n providers:\n cognito:\n domain: your-cognito-domain\n client_id: your-client-id\n region: us-east-1\n \n saml:\n endpoint: https://your-saml-provider.com/saml\n entity_id: your-entity-id\n ```\n\n2. **Configure Group Mappings**:\n ```yaml\n # auth_server/scopes.yml\n group_mappings:\n mcp-admin:\n - \"mcp-servers-unrestricted/read\"\n - \"mcp-servers-unrestricted/execute\"\n ```\n\n### Security Configuration\n\n#### Secret Key Management\n\n```python\n# registry/core/config.py\ndef __init__(self, **kwargs):\n super().__init__(**kwargs)\n # Generate secret key if not provided\n if not self.secret_key:\n self.secret_key = secrets.token_hex(32)\n logger.warning(\"Generated random SECRET_KEY - sessions will not persist across restarts\")\n```\n\n#### Session Security Settings\n\n```python\n# Session cookie configuration\nresponse.set_cookie(\n key=settings.session_cookie_name,\n value=session_data,\n max_age=settings.session_max_age_seconds,\n httponly=True, # Prevent XSS access\n samesite=\"lax\", # CSRF protection\n secure=False # Set to True in production with HTTPS\n)\n```\n\n### Deployment Configuration Examples\n\n#### Docker Compose Setup\n\n```yaml\n# docker-compose.yml\nservices:\n registry:\n build: .\n environment:\n - SECRET_KEY=${SECRET_KEY}\n - AUTH_SERVER_URL=http://auth-server:8888\n - AUTH_SERVER_EXTERNAL_URL=http://localhost:8888\n volumes:\n - ./registry/servers:/app/registry/servers\n - ./logs:/app/logs\n ports:\n - \"7860:7860\"\n \n auth-server:\n build: ./auth_server\n environment:\n - COGNITO_DOMAIN=${COGNITO_DOMAIN}\n - COGNITO_CLIENT_ID=${COGNITO_CLIENT_ID}\n ports:\n - \"8888:8888\"\n```\n\n#### Environment File Template\n\n```bash\n# .env file template\nSECRET_KEY=generate-a-secure-random-key-here\n\n# Auth Server Configuration\nAUTH_SERVER_URL=http://localhost:8888\nAUTH_SERVER_EXTERNAL_URL=http://localhost:8888\n\n# OAuth2 Provider Settings (if applicable)\nCOGNITO_DOMAIN=your-cognito-domain\nCOGNITO_CLIENT_ID=your-client-id\nCOGNITO_REGION=us-east-1\n\n# Optional: Custom paths (usually auto-detected)\n# CONTAINER_REGISTRY_DIR=/custom/path/registry\n# CONTAINER_LOG_DIR=/custom/path/logs\n```\n\n## Troubleshooting\n\n### Common Authentication Issues\n\n#### 1. Session Cookie Problems\n\n**Issue**: Users get redirected to login page repeatedly\n\n**Diagnosis**:\n```python\n# Add debug logging to session validation\ndef get_user_session_data(session: str = None) -> Dict[str, Any]:\n logger.info(f\"Session cookie received: {session[:20] if session else 'None'}...\")\n \n try:\n data = signer.loads(session, max_age=settings.session_max_age_seconds)\n logger.info(f\"Session data valid for user: {data.get('username')}\")\n return data\n except SignatureExpired:\n logger.warning(\"Session cookie has expired\")\n raise HTTPException(status_code=401, detail=\"Session has expired\")\n except BadSignature:\n logger.warning(\"Invalid session cookie signature\")\n raise HTTPException(status_code=401, detail=\"Invalid session\")\n```\n\n**Common Solutions**:\n- **Inconsistent SECRET_KEY**: Ensure `SECRET_KEY` is consistent across application restarts\n- **Clock Skew**: Check system time if using multiple servers\n- **Cookie Domain Issues**: Verify cookie domain matches request domain\n- **Browser Issues**: Clear browser cookies and try again\n\n#### 2. OAuth2 Integration Issues\n\n**Issue**: OAuth2 login fails or redirects incorrectly\n\n**Diagnosis**:\n```python\n# Debug OAuth2 callback handling\n@router.get(\"/auth/callback\")\nasync def oauth2_callback(request: Request, error: str = None, details: str = None):\n logger.info(f\"OAuth2 callback received - Error: {error}, Details: {details}\")\n \n if error:\n logger.error(f\"OAuth2 authentication error: {error} - {details}\")\n return RedirectResponse(url=f\"/login?error={urllib.parse.quote(error)}\")\n \n # Check session cookie from auth server\n session_cookie = request.cookies.get(settings.session_cookie_name)\n logger.info(f\"OAuth2 callback session cookie: {'Present' if session_cookie else 'Missing'}\")\n \n if session_cookie:\n try:\n session_data = signer.loads(session_cookie, max_age=settings.session_max_age_seconds)\n logger.info(f\"OAuth2 session valid for: {session_data.get('username')}\")\n return RedirectResponse(url=\"/\", status_code=302)\n except Exception as e:\n logger.error(f\"OAuth2 session validation failed: {e}\")\n \n return RedirectResponse(url=\"/login?error=oauth2_session_invalid\", status_code=302)\n```\n\n**Common Solutions**:\n- **Auth Server Connectivity**: Test auth server: `curl http://localhost:8888/oauth2/providers`\n- **URL Configuration**: Verify `AUTH_SERVER_URL` and `AUTH_SERVER_EXTERNAL_URL` settings\n- **Provider Configuration**: Check OAuth2 client configuration in identity provider\n- **Redirect URI Mismatch**: Ensure redirect URIs match in provider configuration\n\n#### 3. Permission and Authorization Issues\n\n**Issue**: Users can't access servers they should have permission for\n\n**Diagnosis**:\n```python\n# Debug permission calculation\ndef debug_user_permissions(user_context: dict):\n logger.info(\"=== USER PERMISSION DEBUG ===\")\n logger.info(f\"Username: {user_context['username']}\")\n logger.info(f\"Auth Method: {user_context['auth_method']}\")\n logger.info(f\"Groups: {user_context['groups']}\")\n logger.info(f\"Scopes: {user_context['scopes']}\")\n logger.info(f\"Accessible Servers: {user_context['accessible_servers']}\")\n logger.info(f\"Can Modify: {user_context['can_modify_servers']}\")\n logger.info(f\"Is Admin: {user_context['is_admin']}\")\n logger.info(\"============================\")\n\n# Add to enhanced_auth function\ndef enhanced_auth(session: str = None) -> Dict[str, Any]:\n # ... existing code ...\n \n user_context = {\n # ... context building ...\n }\n \n debug_user_permissions(user_context) # Add this line\n return user_context\n```\n\n**Common Solutions**:\n- **Group Mapping Issues**: Verify `auth_server/scopes.yml` configuration\n- **User Group Assignment**: Check user group assignments in identity provider (Cognito)\n- **Server Name Mismatch**: Ensure server names in scopes.yml exactly match server definitions\n- **Scope Configuration**: Verify scope definitions reference correct server names\n\n#### 4. WebSocket Authentication Issues\n\n**Issue**: Real-time updates not working, WebSocket connections failing\n\n**Diagnosis**:\n```python\n# Debug WebSocket authentication\n@router.websocket(\"/ws/health_status\")\nasync def websocket_endpoint(websocket: WebSocket):\n logger.info(f\"WebSocket connection attempt from: {websocket.client}\")\n \n # Debug cookie extraction\n session_cookie = None\n logger.info(f\"WebSocket cookies: {list(websocket.cookies.keys())}\")\n \n for cookie_name, cookie_value in websocket.cookies.items():\n logger.info(f\"Cookie: {cookie_name} = {cookie_value[:20]}...\")\n if cookie_name == settings.session_cookie_name:\n session_cookie = cookie_value\n \n if not session_cookie:\n logger.warning(\"WebSocket connection without session cookie\")\n await websocket.close(code=1008, reason=\"No session cookie\")\n return\n \n try:\n session_data = signer.loads(session_cookie, max_age=settings.session_max_age_seconds)\n username = session_data.get('username')\n logger.info(f\"WebSocket authenticated for user: {username}\")\n await websocket.accept()\n except Exception as e:\n logger.error(f\"WebSocket authentication failed: {e}\")\n await websocket.close(code=1008, reason=\"Authentication failed\")\n```\n\n**Common Solutions**:\n- **Browser Cookie Issues**: Check browser developer tools for cookie presence\n- **WebSocket URL**: Verify WebSocket URL scheme (ws:// vs wss://)\n- **Proxy Configuration**: Ensure reverse proxy supports WebSocket upgrades\n- **Firewall Issues**: Check if WebSocket ports are accessible\n\n### Health Check and Monitoring\n\n#### Authentication Health Endpoint\n\n```python\n# registry/main.py or separate health module\n@app.get(\"/health/auth\")\nasync def auth_health_check():\n \"\"\"Comprehensive authentication system health check\"\"\"\n health_status = {\n \"timestamp\": datetime.utcnow().isoformat(),\n \"components\": {\n \"session_signer\": \"unknown\",\n \"auth_server\": \"unknown\",\n \"oauth2_providers\": [],\n \"scope_config\": \"unknown\"\n }\n }\n \n # Test session signer\n try:\n test_data = {\"test\": \"data\"}\n test_cookie = signer.dumps(test_data)\n decoded_data = signer.loads(test_cookie, max_age=60)\n if decoded_data == test_data:\n health_status[\"components\"][\"session_signer\"] = \"ok\"\n else:\n health_status[\"components\"][\"session_signer\"] = \"error: data mismatch\"\n except Exception as e:\n health_status[\"components\"][\"session_signer\"] = f\"error: {e}\"\n \n # Test auth server connectivity\n try:\n async with httpx.AsyncClient(timeout=5.0) as client:\n response = await client.get(f\"{settings.auth_server_url}/health\")\n if response.status_code == 200:\n health_status[\"components\"][\"auth_server\"] = \"ok\"\n \n # Test OAuth2 providers endpoint\n providers_response = await client.get(f\"{settings.auth_server_url}/oauth2/providers\")\n if providers_response.status_code == 200:\n providers_data = providers_response.json()\n health_status[\"components\"][\"oauth2_providers\"] = providers_data.get(\"providers\", [])\n else:\n health_status[\"components\"][\"oauth2_providers\"] = \"error: provider endpoint failed\"\n else:\n health_status[\"components\"][\"auth_server\"] = f\"error: HTTP {response.status_code}\"\n except httpx.TimeoutException:\n health_status[\"components\"][\"auth_server\"] = \"error: timeout\"\n except httpx.ConnectError:\n health_status[\"components\"][\"auth_server\"] = \"error: connection failed\"\n except Exception as e:\n health_status[\"components\"][\"auth_server\"] = f\"error: {e}\"\n \n # Test scope configuration\n try:\n from .auth.dependencies import SCOPES_CONFIG\n if SCOPES_CONFIG and \"group_mappings\" in SCOPES_CONFIG:\n group_count = len(SCOPES_CONFIG[\"group_mappings\"])\n health_status[\"components\"][\"scope_config\"] = f\"ok: {group_count} group mappings\"\n else:\n health_status[\"components\"][\"scope_config\"] = \"warning: no scope configuration loaded\"\n except Exception as e:\n health_status[\"components\"][\"scope_config\"] = f\"error: {e}\"\n \n # Overall health determination\n error_components = [k for k, v in health_status[\"components\"].items() if str(v).startswith(\"error\")]\n if error_components:\n health_status[\"status\"] = \"unhealthy\"\n health_status[\"errors\"] = error_components\n else:\n health_status[\"status\"] = \"healthy\"\n \n return health_status\n```\n\n#### Authentication Event Logging\n\n```python\n# Enhanced logging for authentication events\ndef log_auth_event(event_type: str, username: str = None, details: dict = None, \n request: Request = None):\n \"\"\"Comprehensive authentication event logging\"\"\"\n log_data = {\n 'event_type': event_type,\n 'username': username,\n 'timestamp': datetime.utcnow().isoformat(),\n 'details': details or {}\n }\n \n if request:\n log_data.update({\n 'client_ip': request.client.host if request.client else 'unknown',\n 'user_agent': request.headers.get('user-agent', 'unknown'),\n 'request_path': str(request.url.path),\n 'request_method': request.method\n })\n \n logger.info(f\"AUTH_EVENT: {event_type}\", extra=log_data)\n\n# Usage examples throughout the application\nlog_auth_event('LOGIN_SUCCESS', username='admin', request=request)\nlog_auth_event('LOGIN_FAILED', details={'reason': 'invalid_credentials'}, request=request)\nlog_auth_event('PERMISSION_DENIED', username='user', \n details={'resource': '/toggle/fininfo', 'required_permission': 'modify'}, \n request=request)\nlog_auth_event('SESSION_EXPIRED', username='user', request=request)\nlog_auth_event('OAUTH2_LOGIN_START', details={'provider': 'cognito'}, request=request)\nlog_auth_event('OAUTH2_LOGIN_SUCCESS', username='user@example.com', \n details={'provider': 'cognito', 'groups': ['mcp-user']}, request=request)\n```\n\n### Common Configuration Mistakes\n\n#### 1. Incorrect Path Configuration\n```bash\n# Wrong - mixing local and container paths\nCONTAINER_REGISTRY_DIR=/app/registry\n# But running locally where paths should be ./registry/\n\n# Solution: Let the application auto-detect paths or set correctly\n# For local development, omit these variables entirely\n```\n\n#### 2. Secret Key Issues\n```bash\n# Wrong - using a weak or default secret key\nSECRET_KEY=mysecret\n\n# Correct - use a strong, randomly generated key\nSECRET_KEY=$(python -c \"import secrets; print(secrets.token_hex(32))\")\n```\n\n#### 3. Auth Server URL Mismatch\n```bash\n# Wrong - internal and external URLs are the same in Docker\nAUTH_SERVER_URL=http://localhost:8888\nAUTH_SERVER_EXTERNAL_URL=http://localhost:8888\n\n# Correct - distinguish internal vs external access\nAUTH_SERVER_URL=http://auth-server:8888 # Internal Docker communication\nAUTH_SERVER_EXTERNAL_URL=http://localhost:8888 # Browser-accessible URL\n```\n\nThis comprehensive documentation provides complete coverage of the registry's authentication and authorization system, from high-level architecture to specific implementation details and troubleshooting guidance. " }, { "path": "docs/registry-deployment-modes.md", "content": "# Registry Deployment and Registry Mode Configuration\n\nThis guide explains the `DEPLOYMENT_MODE` and `REGISTRY_MODE` environment variables that control how the MCP Gateway Registry operates.\n\n## Overview\n\nThe registry supports two configuration settings that control its behavior:\n\n| Setting | Purpose | Options |\n|---------|---------|---------|\n| `DEPLOYMENT_MODE` | Controls nginx/gateway integration | `with-gateway`, `registry-only` |\n| `REGISTRY_MODE` | Controls which features are enabled (informational) | `full`, `skills-only`, `mcp-servers-only`, `agents-only` |\n\n## DEPLOYMENT_MODE\n\nThe `DEPLOYMENT_MODE` setting determines whether the registry operates as a full gateway with nginx reverse proxy integration, or as a standalone catalog/discovery service.\n\n### Mode: with-gateway (Default)\n\n```bash\nDEPLOYMENT_MODE=with-gateway\n```\n\n**Behavior:**\n- Nginx configuration is regenerated when MCP servers are registered or deleted\n- Frontend shows gateway authentication instructions (Authorization: Bearer token)\n- MCP proxy requests are routed through nginx to backend servers\n- Full gateway functionality enabled\n\n**Use when:**\n- Running the registry as part of the MCP Gateway infrastructure\n- MCP servers are accessed through the nginx reverse proxy\n- You need centralized authentication and routing\n\n### Mode: registry-only\n\n```bash\nDEPLOYMENT_MODE=registry-only\n```\n\n**Behavior:**\n- Nginx configuration is NOT updated when servers are registered/deleted\n- Frontend shows \"Direct Connection Mode\" with `proxy_pass_url`\n- MCP proxy requests return 503 Service Unavailable with JSON error\n- Registry operates as a catalog/discovery service only\n\n**Use when:**\n- Registry is separate from gateway infrastructure\n- Clients connect directly to MCP servers (not through gateway)\n- You only need server/agent discovery and metadata management\n\n## REGISTRY_MODE\n\nThe `REGISTRY_MODE` setting controls which feature flags are returned in the `/api/config` endpoint. This is informational and intended for frontend UI feature gating.\n\n**Note:** Currently, all APIs remain active regardless of this setting. The feature flags are for UI display purposes only.\n\n### Mode Comparison Table\n\n| Mode | MCP Servers | Agents | Skills | Federation | Gateway Proxy |\n|------|-------------|--------|--------|------------|---------------|\n| `full` | Enabled | Enabled | Enabled | Enabled | Based on DEPLOYMENT_MODE |\n| `skills-only` | Disabled | Disabled | Enabled | Disabled | Disabled |\n| `mcp-servers-only` | Enabled | Disabled | Disabled | Disabled | Based on DEPLOYMENT_MODE |\n| `agents-only` | Disabled | Enabled | Disabled | Disabled | Based on DEPLOYMENT_MODE |\n\n### Mode: full (Default)\n\n```bash\nREGISTRY_MODE=full\n```\n\nAll features enabled. The `gateway_proxy` flag depends on `DEPLOYMENT_MODE`.\n\n### Mode: skills-only\n\n```bash\nREGISTRY_MODE=skills-only\n```\n\nOnly the skills feature flag is enabled. Intended for deployments focused solely on Agent Skills management.\n\n### Mode: mcp-servers-only\n\n```bash\nREGISTRY_MODE=mcp-servers-only\n```\n\nOnly the MCP servers feature flag is enabled.\n\n### Mode: agents-only\n\n```bash\nREGISTRY_MODE=agents-only\n```\n\nOnly the A2A agents feature flag is enabled.\n\n## Configuration Combinations\n\n### Valid Combinations\n\n| DEPLOYMENT_MODE | REGISTRY_MODE | Use Case |\n|-----------------|---------------|----------|\n| `with-gateway` | `full` | Full MCP Gateway with all features |\n| `with-gateway` | `mcp-servers-only` | Gateway for MCP servers only |\n| `with-gateway` | `agents-only` | Gateway for A2A agents only |\n| `registry-only` | `full` | Standalone catalog with all metadata |\n| `registry-only` | `skills-only` | Skills catalog only |\n| `registry-only` | `mcp-servers-only` | MCP server catalog only |\n| `registry-only` | `agents-only` | Agent catalog only |\n\n### Invalid Combination (Auto-Corrected)\n\n| DEPLOYMENT_MODE | REGISTRY_MODE | Auto-Corrected To |\n|-----------------|---------------|-------------------|\n| `with-gateway` | `skills-only` | `registry-only` + `skills-only` |\n\n**Rationale:** Skills-only mode doesn't require gateway proxy functionality. The system automatically corrects this invalid combination and logs a warning.\n\n## API Configuration Endpoint\n\nThe `/api/config` endpoint returns the current configuration:\n\n```bash\ncurl http://localhost/api/config\n```\n\n**Example Response (with-gateway + full):**\n```json\n{\n \"deployment_mode\": \"with-gateway\",\n \"registry_mode\": \"full\",\n \"nginx_updates_enabled\": true,\n \"features\": {\n \"mcp_servers\": true,\n \"agents\": true,\n \"skills\": true,\n \"federation\": true,\n \"gateway_proxy\": true\n }\n}\n```\n\n**Example Response (registry-only + skills-only):**\n```json\n{\n \"deployment_mode\": \"registry-only\",\n \"registry_mode\": \"skills-only\",\n \"nginx_updates_enabled\": false,\n \"features\": {\n \"mcp_servers\": false,\n \"agents\": false,\n \"skills\": true,\n \"federation\": false,\n \"gateway_proxy\": false\n }\n}\n```\n\n## Environment Configuration\n\n### Docker Compose\n\nIn your `.env` file:\n\n```bash\n# Deployment mode: with-gateway (default) or registry-only\nDEPLOYMENT_MODE=registry-only\n\n# Registry mode: full (default), skills-only, mcp-servers-only, or agents-only\nREGISTRY_MODE=skills-only\n```\n\n### Terraform (AWS ECS)\n\nIn `terraform.tfvars`:\n\n```hcl\n# Deployment mode\ndeployment_mode = \"registry-only\"\n\n# Registry mode (optional, defaults to \"full\")\nregistry_mode = \"skills-only\"\n```\n\nOr via environment variables:\n\n```bash\nexport TF_VAR_deployment_mode=\"registry-only\"\nexport TF_VAR_registry_mode=\"skills-only\"\n```\n\n## Frontend Behavior\n\n### ServerConfigModal\n\nThe `ServerConfigModal` component adapts based on `deployment_mode`:\n\n**with-gateway mode:**\n- Shows gateway URL constructed from current hostname\n- Displays \"Authentication Required\" warning\n- Shows `[YOUR_AUTH_TOKEN]` placeholder in configuration\n\n**registry-only mode:**\n- Shows `proxy_pass_url` (direct server URL)\n- Displays \"Direct Connection Mode\" banner\n- No gateway authentication headers in configuration\n\n### Feature Flags (Future)\n\nThe `features` object in `/api/config` is intended for frontend navigation gating:\n\n```typescript\nconst { config } = useRegistryConfig();\n\n// Hide navigation items based on features\n{config?.features.mcp_servers && MCP Servers}\n{config?.features.agents && A2A Agents}\n{config?.features.skills && Skills}\n{config?.features.federation && Federation}\n```\n\n**Note:** This frontend gating is not yet implemented. Currently all navigation items are visible regardless of mode.\n\n## Startup Logging\n\nThe registry logs its configuration at startup:\n\n```\nINFO: Registry Configuration:\nINFO: DEPLOYMENT_MODE: registry-only\nINFO: REGISTRY_MODE: skills-only\nINFO: Nginx updates: DISABLED\n```\n\nIf an invalid combination is detected:\n\n```\nWARNING: ============================================================\nWARNING: Invalid configuration detected!\nWARNING: DEPLOYMENT_MODE=with-gateway is incompatible with REGISTRY_MODE=skills-only\nWARNING: Auto-correcting to DEPLOYMENT_MODE=registry-only\nWARNING: ============================================================\n```\n\n## Nginx Behavior in Registry-Only Mode\n\nWhen `DEPLOYMENT_MODE=registry-only`:\n\n1. **Server Registration:** Nginx configuration is NOT updated\n2. **Server Deletion:** Nginx configuration is NOT updated\n3. **MCP Proxy Requests:** Return 503 with JSON error:\n\n```json\n{\n \"error\": \"gateway_proxy_disabled\",\n \"message\": \"Gateway proxy is disabled in registry-only mode. Use proxy_pass_url from server metadata for direct connection.\"\n}\n```\n\nThe 503 response applies to all paths except:\n- `/api/*` - Registry API endpoints\n- `/oauth2/*` - Authentication endpoints\n- `/keycloak/*`, `/realms/*`, `/resources/*` - Keycloak paths\n- `/v0.1/*` - Anthropic-compatible API\n- `/health` - Health check\n- `/static/*`, `/assets/*`, `/_next/*` - Static assets\n- `/validate` - Token validation\n\n## CLI Testing\n\nUse the registry management CLI to check configuration:\n\n```bash\n# Check current configuration\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n config --json\n\n# Output formatted for readability\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n config\n```\n\n## Related Documentation\n\n- [Configuration Reference](configuration.md) - All environment variables\n- [AWS ECS Deployment](../terraform/aws-ecs/README.md) - Production deployment guide\n- [Static Token Auth](static-token-auth.md) - API authentication without IdP\n" }, { "path": "docs/registry_api.md", "content": "# MCP Gateway Registry API Documentation\n\nThis document provides a comprehensive overview of all API endpoints available in the MCP Gateway Registry service.\n\n## Table of Contents\n\n- [Authentication](#authentication)\n - [OAuth2 Login](#oauth2-login)\n - [Logout](#logout)\n- [Server Management](#server-management)\n - [Register a New Service](#register-a-new-service)\n - [Toggle Service Status](#toggle-service-status)\n - [Edit Service Details](#edit-service-details)\n- [API Endpoints](#api-endpoints)\n - [Get Server Details](#get-server-details)\n - [Get Service Tools](#get-service-tools)\n - [Refresh Service](#refresh-service)\n- [WebSocket Endpoints](#websocket-endpoints)\n - [Health Status Updates](#health-status-updates)\n\n## Authentication\n\n> **IMPORTANT**: Most endpoints in this API require authentication via OAuth2 (Keycloak). Users authenticate through the browser-based OAuth2 flow, which sets a session cookie. The examples below use `-b cookies.txt` to include the session cookie in requests. For programmatic API access, use a JWT Bearer token obtained from your OAuth2 provider.\n\n### OAuth2 Login\n\nAuthentication is handled via OAuth2 providers (Keycloak). Navigate to `/login` in your browser to initiate the OAuth2 flow.\n\n**URL:** `/login`\n**Method:** `GET`\n**Response:** Login page with OAuth2 provider buttons\n\n**URL:** `/auth/{provider}`\n**Method:** `GET`\n**Description:** Redirects to the OAuth2 provider for authentication. After successful authentication, a session cookie is set automatically.\n\n### Logout\n\nLogs out the current user by invalidating their session.\n\n**URL:** `/logout` \n**Method:** `POST` \n**Authentication:** Required (session cookie) \n**Response:** Redirects to `/login`\n\n**Example:**\n\n```bash\ncurl -X POST http://localhost:7860/logout \\\n -b cookies.txt\n```\n\n## Server Management\n\n> **Note**: All endpoints in this section require authentication via a session cookie obtained from the OAuth2 login flow.\n\n### Register a New Service\n\nRegisters a new MCP service with the gateway.\n\n**URL:** `/register` \n**Method:** `POST` \n**Content-Type:** `application/x-www-form-urlencoded` \n**Authentication:** Required (session cookie) \n**Parameters:**\n- `name` (required): Display name of the service\n- `description` (required): Description of the service\n- `path` (required): URL path for the service\n- `proxy_pass_url` (required): URL to proxy requests to\n- `tags` (optional): Comma-separated list of tags\n- `num_tools` (optional): Number of tools provided by the service\n- `num_stars` (optional): Star rating for the service\n- `is_python` (optional): Whether the service is Python-based\n- `license` (optional): License information\n- `metadata` (optional): JSON object with custom metadata for organization, compliance, and integration tracking. Fully searchable via semantic search.\n\n**Metadata Examples:**\n```json\n{\n \"team\": \"data-platform\",\n \"owner\": \"alice@example.com\",\n \"compliance_level\": \"PCI-DSS\",\n \"cost_center\": \"engineering\",\n \"deployment_region\": \"us-east-1\"\n}\n```\n\n**Response:**\n- Success: JSON response with status code 201\n- Failure: JSON response with error details\n\n**Example:**\n\n```bash\n# Uses the session cookie from the login request\ncurl -X POST http://localhost:7860/register \\\n -b cookies.txt \\\n -d \"name=Weather Service&description=Provides weather forecasts&path=/weather&proxy_pass_url=http://localhost:8000&tags=weather,forecast&num_tools=3&num_stars=4&is_python=true&license=MIT\"\n```\n\n### Toggle Service Status\n\nEnables or disables a registered service.\n\n**URL:** `/toggle/{service_path}` \n**Method:** `POST` \n**Content-Type:** `application/x-www-form-urlencoded` \n**Authentication:** Required (session cookie) \n**URL Parameters:**\n- `service_path`: Path of the service to toggle\n**Form Parameters:**\n- `enabled`: \"on\" to enable, omit to disable\n\n**Response:** JSON with updated service status\n\n**Example:**\n\n```bash\n# Enable a service (requires session cookie)\ncurl -X POST http://localhost:7860/toggle/weather \\\n -b cookies.txt \\\n -d \"enabled=on\"\n\n# Disable a service (requires session cookie)\ncurl -X POST http://localhost:7860/toggle/weather \\\n -b cookies.txt\n```\n\n### Edit Service Details\n\nUpdates the details of an existing service.\n\n**URL:** `/edit/{service_path}` \n**Method:** `POST` \n**Content-Type:** `application/x-www-form-urlencoded` \n**Authentication:** Required (session cookie) \n**URL Parameters:**\n- `service_path`: Path of the service to edit\n**Form Parameters:**\n- `name` (required): Display name of the service\n- `proxy_pass_url` (required): URL to proxy requests to\n- `description` (optional): Description of the service\n- `tags` (optional): Comma-separated list of tags\n- `num_tools` (optional): Number of tools provided by the service\n- `num_stars` (optional): Star rating for the service\n- `is_python` (optional): Whether the service is Python-based\n- `license` (optional): License information\n\n**Response:** Redirects to the main page on success\n\n**Example:**\n\n```bash\n# Requires session cookie from login\ncurl -X POST http://localhost:7860/edit/weather \\\n -b cookies.txt \\\n -d \"name=Weather API&description=Updated weather service&proxy_pass_url=http://localhost:8001&tags=weather,api&num_tools=5&num_stars=5&is_python=true&license=MIT\"\n```\n\n## API Endpoints\n\n> **Note**: All endpoints in this section require authentication via a session cookie obtained from the OAuth2 login flow.\n\n### Get Server Details\n\nRetrieves detailed information about a registered service.\n\n**URL:** `/api/server_details/{service_path}` \n**Method:** `GET` \n**Authentication:** Required (session cookie) \n**URL Parameters:**\n- `service_path`: Path of the service to get details for, or \"all\" to get details for all services\n\n**Response:** JSON with server details\n\n**Example:**\n\n```bash\n# Get details for a specific service (requires session cookie)\ncurl -X GET http://localhost:7860/api/server_details/weather \\\n -b cookies.txt\n\n# Get details for all services (requires session cookie)\ncurl -X GET http://localhost:7860/api/server_details/all \\\n -b cookies.txt\n```\n\n### Get Service Tools\n\nRetrieves the list of tools provided by a service.\n\n**URL:** `/api/tools/{service_path}` \n**Method:** `GET` \n**Authentication:** Required (session cookie) \n**URL Parameters:**\n- `service_path`: Path of the service to get tools for, or \"all\" to get tools from all services\n\n**Response:** JSON with tool details\n\n**Example:**\n\n```bash\n# Get tools for a specific service (requires session cookie)\ncurl -X GET http://localhost:7860/api/tools/weather \\\n -b cookies.txt\n\n# Get tools from all services (requires session cookie)\ncurl -X GET http://localhost:7860/api/tools/all \\\n -b cookies.txt\n```\n\n### Refresh Service\n\nManually triggers a health check and tool discovery for a service.\n\n**URL:** `/api/refresh/{service_path}` \n**Method:** `POST` \n**Authentication:** Required (session cookie) \n**URL Parameters:**\n- `service_path`: Path of the service to refresh\n\n**Response:** JSON with updated service status\n\n**Example:**\n\n```bash\n# Requires session cookie from login\ncurl -X POST http://localhost:7860/api/refresh/weather \\\n -b cookies.txt\n```\n\n## WebSocket Endpoints\n\n### Health Status Updates\n\nProvides real-time updates on the health status of all registered services.\n\n**URL:** `/ws/health_status` \n**Protocol:** WebSocket \n**Authentication:** Not required (public endpoint) \n**Response:** JSON messages with health status updates\n\n**Example using websocat:**\n\nFirst, install websocat:\n\n```bash\nsudo wget -qO /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl\nsudo chmod +x /usr/local/bin/websocat\n```\n\nThen connect to the WebSocket endpoint:\n\n```bash\nwebsocat ws://localhost:7860/ws/health_status\n```\n\nThis will display the JSON messages with health status updates in real-time in your terminal.\n\n**Example using Python:**\n\n```python\n# Python example using websockets library\nimport asyncio\nimport json\nimport websockets\n\nasync def health_status_monitor():\n uri = \"ws://localhost:7860/ws/health_status\"\n async with websockets.connect(uri) as websocket:\n print(\"WebSocket connection established\")\n \n while True:\n try:\n # Receive health status updates\n message = await websocket.recv()\n data = json.loads(message)\n \n print(\"Health status update received:\")\n for path, info in data.items():\n print(f\"Service {path}: {info['status']}\")\n print(f\"Last checked: {info['last_checked_iso']}\")\n print(f\"Number of tools: {info['num_tools']}\")\n print(\"---\")\n except websockets.exceptions.ConnectionClosed:\n print(\"Connection closed\")\n break\n\n# Run the async function\nasyncio.run(health_status_monitor())\n```\n\n## Authentication Flow\n\n1. **Login**: Navigate to `/login` in your browser and authenticate via your OAuth2 provider (Keycloak). The session cookie is set automatically after successful authentication.\n\n2. **Programmatic Access**: For API access, obtain a JWT Bearer token from your OAuth2 provider and include it in the `Authorization` header:\n ```bash\n curl -X GET http://localhost:7860/api/server_details/all \\\n -H \"Authorization: Bearer \"\n ```\n\n3. **Session Expiration**: The session cookie is valid for 8 hours. After expiration, you'll need to login again.\n\n## API Summary\n\n* `GET /login`: Display login page with OAuth2 provider options.\n* `GET /auth/{provider}`: Redirect to OAuth2 provider for authentication.\n* `POST /logout`: Log out user and invalidate session cookie.\n* `GET /`: Main dashboard (web UI, requires authentication).\n* `GET /edit/{service_path}`: Edit service form (web UI, requires authentication).\n* `POST /register`: Register a new service (requires authentication).\n* `POST /toggle/{service_path}`: Enable/disable a service (requires authentication).\n* `POST /edit/{service_path}`: Update service details (requires authentication).\n* `GET /api/server_details/{service_path}`: Get full details for a service (requires authentication).\n* `GET /api/tools/{service_path}`: Get the discovered tool list for a service (requires authentication).\n* `POST /api/refresh/{service_path}`: Manually trigger a health check/tool update (requires authentication).\n* `WebSocket /ws/health_status`: Real-time connection for receiving server health status updates." }, { "path": "docs/remote-desktop-setup.md", "content": "# Remote Desktop Setup for Ubuntu 24.04 AWS EC2\n\nThis guide explains how to set up remote desktop access on an Ubuntu 24.04 AWS EC2 instance so you can connect from a Windows machine.\n\n## System Information\n\nThis setup is tested on:\n- **OS**: Ubuntu 24.04 LTS (AWS EC2)\n- **Architecture**: x86_64\n- **Kernel**: Linux 6.14.0-1011-aws\n\n## Option 1: XRDP (Recommended for Windows RDP)\n\nXRDP allows you to use Windows' built-in Remote Desktop Connection to connect to your Ubuntu machine.\n\n### Installation Steps\n\n1. **Update the system**:\n ```bash\n sudo apt update && sudo apt upgrade -y\n ```\n\n2. **Install desktop environment (XFCE - lightweight)**:\n ```bash\n sudo apt install -y xfce4 xfce4-goodies\n ```\n\n3. **Install XRDP**:\n ```bash\n sudo apt install -y xrdp\n ```\n\n4. **Configure XRDP to use XFCE**:\n ```bash\n echo \"xfce4-session\" > ~/.xsession\n ```\n\n5. **Start and enable XRDP service**:\n ```bash\n sudo systemctl enable xrdp\n sudo systemctl start xrdp\n ```\n\n6. **Configure firewall** (if ufw is enabled):\n ```bash\n sudo ufw allow 3389\n ```\n\n7. **Set password for ubuntu user**:\n ```bash\n sudo passwd ubuntu\n ```\n\n### Install Firefox Browser\n\n```bash\nsudo apt install -y firefox\n```\n\n## Option 2: VNC Server (Alternative)\n\nVNC provides cross-platform remote desktop access but requires a separate VNC client.\n\n### Installation Steps\n\n1. **Install VNC server and desktop**:\n ```bash\n sudo apt update\n sudo apt install -y ubuntu-desktop-minimal tigervnc-standalone-server tigervnc-common\n ```\n\n2. **Set VNC password**:\n ```bash\n vncpasswd\n ```\n\n3. **Start VNC server**:\n ```bash\n vncserver :1 -geometry 1920x1080 -depth 24\n ```\n\n4. **Configure firewall**:\n ```bash\n sudo ufw allow 5901\n ```\n\n## AWS Security Group Configuration\n\n**Important**: You must configure your AWS Security Group to allow remote desktop connections.\n\n1. Go to AWS Console → EC2 → Security Groups\n2. Select your instance's security group\n3. Add inbound rule:\n - **For XRDP**:\n - Type: Custom TCP\n - Port: 3389\n - Source: Your IP address (for security)\n - **For VNC**:\n - Type: Custom TCP\n - Port: 5901\n - Source: Your IP address (for security)\n\n## Connecting from Windows\n\n### Using XRDP (Option 1)\n1. Open \"Remote Desktop Connection\" (built into Windows)\n2. Computer: `your-ec2-hostname:3389` or `your-ec2-public-ip:3389`\n3. Username: `ubuntu`\n4. Password: The password you set with `sudo passwd ubuntu`\n\n### Using VNC (Option 2)\n1. Install a VNC client (like RealVNC Viewer)\n2. Connect to: `your-ec2-hostname:5901` or `your-ec2-public-ip:5901`\n3. Enter the VNC password you set with `vncpasswd`\n\n## Troubleshooting\n\n### XRDP Issues\n- **Black screen**: Make sure you set the session with `echo \"xfce4-session\" > ~/.xsession`\n- **Connection refused**: Check if XRDP is running: `sudo systemctl status xrdp`\n- **Can't connect**: Verify AWS Security Group allows port 3389\n\n### VNC Issues\n- **Display not found**: Start VNC server with `vncserver :1`\n- **Connection timeout**: Check AWS Security Group allows port 5901\n- **Poor performance**: Try reducing color depth: `vncserver :1 -depth 16`\n\n### General Network Issues\n- Verify your EC2 instance's public IP hasn't changed\n- Check that your home/office IP is allowed in the security group\n- Ensure the EC2 instance is running and accessible via SSH\n\n## Security Considerations\n\n- **Limit source IPs**: Always restrict remote desktop access to your specific IP addresses\n- **Use strong passwords**: Set complex passwords for user accounts\n- **Consider VPN**: For production environments, consider accessing through a VPN\n- **Disable when not needed**: Stop XRDP/VNC services when not in use:\n ```bash\n sudo systemctl stop xrdp # For XRDP\n vncserver -kill :1 # For VNC\n ```\n\n## Performance Tips\n\n- **XFCE is lightweight**: We chose XFCE desktop environment for better performance over RDP\n- **Adjust resolution**: Use appropriate screen resolution for your connection speed\n- **Close unused applications**: Remote desktop uses bandwidth, so close unnecessary programs\n- **Use compression**: Some RDP clients offer compression options for slower connections" }, { "path": "docs/scan_report_example.md", "content": "# MCP Server Security Scan Report\n\n**Scan Date:** 2025-10-21 23:50:03 UTC\n**Analyzers Used:** yara\n\n## Executive Summary\n\n- **Total Servers Scanned:** 5\n- **Passed:** 4 (80%)\n- **Failed:** 1 (20%)\n\n### Aggregate Vulnerability Statistics\n\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 1 |\n| Medium | 0 |\n| Low | 0 |\n\n## Per-Server Scan Results\n\n### io.mcpgateway/currenttime\n\n- **URL:** `https://mcpgateway.ddns.net/currenttime/mcp`\n- **Status:** ✅ SAFE\n\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 0 |\n| Medium | 0 |\n| Low | 0 |\n\n### io.mcpgateway/fininfo\n\n- **URL:** `https://mcpgateway.ddns.net/fininfo/mcp`\n- **Status:** ✅ SAFE\n\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 0 |\n| Medium | 0 |\n| Low | 0 |\n\n**Error:** Scanner exit code: 1\n\n### io.mcpgateway/mcpgw\n\n- **URL:** `https://mcpgateway.ddns.net/mcpgw/mcp`\n- **Status:** ❌ UNSAFE\n\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 1 |\n| Medium | 0 |\n| Low | 0 |\n\n#### Detailed Findings\n\n**Tool: `healthcheck`**\n\n- **Analyzer:** yara_analyzer\n- **Severity:** HIGH\n- **Threats:** INJECTION ATTACK\n- **Summary:** Detected 1 threat: sql injection\n\n**Taxonomy:**\n```json\n{\n \"scanner_category\": \"INJECTION ATTACK\",\n \"aitech\": \"AITech-9.1\",\n \"aitech_name\": \"Model or Agentic System Manipulation\",\n \"aisubtech\": \"AISubtech-9.1.4\",\n \"aisubtech_name\": \"Injection Attacks (SQL, Command Execution, XSS)\",\n \"description\": \"Injecting malicious payloads such as SQL queries, command sequences, or scripts into MCP servers or tools that process model or user input, leading to data exposure, remote code execution, or compromise of the underlying system environment.\"\n}\n```\n\n
\nTool Description\n\n```\nRetrieves health status information from all registered MCP servers via the registry's internal API.\n\nReturns:\n Dict[str, Any]: Health status information for all registered servers, including:\n - status: 'healthy' or 'disabled'\n - last_checked_iso: ISO timestamp of when the server was last checked\n - num_tools: Number of tools provided by the server\n\nRaises:\n Exception: If the API call fails or data cannot be retrieved\n```\n
\n\n**Error:** Scanner exit code: 1\n\n### io.mcpgateway/realserverfaketools\n\n- **URL:** `https://mcpgateway.ddns.net/realserverfaketools/mcp`\n- **Status:** ✅ SAFE\n\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 0 |\n| Medium | 0 |\n| Low | 0 |\n\n### io.mcpgateway/sre-gateway\n\n- **URL:** `https://mcpgateway.ddns.net/sre-gateway/mcp`\n- **Status:** ✅ SAFE\n\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 0 |\n| Medium | 0 |\n| Low | 0 |\n\n**Error:** Scanner exit code: 1\n\n---\n\n*Report generated on 2025-10-21 23:50:03 UTC*\n" }, { "path": "docs/scopes-mgmt.md", "content": "# Scopes Management\n\nThis document describes the scope configuration file format used by the MCP Gateway Registry for fine-grained access control.\n\n## Overview\n\nScopes define what resources (MCP servers, agents) users can access and what actions they can perform. The registry uses JSON-based scope configuration files that can be loaded during initialization or managed via the CLI.\n\n## Scope Configuration File Format\n\n### Example Files\n\n- `scripts/registry-admins.json` - Bootstrap admin scope loaded during database initialization\n- `cli/examples/public-mcp-users.json` - Example scope for users with limited access\n\n### Complete Field Reference\n\n```json\n{\n \"_id\": \"scope-name\",\n \"scope_name\": \"scope-name\",\n \"description\": \"Human-readable description of this scope\",\n \"group_mappings\": [\"group-name-1\", \"group-uuid-2\"],\n \"server_access\": [\n {\n \"server\": \"server-name\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"tool-name-1\", \"tool-name-2\"]\n },\n {\n \"agents\": {\n \"actions\": [\n {\"action\": \"list_agents\", \"resources\": [\"/agent-path\"]},\n {\"action\": \"get_agent\", \"resources\": [\"/agent-path\"]}\n ]\n }\n }\n ],\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"get_agent\": [\"/specific-agent\"],\n \"publish_agent\": [],\n \"list_service\": [\"all\"],\n \"toggle_service\": [\"service-name\"]\n },\n \"create_in_idp\": true\n}\n```\n\n## Field Descriptions\n\n### Top-Level Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `_id` | string | Yes | Unique identifier for the scope document in MongoDB. Should match `scope_name`. |\n| `scope_name` | string | No | Human-readable scope name. If omitted, `_id` is used. |\n| `description` | string | No | Description explaining the purpose of this scope. |\n| `group_mappings` | array | Yes | List of IdP group names or IDs that map to this scope. |\n| `server_access` | array | Yes | List of MCP server access rules and agent action permissions. |\n| `ui_permissions` | object | No | UI-level permissions for the registry web interface. |\n| `create_in_idp` | boolean | No | When true, the CLI will create the group in the IdP (Keycloak/Entra). |\n\n### group_mappings Field\n\nThe `group_mappings` array contains IdP group identifiers that should be mapped to this scope. When a user authenticates, their IdP groups are matched against these mappings to determine their effective scopes.\n\n**Important for Entra ID:**\n- Entra ID uses Group Object IDs (GUIDs), not group names\n- You must include the Group Object ID from Azure Portal > Groups > Overview\n- Example: `\"5f605d68-06bc-4208-b992-bb378eee12c5\"`\n\n**For Keycloak:**\n- Use the group name as defined in Keycloak\n- Example: `\"public-mcp-users\"`\n\n**Example with both:**\n```json\n{\n \"group_mappings\": [\n \"public-mcp-users\",\n \"5f605d68-06bc-4208-b992-bb378eee12c5\"\n ]\n}\n```\n\nThis means users in either the Keycloak group `public-mcp-users` OR the Entra ID group with Object ID `5f605d68-06bc-4208-b992-bb378eee12c5` will receive this scope.\n\n### server_access Field\n\nThe `server_access` array defines what MCP servers and methods users can access. Each entry can be either a server access rule or an agent actions block.\n\n#### Server Access Rule\n\n```json\n{\n \"server\": \"server-name-or-wildcard\",\n \"methods\": [\"method-1\", \"method-2\"],\n \"tools\": [\"tool-name-or-wildcard\"]\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `server` | Server name or `\"*\"` for all servers |\n| `methods` | List of allowed MCP methods (see below) |\n| `tools` | List of allowed tool names or `[\"*\"]` for all tools |\n\n**Standard MCP Methods:**\n- `initialize` - Initialize MCP session\n- `notifications/initialized` - Session initialized notification\n- `ping` - Health check\n- `tools/list` - List available tools\n- `tools/call` - Execute a tool\n- `resources/list` - List available resources\n- `resources/templates/list` - List resource templates\n- `GET`, `POST`, `PUT`, `DELETE` - HTTP methods for REST API access\n\n**Example - Full MCP access to specific servers:**\n```json\n{\n \"server\": \"context7\",\n \"methods\": [\n \"initialize\",\n \"notifications/initialized\",\n \"ping\",\n \"tools/list\",\n \"tools/call\",\n \"resources/list\",\n \"resources/templates/list\"\n ],\n \"tools\": [\"*\"]\n}\n```\n\n**Example - Wildcard access (admin):**\n```json\n{\n \"server\": \"*\",\n \"methods\": [\"all\"],\n \"tools\": [\"all\"]\n}\n```\n\n#### Agent Actions Block\n\nAgent actions define what operations users can perform on A2A agents.\n\n```json\n{\n \"agents\": {\n \"actions\": [\n {\"action\": \"action-name\", \"resources\": [\"/agent-path-1\", \"/agent-path-2\"]}\n ]\n }\n}\n```\n\n**Available Agent Actions:**\n\n| Action | Description | API Endpoint |\n|--------|-------------|--------------|\n| `list_agents` | View agents in listings | `GET /api/agents` |\n| `get_agent` | View agent details | `GET /api/agents/{path}` |\n| `publish_agent` | Register new agents | `POST /api/agents/register` |\n| `modify_agent` | Update existing agents | `PUT /api/agents/{path}` |\n| `delete_agent` | Remove agents | `DELETE /api/agents/{path}` |\n\n**Resource Patterns:**\n- `/agent-name` - Specific agent path (e.g., `/flight-booking`)\n- `all` - All agents (wildcard access)\n\n**Example - Limited agent access:**\n```json\n{\n \"agents\": {\n \"actions\": [\n {\"action\": \"list_agents\", \"resources\": [\"/flight-booking\", \"/code-reviewer\"]},\n {\"action\": \"get_agent\", \"resources\": [\"/flight-booking\", \"/code-reviewer\"]}\n ]\n }\n}\n```\n\n**Example - Full agent admin access:**\n```json\n{\n \"agents\": {\n \"actions\": [\n {\"action\": \"list_agents\", \"resources\": [\"all\"]},\n {\"action\": \"get_agent\", \"resources\": [\"all\"]},\n {\"action\": \"publish_agent\", \"resources\": [\"all\"]},\n {\"action\": \"modify_agent\", \"resources\": [\"all\"]},\n {\"action\": \"delete_agent\", \"resources\": [\"all\"]}\n ]\n }\n}\n```\n\n### ui_permissions Field\n\nUI permissions control what actions users can perform in the web interface and REST API for service/agent management.\n\n```json\n{\n \"ui_permissions\": {\n \"permission_name\": [\"resource-1\", \"resource-2\"]\n }\n}\n```\n\n**Available UI Permissions:**\n\n| Permission | Description | Applies To |\n|------------|-------------|------------|\n| `list_agents` | View agents in UI | Agent paths or `\"all\"` |\n| `get_agent` | View agent details | Agent paths or `\"all\"` |\n| `publish_agent` | Register new agents via UI | Agent paths or `\"all\"` |\n| `modify_agent` | Edit agents via UI | Agent paths or `\"all\"` |\n| `delete_agent` | Delete agents via UI | Agent paths or `\"all\"` |\n| `list_service` | View MCP servers in UI | Server names or `\"all\"` |\n| `register_service` | Register new MCP servers | Server names or `\"all\"` |\n| `health_check_service` | Run health checks | Server names or `\"all\"` |\n| `toggle_service` | Enable/disable servers | Server names or `\"all\"` |\n| `modify_service` | Edit server configurations | Server names or `\"all\"` |\n\n**Example - Read-only access:**\n```json\n{\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n }\n}\n```\n\n**Example - Full admin access:**\n```json\n{\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"get_agent\": [\"all\"],\n \"publish_agent\": [\"all\"],\n \"modify_agent\": [\"all\"],\n \"delete_agent\": [\"all\"],\n \"list_service\": [\"all\"],\n \"register_service\": [\"all\"],\n \"health_check_service\": [\"all\"],\n \"toggle_service\": [\"all\"],\n \"modify_service\": [\"all\"]\n }\n}\n```\n\n## Complete Examples\n\n### Admin Scope (registry-admins.json)\n\nFull access to all servers, agents, and UI functions:\n\n```json\n{\n \"_id\": \"registry-admins\",\n \"group_mappings\": [\"registry-admins\"],\n \"server_access\": [\n {\n \"server\": \"*\",\n \"methods\": [\"all\"],\n \"tools\": [\"all\"]\n },\n {\n \"agents\": {\n \"actions\": [\n {\"action\": \"list_agents\", \"resources\": [\"all\"]},\n {\"action\": \"get_agent\", \"resources\": [\"all\"]},\n {\"action\": \"publish_agent\", \"resources\": [\"all\"]},\n {\"action\": \"modify_agent\", \"resources\": [\"all\"]},\n {\"action\": \"delete_agent\", \"resources\": [\"all\"]}\n ]\n }\n }\n ],\n \"ui_permissions\": {\n \"list_agents\": [\"all\"],\n \"get_agent\": [\"all\"],\n \"publish_agent\": [\"all\"],\n \"modify_agent\": [\"all\"],\n \"delete_agent\": [\"all\"],\n \"list_service\": [\"all\"],\n \"register_service\": [\"all\"],\n \"health_check_service\": [\"all\"],\n \"toggle_service\": [\"all\"],\n \"modify_service\": [\"all\"]\n }\n}\n```\n\n### Limited User Scope (public-mcp-users.json)\n\nAccess to specific MCP servers and one agent:\n\n```json\n{\n \"scope_name\": \"public-mcp-users\",\n \"description\": \"Users with access to public MCP servers and flight-booking agent\",\n \"server_access\": [\n {\n \"server\": \"context7\",\n \"methods\": [\n \"initialize\",\n \"notifications/initialized\",\n \"ping\",\n \"tools/list\",\n \"tools/call\",\n \"resources/list\",\n \"resources/templates/list\"\n ],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"initialize\", \"GET\", \"POST\", \"servers\", \"agents\", \"search\"],\n \"tools\": []\n },\n {\n \"agents\": {\n \"actions\": [\n {\"action\": \"list_agents\", \"resources\": [\"/flight-booking\"]},\n {\"action\": \"get_agent\", \"resources\": [\"/flight-booking\"]}\n ]\n }\n }\n ],\n \"group_mappings\": [\n \"public-mcp-users\",\n \"5f605d68-06bc-4208-b992-bb378eee12c5\"\n ],\n \"ui_permissions\": {\n \"list_service\": [\"all\"],\n \"list_agents\": [\"/flight-booking\"],\n \"get_agent\": [\"/flight-booking\"]\n },\n \"create_in_idp\": true\n}\n```\n\n## Managing Scopes\n\n### Using the CLI\n\nImport a scope from JSON file:\n```bash\nuv run python api/registry_management.py \\\n --token-file .token \\\n --registry-url https://registry.example.com \\\n import-group cli/examples/public-mcp-users.json\n```\n\nList all scopes:\n```bash\nuv run python api/registry_management.py \\\n --token-file .token \\\n --registry-url https://registry.example.com \\\n list-groups\n```\n\n### Bootstrap Admin Scope\n\nThe `registry-admins` scope is automatically loaded during database initialization:\n- **Local (MongoDB CE)**: `docker compose up mongodb-init`\n- **Production (DocumentDB)**: `./terraform/aws-ecs/scripts/run-documentdb-init.sh`\n\n### Server Path Variations\n\nWhen defining server access, you may need to include path variations to handle different URL patterns:\n\n```json\n{\n \"server_access\": [\n {\"server\": \"context7\", \"methods\": [...], \"tools\": [\"*\"]},\n {\"server\": \"/context7\", \"methods\": [...], \"tools\": [\"*\"]},\n {\"server\": \"/context7/\", \"methods\": [...], \"tools\": [\"*\"]}\n ]\n}\n```\n\nThis ensures access works regardless of whether the server is accessed as:\n- `context7`\n- `/context7`\n- `/context7/`\n\n## Entra ID Integration\n\nWhen using Microsoft Entra ID (Azure AD) as the identity provider:\n\n1. **Create a group in Azure Portal:**\n - Navigate to Azure Portal > Azure Active Directory > Groups\n - Create a new Security group\n - Note the Group Object ID (GUID)\n\n2. **Add the Object ID to group_mappings:**\n ```json\n {\n \"group_mappings\": [\n \"my-keycloak-group\",\n \"12345678-1234-1234-1234-123456789012\"\n ]\n }\n ```\n\n3. **Assign users to the Azure AD group:**\n - Users in this group will receive the scope permissions when they authenticate\n\n4. **Configure Entra ID app to include groups in tokens:**\n - In the App Registration, configure the `groups` claim\n - Set `groupMembershipClaims` to `\"SecurityGroup\"` in the manifest\n\n## Troubleshooting\n\n### User Not Getting Expected Permissions\n\n1. Check group membership in IdP (Keycloak/Entra)\n2. Verify `group_mappings` includes the correct group name/ID\n3. Check registry logs for scope mapping messages\n4. Use the debug endpoint: `GET /api/debug/user-context`\n\n### Scope Not Found\n\n1. Ensure the scope was imported: `list-groups` command\n2. Check MongoDB collection: `mcp_scopes_default`\n3. Re-run database initialization if bootstrap scope missing\n\n### Entra ID Groups Not Working\n\n1. Verify Group Object ID (not display name) is in `group_mappings`\n2. Check that `groupMembershipClaims` is configured in app manifest\n3. Verify user is assigned to the group in Azure Portal\n4. Check that optional claims include `groups` in ID token\n" }, { "path": "docs/scopes.md", "content": "# Fine-Grained Access Control System Documentation\n\n> **Note**: While this document discusses Fine-Grained Access Control (FGAC) in the context of Amazon Cognito, the concepts and implementation apply to any Identity Provider (IdP). The same scope-based authorization model can be used with other OAuth2/OIDC providers by adapting the group mapping and token validation mechanisms.\n\nThis document provides comprehensive documentation for the fine-grained access control system in the MCP Gateway Registry, explaining how the scope-based authorization model works and how to configure it properly.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Scope System Architecture](#scope-system-architecture)\n3. [Scope Types and Structure](#scope-types-and-structure)\n4. [Methods vs Tools Access Control](#methods-vs-tools-access-control)\n5. [Cognito Integration](#cognito-integration)\n6. [Scope Validation Logic](#scope-validation-logic)\n7. [Configuration Examples](#configuration-examples)\n8. [Virtual MCP Server Access Control](#virtual-mcp-server-access-control)\n9. [Security Considerations](#security-considerations)\n10. [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThe MCP Gateway Registry implements a sophisticated fine-grained access control system that provides granular permissions for accessing MCP servers, methods, and tools. The system is built around a scope-based authorization model that:\n\n- Maps Amazon Cognito user groups to MCP server scopes\n- Controls access to specific MCP servers, methods, and individual tools\n- Supports both user identity mode (OAuth2 PKCE) and agent identity mode (Machine-to-Machine)\n- Uses hierarchical scope validation for precise permission control\n- Follows the principle of least privilege by default\n\nThe access control system is defined in [`auth_server/scopes.yml`](../auth_server/scopes.yml) and enforced by the validation logic in [`auth_server/server.py`](../auth_server/server.py).\n\n## Scope System Architecture\n\n### Core Components\n\nThe access control system consists of three main components:\n\n1. **Scope Configuration** ([`auth_server/scopes.yml`](../auth_server/scopes.yml)): Defines all available scopes and their permissions\n2. **Group Mappings**: Maps Amazon Cognito groups to both UI and server scopes\n3. **Validation Engine** ([`auth_server/server.py`](../auth_server/server.py)): Enforces access control decisions\n\n### Authentication Flow Integration\n\nThe scope system integrates seamlessly with both authentication modes:\n\n- **User Identity Mode**: Users authenticate via OAuth2 PKCE, and their Cognito groups are mapped to scopes\n- **Agent Identity Mode**: Agents authenticate via M2M JWT tokens with custom scopes directly assigned\n\n### Relationship with Cognito\n\nThe system leverages Amazon Cognito's group membership feature to assign permissions:\n\n1. Users are assigned to Cognito groups (e.g., `mcp-registry-admin`, `mcp-registry-user`)\n2. Groups are mapped to scopes via the `group_mappings` configuration\n3. Scopes define specific permissions for UI operations and MCP server access\n4. The validation engine checks these scopes against requested operations\n\n## Scope Types and Structure\n\nThe system defines several types of scopes, each serving different purposes:\n\n### UI Scopes\n\nUI scopes control access to registry management functions through the web interface:\n\n- **`mcp-registry-admin`**: Full administrative access to all registry functions\n- **`mcp-registry-user`**: Limited user access to specific servers and operations\n- **`mcp-registry-developer`**: Developer access for service registration and management\n- **`mcp-registry-operator`**: Operational access for service control without registration rights\n\n#### UI Scope Permissions\n\nEach UI scope defines permissions for specific registry operations:\n\n```yaml\nUI-Scopes:\n mcp-registry-admin:\n list_service: [all] # Can list all services\n register_service: [all] # Can register any service\n health_check_service: [all] # Can check health of all services\n toggle_service: [all] # Can enable/disable all services\n modify_service: [all] # Can modify all services\n```\n\n### Server Scopes\n\nServer scopes control access to MCP servers with read and execute permissions:\n\n- **`mcp-servers-unrestricted/read`**: Read access to all MCP servers and tools\n- **`mcp-servers-unrestricted/execute`**: Execute access to all MCP servers and tools\n- **`mcp-servers-restricted/read`**: Limited read access to specific servers and tools\n- **`mcp-servers-restricted/execute`**: Limited execute access to specific servers and tools\n\n#### Permission Levels\n\n- **Read Permission**: Allows listing tools and reading server information\n- **Execute Permission**: Allows calling tools and executing server methods\n\n### Group Mappings\n\nGroup mappings connect Cognito groups to both UI and server scopes:\n\n```yaml\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin # UI permissions\n - mcp-servers-unrestricted/read # Server read access\n - mcp-servers-unrestricted/execute # Server execute access\n mcp-registry-user:\n - mcp-registry-user # Limited UI permissions\n - mcp-servers-restricted/read # Limited server access\n```\n\n> **Important**: All group names (such as `mcp-registry-admin`, `mcp-registry-user`) and scope names (such as `mcp-servers-unrestricted/read`, `mcp-servers-restricted/execute`) are completely customizable by the platform administrator deploying this solution. These names are examples and can be changed to match your organization's naming conventions and security requirements. The same group names must be configured consistently in both your Identity Provider (IdP) and the `scopes.yml` configuration file.\n\n## Methods vs Tools Access Control\n\nOne of the key features of the access control system is its ability to differentiate between MCP protocol methods and specific tools, providing granular control over what operations users can perform.\n\n### MCP Protocol Methods\n\nMethods are standard MCP protocol operations that all servers support:\n\n- **`initialize`**: Initialize connection with the server\n- **`notifications/initialized`**: Handle initialization notifications\n- **`ping`**: Health check operation\n- **`tools/list`**: List available tools on the server\n- **`tools/call`**: Call a specific tool (requires additional tool-level validation)\n\n### Tool-Specific Access Control\n\nTools are server-specific functions that can be called via the `tools/call` method. The system provides two levels of validation:\n\n1. **Method-Level Validation**: Check if the user can call `tools/call`\n2. **Tool-Level Validation**: Check if the user can call the specific tool\n\n#### Validation Logic for `tools/call`\n\nWhen a user attempts to call a tool via `tools/call`, the system performs enhanced validation:\n\n```python\n# For tools/call, check if the specific tool is allowed\nif method == 'tools/call' and tool_name:\n if tool_name in allowed_tools:\n # Access granted - user can call this specific tool\n return True\n else:\n # Access denied - user cannot call this tool\n return False\n```\n\n#### Example: Tool Access Configuration\n\n```yaml\nmcp-servers-restricted/execute:\n - server: fininfo\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call # Can call tools/call method\n tools:\n - get_stock_aggregates # Can call this specific tool\n - print_stock_data # Can call this specific tool\n # Note: Cannot call other tools like advanced analytics tools\n```\n\n### Access Control Scenarios\n\n#### Scenario 1: Method Access Only\nUser has permission for `tools/list` but not `tools/call`:\n- ✅ Can list available tools\n- ❌ Cannot execute any tools\n\n#### Scenario 2: Method + Specific Tool Access\nUser has permission for `tools/call` and specific tools:\n- ✅ Can call `get_stock_aggregates`\n- ✅ Can call `print_stock_data`\n- ❌ Cannot call `advanced_analytics_tool` (not in allowed tools list)\n\n#### Scenario 3: Unrestricted Access\nUser has unrestricted execute permissions:\n- ✅ Can call any method\n- ✅ Can call any tool listed in the scope configuration\n\n## Cognito Integration\n\nThe access control system integrates deeply with Amazon Cognito for both user and agent authentication modes.\n\n### User Identity Mode Integration\n\nFor users authenticating through the web interface:\n\n1. **User Authentication**: Users log in via OAuth2 PKCE flow\n2. **Group Membership**: Cognito returns user's group memberships\n3. **Scope Mapping**: Groups are mapped to scopes using `group_mappings`\n4. **Session Management**: Scopes are stored in session cookies for subsequent requests\n\n### Agent Identity Mode Integration\n\nFor agents using their own identity:\n\n1. **M2M Authentication**: Agents authenticate using client credentials flow\n2. **Custom Scopes**: Agents are assigned custom scopes directly in Cognito\n3. **JWT Token**: Scopes are embedded in JWT tokens\n4. **Direct Validation**: Scopes are validated directly without group mapping\n\n### Cognito Configuration Requirements\n\n#### User Pool Setup\n- Create user groups matching the scope system (e.g., `mcp-registry-admin`)\n- Assign users to appropriate groups\n- Configure OAuth2 flows for web application access\n\n#### Resource Server Setup (for M2M)\n- Create resource server with identifier (e.g., `mcp-gateway-api`)\n- Define custom scopes matching server scope names\n- Configure client credentials flow for agent applications\n\nFor detailed Cognito setup instructions, see [`docs/cognito.md`](./cognito.md).\n\n## Scope Validation Logic\n\nThe scope validation is implemented in the [`validate_server_tool_access()`](../auth_server/server.py) function, which follows a systematic approach to determine access permissions.\n\n### Validation Algorithm\n\n```python\ndef validate_server_tool_access(server_name: str, method: str, tool_name: str, user_scopes: List[str]) -> bool:\n \"\"\"\n Validate if the user has access to the specified server method/tool based on scopes.\n \n Returns True if access is allowed, False otherwise\n \"\"\"\n```\n\n### Step-by-Step Validation Process\n\n1. **Input Validation**: Validate server name, method, tool name, and user scopes\n2. **Scope Iteration**: Check each user scope for matching permissions\n3. **Server Matching**: Find server configurations that match the requested server\n4. **Method Validation**: Check if the requested method is allowed\n5. **Tool Validation**: For `tools/call`, validate specific tool permissions\n6. **Access Decision**: Grant access if any scope allows the operation\n\n### Validation Flow Diagram\n\n```\nRequest: server_name, method, tool_name, user_scopes\n ↓\nFor each user_scope:\n ↓\nFind scope configuration\n ↓\nFor each server in scope:\n ↓\nDoes server name match?\n ↓ (Yes)\nIs method in allowed_methods?\n ↓ (Yes)\nIs method == 'tools/call'?\n ↓ (Yes) ↓ (No)\nIs tool_name in Grant Access\nallowed_tools?\n ↓ (Yes) ↓ (No)\nGrant Access Continue to next scope\n```\n\n### Access Decision Logic\n\n- **Default Deny**: Access is denied by default if no scope grants permission\n- **First Match Wins**: Access is granted as soon as any scope allows the operation\n- **Explicit Permission Required**: Both method and tool permissions must be explicitly granted\n- **Error Handling**: Access is denied if validation encounters errors\n\n## Configuration Examples\n\n### Example 1: Basic User Setup\n\nCreate a basic user with read-only access to specific servers:\n\n```yaml\n# In scopes.yml\ngroup_mappings:\n mcp-registry-basic-user:\n - mcp-registry-user\n - mcp-servers-restricted/read\n\nmcp-servers-restricted/read:\n - server: currenttime\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n tools:\n - current_time_by_timezone\n```\n\n**Cognito Setup:**\n1. Create group: `mcp-registry-basic-user`\n2. Assign users to this group\n3. Users can list and read time tools but cannot execute them\n\n### Example 2: Developer with Service Management\n\nCreate a developer role with service registration capabilities:\n\n```yaml\ngroup_mappings:\n mcp-registry-developer:\n - mcp-registry-developer\n - mcp-servers-restricted/read\n - mcp-servers-restricted/execute\n\nUI-Scopes:\n mcp-registry-developer:\n list_service: [all]\n register_service: [all]\n health_check_service: [all]\n```\n\n### Example 3: Agent with Specific Tool Access\n\nConfigure an agent with access to specific financial tools:\n\n```yaml\n# Agent scope (assigned directly in Cognito resource server)\nmcp-servers-restricted/execute:\n - server: fininfo\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n tools:\n - get_stock_aggregates\n - print_stock_data\n```\n\n**Cognito Setup:**\n1. Create resource server: `mcp-gateway-api`\n2. Create custom scope: `mcp-servers-restricted/execute`\n3. Assign scope to agent client\n\n### Example 4: Administrative Access\n\nFull administrative access configuration:\n\n```yaml\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n\nUI-Scopes:\n mcp-registry-admin:\n list_service: [all]\n register_service: [all]\n health_check_service: [all]\n toggle_service: [all]\n modify_service: [all]\n```\n\n## Virtual MCP Server Access Control\n\nVirtual MCP Servers use the same access control model as regular MCP servers. The key difference is that you reference the virtual server by its path (e.g., `/virtual/scoped-tools`) instead of a backend server name.\n\n### How It Works\n\nVirtual servers are treated identically to regular MCP servers in scope definitions:\n\n1. **Server Identification**: Use the virtual server path as the `server` value\n2. **Method Control**: Same MCP methods apply (`initialize`, `tools/list`, `tools/call`, etc.)\n3. **Tool Control**: You can restrict access to specific tools exposed by the virtual server\n\n### Example: Virtual Server Scope Configuration\n\n```json\n{\n \"scope_name\": \"virtual-scoped-tools-users\",\n \"description\": \"Users with access to the scoped virtual server\",\n \"server_access\": [\n {\n \"server\": \"/virtual/scoped-tools\",\n \"methods\": [\"initialize\", \"notifications/initialized\", \"ping\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"*\"]\n },\n {\n \"server\": \"api\",\n \"methods\": [\"GET\", \"POST\", \"servers\", \"virtual-servers\", \"search\"],\n \"tools\": []\n }\n ],\n \"group_mappings\": [\"virtual-scoped-tools-users\"],\n \"custom_scopes\": [\"virtual-scoped-tools/access\"],\n \"create_in_idp\": true\n}\n```\n\nSee [virtual-server-scoped-users.json](../cli/examples/virtual-server-scoped-users.json) for the complete example.\n\n### Key Points\n\n| Aspect | Regular MCP Server | Virtual MCP Server |\n|--------|-------------------|-------------------|\n| Server identifier | Server name (e.g., `fininfo`) | Virtual path (e.g., `/virtual/scoped-tools`) |\n| Methods | Standard MCP methods | Same standard MCP methods |\n| Tools | Backend server tools | Aggregated tools (possibly aliased) |\n| Scope configuration | Identical | Identical |\n\n### Virtual Server-Level Scopes\n\nVirtual servers also support their own `required_scopes` field, which provides an additional layer of access control:\n\n```json\n{\n \"path\": \"/virtual/scoped-tools\",\n \"required_scopes\": [\"virtual-scoped-tools/access\"],\n \"tool_scope_overrides\": [\n {\n \"tool_alias\": \"sensitive-tool\",\n \"required_scopes\": [\"virtual-scoped-tools/admin\"]\n }\n ]\n}\n```\n\nThis means access control happens at two levels:\n1. **Gateway level**: Defined in `scopes.yml` or scope configuration JSON\n2. **Virtual server level**: Defined in the virtual server's `required_scopes`\n\nBoth must be satisfied for access to be granted.\n\n### Testing Virtual Server Access Control\n\nAn E2E test script is provided for testing scope-based access control with virtual servers:\n\n```bash\n./tests/integration/test_virtual_server_scopes_e2e.sh \\\n --registry-url http://localhost \\\n --token-file .token \\\n --no-cleanup\n```\n\nSee [Virtual Server Operations Guide](virtual-server-operations.md#scope-based-access-control) for more details.\n\n## Security Considerations\n\n### Principle of Least Privilege\n\nThe access control system is designed around the principle of least privilege:\n\n- **Default Deny**: All access is denied by default unless explicitly granted\n- **Explicit Permissions**: Each permission must be explicitly configured\n- **Granular Control**: Permissions can be granted at the method and tool level\n- **Scope Separation**: UI and server permissions are managed separately\n\n### Best Practices\n\n#### 1. Group Design\n- Create specific groups for different roles (admin, user, developer, operator)\n- Avoid overly broad permissions\n- Regularly review group memberships\n\n#### 2. Scope Configuration\n- Use restricted scopes for most users\n- Reserve unrestricted access for administrators only\n- Implement tool-level restrictions for sensitive operations\n\n#### 3. Monitoring and Auditing\n- Enable detailed logging for access decisions\n- Monitor failed access attempts\n- Regularly audit scope configurations\n\n#### 4. Production Deployment\n- Use separate Cognito user pools for different environments\n- Implement proper secret management for client credentials\n- Enable MFA for administrative accounts\n\n### Security Boundaries\n\nThe system enforces several security boundaries:\n\n- **Authentication Boundary**: Users must authenticate via Cognito\n- **Authorization Boundary**: Scopes control what authenticated users can access\n- **Server Boundary**: Each server's tools are independently controlled\n- **Method Boundary**: Protocol methods and tools have separate permissions\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Issue 1: User Cannot Access Server\n\n**Symptoms:**\n- User receives \"Access denied\" errors\n- Server appears unavailable to user\n\n**Diagnosis:**\n1. Check user's Cognito group membership\n2. Verify group mapping in `scopes.yml`\n3. Confirm server is listed in user's scopes\n\n**Solution:**\n```yaml\n# Ensure user's group has appropriate server scope\ngroup_mappings:\n user-group-name:\n - mcp-servers-restricted/read # Add appropriate scope\n```\n\n#### Issue 2: Tool Call Fails Despite Method Access\n\n**Symptoms:**\n- User can list tools but cannot call specific tools\n- `tools/call` method fails with permission error\n\n**Diagnosis:**\n1. Verify user has `tools/call` method permission\n2. Check if specific tool is listed in allowed tools\n3. Confirm tool name matches exactly\n\n**Solution:**\n```yaml\nmcp-servers-restricted/execute:\n - server: server-name\n methods:\n - tools/call # Method permission\n tools:\n - specific-tool-name # Tool permission\n```\n\n#### Issue 3: Scope Configuration Not Loading\n\n**Symptoms:**\n- All access is allowed (fallback behavior)\n- Scope validation logs show \"No scopes configuration loaded\"\n\n**Diagnosis:**\n1. Check `scopes.yml` file exists in `auth_server/` directory\n2. Verify YAML syntax is valid\n3. Check file permissions\n\n**Solution:**\n```bash\n# Validate YAML syntax\npython -c \"import yaml; yaml.safe_load(open('auth_server/scopes.yml'))\"\n\n# Check file permissions\nls -la auth_server/scopes.yml\n```\n\n#### Issue 4: Group Mapping Not Working\n\n**Symptoms:**\n- User has correct Cognito group but wrong scopes\n- Scope mapping appears incorrect\n\n**Diagnosis:**\n1. Verify group name matches exactly in Cognito and `scopes.yml`\n2. Check for typos in group names\n3. Confirm group mapping syntax\n\n**Solution:**\n```yaml\n# Ensure exact match between Cognito group name and mapping key\ngroup_mappings:\n exact-cognito-group-name: # Must match Cognito exactly\n - scope-name\n```\n\n### Debugging Tools\n\n#### Enable Verbose Logging\n\nThe validation function provides detailed logging for troubleshooting:\n\n```python\n# Logs show complete validation process\nlogger.info(f\"=== VALIDATE_SERVER_TOOL_ACCESS START ===\")\nlogger.info(f\"Requested server: '{server_name}'\")\nlogger.info(f\"Requested method: '{method}'\")\nlogger.info(f\"Requested tool: '{tool_name}'\")\nlogger.info(f\"User scopes: {user_scopes}\")\n```\n\n#### Test Scope Configuration\n\nCreate a simple test script to validate scope configurations:\n\n```python\nimport yaml\n\ndef test_scope_config():\n with open('auth_server/scopes.yml', 'r') as f:\n config = yaml.safe_load(f)\n \n # Test group mappings\n for group, scopes in config.get('group_mappings', {}).items():\n print(f\"Group: {group} -> Scopes: {scopes}\")\n \n # Test scope definitions\n for scope in ['mcp-servers-restricted/read', 'mcp-servers-restricted/execute']:\n if scope in config:\n print(f\"Scope {scope} has {len(config[scope])} server configurations\")\n\ntest_scope_config()\n```\n\n### Performance Considerations\n\n- **Scope Caching**: Scope configurations are loaded once at startup\n- **Validation Efficiency**: Validation stops at first matching scope\n- **Memory Usage**: Large scope configurations may impact memory usage\n- **Logging Overhead**: Verbose logging can impact performance in production\n\nFor production deployments, consider:\n- Reducing log verbosity\n- Monitoring validation performance\n- Optimizing scope configuration structure\n- Implementing scope configuration caching strategies\n\n---\n\nThis documentation provides a comprehensive guide to understanding and configuring the fine-grained access control system. For additional information about Cognito setup and integration, refer to [`docs/cognito.md`](./cognito.md) and [`docs/auth.md`](./auth.md)." }, { "path": "docs/security-posture.md", "content": "# Security Posture - Enterprise-Grade Security for MCP Gateway & Registry\n\n**Last Updated:** March 13, 2026\n**Version:** 1.0.16+\n\n---\n\n## Executive Summary\n\nThe MCP Gateway & Registry implements defense-in-depth security across all layers of the stack. Our comprehensive security approach ensures that enterprises can safely deploy AI agent infrastructure while maintaining compliance with industry standards and best practices.\n\nThis document outlines our security architecture, controls, and practices that make the MCP Gateway & Registry enterprise-ready.\n\n### Security Pillars\n\n1. **Infrastructure Security** - Multi-layered AWS security controls\n2. **Data Protection** - Encryption at rest and in transit\n3. **Identity & Access Management** - Enterprise SSO and fine-grained authorization\n4. **Container Security** - Hardened container images following CIS benchmarks\n5. **Application Security** - Secure coding practices with automated scanning\n6. **Supply Chain Security** - Automated security analysis of third-party MCP servers\n7. **Observability** - Comprehensive audit logging and monitoring\n\n### Deployment Platforms\n\nThe MCP Gateway & Registry supports multiple deployment platforms. Security controls are categorized by applicability:\n\n**🟦 ECS Deployment** - AWS ECS with Terraform (uses DocumentDB, ALB, CloudFront, Lambda)\n**🟩 EKS Deployment** - Kubernetes/EKS with Helm (uses MongoDB-CE, Kubernetes native features)\n**🟨 Universal** - Applies to all deployment platforms (containers, application code, authentication)\n\n---\n\n## Table of Contents\n\n1. [Encryption & Key Management](#encryption--key-management)\n2. [Secrets Management & Rotation](#secrets-management--rotation)\n3. [Network Security](#network-security)\n4. [Access Logging & Audit Trail](#access-logging--audit-trail)\n5. [Container Hardening](#container-hardening)\n6. [Kubernetes Security](#kubernetes-security)\n7. [Application Security](#application-security)\n8. [Supply Chain Security](#supply-chain-security)\n9. [Identity & Access Management](#identity--access-management)\n10. [Monitoring & Alerting](#monitoring--alerting)\n11. [Security Testing & Validation](#security-testing--validation)\n12. [Compliance & Standards](#compliance--standards)\n\n---\n\n## Encryption & Key Management\n\n**🟦 ECS Deployment** | **🟨 Universal (TLS)**\n\n### Encryption at Rest\n\n**🟦 ECS Deployment Only**\n\nAll sensitive data is encrypted at rest using AWS Key Management Service (KMS) with customer-managed keys.\n\n**Encrypted Resources:**\n- **AWS Secrets Manager**: All secrets encrypted with dedicated KMS keys\n - DocumentDB database credentials\n - RDS PostgreSQL credentials\n - JWT signing keys\n - Session encryption keys\n - API tokens and service credentials\n- **AWS Systems Manager Parameter Store**: All SecureString parameters encrypted\n - Admin passwords\n - Database connection strings\n - Configuration secrets\n- **Amazon DocumentDB** (ECS): Cluster encrypted with customer-managed KMS key\n- **Amazon RDS PostgreSQL** (ECS): Database encrypted with customer-managed KMS key\n- **Amazon S3** (ECS): All buckets use server-side encryption (SSE-S3 or KMS)\n\n**🟩 EKS Deployment:**\n- **MongoDB-CE**: Uses Kubernetes secrets for credentials (can be encrypted with KMS via EKS encryption provider)\n- **RDS PostgreSQL** (Keycloak): Same as ECS - encrypted with customer-managed KMS key\n\n**KMS Key Architecture:**\n\nThree dedicated KMS keys with distinct purposes:\n1. **DocumentDB Key** (`alias/mcp-gateway-documentdb`)\n - Encrypts DocumentDB cluster\n - Encrypts DocumentDB credentials in Secrets Manager\n - Encrypts related SSM parameters\n\n2. **RDS Key** (`alias/keycloak-rds`)\n - Encrypts RDS PostgreSQL database\n - Encrypts RDS credentials in Secrets Manager\n - Encrypts Keycloak configuration parameters\n\n3. **Gateway Secrets Key** (module-specific)\n - Encrypts MCP Gateway application secrets\n - Encrypts JWT signing keys\n - Encrypts session encryption keys\n\n**Key Management Features:**\n- ✅ Automatic key rotation enabled (annual rotation)\n- ✅ Restrictive key policies following least-privilege principle\n- ✅ CloudTrail logging of all key usage\n- ✅ Cross-account access controls\n- ✅ Key deletion protection with 7-day waiting period\n\n### Encryption in Transit\n\n**🟨 Universal**\n\nAll network communication uses TLS encryption:\n\n**TLS Configuration:**\n- **External Traffic**: TLS 1.2+ enforced on all ALBs (ECS) / Ingress controllers (EKS) and CloudFront distributions\n- **Internal Traffic**: TLS connections to DocumentDB (ECS) / MongoDB-CE (EKS) and RDS\n- **API Communication**: HTTPS-only for all REST API endpoints\n- **MCP Protocol**: Encrypted SSE (Server-Sent Events) over HTTPS\n\n**S3 Bucket Policies** (ECS):\n- TLS enforcement via bucket policies (deny all non-HTTPS requests)\n- Applied to all S3 buckets (logs, artifacts, backups)\n\n---\n\n## Secrets Management & Rotation\n\n**🟦 ECS Deployment** | **🟨 Universal (Application-Level)**\n\n### Automated Secret Rotation\n\n**🟦 ECS Deployment Only**\n\nCredentials are automatically rotated on a 30-day schedule using AWS Lambda functions, eliminating manual password management and reducing credential exposure windows.\n\n**Rotation Implementation:**\n\n**DocumentDB Credentials (ECS):**\n- Automated rotation Lambda function\n- Updates master password in DocumentDB cluster\n- Updates stored credentials in Secrets Manager\n- Zero-downtime rotation with connection draining\n\n**RDS PostgreSQL Credentials (ECS and EKS):**\n- Automated rotation Lambda function\n- Updates master password in RDS cluster\n- Updates stored credentials in Secrets Manager\n- Coordinated updates to application configurations\n\n**Rotation Features (ECS):**\n- ✅ 30-day automatic rotation schedule\n- ✅ VPC-integrated Lambda functions (secure network access)\n- ✅ CloudWatch logging for all rotation events\n- ✅ Automatic rollback on rotation failure\n- ✅ CloudWatch alarms for rotation failures\n\n**🟩 EKS Deployment:**\n- MongoDB-CE credentials stored in Kubernetes secrets\n- Manual rotation recommended (can be automated with Kubernetes CronJobs)\n- RDS credentials use same AWS Secrets Manager rotation as ECS\n\n### Secrets Access Control\n\n**🟦 ECS Deployment:**\n\n**IAM-Based Access (ECS):**\n- Secrets accessible only by authorized ECS task execution roles\n- KMS key policies restrict decryption to specific IAM principals\n- No secrets stored in environment variables or code\n\n**🟩 EKS Deployment:**\n- Kubernetes RBAC controls access to secrets\n- IAM Roles for Service Accounts (IRSA) for AWS API access\n- Secrets can be encrypted at rest with KMS via EKS encryption provider\n\n**Application-Level Encryption (Universal):**\n- Backend MCP server credentials encrypted with Fernet encryption\n- JWT tokens signed with cryptographically secure keys\n- Session data encrypted before storage\n\n---\n\n## Network Security\n\n**🟦 ECS Deployment (AWS-specific)** | **🟨 Universal (Concepts)**\n\n### Public Access Prevention\n\n**🟦 ECS Deployment**\n\nAll storage resources are protected against public exposure:\n\n**S3 Bucket Security:**\n- Public access completely blocked on all buckets\n- Bucket policies deny any public ACLs or policies\n- Applied to:\n - ALB access logs bucket\n - CloudFront access logs bucket\n - CodeBuild artifacts bucket\n - Backup storage buckets\n\n**Database Access:**\n- **DocumentDB** (ECS): Cluster deployed in private subnets (no public endpoint)\n- **MongoDB-CE** (EKS): Pod-to-pod communication within cluster, no external exposure\n- **RDS PostgreSQL** (ECS/EKS): Deployed in private subnets (no public endpoint)\n- Security groups (ECS) / Network Policies (EKS) allow connections only from authorized workloads\n\n### Security Groups & Network Segmentation\n\n**🟦 ECS Deployment**\n\n**Principle of Least Privilege:**\n- Dedicated security groups per service layer\n- Ingress rules limited to specific ports and source security groups\n- Egress rules restricted to required destinations only\n\n**Security Group Architecture:**\n```\n[ALB Security Group]\n ↓ TCP 8080 (HTTP)\n[Registry ECS Security Group]\n ↓ TCP 27017 (MongoDB)\n[DocumentDB Security Group]\n\n[ALB Security Group]\n ↓ TCP 8080 (HTTP)\n[Auth Server ECS Security Group]\n ↓ TCP 5432 (PostgreSQL)\n[RDS Security Group]\n```\n\n**Lambda Function Security (ECS):**\n- Secret rotation Lambdas deployed in VPC\n- Dedicated security group with minimal permissions\n- Access to databases via security group rules only\n\n**🟩 EKS Deployment**\n\n**Kubernetes Network Policies:**\n- Define ingress/egress rules for pods\n- Restrict pod-to-pod communication\n- Isolate application tiers (frontend, backend, database)\n- Default deny-all with explicit allow rules\n\n---\n\n## Access Logging & Audit Trail\n\n**🟦 ECS (Infrastructure Logs)** | **🟨 Universal (Application Logs)**\n\n### Comprehensive Access Logging\n\nAll traffic to the platform is logged for security analysis and compliance.\n\n**🟦 Application Load Balancer Logging (ECS):**\n- **MCP Gateway ALB**: All HTTP/HTTPS requests logged to S3\n- **Keycloak ALB**: All authentication traffic logged to S3\n- **Log Format**: W3C Extended Log Format\n- **Storage**: Dedicated S3 bucket with 90-day retention\n- **Encryption**: SSE-S3 (AES-256) encryption\n\n**🟦 CloudFront Access Logging (ECS):**\n- **MCP Gateway Distribution**: All CDN requests logged\n- **Keycloak Distribution**: All auth-related CDN traffic logged\n- **Log Format**: W3C Extended Log Format (compressed .gz)\n- **Storage**: Dedicated S3 bucket with separate prefixes per distribution\n- **Retention**: 90-day lifecycle policy\n\n**🟦 DocumentDB Audit Logging (ECS):**\n- **Audit Events Captured**:\n - Authentication events (login attempts, failures)\n - Authorization decisions (access control checks)\n - DDL operations (schema changes, index creation)\n - User management (user creation, role assignments)\n - Administrative commands (cluster configuration changes)\n- **Destination**: CloudWatch Logs (`/aws/docdb/mcp-gateway-registry/audit`)\n- **Query**: CloudWatch Logs Insights for analysis\n\n### Application Audit Logging\n\n**🟨 Universal (All Deployments)**\n\n**Registry Audit Log:**\n- All API requests logged to DocumentDB (ECS) or MongoDB-CE (EKS)\n- All MCP tool invocations logged\n- User authentication events tracked\n- Configuration changes recorded\n\n**Audit Log Fields:**\n- Timestamp (UTC with timezone)\n- Username and session ID\n- HTTP method and status code\n- Request path and query parameters\n- Response time and size\n- User agent and source IP\n- Error details (if applicable)\n\n**Audit Features:**\n- ✅ Searchable filters (username, method, status code, date range)\n- ✅ Statistics dashboard (event counts, unique users, timelines)\n- ✅ Export to CSV/JSONL for external analysis\n- ✅ Automatic TTL-based retention (configurable, default 7 days)\n- ✅ DocumentDB indexing for fast queries\n\n---\n\n## Container Hardening\n\n**🟨 Universal (All Deployments)**\n\n### CIS Docker Benchmark Compliance\n\nAll container images are hardened following CIS Docker Benchmark 4.1 requirements, regardless of deployment platform (ECS, EKS, Docker Compose).\n\n**Non-Root User Execution:**\n\nEvery container runs as a non-privileged user (UID 1000):\n\n```dockerfile\n# Create non-root user early for security\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\n# Copy files with correct ownership (fast, secure)\nCOPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv\n\n# Switch to non-root user\nUSER appuser\n```\n\n**Container Images Secured (12 total):**\n- Registry service (with nginx)\n- Auth server\n- MCP servers (3 variants: GPU, CPU, lightweight)\n- Metrics service\n- Keycloak\n- Database initialization containers\n- Grafana\n\n**Security Controls Per Container:**\n- ✅ Non-root user execution (CIS 4.1)\n- ✅ No sudo package installed\n- ✅ Health checks configured (CIS 4.6)\n- ✅ Multi-stage builds (minimal attack surface)\n- ✅ No build tools in runtime images\n- ✅ Minimal base images (python:3.14-slim)\n\n### Container Runtime Security\n\n**Docker Compose Security Options:**\n\n```yaml\nservices:\n registry:\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n ports:\n - \"80:8080\" # High port for non-root\n - \"443:8443\" # High port for non-root\n```\n\n**Security Features:**\n- `no-new-privileges:true` - Prevents privilege escalation\n- `cap_drop: ALL` - Drops all Linux capabilities\n- High port binding (8080, 8443) - Non-root operation\n- Read-only root filesystem (where possible)\n\n**MongoDB Capability Exception:**\n\nMongoDB requires `SETUID` and `SETGID` capabilities because its entrypoint uses `gosu` to drop privileges from `root` to the `mongodb` user at startup. Without these capabilities, MongoDB fails with:\n\n```text\nerror: failed switching to 'mongodb': operation not permitted\n```\n\nThe correct least-privilege pattern is to drop all capabilities and then explicitly add back only the minimum required:\n\n```yaml\n mongodb:\n security_opt:\n - no-new-privileges:true\n cap_drop:\n - ALL\n cap_add:\n - SETUID # Required by gosu to switch to mongodb user at startup\n - SETGID # Required by gosu to switch to mongodb group at startup\n```\n\nThis follows CIS Docker Benchmark guidance: explicitly enumerate the minimum capabilities a container needs rather than leaving it with a broad default set.\n\n### Image Supply Chain\n\n**Image Signing & Verification:**\n- Official images published to Docker Hub\n- Versioned releases with semantic versioning\n- Automated builds via GitHub Actions\n- Container vulnerability scanning in CI/CD\n\n---\n\n## Kubernetes Security\n\n**🟩 EKS Deployment Only**\n\n### Pod Security Standards\n\nAll Kubernetes Pods implement Pod Security Standards (PSS) at the **Restricted** level - the most stringent security profile.\n\n**Pod-Level Security Context:**\n\n```yaml\nspec:\n securityContext:\n runAsNonRoot: true\n runAsUser: 1000\n runAsGroup: 1000\n fsGroup: 1000\n seccompProfile:\n type: RuntimeDefault\n```\n\n**Container-Level Security Context:**\n\n```yaml\ncontainers:\n - name: container\n securityContext:\n allowPrivilegeEscalation: false\n runAsNonRoot: true\n runAsUser: 1000\n capabilities:\n drop:\n - ALL\n```\n\n**Security Controls:**\n- ✅ **runAsNonRoot**: Prevents containers from running as root\n- ✅ **Drop ALL Capabilities**: Removes all Linux capabilities\n- ✅ **No Privilege Escalation**: Blocks privilege escalation attempts\n- ✅ **Seccomp Profile**: Restricts system calls\n- ✅ **Read-Only Root Filesystem**: Where application permits\n\n**Helm Charts Secured:**\n- Registry Deployment\n- Auth Server Deployment\n- MCP Gateway (mcpgw) Deployment\n- MongoDB Configuration Job\n- Keycloak Configuration Job\n\n### EKS-Specific Security\n\nWhen deployed to Amazon EKS:\n- IAM Roles for Service Accounts (IRSA) for AWS API access\n- EKS security group policies\n- Pod Security Policy (PSP) enforcement (EKS < 1.25)\n- Pod Security Standards (PSS) enforcement (EKS ≥ 1.25)\n- Network policies for pod-to-pod communication\n\n---\n\n## Application Security\n\n**🟨 Universal (All Deployments)**\n\n### Secure Coding Practices\n\nThe application codebase follows secure coding standards validated by automated security scanning, regardless of deployment platform.\n\n**Bandit Static Analysis:**\n\nAll Python code is continuously scanned with Bandit security linter to detect:\n- SQL injection vulnerabilities\n- Command injection risks\n- Hardcoded credentials\n- Insecure cryptographic functions\n- Subprocess misuse\n- Unsafe deserialization\n- And 50+ other security patterns\n\n**Security Issues Addressed:**\n\n**Subprocess Security:**\n- Always use list form (never `shell=True`)\n- Validate command arguments against allowlists\n- Add timeouts to prevent DoS\n- Proper error handling with logging\n\n```python\n# Secure subprocess pattern\nresult = subprocess.run(\n [\"nginx\", \"-s\", \"reload\"],\n capture_output=True,\n text=True,\n timeout=5,\n)\n```\n\n**SQL Injection Prevention:**\n- Parameterized queries for all database operations\n- Table/column name validation against allowlists\n- No string interpolation in SQL statements\n\n```python\n# Secure SQL pattern\ntable = validate_table_name(table) # Allowlist check\nquery = f\"DELETE FROM {table} WHERE created_at < ?\"\ncursor.execute(query, (cutoff,))\n```\n\n**Request Timeout Protection:**\n- All HTTP requests include timeout parameters\n- Prevents resource exhaustion DoS attacks\n- Default 30-second timeout for external APIs\n\n**Secure Configuration:**\n- No hardcoded credentials in code\n- All sensitive config via environment variables\n- Bind addresses configurable (default 127.0.0.1)\n- TLS-only communication in production\n\n### Dependency Management\n\n**Vulnerability Scanning:**\n- Automated dependency vulnerability scanning in CI/CD\n- Regular updates for security patches\n- Pinned versions for reproducible builds\n\n**Python Dependencies:**\n- `uv` package manager for fast, reproducible installs\n- `pyproject.toml` for dependency management\n- No pip cache to reduce image size\n\n---\n\n## Supply Chain Security\n\n**🟨 Universal (All Deployments)**\n\n### Automated Security Scanning\n\nThird-party MCP servers, A2A agents, and Agent Skills are automatically scanned before being made available to users, regardless of deployment platform.\n\n**Scanning Infrastructure:**\n\n**MCP Server Scanning:**\n- Scanner: [Cisco AI Defense MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner)\n- Analyzers: YARA (pattern-based), LLM (semantic analysis)\n- Detection: SQL injection, command injection, XSS, path traversal, hardcoded secrets\n\n**A2A Agent Scanning:**\n- Scanner: [Cisco AI Defense A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner)\n- Analyzers: YARA, Heuristic, Spec validation, Endpoint analysis\n- Detection: Protocol violations, malicious behaviors, security misconfigurations\n\n**Agent Skills Scanning:**\n- Scanner: [Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/cisco-ai-skill-scanner)\n- Analyzers: Static analysis, Behavioral analysis, LLM semantic analysis\n- Detection: Prompt injection, command injection, data exfiltration, social engineering\n\n### Scanning Workflows\n\n**1. Automatic Registration-Time Scanning:**\n\nEvery new MCP server/agent/skill is scanned before being enabled:\n- Scan triggered automatically on registration\n- Results analyzed for severity (Critical, High, Medium, Low)\n- Safe items: Enabled immediately\n- Unsafe items: Disabled with `security-pending` tag\n- Detailed report saved for administrator review\n\n**2. Manual On-Demand Scanning:**\n\nAdministrators can trigger scans via API or CLI:\n```bash\n# Rescan MCP server\ncurl -X POST /api/servers/{path}/rescan -H \"Authorization: Bearer $TOKEN\"\n\n# Rescan A2A agent\ncurl -X POST /api/agents/{path}/rescan -H \"Authorization: Bearer $TOKEN\"\n\n# Rescan Agent Skill\ncurl -X POST /api/skills/{path}/rescan -H \"Authorization: Bearer $TOKEN\"\n```\n\n**3. Periodic Registry Scanning:**\n\nComprehensive scans of all enabled servers on a schedule:\n- Detects newly discovered vulnerabilities\n- Generates executive security reports\n- Tracks vulnerability trends over time\n\n### Threat Detection\n\n**Security Threats Detected:**\n- SQL injection patterns\n- Command injection vulnerabilities\n- Cross-site scripting (XSS) vectors\n- Path traversal attempts\n- Hardcoded credentials and secrets\n- Malicious code patterns\n- Prompt injection attacks (skills)\n- Data exfiltration risks\n- Privilege escalation patterns\n- SSRF vulnerabilities\n\n**Automated Response:**\n- Critical/High severity: Server/agent/skill automatically disabled\n- Security-pending tag applied for admin review\n- Detailed JSON report saved to `security_scans/` directory\n- UI indicators (shield icons) show security status\n\nFor complete details, see [Security Scanner Documentation](security-scanner.md).\n\n---\n\n## Identity & Access Management\n\n**🟨 Universal (All Deployments)**\n\n### Enterprise Identity Integration\n\n**Supported Identity Providers (All Deployments):**\n- **Keycloak** (default, self-hosted)\n- **Microsoft Entra ID** (Azure AD)\n- **AWS Cognito**\n- Any OIDC-compliant provider\n\n**SSO Features:**\n- Single Sign-On (SSO) with identity provider session\n- Proper OIDC logout flow with `id_token_hint`\n- Multi-factor authentication (MFA) support\n- Conditional access policies (Entra ID)\n\n### Authorization Model\n\n**Role-Based Access Control (RBAC):**\n\n**Admin Role:**\n- Full system access and configuration\n- User and group management\n- Security scan triggers\n- Audit log access\n- System health monitoring\n\n**User Role:**\n- MCP server registration (own servers)\n- Tool discovery and execution\n- Dashboard and API access\n- Limited configuration access\n\n**Service Role:**\n- API authentication with static tokens\n- Registry API access (federation)\n- Metrics collection and export\n\n### Fine-Grained Access Control\n\n**Scope-Based Permissions:**\n- OAuth scopes for granular API access control\n- Tool-level permissions (read, execute)\n- Resource-level isolation (user can only manage own servers)\n- IAM group-based tool access control\n\n**Token Security:**\n- JWT tokens signed with SECRET_KEY\n- Short expiration windows (configurable)\n- Secure cookie transmission (HttpOnly, Secure, SameSite)\n- Rate limiting: 100 tokens per user per hour\n\n**Session Security:**\n- Session data encrypted with SECRET_KEY (Fernet)\n- Secure cookie domain configuration\n- HTTPS-only transmission (production)\n- SameSite=Lax CSRF protection\n\nFor complete details, see [Fine-Grained Access Control](scopes.md).\n\n---\n\n## Monitoring & Alerting\n\n**🟦 ECS (CloudWatch Alarms)** | **🟨 Universal (Metrics & Dashboards)**\n\n### CloudWatch Alarms\n\n**🟦 ECS Deployment Only**\n\nProactive monitoring with automated alerts for security-critical resources.\n\n**KMS Monitoring (2 alarms):**\n- KMS API throttling detection (DocumentDB key)\n- KMS API throttling detection (RDS key)\n- Threshold: >10 errors in 1 minute\n- Impact: Prevents secret decryption failures\n\n**DocumentDB Monitoring (1 alarm):**\n- Audit log failure detection\n- Threshold: >10 failures in 5 minutes\n- Impact: Identifies compliance gaps\n\n**S3 Cost Control (2 alarms):**\n- ALB logs bucket size monitoring\n- CloudFront logs bucket size monitoring\n- Threshold: >100 GB\n- Impact: Prevents unexpected costs\n\n**WAF Attack Detection (4 alarms):**\n- Blocked requests monitoring (both ALBs)\n- Rate limit trigger detection (both ALBs)\n- Threshold: Configurable per alarm type\n- Impact: Early warning of attacks/DDoS\n\n**Alarm Configuration:**\n- Optional SNS topic for email/SMS notifications\n- Alarms created but not intrusive if SNS not configured\n- Multiple evaluation periods to reduce false positives\n- `treat_missing_data: notBreaching` for newly created resources\n\n**🟩 EKS Deployment:**\n- Uses Kubernetes-native monitoring (Prometheus, Alertmanager)\n- Pod resource monitoring via Kubernetes metrics server\n- Custom Prometheus alerts for application and infrastructure\n\n### Metrics & Observability\n\n**🟨 Universal (All Deployments)**\n\n**Prometheus Metrics:**\n- Tool execution counters and duration histograms\n- System resource usage (CPU, memory, connections)\n- Authentication metrics (login, logout, token vending)\n- Error rates and response times\n\n**Grafana Dashboards (All Deployments):**\n- MCP data-plane performance metrics\n- System health and resource utilization\n- Tool usage analytics\n- Real-time performance monitoring\n\n**🟦 Amazon Managed Prometheus (AMP) - ECS Deployment:**\n- Native AWS integration for ECS deployments\n- Metrics service collects and exports to AMP\n- OpenTelemetry support for external platforms (Datadog, etc.)\n\n**🟩 Prometheus - EKS Deployment:**\n- Self-hosted Prometheus in Kubernetes cluster\n- Metrics scraped from pods via ServiceMonitor CRDs\n- Persistent storage for metrics retention\n\n---\n\n## Security Testing & Validation\n\n**🟨 Universal (All Deployments)**\n\n### Automated Security Testing\n\n**Container Security Tests (All Deployments):**\n- Test suite: `tests/security/test_container_security.py`\n- Validates: USER directive, no sudo, HEALTHCHECK, environment config\n- Coverage: 12 Dockerfiles × 7 test categories = 84 test cases\n\n**Pre-Commit Hooks:**\n\nAutomated security checks before every commit:\n```bash\n# Hooks include:\n- Ruff linter (security rules enabled)\n- Bandit security scan\n- MyPy type checking\n- Trailing whitespace removal\n- YAML/JSON validation\n- Python syntax validation\n- Shell script syntax validation\n```\n\n**Semgrep Static Analysis:**\n\nComprehensive multi-language static code analysis:\n- **Languages**: Python, JavaScript/TypeScript, YAML, Terraform, Dockerfile\n- **Rule Sets**:\n - SQL injection detection\n - JWT security validation\n - Secret detection (credentials, tokens, API keys)\n - Docker Compose security best practices\n - Terraform infrastructure security\n - Path traversal prevention\n - CSRF protection validation\n- **Scan Coverage**: 162 initial findings → 25 actionable items (84% reduction)\n- **Resolution Status**:\n - ✅ SQL injection - Column validation implemented in metrics service\n - ✅ Docker Compose - `security_opt` and `cap_drop` added to all services\n - ✅ Terraform secrets - KMS encryption enabled for all AWS Secrets Manager secrets\n - ✅ JWT verification - Confirmed secure (two-step validation pattern)\n - ✅ Path traversal - Fixed in CLI and API endpoints\n- **False Positive Filtering**: `.semgrepignore` excludes docs and tests\n- **Tracking**: GitHub Issue [#650](https://github.com/agentic-community/mcp-gateway-registry/issues/650)\n\n**CI/CD Pipeline:**\n\nGitHub Actions run on every pull request:\n- Bandit security scan (fail on high/critical)\n- Ruff linting with security rules\n- Unit tests (701 tests)\n- Integration tests (57 tests)\n- Type checking with MyPy\n- Container security validation\n\n### Manual Security Testing\n\n**Penetration Testing:**\n- Recommended: Annual third-party penetration testing\n- Internal security reviews before major releases\n- Vulnerability disclosure program\n\n**Security Audits:**\n- Code review with security focus\n- Infrastructure security assessment\n- Compliance gap analysis\n\n---\n\n## Compliance & Standards\n\n**🟨 Universal (All Deployments)**\n\n### Industry Standards\n\n**CIS Docker Benchmark (All Deployments):**\n- ✅ 4.1: Non-root user execution\n- ✅ 4.2: Health checks configured\n- ✅ 4.3: No unnecessary packages\n- ✅ 4.5: Environment security (PIP_NO_CACHE_DIR)\n- ✅ 4.6: Security options in orchestration\n\n**OWASP Top 10 (2021):**\n- ✅ A01: Broken Access Control - IAM, RBAC, fine-grained permissions\n- ✅ A02: Cryptographic Failures - KMS encryption, TLS everywhere\n- ✅ A03: Injection - Parameterized queries, subprocess validation\n- ✅ A05: Security Misconfiguration - Hardened defaults, security contexts\n- ✅ A07: Authentication Failures - Enterprise SSO, MFA, proper session management\n- ✅ A09: Logging Failures - Comprehensive audit logging, CloudWatch\n- ✅ A10: SSRF - Input validation, URL allowlists\n\n**Kubernetes Pod Security Standards (PSS):**\n- ✅ Restricted level compliance (most stringent)\n- ✅ runAsNonRoot enforcement\n- ✅ All capabilities dropped\n- ✅ No privilege escalation\n- ✅ Seccomp profiles applied\n\n### Compliance Frameworks\n\n**SOC 2 Controls:**\n- Encryption at rest and in transit\n- Access control and authentication\n- Audit logging and monitoring\n- Change management and versioning\n- Incident response procedures\n\n**PCI-DSS:**\n- Encryption of sensitive data\n- Secure authentication mechanisms\n- Network segmentation and firewalls\n- Audit logging and monitoring\n- Access control and least privilege\n\n**HIPAA (Healthcare):**\n- Data encryption (at rest and in transit)\n- Access controls and authentication\n- Audit controls and logging\n- Integrity controls\n- Transmission security\n\n**GDPR (Data Protection):**\n- Data encryption\n- Access controls and consent management\n- Audit trails\n- Data retention policies (TTL-based)\n- Right to erasure (data deletion capabilities)\n\n---\n\n## Verification & Validation\n\n### Infrastructure Verification\n\n**🟦 ECS Deployment**\n\n**Verify KMS Encryption:**\n```bash\n# Check secret encryption\naws secretsmanager describe-secret \\\n --secret-id mcp-gateway/documentdb/credentials \\\n --query 'KmsKeyId'\n\n# Check KMS key rotation\naws kms get-key-rotation-status \\\n --key-id alias/mcp-gateway-documentdb\n```\n\n**Verify Access Logging:**\n```bash\n# Check ALB logs\naws s3 ls s3://mcp-gateway-{region}-{account}-alb-logs/ --recursive | head -20\n\n# Check CloudFront logs\naws s3 ls s3://mcp-gateway-{region}-{account}-cloudfront-logs/ --recursive | head -20\n\n# Check DocumentDB audit logs\naws logs describe-log-groups --log-group-name-prefix /aws/docdb\n```\n\n**Verify CloudWatch Alarms:**\n```bash\n# List all security alarms\naws cloudwatch describe-alarms \\\n --alarm-name-prefix mcp-gateway \\\n --query 'MetricAlarms[*].[AlarmName,StateValue]' \\\n --output table\n```\n\n**🟩 EKS Deployment**\n\n**Verify Pod Security Standards:**\n```bash\n# Check pod security context\nkubectl get pod -n mcp-gateway -o jsonpath='{.spec.securityContext}'\n\n# Check container security context\nkubectl get pod -n mcp-gateway -o jsonpath='{.spec.containers[0].securityContext}'\n\n# Verify non-root user\nkubectl exec -n mcp-gateway -- whoami\n# Expected output: appuser\n```\n\n**Verify Network Policies:**\n```bash\n# List network policies\nkubectl get networkpolicies -n mcp-gateway\n\n# Describe specific policy\nkubectl describe networkpolicy -n mcp-gateway\n```\n\n**Verify Kubernetes Secrets:**\n```bash\n# Check if secrets are encrypted at rest (EKS encryption provider)\nkubectl get secret -n mcp-gateway -o jsonpath='{.metadata.annotations}'\n```\n\n### Application Verification\n\n**🟨 Universal (All Deployments)**\n\n**Run Security Tests:**\n```bash\n# Container security tests\npytest tests/security/test_container_security.py -v\n\n# Bandit security scan\nuv run bandit -r registry/ auth_server/ api/ -ll\n\n# Pre-commit checks\npre-commit run --all-files\n```\n\n**Verify Container Security:**\n```bash\n# Check non-root user\ndocker compose exec registry whoami\n# Expected output: appuser\n\n# Check security options\ndocker compose config | grep -A 5 \"security_opt\"\n```\n\n**Verify Supply Chain Security:**\n```bash\n# Check MCP server scan results\ncat security_scans/{server-url}.json | jq '.tool_results[].is_safe'\n\n# Trigger manual scan\ncurl -X POST /api/servers/{path}/rescan -H \"Authorization: Bearer $TOKEN\"\n```\n\n---\n\n## Security Incident Response\n\n### Incident Detection\n\n**Monitoring Channels:**\n- CloudWatch Alarms (immediate notification)\n- Audit log anomaly detection\n- Security scan failure alerts\n- WAF blocked request spikes\n\n### Response Procedures\n\n**Severity Levels:**\n- **Critical**: Data breach, system compromise, authentication bypass\n- **High**: Unauthorized access, privilege escalation, DoS attack\n- **Medium**: Suspicious activity, failed authentication spike, misconfiguration\n- **Low**: Policy violation, informational security event\n\n**Response Steps:**\n1. **Detection**: Alert received via CloudWatch, logs, or monitoring\n2. **Triage**: Assess severity and impact\n3. **Containment**: Isolate affected resources, disable compromised accounts\n4. **Investigation**: Review audit logs, analyze attack patterns\n5. **Remediation**: Patch vulnerabilities, rotate credentials, update policies\n6. **Recovery**: Restore services, verify security posture\n7. **Post-Mortem**: Document incident, update procedures, implement preventions\n\n### Security Contacts\n\n**Report Security Vulnerabilities:**\n- AWS Security: http://aws.amazon.com/security/vulnerability-reporting/\n- Email: aws-security@amazon.com\n- **Do NOT create public GitHub issues for security vulnerabilities**\n\n**Security Updates:**\n- Monitor [release notes](../release-notes/) for security patches\n- Subscribe to [GitHub Security Advisories](https://github.com/agentic-community/mcp-gateway-registry/security/advisories)\n\n---\n\n## Summary\n\nThe MCP Gateway & Registry implements enterprise-grade security across all layers:\n\n✅ **Encryption Everywhere** - At rest (KMS) and in transit (TLS)\n✅ **Zero-Trust Architecture** - Identity verification, least-privilege access\n✅ **Defense-in-Depth** - Multiple security layers at infrastructure, application, and container levels\n✅ **Automated Secrets Management** - 30-day rotation, encrypted storage\n✅ **Comprehensive Logging** - ALB, CloudFront, DocumentDB, application audit logs\n✅ **Supply Chain Security** - Automated scanning of third-party MCP servers\n✅ **Container Hardening** - CIS benchmark compliance, non-root execution\n✅ **Proactive Monitoring** - CloudWatch alarms, Prometheus metrics, Grafana dashboards\n✅ **Compliance Ready** - SOC 2, PCI-DSS, HIPAA, GDPR controls\n\nThis security posture enables enterprises to confidently deploy AI agent infrastructure while maintaining regulatory compliance and protecting sensitive data.\n\n### Security Controls by Deployment Platform\n\n| Security Control | ECS | EKS | Universal |\n|------------------|-----|-----|-----------|\n| **KMS Encryption (AWS Secrets Manager, SSM)** | ✅ | ⚠️ Optional* | ❌ |\n| **Automated Secret Rotation (Lambda)** | ✅ | ⚠️ RDS only | ❌ |\n| **ALB Access Logging** | ✅ | ⚠️ Ingress logs | ❌ |\n| **CloudFront Logging** | ✅ | ✅ | ❌ |\n| **DocumentDB Audit Logging** | ✅ | ❌ | ❌ |\n| **MongoDB-CE Audit Logging** | ❌ | ⚠️ Optional* | ❌ |\n| **CloudWatch Alarms** | ✅ | ⚠️ Custom | ❌ |\n| **S3 Security (Public Block, TLS)** | ✅ | ⚠️ If used | ❌ |\n| **Security Groups** | ✅ | ❌ | ❌ |\n| **Kubernetes Network Policies** | ❌ | ✅ | ❌ |\n| **Pod Security Standards (PSS)** | ❌ | ✅ | ❌ |\n| **Container Hardening (CIS)** | ✅ | ✅ | ✅ |\n| **Non-Root Containers** | ✅ | ✅ | ✅ |\n| **Application Security (Bandit)** | ✅ | ✅ | ✅ |\n| **Supply Chain Security (Scanners)** | ✅ | ✅ | ✅ |\n| **IAM / RBAC** | ✅ | ✅ | ✅ |\n| **Enterprise SSO (OIDC)** | ✅ | ✅ | ✅ |\n| **Application Audit Logging** | ✅ | ✅ | ✅ |\n| **Prometheus Metrics** | ✅ | ✅ | ✅ |\n| **Grafana Dashboards** | ✅ | ✅ | ✅ |\n\n**Legend:**\n- ✅ Fully supported and implemented\n- ⚠️ Partially supported or requires configuration\n- ❌ Not applicable for this platform\n- *EKS can optionally use KMS for Kubernetes secrets encryption via encryption provider\n- *MongoDB-CE audit logging can be enabled in configuration\n\n**Key Differences:**\n- **ECS**: Uses AWS-native services (ALB, DocumentDB, Secrets Manager, Lambda, CloudWatch)\n- **EKS**: Uses Kubernetes-native features (Network Policies, PSS, Ingress, MongoDB-CE)\n- **Universal**: Application-level controls work across all platforms\n\n---\n\n## References\n\n### Documentation\n- [Security Scanner Documentation](security-scanner.md) - Supply chain security for MCP servers\n- [Fine-Grained Access Control](scopes.md) - Permission management\n- [Audit Logging](audit-logging.md) - Comprehensive event tracking\n- [Authentication Guide](auth.md) - Identity provider integration\n- [Configuration Reference](configuration.md) - Security configuration options\n\n### Standards & Frameworks\n- [CIS Docker Benchmark](https://www.cisecurity.org/benchmark/docker) - Container security standards\n- [OWASP Top 10](https://owasp.org/www-project-top-ten/) - Application security risks\n- [Kubernetes Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) - Pod security profiles\n- [AWS Security Best Practices](https://docs.aws.amazon.com/security/) - Cloud security guidance\n- [Bandit Security Linter](https://bandit.readthedocs.io/) - Python security scanning\n\n### Security Tools\n- [Cisco AI Defense MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner) - MCP server security analysis\n- [Cisco AI Defense A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner) - Agent security analysis\n- [Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/cisco-ai-skill-scanner) - Agent Skills security analysis\n\n---\n" }, { "path": "docs/security-scanner.md", "content": "# MCP Security Scanner - Supply Chain Security for MCP Servers, A2A Agents, and Agent Skills\n\n## Introduction\n\n[Watch the Security Scanning Demo Video](https://github.com/user-attachments/assets/9450f027-ef7f-4ed7-a55c-ce970bf26fd8)\n\nAs organizations integrate Model Context Protocol (MCP) servers, Agent-to-Agent (A2A) agents, and Agent Skills into their AI workflows, supply chain security becomes critical. These third-party components provide tools, capabilities, and behavioral guidance to AI systems, making them potential vectors for security vulnerabilities, malicious code injection, and data exfiltration.\n\nThe MCP Gateway Registry addresses this challenge by integrating automated security scanning powered by three specialized tools:\n\n- **[Cisco AI Defence MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner)** - For MCP server security analysis\n- **[Cisco AI Defence A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner)** - For Agent-to-Agent protocol security analysis\n- **[Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/cisco-ai-skill-scanner)** - For Agent Skills (SKILL.md files) security analysis\n\nThese open-source security tools perform deep analysis of MCP servers, A2A agents, and Agent Skills to identify vulnerabilities before they can be exploited in production environments.\n\n**GitHub Repositories:**\n- MCP Scanner: https://github.com/cisco-ai-defense/mcp-scanner\n- A2A Scanner: https://github.com/cisco-ai-defense/a2a-scanner\n- Skill Scanner: https://github.com/cisco-ai-defense/cisco-ai-skill-scanner\n\n### Security Scanning Workflows\n\nThe registry implements multiple complementary security scanning workflows for MCP servers, A2A agents, and Agent Skills:\n\n#### MCP Server Scanning\n1. **Automated Scanning During Server Registration** - Every new server is scanned before being made available to AI agents\n2. **Manual On-Demand Scans via API** - Administrators can trigger security scans for specific servers\n3. **Query Scan Results via API** - View detailed security scan results for any registered server\n4. **Periodic Registry Scans** - Comprehensive security audits across all enabled servers in the registry\n\n#### A2A Agent Scanning\n1. **Automated Scanning During Agent Registration** - Every new agent is scanned before being enabled in the registry\n2. **Manual On-Demand Agent Scans via API** - Administrators can trigger security scans for specific agents\n3. **Query Agent Scan Results** - View detailed security scan results for any registered agent\n\n#### Agent Skills Scanning\n1. **Automated Scanning During Skill Registration** - Every new skill (SKILL.md file) is scanned before being made available\n2. **Manual On-Demand Skill Scans via API** - Administrators can trigger security scans for specific skills\n3. **Query Skill Scan Results via API** - View detailed security scan results for any registered skill\n\nThese workflows ensure continuous security monitoring throughout the MCP server, A2A agent, and Agent Skills lifecycle, from initial registration through ongoing operations.\n\n### Architecture Diagram\n\n```mermaid\nsequenceDiagram\n autonumber\n\n participant Client as Client/Admin\n participant Registry as MCP Gateway Registry
(Scan Orchestrator + MongoDB-CE/DocumentDB)\n participant Scanner as Cisco AI Defense
(YARA | LLM | Cisco Proprietary)\n participant Target as MCP Server / A2A Agent\n\n %% Registration-time scanning\n rect rgb(225, 245, 254)\n note over Client,Target: Registration-Time Scanning (Server or Agent)\n Client->>Registry: Register Server/Agent\n Registry->>Target: Connect & Fetch Tools/Skills\n Target-->>Registry: Tool/Skill Definitions\n\n Registry->>Scanner: Analyze with configured scanner(s)\n Note right of Scanner: Configured via env vars:
SECURITY_ANALYZERS=yara
or yara,llm
or cisco\n Scanner-->>Registry: Findings (severity, threats)\n\n alt SAFE - No Critical/High Issues\n Registry->>Registry: Store (enabled=true)\n else UNSAFE - Critical/High Issues Found\n Registry->>Registry: Store (enabled=false, tag=security-pending)\n end\n\n Registry-->>Client: Registration Response + Scan Summary\n end\n\n %% On-demand scanning\n rect rgb(255, 243, 224)\n note over Client,Target: On-Demand Scanning (Admin API)\n Client->>Registry: POST /api/servers/{path}/rescan
or POST /api/agents/{path}/rescan\n Registry->>Target: Connect & Fetch Tools/Skills\n Target-->>Registry: Tool/Skill Definitions\n\n Registry->>Scanner: Analyze with configured scanner(s)\n Scanner-->>Registry: Findings (severity, threats)\n\n Registry->>Registry: Update Status & Store Results\n Registry-->>Client: Scan Results Response\n end\n```\n\n## Security Scanning During Server Registration\n\nWhen adding a new MCP server to the registry, a security scan is automatically performed as part of the registration workflow. This pre-deployment scanning prevents vulnerable or malicious servers from being exposed to AI agents.\n\n### Command Format\n\n```bash\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost register --config \n```\n\n**Parameters:**\n- ``: JSON configuration file containing server details\n- Security scanning is automatically enabled by default (configured via environment variables)\n\n**Environment Variables for Security Scanning:**\n- `SECURITY_SCAN_ENABLED=true` - Enable/disable security scanning (default: true)\n- `SECURITY_SCAN_ON_REGISTRATION=true` - Scan during registration (default: true)\n- `SECURITY_SCAN_BLOCK_UNSAFE_SERVERS=true` - Auto-disable unsafe servers (default: true)\n- `SECURITY_ANALYZERS=yara` - Comma-separated list of analyzers (default: yara)\n- `SECURITY_SCAN_TIMEOUT=60` - Scan timeout in seconds (default: 60)\n- `MCP_SCANNER_LLM_API_KEY=` - API key for LLM analyzer (optional)\n\n### Example: Registering Cloudflare Documentation Server\n\n**Configuration File** (`cli/examples/cloudflare-docs-server-config.json`):\n\n```json\n{\n \"server_name\": \"Cloudflare Documentation MCP Server\",\n \"description\": \"Search Cloudflare documentation and get migration guides\",\n \"path\": \"/cloudflare-docs\",\n \"proxy_pass_url\": \"https://docs.mcp.cloudflare.com/mcp\",\n \"supported_transports\": [\"streamable-http\"]\n}\n```\n\n**Registering the Server (Security Scan Automatic):**\n\n```bash\n# Register with automatic security scan (default YARA analyzer)\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost register --config cli/examples/cloudflare-docs-server-config.json\n\n# To use LLM analyzer, set environment variable first\nexport MCP_SCANNER_LLM_API_KEY=sk-your-api-key\nexport SECURITY_ANALYZERS=yara,llm\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost register --config cli/examples/cloudflare-docs-server-config.json\n```\n\n### Security Scan Results\n\nThe scanner analyzes each tool provided by the MCP server and generates a detailed security report. Here's an example of scan results for the Cloudflare Documentation server:\n\n**Scan Output** (`security_scans/docs.mcp.cloudflare.com_mcp.json`):\n\n```json\n{\n \"analysis_results\": {\n \"yara_analyzer\": {\n \"findings\": [\n {\n \"tool_name\": \"search_cloudflare_documentation\",\n \"severity\": \"SAFE\",\n \"threat_names\": [],\n \"threat_summary\": \"No threats detected\",\n \"is_safe\": true\n },\n {\n \"tool_name\": \"migrate_pages_to_workers_guide\",\n \"severity\": \"SAFE\",\n \"threat_names\": [],\n \"threat_summary\": \"No threats detected\",\n \"is_safe\": true\n }\n ]\n }\n },\n \"tool_results\": [\n {\n \"tool_name\": \"search_cloudflare_documentation\",\n \"tool_description\": \"Search the Cloudflare documentation...\",\n \"status\": \"completed\",\n \"is_safe\": true,\n \"findings\": {\n \"yara_analyzer\": {\n \"severity\": \"SAFE\",\n \"threat_names\": [],\n \"threat_summary\": \"No threats detected\",\n \"total_findings\": 0\n }\n }\n },\n {\n \"tool_name\": \"migrate_pages_to_workers_guide\",\n \"tool_description\": \"ALWAYS read this guide before migrating Pages projects to Workers.\",\n \"status\": \"completed\",\n \"is_safe\": true,\n \"findings\": {\n \"yara_analyzer\": {\n \"severity\": \"SAFE\",\n \"threat_names\": [],\n \"threat_summary\": \"No threats detected\",\n \"total_findings\": 0\n }\n }\n }\n ]\n}\n```\n\n### What Happens When a Scan Fails\n\nIf the security scan detects critical or high severity vulnerabilities:\n\n1. **Server is Added but Disabled** - The server is registered in the database but marked as `disabled`\n2. **Security-Pending Tag** - The server receives a `security-pending` tag to flag it for review\n3. **AI Agents Cannot Access** - Disabled servers are excluded from agent discovery and tool routing\n4. **Visible in UI** - The server appears in the registry UI with clear indicators of its security status\n5. **Detailed Report Generated** - A comprehensive JSON report is saved to `security_scans/` directory\n\n**Console Output for Failed Scan:**\n\n```\n=== Security Scan ===\nScanning server for security vulnerabilities...\nSecurity scan failed - Server has critical or high severity issues\nServer will be registered but marked as UNHEALTHY with security-pending status\n\nSecurity Issues Found:\n Critical: 2\n High: 3\n Medium: 1\n Low: 0\n\nDetailed report: security_scans/scan_example.com_mcp_20251022_103045.json\n\n=== Security Status Update ===\nMarking server as UNHEALTHY due to failed security scan...\nServer registered but flagged as security-pending\nReview the security scan report before enabling this server\n\nService example-server successfully added and verified\nWARNING: Server failed security scan - Review required before use\n```\n\n**Screenshot:**\n\n![Failed Security Scan - Server in Disabled State with Security-Pending Tag](img/failed_scan.png)\n\n*Servers that fail security scans are automatically added in disabled state with a `security-pending` tag, requiring administrator review before being enabled.*\n\nThis workflow ensures that vulnerable servers never become accessible to AI agents without explicit administrator review and remediation.\n\n## Manual On-Demand Security Scans (API)\n\nAdministrators can trigger manual security scans for specific servers using the REST API or CLI commands. This is useful for:\n- Re-scanning servers after updates or patches\n- On-demand security assessments\n- Validating security fixes\n- Regular compliance checks\n\n### API Endpoints\n\n#### Trigger Security Scan (Admin Only)\n\n**Endpoint:** `POST /api/servers/{path}/rescan`\n\n**Description:** Initiates a new security scan for the specified server and returns the results.\n\n**Authentication:** JWT Bearer token or session cookie\n\n**Authorization:** Requires admin privileges\n\n**Example using CLI:**\n\n```bash\n# Trigger security scan for a specific server\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost rescan --path /cloudflare-docs\n```\n\n**Example Output:**\n\n```\nSecurity scan completed for server '/cloudflare-docs':\n Status: SAFE\n Scan timestamp: 2025-12-15T15:24:46.956393Z\n Analyzers used: yara\n\n Severity counts:\n Critical: 0\n High: 0\n Medium: 0\n Low: 0\n```\n\n**Example using curl:**\n\n```bash\ncurl -X POST http://localhost/api/servers/cloudflare-docs/rescan \\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n```\n\n#### Query Scan Results\n\n**Endpoint:** `GET /api/servers/{path}/security-scan`\n\n**Description:** Retrieves the latest security scan results for a server, including detailed threat analysis and tool-level findings.\n\n**Authentication:** JWT Bearer token or session cookie\n\n**Authorization:** Requires admin privileges or access to the server\n\n**Example using CLI:**\n\n```bash\n# Get security scan results\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost security-scan --path /cloudflare-docs\n\n# Get results in JSON format\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost security-scan --path /cloudflare-docs --json\n```\n\n**Example Output:**\n\n```\nSecurity scan results for server '/cloudflare-docs':\n\n Analyzer: yara_analyzer\n Findings: 2\n - search_cloudflare_documentation: SAFE\n - migrate_pages_to_workers_guide: SAFE\n\n Total tools scanned: 2\n Safe tools: 2\n```\n\n**Example using curl:**\n\n```bash\ncurl -X GET http://localhost/api/servers/cloudflare-docs/security-scan \\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n```\n\n### Python Client Library\n\nThe registry includes a Python client library with built-in security scan support:\n\n```python\nfrom api.registry_client import RegistryClient\n\n# Initialize client\nclient = RegistryClient(\n registry_url=\"http://localhost\",\n token_file=\".oauth-tokens/ingress.json\"\n)\n\n# Trigger security scan\nscan_result = client.rescan_server(path=\"/cloudflare-docs\")\nprint(f\"Scan Status: {'SAFE' if scan_result.is_safe else 'UNSAFE'}\")\nprint(f\"Critical Issues: {scan_result.critical_issues}\")\n\n# Get scan results\nresults = client.get_security_scan(path=\"/cloudflare-docs\")\nfor analyzer_name, analyzer_data in results.analysis_results.items():\n print(f\"Analyzer: {analyzer_name}\")\n print(f\" Findings: {len(analyzer_data.get('findings', []))}\")\n```\n\n### Scan Results Storage\n\nAll security scan results are automatically saved to the `security_scans/` directory:\n\n- **Latest Scans:** `security_scans/.json`\n- **Archived Scans:** `security_scans/YYYY-MM-DD/scan__YYYYMMDD_HHMMSS.json`\n\nThe results can be queried via the API or accessed directly from the filesystem.\n\n## A2A Agent Security Scanning\n\nThe registry provides comprehensive security scanning for Agent-to-Agent (A2A) protocol agents using the [Cisco AI Defence A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner). This ensures that agents registered in the system are safe and compliant with security standards before being made available.\n\n### Automated Scanning During Agent Registration\n\nWhen registering a new A2A agent, security scanning is automatically performed as part of the registration workflow.\n\n**Command Format:**\n\n```bash\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost agent-register --config \n```\n\n**Environment Variables for Agent Security Scanning:**\n- `AGENT_SECURITY_SCAN_ENABLED=true` - Enable/disable agent security scanning (default: true)\n- `AGENT_SECURITY_SCAN_ON_REGISTRATION=true` - Scan during registration (default: true)\n- `AGENT_SECURITY_BLOCK_UNSAFE_AGENTS=true` - Auto-disable unsafe agents (default: true)\n- `AGENT_SECURITY_ANALYZERS=yara,spec` - Comma-separated list of analyzers (default: yara,spec)\n- `AGENT_SECURITY_SCAN_TIMEOUT=60` - Scan timeout in seconds (default: 60)\n- `AGENT_SECURITY_ADD_PENDING_TAG=true` - Add security-pending tag to unsafe agents (default: true)\n\n**Example: Registering Flight Booking Agent**\n\n```bash\n# Register agent with automatic security scan\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost agent-register \\\n --config cli/examples/flight_booking_agent_card.json\n```\n\n**Example Output:**\n\n```json\n{\n \"message\": \"Agent registered successfully\",\n \"agent\": {\n \"name\": \"Flight Booking Agent\",\n \"path\": \"/flight-booking\",\n \"url\": \"http://flight-booking-agent:9000/\",\n \"num_skills\": 5,\n \"is_enabled\": true\n }\n}\n```\n\nThe agent is automatically enabled if it passes the security scan. If vulnerabilities are detected, the agent is registered but disabled with a `security-pending` tag.\n\n### Manual On-Demand Agent Scans (API)\n\nAdministrators can trigger manual security scans for specific agents using CLI commands or the REST API.\n\n#### Trigger Agent Security Scan (Admin Only)\n\n**Endpoint:** `POST /api/agents/{path}/rescan`\n\n**Description:** Initiates a new security scan for the specified agent and returns the results.\n\n**Authentication:** JWT Bearer token or session cookie\n\n**Authorization:** Requires admin privileges\n\n**Example using CLI:**\n\n```bash\n# Trigger security scan for a specific agent\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost agent-rescan --path /flight-booking\n```\n\n**Example Output:**\n\n```\nSecurity scan completed for agent '/flight-booking':\n Status: SAFE\n Scan timestamp: 2025-12-17T19:05:37.499170Z\n Analyzers used: yara, spec\n\n Severity counts:\n Critical: 0\n High: 0\n Medium: 0\n Low: 0\n\n Output file: /app/agent_security_scans/flight-booking.json\n```\n\n**Example with JSON output:**\n\n```bash\n# Get JSON format output\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost agent-rescan --path /flight-booking --json\n```\n\n### Query Agent Scan Results\n\nAgent security scan results are stored in the `agent_security_scans/` directory and can be accessed directly:\n\n**Storage Locations:**\n- **Latest Scans:** `agent_security_scans/.json`\n- **Archived Scans:** `agent_security_scans/YYYY-MM-DD/scan__YYYYMMDD_HHMMSS.json`\n\n**Viewing scan results:**\n\n```bash\n# Set registry container variable\nexport REGISTRY_CONTAINER=$(docker ps --filter \"name=registry\" --format \"{{.Names}}\" | grep \"registry-1\")\n\n# View scan results inside container\ndocker exec $REGISTRY_CONTAINER cat /app/agent_security_scans/flight-booking.json | jq '.'\n\n# Copy scan results to local machine\ndocker cp $REGISTRY_CONTAINER:/app/agent_security_scans/flight-booking.json ./flight_booking_scan.json\n```\n\n**Example Scan Result:**\n\n```json\n{\n \"analysis_results\": {},\n \"scan_results\": {\n \"target_name\": \"Flight Booking Agent\",\n \"target_type\": \"agent_card\",\n \"status\": \"completed\",\n \"analyzers\": [\"yara\", \"heuristic\", \"spec\", \"endpoint\"],\n \"findings\": [],\n \"metadata\": {\n \"agent_id\": null,\n \"url\": \"http://flight-booking-agent:9000/\"\n },\n \"total_findings\": 0,\n \"high_severity_count\": 0\n }\n}\n```\n\n### Python Client Library for Agent Scanning\n\n```python\nfrom api.registry_client import RegistryClient\n\n# Initialize client\nclient = RegistryClient(\n registry_url=\"http://localhost\",\n token_file=\".oauth-tokens/ingress.json\"\n)\n\n# Trigger agent security scan\nscan_result = client.rescan_agent(path=\"/flight-booking\")\nprint(f\"Scan Status: {'SAFE' if scan_result.is_safe else 'UNSAFE'}\")\nprint(f\"Critical Issues: {scan_result.critical_issues}\")\nprint(f\"Analyzers Used: {', '.join(scan_result.analyzers_used)}\")\n```\n\n### What Happens When an Agent Scan Fails\n\nIf the security scan detects critical or high severity vulnerabilities:\n\n1. **Agent is Registered but Disabled** - The agent is added to the database but marked as `is_enabled=false`\n2. **Security-Pending Tag** - The agent receives a `security-pending` tag to flag it for review\n3. **Excluded from Discovery** - Disabled agents are not returned in agent discovery queries\n4. **Detailed Report Generated** - A comprehensive JSON report is saved to `agent_security_scans/` directory\n\nAdministrators must review the security scan results and remediate any issues before manually enabling the agent.\n\n## Agent Skills Security Scanning\n\nThe registry provides comprehensive security scanning for Agent Skills (SKILL.md files) using the [Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/cisco-ai-skill-scanner). This ensures that skills registered in the system are safe and do not contain malicious instructions, prompt injection attempts, or other security threats before being made available to AI coding assistants.\n\n### Automated Scanning During Skill Registration\n\nWhen registering a new Agent Skill, security scanning is automatically performed as part of the registration workflow.\n\n**Environment Variables for Skill Security Scanning:**\n- `SKILL_SECURITY_SCAN_ENABLED=true` - Enable/disable skill security scanning (default: true)\n- `SKILL_SECURITY_SCAN_ON_REGISTRATION=true` - Scan during registration (default: true)\n- `SKILL_SECURITY_BLOCK_UNSAFE_SKILLS=true` - Auto-disable unsafe skills (default: true)\n- `SKILL_SECURITY_ANALYZERS=static` - Comma-separated list of analyzers (default: static)\n- `SKILL_SECURITY_SCAN_TIMEOUT=120` - Scan timeout in seconds (default: 120)\n- `SKILL_SECURITY_ADD_PENDING_TAG=true` - Add security-pending tag to unsafe skills (default: true)\n- `SKILL_SECURITY_LLM_API_KEY=` - API key for LLM analyzer (optional)\n- `SKILL_SECURITY_VIRUSTOTAL_API_KEY=` - API key for VirusTotal integration (optional)\n- `SKILL_SECURITY_AI_DEFENSE_API_KEY=` - API key for Cisco AI Defense (optional)\n\n**Available Analyzers:**\n- `static` - Static code analysis for common security patterns\n- `behavioral` - Behavioral analysis of skill instructions\n- `llm` - LLM-powered semantic analysis (requires API key)\n- `virustotal` - VirusTotal URL reputation checking (requires API key)\n- `ai-defense` - Cisco AI Defense cloud analysis (requires API key)\n- `meta` - Meta-analyzer combining results from other analyzers\n\n**Example: Registering a Skill with Security Scan**\n\nUsing the UI:\n1. Navigate to Skills section in the dashboard\n2. Click \"Register Skill\"\n3. Enter the SKILL.md URL (e.g., `https://github.com/org/repo/blob/main/skills/pdf/SKILL.md`)\n4. The skill is automatically scanned during registration\n5. View scan results in the skill card's security shield icon\n\nUsing the CLI:\n```bash\n# Register skill with automatic security scan\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost skill-register \\\n --name pdf \\\n --url \"https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md\" \\\n --description \"Create and manipulate PDF documents\" \\\n --tags pdf,documents,conversion \\\n --visibility public\n```\n\n### Manual On-Demand Skill Scans (API)\n\nAdministrators can trigger manual security scans for specific skills using CLI commands or the REST API.\n\n#### Trigger Skill Security Scan (Admin Only)\n\n**Endpoint:** `POST /api/skills/{path}/rescan`\n\n**Description:** Initiates a new security scan for the specified skill and returns the results.\n\n**Authentication:** JWT Bearer token or session cookie\n\n**Authorization:** Requires admin privileges\n\n**Example using CLI:**\n\n```bash\n# Trigger security scan for a specific skill\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost skill-rescan --path pdf\n```\n\n**Example Output:**\n\n```\nSecurity scan completed for skill '/pdf':\n Status: SAFE\n Scan timestamp: 2026-02-20T10:30:00.000000Z\n Analyzers used: static\n\n Severity counts:\n Critical: 0\n High: 0\n Medium: 0\n Low: 0\n```\n\n**Example using curl:**\n\n```bash\ncurl -X POST http://localhost/api/skills/pdf/rescan \\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n```\n\n#### Query Skill Scan Results\n\n**Endpoint:** `GET /api/skills/{path}/security-scan`\n\n**Description:** Retrieves the latest security scan results for a skill, including detailed threat analysis and findings.\n\n**Authentication:** JWT Bearer token or session cookie\n\n**Authorization:** Requires admin privileges or access to the skill\n\n**Example using CLI:**\n\n```bash\n# Get security scan results\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost skill-security-scan --path pdf\n\n# Get results in JSON format\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost skill-security-scan --path pdf --json\n```\n\n**Example Output:**\n\n```json\n{\n \"skill_path\": \"/pdf\",\n \"skill_md_url\": \"https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md\",\n \"scan_timestamp\": \"2026-02-20T10:30:00.000000Z\",\n \"is_safe\": true,\n \"critical_issues\": 0,\n \"high_severity\": 0,\n \"medium_severity\": 0,\n \"low_severity\": 0,\n \"analyzers_used\": [\"static\"],\n \"scan_failed\": false\n}\n```\n\n### Python Client Library for Skill Scanning\n\n```python\nfrom api.registry_client import RegistryClient\n\n# Initialize client\nclient = RegistryClient(\n registry_url=\"http://localhost\",\n token_file=\".oauth-tokens/ingress.json\"\n)\n\n# Trigger skill security scan\nscan_result = client.rescan_skill(path=\"/pdf\")\nprint(f\"Scan Status: {'SAFE' if scan_result.is_safe else 'UNSAFE'}\")\nprint(f\"Critical Issues: {scan_result.critical_issues}\")\nprint(f\"Analyzers Used: {', '.join(scan_result.analyzers_used)}\")\n\n# Get skill scan results\nresults = client.get_skill_security_scan(path=\"/pdf\")\nprint(f\"Last Scan: {results.scan_timestamp}\")\nprint(f\"Is Safe: {results.is_safe}\")\n```\n\n### What the Skill Scanner Detects\n\nThe Cisco AI Defense Skill Scanner analyzes SKILL.md files for various security threats:\n\n1. **Prompt Injection Attempts** - Malicious instructions designed to manipulate AI behavior\n2. **Command Injection Patterns** - Dangerous shell command patterns in skill instructions\n3. **Data Exfiltration Risks** - Instructions that could leak sensitive information\n4. **Privilege Escalation** - Instructions attempting to gain elevated permissions\n5. **Social Engineering** - Deceptive patterns designed to trick users or AI systems\n6. **Malicious URL References** - Links to known malicious domains\n7. **Sensitive Data Handling** - Improper handling of credentials, tokens, or PII\n\n### What Happens When a Skill Scan Fails\n\nIf the security scan detects critical or high severity vulnerabilities:\n\n1. **Skill is Registered but Disabled** - The skill is added to the database but marked as `is_enabled=false`\n2. **Security-Pending Tag** - The skill receives a `security-pending` tag to flag it for review\n3. **Excluded from Discovery** - Disabled skills are not returned in skill discovery queries\n4. **Shield Icon Indicator** - The skill card shows a red shield icon in the UI\n5. **Detailed Report Available** - Click the shield icon to view detailed findings\n\nAdministrators must review the security scan results and remediate any issues before manually enabling the skill.\n\n## Periodic Registry Scans\n\nBeyond initial registration security checks, the registry supports comprehensive periodic scans of all enabled servers. This ongoing monitoring detects newly discovered vulnerabilities and ensures continued security compliance.\n\n### Command to Run Periodic Scans\n\n```bash\ncd /home/ubuntu/repos/mcp-gateway-registry\nuv run cli/scan_all_servers.py --base-url https://mcpgateway.example.com\n```\n\n**Command Options:**\n\n```bash\n# Scan with default YARA analyzer\nuv run cli/scan_all_servers.py --base-url https://mcpgateway.example.com\n\n# Scan with both YARA and LLM analyzers (requires API key in .env)\nuv run cli/scan_all_servers.py --base-url https://mcpgateway.example.com --analyzers yara,llm\n\n# Specify custom output directory\nuv run cli/scan_all_servers.py --base-url https://mcpgateway.example.com --output-dir custom_scans\n```\n\n### Generated Report\n\nThe periodic scan generates a comprehensive markdown report that provides an executive summary and detailed vulnerability breakdown for each server in the registry.\n\n**Report Locations:**\n- **Latest Report:** `security_scans/scan_report.md` (always current)\n- **Archived Reports:** `security_scans/reports/scan_report_YYYYMMDD_HHMMSS.md` (timestamped history)\n\nFor a complete example of the report format and structure, see [scan_report_example.md](scan_report_example.md).\n\n### Report Contents\n\nThe generated security report includes:\n\n1. **Executive Summary**\n - Total servers scanned\n - Pass/fail statistics\n - Overall security posture metrics\n\n2. **Aggregate Vulnerability Statistics**\n - Total count by severity level (Critical, High, Medium, Low)\n - Trend analysis across multiple scans\n\n3. **Per-Server Vulnerability Breakdown**\n - Individual server security status\n - Severity distribution per server\n - Scan timestamp and analyzer information\n\n4. **Detailed Findings for Vulnerable Tools**\n - Specific tool names and descriptions\n - Threat categories and taxonomy\n - AI Security Framework (AITech) classification\n - Remediation guidance\n\n**Example Report Summary:**\n\n---\n\n# MCP Server Security Scan Report\n\n**Scan Date:** 2025-10-21 23:50:03 UTC\n**Analyzers Used:** yara\n\n## Executive Summary\n\n- **Total Servers Scanned:** 6\n- **Passed:** 2 (33.3%)\n- **Failed:** 4 (66.7%)\n\n### Aggregate Vulnerability Statistics\n\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 3 |\n| Medium | 0 |\n| Low | 0 |\n\n---\n\nThese reports enable security teams to track vulnerability trends, prioritize remediation efforts, and maintain compliance with organizational security policies.\n\n## Analyzers\n\nThe MCP Scanner supports two analyzer types, each with distinct capabilities and use cases:\n\n### YARA Analyzer\n\n**Type:** Pattern-based detection\n**Speed:** Fast (seconds per server)\n**API Key Required:** No\n**Best For:** Known threat patterns, common vulnerabilities\n\nThe YARA analyzer uses signature-based detection rules to identify known security threats including:\n- SQL injection patterns\n- Command injection vulnerabilities\n- Cross-site scripting (XSS) vectors\n- Path traversal attempts\n- Hardcoded credentials\n- Malicious code patterns\n\nYARA scanning is ideal for automated workflows and continuous integration pipelines due to its speed and zero-configuration requirements.\n\n### LLM Analyzer\n\n**Type:** AI-powered semantic analysis\n**Speed:** Slower (requires API calls)\n**API Key Required:** Yes (OpenAI-compatible API)\n**Best For:** Sophisticated threats, zero-day vulnerabilities, context-aware analysis\n\nThe LLM analyzer uses large language models to perform deep semantic analysis of tool code and descriptions. It can detect:\n- Subtle logic vulnerabilities\n- Context-dependent security issues\n- Novel attack patterns\n- Business logic flaws\n- Privacy concerns in data handling\n\nLLM scanning is recommended for high-value or high-risk MCP servers where comprehensive security analysis justifies the additional time and API costs.\n\n### Analyzer Comparison\n\n| Feature | YARA | LLM | Both |\n|---------|------|-----|------|\n| **Speed** | Fast (seconds) | Slower (minutes) | Slower |\n| **API Key** | Not required | Required | Required |\n| **Detection Type** | Pattern-based | Semantic analysis | Comprehensive |\n| **False Positives** | Low | Medium | Low |\n| **Coverage** | Known threats | Known + novel threats | Maximum |\n| **Use Case** | Automated scans, CI/CD | Critical servers, deep analysis | High-security environments |\n\n### Configuring LLM Analyzer\n\nTo use the LLM analyzer, set the API key in your `.env` file:\n\n```bash\n# Add to .env file\nMCP_SCANNER_LLM_API_KEY=sk-your-openai-api-key\n```\n\n**Using Both Analyzers:**\n\n```bash\n# During server addition\n./cli/service_mgmt.sh add config.json yara,llm\n\n# During periodic scans\nuv run cli/scan_all_servers.py --base-url https://mcpgateway.example.com --analyzers yara,llm\n```\n\n### Recommendation\n\n- **Default (YARA only):** Suitable for most use cases, provides fast scanning with no API costs\n- **Add LLM:** For critical production servers, sensitive data environments, or when unknown threats are a concern\n- **Both analyzers:** Recommended for maximum security coverage in high-stakes deployments\n\nThe combination of both analyzers provides defense-in-depth, with YARA catching known threats quickly and LLM performing deeper analysis for sophisticated attacks.\n\n## Prerequisites\n\n### Set LLM API Key (Optional)\n\nOnly required if using the LLM analyzer:\n\n```bash\n# Add to .env file (recommended)\necho \"MCP_SCANNER_LLM_API_KEY=sk-your-api-key\" >> .env\n```\n\n## Troubleshooting\n\n### API Key Issues\n\nIf you see errors about missing API keys when using the LLM analyzer:\n\n```bash\n# Verify the key is set\necho $MCP_SCANNER_LLM_API_KEY\n\n# Add to .env file\necho \"MCP_SCANNER_LLM_API_KEY=sk-your-key\" >> .env\n```\n\nNote: The scanner uses `MCP_SCANNER_LLM_API_KEY`, not `OPENAI_API_KEY`.\n\n### Permission Issues\n\nEnsure the `security_scans/` directory is writable:\n\n```bash\nmkdir -p security_scans\nchmod 755 security_scans\n```\n\n## Additional Resources\n\n### Documentation\n- **Cisco AI Defence MCP Scanner:** https://github.com/cisco-ai-defense/mcp-scanner\n- **Cisco AI Defence A2A Scanner:** https://github.com/cisco-ai-defense/a2a-scanner\n- **Cisco AI Defense Skill Scanner:** https://github.com/cisco-ai-defense/cisco-ai-skill-scanner\n- **Example Report:** [scan_report_example.md](scan_report_example.md)\n\n### CLI Tools\n- **Registry Management CLI:** `api/registry_management.py` - Main CLI for server and agent registration with security scanning\n- **Periodic Scan Script:** `cli/scan_all_servers.py` - Comprehensive registry-wide security audits for MCP servers\n\n### MCP Server API Endpoints\n- **Trigger Server Scan:** `POST /api/servers/{path}/rescan` - Admin-only manual security scan for MCP servers\n- **Query Server Results:** `GET /api/servers/{path}/security-scan` - Retrieve MCP server scan results\n\n### A2A Agent API Endpoints\n- **Trigger Agent Scan:** `POST /api/agents/{path}/rescan` - Admin-only manual security scan for A2A agents\n- **Query Agent Results:** `GET /api/agents/{path}/security-scan` - Retrieve A2A agent scan results (file system access recommended)\n\n### Agent Skills API Endpoints\n- **Trigger Skill Scan:** `POST /api/skills/{path}/rescan` - Admin-only manual security scan for Agent Skills\n- **Query Skill Results:** `GET /api/skills/{path}/security-scan` - Retrieve Agent Skills scan results\n\n### Registry Management CLI Commands\n\n#### MCP Server Security Commands\n```bash\n# Trigger server security scan\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost rescan --path /server-path\n\n# Get server scan results\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost security-scan --path /server-path\n```\n\n#### A2A Agent Security Commands\n```bash\n# Trigger agent security scan\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost agent-rescan --path /agent-path\n\n# Get agent scan results (with JSON output)\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost agent-rescan --path /agent-path --json\n```\n\n#### Agent Skills Security Commands\n```bash\n# Trigger skill security scan\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost skill-rescan --path skill-path\n\n# Get skill scan results\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost skill-security-scan --path skill-path\n\n# Get skill scan results (with JSON output)\nuv run python api/registry_management.py --token-file .oauth-tokens/ingress.json \\\n --registry-url http://localhost skill-security-scan --path skill-path --json\n```\n\n### Python Client\n- **Registry Client:** `api/registry_client.py` - Python library with security scanning methods:\n - `rescan_server(path)` - Trigger MCP server security scan\n - `get_security_scan(path)` - Get MCP server scan results\n - `rescan_agent(path)` - Trigger A2A agent security scan\n - `get_agent_security_scan(path)` - Get A2A agent scan results\n - `rescan_skill(path)` - Trigger Agent Skill security scan\n - `get_skill_security_scan(path)` - Get Agent Skill scan results\n" }, { "path": "docs/server-versioning-operations.md", "content": "# MCP Server Versioning - Operations Guide\n\nThis guide covers the operational workflows for managing multiple versions of MCP servers in the gateway registry.\n\nFor the technical design and architecture details, see [Server Versioning Design](design/server-versioning.md).\n\n### UI Demo\n\nThe following shows the version badges on server cards (both the MCP server-reported version and the user-provided routing version) and the version swap workflow using the Version Selector Modal:\n\n![MCP Server Versioning UI Flow](img/mcp-server-versioning.gif)\n\n---\n\n## Understanding What You See on the Dashboard\n\n### Version Badges on Server Cards\n\nEach server card can display up to two version indicators:\n\n**Routing Version Badge** (e.g., `v2.0.0` with a dropdown arrow):\n- This is the user-provided version label that controls which backend receives traffic.\n- Only appears when the server has multiple versions registered.\n- Clicking the badge opens the Version Selector Modal where you can switch the active version.\n- Single-version servers do not show this badge.\n\n**MCP Server Version Badge** (e.g., `srv 2.14.5`):\n- This is the software version reported by the running MCP server during health checks.\n- This value is determined automatically -- it comes from the `serverInfo.version` field in the MCP `initialize` response.\n- A small green dot appears if this version changed within the last 24 hours, indicating the upstream server deployed a new build.\n- This badge is informational only and does not affect routing.\n\nThese two versions are independent. The routing version is an operational label you control. The MCP server version is a fact about what code is running at the backend URL.\n\n---\n\n## Workflow 1: MCP Server Updates Its Own Version\n\n**Scenario**: An MCP server developer deploys a new build. The server at `https://mcp.context7.com/mcp` starts reporting version `2.14.5` instead of `2.14.4`. No admin action was taken.\n\n**What happens automatically**:\n\n1. The next health check runs against the active version endpoint\n2. The health check reads `serverInfo.version` from the MCP `initialize` response\n3. The registry detects the version changed from `2.14.4` to `2.14.5`\n4. The registry stores:\n - `mcp_server_version`: `2.14.5` (new value)\n - `mcp_server_version_previous`: `2.14.4` (old value)\n - `mcp_server_version_updated_at`: current timestamp\n5. A WARNING log message is emitted noting the version change\n6. The dashboard card shows `srv 2.14.5` with a green dot indicator\n\n**What the admin sees**:\n\n- The `srv` badge on the server card updates to show the new version\n- A green dot appears next to the version for 24 hours\n- Hovering over the badge shows: \"MCP Server Version: 2.14.5 (previously 2.14.4)\"\n\n**No action required**. This is purely informational. The routing configuration does not change. Traffic continues to flow to the same backend URL. The user-provided routing version label (e.g., `v1.0.0`) is unaffected.\n\n---\n\n## Workflow 2: Platform Admin Registers a New Version of a Server\n\n**Scenario**: A platform admin wants to add version `v2.0.0` of Context7 pointing to a new backend URL, while keeping `v1.0.0` active.\n\n### Step 1: Register the New Version\n\nRegister the server with the same path but a different version. The registry detects this is a new version of an existing server and creates it as an inactive version document.\n\n**Using the CLI**:\n```bash\nuv run python -m api.registry_management register \\\n --name \"Context7 MCP Server\" \\\n --path /context7 \\\n --version v2.0.0 \\\n --status beta \\\n --proxy-url \"https://mcp-v2.context7.com/mcp\" \\\n --transport streamable-http \\\n --tags documentation,search,libraries\n```\n\n**Using the API**:\n```bash\ncurl -X POST https://gateway.example.com/api/servers/register \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"server_name\": \"Context7 MCP Server\",\n \"path\": \"/context7\",\n \"version\": \"v2.0.0\",\n \"status\": \"beta\",\n \"proxy_pass_url\": \"https://mcp-v2.context7.com/mcp\",\n \"supported_transports\": [\"streamable-http\"],\n \"tags\": [\"documentation\", \"search\", \"libraries\"]\n }'\n```\n\n**Using a JSON config file**:\n```bash\nuv run python -m api.registry_management register --config cli/examples/context7-v2-server-config.json\n```\n\nExample config file (`context7-v2-server-config.json`):\n```json\n{\n \"server_name\": \"Context7 MCP Server\",\n \"description\": \"Up-to-date Docs for LLMs and AI code editors (Version 2 - Beta)\",\n \"path\": \"/context7\",\n \"version\": \"v2.0.0\",\n \"status\": \"beta\",\n \"proxy_pass_url\": \"https://mcp-v2.context7.com/mcp\",\n \"supported_transports\": [\"streamable-http\"],\n \"tags\": [\"documentation\", \"search\", \"libraries\", \"packages\", \"api-reference\", \"code-examples\"]\n}\n```\n\n### What Happens After Registration\n\n1. The registry detects that `/context7` already exists with version `v1.0.0`\n2. A new **inactive** version document is created at `_id: /context7:v2.0.0`\n3. The active version document at `_id: /context7` is updated with `/context7:v2.0.0` added to its `other_version_ids` array\n4. The nginx configuration is regenerated to include a version map entry for `v2.0.0`\n5. Nginx is reloaded\n\nThe API response includes `\"is_new_version\": true` to confirm a version was added rather than a new server created.\n\n### What the Admin Sees on the Dashboard\n\n- The existing Context7 server card now shows a **version badge** (e.g., `v1.0.0` with a dropdown arrow)\n- Clicking the badge opens the **Version Selector Modal** showing both versions\n- `v1.0.0` is marked as `ACTIVE` (green badge)\n- `v2.0.0` is marked as `beta` (blue badge)\n\n### Step 2: Test the New Version\n\nBefore promoting `v2.0.0` to active, test it using the `X-MCP-Server-Version` header:\n\n**In an AI coding assistant** (e.g., Roo Code, Claude Desktop):\n\nAdd the header to the MCP server configuration:\n```json\n{\n \"mcpServers\": {\n \"context7\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://gateway.example.com/context7\",\n \"headers\": {\n \"X-MCP-Server-Version\": \"v2.0.0\",\n \"X-Authorization\": \"Bearer \"\n }\n }\n }\n}\n```\n\n**With curl**:\n```bash\ncurl -X POST https://gateway.example.com/context7 \\\n -H \"X-MCP-Server-Version: v2.0.0\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1}'\n```\n\nTraffic without the header continues to route to `v1.0.0`. Only requests with the explicit header reach `v2.0.0`.\n\n### Step 3: Promote to Active\n\nOnce testing is complete, switch the active version:\n\n**Using the Version Selector Modal (UI)**:\n1. Click the version badge on the Context7 server card\n2. In the modal, click \"Set Active\" on version `v2.0.0`\n3. The modal closes and the card updates\n\n**Using the API**:\n```bash\ncurl -X PUT https://gateway.example.com/api/servers/context7/versions/default \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"version\": \"v2.0.0\"}'\n```\n\n**Using the CLI**:\n```bash\nuv run python -m api.registry_management set-default-version \\\n --path /context7 \\\n --version v2.0.0\n```\n\n### What Happens During the Switch\n\n1. The current active document (`/context7`, version `v1.0.0`) becomes an inactive document at `_id: /context7:v1.0.0`\n2. The target inactive document (`/context7:v2.0.0`) becomes the new active document at `_id: /context7`\n3. The `other_version_ids` array is updated to reference `/context7:v1.0.0` instead of `/context7:v2.0.0`\n4. The FAISS search index is re-indexed with `v2.0.0` metadata\n5. The nginx configuration is regenerated and reloaded\n6. A background health check is triggered for the newly active version\n7. The dashboard updates to show `v2.0.0` as active\n\nAll traffic without the `X-MCP-Server-Version` header now routes to `v2.0.0`. Clients that still send `X-MCP-Server-Version: v1.0.0` continue to reach the old version.\n\n---\n\n## Workflow 3: Instant Rollback\n\n**Scenario**: After promoting `v2.0.0`, you discover an issue and need to revert to `v1.0.0`.\n\n```bash\n# API\ncurl -X PUT https://gateway.example.com/api/servers/context7/versions/default \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"version\": \"v1.0.0\"}'\n\n# CLI\nuv run python -m api.registry_management set-default-version \\\n --path /context7 \\\n --version v1.0.0\n```\n\nThe switch is immediate:\n- All default traffic reverts to `v1.0.0`\n- Clients with `X-MCP-Server-Version: v2.0.0` can still reach `v2.0.0` for debugging\n- A health check runs automatically for the restored version\n\n---\n\n## Workflow 4: Deprecate and Remove an Old Version\n\n### Mark as Deprecated\n\nWhen registering the version, use `--status deprecated`:\n```bash\nuv run python -m api.registry_management register \\\n --name \"Context7 MCP Server\" \\\n --path /context7 \\\n --version v1.0.0 \\\n --status deprecated \\\n --proxy-url \"https://mcp.context7.com/mcp\" \\\n --transport streamable-http\n```\n\nThe Version Selector Modal shows deprecated versions with an amber badge.\n\n### Remove a Version\n\n```bash\n# API\ncurl -X DELETE https://gateway.example.com/api/servers/context7/versions/v1.0.0 \\\n -H \"Authorization: Bearer \"\n\n# CLI\nuv run python -m api.registry_management remove-version \\\n --path /context7 \\\n --version v1.0.0\n```\n\nConstraints:\n- You **cannot remove the currently active version**. Switch to a different version first.\n- Removing a version deletes its document from the database and removes its nginx map entry.\n- Clients sending `X-MCP-Server-Version: v1.0.0` will fall back to the default version after removal.\n\n---\n\n## Workflow 5: List All Versions\n\n```bash\n# API\ncurl https://gateway.example.com/api/servers/context7/versions \\\n -H \"Authorization: Bearer \"\n\n# CLI\nuv run python -m api.registry_management list-versions --path /context7\n```\n\nResponse:\n```json\n{\n \"path\": \"/context7\",\n \"default_version\": \"v2.0.0\",\n \"versions\": [\n {\n \"version\": \"v2.0.0\",\n \"proxy_pass_url\": \"https://mcp-v2.context7.com/mcp\",\n \"status\": \"stable\",\n \"is_default\": true\n },\n {\n \"version\": \"v1.0.0\",\n \"proxy_pass_url\": \"https://mcp.context7.com/mcp\",\n \"status\": \"deprecated\",\n \"is_default\": false,\n \"sunset_date\": \"2026-06-01\"\n }\n ]\n}\n```\n\n---\n\n## Workflow 6: Delete a Server (All Versions)\n\nWhen you delete a server entirely, all version documents are cascade-deleted:\n\n```bash\n# CLI\nuv run python -m api.registry_management delete --path /context7\n\n# API\ncurl -X DELETE https://gateway.example.com/api/servers/context7 \\\n -H \"Authorization: Bearer \"\n```\n\nThis removes:\n- The active version document at `/context7`\n- All inactive version documents matching `/context7:*`\n- The FAISS search index entry\n- The nginx location block and map entries\n\n---\n\n## How Versioning Affects Search\n\nOnly the **active version** of each server appears in search results. Inactive versions are excluded at index time (they are never added to the FAISS vector index), so they do not consume result slots.\n\nWhen you switch the active version, the search index is automatically re-indexed with the new active version's metadata (name, description, tags, tools). This means search results always reflect the currently active version.\n\n---\n\n## How Versioning Affects Health Checks\n\nOnly the **active version** is health-checked. Inactive versions are skipped during the health check cycle. When you switch the active version, a health check for the newly active version is triggered immediately in the background.\n\n---\n\n## Client Configuration for Version Pinning\n\nClients that need to pin to a specific version add the `X-MCP-Server-Version` header to their requests:\n\n### Claude Desktop / Roo Code / Other MCP Clients\n\n```json\n{\n \"mcpServers\": {\n \"context7\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://gateway.example.com/context7\",\n \"headers\": {\n \"X-MCP-Server-Version\": \"v1.0.0\"\n }\n }\n }\n}\n```\n\n### Programmatic Access\n\n```python\nimport httpx\n\nresponse = httpx.post(\n \"https://gateway.example.com/context7\",\n headers={\n \"X-MCP-Server-Version\": \"v1.0.0\",\n \"Content-Type\": \"application/json\",\n },\n json={\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1},\n)\n```\n\n### Header Values\n\n| Value | Behavior |\n|-------|----------|\n| Omitted | Routes to active (default) version |\n| `latest` | Routes to active (default) version |\n| `v1.0.0` | Routes to version v1.0.0 specifically |\n| Unknown value | Falls back to default backend URL |\n" }, { "path": "docs/service-management.md", "content": "# Service Management Guide\n\nThis guide documents how to manage MCP servers, users, and access groups in the MCP Gateway Registry using the **Registry Management API**.\n\n## Table of Contents\n- [Overview](#overview)\n- [What's New](#whats-new)\n- [Prerequisites](#prerequisites)\n- [Quick Start](#quick-start)\n- [Service Management](#service-management)\n - [Add Server](#add-server)\n - [Delete Server](#delete-server)\n - [List Servers](#list-servers)\n - [Enable/Disable Server](#enabledisable-server)\n- [Group Management](#group-management)\n - [Create Group](#create-group)\n - [Delete Group](#delete-group)\n - [List Groups](#list-groups)\n - [Add Server to Group](#add-server-to-group)\n - [Remove Server from Group](#remove-server-from-group)\n- [User Management](#user-management)\n - [Create M2M User](#create-m2m-user)\n - [Create Human User](#create-human-user)\n - [Delete User](#delete-user)\n - [List Users](#list-users)\n- [Complete Workflow Example](#complete-workflow-example)\n- [Configuration Format](#configuration-format)\n- [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThe MCP Gateway Registry provides a comprehensive **Registry Management API** for programmatic access to all registry operations. This API replaces the previous shell script approach with a modern, type-safe Python interface.\n\n**Management Options:**\n\n1. **Registry Management API** (`api/registry_management.py`): Core API for server, group, and user management\n2. **Registry Client** (`api/registry_client.py`): High-level Python client with authentication handling\n3. **REST API Endpoints**: Direct HTTP API access at `/api/management/*`\n\nThese tools work together to provide:\n- **Server Registration**: Validates config and registers new servers\n- **Access Control**: Fine-grained permissions via groups\n- **User Management**: M2M service accounts and human users\n- **Health Verification**: Confirms servers are working and discoverable\n- **FAISS Integration**: Automatic indexing for intelligent tool discovery\n\n## What's New\n\n**Registry Management API** (New in v1.0.7):\n- Modern Python API for all registry operations\n- Type-safe interfaces using Pydantic models\n- Automatic FAISS indexing on server registration\n- Integrated health checking and validation\n- RESTful HTTP endpoints for external integrations\n- Comprehensive error handling and logging\n\nThe new API provides the same functionality as the previous shell scripts but with better error handling, type safety, and integration capabilities.\n\n## Prerequisites\n\nBefore using the Registry Management API, ensure:\n\n1. **MCP Gateway is running**: All containers should be up\n ```bash\n docker compose ps\n ```\n\n2. **Authentication is configured**: You need OAuth2/JWT access\n ```bash\n # Obtain an access token via OAuth2 flow or API authentication\n ```\n\n3. **Python environment**: Use `uv` for package management\n ```bash\n # Ensure uv is installed\n uv --version\n ```\n\n## Quick Start\n\n### Using the Registry Client (Python)\n\n```python\nfrom api.registry_client import RegistryClient\n\n# Initialize client\nclient = RegistryClient(\n base_url=\"http://localhost\"\n)\n\n# Add a server\nclient.add_server(\n server_name=\"My MCP Server\",\n path=\"/my-server\",\n proxy_pass_url=\"http://my-server:8000\",\n description=\"My custom MCP server\",\n tags=[\"productivity\", \"automation\"]\n)\n\n# List all servers\nservers = client.list_servers()\nfor server in servers:\n print(f\"{server['name']}: {server['path']}\")\n\n# Delete a server\nclient.delete_server(\"my-server\")\n```\n\n### Using the REST API (HTTP)\n\n```bash\n# Get access token via OAuth2 client credentials flow\nTOKEN=$(curl -X POST http://localhost/api/auth/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d 'grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret' | jq -r '.access_token')\n\n# Add a server\ncurl -X POST http://localhost/api/management/servers \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"server_name\": \"My MCP Server\",\n \"path\": \"/my-server\",\n \"proxy_pass_url\": \"http://my-server:8000\",\n \"description\": \"My custom MCP server\",\n \"tags\": [\"productivity\", \"automation\"]\n }'\n\n# List servers\ncurl -X GET http://localhost/api/management/servers \\\n -H \"Authorization: Bearer $TOKEN\"\n\n# Delete a server\ncurl -X DELETE http://localhost/api/management/servers/my-server \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Service Management\n\n### Add Server\n\n#### Using Python Client\n\n```python\nfrom api.registry_client import RegistryClient\n\nclient = RegistryClient(\n base_url=\"http://localhost\"\n)\n\n# Add server with all options\nresponse = client.add_server(\n server_name=\"Advanced MCP Server\",\n path=\"/advanced-server\",\n proxy_pass_url=\"http://advanced-server:8001/\",\n description=\"A server with all optional fields\",\n tags=[\"productivity\", \"automation\", \"enterprise\"],\n num_tools=5,\n num_stars=4,\n is_python=True,\n license=\"MIT\",\n metadata={\n \"team\": \"data-platform\",\n \"owner\": \"alice@example.com\",\n \"compliance_level\": \"PCI-DSS\",\n \"cost_center\": \"engineering\",\n \"deployment_region\": \"us-east-1\"\n }\n)\n\nprint(f\"Server added: {response['name']}\")\n```\n\n#### Custom Metadata\n\nServers support optional custom metadata for organization, compliance, and integration tracking. All metadata is fully searchable via semantic search.\n\n**Example with Metadata:**\n```python\n# Add server with custom metadata\nresponse = client.add_server(\n server_name=\"Payment Processor\",\n path=\"/payment-processor\",\n proxy_pass_url=\"http://payment:8080/\",\n description=\"Payment processing service\",\n tags=[\"finance\", \"payments\"],\n metadata={\n \"team\": \"finance-platform\",\n \"owner\": \"bob@example.com\",\n \"compliance_level\": \"PCI-DSS\",\n \"data_classification\": \"confidential\",\n \"cost_center\": \"finance-ops\",\n \"deployment_region\": \"us-east-1\",\n \"environment\": \"production\",\n \"jira_ticket\": \"FIN-789\"\n }\n)\n```\n\n**Search by Metadata:**\n```python\n# Servers with metadata are searchable via semantic search API\n# Example queries:\n# - \"team:finance-platform servers\"\n# - \"PCI-DSS compliant services\"\n# - \"bob@example.com owned servers\"\n# - \"us-east-1 deployed services\"\n```\n\n**Metadata Use Cases:**\n- **Organization:** team, owner, department\n- **Compliance:** compliance_level, data_classification, audit_logging\n- **Cost Tracking:** cost_center, project_code, budget_allocation\n- **Deployment:** deployment_region, environment, version\n- **Integration:** jira_ticket, service_now_id, monitoring_url\n\n#### What Happens During Registration\n\n1. Config validation (required fields, constraints)\n2. Server registration with the gateway\n3. Nginx configuration update\n4. FAISS index update (automatic)\n5. Health check verification\n\n### Delete Server\n\n```python\n# Delete by server name\nclient.delete_server(\"advanced-server\")\n```\n\n### List Servers\n\n```python\n# Get all servers\nservers = client.list_servers()\n\nfor server in servers:\n print(f\"Name: {server['name']}\")\n print(f\"Path: {server['path']}\")\n print(f\"Status: {server['enabled']}\")\n print(f\"Tags: {', '.join(server.get('tags', []))}\")\n print(\"---\")\n```\n\n### Enable/Disable Server\n\n```python\n# Disable a server (removes from FAISS, keeps in registry)\nclient.disable_server(\"my-server\")\n\n# Enable a server (adds back to FAISS)\nclient.enable_server(\"my-server\")\n```\n\n## Group Management\n\n### Create Group\n\n```python\n# Create a new access control group\nclient.create_group(\n group_name=\"mcp-servers-finance/read\",\n description=\"Finance services with read access\"\n)\n```\n\n**What this does:**\n- Creates the group in Keycloak\n- Adds the group to scopes.yml\n- Reloads the auth server to apply changes immediately\n\n### List Groups\n\n```python\n# Get all groups\ngroups = client.list_groups()\n\nfor group in groups:\n print(f\"Group: {group['name']}\")\n print(f\"Synced: {group['synced']}\")\n```\n\n### Delete Group\n\n```python\n# Delete a group\nclient.delete_group(\"mcp-servers-finance/read\")\n```\n\n### Add Server to Group\n\n```python\n# Add server to one or more groups\nclient.add_server_to_groups(\n server_name=\"mcpgw\",\n groups=[\"mcp-servers-finance/read\"]\n)\n\n# Add to multiple groups\nclient.add_server_to_groups(\n server_name=\"fininfo\",\n groups=[\"mcp-servers-finance/read\", \"mcp-servers-finance/execute\"]\n)\n```\n\n### Remove Server from Group\n\n```python\n# Remove server from groups\nclient.remove_server_from_groups(\n server_name=\"fininfo\",\n groups=[\"mcp-servers-finance/read\"]\n)\n```\n\n## User Management\n\n### Create M2M User\n\n```python\n# Create machine-to-machine service account\ncredentials = client.create_m2m_user(\n name=\"finance-analyst-bot\",\n groups=[\"mcp-servers-finance/read\", \"mcp-servers-finance/execute\"],\n description=\"Finance analyst bot with full access\"\n)\n\nprint(f\"Client ID: {credentials['client_id']}\")\nprint(f\"Client Secret: {credentials['client_secret']}\")\n```\n\n**What this does:**\n- Creates a new Keycloak M2M client with service account\n- Assigns the service account to specified groups\n- Generates client credentials\n- Returns client_id and client_secret\n\n### Create Human User\n\n```python\n# Create human user account\nclient.create_human_user(\n username=\"jdoe\",\n email=\"jdoe@example.com\",\n firstname=\"John\",\n lastname=\"Doe\",\n password=\"secure_password\",\n groups=[\"mcp-servers-restricted/read\"]\n)\n```\n\n### List Users\n\n```python\n# Get all users\nusers = client.list_users()\n\nfor user in users:\n print(f\"Username: {user['username']}\")\n print(f\"Email: {user.get('email', 'N/A')}\")\n print(f\"Enabled: {user['enabled']}\")\n```\n\n### Delete User\n\n```python\n# Delete a user\nclient.delete_user(username=\"finance-analyst-bot\")\n```\n\n## Complete Workflow Example\n\nThis example demonstrates the complete workflow using the Registry Management API:\n\n```python\nfrom api.registry_client import RegistryClient\n\n# Initialize client\nclient = RegistryClient(\n base_url=\"http://localhost\"\n)\n\n# Step 1: Create a new access group\nprint(\"Creating group...\")\nclient.create_group(\n group_name=\"mcp-servers-time/read\",\n description=\"Time-related services with read access\"\n)\n\n# Step 2: Add servers to the group\nprint(\"Adding servers to group...\")\n\n# Add mcpgw (provides intelligent_tool_finder)\nclient.add_server_to_groups(\n server_name=\"mcpgw\",\n groups=[\"mcp-servers-time/read\"]\n)\n\n# Add currenttime server\nclient.add_server_to_groups(\n server_name=\"currenttime\",\n groups=[\"mcp-servers-time/read\"]\n)\n\n# Step 3: Create M2M service account\nprint(\"Creating M2M user...\")\ncredentials = client.create_m2m_user(\n name=\"time-service-bot\",\n groups=[\"mcp-servers-time/read\"],\n description=\"Bot for accessing time-related services\"\n)\n\nprint(f\"M2M Account Created:\")\nprint(f\" Client ID: {credentials['client_id']}\")\nprint(f\" Client Secret: {credentials['client_secret']}\")\n\n# Step 4: Create human user\nprint(\"Creating human user...\")\nclient.create_human_user(\n username=\"time-user\",\n email=\"time-user@example.com\",\n firstname=\"Time\",\n lastname=\"User\",\n password=\"secure_password\",\n groups=[\"mcp-servers-time/read\"]\n)\n\n# Step 5: Verify setup\nprint(\"\\nVerifying setup...\")\nprint(f\"Groups: {client.list_groups()}\")\nprint(f\"Servers: {[s['name'] for s in client.list_servers()]}\")\nprint(f\"Users: {[u['username'] for u in client.list_users()]}\")\n\nprint(\"\\nWorkflow complete!\")\n```\n\n## Configuration Format\n\n### Required Fields\n\n```python\n{\n \"server_name\": \"Display name for the server\",\n \"path\": \"/unique-url-path\",\n \"proxy_pass_url\": \"http://server-host:port\"\n}\n```\n\n### Complete Example\n\n```python\n{\n \"server_name\": \"Advanced MCP Server\",\n \"path\": \"/advanced-server\",\n \"proxy_pass_url\": \"http://advanced-server:8001/\",\n \"description\": \"A server with all optional fields\",\n \"tags\": [\"productivity\", \"automation\", \"enterprise\"],\n \"num_tools\": 5,\n \"num_stars\": 4,\n \"is_python\": True,\n \"license\": \"MIT\"\n}\n```\n\n### Field Constraints\n\n**Required Fields:**\n- `server_name`: Non-empty string\n- `path`: Must start with `/` and be more than just `/`\n- `proxy_pass_url`: Must start with `http://` or `https://`\n\n**Optional Fields:**\n- `description`: String description\n- `tags`: Array of strings\n- `num_tools`: Non-negative integer\n- `num_stars`: Non-negative integer\n- `is_python`: Boolean\n- `license`: String\n\n## Troubleshooting\n\n### Common Issues\n\n#### Authentication Errors\n```\nERROR: Authentication failed: 401 Unauthorized\n```\n**Solution**: Verify your OAuth2 credentials or JWT token are valid and not expired\n\n#### Server Already Exists\n```\nERROR: Server already exists: /my-server\n```\n**Solution**: Delete the existing server first or use a different path\n\n#### Group Not Found\n```\nERROR: Group not found: mcp-servers-custom/read\n```\n**Solution**: Create the group first using `create_group()`\n\n#### Connection Refused\n```\nERROR: Connection refused to http://localhost\n```\n**Solution**: Ensure MCP Gateway is running (`docker compose ps`)\n\n### Debug Tips\n\n```python\n# Enable debug logging\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\n# Test connectivity\nfrom api.registry_client import RegistryClient\nclient = RegistryClient(base_url=\"http://localhost\")\n\n# This will show detailed request/response logs\nservers = client.list_servers()\n```\n\n### API Documentation\n\nFor complete API reference, see:\n- Registry Management API: `api/registry_management.py`\n- Registry Client: `api/registry_client.py`\n- REST API endpoints: `http://localhost/api/management/docs` (OpenAPI/Swagger)\n\n## Best Practices\n\n1. **Use the Python Client**: The `RegistryClient` handles authentication and error handling automatically\n2. **Version Control Configurations**: Store server configurations in JSON files\n3. **Test After Adding**: Verify servers are accessible after registration\n4. **Use Descriptive Names**: Make server names and groups clear and searchable\n5. **Always Include mcpgw**: Add `mcpgw` to custom groups for `intelligent_tool_finder` functionality\n6. **Handle Errors**: Wrap API calls in try/except blocks for production use\n\n## Integration with CI/CD\n\n```python\n#!/usr/bin/env python3\nfrom api.registry_client import RegistryClient\nimport sys\n\ndef deploy_server(config_file):\n \"\"\"Deploy server from configuration file\"\"\"\n client = RegistryClient(\n base_url=\"http://localhost\"\n )\n\n try:\n # Load configuration\n with open(config_file) as f:\n config = json.load(f)\n\n # Add server\n response = client.add_server(**config)\n print(f\"Server deployed successfully: {response['name']}\")\n return 0\n except Exception as e:\n print(f\"Deployment failed: {e}\", file=sys.stderr)\n return 1\n\nif __name__ == \"__main__\":\n sys.exit(deploy_server(\"production-server.json\"))\n```\n\nFor advanced operations and direct API usage, see the [API documentation](../api/README.md).\n" }, { "path": "docs/static-token-auth.md", "content": "# Static Token Auth for Registry API\n\n> This page has been superseded by [**Registry API Authentication**](registry-api-auth.md), which covers the static token flow alongside session cookies, IdP JWTs, UI-issued self-signed JWTs, and the roadmap for per-key static tokens (#779) and external user access tokens (#826).\n>\n> See the [Static API token section](registry-api-auth.md#static-api-token-registry_api_token) for the content previously on this page.\n" }, { "path": "docs/supported-protocol-and-trust-fields.md", "content": "# Supported Protocol, Trust Level, and Visibility Fields\n\n## Overview\n\nThe Agent Registry now supports registering **any agent** -- not just [A2A (Agent-to-Agent)](https://a2a-protocol.org/latest/specification/) protocol agents. A new `supported_protocol` field distinguishes A2A agents from non-A2A agents, while `trust_level` and `visibility` defaults have been updated for consistency across all layers (backend, API, CLI, frontend).\n\n## Supported Protocol Field\n\nThe `supported_protocol` field indicates which protocol an agent implements:\n\n| Value | Description |\n|---------|-------------|\n| `a2a` | Agent implements the A2A protocol specification |\n| `other` | Agent uses a different protocol (HTTP REST, gRPC, custom, etc.) |\n\n- **Registration API**: `supportedProtocol` is **required** when registering a new agent\n- **Agent Card model**: `supported_protocol` defaults to `None` for backward compatibility with existing agents\n- **Agent listing**: the field appears in all agent list and detail responses\n\n### Registering via the UI\n\nThe registration form includes a **\"This is an A2A Protocol Agent\"** checkbox. When checked, the agent is registered with `supported_protocol: \"a2a\"`. When unchecked, it is registered as `\"other\"`.\n\nThe edit dialog also includes a **Supported Protocol** dropdown (A2A / Other) so you can update an existing agent's protocol type.\n\n### Registering via the API\n\nInclude the `supportedProtocol` field in your registration request:\n\n```bash\ncurl -X POST http://localhost/api/agents/register \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d '{\n \"name\": \"My Agent\",\n \"description\": \"An example agent\",\n \"url\": \"https://my-agent.example.com\",\n \"version\": \"1.0.0\",\n \"supportedProtocol\": \"a2a\",\n \"tags\": [\"example\"]\n }'\n```\n\n### Registering via the CLI\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n agent-register \\\n --name \"My Agent\" \\\n --url \"https://my-agent.example.com\" \\\n --supported-protocol a2a \\\n --tags \"example\"\n```\n\n## Updated Default Values\n\n### Trust Level\n\nThe default `trust_level` has changed from `\"unverified\"` to `\"community\"` across all layers:\n\n| Trust Level | Description |\n|-------------|-------------|\n| `unverified` | No verification performed |\n| `community` | Community-contributed agent (new default) |\n| `verified` | Verified by registry administrators |\n| `trusted` | Fully trusted agent |\n\n### Visibility\n\nThe default `visibility` has changed from `\"internal\"` to `\"public\"` across all layers:\n\n| Visibility | Description |\n|-------------------|-------------|\n| `public` | Visible to all users (new default) |\n| `group-restricted`| Visible only to members of allowed groups |\n| `internal` | Visible only to the agent owner |\n\n## Backfill Script for Existing Agents\n\nExisting agents in MongoDB that were created before this change will not have the `supported_protocol` field, and may still have the old default values for `trust_level` and `visibility`. A one-time backfill script normalizes these:\n\n```bash\nuv run python scripts/backfill_agent_fields.py\n```\n\nThe script performs three operations:\n\n1. **`supported_protocol`** -- Sets `\"other\"` on all agents that don't have the field. Agents already registered as A2A are not affected.\n2. **`trust_level`** -- Updates agents with `\"unverified\"` to `\"community\"` (the new default).\n3. **`visibility`** -- Updates agents with `\"internal\"` to `\"public\"` (the new default).\n\n### Configuration\n\nThe script connects to MongoDB at `localhost:27017` by default. For production deployments (e.g., Amazon DocumentDB), update the `MONGODB_URI` constant in `scripts/backfill_agent_fields.py` before running.\n\nThe script is **idempotent** -- running it multiple times has no additional effect. Each operation logs how many documents were modified.\n\n## Agent Card and Server Card Generation Skills\n\nTwo Claude Code skills are available to help generate registration cards by analyzing source code:\n\n### Generate Agent Card\n\nAnalyzes agent source code (local folder or GitHub URL) and generates an A2A-compliant agent card JSON file. Detects agent name, skills, tools, auth mechanisms, protocol bindings, and streaming support.\n\n```\n/generate-agent-card /path/to/agent/folder\n/generate-agent-card https://github.com/org/agent-repo\n```\n\nSee [.claude/skills/generate-agent-card/SKILL.md](../.claude/skills/generate-agent-card/SKILL.md) for details.\n\n### Generate Server Card\n\nAnalyzes MCP server source code and generates a registry-compatible server card JSON file. Detects server name, tools, transport type, auth scheme, and deployment URLs.\n\n```\n/generate-server-card /path/to/server/folder\n/generate-server-card https://github.com/org/server-repo\n```\n\nSee [.claude/skills/generate-server-card/SKILL.md](../.claude/skills/generate-server-card/SKILL.md) for details.\n\n## Frontend Changes\n\n- The Dashboard now shows an **\"A2A Protocol\"** badge on agent cards for agents with `supported_protocol: \"a2a\"`\n- Agent details modal shows a clickable A2A card URL for A2A agents\n- Trust level and visibility values are read from the API (no longer hardcoded)\n- The edit dialog includes dropdowns for Trust Level, Supported Protocol, and Visibility\n\n## API Response Format\n\nThe `supported_protocol`, `trust_level`, and `visibility` fields are included in all agent API responses:\n\n```json\n{\n \"name\": \"Flight Booking Agent\",\n \"path\": \"/flight-booking\",\n \"supported_protocol\": \"a2a\",\n \"trust_level\": \"community\",\n \"visibility\": \"public\",\n ...\n}\n```\n\nAgents that predate this feature will show `\"supported_protocol\": null` until the backfill script is run.\n" }, { "path": "docs/testing/MAINTENANCE.md", "content": "# Test Maintenance Guide\n\nGuide for maintaining a healthy test suite over time.\n\n## Table of Contents\n\n- [Coverage Monitoring](#coverage-monitoring)\n- [When Coverage Drops](#when-coverage-drops)\n- [Updating Tests](#updating-tests)\n- [Test Performance](#test-performance)\n- [CI/CD Integration](#cicd-integration)\n- [Troubleshooting Flaky Tests](#troubleshooting-flaky-tests)\n- [Test Isolation Issues](#test-isolation-issues)\n- [Deprecating Tests](#deprecating-tests)\n\n## Coverage Monitoring\n\n### Current Coverage Requirements\n\nThe project maintains **80% minimum code coverage** across all source code.\n\n### Checking Current Coverage\n\nCheck coverage locally:\n\n```bash\n# Quick check\nmake test-coverage\n\n# Detailed report\nuv run pytest --cov=registry --cov-report=term-missing\n\n# HTML report for detailed analysis\nuv run pytest --cov=registry --cov-report=html\nopen htmlcov/index.html\n```\n\n### Coverage Reports\n\nCoverage reports show:\n- Overall coverage percentage\n- Coverage per module\n- Missing lines (not covered by tests)\n- Branch coverage (conditional paths)\n\nExample output:\n\n```\nName Stmts Miss Cover Missing\n---------------------------------------------------------------\nregistry/services/server.py 45 3 93% 12, 45-47\nregistry/api/routes.py 120 15 88% 78-82, 156-162\nregistry/core/config.py 25 0 100%\n---------------------------------------------------------------\nTOTAL 450 35 92%\n```\n\n### Monitoring Coverage in CI/CD\n\nCoverage is automatically checked in CI/CD:\n\n1. **GitHub Actions**: Every PR and commit\n2. **Codecov**: Tracks coverage over time\n3. **PR Comments**: Shows coverage changes\n\n### Coverage Badges\n\nAdd coverage badge to README:\n\n```markdown\n[![codecov](https://codecov.io/gh/username/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/username/repo)\n```\n\n## When Coverage Drops\n\n### Identifying Uncovered Code\n\n1. **Run coverage report**:\n ```bash\n uv run pytest --cov=registry --cov-report=html\n open htmlcov/index.html\n ```\n\n2. **Check the HTML report**:\n - Red lines: Not covered\n - Yellow lines: Partially covered (some branches)\n - Green lines: Fully covered\n\n3. **Focus on critical paths first**:\n - API endpoints\n - Business logic\n - Error handling\n - Data validation\n\n### Adding Tests for Uncovered Code\n\nExample: Adding tests for uncovered function\n\n```python\n# Original uncovered function\ndef calculate_score(metrics: Dict[str, float]) -> float:\n \"\"\"Calculate composite score from metrics.\"\"\"\n if not metrics:\n return 0.0\n\n total = sum(metrics.values())\n count = len(metrics)\n return total / count\n\n\n# Add tests to cover this function\n@pytest.mark.unit\nclass TestScoreCalculation:\n \"\"\"Tests for calculate_score function.\"\"\"\n\n def test_calculate_score_with_valid_metrics(self):\n \"\"\"Test score calculation with valid metrics.\"\"\"\n metrics = {\"metric1\": 0.8, \"metric2\": 0.9, \"metric3\": 0.7}\n score = calculate_score(metrics)\n assert score == pytest.approx(0.8, rel=0.01)\n\n def test_calculate_score_with_empty_metrics(self):\n \"\"\"Test score calculation with no metrics.\"\"\"\n score = calculate_score({})\n assert score == 0.0\n\n def test_calculate_score_with_single_metric(self):\n \"\"\"Test score calculation with single metric.\"\"\"\n score = calculate_score({\"metric1\": 0.5})\n assert score == 0.5\n```\n\n### Strategies for Improving Coverage\n\n1. **Start with low-hanging fruit**: Test simple functions first\n2. **Focus on new code**: Ensure new features have tests\n3. **Test error paths**: Add tests for exception handling\n4. **Test edge cases**: Boundary conditions, empty inputs, etc.\n5. **Add integration tests**: Cover component interactions\n\n## Updating Tests\n\n### When Code Changes\n\nUpdate tests when code changes:\n\n1. **API changes**: Update API tests\n2. **Function signatures**: Update unit tests\n3. **New features**: Add new tests\n4. **Bug fixes**: Add regression tests\n5. **Refactoring**: Update mocks and fixtures\n\n### Test Update Checklist\n\nWhen updating code:\n\n- [ ] Update affected unit tests\n- [ ] Update integration tests if needed\n- [ ] Add tests for new functionality\n- [ ] Verify all tests still pass\n- [ ] Check coverage hasn't dropped\n- [ ] Update test documentation\n\n### Example: Updating Tests After Code Change\n\n**Code change**: Add pagination to list_servers endpoint\n\n```python\n# Old code\ndef list_servers():\n return server_service.list_servers()\n\n\n# New code\ndef list_servers(page: int = 1, page_size: int = 10):\n return server_service.list_servers_paginated(page, page_size)\n```\n\n**Update tests**:\n\n```python\n# Old test\ndef test_list_servers(server_service):\n servers = server_service.list_servers()\n assert isinstance(servers, list)\n\n\n# Updated test\ndef test_list_servers_default_pagination(server_service):\n \"\"\"Test list servers with default pagination.\"\"\"\n result = server_service.list_servers_paginated(page=1, page_size=10)\n assert isinstance(result[\"items\"], list)\n assert result[\"page\"] == 1\n assert result[\"page_size\"] == 10\n\n\ndef test_list_servers_custom_pagination(server_service):\n \"\"\"Test list servers with custom pagination.\"\"\"\n result = server_service.list_servers_paginated(page=2, page_size=5)\n assert result[\"page\"] == 2\n assert result[\"page_size\"] == 5\n\n\ndef test_list_servers_invalid_page_raises_error(server_service):\n \"\"\"Test invalid page number raises error.\"\"\"\n with pytest.raises(ValueError):\n server_service.list_servers_paginated(page=0, page_size=10)\n```\n\n## Test Performance\n\n### Identifying Slow Tests\n\nFind slow tests:\n\n```bash\n# Show test durations\nuv run pytest --durations=10\n\n# Show all durations\nuv run pytest --durations=0\n\n# Run only slow tests\nuv run pytest -m slow\n```\n\n### Optimizing Test Performance\n\n1. **Use appropriate fixtures**:\n ```python\n # Good - Function-scoped for isolation\n @pytest.fixture\n def temp_database():\n db = create_database()\n yield db\n db.cleanup()\n\n # Better - Module-scoped for performance\n @pytest.fixture(scope=\"module\")\n def shared_database():\n db = create_database()\n yield db\n db.cleanup()\n ```\n\n2. **Mock expensive operations**:\n ```python\n # Slow - Real API calls\n def test_fetch_data():\n data = external_api.fetch()\n assert data is not None\n\n # Fast - Mocked API\n @patch('module.external_api.fetch')\n def test_fetch_data(mock_fetch):\n mock_fetch.return_value = {\"data\": \"test\"}\n data = external_api.fetch()\n assert data == {\"data\": \"test\"}\n ```\n\n3. **Run tests in parallel**:\n ```bash\n # Install pytest-xdist\n uv add --dev pytest-xdist\n\n # Run tests in parallel\n uv run pytest -n auto\n ```\n\n4. **Skip slow tests during development**:\n ```python\n # Mark slow tests\n @pytest.mark.slow\n def test_expensive_operation():\n pass\n\n # Skip in development\n pytest -m \"not slow\"\n ```\n\n### Test Performance Goals\n\n- **Unit tests**: < 1 second each\n- **Integration tests**: < 5 seconds each\n- **E2E tests**: < 30 seconds each\n- **Total test suite**: < 5 minutes\n\n## CI/CD Integration\n\n### GitHub Actions Configuration\n\nExample test workflow:\n\n```yaml\nname: Tests\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n test:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Set up Python\n uses: actions/setup-python@v4\n with:\n python-version: '3.14'\n\n - name: Install uv\n run: pip install uv\n\n - name: Install dependencies\n run: uv sync\n\n - name: Run tests\n run: uv run pytest --cov=registry --cov-report=xml\n\n - name: Upload coverage\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n```\n\n### Handling CI/CD Test Failures\n\nWhen tests fail in CI/CD:\n\n1. **Check the logs**:\n - Look for error messages\n - Check which test failed\n - Review stack traces\n\n2. **Reproduce locally**:\n ```bash\n # Run the same test\n uv run pytest tests/path/to/test.py::test_name\n\n # Run with same markers\n uv run pytest -m integration\n ```\n\n3. **Common CI/CD issues**:\n - Missing environment variables\n - Service dependencies not running\n - File permissions\n - Timing-sensitive tests\n\n4. **Fix and verify**:\n - Make necessary changes\n - Run tests locally\n - Push fix\n - Verify CI/CD passes\n\n## Troubleshooting Flaky Tests\n\n### Identifying Flaky Tests\n\nFlaky tests pass/fail intermittently. Signs:\n- Tests fail randomly in CI/CD\n- Tests pass when run individually\n- Tests fail when run with others\n- Different results on different machines\n\n### Finding Flaky Tests\n\nRun tests multiple times:\n\n```bash\n# Run tests 10 times\nfor i in {1..10}; do\n uv run pytest tests/test_file.py || echo \"Failed on iteration $i\"\ndone\n\n# Use pytest-repeat\nuv add --dev pytest-repeat\nuv run pytest --count=10 tests/test_file.py\n```\n\n### Common Causes of Flaky Tests\n\n1. **Timing issues**:\n ```python\n # Flaky - Depends on timing\n def test_async_operation():\n start_background_task()\n time.sleep(0.1) # May not be enough\n assert task_complete()\n\n # Fixed - Wait for condition\n def test_async_operation():\n start_background_task()\n wait_for_condition(lambda: task_complete(), timeout=5)\n assert task_complete()\n ```\n\n2. **Shared state**:\n ```python\n # Flaky - Modifies global state\n def test_with_global_state():\n global_config.update({\"key\": \"value\"})\n assert process_data() == expected\n\n # Fixed - Isolated state\n def test_with_isolated_state(monkeypatch):\n test_config = {\"key\": \"value\"}\n monkeypatch.setattr('module.global_config', test_config)\n assert process_data() == expected\n ```\n\n3. **Order dependencies**:\n ```python\n # Flaky - Depends on test order\n def test_first():\n create_resource(\"test\")\n\n def test_second():\n resource = get_resource(\"test\") # Assumes test_first ran\n assert resource is not None\n\n # Fixed - Independent tests\n def test_first():\n create_resource(\"test1\")\n assert get_resource(\"test1\") is not None\n\n def test_second():\n create_resource(\"test2\")\n assert get_resource(\"test2\") is not None\n ```\n\n4. **Non-deterministic data**:\n ```python\n # Flaky - Random data\n def test_with_random_data():\n data = generate_random_data()\n assert process(data) > 0 # May fail with certain random values\n\n # Fixed - Deterministic data\n def test_with_fixed_data():\n data = [1, 2, 3, 4, 5]\n assert process(data) == 15\n ```\n\n## Test Isolation Issues\n\n### Ensuring Test Isolation\n\nTests should not affect each other:\n\n```python\n# Bad - Tests share state\nclass TestSharedState:\n shared_list = []\n\n def test_append(self):\n self.shared_list.append(1)\n assert len(self.shared_list) == 1 # Fails on second run\n\n def test_length(self):\n assert len(self.shared_list) == 0 # Fails if test_append ran first\n\n\n# Good - Tests are isolated\nclass TestIsolatedState:\n def test_append(self):\n test_list = []\n test_list.append(1)\n assert len(test_list) == 1\n\n def test_length(self):\n test_list = []\n assert len(test_list) == 0\n```\n\n### Using Fixtures for Isolation\n\n```python\n@pytest.fixture\ndef isolated_list():\n \"\"\"Provide a fresh list for each test.\"\"\"\n return []\n\n\ndef test_append(isolated_list):\n isolated_list.append(1)\n assert len(isolated_list) == 1\n\n\ndef test_length(isolated_list):\n assert len(isolated_list) == 0\n```\n\n### Cleanup After Tests\n\nAlways cleanup:\n\n```python\n@pytest.fixture\ndef temp_file():\n \"\"\"Create and cleanup temporary file.\"\"\"\n path = Path(\"temp.txt\")\n path.write_text(\"test\")\n\n yield path\n\n # Cleanup\n if path.exists():\n path.unlink()\n\n\n@pytest.fixture\ndef database():\n \"\"\"Create and cleanup test database.\"\"\"\n db = create_database()\n\n yield db\n\n # Cleanup\n db.drop_all_tables()\n db.close()\n```\n\n## Deprecating Tests\n\n### When to Deprecate Tests\n\nDeprecate tests when:\n- Feature is removed\n- API is changed significantly\n- Test is replaced by better test\n- Test is no longer relevant\n\n### How to Deprecate Tests\n\n1. **Mark as deprecated**:\n ```python\n @pytest.mark.skip(reason=\"Deprecated - Use test_new_feature instead\")\n def test_old_feature():\n pass\n ```\n\n2. **Add deprecation warning**:\n ```python\n import warnings\n\n def test_legacy_feature():\n warnings.warn(\n \"This test is deprecated and will be removed in v2.0\",\n DeprecationWarning\n )\n # Test code...\n ```\n\n3. **Document migration path**:\n ```python\n # DEPRECATED: This test is deprecated as of v1.5.0\n # Use test_new_implementation in test_new_feature.py instead\n # Will be removed in v2.0.0\n @pytest.mark.skip(reason=\"Deprecated - see test_new_implementation\")\n def test_old_implementation():\n pass\n ```\n\n## Best Practices\n\n1. **Monitor coverage regularly**: Check coverage on every PR\n2. **Keep tests fast**: Optimize slow tests\n3. **Fix flaky tests immediately**: Don't ignore them\n4. **Update tests with code**: Tests are part of the codebase\n5. **Document test patterns**: Help others write good tests\n6. **Review test code**: Tests deserve code review too\n7. **Refactor tests**: Keep test code clean\n8. **Delete obsolete tests**: Remove tests for removed features\n\n## Maintenance Checklist\n\n### Weekly\n\n- [ ] Review test failures in CI/CD\n- [ ] Check for slow tests\n- [ ] Monitor coverage trends\n\n### Monthly\n\n- [ ] Review and fix flaky tests\n- [ ] Update test dependencies\n- [ ] Refactor duplicate test code\n- [ ] Update test documentation\n\n### Quarterly\n\n- [ ] Audit test coverage\n- [ ] Remove obsolete tests\n- [ ] Review test performance\n- [ ] Update testing guidelines\n\n## Summary\n\nKey maintenance tasks:\n\n1. Monitor and maintain 80% coverage\n2. Keep tests fast and reliable\n3. Fix flaky tests immediately\n4. Ensure test isolation\n5. Update tests with code changes\n6. Optimize test performance\n7. Clean up obsolete tests\n\nFor more information, see:\n- [Testing Guide](./README.md)\n- [Writing Tests Guide](./WRITING_TESTS.md)\n" }, { "path": "docs/testing/QUICK-START.md", "content": "# Test Suite Quick Start Guide\n\n## TL;DR - Just Run Tests Safely\n\n```bash\n# Run all tests (memory-safe, serial execution)\nuv run pytest\n\n# Or use the test runner script\npython scripts/test.py full\n```\n\n## Problem Solved\n\nPreviously, running tests would crash EC2 instances due to:\n- Heavy ML model loading (sentence-transformers, FAISS)\n- Parallel execution spawning multiple model copies\n- Memory multiplication across workers\n\n**Now fixed!** All tests use mocked models by default.\n\n## Quick Commands\n\n### Safe for All EC2 Instances\n\n```bash\n# Run unit tests (fast)\npython scripts/test.py unit\n\n# Run specific domains\npython scripts/test.py auth\npython scripts/test.py servers\n\n# Run fast tests (2 workers, still safe)\npython scripts/test.py fast\n\n# Full test suite (serial, safest)\npython scripts/test.py full\n```\n\n### If You Have More Memory (16GB+ RAM)\n\n```bash\n# Run with 2 workers\npython scripts/test.py full -n 2\n\n# Run with 4 workers (requires 16GB+ RAM)\npython scripts/test.py unit -n 4\n```\n\n## What Changed\n\n### 1. Mocked Dependencies (Automatic)\n\nAll tests now automatically use mocked versions of:\n- FAISS vector database\n- Sentence-transformers embedding models\n- PyTorch model loading\n\nNo changes needed to existing tests - it just works!\n\n### 2. Serial Execution by Default\n\nTests run one at a time by default to prevent memory issues:\n\n```bash\n# Before (would crash)\npytest -n auto # ❌ Crashes EC2\n\n# Now (safe)\npytest # ✅ Runs serially, no crash\n```\n\n### 3. Optional Parallelization\n\nUse the `-n` flag to control workers:\n\n```bash\n# 2 workers (safe for most EC2)\npython scripts/test.py unit -n 2\n\n# 4 workers (needs 16GB+ RAM)\npython scripts/test.py unit -n 4\n```\n\n## Memory Guidelines\n\n| EC2 Instance | Safe Workers | Notes |\n|--------------|--------------|-------|\n| t3.small (2GB) | 1 (serial) | ✅ Now works! |\n| t3.medium (4GB) | 1-2 | ✅ Now works! |\n| t3.large (8GB) | 2 | ✅ Recommended |\n| t3.xlarge (16GB+) | 2-4 | ✅ Can use more workers |\n\n## Monitoring Memory\n\nWhile tests run:\n\n```bash\n# Check current memory usage\nfree -h\n\n# Watch memory in real-time\nwatch -n 1 free -h\n```\n\n## Writing New Tests\n\nTests automatically use mocked models - no special setup needed:\n\n```python\nimport pytest\n\n@pytest.mark.unit\ndef test_my_feature(server_service):\n # FAISS and embeddings are automatically mocked\n result = server_service.do_something()\n assert result is not None\n```\n\n## When Tests Fail\n\n```bash\n# Run specific failing test\npytest tests/unit/auth/test_auth_routes.py::test_login -v\n\n# Show debug output\npytest tests/unit/auth/ --log-cli-level=DEBUG\n\n# Stop on first failure\npytest -x\n```\n\n## Getting Coverage\n\n```bash\n# Generate coverage report\npython scripts/test.py coverage\n\n# View in browser\nopen htmlcov/index.html\n```\n\n## More Information\n\n- **[Memory Management Details](./memory-management.md)** - In-depth explanation\n- **[Test Categories](./test-categories.md)** - How tests are organized\n- **[Main Testing README](./README.md)** - Complete reference\n\n## Still Having Issues?\n\nIf tests still crash:\n\n1. **Check you're on the latest version:**\n ```bash\n git pull\n uv sync --extra dev\n ```\n\n2. **Verify mocking is enabled:**\n ```bash\n pytest tests/unit/core/test_config.py -v\n ```\n Should pass quickly (< 1 second) without loading models\n\n3. **Run completely serially:**\n ```bash\n pytest -x # Stop on first failure\n ```\n\n4. **Check memory before running:**\n ```bash\n free -h # Should have several GB free\n ```\n\n## Summary\n\n✅ Tests now run safely on any EC2 instance\n✅ No more OOM crashes\n✅ Automatic model mocking\n✅ Serial execution by default\n✅ Optional parallelization with `-n` flag\n✅ Existing tests work without changes\n" }, { "path": "docs/testing/README.md", "content": "# Testing Guide\n\nComprehensive testing documentation for the MCP Gateway Registry project.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Test Structure](#test-structure)\n- [Running Tests](#running-tests)\n- [Test Categories](#test-categories)\n- [Coverage Requirements](#coverage-requirements)\n- [CI/CD Integration](#cicd-integration)\n- [Troubleshooting](#troubleshooting)\n\n## Quick Start\n\nRun all tests:\n\n```bash\nmake test\n```\n\nRun specific test categories:\n\n```bash\n# Unit tests only (fast)\nmake test-unit\n\n# Integration tests\nmake test-integration\n\n# E2E tests (slow)\nmake test-e2e\n\n# With coverage report\nmake test-coverage\n```\n\nRun tests using pytest directly:\n\n```bash\n# All tests\nuv run pytest\n\n# Specific test file\nuv run pytest tests/unit/test_server_service.py\n\n# Specific test class\nuv run pytest tests/unit/test_server_service.py::TestServerService\n\n# Specific test function\nuv run pytest tests/unit/test_server_service.py::TestServerService::test_register_server\n\n# With verbose output\nuv run pytest -v\n\n# With coverage\nuv run pytest --cov=registry --cov-report=html\n```\n\n## Test Structure\n\nThe test suite is organized into three main categories:\n\n```\ntests/\n├── unit/ # Unit tests (fast, isolated)\n│ ├── services/ # Service layer tests\n│ ├── api/ # API endpoint tests\n│ ├── core/ # Core functionality tests\n│ └── agents/ # Agent-specific tests\n├── integration/ # Integration tests (slower)\n│ ├── test_server_integration.py\n│ ├── test_api_integration.py\n│ └── test_e2e_workflows.py\n├── fixtures/ # Shared test fixtures\n│ └── factories.py # Factory functions for test data\n├── conftest.py # Shared pytest configuration\n└── reports/ # Test reports and coverage data\n```\n\n### Test File Organization\n\n- **Unit tests**: Test individual components in isolation\n - Mock external dependencies\n - Fast execution (< 1 second per test)\n - High coverage of edge cases\n\n- **Integration tests**: Test component interactions\n - May use real services (databases, files)\n - Moderate execution time (< 5 seconds per test)\n - Test realistic workflows\n\n- **E2E tests**: Test complete user workflows\n - Test entire system end-to-end\n - Slower execution (5-30 seconds per test)\n - Marked with `@pytest.mark.slow`\n\n## Running Tests\n\n### Using Make Commands\n\nThe project includes convenient Make targets for running tests:\n\n```bash\n# Run all tests\nmake test\n\n# Run only unit tests (fast)\nmake test-unit\n\n# Run only integration tests\nmake test-integration\n\n# Run E2E tests\nmake test-e2e\n\n# Run with coverage report\nmake test-coverage\n\n# Run and open HTML coverage report\nmake test-coverage-html\n```\n\n### Using Pytest Directly\n\nFor more control, use pytest commands:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run tests with specific markers\nuv run pytest -m unit # Only unit tests\nuv run pytest -m integration # Only integration tests\nuv run pytest -m \"not slow\" # Skip slow tests\n\n# Run tests in parallel (faster)\nuv run pytest -n auto # Auto-detect CPU count\n\n# Run with verbose output\nuv run pytest -v\n\n# Show print statements\nuv run pytest -s\n\n# Run specific tests by keyword\nuv run pytest -k \"server\" # All tests with \"server\" in name\n\n# Stop on first failure\nuv run pytest -x\n\n# Run last failed tests\nuv run pytest --lf\n\n# Run failed tests first\nuv run pytest --ff\n```\n\n### Integration Test Requirements\n\nIntegration and E2E tests may require:\n\n1. **Authentication tokens**: Generate tokens before running:\n ```bash\n ./keycloak/setup/generate-agent-token.sh admin-bot\n ./keycloak/setup/generate-agent-token.sh lob1-bot\n ./keycloak/setup/generate-agent-token.sh lob2-bot\n ```\n\n2. **Running services**: Ensure Docker containers are running:\n ```bash\n docker-compose up -d\n ```\n\n3. **Environment variables**:\n ```bash\n export BASE_URL=\"http://localhost\"\n export TOKEN_FILE=\".oauth-tokens/admin-bot-token.json\"\n ```\n\n## Test Categories\n\nTests are organized using pytest markers:\n\n### Available Markers\n\n- `@pytest.mark.unit` - Unit tests (fast, isolated)\n- `@pytest.mark.integration` - Integration tests\n- `@pytest.mark.e2e` - End-to-end tests\n- `@pytest.mark.slow` - Slow tests (> 5 seconds)\n- `@pytest.mark.auth` - Authentication/authorization tests\n- `@pytest.mark.servers` - Server management tests\n- `@pytest.mark.agents` - Agent-specific tests\n- `@pytest.mark.search` - Search functionality tests\n- `@pytest.mark.health` - Health monitoring tests\n\n### Running Tests by Marker\n\n```bash\n# Run only unit tests\nuv run pytest -m unit\n\n# Run integration tests\nuv run pytest -m integration\n\n# Run E2E tests\nuv run pytest -m e2e\n\n# Skip slow tests\nuv run pytest -m \"not slow\"\n\n# Run auth and agent tests\nuv run pytest -m \"auth or agents\"\n\n# Run integration but not slow tests\nuv run pytest -m \"integration and not slow\"\n```\n\n## Coverage Requirements\n\nThe project maintains **80% minimum code coverage**.\n\n### Checking Coverage\n\n```bash\n# Run tests with coverage report\nuv run pytest --cov=registry --cov-report=term-missing\n\n# Generate HTML coverage report\nuv run pytest --cov=registry --cov-report=html\n\n# Open HTML report\nopen htmlcov/index.html # macOS\nxdg-open htmlcov/index.html # Linux\n```\n\n### Coverage Configuration\n\nCoverage settings are configured in `pyproject.toml`:\n\n```toml\n[tool.pytest.ini_options]\naddopts = [\n \"--cov=registry\",\n \"--cov-report=term-missing\",\n \"--cov-report=html\",\n \"--cov-fail-under=80\",\n]\n```\n\n### What Gets Covered\n\nCoverage includes:\n- All source code in `registry/` directory\n- Excludes: tests, migrations, __init__.py files\n- Reports missing lines for easy identification\n\n## CI/CD Integration\n\nTests run automatically in CI/CD pipelines on:\n- Every pull request\n- Every push to main branch\n- Nightly scheduled runs\n\n### GitHub Actions\n\nThe project uses GitHub Actions for CI/CD. Test workflows are defined in:\n\n```\n.github/workflows/\n├── test.yml # Main test workflow\n├── coverage.yml # Coverage reporting\n└── integration.yml # Integration test workflow\n```\n\n### Pre-commit Hooks\n\nInstall pre-commit hooks to run tests before commits:\n\n```bash\n# Install pre-commit\npip install pre-commit\n\n# Install hooks\npre-commit install\n\n# Run hooks manually\npre-commit run --all-files\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1. Token File Not Found\n\n**Error**: `Token file not found: .oauth-tokens/admin-bot-token.json`\n\n**Solution**: Generate authentication tokens:\n```bash\n./keycloak/setup/generate-agent-token.sh admin-bot\n```\n\n#### 2. Docker Containers Not Running\n\n**Error**: `Cannot connect to gateway at http://localhost`\n\n**Solution**: Start Docker containers:\n```bash\ndocker-compose up -d\n```\n\n#### 3. Import Errors\n\n**Error**: `ModuleNotFoundError: No module named 'registry'`\n\n**Solution**: Ensure you're using `uv run`:\n```bash\nuv run pytest # Correct\npytest # May fail if environment not activated\n```\n\n#### 4. Fixture Not Found\n\n**Error**: `fixture 'some_fixture' not found`\n\n**Solution**: Check fixture is defined in:\n- `tests/conftest.py` (shared fixtures)\n- Test file's conftest.py\n- Imported from fixtures module\n\n#### 5. Slow Tests\n\n**Issue**: Tests taking too long\n\n**Solution**: Skip slow tests during development:\n```bash\nuv run pytest -m \"not slow\"\n```\n\n#### 6. Failed Async Tests\n\n**Error**: `RuntimeError: Event loop is closed`\n\n**Solution**: Check async fixtures are properly defined:\n```python\n@pytest.fixture\nasync def async_client():\n async with AsyncClient() as client:\n yield client\n```\n\n#### 7. Coverage Too Low\n\n**Error**: `FAIL Required test coverage of 80% not reached`\n\n**Solution**: Add tests for uncovered code:\n```bash\n# Check which lines are missing\nuv run pytest --cov=registry --cov-report=term-missing\n\n# Generate detailed HTML report\nuv run pytest --cov=registry --cov-report=html\nopen htmlcov/index.html\n```\n\n### Debug Mode\n\nRun tests in debug mode for detailed output:\n\n```bash\n# Show print statements\nuv run pytest -s\n\n# Verbose output\nuv run pytest -v\n\n# Very verbose (shows fixtures)\nuv run pytest -vv\n\n# Show local variables on failure\nuv run pytest -l\n\n# Enter debugger on failure\nuv run pytest --pdb\n```\n\n### Logging During Tests\n\nEnable logging output:\n\n```bash\n# Show all logs\nuv run pytest --log-cli-level=DEBUG\n\n# Show only INFO and above\nuv run pytest --log-cli-level=INFO\n\n# Log to file\nuv run pytest --log-file=tests/reports/test.log\n```\n\n## Additional Resources\n\n- [Writing Tests Guide](./WRITING_TESTS.md) - How to write effective tests\n- [Test Maintenance Guide](./MAINTENANCE.md) - Maintaining test suite health\n- [Pytest Documentation](https://docs.pytest.org/) - Official pytest docs\n- [Coverage.py Documentation](https://coverage.readthedocs.io/) - Coverage tool docs\n\n## Getting Help\n\nIf you encounter issues:\n\n1. Check this troubleshooting guide\n2. Review test output for error messages\n3. Check relevant documentation\n4. Ask in team chat or create an issue\n\n## Summary\n\nKey commands to remember:\n\n```bash\n# Development workflow\nmake test-unit # Quick unit tests\nmake test-coverage # Full test with coverage\nuv run pytest -m \"not slow\" # Skip slow tests\n\n# Before committing\nmake test # Run all tests\npre-commit run --all-files # Run all checks\n\n# Debugging\nuv run pytest -v -s # Verbose with prints\nuv run pytest --pdb # Debug on failure\n```\n" }, { "path": "docs/testing/WRITING_TESTS.md", "content": "# Writing Tests Guide\n\nA comprehensive guide to writing effective tests for the MCP Gateway Registry project.\n\n## Table of Contents\n\n- [Test Writing Principles](#test-writing-principles)\n- [Test Structure](#test-structure)\n- [Test Patterns](#test-patterns)\n- [Using Fixtures](#using-fixtures)\n- [Mocking Strategies](#mocking-strategies)\n- [Async Testing](#async-testing)\n- [Factory Pattern](#factory-pattern)\n- [Best Practices](#best-practices)\n- [Examples](#examples)\n\n## Test Writing Principles\n\n### 1. Follow AAA Pattern\n\nOrganize tests using Arrange-Act-Assert:\n\n```python\ndef test_register_server(server_service, sample_server):\n # Arrange - Set up test data and preconditions\n server_id = \"test-server\"\n server_info = sample_server\n\n # Act - Perform the action being tested\n result = server_service.register_server(server_id, server_info)\n\n # Assert - Verify the outcome\n assert result is not None\n assert result[\"id\"] == server_id\n```\n\n### 2. One Assertion Per Test (When Possible)\n\nEach test should verify one specific behavior:\n\n```python\n# Good - Tests one thing\ndef test_server_registration_succeeds(server_service, sample_server):\n result = server_service.register_server(\"test\", sample_server)\n assert result is not None\n\ndef test_server_registration_stores_data(server_service, sample_server):\n result = server_service.register_server(\"test\", sample_server)\n assert result[\"name\"] == sample_server[\"name\"]\n\n# Avoid - Tests too many things\ndef test_server_registration(server_service, sample_server):\n result = server_service.register_server(\"test\", sample_server)\n assert result is not None\n assert result[\"name\"] == sample_server[\"name\"]\n assert len(server_service.list_servers()) == 1\n assert server_service.get_server(\"test\") == result\n```\n\n### 3. Descriptive Test Names\n\nUse clear, descriptive names that explain what is being tested:\n\n```python\n# Good - Clear and descriptive\ndef test_register_server_with_valid_data_succeeds():\n pass\n\ndef test_register_server_with_duplicate_id_raises_error():\n pass\n\ndef test_list_servers_returns_empty_list_when_no_servers():\n pass\n\n# Avoid - Vague names\ndef test_server():\n pass\n\ndef test_register():\n pass\n\ndef test_list():\n pass\n```\n\n## Test Structure\n\n### File Organization\n\nOrganize tests to mirror the source code structure:\n\n```\nregistry/\n├── services/\n│ ├── server_service.py\n│ └── agent_service.py\n└── api/\n └── routes.py\n\ntests/\n├── unit/\n│ ├── services/\n│ │ ├── test_server_service.py\n│ │ └── test_agent_service.py\n│ └── api/\n│ └── test_routes.py\n```\n\n### Test Class Structure\n\nGroup related tests in classes:\n\n```python\nimport pytest\n\n\n@pytest.mark.unit\nclass TestServerService:\n \"\"\"Tests for ServerService class.\"\"\"\n\n def test_register_server_succeeds(self, server_service):\n \"\"\"Test successful server registration.\"\"\"\n pass\n\n def test_register_server_duplicate_fails(self, server_service):\n \"\"\"Test that duplicate server IDs are rejected.\"\"\"\n pass\n\n def test_list_servers_returns_all(self, server_service):\n \"\"\"Test listing all registered servers.\"\"\"\n pass\n\n\n@pytest.mark.unit\nclass TestServerServiceValidation:\n \"\"\"Tests for ServerService validation logic.\"\"\"\n\n def test_validate_server_info_with_valid_data(self):\n \"\"\"Test validation passes with valid server info.\"\"\"\n pass\n\n def test_validate_server_info_rejects_missing_name(self):\n \"\"\"Test validation fails when name is missing.\"\"\"\n pass\n```\n\n## Test Patterns\n\n### Unit Test Pattern\n\nTest individual functions/methods in isolation:\n\n```python\n@pytest.mark.unit\ndef test_calculate_health_score():\n \"\"\"Test health score calculation.\"\"\"\n # Arrange\n server_status = {\n \"available\": True,\n \"response_time\": 100,\n \"error_rate\": 0.01\n }\n\n # Act\n score = calculate_health_score(server_status)\n\n # Assert\n assert 0.0 <= score <= 1.0\n assert score > 0.9 # Healthy server\n```\n\n### Integration Test Pattern\n\nTest component interactions:\n\n```python\n@pytest.mark.integration\nasync def test_server_registration_workflow(\n server_service,\n health_service,\n sample_server,\n):\n \"\"\"Test complete server registration workflow.\"\"\"\n # Register server\n server_id = \"integration-test\"\n result = server_service.register_server(server_id, sample_server)\n\n # Verify health monitoring started\n await asyncio.sleep(0.1)\n health_status = health_service.get_health_status(server_id)\n\n assert result is not None\n assert health_status is not None\n```\n\n### E2E Test Pattern\n\nTest complete user workflows:\n\n```python\n@pytest.mark.e2e\n@pytest.mark.slow\nasync def test_complete_agent_lifecycle(\n base_url,\n auth_headers,\n test_agent_data,\n):\n \"\"\"Test complete agent lifecycle: create, update, delete.\"\"\"\n async with httpx.AsyncClient() as client:\n # Create agent\n response = await client.post(\n f\"{base_url}/api/agents/register\",\n headers=auth_headers,\n json=test_agent_data,\n )\n assert response.status_code == 200\n agent_path = response.json()[\"path\"]\n\n # Update agent\n response = await client.put(\n f\"{base_url}/api/agents/{agent_path}\",\n headers=auth_headers,\n json={\"description\": \"Updated\"},\n )\n assert response.status_code == 200\n\n # Delete agent\n response = await client.delete(\n f\"{base_url}/api/agents/{agent_path}\",\n headers=auth_headers,\n )\n assert response.status_code in [200, 204]\n```\n\n## Using Fixtures\n\n### Built-in Fixtures\n\nLeverage pytest's built-in fixtures:\n\n```python\ndef test_with_temp_directory(tmp_path):\n \"\"\"Use tmp_path for temporary directories.\"\"\"\n test_file = tmp_path / \"test.json\"\n test_file.write_text('{\"key\": \"value\"}')\n assert test_file.exists()\n\n\ndef test_with_monkeypatch(monkeypatch):\n \"\"\"Use monkeypatch to modify environment.\"\"\"\n monkeypatch.setenv(\"TEST_VAR\", \"test_value\")\n assert os.getenv(\"TEST_VAR\") == \"test_value\"\n```\n\n### Custom Fixtures\n\nCreate reusable test fixtures in `conftest.py`:\n\n```python\n# tests/conftest.py\nimport pytest\n\n\n@pytest.fixture\ndef sample_server():\n \"\"\"Create a sample server for testing.\"\"\"\n return {\n \"name\": \"Test Server\",\n \"url\": \"http://test.example.com\",\n \"description\": \"Test server for unit tests\"\n }\n\n\n@pytest.fixture\ndef authenticated_client(test_client, auth_token):\n \"\"\"Create an authenticated test client.\"\"\"\n test_client.headers[\"Authorization\"] = f\"Bearer {auth_token}\"\n return test_client\n```\n\n### Fixture Scopes\n\nUse appropriate fixture scopes:\n\n```python\n@pytest.fixture(scope=\"function\") # Default - new instance per test\ndef temp_database():\n \"\"\"Create a fresh database for each test.\"\"\"\n db = create_test_database()\n yield db\n db.cleanup()\n\n\n@pytest.fixture(scope=\"class\") # Shared across test class\ndef shared_resource():\n \"\"\"Create resource shared by all tests in class.\"\"\"\n resource = expensive_setup()\n yield resource\n resource.cleanup()\n\n\n@pytest.fixture(scope=\"module\") # Shared across module\ndef module_database():\n \"\"\"Create database shared by all tests in module.\"\"\"\n db = create_test_database()\n yield db\n db.cleanup()\n```\n\n## Mocking Strategies\n\n### Using unittest.mock\n\nMock external dependencies:\n\n```python\nfrom unittest.mock import Mock, AsyncMock, patch\n\n\ndef test_with_mock_dependency():\n \"\"\"Test with mocked dependency.\"\"\"\n # Create mock\n mock_service = Mock()\n mock_service.get_data.return_value = {\"key\": \"value\"}\n\n # Use mock\n result = function_under_test(mock_service)\n\n # Verify mock was called\n mock_service.get_data.assert_called_once()\n assert result is not None\n\n\nasync def test_with_async_mock():\n \"\"\"Test with async mock.\"\"\"\n mock_service = AsyncMock()\n mock_service.fetch_data.return_value = {\"data\": \"test\"}\n\n result = await async_function_under_test(mock_service)\n\n mock_service.fetch_data.assert_called_once()\n assert result == {\"data\": \"test\"}\n```\n\n### Patching Functions\n\nUse `@patch` decorator or context manager:\n\n```python\n@patch('registry.services.external_api_call')\ndef test_with_patched_function(mock_api):\n \"\"\"Test with patched external function.\"\"\"\n mock_api.return_value = {\"status\": \"success\"}\n\n result = function_that_calls_api()\n\n mock_api.assert_called_once()\n assert result[\"status\"] == \"success\"\n\n\ndef test_with_patch_context_manager():\n \"\"\"Test using patch as context manager.\"\"\"\n with patch('registry.services.external_api_call') as mock_api:\n mock_api.return_value = {\"status\": \"success\"}\n result = function_that_calls_api()\n assert result[\"status\"] == \"success\"\n```\n\n### Mock Configuration\n\nConfigure mocks for specific behaviors:\n\n```python\ndef test_mock_configuration():\n \"\"\"Test with configured mock.\"\"\"\n mock_service = Mock()\n\n # Configure return values\n mock_service.get.return_value = \"value\"\n mock_service.list.return_value = [\"item1\", \"item2\"]\n\n # Configure side effects\n mock_service.process.side_effect = [1, 2, 3]\n\n # Configure exceptions\n mock_service.fail.side_effect = ValueError(\"Test error\")\n\n # Use configured mock\n assert mock_service.get() == \"value\"\n assert mock_service.process() == 1\n assert mock_service.process() == 2\n\n with pytest.raises(ValueError):\n mock_service.fail()\n```\n\n## Async Testing\n\n### Async Test Functions\n\nUse `async def` for async tests:\n\n```python\n@pytest.mark.asyncio\nasync def test_async_function():\n \"\"\"Test async function.\"\"\"\n result = await async_function()\n assert result is not None\n\n\n@pytest.mark.asyncio\nasync def test_async_client(async_client):\n \"\"\"Test with async HTTP client.\"\"\"\n response = await async_client.get(\"/api/endpoint\")\n assert response.status_code == 200\n```\n\n### Async Fixtures\n\nCreate async fixtures:\n\n```python\n@pytest.fixture\nasync def async_database():\n \"\"\"Create async database connection.\"\"\"\n db = await create_async_database()\n yield db\n await db.close()\n\n\n@pytest.mark.asyncio\nasync def test_with_async_fixture(async_database):\n \"\"\"Test using async fixture.\"\"\"\n result = await async_database.query(\"SELECT * FROM table\")\n assert result is not None\n```\n\n### Testing Async Context Managers\n\nTest async context managers:\n\n```python\n@pytest.mark.asyncio\nasync def test_async_context_manager():\n \"\"\"Test async context manager.\"\"\"\n async with AsyncResource() as resource:\n result = await resource.do_something()\n assert result is not None\n```\n\n## Factory Pattern\n\n### Creating Test Data Factories\n\nUse factories to generate test data:\n\n```python\n# tests/fixtures/factories.py\ndef ServerInfoFactory(\n name: str = \"Test Server\",\n url: str = \"http://test.example.com\",\n **kwargs\n) -> Dict[str, Any]:\n \"\"\"Factory for creating server info dictionaries.\"\"\"\n return {\n \"name\": name,\n \"url\": url,\n \"description\": kwargs.get(\"description\", \"Test server\"),\n \"tags\": kwargs.get(\"tags\", [\"test\"]),\n \"version\": kwargs.get(\"version\", \"1.0.0\"),\n }\n\n\ndef create_multiple_servers(count: int = 3) -> Dict[str, Dict[str, Any]]:\n \"\"\"Create multiple test servers.\"\"\"\n return {\n f\"server-{i}\": ServerInfoFactory(\n name=f\"Test Server {i}\",\n url=f\"http://server{i}.example.com\"\n )\n for i in range(count)\n }\n\n\ndef create_server_with_tools(num_tools: int = 5) -> Dict[str, Any]:\n \"\"\"Create a server with tools.\"\"\"\n server = ServerInfoFactory()\n server[\"tools\"] = [\n {\n \"name\": f\"tool_{i}\",\n \"description\": f\"Test tool {i}\",\n \"parameters\": {}\n }\n for i in range(num_tools)\n ]\n return server\n```\n\n### Using Factories in Tests\n\n```python\ndef test_with_factory(server_service):\n \"\"\"Test using factory-created data.\"\"\"\n # Create single server\n server = ServerInfoFactory(name=\"Custom Server\")\n result = server_service.register_server(\"test\", server)\n assert result[\"name\"] == \"Custom Server\"\n\n\ndef test_with_multiple_factories(server_service):\n \"\"\"Test with multiple factory-created servers.\"\"\"\n servers = create_multiple_servers(count=5)\n\n for server_id, server_info in servers.items():\n server_service.register_server(server_id, server_info)\n\n assert len(server_service.list_servers()) == 5\n```\n\n## Best Practices\n\n### 1. Test Independence\n\nTests should be independent and not rely on execution order:\n\n```python\n# Good - Independent tests\ndef test_register_server(server_service, sample_server):\n \"\"\"Test registers its own server.\"\"\"\n result = server_service.register_server(\"test1\", sample_server)\n assert result is not None\n\n\ndef test_list_servers(server_service, sample_server):\n \"\"\"Test creates its own data.\"\"\"\n server_service.register_server(\"test2\", sample_server)\n servers = server_service.list_servers()\n assert len(servers) >= 1\n\n\n# Avoid - Tests depend on each other\ndef test_register_server_first(server_service, sample_server):\n \"\"\"Test creates server for other tests.\"\"\"\n server_service.register_server(\"shared\", sample_server)\n\n\ndef test_list_servers_second(server_service):\n \"\"\"Test assumes server from previous test exists.\"\"\"\n servers = server_service.list_servers()\n assert \"shared\" in servers # Fragile!\n```\n\n### 2. Test Edge Cases\n\nTest boundary conditions and edge cases:\n\n```python\ndef test_edge_cases():\n \"\"\"Test edge cases and boundary conditions.\"\"\"\n # Empty input\n assert process_data([]) == []\n\n # Single item\n assert process_data([1]) == [1]\n\n # Large input\n assert len(process_data(range(10000))) == 10000\n\n # Null/None input\n with pytest.raises(ValueError):\n process_data(None)\n\n # Invalid type\n with pytest.raises(TypeError):\n process_data(\"not a list\")\n```\n\n### 3. Test Error Handling\n\nVerify error handling behavior:\n\n```python\ndef test_error_handling():\n \"\"\"Test error handling.\"\"\"\n # Test specific exception\n with pytest.raises(ValueError):\n function_that_raises_value_error()\n\n # Test exception message\n with pytest.raises(ValueError, match=\"Invalid input\"):\n function_with_specific_error()\n\n # Test exception attributes\n with pytest.raises(CustomError) as exc_info:\n function_with_custom_error()\n\n assert exc_info.value.code == 400\n assert \"error\" in str(exc_info.value)\n```\n\n### 4. Use Parametrize for Similar Tests\n\nUse `@pytest.mark.parametrize` to test multiple inputs:\n\n```python\n@pytest.mark.parametrize(\"input,expected\", [\n (1, 2),\n (2, 4),\n (3, 6),\n (0, 0),\n (-1, -2),\n])\ndef test_double(input, expected):\n \"\"\"Test double function with multiple inputs.\"\"\"\n assert double(input) == expected\n\n\n@pytest.mark.parametrize(\"server_id,should_fail\", [\n (\"valid-id\", False),\n (\"valid_id\", False),\n (\"invalid id\", True), # Spaces not allowed\n (\"\", True), # Empty string\n (\"a\" * 256, True), # Too long\n])\ndef test_server_id_validation(server_id, should_fail):\n \"\"\"Test server ID validation with various inputs.\"\"\"\n if should_fail:\n with pytest.raises(ValueError):\n validate_server_id(server_id)\n else:\n validate_server_id(server_id) # Should not raise\n```\n\n### 5. Clean Up Resources\n\nAlways clean up resources after tests:\n\n```python\n@pytest.fixture\ndef temp_file():\n \"\"\"Create temporary file and clean up after.\"\"\"\n file_path = Path(\"temp_test_file.txt\")\n file_path.write_text(\"test data\")\n\n yield file_path\n\n # Cleanup\n if file_path.exists():\n file_path.unlink()\n\n\n@pytest.fixture\ndef database_connection():\n \"\"\"Create database connection and close after.\"\"\"\n connection = create_connection()\n\n yield connection\n\n # Cleanup\n connection.close()\n```\n\n## Examples\n\n### Complete Unit Test Example\n\n```python\nimport pytest\nfrom unittest.mock import Mock\nfrom registry.services.server_service import ServerService\n\n\n@pytest.mark.unit\nclass TestServerService:\n \"\"\"Tests for ServerService.\"\"\"\n\n def test_register_server_with_valid_data(\n self,\n server_service,\n sample_server,\n ):\n \"\"\"Test registering a server with valid data.\"\"\"\n # Arrange\n server_id = \"test-server\"\n\n # Act\n result = server_service.register_server(server_id, sample_server)\n\n # Assert\n assert result is not None\n assert result[\"id\"] == server_id\n assert result[\"name\"] == sample_server[\"name\"]\n\n def test_register_server_with_duplicate_id_raises_error(\n self,\n server_service,\n sample_server,\n ):\n \"\"\"Test that duplicate server IDs raise an error.\"\"\"\n # Arrange\n server_id = \"test-server\"\n server_service.register_server(server_id, sample_server)\n\n # Act & Assert\n with pytest.raises(ValueError, match=\"already registered\"):\n server_service.register_server(server_id, sample_server)\n\n def test_list_servers_returns_all_registered_servers(\n self,\n server_service,\n ):\n \"\"\"Test listing all registered servers.\"\"\"\n # Arrange\n servers = create_multiple_servers(count=3)\n for server_id, server_info in servers.items():\n server_service.register_server(server_id, server_info)\n\n # Act\n result = server_service.list_servers()\n\n # Assert\n assert len(result) == 3\n assert all(s[\"id\"] in servers for s in result)\n```\n\n### Complete Integration Test Example\n\n```python\nimport pytest\nimport httpx\n\n\n@pytest.mark.integration\nclass TestAgentAPI:\n \"\"\"Integration tests for Agent API.\"\"\"\n\n async def test_complete_agent_workflow(\n self,\n base_url,\n auth_headers,\n ):\n \"\"\"Test complete agent registration workflow.\"\"\"\n async with httpx.AsyncClient() as client:\n # Create agent\n agent_data = {\n \"name\": \"Test Agent\",\n \"description\": \"Integration test agent\",\n \"url\": \"http://test.example.com\",\n }\n\n response = await client.post(\n f\"{base_url}/api/agents/register\",\n headers=auth_headers,\n json=agent_data,\n )\n\n assert response.status_code == 200\n agent_path = response.json()[\"path\"]\n\n # Retrieve agent\n response = await client.get(\n f\"{base_url}/api/agents/{agent_path}\",\n headers=auth_headers,\n )\n\n assert response.status_code == 200\n agent = response.json()\n assert agent[\"name\"] == \"Test Agent\"\n\n # Update agent\n response = await client.put(\n f\"{base_url}/api/agents/{agent_path}\",\n headers=auth_headers,\n json={\"description\": \"Updated description\"},\n )\n\n assert response.status_code == 200\n\n # Delete agent\n response = await client.delete(\n f\"{base_url}/api/agents/{agent_path}\",\n headers=auth_headers,\n )\n\n assert response.status_code in [200, 204]\n```\n\n## Summary\n\nKey points for writing effective tests:\n\n1. Follow AAA pattern (Arrange, Act, Assert)\n2. Write descriptive test names\n3. Test one thing per test\n4. Use fixtures for reusable test data\n5. Mock external dependencies\n6. Test edge cases and error handling\n7. Use parametrize for similar tests\n8. Keep tests independent\n9. Clean up resources\n10. Maintain good test coverage\n\nFor more information, see:\n- [Testing Guide](./README.md)\n- [Test Maintenance](./MAINTENANCE.md)\n" }, { "path": "docs/testing/memory-management.md", "content": "# Test Suite Memory Management\n\n## Problem\n\nRunning the full test suite with parallel execution can cause Out-of-Memory (OOM) crashes on EC2 instances, especially smaller instances with limited RAM.\n\n### Root Cause\n\nThe test suite includes:\n- **38 test files** with over 14,000 lines of test code\n- Heavy dependencies including:\n - Sentence-transformers embedding models (~120-200MB per process)\n - FAISS vector indexes\n - Full FastAPI application stack\n\nWhen using pytest-xdist with `-n auto`, pytest spawns one worker process per CPU core (4 workers on a 4-core EC2 instance). Each worker loads:\n- The embedding model\n- FAISS indexes\n- Test fixtures and data\n- The full application\n\n**Memory multiplication:** 4 workers × ~500MB per worker = ~2GB+ just for test processes\n\nThis can overwhelm EC2 instances with 8-16GB of RAM, especially when the OS and other services are also running.\n\n## Solution\n\n### Default Behavior (Serial Execution)\n\nThe test suite now runs **serially by default** to prevent OOM crashes:\n\n```bash\n# Safe for all EC2 instances - runs tests one at a time\npython scripts/test.py full\n```\n\n### Parallel Execution (Use with Caution)\n\nIf you have sufficient memory (16GB+ RAM), you can enable parallel execution:\n\n```bash\n# Run with 2 workers (safer for smaller EC2 instances)\npython scripts/test.py full -n 2\n\n# Run fast tests with 2 workers\npython scripts/test.py fast\n\n# Run unit tests with 4 workers (requires more memory)\npython scripts/test.py unit -n 4\n```\n\n### Monitoring Memory Usage\n\nBefore running tests with parallelization, check available memory:\n\n```bash\n# Check memory usage\nfree -h\n\n# Monitor memory in real-time\nwatch -n 1 free -h\n\n# Check processes by memory usage\nps aux --sort=-%mem | head -20\n```\n\n### Memory Guidelines\n\n| EC2 Instance Type | Recommended Workers | Notes |\n|-------------------|---------------------|-------|\n| t3.small (2GB) | 1 (serial) | Parallel execution will crash |\n| t3.medium (4GB) | 1 (serial) | May work with -n 2 for unit tests |\n| t3.large (8GB) | 2 | Safe for most tests |\n| t3.xlarge (16GB) | 3-4 | Can handle full parallelization |\n| t3.2xlarge (32GB) | auto | Full parallel execution safe |\n\n## Test Commands\n\n### Recommended Commands for EC2\n\n```bash\n# Check dependencies first\npython scripts/test.py check\n\n# Run unit tests only (fastest, safest)\npython scripts/test.py unit\n\n# Run integration tests\npython scripts/test.py integration\n\n# Run fast tests with 2 workers\npython scripts/test.py fast\n\n# Run full test suite serially (safe but slow)\npython scripts/test.py full\n\n# Generate coverage report (always serial)\npython scripts/test.py coverage\n```\n\n### Advanced Options\n\n```bash\n# Run specific domain tests\npython scripts/test.py auth # Authentication tests\npython scripts/test.py servers # Server management tests\npython scripts/test.py search # Search and AI tests\npython scripts/test.py health # Health monitoring tests\npython scripts/test.py core # Core infrastructure tests\n\n# Enable debug logging\npython scripts/test.py unit --debug\n\n# Run with custom worker count\npython scripts/test.py unit -n 3\n```\n\n## Direct pytest Usage\n\nIf using pytest directly, be aware of memory implications:\n\n```bash\n# DANGEROUS: May crash EC2 instance\npytest -n auto # Spawns workers = CPU cores\n\n# SAFER: Limit workers\npytest -n 2\n\n# SAFEST: Serial execution (no -n flag)\npytest\n```\n\n## Optimizations\n\n### For Local Development\n\nIf running locally with sufficient RAM (16GB+):\n\n```bash\n# Fast parallel execution for unit tests\npytest tests/unit -n auto\n\n# Fast parallel for specific domains\npytest tests/unit/auth -n auto\n```\n\n### For CI/CD\n\nGitHub Actions and other CI environments typically have limited memory. Use:\n\n```bash\n# Serial execution in CI\npytest\n\n# Or limit workers\npytest -n 2\n```\n\n### Future Improvements\n\nTo further reduce memory usage:\n\n1. **Mock Heavy Dependencies**: Mock sentence-transformers and FAISS in unit tests\n2. **Test Fixtures Optimization**: Share model loading across tests using session-scoped fixtures\n3. **Test Categorization**: Split heavy integration tests from lightweight unit tests\n4. **Lazy Loading**: Only load ML models when actually needed in tests\n\n## Troubleshooting\n\n### OOM Crash Symptoms\n\n- EC2 instance becomes unresponsive\n- SSH connection drops\n- Test suite hangs indefinitely\n- System logs show \"Out of memory: Killed process\"\n\n### Recovery Steps\n\n1. Reboot the EC2 instance if unresponsive\n2. Run tests serially: `python scripts/test.py full`\n3. Consider upgrading to a larger instance type\n4. Run tests in batches by domain:\n ```bash\n python scripts/test.py auth\n python scripts/test.py servers\n python scripts/test.py search\n ```\n\n### Debugging Memory Issues\n\n```bash\n# Check which process is using memory during tests\nwatch -n 1 'ps aux --sort=-%mem | head -20'\n\n# Check for OOM killer logs\ndmesg | grep -i \"out of memory\"\nsudo journalctl | grep -i \"out of memory\"\n```\n\n## Summary\n\n- **Default:** Tests run serially to prevent OOM crashes\n- **Safe Parallel:** Use `-n 2` for faster execution on typical EC2 instances\n- **Full Parallel:** Only use `-n auto` or higher worker counts on instances with 16GB+ RAM\n- **Monitor:** Always monitor memory usage when experimenting with parallelization\n" }, { "path": "docs/testing/test-categories.md", "content": "# Test Categories and Best Practices\n\n## Test Markers\n\nTests are organized using pytest markers to enable selective test execution:\n\n### Primary Categories\n\n- **`@pytest.mark.unit`** - Fast, isolated unit tests\n - No external dependencies\n - Mocked services and models\n - Should run in < 1 second each\n\n- **`@pytest.mark.integration`** - Integration tests\n - May interact with services\n - May use real HTTP clients\n - Can take longer to run\n\n- **`@pytest.mark.e2e`** - End-to-end workflow tests\n - Test complete user workflows\n - May involve multiple components\n - Typically slower\n\n### Domain-Specific Markers\n\n- **`@pytest.mark.auth`** - Authentication and authorization tests\n- **`@pytest.mark.servers`** - Server management tests\n- **`@pytest.mark.search`** - Search and AI functionality tests\n- **`@pytest.mark.health`** - Health monitoring tests\n- **`@pytest.mark.core`** - Core infrastructure tests\n\n### Special Markers\n\n- **`@pytest.mark.slow`** - Slow-running tests (> 5 seconds)\n - Excluded by default in fast test runs\n - Should be minimized\n\n- **`@pytest.mark.requires_models`** - Tests requiring real ML models\n - Will load actual embeddings models and FAISS\n - **WARNING**: These tests can cause OOM on small EC2 instances\n - Should only be used when absolutely necessary\n - Consider if the functionality can be tested with mocks instead\n\n## Default Test Behavior (Memory-Safe)\n\nBy default, **ALL** tests use mocked versions of heavy dependencies to prevent OOM crashes:\n\n- **FAISS service** - Mocked automatically\n- **Embeddings models** - Mocked automatically\n- **Sentence-transformers** - Mocked automatically\n- **PyTorch model loading** - Blocked\n\nThis means tests run fast and safely on any EC2 instance size.\n\n## Writing Memory-Safe Tests\n\n### Good Example (Default)\n\n```python\nimport pytest\n\n@pytest.mark.unit\ndef test_server_registration(server_service, sample_server):\n \"\"\"Test server registration with mocked dependencies.\"\"\"\n # FAISS and embeddings are automatically mocked\n server_service.register_server(sample_server)\n assert server_service.is_registered(sample_server[\"name\"])\n```\n\n### When You Need Real Models (Use Sparingly)\n\nOnly use real models when:\n1. Testing the actual ML model functionality\n2. Testing embeddings quality or accuracy\n3. Integration testing with real vector search\n\n```python\nimport pytest\n\n@pytest.mark.requires_models # Mark as requiring real models\n@pytest.mark.slow # Will be slow\n@pytest.mark.integration # Not a unit test\ndef test_real_embeddings_search(real_faiss_service):\n \"\"\"Test search with real embeddings model.\n\n WARNING: This test loads real ML models and may cause OOM on small instances.\n \"\"\"\n # This test actually loads sentence-transformers and FAISS\n await real_faiss_service.initialize()\n results = await real_faiss_service.search_services(\"test query\")\n assert len(results) > 0\n```\n\n**Running tests that require models:**\n\n```bash\n# Run all tests including those requiring models (WARNING: High memory usage)\npytest -m requires_models\n\n# Exclude tests requiring models (safe for EC2)\npytest -m \"not requires_models\"\n```\n\n## Test Fixtures\n\n### Automatically Available (Mocked)\n\nThese fixtures are automatically mocked for all tests:\n\n- `mock_faiss_service` - Mocked FAISS vector database\n- `mock_embeddings` - Mocked embeddings client\n- `prevent_real_model_loading` - Prevents torch/sentence-transformers loading\n\n### Commonly Used Test Fixtures\n\n- `test_client` - FastAPI TestClient\n- `async_client` - Async HTTP client\n- `mock_authenticated_user` - Simulates authenticated user\n- `server_service` - Server management service\n- `health_service` - Health monitoring service\n- `sample_server` - Sample server data for testing\n- `sample_servers` - Multiple sample servers\n- `temp_dir` - Temporary directory for tests\n\n### Settings and Configuration\n\n- `test_settings` - Test configuration with temp directories\n- `mock_settings` - Globally mocked settings\n\n## Writing Good Tests\n\n### Unit Test Example\n\n```python\nimport pytest\nfrom unittest.mock import Mock, AsyncMock\n\n@pytest.mark.unit\n@pytest.mark.auth\nclass TestAuthService:\n \"\"\"Tests for authentication service.\"\"\"\n\n def test_valid_token_verification(self, auth_service):\n \"\"\"Test that valid tokens are verified correctly.\"\"\"\n token = \"valid-token-12345\"\n result = auth_service.verify_token(token)\n assert result is True\n\n async def test_token_generation(self, auth_service):\n \"\"\"Test JWT token generation.\"\"\"\n user_data = {\"username\": \"testuser\", \"role\": \"admin\"}\n token = await auth_service.generate_token(user_data)\n assert token is not None\n assert len(token) > 50\n```\n\n### Integration Test Example\n\n```python\nimport pytest\nfrom httpx import AsyncClient\n\n@pytest.mark.integration\n@pytest.mark.servers\nclass TestServerRegistration:\n \"\"\"Integration tests for server registration API.\"\"\"\n\n async def test_register_server_endpoint(\n self,\n async_client: AsyncClient,\n sample_server,\n integration_auth_headers\n ):\n \"\"\"Test server registration via API endpoint.\"\"\"\n response = await async_client.post(\n \"/api/servers\",\n json=sample_server,\n headers=integration_auth_headers\n )\n assert response.status_code == 201\n data = response.json()\n assert data[\"name\"] == sample_server[\"name\"]\n```\n\n## Test Organization\n\n```\ntests/\n├── unit/ # Unit tests (fast, isolated)\n│ ├── auth/ # Authentication tests\n│ ├── api/ # API endpoint tests\n│ ├── core/ # Core functionality tests\n│ ├── services/ # Service layer tests\n│ └── ...\n├── integration/ # Integration tests\n│ ├── test_server_routes.py\n│ ├── test_search_routes.py\n│ └── test_e2e_workflows.py\n├── fixtures/ # Test data factories\n│ └── factories.py\n├── reports/ # Generated test reports\n└── conftest.py # Shared fixtures and configuration\n```\n\n## Best Practices\n\n### DO\n\n✅ Use markers to categorize tests\n✅ Mock heavy dependencies by default\n✅ Keep unit tests fast (< 1 second)\n✅ Test one thing per test function\n✅ Use descriptive test names\n✅ Clean up resources in fixtures\n✅ Use AAA pattern (Arrange, Act, Assert)\n\n### DON'T\n\n❌ Load real ML models in unit tests\n❌ Make network calls in unit tests\n❌ Share state between tests\n❌ Test implementation details\n❌ Write tests longer than 30 lines\n❌ Use `time.sleep()` - use mocks instead\n\n### Memory-Safe Testing\n\n✅ Use mocked services by default\n✅ Mark tests requiring real models with `@pytest.mark.requires_models`\n✅ Run tests serially on EC2 by default\n✅ Monitor memory usage during test development\n\n❌ Don't use `-n auto` on small EC2 instances\n❌ Don't load real models unless absolutely necessary\n❌ Don't skip mocking fixtures without good reason\n\n## Running Tests Efficiently\n\n```bash\n# Fast unit tests only (seconds)\npython scripts/test.py unit\n\n# Specific domain tests\npython scripts/test.py auth\npython scripts/test.py servers\n\n# Exclude slow tests\npython scripts/test.py fast\n\n# Full test suite (serial, safe)\npython scripts/test.py full\n\n# With parallelization (if you have memory)\npython scripts/test.py full -n 2\n\n# Exclude tests requiring real models\npytest -m \"not requires_models\"\n\n# Run only tests requiring models (high memory!)\npytest -m requires_models\n```\n\n## Debugging Test Failures\n\n```bash\n# Run with verbose output\npytest tests/unit/auth/test_auth_routes.py -v\n\n# Run specific test\npytest tests/unit/auth/test_auth_routes.py::test_login_success -v\n\n# Run with debug output\npytest tests/unit/auth/ -v --log-cli-level=DEBUG\n\n# Stop on first failure\npytest -x\n\n# Show local variables on failure\npytest -l\n\n# Run last failed tests\npytest --lf\n```\n\n## Coverage Requirements\n\n- Minimum overall coverage: 80%\n- All new code should have tests\n- Critical paths should have 100% coverage\n\n```bash\n# Generate coverage report\npython scripts/test.py coverage\n\n# View coverage report\nopen htmlcov/index.html\n```\n" }, { "path": "docs/testing.md", "content": "# MCP Gateway Testing Guide\n\nThis guide provides comprehensive testing instructions for the MCP Gateway using both the CLI client and the Python agent.\n\n## Table of Contents\n- [Regenerate Credentials](#regenerate-credentials)\n- [Quick Start Testing](#quick-start-testing)\n- [CLI Testing with mcp_client.py](#cli-testing-with-mcp_clientpy)\n- [Python Agent Testing](#python-agent-testing)\n- [Authentication Testing](#authentication-testing)\n- [Service Management Testing](#service-management-testing)\n- [Troubleshooting](#troubleshooting)\n\n## Regenerate Credentials\n\n**⚠️ Important:** Unless changed, Keycloak has an access token lifetime of only 5 minutes. You will most likely need to regenerate credentials before testing.\n\n### Generate Fresh Credentials\n\nRun the credential generation script to create fresh tokens:\n\n```bash\n# Generate new credentials for all agents and services\n./credentials-provider/generate_creds.sh\n```\n\nThis script will:\n- Generate fresh access tokens for all configured agents\n- Create M2M (machine-to-machine) tokens for service authentication\n- Update all credential files in `.oauth-tokens/` directory\n- Ensure tokens are valid for the current testing session\n\n**Note:** The script should be run whenever you encounter authentication errors or when tokens have expired (every 5 minutes by default).\n\n## Quick Start Testing\n\n### Prerequisites\n1. Ensure all containers are running:\n ```bash\n docker-compose ps\n ```\n\n2. Set up authentication (choose one method):\n ```bash\n # Method 1: Source M2M credentials\n source .oauth-tokens/agent-test-agent-m2m.env\n\n # Method 2: Automatic ingress token\n # The CLI will automatically use .oauth-tokens/ingress.json if available\n ```\n\n### Basic Connectivity Test\n```bash\n# Test gateway connectivity\nuv run python cli/mcp_client.py ping\n\n# List available tools\nuv run python cli/mcp_client.py list\n```\n\n## CLI Testing with mcp_client.py\n\nThe `mcp_client.py` tool provides direct access to MCP servers and gateway functionality.\n\n### Core Commands\n\n#### 1. Ping (Connectivity Test)\n```bash\n# Ping default gateway\nuv run python cli/mcp_client.py ping\n\n# Ping specific server\nuv run python cli/mcp_client.py --url http://localhost/currenttime/mcp ping\n```\n\n#### 2. List Tools\n```bash\n# List tools from gateway\nuv run python cli/mcp_client.py list\n\n# List tools from specific server\nuv run python cli/mcp_client.py --url http://localhost/currenttime/mcp list\n```\n\n#### 3. Call Tools\n```bash\n# Find tools using natural language\nuv run python cli/mcp_client.py call \\\n --tool intelligent_tool_finder \\\n --args '{\"natural_language_query\": \"get current time\"}'\n\n# Call specific tool with arguments\nuv run python cli/mcp_client.py --url http://localhost/currenttime/mcp call \\\n --tool current_time_by_timezone \\\n --args '{\"tz_name\": \"America/New_York\"}'\n\n# Health check all services\nuv run python cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool healthcheck \\\n --args '{}'\n```\n\n### Advanced Examples\n\n#### Tool Discovery\n```bash\n# Find tools by description\nuv run python cli/mcp_client.py call \\\n --tool intelligent_tool_finder \\\n --args '{\"natural_language_query\": \"time zone tools\", \"top_n_tools\": 5}'\n\n# Find tools by tags\nuv run python cli/mcp_client.py call \\\n --tool intelligent_tool_finder \\\n --args '{\"tags\": [\"time\", \"timezone\"], \"top_n_tools\": 3}'\n```\n\n#### Service Management\n```bash\n# List all registered services\nuv run python cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool list_services \\\n --args '{}'\n\n# Register a new service\nuv run python cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool register_service \\\n --args '{\"server_name\": \"Test Server\", \"path\": \"/test\", \"proxy_pass_url\": \"http://test:8000\"}'\n\n# Remove a service\nuv run python cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool remove_service \\\n --args '{\"service_path\": \"/test\"}'\n```\n\n## Python Agent Testing\n\nThe Python agent (`agents/agent.py`) provides advanced AI capabilities with LangGraph-based multi-turn conversations.\n\n### Prerequisites\n```bash\n# Install dependencies\ncd agents\npip install -r requirements.txt\n```\n\n### Basic Usage\n\n#### Non-Interactive Mode\n```bash\n# Simple query with default settings\nuv run python agents/agent.py --prompt \"What time is it in Tokyo?\"\n\n# Use specific model provider\nuv run python agents/agent.py --provider anthropic --prompt \"Get the current time\"\n\n# Use Amazon Bedrock\nuv run python agents/agent.py --provider bedrock --model anthropic.claude-3-5-sonnet-20240620-v1:0 \\\n --prompt \"What tools are available?\"\n```\n\n#### Interactive Mode\n```bash\n# Start interactive conversation\nuv run python agents/agent.py --interactive\n\n# Interactive with specific model\nuv run python agents/agent.py --interactive --provider anthropic\n\n# Interactive with verbose output\nuv run python agents/agent.py --interactive --verbose\n```\n\n### Authentication Options\n\n#### Using Agent Credentials\n```bash\n# Load credentials from .oauth-tokens/{agent-name}.json\nuv run python agents/agent.py --agent-name test-agent --prompt \"List available tools\"\n```\n\n#### Using JWT Token\n```bash\n# Use pre-generated JWT token\nuv run python agents/agent.py --jwt-token \"your-jwt-token\" --prompt \"Get current time\"\n```\n\n#### Using Session Cookie\n```bash\n# Use session cookie authentication\nuv run python agents/agent.py --use-session-cookie --prompt \"What tools are available?\"\n```\n\n#### Using Direct Access Token\n```bash\n# Override with direct access token\nuv run python agents/agent.py --access-token \"your-token\" --prompt \"List services\"\n```\n\n### Advanced Agent Examples\n\n#### Tool Filtering\n```bash\n# Filter to use specific MCP tool\nuv run python agents/agent.py --mcp-tool-name current_time_by_timezone \\\n --prompt \"What time is it in Paris?\"\n```\n\n#### Custom MCP Registry URL\n```bash\n# Use different registry\nuv run python agents/agent.py --mcp-registry-url https://your-registry.com \\\n --prompt \"List available services\"\n```\n\n#### Verbose Debugging\n```bash\n# Enable HTTP debugging\nuv run python agents/agent.py --verbose --prompt \"Test connection\"\n```\n\n## Authentication Testing\n\n### M2M Authentication\n```bash\n# Set environment variables\nexport CLIENT_ID=your_client_id\nexport CLIENT_SECRET=your_client_secret\nexport KEYCLOAK_URL=http://localhost:8080\nexport KEYCLOAK_REALM=mcp-gateway\n\n# Test with M2M auth\nuv run python cli/mcp_client.py list\n```\n\n### Ingress Token\n```bash\n# CLI automatically uses .oauth-tokens/ingress.json if available\nuv run python cli/mcp_client.py ping\n```\n\n### Testing Different Scopes\n```bash\n# Test with specific scopes (agent.py)\nuv run python agents/agent.py --scopes \"read:tools\" \"execute:tools\" \\\n --prompt \"List and execute time tools\"\n```\n\n## Service Management Testing\n\nUse the `service_mgmt.sh` script for comprehensive server lifecycle management:\n\n### Add a Service\n```bash\n# Add service from config file\n./cli/service_mgmt.sh add cli/examples/example-server-config.json\n```\n\n### Monitor Services\n```bash\n# Monitor all services\n./cli/service_mgmt.sh monitor\n\n# Monitor specific service\n./cli/service_mgmt.sh monitor cli/examples/example-server-config.json\n```\n\n### Test Service Searchability\n```bash\n# Test if service is discoverable\n./cli/service_mgmt.sh test cli/examples/example-server-config.json\n```\n\n### Delete a Service\n```bash\n# Remove service\n./cli/service_mgmt.sh delete cli/examples/example-server-config.json\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Connection Refused\n```bash\n# Check if services are running\ndocker-compose ps\n\n# Test direct registry access\ncurl http://localhost:7860/health\n\n# Check if MCP server is responding\nuv run python cli/mcp_client.py ping\n```\n\n#### Authentication Errors\n```bash\n# Verify credentials are loaded\necho $CLIENT_ID\necho $CLIENT_SECRET\n\n# Check token file exists\nls -la .oauth-tokens/ingress.json\n\n# Test with explicit credentials\nCLIENT_ID=test CLIENT_SECRET=secret uv run python cli/mcp_client.py list\n```\n\n#### Tool Not Found\n```bash\n# List all available tools\nuv run python cli/mcp_client.py list\n\n# Search for specific tools\nuv run python cli/mcp_client.py call \\\n --tool intelligent_tool_finder \\\n --args '{\"natural_language_query\": \"your tool description\"}'\n```\n\n### Debug Mode\n\n#### CLI Debug Output\n```bash\n# The CLI client shows detailed error messages by default\nuv run python cli/mcp_client.py call --tool nonexistent --args '{}'\n```\n\n#### Agent Verbose Mode\n```bash\n# Enable verbose HTTP debugging\nuv run python agents/agent.py --verbose --prompt \"test\"\n```\n\n### Health Checks\n\n#### Check All Services\n```bash\n# Full health check\nuv run python cli/mcp_client.py --url http://localhost/mcpgw/mcp call \\\n --tool healthcheck \\\n --args '{}'\n```\n\n#### Check Specific Server\n```bash\n# Direct server ping\nuv run python cli/mcp_client.py --url http://localhost/currenttime/mcp ping\n```\n\n## Integration Testing\n\n### CI/CD Pipeline Example\n```yaml\nname: MCP Gateway Tests\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n\n - name: Start services\n run: docker-compose up -d\n\n - name: Wait for services\n run: sleep 10\n\n - name: Test connectivity\n run: |\n uv run python cli/mcp_client.py ping\n\n - name: Test tool discovery\n run: |\n uv run python cli/mcp_client.py list\n\n - name: Test agent\n run: |\n uv run python agents/agent.py --prompt \"system health check\"\n```\n\n### Docker Container Testing\n```dockerfile\nFROM python:3.14-slim\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install -r requirements.txt\nCOPY cli/ cli/\nCOPY agents/ agents/\nCMD [\"python\", \"cli/mcp_client.py\", \"ping\"]\n```\n\n## Performance Testing\n\n### Load Testing\n```bash\n# Simple load test with multiple requests\nfor i in {1..10}; do\n uv run python cli/mcp_client.py ping &\ndone\nwait\n```\n\n### Response Time Testing\n```bash\n# Measure response time\ntime uv run python cli/mcp_client.py list\n```\n\n## Security Testing\n\n### Test Authentication\n```bash\n# Test without credentials (should fail appropriately)\nunset CLIENT_ID CLIENT_SECRET\nuv run python cli/mcp_client.py list\n\n# Test with invalid credentials\nCLIENT_ID=invalid CLIENT_SECRET=invalid uv run python cli/mcp_client.py list\n```\n\n### Test Authorization\n```bash\n# Test tool access with different scopes\nuv run python cli/mcp_client.py call \\\n --tool restricted_tool \\\n --args '{}'\n```\n\n## Notes\n\n- All examples assume you're running from the project root directory\n- The CLI client (`mcp_client.py`) automatically handles authentication via environment variables or ingress tokens\n- The Python agent (`agent.py`) provides more advanced AI capabilities for complex interactions\n- Use `service_mgmt.sh` for comprehensive server lifecycle management\n- For production testing, always use proper authentication and secure connections" }, { "path": "docs/token-refresh-service.md", "content": "# Token Refresh Service\n\nThe MCP Gateway Registry includes an automated token refresh service that maintains continuous authentication by monitoring token expiration and proactively refreshing them. This service ensures uninterrupted access to external services and generates MCP client configurations for coding assistants.\n\n## Overview\n\nThe token refresh service provides:\n\n- **Automated Token Monitoring** - Continuously monitors OAuth tokens for expiration\n- **Proactive Token Refresh** - Refreshes tokens before they expire using configurable buffer times\n- **MCP Configuration Generation** - Creates client configs for VS Code, Cursor, and other coding assistants\n- **Service Discovery** - Automatically includes both OAuth-authenticated and no-auth services\n- **Background Operation** - Runs as a daemon service with comprehensive logging\n\n## Architecture\n\n```mermaid\ngraph TB\n A[Token Refresher Service] --> B[OAuth Token Monitor]\n A --> C[No-Auth Service Scanner]\n A --> D[MCP Config Generator]\n \n B --> E[.oauth-tokens/*.json]\n C --> F[registry/servers/*.json]\n D --> G[.oauth-tokens/mcp.json]\n D --> H[.oauth-tokens/vscode_mcp.json]\n \n E --> I[External OAuth Services]\n F --> J[Local MCP Servers]\n G --> K[Roocode/Claude Code]\n H --> L[VS Code Extensions]\n```\n\nThe service integrates with:\n- **External OAuth services** (GitHub, Google, SRE Gateway, etc.)\n- **Local MCP servers** (Current Time, Real Server Fake Tools, etc.)\n- **MCP clients** (VS Code extensions, Claude Code, etc.)\n\n## Setup and Configuration\n\n### Prerequisites\n\n- Python 3.14+ with `uv` package manager\n- Valid OAuth tokens in `.oauth-tokens/` directory\n- MCP server configurations in `registry/servers/`\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `TOKEN_REFRESH_INTERVAL` | Check interval in seconds | 300 (5 minutes) |\n| `TOKEN_EXPIRY_BUFFER` | Refresh buffer time in seconds | 3600 (1 hour) |\n\n### Starting the Service\n\n#### Option 1: Using the Launch Script (Recommended)\n\n```bash\n# Start with interactive prompts\n./start_token_refresher.sh\n\n# Start with custom configuration\nexport TOKEN_REFRESH_INTERVAL=180 # 3 minutes\nexport TOKEN_EXPIRY_BUFFER=1800 # 30 minutes\n./start_token_refresher.sh\n```\n\n#### Option 2: Direct Python Execution\n\n```bash\n# Start with default settings\nuv run python credentials-provider/token_refresher.py\n\n# Start with custom settings\nuv run python credentials-provider/token_refresher.py \\\n --interval 300 \\\n --buffer 3600\n```\n\n### Command Line Options\n\n```\nusage: token_refresher.py [-h] [--interval INTERVAL] [--buffer BUFFER]\n [--log-level {DEBUG,INFO,WARNING,ERROR}]\n\nMCP Gateway OAuth Token Refresher Service\n\noptions:\n -h, --help show this help message and exit\n --interval INTERVAL Token check interval in seconds (default: 300)\n --buffer BUFFER Token expiry buffer in seconds (default: 3600)\n --log-level {DEBUG,INFO,WARNING,ERROR}\n Set the logging level (default: INFO)\n```\n\n## Service Management\n\n### Monitoring Service Status\n\n```bash\n# Check if service is running\npgrep -f \"token_refresher.py\"\n\n# View recent logs\ntail -f token_refresher.log\n\n# Monitor real-time activity\ntail -f token_refresher.log | grep -E \"(REFRESH|CONFIG|ERROR)\"\n```\n\n### Stopping the Service\n\n```bash\n# Graceful shutdown\npkill -f \"token_refresher.py\"\n\n# Force kill if needed\npkill -9 -f \"token_refresher.py\"\n```\n\n### Service Health Checks\n\nThe service creates a PID file (`token_refresher.pid`) for process management and logs all activities to `token_refresher.log`.\n\n## Generated Configurations\n\n### MCP Client Configurations\n\nThe service automatically generates two MCP configuration files:\n\n#### Roocode/Claude Code Configuration\n**File**: `.oauth-tokens/mcp.json`\n```json\n{\n \"mcpServers\": {\n \"sre-gateway\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/path/to/project\", \"run\", \"mcp\"],\n \"env\": {\n \"MCP_SERVER_URL\": \"https://gateway.example.com/mcp/sre-gateway/mcp\",\n \"MCP_SERVER_AUTH_TOKEN\": \"Bearer \"\n }\n }\n }\n}\n```\n\n#### VS Code Extension Configuration \n**File**: `.oauth-tokens/vscode_mcp.json`\n```json\n{\n \"mcpServers\": {\n \"sre-gateway\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-fetch\"],\n \"env\": {\n \"FETCH_BASE_URL\": \"https://gateway.example.com/mcp/sre-gateway/mcp\",\n \"FETCH_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer \\\"}\"\n }\n }\n }\n}\n```\n\n### Service Types\n\nThe service automatically includes:\n\n1. **OAuth Services** - Services requiring external authentication (e.g., GitHub, SRE Gateway)\n2. **No-Auth Services** - Local services with `auth_type: \"none\"` (e.g., Current Time, Real Server Fake Tools)\n\n## Integration Examples\n\n### With JWT Token Vending Service\n\nThe token refresh service complements the [JWT Token Vending Service](jwt-token-vending.md) by:\n\n1. **Monitoring vended tokens** for expiration\n2. **Automatically refreshing** tokens using stored refresh tokens\n3. **Updating MCP configurations** with new tokens\n4. **Maintaining continuous service** without manual intervention\n\n### With Existing Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant User as User/Script\n participant Vending as Token Vending Service\n participant Refresher as Token Refresh Service\n participant External as External Service\n participant MCP as MCP Client\n \n User->>Vending: Request JWT token\n Vending->>User: Return token + refresh token\n Vending->>Refresher: Save tokens to .oauth-tokens/\n \n loop Every 5 minutes\n Refresher->>Refresher: Check token expiration\n alt Token expires within buffer time\n Refresher->>External: Refresh token\n External->>Refresher: New token\n Refresher->>Refresher: Update .oauth-tokens/\n Refresher->>Refresher: Regenerate MCP configs\n end\n end\n \n MCP->>Refresher: Read latest MCP config\n MCP->>External: Use refreshed token\n```\n\n## Monitoring and Logging\n\n### Log Levels\n\n- **INFO** - Normal operations, token refreshes, config generation\n- **WARNING** - Token refresh failures, missing services\n- **ERROR** - Critical failures, authentication errors\n- **DEBUG** - Detailed trace information for troubleshooting\n\n### Sample Log Output\n\n```\n2024-09-06 15:30:00,123 - Token refresh check starting...\n2024-09-06 15:30:00,124 - Found 2 egress token files to check\n2024-09-06 15:30:00,125 - bedrock-agentcore-sre-gateway-egress.json: expires in 2 hours, no refresh needed\n2024-09-06 15:30:00,126 - github-github-egress.json: expires in 45 minutes, refreshing...\n2024-09-06 15:30:01,234 - Successfully refreshed token for github-github-\n2024-09-06 15:30:01,235 - Scanning for no-auth services...\n2024-09-06 15:30:01,236 - Found 3 no-auth services: mcpgw, currenttime, realserverfaketools\n2024-09-06 15:30:01,237 - Generating MCP configurations...\n2024-09-06 15:30:01,345 - Generated Roocode config with 5 servers\n2024-09-06 15:30:01,346 - Generated VSCode config with 5 servers\n2024-09-06 15:30:01,347 - Token refresh cycle completed successfully\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Service Won't Start\n\n**Symptoms**: Service exits immediately or fails to start\n**Causes**: \n- Missing dependencies\n- Invalid OAuth token files\n- Permission issues\n\n**Solutions**:\n```bash\n# Check dependencies\nuv run python -c \"import httpx, json, time, argparse, asyncio\"\n\n# Verify token files\nls -la .oauth-tokens/*.json\n\n# Check permissions\nchmod +x credentials-provider/token_refresher.py\nchmod +x start_token_refresher.sh\n```\n\n#### Token Refresh Failures\n\n**Symptoms**: Tokens not being refreshed, authentication errors\n**Causes**:\n- Expired refresh tokens\n- Invalid OAuth configuration\n- Network connectivity issues\n\n**Solutions**:\n```bash\n# Check token validity\ncat .oauth-tokens/*egress.json | jq '.expires_at'\n\n# Test network connectivity\ncurl -v https://your-oauth-provider.com/token\n\n# Re-run initial OAuth flow\n./credentials-provider/oauth/egress_oauth.py\n```\n\n#### MCP Configuration Issues\n\n**Symptoms**: MCP clients can't connect, missing services\n**Causes**:\n- Invalid service configurations\n- Missing environment variables\n- Incorrect file paths\n\n**Solutions**:\n```bash\n# Validate generated configs\ncat .oauth-tokens/mcp.json | jq '.'\ncat .oauth-tokens/vscode_mcp.json | jq '.'\n\n# Check service definitions\nls -la registry/servers/*.json\n\n# Verify environment variables\nenv | grep -E \"(MCP|TOKEN)\"\n```\n\n### Debug Mode\n\nEnable detailed logging for troubleshooting:\n\n```bash\n# Start with debug logging\nuv run python credentials-provider/token_refresher.py --log-level DEBUG\n\n# Or set environment variable\nexport LOG_LEVEL=DEBUG\n./start_token_refresher.sh\n```\n\n## Security Considerations\n\n### Token Storage\n\n- Token files are stored in `.oauth-tokens/` directory (excluded from Git)\n- File permissions are set to `600` (owner read/write only)\n- Refresh tokens are encrypted in transit and at rest\n\n### Network Security\n\n- All OAuth communication uses HTTPS/TLS\n- Tokens are transmitted using secure headers\n- Failed authentication attempts are logged and monitored\n\n### Access Control\n\n- Service runs with minimal required permissions\n- No network listeners (outbound connections only)\n- Process isolation using dedicated service account (recommended in production)\n\n## Production Deployment\n\n### Systemd Service (Linux)\n\nCreate `/etc/systemd/system/token-refresher.service`:\n\n```ini\n[Unit]\nDescription=MCP Gateway Token Refresh Service\nAfter=network.target\nWants=network.target\n\n[Service]\nType=simple\nUser=mcp-gateway\nWorkingDirectory=${HOME}/mcp-gateway-registry\nEnvironment=TOKEN_REFRESH_INTERVAL=300\nEnvironment=TOKEN_EXPIRY_BUFFER=3600\nExecStart=${HOME}/mcp-gateway-registry/.venv/bin/python credentials-provider/token_refresher.py\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\nEnable and start:\n```bash\nsudo systemctl enable token-refresher\nsudo systemctl start token-refresher\nsudo systemctl status token-refresher\n```\n\n### Docker Deployment\n\n```dockerfile\nFROM python:3.14-slim\n\nWORKDIR /app\nCOPY . .\nRUN pip install uv && uv install\n\nCMD [\"uv\", \"run\", \"python\", \"credentials-provider/token_refresher.py\"]\n```\n\n### Health Monitoring\n\nSet up monitoring for production:\n\n```bash\n# Create health check script\ncat > /opt/scripts/check-token-refresher.sh << 'EOF'\n#!/bin/bash\nif ! pgrep -f \"token_refresher.py\" > /dev/null; then\n echo \"CRITICAL: Token refresher service is not running\"\n exit 2\nfi\necho \"OK: Token refresher service is running\"\nexit 0\nEOF\n```\n\n## API Reference\n\n### Service Methods\n\nThe token refresher service provides these internal methods:\n\n- `_check_token_expiry()` - Check if token needs refresh\n- `_refresh_oauth_token()` - Refresh an expired token\n- `_scan_noauth_services()` - Discover no-auth services\n- `_generate_mcp_configs()` - Generate MCP client configurations\n- `_save_configurations()` - Write config files to disk\n\n### Configuration Schema\n\n#### Egress Token File Format\n```json\n{\n \"access_token\": \"eyJ...\",\n \"refresh_token\": \"eyJ...\", \n \"expires_at\": 1725634800,\n \"token_type\": \"Bearer\",\n \"scope\": \"read write\"\n}\n```\n\n#### MCP Server Configuration Format\n```json\n{\n \"server_name\": \"example-service\",\n \"auth_type\": \"oauth\" | \"none\",\n \"path\": \"/mcp/example-service/mcp\",\n \"supported_transports\": [\"streamable-http\", \"sse\"]\n}\n```\n\n## Related Documentation\n\n- [Authentication Guide](auth.md) - OAuth setup and configuration\n- [JWT Token Vending](jwt-token-vending.md) - Token generation and management \n- [AI Coding Assistants Setup](ai-coding-assistants-setup.md) - Client configuration\n- [Configuration Reference](configuration.md) - Environment variables and settings\n\n## Support\n\nFor issues with the token refresh service:\n\n1. Check the [Troubleshooting Guide](faq/index.md)\n2. Enable debug logging to gather detailed information\n3. Search existing [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues)\n4. Create a new issue with logs and configuration details" }, { "path": "docs/virtual-server-operations.md", "content": "# Virtual MCP Server Operations\n\nThis document describes operations for managing Virtual MCP Servers. Virtual servers aggregate tools from multiple backend MCP servers into a single unified endpoint.\n\nFor the full design and architecture details, see [Virtual MCP Server Design Document](design/virtual-mcp-server.md).\n\n## Video Demo\n\nWatch the video demonstration of Virtual MCP Server creation and management through the web UI:\n\n[![Virtual MCP Server Demo](https://img.shields.io/badge/Watch-Video%20Demo-red?style=for-the-badge&logo=youtube)](https://app.vidcast.io/share/954e6296-f217-4559-8d86-88cec25af763)\n\n[View Video Demo](https://app.vidcast.io/share/954e6296-f217-4559-8d86-88cec25af763)\n\n## Prerequisites\n\n- A valid JWT token (saved to a file, e.g., `.token`)\n- Registry URL (e.g., `http://localhost` for local development)\n\n## Available CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `vs-create` | Create a virtual MCP server from JSON config |\n| `vs-list` | List all virtual MCP servers |\n| `vs-get` | Get virtual MCP server details |\n| `vs-update` | Update a virtual MCP server |\n| `vs-delete` | Delete a virtual MCP server |\n| `vs-toggle` | Enable or disable a virtual server |\n| `vs-rate` | Rate a virtual MCP server (1-5 stars) |\n| `vs-rating` | Get rating information |\n\n## Configuration File Format\n\nVirtual servers are created from a JSON configuration file. Here is an example that combines tools from Context7 (documentation search) and CurrentTime (timezone) servers:\n\n```json\n{\n \"path\": \"/virtual/combined-tools\",\n \"server_name\": \"Combined Context7 and CurrentTime Tools\",\n \"description\": \"Virtual server aggregating documentation search tools from Context7 and timezone tools from CurrentTime server\",\n \"tool_mappings\": [\n {\n \"tool_name\": \"resolve-library-id\",\n \"backend_server_path\": \"/context7\"\n },\n {\n \"tool_name\": \"query-docs\",\n \"backend_server_path\": \"/context7\"\n },\n {\n \"tool_name\": \"current_time_by_timezone\",\n \"alias\": \"get-current-time\",\n \"backend_server_path\": \"/currenttime/\"\n }\n ],\n \"required_scopes\": [],\n \"tool_scope_overrides\": [],\n \"tags\": [\n \"documentation\",\n \"time\",\n \"timezone\",\n \"libraries\",\n \"combined\"\n ],\n \"supported_transports\": [\n \"streamable-http\"\n ],\n \"is_enabled\": true\n}\n```\n\nSee [cli/examples/virtual-server-combined-example.json](../cli/examples/virtual-server-combined-example.json) for the full example.\n\n### Configuration Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `path` | Yes | Virtual server path (e.g., `/virtual/dev-tools`) |\n| `server_name` | Yes | Display name for the virtual server |\n| `description` | No | Description of the virtual server |\n| `tool_mappings` | Yes | Array of tool mappings (at least one required) |\n| `required_scopes` | No | Server-level scope requirements |\n| `tool_scope_overrides` | No | Per-tool scope overrides |\n| `tags` | No | Tags for categorization |\n| `supported_transports` | No | Supported transports (default: `[\"streamable-http\"]`) |\n| `is_enabled` | No | Whether to enable on creation (default: `true`) |\n\n### Tool Mapping Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `tool_name` | Yes | Original tool name on backend server |\n| `backend_server_path` | Yes | Backend server path (e.g., `/github`) |\n| `alias` | No | Renamed tool name in virtual server |\n| `backend_version` | No | Pin to specific backend version |\n| `description_override` | No | Override tool description |\n\n## CLI Usage Examples\n\n### Create a Virtual Server\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-create --config cli/examples/virtual-server-combined-example.json\n```\n\n**Example Output:**\n\n```\nVirtual server created: /virtual/combined-tools\n{\n \"message\": \"Virtual server created successfully\",\n \"virtual_server\": {\n \"path\": \"/virtual/combined-tools\",\n \"server_name\": \"Combined Context7 and CurrentTime Tools\",\n \"description\": \"Virtual server aggregating documentation search tools from Context7 and timezone tools from CurrentTime server\",\n \"is_enabled\": false,\n \"tool_count\": 3\n }\n}\n```\n\n### List Virtual Servers\n\n```bash\n# List all virtual servers\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-list\n\n# List only enabled virtual servers\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-list --enabled-only\n\n# Output as JSON\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-list --json\n```\n\n### Get Virtual Server Details\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-get --path /virtual/combined-tools\n```\n\n**Example Output:**\n\n```\nVirtual MCP Server: /virtual/combined-tools\n------------------------------------------------------------\n Name: Combined Context7 and CurrentTime Tools\n Status: enabled\n Description: Virtual server aggregating documentation search tools from Context7 and timezone tools from CurrentTime server\n Rating: 0.0 stars\n Tags: documentation, time, timezone, libraries, combined\n Transports: streamable-http\n Required Scopes: None\n\n Tool Mappings (3):\n - resolve-library-id\n Backend: /context7\n - query-docs\n Backend: /context7\n - current_time_by_timezone -> get-current-time\n Backend: /currenttime/\n\n Created: 2026-02-17T13:35:22.803009Z\n Updated: 2026-02-17T13:35:41.075488Z\n Created By: admin\n```\n\n### Enable or Disable a Virtual Server\n\n```bash\n# Enable\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-toggle --path /virtual/combined-tools --enabled true\n\n# Disable\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-toggle --path /virtual/combined-tools --enabled false\n```\n\n### Update a Virtual Server\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-update --path /virtual/combined-tools --config updated-config.json\n```\n\n### Delete a Virtual Server\n\n```bash\n# With confirmation prompt\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-delete --path /virtual/combined-tools\n\n# Skip confirmation\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-delete --path /virtual/combined-tools --force\n```\n\n### Rate a Virtual Server\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-rate --path /virtual/combined-tools --rating 5\n```\n\n### Get Virtual Server Rating\n\n```bash\nuv run python api/registry_management.py \\\n --registry-url http://localhost \\\n --token-file .token \\\n vs-rating --path /virtual/combined-tools\n```\n\n## Scope-Based Access Control\n\nVirtual servers support fine-grained access control through scopes. Virtual servers are configured in scope definitions exactly the same way as regular MCP servers - you simply use the virtual server path (e.g., `/virtual/scoped-tools`) as the server identifier.\n\nFor comprehensive documentation on how access control works, see [Virtual MCP Server Access Control](scopes.md#virtual-mcp-server-access-control) in the Fine-Grained Access Control documentation.\n\nSee [Scope-Based Access Control Example](../cli/examples/virtual-server-scoped-example.json) for a virtual server configuration with scopes.\n\n### Server-Level Scopes\n\nUse `required_scopes` to require users to have specific scopes to access the virtual server:\n\n```json\n{\n \"required_scopes\": [\"virtual-server/access\"]\n}\n```\n\n### Per-Tool Scope Overrides\n\nUse `tool_scope_overrides` to require additional scopes for specific tools:\n\n```json\n{\n \"tool_scope_overrides\": [\n {\n \"tool_alias\": \"sensitive-tool\",\n \"required_scopes\": [\"virtual-server/admin\"]\n }\n ]\n}\n```\n\n### E2E Testing Script\n\nAn end-to-end test script is provided for testing scope-based access control:\n\n```bash\n# Run the E2E test (with automatic cleanup)\n./tests/integration/test_virtual_server_scopes_e2e.sh \\\n --registry-url http://localhost \\\n --token-file .token\n\n# Run without cleanup (saves credentials for UI testing)\n./tests/integration/test_virtual_server_scopes_e2e.sh \\\n --registry-url http://localhost \\\n --token-file .token \\\n --no-cleanup\n\n# View saved credentials\ncat /tmp/.vs-creds\n```\n\nThe test script creates:\n- A virtual server with scope-based access control\n- A user group with matching scopes\n- An M2M service account for API testing\n- A regular user for UI testing\n\nSee [test_virtual_server_scopes_e2e.sh](../tests/integration/test_virtual_server_scopes_e2e.sh) for details.\n\n## Web UI Alternative\n\nAll virtual server management operations can also be performed through the web UI. The UI provides a guided wizard for creating virtual servers with:\n\n- Server configuration form\n- Tool selection from registered backend servers\n- Tool aliasing and scope configuration\n- Real-time validation\n\n## Environment Variables\n\nInstead of passing `--registry-url` each time, you can set environment variables:\n\n```bash\nexport REGISTRY_URL=http://localhost\nexport TOKEN_FILE=.token\n\n# Then run commands without flags\nuv run python api/registry_management.py vs-list\n```\n\n## Related Documentation\n\n- [Virtual MCP Server Design Document](design/virtual-mcp-server.md)\n- [CLI Reference](cli.md)\n- [Server Management](service-management.md)\n" }, { "path": "frontend/.gitignore", "content": ".Jules/\n" }, { "path": "frontend/README.md", "content": "# MCP Gateway Registry Frontend\n\nReact-based frontend for the MCP Gateway Registry application.\n\n## Development Setup\n\n### Prerequisites\n\n- Node.js 16+ and npm\n- Backend server running on `http://localhost:7860` (configured in `package.json` proxy)\n\n### Installation\n\n```bash\nnpm install\n```\n\nNote: The postinstall script will automatically apply patches to dependencies.\n\n### Running Development Server\n\n```bash\nnpm start\n```\n\nThe development server will start on `http://localhost:3000`.\n\n## Important Configuration Notes\n\n### webpack-dev-server v5 Compatibility Patch\n\nThis project uses `react-scripts` v5.0.1, which has a compatibility issue with `webpack-dev-server` v5. The project includes a patch to fix this issue.\n\n**Problem**: react-scripts v5.0.1 uses deprecated webpack-dev-server hooks (`onBeforeSetupMiddleware` and `onAfterSetupMiddleware`) that were removed in webpack-dev-server v5.\n\n**Solution**: We use `patch-package` to apply a patch that replaces the deprecated hooks with the modern `setupMiddlewares` API.\n\n**Patch Location**: `patches/react-scripts+5.0.1.patch`\n\n**How it Works**:\n1. The patch modifies `node_modules/react-scripts/config/webpackDevServer.config.js`\n2. Replaces deprecated hooks with `setupMiddlewares` function\n3. The patch is automatically applied after `npm install` via the postinstall script\n\n**If you encounter webpack-dev-server errors**:\n1. Delete `node_modules` and `package-lock.json`\n2. Run `npm install` to reinstall dependencies and reapply the patch\n3. If the patch fails, check the `patches/react-scripts+5.0.1.patch` file for conflicts\n\n## Available Scripts\n\n- `npm start` - Start the development server\n- `npm build` - Build the production bundle\n- `npm test` - Run the test suite\n- `npm run eject` - Eject from create-react-app (not recommended)\n\n## Tech Stack\n\n- React 18\n- TypeScript\n- Tailwind CSS\n- React Router v6\n- Heroicons\n- Axios\n\n## Project Structure\n\n```\nfrontend/\n├── src/\n│ ├── components/ # Reusable React components\n│ ├── contexts/ # React Context providers\n│ ├── hooks/ # Custom React hooks\n│ ├── pages/ # Page components\n│ └── App.tsx # Main application component\n├── public/ # Static assets\n├── patches/ # Dependency patches (managed by patch-package)\n└── package.json\n```\n\n## Dependencies Management\n\n### Using patch-package\n\nThis project uses `patch-package` to maintain patches for third-party dependencies. If you need to modify a dependency:\n\n1. Make changes to files in `node_modules/`\n2. Run `npx patch-package `\n3. Commit the generated patch file in `patches/` directory\n\nThe patches will be automatically applied after `npm install` via the postinstall script.\n" }, { "path": "frontend/e2e/helpers/auth.ts", "content": "import { Page, expect } from '@playwright/test';\n\nconst BASE_URL = 'http://localhost';\n\n/**\n * FastAPI backend URL (bypasses nginx auth_request).\n */\nconst BACKEND_URL = 'http://localhost:7860';\n\n/**\n * Headers that nginx normally sets after auth_request validation.\n */\nconst ADMIN_AUTH_HEADERS: Record = {\n 'X-User': 'admin',\n 'X-Username': 'admin',\n 'X-Scopes': 'mcp-registry-admin,mcp-servers-unrestricted/read,mcp-servers-unrestricted/execute,federation/peers',\n 'X-Auth-Method': 'oauth2',\n 'X-Client-Id': '',\n};\n\n/**\n * Mock response for /api/auth/me.\n */\nconst ADMIN_ME_RESPONSE = {\n username: 'admin',\n email: 'admin@local',\n auth_method: 'oauth2',\n provider: 'oauth2',\n scopes: ['mcp-registry-admin'],\n groups: ['mcp-registry-admin'],\n can_modify_servers: true,\n is_admin: true,\n ui_permissions: {\n list_service: ['all'],\n register_service: ['all'],\n health_check_service: ['all'],\n toggle_service: ['all'],\n modify_service: ['all'],\n list_agents: ['all'],\n get_agent: ['all'],\n publish_agent: ['all'],\n modify_agent: ['all'],\n delete_agent: ['all'],\n },\n accessible_servers: ['*'],\n accessible_services: ['all'],\n accessible_agents: ['all'],\n};\n\n/**\n * Default mock responses for API endpoints.\n * Used when the backend returns 500 (e.g. MongoDB auth issues).\n */\nconst MOCK_RESPONSES: Record = {\n '/api/servers': [],\n '/api/agents': [],\n '/api/skills': [],\n '/api/virtual-servers': [],\n '/api/peers': [],\n '/api/version': { version: '0.0.0-e2e' },\n};\n\n/**\n * Authenticate for e2e tests.\n *\n * Strategy:\n * 1. /api/auth/me is intercepted with a mock admin profile.\n * 2. Protected /api/* requests are proxied to the backend (port 7860)\n * with admin auth headers. 500 responses are replaced with safe\n * mock data so the SPA does not crash.\n * 3. Public auth endpoints flow through nginx normally.\n */\nexport async function loginAsAdmin(page: Page): Promise {\n // Intercept /api/auth/me with mock admin profile.\n await page.route('**/api/auth/me', async (route) => {\n await route.fulfill({\n status: 200,\n contentType: 'application/json',\n body: JSON.stringify(ADMIN_ME_RESPONSE),\n });\n });\n\n // Proxy protected /api/* requests to the backend.\n await page.route('**/api/**', async (route) => {\n const url = new URL(route.request().url());\n\n // Public auth paths go through nginx normally.\n if (url.pathname.startsWith('/api/auth/')) {\n return route.fallback();\n }\n\n // Build backend URL with admin auth headers.\n const backendUrl = `${BACKEND_URL}${url.pathname}${url.search}`;\n const headers: Record = {\n ...route.request().headers(),\n ...ADMIN_AUTH_HEADERS,\n };\n // Remove host header to avoid confusing the backend.\n delete headers['host'];\n\n try {\n const response = await page.request.fetch(backendUrl, {\n method: route.request().method(),\n headers,\n data: route.request().postDataBuffer() ?? undefined,\n });\n\n const status = response.status();\n\n if (status >= 400) {\n // Use mock response if we have one, otherwise return empty.\n const mock = MOCK_RESPONSES[url.pathname];\n if (mock !== undefined) {\n await route.fulfill({\n status: 200,\n contentType: 'application/json',\n body: JSON.stringify(mock),\n });\n } else {\n // Generic fallback: array for plural endpoints, object otherwise.\n const body = url.pathname.match(/\\/[a-z-]+s(\\/)?$/) ? '[]' : '{}';\n await route.fulfill({\n status: 200,\n contentType: 'application/json',\n body,\n });\n }\n return;\n }\n\n await route.fulfill({ response });\n } catch {\n // Backend unreachable - return mock data.\n const mock = MOCK_RESPONSES[url.pathname];\n try {\n await route.fulfill({\n status: 200,\n contentType: 'application/json',\n body: JSON.stringify(mock ?? []),\n });\n } catch {\n // Route was already handled; ignore.\n }\n }\n });\n\n // Navigate to the app (auth is handled via route interception above).\n await page.goto('/');\n await page.waitForLoadState('networkidle');\n\n // Verify we landed on the Dashboard (not the login page).\n await expect(page).toHaveURL('/', { timeout: 15000 });\n}\n\n/**\n * Navigate to the Settings page > Virtual MCP > Virtual Servers.\n *\n * The SPA uses relative asset paths (`./static/...`) so a direct\n * page.goto('/settings/virtual-mcp/servers') would fail to load JS/CSS.\n * Instead we click the Settings gear icon (which is a React Router Link)\n * then expand the Virtual MCP sidebar category.\n */\nexport async function navigateToVirtualServers(page: Page): Promise {\n // Ensure we start from the Dashboard (page loaded from /).\n const currentUrl = page.url();\n if (!currentUrl.endsWith('/') && !currentUrl.endsWith('localhost')) {\n await page.goto('/');\n await page.waitForLoadState('networkidle');\n }\n\n // Click the Settings gear icon (React Router ).\n const settingsLink = page.locator('a[title=\"Settings\"]');\n await expect(settingsLink).toBeVisible({ timeout: 5000 });\n await settingsLink.click();\n await page.waitForLoadState('networkidle');\n\n // Expand the \"Virtual MCP\" category in the settings sidebar.\n const virtualMcpCategory = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualMcpCategory).toBeVisible({ timeout: 10000 });\n await virtualMcpCategory.click();\n await page.waitForTimeout(300);\n\n // Click \"Virtual Servers\" under the expanded category.\n const virtualServersItem = page.locator('button:has-text(\"Virtual Servers\")');\n await expect(virtualServersItem).toBeVisible({ timeout: 5000 });\n await virtualServersItem.click();\n await page.waitForLoadState('networkidle');\n\n // Verify the Virtual MCP Servers heading appears.\n await expect(\n page.locator('h2:has-text(\"Virtual MCP Servers\")')\n ).toBeVisible({ timeout: 15000 });\n}\n" }, { "path": "frontend/e2e/virtual-server-accessibility.spec.ts", "content": "import { test, expect } from '@playwright/test';\nimport { loginAsAdmin, navigateToVirtualServers } from './helpers/auth';\n\n/**\n * Accessibility tests for Virtual MCP Server UI components.\n *\n * Verifies ARIA attributes, keyboard navigation, and screen reader\n * compatibility for modals, toggles, and interactive elements.\n */\ntest.describe('Virtual Server Accessibility', () => {\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n });\n\n test('create form modal should have correct ARIA attributes', async ({\n page,\n }) => {\n await navigateToVirtualServers(page);\n await page.click('button:has-text(\"Create Virtual Server\")');\n\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Verify role=\"dialog\" and aria-modal=\"true\"\n await expect(dialog).toHaveAttribute('role', 'dialog');\n await expect(dialog).toHaveAttribute('aria-modal', 'true');\n\n // Verify aria-label is set\n const ariaLabel = await dialog.getAttribute('aria-label');\n expect(ariaLabel).toBeTruthy();\n expect(ariaLabel).toContain('Create Virtual Server');\n\n // Clean up\n await page.keyboard.press('Escape');\n });\n\n test('Escape key should close the create form modal', async ({ page }) => {\n await navigateToVirtualServers(page);\n await page.click('button:has-text(\"Create Virtual Server\")');\n\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n await page.keyboard.press('Escape');\n await expect(dialog).not.toBeVisible({ timeout: 3000 });\n });\n\n test('toggle switches should have aria-label', async ({ page }) => {\n await navigateToVirtualServers(page);\n\n // Find all toggle switches in the virtual server table\n const toggleInputs = page.locator(\n 'input[type=\"checkbox\"][aria-label^=\"Enable\"]'\n );\n const count = await toggleInputs.count();\n\n if (count === 0) {\n // No servers exist (empty mock), so skip assertion but pass\n return;\n }\n\n // Each toggle should have a meaningful aria-label\n for (let i = 0; i < count; i++) {\n const ariaLabel = await toggleInputs.nth(i).getAttribute('aria-label');\n expect(ariaLabel).toBeTruthy();\n expect(ariaLabel).toMatch(/^Enable .+/);\n }\n });\n\n test('delete confirmation dialog should have correct ARIA attributes', async ({\n page,\n }) => {\n await navigateToVirtualServers(page);\n\n // Find a Delete button in the table\n const deleteButtons = page.locator('button:has-text(\"Delete\")');\n const hasServers = (await deleteButtons.count()) > 0;\n\n if (!hasServers) {\n test.skip();\n return;\n }\n\n // Click the first Delete button\n await deleteButtons.first().click();\n\n // The delete confirmation dialog should have correct ARIA\n const deleteDialog = page.locator(\n '[role=\"dialog\"][aria-label=\"Delete virtual server confirmation\"]'\n );\n await expect(deleteDialog).toBeVisible({ timeout: 5000 });\n await expect(deleteDialog).toHaveAttribute('role', 'dialog');\n await expect(deleteDialog).toHaveAttribute('aria-modal', 'true');\n\n // Clean up - dismiss dialog\n await deleteDialog.locator('button:has-text(\"Cancel\")').click();\n await expect(deleteDialog).not.toBeVisible({ timeout: 3000 });\n });\n\n test('Escape key should close the delete confirmation dialog', async ({\n page,\n }) => {\n await navigateToVirtualServers(page);\n\n const deleteButtons = page.locator('button:has-text(\"Delete\")');\n const hasServers = (await deleteButtons.count()) > 0;\n\n if (!hasServers) {\n test.skip();\n return;\n }\n\n await deleteButtons.first().click();\n\n const deleteDialog = page.locator(\n '[role=\"dialog\"][aria-label=\"Delete virtual server confirmation\"]'\n );\n await expect(deleteDialog).toBeVisible({ timeout: 5000 });\n\n // The delete input handles Escape to close the modal\n const inputField = deleteDialog.locator('input[type=\"text\"]');\n await inputField.focus();\n await page.keyboard.press('Escape');\n\n await expect(deleteDialog).not.toBeVisible({ timeout: 3000 });\n });\n\n test('Dashboard Virtual MCP filter tab should be accessible', async ({\n page,\n }) => {\n // The \"Virtual MCP\" filter button should be a proper button element\n const virtualTab = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualTab).toBeVisible({ timeout: 5000 });\n\n // It should be focusable\n await virtualTab.focus();\n\n // Pressing Enter should activate it\n await page.keyboard.press('Enter');\n await page.waitForTimeout(500);\n\n // The filter should be applied (button state should change)\n // Check that the button has an active/selected visual state\n const buttonText = await virtualTab.textContent();\n expect(buttonText).toContain('Virtual MCP');\n });\n});\n" }, { "path": "frontend/e2e/virtual-server-crud.spec.ts", "content": "import { test, expect } from '@playwright/test';\nimport { loginAsAdmin, navigateToVirtualServers } from './helpers/auth';\n\n/**\n * Full CRUD lifecycle tests for Virtual MCP Servers.\n *\n * Flow: Create -> Verify in list -> Toggle enable/disable -> Delete with\n * name confirmation -> Verify removal.\n */\ntest.describe('Virtual Server CRUD', () => {\n const SERVER_NAME = `E2E Test Server ${Date.now()}`;\n const SERVER_DESCRIPTION = 'Created by Playwright e2e test';\n\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n });\n\n test('should create a virtual server via the wizard', async ({ page }) => {\n await navigateToVirtualServers(page);\n\n // Click \"Create Virtual Server\" button\n const createBtn = page.locator('button:has-text(\"Create Virtual Server\")');\n await expect(createBtn).toBeVisible({ timeout: 5000 });\n await createBtn.click();\n\n // The modal dialog should appear\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Step 1: Basics - fill in name and description\n // Placeholder is \"e.g. Dev Essentials\"\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', SERVER_NAME);\n await page.fill(\n 'textarea[placeholder=\"Describe what this virtual server provides...\"]',\n SERVER_DESCRIPTION\n );\n\n // The path should auto-generate from the name\n const pathInput = page.locator('input[placeholder=\"/virtual/dev-essentials\"]');\n await expect(pathInput).not.toHaveValue('');\n\n // Click Next to go to Tool Selection\n await dialog.locator('button:has-text(\"Next\")').click();\n\n // Step 2: Tool Selection\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // Click Next to go to Configuration (skip tool selection)\n await dialog.locator('button:has-text(\"Next\")').click();\n\n // Step 3: Configuration\n await expect(page.locator('text=Tool Aliases and Version Pins')).toBeVisible({\n timeout: 3000,\n });\n\n // Click Next to go to Review\n await dialog.locator('button:has-text(\"Next\")').click();\n\n // Step 4: Review - verify the name appears\n await expect(page.locator('text=Server Details')).toBeVisible({\n timeout: 3000,\n });\n await expect(dialog.locator(`text=${SERVER_NAME}`)).toBeVisible();\n await expect(dialog.locator(`text=${SERVER_DESCRIPTION}`)).toBeVisible();\n\n // Submit the form\n await dialog.locator('button:has-text(\"Create Virtual Server\")').click();\n\n // Wait for the modal to close\n await expect(dialog).not.toBeVisible({ timeout: 10000 });\n\n // Verify the server appears in the list (or empty state message)\n // The API might return empty if backend is mocked\n });\n\n test('should toggle a virtual server enable/disable', async ({ page }) => {\n await navigateToVirtualServers(page);\n\n // Find any toggle checkbox in the table (aria-label=\"Enable ...\")\n const toggle = page.locator('input[type=\"checkbox\"][aria-label^=\"Enable\"]').first();\n if (!(await toggle.isVisible({ timeout: 3000 }).catch(() => false))) {\n test.skip();\n return;\n }\n\n const isChecked = await toggle.isChecked();\n\n // Click the parent label since the checkbox is hidden (sr-only)\n // and a styled div overlay intercepts pointer events.\n const label = page.locator('label').filter({ has: toggle }).first();\n await label.click();\n await page.waitForTimeout(500);\n\n // Verify the toggle state flipped\n if (isChecked) {\n await expect(toggle).not.toBeChecked();\n } else {\n await expect(toggle).toBeChecked();\n }\n });\n\n test('should delete a virtual server with name confirmation', async ({\n page,\n }) => {\n await navigateToVirtualServers(page);\n\n // Find a Delete button in the table\n const deleteBtn = page.locator('button:has-text(\"Delete\")').first();\n if (!(await deleteBtn.isVisible({ timeout: 3000 }).catch(() => false))) {\n test.skip();\n return;\n }\n\n await deleteBtn.click();\n\n // Delete confirmation dialog should appear\n const deleteDialog = page.locator(\n '[role=\"dialog\"][aria-label=\"Delete virtual server confirmation\"]'\n );\n await expect(deleteDialog).toBeVisible({ timeout: 5000 });\n\n // The Delete button should be disabled until we type the name\n const confirmDeleteBtn = deleteDialog.locator('button:has-text(\"Delete\")');\n await expect(confirmDeleteBtn).toBeDisabled();\n\n // Type the server name from the placeholder (it shows the required name)\n const nameInput = deleteDialog.locator('input[type=\"text\"]');\n const placeholder = await nameInput.getAttribute('placeholder');\n if (placeholder) {\n await nameInput.fill(placeholder);\n // Now the delete button should be enabled\n await expect(confirmDeleteBtn).toBeEnabled();\n }\n\n // Cancel instead of actually deleting\n await deleteDialog.locator('button:has-text(\"Cancel\")').click();\n await expect(deleteDialog).not.toBeVisible({ timeout: 3000 });\n });\n});\n" }, { "path": "frontend/e2e/virtual-server-dashboard.spec.ts", "content": "import { test, expect } from '@playwright/test';\nimport { loginAsAdmin } from './helpers/auth';\n\n/**\n * Dashboard integration tests for Virtual MCP Servers.\n *\n * Verifies virtual server visibility and interactions on the Dashboard.\n */\ntest.describe('Virtual Server Dashboard', () => {\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n });\n\n test('should display the Virtual MCP filter tab on the Dashboard', async ({\n page,\n }) => {\n // The Dashboard should have a \"Virtual MCP\" filter button\n const virtualTab = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualTab).toBeVisible({ timeout: 5000 });\n });\n\n test('should show virtual server section when Virtual MCP tab is clicked', async ({\n page,\n }) => {\n // Click the \"Virtual MCP\" filter tab\n const virtualTab = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualTab).toBeVisible({ timeout: 5000 });\n await virtualTab.click();\n await page.waitForTimeout(500);\n\n // After clicking Virtual MCP tab, the \"Virtual MCP Servers\" heading\n // should appear. If no servers exist, an empty state is shown.\n const heading = page.locator('text=Virtual MCP Servers');\n const emptyState = page.locator(\n 'text=No virtual servers found'\n );\n\n const hasHeading = await heading.isVisible().catch(() => false);\n const hasEmptyState = await emptyState.isVisible().catch(() => false);\n\n // Either a heading or empty state should be visible\n expect(hasHeading || hasEmptyState).toBeTruthy();\n });\n\n test('should show empty state when Virtual MCP filter has no servers', async ({\n page,\n }) => {\n // Click \"Virtual MCP\" filter tab\n const virtualTab = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualTab).toBeVisible({ timeout: 5000 });\n await virtualTab.click();\n await page.waitForTimeout(500);\n\n // With mocked empty data, we should see a \"no results\" state or empty list\n const noServersMsg = page.locator(\n 'text=No virtual servers configured'\n );\n const noResultsMsg = page.locator('text=No servers found');\n const virtualBadges = page.locator('text=VIRTUAL');\n\n const hasNoServers = await noServersMsg.isVisible().catch(() => false);\n const hasNoResults = await noResultsMsg.isVisible().catch(() => false);\n const hasBadges = (await virtualBadges.count()) > 0;\n\n // One of these states should be true\n expect(hasNoServers || hasNoResults || hasBadges).toBeTruthy();\n });\n});\n" }, { "path": "frontend/e2e/virtual-server-e2e-full.spec.ts", "content": "import { test, expect } from '@playwright/test';\nimport { loginAsAdmin, navigateToVirtualServers } from './helpers/auth';\n\n/**\n * Comprehensive E2E test suite for Virtual MCP Servers.\n *\n * Covers: Dashboard tab, Settings list view, full CRUD lifecycle,\n * form validation / wizard navigation, and multi-backend inspection.\n */\n\n// ---------------------------------------------------------------------------\n// 1. Dashboard Virtual MCP tab\n// ---------------------------------------------------------------------------\ntest.describe('Dashboard Virtual MCP tab', () => {\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n });\n\n test('should render Virtual MCP filter tab on Dashboard', async ({ page }) => {\n const virtualTab = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualTab).toBeVisible({ timeout: 5000 });\n });\n\n test('should show virtual server cards when Virtual MCP tab is clicked', async ({\n page,\n }) => {\n const virtualTab = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualTab).toBeVisible({ timeout: 5000 });\n await virtualTab.click();\n await page.waitForTimeout(500);\n\n // After clicking the tab we should see either virtual server cards\n // (with names and VIRTUAL badges) or an appropriate heading/empty state.\n const heading = page.locator('text=Virtual MCP Servers');\n const virtualBadges = page.locator('text=VIRTUAL');\n const emptyState = page.locator('text=No virtual servers');\n\n const hasHeading = await heading.isVisible().catch(() => false);\n const hasBadges = (await virtualBadges.count()) > 0;\n const hasEmpty = await emptyState.isVisible().catch(() => false);\n\n expect(hasHeading || hasBadges || hasEmpty).toBeTruthy();\n });\n\n test('should display status badges on virtual server cards', async ({\n page,\n }) => {\n const virtualTab = page.locator('button:has-text(\"Virtual MCP\")');\n await expect(virtualTab).toBeVisible({ timeout: 5000 });\n await virtualTab.click();\n await page.waitForTimeout(500);\n\n // Look for Enabled / Disabled status text inside the card footer\n const enabledBadge = page.locator('text=Enabled');\n const disabledBadge = page.locator('text=Disabled');\n\n const hasEnabled = (await enabledBadge.count()) > 0;\n const hasDisabled = (await disabledBadge.count()) > 0;\n\n // At least one status badge should be visible if there are servers\n const virtualBadges = page.locator('text=VIRTUAL');\n const hasBadges = (await virtualBadges.count()) > 0;\n if (hasBadges) {\n expect(hasEnabled || hasDisabled).toBeTruthy();\n }\n });\n});\n\n// ---------------------------------------------------------------------------\n// 2. Settings list view\n// ---------------------------------------------------------------------------\ntest.describe('Settings list view', () => {\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n });\n\n test('should display Virtual MCP Servers heading and table', async ({\n page,\n }) => {\n await expect(\n page.locator('h2:has-text(\"Virtual MCP Servers\")')\n ).toBeVisible({ timeout: 5000 });\n\n // The table (or empty state) should be present\n const table = page.locator('table');\n const emptyState = page.locator('text=No virtual servers configured');\n\n const hasTable = await table.isVisible().catch(() => false);\n const hasEmpty = await emptyState.isVisible().catch(() => false);\n expect(hasTable || hasEmpty).toBeTruthy();\n });\n\n test('should show server rows with name, path, tools, backends, status columns', async ({\n page,\n }) => {\n const rows = page.locator('table tbody tr');\n const rowCount = await rows.count();\n\n if (rowCount === 0) {\n // No servers - empty state is fine\n return;\n }\n\n // Verify at least the first row has cells for name, path, tools, backends, status\n const firstRow = rows.first();\n const cells = firstRow.locator('td');\n // Table has 6 columns: Name, Path, Tools, Backends, Status, Actions\n expect(await cells.count()).toBeGreaterThanOrEqual(5);\n });\n\n test('should filter servers using the search input', async ({ page }) => {\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n\n // Type a search query that should not match anything\n await searchInput.fill('xyznonexistent');\n await page.waitForTimeout(300);\n\n // Should show \"No matching virtual servers\" empty state\n const noMatch = page.locator('text=No matching virtual servers');\n await expect(noMatch).toBeVisible({ timeout: 3000 });\n\n // Clear search\n await searchInput.fill('');\n await page.waitForTimeout(300);\n\n // Original servers should reappear (or default empty state)\n const table = page.locator('table');\n const emptyState = page.locator('text=No virtual servers configured');\n const hasTable = await table.isVisible().catch(() => false);\n const hasEmpty = await emptyState.isVisible().catch(() => false);\n expect(hasTable || hasEmpty).toBeTruthy();\n });\n\n test('should filter and find \"Time Only\" server by name', async ({\n page,\n }) => {\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n\n await searchInput.fill('Time Only');\n await page.waitForTimeout(300);\n\n // \"Time Only\" should still be visible in the table\n const timeOnly = page.locator('td:has-text(\"Time Only\")');\n const count = await timeOnly.count();\n if (count === 0) {\n // Server might not exist in this environment - acceptable\n return;\n }\n expect(count).toBeGreaterThanOrEqual(1);\n });\n});\n\n// ---------------------------------------------------------------------------\n// 3. Full CRUD lifecycle (serial - tests depend on order)\n// ---------------------------------------------------------------------------\ntest.describe.serial('Full CRUD lifecycle', () => {\n const SERVER_NAME = `Playwright Full Test ${Date.now()}`;\n const SERVER_DESCRIPTION = 'Full E2E lifecycle test by Playwright';\n const UPDATED_DESCRIPTION = 'Updated description by Playwright E2E';\n\n test('should create a virtual server via the wizard', async ({ page }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n\n // Click \"Create Virtual Server\"\n const createBtn = page.locator('button:has-text(\"Create Virtual Server\")');\n await expect(createBtn).toBeVisible({ timeout: 5000 });\n await createBtn.click();\n\n // Dialog should appear\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Step 1: Basics\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', SERVER_NAME);\n await page.fill(\n 'textarea[placeholder=\"Describe what this virtual server provides...\"]',\n SERVER_DESCRIPTION\n );\n\n // Path should auto-generate\n const pathInput = page.locator('input[placeholder=\"/virtual/dev-essentials\"]');\n await expect(pathInput).not.toHaveValue('');\n\n // Next -> Step 2: Tool Selection\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // Next -> Step 3: Configuration\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(\n page.locator('text=Tool Aliases and Version Pins')\n ).toBeVisible({ timeout: 3000 });\n\n // Next -> Step 4: Review\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(page.locator('text=Server Details')).toBeVisible({\n timeout: 3000,\n });\n\n // Verify review shows our name and description\n await expect(dialog.locator(`text=${SERVER_NAME}`)).toBeVisible();\n await expect(dialog.locator(`text=${SERVER_DESCRIPTION}`)).toBeVisible();\n\n // Submit\n await dialog.locator('button:has-text(\"Create Virtual Server\")').click();\n await expect(dialog).not.toBeVisible({ timeout: 10000 });\n });\n\n test('should verify the created server appears in the list', async ({\n page,\n }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n\n // Search for our server\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n await searchInput.fill(SERVER_NAME);\n await page.waitForTimeout(500);\n\n // The server should appear in the table\n const serverCell = page.locator(`td:has-text(\"${SERVER_NAME}\")`);\n const count = await serverCell.count();\n expect(count).toBeGreaterThanOrEqual(1);\n });\n\n test('should toggle a virtual server enable/disable', async ({ page }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n\n // Find any toggle checkbox in the table\n const toggle = page.locator(\n 'input[type=\"checkbox\"][aria-label^=\"Enable\"]'\n ).first();\n if (!(await toggle.isVisible({ timeout: 3000 }).catch(() => false))) {\n test.skip();\n return;\n }\n\n const isCheckedBefore = await toggle.isChecked();\n\n // Click the parent label (checkbox is sr-only) and wait for the\n // toggle POST + list refetch GET to complete.\n const label = page.locator('label').filter({ has: toggle }).first();\n await Promise.all([\n page.waitForResponse(\n (resp) =>\n resp.url().includes('/api/virtual-servers') &&\n resp.request().method() === 'GET',\n { timeout: 10000 },\n ),\n label.click(),\n ]);\n\n // Re-locate after possible re-render and verify the state flipped\n const toggleAfter = page\n .locator('input[type=\"checkbox\"][aria-label^=\"Enable\"]')\n .first();\n const isCheckedAfter = await toggleAfter.isChecked();\n\n // The state should have changed\n expect(isCheckedAfter).not.toBe(isCheckedBefore);\n\n // Toggle back to restore original state\n const labelAfter = page.locator('label').filter({ has: toggleAfter }).first();\n await Promise.all([\n page.waitForResponse(\n (resp) =>\n resp.url().includes('/api/virtual-servers') &&\n resp.request().method() === 'GET',\n { timeout: 10000 },\n ),\n labelAfter.click(),\n ]);\n });\n\n test('should delete the created server with name confirmation', async ({\n page,\n }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n\n // Search for our server\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n await searchInput.fill(SERVER_NAME);\n await page.waitForTimeout(500);\n\n // Click the Delete button in the matching row\n const deleteBtn = page.locator('button:has-text(\"Delete\")').first();\n if (!(await deleteBtn.isVisible({ timeout: 3000 }).catch(() => false))) {\n test.skip();\n return;\n }\n await deleteBtn.click();\n\n // Delete dialog should appear\n const deleteDialog = page.locator(\n '[role=\"dialog\"][aria-label=\"Delete virtual server confirmation\"]'\n );\n await expect(deleteDialog).toBeVisible({ timeout: 5000 });\n\n // Confirm button should be disabled initially\n const confirmDeleteBtn = deleteDialog.locator('button:has-text(\"Delete\")');\n await expect(confirmDeleteBtn).toBeDisabled();\n\n // Type the server name from the placeholder\n const nameInput = deleteDialog.locator('input[type=\"text\"]');\n const placeholder = await nameInput.getAttribute('placeholder');\n expect(placeholder).toBeTruthy();\n await nameInput.fill(placeholder!);\n\n // Now the delete button should be enabled\n await expect(confirmDeleteBtn).toBeEnabled();\n\n // Actually delete\n await confirmDeleteBtn.click();\n\n // Dialog should close\n await expect(deleteDialog).not.toBeVisible({ timeout: 10000 });\n });\n\n test('should verify the deleted server is removed from the list', async ({\n page,\n }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n\n // Search for our server\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n await searchInput.fill(SERVER_NAME);\n await page.waitForTimeout(500);\n\n // The server should no longer appear\n const serverCell = page.locator(`td:has-text(\"${SERVER_NAME}\")`);\n const count = await serverCell.count();\n\n // Either 0 rows or the \"No matching\" empty state\n const noMatch = page.locator('text=No matching virtual servers');\n const hasNoMatch = await noMatch.isVisible().catch(() => false);\n expect(count === 0 || hasNoMatch).toBeTruthy();\n });\n});\n\n// ---------------------------------------------------------------------------\n// 4. Form validation and wizard navigation\n// ---------------------------------------------------------------------------\ntest.describe('Form validation and wizard navigation', () => {\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n });\n\n test('should show error when name is empty and Next is clicked', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Click Next without filling name\n await dialog.locator('button:has-text(\"Next\")').click();\n\n // Validation error should appear\n await expect(page.locator('text=Server name is required')).toBeVisible({\n timeout: 3000,\n });\n });\n\n test('should auto-generate path from name', async ({ page }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', 'My Test Server');\n\n const pathInput = page.locator('input[placeholder=\"/virtual/dev-essentials\"]');\n await expect(pathInput).toHaveValue('/virtual/my-test-server');\n });\n\n test('should navigate through all 4 wizard steps forward and back', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Step 1: Basics\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', 'Wizard Nav Test');\n await expect(page.locator('text=Basics')).toBeVisible();\n\n // Forward to Step 2: Tool Selection\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // Forward to Step 3: Configuration\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(page.locator('text=Tool Aliases and Version Pins')).toBeVisible({\n timeout: 3000,\n });\n\n // Forward to Step 4: Review\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(page.locator('text=Server Details')).toBeVisible({\n timeout: 3000,\n });\n\n // Back to Step 3\n await dialog.locator('button:has-text(\"Back\")').click();\n await expect(page.locator('text=Tool Aliases and Version Pins')).toBeVisible({\n timeout: 3000,\n });\n\n // Back to Step 2\n await dialog.locator('button:has-text(\"Back\")').click();\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // Back to Step 1\n await dialog.locator('button:has-text(\"Back\")').click();\n await expect(\n page.locator('input[placeholder=\"e.g. Dev Essentials\"]')\n ).toBeVisible({ timeout: 3000 });\n });\n\n test('should close the form when Cancel is clicked on step 1', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n await dialog.locator('button:has-text(\"Cancel\")').click();\n await expect(dialog).not.toBeVisible({ timeout: 3000 });\n });\n\n test('should close the form when Cancel is clicked on a later step', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Fill name and advance to step 2\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', 'Cancel Test');\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // Cancel on step 2\n const cancelBtn = dialog.locator('button:has-text(\"Cancel\")');\n await cancelBtn.click();\n await expect(dialog).not.toBeVisible({ timeout: 3000 });\n });\n\n test('should close the form when Escape key is pressed', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n await page.keyboard.press('Escape');\n await expect(dialog).not.toBeVisible({ timeout: 3000 });\n });\n});\n\n// ---------------------------------------------------------------------------\n// 5. Multi-backend server inspection\n// ---------------------------------------------------------------------------\ntest.describe('Multi-backend server inspection', () => {\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n });\n\n test('should find \"E2E Multi Backend\" in the server list', async ({\n page,\n }) => {\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n await searchInput.fill('E2E Multi Backend');\n await page.waitForTimeout(500);\n\n const serverCell = page.locator('td:has-text(\"E2E Multi Backend\")');\n const count = await serverCell.count();\n if (count === 0) {\n // Server might not exist in this environment\n test.skip();\n return;\n }\n expect(count).toBeGreaterThanOrEqual(1);\n });\n\n test('should show tool count of 4 for \"E2E Multi Backend\"', async ({\n page,\n }) => {\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n await searchInput.fill('E2E Multi Backend');\n await page.waitForTimeout(500);\n\n const serverRow = page.locator('tr').filter({\n has: page.locator('td:has-text(\"E2E Multi Backend\")'),\n });\n const count = await serverRow.count();\n if (count === 0) {\n test.skip();\n return;\n }\n\n // The Tools column (3rd column, index 2) should contain \"4\"\n const toolsCell = serverRow.locator('td').nth(2);\n await expect(toolsCell).toHaveText('4');\n });\n\n test('should show 2 backend paths for \"E2E Multi Backend\"', async ({\n page,\n }) => {\n const searchInput = page.locator('input[placeholder=\"Search virtual servers...\"]');\n await expect(searchInput).toBeVisible({ timeout: 5000 });\n await searchInput.fill('E2E Multi Backend');\n await page.waitForTimeout(500);\n\n const serverRow = page.locator('tr').filter({\n has: page.locator('td:has-text(\"E2E Multi Backend\")'),\n });\n const count = await serverRow.count();\n if (count === 0) {\n test.skip();\n return;\n }\n\n // The Backends column (4th column, index 3) should show 2 backend path badges\n const backendsCell = serverRow.locator('td').nth(3);\n const backendBadges = backendsCell.locator('span');\n const badgeCount = await backendBadges.count();\n expect(badgeCount).toBe(2);\n\n // Verify the actual backend paths\n const badge1Text = await backendBadges.nth(0).textContent();\n const badge2Text = await backendBadges.nth(1).textContent();\n const allText = [badge1Text, badge2Text].join(' ');\n expect(allText).toContain('/currenttime/');\n expect(allText).toContain('/realserverfaketools/');\n });\n});\n" }, { "path": "frontend/e2e/virtual-server-form.spec.ts", "content": "import { test, expect } from '@playwright/test';\nimport { loginAsAdmin, navigateToVirtualServers } from './helpers/auth';\n\n/**\n * Form validation and wizard navigation tests for the Virtual Server form.\n *\n * Covers: required field validation, wizard step navigation, cancel/escape\n * behavior, and form auto-generation (path from name).\n */\ntest.describe('Virtual Server Form Validation', () => {\n test.beforeEach(async ({ page }) => {\n await loginAsAdmin(page);\n await navigateToVirtualServers(page);\n });\n\n test('should show validation error when name is empty and Next is clicked', async ({\n page,\n }) => {\n // Open create form\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Name field should be empty by default; click Next\n await dialog.locator('button:has-text(\"Next\")').click();\n\n // A validation error should appear\n await expect(page.locator('text=Server name is required')).toBeVisible({\n timeout: 3000,\n });\n });\n\n test('should auto-generate path from name', async ({ page }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Type a name\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', 'My Test Server');\n\n // The path should be auto-generated\n const pathInput = page.locator('input[placeholder=\"/virtual/dev-essentials\"]');\n await expect(pathInput).toHaveValue('/virtual/my-test-server');\n });\n\n test('should navigate through all wizard steps', async ({ page }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Step 1: Basics - fill required fields\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', 'Wizard Nav Test');\n await expect(page.locator('text=Basics')).toBeVisible();\n\n // Go to step 2: Tool Selection\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // Go to step 3: Configuration\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(page.locator('text=Tool Aliases and Version Pins')).toBeVisible({\n timeout: 3000,\n });\n\n // Go to step 4: Review\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(page.locator('text=Server Details')).toBeVisible({\n timeout: 3000,\n });\n\n // Go back to step 3 (footer left button says \"Back\")\n await dialog.locator('button:has-text(\"Back\")').click();\n await expect(page.locator('text=Tool Aliases and Version Pins')).toBeVisible({\n timeout: 3000,\n });\n\n // Go back to step 2\n await dialog.locator('button:has-text(\"Back\")').click();\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // Go back to step 1\n await dialog.locator('button:has-text(\"Back\")').click();\n await expect(\n page.locator('input[placeholder=\"e.g. Dev Essentials\"]')\n ).toBeVisible({ timeout: 3000 });\n });\n\n test('should close the form when Cancel is clicked on step 1', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // On step 1, the left footer button says \"Cancel\"\n await dialog.locator('button:has-text(\"Cancel\")').click();\n\n // Dialog should close\n await expect(dialog).not.toBeVisible({ timeout: 3000 });\n });\n\n test('should close the form when Cancel is clicked on a later step', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Fill name and advance to step 2\n await page.fill('input[placeholder=\"e.g. Dev Essentials\"]', 'Cancel Test');\n await dialog.locator('button:has-text(\"Next\")').click();\n await expect(\n page.locator('text=Select tools to include in this virtual server')\n ).toBeVisible({ timeout: 3000 });\n\n // On step 2+, there is a text \"Cancel\" button in the footer right area\n const cancelBtn = dialog.locator('button:has-text(\"Cancel\")');\n await cancelBtn.click();\n\n // Dialog should close\n await expect(dialog).not.toBeVisible({ timeout: 3000 });\n });\n\n test('should close the form when Escape key is pressed', async ({\n page,\n }) => {\n await page.click('button:has-text(\"Create Virtual Server\")');\n const dialog = page.locator('[role=\"dialog\"]');\n await expect(dialog).toBeVisible({ timeout: 5000 });\n\n // Press Escape\n await page.keyboard.press('Escape');\n\n // Dialog should close\n await expect(dialog).not.toBeVisible({ timeout: 3000 });\n });\n});\n" }, { "path": "frontend/package.json", "content": "{\n \"name\": \"mcp-gateway-frontend\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"homepage\": \"/\",\n \"dependencies\": {\n \"@headlessui/react\": \"^1.7.17\",\n \"@heroicons/react\": \"^2.0.18\",\n \"@tailwindcss/forms\": \"^0.5.7\",\n \"@tailwindcss/typography\": \"^0.5.10\",\n \"@types/node\": \"^16.18.0\",\n \"@types/react\": \"^18.2.45\",\n \"@types/react-dom\": \"^18.2.18\",\n \"ajv\": \"8.18.0\",\n \"autoprefixer\": \"^10.4.16\",\n \"axios\": \"^1.15.0\",\n \"clsx\": \"^2.0.0\",\n \"date-fns\": \"^4.1.0\",\n \"jszip\": \"^3.10.1\",\n \"postcss\": \"^8.5.12\",\n \"react\": \"^18.2.0\",\n \"react-dom\": \"^18.2.0\",\n \"react-markdown\": \"^10.1.0\",\n \"react-router-dom\": \"^6.30.3\",\n \"react-scripts\": \"5.0.1\",\n \"remark-gfm\": \"^4.0.0\",\n \"tailwindcss\": \"^3.3.6\",\n \"typescript\": \"^4.9.5\"\n },\n \"scripts\": {\n \"start\": \"react-scripts start\",\n \"build\": \"react-scripts build\",\n \"test\": \"react-scripts test\",\n \"eject\": \"react-scripts eject\",\n \"postinstall\": \"patch-package\"\n },\n \"eslintConfig\": {\n \"extends\": [\n \"react-app\",\n \"react-app/jest\"\n ]\n },\n \"browserslist\": {\n \"production\": [\n \">0.2%\",\n \"not dead\",\n \"not op_mini all\"\n ],\n \"development\": [\n \"last 1 chrome version\",\n \"last 1 firefox version\",\n \"last 1 safari version\"\n ]\n },\n \"jest\": {\n \"transformIgnorePatterns\": [\n \"node_modules/(?!axios)/\"\n ]\n },\n \"proxy\": \"http://localhost:7860\",\n \"overrides\": {\n \"nth-check\": \"^2.1.1\",\n \"webpack-dev-server\": \"^5.2.1\",\n \"resolve-url-loader\": \"^5.0.0\",\n \"serialize-javascript\": \">=7.0.5\",\n \"svgo\": \">=2.8.1\",\n \"@tootallnate/once\": \">=3.0.1\",\n \"underscore\": \">=1.13.8\",\n \"ajv@<6.14.0\": \"6.14.0\",\n \"qs\": \">=6.14.2\"\n },\n \"devDependencies\": {\n \"@playwright/test\": \"^1.58.2\",\n \"@testing-library/jest-dom\": \"^6.9.1\",\n \"@testing-library/react\": \"^16.3.2\",\n \"@testing-library/user-event\": \"^14.6.1\",\n \"@types/jest\": \"^30.0.0\",\n \"patch-package\": \"^8.0.1\",\n \"postinstall-postinstall\": \"^2.1.0\"\n }\n}\n" }, { "path": "frontend/patches/react-scripts+5.0.1.patch", "content": "diff --git a/node_modules/react-scripts/config/webpackDevServer.config.js b/node_modules/react-scripts/config/webpackDevServer.config.js\nindex 522a81b..75d3959 100644\n--- a/node_modules/react-scripts/config/webpackDevServer.config.js\n+++ b/node_modules/react-scripts/config/webpackDevServer.config.js\n@@ -109,7 +109,11 @@ module.exports = function (proxy, allowedHost) {\n },\n // `proxy` is run between `before` and `after` `webpack-dev-server` hooks\n proxy,\n- onBeforeSetupMiddleware(devServer) {\n+ setupMiddlewares: (middlewares, devServer) => {\n+ if (!devServer) {\n+ throw new Error('webpack-dev-server is not defined');\n+ }\n+\n // Keep `evalSourceMapMiddleware`\n // middlewares before `redirectServedPath` otherwise will not have any effect\n // This lets us fetch source contents from webpack for the error overlay\n@@ -119,8 +123,7 @@ module.exports = function (proxy, allowedHost) {\n // This registers user provided middleware for proxy reasons\n require(paths.proxySetup)(devServer.app);\n }\n- },\n- onAfterSetupMiddleware(devServer) {\n+\n // Redirect to `PUBLIC_URL` or `homepage` from `package.json` if url not match\n devServer.app.use(redirectServedPath(paths.publicUrlOrPath));\n \n@@ -130,6 +133,8 @@ module.exports = function (proxy, allowedHost) {\n // it used the same host and port.\n // https://github.com/facebook/create-react-app/issues/2272#issuecomment-302832432\n devServer.app.use(noopServiceWorkerMiddleware(paths.publicUrlOrPath));\n+\n+ return middlewares;\n },\n };\n };\n" }, { "path": "frontend/playwright.config.ts", "content": "import { defineConfig, devices } from '@playwright/test';\n\n/**\n * Playwright configuration for MCP Gateway Registry e2e tests.\n *\n * The app is served by nginx on port 80 (http://localhost).\n * Authentication uses basic auth with session cookies.\n */\nexport default defineConfig({\n testDir: './e2e',\n fullyParallel: false,\n forbidOnly: !!process.env.CI,\n retries: process.env.CI ? 2 : 0,\n workers: 1,\n reporter: 'html',\n timeout: 60_000,\n\n use: {\n baseURL: 'http://localhost',\n trace: 'on-first-retry',\n screenshot: 'only-on-failure',\n video: 'retain-on-failure',\n },\n\n projects: [\n {\n name: 'chromium',\n use: { ...devices['Desktop Chrome'] },\n },\n ],\n});\n" }, { "path": "frontend/postcss.config.js", "content": "module.exports = {\n plugins: {\n tailwindcss: {},\n autoprefixer: {},\n },\n} " }, { "path": "frontend/public/index.html", "content": "\n\n \n \n \n \n \n \n AI Gateway & Registry\n \n \n \n
\n \n " }, { "path": "frontend/src/App.tsx", "content": "import React from 'react';\nimport { BrowserRouter as Router, Routes, Route } from 'react-router-dom';\nimport { AuthProvider } from './contexts/AuthContext';\nimport { ThemeProvider } from './contexts/ThemeContext';\nimport Layout from './components/Layout';\nimport Dashboard from './pages/Dashboard';\nimport TokenGeneration from './pages/TokenGeneration';\nimport RegisterPage from './pages/RegisterPage';\nimport Login from './pages/Login';\nimport Logout from './pages/Logout';\nimport OAuthCallback from './pages/OAuthCallback';\nimport ProtectedRoute from './components/ProtectedRoute';\nimport SettingsPage from './pages/SettingsPage';\n\n// Get basename from tag for path-based routing (e.g., /registry)\nconst getBasename = () => {\n const baseTag = document.querySelector('base');\n if (baseTag && baseTag.href) {\n const url = new URL(baseTag.href);\n return url.pathname.replace(/\\/$/, '') || '/';\n }\n return '/';\n};\n\nfunction App() {\n return (\n \n \n \n \n } />\n } />\n } />\n \n \n \n \n \n } />\n \n \n \n \n \n } />\n \n \n \n \n \n } />\n \n \n \n \n \n } />\n \n \n \n \n );\n}\n\nexport default App; " }, { "path": "frontend/src/components/ANSBadge.tsx", "content": "import React, { useState, useEffect, useCallback } from 'react';\nimport { ShieldCheckIcon, ExclamationTriangleIcon, XCircleIcon, CodeBracketIcon } from '@heroicons/react/24/solid';\n\ninterface ANSFunction {\n id?: string;\n name?: string;\n tags?: string[] | null;\n}\n\ninterface ANSEndpoint {\n type?: string;\n url?: string;\n protocol?: string;\n transports?: string[];\n functions?: ANSFunction[];\n}\n\ninterface ANSLink {\n rel?: string;\n href?: string;\n}\n\ninterface ANSMetadata {\n ans_agent_id: string;\n status: 'verified' | 'expired' | 'revoked' | 'not_found' | 'pending';\n domain?: string;\n organization?: string;\n ans_name?: string;\n ans_display_name?: string;\n ans_description?: string;\n ans_version?: string;\n registered_with_ans_at?: string;\n certificate?: {\n not_after?: string;\n not_before?: string;\n subject_dn?: string;\n issuer_dn?: string;\n serial_number?: string;\n };\n endpoints?: ANSEndpoint[];\n links?: ANSLink[];\n raw_ans_response?: Record;\n last_verified?: string;\n}\n\ninterface ANSBadgeProps {\n ansMetadata: ANSMetadata | null | undefined;\n compact?: boolean;\n}\n\nconst STATUS_CONFIG = {\n verified: {\n label: 'ANS VERIFIED',\n Icon: ShieldCheckIcon,\n badgeClasses: 'bg-gradient-to-r from-emerald-100 to-green-100 text-emerald-700 ' +\n 'dark:from-emerald-900/30 dark:to-green-900/30 dark:text-emerald-300 ' +\n 'border border-emerald-200 dark:border-emerald-600',\n iconColor: 'text-emerald-600 dark:text-emerald-400',\n modalBadgeClasses: 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-300',\n },\n expired: {\n label: 'ANS EXPIRED',\n Icon: ExclamationTriangleIcon,\n badgeClasses: 'bg-gradient-to-r from-yellow-100 to-amber-100 text-yellow-700 ' +\n 'dark:from-yellow-900/30 dark:to-amber-900/30 dark:text-yellow-300 ' +\n 'border border-yellow-200 dark:border-yellow-600',\n iconColor: 'text-yellow-600 dark:text-yellow-400',\n modalBadgeClasses: 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-300',\n },\n revoked: {\n label: 'ANS REVOKED',\n Icon: XCircleIcon,\n badgeClasses: 'bg-gradient-to-r from-red-100 to-rose-100 text-red-700 ' +\n 'dark:from-red-900/30 dark:to-rose-900/30 dark:text-red-300 ' +\n 'border border-red-200 dark:border-red-600',\n iconColor: 'text-red-600 dark:text-red-400',\n modalBadgeClasses: 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-300',\n },\n not_found: {\n label: 'ANS NOT FOUND',\n Icon: ExclamationTriangleIcon,\n badgeClasses: 'bg-gradient-to-r from-gray-100 to-slate-100 text-gray-700 ' +\n 'dark:from-gray-900/30 dark:to-slate-900/30 dark:text-gray-300 ' +\n 'border border-gray-200 dark:border-gray-600',\n iconColor: 'text-gray-600 dark:text-gray-400',\n modalBadgeClasses: 'bg-gray-100 text-gray-700 dark:bg-gray-900/30 dark:text-gray-300',\n },\n pending: {\n label: 'ANS PENDING',\n Icon: ShieldCheckIcon,\n badgeClasses: 'bg-gradient-to-r from-blue-100 to-indigo-100 text-blue-700 ' +\n 'dark:from-blue-900/30 dark:to-indigo-900/30 dark:text-blue-300 ' +\n 'border border-blue-200 dark:border-blue-600',\n iconColor: 'text-blue-600 dark:text-blue-400',\n modalBadgeClasses: 'bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-300',\n },\n};\n\nconst LINK_LABELS: Record = {\n 'self': 'ANS Agent API',\n 'server-certificates': 'Server Certificates',\n 'identity-certificates': 'Identity Certificates',\n 'agent-details': 'Agent Details',\n};\n\n\nexport const ANSBadge: React.FC = ({ ansMetadata }) => {\n const [showModal, setShowModal] = useState(false);\n\n if (!ansMetadata) return null;\n\n const config = STATUS_CONFIG[ansMetadata.status] || STATUS_CONFIG.pending;\n const { label, Icon, badgeClasses, iconColor } = config;\n\n return (\n <>\n setShowModal(true)}\n >\n \n {label}\n \n\n {showModal && (\n setShowModal(false)}\n />\n )}\n \n );\n};\n\n\ninterface ANSCertificateModalProps {\n ansMetadata: ANSMetadata;\n onClose: () => void;\n}\n\nconst ANSCertificateModal: React.FC = ({ ansMetadata, onClose }) => {\n const [showRawJson, setShowRawJson] = useState(false);\n const config = STATUS_CONFIG[ansMetadata.status] || STATUS_CONFIG.pending;\n const { label, Icon, iconColor, modalBadgeClasses } = config;\n\n // Close on ESC key\n const handleKeyDown = useCallback((e: KeyboardEvent) => {\n if (e.key === 'Escape') {\n onClose();\n }\n }, [onClose]);\n\n useEffect(() => {\n document.addEventListener('keydown', handleKeyDown);\n return () => document.removeEventListener('keydown', handleKeyDown);\n }, [handleKeyDown]);\n\n const hasCertDetails = ansMetadata.certificate && (\n ansMetadata.certificate.subject_dn ||\n ansMetadata.certificate.issuer_dn ||\n ansMetadata.certificate.not_after\n );\n\n const hasEndpoints = ansMetadata.endpoints && ansMetadata.endpoints.length > 0;\n const hasLinks = ansMetadata.links && ansMetadata.links.length > 0;\n\n // Collect all unique functions across endpoints\n const allFunctions = (ansMetadata.endpoints || [])\n .flatMap(ep => ep.functions || [])\n .filter(fn => fn && fn.id);\n\n return (\n
\n
e.stopPropagation()}>\n\n {/* Header */}\n
\n

\n ANS Certificate Details\n

\n
\n {ansMetadata.raw_ans_response && (\n setShowRawJson(!showRawJson)}\n className={`p-1.5 rounded-lg transition-colors ${\n showRawJson\n ? 'bg-cyan-100 text-cyan-700 dark:bg-cyan-900/30 dark:text-cyan-400'\n : 'text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800'\n }`}\n title=\"View raw ANS JSON\"\n >\n \n \n )}\n \n ×\n \n
\n
\n\n {/* Raw JSON View */}\n {showRawJson && ansMetadata.raw_ans_response && (\n
\n 
\n              {JSON.stringify(ansMetadata.raw_ans_response, null, 2)}\n
\n
\n )}\n\n {/* Normal View */}\n {!showRawJson && (\n
\n\n {/* Status */}\n
\n
\n Status\n
\n \n \n {label}\n \n
\n\n {/* ANS Display Name */}\n {ansMetadata.ans_display_name && (\n
\n
\n ANS Registered Name\n
\n {ansMetadata.ans_display_name}\n
\n )}\n\n {/* Agent ID */}\n
\n
\n Agent ID\n
\n \n {ansMetadata.ans_agent_id}\n \n
\n\n {/* Domain */}\n {ansMetadata.domain && (\n
\n
\n Domain\n
\n \n {ansMetadata.domain}\n \n
\n )}\n\n {/* Agent Card URL */}\n {ansMetadata.domain && (\n
\n
\n Agent Card\n
\n \n https://{ansMetadata.domain}/.well-known/agent-card.json\n \n
\n )}\n\n {/* Organization */}\n {ansMetadata.organization && (\n
\n
\n Organization\n
\n {ansMetadata.organization}\n
\n )}\n\n {/* Version */}\n {ansMetadata.ans_version && (\n
\n
\n ANS Version\n
\n {ansMetadata.ans_version}\n
\n )}\n\n {/* ANS Registration Date */}\n {ansMetadata.registered_with_ans_at && (\n
\n
\n Registered with ANS\n
\n {new Date(ansMetadata.registered_with_ans_at).toLocaleString()}\n
\n )}\n\n {/* Certificate Section */}\n {hasCertDetails && (\n
\n
\n Certificate\n
\n
\n {ansMetadata.certificate?.subject_dn && (\n
\n Subject:{' '}\n {ansMetadata.certificate.subject_dn}\n
\n )}\n {ansMetadata.certificate?.issuer_dn && (\n
\n Issuer:{' '}\n {ansMetadata.certificate.issuer_dn}\n
\n )}\n {ansMetadata.certificate?.not_after && (\n
\n Expires:{' '}\n {new Date(ansMetadata.certificate.not_after).toLocaleDateString()}\n
\n )}\n {ansMetadata.certificate?.serial_number && (\n
\n Serial:{' '}\n {ansMetadata.certificate.serial_number}\n
\n )}\n
\n
\n )}\n\n {/* Endpoints Section */}\n {hasEndpoints && (\n
\n
\n Endpoints\n
\n
\n {ansMetadata.endpoints!.map((ep, idx) => (\n
\n
\n \n {ep.type || 'HTTP'}\n \n \n {ep.url}\n \n {ep.protocol && (\n \n {ep.protocol}\n \n )}\n
\n {ep.transports && ep.transports.length > 0 && (\n
\n Transport:\n {ep.transports.map((t, ti) => (\n \n {t}\n \n ))}\n
\n )}\n
\n ))}\n
\n
\n )}\n\n {/* Functions/Skills Section */}\n {allFunctions.length > 0 && (\n
\n
\n Functions\n
\n
\n {allFunctions.map((fn, idx) => (\n
\n {fn.name || fn.id}\n {fn.tags && fn.tags.length > 0 && (\n
\n {fn.tags.map((tag, ti) => (\n \n {tag}\n \n ))}\n
\n )}\n
\n ))}\n
\n
\n )}\n\n {/* ANS API Links Section */}\n {hasLinks && (\n
\n
\n ANS API Links\n
\n
\n {ansMetadata.links!.map((link, idx) => (\n
\n \n {LINK_LABELS[link.rel || ''] || link.rel}:\n \n \n {link.href}\n \n
\n ))}\n
\n
\n )}\n\n {/* Description from ANS */}\n {ansMetadata.ans_description && (\n
\n
\n ANS Description\n
\n

{ansMetadata.ans_description}

\n
\n )}\n\n {/* Last Verified */}\n {ansMetadata.last_verified && (\n
\n Last Verified: {new Date(ansMetadata.last_verified).toLocaleString()}\n
\n )}\n
\n )}\n\n {/* Close button */}\n
\n \n Close\n \n
\n
\n
\n );\n};\n\nexport default ANSBadge;\n" }, { "path": "frontend/src/components/AddRegistryEntryModal.tsx", "content": "import React, { useState } from 'react';\nimport axios from 'axios';\nimport DetailsModal from './DetailsModal';\n\n\n/**\n * Source types supported by this modal.\n */\nexport type RegistrySourceType = 'aws_registry' | 'anthropic' | 'asor';\n\n\n/**\n * Props for the AddRegistryEntryModal component.\n */\ninterface AddRegistryEntryModalProps {\n isOpen: boolean;\n onClose: () => void;\n sourceType: RegistrySourceType;\n onSuccess: () => void;\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\n\n/**\n * Form data for AWS Registry source.\n */\ninterface AwsRegistryFormData {\n registry_id: string;\n aws_account_id: string;\n aws_region: string;\n assume_role_arn: string;\n descriptor_types: string[];\n sync_status_filter: string;\n}\n\n\n/**\n * All available descriptor types for AWS Registry.\n */\nconst ALL_DESCRIPTOR_TYPES = ['MCP', 'A2A', 'CUSTOM', 'AGENT_SKILLS'];\n\n\n/**\n * Source type display labels.\n */\nconst SOURCE_TITLES: Record = {\n aws_registry: 'Add AWS Agent Registry',\n anthropic: 'Add Anthropic Server',\n asor: 'Add ASOR Agent',\n};\n\n\n/**\n * CSS classes for form inputs.\n */\nconst INPUT_CLASS =\n 'w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg ' +\n 'bg-white dark:bg-gray-900 text-gray-900 dark:text-white ' +\n 'focus:ring-2 focus:ring-purple-500 focus:border-transparent ' +\n 'placeholder-gray-400 dark:placeholder-gray-500 text-sm';\n\n\n/**\n * CSS classes for form labels.\n */\nconst LABEL_CLASS = 'block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1';\n\n\n/**\n * Default form data for AWS Registry.\n */\nfunction _defaultAwsFormData(): AwsRegistryFormData {\n return {\n registry_id: '',\n aws_account_id: '',\n aws_region: '',\n assume_role_arn: '',\n descriptor_types: [...ALL_DESCRIPTOR_TYPES],\n sync_status_filter: 'APPROVED',\n };\n}\n\n\n/**\n * Modal for adding a new entry to any federation source.\n *\n * Renders different form fields based on sourceType:\n * - aws_registry: multi-field form for AWS Agent Registry\n * - anthropic: single field for server name\n * - asor: single field for agent ID\n */\nconst AddRegistryEntryModal: React.FC = ({\n isOpen,\n onClose,\n sourceType,\n onSuccess,\n onShowToast,\n}) => {\n // Simple string fields for Anthropic/ASOR\n const [simpleValue, setSimpleValue] = useState('');\n\n // Multi-field form for AWS Registry\n const [awsForm, setAwsForm] = useState(_defaultAwsFormData());\n\n const [errors, setErrors] = useState>({});\n const [isSubmitting, setIsSubmitting] = useState(false);\n\n\n /**\n * Reset all form state when closing.\n */\n const handleClose = () => {\n setSimpleValue('');\n setAwsForm(_defaultAwsFormData());\n setErrors({});\n setIsSubmitting(false);\n onClose();\n };\n\n\n /**\n * Extract region and account ID from an ARN string.\n * ARN format: arn:aws:bedrock-agentcore:::registry/...\n * Returns extracted values as soon as enough colon-separated parts are present.\n */\n const extractFromArn = (arn: string): { region: string; accountId: string } | null => {\n const trimmed = arn.trim();\n if (!trimmed.startsWith('arn:')) return null;\n\n const parts = trimmed.split(':');\n // parts[3] = region, parts[4] = account_id\n const region = parts.length > 3 ? parts[3] : '';\n const accountId = parts.length > 4 ? parts[4] : '';\n\n // Only return if we have at least one useful value\n if (region || accountId) {\n return { region, accountId };\n }\n return null;\n };\n\n\n /**\n * Handle changes to AWS Registry form fields.\n * Auto-populates region and account ID when registry_id is an ARN.\n */\n const handleAwsChange = (e: React.ChangeEvent) => {\n const { name, value } = e.target;\n\n if (name === 'registry_id') {\n const extracted = extractFromArn(value);\n setAwsForm((prev) => ({\n ...prev,\n registry_id: value,\n aws_region: extracted?.region ?? prev.aws_region,\n aws_account_id: extracted?.accountId ?? prev.aws_account_id,\n }));\n } else {\n setAwsForm((prev) => ({ ...prev, [name]: value }));\n }\n\n if (errors[name]) {\n setErrors((prev) => ({ ...prev, [name]: '' }));\n }\n };\n\n\n /**\n * Toggle a descriptor type checkbox.\n */\n const handleDescriptorToggle = (dtype: string) => {\n setAwsForm((prev) => {\n const current = prev.descriptor_types;\n const updated = current.includes(dtype)\n ? current.filter((d) => d !== dtype)\n : [...current, dtype];\n return { ...prev, descriptor_types: updated };\n });\n };\n\n\n /**\n * Validate the form before submission.\n */\n const validateForm = (): boolean => {\n const newErrors: Record = {};\n\n if (sourceType === 'anthropic') {\n if (!simpleValue.trim()) {\n newErrors.server_name = 'Server name is required';\n }\n } else if (sourceType === 'asor') {\n if (!simpleValue.trim()) {\n newErrors.agent_id = 'Agent ID is required';\n }\n } else if (sourceType === 'aws_registry') {\n if (!awsForm.registry_id.trim()) {\n newErrors.registry_id = 'Registry ID is required';\n }\n if (awsForm.descriptor_types.length === 0) {\n newErrors.descriptor_types = 'At least one descriptor type is required';\n }\n }\n\n setErrors(newErrors);\n return Object.keys(newErrors).length === 0;\n };\n\n\n /**\n * Submit the form to add a new entry.\n */\n const handleSubmit = async (e: React.FormEvent) => {\n e.preventDefault();\n\n if (!validateForm()) return;\n\n setIsSubmitting(true);\n try {\n if (sourceType === 'anthropic') {\n await axios.post(\n `/api/federation/config/default/anthropic/servers?server_name=${encodeURIComponent(simpleValue.trim())}`\n );\n onShowToast(`Server '${simpleValue.trim()}' added`, 'success');\n } else if (sourceType === 'asor') {\n await axios.post(\n `/api/federation/config/default/asor/agents?agent_id=${encodeURIComponent(simpleValue.trim())}`\n );\n onShowToast(`Agent '${simpleValue.trim()}' added`, 'success');\n } else if (sourceType === 'aws_registry') {\n const payload: Record = {\n registry_id: awsForm.registry_id.trim(),\n descriptor_types: awsForm.descriptor_types,\n sync_status_filter: awsForm.sync_status_filter,\n };\n // Only include optional fields if filled\n if (awsForm.aws_account_id.trim()) {\n payload.aws_account_id = awsForm.aws_account_id.trim();\n }\n if (awsForm.aws_region.trim()) {\n payload.aws_region = awsForm.aws_region.trim();\n }\n if (awsForm.assume_role_arn.trim()) {\n payload.assume_role_arn = awsForm.assume_role_arn.trim();\n }\n await axios.post('/api/federation/config/default/aws_registry/registries', payload);\n onShowToast(`Registry '${awsForm.registry_id.trim()}' added`, 'success');\n }\n handleClose();\n onSuccess();\n } catch (err: any) {\n const detail = err?.response?.data?.detail || 'Failed to add entry';\n onShowToast(detail, 'error');\n } finally {\n setIsSubmitting(false);\n }\n };\n\n const maxWidth = sourceType === 'aws_registry' ? 'lg' : 'md';\n\n return (\n \n
\n {/* Anthropic: single server_name field */}\n {sourceType === 'anthropic' && (\n
\n \n {\n setSimpleValue(e.target.value);\n if (errors.server_name) setErrors((prev) => ({ ...prev, server_name: '' }));\n }}\n disabled={isSubmitting}\n className={INPUT_CLASS}\n placeholder=\"io.github.owner/server-name\"\n autoFocus\n />\n {errors.server_name && (\n

{errors.server_name}

\n )}\n

\n The server identifier from the Anthropic MCP Registry\n

\n
\n )}\n\n {/* ASOR: single agent_id field */}\n {sourceType === 'asor' && (\n
\n \n {\n setSimpleValue(e.target.value);\n if (errors.agent_id) setErrors((prev) => ({ ...prev, agent_id: '' }));\n }}\n disabled={isSubmitting}\n className={INPUT_CLASS}\n placeholder=\"my_agent_id\"\n autoFocus\n />\n {errors.agent_id && (\n

{errors.agent_id}

\n )}\n

\n The agent identifier from the ASOR registry\n

\n
\n )}\n\n {/* AWS Registry: multi-field form */}\n {sourceType === 'aws_registry' && (\n <>\n {/* Registry ID (required) */}\n
\n \n \n {errors.registry_id && (\n

{errors.registry_id}

\n )}\n
\n\n {/* Two-column layout for optional fields */}\n
\n
\n \n \n
\n
\n \n \n

\n Leave empty to use the global region\n

\n
\n
\n\n {/* Assume Role ARN */}\n
\n \n \n

\n Only needed if adding a registry from a different AWS account\n

\n
\n\n {/* Descriptor Types checkboxes */}\n
\n \n
\n {ALL_DESCRIPTOR_TYPES.map((dtype) => (\n \n handleDescriptorToggle(dtype)}\n disabled={isSubmitting}\n className=\"rounded border-gray-300 dark:border-gray-600\n text-purple-600 focus:ring-purple-500\"\n />\n {dtype}\n \n ))}\n
\n {errors.descriptor_types && (\n

\n {errors.descriptor_types}\n

\n )}\n
\n\n {/* Sync Status Filter */}\n
\n \n \n \n \n \n \n
\n \n )}\n\n {/* Action buttons */}\n
\n \n Cancel\n \n \n {isSubmitting ? 'Adding...' : 'Add'}\n \n
\n
\n \n );\n};\n\n\nexport default AddRegistryEntryModal;\n" }, { "path": "frontend/src/components/AgentCard.tsx", "content": "import React, { useState, useCallback, useEffect } from 'react';\nimport axios from 'axios';\nimport {\n StarIcon,\n ArrowPathIcon,\n PencilIcon,\n ClockIcon,\n CheckCircleIcon,\n XCircleIcon,\n QuestionMarkCircleIcon,\n ShieldCheckIcon,\n ShieldExclamationIcon,\n GlobeAltIcon,\n LockClosedIcon,\n InformationCircleIcon,\n TrashIcon,\n} from '@heroicons/react/24/outline';\nimport AgentDetailsModal from './AgentDetailsModal';\nimport SecurityScanModal from './SecurityScanModal';\nimport StarRatingWidget from './StarRatingWidget';\nimport DeleteConfirmation from './DeleteConfirmation';\nimport StatusBadge from './StatusBadge';\nimport { ANSBadge } from './ANSBadge';\nimport { formatRelativeTime } from '../utils/dateUtils';\n\ninterface SyncMetadata {\n is_federated?: boolean;\n source_peer_id?: string;\n upstream_path?: string;\n last_synced_at?: string;\n is_read_only?: boolean;\n is_orphaned?: boolean;\n orphaned_at?: string;\n}\n\n/**\n * Agent interface representing an A2A agent.\n */\nexport interface Agent {\n name: string;\n path: string;\n url?: string;\n description?: string;\n version?: string;\n visibility?: 'public' | 'private' | 'group-restricted';\n trust_level?: 'community' | 'verified' | 'trusted' | 'unverified';\n enabled: boolean;\n tags?: string[];\n last_checked_time?: string;\n usersCount?: number;\n rating?: number;\n rating_details?: Array<{ user: string; rating: number }>;\n status?: 'healthy' | 'healthy-auth-expired' | 'unhealthy' | 'unknown';\n // Federation sync metadata\n sync_metadata?: SyncMetadata;\n // ANS verification metadata\n ans_metadata?: {\n ans_agent_id: string;\n status: 'verified' | 'expired' | 'revoked' | 'not_found' | 'pending';\n domain?: string;\n organization?: string;\n certificate?: {\n not_after?: string;\n subject_dn?: string;\n issuer_dn?: string;\n };\n last_verified?: string;\n };\n // Lifecycle status\n lifecycle_status?: 'active' | 'deprecated' | 'draft' | 'beta';\n source_created_at?: string;\n source_updated_at?: string;\n // Supported protocol (e.g., 'a2a', 'mcp')\n supported_protocol?: string | null;\n}\n\n/**\n * Props for the AgentCard component.\n */\ninterface AgentCardProps {\n agent: Agent & { [key: string]: any }; // Allow additional fields from full agent JSON\n onToggle: (path: string, enabled: boolean) => void;\n onEdit?: (agent: Agent) => void;\n canModify?: boolean;\n canHealthCheck?: boolean; // Whether user can run health check on this agent\n canToggle?: boolean; // Whether user can enable/disable this agent\n canDelete?: boolean; // Whether user can delete this agent\n onDelete?: (path: string) => Promise; // Callback to delete the agent\n onRefreshSuccess?: () => void;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n onAgentUpdate?: (path: string, updates: Partial) => void;\n authToken?: string | null;\n}\n\n/**\n * Helper function to format time since last checked.\n */\nconst formatTimeSince = (timestamp: string | null | undefined): string | null => {\n if (!timestamp) {\n return null;\n }\n\n try {\n const now = new Date();\n const lastChecked = new Date(timestamp);\n\n // Check if the date is valid\n if (isNaN(lastChecked.getTime())) {\n return null;\n }\n\n const diffMs = now.getTime() - lastChecked.getTime();\n\n const diffSeconds = Math.floor(diffMs / 1000);\n const diffMinutes = Math.floor(diffSeconds / 60);\n const diffHours = Math.floor(diffMinutes / 60);\n const diffDays = Math.floor(diffHours / 24);\n\n let result;\n if (diffSeconds < 0) {\n result = 'just now';\n } else if (diffDays > 0) {\n result = `${diffDays}d ago`;\n } else if (diffHours > 0) {\n result = `${diffHours}h ago`;\n } else if (diffMinutes > 0) {\n result = `${diffMinutes}m ago`;\n } else {\n result = `${diffSeconds}s ago`;\n }\n\n return result;\n } catch (error) {\n console.error('formatTimeSince error:', error, 'for timestamp:', timestamp);\n return null;\n }\n};\n\nconst normalizeHealthStatus = (status?: string | null): Agent['status'] => {\n if (status === 'healthy' || status === 'healthy-auth-expired') {\n return status;\n }\n if (status === 'unhealthy') {\n return 'unhealthy';\n }\n return 'unknown';\n};\n\n/**\n * AgentCard component for displaying A2A agents.\n *\n * Displays agent information with a distinct visual style from MCP servers,\n * using blue/cyan tones and robot-themed icons.\n */\nconst AgentCard: React.FC = React.memo(({\n agent,\n onToggle,\n onEdit,\n canModify,\n canHealthCheck = true,\n canToggle = true,\n canDelete,\n onDelete,\n onRefreshSuccess,\n onShowToast,\n onAgentUpdate,\n authToken\n}) => {\n const [showDetails, setShowDetails] = useState(false);\n const [loadingRefresh, setLoadingRefresh] = useState(false);\n const [fullAgentDetails, setFullAgentDetails] = useState(null);\n const [loadingDetails, setLoadingDetails] = useState(false);\n const [showSecurityScan, setShowSecurityScan] = useState(false);\n const [securityScanResult, setSecurityScanResult] = useState(null);\n const [loadingSecurityScan, setLoadingSecurityScan] = useState(false);\n const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);\n\n // Check if this is a federated agent from a peer registry using sync_metadata\n const isFederatedAgent = agent.sync_metadata?.is_federated === true;\n const peerRegistryId = isFederatedAgent && agent.sync_metadata?.source_peer_id\n ? agent.sync_metadata.source_peer_id\n : null;\n\n // Check if this agent is orphaned (no longer exists on peer registry)\n const isOrphanedAgent = agent.sync_metadata?.is_orphaned === true;\n\n // Fetch security scan status on mount to show correct icon color\n useEffect(() => {\n const fetchSecurityScan = async () => {\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/agents${agent.path}/security-scan`,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n } catch {\n // Silently ignore - no scan result available\n }\n };\n fetchSecurityScan();\n }, [agent.path, authToken]);\n\n const getStatusIcon = () => {\n switch (agent.status) {\n case 'healthy':\n return ;\n case 'healthy-auth-expired':\n return ;\n case 'unhealthy':\n return ;\n default:\n return ;\n }\n };\n\n const getTrustLevelColor = () => {\n switch (agent.trust_level) {\n case 'trusted':\n return 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400 border border-green-200 dark:border-green-700';\n case 'verified':\n return 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400 border border-blue-200 dark:border-blue-700';\n case 'community':\n default:\n return 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300 border border-gray-200 dark:border-gray-600';\n }\n };\n\n const getTrustLevelIcon = () => {\n switch (agent.trust_level) {\n case 'trusted':\n return ;\n case 'verified':\n return ;\n default:\n return null;\n }\n };\n\n const getVisibilityIcon = () => {\n return agent.visibility === 'public' ? (\n \n ) : (\n \n );\n };\n\n const handleRefreshHealth = useCallback(async () => {\n if (loadingRefresh) return;\n\n setLoadingRefresh(true);\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.post(\n `/api/agents${agent.path}/health`,\n undefined,\n headers ? { headers } : undefined\n );\n\n // Update just this agent instead of triggering global refresh\n if (onAgentUpdate && response.data) {\n const updates: Partial = {\n status: normalizeHealthStatus(response.data.status),\n last_checked_time: response.data.last_checked_iso\n };\n\n onAgentUpdate(agent.path, updates);\n } else if (onRefreshSuccess) {\n // Fallback to global refresh if onAgentUpdate is not provided\n onRefreshSuccess();\n }\n\n if (onShowToast) {\n onShowToast('Agent health status refreshed successfully', 'success');\n }\n } catch (error: any) {\n console.error('Failed to refresh agent health:', error);\n if (onShowToast) {\n onShowToast(error.response?.data?.detail || 'Failed to refresh agent health status', 'error');\n }\n } finally {\n setLoadingRefresh(false);\n }\n }, [agent.path, authToken, loadingRefresh, onRefreshSuccess, onShowToast, onAgentUpdate]);\n\n const handleCopyDetails = useCallback(\n async (data: any) => {\n try {\n await navigator.clipboard.writeText(JSON.stringify(data, null, 2));\n onShowToast?.('Full agent JSON copied to clipboard!', 'success');\n } catch (error) {\n console.error('Failed to copy JSON:', error);\n onShowToast?.('Failed to copy JSON', 'error');\n }\n },\n [onShowToast]\n );\n\n const handleViewSecurityScan = useCallback(async () => {\n if (loadingSecurityScan) return;\n\n setShowSecurityScan(true);\n setLoadingSecurityScan(true);\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/agents${agent.path}/security-scan`,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n } catch (error: any) {\n if (error.response?.status !== 404) {\n console.error('Failed to fetch security scan:', error);\n if (onShowToast) {\n onShowToast('Failed to load security scan results', 'error');\n }\n }\n setSecurityScanResult(null);\n } finally {\n setLoadingSecurityScan(false);\n }\n }, [agent.path, authToken, loadingSecurityScan, onShowToast]);\n\n const handleRescan = useCallback(async () => {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.post(\n `/api/agents${agent.path}/rescan`,\n undefined,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n }, [agent.path, authToken]);\n\n const getSecurityIconState = () => {\n // Gray: no scan result yet\n if (!securityScanResult) {\n return { Icon: ShieldCheckIcon, color: 'text-gray-400 dark:text-gray-500', title: 'View security scan results' };\n }\n // Red: scan failed or any vulnerabilities found\n if (securityScanResult.scan_failed) {\n return { Icon: ShieldExclamationIcon, color: 'text-red-500 dark:text-red-400', title: 'Security scan failed' };\n }\n const hasVulnerabilities = securityScanResult.critical_issues > 0 ||\n securityScanResult.high_severity > 0 ||\n securityScanResult.medium_severity > 0 ||\n securityScanResult.low_severity > 0;\n if (hasVulnerabilities) {\n return { Icon: ShieldExclamationIcon, color: 'text-red-500 dark:text-red-400', title: 'Security issues found' };\n }\n // Green: scan passed with no vulnerabilities\n return { Icon: ShieldCheckIcon, color: 'text-green-500 dark:text-green-400', title: 'Security scan passed' };\n };\n\n return (\n <>\n
\n {showDeleteConfirm ? (\n /* Delete Confirmation - replaces card content when active */\n
\n setShowDeleteConfirm(false)}\n />\n
\n ) : (\n /* Normal card content */\n <>\n {/* Header */}\n
\n
\n
\n
\n

\n {agent.name}\n

\n {agent.lifecycle_status && agent.lifecycle_status !== 'active' && (\n \n )}\n {/* Check if this is an ASOR agent */}\n {(agent.tags?.includes('asor') || (agent as any).provider === 'ASOR') && (\n \n ASOR\n \n )}\n {/* A2A tag badge (for AgentCore imported agents) */}\n {agent.tags?.includes('a2a') && (\n \n A2A\n \n )}\n {/* Supported Protocol Badge */}\n {agent.supported_protocol === 'a2a' && !agent.tags?.includes('a2a') && (\n \n A2A Protocol\n \n )}\n {agent.trust_level && (\n \n {getTrustLevelIcon()}\n {agent.trust_level.toUpperCase()}\n \n )}\n {agent.visibility && (\n \n {getVisibilityIcon()}\n {agent.visibility.toUpperCase()}\n \n )}\n {/* Registry source badge - only show for federated (peer registry) items */}\n {isFederatedAgent && (\n \n {peerRegistryId?.toUpperCase().replace('PEER-REGISTRY-', '').replace('PEER-', '')}\n \n )}\n {/* Orphaned badge - agent no longer exists on peer registry */}\n {isOrphanedAgent && (\n \n ORPHANED\n \n )}\n
\n {/* ANS Verified badge on its own row to avoid overlap */}\n {agent.ans_metadata && (\n
\n \n
\n )}\n\n \n {agent.path}\n \n {agent.version && (\n \n v{agent.version}\n \n )}\n {agent.url && (\n \n {agent.url}\n \n )}\n
\n\n {canModify && (\n onEdit?.(agent)}\n title=\"Edit agent\"\n >\n \n \n )}\n\n {/* Security Scan Button */}\n \n {React.createElement(getSecurityIconState().Icon, { className: \"h-4 w-4\" })}\n \n\n {/* Full Details Button */}\n {\n setShowDetails(true);\n setLoadingDetails(true);\n try {\n const response = await axios.get(`/api/agents${agent.path}`);\n setFullAgentDetails(response.data);\n } catch (error) {\n console.error('Failed to fetch agent details:', error);\n if (onShowToast) {\n onShowToast('Failed to load full agent details', 'error');\n }\n } finally {\n setLoadingDetails(false);\n }\n }}\n className=\"p-2 text-gray-400 hover:text-blue-600 dark:hover:text-blue-300 hover:bg-blue-50 dark:hover:bg-blue-700/50 rounded-lg transition-all duration-200 flex-shrink-0\"\n title=\"View full agent details (JSON)\"\n >\n \n \n\n {/* Delete Button */}\n {canDelete && (\n setShowDeleteConfirm(true)}\n className=\"p-2 text-gray-400 hover:text-red-600 dark:hover:text-red-400 hover:bg-red-50 dark:hover:bg-red-700/50 rounded-lg transition-all duration-200 flex-shrink-0\"\n title=\"Delete agent\"\n aria-label={`Delete ${agent.name}`}\n >\n \n \n )}\n
\n\n {/* Description */}\n

\n {agent.description || 'No description available'}\n

\n\n {/* Tags */}\n {agent.tags && agent.tags.length > 0 && (\n
\n {agent.tags.slice(0, 3).map((tag) => (\n \n #{tag}\n \n ))}\n {agent.tags.length > 3 && (\n \n +{agent.tags.length - 3}\n \n )}\n
\n )}\n
\n\n {/* Stats */}\n
\n {\n // Update local agent rating when user submits rating\n if (onAgentUpdate) {\n onAgentUpdate(agent.path, { rating: newRating });\n }\n }}\n />\n
\n\n {/* Footer */}\n
\n
\n
\n {/* Status Indicators */}\n
\n
\n \n {agent.enabled ? 'Enabled' : 'Disabled'}\n \n
\n\n
\n\n
\n
\n \n {agent.status === 'healthy' ? 'Healthy' :\n agent.status === 'healthy-auth-expired' ? 'Healthy (Auth Expired)' :\n agent.status === 'unhealthy' ? 'Unhealthy' : 'Unknown'}\n \n
\n
\n\n {/* Controls */}\n
\n {/* Last Updated (source timestamp) */}\n {agent.source_updated_at && (\n
\n \n \n {formatRelativeTime(agent.source_updated_at)}\n \n
\n )}\n\n {/* Last Checked */}\n {(() => {\n const timeText = formatTimeSince(agent.last_checked_time);\n return agent.last_checked_time && timeText && !agent.source_updated_at ? (\n
\n \n {timeText}\n
\n ) : null;\n })()}\n\n {/* Refresh Button - only show if user has health_check_agent permission */}\n {canHealthCheck && (\n \n \n \n )}\n\n {/* Toggle Switch - only show if user has toggle_agent permission */}\n {canToggle && (\n
\n
\n \n )}\n
\n\n setShowDetails(false)}\n loading={loadingDetails}\n fullDetails={fullAgentDetails}\n onCopy={handleCopyDetails}\n />\n\n setShowSecurityScan(false)}\n loading={loadingSecurityScan}\n scanResult={securityScanResult}\n onRescan={canModify ? handleRescan : undefined}\n canRescan={canModify}\n onShowToast={onShowToast}\n />\n\n \n );\n});\n\nAgentCard.displayName = 'AgentCard';\n\nexport default AgentCard;\n" }, { "path": "frontend/src/components/AgentDetailsModal.tsx", "content": "import React from 'react';\nimport { ClipboardDocumentIcon } from '@heroicons/react/24/outline';\nimport DetailsModal from './DetailsModal';\n\ninterface AgentLike {\n name: string;\n path: string;\n description?: string;\n version?: string;\n visibility?: string;\n trust_level?: string;\n enabled: boolean;\n tags?: string[];\n}\n\ninterface AgentDetailsModalProps {\n agent: AgentLike & { [key: string]: any };\n isOpen: boolean;\n onClose: () => void;\n loading: boolean;\n fullDetails?: any;\n onCopy?: (data: any) => Promise | void;\n}\n\n/**\n * AgentDetailsModal displays the complete agent JSON schema.\n *\n * Features:\n * - Uses shared DetailsModal component\n * - Copy to clipboard functionality\n * - Field reference documentation\n * - Loading states handled by parent DetailsModal\n */\nconst getAgentCardUrl = (agentUrl: string): string | null => {\n try {\n const origin = new URL(agentUrl).origin;\n return `${origin}/.well-known/agent-card.json`;\n } catch {\n return null;\n }\n};\n\nconst AgentDetailsModal: React.FC = ({\n agent,\n isOpen,\n onClose,\n loading,\n fullDetails,\n onCopy,\n}) => {\n const dataToCopy = fullDetails || agent;\n\n const handleCopy = async () => {\n try {\n if (onCopy) {\n await onCopy(dataToCopy);\n } else {\n await navigator.clipboard.writeText(JSON.stringify(dataToCopy, null, 2));\n }\n } catch (error) {\n console.error('Failed to copy agent JSON:', error);\n }\n };\n\n return (\n \n
\n
\n

Complete Agent Schema

\n

\n This is the complete A2A agent definition stored in the registry. It includes all metadata, skills,\n security schemes, and configuration details.\n

\n
\n\n {/* A2A Agent Card URL for A2A agents */}\n {fullDetails?.supported_protocol === 'a2a' && fullDetails?.url && (() => {\n const cardUrl = getAgentCardUrl(fullDetails.url);\n return cardUrl ? (\n
\n

\n A2A Agent Card:{' '}\n \n {cardUrl}\n \n

\n
\n ) : null;\n })()}\n\n
\n
\n

Agent JSON Schema:

\n \n \n Copy JSON\n \n
\n\n 
\n            {JSON.stringify(dataToCopy, null, 2)}\n
\n
\n\n
\n

Field Reference

\n
\n
\n
Core Fields
\n
    \n
  • \n protocol_version - A2A protocol\n version\n
    • \n
  • \n name - Agent display name\n
    • \n
  • \n description - Agent purpose\n
    • \n
  • \n url - Agent endpoint URL\n
    • \n
  • \n path - Registry path\n
    • \n
\n
\n
\n
Metadata Fields
\n
    \n
  • \n skills - Agent capabilities\n
    • \n
  • \n security_schemes - Auth methods\n
    • \n
  • \n tags - Categorization\n
    • \n
  • \n trust_level - Verification status\n
    • \n
  • \n status - Lifecycle status\n
    • \n
\n
\n
\n
\n
\n \n );\n};\n\nexport default AgentDetailsModal;\n" }, { "path": "frontend/src/components/ApplicationLogs.tsx", "content": "import React, { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\nimport {\n ArrowDownTrayIcon,\n ArrowPathIcon,\n FunnelIcon,\n XMarkIcon,\n ChevronLeftIcon,\n ChevronRightIcon,\n ExclamationTriangleIcon,\n} from '@heroicons/react/24/outline';\n\n\ninterface LogEntry {\n timestamp: string;\n hostname: string;\n service: string;\n level: string;\n logger: string;\n filename: string;\n lineno: number;\n message: string;\n}\n\ninterface LogQueryResponse {\n entries: LogEntry[];\n total_count: number;\n limit: number;\n offset: number;\n has_next: boolean;\n}\n\ninterface LogMetadata {\n services: string[];\n hostnames: string[];\n levels: string[];\n}\n\ninterface LogFilters {\n service: string;\n level: string;\n hostname: string;\n search: string;\n start: string;\n end: string;\n}\n\ninterface ApplicationLogsProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\nconst LEVEL_COLORS: Record = {\n DEBUG: 'bg-gray-100 text-gray-700 dark:bg-gray-700 dark:text-gray-300',\n INFO: 'bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-300',\n WARNING: 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-300',\n ERROR: 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-300',\n CRITICAL: 'bg-red-200 text-red-900 dark:bg-red-900/50 dark:text-red-200',\n};\n\nconst PAGE_SIZE = 50;\n\n\nconst ApplicationLogs: React.FC = ({ onShowToast }) => {\n const [entries, setEntries] = useState([]);\n const [totalCount, setTotalCount] = useState(0);\n const [hasNext, setHasNext] = useState(false);\n const [offset, setOffset] = useState(0);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n const [metadata, setMetadata] = useState(null);\n const [showFilters, setShowFilters] = useState(false);\n const [expandedRow, setExpandedRow] = useState(null);\n const [fetchTrigger, setFetchTrigger] = useState(0);\n const [filters, setFilters] = useState({\n service: '',\n level: '',\n hostname: '',\n search: '',\n start: '',\n end: '',\n });\n\n const _buildParams = useCallback((extraOffset?: number): URLSearchParams => {\n const params = new URLSearchParams();\n params.set('limit', PAGE_SIZE.toString());\n params.set('offset', (extraOffset ?? offset).toString());\n if (filters.service) params.set('service', filters.service);\n if (filters.level) params.set('level', filters.level);\n if (filters.hostname) params.set('hostname', filters.hostname);\n if (filters.search) params.set('search', filters.search);\n if (filters.start) params.set('start', new Date(filters.start).toISOString());\n if (filters.end) params.set('end', new Date(filters.end).toISOString());\n return params;\n }, [filters, offset]);\n\n const _fetchLogs = useCallback(async (currentOffset: number) => {\n setLoading(true);\n setError(null);\n try {\n const params = _buildParams(currentOffset);\n const response = await axios.get(\n `/api/admin/logs?${params.toString()}`\n );\n setEntries(response.data.entries);\n setTotalCount(response.data.total_count);\n setHasNext(response.data.has_next);\n } catch (err: any) {\n if (err.response?.status === 403) {\n setError('Access denied. Admin permissions required.');\n } else if (err.response?.status === 503) {\n setError('Centralized application logging is not enabled. Set APP_LOG_CENTRALIZED_ENABLED=true.');\n } else {\n setError(err.response?.data?.detail || 'Failed to load application logs.');\n }\n } finally {\n setLoading(false);\n }\n }, [_buildParams]);\n\n const _fetchMetadata = useCallback(async () => {\n try {\n const response = await axios.get('/api/admin/logs/metadata');\n setMetadata(response.data);\n } catch {\n // Metadata is optional; silently ignore\n }\n }, []);\n\n useEffect(() => {\n _fetchLogs(offset);\n }, [offset, fetchTrigger, _fetchLogs]);\n\n useEffect(() => {\n _fetchMetadata();\n }, [_fetchMetadata]);\n\n const handleApplyFilters = () => {\n setExpandedRow(null);\n setOffset(0);\n setFetchTrigger((prev) => prev + 1);\n };\n\n const handleClearFilters = () => {\n setFilters({ service: '', level: '', hostname: '', search: '', start: '', end: '' });\n setExpandedRow(null);\n setOffset(0);\n setFetchTrigger((prev) => prev + 1);\n };\n\n const handleExport = useCallback(() => {\n const params = _buildParams(0);\n params.set('limit', '50000');\n params.delete('offset');\n window.open(`/api/admin/logs/export?${params.toString()}`, '_blank');\n onShowToast('Log export started', 'info');\n }, [_buildParams, onShowToast]);\n\n const handleRefresh = () => {\n setExpandedRow(null);\n _fetchLogs(offset);\n };\n\n const handlePrevPage = () => {\n const newOffset = Math.max(0, offset - PAGE_SIZE);\n setOffset(newOffset);\n setExpandedRow(null);\n };\n\n const handleNextPage = () => {\n if (hasNext) {\n setOffset(offset + PAGE_SIZE);\n setExpandedRow(null);\n }\n };\n\n const _activeFilterCount = (): number => {\n let count = 0;\n if (filters.service) count++;\n if (filters.level) count++;\n if (filters.hostname) count++;\n if (filters.search) count++;\n if (filters.start) count++;\n if (filters.end) count++;\n return count;\n };\n\n const _formatTimestamp = (ts: string): string => {\n try {\n const d = new Date(ts);\n return d.toLocaleString(undefined, {\n year: 'numeric',\n month: '2-digit',\n day: '2-digit',\n hour: '2-digit',\n minute: '2-digit',\n second: '2-digit',\n hour12: false,\n });\n } catch {\n return ts;\n }\n };\n\n const _truncateMessage = (msg: string, maxLen: number = 120): string => {\n const firstLine = msg.split('\\n')[0];\n if (firstLine.length <= maxLen) return firstLine;\n return firstLine.substring(0, maxLen) + '...';\n };\n\n const currentPage = Math.floor(offset / PAGE_SIZE) + 1;\n const totalPages = Math.ceil(totalCount / PAGE_SIZE);\n const filterCount = _activeFilterCount();\n\n return (\n
\n {/* Header */}\n
\n
\n

\n Application Logs\n

\n

\n View and download centralized application logs from all services.\n

\n
\n
\n \n \n \n \n \n Download JSONL\n \n
\n
\n\n {/* Filter Toggle */}\n
\n setShowFilters(!showFilters)}\n className={`flex items-center gap-2 px-3 py-2 text-sm font-medium rounded-lg border transition-colors ${\n filterCount > 0\n ? 'text-purple-700 dark:text-purple-300 bg-purple-50 dark:bg-purple-900/20 border-purple-300 dark:border-purple-700'\n : 'text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border-gray-300 dark:border-gray-600 hover:bg-gray-50 dark:hover:bg-gray-600'\n }`}\n >\n \n Filters{filterCount > 0 ? ` (${filterCount})` : ''}\n \n
\n\n {/* Filter Panel */}\n {showFilters && (\n
\n
\n {/* Service */}\n
\n \n setFilters({ ...filters, service: e.target.value })}\n className=\"w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n >\n \n {metadata?.services.map((s) => (\n \n ))}\n \n
\n\n {/* Level */}\n
\n \n setFilters({ ...filters, level: e.target.value })}\n className=\"w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n >\n \n {metadata?.levels.map((l) => (\n \n ))}\n \n
\n\n {/* Hostname */}\n
\n \n setFilters({ ...filters, hostname: e.target.value })}\n className=\"w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n >\n \n {metadata?.hostnames.map((h) => (\n \n ))}\n \n
\n\n {/* Search */}\n
\n \n setFilters({ ...filters, search: e.target.value })}\n onKeyDown={(e) => { if (e.key === 'Enter') handleApplyFilters(); }}\n placeholder=\"e.g. timeout, connection refused\"\n className=\"w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n\n {/* Start time */}\n
\n \n setFilters({ ...filters, start: e.target.value })}\n className=\"w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n\n {/* End time */}\n
\n \n setFilters({ ...filters, end: e.target.value })}\n className=\"w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n
\n\n {/* Filter actions */}\n
\n \n Apply Filters\n \n {filterCount > 0 && (\n \n \n Clear All\n \n )}\n
\n
\n )}\n\n {/* Error State */}\n {error && (\n
\n \n

{error}

\n
\n )}\n\n {/* Summary bar */}\n {!error && (\n
\n \n {totalCount.toLocaleString()} log entries\n {filterCount > 0 && ' (filtered)'}\n \n \n Page {currentPage} of {totalPages || 1}\n \n
\n )}\n\n {/* Log Table */}\n {!error && (\n
\n {loading && entries.length === 0 ? (\n
\n
\n
\n ) : entries.length === 0 ? (\n
\n No log entries found.\n
\n ) : (\n
\n \n \n \n \n \n \n \n \n \n \n \n {entries.map((entry, idx) => (\n \n setExpandedRow(expandedRow === idx ? null : idx)}\n onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setExpandedRow(expandedRow === idx ? null : idx); } }}\n >\n \n \n \n \n \n \n {expandedRow === idx && (\n \n \n \n )}\n \n ))}\n \n
TimestampLevelServiceSourceMessage
\n {_formatTimestamp(entry.timestamp)}\n \n \n {entry.level}\n \n \n {entry.service}\n \n {entry.filename}:{entry.lineno}\n \n {_truncateMessage(entry.message)}\n
\n
\n
\n Hostname: {entry.hostname}\n Logger: {entry.logger}\n
\n 
\n                                {entry.message}\n
\n
\n
\n
\n )}\n\n {/* Pagination */}\n {entries.length > 0 && (\n
\n
\n Showing {offset + 1}-{Math.min(offset + entries.length, totalCount)} of {totalCount.toLocaleString()}\n
\n
\n \n \n \n \n {currentPage} / {totalPages}\n \n \n \n \n
\n
\n )}\n
\n )}\n
\n );\n};\n\nexport default ApplicationLogs;\n" }, { "path": "frontend/src/components/AuditEventDetail.tsx", "content": "import React, { useState } from 'react';\nimport {\n XMarkIcon,\n ClipboardDocumentIcon,\n CheckIcon,\n} from '@heroicons/react/24/outline';\nimport { AuditEvent } from './AuditLogTable';\n\ninterface AuditEventDetailProps {\n event: AuditEvent;\n onClose: () => void;\n}\n\nconst AuditEventDetail: React.FC = ({ event, onClose }) => {\n const [copied, setCopied] = useState(false);\n\n const isMcpEvent = event.log_type === 'mcp_server_access';\n\n const handleCopy = async () => {\n try {\n await navigator.clipboard.writeText(JSON.stringify(event, null, 2));\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n } catch (err) {\n console.error('Failed to copy to clipboard:', err);\n }\n };\n\n const formatJson = (obj: unknown): string => {\n return JSON.stringify(obj, null, 2);\n };\n\n const getStatusColor = (statusCode: number): string => {\n if (statusCode >= 200 && statusCode < 300) return 'text-green-600 dark:text-green-400';\n if (statusCode >= 400 && statusCode < 500) return 'text-yellow-600 dark:text-yellow-400';\n if (statusCode >= 500) return 'text-red-600 dark:text-red-400';\n return 'text-gray-600 dark:text-gray-400';\n };\n\n const getMcpStatusColor = (status: string): string => {\n switch (status?.toLowerCase()) {\n case 'success':\n return 'text-green-600 dark:text-green-400';\n case 'error':\n return 'text-red-600 dark:text-red-400';\n case 'timeout':\n return 'text-yellow-600 dark:text-yellow-400';\n default:\n return 'text-gray-600 dark:text-gray-400';\n }\n };\n\n return (\n
\n {/* Header */}\n
\n
\n

\n Event Details\n

\n \n {event.request_id}\n \n
\n
\n \n {copied ? (\n <>\n \n Copied!\n \n ) : (\n <>\n \n Copy JSON\n \n )}\n \n \n \n \n
\n
\n\n {/* Summary */}\n
\n
\n
\n Timestamp\n
\n
\n {new Date(event.timestamp).toLocaleString()}\n
\n
\n
\n
\n User\n
\n
\n \n {event.identity.username}\n \n {event.identity.is_admin && (\n \n Admin\n \n )}\n
\n
\n
\n
\n Status\n
\n {isMcpEvent ? (\n
\n {event.mcp_response?.status || '-'}\n
\n ) : (\n
\n {event.response?.status_code || '-'}\n
\n )}\n
\n
\n
\n Duration\n
\n
\n {isMcpEvent\n ? `${(event.mcp_response?.duration_ms || 0).toFixed(2)} ms`\n : `${(event.response?.duration_ms || 0).toFixed(2)} ms`\n }\n
\n
\n
\n\n {/* MCP-specific summary row */}\n {isMcpEvent && (\n
\n
\n
\n Server\n
\n \n {event.mcp_server?.name || '-'}\n
\n
\n
\n
\n Method\n
\n \n {event.mcp_request?.method || '-'}\n
\n
\n
\n
\n Tool\n
\n \n {event.mcp_request?.tool_name || event.mcp_request?.resource_uri || '-'}\n
\n
\n
\n
\n Transport\n
\n \n {event.mcp_request?.transport || '-'}\n
\n
\n
\n )}\n\n {/* JSON Content */}\n
\n 
\n          {formatJson(event)}\n
\n
\n
\n );\n};\n\nexport default AuditEventDetail;\n" }, { "path": "frontend/src/components/AuditFilterBar.tsx", "content": "import React, { useState, useEffect, useRef } from 'react';\nimport SearchableSelect, { SelectOption } from './SearchableSelect';\nimport axios from 'axios';\nimport {\n FunnelIcon,\n XMarkIcon,\n ArrowPathIcon,\n} from '@heroicons/react/24/outline';\n\nexport interface AuditFilters {\n stream: 'registry_api' | 'mcp_access';\n from?: string;\n to?: string;\n username?: string;\n operation?: string;\n resourceType?: string;\n statusMin?: number;\n statusMax?: number;\n}\n\ninterface AuditFilterBarProps {\n filters: AuditFilters;\n onFilterChange: (filters: AuditFilters) => void;\n onRefresh?: () => void;\n loading?: boolean;\n}\n\nconst REGISTRY_OPERATION_OPTIONS = [\n { value: '', label: 'All Operations' },\n { value: 'create', label: 'Create' },\n { value: 'read', label: 'Read' },\n { value: 'update', label: 'Update' },\n { value: 'delete', label: 'Delete' },\n { value: 'list', label: 'List' },\n { value: 'toggle', label: 'Toggle' },\n { value: 'rate', label: 'Rate' },\n { value: 'login', label: 'Login' },\n { value: 'logout', label: 'Logout' },\n { value: 'search', label: 'Search' },\n];\n\nconst MCP_OPERATION_OPTIONS = [\n { value: '', label: 'All Methods' },\n { value: 'initialize', label: 'Initialize' },\n { value: 'tools/list', label: 'Tools List' },\n { value: 'tools/call', label: 'Tools Call' },\n { value: 'resources/list', label: 'Resources List' },\n { value: 'resources/templates/list', label: 'Resource Templates' },\n { value: 'notifications/initialized', label: 'Notifications' },\n];\n\nconst REGISTRY_RESOURCE_TYPE_OPTIONS = [\n { value: '', label: 'All Resources' },\n { value: 'server', label: 'Server' },\n { value: 'agent', label: 'Agent' },\n { value: 'auth', label: 'Auth' },\n { value: 'federation', label: 'Federation' },\n { value: 'health', label: 'Health' },\n { value: 'search', label: 'Search' },\n];\n\nconst MCP_RESOURCE_TYPE_OPTIONS = [\n { value: '', label: 'All Servers' },\n];\n\nconst STATUS_PRESETS = [\n { value: '', label: 'All Status Codes' },\n { value: '2xx', label: '2xx Success' },\n { value: '4xx', label: '4xx Client Error' },\n { value: '5xx', label: '5xx Server Error' },\n { value: 'error', label: 'All Errors (4xx & 5xx)' },\n];\n\ninterface FilterOptionsCache {\n registry_api?: { usernames: SelectOption[]; serverNames: SelectOption[] };\n mcp_access?: { usernames: SelectOption[]; serverNames: SelectOption[] };\n}\n\nconst AuditFilterBar: React.FC = ({\n filters,\n onFilterChange,\n onRefresh,\n loading = false,\n}) => {\n const isMcpStream = filters.stream === 'mcp_access';\n const operationOptions = isMcpStream ? MCP_OPERATION_OPTIONS : REGISTRY_OPERATION_OPTIONS;\n const resourceTypeOptions = isMcpStream ? MCP_RESOURCE_TYPE_OPTIONS : REGISTRY_RESOURCE_TYPE_OPTIONS;\n\n const [usernameOptions, setUsernameOptions] = useState([]);\n const [serverNameOptions, setServerNameOptions] = useState([]);\n const [optionsLoading, setOptionsLoading] = useState(false);\n const optionsCacheRef = useRef({});\n\n // Prefetch both streams' filter options on mount\n useEffect(() => {\n const fetchAllOptions = async () => {\n setOptionsLoading(true);\n try {\n const [registryRes, mcpRes] = await Promise.all([\n axios.get('/api/audit/filter-options', { params: { stream: 'registry_api' } }),\n axios.get('/api/audit/filter-options', { params: { stream: 'mcp_access' } }),\n ]);\n\n optionsCacheRef.current = {\n registry_api: {\n usernames: registryRes.data.usernames.map((u: string) => ({ value: u, label: u })),\n serverNames: [],\n },\n mcp_access: {\n usernames: mcpRes.data.usernames.map((u: string) => ({ value: u, label: u })),\n serverNames: mcpRes.data.server_names.map((s: string) => ({ value: s, label: s })),\n },\n };\n\n // Set current stream's options\n const current = optionsCacheRef.current[filters.stream];\n if (current) {\n setUsernameOptions(current.usernames);\n setServerNameOptions(current.serverNames);\n }\n } catch (error) {\n console.error('Failed to fetch filter options:', error);\n } finally {\n setOptionsLoading(false);\n }\n };\n fetchAllOptions();\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, []);\n\n // When stream changes, serve from cache\n useEffect(() => {\n const cached = optionsCacheRef.current[filters.stream];\n if (cached) {\n setUsernameOptions(cached.usernames);\n setServerNameOptions(cached.serverNames);\n }\n }, [filters.stream]);\n\n const handleStreamChange = (e: React.ChangeEvent) => {\n // Clear operation and resource type filters when switching streams\n onFilterChange({\n ...filters,\n stream: e.target.value as 'registry_api' | 'mcp_access',\n operation: undefined,\n resourceType: undefined,\n });\n };\n\n const handleFromChange = (e: React.ChangeEvent) => {\n onFilterChange({\n ...filters,\n from: e.target.value || undefined,\n });\n };\n\n const handleToChange = (e: React.ChangeEvent) => {\n onFilterChange({\n ...filters,\n to: e.target.value || undefined,\n });\n };\n\n const handleUsernameSelect = (value: string) => {\n onFilterChange({\n ...filters,\n username: value || undefined,\n });\n };\n\n const handleOperationChange = (e: React.ChangeEvent) => {\n onFilterChange({\n ...filters,\n operation: e.target.value || undefined,\n });\n };\n\n const handleResourceTypeChange = (e: React.ChangeEvent) => {\n onFilterChange({\n ...filters,\n resourceType: e.target.value || undefined,\n });\n };\n\n const handleServerNameSelect = (value: string) => {\n onFilterChange({\n ...filters,\n resourceType: value || undefined,\n });\n };\n\n const handleStatusPresetChange = (e: React.ChangeEvent) => {\n const value = e.target.value;\n let statusMin: number | undefined;\n let statusMax: number | undefined;\n\n switch (value) {\n case '2xx':\n statusMin = 200;\n statusMax = 299;\n break;\n case '4xx':\n statusMin = 400;\n statusMax = 499;\n break;\n case '5xx':\n statusMin = 500;\n statusMax = 599;\n break;\n case 'error':\n statusMin = 400;\n statusMax = 599;\n break;\n default:\n statusMin = undefined;\n statusMax = undefined;\n }\n\n onFilterChange({\n ...filters,\n statusMin,\n statusMax,\n });\n };\n\n const getStatusPresetValue = (): string => {\n const { statusMin, statusMax } = filters;\n if (statusMin === 200 && statusMax === 299) return '2xx';\n if (statusMin === 400 && statusMax === 499) return '4xx';\n if (statusMin === 500 && statusMax === 599) return '5xx';\n if (statusMin === 400 && statusMax === 599) return 'error';\n return '';\n };\n\n const handleClearFilters = () => {\n onFilterChange({\n stream: filters.stream,\n from: undefined,\n to: undefined,\n username: undefined,\n operation: undefined,\n resourceType: undefined,\n statusMin: undefined,\n statusMax: undefined,\n });\n };\n\n const hasActiveFilters = !!(\n filters.from ||\n filters.to ||\n filters.username ||\n filters.operation ||\n filters.resourceType ||\n filters.statusMin ||\n filters.statusMax\n );\n\n return (\n
\n
\n \n

\n Filters\n

\n {hasActiveFilters && (\n \n \n Clear filters\n \n )}\n {onRefresh && (\n \n \n \n )}\n
\n\n
\n {/* Stream Selector */}\n
\n \n \n \n \n \n
\n\n {/* Date Range - From */}\n
\n \n \n
\n\n {/* Date Range - To */}\n
\n \n \n
\n\n {/* Username Filter */}\n
\n \n \n
\n\n {/* Operation / MCP Method Filter */}\n
\n \n \n {operationOptions.map((opt) => (\n \n ))}\n \n
\n\n {/* Resource Type / Server Name Filter */}\n
\n \n {isMcpStream ? (\n \n ) : (\n \n {resourceTypeOptions.map((opt) => (\n \n ))}\n \n )}\n
\n\n {/* Status Code Range Filter */}\n
\n \n \n {STATUS_PRESETS.map((opt) => (\n \n ))}\n \n
\n
\n
\n );\n};\n\nexport default AuditFilterBar;\n" }, { "path": "frontend/src/components/AuditLogTable.tsx", "content": "import React, { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\nimport {\n ChevronLeftIcon,\n ChevronRightIcon,\n ChevronDoubleLeftIcon,\n ChevronDoubleRightIcon,\n ChevronDownIcon,\n ChevronUpIcon,\n ExclamationTriangleIcon,\n} from '@heroicons/react/24/outline';\nimport { AuditFilters } from './AuditFilterBar';\n\nexport interface AuditEvent {\n _id?: string;\n timestamp: string;\n request_id: string;\n log_type: string;\n version?: string;\n correlation_id?: string;\n identity: {\n username: string;\n auth_method: string;\n provider?: string;\n groups?: string[];\n scopes?: string[];\n is_admin: boolean;\n credential_type: string;\n credential_hint?: string;\n };\n request?: {\n method: string;\n path: string;\n query_params?: Record;\n client_ip: string;\n forwarded_for?: string;\n user_agent?: string;\n content_length?: number;\n };\n response?: {\n status_code: number;\n duration_ms: number;\n content_length?: number;\n };\n action?: {\n operation: string;\n resource_type: string;\n resource_id?: string;\n description?: string;\n };\n authorization?: {\n decision: string;\n required_permission?: string;\n evaluated_scopes?: string[];\n };\n // MCP-specific fields\n mcp_server?: {\n name: string;\n path: string;\n version?: string;\n proxy_target: string;\n };\n mcp_request?: {\n method: string;\n tool_name?: string;\n resource_uri?: string;\n mcp_session_id?: string;\n transport: string;\n jsonrpc_id?: string;\n };\n mcp_response?: {\n status: string;\n duration_ms: number;\n error_code?: number;\n error_message?: string;\n };\n}\n\ninterface AuditLogTableProps {\n filters: AuditFilters;\n onEventSelect?: (event: AuditEvent) => void;\n selectedEventId?: string;\n}\n\ninterface PaginationState {\n total: number;\n limit: number;\n offset: number;\n}\n\nconst getStatusColor = (statusCode: number): string => {\n if (statusCode >= 200 && statusCode < 300) {\n return 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400';\n }\n if (statusCode >= 300 && statusCode < 400) {\n return 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400';\n }\n if (statusCode >= 400 && statusCode < 500) {\n return 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400';\n }\n if (statusCode >= 500) {\n return 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400';\n }\n return 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300';\n};\n\nconst getMethodColor = (method: string): string => {\n switch (method.toUpperCase()) {\n case 'GET':\n return 'text-blue-600 dark:text-blue-400';\n case 'POST':\n return 'text-green-600 dark:text-green-400';\n case 'PUT':\n case 'PATCH':\n return 'text-yellow-600 dark:text-yellow-400';\n case 'DELETE':\n return 'text-red-600 dark:text-red-400';\n default:\n return 'text-gray-600 dark:text-gray-400';\n }\n};\n\nconst getMcpStatusColor = (status: string): string => {\n switch (status.toLowerCase()) {\n case 'success':\n return 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400';\n case 'error':\n return 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400';\n case 'timeout':\n return 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400';\n default:\n return 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300';\n }\n};\n\nconst formatTimestamp = (timestamp: string): string => {\n try {\n const date = new Date(timestamp);\n return date.toLocaleString(undefined, {\n year: 'numeric',\n month: 'short',\n day: '2-digit',\n hour: '2-digit',\n minute: '2-digit',\n second: '2-digit',\n });\n } catch {\n return timestamp;\n }\n};\n\nconst AuditLogTable: React.FC = ({\n filters,\n onEventSelect,\n selectedEventId,\n}) => {\n const [events, setEvents] = useState([]);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n const [pagination, setPagination] = useState({\n total: 0,\n limit: 50,\n offset: 0,\n });\n // Sort order: -1 = descending (newest first), 1 = ascending (oldest first)\n const [sortOrder, setSortOrder] = useState<-1 | 1>(-1);\n\n const fetchEvents = useCallback(async (offset: number = 0, currentSortOrder: -1 | 1 = sortOrder) => {\n setLoading(true);\n setError(null);\n\n try {\n const params = new URLSearchParams();\n params.set('stream', filters.stream);\n params.set('limit', pagination.limit.toString());\n params.set('offset', offset.toString());\n params.set('sort_order', currentSortOrder.toString());\n\n if (filters.from) {\n params.set('from', new Date(filters.from).toISOString());\n }\n if (filters.to) {\n params.set('to', new Date(filters.to).toISOString());\n }\n if (filters.username) {\n params.set('username', filters.username);\n }\n if (filters.operation) {\n params.set('operation', filters.operation);\n }\n if (filters.resourceType) {\n params.set('resource_type', filters.resourceType);\n }\n if (filters.statusMin !== undefined) {\n params.set('status_min', filters.statusMin.toString());\n }\n if (filters.statusMax !== undefined) {\n params.set('status_max', filters.statusMax.toString());\n }\n\n const response = await axios.get(`/api/audit/events?${params.toString()}`);\n const data = response.data;\n\n setEvents(data.events || []);\n setPagination({\n total: data.total || 0,\n limit: data.limit || 50,\n offset: data.offset || 0,\n });\n } catch (err: any) {\n console.error('Failed to fetch audit events:', err);\n if (err.response?.status === 403) {\n setError('Access denied. Admin permissions required.');\n } else {\n setError(err.response?.data?.detail || 'Failed to load audit events');\n }\n setEvents([]);\n } finally {\n setLoading(false);\n }\n }, [filters, pagination.limit, sortOrder]);\n\n useEffect(() => {\n fetchEvents(0, sortOrder);\n }, [filters, sortOrder]); // eslint-disable-line react-hooks/exhaustive-deps\n\n const handlePageChange = (newOffset: number) => {\n fetchEvents(newOffset, sortOrder);\n };\n\n const handleSortToggle = () => {\n const newSortOrder = sortOrder === -1 ? 1 : -1;\n setSortOrder(newSortOrder);\n };\n\n const totalPages = Math.ceil(pagination.total / pagination.limit);\n const currentPage = Math.floor(pagination.offset / pagination.limit) + 1;\n\n const handleFirstPage = () => handlePageChange(0);\n const handlePrevPage = () => handlePageChange(Math.max(0, pagination.offset - pagination.limit));\n const handleNextPage = () => handlePageChange(pagination.offset + pagination.limit);\n const handleLastPage = () => handlePageChange((totalPages - 1) * pagination.limit);\n\n const isMcpStream = filters.stream === 'mcp_access';\n\n if (error) {\n return (\n
\n
\n \n {error}\n
\n
\n );\n }\n\n return (\n
\n {/* Table */}\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n {loading ? (\n \n \n \n ) : events.length === 0 ? (\n \n \n \n ) : (\n events.map((event) => (\n onEventSelect?.(event)}\n className={`cursor-pointer transition-colors ${\n selectedEventId === event.request_id\n ? 'bg-blue-50 dark:bg-blue-900/20'\n : 'hover:bg-gray-50 dark:hover:bg-gray-700/50'\n }`}\n >\n \n \n \n \n \n \n \n \n ))\n )}\n \n
\n \n Timestamp\n {sortOrder === -1 ? (\n \n ) : (\n \n )}\n \n \n User\n \n {isMcpStream ? 'MCP Method' : 'Method'}\n \n {isMcpStream ? 'Tool/Resource' : 'Operation'}\n \n {isMcpStream ? 'MCP Server' : 'Resource'}\n \n Status\n \n Duration\n
\n
\n
\n Loading events...\n
\n
\n No audit events found matching the current filters.\n
\n {formatTimestamp(event.timestamp)}\n \n
\n \n {event.identity.username}\n \n {event.identity.is_admin && (\n \n Admin\n \n )}\n
\n 		\n {isMcpStream ? (\n \n {event.mcp_request?.method || '-'}\n \n ) : (\n \n {event.request?.method || '-'}\n \n )}\n \n {isMcpStream ? (\n event.mcp_request?.tool_name || event.mcp_request?.resource_uri || '-'\n ) : (\n event.action?.operation || '-'\n )}\n \n {isMcpStream ? (\n event.mcp_server?.name || '-'\n ) : event.action ? (\n \n {event.action.resource_type}\n {event.action.resource_id && (\n \n /{event.action.resource_id}\n \n )}\n \n ) : (\n -\n )}\n \n {isMcpStream ? (\n \n {event.mcp_response?.status || '-'}\n \n ) : (\n \n {event.response?.status_code || '-'}\n \n )}\n \n {isMcpStream\n ? `${(event.mcp_response?.duration_ms || 0).toFixed(1)} ms`\n : `${(event.response?.duration_ms || 0).toFixed(1)} ms`\n }\n
\n
\n\n {/* Pagination */}\n {!loading && events.length > 0 && (\n
\n
\n
\n Showing{' '}\n {pagination.offset + 1}\n {' '}-{' '}\n \n {Math.min(pagination.offset + pagination.limit, pagination.total)}\n \n {' '}of{' '}\n {pagination.total}\n {' '}events\n
\n
\n \n \n \n \n \n \n \n Page {currentPage} of {totalPages}\n \n \n \n \n \n \n \n
\n
\n
\n )}\n
\n );\n};\n\nexport default AuditLogTable;\n" }, { "path": "frontend/src/components/AuditStatistics.tsx", "content": "import React, { useState, useEffect, useCallback, useRef } from 'react';\nimport axios from 'axios';\nimport {\n ChartBarIcon,\n ChevronDownIcon,\n ChevronRightIcon,\n ArrowPathIcon,\n} from '@heroicons/react/24/outline';\n\ninterface UsageSummaryItem {\n name: string;\n count: number;\n}\n\ninterface TimeSeriesBucket {\n period: string;\n count: number;\n}\n\ninterface StatusDistribution {\n status_2xx: number;\n status_4xx: number;\n status_5xx: number;\n}\n\ninterface UserActivityItem {\n username: string;\n total: number;\n operations: UsageSummaryItem[];\n}\n\ninterface AuditStatisticsData {\n total_events: number;\n top_users: UsageSummaryItem[];\n top_servers: UsageSummaryItem[];\n top_operations: UsageSummaryItem[];\n activity_timeline: TimeSeriesBucket[];\n status_distribution: StatusDistribution;\n user_activity: UserActivityItem[];\n}\n\ninterface AuditStatisticsProps {\n stream: 'registry_api' | 'mcp_access';\n days?: number;\n username?: string;\n}\n\nconst STORAGE_KEY = 'audit-statistics-collapsed';\n\nconst BarChart: React.FC<{\n items: UsageSummaryItem[];\n color: string;\n emptyMessage?: string;\n}> = ({ items, color, emptyMessage = 'No data available' }) => {\n if (!items.length) {\n return

{emptyMessage}

;\n }\n\n const maxCount = Math.max(...items.map((i) => i.count));\n\n return (\n
\n {items.map((item) => (\n
\n \n {item.name}\n \n
\n \n
\n \n {item.count.toLocaleString()}\n \n
\n ))}\n
\n );\n};\n\nconst StatusBar: React.FC<{ distribution: StatusDistribution }> = ({ distribution }) => {\n const total = distribution.status_2xx + distribution.status_4xx + distribution.status_5xx;\n if (total === 0) {\n return

No data available

;\n }\n\n const segments = [\n { label: '2xx', count: distribution.status_2xx, color: 'bg-green-500', textColor: 'text-green-600 dark:text-green-400' },\n { label: '4xx', count: distribution.status_4xx, color: 'bg-yellow-500', textColor: 'text-yellow-600 dark:text-yellow-400' },\n { label: '5xx', count: distribution.status_5xx, color: 'bg-red-500', textColor: 'text-red-600 dark:text-red-400' },\n ];\n\n return (\n
\n {/* Stacked bar */}\n
\n {segments.map((seg) =>\n seg.count > 0 ? (\n \n ) : null\n )}\n
\n {/* Legend */}\n
\n {segments.map((seg) => (\n
\n
\n \n {seg.label}: {seg.count.toLocaleString()} ({total > 0 ? ((seg.count / total) * 100).toFixed(1) : 0}%)\n \n
\n ))}\n
\n
\n );\n};\n\nconst WEEKDAY_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];\n\n/**\n * Fill in missing days so every day in the range has an entry.\n * The API only returns days with events, so days with 0 events are missing.\n */\nfunction _fillTimelineDays(timeline: TimeSeriesBucket[], days: number): TimeSeriesBucket[] {\n const countByDate = new Map(timeline.map((t) => [t.period, t.count]));\n const filled: TimeSeriesBucket[] = [];\n const now = new Date();\n\n for (let i = days - 1; i >= 0; i--) {\n const d = new Date(now);\n d.setDate(d.getDate() - i);\n const key = d.toISOString().slice(0, 10);\n filled.push({ period: key, count: countByDate.get(key) || 0 });\n }\n\n return filled;\n}\n\nfunction _formatDateLabel(period: string): string {\n const d = new Date(period + 'T00:00:00');\n const weekday = WEEKDAY_NAMES[d.getDay()];\n const month = String(d.getMonth() + 1).padStart(2, '0');\n const day = String(d.getDate()).padStart(2, '0');\n return `${weekday} ${month}/${day}`;\n}\n\nconst VB_W = 600;\nconst VB_H = 180;\nconst PAD = { top: 20, right: 50, bottom: 32, left: 45 };\n\nconst TimelineChart: React.FC<{ timeline: TimeSeriesBucket[]; days: number }> = ({ timeline, days }) => {\n const [hoverIndex, setHoverIndex] = useState(null);\n const filled = _fillTimelineDays(timeline, days);\n const maxCount = Math.max(...filled.map((t) => t.count), 1);\n\n if (!filled.length) {\n return

No data available

;\n }\n\n const plotW = VB_W - PAD.left - PAD.right;\n const plotH = VB_H - PAD.top - PAD.bottom;\n\n const points = filled.map((b, i) => {\n const x = PAD.left + (filled.length > 1 ? (i / (filled.length - 1)) * plotW : plotW / 2);\n const y = PAD.top + plotH - (b.count / maxCount) * plotH;\n return { x, y, ...b };\n });\n\n const linePath = points.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ');\n const areaPath = `${linePath} L${points[points.length - 1].x},${PAD.top + plotH} L${points[0].x},${PAD.top + plotH} Z`;\n\n const gridValues = [0, Math.round(maxCount / 2), maxCount];\n const gridLines = gridValues.map((v) => ({\n y: PAD.top + plotH - (v / maxCount) * plotH,\n label: v >= 1000 ? `${(v / 1000).toFixed(1)}k` : String(v),\n }));\n\n return (\n
\n \n {/* Horizontal grid lines + Y-axis labels */}\n {gridLines.map((g, i) => (\n \n \n \n {g.label}\n \n \n ))}\n\n {/* Area fill */}\n \n\n {/* Line */}\n \n\n {/* Data points */}\n {points.map((p, i) => (\n 0 ? 3.5 : 2)}\n className={\n p.count > 0\n ? 'fill-blue-500 dark:fill-blue-400'\n : 'fill-gray-300 dark:fill-gray-600'\n }\n stroke=\"white\"\n strokeWidth=\"1.5\"\n />\n ))}\n\n {/* Hover tooltip */}\n {hoverIndex !== null && points[hoverIndex] && (() => {\n const hp = points[hoverIndex];\n const label = `${hp.count.toLocaleString()} events`;\n const boxW = label.length * 7 + 16;\n const boxH = 22;\n const boxX = Math.max(4, Math.min(hp.x - boxW / 2, VB_W - boxW - 4));\n const boxY = Math.max(2, hp.y - boxH - 10);\n return (\n \n \n \n \n {label}\n \n \n );\n })()}\n\n {/* Invisible hit areas for hover */}\n {points.map((p, i) => (\n setHoverIndex(i)}\n onMouseLeave={() => setHoverIndex(null)}\n />\n ))}\n\n {/* X-axis labels */}\n {points.map((p) => (\n \n {_formatDateLabel(p.period)}\n \n ))}\n \n
\n );\n};\n\nconst UserActivityTable: React.FC<{ items: UserActivityItem[] }> = ({ items }) => {\n if (!items.length) {\n return

No user activity data

;\n }\n\n return (\n
\n \n \n \n \n \n \n \n \n \n {items.map((item) => (\n \n \n \n \n \n ))}\n \n
UserTotalTop Operations
\n {item.username}\n \n {item.total.toLocaleString()}\n \n
\n {item.operations.slice(0, 3).map((op) => (\n \n {op.name}\n ({op.count})\n \n ))}\n
\n
\n
\n );\n};\n\nconst AuditStatistics: React.FC = ({ stream, days = 7, username }) => {\n const [data, setData] = useState(null);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n const [collapsed, setCollapsed] = useState(() => {\n try {\n const stored = localStorage.getItem(STORAGE_KEY);\n return stored === null ? true : stored === 'true';\n } catch {\n return true;\n }\n });\n\n const debounceRef = useRef | null>(null);\n\n const fetchStatistics = useCallback(async (currentStream: string, currentDays: number, currentUsername?: string) => {\n setLoading(true);\n setError(null);\n try {\n const params: Record = { stream: currentStream, days: currentDays };\n if (currentUsername) {\n params.username = currentUsername;\n }\n const res = await axios.get('/api/audit/statistics', { params });\n setData(res.data);\n } catch (err) {\n console.error('Failed to fetch audit statistics:', err);\n setError('Failed to load statistics');\n } finally {\n setLoading(false);\n }\n }, []);\n\n // Debounced fetch when stream, days, or username change\n useEffect(() => {\n if (collapsed) return;\n\n if (debounceRef.current) {\n clearTimeout(debounceRef.current);\n }\n\n debounceRef.current = setTimeout(() => {\n fetchStatistics(stream, days, username);\n }, 300);\n\n return () => {\n if (debounceRef.current) {\n clearTimeout(debounceRef.current);\n }\n };\n }, [stream, days, username, collapsed, fetchStatistics]);\n\n const toggleCollapsed = () => {\n const next = !collapsed;\n setCollapsed(next);\n try {\n localStorage.setItem(STORAGE_KEY, String(next));\n } catch {\n // Ignore localStorage errors\n }\n };\n\n const handleRefresh = () => {\n fetchStatistics(stream, days, username);\n };\n\n const isMcpStream = stream === 'mcp_access';\n\n return (\n
\n {/* Header */}\n \n
\n {collapsed ? (\n \n ) : (\n \n )}\n \n

\n Statistics\n

\n {data && !collapsed && (\n \n {data.total_events.toLocaleString()} events (last {days} days){username ? ` - filtered by \"${username}\"` : ''}\n \n )}\n
\n {!collapsed && (\n {\n e.stopPropagation();\n handleRefresh();\n }}\n disabled={loading}\n className=\"p-1.5 text-gray-500 hover:text-blue-600 dark:text-gray-400 dark:hover:text-blue-400 hover:bg-blue-50 dark:hover:bg-blue-900/20 rounded transition-colors disabled:opacity-50\"\n title=\"Refresh statistics\"\n >\n \n \n )}\n
\n\n {/* Content */}\n {!collapsed && (\n
\n {loading && !data ? (\n
\n \n Loading statistics...\n
\n ) : error ? (\n
\n

{error}

\n \n Retry\n \n
\n ) : data ? (\n
\n {/* Top Users */}\n
\n

\n Top Users\n

\n u.name !== 'anonymous')}\n color=\"bg-blue-500\"\n emptyMessage=\"No user data\"\n />\n {(() => {\n const anon = data.top_users.find((u) => u.name === 'anonymous');\n return anon ? (\n

\n + {anon.count.toLocaleString()} anonymous events (unauthenticated API calls, health checks, login attempts)\n

\n ) : null;\n })()}\n
\n\n {/* Top Operations */}\n
\n

\n {isMcpStream ? 'Top MCP Methods' : 'Top Operations'}\n

\n \n
\n\n {/* Top MCP Servers (MCP stream only) */}\n {isMcpStream && (\n
\n

\n Top MCP Servers\n

\n \n
\n )}\n\n {/* Status Distribution */}\n
\n

\n Status Distribution\n

\n \n
\n\n {/* User Activity + Activity Timeline - split panel */}\n
\n
\n {/* Left: User Activity Table */}\n
\n

\n User Activity Breakdown\n

\n \n
\n {/* Right: Activity Timeline */}\n
\n

\n Activity Timeline (Last {days} Days)\n

\n \n
\n
\n
\n
\n ) : null}\n
\n )}\n
\n );\n};\n\nexport default AuditStatistics;\n" }, { "path": "frontend/src/components/ConfigPanel.tsx", "content": "import React, { useState, useEffect, useMemo, useCallback } from 'react';\nimport axios from 'axios';\nimport {\n MagnifyingGlassIcon,\n ArrowPathIcon,\n ClipboardIcon,\n ChevronDownIcon,\n ChevronRightIcon,\n ArrowDownTrayIcon,\n XMarkIcon,\n CheckIcon,\n ExclamationCircleIcon,\n} from '@heroicons/react/24/outline';\n\n/* ------------------------------------------------------------------ */\n/* Types */\n/* ------------------------------------------------------------------ */\n\ninterface ConfigField {\n key: string;\n label: string;\n value: string;\n raw_value: string | null;\n is_masked: boolean;\n unit: string | null;\n}\n\ninterface ConfigSubgroup {\n id: string;\n title: string;\n fields: ConfigField[];\n}\n\ninterface ConfigGroup {\n id: string;\n title: string;\n order: number;\n fields: ConfigField[];\n subgroups?: ConfigSubgroup[];\n}\n\ninterface ConfigResponse {\n groups: ConfigGroup[];\n total_groups: number;\n is_local_dev: boolean;\n}\n\ntype ExportFormat = 'env' | 'json' | 'tfvars' | 'yaml';\n\ninterface ConfigPanelProps {\n onError?: (error: string) => void;\n showToast?: (message: string, type: 'success' | 'error') => void;\n}\n\n/* ------------------------------------------------------------------ */\n/* Helpers */\n/* ------------------------------------------------------------------ */\n\nconst EXPORT_OPTIONS: { format: ExportFormat; label: string }[] = [\n { format: 'env', label: '.env' },\n { format: 'json', label: 'JSON' },\n { format: 'tfvars', label: 'Terraform (.tfvars)' },\n { format: 'yaml', label: 'YAML' },\n];\n\nconst DEFAULT_EXPANDED: Set = new Set(['deployment', 'storage']);\n\n/**\n * Highlight occurrences of `term` inside `text` using tags.\n */\nfunction highlightMatch(text: string, term: string): React.ReactNode {\n if (!term) return text;\n const idx = text.toLowerCase().indexOf(term.toLowerCase());\n if (idx === -1) return text;\n return (\n <>\n {text.slice(0, idx)}\n {text.slice(idx, idx + term.length)}\n {text.slice(idx + term.length)}\n \n );\n}\n\n/* ------------------------------------------------------------------ */\n/* ConfigGroupPanel sub-component */\n/* ------------------------------------------------------------------ */\n\ninterface ConfigGroupPanelProps {\n group: ConfigGroup;\n expanded: boolean;\n onToggle: () => void;\n searchTerm: string;\n copiedKey: string | null;\n onCopy: (key: string, value: string) => void;\n}\n\n/**\n * Render a single field row (reused in top-level fields and subgroups).\n */\nconst FieldRow: React.FC<{\n field: ConfigField;\n searchTerm: string;\n copiedKey: string | null;\n onCopy: (key: string, value: string) => void;\n}> = ({ field, searchTerm, copiedKey, onCopy }) => (\n \n
\n
\n {highlightMatch(field.key, searchTerm)}\n
\n
\n {highlightMatch(field.label, searchTerm)}\n
\n
\n
\n \n {highlightMatch(field.value, searchTerm)}\n {field.unit && !field.is_masked && (\n \n {field.unit}\n \n )}\n \n {!field.is_masked && field.raw_value !== null && (\n onCopy(field.key, String(field.raw_value))}\n className=\"p-1 rounded hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors\"\n aria-label={`Copy ${field.label} value`}\n title=\"Copy value\"\n >\n {copiedKey === field.key ? (\n \n ) : (\n \n )}\n \n )}\n
\n \n);\n\nconst ConfigGroupPanel: React.FC = ({\n group,\n expanded,\n onToggle,\n searchTerm,\n copiedKey,\n onCopy,\n}) => {\n const panelId = `config-group-${group.id}`;\n const totalFields = group.fields.length +\n (group.subgroups?.reduce((s, sg) => s + sg.fields.length, 0) || 0);\n\n return (\n
\n {/* Group header */}\n \n
\n {expanded ? (\n \n ) : (\n \n )}\n \n {highlightMatch(group.title, searchTerm)}\n \n
\n
\n {group.subgroups && group.subgroups.length > 0 && (\n \n {group.subgroups.length} {group.subgroups.length === 1 ? 'provider' : 'providers'}\n \n )}\n \n {totalFields} {totalFields === 1 ? 'field' : 'fields'}\n \n
\n \n\n {/* Group fields and subgroups */}\n {expanded && (\n
\n {/* Top-level fields */}\n {group.fields.length > 0 && (\n
\n {group.fields.map((field) => (\n \n ))}\n
\n )}\n\n {/* Subgroups */}\n {group.subgroups?.map((sg) => (\n
\n
\n \n {highlightMatch(sg.title, searchTerm)}\n \n \n {sg.fields.length} {sg.fields.length === 1 ? 'field' : 'fields'}\n \n
\n
\n {sg.fields.map((field) => (\n \n ))}\n
\n
\n ))}\n
\n )}\n
\n );\n};\n\n/* ------------------------------------------------------------------ */\n/* ConfigPanel main component */\n/* ------------------------------------------------------------------ */\n\nconst ConfigPanel: React.FC = ({ onError, showToast }) => {\n const [config, setConfig] = useState(null);\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n const [expandedGroups, setExpandedGroups] = useState>(new Set(DEFAULT_EXPANDED));\n const [searchTerm, setSearchTerm] = useState('');\n const [copiedKey, setCopiedKey] = useState(null);\n const [exportOpen, setExportOpen] = useState(false);\n\n /* ---- Data fetching ---- */\n\n const fetchConfig = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const res = await axios.get('/api/config/full');\n setConfig(res.data);\n } catch (err: any) {\n const msg = err.response?.data?.detail || 'Failed to load configuration';\n setError(msg);\n onError?.(msg);\n } finally {\n setLoading(false);\n }\n }, [onError]);\n\n useEffect(() => {\n fetchConfig();\n }, [fetchConfig]);\n\n /* ---- Filtering ---- */\n\n const filteredGroups = useMemo(() => {\n if (!config) return [];\n if (!searchTerm.trim()) return config.groups;\n\n const term = searchTerm.toLowerCase();\n const matchField = (f: ConfigField) =>\n f.key.toLowerCase().includes(term) ||\n f.label.toLowerCase().includes(term) ||\n f.value.toLowerCase().includes(term);\n\n return config.groups\n .map((group) => ({\n ...group,\n fields: group.fields.filter(matchField),\n subgroups: group.subgroups?.map((sg) => ({\n ...sg,\n fields: sg.fields.filter(matchField),\n })).filter((sg) => sg.fields.length > 0),\n }))\n .filter((group) => group.fields.length > 0 || (group.subgroups && group.subgroups.length > 0));\n }, [config, searchTerm]);\n\n const totalMatchingFields = useMemo(\n () => filteredGroups.reduce((sum, g) => {\n const sgFields = g.subgroups?.reduce((s, sg) => s + sg.fields.length, 0) || 0;\n return sum + g.fields.length + sgFields;\n }, 0),\n [filteredGroups]\n );\n\n /* ---- Group expand/collapse ---- */\n\n const toggleGroup = useCallback((groupId: string) => {\n setExpandedGroups((prev) => {\n const next = new Set(prev);\n if (next.has(groupId)) next.delete(groupId);\n else next.add(groupId);\n return next;\n });\n }, []);\n\n const expandAll = useCallback(() => {\n if (!config) return;\n setExpandedGroups(new Set(config.groups.map((g) => g.id)));\n }, [config]);\n\n const collapseAll = useCallback(() => {\n setExpandedGroups(new Set());\n }, []);\n\n /* ---- Clipboard ---- */\n\n const copyToClipboard = useCallback(\n async (key: string, value: string) => {\n try {\n await navigator.clipboard.writeText(value);\n setCopiedKey(key);\n showToast?.('Copied to clipboard', 'success');\n setTimeout(() => setCopiedKey(null), 2000);\n } catch {\n showToast?.('Failed to copy', 'error');\n }\n },\n [showToast]\n );\n\n /* ---- Export ---- */\n\n const handleExport = useCallback(\n async (format: ExportFormat) => {\n setExportOpen(false);\n try {\n const res = await axios.get(`/api/config/export`, {\n params: { format },\n responseType: 'blob',\n });\n\n const disposition = res.headers['content-disposition'];\n let filename = `mcp-registry-config.${format}`;\n if (disposition) {\n const match = disposition.match(/filename=\"?([^\"]+)\"?/);\n if (match) filename = match[1];\n }\n\n const url = window.URL.createObjectURL(new Blob([res.data]));\n const link = document.createElement('a');\n link.href = url;\n link.setAttribute('download', filename);\n document.body.appendChild(link);\n link.click();\n link.remove();\n window.URL.revokeObjectURL(url);\n } catch (err: any) {\n const msg = err.response?.data?.detail || 'Export failed';\n showToast?.(msg, 'error');\n }\n },\n [showToast]\n );\n\n /* ---- Skeleton loading ---- */\n\n if (loading) {\n return (\n
\n
\n
\n
\n
\n
\n
\n
\n
\n {[1, 2, 3, 4].map((i) => (\n
\n ))}\n
\n );\n }\n\n /* ---- Error state ---- */\n\n if (error) {\n return (\n
\n \n

\n Failed to Load Configuration\n

\n

{error}

\n \n Retry\n \n
\n );\n }\n\n if (!config) return null;\n\n /* ---- Main render ---- */\n\n return (\n
\n {/* Header row */}\n
\n
\n

\n System Configuration\n

\n {config.is_local_dev && (\n \n Local Development Mode\n \n )}\n
\n\n
\n {/* Export dropdown */}\n
\n setExportOpen((o) => !o)}\n className=\"flex items-center px-3 py-2 text-sm border border-gray-300 dark:border-gray-600\n rounded-lg bg-white dark:bg-gray-800 text-gray-700 dark:text-gray-200\n hover:bg-gray-50 dark:hover:bg-gray-700 transition-colors\"\n aria-label=\"Export configuration\"\n >\n \n Export\n \n {exportOpen && (\n
\n {EXPORT_OPTIONS.map((opt) => (\n handleExport(opt.format)}\n className=\"w-full text-left px-4 py-2 text-sm text-gray-700 dark:text-gray-200\n hover:bg-gray-100 dark:hover:bg-gray-700 first:rounded-t-lg last:rounded-b-lg\"\n >\n {opt.label}\n \n ))}\n
\n )}\n
\n\n {/* Expand / Collapse */}\n \n Expand All\n \n \n Collapse All\n \n\n {/* Refresh */}\n \n \n \n
\n
\n\n {/* Search */}\n
\n \n setSearchTerm(e.target.value)}\n placeholder=\"Search configuration...\"\n aria-label=\"Search configuration\"\n className=\"w-full pl-10 pr-10 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n {searchTerm && (\n setSearchTerm('')}\n className=\"absolute right-3 top-1/2 -translate-y-1/2 text-gray-400 hover:text-gray-600 dark:hover:text-gray-300\"\n aria-label=\"Clear search\"\n >\n \n \n )}\n
\n\n {/* Search results count */}\n {searchTerm.trim() && filteredGroups.length > 0 && (\n

\n {totalMatchingFields} {totalMatchingFields === 1 ? 'field' : 'fields'} in{' '}\n {filteredGroups.length} {filteredGroups.length === 1 ? 'group' : 'groups'}\n

\n )}\n\n {/* No results */}\n {searchTerm.trim() && filteredGroups.length === 0 && (\n
\n

\n No configuration fields match \"{searchTerm}\"\n

\n
\n )}\n\n {/* Config groups */}\n
\n {filteredGroups.map((group) => (\n toggleGroup(group.id)}\n searchTerm={searchTerm}\n copiedKey={copiedKey}\n onCopy={copyToClipboard}\n />\n ))}\n
\n\n {/* Legend */}\n
\n \n **** = masked sensitive value\n \n \n (not set) = not configured\n \n
\n
\n );\n};\n\nexport default ConfigPanel;\n" }, { "path": "frontend/src/components/ConfirmModal.tsx", "content": "import React from 'react';\nimport DetailsModal from './DetailsModal';\nimport { ExclamationTriangleIcon } from '@heroicons/react/24/outline';\n\n\n/**\n * Props for the ConfirmModal component.\n */\ninterface ConfirmModalProps {\n isOpen: boolean;\n onClose: () => void;\n onConfirm: () => void;\n title: string;\n message: string;\n confirmLabel?: string;\n cancelLabel?: string;\n isDestructive?: boolean;\n isLoading?: boolean;\n}\n\n\n/**\n * A styled confirmation modal that replaces window.confirm().\n *\n * Renders a centered dialog with a warning icon, message, and\n * Cancel / Confirm action buttons. Supports destructive (red)\n * and normal (purple) confirm button styles.\n */\nconst ConfirmModal: React.FC = ({\n isOpen,\n onClose,\n onConfirm,\n title,\n message,\n confirmLabel = 'Confirm',\n cancelLabel = 'Cancel',\n isDestructive = false,\n isLoading = false,\n}) => {\n return (\n \n
\n
\n \n
\n\n

\n {message}\n

\n\n
\n \n {cancelLabel}\n \n \n {isLoading ? 'Removing...' : confirmLabel}\n \n
\n
\n \n );\n};\n\n\nexport default ConfirmModal;\n" }, { "path": "frontend/src/components/DataExport.tsx", "content": "import React, { useState, useEffect, useCallback } from 'react';\nimport {\n ArrowDownTrayIcon,\n CheckCircleIcon,\n ExclamationTriangleIcon,\n ArrowPathIcon,\n} from '@heroicons/react/24/outline';\nimport axios from 'axios';\nimport JSZip from 'jszip';\n\n\ninterface ExportableCollection {\n id: string;\n label: string;\n description: string;\n endpoint: string;\n queryParams: Record;\n dataKey: string | null;\n countKey: string | null;\n filename: string;\n isPaginated: boolean;\n paginationLimit: number;\n paginationOffsetKey?: string;\n}\n\nconst EXPORTABLE_COLLECTIONS: ExportableCollection[] = [\n {\n id: 'servers',\n label: 'Servers',\n description: 'All registered MCP servers',\n endpoint: '/api/servers',\n queryParams: {},\n dataKey: 'servers',\n countKey: 'total_count',\n filename: 'servers',\n isPaginated: true,\n paginationLimit: 500,\n },\n {\n id: 'agents',\n label: 'Agents',\n description: 'All registered AI agents',\n endpoint: '/api/agents',\n queryParams: {},\n dataKey: 'agents',\n countKey: 'total_count',\n filename: 'agents',\n isPaginated: true,\n paginationLimit: 500,\n },\n {\n id: 'skills',\n label: 'Skills',\n description: 'All registered skills (including disabled)',\n endpoint: '/api/skills',\n queryParams: { include_disabled: 'true' },\n dataKey: 'skills',\n countKey: 'total_count',\n filename: 'skills',\n isPaginated: true,\n paginationLimit: 500,\n },\n {\n id: 'virtual-servers',\n label: 'Virtual Servers',\n description: 'All virtual server configurations',\n endpoint: '/api/virtual-servers',\n queryParams: {},\n dataKey: null,\n countKey: null,\n filename: 'virtual-servers',\n isPaginated: false,\n paginationLimit: 500,\n },\n {\n id: 'federation-peers',\n label: 'Federation Peers',\n description: 'All configured federation peers',\n endpoint: '/api/peers',\n queryParams: {},\n dataKey: null,\n countKey: null,\n filename: 'federation-peers',\n isPaginated: false,\n paginationLimit: 500,\n },\n {\n id: 'federation-configs',\n label: 'Federation Configs',\n description: 'Federation configuration settings',\n endpoint: '/api/federation/configs',\n queryParams: {},\n dataKey: 'configs',\n countKey: null,\n filename: 'federation-configs',\n isPaginated: false,\n paginationLimit: 500,\n },\n {\n id: 'registry-card',\n label: 'Registry Card',\n description: 'Registry metadata and card information',\n endpoint: '/api/registry/v0.1/card',\n queryParams: {},\n dataKey: null,\n countKey: null,\n filename: 'registry-card',\n isPaginated: false,\n paginationLimit: 1,\n },\n {\n id: 'iam-users',\n label: 'IAM Users',\n description: 'All users and service accounts',\n endpoint: '/api/management/iam/users',\n queryParams: {},\n dataKey: 'users',\n countKey: null,\n filename: 'iam-users',\n isPaginated: false,\n paginationLimit: 500,\n },\n {\n id: 'iam-groups',\n label: 'IAM Groups',\n description: 'All IAM groups and scopes',\n endpoint: '/api/management/iam/groups',\n queryParams: {},\n dataKey: 'groups',\n countKey: null,\n filename: 'iam-groups',\n isPaginated: false,\n paginationLimit: 500,\n },\n {\n id: 'iam-m2m-clients',\n label: 'IAM M2M Clients',\n description: 'All machine-to-machine service accounts',\n endpoint: '/api/iam/m2m-clients',\n queryParams: {},\n dataKey: 'items',\n countKey: 'total',\n filename: 'iam-m2m-clients',\n isPaginated: true,\n paginationLimit: 500,\n paginationOffsetKey: 'skip',\n },\n {\n id: 'scopes',\n label: 'Scopes',\n description: 'Authorization scopes, server access rules, and group permissions',\n endpoint: '/api/export/scopes',\n queryParams: {},\n dataKey: 'scopes',\n countKey: 'total_count',\n filename: 'scopes',\n isPaginated: false,\n paginationLimit: 500,\n },\n];\n\n\nfunction _buildDateSuffix(): string {\n return new Date().toISOString().slice(0, 10);\n}\n\n\nasync function _fetchAllPages(\n collection: ExportableCollection,\n): Promise {\n const { endpoint, queryParams, dataKey, isPaginated, paginationLimit } = collection;\n const offsetKey = collection.paginationOffsetKey || 'offset';\n\n if (!isPaginated) {\n const response = await axios.get(endpoint, { params: queryParams });\n const json = response.data;\n if (dataKey) {\n return json[dataKey] || [];\n }\n return Array.isArray(json) ? json : [json];\n }\n\n const allRecords: any[] = [];\n let offset = 0;\n while (true) {\n const params = {\n ...queryParams,\n limit: String(paginationLimit),\n [offsetKey]: String(offset),\n };\n const response = await axios.get(endpoint, { params });\n const json = response.data;\n const page = dataKey ? (json[dataKey] || []) : json;\n allRecords.push(...page);\n if (page.length < paginationLimit) {\n break;\n }\n offset += paginationLimit;\n }\n return allRecords;\n}\n\n\nfunction _triggerBlobDownload(\n blob: Blob,\n filename: string,\n): void {\n const url = window.URL.createObjectURL(blob);\n const link = document.createElement('a');\n link.href = url;\n link.setAttribute('download', filename);\n document.body.appendChild(link);\n link.click();\n link.remove();\n window.URL.revokeObjectURL(url);\n}\n\n\nasync function _recordAuditEvent(\n exportType: string,\n collections: string[],\n): Promise {\n try {\n await axios.post('/api/export/audit-event', {\n export_type: exportType,\n collections,\n });\n } catch {\n // Audit event recording is best-effort; do not block the export\n }\n}\n\n\nasync function _fetchCount(\n collection: ExportableCollection,\n): Promise {\n const { endpoint, queryParams, dataKey, countKey, isPaginated, paginationLimit } = collection;\n const offsetKey = collection.paginationOffsetKey || 'offset';\n\n try {\n // Fast path: API returns a count field (servers, agents, skills, m2m-clients)\n if (countKey && isPaginated) {\n const response = await axios.get(endpoint, {\n params: { ...queryParams, limit: '1', [offsetKey]: '0' },\n });\n return response.data[countKey] ?? 0;\n }\n\n // Fallback: fetch data and count the array length\n const params: Record = { ...queryParams };\n if (isPaginated) {\n params.limit = String(paginationLimit);\n params[offsetKey] = '0';\n }\n const response = await axios.get(endpoint, { params });\n const json = response.data;\n\n if (dataKey) {\n return Array.isArray(json[dataKey]) ? json[dataKey].length : 0;\n }\n return Array.isArray(json) ? json.length : 1;\n } catch {\n return 0;\n }\n}\n\n\ninterface DataExportProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\n\nconst DataExport: React.FC = ({ onShowToast }) => {\n const [counts, setCounts] = useState>({});\n const [downloading, setDownloading] = useState>({});\n const [downloadingAll, setDownloadingAll] = useState(false);\n const [completedInZip, setCompletedInZip] = useState>(new Set());\n const [loadingCounts, setLoadingCounts] = useState(true);\n\n const fetchCounts = useCallback(async () => {\n setLoadingCounts(true);\n const results = await Promise.allSettled(\n EXPORTABLE_COLLECTIONS.map(async (col) => {\n const count = await _fetchCount(col);\n return { id: col.id, count };\n })\n );\n\n const newCounts: Record = {};\n // Promise.allSettled preserves input order, so index maps to collection\n for (let i = 0; i < results.length; i++) {\n const result = results[i];\n const collectionId = EXPORTABLE_COLLECTIONS[i].id;\n if (result.status === 'fulfilled') {\n newCounts[collectionId] = result.value.count;\n } else {\n newCounts[collectionId] = null;\n }\n }\n setCounts(newCounts);\n setLoadingCounts(false);\n }, []);\n\n useEffect(() => {\n fetchCounts();\n }, [fetchCounts]);\n\n const handleDownload = useCallback(async (collection: ExportableCollection) => {\n setDownloading((prev) => ({ ...prev, [collection.id]: true }));\n try {\n const data = await _fetchAllPages(collection);\n const dateSuffix = _buildDateSuffix();\n const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });\n _triggerBlobDownload(blob, `${collection.filename}-export-${dateSuffix}.json`);\n await _recordAuditEvent('single', [collection.id]);\n onShowToast(`Downloaded ${collection.label} (${data.length} records)`, 'success');\n } catch (err: any) {\n onShowToast(`Failed to download ${collection.label}: ${err.message}`, 'error');\n } finally {\n setDownloading((prev) => ({ ...prev, [collection.id]: false }));\n }\n }, [onShowToast]);\n\n const handleDownloadAll = useCallback(async () => {\n setDownloadingAll(true);\n setCompletedInZip(new Set());\n const zip = new JSZip();\n const dateSuffix = _buildDateSuffix();\n const failedIds: string[] = [];\n\n for (const collection of EXPORTABLE_COLLECTIONS) {\n try {\n const data = await _fetchAllPages(collection);\n const jsonStr = JSON.stringify(data, null, 2);\n zip.file(`${collection.filename}-export-${dateSuffix}.json`, jsonStr);\n setCompletedInZip((prev) => new Set(prev).add(collection.id));\n } catch (err: any) {\n failedIds.push(collection.id);\n }\n }\n\n try {\n const blob = await zip.generateAsync({ type: 'blob' });\n _triggerBlobDownload(blob, `registry-export-${dateSuffix}.zip`);\n const exportedIds = EXPORTABLE_COLLECTIONS\n .filter((c) => !failedIds.includes(c.id))\n .map((c) => c.id);\n await _recordAuditEvent('all', exportedIds);\n\n if (failedIds.length > 0) {\n const failedLabels = EXPORTABLE_COLLECTIONS\n .filter((c) => failedIds.includes(c.id))\n .map((c) => c.label);\n onShowToast(\n `ZIP downloaded with errors. Failed: ${failedLabels.join(', ')}`,\n 'error',\n );\n } else {\n onShowToast('All collections downloaded as ZIP', 'success');\n }\n } catch (err: any) {\n onShowToast(`Failed to create ZIP: ${err.message}`, 'error');\n } finally {\n setDownloadingAll(false);\n }\n }, [onShowToast]);\n\n const isAnyDownloading = downloadingAll || Object.values(downloading).some(Boolean);\n\n return (\n
\n {/* Page header */}\n
\n

\n Data Export\n

\n

\n Download registry data as JSON for debugging and auditing purposes.\n

\n
\n\n {/* Sensitive data warning banner */}\n
\n \n

\n Exported data may contain sensitive information such as email addresses,\n client IDs, and configuration details. Handle exported files with care.\n

\n
\n\n {/* Collection table */}\n
\n \n \n \n \n \n \n \n \n \n \n {EXPORTABLE_COLLECTIONS.map((collection) => (\n \n \n \n \n \n \n ))}\n \n
\n Collection\n \n Records\n \n Action\n
\n {collection.label}\n \n {loadingCounts ? (\n \n ) : (\n counts[collection.id] ?? '—'\n )}\n \n
\n {downloadingAll && completedInZip.has(collection.id) && (\n \n )}\n handleDownload(collection)}\n disabled={isAnyDownloading}\n className=\"inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-md\n text-purple-700 dark:text-purple-300\n bg-purple-50 dark:bg-purple-900/30\n hover:bg-purple-100 dark:hover:bg-purple-900/50\n disabled:opacity-50 disabled:cursor-not-allowed\n transition-colors\"\n >\n {downloading[collection.id] ? (\n \n ) : (\n \n )}\n Download\n \n
\n
\n
\n\n {/* Download All button */}\n
\n \n {downloadingAll ? (\n <>\n \n Downloading...\n \n ) : (\n <>\n \n Download All as ZIP\n \n )}\n \n
\n
\n );\n};\n\nexport default DataExport;\n" }, { "path": "frontend/src/components/DeleteConfirmation.tsx", "content": "import React, { useState } from 'react';\nimport { ArrowPathIcon } from '@heroicons/react/24/outline';\n\n/**\n * Props for the DeleteConfirmation component.\n */\nexport interface DeleteConfirmationProps {\n entityType: 'server' | 'agent' | 'group' | 'user' | 'm2m';\n entityName: string;\n entityPath: string;\n onConfirm: (path: string) => Promise;\n onCancel: () => void;\n}\n\n/**\n * DeleteConfirmation component provides an inline confirmation UI for delete operations.\n * \n * Displays a red-tinted container with warning text, requiring users to type the entity\n * name exactly before the delete button becomes enabled. Shows loading state during\n * API calls and displays error messages on failure.\n * \n * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8\n */\nconst DeleteConfirmation: React.FC = ({\n entityType,\n entityName,\n entityPath,\n onConfirm,\n onCancel,\n}) => {\n const [typedName, setTypedName] = useState('');\n const [isDeleting, setIsDeleting] = useState(false);\n const [error, setError] = useState(null);\n\n const isConfirmed = typedName === entityName;\n\n const handleDelete = async () => {\n if (!isConfirmed || isDeleting) return;\n\n setIsDeleting(true);\n setError(null);\n\n try {\n await onConfirm(entityPath);\n onCancel(); // Close on success - parent handles list refresh + toast\n } catch (err: any) {\n setError(\n err.response?.data?.detail ||\n err.response?.data?.reason ||\n `Failed to delete ${entityType}`\n );\n } finally {\n setIsDeleting(false);\n }\n };\n\n const entityTypeLabels: Record = {\n server: 'Server',\n agent: 'Agent',\n group: 'Group',\n user: 'User',\n m2m: 'M2M Account',\n };\n const entityTypeLabel = entityTypeLabels[entityType] || entityType;\n\n return (\n
\n

\n Delete {entityTypeLabel}\n

\n

\n This action is irreversible. This will permanently delete the {entityType}{' '}\n \"{entityName}\" and remove it from the registry.\n

\n

\n Type {entityName} to confirm:\n

\n setTypedName(e.target.value)}\n className=\"w-full px-3 py-2 border border-red-300 dark:border-red-700 rounded mb-3 \n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\"\n placeholder={entityName}\n disabled={isDeleting}\n />\n {error && (\n

{error}

\n )}\n
\n \n Cancel\n \n \n {isDeleting && }\n Delete {entityTypeLabel}\n \n
\n
\n );\n};\n\nexport default DeleteConfirmation;\n" }, { "path": "frontend/src/components/DeploymentModeIndicator.tsx", "content": "import React from 'react';\nimport { useRegistryConfig } from '../hooks/useRegistryConfig';\n\nexport const DeploymentModeIndicator: React.FC = () => {\n const { config } = useRegistryConfig();\n\n if (!config || config.deployment_mode === 'with-gateway') {\n return null;\n }\n\n return (\n \n Registry Only\n \n );\n};\n" }, { "path": "frontend/src/components/DetailsModal.tsx", "content": "import React from 'react';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\ninterface DetailsModalProps {\n title: string;\n isOpen: boolean;\n onClose: () => void;\n loading?: boolean;\n error?: string | null;\n children: React.ReactNode;\n maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';\n}\n\nconst MAX_WIDTH_CLASSES = {\n sm: 'max-w-sm',\n md: 'max-w-md',\n lg: 'max-w-lg',\n xl: 'max-w-xl',\n '2xl': 'max-w-2xl',\n '3xl': 'max-w-3xl',\n '4xl': 'max-w-4xl',\n};\n\n/**\n * Shared DetailsModal component with loading and error states.\n *\n * Features:\n * - Backdrop with blur effect\n * - Escape key handler\n * - Configurable max width\n * - Built-in loading spinner\n * - Built-in error display\n * - Dark mode support\n *\n * Usage:\n * ```tsx\n * \n * \n * \n * ```\n */\nconst DetailsModal: React.FC = ({\n title,\n isOpen,\n onClose,\n loading = false,\n error = null,\n children,\n maxWidth = '4xl',\n}) => {\n useEscapeKey(onClose, isOpen);\n\n if (!isOpen) {\n return null;\n }\n\n return (\n
\n \n {/* Header */}\n
\n

\n {title}\n

\n \n ✕\n \n
\n\n {/* Loading State */}\n {loading && (\n
\n
\n
\n

\n Loading details...\n

\n
\n
\n )}\n\n {/* Error State */}\n {!loading && error && (\n
\n

\n Error Loading Details\n

\n

{error}

\n
\n )}\n\n {/* Content */}\n {!loading && !error && children}\n
\n
\n );\n};\n\nexport default DetailsModal;\n" }, { "path": "frontend/src/components/DiscoverListRow.tsx", "content": "import React, { useState } from 'react';\nimport {\n StarIcon,\n WrenchScrewdriverIcon,\n ChevronDownIcon,\n ChevronUpIcon,\n} from '@heroicons/react/24/solid';\nimport {\n ServerIcon,\n CpuChipIcon,\n SparklesIcon,\n Square3Stack3DIcon,\n GlobeAltIcon,\n} from '@heroicons/react/24/outline';\nimport ServerCard from './ServerCard';\nimport type { Server } from './ServerCard';\nimport AgentCard from './AgentCard';\nimport SkillCard from './SkillCard';\nimport type { Skill } from '../types/skill';\nimport VirtualServerCard from './VirtualServerCard';\nimport type { VirtualServerInfo } from '../types/virtualServer';\n\n\ntype ItemType = 'server' | 'agent' | 'skill' | 'virtual';\n\n\ninterface DiscoverListRowProps {\n type: ItemType;\n item: Server | Skill | VirtualServerInfo;\n onToggle: (path: string, enabled: boolean) => void;\n onEdit?: (item: any) => void;\n onDelete?: (path: string) => any;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n authToken?: string | null;\n}\n\n\n/**\n * Get average rating from rating_details array.\n */\nfunction _getAverageRating(\n ratingDetails: Array<{ user: string; rating: number }> | undefined\n): number {\n if (!ratingDetails || ratingDetails.length === 0) {\n return 0;\n }\n const sum = ratingDetails.reduce((acc, r) => acc + r.rating, 0);\n return sum / ratingDetails.length;\n}\n\n\n/**\n * Get type badge styling by item type.\n */\nfunction _getTypeBadge(type: ItemType) {\n if (type === 'server') {\n return {\n bg: 'bg-indigo-500/15 text-indigo-300',\n icon: ServerIcon,\n label: 'Server',\n };\n }\n if (type === 'virtual') {\n return {\n bg: 'bg-teal-500/15 text-teal-300',\n icon: Square3Stack3DIcon,\n label: 'Virtual',\n };\n }\n if (type === 'agent') {\n return {\n bg: 'bg-cyan-500/15 text-cyan-300',\n icon: CpuChipIcon,\n label: 'Agent',\n };\n }\n return {\n bg: 'bg-amber-500/15 text-amber-300',\n icon: SparklesIcon,\n label: 'Skill',\n };\n}\n\n\n/**\n * Get the source registry name for a server or agent, if it comes from\n * a federated peer or an external registry.\n */\nfunction _getServerRegistrySource(server: Server): string | null {\n // Federated peer registry\n if (server.sync_metadata?.is_federated && server.sync_metadata?.source_peer_id) {\n return server.sync_metadata.source_peer_id;\n }\n // External registry identified by tags\n const tags = server.tags || [];\n const externalTags = ['anthropic-registry', 'workday-asor', 'asor', 'federated'];\n const match = tags.find(t => externalTags.includes(t));\n if (match) {\n return match;\n }\n return null;\n}\n\n\n/**\n * Extract display fields from any item type in a uniform way.\n */\nfunction _extractDisplayFields(\n type: ItemType,\n item: Server | Skill | VirtualServerInfo\n) {\n if (type === 'virtual') {\n const vs = item as VirtualServerInfo;\n return {\n name: vs.server_name,\n description: vs.description || '',\n tags: vs.tags || [],\n rating: _getAverageRating(vs.rating_details),\n ratingCount: vs.rating_details?.length || 0,\n toolCount: vs.tool_count || 0,\n registrySource: null as string | null,\n };\n }\n if (type === 'skill') {\n const skill = item as Skill;\n const source = skill.registry_name && skill.registry_name !== 'local'\n ? skill.registry_name\n : null;\n return {\n name: skill.name,\n description: skill.description || '',\n tags: skill.tags || [],\n rating: skill.num_stars || 0,\n ratingCount: 0,\n toolCount: 0,\n registrySource: source,\n };\n }\n // server or agent\n const server = item as Server;\n return {\n name: server.name,\n description: (server as any).description || '',\n tags: (server as any).tags || [],\n rating: _getAverageRating(server.rating_details),\n ratingCount: server.rating_details?.length || 0,\n toolCount: (server as any).num_tools || 0,\n registrySource: _getServerRegistrySource(server),\n };\n}\n\n\nconst DiscoverListRow: React.FC = ({\n type,\n item,\n onToggle,\n onEdit,\n onDelete,\n onShowToast,\n authToken,\n}) => {\n const [expanded, setExpanded] = useState(false);\n\n const badge = _getTypeBadge(type);\n const TypeIcon = badge.icon;\n const fields = _extractDisplayFields(type, item);\n\n return (\n
\n {/* Compact row */}\n setExpanded(!expanded)}\n data-testid={`list-row-${type}-${item.path}`}\n >\n {/* Type badge */}\n \n \n {badge.label}\n \n\n {/* Registry source label */}\n {fields.registrySource && (\n \n \n {fields.registrySource}\n \n )}\n\n {/* Name */}\n \n {fields.name}\n \n\n {/* Separator */}\n {fields.description && (\n ·\n )}\n\n {/* Description */}\n \n {fields.description}\n \n\n {/* Tags (up to 2) */}\n {fields.tags.length > 0 && (\n
\n {fields.tags.slice(0, 2).map((tag: string) => (\n \n #{tag}\n \n ))}\n {fields.tags.length > 2 && (\n +{fields.tags.length - 2}\n )}\n
\n )}\n\n {/* Tool count */}\n {fields.toolCount > 0 && (\n \n \n {fields.toolCount}\n \n )}\n\n {/* Rating */}\n {fields.rating > 0 && (\n \n \n {fields.rating.toFixed(1)}\n {fields.ratingCount > 0 && (\n ({fields.ratingCount})\n )}\n \n )}\n\n {/* Expand chevron */}\n {expanded ? (\n \n ) : (\n \n )}\n
\n\n {/* Expanded detail: full card */}\n {expanded && (\n
\n {type === 'server' && (\n \n )}\n {type === 'agent' && (\n \n )}\n {type === 'skill' && (\n \n )}\n {type === 'virtual' && (\n \n )}\n
\n )}\n
\n );\n};\n\nexport default DiscoverListRow;\n" }, { "path": "frontend/src/components/DiscoverTab.tsx", "content": "import React, { useState, useMemo, useCallback } from 'react';\nimport { MagnifyingGlassIcon, XMarkIcon } from '@heroicons/react/24/outline';\nimport { useSemanticSearch } from '../hooks/useSemanticSearch';\nimport SemanticSearchResults from './SemanticSearchResults';\nimport DiscoverListRow from './DiscoverListRow';\nimport type { Server } from './ServerCard';\nimport type { Skill } from '../types/skill';\nimport type { VirtualServerInfo } from '../types/virtualServer';\n\n\n// Path for the built-in AI Registry Tools server\nconst AI_REGISTRY_TOOLS_PATH = '/airegistry-tools/';\n\n// Maximum featured items per category\nconst MAX_FEATURED = 4;\n\n\ninterface DiscoverTabProps {\n servers: Server[];\n agents: Server[];\n skills: Skill[];\n virtualServers: VirtualServerInfo[];\n externalServers: Server[];\n externalAgents: Server[];\n loading: boolean;\n onServerToggle: (path: string, enabled: boolean) => void;\n onServerEdit?: (server: Server) => void;\n onServerDelete?: (path: string) => Promise;\n onAgentToggle: (path: string, enabled: boolean) => void;\n onAgentEdit?: (agent: Server) => void;\n onAgentDelete?: (path: string) => Promise;\n onSkillToggle: (path: string, enabled: boolean) => void;\n onSkillEdit?: (skill: Skill) => void;\n onSkillDelete?: (path: string) => void;\n onVirtualServerToggle: (path: string, enabled: boolean) => void;\n onVirtualServerEdit?: (vs: VirtualServerInfo) => void;\n onVirtualServerDelete?: (path: string) => void;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n authToken?: string | null;\n}\n\n\n/**\n * Compute average rating from rating_details array.\n */\nfunction _getAverageRating(\n ratingDetails: Array<{ user: string; rating: number }> | undefined\n): number {\n if (!ratingDetails || ratingDetails.length === 0) {\n return 0;\n }\n const sum = ratingDetails.reduce((acc, r) => acc + r.rating, 0);\n return sum / ratingDetails.length;\n}\n\n\n/**\n * Sort servers by average rating (descending), then alphabetically by name.\n */\nfunction _sortServersByRating(servers: Server[]): Server[] {\n return [...servers].sort((a, b) => {\n const ratingDiff = _getAverageRating(b.rating_details) - _getAverageRating(a.rating_details);\n if (ratingDiff !== 0) return ratingDiff;\n return a.name.localeCompare(b.name);\n });\n}\n\n\n/**\n * Sort skills by num_stars (descending), then alphabetically by name.\n */\nfunction _sortSkillsByStars(skills: Skill[]): Skill[] {\n return [...skills].sort((a, b) => {\n const ratingDiff = (b.num_stars || 0) - (a.num_stars || 0);\n if (ratingDiff !== 0) return ratingDiff;\n return a.name.localeCompare(b.name);\n });\n}\n\n\n/**\n * Sort virtual servers by rating then name.\n */\nfunction _sortVirtualServersByRating(vs: VirtualServerInfo[]): VirtualServerInfo[] {\n return [...vs].sort((a, b) => {\n const ratingDiff = _getAverageRating(b.rating_details) - _getAverageRating(a.rating_details);\n if (ratingDiff !== 0) return ratingDiff;\n return a.server_name.localeCompare(b.server_name);\n });\n}\n\n\n/**\n * Check if an item matches a keyword search query.\n * Searches name, description, path, and tags.\n */\nfunction _matchesKeyword(\n item: { name: string; description?: string; path: string; tags?: string[] },\n query: string\n): boolean {\n const q = query.toLowerCase();\n return (\n item.name.toLowerCase().includes(q) ||\n (item.description || '').toLowerCase().includes(q) ||\n item.path.toLowerCase().includes(q) ||\n (item.tags || []).some(tag => tag.toLowerCase().includes(q))\n );\n}\n\n\n/**\n * Build a count fragment like \"4 servers\".\n */\nfunction _countFragment(\n count: number,\n label: string\n): string {\n const plural = count !== 1 ? 's' : '';\n return `${count} ${label}${plural}`;\n}\n\n\n/**\n * Build the summary text showing counts per category.\n * Default: \"18 servers, 2 virtual, 8 agents, 4 skills, 3 external\"\n * Searching: \"3 servers\" (only matched counts, no totals)\n */\nfunction _buildSummaryText(\n totals: { servers: number; virtual: number; agents: number; skills: number; external: number },\n matched: { servers: number; virtual: number; agents: number; skills: number; external: number },\n isSearching: boolean\n): string {\n const parts: string[] = [];\n\n // When searching, only show categories that have matches\n // When not searching, show all categories that have items\n const categories = [\n { total: totals.servers, match: matched.servers, label: 'server' },\n { total: totals.virtual, match: matched.virtual, label: 'virtual' },\n { total: totals.agents, match: matched.agents, label: 'agent' },\n { total: totals.skills, match: matched.skills, label: 'skill' },\n { total: totals.external, match: matched.external, label: 'external' },\n ];\n\n for (const cat of categories) {\n if (isSearching && cat.match > 0) {\n parts.push(_countFragment(cat.match, cat.label));\n } else if (!isSearching && cat.total > 0) {\n parts.push(_countFragment(cat.total, cat.label));\n }\n }\n\n if (parts.length === 0) {\n return isSearching ? 'No matches' : 'No items registered';\n }\n\n const prefix = isSearching ? 'Showing ' : '';\n return prefix + parts.join(', ');\n}\n\n\n/**\n * Check if a virtual server matches a keyword search query.\n */\nfunction _virtualServerMatchesKeyword(\n vs: VirtualServerInfo,\n query: string\n): boolean {\n const q = query.toLowerCase();\n return (\n vs.server_name.toLowerCase().includes(q) ||\n (vs.description || '').toLowerCase().includes(q) ||\n vs.path.toLowerCase().includes(q) ||\n (vs.tags || []).some(tag => tag.toLowerCase().includes(q))\n );\n}\n\n\n/**\n * Get featured items for the Discover landing page.\n * AI Registry Tools always first among servers if it exists.\n * Returns sorted, enabled items up to the max per category.\n */\nfunction _getFeaturedItems(\n servers: Server[],\n agents: Server[],\n skills: Skill[],\n virtualServers: VirtualServerInfo[],\n externalServers: Server[],\n externalAgents: Server[],\n keywordFilter: string\n) {\n // Filter enabled items\n const enabledServers = servers.filter(s => s.enabled);\n const enabledAgents = agents.filter(a => a.enabled);\n const enabledSkills = skills.filter(s => s.is_enabled);\n const enabledVirtual = virtualServers.filter(vs => vs.is_enabled);\n const enabledExtServers = externalServers.filter(s => s.enabled);\n const enabledExtAgents = externalAgents.filter(a => a.enabled);\n\n // Apply keyword filter if present\n const hasFilter = keywordFilter.length > 0;\n\n const filteredServers = hasFilter\n ? enabledServers.filter(s => _matchesKeyword(s, keywordFilter))\n : enabledServers;\n const filteredAgents = hasFilter\n ? enabledAgents.filter(a => _matchesKeyword(a, keywordFilter))\n : enabledAgents;\n const filteredSkills = hasFilter\n ? enabledSkills.filter(s => _matchesKeyword({\n name: s.name, description: s.description, path: s.path, tags: s.tags,\n }, keywordFilter))\n : enabledSkills;\n const filteredVirtual = hasFilter\n ? enabledVirtual.filter(vs => _virtualServerMatchesKeyword(vs, keywordFilter))\n : enabledVirtual;\n const filteredExtServers = hasFilter\n ? enabledExtServers.filter(s => _matchesKeyword(s, keywordFilter))\n : enabledExtServers;\n const filteredExtAgents = hasFilter\n ? enabledExtAgents.filter(a => _matchesKeyword(a, keywordFilter))\n : enabledExtAgents;\n\n // Sort and pick top items\n // AI Registry Tools goes first if it's in the filtered list\n const aiRegistryTools = filteredServers.find(s => s.path === AI_REGISTRY_TOOLS_PATH);\n const otherServers = filteredServers.filter(s => s.path !== AI_REGISTRY_TOOLS_PATH);\n const sortedOther = _sortServersByRating(otherServers);\n\n const featuredServers: Server[] = [];\n if (aiRegistryTools) {\n featuredServers.push(aiRegistryTools);\n }\n featuredServers.push(...sortedOther.slice(0, MAX_FEATURED - featuredServers.length));\n\n const featuredAgents = _sortServersByRating(filteredAgents).slice(0, MAX_FEATURED);\n const featuredSkills = _sortSkillsByStars(filteredSkills).slice(0, MAX_FEATURED);\n const featuredVirtual = _sortVirtualServersByRating(filteredVirtual).slice(0, MAX_FEATURED);\n const featuredExtServers = _sortServersByRating(filteredExtServers).slice(0, MAX_FEATURED);\n const featuredExtAgents = _sortServersByRating(filteredExtAgents).slice(0, MAX_FEATURED);\n\n return {\n featuredServers,\n featuredAgents,\n featuredSkills,\n featuredVirtual,\n featuredExtServers,\n featuredExtAgents,\n // Total enabled counts (before keyword filter + before MAX_FEATURED cap)\n totalServers: enabledServers.length,\n totalVirtual: enabledVirtual.length,\n totalAgents: enabledAgents.length,\n totalSkills: enabledSkills.length,\n totalExternal: enabledExtServers.length + enabledExtAgents.length,\n // Filtered counts (after keyword filter, before MAX_FEATURED cap)\n matchedServers: filteredServers.length,\n matchedVirtual: filteredVirtual.length,\n matchedAgents: filteredAgents.length,\n matchedSkills: filteredSkills.length,\n matchedExternal: filteredExtServers.length + filteredExtAgents.length,\n matchedExtServers: filteredExtServers.length,\n matchedExtAgents: filteredExtAgents.length,\n };\n}\n\n\nconst DiscoverTab: React.FC = ({\n servers,\n agents,\n skills,\n virtualServers,\n externalServers,\n externalAgents,\n loading,\n onServerToggle,\n onServerEdit,\n onServerDelete,\n onAgentToggle,\n onAgentEdit,\n onAgentDelete,\n onSkillToggle,\n onSkillEdit,\n onSkillDelete,\n onVirtualServerToggle,\n onVirtualServerEdit,\n onVirtualServerDelete,\n onShowToast,\n authToken,\n}) => {\n const [searchTerm, setSearchTerm] = useState('');\n const [committedQuery, setCommittedQuery] = useState('');\n\n // Semantic search (only fires when committedQuery is set via Enter)\n const {\n results: searchResults,\n loading: searchLoading,\n error: searchError,\n } = useSemanticSearch(committedQuery, {\n enabled: committedQuery.length >= 2,\n });\n\n const isSemanticActive = committedQuery.length >= 2;\n\n // Compute featured items with keyword filtering\n const {\n featuredServers,\n featuredAgents,\n featuredSkills,\n featuredVirtual,\n featuredExtServers,\n featuredExtAgents,\n totalServers, totalVirtual, totalAgents, totalSkills, totalExternal,\n matchedServers, matchedVirtual, matchedAgents, matchedSkills, matchedExternal,\n matchedExtServers, matchedExtAgents,\n } = useMemo(\n () => _getFeaturedItems(\n servers, agents, skills, virtualServers,\n externalServers, externalAgents,\n isSemanticActive ? '' : searchTerm\n ),\n [servers, agents, skills, virtualServers, externalServers, externalAgents, searchTerm, isSemanticActive]\n );\n\n const totalFeatured = featuredServers.length + featuredAgents.length +\n featuredSkills.length + featuredVirtual.length +\n featuredExtServers.length + featuredExtAgents.length;\n\n const handleSemanticSearch = useCallback(() => {\n if (searchTerm.trim().length >= 2) {\n setCommittedQuery(searchTerm.trim());\n }\n }, [searchTerm]);\n\n const handleClearSearch = useCallback(() => {\n setSearchTerm('');\n setCommittedQuery('');\n }, []);\n\n return (\n
\n {/* Header: title + search bar - always at top */}\n
\n

\n Discover MCP Servers, Agents & Skills\n

\n\n {/* Search Input */}\n
\n
\n \n
\n {\n setSearchTerm(e.target.value);\n if (committedQuery) {\n setCommittedQuery('');\n }\n }}\n onKeyDown={(e) => {\n if (e.key === 'Enter') {\n e.preventDefault();\n handleSemanticSearch();\n }\n }}\n />\n {searchTerm && (\n \n \n \n )}\n
\n\n {/* Summary counts + hint */}\n {!isSemanticActive && (\n

\n {_buildSummaryText(\n { servers: totalServers, virtual: totalVirtual, agents: totalAgents, skills: totalSkills, external: totalExternal },\n { servers: matchedServers, virtual: matchedVirtual, agents: matchedAgents, skills: matchedSkills, external: matchedExternal },\n searchTerm.length > 0\n )}\n {searchTerm && (\n \n {' '}· press Enter for semantic search\n \n )}\n

\n )}\n
\n\n {/* Content Area */}\n {isSemanticActive ? (\n /* Semantic Search Results */\n
\n \n
\n ) : (\n /* Featured List Rows */\n
\n
\n {loading ? (\n
\n Loading featured items...\n
\n ) : totalFeatured === 0 ? (\n
\n {searchTerm\n ? `No items matching \"${searchTerm}\"`\n : 'No items registered yet. Register your first MCP server, agent, or skill!'}\n
\n ) : (\n
\n {/* MCP Servers section */}\n {featuredServers.length > 0 && (\n
\n

\n MCP Servers\n {matchedServers > featuredServers.length && (\n \n (showing {featuredServers.length} of {matchedServers})\n \n )}\n

\n {featuredServers.map(server => (\n \n ))}\n
\n )}\n\n {/* Virtual MCP Servers section */}\n {featuredVirtual.length > 0 && (\n
\n

\n Virtual MCP Servers\n {matchedVirtual > featuredVirtual.length && (\n \n (showing {featuredVirtual.length} of {matchedVirtual})\n \n )}\n

\n {featuredVirtual.map(vs => (\n \n ))}\n
\n )}\n\n {/* Agents section */}\n {featuredAgents.length > 0 && (\n
\n

\n Agents\n {matchedAgents > featuredAgents.length && (\n \n (showing {featuredAgents.length} of {matchedAgents})\n \n )}\n

\n {featuredAgents.map(agent => (\n \n ))}\n
\n )}\n\n {/* Skills section */}\n {featuredSkills.length > 0 && (\n
\n

\n Skills\n {matchedSkills > featuredSkills.length && (\n \n (showing {featuredSkills.length} of {matchedSkills})\n \n )}\n

\n {featuredSkills.map(skill => (\n \n ))}\n
\n )}\n\n {/* External Servers section */}\n {featuredExtServers.length > 0 && (\n
\n

\n External Registry Servers\n {matchedExtServers > featuredExtServers.length && (\n \n (showing {featuredExtServers.length} of {matchedExtServers})\n \n )}\n

\n {featuredExtServers.map(server => (\n \n ))}\n
\n )}\n\n {/* External Agents section */}\n {featuredExtAgents.length > 0 && (\n
\n

\n External Registry Agents\n {matchedExtAgents > featuredExtAgents.length && (\n \n (showing {featuredExtAgents.length} of {matchedExtAgents})\n \n )}\n

\n {featuredExtAgents.map(agent => (\n \n ))}\n
\n )}\n\n {/* Bottom padding so fade gradient doesn't cover last row */}\n
\n
\n )}\n
\n {/* Fade gradient at bottom to hint more content */}\n
\n
\n )}\n
\n );\n};\n\nexport default DiscoverTab;\n" }, { "path": "frontend/src/components/ExternalRegistries.tsx", "content": "import React, { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\nimport {\n ArrowPathIcon,\n CheckCircleIcon,\n ExclamationCircleIcon,\n CloudIcon,\n ServerStackIcon,\n CpuChipIcon,\n SparklesIcon,\n PlusIcon,\n XMarkIcon,\n} from '@heroicons/react/24/outline';\nimport AddRegistryEntryModal, { RegistrySourceType } from './AddRegistryEntryModal';\nimport ConfirmModal from './ConfirmModal';\n\n\n/**\n * Props for the ExternalRegistries component.\n */\ninterface ExternalRegistriesProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\n\n/**\n * Anthropic server config shape.\n */\ninterface AnthropicServerConfig {\n name: string;\n}\n\n\n/**\n * Anthropic federation config shape.\n */\ninterface AnthropicConfig {\n enabled: boolean;\n endpoint: string;\n sync_on_startup: boolean;\n servers: AnthropicServerConfig[];\n}\n\n\n/**\n * ASOR agent config shape.\n */\ninterface AsorAgentConfig {\n id: string;\n}\n\n\n/**\n * ASOR federation config shape.\n */\ninterface AsorConfig {\n enabled: boolean;\n endpoint: string;\n auth_env_var: string | null;\n sync_on_startup: boolean;\n agents: AsorAgentConfig[];\n}\n\n\n/**\n * AgentCore registry config shape.\n */\ninterface AgentCoreRegistryConfig {\n registry_id: string;\n aws_account_id: string | null;\n aws_region: string | null;\n assume_role_arn: string | null;\n descriptor_types: string[];\n sync_status_filter: string;\n}\n\n\n/**\n * AgentCore federation config shape.\n */\ninterface AgentCoreConfig {\n enabled: boolean;\n aws_region: string;\n sync_on_startup: boolean;\n sync_interval_minutes: number;\n sync_timeout_seconds: number;\n max_concurrent_fetches: number;\n registries: AgentCoreRegistryConfig[];\n}\n\n\n/**\n * Root federation config shape.\n */\ninterface FederationConfig {\n anthropic: AnthropicConfig;\n asor: AsorConfig;\n aws_registry: AgentCoreConfig;\n}\n\n\n/**\n * Sync result shape from /api/federation/sync.\n */\ninterface SyncResults {\n anthropic: { count: number; servers: string[] };\n asor: { count: number; agents: string[] };\n aws_registry: { count: number; servers: string[]; agents: string[]; skills: string[] };\n}\n\n\n/**\n * Format a relative time string from an ISO timestamp.\n */\nfunction _formatRelativeTime(dateString: string | null | undefined): string {\n if (!dateString) return 'Never';\n\n const date = new Date(dateString);\n const now = new Date();\n const diffMs = now.getTime() - date.getTime();\n const diffMins = Math.floor(diffMs / (1000 * 60));\n const diffHours = Math.floor(diffMs / (1000 * 60 * 60));\n const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));\n\n if (diffMins < 1) return 'Just now';\n if (diffMins < 60) return `${diffMins}m ago`;\n if (diffHours < 24) return `${diffHours}h ago`;\n if (diffDays < 7) return `${diffDays}d ago`;\n\n return date.toLocaleDateString();\n}\n\n\n/**\n * Truncate a string (like an ARN) for display.\n */\nfunction _truncateArn(arn: string, maxLen: number = 60): string {\n if (arn.length <= maxLen) return arn;\n return arn.slice(0, maxLen - 3) + '...';\n}\n\n\n/**\n * ExternalRegistries displays the federation configuration for\n * Anthropic, AWS Agent Registry, and ASOR external registries.\n *\n * Shows config details, sync status, and provides a Sync Now button.\n */\nconst ExternalRegistries: React.FC = ({ onShowToast }) => {\n const [config, setConfig] = useState(null);\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n const [syncing, setSyncing] = useState(null);\n const [lastSyncTime, setLastSyncTime] = useState(null);\n const [lastSyncResults, setLastSyncResults] = useState(null);\n const [addModalSource, setAddModalSource] = useState(null);\n const [deletingItem, setDeletingItem] = useState(null);\n const [confirmDelete, setConfirmDelete] = useState<{\n source: 'aws_registry' | 'anthropic' | 'asor';\n identifier: string;\n } | null>(null);\n\n /**\n * Fetch federation config from API.\n */\n const fetchConfig = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const response = await axios.get('/api/federation/config');\n setConfig(response.data);\n } catch (err: any) {\n if (err?.response?.status === 404) {\n setConfig(null);\n setError(null);\n } else {\n setError('Failed to load federation configuration');\n }\n } finally {\n setLoading(false);\n }\n }, []);\n\n useEffect(() => {\n fetchConfig();\n }, [fetchConfig]);\n\n /**\n * Trigger a federation sync for a specific source.\n */\n const handleSync = async (source: string) => {\n setSyncing(source);\n try {\n const response = await axios.post(`/api/federation/sync?source=${source}`);\n const data = response.data;\n const totalSynced = data.total_synced || 0;\n setLastSyncTime(new Date().toISOString());\n setLastSyncResults(data.results || null);\n onShowToast(`Sync completed: ${totalSynced} items synced from ${source}`, 'success');\n } catch (err: any) {\n const detail = err?.response?.data?.detail || 'Sync failed';\n onShowToast(`Sync failed for ${source}: ${detail}`, 'error');\n } finally {\n setSyncing(null);\n }\n };\n\n /**\n * Trigger sync for all enabled sources.\n */\n const handleSyncAll = async () => {\n setSyncing('all');\n try {\n const response = await axios.post('/api/federation/sync');\n const data = response.data;\n const totalSynced = data.total_synced || 0;\n setLastSyncTime(new Date().toISOString());\n setLastSyncResults(data.results || null);\n onShowToast(`Sync completed: ${totalSynced} total items synced`, 'success');\n } catch (err: any) {\n const detail = err?.response?.data?.detail || 'Sync failed';\n onShowToast(`Sync failed: ${detail}`, 'error');\n } finally {\n setSyncing(null);\n }\n };\n\n /**\n * Show the confirm modal before deleting an entry.\n */\n const handleDeleteEntry = (\n source: 'aws_registry' | 'anthropic' | 'asor',\n identifier: string,\n ) => {\n setConfirmDelete({ source, identifier });\n };\n\n /**\n * Execute the deletion after user confirms via modal.\n */\n const executeDelete = async () => {\n if (!confirmDelete) return;\n\n const { source, identifier } = confirmDelete;\n setDeletingItem(identifier);\n try {\n if (source === 'anthropic') {\n await axios.delete(\n `/api/federation/config/default/anthropic/servers/${encodeURIComponent(identifier)}`\n );\n } else if (source === 'asor') {\n await axios.delete(\n `/api/federation/config/default/asor/agents/${encodeURIComponent(identifier)}`\n );\n } else if (source === 'aws_registry') {\n await axios.delete(\n `/api/federation/config/default/aws_registry/registries/${encodeURIComponent(identifier)}`\n );\n }\n onShowToast(`Removed \"${identifier}\"`, 'success');\n fetchConfig();\n } catch (err: any) {\n const detail = err?.response?.data?.detail || 'Failed to remove entry';\n onShowToast(detail, 'error');\n } finally {\n setDeletingItem(null);\n setConfirmDelete(null);\n }\n };\n\n /**\n * Called after successfully adding a new entry via the modal.\n */\n const handleAddSuccess = () => {\n fetchConfig();\n };\n\n // Loading state\n if (loading) {\n return (\n
\n
\n
\n );\n }\n\n // Error state\n if (error) {\n return (\n
\n \n

{error}

\n \n Retry\n \n
\n );\n }\n\n // No config state\n if (!config) {\n return (\n
\n \n

\n No Federation Configuration\n

\n

\n Federation configuration has not been set up yet.\n Use the CLI or API to create a federation config.\n

\n
\n );\n }\n\n // Count enabled sources\n const enabledSources: string[] = [];\n if (config.anthropic.enabled) enabledSources.push('anthropic');\n if (config.aws_registry.enabled) enabledSources.push('aws_registry');\n if (config.asor.enabled) enabledSources.push('asor');\n\n return (\n
\n {/* Header */}\n
\n
\n

\n External Registries\n

\n

\n {enabledSources.length} source{enabledSources.length !== 1 ? 's' : ''} configured\n {lastSyncTime && (\n \n | Last sync: {_formatRelativeTime(lastSyncTime)}\n \n )}\n

\n
\n \n \n {syncing === 'all' ? 'Syncing...' : 'Sync All'}\n \n
\n\n {/* Registry cards */}\n
\n {/* AWS Agent Registry */}\n {_renderAgentCoreCard(\n config.aws_registry, syncing, lastSyncResults, handleSync,\n () => setAddModalSource('aws_registry'),\n (id) => handleDeleteEntry('aws_registry', id),\n deletingItem,\n )}\n\n {/* Anthropic */}\n {_renderAnthropicCard(\n config.anthropic, syncing, lastSyncResults, handleSync,\n () => setAddModalSource('anthropic'),\n (name) => handleDeleteEntry('anthropic', name),\n deletingItem,\n )}\n\n {/* ASOR */}\n {_renderAsorCard(\n config.asor, syncing, lastSyncResults, handleSync,\n () => setAddModalSource('asor'),\n (id) => handleDeleteEntry('asor', id),\n deletingItem,\n )}\n
\n\n {/* Add Entry Modal */}\n {addModalSource && (\n setAddModalSource(null)}\n sourceType={addModalSource}\n onSuccess={handleAddSuccess}\n onShowToast={onShowToast}\n />\n )}\n\n {/* Delete Confirmation Modal */}\n {confirmDelete && (\n setConfirmDelete(null)}\n onConfirm={executeDelete}\n title=\"Remove Entry\"\n message={`Are you sure you want to remove \"${confirmDelete.identifier}\"? Any servers, agents, and skills synced from this source will also be deregistered.`}\n confirmLabel=\"Remove\"\n isDestructive={true}\n isLoading={deletingItem !== null}\n />\n )}\n
\n );\n};\n\n\n/**\n * Render the AWS Agent Registry card.\n */\nfunction _renderAgentCoreCard(\n agentcore: AgentCoreConfig,\n syncing: string | null,\n lastSyncResults: SyncResults | null,\n onSync: (source: string) => void,\n onAdd: () => void,\n onRemove: (registryId: string) => void,\n deletingItem: string | null,\n): React.ReactNode {\n return (\n
\n {/* Card header */}\n
\n
\n
\n \n
\n
\n

\n AWS Agent Registry\n

\n
\n \n {agentcore.enabled ? 'Enabled' : 'Disabled'}\n \n {agentcore.sync_on_startup && (\n \n Sync on startup\n \n )}\n
\n
\n
\n {agentcore.enabled && (\n
\n \n \n Add\n \n onSync('aws_registry')}\n disabled={syncing !== null}\n className=\"inline-flex items-center px-3 py-1.5 text-sm font-medium rounded-lg\n border border-gray-300 dark:border-gray-600 text-gray-700\n dark:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-700\n disabled:opacity-50 disabled:cursor-not-allowed transition-colors\"\n >\n \n {syncing === 'aws_registry' ? 'Syncing...' : 'Sync'}\n \n
\n )}\n
\n\n {/* Config details */}\n {agentcore.enabled && (\n
\n
\n
\n Region:\n \n {agentcore.aws_region}\n \n
\n
\n Sync interval:\n \n {agentcore.sync_interval_minutes} min\n \n
\n
\n Timeout:\n \n {agentcore.sync_timeout_seconds}s\n \n
\n
\n Concurrency:\n \n {agentcore.max_concurrent_fetches}\n \n
\n
\n\n {/* Registry list */}\n {agentcore.registries.length > 0 && (\n
\n

\n Registries ({agentcore.registries.length})\n

\n
\n {agentcore.registries.map((reg, idx) => (\n \n
\n
\n {reg.registry_id}\n
\n onRemove(reg.registry_id)}\n disabled={deletingItem === reg.registry_id}\n className=\"ml-2 flex-shrink-0 p-0.5 text-gray-400 hover:text-red-500\n dark:hover:text-red-400 disabled:opacity-50 transition-colors\"\n title=\"Remove registry\"\n >\n \n \n
\n
\n {reg.aws_region && (\n \n {reg.aws_region}\n \n )}\n {reg.aws_account_id && (\n \n Account: {reg.aws_account_id}\n \n )}\n \n Status: {reg.sync_status_filter}\n \n {reg.descriptor_types.map((dt) => (\n \n {dt}\n \n ))}\n
\n {reg.assume_role_arn && (\n
\n Role: {_truncateArn(reg.assume_role_arn)}\n
\n )}\n
\n ))}\n
\n
\n )}\n\n {/* Last sync results */}\n {lastSyncResults?.aws_registry && lastSyncResults.aws_registry.count > 0 && (\n
\n
\n \n \n Last sync: {lastSyncResults.aws_registry.count} items\n \n
\n
\n {lastSyncResults.aws_registry.servers.length > 0 && (\n Servers: {lastSyncResults.aws_registry.servers.length} \n )}\n {lastSyncResults.aws_registry.agents.length > 0 && (\n Agents: {lastSyncResults.aws_registry.agents.length} \n )}\n {lastSyncResults.aws_registry.skills.length > 0 && (\n Skills: {lastSyncResults.aws_registry.skills.length}\n )}\n
\n
\n )}\n
\n )}\n
\n );\n}\n\n\n/**\n * Render the Anthropic registry card.\n */\nfunction _renderAnthropicCard(\n anthropic: AnthropicConfig,\n syncing: string | null,\n lastSyncResults: SyncResults | null,\n onSync: (source: string) => void,\n onAdd: () => void,\n onRemove: (serverName: string) => void,\n deletingItem: string | null,\n): React.ReactNode {\n return (\n
\n {/* Card header */}\n
\n
\n
\n \n
\n
\n

\n Anthropic\n

\n
\n \n {anthropic.enabled ? 'Enabled' : 'Disabled'}\n \n {anthropic.sync_on_startup && (\n \n Sync on startup\n \n )}\n
\n
\n
\n {anthropic.enabled && (\n
\n \n \n Add\n \n onSync('anthropic')}\n disabled={syncing !== null}\n className=\"inline-flex items-center px-3 py-1.5 text-sm font-medium rounded-lg\n border border-gray-300 dark:border-gray-600 text-gray-700\n dark:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-700\n disabled:opacity-50 disabled:cursor-not-allowed transition-colors\"\n >\n \n {syncing === 'anthropic' ? 'Syncing...' : 'Sync'}\n \n
\n )}\n
\n\n {/* Config details */}\n {anthropic.enabled && (\n
\n
\n Endpoint:\n \n {anthropic.endpoint}\n \n
\n\n {/* Server list */}\n {anthropic.servers.length > 0 && (\n
\n

\n Servers ({anthropic.servers.length})\n

\n
\n {anthropic.servers.map((srv) => (\n \n \n {srv.name}\n onRemove(srv.name)}\n disabled={deletingItem === srv.name}\n className=\"ml-1.5 text-gray-400 hover:text-red-500 dark:hover:text-red-400\n disabled:opacity-50 transition-colors\"\n title=\"Remove server\"\n >\n \n \n \n ))}\n
\n
\n )}\n\n {/* Last sync results */}\n {lastSyncResults?.anthropic && lastSyncResults.anthropic.count > 0 && (\n
\n
\n \n \n Last sync: {lastSyncResults.anthropic.count} servers\n \n
\n
\n )}\n
\n )}\n
\n );\n}\n\n\n/**\n * Render the ASOR registry card.\n */\nfunction _renderAsorCard(\n asor: AsorConfig,\n syncing: string | null,\n lastSyncResults: SyncResults | null,\n onSync: (source: string) => void,\n onAdd: () => void,\n onRemove: (agentId: string) => void,\n deletingItem: string | null,\n): React.ReactNode {\n return (\n
\n {/* Card header */}\n
\n
\n
\n \n
\n
\n

\n ASOR\n

\n
\n \n {asor.enabled ? 'Enabled' : 'Disabled'}\n \n {asor.sync_on_startup && (\n \n Sync on startup\n \n )}\n
\n
\n
\n {asor.enabled && (\n
\n \n \n Add\n \n onSync('asor')}\n disabled={syncing !== null}\n className=\"inline-flex items-center px-3 py-1.5 text-sm font-medium rounded-lg\n border border-gray-300 dark:border-gray-600 text-gray-700\n dark:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-700\n disabled:opacity-50 disabled:cursor-not-allowed transition-colors\"\n >\n \n {syncing === 'asor' ? 'Syncing...' : 'Sync'}\n \n
\n )}\n
\n\n {/* Config details */}\n {asor.enabled && (\n
\n {asor.endpoint && (\n
\n Endpoint:\n \n {asor.endpoint}\n \n
\n )}\n\n {asor.agents.length > 0 && (\n
\n

\n Agents ({asor.agents.length})\n

\n
\n {asor.agents.map((agent) => (\n \n {agent.id}\n onRemove(agent.id)}\n disabled={deletingItem === agent.id}\n className=\"ml-1.5 text-gray-400 hover:text-red-500 dark:hover:text-red-400\n disabled:opacity-50 transition-colors\"\n title=\"Remove agent\"\n >\n \n \n \n ))}\n
\n
\n )}\n\n {/* Last sync results */}\n {lastSyncResults?.asor && lastSyncResults.asor.count > 0 && (\n
\n
\n \n \n Last sync: {lastSyncResults.asor.count} agents\n \n
\n
\n )}\n
\n )}\n
\n );\n}\n\n\n/**\n * Simple globe icon wrapper (GlobeAltIcon from heroicons).\n */\nfunction GlobeIcon(props: React.ComponentProps<'svg'>) {\n return (\n \n \n \n );\n}\n\n\nexport default ExternalRegistries;\n" }, { "path": "frontend/src/components/FederationPeerForm.tsx", "content": "import React, { useState, useEffect } from 'react';\nimport { useNavigate } from 'react-router-dom';\nimport {\n ArrowLeftIcon,\n ArrowPathIcon,\n ExclamationCircleIcon,\n} from '@heroicons/react/24/outline';\nimport {\n useFederationPeer,\n createPeer,\n updatePeer,\n PeerFormData,\n} from '../hooks/useFederationPeers';\n\n\n/**\n * Props for the FederationPeerForm component.\n */\ninterface FederationPeerFormProps {\n peerId?: string;\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\n\n/**\n * Form validation errors interface.\n */\ninterface FormErrors {\n peer_id?: string;\n name?: string;\n endpoint?: string;\n federation_token?: string;\n sync_interval_minutes?: string;\n whitelist?: string;\n tag_filters?: string;\n}\n\n\n/**\n * FederationPeerForm component for adding or editing a peer registry.\n *\n * Provides a form with validation for configuring peer connection settings,\n * authentication, and sync options.\n */\nconst FederationPeerForm: React.FC = ({\n peerId,\n onShowToast,\n}) => {\n const navigate = useNavigate();\n const isEditMode = !!peerId;\n\n const { peer, isLoading: isLoadingPeer, error: loadError } = useFederationPeer(peerId);\n\n // Form state\n const [formData, setFormData] = useState({\n peer_id: '',\n name: '',\n endpoint: '',\n enabled: true,\n sync_mode: 'all',\n whitelist_servers: [],\n whitelist_agents: [],\n tag_filters: [],\n sync_interval_minutes: 60,\n federation_token: '',\n });\n\n // Whitelist and tags as comma-separated strings for easier editing\n const [whitelistText, setWhitelistText] = useState('');\n const [tagFiltersText, setTagFiltersText] = useState('');\n\n // Form state\n const [errors, setErrors] = useState({});\n const [isSubmitting, setIsSubmitting] = useState(false);\n\n // Populate form in edit mode\n useEffect(() => {\n if (peer) {\n setFormData({\n peer_id: peer.peer_id,\n name: peer.name,\n endpoint: peer.endpoint,\n enabled: peer.enabled,\n sync_mode: peer.sync_mode,\n whitelist_servers: peer.whitelist_servers || [],\n whitelist_agents: peer.whitelist_agents || [],\n tag_filters: peer.tag_filters || [],\n sync_interval_minutes: peer.sync_interval_minutes,\n federation_token: '', // Don't populate token for security\n });\n\n // Combine whitelists for display\n const whitelistItems = [\n ...(peer.whitelist_servers || []).map((s) => `server:${s}`),\n ...(peer.whitelist_agents || []).map((a) => `agent:${a}`),\n ];\n setWhitelistText(whitelistItems.join(', '));\n setTagFiltersText((peer.tag_filters || []).join(', '));\n }\n }, [peer]);\n\n /**\n * Handle input field changes.\n */\n const handleChange = (\n e: React.ChangeEvent\n ) => {\n const { name, value, type } = e.target;\n const newValue = type === 'checkbox' ? (e.target as HTMLInputElement).checked : value;\n\n setFormData((prev) => ({\n ...prev,\n [name]: name === 'sync_interval_minutes' ? parseInt(value) || 60 : newValue,\n }));\n\n // Clear error for this field\n if (errors[name as keyof FormErrors]) {\n setErrors((prev) => ({ ...prev, [name]: undefined }));\n }\n };\n\n /**\n * Validate form data.\n */\n const validateForm = (): boolean => {\n const newErrors: FormErrors = {};\n\n // Peer ID validation\n if (!formData.peer_id.trim()) {\n newErrors.peer_id = 'Peer ID is required';\n } else if (!/^[a-zA-Z0-9-_]+$/.test(formData.peer_id)) {\n newErrors.peer_id = 'Peer ID must be alphanumeric with dashes or underscores only';\n }\n\n // Name validation\n if (!formData.name.trim()) {\n newErrors.name = 'Display name is required';\n }\n\n // Endpoint validation\n if (!formData.endpoint.trim()) {\n newErrors.endpoint = 'Endpoint URL is required';\n } else if (!formData.endpoint.startsWith('http://') && !formData.endpoint.startsWith('https://')) {\n newErrors.endpoint = 'Endpoint must be a valid HTTP or HTTPS URL';\n }\n\n // Token validation (required for new peers)\n if (!isEditMode && !formData.federation_token?.trim()) {\n newErrors.federation_token = 'Federation token is required';\n }\n\n // Sync interval validation\n if (formData.sync_interval_minutes < 5 || formData.sync_interval_minutes > 1440) {\n newErrors.sync_interval_minutes = 'Sync interval must be between 5 and 1440 minutes';\n }\n\n // Whitelist validation when sync_mode is 'whitelist'\n if (formData.sync_mode === 'whitelist') {\n const items = whitelistText.split(',').map((s) => s.trim()).filter(Boolean);\n if (items.length === 0) {\n newErrors.whitelist = 'At least one whitelist item is required';\n }\n }\n\n // Tag filter validation when sync_mode is 'tag_filter'\n if (formData.sync_mode === 'tag_filter') {\n const tags = tagFiltersText.split(',').map((s) => s.trim()).filter(Boolean);\n if (tags.length === 0) {\n newErrors.tag_filters = 'At least one tag is required';\n }\n }\n\n setErrors(newErrors);\n return Object.keys(newErrors).length === 0;\n };\n\n /**\n * Handle form submission.\n */\n const handleSubmit = async (e: React.FormEvent) => {\n e.preventDefault();\n\n if (!validateForm()) {\n return;\n }\n\n setIsSubmitting(true);\n\n try {\n // Parse whitelist items\n const whitelistItems = whitelistText.split(',').map((s) => s.trim()).filter(Boolean);\n const whitelistServers: string[] = [];\n const whitelistAgents: string[] = [];\n\n for (const item of whitelistItems) {\n if (item.startsWith('server:')) {\n whitelistServers.push(item.substring(7));\n } else if (item.startsWith('agent:')) {\n whitelistAgents.push(item.substring(6));\n } else {\n // Default to server if no prefix\n whitelistServers.push(item);\n }\n }\n\n // Parse tag filters\n const tagFilters = tagFiltersText.split(',').map((s) => s.trim()).filter(Boolean);\n\n const payload: PeerFormData = {\n ...formData,\n whitelist_servers: whitelistServers,\n whitelist_agents: whitelistAgents,\n tag_filters: tagFilters,\n };\n\n // Don't send empty token on edit (keep existing)\n if (isEditMode && !payload.federation_token) {\n delete payload.federation_token;\n }\n\n if (isEditMode) {\n await updatePeer(peerId!, payload);\n onShowToast(`Peer \"${formData.name}\" has been updated`, 'success');\n } else {\n await createPeer(payload);\n onShowToast(`Peer \"${formData.name}\" has been added`, 'success');\n }\n\n navigate('/settings/federation/peers');\n } catch (err: any) {\n const errorMessage =\n err.response?.data?.detail ||\n err.message ||\n `Failed to ${isEditMode ? 'update' : 'create'} peer`;\n onShowToast(errorMessage, 'error');\n } finally {\n setIsSubmitting(false);\n }\n };\n\n // Loading state for edit mode\n if (isEditMode && isLoadingPeer) {\n return (\n
\n
\n
\n {[1, 2, 3, 4, 5].map((i) => (\n
\n ))}\n
\n
\n );\n }\n\n // Error state for edit mode\n if (isEditMode && loadError) {\n return (\n
\n \n

\n Failed to Load Peer\n

\n

{loadError}

\n navigate('/settings/federation/peers')}\n className=\"px-4 py-2 bg-gray-200 dark:bg-gray-700 text-gray-800 dark:text-gray-200\n rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600\"\n >\n Back to Peers\n \n
\n );\n }\n\n return (\n
\n {/* Header */}\n
\n
\n

\n {isEditMode ? 'Edit Peer' : 'Add Peer'}\n

\n

\n {isEditMode\n ? 'Update peer registry configuration'\n : 'Configure a new peer registry for federation'}\n

\n
\n navigate('/settings/federation/peers')}\n className=\"flex items-center text-gray-600 dark:text-gray-400\n hover:text-gray-900 dark:hover:text-white transition-colors\"\n >\n \n Back to List\n \n
\n\n
\n {/* Basic Information */}\n
\n

\n Basic Information\n

\n\n {/* Peer ID */}\n
\n \n Peer ID *\n \n \n {errors.peer_id && (\n

{errors.peer_id}

\n )}\n

\n Unique identifier for this peer (alphanumeric, dashes, underscores)\n

\n
\n\n {/* Display Name */}\n
\n \n Display Name *\n \n \n {errors.name && (\n

{errors.name}

\n )}\n
\n\n {/* Endpoint URL */}\n
\n \n Endpoint URL *\n \n \n {errors.endpoint && (\n

{errors.endpoint}

\n )}\n

\n Base URL of the peer registry API\n

\n
\n\n {/* Enabled toggle */}\n
\n \n \n Enable sync from this peer\n \n
\n
\n\n {/* Authentication */}\n
\n

\n Authentication\n

\n\n {/* Federation Token */}\n
\n \n Federation Static Token {!isEditMode && *}\n \n \n {errors.federation_token && (\n

{errors.federation_token}

\n )}\n

\n {isEditMode\n ? 'Leave blank to keep existing token, or enter a new value to update'\n : 'The FEDERATION_STATIC_TOKEN value from the peer registry'}\n

\n
\n
\n\n {/* Sync Configuration */}\n
\n

\n Sync Configuration\n

\n\n {/* Sync Mode */}\n
\n \n Sync Mode\n \n \n \n \n \n \n
\n\n {/* Whitelist (shown when sync_mode is 'whitelist') */}\n {formData.sync_mode === 'whitelist' && (\n
\n \n Whitelist Items\n \n setWhitelistText(e.target.value)}\n placeholder=\"server:/finance-tools, agent:/code-reviewer\"\n rows={3}\n className={`w-full px-3 py-2 border rounded-lg bg-white dark:bg-gray-900\n text-gray-900 dark:text-white\n ${errors.whitelist ? 'border-red-500' : 'border-gray-300 dark:border-gray-600'}\n focus:ring-2 focus:ring-purple-500 focus:border-transparent`}\n />\n {errors.whitelist && (\n

{errors.whitelist}

\n )}\n

\n Comma-separated list. Prefix with \"server:\" or \"agent:\" (default: server)\n

\n
\n )}\n\n {/* Tag Filters (shown when sync_mode is 'tag_filter') */}\n {formData.sync_mode === 'tag_filter' && (\n
\n \n Tag Filters\n \n setTagFiltersText(e.target.value)}\n placeholder=\"production, approved, finance\"\n className={`w-full px-3 py-2 border rounded-lg bg-white dark:bg-gray-900\n text-gray-900 dark:text-white\n ${errors.tag_filters ? 'border-red-500' : 'border-gray-300 dark:border-gray-600'}\n focus:ring-2 focus:ring-purple-500 focus:border-transparent`}\n />\n {errors.tag_filters && (\n

{errors.tag_filters}

\n )}\n

\n Comma-separated list of tags. Only items with these tags will be synced.\n

\n
\n )}\n\n {/* Sync Interval */}\n
\n \n Sync Interval (minutes)\n \n \n {errors.sync_interval_minutes && (\n

{errors.sync_interval_minutes}

\n )}\n

\n How often to sync from this peer (5-1440 minutes)\n

\n
\n
\n\n {/* Form Actions */}\n
\n navigate('/settings/federation/peers')}\n disabled={isSubmitting}\n className=\"px-4 py-2 bg-gray-200 dark:bg-gray-700 text-gray-800 dark:text-gray-200\n rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600 disabled:opacity-50\"\n >\n Cancel\n \n \n {isSubmitting && }\n {isEditMode ? 'Save Changes' : 'Add Peer'}\n \n
\n
\n
\n );\n};\n\nexport default FederationPeerForm;\n" }, { "path": "frontend/src/components/FederationPeers.tsx", "content": "import React, { useState, useMemo, useEffect, useRef, useCallback } from 'react';\nimport { createPortal } from 'react-dom';\nimport { useNavigate } from 'react-router-dom';\nimport {\n PlusIcon,\n MagnifyingGlassIcon,\n ArrowPathIcon,\n EllipsisVerticalIcon,\n PencilIcon,\n TrashIcon,\n PlayIcon,\n ExclamationCircleIcon,\n} from '@heroicons/react/24/outline';\nimport { Menu, Transition } from '@headlessui/react';\nimport {\n useFederationPeers,\n PeerRegistry,\n PeerWithStatus,\n deletePeer,\n syncPeer,\n} from '../hooks/useFederationPeers';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\n\n/**\n * Props for the FederationPeers component.\n */\ninterface FederationPeersProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\n\n/**\n * Health status type for peers.\n */\ntype PeerHealthStatus = 'healthy' | 'warning' | 'error' | 'unknown';\n\n\n/**\n * Get health status color classes.\n */\nfunction getHealthColorClasses(health: PeerHealthStatus): string {\n switch (health) {\n case 'healthy':\n return 'bg-green-500';\n case 'warning':\n return 'bg-yellow-500';\n case 'error':\n return 'bg-red-500';\n default:\n return 'bg-gray-400';\n }\n}\n\n\n/**\n * Format last sync time for display.\n */\nfunction formatLastSync(dateString: string | null | undefined): string {\n if (!dateString) return 'Never';\n\n const date = new Date(dateString);\n const now = new Date();\n const diffMs = now.getTime() - date.getTime();\n const diffMins = Math.floor(diffMs / (1000 * 60));\n const diffHours = Math.floor(diffMs / (1000 * 60 * 60));\n const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));\n\n if (diffMins < 1) return 'Just now';\n if (diffMins < 60) return `${diffMins}m ago`;\n if (diffHours < 24) return `${diffHours}h ago`;\n if (diffDays < 7) return `${diffDays}d ago`;\n\n return date.toLocaleDateString();\n}\n\n\n/**\n * Props for PeerActionMenu component.\n */\ninterface PeerActionMenuProps {\n peer: PeerRegistry;\n isSyncing: boolean;\n onSync: () => void;\n onEdit: () => void;\n onDelete: () => void;\n}\n\n\n/**\n * PeerActionMenu renders the action dropdown for a peer row.\n * Uses portal to escape overflow containers.\n */\nconst PeerActionMenu: React.FC = ({\n peer,\n isSyncing,\n onSync,\n onEdit,\n onDelete,\n}) => {\n const buttonRef = useRef(null);\n const [menuPosition, setMenuPosition] = useState({ top: 0, left: 0 });\n\n const updatePosition = useCallback(() => {\n if (buttonRef.current) {\n const rect = buttonRef.current.getBoundingClientRect();\n setMenuPosition({\n top: rect.bottom + 4,\n left: rect.right - 192, // 192px = w-48 width\n });\n }\n }, []);\n\n return (\n \n {({ open }) => {\n // Update position when menu opens\n if (open) {\n // Use setTimeout to ensure DOM is ready\n setTimeout(updatePosition, 0);\n }\n\n return (\n <>\n \n \n \n {open &&\n createPortal(\n \n \n
\n \n {({ active }) => (\n \n {isSyncing ? (\n \n ) : (\n \n )}\n {isSyncing ? 'Syncing...' : 'Sync Now'}\n \n )}\n \n \n {({ active }) => (\n \n \n Edit\n \n )}\n \n
\n \n {({ active }) => (\n \n \n Delete\n \n )}\n \n
\n \n ,\n document.body\n )}\n \n );\n }}\n
\n );\n};\n\n\n/**\n * FederationPeers component displays a list of configured peer registries.\n *\n * Provides functionality to view, search, sync, and delete peers.\n */\nconst FederationPeers: React.FC = ({ onShowToast }) => {\n const navigate = useNavigate();\n const { peers, isLoading, error, refetch } = useFederationPeers();\n\n const [searchQuery, setSearchQuery] = useState('');\n const [syncingPeers, setSyncingPeers] = useState>(new Set());\n const [deleteTarget, setDeleteTarget] = useState(null);\n const [typedName, setTypedName] = useState('');\n const [isDeleting, setIsDeleting] = useState(false);\n\n useEscapeKey(() => { setDeleteTarget(null); setTypedName(''); }, !!deleteTarget);\n\n // Auto-refresh every 30 seconds for sync status updates\n useEffect(() => {\n const interval = setInterval(refetch, 30000);\n return () => clearInterval(interval);\n }, [refetch]);\n\n // Filter peers by search query\n const filteredPeers = useMemo(() => {\n if (!searchQuery) return peers;\n const query = searchQuery.toLowerCase();\n return peers.filter(\n (peer) =>\n peer.peer_id.toLowerCase().includes(query) ||\n peer.name.toLowerCase().includes(query) ||\n peer.endpoint.toLowerCase().includes(query)\n );\n }, [peers, searchQuery]);\n\n /**\n * Calculate health status for a peer based on sync status.\n */\n const getPeerHealth = (peer: PeerWithStatus): PeerHealthStatus => {\n if (!peer.enabled) return 'unknown';\n if (!peer.syncStatus) return 'unknown';\n if (peer.syncStatus.consecutive_failures > 2) return 'error';\n if (peer.syncStatus.consecutive_failures > 0) return 'warning';\n if (peer.syncStatus.is_healthy) return 'healthy';\n return 'unknown';\n };\n\n /**\n * Handle manual sync for a peer.\n */\n const handleSync = async (peer: PeerRegistry) => {\n setSyncingPeers((prev) => new Set(prev).add(peer.peer_id));\n try {\n const result = await syncPeer(peer.peer_id);\n if (result.success) {\n onShowToast(\n `Synced ${result.servers_synced} servers and ${result.agents_synced} agents from \"${peer.name}\"`,\n 'success'\n );\n } else {\n onShowToast(\n result.error_message || `Sync failed for \"${peer.name}\"`,\n 'error'\n );\n }\n await refetch();\n } catch (err: any) {\n onShowToast(\n err.response?.data?.detail || `Failed to sync \"${peer.name}\"`,\n 'error'\n );\n } finally {\n setSyncingPeers((prev) => {\n const next = new Set(prev);\n next.delete(peer.peer_id);\n return next;\n });\n }\n };\n\n /**\n * Handle peer deletion.\n */\n const handleDelete = async () => {\n if (!deleteTarget || typedName !== deleteTarget.name) return;\n\n setIsDeleting(true);\n try {\n await deletePeer(deleteTarget.peer_id);\n onShowToast(`Peer \"${deleteTarget.name}\" has been deleted`, 'success');\n setDeleteTarget(null);\n setTypedName('');\n await refetch();\n } catch (err: any) {\n onShowToast(\n err.response?.data?.detail || `Failed to delete peer`,\n 'error'\n );\n } finally {\n setIsDeleting(false);\n }\n };\n\n /**\n * Get sync mode display text.\n */\n const getSyncModeLabel = (peer: PeerRegistry): string => {\n switch (peer.sync_mode) {\n case 'all':\n return 'All Public';\n case 'whitelist':\n return 'Whitelist';\n case 'tag_filter':\n return `Tags: ${peer.tag_filters?.join(', ') || 'None'}`;\n default:\n return peer.sync_mode;\n }\n };\n\n // Loading state\n if (isLoading) {\n return (\n
\n
\n
\n
\n
\n
\n
\n {[1, 2, 3].map((i) => (\n \n ))}\n
\n
\n );\n }\n\n // Error state\n if (error) {\n return (\n
\n \n

\n Failed to Load Peers\n

\n

{error}

\n \n Retry\n \n
\n );\n }\n\n return (\n
\n {/* Header */}\n
\n
\n

\n Federation Peers\n

\n

\n Manage peer registries for cross-registry synchronization\n

\n
\n navigate('/settings/federation/peers/add')}\n className=\"flex items-center px-4 py-2 bg-purple-600 text-white rounded-lg\n hover:bg-purple-700 transition-colors\"\n >\n \n Add Peer\n \n
\n\n {/* Search */}\n
\n \n setSearchQuery(e.target.value)}\n placeholder=\"Search peers...\"\n className=\"w-full pl-10 pr-4 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n\n {/* Peers table */}\n {filteredPeers.length === 0 ? (\n
\n \n \n \n

\n {searchQuery ? 'No matching peers' : 'No peers configured'}\n

\n

\n {searchQuery\n ? 'Try a different search term'\n : 'Add a peer registry to enable federation'}\n

\n {!searchQuery && (\n navigate('/settings/federation/peers/add')}\n className=\"px-4 py-2 bg-purple-600 text-white rounded-lg hover:bg-purple-700\"\n >\n Add First Peer\n \n )}\n
\n ) : (\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n {filteredPeers.map((peer) => {\n const health = getPeerHealth(peer);\n const isSyncing = syncingPeers.has(peer.peer_id);\n\n return (\n \n \n \n \n \n \n \n \n \n );\n })}\n \n
\n Name\n \n Endpoint\n \n Status\n \n Sync Mode\n \n Interval\n \n Last Sync\n \n Actions\n
\n
\n \n {peer.name}\n \n \n {peer.peer_id}\n \n
\n 		\n \n {peer.endpoint}\n \n \n
\n \n \n {peer.enabled ? 'Enabled' : 'Disabled'}\n \n
\n 		\n \n {getSyncModeLabel(peer)}\n \n \n {peer.sync_interval_minutes}m\n \n \n {formatLastSync(peer.syncStatus?.last_successful_sync)}\n \n \n handleSync(peer)}\n onEdit={() => navigate(`/settings/federation/peers/${peer.peer_id}/edit`)}\n onDelete={() => setDeleteTarget(peer)}\n />\n
\n
\n )}\n\n {/* Delete confirmation modal */}\n {deleteTarget && (\n
\n
\n

\n Delete Peer\n

\n

\n This action is irreversible. All servers and agents synced from this\n peer will be removed.\n

\n

\n Type {deleteTarget.name} to confirm:\n

\n setTypedName(e.target.value)}\n placeholder={deleteTarget.name}\n disabled={isDeleting}\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white mb-4\"\n />\n
\n {\n setDeleteTarget(null);\n setTypedName('');\n }}\n disabled={isDeleting}\n className=\"px-4 py-2 bg-gray-200 dark:bg-gray-700 text-gray-800 dark:text-gray-200\n rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600 disabled:opacity-50\"\n >\n Cancel\n \n \n {isDeleting && }\n Delete\n \n
\n
\n
\n )}\n
\n );\n};\n\nexport default FederationPeers;\n" }, { "path": "frontend/src/components/IAMGroups.tsx", "content": "import React, { useState, useMemo, useCallback } from 'react';\nimport {\n PlusIcon,\n MagnifyingGlassIcon,\n TrashIcon,\n ArrowLeftIcon,\n ArrowPathIcon,\n ArrowDownTrayIcon,\n DocumentArrowUpIcon,\n ChevronDownIcon,\n ChevronRightIcon,\n XMarkIcon,\n PencilIcon,\n} from '@heroicons/react/24/outline';\nimport {\n useIAMGroups,\n createGroup,\n deleteGroup,\n getGroup,\n updateGroup,\n CreateGroupPayload,\n GroupDetail,\n UpdateGroupPayload,\n} from '../hooks/useIAM';\nimport { useServerList, useServerTools } from '../hooks/useToolCatalog';\nimport { useAgentList } from '../hooks/useAgentList';\nimport DeleteConfirmation from './DeleteConfirmation';\nimport SearchableSelect from './SearchableSelect';\n\ninterface IAMGroupsProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\ntype View = 'list' | 'create' | 'edit';\n\n// ─── Server access entry shape ──────────────────────────────────\ninterface ServerAccessEntry {\n server: string;\n methods: string[];\n tools: string[]; // array of selected tool names\n}\n\n// ─── Available ui_permissions keys from scopes.yml ──────────────\nconst UI_PERMISSION_KEYS = [\n { key: 'list_service', label: 'List Services' },\n { key: 'register_service', label: 'Register Service' },\n { key: 'health_check_service', label: 'Health Check Service' },\n { key: 'toggle_service', label: 'Toggle Service' },\n { key: 'modify_service', label: 'Modify Service' },\n { key: 'delete_service', label: 'Delete Service' },\n { key: 'list_agents', label: 'List Agents' },\n { key: 'get_agent', label: 'Get Agent' },\n { key: 'publish_agent', label: 'Publish Agent' },\n { key: 'modify_agent', label: 'Modify Agent' },\n { key: 'delete_agent', label: 'Delete Agent' },\n];\n\nconst COMMON_METHODS = [\n 'initialize',\n 'notifications/initialized',\n 'ping',\n 'tools/list',\n 'tools/call',\n 'resources/list',\n 'resources/templates/list',\n 'GET',\n 'POST',\n 'PUT',\n 'DELETE',\n];\n\n// Example scope JSON matching the format from scripts/registry-admins.json\nconst EXAMPLE_SCOPE_JSON = {\n scope_name: 'currenttime-users',\n description: 'Users with access to currenttime server',\n server_access: [\n {\n server: 'currenttime',\n methods: ['initialize', 'tools/list', 'tools/call'],\n tools: ['current_time_by_timezone'],\n },\n ],\n group_mappings: ['currenttime-users'],\n ui_permissions: {\n list_service: ['currenttime'],\n health_check_service: ['currenttime'],\n },\n create_in_idp: false,\n};\n\n// Default entry has all methods selected\nconst EMPTY_SERVER_ENTRY: ServerAccessEntry = { server: '', methods: [...COMMON_METHODS], tools: [] };\n\n\n/**\n * Sub-component for selecting tools for a specific server.\n * Uses useServerTools hook to fetch available tools and SearchableSelect for UI.\n */\ninterface ServerToolsSelectorProps {\n serverPath: string;\n selectedTools: string[];\n onChange: (tools: string[]) => void;\n}\n\nconst ServerToolsSelector: React.FC = ({\n serverPath,\n selectedTools,\n onChange,\n}) => {\n const { tools, isLoading } = useServerTools(serverPath);\n\n // Handle adding a tool\n const handleAddTool = (toolName: string) => {\n if (!toolName) return;\n\n // If selecting wildcard, replace all with just wildcard\n if (toolName === '*') {\n onChange(['*']);\n return;\n }\n\n // If wildcard is already selected, don't add specific tools\n if (selectedTools.includes('*')) {\n return;\n }\n\n // Add tool if not already selected\n if (!selectedTools.includes(toolName)) {\n onChange([...selectedTools, toolName]);\n }\n };\n\n // Handle removing a tool\n const handleRemoveTool = (toolName: string) => {\n onChange(selectedTools.filter((t) => t !== toolName));\n };\n\n // If server is wildcard, show message\n if (serverPath === '*') {\n return (\n
\n \n

All tools on all servers

\n
\n );\n }\n\n // If no server selected, show disabled state\n if (!serverPath) {\n return (\n
\n \n

Select a server first

\n
\n );\n }\n\n // If wildcard is selected, show that with remove option\n if (selectedTools.includes('*')) {\n return (\n
\n \n
\n \n * (All tools)\n handleRemoveTool('*')}\n className=\"ml-1 hover:text-purple-900 dark:hover:text-purple-100\"\n >\n \n \n \n
\n
\n );\n }\n\n // Build options from available tools, excluding already selected\n const availableOptions = tools\n .filter((t) => !selectedTools.includes(t.name))\n .map((t) => ({\n value: t.name,\n label: t.name,\n description: t.description,\n }));\n\n return (\n
\n \n
\n {/* Selected tools as removable tags */}\n {selectedTools.length > 0 && (\n
\n {selectedTools.map((toolName) => (\n \n {toolName}\n handleRemoveTool(toolName)}\n className=\"ml-1 hover:text-purple-900 dark:hover:text-purple-100\"\n >\n \n \n \n ))}\n
\n )}\n\n {/* Searchable tool selector */}\n \n
\n
\n );\n};\n\n\n/**\n * Build the full scope JSON from form state for preview and API payload.\n */\nfunction _buildScopeJson(\n name: string,\n description: string,\n serverAccess: ServerAccessEntry[],\n groupMappings: string,\n selectedAgents: string[],\n uiPermissions: Record,\n createInIdp: boolean,\n): Record {\n const result: Record = { scope_name: name };\n if (description) result.description = description;\n\n // Convert server access entries\n const access = serverAccess\n .filter((e) => e.server.trim())\n .map((e) => {\n const entry: Record = {\n server: e.server.trim().replace(/^\\/+|\\/+$/g, ''),\n methods: e.methods.length > 0 ? e.methods : ['all'],\n };\n // Tools is now an array; check for wildcard or list\n if (e.tools.includes('*')) {\n entry.tools = '*';\n } else if (e.tools.length > 0) {\n entry.tools = e.tools;\n }\n return entry;\n });\n if (access.length > 0) result.server_access = access;\n\n // Group mappings (optional)\n const mappings = groupMappings\n .split(',')\n .map((m) => m.trim())\n .filter(Boolean);\n if (mappings.length > 0) result.group_mappings = mappings;\n\n // Agent access (optional)\n if (selectedAgents.length > 0) result.agent_access = selectedAgents;\n\n // UI permissions -- only include keys that have a non-empty value\n const perms: Record = {};\n for (const [key, val] of Object.entries(uiPermissions)) {\n const items = val.split(',').map((v) => v.trim()).filter(Boolean);\n if (items.length > 0) perms[key] = items;\n }\n\n // Auto-sync UI permissions with server_access entries.\n // Normalize server paths (strip slashes) for consistent matching.\n const serverPaths = serverAccess\n .filter((e) => e.server.trim())\n .map((e) => e.server.trim());\n\n // Separate virtual servers from regular MCP servers\n const virtualServerPaths = serverPaths.filter((p) => p.startsWith('/virtual/'));\n const mcpServerPaths = serverPaths\n .filter((p) => !p.startsWith('/virtual/'))\n .map((p) => p.replace(/^\\/+|\\/+$/g, ''));\n\n // Always sync MCP server UI permissions with current server_access\n if (mcpServerPaths.length > 0) {\n perms['list_service'] = mcpServerPaths;\n perms['health_check_service'] = mcpServerPaths;\n perms['get_service'] = mcpServerPaths;\n perms['list_tools'] = mcpServerPaths;\n perms['call_tool'] = mcpServerPaths;\n } else {\n delete perms['list_service'];\n delete perms['health_check_service'];\n delete perms['get_service'];\n delete perms['list_tools'];\n delete perms['call_tool'];\n }\n\n // Always sync list_virtual_server with selected virtual servers\n if (virtualServerPaths.length > 0) {\n perms['list_virtual_server'] = virtualServerPaths;\n }\n\n // Always sync list_agents and get_agent with selected agents\n // This ensures UI permissions match the agent_access selection\n if (selectedAgents.length > 0) {\n perms['list_agents'] = selectedAgents;\n perms['get_agent'] = selectedAgents;\n }\n\n if (Object.keys(perms).length > 0) result.ui_permissions = perms;\n\n result.create_in_idp = createInIdp;\n return result;\n}\n\n\nconst IAMGroups: React.FC = ({ onShowToast }) => {\n const { groups, isLoading, error, refetch } = useIAMGroups();\n const { servers: availableServers, isLoading: serversLoading } = useServerList();\n const { agents: availableAgents, isLoading: agentsLoading } = useAgentList();\n const [searchQuery, setSearchQuery] = useState('');\n const [view, setView] = useState('list');\n\n // ─── Create form state ──────────────────────────────────────\n const [formName, setFormName] = useState('');\n const [formDescription, setFormDescription] = useState('');\n const [serverAccess, setServerAccess] = useState([{ ...EMPTY_SERVER_ENTRY }]);\n const [groupMappings, setGroupMappings] = useState('');\n const [selectedAgents, setSelectedAgents] = useState([]);\n const [uiPermissions, setUiPermissions] = useState>({});\n const [createInIdp, setCreateInIdp] = useState(false);\n const [isCreating, setIsCreating] = useState(false);\n const [showUiPermissions, setShowUiPermissions] = useState(false);\n\n // ─── Edit state ────────────────────────────────────────────\n const [editingGroup, setEditingGroup] = useState(null);\n const [groupDetail, setGroupDetail] = useState(null);\n const [isLoadingGroup, setIsLoadingGroup] = useState(false);\n const [isSaving, setIsSaving] = useState(false);\n\n // Delete state\n const [deleteTarget, setDeleteTarget] = useState(null);\n\n // Derived: read-only JSON preview\n const jsonPreview = useMemo(() => {\n if (!formName.trim()) return null;\n return JSON.stringify(\n _buildScopeJson(formName.trim(), formDescription.trim(), serverAccess, groupMappings, selectedAgents, uiPermissions, createInIdp),\n null,\n 2,\n );\n }, [formName, formDescription, serverAccess, groupMappings, selectedAgents, uiPermissions, createInIdp]);\n\n const filteredGroups = useMemo(() => {\n if (!searchQuery) return groups;\n const q = searchQuery.toLowerCase();\n return groups.filter(\n (g) =>\n g.name.toLowerCase().includes(q) ||\n (g.description || '').toLowerCase().includes(q)\n );\n }, [groups, searchQuery]);\n\n const resetForm = useCallback(() => {\n setFormName('');\n setFormDescription('');\n setServerAccess([{ ...EMPTY_SERVER_ENTRY }]);\n setGroupMappings('');\n setSelectedAgents([]);\n setUiPermissions({});\n setCreateInIdp(true);\n }, []);\n\n\n // ─── Handlers ─────────────────────────────────────────────────\n\n const handleCreate = async () => {\n if (!formName.trim()) return;\n setIsCreating(true);\n try {\n // Build scope_config from form state.\n // The management API currently only processes name/description.\n // scope_config is included for future backend support.\n const scopeJson = _buildScopeJson(\n formName.trim(), formDescription.trim(),\n serverAccess, groupMappings, selectedAgents, uiPermissions, createInIdp,\n );\n const { scope_name, description, ...scopeConfig } = scopeJson;\n\n const payload: CreateGroupPayload = {\n name: formName.trim(),\n description: formDescription.trim() || undefined,\n scope_config: Object.keys(scopeConfig).length > 0 ? scopeConfig : undefined,\n };\n await createGroup(payload);\n onShowToast(`Group \"${formName}\" created successfully`, 'success');\n resetForm();\n setView('list');\n await refetch();\n } catch (err: any) {\n const detail = err.response?.data?.detail;\n const message = Array.isArray(detail)\n ? detail.map((d: any) => d.msg).join(', ')\n : detail || 'Failed to create group';\n onShowToast(message, 'error');\n } finally {\n setIsCreating(false);\n }\n };\n\n const handleDelete = async (name: string) => {\n await deleteGroup(name);\n onShowToast(`Group \"${name}\" deleted`, 'success');\n setDeleteTarget(null);\n await refetch();\n };\n\n const handleEditClick = async (groupName: string) => {\n setIsLoadingGroup(true);\n setEditingGroup(groupName);\n try {\n const detail = await getGroup(groupName);\n setGroupDetail(detail);\n\n // Populate form fields with existing group data\n setFormName(detail.name);\n setFormDescription(detail.description || '');\n\n // Server access - only include entries with actual server values\n if (detail.server_access && detail.server_access.length > 0) {\n const entries: ServerAccessEntry[] = detail.server_access\n .filter((sa) => sa.server && sa.server.trim())\n .map((sa) => ({\n server: sa.server || '',\n methods: sa.methods || [],\n tools: sa.tools || [],\n }));\n setServerAccess(entries.length > 0 ? entries : [{ ...EMPTY_SERVER_ENTRY }]);\n } else {\n setServerAccess([{ ...EMPTY_SERVER_ENTRY }]);\n }\n\n // Group mappings\n if (detail.group_mappings && detail.group_mappings.length > 0) {\n setGroupMappings(detail.group_mappings.join(', '));\n } else {\n setGroupMappings('');\n }\n\n // Agent access\n if (detail.agent_access && detail.agent_access.length > 0) {\n setSelectedAgents(detail.agent_access);\n } else {\n setSelectedAgents([]);\n }\n\n // UI permissions\n if (detail.ui_permissions) {\n const perms: Record = {};\n for (const [key, val] of Object.entries(detail.ui_permissions)) {\n perms[key] = Array.isArray(val) ? val.join(', ') : String(val);\n }\n setUiPermissions(perms);\n } else {\n setUiPermissions({});\n }\n\n setCreateInIdp(true);\n setView('edit');\n } catch (err: any) {\n const detail = err.response?.data?.detail;\n const message = typeof detail === 'string' ? detail : 'Failed to load group details';\n onShowToast(message, 'error');\n setEditingGroup(null);\n } finally {\n setIsLoadingGroup(false);\n }\n };\n\n const handleUpdate = async () => {\n if (!editingGroup) return;\n setIsSaving(true);\n try {\n // Build scope_config from form state\n const serverAccessPayload = serverAccess\n .filter((e) => e.server.trim())\n .map((e) => {\n // Normalize server path: strip leading/trailing slashes for consistency\n const normalizedServer = e.server.trim().replace(/^\\/+|\\/+$/g, '');\n const entry: {server: string; methods: string[]; tools?: string[]} = {\n server: normalizedServer,\n methods: e.methods.length > 0 ? e.methods : ['all'],\n };\n if (e.tools.length > 0) {\n entry.tools = e.tools;\n }\n return entry;\n });\n\n // Build UI permissions\n const perms: Record = {};\n for (const [key, val] of Object.entries(uiPermissions)) {\n const items = val.split(',').map((v) => v.trim()).filter(Boolean);\n if (items.length > 0) perms[key] = items;\n }\n\n // Auto-sync UI permissions with server_access entries.\n // Normalize server paths (strip slashes) for consistent matching.\n const serverPaths = serverAccess\n .filter((e) => e.server.trim())\n .map((e) => e.server.trim());\n\n // Separate virtual servers from regular MCP servers\n const virtualServerPaths = serverPaths.filter((p) => p.startsWith('/virtual/'));\n const mcpServerPaths = serverPaths\n .filter((p) => !p.startsWith('/virtual/'))\n .map((p) => p.replace(/^\\/+|\\/+$/g, ''));\n\n // Always sync MCP server UI permissions with current server_access\n // (matches the virtual server sync pattern below)\n if (mcpServerPaths.length > 0) {\n perms['list_service'] = mcpServerPaths;\n perms['health_check_service'] = mcpServerPaths;\n perms['get_service'] = mcpServerPaths;\n perms['list_tools'] = mcpServerPaths;\n perms['call_tool'] = mcpServerPaths;\n } else {\n delete perms['list_service'];\n delete perms['health_check_service'];\n delete perms['get_service'];\n delete perms['list_tools'];\n delete perms['call_tool'];\n }\n\n // Always sync list_virtual_server with selected virtual servers\n if (virtualServerPaths.length > 0) {\n perms['list_virtual_server'] = virtualServerPaths;\n } else {\n // Remove virtual server permission if none selected\n delete perms['list_virtual_server'];\n }\n\n // Always sync list_agents and get_agent with selected agents\n // This ensures UI permissions match the agent_access selection\n if (selectedAgents.length > 0) {\n perms['list_agents'] = selectedAgents;\n perms['get_agent'] = selectedAgents;\n } else {\n // Remove agent permissions if no agents selected\n delete perms['list_agents'];\n delete perms['get_agent'];\n }\n\n const payload: UpdateGroupPayload = {\n description: formDescription.trim() || undefined,\n scope_config: {\n server_access: serverAccessPayload.length > 0 ? serverAccessPayload : undefined,\n ui_permissions: Object.keys(perms).length > 0 ? perms : undefined,\n agent_access: selectedAgents.length > 0 ? selectedAgents : undefined,\n },\n };\n\n await updateGroup(editingGroup, payload);\n onShowToast(`Group \"${editingGroup}\" updated successfully`, 'success');\n resetForm();\n setEditingGroup(null);\n setGroupDetail(null);\n setView('list');\n await refetch();\n } catch (err: any) {\n const detail = err.response?.data?.detail;\n const message = Array.isArray(detail)\n ? detail.map((d: any) => d.msg).join(', ')\n : detail || 'Failed to update group';\n onShowToast(message, 'error');\n } finally {\n setIsSaving(false);\n }\n };\n\n // ─── JSON upload sync ─────────────────────────────────────────\n\n const parseJsonContent = (content: string) => {\n try {\n const parsed = JSON.parse(content);\n\n // Sync all form fields from uploaded JSON\n if (parsed.scope_name) setFormName(parsed.scope_name);\n if (parsed.description) setFormDescription(parsed.description);\n if (parsed.create_in_idp !== undefined) setCreateInIdp(parsed.create_in_idp);\n\n // Group mappings (optional)\n if (Array.isArray(parsed.group_mappings)) {\n setGroupMappings(parsed.group_mappings.join(', '));\n }\n\n // Server access\n if (Array.isArray(parsed.server_access)) {\n const entries: ServerAccessEntry[] = parsed.server_access\n .filter((e: any) => e.server)\n .map((e: any) => ({\n server: e.server || '',\n methods: Array.isArray(e.methods) ? e.methods : [],\n tools: Array.isArray(e.tools) ? e.tools : (e.tools === '*' ? ['*'] : []),\n }));\n if (entries.length > 0) setServerAccess(entries);\n }\n\n // Agent access (optional)\n if (Array.isArray(parsed.agent_access)) {\n setSelectedAgents(parsed.agent_access);\n }\n\n // UI permissions\n if (parsed.ui_permissions && typeof parsed.ui_permissions === 'object') {\n const perms: Record = {};\n for (const [key, val] of Object.entries(parsed.ui_permissions)) {\n perms[key] = Array.isArray(val) ? (val as string[]).join(', ') : String(val);\n }\n setUiPermissions(perms);\n }\n\n onShowToast('JSON loaded', 'success');\n } catch {\n onShowToast('Invalid JSON file', 'error');\n }\n };\n\n const handleFileUpload = (e: React.ChangeEvent) => {\n const file = e.target.files?.[0];\n if (!file) return;\n const reader = new FileReader();\n reader.onload = (ev) => parseJsonContent(ev.target?.result as string);\n reader.readAsText(file);\n };\n\n const handleDrop = (e: React.DragEvent) => {\n e.preventDefault();\n const file = e.dataTransfer.files[0];\n if (!file) return;\n const reader = new FileReader();\n reader.onload = (ev) => parseJsonContent(ev.target?.result as string);\n reader.readAsText(file);\n };\n\n const downloadExampleJson = () => {\n const blob = new Blob([JSON.stringify(EXAMPLE_SCOPE_JSON, null, 2)], { type: 'application/json' });\n const url = URL.createObjectURL(blob);\n const a = document.createElement('a');\n a.href = url;\n a.download = 'example-group-scope.json';\n a.click();\n URL.revokeObjectURL(url);\n };\n\n // ─── Server access helpers ────────────────────────────────────\n\n const updateServerEntry = (idx: number, field: keyof ServerAccessEntry, value: any) => {\n setServerAccess((prev) => prev.map((e, i) => (i === idx ? { ...e, [field]: value } : e)));\n };\n\n const toggleMethod = (idx: number, method: string) => {\n setServerAccess((prev) =>\n prev.map((e, i) => {\n if (i !== idx) return e;\n const methods = e.methods.includes(method)\n ? e.methods.filter((m) => m !== method)\n : [...e.methods, method];\n return { ...e, methods };\n }),\n );\n };\n\n const addServerEntry = () => setServerAccess((prev) => [...prev, { ...EMPTY_SERVER_ENTRY }]);\n const removeServerEntry = (idx: number) => setServerAccess((prev) => prev.filter((_, i) => i !== idx));\n\n // ─── UI permission helpers ────────────────────────────────────\n\n const setPermValue = (key: string, value: string) => {\n setUiPermissions((prev) => {\n if (!value.trim()) {\n const next = { ...prev };\n delete next[key];\n return next;\n }\n return { ...prev, [key]: value };\n });\n };\n\n\n // ─── Create View ──────────────────────────────────────────────\n if (view === 'create') {\n return (\n
\n
\n

\n IAM > Groups > Create\n

\n { resetForm(); setView('list'); }}\n className=\"flex items-center text-sm text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-200\"\n >\n \n Back to List\n \n
\n\n {/* ── Basic Info ─────────────────────────────────────── */}\n
\n
\n \n setFormName(e.target.value)}\n placeholder=\"e.g. currenttime-users\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n
\n \n setFormDescription(e.target.value)}\n placeholder=\"Optional description\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n
\n \n setGroupMappings(e.target.value)}\n placeholder=\"e.g. currenttime-users, other-group\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n
\n setCreateInIdp(e.target.checked)}\n className=\"rounded border-gray-300 dark:border-gray-600 text-purple-600 focus:ring-purple-500\"\n />\n \n
\n
\n\n {/* ── Server Access ──────────────────────────────────── */}\n
\n
\n

Server Access

\n \n + Add Server\n \n
\n {serversLoading && (\n

Loading servers...

\n )}\n {serverAccess.map((entry, idx) => (\n
\n
\n \n Server {idx + 1}\n \n {serverAccess.length > 1 && (\n removeServerEntry(idx)}\n className=\"text-xs text-red-500 hover:underline\"\n >\n Remove\n \n )}\n
\n
\n \n ({\n value: s.path,\n label: `${s.type === 'virtual' ? '[Virtual] ' : ''}${s.name} (${s.path})`,\n description: s.description,\n }))}\n value={entry.server}\n onChange={(val) => {\n updateServerEntry(idx, 'server', val);\n // Reset tools when server changes\n updateServerEntry(idx, 'tools', []);\n }}\n placeholder=\"Search servers...\"\n isLoading={serversLoading}\n maxDescriptionWords={8}\n specialOptions={[\n { value: '*', label: '* (All servers)', description: 'Grant access to all servers' },\n ]}\n />\n
\n
\n \n
\n {COMMON_METHODS.map((method) => (\n \n ))}\n
\n
\n updateServerEntry(idx, 'tools', tools)}\n />\n
\n ))}\n
\n\n {/* ── Agent Access ──────────────────────────────────── */}\n
\n

\n Agent Access\n (optional)\n

\n {/* Selected agents as removable tags */}\n {selectedAgents.length > 0 && (\n
\n {selectedAgents.map((agentName) => (\n \n {agentName}\n setSelectedAgents((prev) => prev.filter((a) => a !== agentName))}\n className=\"ml-1 hover:text-purple-900 dark:hover:text-purple-100\"\n >\n \n \n \n ))}\n
\n )}\n {/* Searchable agent selector */}\n !selectedAgents.includes(a.path))\n .map((a) => ({\n value: a.path,\n label: `${a.name} (${a.path})`,\n description: a.description,\n }))}\n value=\"\"\n onChange={(val) => {\n if (val && !selectedAgents.includes(val)) {\n setSelectedAgents((prev) => [...prev, val]);\n }\n }}\n placeholder=\"Search and add agents...\"\n isLoading={agentsLoading}\n maxDescriptionWords={8}\n />\n
\n\n {/* ── UI Permissions (collapsible) ───────────────────── */}\n
\n setShowUiPermissions(!showUiPermissions)}\n className=\"flex items-center space-x-2 text-sm font-medium text-gray-700 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100\"\n >\n {showUiPermissions ? (\n \n ) : (\n \n )}\n \n UI Permissions\n (enter \"all\" or a comma-separated list of service/agent names)\n \n \n {showUiPermissions && (\n
\n {UI_PERMISSION_KEYS.map(({ key, label }) => (\n
\n \n setPermValue(key, e.target.value)}\n placeholder=\"e.g. all or currenttime, mcpgw\"\n className=\"w-full px-3 py-1.5 text-sm border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n ))}\n
\n )}\n
\n\n {/* ── JSON Upload / Preview ──────────────────────────── */}\n
\n

\n Or Upload JSON Configuration\n

\n e.preventDefault()}\n onDrop={handleDrop}\n className=\"border-2 border-dashed border-gray-300 dark:border-gray-600 rounded-lg p-6\n text-center hover:border-purple-400 dark:hover:border-purple-500 transition-colors\"\n >\n \n

\n Drag & drop a scope JSON file here\n

\n \n
\n\n {jsonPreview && (\n
\n

\n JSON Preview (auto-generated from form):\n

\n 
\n                {jsonPreview}\n
\n
\n )}\n\n \n \n Download Example JSON\n \n
\n\n {/* ── Actions ────────────────────────────────────────── */}\n
\n { resetForm(); setView('list'); }}\n className=\"px-4 py-2 text-sm text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700\n rounded-lg hover:bg-gray-200 dark:hover:bg-gray-600\"\n >\n Cancel\n \n \n {isCreating ? 'Creating...' : 'Create Group'}\n \n
\n
\n );\n }\n\n\n // ─── Edit View ───────────────────────────────────────────────\n if (view === 'edit') {\n return (\n
\n
\n

\n IAM > Groups > Edit: {editingGroup}\n

\n { resetForm(); setEditingGroup(null); setGroupDetail(null); setView('list'); }}\n className=\"flex items-center text-sm text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-200\"\n >\n \n Back to List\n \n
\n\n {isLoadingGroup && (\n
\n \n
\n )}\n\n {!isLoadingGroup && (\n <>\n {/* ── Basic Info ─────────────────────────────────────── */}\n
\n
\n \n \n

Group name cannot be changed

\n
\n
\n \n setFormDescription(e.target.value)}\n placeholder=\"Optional description\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n
\n \n setGroupMappings(e.target.value)}\n placeholder=\"e.g. currenttime-users, other-group\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n
\n\n {/* ── Server Access ──────────────────────────────────── */}\n
\n
\n

Server Access

\n \n + Add Server\n \n
\n {serversLoading && (\n

Loading servers...

\n )}\n {serverAccess.map((entry, idx) => (\n
\n
\n \n Server {idx + 1}\n \n {serverAccess.length > 1 && (\n removeServerEntry(idx)}\n className=\"text-xs text-red-500 hover:underline\"\n >\n Remove\n \n )}\n
\n
\n \n ({\n value: s.path,\n label: `${s.type === 'virtual' ? '[Virtual] ' : ''}${s.name} (${s.path})`,\n description: s.description,\n }))}\n value={entry.server}\n onChange={(val) => {\n updateServerEntry(idx, 'server', val);\n // Reset tools when server changes\n updateServerEntry(idx, 'tools', []);\n }}\n placeholder=\"Search servers...\"\n isLoading={serversLoading}\n maxDescriptionWords={8}\n specialOptions={[\n { value: '*', label: '* (All servers)', description: 'Grant access to all servers' },\n ]}\n />\n
\n
\n \n
\n {COMMON_METHODS.map((method) => (\n \n ))}\n
\n
\n updateServerEntry(idx, 'tools', tools)}\n />\n
\n ))}\n
\n\n {/* ── Agent Access ──────────────────────────────────── */}\n
\n

\n Agent Access\n (optional)\n

\n {/* Selected agents as removable tags */}\n {selectedAgents.length > 0 && (\n
\n {selectedAgents.map((agentName) => (\n \n {agentName}\n setSelectedAgents((prev) => prev.filter((a) => a !== agentName))}\n className=\"ml-1 hover:text-purple-900 dark:hover:text-purple-100\"\n >\n \n \n \n ))}\n
\n )}\n {/* Searchable agent selector */}\n !selectedAgents.includes(a.path))\n .map((a) => ({\n value: a.path,\n label: `${a.name} (${a.path})`,\n description: a.description,\n }))}\n value=\"\"\n onChange={(val) => {\n if (val && !selectedAgents.includes(val)) {\n setSelectedAgents((prev) => [...prev, val]);\n }\n }}\n placeholder=\"Search and add agents...\"\n isLoading={agentsLoading}\n maxDescriptionWords={8}\n />\n
\n\n {/* ── UI Permissions (collapsible) ───────────────────── */}\n
\n setShowUiPermissions(!showUiPermissions)}\n className=\"flex items-center space-x-2 text-sm font-medium text-gray-700 dark:text-gray-300 hover:text-gray-900 dark:hover:text-gray-100\"\n >\n {showUiPermissions ? (\n \n ) : (\n \n )}\n \n UI Permissions\n (enter \"all\" or a comma-separated list of service/agent names)\n \n \n {showUiPermissions && (\n
\n {UI_PERMISSION_KEYS.map(({ key, label }) => (\n
\n \n setPermValue(key, e.target.value)}\n placeholder=\"e.g. all or currenttime, mcpgw\"\n className=\"w-full px-3 py-1.5 text-sm border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n ))}\n
\n )}\n
\n\n {/* ── JSON Preview ──────────────────────────────────────── */}\n {jsonPreview && (\n
\n
\n

\n JSON Preview (auto-generated from form):\n

\n 
\n                    {jsonPreview}\n
\n
\n
\n )}\n\n {/* ── Actions ────────────────────────────────────────── */}\n
\n { resetForm(); setEditingGroup(null); setGroupDetail(null); setView('list'); }}\n className=\"px-4 py-2 text-sm text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700\n rounded-lg hover:bg-gray-200 dark:hover:bg-gray-600\"\n >\n Cancel\n \n \n {isSaving ? 'Saving...' : 'Save Changes'}\n \n
\n \n )}\n
\n );\n }\n\n\n // ─── List View ────────────────────────────────────────────────\n return (\n
\n
\n

\n IAM > Groups\n

\n
\n \n setView('create')}\n className=\"flex items-center px-3 py-2 text-sm text-white bg-purple-600 rounded-lg hover:bg-purple-700\"\n >\n \n Create Group\n \n
\n
\n\n {/* Search */}\n
\n \n setSearchQuery(e.target.value)}\n placeholder=\"Search groups...\"\n className=\"w-full pl-10 pr-4 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white text-sm\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n
\n\n {/* Loading / Error / Empty states */}\n {isLoading && (\n
\n \n
\n )}\n\n {error && !isLoading && (\n
{error}
\n )}\n\n {!isLoading && !error && filteredGroups.length === 0 && (\n
\n {searchQuery ? 'No groups match your search.' : 'No groups yet. Create your first group.'}\n
\n )}\n\n {/* Table */}\n {!isLoading && !error && filteredGroups.length > 0 && (\n
\n \n \n \n \n \n \n \n \n \n \n {filteredGroups.map((group) => (\n \n \n \n \n \n \n \n {deleteTarget === group.name && (\n \n \n \n )}\n \n ))}\n \n
NameDescriptionPathAction
{group.name}{group.description || '\\u2014'}{group.path || '\\u2014'}\n handleEditClick(group.name)}\n className=\"p-1 text-gray-400 hover:text-purple-500 dark:hover:text-purple-400 mr-1\"\n title=\"Edit group\"\n disabled={isLoadingGroup && editingGroup === group.name}\n >\n {isLoadingGroup && editingGroup === group.name ? (\n \n ) : (\n \n )}\n \n setDeleteTarget(group.name)}\n className=\"p-1 text-gray-400 hover:text-red-500 dark:hover:text-red-400\"\n title=\"Delete group\"\n >\n \n \n
\n setDeleteTarget(null)}\n />\n
\n
\n )}\n
\n );\n};\n\nexport default IAMGroups;\n" }, { "path": "frontend/src/components/IAMM2M.tsx", "content": "import React, { useState, useMemo, useCallback } from 'react';\nimport {\n PlusIcon,\n MagnifyingGlassIcon,\n TrashIcon,\n ArrowLeftIcon,\n ArrowPathIcon,\n ClipboardDocumentIcon,\n EyeIcon,\n EyeSlashIcon,\n PencilIcon,\n} from '@heroicons/react/24/outline';\nimport { useIAMUsers, useIAMGroups, createM2MAccount, deleteUser, updateUserGroups, CreateM2MPayload, M2MCredentials, IAMUser } from '../hooks/useIAM';\nimport DeleteConfirmation from './DeleteConfirmation';\n\ninterface IAMM2MProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\ntype View = 'list' | 'create' | 'credentials' | 'edit';\n\ninterface FormErrors {\n name?: string;\n groups?: string;\n}\n\nconst IAMM2M: React.FC = ({ onShowToast }) => {\n // Filter to only M2M accounts\n const { users, isLoading, error, refetch } = useIAMUsers();\n const { groups } = useIAMGroups();\n const [searchQuery, setSearchQuery] = useState('');\n const [view, setView] = useState('list');\n\n // Create form state\n const [formName, setFormName] = useState('');\n const [formDescription, setFormDescription] = useState('');\n const [formGroups, setFormGroups] = useState>(new Set());\n const [isCreating, setIsCreating] = useState(false);\n const [errors, setErrors] = useState({});\n\n // Credentials display\n const [credentials, setCredentials] = useState(null);\n const [showSecret, setShowSecret] = useState(false);\n\n // Delete state\n const [deleteTarget, setDeleteTarget] = useState(null);\n\n // Edit state\n const [editTarget, setEditTarget] = useState(null);\n const [isUpdating, setIsUpdating] = useState(false);\n\n const m2mAccounts = useMemo(() => {\n // M2M service accounts are identified by their email domain.\n // The backend sets email to \"{clientId}@service-account.local\" for all M2M accounts.\n return users.filter(\n (u) => (u.email || '').endsWith('@service-account.local')\n );\n }, [users]);\n\n const filteredAccounts = useMemo(() => {\n if (!searchQuery) return m2mAccounts;\n const q = searchQuery.toLowerCase();\n return m2mAccounts.filter(\n (u) =>\n u.username.toLowerCase().includes(q) ||\n (u.email || '').toLowerCase().includes(q)\n );\n }, [m2mAccounts, searchQuery]);\n\n const resetForm = useCallback(() => {\n setFormName('');\n setFormDescription('');\n setFormGroups(new Set());\n setErrors({});\n }, []);\n\n const toggleGroup = (groupName: string) => {\n setFormGroups((prev) => {\n const next = new Set(prev);\n if (next.has(groupName)) next.delete(groupName);\n else next.add(groupName);\n return next;\n });\n };\n\n const copyToClipboard = async (text: string, label: string) => {\n try {\n await navigator.clipboard.writeText(text);\n onShowToast(`${label} copied to clipboard`, 'info');\n } catch {\n onShowToast('Failed to copy to clipboard', 'error');\n }\n };\n\n const handleCreate = async () => {\n // Validate\n const newErrors: FormErrors = {};\n if (!formName.trim()) newErrors.name = 'Name is required';\n if (formGroups.size === 0) newErrors.groups = 'At least one group is required';\n setErrors(newErrors);\n if (Object.keys(newErrors).length > 0) return;\n\n setIsCreating(true);\n try {\n const payload: CreateM2MPayload = {\n name: formName.trim(),\n description: formDescription.trim() || undefined,\n groups: Array.from(formGroups),\n };\n const creds = await createM2MAccount(payload);\n setCredentials(creds);\n setView('credentials');\n onShowToast(`M2M account \"${formName}\" created`, 'success');\n resetForm();\n } catch (err: any) {\n const detail = err.response?.data?.detail;\n const message = Array.isArray(detail)\n ? detail.map((d: any) => d.msg).join(', ')\n : detail || 'Failed to create M2M account';\n onShowToast(message, 'error');\n } finally {\n setIsCreating(false);\n }\n };\n\n const handleDelete = async (username: string) => {\n await deleteUser(username);\n onShowToast(`Account \"${username}\" deleted`, 'success');\n setDeleteTarget(null);\n await refetch();\n };\n\n const handleEdit = (user: IAMUser) => {\n setEditTarget(user);\n setFormGroups(new Set(user.groups || []));\n setView('edit');\n };\n\n const handleUpdate = async () => {\n if (!editTarget) return;\n\n // Validate\n const newErrors: FormErrors = {};\n if (formGroups.size === 0) newErrors.groups = 'At least one group is required';\n setErrors(newErrors);\n if (Object.keys(newErrors).length > 0) return;\n\n setIsUpdating(true);\n try {\n await updateUserGroups(editTarget.username, Array.from(formGroups));\n onShowToast(`Groups updated for \"${editTarget.username}\"`, 'success');\n setEditTarget(null);\n setFormGroups(new Set());\n setView('list');\n await refetch();\n } catch (err: any) {\n const detail = err.response?.data?.detail;\n const message = Array.isArray(detail)\n ? detail.map((d: any) => d.msg).join(', ')\n : detail || 'Failed to update groups';\n onShowToast(message, 'error');\n } finally {\n setIsUpdating(false);\n }\n };\n\n // ─── Credentials View (after creation) ────────────────────────\n if (view === 'credentials' && credentials) {\n return (\n
\n

\n IAM > M2M Accounts > Credentials\n

\n\n
\n

\n M2M Account Created Successfully\n

\n\n
\n
\n
\n Client ID\n

{credentials.client_id}

\n
\n \n
\n\n
\n
\n Client Secret\n

\n {showSecret ? credentials.client_secret : '••••••••••••••••'}\n

\n
\n
\n \n \n
\n
\n
\n\n
\n

\n Save these credentials now. The client secret cannot be retrieved later.\n

\n
\n
\n\n { setCredentials(null); setShowSecret(false); setView('list'); refetch(); }}\n className=\"flex items-center text-sm text-purple-600 dark:text-purple-400 hover:underline\"\n >\n \n Back to M2M Accounts List\n \n
\n );\n }\n\n // ─── Edit View ────────────────────────────────────────────────\n if (view === 'edit' && editTarget) {\n return (\n
\n
\n

\n IAM > M2M Accounts > Edit \"{editTarget.username}\"\n

\n \n
\n\n
\n
\n \n
\n {groups.length === 0 ? (\n

No groups available

\n ) : (\n groups.map((g) => (\n \n ))\n )}\n
\n {errors.groups &&

{errors.groups}

}\n
\n
\n\n
\n \n \n
\n
\n );\n }\n\n // ─── Create View ──────────────────────────────────────────────\n if (view === 'create') {\n return (\n
\n
\n

\n IAM > M2M Accounts > Create\n

\n \n
\n\n
\n
\n \n { setFormName(e.target.value); if (errors.name) setErrors((p) => ({ ...p, name: undefined })); }}\n placeholder=\"e.g. ci-pipeline\"\n className={`w-full px-3 py-2 border rounded-lg bg-white dark:bg-gray-900 text-gray-900 dark:text-white focus:ring-2 focus:ring-purple-500 focus:border-transparent ${\n errors.name ? 'border-red-500' : 'border-gray-300 dark:border-gray-600'\n }`} />\n {errors.name &&

{errors.name}

}\n
\n
\n \n setFormDescription(e.target.value)}\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-900 text-gray-900 dark:text-white focus:ring-2 focus:ring-purple-500 focus:border-transparent\" />\n
\n\n
\n \n
\n {groups.length === 0 ? (\n

No groups available

\n ) : (\n groups.map((g) => (\n \n ))\n )}\n
\n {errors.groups &&

{errors.groups}

}\n
\n
\n\n
\n \n \n
\n
\n );\n }\n\n // ─── List View ────────────────────────────────────────────────\n return (\n
\n
\n

IAM > M2M Accounts

\n
\n \n \n
\n
\n\n
\n \n setSearchQuery(e.target.value)}\n placeholder=\"Search M2M accounts...\"\n className=\"w-full pl-10 pr-4 py-2 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-900 text-gray-900 dark:text-white text-sm focus:ring-2 focus:ring-purple-500 focus:border-transparent\" />\n
\n\n {isLoading && (\n
\n )}\n {error && !isLoading && (\n
{error}
\n )}\n {!isLoading && !error && filteredAccounts.length === 0 && (\n
\n {searchQuery ? 'No accounts match your search.' : 'No M2M accounts yet. Create your first service account.'}\n
\n )}\n\n {!isLoading && !error && filteredAccounts.length > 0 && (\n
\n \n \n \n \n \n \n \n \n \n {filteredAccounts.map((u) => (\n \n \n \n \n \n \n {deleteTarget === u.username && (\n \n \n \n )}\n \n ))}\n \n
NameGroupsAction
{u.username}\n
\n {(u.groups || []).map((g) => (\n \n {g}\n \n ))}\n {(!u.groups || u.groups.length === 0) && {'\\u2014'}}\n
\n 		\n
\n \n \n
\n
\n setDeleteTarget(null)}\n />\n
\n
\n )}\n
\n );\n};\n\nexport default IAMM2M;\n" }, { "path": "frontend/src/components/IAMUsers.tsx", "content": "import React, { useState, useMemo, useCallback } from 'react';\nimport {\n PlusIcon,\n MagnifyingGlassIcon,\n TrashIcon,\n ArrowLeftIcon,\n ArrowPathIcon,\n EyeIcon,\n EyeSlashIcon,\n PencilIcon,\n XMarkIcon,\n CheckIcon,\n} from '@heroicons/react/24/outline';\nimport { useIAMUsers, useIAMGroups, createHumanUser, deleteUser, updateUserGroups, CreateHumanUserPayload } from '../hooks/useIAM';\nimport DeleteConfirmation from './DeleteConfirmation';\nimport SearchableSelect from './SearchableSelect';\n\ninterface IAMUsersProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\ntype View = 'list' | 'create';\n\n/**\n * Form validation errors -- follows the same pattern as FederationPeerForm.\n */\ninterface FormErrors {\n username?: string;\n email?: string;\n first_name?: string;\n last_name?: string;\n password?: string;\n}\n\nconst IAMUsers: React.FC = ({ onShowToast }) => {\n const { users, isLoading, error, refetch } = useIAMUsers();\n const { groups } = useIAMGroups();\n const [searchQuery, setSearchQuery] = useState('');\n const [view, setView] = useState('list');\n\n // Create form state\n const [formUsername, setFormUsername] = useState('');\n const [formEmail, setFormEmail] = useState('');\n const [formFirstName, setFormFirstName] = useState('');\n const [formLastName, setFormLastName] = useState('');\n const [formPassword, setFormPassword] = useState('');\n const [showPassword, setShowPassword] = useState(false);\n const [formGroups, setFormGroups] = useState>(new Set());\n const [isCreating, setIsCreating] = useState(false);\n const [errors, setErrors] = useState({});\n\n // Delete state\n const [deleteTarget, setDeleteTarget] = useState(null);\n\n // Edit groups state\n const [editingUser, setEditingUser] = useState(null);\n const [editGroups, setEditGroups] = useState>(new Set());\n const [isSavingGroups, setIsSavingGroups] = useState(false);\n\n const filteredUsers = useMemo(() => {\n if (!searchQuery) return users;\n const q = searchQuery.toLowerCase();\n return users.filter(\n (u) =>\n u.username.toLowerCase().includes(q) ||\n (u.email || '').toLowerCase().includes(q) ||\n (u.first_name || '').toLowerCase().includes(q) ||\n (u.last_name || '').toLowerCase().includes(q)\n );\n }, [users, searchQuery]);\n\n const resetForm = useCallback(() => {\n setFormUsername('');\n setFormEmail('');\n setFormFirstName('');\n setFormLastName('');\n setFormPassword('');\n setShowPassword(false);\n setFormGroups(new Set());\n setErrors({});\n }, []);\n\n const toggleGroup = (groupName: string) => {\n setFormGroups((prev) => {\n const next = new Set(prev);\n if (next.has(groupName)) next.delete(groupName);\n else next.add(groupName);\n return next;\n });\n };\n\n /** Clear a single field error when the user edits that field. */\n const clearError = (field: keyof FormErrors) => {\n if (errors[field]) {\n setErrors((prev) => ({ ...prev, [field]: undefined }));\n }\n };\n\n /** Validate all fields. Returns true if valid. */\n const validateForm = (): boolean => {\n const newErrors: FormErrors = {};\n\n if (!formUsername.trim()) newErrors.username = 'Username is required';\n if (!formEmail.trim()) {\n newErrors.email = 'Email is required';\n } else if (!/\\S+@\\S+\\.\\S+/.test(formEmail.trim())) {\n newErrors.email = 'Enter a valid email address';\n }\n if (!formFirstName.trim()) newErrors.first_name = 'First name is required';\n if (!formLastName.trim()) newErrors.last_name = 'Last name is required';\n if (!formPassword) newErrors.password = 'Password is required';\n\n setErrors(newErrors);\n return Object.keys(newErrors).length === 0;\n };\n\n const handleCreate = async () => {\n if (!validateForm()) return;\n setIsCreating(true);\n try {\n const payload: CreateHumanUserPayload = {\n username: formUsername.trim(),\n email: formEmail.trim(),\n first_name: formFirstName.trim(),\n last_name: formLastName.trim(),\n password: formPassword,\n groups: formGroups.size > 0 ? Array.from(formGroups) : undefined,\n };\n await createHumanUser(payload);\n onShowToast(`User \"${formUsername}\" created successfully`, 'success');\n resetForm();\n setView('list');\n await refetch();\n } catch (err: any) {\n const detail = err.response?.data?.detail;\n const message = Array.isArray(detail)\n ? detail.map((d: any) => d.msg).join(', ')\n : detail || 'Failed to create user';\n onShowToast(message, 'error');\n } finally {\n setIsCreating(false);\n }\n };\n\n const handleDelete = async (username: string) => {\n await deleteUser(username);\n onShowToast(`User \"${username}\" deleted`, 'success');\n setDeleteTarget(null);\n await refetch();\n };\n\n const startEditGroups = (username: string, currentGroups: string[]) => {\n setEditingUser(username);\n setEditGroups(new Set(currentGroups));\n };\n\n const cancelEditGroups = () => {\n setEditingUser(null);\n setEditGroups(new Set());\n };\n\n const handleSaveGroups = async () => {\n if (!editingUser) return;\n setIsSavingGroups(true);\n try {\n const result = await updateUserGroups(editingUser, Array.from(editGroups));\n const addedCount = result.added?.length || 0;\n const removedCount = result.removed?.length || 0;\n if (addedCount > 0 || removedCount > 0) {\n onShowToast(\n `Groups updated: ${addedCount} added, ${removedCount} removed`,\n 'success'\n );\n } else {\n onShowToast('No changes made', 'info');\n }\n setEditingUser(null);\n setEditGroups(new Set());\n await refetch();\n } catch (err: any) {\n const message = err.response?.data?.detail || 'Failed to update groups';\n onShowToast(message, 'error');\n } finally {\n setIsSavingGroups(false);\n }\n };\n\n const toggleEditGroup = (groupName: string) => {\n setEditGroups((prev) => {\n const next = new Set(prev);\n if (next.has(groupName)) next.delete(groupName);\n else next.add(groupName);\n return next;\n });\n };\n\n const addGroupToEdit = (groupName: string) => {\n if (groupName && !editGroups.has(groupName)) {\n setEditGroups((prev) => {\n const next = new Set(prev);\n next.add(groupName);\n return next;\n });\n }\n };\n\n const removeGroupFromEdit = (groupName: string) => {\n setEditGroups((prev) => {\n const next = new Set(prev);\n next.delete(groupName);\n return next;\n });\n };\n\n // Helper: input border class based on error state\n const inputClass = (field: keyof FormErrors) =>\n `w-full px-3 py-2 border rounded-lg bg-white dark:bg-gray-900 text-gray-900 dark:text-white focus:ring-2 focus:ring-purple-500 focus:border-transparent ${\n errors[field] ? 'border-red-500' : 'border-gray-300 dark:border-gray-600'\n }`;\n\n // ─── Create View ──────────────────────────────────────────────\n if (view === 'create') {\n return (\n
\n
\n

\n IAM > Users > Create\n

\n { resetForm(); setView('list'); }}\n className=\"flex items-center text-sm text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-200\"\n >\n \n Back to List\n \n
\n\n
\n
\n \n { setFormUsername(e.target.value); clearError('username'); }}\n placeholder=\"e.g. jdoe\"\n className={inputClass('username')} />\n {errors.username &&

{errors.username}

}\n
\n
\n \n { setFormEmail(e.target.value); clearError('email'); }}\n placeholder=\"user@example.com\"\n className={inputClass('email')} />\n {errors.email &&

{errors.email}

}\n
\n
\n
\n \n { setFormFirstName(e.target.value); clearError('first_name'); }}\n className={inputClass('first_name')} />\n {errors.first_name &&

{errors.first_name}

}\n
\n
\n \n { setFormLastName(e.target.value); clearError('last_name'); }}\n className={inputClass('last_name')} />\n {errors.last_name &&

{errors.last_name}

}\n
\n
\n
\n \n
\n { setFormPassword(e.target.value); clearError('password'); }}\n placeholder=\"Initial password\"\n className={`${inputClass('password')} pr-10`}\n />\n setShowPassword(!showPassword)}\n className=\"absolute right-3 top-1/2 -translate-y-1/2 text-gray-400 hover:text-gray-600 dark:hover:text-gray-200\"\n title={showPassword ? 'Hide password' : 'Show password'}\n >\n {showPassword ? : }\n \n
\n {errors.password &&

{errors.password}

}\n
\n\n {/* Group selection */}\n
\n \n
\n {groups.length === 0 ? (\n

No groups available

\n ) : (\n groups.map((g) => (\n \n ))\n )}\n
\n
\n
\n\n
\n \n \n
\n
\n );\n }\n\n // ─── List View ────────────────────────────────────────────────\n return (\n
\n
\n

IAM > Users

\n
\n \n \n
\n
\n\n
\n \n setSearchQuery(e.target.value)}\n placeholder=\"Search users...\"\n className=\"w-full pl-10 pr-4 py-2 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-900 text-gray-900 dark:text-white text-sm focus:ring-2 focus:ring-purple-500 focus:border-transparent\" />\n
\n\n {isLoading && (\n
\n )}\n {error && !isLoading && (\n
{error}
\n )}\n {!isLoading && !error && filteredUsers.length === 0 && (\n
\n {searchQuery ? 'No users match your search.' : 'No users yet. Create your first user.'}\n
\n )}\n\n {!isLoading && !error && filteredUsers.length > 0 && (\n
\n \n \n \n \n \n \n \n \n \n \n \n {filteredUsers.map((u) => (\n \n \n \n \n \n \n \n \n {deleteTarget === u.username && (\n \n \n \n )}\n {editingUser === u.username && (\n \n \n \n )}\n \n ))}\n \n
UsernameEmailNameGroupsAction
{u.username}{u.email || '\\u2014'}\n {[u.first_name, u.last_name].filter(Boolean).join(' ') || '\\u2014'}\n \n
\n {(u.groups || []).map((g) => (\n \n {g}\n \n ))}\n {(!u.groups || u.groups.length === 0) && {'\\u2014'}}\n startEditGroups(u.username, u.groups || [])}\n className=\"ml-2 p-1 text-gray-400 hover:text-purple-600 dark:hover:text-purple-400\"\n title=\"Edit groups\"\n >\n \n \n
\n 		\n \n
\n setDeleteTarget(null)}\n />\n
\n
\n
\n \n Edit Groups for {u.username}\n \n
\n \n Cancel\n \n \n \n {isSavingGroups ? 'Saving...' : 'Save'}\n \n
\n
\n\n {/* Selected groups as removable tags */}\n
\n {Array.from(editGroups).map((groupName) => (\n \n {groupName}\n removeGroupFromEdit(groupName)}\n className=\"ml-1 hover:text-purple-900 dark:hover:text-purple-100\"\n >\n \n \n \n ))}\n {editGroups.size === 0 && (\n No groups assigned\n )}\n
\n\n {/* Searchable dropdown to add groups */}\n
\n !editGroups.has(g.name))\n .map((g) => ({\n value: g.name,\n label: g.name,\n description: g.path || undefined,\n }))}\n value=\"\"\n onChange={addGroupToEdit}\n placeholder=\"Search and add groups...\"\n maxDescriptionWords={5}\n />\n
\n
\n
\n
\n )}\n
\n );\n};\n\nexport default IAMUsers;\n" }, { "path": "frontend/src/components/Layout.tsx", "content": "import React, { useState, useEffect, useCallback, Fragment } from 'react';\nimport { Menu, Transition } from '@headlessui/react';\nimport { Link } from 'react-router-dom';\nimport {\n Bars3Icon,\n UserIcon,\n ChevronDownIcon,\n ArrowRightOnRectangleIcon,\n Cog6ToothIcon,\n} from '@heroicons/react/24/outline';\nimport Sidebar from './Sidebar';\nimport UptimeDisplay from './UptimeDisplay';\nimport { useServerStats } from '../hooks/useServerStats';\nimport { useAuth } from '../contexts/AuthContext';\nimport logo from '../assets/logo.png';\n\ninterface LayoutProps {\n children: React.ReactNode;\n}\n\nconst Layout: React.FC = ({ children }) => {\n const [sidebarOpen, setSidebarOpen] = useState(true);\n const [version, setVersion] = useState(null);\n const { user, logout } = useAuth();\n const { stats, activeFilter, setActiveFilter } = useServerStats();\n const [availableTags, setAvailableTags] = useState([]);\n const [selectedTags, setSelectedTags] = useState([]);\n\n const handleTagSelect = useCallback((tag: string) => {\n setSelectedTags(prev =>\n prev.includes(tag) ? prev.filter(t => t !== tag) : [...prev, tag]\n );\n }, []);\n\n const fetchTags = useCallback(() => {\n fetch('/api/search/tags')\n .then(res => res.json())\n .then(data => setAvailableTags(data.tags || []))\n .catch(err => console.error('Failed to fetch tags:', err));\n }, []);\n\n useEffect(() => {\n // Fetch version from API\n fetch('/api/version')\n .then(res => res.json())\n .then(data => setVersion(data.version))\n .catch(err => console.error('Failed to fetch version:', err));\n\n // Initial tag fetch\n fetchTags();\n\n // Re-fetch tags when servers/agents are registered, updated, or deleted\n const handleTagRefresh = () => fetchTags();\n window.addEventListener('registry-data-changed', handleTagRefresh);\n return () => window.removeEventListener('registry-data-changed', handleTagRefresh);\n }, [fetchTags]);\n\n const handleLogout = async () => {\n try {\n await logout();\n } catch (error) {\n console.error('Logout failed:', error);\n }\n };\n\n return (\n
\n {/* Header */}\n
\n
\n
\n {/* Left side */}\n
\n {/* Sidebar toggle button - visible on all screen sizes */}\n {\n console.log('Toggle clicked, current state:', sidebarOpen);\n setSidebarOpen(!sidebarOpen);\n }}\n >\n \n \n\n {/* Logo */}\n
\n \n \n \n AI Gateway & Registry\n \n \n
\n
\n\n {/* Right side */}\n
\n {/* GitHub link */}\n \n \n \n \n \n\n {/* Version badge */}\n {version && (\n
\n \n {version}\n \n
\n )}\n\n {/* Uptime display */}\n \n\n {/* Settings gear icon (admin only) */}\n {user?.is_admin && (\n \n \n \n )}\n\n {/* User dropdown */}\n \n
\n \n
\n \n
\n \n {user?.username || 'Admin'}\n \n \n \n
\n\n \n \n \n {({ active }) => (\n \n \n Sign out\n \n )}\n \n \n \n \n
\n
\n
\n
\n\n
\n {/* Sidebar */}\n \n\n\n {/* Main content */}\n
\n
\n {React.cloneElement(children as React.ReactElement, { activeFilter, setActiveFilter, selectedTags })}\n
\n
\n
\n
\n );\n};\n\nexport default Layout; " }, { "path": "frontend/src/components/ProtectedRoute.tsx", "content": "import React from 'react';\nimport { useNavigate } from 'react-router-dom';\nimport { useAuth } from '../contexts/AuthContext';\nimport { useEffect } from 'react';\n\ninterface ProtectedRouteProps {\n children: React.ReactNode;\n}\n\nconst ProtectedRoute: React.FC = ({ children }) => {\n const { user, loading } = useAuth();\n const navigate = useNavigate();\n\n useEffect(() => {\n if (!loading && !user) {\n navigate('/login', { replace: true });\n }\n }, [loading, user, navigate]);\n\n if (loading) {\n return (\n
\n
\n
\n );\n }\n\n if (!user) {\n return null;\n }\n\n return <>{children};\n};\n\nexport default ProtectedRoute; " }, { "path": "frontend/src/components/RegistryCardSettings.tsx", "content": "import React, { useState, useEffect } from 'react';\nimport axios from 'axios';\nimport {\n DocumentTextIcon,\n GlobeAltIcon,\n EnvelopeIcon,\n LinkIcon,\n InformationCircleIcon,\n} from '@heroicons/react/24/outline';\n\ninterface RegistryCardData {\n schema_version: string;\n id: string;\n name: string;\n description: string | null;\n registry_url: string;\n organization_name: string;\n federation_api_version: string;\n federation_endpoint: string;\n contact_email: string | null;\n contact_url: string | null;\n capabilities: {\n servers: boolean;\n agents: boolean;\n skills: boolean;\n prompts: boolean;\n security_scans: boolean;\n incremental_sync: boolean;\n webhooks: boolean;\n };\n authentication: {\n schemes: string[];\n oauth2_issuer: string | null;\n oauth2_token_endpoint: string | null;\n scopes_supported: string[];\n };\n metadata: Record;\n}\n\ninterface RegistryCardSettingsProps {\n onShowToast?: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\n/**\n * RegistryCardSettings component for viewing and editing the Registry Card.\n *\n * Features:\n * - Fetches registry card from /api/registry/v0.1/card\n * - Displays current configuration\n * - Allows editing contact information\n * - Updates via PATCH /api/registry/v0.1/card\n * - Loading and error states\n */\nconst RegistryCardSettings: React.FC = ({ onShowToast }) => {\n const [loading, setLoading] = useState(true);\n const [saving, setSaving] = useState(false);\n const [error, setError] = useState(null);\n const [card, setCard] = useState(null);\n const [formData, setFormData] = useState({\n description: '',\n contact_email: '',\n contact_url: '',\n });\n\n useEffect(() => {\n fetchRegistryCard();\n }, []);\n\n const fetchRegistryCard = async () => {\n setLoading(true);\n setError(null);\n try {\n const response = await axios.get('/api/registry/v0.1/card');\n const cardData = response.data;\n setCard(cardData);\n setFormData({\n description: cardData.description || '',\n contact_email: cardData.contact_email || '',\n contact_url: cardData.contact_url || '',\n });\n } catch (err: any) {\n const errorMsg = err.response?.status === 404\n ? 'Registry card not initialized. Please configure REGISTRY_URL, REGISTRY_NAME, and REGISTRY_ORGANIZATION_NAME in .env'\n : err.response?.data?.detail || 'Failed to load registry card';\n setError(errorMsg);\n if (onShowToast) {\n onShowToast(errorMsg, 'error');\n }\n } finally {\n setLoading(false);\n }\n };\n\n const handleSave = async () => {\n if (!card) return;\n\n setSaving(true);\n try {\n await axios.patch('/api/registry/v0.1/card', {\n description: formData.description || null,\n contact_email: formData.contact_email || null,\n contact_url: formData.contact_url || null,\n });\n\n if (onShowToast) {\n onShowToast('Registry card updated successfully', 'success');\n }\n\n // Refresh the card\n await fetchRegistryCard();\n } catch (err: any) {\n const errorMsg = err.response?.data?.detail || 'Failed to update registry card';\n setError(errorMsg);\n if (onShowToast) {\n onShowToast(errorMsg, 'error');\n }\n } finally {\n setSaving(false);\n }\n };\n\n const hasChanges = card && (\n formData.description !== (card.description || '') ||\n formData.contact_email !== (card.contact_email || '') ||\n formData.contact_url !== (card.contact_url || '')\n );\n\n if (loading) {\n return (\n
\n
\n
\n

Loading registry card...

\n
\n
\n );\n }\n\n if (error && !card) {\n return (\n
\n

\n \n Error Loading Registry Card\n

\n

{error}

\n \n Retry\n \n
\n );\n }\n\n if (!card) return null;\n\n return (\n
\n {/* Header */}\n
\n

\n Registry Card\n

\n

\n Manage your registry's metadata and contact information for federation discovery.\n

\n
\n\n {/* Read-only Information */}\n
\n

\n \n Registry Information\n

\n
\n
\n Registry ID:\n

{card.id}

\n
\n
\n Name:\n

{card.name}

\n
\n
\n Organization:\n

{card.organization_name}

\n
\n
\n Registry URL:\n

{card.registry_url}

\n
\n
\n Federation Endpoint:\n

{card.federation_endpoint}

\n
\n
\n API Version:\n

{card.federation_api_version}

\n
\n
\n
\n\n {/* Authentication Configuration */}\n
\n

\n \n \n \n Authentication Configuration\n

\n
\n
\n Supported Schemes:\n

\n {card.authentication.schemes.join(', ')}\n

\n
\n {card.authentication.oauth2_issuer && (\n
\n OAuth2 Issuer:\n

\n {card.authentication.oauth2_issuer}\n

\n
\n )}\n {card.authentication.oauth2_token_endpoint && (\n
\n OAuth2 Token Endpoint:\n

\n {card.authentication.oauth2_token_endpoint}\n

\n
\n )}\n
\n Scopes Supported:\n

\n {card.authentication.scopes_supported.join(', ')}\n

\n
\n
\n
\n\n {/* Editable Fields */}\n
\n

\n \n Editable Information\n

\n\n {/* Description */}\n
\n \n setFormData({ ...formData, description: e.target.value })}\n placeholder=\"Describe your registry's purpose and contents...\"\n rows={3}\n maxLength={1000}\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-700 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\n placeholder-gray-400 dark:placeholder-gray-500\"\n />\n

\n {formData.description.length}/1000 characters\n

\n
\n\n {/* Contact Email */}\n
\n \n setFormData({ ...formData, contact_email: e.target.value })}\n placeholder=\"contact@example.com\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-700 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\n placeholder-gray-400 dark:placeholder-gray-500\"\n />\n
\n\n {/* Contact URL */}\n
\n \n setFormData({ ...formData, contact_url: e.target.value })}\n placeholder=\"https://example.com/contact\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-700 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-purple-500 focus:border-transparent\n placeholder-gray-400 dark:placeholder-gray-500\"\n />\n
\n
\n\n {/* Save Button */}\n
\n \n {saving ? (\n <>\n
\n Saving...\n \n ) : (\n 'Save Changes'\n )}\n \n
\n\n {/* Capabilities */}\n
\n

\n \n Capabilities\n

\n
\n {Object.entries(card.capabilities).map(([key, value]) => (\n
\n
\n \n {key.replace(/_/g, ' ')}\n \n
\n ))}\n
\n
\n
\n );\n};\n\nexport default RegistryCardSettings;\n" }, { "path": "frontend/src/components/SearchableSelect.tsx", "content": "/**\n * Searchable select component with autocomplete functionality.\n *\n * Displays a text input that filters options as you type,\n * showing results in a dropdown list below.\n */\n\nimport React, { useState, useRef, useEffect } from 'react';\nimport { MagnifyingGlassIcon, XMarkIcon } from '@heroicons/react/24/outline';\n\n\nexport interface SelectOption {\n value: string;\n label: string;\n description?: string;\n}\n\ninterface SearchableSelectProps {\n options: SelectOption[];\n value: string;\n onChange: (value: string) => void;\n placeholder?: string;\n disabled?: boolean;\n isLoading?: boolean;\n maxDescriptionWords?: number;\n allowCustom?: boolean; // Allow entering values not in the list\n specialOptions?: SelectOption[]; // Options shown at top (e.g., \"* All\")\n focusColor?: string;\n}\n\n\n/**\n * Truncate text to a maximum number of words.\n */\nfunction _truncateWords(text: string, maxWords: number): string {\n const words = text.split(/\\s+/);\n if (words.length <= maxWords) return text;\n return words.slice(0, maxWords).join(' ') + '...';\n}\n\n\nconst SearchableSelect: React.FC = ({\n options,\n value,\n onChange,\n placeholder = 'Search...',\n disabled = false,\n isLoading = false,\n maxDescriptionWords = 8,\n allowCustom = false,\n specialOptions = [],\n focusColor,\n}) => {\n const [isOpen, setIsOpen] = useState(false);\n const [searchQuery, setSearchQuery] = useState('');\n const containerRef = useRef(null);\n const inputRef = useRef(null);\n\n // Find the selected option to display its label\n const selectedOption = [...specialOptions, ...options].find((o) => o.value === value);\n\n // Filter options based on search query\n const filteredOptions = options.filter((option) => {\n const query = searchQuery.toLowerCase();\n return (\n option.label.toLowerCase().includes(query) ||\n option.value.toLowerCase().includes(query) ||\n (option.description?.toLowerCase().includes(query) ?? false)\n );\n });\n\n // Close dropdown when clicking outside\n useEffect(() => {\n const handleClickOutside = (event: MouseEvent) => {\n if (containerRef.current && !containerRef.current.contains(event.target as Node)) {\n setIsOpen(false);\n setSearchQuery('');\n }\n };\n\n document.addEventListener('mousedown', handleClickOutside);\n return () => document.removeEventListener('mousedown', handleClickOutside);\n }, []);\n\n const handleSelect = (optionValue: string) => {\n onChange(optionValue);\n setIsOpen(false);\n setSearchQuery('');\n };\n\n const handleClear = () => {\n onChange('');\n setSearchQuery('');\n inputRef.current?.focus();\n };\n\n const handleInputChange = (e: React.ChangeEvent) => {\n setSearchQuery(e.target.value);\n if (!isOpen) setIsOpen(true);\n };\n\n const handleInputFocus = () => {\n setIsOpen(true);\n };\n\n const handleKeyDown = (e: React.KeyboardEvent) => {\n if (e.key === 'Escape') {\n setIsOpen(false);\n setSearchQuery('');\n } else if (e.key === 'Enter' && allowCustom && searchQuery.trim()) {\n handleSelect(searchQuery.trim());\n }\n };\n\n return (\n
\n {/* Input field */}\n
\n \n \n {value && !disabled && (\n \n \n \n )}\n
\n\n {/* Dropdown */}\n {isOpen && !disabled && (\n
\n {isLoading ? (\n
Loading...
\n ) : (\n <>\n {/* Special options (e.g., \"* All servers\") */}\n {specialOptions.map((option) => (\n handleSelect(option.value)}\n className={`w-full text-left px-3 py-2 text-sm hover:bg-gray-100 dark:hover:bg-gray-700\n ${value === option.value ? 'bg-purple-50 dark:bg-purple-900/20' : ''}`}\n >\n {option.label}\n {option.description && (\n {option.description}\n )}\n \n ))}\n\n {specialOptions.length > 0 && filteredOptions.length > 0 && (\n
\n )}\n\n {/* Filtered options */}\n {filteredOptions.length === 0 ? (\n
\n {searchQuery ? 'No matches found' : 'No options available'}\n
\n ) : (\n filteredOptions.slice(0, 50).map((option) => (\n handleSelect(option.value)}\n className={`w-full text-left px-3 py-2 hover:bg-gray-100 dark:hover:bg-gray-700\n ${value === option.value ? 'bg-purple-50 dark:bg-purple-900/20' : ''}`}\n >\n
\n {option.label}\n
\n {option.description && (\n
\n {_truncateWords(option.description, maxDescriptionWords)}\n
\n )}\n \n ))\n )}\n\n {filteredOptions.length > 50 && (\n
\n Showing first 50 results. Type to filter.\n
\n )}\n \n )}\n
\n )}\n
\n );\n};\n\n\nexport default SearchableSelect;\n" }, { "path": "frontend/src/components/SecurityScanModal.tsx", "content": "import React, { useState } from 'react';\nimport {\n ShieldCheckIcon,\n ShieldExclamationIcon,\n ExclamationTriangleIcon,\n ClipboardDocumentIcon,\n ArrowPathIcon,\n ChevronDownIcon,\n ChevronRightIcon,\n} from '@heroicons/react/24/outline';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\n\nexport interface SecurityScanResult {\n server_path?: string;\n server_url?: string;\n agent_path?: string;\n agent_url?: string;\n scan_timestamp: string;\n is_safe: boolean;\n critical_issues: number;\n high_severity: number;\n medium_severity: number;\n low_severity: number;\n analyzers_used: string[];\n raw_output: {\n analysis_results?: Record;\n tool_results?: Record;\n scan_results?: Record;\n };\n scan_failed: boolean;\n error_message?: string;\n}\n\n\ninterface SecurityScanModalProps {\n resourceName: string;\n resourceType: 'server' | 'agent' | 'skill';\n isOpen: boolean;\n onClose: () => void;\n loading: boolean;\n scanResult?: SecurityScanResult | null;\n onRescan?: () => Promise;\n canRescan?: boolean;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n}\n\n\ninterface StatusInfo {\n icon: React.ComponentType<{ className?: string }>;\n color: string;\n text: string;\n}\n\n\nconst SEVERITY_BOX_STYLES: Record = {\n critical: 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400 border-red-200 dark:border-red-700',\n high: 'bg-orange-100 text-orange-800 dark:bg-orange-900/30 dark:text-orange-400 border-orange-200 dark:border-orange-700',\n medium: 'bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-400 border-amber-200 dark:border-amber-700',\n low: 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400 border-blue-200 dark:border-blue-700',\n};\n\n\nconst _getStatusInfo = (scanResult: SecurityScanResult | null | undefined): StatusInfo => {\n if (!scanResult) {\n return { icon: ShieldCheckIcon, color: 'gray', text: 'No Scan Data' };\n }\n if (scanResult.scan_failed) {\n return { icon: ExclamationTriangleIcon, color: 'red', text: 'Scan Failed' };\n }\n if (scanResult.critical_issues > 0 || scanResult.high_severity > 0) {\n return { icon: ExclamationTriangleIcon, color: 'red', text: 'UNSAFE' };\n }\n if (scanResult.medium_severity > 0 || scanResult.low_severity > 0) {\n return { icon: ShieldExclamationIcon, color: 'amber', text: 'WARNING' };\n }\n return { icon: ShieldCheckIcon, color: 'green', text: 'SAFE' };\n};\n\n\nconst _getStatusBannerClasses = (color: string): string => {\n switch (color) {\n case 'green':\n return 'bg-green-50 dark:bg-green-900/20 border-green-200 dark:border-green-800';\n case 'amber':\n return 'bg-amber-50 dark:bg-amber-900/20 border-amber-200 dark:border-amber-800';\n case 'red':\n return 'bg-red-50 dark:bg-red-900/20 border-red-200 dark:border-red-800';\n default:\n return 'bg-gray-50 dark:bg-gray-900/20 border-gray-200 dark:border-gray-700';\n }\n};\n\n\nconst _getStatusIconClasses = (color: string): string => {\n switch (color) {\n case 'green':\n return 'text-green-600 dark:text-green-400';\n case 'amber':\n return 'text-amber-600 dark:text-amber-400';\n case 'red':\n return 'text-red-600 dark:text-red-400';\n default:\n return 'text-gray-500 dark:text-gray-400';\n }\n};\n\n\nconst _getSeverityBadgeClasses = (severity: string): string => {\n const severityLower = severity.toLowerCase();\n switch (severityLower) {\n case 'critical':\n return 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400';\n case 'high':\n return 'bg-orange-100 text-orange-800 dark:bg-orange-900/30 dark:text-orange-400';\n case 'medium':\n return 'bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-400';\n default:\n return 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400';\n }\n};\n\n\nconst SecurityScanModal: React.FC = ({\n resourceName,\n resourceType,\n isOpen,\n onClose,\n loading,\n scanResult,\n onRescan,\n canRescan,\n onShowToast,\n}) => {\n const [showRawJson, setShowRawJson] = useState(false);\n const [expandedAnalyzers, setExpandedAnalyzers] = useState>(new Set());\n const [rescanning, setRescanning] = useState(false);\n\n useEscapeKey(onClose, isOpen);\n\n if (!isOpen) {\n return null;\n }\n\n const toggleAnalyzer = (analyzer: string) => {\n const newExpanded = new Set(expandedAnalyzers);\n if (newExpanded.has(analyzer)) {\n newExpanded.delete(analyzer);\n } else {\n newExpanded.add(analyzer);\n }\n setExpandedAnalyzers(newExpanded);\n };\n\n const handleCopy = async () => {\n try {\n await navigator.clipboard.writeText(JSON.stringify(scanResult, null, 2));\n onShowToast?.('Security scan results copied to clipboard!', 'success');\n } catch (error) {\n console.error('Failed to copy:', error);\n onShowToast?.('Failed to copy results', 'error');\n }\n };\n\n const handleRescan = async () => {\n if (!onRescan || rescanning) return;\n setRescanning(true);\n try {\n await onRescan();\n onShowToast?.('Security scan completed', 'success');\n } catch (error) {\n onShowToast?.('Failed to rescan', 'error');\n } finally {\n setRescanning(false);\n }\n };\n\n const statusInfo = _getStatusInfo(scanResult);\n const StatusIcon = statusInfo.icon;\n\n const severityItems = [\n { label: 'CRITICAL', count: scanResult?.critical_issues ?? 0, key: 'critical' },\n { label: 'HIGH', count: scanResult?.high_severity ?? 0, key: 'high' },\n { label: 'MEDIUM', count: scanResult?.medium_severity ?? 0, key: 'medium' },\n { label: 'LOW', count: scanResult?.low_severity ?? 0, key: 'low' },\n ];\n\n return (\n
\n
\n {/* Header */}\n
\n

\n Security Scan Results - {resourceName}\n

\n \n ×\n \n
\n\n {loading ? (\n
\n \n Loading scan results...\n
\n ) : !scanResult ? (\n
\n \n

\n No security scan results available for this {resourceType}.\n

\n {canRescan && onRescan && (\n \n {rescanning ? 'Scanning...' : 'Run Security Scan'}\n \n )}\n
\n ) : (\n
\n {/* Overall Status */}\n
\n
\n \n
\n
\n Overall Status: {statusInfo.text}\n
\n
\n Scanned: {new Date(scanResult.scan_timestamp).toLocaleString()}\n
\n
\n
\n {scanResult.scan_failed && scanResult.error_message && (\n
\n Error: {scanResult.error_message}\n
\n )}\n
\n\n {/* Severity Summary */}\n
\n

Severity Summary

\n
\n {severityItems.map((item) => (\n \n
{item.label}
\n
{item.count}
\n
\n ))}\n
\n
\n\n {/* Analyzers Used */}\n {scanResult.analyzers_used && scanResult.analyzers_used.length > 0 && (\n
\n

Analyzers Used

\n
\n {scanResult.analyzers_used.map((analyzer) => (\n \n {analyzer.toUpperCase()}\n \n ))}\n
\n
\n )}\n\n {/* Detailed Findings */}\n {scanResult.raw_output && scanResult.raw_output.analysis_results && (\n
\n

Detailed Findings

\n
\n {Object.entries(scanResult.raw_output.analysis_results).map(([analyzer, analyzerData]) => {\n // Handle both formats: direct array or object with findings property\n const findings = Array.isArray(analyzerData)\n ? analyzerData\n : (analyzerData as any)?.findings || [];\n const findingsCount = Array.isArray(findings) ? findings.length : 0;\n\n return (\n
\n toggleAnalyzer(analyzer)}\n className=\"w-full flex items-center justify-between p-3 hover:bg-gray-50 dark:hover:bg-gray-700/50 transition-colors\"\n aria-expanded={expandedAnalyzers.has(analyzer)}\n >\n \n {analyzer.charAt(0).toUpperCase() + analyzer.slice(1).replace(/_/g, ' ')} Analysis\n \n ({findingsCount} finding{findingsCount !== 1 ? 's' : ''})\n \n \n {expandedAnalyzers.has(analyzer) ? (\n \n ) : (\n \n )}\n \n {/* Always show finding summaries - collapsed shows preview, expanded shows full details */}\n {Array.isArray(findings) && findings.length > 0 && !expandedAnalyzers.has(analyzer) && (\n
\n
\n {findings.map((finding: any, idx: number) => {\n // Try multiple possible field names for the description\n const description = finding.threat_summary\n || finding.description\n || finding.message\n || finding.detail\n || finding.reason\n || (finding.threat_names && finding.threat_names.length > 0\n ? finding.threat_names.join(', ')\n : null);\n const title = finding.title || finding.tool_name || finding.skill_name || finding.name || finding.rule_id;\n\n return (\n \n \n {title || description || 'Finding'}\n {description && title && (\n \n - {description.length > 60\n ? description.substring(0, 60) + '...'\n : description}\n \n )}\n {!title && description && description.length > 80 && (\n ...\n )}\n \n \n {finding.severity}\n \n
\n );\n })}\n
\n
\n )}\n {expandedAnalyzers.has(analyzer) && (\n
\n {Array.isArray(findings) && findings.length > 0 ? (\n
\n {findings.map((finding: any, idx: number) => {\n const findingTitle = finding.title || finding.tool_name || finding.skill_name || finding.name || 'Finding';\n const findingDesc = finding.description || finding.threat_summary || finding.message;\n\n return (\n \n
\n \n {findingTitle}\n \n \n {finding.severity}\n \n
\n {findingDesc && (\n

\n {findingDesc}\n

\n )}\n {finding.remediation && (\n

\n Fix: {finding.remediation}\n

\n )}\n {finding.file_path && (\n

\n {finding.file_path}{finding.line_number ? `:${finding.line_number}` : ''}\n

\n )}\n {finding.threat_names && finding.threat_names.length > 0 && (\n
\n {finding.threat_names.map((threat: string, tidx: number) => (\n \n {threat}\n \n ))}\n
\n )}\n
\n );\n })}\n
\n ) : (\n

\n No findings from this analyzer.\n

\n )}\n
\n )}\n
\n );\n })}\n
\n
\n )}\n\n {/* Raw JSON Toggle */}\n
\n setShowRawJson(!showRawJson)}\n className=\"text-sm text-blue-600 dark:text-blue-400 hover:underline\"\n >\n {showRawJson ? 'Hide' : 'View'} Raw JSON\n \n {showRawJson && (\n 
\n                  {JSON.stringify(scanResult, null, 2)}\n
\n )}\n
\n\n {/* Action Buttons */}\n
\n \n \n Copy Results\n \n {canRescan && onRescan && (\n \n \n {rescanning ? 'Scanning...' : 'Rescan'}\n \n )}\n
\n
\n )}\n
\n
\n );\n};\n\nexport default SecurityScanModal;\n" }, { "path": "frontend/src/components/SemanticSearchResults.tsx", "content": "import React, { useState, useMemo, useCallback } from 'react';\nimport {\n ArrowPathIcon,\n CogIcon,\n InformationCircleIcon,\n XMarkIcon,\n ArrowTopRightOnSquareIcon,\n ClipboardIcon,\n ArrowDownTrayIcon\n} from '@heroicons/react/24/outline';\nimport axios from 'axios';\nimport ReactMarkdown from 'react-markdown';\nimport remarkGfm from 'remark-gfm';\nimport {\n SemanticServerHit,\n SemanticToolHit,\n SemanticAgentHit,\n SemanticSkillHit,\n SemanticVirtualServerHit\n} from '../hooks/useSemanticSearch';\nimport ServerConfigModal from './ServerConfigModal';\nimport AgentDetailsModal from './AgentDetailsModal';\nimport type { Server } from './ServerCard';\nimport type { Agent as AgentType } from './AgentCard';\nimport useEscapeKey from '../hooks/useEscapeKey';\nimport ANSBadge from './ANSBadge';\n\ninterface SemanticSearchResultsProps {\n query: string;\n loading: boolean;\n error: string | null;\n servers: SemanticServerHit[];\n tools: SemanticToolHit[];\n agents: SemanticAgentHit[];\n skills: SemanticSkillHit[];\n virtualServers?: SemanticVirtualServerHit[];\n}\n\ninterface ToolSchemaModalProps {\n toolName: string;\n serverName: string;\n schema: Record | null;\n isOpen: boolean;\n onClose: () => void;\n}\n\nconst ToolSchemaModal: React.FC = ({\n toolName,\n serverName,\n schema,\n isOpen,\n onClose\n}) => {\n useEscapeKey(onClose, isOpen);\n if (!isOpen) return null;\n\n return (\n
\n
\n
\n
\n

\n {toolName}\n

\n

{serverName}

\n
\n \n \n \n
\n
\n

\n Input Schema\n

\n {schema && Object.keys(schema).length > 0 ? (\n 
\n              {JSON.stringify(schema, null, 2)}\n
\n ) : (\n

\n No input schema available for this tool.\n

\n )}\n
\n
\n
\n );\n};\n\n// Helper function to parse YAML frontmatter from markdown\nconst parseYamlFrontmatter = (content: string): { frontmatter: Record | null; body: string } => {\n const frontmatterRegex = /^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n([\\s\\S]*)$/;\n const match = content.match(frontmatterRegex);\n\n if (match) {\n const yamlContent = match[1];\n const body = match[2];\n const frontmatter: Record = {};\n const lines = yamlContent.split('\\n');\n for (const line of lines) {\n const colonIndex = line.indexOf(':');\n if (colonIndex > 0) {\n const key = line.substring(0, colonIndex).trim();\n const value = line.substring(colonIndex + 1).trim();\n if (key && value) {\n frontmatter[key] = value;\n }\n }\n }\n return { frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null, body };\n }\n return { frontmatter: null, body: content };\n};\n\n\ninterface ServerDetailsModalProps {\n server: SemanticServerHit;\n isOpen: boolean;\n onClose: () => void;\n}\n\nconst ServerDetailsModal: React.FC = ({\n server,\n isOpen,\n onClose\n}) => {\n useEscapeKey(onClose, isOpen);\n if (!isOpen) return null;\n\n const isFederatedServer = server.sync_metadata?.is_federated === true;\n const peerRegistryId = isFederatedServer && server.sync_metadata?.source_peer_id\n ? server.sync_metadata.source_peer_id.replace('peer-registry-', '').replace('peer-', '').toUpperCase()\n : null;\n\n return (\n
\n
\n
\n
\n
\n

\n {server.server_name}\n

\n {isFederatedServer && peerRegistryId && (\n \n {peerRegistryId}\n \n )}\n
\n

{server.path}

\n
\n \n \n \n
\n
\n {/* Description */}\n
\n

\n Description\n

\n

\n {server.description || 'No description available.'}\n

\n
\n\n {/* Tags */}\n {server.tags && server.tags.length > 0 && (\n
\n

\n Tags\n

\n
\n {server.tags.map((tag) => (\n \n {tag}\n \n ))}\n
\n
\n )}\n\n {/* Tools */}\n {server.matching_tools && server.matching_tools.length > 0 && (\n
\n

\n Tools ({server.matching_tools.length})\n

\n
    \n {server.matching_tools.map((tool) => (\n
  • \n {tool.tool_name}\n {tool.description && (\n

    \n {tool.description}\n

    \n )}\n
    • \n ))}\n
\n
\n )}\n\n {/* Status */}\n
\n

\n Status\n

\n
\n
\n \n {server.is_enabled ? 'Enabled' : 'Disabled'}\n \n
\n
\n\n {/* Relevance Score */}\n
\n

\n Match Score\n

\n \n {Math.round(Math.min(server.relevance_score, 1) * 100)}% match\n \n
\n
\n
\n
\n );\n};\n\n\ninterface SkillContentModalProps {\n skill: SemanticSkillHit;\n isOpen: boolean;\n onClose: () => void;\n}\n\nconst SkillContentModal: React.FC = ({\n skill,\n isOpen,\n onClose\n}) => {\n const [loading, setLoading] = useState(false);\n const [content, setContent] = useState(null);\n const [error, setError] = useState(null);\n\n useEscapeKey(onClose, isOpen);\n\n // Fetch content when modal opens\n React.useEffect(() => {\n if (!isOpen) {\n setContent(null);\n setError(null);\n return;\n }\n\n const fetchContent = async () => {\n setLoading(true);\n setError(null);\n try {\n // skill.path is like \"/skills/doc-coauthoring\", need just \"/doc-coauthoring\"\n const apiPath = skill.path.startsWith('/skills/')\n ? skill.path.replace('/skills/', '/')\n : skill.path;\n const response = await axios.get(`/api/skills${apiPath}/content`);\n setContent(response.data.content);\n } catch (err: any) {\n console.error('Failed to fetch SKILL.md content:', err);\n setError(err.response?.data?.detail || 'Failed to load SKILL.md content');\n } finally {\n setLoading(false);\n }\n };\n\n fetchContent();\n }, [isOpen, skill.path]);\n\n if (!isOpen) return null;\n\n const handleCopy = () => {\n if (content) {\n navigator.clipboard.writeText(content);\n }\n };\n\n const handleDownload = () => {\n if (content) {\n const blob = new Blob([content], { type: 'text/markdown' });\n const url = URL.createObjectURL(blob);\n const a = document.createElement('a');\n a.href = url;\n a.download = `${skill.skill_name || 'skill'}.md`;\n document.body.appendChild(a);\n a.click();\n document.body.removeChild(a);\n URL.revokeObjectURL(url);\n }\n };\n\n const { frontmatter, body } = content ? parseYamlFrontmatter(content) : { frontmatter: null, body: '' };\n\n return (\n
\n
\n
\n
\n

\n {skill.skill_name}\n

\n \n SKILL\n \n
\n \n \n \n
\n\n {/* Action buttons */}\n
\n {skill.skill_md_url && (\n \n \n View Skill\n \n )}\n {skill.repository_url && (\n \n \n View Repo\n \n )}\n {content && (\n <>\n \n \n Copy\n \n \n \n Download\n \n \n )}\n
\n\n
\n {loading ? (\n
\n
\n
\n ) : error ? (\n
\n

{error}

\n {skill.skill_md_url && (\n

\n Try visiting the{' '}\n \n source URL\n {' '}\n directly.\n

\n )}\n
\n ) : content ? (\n <>\n {/* YAML Frontmatter Table */}\n {frontmatter && (\n
\n \n \n {Object.entries(frontmatter).map(([key, value]) => (\n \n \n \n \n ))}\n \n
\n {key}\n \n {value}\n
\n
\n )}\n {/* Markdown Body */}\n
\n {body}\n
\n \n ) : (\n
\n

Could not load SKILL.md content.

\n
\n )}\n
\n
\n
\n );\n};\n\n\ninterface VirtualServerDetailsModalProps {\n virtualServer: SemanticVirtualServerHit;\n isOpen: boolean;\n onClose: () => void;\n}\n\nconst VirtualServerDetailsModal: React.FC = ({\n virtualServer,\n isOpen,\n onClose\n}) => {\n const [copiedEndpoint, setCopiedEndpoint] = useState(false);\n const [expandedTools, setExpandedTools] = useState>(new Set());\n\n useEscapeKey(onClose, isOpen);\n if (!isOpen) return null;\n\n const tools = virtualServer.matching_tools || [];\n const backendPaths = virtualServer.backend_paths || [];\n\n const handleCopyEndpoint = () => {\n if (virtualServer.endpoint_url) {\n navigator.clipboard.writeText(virtualServer.endpoint_url);\n setCopiedEndpoint(true);\n setTimeout(() => setCopiedEndpoint(false), 2000);\n }\n };\n\n const toggleToolExpand = (toolName: string) => {\n setExpandedTools(prev => {\n const next = new Set(prev);\n if (next.has(toolName)) {\n next.delete(toolName);\n } else {\n next.add(toolName);\n }\n return next;\n });\n };\n\n return (\n
\n
\n
\n
\n
\n

\n {virtualServer.server_name}\n

\n \n VIRTUAL\n \n
\n

{virtualServer.path}

\n
\n \n \n \n
\n
\n {/* Endpoint URL */}\n {virtualServer.endpoint_url && (\n
\n

\n Endpoint URL\n

\n
\n \n {virtualServer.endpoint_url}\n \n \n {copiedEndpoint ? (\n Copied!\n ) : (\n \n )}\n \n
\n
\n )}\n\n {/* Description */}\n
\n

\n Description\n

\n

\n {virtualServer.description || 'No description available.'}\n

\n
\n\n {/* Tags */}\n {virtualServer.tags && virtualServer.tags.length > 0 && (\n
\n

\n Tags\n

\n
\n {virtualServer.tags.map((tag) => (\n \n {tag}\n \n ))}\n
\n
\n )}\n\n {/* Backend Servers */}\n {backendPaths.length > 0 && (\n
\n

\n Backend Servers ({backendPaths.length})\n

\n
    \n {backendPaths.map((path) => (\n
  • \n {path}\n
    • \n ))}\n
\n
\n )}\n\n {/* Tools */}\n {tools.length > 0 && (\n
\n

\n Tools ({tools.length})\n

\n
    \n {tools.map((tool) => {\n const isExpanded = expandedTools.has(tool.tool_name);\n return (\n
  • \n toggleToolExpand(tool.tool_name)}\n className=\"w-full p-3 text-left hover:bg-gray-100 dark:hover:bg-gray-800/50 transition-colors\"\n >\n
    \n {tool.tool_name}\n
    \n {tool.relevance_score !== undefined && (\n \n {Math.round(tool.relevance_score * 100)}%\n \n )}\n \n
    \n
    \n {(tool.description || tool.match_context) && (\n

    \n {tool.description || tool.match_context}\n

    \n )}\n \n {isExpanded && (\n
    \n {tool.inputSchema && Object.keys(tool.inputSchema).length > 0 ? (\n <>\n

    \n Input Schema\n

    \n 
    \n                                {JSON.stringify(tool.inputSchema, null, 2)}\n
    \n \n ) : (\n

    \n No input schema available for this tool.\n

    \n )}\n
    \n )}\n
    • \n );\n })}\n
\n
\n )}\n\n {/* Status */}\n
\n

\n Status\n

\n
\n
\n \n {virtualServer.is_enabled ? 'Enabled' : 'Disabled'}\n \n
\n
\n\n {/* Relevance Score */}\n
\n

\n Match Score\n

\n \n {Math.round(Math.min(virtualServer.relevance_score, 1) * 100)}% match\n \n
\n
\n
\n
\n );\n};\n\n\ninterface VirtualServerResultCardProps {\n virtualServer: SemanticVirtualServerHit;\n onViewDetails: () => void;\n}\n\nconst VirtualServerResultCard: React.FC = ({\n virtualServer,\n onViewDetails\n}) => {\n const [showAllTools, setShowAllTools] = useState(false);\n const tools = virtualServer.matching_tools || [];\n const visibleTools = showAllTools ? tools : tools.slice(0, 3);\n const hasMoreTools = tools.length > 3;\n\n return (\n
\n
\n
\n
\n

\n {virtualServer.server_name}\n

\n \n VIRTUAL\n \n
\n

{virtualServer.path}

\n
\n
\n \n \n \n \n {Math.round(Math.min(virtualServer.relevance_score, 1) * 100)}% match\n \n
\n
\n\n

\n {virtualServer.description || virtualServer.match_context || 'No description available.'}\n

\n\n {virtualServer.tags && virtualServer.tags.length > 0 && (\n
\n {virtualServer.tags.slice(0, 6).map((tag) => (\n \n {tag}\n \n ))}\n
\n )}\n\n {/* Tools Section */}\n {tools.length > 0 && (\n
\n

\n Tools ({tools.length})\n

\n
    \n {visibleTools.map((tool) => (\n
  • \n
    \n {tool.tool_name}\n {tool.relevance_score !== undefined && (\n \n {Math.round(tool.relevance_score * 100)}%\n \n )}\n {(tool.description || tool.match_context) && (\n

    \n {tool.description || tool.match_context}\n

    \n )}\n
    \n
    • \n ))}\n
\n {hasMoreTools && (\n setShowAllTools(!showAllTools)}\n className=\"mt-2 text-xs text-indigo-600 dark:text-indigo-400 hover:underline\"\n >\n {showAllTools ? 'Show less' : `+${tools.length - 3} more tools...`}\n \n )}\n
\n )}\n\n
\n {virtualServer.backend_count || 0} backends\n {virtualServer.is_enabled ? 'Enabled' : 'Disabled'}\n
\n
\n );\n};\n\n\nconst formatPercent = (value: number) => `${Math.round(Math.min(value, 1) * 100)}%`;\n\nconst SemanticSearchResults: React.FC = ({\n query,\n loading,\n error,\n servers,\n tools,\n agents,\n skills,\n virtualServers = []\n}) => {\n const hasResults = servers.length > 0 || tools.length > 0 || agents.length > 0 || skills.length > 0 || virtualServers.length > 0;\n const [configServer, setConfigServer] = useState(null);\n const [detailsServer, setDetailsServer] = useState(null);\n const [detailsSkill, setDetailsSkill] = useState(null);\n const [detailsAgent, setDetailsAgent] = useState(null);\n const [detailsVirtualServer, setDetailsVirtualServer] = useState(null);\n const [agentDetailsData, setAgentDetailsData] = useState(null);\n const [agentDetailsLoading, setAgentDetailsLoading] = useState(false);\n const [selectedToolSchema, setSelectedToolSchema] = useState<{\n toolName: string;\n serverName: string;\n schema: Record | null;\n } | null>(null);\n\n // Build a lookup map from server_path + tool_name to inputSchema\n const toolSchemaMap = useMemo(() => {\n const map = new Map>();\n for (const tool of tools) {\n const key = `${tool.server_path}:${tool.tool_name}`;\n if (tool.inputSchema) {\n map.set(key, tool.inputSchema);\n }\n }\n return map;\n }, [tools]);\n\n const openToolSchema = (\n serverPath: string,\n serverName: string,\n toolName: string\n ) => {\n const key = `${serverPath}:${toolName}`;\n const schema = toolSchemaMap.get(key) || null;\n setSelectedToolSchema({ toolName, serverName, schema });\n };\n\n const openAgentDetails = async (agentHit: SemanticAgentHit) => {\n setDetailsAgent(agentHit);\n setAgentDetailsData(null);\n setAgentDetailsLoading(true);\n try {\n const response = await axios.get(`/api/agents${agentHit.path}`);\n setAgentDetailsData(response.data);\n } catch (error) {\n console.error('Failed to fetch agent details:', error);\n } finally {\n setAgentDetailsLoading(false);\n }\n };\n\n const mapHitToAgent = (hit: SemanticAgentHit): AgentType => {\n const card = hit.agent_card || {};\n // Derive trust_level from the top-level trust_verified field returned by search API\n const trustVerified = hit.trust_verified || 'none';\n let trustLevel: AgentType['trust_level'] = card.trust_level || 'unverified';\n if (trustVerified === 'verified') {\n trustLevel = 'verified';\n }\n return {\n name: card.name || hit.path.replace(/^\\//, ''),\n path: hit.path,\n url: card.url,\n description: card.description,\n version: card.version,\n visibility: (card.visibility as AgentType['visibility']) ?? 'public',\n trust_level: trustLevel,\n enabled: card.is_enabled ?? true,\n tags: card.tags || [],\n status: 'unknown',\n ans_metadata: card.ans_metadata || card.ansMetadata || undefined,\n };\n };\n\n return (\n <>\n
\n
\n
\n

\n Semantic Search\n

\n

\n Results for “{query}”\n

\n
\n {loading && (\n
\n \n Searching…\n
\n )}\n
\n\n {error && (\n
\n {error}\n
\n )}\n\n {!loading && !error && !hasResults && (\n
\n

\n No semantic matches found\n

\n

\n Try refining your query or describing the tools or capabilities you need. Semantic\n search understands natural language — phrases like “servers that handle authentication”\n or “tools for syncing calendars” work great.\n

\n
\n )}\n\n {servers.length > 0 && (\n
\n
\n

\n Matching Servers ({servers.length})\n

\n
\n \n {servers.map((server) => {\n // Detect if server is from a peer registry using sync_metadata\n const isFederatedServer = server.sync_metadata?.is_federated === true;\n const peerRegistryId = isFederatedServer && server.sync_metadata?.source_peer_id\n ? server.sync_metadata.source_peer_id.replace('peer-registry-', '').replace('peer-', '').toUpperCase()\n : null;\n const isOrphanedServer = server.sync_metadata?.is_orphaned === true;\n\n return (\n \n
\n
\n
\n

\n {server.server_name}\n

\n {/* Registry source badge - only show for federated (peer registry) items */}\n {isFederatedServer && (\n \n {peerRegistryId}\n \n )}\n {/* Orphaned badge */}\n {isOrphanedServer && (\n \n ORPHANED\n \n )}\n
\n

{server.path}

\n
\n
\n setDetailsServer(server)}\n className=\"p-2 text-gray-400 hover:text-purple-600 dark:hover:text-purple-300 hover:bg-purple-50 dark:hover:bg-purple-700/30 rounded-lg transition-colors\"\n title=\"View server details\"\n >\n \n \n setConfigServer(server)}\n className=\"p-2 text-gray-400 hover:text-green-600 dark:hover:text-green-300 hover:bg-green-50 dark:hover:bg-green-700/30 rounded-lg transition-colors\"\n title=\"Open MCP configuration\"\n >\n \n \n \n {formatPercent(server.relevance_score)} match\n \n
\n
\n

\n {server.description || server.match_context || 'No description available.'}\n

\n\n {server.tags?.length > 0 && (\n
\n {server.tags.slice(0, 6).map((tag) => (\n \n {tag}\n \n ))}\n
\n )}\n\n {server.matching_tools?.length > 0 && (\n
\n

\n Relevant tools\n

\n
    \n {server.matching_tools.slice(0, 3).map((tool) => (\n
  • \n
    \n {tool.tool_name}\n -\n \n {tool.description || tool.match_context || 'No description'}\n \n
    \n openToolSchema(server.path, server.server_name, tool.tool_name)}\n className=\"flex-shrink-0 p-1 text-gray-400 hover:text-blue-600 dark:hover:text-blue-400 rounded transition-colors\"\n title=\"View input schema\"\n >\n \n \n
    • \n ))}\n
\n
\n )}\n
\n );\n })}\n
\n \n )}\n\n {tools.length > 0 && (\n
\n
\n

\n Matching Tools ({tools.length})\n

\n
\n \n {tools.map((tool) => (\n \n
\n

\n {tool.tool_name}\n \n ({tool.server_name})\n \n

\n

\n {tool.description || tool.match_context || 'No description available.'}\n

\n
\n
\n setSelectedToolSchema({\n toolName: tool.tool_name,\n serverName: tool.server_name,\n schema: tool.inputSchema || null\n })}\n className=\"p-1.5 text-gray-400 hover:text-blue-600 dark:hover:text-blue-400 hover:bg-blue-50 dark:hover:bg-blue-900/30 rounded-lg transition-colors\"\n title=\"View input schema\"\n >\n \n \n \n {formatPercent(tool.relevance_score)} match\n \n
\n
\n ))}\n
\n \n )}\n\n {agents.length > 0 && (\n
\n
\n

\n Matching Agents ({agents.length})\n

\n
\n \n {agents.map((agent) => {\n // Extract agent details from agent_card\n const card = agent.agent_card || {};\n const agentName = card.name || agent.path.replace(/^\\//, '');\n const agentDescription = card.description;\n const agentTags = card.tags || [];\n const agentVisibility = card.visibility || 'public';\n const trustVerified = agent.trust_verified || 'none';\n const agentTrustLevel = trustVerified === 'verified' ? 'verified' : (card.trust_level || 'unverified');\n const agentIsEnabled = card.is_enabled ?? false;\n const syncMetadata = card.sync_metadata;\n\n // Extract skill names from agent_card.skills (array of skill objects)\n const rawSkills = card.skills || [];\n const skillNames = rawSkills.map((s: any) =>\n typeof s === 'string' ? s : s?.name || s?.id\n ).filter(Boolean);\n\n // Detect if agent is from a peer registry using sync_metadata\n const isFederatedAgent = syncMetadata?.is_federated === true;\n const peerRegistryId = isFederatedAgent && syncMetadata?.source_peer_id\n ? syncMetadata.source_peer_id.replace('peer-registry-', '').replace('peer-', '').toUpperCase()\n : null;\n const isOrphanedAgent = syncMetadata?.is_orphaned === true;\n\n return (\n \n
\n
\n
\n

\n {agentName}\n

\n {/* Registry source badge - only show for federated (peer registry) items */}\n {isFederatedAgent && (\n \n {peerRegistryId}\n \n )}\n {/* Orphaned badge */}\n {isOrphanedAgent && (\n \n ORPHANED\n \n )}\n
\n

\n {agentVisibility}\n

\n
\n
\n openAgentDetails(agent)}\n className=\"p-2 text-gray-400 hover:text-cyan-600 dark:hover:text-cyan-300 hover:bg-cyan-50 dark:hover:bg-cyan-700/30 rounded-lg transition-colors\"\n title=\"View full agent details\"\n >\n \n \n \n {formatPercent(agent.relevance_score)} match\n \n
\n
\n\n

\n {agentDescription || agent.match_context || 'No description available.'}\n

\n\n {skillNames.length > 0 && (\n
\n

\n Key Skills\n

\n

\n {skillNames.slice(0, 4).join(', ')}\n {skillNames.length > 4 && '…'}\n

\n
\n )}\n\n {agentTags.length > 0 && (\n
\n {agentTags.slice(0, 6).map((tag: string) => (\n \n {tag}\n \n ))}\n
\n )}\n\n
\n {(card.ans_metadata || card.ansMetadata) ? (\n \n ) : (\n \n {agentTrustLevel}\n \n )}\n {agentIsEnabled ? 'Enabled' : 'Disabled'}\n
\n
\n );\n })}\n
\n \n )}\n\n {skills.length > 0 && (\n
\n
\n

\n Matching Skills ({skills.length})\n

\n
\n \n {skills.map((skill) => (\n \n
\n
\n
\n

\n {skill.skill_name}\n

\n \n SKILL\n \n
\n

\n {skill.visibility || 'public'}\n

\n
\n
\n setDetailsSkill(skill)}\n className=\"p-2 text-gray-400 hover:text-amber-600 dark:hover:text-amber-300 hover:bg-amber-50 dark:hover:bg-amber-700/30 rounded-lg transition-colors\"\n title=\"View SKILL.md content\"\n >\n \n \n \n {formatPercent(skill.relevance_score)} match\n \n
\n
\n\n

\n {skill.description || skill.match_context || 'No description available.'}\n

\n\n {skill.tags && skill.tags.length > 0 && (\n
\n {skill.tags.slice(0, 6).map((tag) => (\n \n {tag}\n \n ))}\n
\n )}\n\n
\n
\n {skill.author && (\n by {skill.author}\n )}\n {skill.version && (\n v{skill.version}\n )}\n
\n {skill.is_enabled ? 'Enabled' : 'Disabled'}\n
\n
\n ))}\n
\n \n )}\n\n {virtualServers.length > 0 && (\n
\n
\n

\n Matching Virtual Servers ({virtualServers.length})\n

\n
\n \n {virtualServers.map((vs) => (\n setDetailsVirtualServer(vs)}\n />\n ))}\n
\n \n )}\n
\n\n {configServer && (\n setConfigServer(null)}\n />\n )}\n\n {detailsAgent && (\n setDetailsAgent(null)}\n loading={agentDetailsLoading}\n fullDetails={agentDetailsData}\n />\n )}\n\n {selectedToolSchema && (\n setSelectedToolSchema(null)}\n />\n )}\n\n {detailsServer && (\n setDetailsServer(null)}\n />\n )}\n\n {detailsSkill && (\n setDetailsSkill(null)}\n />\n )}\n\n {detailsVirtualServer && (\n setDetailsVirtualServer(null)}\n />\n )}\n \n );\n};\n\nexport default SemanticSearchResults;\n" }, { "path": "frontend/src/components/ServerCard.tsx", "content": "import React, { useState, useCallback, useEffect } from 'react';\nimport axios from 'axios';\nimport {\n EyeIcon,\n WrenchScrewdriverIcon,\n StarIcon,\n ArrowPathIcon,\n PencilIcon,\n ClockIcon,\n CheckCircleIcon,\n XCircleIcon,\n QuestionMarkCircleIcon,\n CogIcon,\n LinkIcon,\n ShieldCheckIcon,\n ShieldExclamationIcon,\n TrashIcon,\n InformationCircleIcon,\n} from '@heroicons/react/24/outline';\nimport ServerConfigModal from './ServerConfigModal';\nimport SecurityScanModal from './SecurityScanModal';\nimport StarRatingWidget from './StarRatingWidget';\nimport VersionBadge from './VersionBadge';\nimport VersionSelectorModal from './VersionSelectorModal';\nimport DeleteConfirmation from './DeleteConfirmation';\nimport StatusBadge from './StatusBadge';\nimport { ANSBadge } from './ANSBadge';\nimport ServerDetailsModal from './ServerDetailsModal';\nimport useEscapeKey from '../hooks/useEscapeKey';\nimport { formatRelativeTime } from '../utils/dateUtils';\n\ninterface ServerVersion {\n version: string;\n proxy_pass_url: string;\n status: string;\n is_default: boolean;\n released?: string;\n sunset_date?: string;\n description?: string;\n}\n\ninterface SyncMetadata {\n is_federated?: boolean;\n source_peer_id?: string;\n upstream_path?: string;\n last_synced_at?: string;\n is_read_only?: boolean;\n is_orphaned?: boolean;\n orphaned_at?: string;\n}\n\nexport interface Server {\n name: string;\n path: string;\n description?: string;\n official?: boolean;\n enabled: boolean;\n tags?: string[];\n last_checked_time?: string;\n usersCount?: number;\n rating_details?: Array<{ user: string; rating: number }>;\n status?: 'healthy' | 'healthy-auth-expired' | 'unhealthy' | 'unknown';\n num_tools?: number;\n proxy_pass_url?: string;\n mcp_endpoint?: string;\n // Version routing fields\n version?: string; // Current active version\n versions?: ServerVersion[];\n default_version?: string;\n // MCP server info from initialize response\n mcp_server_version?: string;\n mcp_server_version_previous?: string;\n mcp_server_version_updated_at?: string;\n // Federation sync metadata\n sync_metadata?: SyncMetadata;\n // Backend authentication\n auth_scheme?: string;\n auth_header_name?: string;\n // Lifecycle status\n lifecycle_status?: 'active' | 'deprecated' | 'draft' | 'beta';\n source_created_at?: string;\n source_updated_at?: string;\n // ANS Integration\n ans_metadata?: {\n ans_agent_id: string;\n status: 'verified' | 'expired' | 'revoked' | 'not_found' | 'pending';\n domain?: string;\n organization?: string;\n certificate?: {\n not_after?: string;\n subject_dn?: string;\n issuer_dn?: string;\n };\n last_verified?: string;\n };\n}\n\ninterface ServerCardProps {\n server: Server;\n onToggle: (path: string, enabled: boolean) => void;\n onEdit?: (server: Server) => void;\n canModify?: boolean;\n canHealthCheck?: boolean;\n canToggle?: boolean;\n canDelete?: boolean;\n onRefreshSuccess?: () => void;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n onServerUpdate?: (path: string, updates: Partial) => void;\n onDelete?: (path: string) => Promise;\n authToken?: string | null;\n}\n\ninterface Tool {\n name: string;\n description?: string;\n schema?: any;\n}\n\n// Helper function to format time since last checked\nconst formatTimeSince = (timestamp: string | null | undefined): string | null => {\n if (!timestamp) {\n return null;\n }\n \n try {\n const now = new Date();\n const lastChecked = new Date(timestamp);\n \n // Check if the date is valid\n if (isNaN(lastChecked.getTime())) {\n return null;\n }\n \n const diffMs = now.getTime() - lastChecked.getTime();\n \n const diffSeconds = Math.floor(diffMs / 1000);\n const diffMinutes = Math.floor(diffSeconds / 60);\n const diffHours = Math.floor(diffMinutes / 60);\n const diffDays = Math.floor(diffHours / 24);\n \n let result;\n if (diffSeconds < 0) {\n result = 'just now';\n } else if (diffDays > 0) {\n result = `${diffDays}d ago`;\n } else if (diffHours > 0) {\n result = `${diffHours}h ago`;\n } else if (diffMinutes > 0) {\n result = `${diffMinutes}m ago`;\n } else {\n result = `${diffSeconds}s ago`;\n }\n \n return result;\n } catch (error) {\n console.error('formatTimeSince error:', error, 'for timestamp:', timestamp);\n return null;\n }\n};\n\nconst ServerCard: React.FC = React.memo(({ server, onToggle, onEdit, canModify, canHealthCheck = true, canToggle = true, canDelete, onRefreshSuccess, onShowToast, onServerUpdate, onDelete, authToken }) => {\n const [tools, setTools] = useState([]);\n const [loadingTools, setLoadingTools] = useState(false);\n const [showTools, setShowTools] = useState(false);\n const [showConfig, setShowConfig] = useState(false);\n const [loadingRefresh, setLoadingRefresh] = useState(false);\n const [showSecurityScan, setShowSecurityScan] = useState(false);\n const [securityScanResult, setSecurityScanResult] = useState(null);\n const [loadingSecurityScan, setLoadingSecurityScan] = useState(false);\n const [showVersionSelector, setShowVersionSelector] = useState(false);\n const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);\n const [showDetails, setShowDetails] = useState(false);\n const [expandedDescriptions, setExpandedDescriptions] = useState>(new Set());\n\n const closeToolsModal = useCallback(() => {\n setShowTools(false);\n setExpandedDescriptions(new Set());\n }, []);\n useEscapeKey(closeToolsModal, showTools);\n useEscapeKey(() => setShowDeleteConfirm(false), showDeleteConfirm);\n\n // Fetch security scan status on mount to show correct icon color\n useEffect(() => {\n const fetchSecurityScan = async () => {\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/servers${server.path}/security-scan`,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n } catch {\n // Silently ignore - no scan result available\n }\n };\n fetchSecurityScan();\n }, [server.path, authToken]);\n\n const getStatusIcon = () => {\n switch (server.status) {\n case 'healthy':\n return ;\n case 'healthy-auth-expired':\n return ;\n case 'unhealthy':\n return ;\n default:\n return ;\n }\n };\n\n const getStatusColor = () => {\n switch (server.status) {\n case 'healthy':\n return 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400';\n case 'healthy-auth-expired':\n return 'bg-orange-100 text-orange-800 dark:bg-orange-900/30 dark:text-orange-400';\n case 'unhealthy':\n return 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400';\n default:\n return 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-200';\n }\n };\n\n const handleViewTools = useCallback(async () => {\n if (loadingTools) return;\n \n setLoadingTools(true);\n try {\n const response = await axios.get(`/api/tools${server.path}`);\n setTools(response.data.tools || []);\n setShowTools(true);\n } catch (error) {\n console.error('Failed to fetch tools:', error);\n if (onShowToast) {\n onShowToast('Failed to fetch tools', 'error');\n }\n } finally {\n setLoadingTools(false);\n }\n }, [server.path, loadingTools, onShowToast]);\n\n const handleRefreshHealth = useCallback(async () => {\n if (loadingRefresh) return;\n \n setLoadingRefresh(true);\n try {\n // Extract service name from path (remove leading slash)\n const serviceName = server.path.replace(/^\\//, '');\n \n const response = await axios.post(`/api/refresh/${serviceName}`);\n \n // Update just this server instead of triggering global refresh\n if (onServerUpdate && response.data) {\n const updates: Partial = {\n status: response.data.status === 'healthy' ? 'healthy' : \n response.data.status === 'healthy-auth-expired' ? 'healthy-auth-expired' :\n response.data.status === 'unhealthy' ? 'unhealthy' : 'unknown',\n last_checked_time: response.data.last_checked_iso,\n num_tools: response.data.num_tools\n };\n \n onServerUpdate(server.path, updates);\n } else if (onRefreshSuccess) {\n // Fallback to global refresh if onServerUpdate is not provided\n onRefreshSuccess();\n }\n \n if (onShowToast) {\n onShowToast('Health status refreshed successfully', 'success');\n }\n } catch (error: any) {\n console.error('Failed to refresh health:', error);\n if (onShowToast) {\n onShowToast(error.response?.data?.detail || 'Failed to refresh health status', 'error');\n }\n } finally {\n setLoadingRefresh(false);\n }\n }, [server.path, loadingRefresh, onRefreshSuccess, onShowToast, onServerUpdate]);\n\n const handleViewSecurityScan = useCallback(async () => {\n if (loadingSecurityScan) return;\n\n setShowSecurityScan(true);\n setLoadingSecurityScan(true);\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/servers${server.path}/security-scan`,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n } catch (error: any) {\n if (error.response?.status !== 404) {\n console.error('Failed to fetch security scan:', error);\n if (onShowToast) {\n onShowToast('Failed to load security scan results', 'error');\n }\n }\n setSecurityScanResult(null);\n } finally {\n setLoadingSecurityScan(false);\n }\n }, [server.path, authToken, loadingSecurityScan, onShowToast]);\n\n const handleRescan = useCallback(async () => {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.post(\n `/api/servers${server.path}/rescan`,\n undefined,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n }, [server.path, authToken]);\n\n const handleRefreshServerData = useCallback(async () => {\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/server_details${server.path}`,\n headers ? { headers } : undefined\n );\n\n if (onServerUpdate && response.data) {\n const serverData = response.data;\n const updates: Partial = {\n name: serverData.server_name,\n description: serverData.description,\n enabled: serverData.is_enabled,\n tags: serverData.tags,\n status: serverData.health_status === 'healthy' ? 'healthy' :\n serverData.health_status === 'healthy-auth-expired' ? 'healthy-auth-expired' :\n serverData.health_status === 'unhealthy' ? 'unhealthy' : 'unknown',\n last_checked_time: serverData.last_checked_iso,\n num_tools: serverData.num_tools,\n proxy_pass_url: serverData.proxy_pass_url,\n mcp_endpoint: serverData.mcp_endpoint,\n version: serverData.version,\n versions: serverData.versions,\n default_version: serverData.default_version,\n mcp_server_version: serverData.mcp_server_version,\n mcp_server_version_previous: serverData.mcp_server_version_previous,\n mcp_server_version_updated_at: serverData.mcp_server_version_updated_at,\n };\n onServerUpdate(server.path, updates);\n }\n } catch (error) {\n console.error('Failed to refresh server data:', error);\n }\n }, [server.path, authToken, onServerUpdate]);\n\n const getSecurityIconState = () => {\n // Gray: no scan result yet\n if (!securityScanResult) {\n return { Icon: ShieldCheckIcon, color: 'text-gray-400 dark:text-gray-500', title: 'View security scan results' };\n }\n // Red: scan failed or any vulnerabilities found\n if (securityScanResult.scan_failed) {\n return { Icon: ShieldExclamationIcon, color: 'text-red-500 dark:text-red-400', title: 'Security scan failed' };\n }\n const hasVulnerabilities = securityScanResult.critical_issues > 0 ||\n securityScanResult.high_severity > 0 ||\n securityScanResult.medium_severity > 0 ||\n securityScanResult.low_severity > 0;\n if (hasVulnerabilities) {\n return { Icon: ShieldExclamationIcon, color: 'text-red-500 dark:text-red-400', title: 'Security issues found' };\n }\n // Green: scan passed with no vulnerabilities\n return { Icon: ShieldCheckIcon, color: 'text-green-500 dark:text-green-400', title: 'Security scan passed' };\n };\n\n // Generate MCP configuration for the server\n // Check if this is an Anthropic registry server\n const isAnthropicServer = server.tags?.includes('anthropic-registry');\n\n // Check if this server has security pending\n const isSecurityPending = server.tags?.includes('security-pending');\n\n // Check if this is a federated server from a peer registry using sync_metadata\n const isFederatedServer = server.sync_metadata?.is_federated === true;\n const peerRegistryId = isFederatedServer && server.sync_metadata?.source_peer_id\n ? server.sync_metadata.source_peer_id\n : null;\n\n // Check if this server is orphaned (no longer exists on peer registry)\n const isOrphanedServer = server.sync_metadata?.is_orphaned === true;\n\n return (\n <>\n
\n {/* Render DeleteConfirmation inline when showDeleteConfirm is true */}\n {showDeleteConfirm ? (\n
\n setShowDeleteConfirm(false)}\n />\n
\n ) : (\n <>\n {/* Header */}\n
\n
\n
\n
\n

\n {server.name}\n

\n {server.lifecycle_status && server.lifecycle_status !== 'active' && (\n \n )}\n {server.official && (\n \n OFFICIAL\n \n )}\n {isAnthropicServer && (\n \n ANTHROPIC\n \n )}\n {/* Check if this is an ASOR server */}\n {server.tags?.includes('asor') && (\n \n ASOR\n \n )}\n {isSecurityPending && (\n \n SECURITY PENDING\n \n )}\n {/* ANS badge moved to trust bar below description */}\n {/* Registry source badge - only show for federated (peer registry) items */}\n {isFederatedServer && (\n \n {peerRegistryId?.toUpperCase().replace('PEER-REGISTRY-', '').replace('PEER-', '')}\n \n )}\n {/* Orphaned badge - server no longer exists on peer registry */}\n {isOrphanedServer && (\n \n ORPHANED\n \n )}\n {/* Backend auth scheme badge */}\n {server.auth_scheme && server.auth_scheme !== 'none' && server.auth_scheme === 'bearer' && (\n \n BEARER AUTH\n \n )}\n {server.auth_scheme && server.auth_scheme === 'api_key' && (\n \n API KEY AUTH\n \n )}\n
\n \n \n {server.path}\n \n
\n\n {canModify && (\n onEdit?.(server)}\n title=\"Edit server\"\n aria-label={`Edit ${server.name}`}\n >\n \n \n )}\n\n {/* Connect Button */}\n setShowConfig(true)}\n className=\"flex items-center gap-1 px-2 py-1.5 text-xs font-medium text-green-600 dark:text-green-400 hover:bg-green-50 dark:hover:bg-green-700/50 rounded-lg transition-all duration-200 flex-shrink-0 border border-green-200 dark:border-green-700\"\n title=\"Get connection details and mcp.json configuration\"\n aria-label={`Connect to ${server.name}`}\n >\n \n Connect\n \n\n {/* Security Scan Button */}\n \n {React.createElement(getSecurityIconState().Icon, { className: \"h-4 w-4\" })}\n \n\n {/* Delete Button */}\n {canDelete && (\n setShowDeleteConfirm(true)}\n className=\"p-2 text-gray-400 hover:text-red-600 dark:hover:text-red-400 hover:bg-red-50 dark:hover:bg-red-700/50 rounded-lg transition-all duration-200 flex-shrink-0\"\n title=\"Delete server\"\n aria-label={`Delete ${server.name}`}\n >\n \n \n )}\n
\n\n {/* Description */}\n

\n {server.description || 'No description available'}\n

\n\n {/* ANS Trust Bar */}\n {server.ans_metadata && (\n
\n \n \n {server.ans_metadata.domain || server.ans_metadata.ans_agent_id}\n \n
\n )}\n\n {/* Tags */}\n {server.tags && server.tags.length > 0 && (\n
\n {server.tags.slice(0, 3).map((tag) => (\n \n #{tag}\n \n ))}\n {server.tags.length > 3 && (\n \n +{server.tags.length - 3}\n \n )}\n
\n )}\n
\n\n {/* Stats */}\n
\n
\n \n
\n {(server.num_tools || 0) > 0 ? (\n \n
\n \n
\n
\n
{server.num_tools}
\n
Tools
\n
\n \n ) : (\n
\n
\n \n
\n
\n
{server.num_tools || 0}
\n
Tools
\n
\n
\n )}\n
\n {/* Version display - user routing version and/or MCP server version */}\n
\n {server.versions && server.versions.length > 1 && (\n setShowVersionSelector(true)}\n />\n )}\n {server.mcp_server_version && (\n \n srv\n {server.mcp_server_version}\n {server.mcp_server_version_updated_at &&\n (Date.now() - new Date(server.mcp_server_version_updated_at).getTime()) < 24 * 60 * 60 * 1000 && (\n \n )}\n \n )}\n
\n
\n
\n\n {/* Footer */}\n
\n
\n
\n {/* Status Indicators */}\n
\n
\n \n {server.enabled ? 'Enabled' : 'Disabled'}\n \n
\n \n
\n \n
\n
\n \n {server.status === 'healthy' ? 'Healthy' : \n server.status === 'healthy-auth-expired' ? 'Healthy (Auth Expired)' :\n server.status === 'unhealthy' ? 'Unhealthy' : 'Unknown'}\n \n
\n
\n\n {/* Controls */}\n
\n {/* Last Updated (source timestamp) */}\n {server.source_updated_at && (\n
\n \n \n {formatRelativeTime(server.source_updated_at)}\n \n
\n )}\n\n {/* Last Checked */}\n {(() => {\n const timeText = formatTimeSince(server.last_checked_time);\n return server.last_checked_time && timeText && !server.source_updated_at ? (\n
\n \n {timeText}\n
\n ) : null;\n })()}\n\n {/* Refresh Button - only show if user has health_check_service permission */}\n {canHealthCheck && (\n \n \n \n )}\n\n {/* Toggle Switch - only show if user has toggle_service permission */}\n {canToggle && (\n
\n
\n \n )}\n
\n\n {/* Tools Modal */}\n {showTools && (\n {\n setShowTools(false);\n setExpandedDescriptions(new Set());\n }}\n >\n e.stopPropagation()}\n >\n
\n

\n Tools for {server.name}\n

\n {\n setShowTools(false);\n setExpandedDescriptions(new Set());\n }}\n className=\"text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200\"\n >\n ✕\n \n
\n \n
\n {tools.length > 0 ? (\n tools.map((tool, index) => {\n const isExpanded = expandedDescriptions.has(index);\n const toggleExpand = () => {\n const newExpanded = new Set(expandedDescriptions);\n if (isExpanded) {\n newExpanded.delete(index);\n } else {\n newExpanded.add(index);\n }\n setExpandedDescriptions(newExpanded);\n };\n\n return (\n
\n

\n {tool.name}\n

\n {tool.description && (\n
\n

\n {tool.description}\n

\n {tool.description.length > 150 && (\n \n {isExpanded ? 'Show less' : 'Show more'}\n \n )}\n
\n )}\n {tool.schema && (\n
\n \n View Schema\n \n 
\n                            {JSON.stringify(tool.schema, null, 2)}\n
\n
\n )}\n
\n );\n })\n ) : (\n

No tools available for this server.

\n )}\n
\n
\n
\n )}\n\n setShowConfig(false)}\n onShowToast={onShowToast}\n />\n\n setShowSecurityScan(false)}\n loading={loadingSecurityScan}\n scanResult={securityScanResult}\n onRescan={canModify ? handleRescan : undefined}\n canRescan={canModify}\n onShowToast={onShowToast}\n />\n\n setShowVersionSelector(false)}\n serverName={server.name}\n serverPath={server.path}\n versions={server.versions || []}\n defaultVersion={server.default_version || null}\n onVersionChange={(newDefaultVersion) => {\n if (onServerUpdate) {\n // Update both default_version and versions array to reflect the change\n const updatedVersions = server.versions?.map(v => ({\n ...v,\n is_default: v.version === newDefaultVersion\n }));\n onServerUpdate(server.path, {\n default_version: newDefaultVersion,\n versions: updatedVersions\n });\n }\n }}\n onRefreshServer={handleRefreshServerData}\n onShowToast={onShowToast}\n authToken={authToken}\n canModify={canModify}\n />\n\n setShowDetails(false)}\n fullDetails={server}\n />\n\n \n );\n});\n\nServerCard.displayName = 'ServerCard';\n\nexport default ServerCard;\n" }, { "path": "frontend/src/components/ServerConfigModal.tsx", "content": "import React, { useCallback, useState, useEffect } from 'react';\nimport { ClipboardDocumentIcon, KeyIcon } from '@heroicons/react/24/outline';\nimport axios from 'axios';\nimport type { Server } from './ServerCard';\nimport { useRegistryConfig } from '../hooks/useRegistryConfig';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\ntype IDE = 'cursor' | 'roo-code' | 'claude-code' | 'kiro';\n\ninterface ServerConfigModalProps {\n server: Server;\n isOpen: boolean;\n onClose: () => void;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n}\n\nconst ServerConfigModal: React.FC = ({\n server,\n isOpen,\n onClose,\n onShowToast,\n}) => {\n const [selectedIDE, setSelectedIDE] = useState('cursor');\n const [jwtToken, setJwtToken] = useState(null);\n const [tokenLoading, setTokenLoading] = useState(false);\n const [tokenError, setTokenError] = useState(null);\n const [copied, setCopied] = useState(false);\n const { config: registryConfig, loading: configLoading } = useRegistryConfig();\n\n useEscapeKey(onClose, isOpen);\n\n // Determine if we're in registry-only mode\n // While config is loading, default to with-gateway behavior (safer default)\n const isRegistryOnly = !configLoading && registryConfig?.deployment_mode === 'registry-only';\n\n // Fetch JWT token when modal opens (only in gateway mode)\n // We intentionally only depend on isOpen and isRegistryOnly to fetch once per modal open\n useEffect(() => {\n if (isOpen && !isRegistryOnly) {\n // Reset token state when modal opens\n setJwtToken(null);\n setTokenError(null);\n fetchJwtToken();\n }\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [isOpen, isRegistryOnly]);\n\n const fetchJwtToken = async () => {\n setTokenLoading(true);\n setTokenError(null);\n try {\n const response = await axios.post('/api/tokens/generate', {\n description: 'Generated for MCP configuration',\n expires_in_hours: 8,\n }, {\n headers: {\n 'Content-Type': 'application/json',\n },\n });\n\n if (response.data.success) {\n // Token can be in response.data.tokens.access_token or response.data.access_token\n const accessToken = response.data.tokens?.access_token || response.data.access_token;\n if (accessToken) {\n setJwtToken(accessToken);\n } else {\n setTokenError('Token not found in response');\n }\n } else {\n setTokenError('Token generation failed');\n }\n } catch (err: any) {\n const status = err.response?.status;\n const errorMessage = err.response?.data?.detail || err.message || 'Failed to generate token';\n\n // Provide more helpful error messages based on status\n if (status === 401 || status === 403) {\n setTokenError('Authentication required. Please log in first.');\n } else {\n setTokenError(errorMessage);\n }\n console.error('Failed to fetch JWT token:', err);\n } finally {\n setTokenLoading(false);\n }\n };\n\n const generateMCPConfig = useCallback(() => {\n const serverName = server.name.toLowerCase().replace(/\\s+/g, '-').replace(/[^a-z0-9-]/g, '');\n\n // URL determination with fallback chain:\n // 1. mcp_endpoint (custom override) - always takes precedence\n // 2. proxy_pass_url (in registry-only mode)\n // 3. Constructed gateway URL (default/fallback)\n let url: string;\n\n if (server.mcp_endpoint) {\n url = server.mcp_endpoint;\n } else if (isRegistryOnly && server.proxy_pass_url) {\n url = server.proxy_pass_url;\n } else {\n const currentUrl = new URL(window.location.origin);\n const baseUrl = `${currentUrl.protocol}//${currentUrl.hostname}`;\n const cleanPath = server.path.replace(/\\/+$/, '').replace(/^\\/+/, '/');\n url = `${baseUrl}${cleanPath}/mcp`;\n }\n\n // In registry-only mode, don't include gateway auth headers\n const includeAuthHeaders = !isRegistryOnly;\n\n // Use actual JWT token if available, otherwise show placeholder\n const authToken = jwtToken || '[YOUR_GATEWAY_AUTH_TOKEN]';\n\n // Build headers object with both gateway auth and server auth (if applicable)\n const buildHeaders = () => {\n const headers: Record = {};\n\n // Add gateway authentication header\n headers['X-Authorization'] = `Bearer ${authToken}`;\n\n // Add server authentication headers if server requires auth\n if (server.auth_scheme && server.auth_scheme !== 'none') {\n if (server.auth_scheme === 'bearer') {\n headers['Authorization'] = 'Bearer [YOUR_SERVER_AUTH_TOKEN]';\n } else if (server.auth_scheme === 'api_key') {\n const headerName = server.auth_header_name || 'X-API-Key';\n headers[headerName] = '[YOUR_API_KEY]';\n }\n }\n\n return headers;\n };\n\n switch (selectedIDE) {\n case 'cursor':\n return {\n mcpServers: {\n [serverName]: {\n url,\n ...(includeAuthHeaders && {\n headers: buildHeaders(),\n }),\n },\n },\n };\n case 'roo-code':\n return {\n mcpServers: {\n [serverName]: {\n type: 'streamable-http',\n url,\n disabled: false,\n ...(includeAuthHeaders && {\n headers: buildHeaders(),\n }),\n },\n },\n };\n case 'claude-code':\n return {\n mcpServers: {\n [serverName]: {\n type: 'http',\n url,\n ...(includeAuthHeaders && {\n headers: buildHeaders(),\n }),\n },\n },\n };\n case 'kiro':\n return {\n mcpServers: {\n [serverName]: {\n url,\n ...(includeAuthHeaders && {\n headers: buildHeaders(),\n }),\n disabled: false,\n autoApprove: [],\n },\n },\n };\n default:\n return {\n mcpServers: {\n [serverName]: {\n url,\n ...(includeAuthHeaders && {\n headers: buildHeaders(),\n }),\n },\n },\n };\n }\n }, [server.name, server.path, server.proxy_pass_url, server.mcp_endpoint, server.auth_scheme, server.auth_header_name, selectedIDE, isRegistryOnly, jwtToken]);\n\n const generateClaudeCodeCommand = useCallback(() => {\n const serverName = server.name.toLowerCase().replace(/\\s+/g, '-').replace(/[^a-z0-9-]/g, '');\n\n // URL determination (same logic as generateMCPConfig)\n let url: string;\n if (server.mcp_endpoint) {\n url = server.mcp_endpoint;\n } else if (isRegistryOnly && server.proxy_pass_url) {\n url = server.proxy_pass_url;\n } else {\n const currentUrl = new URL(window.location.origin);\n const baseUrl = `${currentUrl.protocol}//${currentUrl.hostname}`;\n const cleanPath = server.path.replace(/\\/+$/, '').replace(/^\\/+/, '/');\n url = `${baseUrl}${cleanPath}/mcp`;\n }\n\n const includeAuthHeaders = !isRegistryOnly;\n const authToken = jwtToken || '[YOUR_GATEWAY_AUTH_TOKEN]';\n\n // Build command with headers\n let command = `claude mcp add --transport http ${serverName} ${url}`;\n\n if (includeAuthHeaders) {\n // Add gateway auth header\n command += ` \\\\\\n --header \"X-Authorization: Bearer ${authToken}\"`;\n\n // Add server auth header if applicable\n if (server.auth_scheme && server.auth_scheme !== 'none') {\n if (server.auth_scheme === 'bearer') {\n command += ` \\\\\\n --header \"Authorization: Bearer [YOUR_SERVER_AUTH_TOKEN]\"`;\n } else if (server.auth_scheme === 'api_key') {\n const headerName = server.auth_header_name || 'X-API-Key';\n command += ` \\\\\\n --header \"${headerName}: [YOUR_API_KEY]\"`;\n }\n }\n }\n\n return command;\n }, [server.name, server.path, server.proxy_pass_url, server.mcp_endpoint, server.auth_scheme, server.auth_header_name, isRegistryOnly, jwtToken]);\n\n\n const copyConfigToClipboard = useCallback(async () => {\n try {\n const config = generateMCPConfig();\n const configText = JSON.stringify(config, null, 2);\n await navigator.clipboard.writeText(configText);\n\n // Show visual feedback\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n\n onShowToast?.('Configuration copied to clipboard!', 'success');\n } catch (error) {\n console.error('Failed to copy to clipboard:', error);\n onShowToast?.('Failed to copy configuration', 'error');\n }\n }, [generateMCPConfig, onShowToast]);\n\n const copyCommandToClipboard = useCallback(async () => {\n try {\n const command = generateClaudeCodeCommand();\n await navigator.clipboard.writeText(command);\n\n // Show visual feedback\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n\n onShowToast?.('Command copied to clipboard!', 'success');\n } catch (error) {\n console.error('Failed to copy to clipboard:', error);\n onShowToast?.('Failed to copy command', 'error');\n }\n }, [generateClaudeCodeCommand, onShowToast]);\n\n if (!isOpen) {\n return null;\n }\n\n return (\n
\n
\n
\n

\n MCP Configuration for {server.name}\n

\n \n ✕\n \n
\n\n
\n
\n

\n How to use this configuration:\n

\n
    \n
  1. Copy the configuration below
    2. \n
  2. \n Paste it into your mcp.json file\n
    3. \n {!isRegistryOnly && !jwtToken && (\n
  3. \n Replace [YOUR_AUTH_TOKEN] with your\n gateway authentication token (or wait for auto-generation)\n
    4. \n )}\n
  4. Restart your AI coding assistant to load the new configuration
    5. \n
\n
\n\n {!isRegistryOnly ? (\n
\n
\n

\n {tokenLoading\n ? 'Fetching Token...'\n : jwtToken\n ? 'Token Ready - Copy and Paste!'\n : tokenError\n ? 'Token Generation Failed'\n : 'Authentication Required'}\n

\n {!tokenLoading && (\n \n \n {jwtToken ? 'Refresh' : 'Get Token'}\n \n )}\n
\n {tokenLoading ? (\n

\n Generating JWT token for your configuration...\n

\n ) : jwtToken ? (\n

\n JWT token has been automatically added to the configuration below. You can copy and paste it directly into your mcp.json file. Token expires in 8 hours.\n

\n ) : tokenError ? (\n

\n {tokenError}. Click "Get Token" to retry, or manually replace [YOUR_AUTH_TOKEN] with your gateway token.\n

\n ) : (\n

\n This configuration requires gateway authentication tokens. The tokens authenticate your AI assistant with\n the MCP Gateway, not the individual server.\n

\n )}\n
\n ) : (\n
\n

Direct Connection Mode

\n

\n This registry operates in catalog-only mode. The configuration connects directly to the MCP server\n endpoint without going through a gateway proxy.\n

\n

\n Note: The MCP server may still require authentication (API key, auth header, etc.).\n Check the server's documentation to determine if any credentials are needed.\n

\n
\n )}\n\n {server.mcp_endpoint && (\n
\n

Custom Endpoint Configured

\n

\n This server uses a custom MCP endpoint:{' '}\n {server.mcp_endpoint}\n

\n
\n )}\n\n
\n

Select your IDE/Tool:

\n
\n {(['cursor', 'roo-code', 'claude-code', 'kiro'] as IDE[]).map((ide) => (\n setSelectedIDE(ide)}\n className={`px-3 py-2 rounded-lg text-sm font-medium transition-colors ${\n selectedIDE === ide\n ? 'bg-blue-600 text-white'\n : 'bg-gray-200 dark:bg-gray-700 text-gray-700 dark:text-gray-300 hover:bg-gray-300 dark:hover:bg-gray-600'\n }`}\n >\n {ide === 'cursor'\n ? 'Cursor'\n : ide === 'roo-code'\n ? 'Roo Code'\n : ide === 'claude-code'\n ? 'Claude Code'\n : 'Kiro'}\n \n ))}\n
\n

\n Configuration format optimized for{' '}\n {selectedIDE === 'cursor'\n ? 'Cursor'\n : selectedIDE === 'roo-code'\n ? 'Roo Code'\n : selectedIDE === 'claude-code'\n ? 'Claude Code'\n : 'Kiro'}{' '}\n integration\n

\n
\n\n {selectedIDE === 'claude-code' ? (\n
\n
\n

CLI Command:

\n \n \n {copied ? 'Copied!' : 'Copy Command'}\n \n
\n 
\n                {generateClaudeCodeCommand()}\n
\n

\n Run this command in your terminal to add the MCP server to Claude Code.\n

\n
\n ) : selectedIDE === 'kiro' ? (\n
\n
\n

Kiro Configuration:

\n

\n Copy the JSON below and paste it into{' '}\n ~/.kiro/settings/mcp.json\n

\n
\n
\n

Configuration JSON:

\n \n \n {copied ? 'Copied!' : 'Copy to Clipboard'}\n \n
\n 
\n                {JSON.stringify(generateMCPConfig(), null, 2)}\n
\n
\n ) : (\n
\n
\n

Configuration JSON:

\n \n \n {copied ? 'Copied!' : 'Copy to Clipboard'}\n \n
\n 
\n                {JSON.stringify(generateMCPConfig(), null, 2)}\n
\n
\n )}\n
\n
\n
\n );\n};\n\nexport default ServerConfigModal;\n" }, { "path": "frontend/src/components/ServerDetailsModal.tsx", "content": "import React from 'react';\nimport { ClipboardDocumentIcon } from '@heroicons/react/24/outline';\nimport DetailsModal from './DetailsModal';\n\ninterface ServerDetailsModalProps {\n server: any;\n isOpen: boolean;\n onClose: () => void;\n loading?: boolean;\n error?: string | null;\n fullDetails?: any;\n onCopy?: (data: any) => Promise | void;\n}\n\n/**\n * ServerDetailsModal displays the complete server JSON schema.\n *\n * Features:\n * - Uses shared DetailsModal component\n * - Copy to clipboard functionality\n * - Field reference documentation\n * - Loading and error states\n */\nconst ServerDetailsModal: React.FC = ({\n server,\n isOpen,\n onClose,\n loading = false,\n error = null,\n fullDetails,\n onCopy,\n}) => {\n const dataToCopy = fullDetails || server;\n\n const handleCopy = async () => {\n try {\n if (onCopy) {\n await onCopy(dataToCopy);\n } else {\n await navigator.clipboard.writeText(JSON.stringify(dataToCopy, null, 2));\n }\n } catch (err) {\n console.error('Failed to copy server JSON:', err);\n }\n };\n\n return (\n \n
\n
\n

\n Complete Server Schema\n

\n

\n This is the complete MCP server definition stored in the registry. It includes all\n metadata, tools, authentication configuration, and runtime details.\n

\n
\n\n
\n
\n

Server JSON Schema:

\n \n \n Copy JSON\n \n
\n\n 
\n            {JSON.stringify(dataToCopy, null, 2)}\n
\n
\n\n
\n

Field Reference

\n
\n
\n
Core Fields
\n
    \n
  • \n name - Server\n display name\n
    • \n
  • \n path - Registry\n path\n
    • \n
  • \n description -\n Server purpose\n
    • \n
  • \n mcp_endpoint -\n MCP endpoint URL\n
    • \n
  • \n status -\n Lifecycle status (active/deprecated/draft/beta)\n
    • \n
\n
\n
\n
Metadata Fields
\n
    \n
  • \n enabled -\n Server enabled state\n
    • \n
  • \n tags -\n Categorization tags\n
    • \n
  • \n num_tools -\n Number of tools\n
    • \n
  • \n provider -\n Source registry information\n
    • \n
  • \n source_created_at{' '}\n - Creation timestamp\n
    • \n
\n
\n
\n
\n
\n \n );\n};\n\nexport default ServerDetailsModal;\n" }, { "path": "frontend/src/components/Sidebar.tsx", "content": "import React, { Fragment, useEffect, useState } from 'react';\nimport { Dialog, Transition } from '@headlessui/react';\nimport { Link, useLocation } from 'react-router-dom';\nimport {\n XMarkIcon,\n FunnelIcon,\n ChartBarIcon,\n KeyIcon,\n ArrowLeftIcon,\n ChevronDownIcon,\n ChevronUpIcon,\n ClipboardIcon,\n CheckIcon,\n ArrowDownTrayIcon,\n TagIcon,\n} from '@heroicons/react/24/outline';\nimport { useAuth } from '../contexts/AuthContext';\nimport axios from 'axios';\n\ninterface SidebarProps {\n sidebarOpen: boolean;\n setSidebarOpen: (open: boolean) => void;\n stats: {\n total: number;\n enabled: number;\n disabled: number;\n withIssues: number;\n };\n activeFilter: string;\n setActiveFilter: (filter: string) => void;\n availableTags: string[];\n selectedTags: string[];\n onTagSelect: (tag: string) => void;\n}\n\n\nconst Sidebar: React.FC = ({ sidebarOpen, setSidebarOpen, stats, activeFilter, setActiveFilter, availableTags, selectedTags, onTagSelect }) => {\n // const { stats, activeFilter, setActiveFilter } = useServerStats();\n const { user } = useAuth();\n const location = useLocation();\n const [showScopes, setShowScopes] = useState(false);\n const [tagDropdownOpen, setTagDropdownOpen] = useState(false);\n const [tagSearch, setTagSearch] = useState('');\n const [tagHighlightIndex, setTagHighlightIndex] = useState(0);\n const tagDropdownRef = React.useRef(null);\n const [showTokenModal, setShowTokenModal] = useState(false);\n const [tokenData, setTokenData] = useState(null);\n const [loading, setLoading] = useState(false);\n const [copied, setCopied] = useState(false);\n const [error, setError] = useState('');\n\n const filters = [\n { key: 'all', label: 'All Services', count: 'total' },\n { key: 'enabled', label: 'Enabled', count: 'enabled' },\n { key: 'disabled', label: 'Disabled', count: 'disabled' },\n { key: 'unhealthy', label: 'With Issues', count: 'withIssues' },\n ];\n\n const isTokenPage = location.pathname === '/generate-token';\n\n // Close tag dropdown when clicking outside\n useEffect(() => {\n const handleClickOutside = (e: MouseEvent) => {\n if (tagDropdownRef.current && !tagDropdownRef.current.contains(e.target as Node)) {\n setTagDropdownOpen(false);\n }\n };\n document.addEventListener('mousedown', handleClickOutside);\n return () => document.removeEventListener('mousedown', handleClickOutside);\n }, []);\n\n // Debug logging\n useEffect(() => {\n console.log('Sidebar state changed:', sidebarOpen);\n }, [sidebarOpen]);\n\n // Scope descriptions mapping\n const getScopeDescription = (scope: string) => {\n const scopeMappings: { [key: string]: string } = {\n 'mcp-servers-restricted/read': 'Read access to restricted MCP servers',\n 'mcp-servers/read': 'Read access to all MCP servers',\n 'mcp-servers/write': 'Write access to MCP servers',\n 'mcp-registry-user': 'Basic registry user permissions',\n 'mcp-registry-admin': 'Full registry administration access',\n 'health-check': 'Health check and monitoring access',\n 'token-generation': 'Ability to generate access tokens',\n 'server-management': 'Manage server configurations',\n };\n return scopeMappings[scope] || 'Custom permission scope';\n };\n\nconst fetchAdminTokens = async () => {\n setLoading(true);\n setError('');\n try {\n const requestData = {\n description: 'Generated via sidebar',\n expires_in_hours: 8,\n };\n \n const response = await axios.post('/api/tokens/generate', requestData, {\n headers: {\n 'Content-Type': 'application/json',\n },\n });\n \n if (response.data.success) {\n setTokenData(response.data);\n setShowTokenModal(true);\n }\n } catch (err: any) {\n setError(err.response?.data?.detail || 'Failed to generate token');\n } finally {\n setLoading(false);\n }\n};\n\n\n const handleCopyTokens = async () => {\n if (!tokenData) return;\n\n const formattedData = JSON.stringify(tokenData, null, 2);\n try {\n await navigator.clipboard.writeText(formattedData);\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n } catch (error) {\n console.error('Failed to copy:', error);\n }\n };\n\n const handleDownloadTokens = () => {\n if (!tokenData) return;\n\n const formattedData = JSON.stringify(tokenData, null, 2);\n const blob = new Blob([formattedData], { type: 'application/json' });\n const url = URL.createObjectURL(blob);\n const a = document.createElement('a');\n a.href = url;\n a.download = `mcp-registry-api-tokens-${new Date().toISOString().split('T')[0]}.json`;\n document.body.appendChild(a);\n a.click();\n document.body.removeChild(a);\n URL.revokeObjectURL(url);\n };\n\n const sidebarContent = (\n
\n {/* Conditional Content */}\n {isTokenPage ? (\n /* Token Page - Show navigation and user info */\n
\n {/* Navigation Links */}\n
\n window.innerWidth < 768 && setSidebarOpen(false)} // Only close on mobile\n tabIndex={0}\n >\n \n Back to Dashboard\n \n \n \n \n Generate Token\n \n
\n\n {/* User Access Information */}\n {user && (\n
\n
\n
\n {user.username}\n
\n
\n {user.is_admin ? (\n 🔑 Admin Access\n ) : user.can_modify_servers ? (\n ⚙️ Modify Access\n ) : (\n 👁️ Read-only Access\n )}\n {user.auth_method === 'oauth2' && user.provider && (\n ({user.provider})\n )}\n
\n \n {/* Scopes toggle */}\n {!user.is_admin && user.scopes && user.scopes.length > 0 && (\n
\n setShowScopes(!showScopes)}\n className=\"flex items-center justify-between w-full text-xs text-gray-500 dark:text-gray-300 hover:text-gray-700 dark:hover:text-gray-100 transition-colors py-1\"\n >\n Scopes ({user.scopes.length})\n {showScopes ? (\n \n ) : (\n \n )}\n \n \n {showScopes && (\n
\n {user.scopes.map((scope) => (\n
\n
\n {scope}\n
\n
\n {getScopeDescription(scope)}\n
\n
\n ))}\n
\n )}\n
\n )}\n
\n
\n )}\n\n {/* Token Generation Help */}\n
\n \n

Token Generation

\n

\n Create personal access tokens for programmatic access to MCP servers\n

\n
\n

• Tokens inherit your current permissions

\n

• Configure expiration time and scopes

\n

• Use tokens for programmatic access

\n
\n
\n
\n ) : (\n /* Dashboard - Show user info, filters and stats */\n <>\n {/* User Info Header */}\n
\n {/* User Access Information */}\n {user && (\n
\n
\n
\n {user.username}\n
\n
\n {user.is_admin ? (\n 🔑 Admin Access\n ) : user.can_modify_servers ? (\n ⚙️ Modify Access\n ) : (\n 👁️ Read-only Access\n )}\n {user.auth_method === 'oauth2' && user.provider && (\n ({user.provider})\n )}\n
\n\n {/* JWT Token Button - Available to all users */}\n
\n \n {loading ? (\n <>\n
\n Loading...\n \n ) : (\n <>\n \n Get JWT Token\n \n )}\n \n {error && (\n

{error}

\n )}\n
\n\n {/* Scopes toggle */}\n {!user.is_admin && user.scopes && user.scopes.length > 0 && (\n
\n setShowScopes(!showScopes)}\n className=\"flex items-center justify-between w-full text-xs text-gray-500 dark:text-gray-300 hover:text-gray-700 dark:hover:text-gray-100 transition-colors py-1\"\n >\n Scopes ({user.scopes.length})\n {showScopes ? (\n \n ) : (\n \n )}\n \n\n {showScopes && (\n
\n {user.scopes.map((scope) => (\n
\n
\n {scope}\n
\n
\n {getScopeDescription(scope)}\n
\n
\n ))}\n
\n )}\n
\n )}\n
\n
\n )}\n
\n\n {/* Filters Section */}\n
\n
\n \n

Filter Services

\n
\n \n
\n {filters.map((filter) => (\n setActiveFilter(filter.key)}\n className={`w-full text-left px-3 py-2 rounded-lg text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-purple-500 ${\n activeFilter === filter.key\n ? 'bg-primary-100 dark:bg-primary-900 text-primary-700 dark:text-primary-300 border border-primary-200 dark:border-primary-800'\n : 'text-gray-700 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800'\n }`}\n tabIndex={0}\n >\n
\n {filter.label}\n \n {stats[filter.count as keyof typeof stats]}\n \n
\n \n ))}\n\n {/* Deprecated toggle - separate from main filters */}\n
\n setActiveFilter(activeFilter === 'deprecated' ? 'all' : 'deprecated')}\n className={`w-full text-left px-3 py-2 rounded-lg text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-purple-500 ${\n activeFilter === 'deprecated'\n ? 'bg-orange-100 dark:bg-orange-900/30 text-orange-700 dark:text-orange-300 border border-orange-200 dark:border-orange-800'\n : 'text-gray-500 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-gray-800'\n }`}\n tabIndex={0}\n >\n {activeFilter === 'deprecated' ? 'Showing deprecated' : 'Also show deprecated'}\n \n
\n
\n\n
\n\n {/* Tags Section */}\n {availableTags.length > 0 && (\n
\n
\n \n

Filter by Tag

\n {selectedTags.length > 0 && (\n selectedTags.forEach(t => onTagSelect(t))}\n className=\"text-xs text-purple-600 dark:text-purple-400 hover:underline ml-auto\"\n >\n Clear all\n \n )}\n
\n\n {/* Selected tag chips */}\n {selectedTags.length > 0 && (\n
\n {selectedTags.map((tag) => (\n \n {tag}\n onTagSelect(tag)}\n className=\"hover:text-purple-900 dark:hover:text-purple-100 focus:outline-none\"\n aria-label={`Remove tag ${tag}`}\n >\n \n \n \n ))}\n
\n )}\n\n {/* Tag dropdown */}\n {(() => {\n const filteredTags = availableTags.filter(tag =>\n !selectedTags.includes(tag) &&\n tag.toLowerCase().includes(tagSearch.toLowerCase())\n );\n return (\n
\n {\n setTagSearch(e.target.value);\n setTagHighlightIndex(0);\n setTagDropdownOpen(true);\n }}\n onFocus={() => {\n setTagDropdownOpen(true);\n setTagHighlightIndex(0);\n }}\n onKeyDown={(e) => {\n if (!tagDropdownOpen || filteredTags.length === 0) return;\n if (e.key === 'ArrowDown') {\n e.preventDefault();\n setTagHighlightIndex(prev => Math.min(prev + 1, filteredTags.length - 1));\n } else if (e.key === 'ArrowUp') {\n e.preventDefault();\n setTagHighlightIndex(prev => Math.max(prev - 1, 0));\n } else if (e.key === 'Enter') {\n e.preventDefault();\n const tag = filteredTags[tagHighlightIndex];\n if (tag) {\n onTagSelect(tag);\n setTagSearch('');\n setTagHighlightIndex(0);\n setTagDropdownOpen(false);\n }\n } else if (e.key === 'Escape') {\n setTagDropdownOpen(false);\n }\n }}\n className=\"w-full px-3 py-1.5 text-xs rounded-lg border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 placeholder-gray-400 dark:placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:border-transparent\"\n />\n {tagDropdownOpen && (\n
\n {filteredTags.map((tag, idx) => (\n {\n onTagSelect(tag);\n setTagSearch('');\n setTagHighlightIndex(0);\n setTagDropdownOpen(false);\n }}\n onMouseEnter={() => setTagHighlightIndex(idx)}\n className={`w-full text-left px-3 py-1.5 text-xs transition-colors ${\n idx === tagHighlightIndex\n ? 'bg-purple-50 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300'\n : 'text-gray-700 dark:text-gray-300 hover:bg-purple-50 dark:hover:bg-purple-900/30 hover:text-purple-700 dark:hover:text-purple-300'\n }`}\n >\n {tag}\n \n ))}\n {filteredTags.length === 0 && (\n
\n No matching tags\n
\n )}\n
\n )}\n
\n );\n })()}\n
\n )}\n\n {/* Statistics Section */}\n
\n
\n \n

Statistics

\n
\n \n
\n
\n
{stats.total}
\n
Total
\n
\n
\n
{stats.enabled}
\n
Enabled
\n
\n
\n
{stats.disabled}
\n
Disabled
\n
\n
\n
{stats.withIssues}
\n
Issues
\n
\n
\n
\n \n )}\n
\n );\n\n return (\n <>\n {/* Mobile sidebar only */}\n {window.innerWidth < 768 && (\n \n \n \n
\n \n\n
\n \n \n \n
\n setSidebarOpen(false)}\n aria-label=\"Close sidebar\"\n >\n \n \n
\n \n \n
\n {sidebarContent}\n
\n \n \n
\n
\n \n )}\n\n {/* Desktop sidebar only */}\n {window.innerWidth >= 768 && (\n \n \n
\n {sidebarContent}\n
\n \n \n )}\n\n {/* Token Modal */}\n \n setShowTokenModal(false)}>\n \n
\n \n\n
\n
\n \n \n \n JWT Access Token\n \n\n {tokenData && (\n
\n {/* Action Buttons */}\n
\n \n {copied ? (\n <>\n \n Copied!\n \n ) : (\n <>\n \n Copy JSON\n \n )}\n \n \n \n Download JSON\n \n
\n\n {/* Token Data Display */}\n
\n 
\n                          {JSON.stringify(tokenData, null, 2)}\n
\n
\n\n {/* Close Button */}\n
\n setShowTokenModal(false)}\n className=\"px-4 py-2 bg-gray-200 dark:bg-gray-700 text-gray-800 dark:text-gray-200 rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600 transition-colors text-sm\"\n >\n Close\n \n
\n
\n )}\n \n \n
\n
\n
\n \n \n );\n};\n\nexport default Sidebar; " }, { "path": "frontend/src/components/SkillCard.tsx", "content": "import React, { useState, useCallback, useEffect } from 'react';\nimport axios from 'axios';\nimport ReactMarkdown from 'react-markdown';\nimport remarkGfm from 'remark-gfm';\nimport {\n SparklesIcon,\n PencilIcon,\n TrashIcon,\n GlobeAltIcon,\n LockClosedIcon,\n UserGroupIcon,\n InformationCircleIcon,\n ArrowTopRightOnSquareIcon,\n WrenchScrewdriverIcon,\n CheckCircleIcon,\n XCircleIcon,\n ArrowPathIcon,\n ClockIcon,\n ClipboardIcon,\n ArrowDownTrayIcon,\n ShieldCheckIcon,\n ShieldExclamationIcon,\n} from '@heroicons/react/24/outline';\nimport { Skill } from '../types/skill';\nimport StatusBadge from './StatusBadge';\nimport StarRatingWidget from './StarRatingWidget';\nimport SecurityScanModal from './SecurityScanModal';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\n/**\n * Props for the SkillCard component.\n */\ninterface SkillCardProps {\n skill: Skill & { [key: string]: any };\n onToggle: (path: string, enabled: boolean) => void;\n onEdit?: (skill: Skill) => void;\n onDelete?: (path: string) => void;\n canModify?: boolean;\n canToggle?: boolean;\n canHealthCheck?: boolean;\n onRefreshSuccess?: () => void;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n onSkillUpdate?: (path: string, updates: Partial) => void;\n authToken?: string | null;\n}\n\n// Helper function to parse YAML frontmatter from markdown\nconst parseYamlFrontmatter = (content: string): { frontmatter: Record | null; body: string } => {\n // Check if content starts with --- (YAML frontmatter delimiter)\n const frontmatterRegex = /^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n([\\s\\S]*)$/;\n const match = content.match(frontmatterRegex);\n\n if (match) {\n const yamlContent = match[1];\n const body = match[2];\n\n // Simple YAML parsing for key: value pairs\n const frontmatter: Record = {};\n const lines = yamlContent.split('\\n');\n for (const line of lines) {\n const colonIndex = line.indexOf(':');\n if (colonIndex > 0) {\n const key = line.substring(0, colonIndex).trim();\n const value = line.substring(colonIndex + 1).trim();\n if (key && value) {\n frontmatter[key] = value;\n }\n }\n }\n\n return { frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null, body };\n }\n\n return { frontmatter: null, body: content };\n};\n\n\n// Helper function to format time since last checked\nconst formatTimeSince = (timestamp: string | null | undefined): string | null => {\n if (!timestamp) {\n return null;\n }\n\n try {\n const now = new Date();\n const lastChecked = new Date(timestamp);\n\n if (isNaN(lastChecked.getTime())) {\n return null;\n }\n\n const diffMs = now.getTime() - lastChecked.getTime();\n const diffSeconds = Math.floor(diffMs / 1000);\n const diffMinutes = Math.floor(diffSeconds / 60);\n const diffHours = Math.floor(diffMinutes / 60);\n const diffDays = Math.floor(diffHours / 24);\n\n if (diffDays > 0) {\n return `${diffDays}d ago`;\n } else if (diffHours > 0) {\n return `${diffHours}h ago`;\n } else if (diffMinutes > 0) {\n return `${diffMinutes}m ago`;\n } else {\n return `${diffSeconds}s ago`;\n }\n } catch (error) {\n console.error('formatTimeSince error:', error, 'for timestamp:', timestamp);\n return null;\n }\n};\n\n/**\n * SkillCard component for displaying Agent Skills.\n *\n * Uses amber/orange tones to distinguish from servers (purple) and agents (cyan).\n */\nconst SkillCard: React.FC = React.memo(({\n skill,\n onToggle,\n onEdit,\n onDelete,\n canModify,\n canToggle = true,\n canHealthCheck = true,\n onShowToast,\n onSkillUpdate,\n authToken\n}) => {\n const [showDetails, setShowDetails] = useState(false);\n const [loadingDetails, setLoadingDetails] = useState(false);\n const [skillMdContent, setSkillMdContent] = useState(null);\n\n useEscapeKey(() => setShowDetails(false), showDetails);\n const [loadingToolCheck, setLoadingToolCheck] = useState(false);\n const [toolCheckResult, setToolCheckResult] = useState(null);\n const [loadingHealthCheck, setLoadingHealthCheck] = useState(false);\n const [healthStatus, setHealthStatus] = useState<'healthy' | 'unhealthy' | 'unknown'>(\n skill.health_status || 'unknown'\n );\n const [lastCheckedTime, setLastCheckedTime] = useState(\n skill.last_checked_time || null\n );\n const [showSecurityScan, setShowSecurityScan] = useState(false);\n const [securityScanResult, setSecurityScanResult] = useState(null);\n const [loadingSecurityScan, setLoadingSecurityScan] = useState(false);\n\n // Sync health status from props when skill changes\n useEffect(() => {\n setHealthStatus(skill.health_status || 'unknown');\n setLastCheckedTime(skill.last_checked_time || null);\n }, [skill.health_status, skill.last_checked_time]);\n\n // Extract skill name from path for API calls\n // skill.path is like \"/skills/doc-coauthoring\", API routes already have /skills prefix\n // so we need just \"/doc-coauthoring\" for the path parameter\n const getSkillApiPath = (path: string) => {\n if (path.startsWith('/skills/')) {\n return path.replace('/skills/', '/');\n }\n return path;\n };\n const skillApiPath = getSkillApiPath(skill.path);\n\n // Fetch security scan status on mount to show correct icon color\n useEffect(() => {\n const fetchSecurityScan = async () => {\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/skills${skillApiPath}/security-scan`,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n } catch {\n // Silently ignore - no scan result available\n }\n };\n fetchSecurityScan();\n }, [skillApiPath, authToken]);\n\n const getVisibilityIcon = () => {\n switch (skill.visibility) {\n case 'public':\n return ;\n case 'group':\n return ;\n default:\n return ;\n }\n };\n\n const getVisibilityColor = () => {\n switch (skill.visibility) {\n case 'public':\n return 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400 border border-green-200 dark:border-green-700';\n case 'group':\n return 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400 border border-blue-200 dark:border-blue-700';\n default:\n return 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300 border border-gray-200 dark:border-gray-600';\n }\n };\n\n const handleViewDetails = useCallback(async () => {\n setShowDetails(true);\n setLoadingDetails(true);\n setSkillMdContent(null);\n\n try {\n // Fetch SKILL.md content via backend proxy to avoid CORS issues\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/skills${skillApiPath}/content`,\n headers ? { headers } : undefined\n );\n setSkillMdContent(response.data.content);\n } catch (error: any) {\n console.error('Failed to fetch SKILL.md content:', error);\n const detail = error.response?.data?.detail;\n if (error.response?.status === 409 && detail) {\n setSkillMdContent(`> **Content Drift Detected**\\n>\\n> ${detail}\\n>\\n> Re-register this skill to update the integrity baseline and re-enable it.`);\n } else if (onShowToast) {\n onShowToast(detail || 'Failed to load SKILL.md content', 'error');\n }\n } finally {\n setLoadingDetails(false);\n }\n }, [skillApiPath, authToken, onShowToast]);\n\n const handleCheckTools = useCallback(async () => {\n if (loadingToolCheck) return;\n\n setLoadingToolCheck(true);\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/skills${skillApiPath}/tools`,\n headers ? { headers } : undefined\n );\n setToolCheckResult(response.data);\n if (onShowToast) {\n const result = response.data;\n if (result.all_available) {\n onShowToast('All required tools are available', 'success');\n } else {\n onShowToast(`Missing tools: ${result.missing_tools?.join(', ') || 'Unknown'}`, 'error');\n }\n }\n } catch (error: any) {\n console.error('Failed to check tool availability:', error);\n if (onShowToast) {\n onShowToast('Failed to check tool availability', 'error');\n }\n } finally {\n setLoadingToolCheck(false);\n }\n }, [skill.path, authToken, loadingToolCheck, onShowToast]);\n\n const handleRefreshHealth = useCallback(async () => {\n if (loadingHealthCheck) return;\n\n setLoadingHealthCheck(true);\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/skills${skillApiPath}/health`,\n headers ? { headers } : undefined\n );\n\n const newStatus = response.data.healthy ? 'healthy' : 'unhealthy';\n setHealthStatus(newStatus);\n setLastCheckedTime(new Date().toISOString());\n\n // Update parent if callback provided\n if (onSkillUpdate) {\n onSkillUpdate(skill.path, {\n health_status: newStatus,\n last_checked_time: new Date().toISOString()\n } as any);\n }\n\n if (onShowToast) {\n onShowToast(\n response.data.healthy\n ? 'SKILL.md is accessible'\n : `SKILL.md check failed: ${response.data.error || 'Unknown error'}`,\n response.data.healthy ? 'success' : 'error'\n );\n }\n } catch (error: any) {\n console.error('Failed to check skill health:', error);\n setHealthStatus('unhealthy');\n if (onShowToast) {\n onShowToast('Failed to check skill health', 'error');\n }\n } finally {\n setLoadingHealthCheck(false);\n }\n }, [skill.path, authToken, loadingHealthCheck, onShowToast, onSkillUpdate]);\n\n const handleViewSecurityScan = useCallback(async () => {\n if (loadingSecurityScan) return;\n\n setShowSecurityScan(true);\n setLoadingSecurityScan(true);\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.get(\n `/api/skills${skillApiPath}/security-scan`,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n } catch (error: any) {\n if (error.response?.status !== 404) {\n if (onShowToast) {\n onShowToast('Failed to load security scan results', 'error');\n }\n }\n setSecurityScanResult(null);\n } finally {\n setLoadingSecurityScan(false);\n }\n }, [skillApiPath, authToken, loadingSecurityScan, onShowToast]);\n\n const handleRescan = useCallback(async () => {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n const response = await axios.post(\n `/api/skills${skillApiPath}/rescan`,\n undefined,\n headers ? { headers } : undefined\n );\n setSecurityScanResult(response.data);\n }, [skillApiPath, authToken]);\n\n const getSecurityIconState = () => {\n if (!securityScanResult) {\n return { Icon: ShieldCheckIcon, color: 'text-gray-400 dark:text-gray-500', title: 'View security scan results' };\n }\n if (securityScanResult.scan_failed) {\n return { Icon: ShieldExclamationIcon, color: 'text-red-500 dark:text-red-400', title: 'Security scan failed' };\n }\n const hasVulnerabilities = securityScanResult.critical_issues > 0 ||\n securityScanResult.high_severity > 0 ||\n securityScanResult.medium_severity > 0 ||\n securityScanResult.low_severity > 0;\n if (hasVulnerabilities) {\n return { Icon: ShieldExclamationIcon, color: 'text-red-500 dark:text-red-400', title: 'Security issues found' };\n }\n return { Icon: ShieldCheckIcon, color: 'text-green-500 dark:text-green-400', title: 'Security scan passed' };\n };\n\n return (\n <>\n
\n {/* Header */}\n
\n
\n
\n
\n

\n {skill.name}\n

\n \n SKILL\n \n \n {getVisibilityIcon()}\n {skill.visibility.toUpperCase()}\n \n {skill.status && skill.status !== 'active' && (\n \n )}\n
\n\n \n {skill.path}\n \n {skill.version && (\n \n v{skill.version}\n \n )}\n {skill.author && (\n \n by {skill.author}\n \n )}\n
\n\n
\n {canModify && (\n <>\n onEdit?.(skill)}\n title=\"Edit skill\"\n >\n \n \n onDelete?.(skillApiPath)}\n title=\"Delete skill\"\n >\n \n \n \n )}\n\n {/* Tool Check Button */}\n {skill.allowed_tools && skill.allowed_tools.length > 0 && (\n \n \n \n )}\n\n {/* Security Scan Button */}\n \n {React.createElement(getSecurityIconState().Icon, { className: `h-4 w-4 ${loadingSecurityScan ? 'animate-pulse' : ''}` })}\n \n\n {/* Details Button */}\n \n \n \n
\n
\n\n {/* Description */}\n

\n {skill.description || 'No description available'}\n

\n\n {/* Tags */}\n {skill.tags && skill.tags.length > 0 && (\n
\n {skill.tags.slice(0, 3).map((tag) => (\n \n #{tag}\n \n ))}\n {skill.tags.length > 3 && (\n \n +{skill.tags.length - 3}\n \n )}\n
\n )}\n\n {/* Target Agents */}\n {skill.target_agents && skill.target_agents.length > 0 && (\n
\n Target agents: \n \n {skill.target_agents.join(', ')}\n \n
\n )}\n\n {/* Tools Count */}\n {skill.allowed_tools && skill.allowed_tools.length > 0 && (\n
\n \n \n {skill.allowed_tools.length} tool{skill.allowed_tools.length !== 1 ? 's' : ''} required\n \n {toolCheckResult && (\n toolCheckResult.all_available ? (\n \n ) : (\n \n )\n )}\n
\n )}\n
\n\n {/* Stats */}\n
\n
\n
\n
\n \n
\n
\n
Registry
\n
\n {skill.registry_name || 'local'}\n
\n
\n
\n\n {/* Rating Widget */}\n \n\n {/* SKILL.md Link */}\n {skill.skill_md_url && (\n \n \n SKILL.md\n \n )}\n
\n
\n\n {/* Footer */}\n
\n
\n
\n {/* Status Indicator */}\n
\n
\n \n {skill.is_enabled ? 'Enabled' : 'Disabled'}\n \n {!skill.is_enabled && skill.tags?.includes('content-drifted') && (\n \n — content drifted\n \n )}\n {!skill.is_enabled && skill.tags?.includes('security-pending') && !skill.tags?.includes('content-drifted') && (\n \n — security review pending\n \n )}\n
\n\n
\n\n {/* Health Status */}\n
\n
\n \n {healthStatus === 'healthy' ? 'Healthy' :\n healthStatus === 'unhealthy' ? 'Unhealthy' : 'Unknown'}\n \n
\n
\n\n {/* Controls */}\n
\n {/* Last Checked */}\n {(() => {\n const timeText = formatTimeSince(lastCheckedTime);\n return lastCheckedTime && timeText ? (\n
\n \n {timeText}\n
\n ) : null;\n })()}\n\n {/* Refresh Health Button */}\n {canHealthCheck && (\n \n \n \n )}\n\n {/* Toggle Switch */}\n {canToggle && (\n
\n
\n
\n\n {/* Skill Details Modal */}\n {showDetails && (\n
\n
\n
\n

\n {skill.name}\n

\n setShowDetails(false)}\n className=\"text-gray-400 hover:text-gray-600 dark:hover:text-gray-300\"\n >\n \n \n \n \n
\n\n {/* Action buttons */}\n
\n {skill.skill_md_url && (\n \n \n View Skill\n \n )}\n {skill.repository_url && (\n \n \n View Repo\n \n )}\n {skillMdContent && (\n <>\n {\n navigator.clipboard.writeText(skillMdContent);\n if (onShowToast) {\n onShowToast('SKILL.md copied to clipboard', 'success');\n }\n }}\n className=\"flex items-center gap-1 text-sm text-gray-600 dark:text-gray-400 hover:text-amber-700 dark:hover:text-amber-300 transition-colors\"\n title=\"Copy to clipboard\"\n >\n \n Copy\n \n {\n const blob = new Blob([skillMdContent], { type: 'text/markdown' });\n const url = URL.createObjectURL(blob);\n const a = document.createElement('a');\n a.href = url;\n a.download = `${skill.name || 'skill'}.md`;\n document.body.appendChild(a);\n a.click();\n document.body.removeChild(a);\n URL.revokeObjectURL(url);\n }}\n className=\"flex items-center gap-1 text-sm text-gray-600 dark:text-gray-400 hover:text-amber-700 dark:hover:text-amber-300 transition-colors\"\n title=\"Download SKILL.md\"\n >\n \n Download\n \n \n )}\n
\n\n {loadingDetails ? (\n
\n
\n
\n ) : skillMdContent ? (\n (() => {\n const { frontmatter, body } = parseYamlFrontmatter(skillMdContent);\n return (\n <>\n {/* YAML Frontmatter Table */}\n {frontmatter && (\n
\n \n \n {Object.entries(frontmatter).map(([key, value]) => (\n \n \n \n \n ))}\n \n
\n {key}\n \n {value}\n
\n
\n )}\n {/* Markdown Body */}\n
\n {body}\n
\n \n );\n })()\n ) : (\n
\n

Could not load SKILL.md content.

\n

\n Try visiting the{' '}\n \n source URL\n {' '}\n directly.\n

\n
\n )}\n
\n
\n )}\n {/* Security Scan Modal */}\n setShowSecurityScan(false)}\n loading={loadingSecurityScan}\n scanResult={securityScanResult}\n onRescan={canModify ? handleRescan : undefined}\n canRescan={canModify}\n onShowToast={onShowToast}\n />\n \n );\n});\n\nSkillCard.displayName = 'SkillCard';\n\nexport default SkillCard;\n" }, { "path": "frontend/src/components/StarRatingWidget.tsx", "content": "import React, { useState, useEffect, useRef } from 'react';\nimport { StarIcon } from '@heroicons/react/24/solid';\nimport { StarIcon as StarIconOutline } from '@heroicons/react/24/outline';\nimport axios from 'axios';\n\ninterface RatingDetail {\n user: string;\n rating: number;\n}\n\ninterface RatingInfoResponse {\n num_stars: number;\n rating_details: RatingDetail[];\n}\n\ninterface StarRatingWidgetProps {\n resourceType: 'agents' | 'servers' | 'skills' | 'virtual-servers';\n path: string;\n initialRating?: number;\n initialCount?: number;\n authToken?: string | null;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n onRatingUpdate?: (newRating: number) => void;\n}\n\n\nconst StarRatingWidget: React.FC = ({\n resourceType,\n path,\n initialRating = 0,\n initialCount = 0,\n authToken,\n onShowToast,\n onRatingUpdate\n}) => {\n const [isDropdownOpen, setIsDropdownOpen] = useState(false);\n const [selectedRating, setSelectedRating] = useState(null);\n const [hoverRating, setHoverRating] = useState(null);\n const [currentUserRating, setCurrentUserRating] = useState(null);\n const [averageRating, setAverageRating] = useState(initialRating);\n const [ratingCount, setRatingCount] = useState(initialCount);\n const [isSubmitting, setIsSubmitting] = useState(false);\n const [showSuccess, setShowSuccess] = useState(false);\n const [dropdownPos, setDropdownPos] = useState<{ top: number; left: number }>({ top: 0, left: 0 });\n const dropdownRef = useRef(null);\n const buttonRef = useRef(null);\n\n\n // Load current rating on mount\n useEffect(() => {\n loadCurrentRating();\n }, [resourceType, path]);\n\n\n // Close dropdown when clicking outside\n useEffect(() => {\n const handleClickOutside = (event: MouseEvent) => {\n if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {\n setIsDropdownOpen(false);\n }\n };\n\n if (isDropdownOpen) {\n document.addEventListener('mousedown', handleClickOutside);\n }\n\n return () => {\n document.removeEventListener('mousedown', handleClickOutside);\n };\n }, [isDropdownOpen]);\n\n\n const loadCurrentRating = async () => {\n try {\n // Build headers - use Bearer token if provided, otherwise rely on cookies\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n // Both servers and agents now use consistent path parameter pattern\n const url = `/api/${resourceType}${path}/rating`;\n const response = await axios.get(\n url,\n headers ? { headers } : undefined\n );\n\n setAverageRating(response.data.num_stars);\n setRatingCount(response.data.rating_details.length);\n\n // Find current user's rating from the rating details\n // The backend should return rating_details for the current authenticated user\n if (response.data.rating_details && response.data.rating_details.length > 0) {\n // For now, use the first rating (should be the current user's rating from backend)\n const userRating = response.data.rating_details[0];\n if (userRating) {\n setCurrentUserRating(userRating.rating);\n setSelectedRating(userRating.rating);\n }\n }\n } catch (error: any) {\n console.error('Failed to load rating:', error);\n }\n };\n\n\n const handleSubmitRating = async () => {\n console.log('handleSubmitRating called', { selectedRating, authToken: !!authToken });\n if (!selectedRating) {\n console.log('Validation failed - no rating selected');\n return;\n }\n\n setIsSubmitting(true);\n try {\n // Build headers - use Bearer token if provided, otherwise rely on cookies\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n // Both servers and agents now use consistent path parameter pattern\n const url = `/api/${resourceType}${path}/rate`;\n console.log('Submitting rating to:', url, { rating: selectedRating });\n\n const response = await axios.post(\n url,\n { rating: selectedRating },\n headers ? { headers } : undefined\n );\n\n console.log('Rating response:', response.data);\n const newAverageRating = response.data.average_rating;\n setAverageRating(newAverageRating);\n setCurrentUserRating(selectedRating);\n\n // Update count (increment if new rating, keep same if update)\n if (!currentUserRating) {\n setRatingCount(prev => prev + 1);\n }\n\n setShowSuccess(true);\n\n if (onShowToast) {\n onShowToast(\n currentUserRating ? 'Rating updated successfully!' : 'Rating submitted successfully!',\n 'success'\n );\n }\n\n if (onRatingUpdate) {\n onRatingUpdate(newAverageRating);\n }\n\n // Auto-close after 2 seconds\n console.log('Setting timeout to close dialog...');\n setTimeout(() => {\n console.log('Closing dialog now');\n setShowSuccess(false);\n setIsDropdownOpen(false);\n }, 2000);\n } catch (error: any) {\n console.error('Failed to submit rating:', error);\n console.error('Error details:', error.response?.data);\n if (onShowToast) {\n onShowToast(\n error.response?.data?.detail || 'Failed to submit rating',\n 'error'\n );\n }\n } finally {\n setIsSubmitting(false);\n }\n };\n\n\n const handleStarClick = (rating: number) => {\n setSelectedRating(rating);\n };\n\n\n const handleCancel = () => {\n setIsDropdownOpen(false);\n setSelectedRating(currentUserRating);\n setHoverRating(null);\n };\n\n\n const renderStars = (count: number, filled: boolean, size: 'small' | 'large' = 'large') => {\n const sizeClass = size === 'small' ? 'h-4 w-4' : 'h-6 w-6';\n const IconComponent = filled ? StarIcon : StarIconOutline;\n\n return (\n \n );\n };\n\n\n const displayRating = hoverRating !== null ? hoverRating : (selectedRating || currentUserRating || 0);\n\n\n return (\n
\n {/* Rating Display - Clickable */}\n {\n if (!isDropdownOpen && buttonRef.current) {\n const rect = buttonRef.current.getBoundingClientRect();\n setDropdownPos({ top: rect.bottom + 8, left: rect.left });\n }\n setIsDropdownOpen(!isDropdownOpen);\n }}\n className=\"flex items-center gap-2 hover:bg-yellow-50 dark:hover:bg-yellow-900/20 p-2 rounded-lg transition-colors duration-200\"\n title={`Click to rate this ${resourceType.slice(0, -1)}`}\n aria-label={`Rate this ${resourceType.slice(0, -1)}`}\n aria-expanded={isDropdownOpen}\n aria-haspopup=\"dialog\"\n >\n
\n \n
\n
\n
\n {averageRating > 0 ? averageRating.toFixed(1) : '0'}\n
\n
\n {ratingCount === 0 ? 'No ratings' : `${ratingCount} rating${ratingCount !== 1 ? 's' : ''}`}\n
\n
\n \n\n {/* Rating Dropdown */}\n {isDropdownOpen && (\n \n {/* Success State */}\n {showSuccess ? (\n
\n
\n \n \n \n
\n

\n Rating {currentUserRating && selectedRating !== currentUserRating ? 'updated' : 'submitted'}!\n

\n
\n {[1, 2, 3, 4, 5].map((star) => (\n
\n {renderStars(star, star <= (selectedRating || 0), 'small')}\n
\n ))}\n \n ({selectedRating} stars)\n \n
\n

\n New average: {averageRating.toFixed(1)} ★\n

\n
\n ) : isSubmitting ? (\n // Loading State\n
\n
\n \n \n \n \n
\n

\n Submitting your rating...\n

\n
\n ) : (\n // Rating Form\n <>\n

\n {currentUserRating ? 'Update your rating:' : `Rate this ${resourceType.slice(0, -1)}:`}\n

\n {currentUserRating && (\n

\n Currently: {currentUserRating} stars\n

\n )}\n\n {/* Star Selection */}\n \n {[1, 2, 3, 4, 5].map((star) => (\n handleStarClick(star)}\n onMouseEnter={() => setHoverRating(star)}\n onMouseLeave={() => setHoverRating(null)}\n className=\"p-1 hover:scale-110 transition-transform duration-150 focus:outline-none focus:ring-2 focus:ring-yellow-400 rounded\"\n role=\"radio\"\n aria-checked={selectedRating === star}\n aria-label={`${star} star${star !== 1 ? 's' : ''}`}\n >\n {renderStars(star, star <= displayRating)}\n \n ))}\n
\n\n {/* Rating Preview Text */}\n {displayRating > 0 && (\n

\n {displayRating} star{displayRating !== 1 ? 's' : ''}\n

\n )}\n\n {/* Action Buttons */}\n
\n \n Cancel\n \n \n {currentUserRating ? 'Update Rating' : 'Submit Rating'}\n {selectedRating && (\n \n \n \n )}\n \n
\n \n )}\n
\n )}\n
\n );\n};\n\n\nexport default StarRatingWidget;\n" }, { "path": "frontend/src/components/StatusBadge.tsx", "content": "import React from 'react';\n\ntype LifecycleStatus = 'active' | 'deprecated' | 'draft' | 'beta';\n\ninterface StatusBadgeProps {\n status: LifecycleStatus;\n className?: string;\n}\n\nconst STATUS_CONFIG: Record<\n LifecycleStatus,\n {\n label: string;\n tooltip: string;\n colorClasses: string;\n }\n> = {\n active: {\n label: 'Active',\n tooltip: 'This item is active and ready for use',\n colorClasses:\n 'bg-green-50 text-green-700 dark:bg-green-900/30 dark:text-green-300',\n },\n deprecated: {\n label: 'Deprecated',\n tooltip: 'This item is deprecated and may be removed in the future',\n colorClasses:\n 'bg-orange-50 text-orange-700 dark:bg-orange-900/30 dark:text-orange-300',\n },\n draft: {\n label: 'Draft',\n tooltip: 'This item is in draft mode and not yet ready for production',\n colorClasses:\n 'bg-gray-50 text-gray-700 dark:bg-gray-800 dark:text-gray-300',\n },\n beta: {\n label: 'Beta',\n tooltip: 'This item is in beta testing phase',\n colorClasses:\n 'bg-blue-50 text-blue-700 dark:bg-blue-900/30 dark:text-blue-300',\n },\n};\n\n/**\n * StatusBadge component displays the lifecycle status of a server or agent.\n *\n * Features:\n * - Color-coded badges for different statuses\n * - Tooltip with status description\n * - Dark mode support\n */\nconst StatusBadge: React.FC = ({ status, className = '' }) => {\n const config = STATUS_CONFIG[status] || STATUS_CONFIG.active;\n\n return (\n \n {config.label}\n \n );\n};\n\nexport default StatusBadge;\n" }, { "path": "frontend/src/components/ToolSelector.tsx", "content": "import React, { useState, useMemo } from 'react';\nimport {\n MagnifyingGlassIcon,\n PlusIcon,\n XMarkIcon,\n PencilIcon,\n ChevronDownIcon,\n ChevronRightIcon,\n} from '@heroicons/react/24/outline';\nimport { ToolMapping, ToolCatalogEntry } from '../types/virtualServer';\nimport { useToolCatalog } from '../hooks/useVirtualServers';\n\n\n/**\n * Props for the ToolSelector component.\n */\ninterface ToolSelectorProps {\n selectedTools: ToolMapping[];\n onToolsChange: (tools: ToolMapping[]) => void;\n}\n\n\n/**\n * Group catalog entries by server for display.\n */\ninterface ServerGroup {\n serverPath: string;\n serverName: string;\n tools: ToolCatalogEntry[];\n}\n\n\n/**\n * ToolSelector provides a two-panel picker for selecting tools\n * from the global tool catalog and configuring them as ToolMappings.\n *\n * Left panel: available tools grouped by server with search.\n * Right panel: selected tools with alias and version configuration.\n */\nconst ToolSelector: React.FC = ({\n selectedTools,\n onToolsChange,\n}) => {\n const { catalog, loading, error } = useToolCatalog();\n const [searchQuery, setSearchQuery] = useState('');\n const [expandedServers, setExpandedServers] = useState>(new Set());\n const [editingAlias, setEditingAlias] = useState(null);\n\n // Group catalog tools by server\n const serverGroups: ServerGroup[] = useMemo(() => {\n const groupMap = new Map();\n\n for (const entry of catalog) {\n const existing = groupMap.get(entry.server_path);\n if (existing) {\n existing.tools.push(entry);\n } else {\n groupMap.set(entry.server_path, {\n serverPath: entry.server_path,\n serverName: entry.server_name,\n tools: [entry],\n });\n }\n }\n\n return Array.from(groupMap.values()).sort((a, b) =>\n a.serverName.localeCompare(b.serverName)\n );\n }, [catalog]);\n\n // Filter groups and tools by search\n const filteredGroups = useMemo(() => {\n if (!searchQuery) return serverGroups;\n const query = searchQuery.toLowerCase();\n\n return serverGroups\n .map((group) => ({\n ...group,\n tools: group.tools.filter(\n (tool) =>\n tool.tool_name.toLowerCase().includes(query) ||\n tool.description.toLowerCase().includes(query) ||\n tool.server_name.toLowerCase().includes(query)\n ),\n }))\n .filter((group) => group.tools.length > 0);\n }, [serverGroups, searchQuery]);\n\n const toggleServerGroup = (serverPath: string) => {\n setExpandedServers((prev) => {\n const next = new Set(prev);\n if (next.has(serverPath)) {\n next.delete(serverPath);\n } else {\n next.add(serverPath);\n }\n return next;\n });\n };\n\n const isToolSelected = (entry: ToolCatalogEntry): boolean => {\n return selectedTools.some(\n (t) =>\n t.tool_name === entry.tool_name &&\n t.backend_server_path === entry.server_path\n );\n };\n\n const areAllGroupToolsSelected = (group: ServerGroup): boolean => {\n return group.tools.every((tool) => isToolSelected(tool));\n };\n\n const handleAddTool = (entry: ToolCatalogEntry) => {\n if (isToolSelected(entry)) return;\n\n const newMapping: ToolMapping = {\n tool_name: entry.tool_name,\n backend_server_path: entry.server_path,\n alias: null,\n backend_version: null,\n };\n\n onToolsChange([...selectedTools, newMapping]);\n };\n\n const handleSelectAllFromGroup = (group: ServerGroup) => {\n const newMappings: ToolMapping[] = [];\n for (const tool of group.tools) {\n if (!isToolSelected(tool)) {\n newMappings.push({\n tool_name: tool.tool_name,\n backend_server_path: tool.server_path,\n alias: null,\n backend_version: null,\n });\n }\n }\n if (newMappings.length > 0) {\n onToolsChange([...selectedTools, ...newMappings]);\n }\n };\n\n const handleRemoveTool = (index: number) => {\n const updated = selectedTools.filter((_, i) => i !== index);\n onToolsChange(updated);\n };\n\n const handleAliasChange = (index: number, alias: string) => {\n const updated = selectedTools.map((tool, i) =>\n i === index ? { ...tool, alias: alias || null } : tool\n );\n onToolsChange(updated);\n };\n\n const handleVersionChange = (index: number, version: string) => {\n const updated = selectedTools.map((tool, i) =>\n i === index ? { ...tool, backend_version: version || null } : tool\n );\n onToolsChange(updated);\n };\n\n // Find catalog entry for a selected tool to get available versions\n const findCatalogEntry = (mapping: ToolMapping): ToolCatalogEntry | undefined => {\n return catalog.find(\n (entry) =>\n entry.tool_name === mapping.tool_name &&\n entry.server_path === mapping.backend_server_path\n );\n };\n\n return (\n
\n {/* Left Panel: Available Tools */}\n
\n
\n

\n Available Tools\n

\n
\n \n setSearchQuery(e.target.value)}\n placeholder=\"Search tools...\"\n aria-label=\"Search available tools\"\n className=\"w-full pl-9 pr-4 py-1.5 text-sm border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-teal-500 focus:border-transparent\"\n />\n
\n
\n\n
\n {loading && (\n
\n Loading tool catalog...\n
\n )}\n\n {error && (\n
\n {error}\n
\n )}\n\n {!loading && !error && filteredGroups.length === 0 && (\n
\n {searchQuery ? 'No matching tools found' : 'No tools available'}\n
\n )}\n\n {filteredGroups.map((group) => (\n
\n toggleServerGroup(group.serverPath)}\n className=\"w-full flex items-center justify-between px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors\"\n >\n
\n {expandedServers.has(group.serverPath) ? (\n \n ) : (\n \n )}\n {group.serverName}\n
\n \n {group.tools.length}\n \n \n\n {expandedServers.has(group.serverPath) && (\n
\n {!areAllGroupToolsSelected(group) && (\n handleSelectAllFromGroup(group)}\n className=\"w-full text-left px-3 py-1.5 text-xs font-medium text-teal-600 dark:text-teal-400 hover:bg-teal-50 dark:hover:bg-teal-900/20 rounded transition-colors mb-1\"\n >\n Select All ({group.tools.length} tools)\n \n )}\n {group.tools.map((tool) => {\n const selected = isToolSelected(tool);\n return (\n handleAddTool(tool)}\n disabled={selected}\n role=\"option\"\n aria-selected={selected}\n className={`w-full text-left px-3 py-2 text-sm rounded transition-colors mb-1 ${\n selected\n ? 'bg-teal-50 dark:bg-teal-900/20 text-teal-600 dark:text-teal-400 cursor-default'\n : 'hover:bg-gray-100 dark:hover:bg-gray-700 text-gray-700 dark:text-gray-300'\n }`}\n >\n
\n {tool.tool_name}\n {!selected && (\n \n )}\n {selected && (\n Added\n )}\n
\n {tool.description && (\n

\n {tool.description}\n

\n )}\n \n );\n })}\n
\n )}\n
\n ))}\n
\n
\n\n {/* Right Panel: Selected Tools */}\n
\n
\n

\n Selected Tools ({selectedTools.length})\n

\n
\n\n
\n {selectedTools.length === 0 && (\n
\n No tools selected. Click on tools from the left panel to add them.\n
\n )}\n\n {selectedTools.map((mapping, index) => {\n const catalogEntry = findCatalogEntry(mapping);\n const hasMultipleVersions =\n catalogEntry && catalogEntry.available_versions.length > 1;\n\n return (\n \n
\n
\n \n {mapping.alias || mapping.tool_name}\n \n {mapping.alias && (\n \n (from {mapping.tool_name})\n \n )}\n
\n
\n \n setEditingAlias(editingAlias === index ? null : index)\n }\n className=\"p-1 text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 rounded transition-colors\"\n title=\"Set alias\"\n >\n \n \n handleRemoveTool(index)}\n className=\"p-1 text-gray-400 hover:text-red-500 rounded transition-colors\"\n title=\"Remove tool\"\n >\n \n \n
\n
\n\n
\n {mapping.backend_server_path}\n
\n\n {/* Alias input */}\n {editingAlias === index && (\n
\n handleAliasChange(index, e.target.value)}\n placeholder=\"Tool alias (optional)\"\n className=\"w-full px-2 py-1 text-xs border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\n focus:ring-1 focus:ring-teal-500 focus:border-transparent\"\n />\n
\n )}\n\n {/* Version selector */}\n {hasMultipleVersions && (\n
\n handleVersionChange(index, e.target.value)}\n className=\"w-full px-2 py-1 text-xs border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\n focus:ring-1 focus:ring-teal-500 focus:border-transparent\"\n >\n \n {catalogEntry.available_versions.map((v) => (\n \n ))}\n \n
\n )}\n
\n );\n })}\n
\n
\n
\n );\n};\n\nexport default ToolSelector;\n" }, { "path": "frontend/src/components/UptimeDisplay.tsx", "content": "import React, {\n useState,\n useEffect,\n} from 'react';\nimport {\n SystemStats,\n} from '../types/stats';\n\n\n/**\n * UptimeDisplay component shows system uptime with a hover tooltip containing detailed stats.\n *\n * Features:\n * - Fetches /api/stats every 60 seconds\n * - Displays human-readable uptime (e.g., \"2 days 5 hours\")\n * - Shows detailed system info on hover\n * - Handles loading and error states gracefully\n * - Hidden on mobile screens (<768px)\n */\nconst UptimeDisplay: React.FC = () => {\n const [stats, setStats] = useState(null);\n const [error, setError] = useState(false);\n\n\n useEffect(() => {\n const fetchStats = async () => {\n try {\n const response = await fetch('/api/stats');\n if (!response.ok) {\n throw new Error('Failed to fetch stats');\n }\n const data = await response.json();\n setStats(data);\n setError(false);\n } catch (err) {\n console.error('Error fetching stats:', err);\n setError(true);\n }\n };\n\n // Initial fetch\n fetchStats();\n\n // Poll every 60 seconds\n const interval = setInterval(fetchStats, 60000);\n\n return () => clearInterval(interval);\n }, []);\n\n\n const formatUptime = (\n seconds: number,\n ): string => {\n const days = Math.floor(seconds / 86400);\n const hours = Math.floor((seconds % 86400) / 3600);\n const minutes = Math.floor((seconds % 3600) / 60);\n\n const parts: string[] = [];\n if (days > 0) {\n parts.push(`${days} day${days > 1 ? 's' : ''}`);\n }\n if (hours > 0) {\n parts.push(`${hours} hour${hours > 1 ? 's' : ''}`);\n }\n if (parts.length === 0 && minutes > 0) {\n parts.push(`${minutes} minute${minutes > 1 ? 's' : ''}`);\n }\n if (parts.length === 0) {\n return 'less than a minute';\n }\n\n return parts.join(' ');\n };\n\n\n if (error) {\n return (\n
\n \n Uptime: unavailable\n \n
\n );\n }\n\n\n if (!stats) {\n return null;\n }\n\n\n const uptimeText = formatUptime(stats.uptime_seconds);\n const dbStatusColor = stats.database_status.status.toLowerCase() === 'healthy'\n ? 'text-green-600 dark:text-green-400'\n : 'text-red-600 dark:text-red-400';\n const authStatusColor = stats.auth_status.status.toLowerCase() === 'healthy'\n ? 'text-green-600 dark:text-green-400'\n : 'text-red-600 dark:text-red-400';\n\n\n return (\n
\n \n Uptime: {uptimeText}\n \n\n {/* Tooltip on hover */}\n
\n
\n

\n AI Gateway and Registry\n

\n\n {/* Version & Start Time */}\n
\n
\n Version:\n \n {stats.version}\n \n
\n
\n Started:\n \n {new Date(stats.started_at).toLocaleString()}\n \n
\n
\n\n {/* Deployment */}\n
\n

\n Deployment\n

\n
\n
\n Type:\n \n {stats.deployment_type}\n \n
\n
\n Mode:\n \n {stats.deployment_mode}\n \n
\n
\n
\n\n {/* Registry Stats */}\n
\n

\n Registry Stats\n

\n
\n
\n Servers:\n \n {stats.registry_stats.servers}\n \n
\n
\n Agents:\n \n {stats.registry_stats.agents}\n \n
\n
\n Skills:\n \n {stats.registry_stats.skills}\n \n
\n
\n
\n\n {/* Database Status */}\n
\n

\n Database\n

\n
\n
\n Backend:\n \n {stats.database_status.backend}\n \n
\n
\n Status:\n \n {stats.database_status.status}\n \n
\n
\n Host:\n \n {stats.database_status.host}\n \n
\n
\n
\n\n {/* Auth Server Status */}\n
\n

\n Auth Server\n

\n
\n
\n Provider:\n \n {stats.auth_status.provider}\n \n
\n
\n Status:\n \n {stats.auth_status.status}\n \n
\n
\n URL:\n \n {stats.auth_status.url}\n \n
\n
\n
\n
\n
\n
\n );\n};\n\n\nexport default UptimeDisplay;\n" }, { "path": "frontend/src/components/VersionBadge.tsx", "content": "import React from 'react';\nimport { ChevronDownIcon } from '@heroicons/react/24/outline';\n\n\ninterface ServerVersion {\n version: string;\n proxy_pass_url: string;\n status: string;\n is_default: boolean;\n released?: string;\n sunset_date?: string;\n description?: string;\n}\n\n\ninterface VersionBadgeProps {\n versions?: ServerVersion[] | null;\n defaultVersion?: string | null;\n onClick?: () => void;\n}\n\n\n/**\n * VersionBadge component displays the current version of a server.\n *\n * - Shows the default version as a clickable badge\n * - Displays dropdown arrow when multiple versions exist\n * - Hidden when server has no versions (single-version backward compatibility)\n */\nconst VersionBadge: React.FC = ({\n versions,\n defaultVersion,\n onClick\n}) => {\n // Don't render badge if no versions configured (backward compatibility)\n if (!versions || versions.length === 0) {\n return null;\n }\n\n // Find the current default version\n const currentVersion = defaultVersion ||\n versions.find(v => v.is_default)?.version ||\n versions[0]?.version ||\n 'v1.0.0';\n\n const hasMultipleVersions = versions.length > 1;\n\n return (\n \n {currentVersion}\n {hasMultipleVersions && (\n \n )}\n \n );\n};\n\n\nexport default VersionBadge;\n" }, { "path": "frontend/src/components/VersionSelectorModal.tsx", "content": "import React, { useState } from 'react';\nimport axios from 'axios';\nimport {\n XMarkIcon,\n CheckCircleIcon,\n ExclamationTriangleIcon,\n ArrowPathIcon,\n} from '@heroicons/react/24/outline';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\n\ninterface ServerVersion {\n version: string;\n proxy_pass_url: string;\n status: string;\n is_default: boolean;\n released?: string;\n sunset_date?: string;\n description?: string;\n}\n\n\ninterface VersionSelectorModalProps {\n isOpen: boolean;\n onClose: () => void;\n serverName: string;\n serverPath: string;\n versions: ServerVersion[];\n defaultVersion: string | null;\n onVersionChange?: (newDefaultVersion: string) => void;\n onRefreshServer?: () => void;\n onShowToast?: (message: string, type: 'success' | 'error') => void;\n authToken?: string | null;\n canModify?: boolean;\n}\n\n\n/**\n * VersionSelectorModal displays all versions of a server and allows\n * administrators to switch the default version.\n */\nconst VersionSelectorModal: React.FC = ({\n isOpen,\n onClose,\n serverName,\n serverPath,\n versions,\n defaultVersion,\n onVersionChange,\n onRefreshServer,\n onShowToast,\n authToken,\n canModify = false,\n}) => {\n const [loading, setLoading] = useState(null);\n\n useEscapeKey(onClose, isOpen);\n\n if (!isOpen) {\n return null;\n }\n\n const handleSetDefault = async (version: string) => {\n if (loading || version === defaultVersion) {\n return;\n }\n\n setLoading(version);\n try {\n const headers = authToken ? { Authorization: `Bearer ${authToken}` } : undefined;\n await axios.put(\n `/api/servers${serverPath}/versions/default`,\n { version },\n headers ? { headers } : undefined\n );\n\n if (onVersionChange) {\n onVersionChange(version);\n }\n\n if (onShowToast) {\n onShowToast(`Switched to ${version}`, 'success');\n }\n\n // Trigger a server refresh to get updated data\n if (onRefreshServer) {\n onRefreshServer();\n }\n\n onClose();\n } catch (error: any) {\n console.error('Failed to set default version:', error);\n if (onShowToast) {\n onShowToast(\n error.response?.data?.detail || 'Failed to switch version',\n 'error'\n );\n }\n } finally {\n setLoading(null);\n }\n };\n\n const getStatusBadge = (status: string, isDefault: boolean) => {\n if (isDefault) {\n return (\n \n \n ACTIVE\n \n );\n }\n\n switch (status) {\n case 'deprecated':\n return (\n \n \n deprecated\n \n );\n case 'beta':\n return (\n \n beta\n \n );\n default:\n return (\n \n stable\n \n );\n }\n };\n\n return (\n
\n
\n {/* Header */}\n
\n
\n

\n Select Version\n

\n

\n {serverName}\n

\n
\n \n \n \n
\n\n {/* Version Cards */}\n
\n {versions.map((version) => {\n const isCurrentDefault = version.version === defaultVersion || version.is_default;\n const isLoading = loading === version.version;\n\n return (\n \n {/* Version Header */}\n
\n
\n \n {version.version}\n \n {getStatusBadge(version.status, isCurrentDefault)}\n
\n\n {canModify && !isCurrentDefault && (\n handleSetDefault(version.version)}\n disabled={isLoading}\n className=\"px-3 py-1.5 text-sm font-medium text-indigo-600 hover:text-indigo-700 hover:bg-indigo-50 dark:text-indigo-400 dark:hover:text-indigo-300 dark:hover:bg-indigo-900/30 rounded-lg transition-colors disabled:opacity-50\"\n >\n {isLoading ? (\n \n ) : (\n 'Set Active'\n )}\n \n )}\n
\n\n {/* Version Details */}\n
\n
\n Backend:{' '}\n \n {version.proxy_pass_url}\n \n
\n\n {version.released && (\n
\n Released: {version.released}\n
\n )}\n\n {version.sunset_date && (\n
\n Sunset: {version.sunset_date}\n
\n )}\n\n {version.description && (\n
\n {version.description}\n
\n )}\n
\n
\n );\n })}\n
\n\n {/* Info Footer */}\n
\n

\n Clients can request specific versions using the{' '}\n \n X-MCP-Server-Version\n {' '}\n header.\n

\n
\n
\n
\n );\n};\n\n\nexport default VersionSelectorModal;\n" }, { "path": "frontend/src/components/VirtualServerCard.tsx", "content": "import React, { useState, useCallback } from 'react';\nimport axios from 'axios';\nimport {\n PencilIcon,\n TrashIcon,\n CogIcon,\n WrenchScrewdriverIcon,\n XMarkIcon,\n ChevronDownIcon,\n ChevronRightIcon,\n} from '@heroicons/react/24/outline';\nimport { VirtualServerInfo, ResolvedTool } from '../types/virtualServer';\nimport ServerConfigModal from './ServerConfigModal';\nimport StarRatingWidget from './StarRatingWidget';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\n\n/**\n * Props for the VirtualServerCard component.\n */\ninterface VirtualServerCardProps {\n virtualServer: VirtualServerInfo;\n canModify: boolean;\n onToggle: (path: string, enabled: boolean) => void;\n onEdit: (server: VirtualServerInfo) => void;\n onDelete: (path: string) => void;\n onShowToast?: (message: string, type: 'success' | 'error' | 'info') => void;\n onServerUpdate?: (path: string, updates: Partial) => void;\n authToken?: string | null;\n}\n\n\n/**\n * VirtualServerCard renders a dashboard card for a virtual MCP server.\n *\n * Uses a teal/cyan gradient for visual distinction from regular ServerCard.\n * Matches the layout and UI elements of the regular ServerCard.\n */\nconst VirtualServerCard: React.FC = ({\n virtualServer: server,\n canModify,\n onToggle,\n onEdit,\n onDelete,\n onShowToast,\n onServerUpdate,\n authToken,\n}) => {\n const [showTools, setShowTools] = useState(false);\n const [tools, setTools] = useState([]);\n const [loadingTools, setLoadingTools] = useState(false);\n const [expandedBackends, setExpandedBackends] = useState>({});\n const [expandedTools, setExpandedTools] = useState>({});\n const [showConfig, setShowConfig] = useState(false);\n\n useEscapeKey(() => setShowTools(false), showTools);\n\n const handleViewTools = useCallback(async () => {\n if (loadingTools) return;\n\n setShowTools(true);\n setLoadingTools(true);\n\n try {\n // Fetch resolved tools with full details (description, schema)\n const response = await axios.get<{ tools: ResolvedTool[] }>(\n `/api/virtual-servers${server.path}/tools`\n );\n const resolvedTools = response.data.tools || [];\n setTools(resolvedTools);\n\n // Group tools by backend to determine collapse state\n const toolsByBackend: Record = {};\n for (const tool of resolvedTools) {\n const backend = tool.backend_server_path;\n if (!toolsByBackend[backend]) {\n toolsByBackend[backend] = [];\n }\n toolsByBackend[backend].push(tool);\n }\n\n // Auto-expand first backend, collapse tools if more than 3 in any backend\n const backends = Object.keys(toolsByBackend);\n if (backends.length > 0) {\n setExpandedBackends({ [backends[0]]: true });\n }\n\n // If any backend has more than 3 tools, collapse all tools by default\n // Otherwise expand all tools\n const hasLargeBackend = Object.values(toolsByBackend).some(t => t.length > 3);\n if (!hasLargeBackend) {\n // Expand all tools if small number of tools\n const allToolsExpanded: Record = {};\n for (const tool of resolvedTools) {\n allToolsExpanded[tool.name] = true;\n }\n setExpandedTools(allToolsExpanded);\n } else {\n setExpandedTools({});\n }\n } catch (error) {\n console.error('Failed to fetch tools:', error);\n onShowToast?.('Failed to load tools', 'error');\n setTools([]);\n } finally {\n setLoadingTools(false);\n }\n }, [server.path, loadingTools, onShowToast]);\n\n const toggleBackend = (backend: string) => {\n setExpandedBackends(prev => ({\n ...prev,\n [backend]: !prev[backend]\n }));\n };\n\n const toggleTool = (toolName: string) => {\n setExpandedTools(prev => ({\n ...prev,\n [toolName]: !prev[toolName]\n }));\n };\n\n // Group tools by backend server\n const toolsByBackend = tools.reduce>((acc, tool) => {\n const backend = tool.backend_server_path;\n if (!acc[backend]) {\n acc[backend] = [];\n }\n acc[backend].push(tool);\n return acc;\n }, {});\n\n const backendPaths = Object.keys(toolsByBackend);\n\n // Create a Server-like object for ServerConfigModal\n const serverForConfig = {\n name: server.server_name,\n path: server.path,\n description: server.description,\n enabled: server.is_enabled,\n tags: server.tags,\n };\n\n return (\n <>\n
\n {/* Header */}\n
\n
\n
\n
\n

\n {server.server_name}\n

\n \n VIRTUAL\n \n
\n\n \n {server.path}\n \n
\n\n
\n {canModify && (\n onEdit(server)}\n title=\"Edit virtual server\"\n >\n \n \n )}\n\n {/* Configuration Generator Button */}\n setShowConfig(true)}\n className=\"p-2 text-gray-400 hover:text-green-600 dark:hover:text-green-300 hover:bg-green-50 dark:hover:bg-green-700/50 rounded-lg transition-all duration-200\"\n title=\"Copy mcp.json configuration\"\n >\n \n \n\n {canModify && (\n onDelete(server.path)}\n className=\"p-2 text-gray-400 hover:text-red-600 dark:hover:text-red-400 hover:bg-red-50 dark:hover:bg-red-700/50 rounded-lg transition-all duration-200\"\n title=\"Delete virtual server\"\n >\n \n \n )}\n
\n
\n\n {/* Description */}\n

\n {server.description || 'No description available'}\n

\n\n {/* Tags */}\n {server.tags && server.tags.length > 0 && (\n
\n {server.tags.slice(0, 3).map((tag) => (\n \n #{tag}\n \n ))}\n {server.tags.length > 3 && (\n \n +{server.tags.length - 3}\n \n )}\n
\n )}\n
\n\n {/* Stats - 2-column layout */}\n
\n
\n {/* Rating */}\n {\n onServerUpdate?.(server.path, { num_stars: newRating });\n }}\n />\n\n {/* Tools - clickable */}\n
\n {server.tool_count > 0 ? (\n \n
\n \n
\n
\n
{server.tool_count}
\n
Tools
\n
\n \n ) : (\n
\n
\n \n
\n
\n
0
\n
Tools
\n
\n
\n )}\n
\n\n
\n
\n\n {/* Footer */}\n
\n
\n
\n
\n \n {server.is_enabled ? 'Enabled' : 'Disabled'}\n \n
\n\n {/* Toggle Switch */}\n {canModify && (\n
\n
\n\n {/* Tools Modal */}\n {showTools && (\n
\n
\n
\n

\n Tools for {server.server_name}\n

\n setShowTools(false)}\n className=\"p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-700\"\n >\n \n \n
\n\n {loadingTools ? (\n
\n
\n Loading tools...\n
\n ) : tools.length > 0 ? (\n
\n {backendPaths.map((backend) => {\n const backendTools = toolsByBackend[backend];\n const isBackendExpanded = expandedBackends[backend];\n\n return (\n
\n toggleBackend(backend)}\n className=\"w-full flex items-center justify-between px-4 py-3 bg-gray-50 dark:bg-gray-900/50 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors text-left\"\n >\n
\n {isBackendExpanded ? (\n \n ) : (\n \n )}\n \n {backend}\n \n
\n \n {backendTools.length} tool{backendTools.length !== 1 ? 's' : ''}\n \n \n\n {isBackendExpanded && (\n
    \n {backendTools.map((tool) => {\n const isToolExpanded = expandedTools[tool.name];\n const hasDetails = tool.description || (tool.input_schema && Object.keys(tool.input_schema).length > 0);\n\n return (\n \n {/* Tool header - clickable to expand */}\n hasDetails && toggleTool(tool.name)}\n className={`w-full px-4 py-3 text-left ${hasDetails ? 'cursor-pointer hover:bg-gray-50 dark:hover:bg-gray-700/50' : 'cursor-default'}`}\n disabled={!hasDetails}\n >\n
    \n
    \n {hasDetails && (\n isToolExpanded ? (\n \n ) : (\n \n )\n )}\n {!hasDetails &&
    }\n \n {tool.name}\n \n {tool.original_name && tool.name !== tool.original_name && (\n \n (original: {tool.original_name})\n \n )}\n
    \n {tool.backend_version && (\n \n v{tool.backend_version}\n \n )}\n
    \n \n\n {/* Expanded tool details */}\n {isToolExpanded && hasDetails && (\n
    \n {/* Description */}\n {tool.description && (\n
    \n

    \n {tool.description}\n

    \n
    \n )}\n\n {/* Schema */}\n {tool.input_schema && Object.keys(tool.input_schema).length > 0 && (\n
    \n
    \n \n View Schema\n \n 
    \n                                            {JSON.stringify(tool.input_schema, null, 2)}\n
    \n
    \n
    \n )}\n\n {/* Required scopes */}\n {tool.required_scopes && tool.required_scopes.length > 0 && (\n
    \n {tool.required_scopes.map((scope) => (\n \n {scope}\n \n ))}\n
    \n )}\n
    \n )}\n \n );\n })}\n
\n )}\n
\n );\n })}\n
\n ) : (\n

\n No tools available for this virtual server.\n

\n )}\n
\n
\n )}\n\n {/* ServerConfigModal - reusing exact same component as ServerCard */}\n setShowConfig(false)}\n onShowToast={onShowToast}\n />\n \n );\n};\n\nexport default VirtualServerCard;\n" }, { "path": "frontend/src/components/VirtualServerDetailsModal.tsx", "content": "import React, { useState, useEffect, useMemo } from 'react';\nimport { XMarkIcon, ChevronDownIcon, ChevronRightIcon } from '@heroicons/react/24/outline';\nimport { VirtualServerInfo, VirtualServerConfig, ToolMapping } from '../types/virtualServer';\nimport axios from 'axios';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\n\ninterface VirtualServerDetailsModalProps {\n virtualServer: VirtualServerInfo;\n isOpen: boolean;\n onClose: () => void;\n}\n\n\nconst VirtualServerDetailsModal: React.FC = ({\n virtualServer,\n isOpen,\n onClose\n}) => {\n const [fullConfig, setFullConfig] = useState(null);\n const [loading, setLoading] = useState(false);\n const [expandedBackends, setExpandedBackends] = useState>({});\n\n useEscapeKey(onClose, isOpen);\n\n // Fetch full config when modal opens\n useEffect(() => {\n if (!isOpen || !virtualServer?.path) {\n setFullConfig(null);\n return;\n }\n\n const fetchConfig = async () => {\n setLoading(true);\n try {\n const response = await axios.get(\n `/api/virtual-servers${virtualServer.path}`\n );\n setFullConfig(response.data);\n // Auto-expand first backend\n if (response.data.tool_mappings?.length > 0) {\n const firstBackend = response.data.tool_mappings[0].backend_server_path;\n setExpandedBackends({ [firstBackend]: true });\n }\n } catch (err) {\n console.error('Failed to fetch virtual server config:', err);\n } finally {\n setLoading(false);\n }\n };\n\n fetchConfig();\n }, [isOpen, virtualServer?.path]);\n\n // Group tools by backend server\n const toolsByBackend = useMemo(() => {\n const tools = fullConfig?.tool_mappings || virtualServer.tool_mappings || [];\n const grouped: Record = {};\n\n for (const tool of tools) {\n const backend = tool.backend_server_path;\n if (!grouped[backend]) {\n grouped[backend] = [];\n }\n grouped[backend].push(tool);\n }\n\n return grouped;\n }, [fullConfig, virtualServer.tool_mappings]);\n\n const toggleBackend = (backend: string) => {\n setExpandedBackends(prev => ({\n ...prev,\n [backend]: !prev[backend]\n }));\n };\n\n if (!isOpen) return null;\n\n const backendPaths = virtualServer.backend_paths || [];\n const hasToolDetails = Object.keys(toolsByBackend).length > 0;\n\n return (\n
\n
\n
\n
\n
\n

\n {virtualServer.server_name}\n

\n \n VIRTUAL\n \n
\n

{virtualServer.path}

\n
\n \n \n \n
\n
\n {/* Description */}\n
\n

\n Description\n

\n

\n {virtualServer.description || 'No description available.'}\n

\n
\n\n {/* Tags */}\n {virtualServer.tags && virtualServer.tags.length > 0 && (\n
\n

\n Tags\n

\n
\n {virtualServer.tags.map((tag) => (\n \n {tag}\n \n ))}\n
\n
\n )}\n\n {/* Backend Servers with Tools */}\n {backendPaths.length > 0 && (\n
\n

\n Backend Servers ({backendPaths.length}) - Tools ({virtualServer.tool_count})\n

\n {loading ? (\n
\n
\n Loading tool details...\n
\n ) : (\n
    \n {backendPaths.map((path) => {\n const backendTools = toolsByBackend[path] || [];\n const isExpanded = expandedBackends[path];\n const toolCount = backendTools.length;\n\n return (\n
  • \n toggleBackend(path)}\n className=\"w-full flex items-center justify-between px-3 py-2 bg-gray-50 dark:bg-gray-900/50 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors text-left\"\n >\n
    \n {hasToolDetails ? (\n isExpanded ? (\n \n ) : (\n \n )\n ) : (\n
    \n )}\n \n {path}\n \n
    \n {hasToolDetails && (\n \n {toolCount} tool{toolCount !== 1 ? 's' : ''}\n \n )}\n \n\n {/* Expanded tools list */}\n {isExpanded && backendTools.length > 0 && (\n
      \n {backendTools.map((tool) => (\n \n
      \n
      \n \n {tool.alias || tool.tool_name}\n \n {tool.alias && tool.alias !== tool.tool_name && (\n \n (original: {tool.tool_name})\n \n )}\n
      \n {tool.backend_version && (\n \n v{tool.backend_version}\n \n )}\n
      \n {tool.description_override && (\n

      \n {tool.description_override}\n

      \n )}\n \n ))}\n
    \n )}\n
    • \n );\n })}\n
\n )}\n
\n )}\n\n {/* Status */}\n
\n

\n Status\n

\n
\n
\n \n {virtualServer.is_enabled ? 'Enabled' : 'Disabled'}\n \n
\n
\n\n {/* Required Scopes */}\n {virtualServer.required_scopes && virtualServer.required_scopes.length > 0 && (\n
\n

\n Required Scopes\n

\n
\n {virtualServer.required_scopes.map((scope) => (\n \n {scope}\n \n ))}\n
\n
\n )}\n\n {/* Supported Transports */}\n {virtualServer.supported_transports && virtualServer.supported_transports.length > 0 && (\n
\n

\n Supported Transports\n

\n
\n {virtualServer.supported_transports.map((transport) => (\n \n {transport}\n \n ))}\n
\n
\n )}\n
\n
\n
\n );\n};\n\nexport default VirtualServerDetailsModal;\n" }, { "path": "frontend/src/components/VirtualServerForm.tsx", "content": "import React, { useState, useEffect, useMemo } from 'react';\nimport { XMarkIcon, PlusIcon, TrashIcon, CheckIcon } from '@heroicons/react/24/outline';\nimport {\n VirtualServerConfig,\n CreateVirtualServerRequest,\n UpdateVirtualServerRequest,\n ToolMapping,\n} from '../types/virtualServer';\nimport ToolSelector from './ToolSelector';\n\n\n/**\n * Props for the VirtualServerForm component.\n */\ninterface VirtualServerFormProps {\n virtualServer?: VirtualServerConfig | null;\n onSave: (\n data: CreateVirtualServerRequest | UpdateVirtualServerRequest,\n ) => Promise;\n onCancel: () => void;\n}\n\n\n/**\n * Step definitions for the wizard.\n */\nconst STEPS = [\n { id: 'basics', label: 'Basics' },\n { id: 'tools', label: 'Tool Selection' },\n { id: 'config', label: 'Configuration' },\n { id: 'review', label: 'Review' },\n] as const;\n\ntype StepId = typeof STEPS[number]['id'];\n\n\n/**\n * Generate a URL path from a server name.\n */\nfunction _generatePathFromName(name: string): string {\n const slug = name\n .toLowerCase()\n .replace(/[^a-z0-9]+/g, '-')\n .replace(/^-|-$/g, '');\n return `/virtual/${slug}`;\n}\n\n\n/**\n * VirtualServerForm provides a stepped wizard for creating or editing virtual\n * MCP servers.\n *\n * Steps: Basics -> Tool Selection -> Configuration -> Review\n *\n * In edit mode (when virtualServer prop is provided), the form is pre-populated\n * with existing data. In create mode, the path auto-generates from the name.\n */\nconst VirtualServerForm: React.FC = ({\n virtualServer,\n onSave,\n onCancel,\n}) => {\n const isEditMode = !!virtualServer;\n\n const [currentStep, setCurrentStep] = useState('basics');\n const [name, setName] = useState('');\n const [path, setPath] = useState('');\n const [description, setDescription] = useState('');\n const [tags, setTags] = useState('');\n const [requiredScopes, setRequiredScopes] = useState('');\n const [toolMappings, setToolMappings] = useState([]);\n const [manualMappings, setManualMappings] = useState<\n Array<{ backend_server_path: string; tool_name: string; alias: string }>\n >([]);\n const [useToolSelector, setUseToolSelector] = useState(true);\n const [saving, setSaving] = useState(false);\n const [validationError, setValidationError] = useState(null);\n const [pathManuallyEdited, setPathManuallyEdited] = useState(false);\n\n const currentStepIndex = STEPS.findIndex((s) => s.id === currentStep);\n\n // Populate form when editing\n useEffect(() => {\n if (virtualServer) {\n setName(virtualServer.server_name);\n setPath(virtualServer.path);\n setDescription(virtualServer.description || '');\n setTags(virtualServer.tags?.join(', ') || '');\n setRequiredScopes(virtualServer.required_scopes?.join(', ') || '');\n setToolMappings(virtualServer.tool_mappings || []);\n setPathManuallyEdited(true);\n }\n }, [virtualServer]);\n\n // Auto-generate path from name in create mode\n useEffect(() => {\n if (!isEditMode && !pathManuallyEdited && name) {\n setPath(_generatePathFromName(name));\n }\n }, [name, isEditMode, pathManuallyEdited]);\n\n const handlePathChange = (value: string) => {\n setPath(value);\n setPathManuallyEdited(true);\n };\n\n const addManualMapping = () => {\n setManualMappings([\n ...manualMappings,\n { backend_server_path: '', tool_name: '', alias: '' },\n ]);\n };\n\n const removeManualMapping = (index: number) => {\n setManualMappings(manualMappings.filter((_, i) => i !== index));\n };\n\n const updateManualMapping = (\n index: number,\n field: 'backend_server_path' | 'tool_name' | 'alias',\n value: string,\n ) => {\n setManualMappings(\n manualMappings.map((m, i) =>\n i === index ? { ...m, [field]: value } : m,\n ),\n );\n };\n\n // Combine all tool mappings from both modes\n const allMappings: ToolMapping[] = useMemo(() => [\n ...toolMappings,\n ...manualMappings\n .filter((m) => m.backend_server_path && m.tool_name)\n .map((m) => ({\n tool_name: m.tool_name,\n backend_server_path: m.backend_server_path,\n alias: m.alias || null,\n backend_version: null,\n })),\n ], [toolMappings, manualMappings]);\n\n const parsedTags = useMemo(() =>\n tags.split(',').map((t) => t.trim()).filter(Boolean),\n [tags]\n );\n\n const parsedScopes = useMemo(() =>\n requiredScopes.split(',').map((s) => s.trim()).filter(Boolean),\n [requiredScopes]\n );\n\n // Validate current step before advancing\n const validateStep = (step: StepId): string | null => {\n if (step === 'basics') {\n if (!name.trim()) return 'Server name is required';\n if (!path.trim()) return 'Server path is required';\n }\n return null;\n };\n\n const goToNext = () => {\n const error = validateStep(currentStep);\n if (error) {\n setValidationError(error);\n return;\n }\n setValidationError(null);\n const nextIndex = currentStepIndex + 1;\n if (nextIndex < STEPS.length) {\n setCurrentStep(STEPS[nextIndex].id);\n }\n };\n\n const goToPrev = () => {\n setValidationError(null);\n const prevIndex = currentStepIndex - 1;\n if (prevIndex >= 0) {\n setCurrentStep(STEPS[prevIndex].id);\n }\n };\n\n const goToStep = (step: StepId) => {\n const targetIndex = STEPS.findIndex((s) => s.id === step);\n // Allow jumping backward freely, but forward only to visited steps\n if (targetIndex <= currentStepIndex) {\n setValidationError(null);\n setCurrentStep(step);\n }\n };\n\n const handleSubmit = async () => {\n setValidationError(null);\n\n const basicsError = validateStep('basics');\n if (basicsError) {\n setCurrentStep('basics');\n setValidationError(basicsError);\n return;\n }\n\n setSaving(true);\n try {\n if (isEditMode) {\n const updateData: UpdateVirtualServerRequest = {\n server_name: name.trim(),\n description: description.trim() || null,\n tool_mappings: allMappings,\n required_scopes: parsedScopes,\n tags: parsedTags,\n };\n await onSave(updateData);\n } else {\n const createData: CreateVirtualServerRequest = {\n server_name: name.trim(),\n path: path.trim(),\n description: description.trim(),\n tool_mappings: allMappings,\n required_scopes: parsedScopes,\n tags: parsedTags,\n };\n await onSave(createData);\n }\n } catch (err: unknown) {\n const axiosErr = err as { response?: { data?: { detail?: string } }; message?: string };\n setValidationError(\n axiosErr.response?.data?.detail ||\n axiosErr.message ||\n 'Failed to save virtual server'\n );\n } finally {\n setSaving(false);\n }\n };\n\n // Render step indicator\n const renderStepIndicator = () => (\n
\n {STEPS.map((step, index) => {\n const isActive = step.id === currentStep;\n const isCompleted = index < currentStepIndex;\n const isClickable = index <= currentStepIndex;\n\n return (\n \n {index > 0 && (\n
\n )}\n isClickable && goToStep(step.id)}\n disabled={!isClickable}\n className={`flex items-center gap-2 px-3 py-1.5 rounded-lg text-sm font-medium transition-colors ${\n isActive\n ? 'bg-teal-100 dark:bg-teal-900/30 text-teal-700 dark:text-teal-300'\n : isCompleted\n ? 'text-teal-600 dark:text-teal-400 hover:bg-teal-50 dark:hover:bg-teal-900/20 cursor-pointer'\n : 'text-gray-400 dark:text-gray-500 cursor-default'\n }`}\n >\n \n {isCompleted ? : index + 1}\n \n {step.label}\n \n \n );\n })}\n
\n );\n\n // Step 1: Basics\n const renderBasicsStep = () => (\n
\n
\n \n setName(e.target.value)}\n placeholder=\"e.g. Dev Essentials\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-teal-500 focus:border-transparent\"\n />\n
\n\n
\n \n handlePathChange(e.target.value)}\n placeholder=\"/virtual/dev-essentials\"\n disabled={isEditMode}\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-teal-500 focus:border-transparent\n disabled:opacity-50 disabled:cursor-not-allowed font-mono text-sm\"\n />\n {!isEditMode && (\n

\n Auto-generated from name. Must start with /virtual/.\n

\n )}\n
\n\n
\n \n setDescription(e.target.value)}\n placeholder=\"Describe what this virtual server provides...\"\n rows={3}\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-teal-500 focus:border-transparent\"\n />\n
\n\n
\n \n setTags(e.target.value)}\n placeholder=\"development, tools, frontend (comma-separated)\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-teal-500 focus:border-transparent\"\n />\n
\n
\n );\n\n // Step 2: Tool Selection\n const renderToolSelectionStep = () => (\n
\n
\n \n setUseToolSelector(!useToolSelector)}\n className=\"text-xs text-teal-600 dark:text-teal-400 hover:underline\"\n >\n {useToolSelector ? 'Switch to manual entry' : 'Switch to tool picker'}\n \n
\n\n {useToolSelector ? (\n \n ) : (\n
\n {manualMappings.map((mapping, index) => (\n \n
\n \n updateManualMapping(index, 'backend_server_path', e.target.value)\n }\n placeholder=\"Backend server path (e.g. /github)\"\n className=\"w-full px-2 py-1.5 text-sm border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\"\n />\n \n updateManualMapping(index, 'tool_name', e.target.value)\n }\n placeholder=\"Tool name\"\n className=\"w-full px-2 py-1.5 text-sm border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\"\n />\n \n updateManualMapping(index, 'alias', e.target.value)\n }\n placeholder=\"Alias (optional)\"\n className=\"w-full px-2 py-1.5 text-sm border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\"\n />\n
\n removeManualMapping(index)}\n className=\"p-2 text-gray-400 hover:text-red-500 transition-colors\"\n >\n \n \n
\n ))}\n \n \n Add Tool Mapping\n \n
\n )}\n
\n );\n\n // Step 3: Configuration (aliases, version pins, scopes)\n const renderConfigStep = () => (\n
\n {/* Tool alias/version overrides */}\n
\n \n {allMappings.length === 0 ? (\n

\n No tools selected. Go back to add tools.\n

\n ) : (\n
\n {allMappings.map((mapping, index) => (\n \n
\n
\n {mapping.tool_name}\n
\n
\n {mapping.backend_server_path}\n
\n
\n
\n {\n if (index < toolMappings.length) {\n const updated = [...toolMappings];\n updated[index] = { ...updated[index], alias: e.target.value || null };\n setToolMappings(updated);\n } else {\n const manualIndex = index - toolMappings.length;\n if (manualIndex < manualMappings.length) {\n updateManualMapping(manualIndex, 'alias', e.target.value);\n }\n }\n }}\n placeholder=\"Alias\"\n className=\"w-full px-2 py-1 text-xs border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\"\n />\n
\n
\n {\n if (index < toolMappings.length) {\n const updated = [...toolMappings];\n updated[index] = { ...updated[index], backend_version: e.target.value || null };\n setToolMappings(updated);\n }\n // Manual mappings don't have backend_version support\n }}\n placeholder=\"Version\"\n className=\"w-full px-2 py-1 text-xs border border-gray-300 dark:border-gray-600 rounded\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\"\n />\n
\n
\n ))}\n
\n )}\n
\n\n {/* Required Scopes */}\n
\n \n setRequiredScopes(e.target.value)}\n placeholder=\"scope1, scope2 (comma-separated)\"\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-teal-500 focus:border-transparent\"\n />\n

\n Scopes required to access this virtual server. Leave empty for unrestricted access.\n

\n
\n
\n );\n\n // Step 4: Review\n const renderReviewStep = () => (\n
\n
\n

\n Server Details\n

\n
\n
Name
\n
{name || '-'}
\n
Path
\n
{path || '-'}
\n
Description
\n
{description || '-'}
\n
Tags
\n
\n {parsedTags.length > 0 ? parsedTags.join(', ') : '-'}\n
\n
Required Scopes
\n
\n {parsedScopes.length > 0 ? parsedScopes.join(', ') : 'None (unrestricted)'}\n
\n
\n
\n\n
\n

\n Tool Mappings ({allMappings.length})\n

\n {allMappings.length === 0 ? (\n

No tools configured

\n ) : (\n
\n {allMappings.map((mapping, index) => (\n \n
\n \n {mapping.alias || mapping.tool_name}\n \n {mapping.alias && (\n \n (from {mapping.tool_name})\n \n )}\n
\n \n {mapping.backend_server_path}\n {mapping.backend_version && ` @${mapping.backend_version}`}\n \n
\n ))}\n
\n )}\n
\n\n {/* Unique backend servers count */}\n
\n {(() => {\n const uniqueBackends = new Set(allMappings.map((m) => m.backend_server_path));\n return `${allMappings.length} tool(s) from ${uniqueBackends.size} backend server(s)`;\n })()}\n
\n
\n );\n\n // Render the current step content\n const renderCurrentStep = () => {\n switch (currentStep) {\n case 'basics':\n return renderBasicsStep();\n case 'tools':\n return renderToolSelectionStep();\n case 'config':\n return renderConfigStep();\n case 'review':\n return renderReviewStep();\n }\n };\n\n const isLastStep = currentStepIndex === STEPS.length - 1;\n const isFirstStep = currentStepIndex === 0;\n\n // Handle Escape key to close the modal\n useEffect(() => {\n const handleKeyDown = (e: KeyboardEvent) => {\n if (e.key === 'Escape' && !saving) {\n onCancel();\n }\n };\n document.addEventListener('keydown', handleKeyDown);\n return () => document.removeEventListener('keydown', handleKeyDown);\n }, [onCancel, saving]);\n\n return (\n
\n \n {/* Header */}\n
\n

\n {isEditMode ? 'Edit Virtual Server' : 'Create Virtual Server'}\n

\n \n \n \n
\n\n {/* Step indicator */}\n {renderStepIndicator()}\n\n {/* Step content */}\n
\n {/* Validation error */}\n {validationError && (\n
\n

\n {validationError}\n

\n
\n )}\n\n {renderCurrentStep()}\n
\n\n {/* Navigation */}\n
\n \n {isFirstStep ? 'Cancel' : 'Back'}\n \n\n
\n {!isFirstStep && (\n \n Cancel\n \n )}\n {isLastStep ? (\n \n {saving && (\n \n \n \n \n )}\n {isEditMode ? 'Save Changes' : 'Create Virtual Server'}\n \n ) : (\n \n Next\n \n )}\n
\n
\n
\n
\n );\n};\n\nexport default VirtualServerForm;\n" }, { "path": "frontend/src/components/VirtualServerList.tsx", "content": "import React, { useState, useEffect } from 'react';\nimport { useSearchParams } from 'react-router-dom';\nimport {\n PlusIcon,\n MagnifyingGlassIcon,\n ExclamationCircleIcon,\n ArrowPathIcon,\n} from '@heroicons/react/24/outline';\nimport { useAuth } from '../contexts/AuthContext';\nimport {\n useVirtualServers,\n useVirtualServer,\n} from '../hooks/useVirtualServers';\nimport {\n VirtualServerInfo,\n CreateVirtualServerRequest,\n UpdateVirtualServerRequest,\n} from '../types/virtualServer';\nimport VirtualServerForm from './VirtualServerForm';\nimport useEscapeKey from '../hooks/useEscapeKey';\n\n\n/**\n * Props for VirtualServerList component.\n */\ninterface VirtualServerListProps {\n onShowToast: (message: string, type: 'success' | 'error' | 'info') => void;\n}\n\n\n/**\n * VirtualServerList displays a table of all virtual MCP servers\n * with search, create, edit, delete, and toggle functionality.\n */\nconst VirtualServerList: React.FC = ({ onShowToast }) => {\n const { user } = useAuth();\n const [searchParams, setSearchParams] = useSearchParams();\n const {\n virtualServers,\n loading,\n error,\n refreshData,\n createVirtualServer,\n updateVirtualServer,\n deleteVirtualServer,\n toggleVirtualServer,\n } = useVirtualServers();\n\n const [searchQuery, setSearchQuery] = useState('');\n const [showForm, setShowForm] = useState(false);\n const [editingPath, setEditingPath] = useState(undefined);\n const [deleteTarget, setDeleteTarget] = useState(null);\n const [typedName, setTypedName] = useState('');\n const [isDeleting, setIsDeleting] = useState(false);\n\n useEscapeKey(() => { setShowForm(false); setEditingPath(undefined); }, showForm);\n useEscapeKey(() => { setDeleteTarget(null); setTypedName(''); }, !!deleteTarget);\n\n const canModify = user?.can_modify_servers || user?.is_admin || false;\n\n // Fetch full config when editing\n const { virtualServer: editingServer, loading: editingServerLoading } = useVirtualServer(editingPath);\n\n // Handle ?edit= query parameter from Dashboard navigation\n useEffect(() => {\n const editParam = searchParams.get('edit');\n if (editParam && !loading && virtualServers.length > 0) {\n const decodedPath = decodeURIComponent(editParam);\n const serverExists = virtualServers.some((s) => s.path === decodedPath);\n if (serverExists) {\n setEditingPath(decodedPath);\n setShowForm(true);\n }\n // Clear the query param so it doesn't re-trigger\n searchParams.delete('edit');\n setSearchParams(searchParams, { replace: true });\n }\n }, [searchParams, loading, virtualServers]);\n\n // Filter servers by search\n const filteredServers = searchQuery\n ? virtualServers.filter(\n (s) =>\n s.server_name.toLowerCase().includes(searchQuery.toLowerCase()) ||\n s.path.toLowerCase().includes(searchQuery.toLowerCase()) ||\n s.description?.toLowerCase().includes(searchQuery.toLowerCase()) ||\n s.tags?.some((t) => t.toLowerCase().includes(searchQuery.toLowerCase()))\n )\n : virtualServers;\n\n const handleCreate = () => {\n setEditingPath(undefined);\n setShowForm(true);\n };\n\n const handleEdit = (server: VirtualServerInfo) => {\n setEditingPath(server.path);\n setShowForm(true);\n };\n\n const handleSave = async (\n data: CreateVirtualServerRequest | UpdateVirtualServerRequest,\n ) => {\n try {\n if (editingPath) {\n await updateVirtualServer(editingPath, data as UpdateVirtualServerRequest);\n onShowToast('Virtual server updated successfully', 'success');\n } else {\n await createVirtualServer(data as CreateVirtualServerRequest);\n onShowToast('Virtual server created successfully', 'success');\n }\n setShowForm(false);\n setEditingPath(undefined);\n } catch (err: unknown) {\n const message =\n err instanceof Error ? err.message : 'An unexpected error occurred';\n onShowToast(`Failed to save virtual server: ${message}`, 'error');\n }\n };\n\n const handleDelete = async () => {\n if (!deleteTarget || typedName !== deleteTarget.server_name) return;\n\n setIsDeleting(true);\n try {\n await deleteVirtualServer(deleteTarget.path);\n onShowToast(`Virtual server \"${deleteTarget.server_name}\" deleted`, 'success');\n setDeleteTarget(null);\n setTypedName('');\n } catch (err: unknown) {\n const axiosErr = err as { response?: { data?: { detail?: string } }; message?: string };\n onShowToast(\n axiosErr.response?.data?.detail || 'Failed to delete virtual server',\n 'error',\n );\n } finally {\n setIsDeleting(false);\n }\n };\n\n const handleToggle = async (path: string, enabled: boolean) => {\n try {\n await toggleVirtualServer(path, enabled);\n onShowToast(\n `Virtual server ${enabled ? 'enabled' : 'disabled'}`,\n 'success',\n );\n } catch {\n onShowToast('Failed to toggle virtual server', 'error');\n }\n };\n\n // Loading state\n if (loading) {\n return (\n
\n
\n
\n
\n
\n
\n
\n {[1, 2, 3].map((i) => (\n \n ))}\n
\n
\n );\n }\n\n // Error state\n if (error) {\n return (\n
\n \n

\n Failed to Load Virtual Servers\n

\n

{error}

\n \n Retry\n \n
\n );\n }\n\n return (\n
\n {/* Header */}\n
\n
\n

\n Virtual MCP Servers\n

\n

\n Manage virtual servers that aggregate tools from multiple backends\n

\n
\n
\n \n \n \n {canModify && (\n \n \n Create Virtual Server\n \n )}\n
\n
\n\n {/* Search */}\n
\n \n setSearchQuery(e.target.value)}\n placeholder=\"Search virtual servers...\"\n className=\"w-full pl-10 pr-4 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-800 text-gray-900 dark:text-white\n focus:ring-2 focus:ring-teal-500 focus:border-transparent\"\n />\n
\n\n {/* Table */}\n {filteredServers.length === 0 ? (\n
\n \n \n \n

\n {searchQuery ? 'No matching virtual servers' : 'No virtual servers configured'}\n

\n

\n {searchQuery\n ? 'Try a different search term'\n : 'Create a virtual server to aggregate tools from multiple backends'}\n

\n {!searchQuery && canModify && (\n \n Create First Virtual Server\n \n )}\n
\n ) : (\n
\n \n \n \n \n \n \n \n \n \n \n \n \n {filteredServers.map((server) => (\n \n \n \n \n \n \n \n \n ))}\n \n
\n Name\n \n Path\n \n Tools\n \n Backends\n \n Status\n \n Actions\n
\n
\n \n {server.server_name}\n \n {server.description && (\n \n {server.description}\n \n )}\n
\n 		\n \n {server.path}\n \n \n {server.tool_count}\n \n
\n {server.backend_paths.slice(0, 2).map((bp) => (\n \n {bp}\n \n ))}\n {server.backend_paths.length > 2 && (\n \n +{server.backend_paths.length - 2}\n \n )}\n
\n 		\n \n {server.is_enabled ? 'Enabled' : 'Disabled'}\n \n \n
\n {canModify && (\n <>\n
\n \n handleEdit(server)}\n className=\"px-3 py-1 text-xs font-medium text-teal-700 dark:text-teal-300\n bg-teal-50 dark:bg-teal-900/20 rounded hover:bg-teal-100\n dark:hover:bg-teal-900/40 transition-colors\"\n >\n Edit\n \n setDeleteTarget(server)}\n className=\"px-3 py-1 text-xs font-medium text-red-700 dark:text-red-300\n bg-red-50 dark:bg-red-900/20 rounded hover:bg-red-100\n dark:hover:bg-red-900/40 transition-colors\"\n >\n Delete\n \n \n )}\n \n
\n
\n )}\n\n {/* Form modal */}\n {showForm && editingPath && editingServerLoading && (\n
\n
\n \n

Loading server data...

\n
\n
\n )}\n {showForm && (!editingPath || (editingPath && !editingServerLoading)) && (\n {\n setShowForm(false);\n setEditingPath(undefined);\n }}\n />\n )}\n\n {/* Delete confirmation modal */}\n {deleteTarget && (\n \n
\n

\n Delete Virtual Server\n

\n

\n This action is irreversible. The virtual server and all its tool\n mappings will be permanently removed.\n

\n

\n Type {deleteTarget.server_name} to confirm:\n

\n setTypedName(e.target.value)}\n placeholder={deleteTarget.server_name}\n disabled={isDeleting}\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white mb-4\"\n onKeyDown={(e) => {\n if (e.key === 'Escape') {\n setDeleteTarget(null);\n setTypedName('');\n }\n }}\n autoFocus\n />\n
\n {\n setDeleteTarget(null);\n setTypedName('');\n }}\n disabled={isDeleting}\n className=\"px-4 py-2 bg-gray-200 dark:bg-gray-700 text-gray-800 dark:text-gray-200\n rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600 disabled:opacity-50\"\n >\n Cancel\n \n \n {isDeleting && (\n \n )}\n Delete\n \n
\n
\n
\n )}\n
\n );\n};\n\nexport default VirtualServerList;\n" }, { "path": "frontend/src/components/__tests__/ConfigPanel.test.tsx", "content": "import React from 'react';\nimport { render, screen, fireEvent, waitFor } from '@testing-library/react';\nimport axios from 'axios';\nimport ConfigPanel from '../ConfigPanel';\n\n// Mock axios\njest.mock('axios');\nconst mockedAxios = axios as jest.Mocked;\n\n// Mock clipboard API\nObject.assign(navigator, {\n clipboard: { writeText: jest.fn().mockResolvedValue(undefined) },\n});\n\n/** Sample API response used across tests. */\nconst mockConfigResponse = {\n groups: [\n {\n id: 'deployment',\n title: 'Deployment Mode',\n order: 1,\n fields: [\n { key: 'deployment_mode', label: 'Deployment Mode', value: 'with-gateway', raw_value: 'with-gateway', is_masked: false, unit: null },\n { key: 'registry_mode', label: 'Registry Mode', value: 'full', raw_value: 'full', is_masked: false, unit: null },\n ],\n },\n {\n id: 'storage',\n title: 'Storage Backend',\n order: 2,\n fields: [\n { key: 'storage_backend', label: 'Storage Backend', value: 'mongodb', raw_value: 'mongodb', is_masked: false, unit: null },\n ],\n },\n {\n id: 'auth',\n title: 'Authentication',\n order: 3,\n fields: [\n { key: 'auth_enabled', label: 'Auth Enabled', value: 'true', raw_value: true, is_masked: false, unit: null },\n { key: 'auth_secret_key', label: 'Auth Secret Key', value: 'sk-t********', raw_value: null, is_masked: true, unit: null },\n ],\n },\n ],\n total_groups: 3,\n is_local_dev: false,\n};\n\ndescribe('ConfigPanel', () => {\n beforeEach(() => {\n jest.clearAllMocks();\n });\n\n test('renders groups from API response', async () => {\n mockedAxios.get.mockResolvedValueOnce({ data: mockConfigResponse });\n render();\n\n await waitFor(() => {\n expect(screen.getByText('System Configuration')).toBeInTheDocument();\n });\n // Group titles visible (may appear multiple times due to field labels matching)\n expect(screen.getAllByText(/Deployment Mode/).length).toBeGreaterThanOrEqual(1);\n expect(screen.getAllByText(/Storage Backend/).length).toBeGreaterThanOrEqual(1);\n expect(screen.getByText(/Authentication/)).toBeInTheDocument();\n });\n\n test('deployment and storage groups are expanded by default', async () => {\n mockedAxios.get.mockResolvedValueOnce({ data: mockConfigResponse });\n render();\n\n await waitFor(() => {\n expect(screen.getByText('System Configuration')).toBeInTheDocument();\n });\n\n // Fields from expanded groups should be visible\n expect(screen.getByText('with-gateway')).toBeInTheDocument();\n expect(screen.getByText('mongodb')).toBeInTheDocument();\n\n // Auth group is collapsed — its field labels should not be rendered\n expect(screen.queryByText('Auth Enabled')).not.toBeInTheDocument();\n });\n\n test('search filtering hides non-matching fields', async () => {\n mockedAxios.get.mockResolvedValueOnce({ data: mockConfigResponse });\n render();\n\n await waitFor(() => {\n expect(screen.getByText('System Configuration')).toBeInTheDocument();\n });\n\n const searchInput = screen.getByPlaceholderText('Search configuration...');\n fireEvent.change(searchInput, { target: { value: 'mongodb' } });\n\n // Storage group should remain (has matching field value)\n expect(screen.getAllByText(/Storage Backend/).length).toBeGreaterThanOrEqual(1);\n\n // Deployment group fields should be gone (no match for \"mongodb\")\n expect(screen.queryByText('Registry Mode')).not.toBeInTheDocument();\n });\n\n test('shows \"no results\" message for non-matching search', async () => {\n mockedAxios.get.mockResolvedValueOnce({ data: mockConfigResponse });\n render();\n\n await waitFor(() => {\n expect(screen.getByText('System Configuration')).toBeInTheDocument();\n });\n\n const searchInput = screen.getByPlaceholderText('Search configuration...');\n fireEvent.change(searchInput, { target: { value: 'zzz_nonexistent_zzz' } });\n\n expect(screen.getByTestId('no-results')).toBeInTheDocument();\n });\n\n test('shows skeleton loading state during fetch', () => {\n mockedAxios.get.mockReturnValue(new Promise(() => {}));\n render();\n\n expect(screen.getByTestId('config-skeleton')).toBeInTheDocument();\n });\n\n test('shows error state on API failure', async () => {\n mockedAxios.get.mockRejectedValueOnce({\n response: { data: { detail: 'Admin access required' } },\n });\n render();\n\n await waitFor(() => {\n expect(screen.getByTestId('config-error')).toBeInTheDocument();\n });\n expect(screen.getByText('Admin access required')).toBeInTheDocument();\n });\n\n test('shows is_local_dev badge when true', async () => {\n mockedAxios.get.mockResolvedValueOnce({\n data: { ...mockConfigResponse, is_local_dev: true },\n });\n render();\n\n await waitFor(() => {\n expect(screen.getByTestId('local-dev-badge')).toBeInTheDocument();\n });\n expect(screen.getByText('Local Development Mode')).toBeInTheDocument();\n });\n\n test('ARIA attributes present on group headers', async () => {\n mockedAxios.get.mockResolvedValueOnce({ data: mockConfigResponse });\n render();\n\n await waitFor(() => {\n expect(screen.getByText('System Configuration')).toBeInTheDocument();\n });\n\n // Find the deployment group header button (expanded by default)\n const buttons = screen.getAllByRole('button');\n const deploymentBtn = buttons.find(\n (btn) => btn.getAttribute('aria-controls') === 'config-group-deployment'\n );\n expect(deploymentBtn).toBeDefined();\n expect(deploymentBtn).toHaveAttribute('aria-expanded', 'true');\n\n // Auth group header (collapsed by default)\n const authBtn = buttons.find(\n (btn) => btn.getAttribute('aria-controls') === 'config-group-auth'\n );\n expect(authBtn).toBeDefined();\n expect(authBtn).toHaveAttribute('aria-expanded', 'false');\n });\n});\n" }, { "path": "frontend/src/components/__tests__/DiscoverTab.test.tsx", "content": "import React from 'react';\nimport { render, screen, fireEvent } from '@testing-library/react';\nimport DiscoverTab from '../DiscoverTab';\n\n\n// Mock useSemanticSearch hook\nconst mockSemanticSearch = {\n results: null,\n loading: false,\n error: null,\n debouncedQuery: '',\n};\njest.mock('../../hooks/useSemanticSearch', () => ({\n useSemanticSearch: () => mockSemanticSearch,\n}));\n\n// Mock DiscoverListRow to simplify testing\njest.mock('../DiscoverListRow', () => {\n const MockListRow = (props) => (\n
\n {props.item.name}\n
\n );\n MockListRow.displayName = 'DiscoverListRow';\n return MockListRow;\n});\n\njest.mock('../SemanticSearchResults', () => {\n const MockSearchResults = (props) => (\n
\n Search results for: {props.query}\n
\n );\n MockSearchResults.displayName = 'SemanticSearchResults';\n return MockSearchResults;\n});\n\n\n// Test data factories\nconst makeServer = (overrides = {}) => ({\n name: 'Test Server',\n path: '/test-server/',\n enabled: true,\n rating_details: [],\n ...overrides,\n});\n\n\nconst makeSkill = (overrides = {}) => ({\n name: 'Test Skill',\n path: '/test-skill/',\n skill_md_url: '',\n visibility: 'public',\n is_enabled: true,\n num_stars: 0,\n ...overrides,\n});\n\n\nconst defaultProps = {\n servers: [],\n agents: [],\n skills: [],\n virtualServers: [],\n externalServers: [],\n externalAgents: [],\n loading: false,\n onServerToggle: jest.fn(),\n onAgentToggle: jest.fn(),\n onSkillToggle: jest.fn(),\n onVirtualServerToggle: jest.fn(),\n onShowToast: jest.fn(),\n authToken: null,\n};\n\n\ndescribe('DiscoverTab', () => {\n beforeEach(() => {\n jest.clearAllMocks();\n mockSemanticSearch.results = null;\n mockSemanticSearch.loading = false;\n mockSemanticSearch.error = null;\n });\n\n test('renders search bar and title at the top', () => {\n render();\n expect(\n screen.getByPlaceholderText(/search servers, agents, skills/i)\n ).toBeInTheDocument();\n expect(\n screen.getByText('Discover MCP Servers, Agents & Skills')\n ).toBeInTheDocument();\n });\n\n test('title stays visible during keyword search', () => {\n render();\n\n const input = screen.getByPlaceholderText(/search servers/i);\n fireEvent.change(input, { target: { value: 'test' } });\n\n expect(\n screen.getByText('Discover MCP Servers, Agents & Skills')\n ).toBeInTheDocument();\n });\n\n test('shows loading state', () => {\n render();\n expect(screen.getByText(/loading featured items/i)).toBeInTheDocument();\n });\n\n test('shows empty state when no items registered', () => {\n render();\n expect(\n screen.getByText(/no items registered yet/i)\n ).toBeInTheDocument();\n });\n\n test('shows \"no items matching\" when keyword filter has no results', () => {\n render(\n \n );\n\n const input = screen.getByPlaceholderText(/search servers/i);\n fireEvent.change(input, { target: { value: 'zzzznonexistent' } });\n\n expect(screen.getByText(/no items matching/i)).toBeInTheDocument();\n });\n\n test('renders section headers for servers, agents, and skills', () => {\n render(\n \n );\n\n expect(screen.getByText('MCP Servers')).toBeInTheDocument();\n expect(screen.getByText('Agents')).toBeInTheDocument();\n expect(screen.getByText('Skills')).toBeInTheDocument();\n });\n\n test('renders list rows for each item type', () => {\n render(\n \n );\n\n expect(screen.getByTestId('list-row-server-/airegistry-tools/')).toBeInTheDocument();\n expect(screen.getByTestId('list-row-server-/cloudflare-docs/')).toBeInTheDocument();\n expect(screen.getByTestId('list-row-agent-/test-agent/')).toBeInTheDocument();\n expect(screen.getByTestId('list-row-skill-/code-review/')).toBeInTheDocument();\n });\n\n test('sorts servers by rating descending, alphabetical tiebreaker', () => {\n const servers = [\n makeServer({ name: 'AI Registry tools', path: '/airegistry-tools/' }),\n makeServer({\n name: 'Beta Server',\n path: '/beta/',\n rating_details: [{ user: 'u1', rating: 3 }],\n }),\n makeServer({\n name: 'Alpha Server',\n path: '/alpha/',\n rating_details: [{ user: 'u1', rating: 5 }],\n }),\n makeServer({\n name: 'Gamma Server',\n path: '/gamma/',\n rating_details: [{ user: 'u1', rating: 5 }],\n }),\n ];\n\n render();\n\n expect(screen.getByTestId('list-row-server-/airegistry-tools/')).toBeInTheDocument();\n expect(screen.getByTestId('list-row-server-/alpha/')).toBeInTheDocument();\n expect(screen.getByTestId('list-row-server-/gamma/')).toBeInTheDocument();\n expect(screen.getByTestId('list-row-server-/beta/')).toBeInTheDocument();\n });\n\n test('excludes disabled items from featured', () => {\n const servers = [\n makeServer({ name: 'AI Registry tools', path: '/airegistry-tools/' }),\n makeServer({\n name: 'Disabled Server',\n path: '/disabled/',\n enabled: false,\n rating_details: [{ user: 'u1', rating: 5 }],\n }),\n ];\n\n render();\n\n expect(screen.getByText('AI Registry tools')).toBeInTheDocument();\n expect(screen.queryByText('Disabled Server')).not.toBeInTheDocument();\n });\n\n test('keyword search filters items instantly as you type', () => {\n render(\n \n );\n\n expect(screen.getByText('AI Registry tools')).toBeInTheDocument();\n expect(screen.getByText('Cloudflare Docs')).toBeInTheDocument();\n expect(screen.getByText('Test Agent')).toBeInTheDocument();\n\n const input = screen.getByPlaceholderText(/search servers/i);\n fireEvent.change(input, { target: { value: 'cloud' } });\n\n expect(screen.queryByText('AI Registry tools')).not.toBeInTheDocument();\n expect(screen.getByText('Cloudflare Docs')).toBeInTheDocument();\n expect(screen.queryByText('Test Agent')).not.toBeInTheDocument();\n });\n\n test('keyword search matches tags', () => {\n render(\n \n );\n\n const input = screen.getByPlaceholderText(/search servers/i);\n fireEvent.change(input, { target: { value: 'documentation' } });\n\n expect(screen.getByText('Server A')).toBeInTheDocument();\n expect(screen.queryByText('Server B')).not.toBeInTheDocument();\n });\n\n test('Enter key triggers semantic search', () => {\n render();\n\n const input = screen.getByPlaceholderText(/search servers/i);\n fireEvent.change(input, { target: { value: 'find something' } });\n fireEvent.keyDown(input, { key: 'Enter' });\n\n expect(screen.getByTestId('semantic-search-results')).toBeInTheDocument();\n expect(\n screen.getByText(/search results for: find something/i)\n ).toBeInTheDocument();\n });\n\n test('clearing search returns to full listing', () => {\n render(\n \n );\n\n const input = screen.getByPlaceholderText(/search servers/i);\n\n fireEvent.change(input, { target: { value: 'test query' } });\n fireEvent.keyDown(input, { key: 'Enter' });\n expect(screen.getByTestId('semantic-search-results')).toBeInTheDocument();\n\n const clearButton = screen.getByRole('button');\n fireEvent.click(clearButton);\n\n expect(screen.queryByTestId('semantic-search-results')).not.toBeInTheDocument();\n expect(screen.getByText('AI Registry tools')).toBeInTheDocument();\n });\n\n test('backspacing exits semantic mode and shows keyword-filtered results', () => {\n render(\n \n );\n\n const input = screen.getByPlaceholderText(/search servers/i);\n\n fireEvent.change(input, { target: { value: 'cloud' } });\n fireEvent.keyDown(input, { key: 'Enter' });\n expect(screen.getByTestId('semantic-search-results')).toBeInTheDocument();\n\n fireEvent.change(input, { target: { value: 'clou' } });\n expect(screen.queryByTestId('semantic-search-results')).not.toBeInTheDocument();\n\n expect(screen.queryByText('AI Registry tools')).not.toBeInTheDocument();\n expect(screen.getByText('Cloudflare Docs')).toBeInTheDocument();\n });\n\n test('does not trigger semantic search for queries shorter than 2 characters', () => {\n render();\n\n const input = screen.getByPlaceholderText(/search servers/i);\n fireEvent.change(input, { target: { value: 'a' } });\n fireEvent.keyDown(input, { key: 'Enter' });\n\n expect(screen.queryByTestId('semantic-search-results')).not.toBeInTheDocument();\n });\n\n test('graceful degradation when no agents exist', () => {\n render(\n \n );\n\n expect(screen.getByText('AI Registry tools')).toBeInTheDocument();\n expect(screen.getByText('My Skill')).toBeInTheDocument();\n expect(screen.queryByText('Agents')).not.toBeInTheDocument();\n });\n});\n" }, { "path": "frontend/src/components/__tests__/ServerConfigModal.test.tsx", "content": "import React from 'react';\nimport { render, screen } from '@testing-library/react';\nimport ServerConfigModal from '../ServerConfigModal';\nimport type { Server } from '../ServerCard';\n\n// Mock the useRegistryConfig hook\nconst mockUseRegistryConfig = jest.fn();\njest.mock('../../hooks/useRegistryConfig', () => ({\n useRegistryConfig: () => mockUseRegistryConfig(),\n}));\n\n// Mock clipboard API\nObject.assign(navigator, {\n clipboard: { writeText: jest.fn().mockResolvedValue(undefined) },\n});\n\nconst baseServer: Server = {\n name: 'Test Server',\n path: '/test-server',\n enabled: true,\n proxy_pass_url: 'http://internal-host:8080/mcp',\n};\n\nfunction renderModal(serverOverrides: Partial = {}, configOverride?: ReturnType) {\n const server = { ...baseServer, ...serverOverrides };\n return render(\n \n );\n}\n\nfunction getDisplayedConfig(): any {\n // The config JSON is rendered inside a 
 tag\n  const preElement = screen.getByText(/{/, { selector: 'pre' });\n  return JSON.parse(preElement.textContent || '');\n}\n\ndescribe('ServerConfigModal URL generation', () => {\n  beforeEach(() => {\n    jest.clearAllMocks();\n    // Default: jsdom sets window.location.origin to http://localhost\n  });\n\n  test('should use gateway URL in with-gateway mode', () => {\n    mockUseRegistryConfig.mockReturnValue({\n      config: {\n        deployment_mode: 'with-gateway',\n        registry_mode: 'full',\n        nginx_updates_enabled: true,\n        features: { mcp_servers: true, agents: true, skills: true, federation: true, gateway_proxy: true },\n      },\n      loading: false,\n      error: null,\n    });\n\n    renderModal();\n    const config = getDisplayedConfig();\n\n    // VS Code is the default IDE — config uses \"servers\" key\n    const serverConfig = config.servers['test-server'];\n    expect(serverConfig.url).toBe('http://localhost/test-server/mcp');\n    // Gateway mode includes auth headers\n    expect(serverConfig.headers).toBeDefined();\n    expect(serverConfig.headers.Authorization).toContain('Bearer');\n  });\n\n  test('should use proxy_pass_url in registry-only mode', () => {\n    mockUseRegistryConfig.mockReturnValue({\n      config: {\n        deployment_mode: 'registry-only',\n        registry_mode: 'full',\n        nginx_updates_enabled: false,\n        features: { mcp_servers: true, agents: true, skills: true, federation: true, gateway_proxy: false },\n      },\n      loading: false,\n      error: null,\n    });\n\n    renderModal({ proxy_pass_url: 'http://internal-host:8080/mcp' });\n    const config = getDisplayedConfig();\n\n    const serverConfig = config.servers['test-server'];\n    expect(serverConfig.url).toBe('http://internal-host:8080/mcp');\n    // Registry-only mode should NOT include auth headers\n    expect(serverConfig.headers).toBeUndefined();\n  });\n\n  test('should always use mcp_endpoint when provided', () => {\n    // Test with with-gateway mode\n    mockUseRegistryConfig.mockReturnValue({\n      config: {\n        deployment_mode: 'with-gateway',\n        registry_mode: 'full',\n        nginx_updates_enabled: true,\n        features: { mcp_servers: true, agents: true, skills: true, federation: true, gateway_proxy: true },\n      },\n      loading: false,\n      error: null,\n    });\n\n    const { unmount } = renderModal({\n      mcp_endpoint: 'https://custom-endpoint.example.com/mcp',\n      proxy_pass_url: 'http://internal-host:8080/mcp',\n    });\n    let config = getDisplayedConfig();\n    let serverConfig = config.servers['test-server'];\n    expect(serverConfig.url).toBe('https://custom-endpoint.example.com/mcp');\n\n    unmount();\n\n    // Test with registry-only mode — mcp_endpoint still takes precedence\n    mockUseRegistryConfig.mockReturnValue({\n      config: {\n        deployment_mode: 'registry-only',\n        registry_mode: 'full',\n        nginx_updates_enabled: false,\n        features: { mcp_servers: true, agents: true, skills: true, federation: true, gateway_proxy: false },\n      },\n      loading: false,\n      error: null,\n    });\n\n    renderModal({\n      mcp_endpoint: 'https://custom-endpoint.example.com/mcp',\n      proxy_pass_url: 'http://internal-host:8080/mcp',\n    });\n    config = getDisplayedConfig();\n    serverConfig = config.servers['test-server'];\n    expect(serverConfig.url).toBe('https://custom-endpoint.example.com/mcp');\n  });\n});\n"
  },
  {
    "path": "frontend/src/components/__tests__/SettingsPageConfigIntegration.test.tsx",
    "content": "import React from 'react';\nimport { render, screen } from '@testing-library/react';\nimport { MemoryRouter } from 'react-router-dom';\nimport SettingsPage from '../../pages/SettingsPage';\n\n// Mock auth context\njest.mock('../../contexts/AuthContext', () => ({\n  useAuth: jest.fn(),\n}));\nimport { useAuth } from '../../contexts/AuthContext';\n\n// Mock child components to avoid deep rendering\njest.mock('../../pages/AuditLogsPage', () => () => 
AuditLogsPage
);\njest.mock('../FederationPeers', () => () => 
FederationPeers
);\njest.mock('../FederationPeerForm', () => () => 
FederationPeerForm
);\njest.mock('../ConfigPanel', () => () => 
ConfigPanel
);\n\ndescribe('SettingsPage - System Config category', () => {\n  test('shows System Config category for admin users', () => {\n    (useAuth as jest.Mock).mockReturnValue({\n      user: { username: 'admin', is_admin: true },\n      loading: false,\n    });\n\n    render(\n      \n        \n      \n    );\n\n    expect(screen.getByText('System Config')).toBeInTheDocument();\n  });\n\n  test('hides System Config category for non-admin users', () => {\n    (useAuth as jest.Mock).mockReturnValue({\n      user: { username: 'viewer', is_admin: false },\n      loading: false,\n    });\n\n    render(\n      \n        \n      \n    );\n\n    expect(screen.queryByText('System Config')).not.toBeInTheDocument();\n  });\n});\n"
  },
  {
    "path": "frontend/src/contexts/AuthContext.tsx",
    "content": "import React, { createContext, useContext, useState, useEffect, ReactNode } from 'react';\nimport axios from 'axios';\n\n// Get base URL from  tag for path-based routing (e.g., /registry)\nconst getBaseURL = () => {\n  const baseTag = document.querySelector('base');\n  if (baseTag && baseTag.href) {\n    const url = new URL(baseTag.href);\n    return url.pathname.replace(/\\/$/, '');\n  }\n  return '';\n};\n\n// Configure axios to include credentials (cookies) with all requests\naxios.defaults.withCredentials = true;\n\n// UIPermissions keys match exactly what scopes.yml defines.\n// These control server/agent access\ninterface UIPermissions {\n  list_service?: string[];\n  register_service?: string[];\n  health_check_service?: string[];\n  toggle_service?: string[];\n  modify_service?: string[];\n  list_agents?: string[];\n  get_agent?: string[];\n  publish_agent?: string[];\n  modify_agent?: string[];\n  delete_agent?: string[];\n  [key: string]: string[] | undefined;\n}\n\ninterface User {\n  username: string;\n  email?: string;\n  scopes?: string[];\n  groups?: string[];\n  auth_method?: string;\n  provider?: string;\n  can_modify_servers?: boolean;\n  is_admin?: boolean;\n  ui_permissions?: UIPermissions;\n}\n\ninterface AuthContextType {\n  user: User | null;\n  logout: () => Promise;\n  loading: boolean;\n}\n\nconst AuthContext = createContext(undefined);\n\nexport const useAuth = () => {\n  const context = useContext(AuthContext);\n  if (context === undefined) {\n    throw new Error('useAuth must be used within an AuthProvider');\n  }\n  return context;\n};\n\ninterface AuthProviderProps {\n  children: ReactNode;\n}\n\nexport const AuthProvider: React.FC = ({ children }) => {\n  const [user, setUser] = useState(null);\n  const [loading, setLoading] = useState(true);\n  const [csrfToken, setCsrfToken] = useState(null);\n\n  useEffect(() => {\n    // Set axios baseURL from  tag when component mounts\n    axios.defaults.baseURL = getBaseURL();\n\n    // Setup axios interceptor to include CSRF token in requests\n    const interceptor = axios.interceptors.request.use((config) => {\n      if (csrfToken && config.method && ['post', 'put', 'delete', 'patch'].includes(config.method.toLowerCase())) {\n        config.headers['X-CSRF-Token'] = csrfToken;\n      }\n      return config;\n    });\n\n    checkAuth();\n\n    // Cleanup interceptor on unmount\n    return () => {\n      axios.interceptors.request.eject(interceptor);\n    };\n  }, [csrfToken]);\n\n  const checkAuth = async () => {\n    try {\n      const response = await axios.get('/api/auth/me');\n      const userData = response.data;\n      setUser({\n        username: userData.username,\n        email: userData.email,\n        scopes: userData.scopes || [],\n        groups: userData.groups || [],\n        auth_method: userData.auth_method || 'oauth2',\n        provider: userData.provider,\n        can_modify_servers: userData.can_modify_servers || false,\n        is_admin: userData.is_admin || false,\n        ui_permissions: userData.ui_permissions || {},\n      });\n\n      // Fetch CSRF token after successful authentication\n      try {\n        const csrfResponse = await axios.get('/api/auth/csrf-token');\n        if (csrfResponse.data.csrf_token) {\n          setCsrfToken(csrfResponse.data.csrf_token);\n        }\n      } catch (csrfError) {\n        console.warn('Failed to fetch CSRF token:', csrfError);\n      }\n    } catch (error) {\n      // User not authenticated\n      setUser(null);\n      setCsrfToken(null);\n    } finally {\n      setLoading(false);\n    }\n  };\n\n  const logout = async () => {\n    // Clear user state and CSRF token immediately for responsive UI\n    setUser(null);\n    setCsrfToken(null);\n    // Perform full-page redirect to logout endpoint\n    // This allows the browser to follow the redirect chain: Registry → Auth-server → IdP → Registry\n    // Using window.location.href avoids CORS issues with cross-origin redirects\n    window.location.href = `${getBaseURL()}/api/auth/logout`;\n  };\n\n  const value = {\n    user,\n    logout,\n    loading,\n  };\n\n  return {children};\n}; "
  },
  {
    "path": "frontend/src/contexts/ThemeContext.tsx",
    "content": "import React, { createContext, useContext, useState, useEffect, ReactNode } from 'react';\n\ntype Theme = 'light' | 'dark';\n\ninterface ThemeContextType {\n  theme: Theme;\n  toggleTheme: () => void;\n}\n\nconst ThemeContext = createContext(undefined);\n\nexport const useTheme = () => {\n  const context = useContext(ThemeContext);\n  if (context === undefined) {\n    throw new Error('useTheme must be used within a ThemeProvider');\n  }\n  return context;\n};\n\ninterface ThemeProviderProps {\n  children: ReactNode;\n}\n\nexport const ThemeProvider: React.FC = ({ children }) => {\n  const [theme, setTheme] = useState('dark');\n\n  useEffect(() => {\n    // Check for saved theme in localStorage or default to 'dark'\n    const savedTheme = localStorage.getItem('theme') as Theme;\n    if (savedTheme) {\n      setTheme(savedTheme);\n    } else {\n      setTheme('dark');\n    }\n  }, []);\n\n  useEffect(() => {\n    // Apply theme to document\n    const root = window.document.documentElement;\n    if (theme === 'dark') {\n      root.classList.add('dark');\n    } else {\n      root.classList.remove('dark');\n    }\n    localStorage.setItem('theme', theme);\n  }, [theme]);\n\n  const toggleTheme = () => {\n    setTheme(prevTheme => prevTheme === 'light' ? 'dark' : 'light');\n  };\n\n  const value = {\n    theme,\n    toggleTheme,\n  };\n\n  return {children};\n}; "
  },
  {
    "path": "frontend/src/hooks/useAgentList.ts",
    "content": "/**\n * Hook for fetching the list of agents with descriptions.\n *\n * Provides agent names and descriptions for scope configuration\n * in IAM Groups form using searchable select components.\n */\n\nimport { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\n\n\nexport interface AgentInfo {\n  name: string;\n  path: string;\n  description: string;\n}\n\ninterface AgentListResponse {\n  agents: Array<{\n    name: string;\n    path: string;\n    description?: string;\n    [key: string]: unknown;\n  }>;\n}\n\ninterface UseAgentListReturn {\n  agents: AgentInfo[];\n  isLoading: boolean;\n  error: string | null;\n  refetch: () => Promise;\n}\n\n\nexport function useAgentList(): UseAgentListReturn {\n  const [agents, setAgents] = useState([]);\n  const [isLoading, setIsLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchAgents = useCallback(async () => {\n    setIsLoading(true);\n    setError(null);\n\n    try {\n      const response = await axios.get('/api/agents');\n      const data = response.data;\n\n      const agentList: AgentInfo[] = (data.agents || []).map((agent) => ({\n        name: agent.name,\n        path: agent.path,\n        description: agent.description || '',\n      }));\n\n      // Sort by name\n      agentList.sort((a, b) => a.name.localeCompare(b.name));\n\n      setAgents(agentList);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : 'Failed to fetch agents';\n      setError(message);\n      setAgents([]);\n    } finally {\n      setIsLoading(false);\n    }\n  }, []);\n\n  useEffect(() => {\n    fetchAgents();\n  }, [fetchAgents]);\n\n  return {\n    agents,\n    isLoading,\n    error,\n    refetch: fetchAgents,\n  };\n}\n"
  },
  {
    "path": "frontend/src/hooks/useEscapeKey.ts",
    "content": "import { useEffect } from 'react';\n\n/**\n * Calls the provided callback when the Escape key is pressed,\n * but only while `isActive` is true.\n */\nconst useEscapeKey = (onEscape: () => void, isActive: boolean) => {\n  useEffect(() => {\n    if (!isActive) return;\n\n    const handleKeyDown = (e: KeyboardEvent) => {\n      if (e.key === 'Escape') {\n        onEscape();\n      }\n    };\n\n    document.addEventListener('keydown', handleKeyDown);\n    return () => document.removeEventListener('keydown', handleKeyDown);\n  }, [onEscape, isActive]);\n};\n\nexport default useEscapeKey;\n"
  },
  {
    "path": "frontend/src/hooks/useFederationPeers.ts",
    "content": "import { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\n\n\n/**\n * Peer registry configuration from the backend API.\n */\nexport interface PeerRegistry {\n  peer_id: string;\n  name: string;\n  endpoint: string;\n  enabled: boolean;\n  sync_mode: 'all' | 'whitelist' | 'tag_filter';\n  whitelist_servers: string[];\n  whitelist_agents: string[];\n  tag_filters: string[];\n  sync_interval_minutes: number;\n  federation_token?: string | null;\n  expected_client_id?: string | null;\n  expected_issuer?: string | null;\n  created_at?: string | null;\n  updated_at?: string | null;\n}\n\n\n/**\n * Peer sync status from the backend API.\n */\nexport interface PeerSyncStatus {\n  peer_id: string;\n  is_healthy: boolean;\n  last_health_check?: string | null;\n  last_successful_sync?: string | null;\n  last_sync_attempt?: string | null;\n  current_generation: number;\n  total_servers_synced: number;\n  total_agents_synced: number;\n  sync_in_progress: boolean;\n  consecutive_failures: number;\n}\n\n\n/**\n * Sync result from triggering a sync operation.\n */\nexport interface SyncResult {\n  success: boolean;\n  peer_id: string;\n  servers_synced: number;\n  agents_synced: number;\n  servers_orphaned: number;\n  agents_orphaned: number;\n  error_message?: string | null;\n  duration_seconds: number;\n  new_generation: number;\n}\n\n\n/**\n * Form data for creating or updating a peer.\n */\nexport interface PeerFormData {\n  peer_id: string;\n  name: string;\n  endpoint: string;\n  enabled: boolean;\n  sync_mode: 'all' | 'whitelist' | 'tag_filter';\n  whitelist_servers: string[];\n  whitelist_agents: string[];\n  tag_filters: string[];\n  sync_interval_minutes: number;\n  federation_token?: string;\n}\n\n\n/**\n * Peer with sync status combined for list display.\n */\nexport interface PeerWithStatus extends PeerRegistry {\n  syncStatus?: PeerSyncStatus | null;\n}\n\n\n/**\n * Return type for the useFederationPeers hook.\n */\ninterface UseFederationPeersReturn {\n  peers: PeerWithStatus[];\n  isLoading: boolean;\n  error: string | null;\n  refetch: () => Promise;\n  hasPeers: boolean;\n}\n\n\n/**\n * Fetch sync status for a single peer.\n * Returns null on error to avoid failing the whole list.\n */\nasync function fetchPeerStatus(peerId: string): Promise {\n  try {\n    const response = await axios.get(`/api/peers/${peerId}/status`);\n    return response.data;\n  } catch {\n    return null;\n  }\n}\n\n\n/**\n * Hook for fetching and managing federation peers.\n *\n * Provides the list of configured peer registries with sync status and loading/error states.\n */\nexport function useFederationPeers(): UseFederationPeersReturn {\n  const [peers, setPeers] = useState([]);\n  const [isLoading, setIsLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchPeers = useCallback(async () => {\n    try {\n      setIsLoading(true);\n      setError(null);\n\n      const response = await axios.get('/api/peers');\n      const peerList: PeerRegistry[] = response.data || [];\n\n      // Fetch sync status for all peers in parallel\n      const statusPromises = peerList.map((peer) => fetchPeerStatus(peer.peer_id));\n      const statuses = await Promise.all(statusPromises);\n\n      // Combine peers with their sync status\n      const peersWithStatus: PeerWithStatus[] = peerList.map((peer, index) => ({\n        ...peer,\n        syncStatus: statuses[index],\n      }));\n\n      setPeers(peersWithStatus);\n    } catch (err: any) {\n      console.error('Failed to fetch federation peers:', err);\n      setError(\n        err.response?.data?.detail ||\n        err.message ||\n        'Failed to fetch peers'\n      );\n      setPeers([]);\n    } finally {\n      setIsLoading(false);\n    }\n  }, []);\n\n  useEffect(() => {\n    fetchPeers();\n  }, [fetchPeers]);\n\n  return {\n    peers,\n    isLoading,\n    error,\n    refetch: fetchPeers,\n    hasPeers: peers.length > 0,\n  };\n}\n\n\n/**\n * Return type for the useFederationPeer hook.\n */\ninterface UseFederationPeerReturn {\n  peer: PeerRegistry | null;\n  status: PeerSyncStatus | null;\n  isLoading: boolean;\n  error: string | null;\n  refetch: () => Promise;\n}\n\n\n/**\n * Hook for fetching a single federation peer by ID.\n *\n * @param peerId - The peer ID to fetch, or undefined to skip fetching\n */\nexport function useFederationPeer(peerId: string | undefined): UseFederationPeerReturn {\n  const [peer, setPeer] = useState(null);\n  const [status, setStatus] = useState(null);\n  const [isLoading, setIsLoading] = useState(false);\n  const [error, setError] = useState(null);\n\n  const fetchPeer = useCallback(async () => {\n    if (!peerId) {\n      setPeer(null);\n      setStatus(null);\n      return;\n    }\n\n    try {\n      setIsLoading(true);\n      setError(null);\n\n      // Fetch peer config and status in parallel\n      const [peerResponse, statusResponse] = await Promise.all([\n        axios.get(`/api/peers/${peerId}`),\n        axios.get(`/api/peers/${peerId}/status`).catch(() => ({ data: null })),\n      ]);\n\n      setPeer(peerResponse.data);\n      setStatus(statusResponse.data);\n    } catch (err: any) {\n      console.error(`Failed to fetch peer ${peerId}:`, err);\n      setError(\n        err.response?.data?.detail ||\n        err.message ||\n        'Failed to fetch peer'\n      );\n      setPeer(null);\n      setStatus(null);\n    } finally {\n      setIsLoading(false);\n    }\n  }, [peerId]);\n\n  useEffect(() => {\n    fetchPeer();\n  }, [fetchPeer]);\n\n  return {\n    peer,\n    status,\n    isLoading,\n    error,\n    refetch: fetchPeer,\n  };\n}\n\n\n/**\n * API functions for peer management operations.\n */\nexport async function createPeer(data: PeerFormData): Promise {\n  const response = await axios.post('/api/peers', data);\n  return response.data;\n}\n\n\nexport async function updatePeer(\n  peerId: string,\n  updates: Partial\n): Promise {\n  const response = await axios.put(`/api/peers/${peerId}`, updates);\n  return response.data;\n}\n\n\nexport async function deletePeer(peerId: string): Promise {\n  await axios.delete(`/api/peers/${peerId}`);\n}\n\n\nexport async function syncPeer(peerId: string): Promise {\n  const response = await axios.post(`/api/peers/${peerId}/sync`);\n  return response.data;\n}\n\n\nexport async function enablePeer(peerId: string): Promise {\n  const response = await axios.post(`/api/peers/${peerId}/enable`);\n  return response.data;\n}\n\n\nexport async function disablePeer(peerId: string): Promise {\n  const response = await axios.post(`/api/peers/${peerId}/disable`);\n  return response.data;\n}\n"
  },
  {
    "path": "frontend/src/hooks/useIAM.ts",
    "content": "import { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\n\n// ─── Types ──────────────────────────────────────────────────────\n\nexport interface IAMGroup {\n  name: string;\n  description?: string;\n  path?: string;\n  members_count?: number;\n}\n\nexport interface IAMUser {\n  username: string;\n  email?: string;\n  first_name?: string;\n  last_name?: string;\n  groups?: string[];\n  enabled?: boolean;\n  is_admin?: boolean;\n  account_type?: string;\n  serviceAccountsEnabled?: boolean;\n}\n\nexport interface M2MCredentials {\n  client_id: string;\n  client_secret: string;\n  name: string;\n}\n\nexport interface CreateHumanUserPayload {\n  username: string;\n  email: string;\n  first_name: string;\n  last_name: string;\n  password?: string;\n  groups?: string[];\n}\n\nexport interface CreateM2MPayload {\n  name: string;\n  description?: string;\n  groups?: string[];\n}\n\nexport interface CreateGroupPayload {\n  name: string;\n  description?: string;\n  // scope_config is included for future backend support.\n  // Currently the backend accepts but does not process it.\n  scope_config?: Record;\n}\n\n// ─── Hook: useIAMGroups ─────────────────────────────────────────\n\nexport function useIAMGroups() {\n  const [groups, setGroups] = useState([]);\n  const [isLoading, setIsLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchGroups = useCallback(async () => {\n    setIsLoading(true);\n    setError(null);\n    try {\n      const res = await axios.get('/api/management/iam/groups');\n      setGroups(res.data.groups || res.data || []);\n    } catch (err: any) {\n      setError(err.response?.data?.detail || 'Failed to load groups');\n    } finally {\n      setIsLoading(false);\n    }\n  }, []);\n\n  useEffect(() => { fetchGroups(); }, [fetchGroups]);\n\n  return { groups, isLoading, error, refetch: fetchGroups };\n}\n\nexport async function createGroup(payload: CreateGroupPayload): Promise {\n  const res = await axios.post('/api/management/iam/groups', payload);\n  return res.data;\n}\n\nexport async function deleteGroup(name: string): Promise {\n  await axios.delete(`/api/management/iam/groups/${encodeURIComponent(name)}`);\n}\n\n// ─── Group Detail Types & Functions ────────────────────────────\n\nexport interface GroupDetail {\n  id: string;\n  name: string;\n  path?: string;\n  description?: string;\n  server_access?: Array<{server: string; methods: string[]; tools?: string[]}>;\n  group_mappings?: string[];\n  ui_permissions?: Record;\n  agent_access?: string[];\n}\n\nexport interface UpdateGroupPayload {\n  description?: string;\n  scope_config?: {\n    server_access?: Array<{server: string; methods: string[]; tools?: string[]}>;\n    ui_permissions?: Record;\n    agent_access?: string[];\n  };\n}\n\nexport async function getGroup(groupName: string): Promise {\n  const res = await axios.get(`/api/management/iam/groups/${encodeURIComponent(groupName)}`);\n  return res.data;\n}\n\nexport async function updateGroup(\n  groupName: string,\n  payload: UpdateGroupPayload\n): Promise {\n  const res = await axios.patch(\n    `/api/management/iam/groups/${encodeURIComponent(groupName)}`,\n    payload\n  );\n  return res.data;\n}\n\n// ─── Hook: useIAMUsers ──────────────────────────────────────────\n\nexport function useIAMUsers(search?: string) {\n  const [users, setUsers] = useState([]);\n  const [isLoading, setIsLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchUsers = useCallback(async () => {\n    setIsLoading(true);\n    setError(null);\n    try {\n      const params: Record = { limit: 500 };\n      if (search) params.search = search;\n      const res = await axios.get('/api/management/iam/users', { params });\n      setUsers(res.data.users || res.data || []);\n    } catch (err: any) {\n      setError(err.response?.data?.detail || 'Failed to load users');\n    } finally {\n      setIsLoading(false);\n    }\n  }, [search]);\n\n  useEffect(() => { fetchUsers(); }, [fetchUsers]);\n\n  return { users, isLoading, error, refetch: fetchUsers };\n}\n\nexport async function createHumanUser(payload: CreateHumanUserPayload): Promise {\n  const res = await axios.post('/api/management/iam/users/human', payload);\n  return res.data;\n}\n\nexport async function createM2MAccount(payload: CreateM2MPayload): Promise {\n  const res = await axios.post('/api/management/iam/users/m2m', payload);\n  return res.data;\n}\n\nexport async function deleteUser(username: string): Promise {\n  await axios.delete(`/api/management/iam/users/${encodeURIComponent(username)}`);\n}\n\nexport interface UpdateUserGroupsResponse {\n  username: string;\n  groups: string[];\n  added: string[];\n  removed: string[];\n}\n\nexport async function updateUserGroups(\n  username: string,\n  groups: string[]\n): Promise {\n  const res = await axios.patch(\n    `/api/management/iam/users/${encodeURIComponent(username)}/groups`,\n    { groups }\n  );\n  return res.data;\n}\n"
  },
  {
    "path": "frontend/src/hooks/useRegistryConfig.ts",
    "content": "import { useState, useEffect } from 'react';\nimport axios from 'axios';\n\ninterface RegistryConfig {\n  deployment_mode: 'with-gateway' | 'registry-only';\n  registry_mode: 'full' | 'skills-only' | 'mcp-servers-only' | 'agents-only';\n  nginx_updates_enabled: boolean;\n  features: {\n    mcp_servers: boolean;\n    agents: boolean;\n    skills: boolean;\n    virtual_servers: boolean;\n    federation: boolean;\n    gateway_proxy: boolean;\n  };\n}\n\nconst DEFAULT_CONFIG: RegistryConfig = {\n  deployment_mode: 'with-gateway',\n  registry_mode: 'full',\n  nginx_updates_enabled: true,\n  features: {\n    mcp_servers: true,\n    agents: true,\n    skills: true,\n    virtual_servers: true,\n    federation: true,\n    gateway_proxy: true,\n  },\n};\n\nlet cachedConfig: RegistryConfig | null = null;\n\nexport function useRegistryConfig(): {\n  config: RegistryConfig | null;\n  loading: boolean;\n  error: Error | null;\n} {\n  const [config, setConfig] = useState(cachedConfig);\n  const [loading, setLoading] = useState(!cachedConfig);\n  const [error, setError] = useState(null);\n\n  useEffect(() => {\n    if (cachedConfig) return;\n\n    setLoading(true);\n    axios\n      .get('/api/config')\n      .then((res) => {\n        cachedConfig = res.data;\n        setConfig(res.data);\n        setError(null);\n      })\n      .catch((err) => {\n        console.error('Failed to load registry config:', err);\n        setError(err);\n        setConfig(DEFAULT_CONFIG);\n      })\n      .finally(() => setLoading(false));\n  }, []);\n\n  return { config, loading, error };\n}\n"
  },
  {
    "path": "frontend/src/hooks/useSemanticSearch.ts",
    "content": "import { useEffect, useState } from 'react';\nimport axios from 'axios';\n\ntype EntityType = 'mcp_server' | 'tool' | 'a2a_agent' | 'skill' | 'virtual_server';\n\nconst DEFAULT_ENTITY_TYPES: EntityType[] = ['mcp_server', 'tool', 'a2a_agent', 'skill', 'virtual_server'];\nconst DEFAULT_ENTITY_TYPES_KEY = DEFAULT_ENTITY_TYPES.join('|');\n\nexport interface MatchingToolHit {\n  tool_name: string;\n  description?: string;\n  relevance_score: number;\n  match_context?: string;\n}\n\nexport interface SyncMetadata {\n  is_federated?: boolean;\n  source_peer_id?: string;\n  upstream_path?: string;\n  last_synced_at?: string;\n  is_read_only?: boolean;\n  is_orphaned?: boolean;\n  orphaned_at?: string;\n}\n\nexport interface SemanticServerHit {\n  path: string;\n  server_name: string;\n  description?: string;\n  tags: string[];\n  num_tools: number;\n  is_enabled: boolean;\n  relevance_score: number;\n  match_context?: string;\n  matching_tools: MatchingToolHit[];\n  sync_metadata?: SyncMetadata;\n  // Endpoint URL for agent connectivity (computed based on deployment mode)\n  endpoint_url?: string;\n  // Raw endpoint fields (for advanced use cases)\n  proxy_pass_url?: string;\n  mcp_endpoint?: string;\n  sse_endpoint?: string;\n  supported_transports?: string[];\n}\n\nexport interface SemanticToolHit {\n  server_path: string;\n  server_name: string;\n  tool_name: string;\n  description?: string;\n  inputSchema?: Record;\n  relevance_score: number;\n  match_context?: string;\n  // Endpoint URL for the parent MCP server\n  endpoint_url?: string;\n}\n\nexport interface SemanticAgentHit {\n  // Only search-specific fields at top level; all agent details in agent_card\n  path: string;\n  relevance_score: number;\n  match_context?: string;\n  agent_card: Record;\n  trust_verified?: string;\n}\n\nexport interface SemanticSkillHit {\n  path: string;\n  skill_name: string;\n  description?: string;\n  tags: string[];\n  skill_md_url?: string;\n  skill_md_raw_url?: string;\n  repository_url?: string;\n  version?: string;\n  author?: string;\n  visibility?: string;\n  owner?: string;\n  is_enabled?: boolean;\n  health_status?: 'healthy' | 'unhealthy' | 'unknown';\n  last_checked_time?: string;\n  relevance_score: number;\n  match_context?: string;\n}\n\nexport interface VirtualServerToolHit {\n  tool_name: string;\n  description?: string;\n  relevance_score?: number;\n  match_context?: string;\n  inputSchema?: Record;\n}\n\nexport interface SemanticVirtualServerHit {\n  path: string;\n  server_name: string;\n  description?: string;\n  tags: string[];\n  num_tools: number;\n  backend_count?: number;\n  backend_paths?: string[];\n  is_enabled: boolean;\n  relevance_score: number;\n  match_context?: string;\n  matching_tools?: VirtualServerToolHit[];\n  // Endpoint URL for agent connectivity (computed based on deployment mode)\n  endpoint_url?: string;\n}\n\nexport interface SemanticSearchResponse {\n  query: string;\n  servers: SemanticServerHit[];\n  tools: SemanticToolHit[];\n  agents: SemanticAgentHit[];\n  skills: SemanticSkillHit[];\n  virtual_servers: SemanticVirtualServerHit[];\n  total_servers: number;\n  total_tools: number;\n  total_agents: number;\n  total_skills: number;\n  total_virtual_servers: number;\n}\n\ninterface UseSemanticSearchOptions {\n  enabled?: boolean;\n  minLength?: number;\n  maxResults?: number;\n  entityTypes?: EntityType[];\n  tags?: string[];\n}\n\ninterface UseSemanticSearchReturn {\n  results: SemanticSearchResponse | null;\n  loading: boolean;\n  error: string | null;\n  debouncedQuery: string;\n}\n\nexport const useSemanticSearch = (\n  query: string,\n  options: UseSemanticSearchOptions = {}\n): UseSemanticSearchReturn => {\n  const [results, setResults] = useState(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState(null);\n  const [debouncedQuery, setDebouncedQuery] = useState('');\n\n  const enabled = options.enabled ?? true;\n  const minLength = options.minLength ?? 2;\n  const maxResults = options.maxResults ?? 10;\n  const entityTypes = options.entityTypes ?? DEFAULT_ENTITY_TYPES;\n  const entityTypesKey =\n    options.entityTypes?.join('|') ?? DEFAULT_ENTITY_TYPES_KEY;\n  const tags = options.tags;\n  const tagsKey = tags?.join('|') ?? '';\n\n  // Debounce user input to minimize API calls\n  useEffect(() => {\n    const handle = setTimeout(() => {\n      setDebouncedQuery(query.trim());\n    }, 350);\n\n    return () => clearTimeout(handle);\n  }, [query]);\n\n  useEffect(() => {\n    // Allow search if we have a text query or explicit tag filters\n    const hasQuery = debouncedQuery.length >= minLength;\n    const hasTags = tags && tags.length > 0;\n    if (!enabled || (!hasQuery && !hasTags)) {\n      setResults(null);\n      setError(null);\n      setLoading(false);\n      return;\n    }\n\n    let cancelled = false;\n    const controller = new AbortController();\n\n    const runSearch = async () => {\n      setLoading(true);\n      setError(null);\n      try {\n        const body: Record = {\n          query: debouncedQuery || '*',\n          entity_types: entityTypes,\n          max_results: maxResults,\n        };\n        if (tags && tags.length > 0) {\n          body.tags = tags;\n        }\n        const response = await axios.post(\n          '/api/search/semantic',\n          body,\n          { signal: controller.signal }\n        );\n        if (!cancelled) {\n          setResults(response.data);\n        }\n      } catch (err: any) {\n        if (axios.isCancel(err) || cancelled) return;\n        const message =\n          err.response?.data?.detail ||\n          err.message ||\n          'Semantic search failed.';\n        setError(message);\n        setResults(null);\n      } finally {\n        if (!cancelled) {\n          setLoading(false);\n        }\n      }\n    };\n\n    runSearch();\n\n    return () => {\n      cancelled = true;\n      controller.abort();\n    };\n  }, [debouncedQuery, enabled, minLength, maxResults, entityTypesKey, tagsKey]);\n\n  return { results, loading, error, debouncedQuery };\n};\n"
  },
  {
    "path": "frontend/src/hooks/useServerStats.ts",
    "content": "import React, { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\nimport { useRegistryConfig } from './useRegistryConfig';\n\ninterface ServerVersion {\n  version: string;\n  proxy_pass_url: string;\n  status: string;\n  is_default: boolean;\n}\n\ninterface SyncMetadata {\n  is_federated?: boolean;\n  source_peer_id?: string;\n  upstream_path?: string;\n  last_synced_at?: string;\n  is_read_only?: boolean;\n}\n\ninterface Server {\n  name: string;\n  path: string;\n  description?: string;\n  official?: boolean;\n  enabled: boolean;\n  tags?: string[];\n  last_checked_time?: string;\n  usersCount?: number;\n  rating?: number;\n  status?: 'healthy' | 'healthy-auth-expired' | 'unhealthy' | 'unknown';\n  num_tools?: number;\n  type: 'server' | 'agent';\n  proxy_pass_url?: string;\n  version?: string;\n  versions?: ServerVersion[];\n  default_version?: string;\n  mcp_server_version?: string;\n  mcp_server_version_previous?: string;\n  mcp_server_version_updated_at?: string;\n  sync_metadata?: SyncMetadata;\n  ans_metadata?: {\n    ans_agent_id: string;\n    status: 'verified' | 'expired' | 'revoked' | 'not_found' | 'pending';\n    domain?: string;\n    organization?: string;\n    certificate?: {\n      not_after?: string;\n      subject_dn?: string;\n      issuer_dn?: string;\n    };\n    last_verified?: string;\n  };\n  registered_by?: string | null;\n  trust_level?: string;\n  visibility?: string;\n  supported_protocol?: string | null;\n  lifecycle_status?: 'active' | 'draft' | 'deprecated' | 'beta';\n}\n\ninterface ServerStats {\n  total: number;\n  enabled: number;\n  disabled: number;\n  withIssues: number;\n}\n\ninterface UseServerStatsReturn {\n  stats: ServerStats;\n  servers: Server[];\n  agents: Server[];\n  setServers: React.Dispatch>;\n  setAgents: React.Dispatch>;\n  activeFilter: string;\n  setActiveFilter: (filter: string) => void;\n  loading: boolean;\n  error: string | null;\n  refreshData: () => Promise;\n}\n\nexport const useServerStats = (): UseServerStatsReturn => {\n  const [stats, setStats] = useState({\n    total: 0,\n    enabled: 0,\n    disabled: 0,\n    withIssues: 0,\n  });\n  const [servers, setServers] = useState([]);\n  const [agents, setAgents] = useState([]);\n  const [activeFilter, setActiveFilter] = useState('all');\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  // Get registry config to determine which features are enabled\n  const { config: registryConfig } = useRegistryConfig();\n\n  // Helper function to map backend health status to frontend status\n  const mapHealthStatus = (healthStatus: string): 'healthy' | 'unhealthy' | 'unknown' => {\n    if (!healthStatus || healthStatus === 'unknown') return 'unknown';\n    if (healthStatus === 'healthy') return 'healthy';\n    if (healthStatus.includes('unhealthy') || healthStatus.includes('error') || healthStatus.includes('timeout')) return 'unhealthy';\n    return 'unknown';\n  };\n\n  const fetchData = useCallback(async () => {\n    try {\n      setLoading(true);\n      setError(null);\n\n      // Check which features are enabled based on registry mode\n      const serversEnabled = registryConfig?.features.mcp_servers !== false;\n      const agentsEnabled = registryConfig?.features.agents !== false;\n      const skillsEnabled = registryConfig?.features.skills !== false;\n\n      // Build fetch promises based on enabled features\n      const fetchPromises: Promise[] = [];\n\n      if (serversEnabled) {\n        fetchPromises.push(axios.get('/api/servers?limit=500').catch(() => ({ data: { servers: [] } })));\n      } else {\n        fetchPromises.push(Promise.resolve({ data: { servers: [] } }));\n      }\n\n      if (agentsEnabled) {\n        fetchPromises.push(axios.get('/api/agents?limit=500').catch(() => ({ data: { agents: [] } })));\n      } else {\n        fetchPromises.push(Promise.resolve({ data: { agents: [] } }));\n      }\n\n      // Fetch skills for stats if skills are enabled\n      if (skillsEnabled) {\n        fetchPromises.push(axios.get('/api/skills?include_disabled=true&limit=500').catch(() => ({ data: { skills: [] } })));\n      } else {\n        fetchPromises.push(Promise.resolve({ data: { skills: [] } }));\n      }\n\n      const [serversResponse, agentsResponse, skillsResponse] = await Promise.all(fetchPromises);\n      \n      // The API returns {\"servers\": [...]} \n      const responseData = serversResponse.data || {};\n      const serversList = responseData.servers || [];\n      \n      // The agents API returns {\"agents\": [...]}\n      const agentsData = agentsResponse.data || {};\n      const agentsList = agentsData.agents || [];\n\n      // The skills API returns {\"skills\": [...]}\n      const skillsData = skillsResponse.data || {};\n      const skillsList = skillsData.skills || [];\n\n      // Debug logging to see what servers are returned\n      console.log('🔍 Server filtering debug info:');\n      console.log(`📊 Total servers returned from API: ${serversList.length}`);\n      console.log('📋 Server list:', serversList.map((s: any) => ({ \n        name: s.display_name, \n        path: s.path, \n        enabled: s.is_enabled \n      })));\n      \n      // Debug logging for agents\n      console.log(`📊 Total agents returned from API: ${agentsList.length}`);\n      console.log('📋 Agent list:', agentsList.map((a: any) => ({ \n        name: a.name, \n        path: a.path, \n        enabled: a.is_enabled \n      })));\n      \n      // Transform server data from backend format to frontend format\n      const transformedServers: Server[] = serversList.map((serverInfo: any) => {\n        // Debug log to see what last_checked_iso data we're getting\n        console.log(`🕐 Server ${serverInfo.display_name}: last_checked_iso =`, serverInfo.last_checked_iso);\n        \n        const transformed = {\n          name: serverInfo.display_name || 'Unknown Server',\n          path: serverInfo.path,\n          description: serverInfo.description || '',\n          official: serverInfo.is_official || false,\n          enabled: serverInfo.is_enabled !== undefined ? serverInfo.is_enabled : false,\n          tags: serverInfo.tags || [],\n          last_checked_time: serverInfo.last_checked_iso,  // Fixed field mapping\n          usersCount: 0, // Not available in backend\n          rating: serverInfo.num_stars || 0,\n          rating_details: serverInfo.rating_details || [],\n          status: mapHealthStatus(serverInfo.health_status || 'unknown'),\n          num_tools: serverInfo.num_tools || 0,\n          type: 'server' as const,\n          proxy_pass_url: serverInfo.proxy_pass_url || '',\n          version: serverInfo.version,\n          versions: serverInfo.versions,\n          default_version: serverInfo.default_version,\n          mcp_server_version: serverInfo.mcp_server_version,\n          mcp_server_version_previous: serverInfo.mcp_server_version_previous,\n          mcp_server_version_updated_at: serverInfo.mcp_server_version_updated_at,\n          sync_metadata: serverInfo.sync_metadata,\n          ans_metadata: serverInfo.ans_metadata || serverInfo.ansMetadata,\n          auth_scheme: serverInfo.auth_scheme,\n          auth_header_name: serverInfo.auth_header_name,\n          lifecycle_status: serverInfo.status || 'active',\n        };\n        \n        // Debug log the transformed server\n        console.log(`🔄 Transformed server ${transformed.name}:`, {\n          last_checked_time: transformed.last_checked_time,\n          status: transformed.status,\n          enabled: transformed.enabled\n        });\n        \n        return transformed;\n      });\n      \n      // Transform agent data from backend format to frontend format\n      const transformedAgents: Server[] = agentsList.map((agentInfo: any) => {\n        const transformed = {\n          name: agentInfo.name || 'Unknown Agent',\n          path: agentInfo.path,\n          description: agentInfo.description || '',\n          official: false, // Agents don't have official flag\n          enabled: agentInfo.is_enabled !== undefined ? agentInfo.is_enabled : false,\n          tags: agentInfo.tags || [],\n          last_checked_time: agentInfo.last_health_check || agentInfo.lastHealthCheck || undefined,\n          usersCount: 0,\n          rating: agentInfo.num_stars || 0,\n          status: mapHealthStatus(agentInfo.health_status || agentInfo.healthStatus || 'unknown'),\n          num_tools: agentInfo.num_skills || 0, // Use num_skills for agents\n          type: 'agent' as const,\n          sync_metadata: agentInfo.sync_metadata,\n          ans_metadata: agentInfo.ans_metadata || agentInfo.ansMetadata,\n          registered_by: agentInfo.registered_by || agentInfo.registeredBy || null,\n          trust_level: agentInfo.trust_level || agentInfo.trustLevel || 'community',\n          visibility: agentInfo.visibility || 'public',\n          supported_protocol: agentInfo.supported_protocol || agentInfo.supportedProtocol || null,\n          lifecycle_status: agentInfo.status || 'active',\n        };\n        \n        console.log(`🔄 Transformed agent ${transformed.name}:`, {\n          enabled: transformed.enabled,\n          num_skills: transformed.num_tools\n        });\n        \n        return transformed;\n      });\n      \n      // Store servers and agents separately\n      setServers(transformedServers);\n      setAgents(transformedAgents);\n\n      // Calculate stats based on what features are enabled\n      let total = 0;\n      let enabled = 0;\n      let disabled = 0;\n      let withIssues = 0;\n\n      // Include servers in stats if enabled\n      if (serversEnabled) {\n        transformedServers.forEach((service) => {\n          total++;\n          if (service.enabled) {\n            enabled++;\n          } else {\n            disabled++;\n          }\n          if (service.status === 'unhealthy') {\n            withIssues++;\n          }\n        });\n      }\n\n      // Include agents in stats if enabled\n      if (agentsEnabled) {\n        transformedAgents.forEach((service) => {\n          total++;\n          if (service.enabled) {\n            enabled++;\n          } else {\n            disabled++;\n          }\n          if (service.status === 'unhealthy') {\n            withIssues++;\n          }\n        });\n      }\n\n      // Include skills in stats if enabled (and servers/agents are not)\n      // This ensures skills-only mode shows skill stats\n      if (skillsEnabled) {\n        skillsList.forEach((skill: any) => {\n          total++;\n          if (skill.is_enabled !== false) {\n            enabled++;\n          } else {\n            disabled++;\n          }\n          // Skills don't have health status, so no withIssues increment\n        });\n      }\n\n      const newStats = {\n        total,\n        enabled,\n        disabled,\n        withIssues,\n      };\n      \n      console.log('Calculated stats (servers + agents + skills):', newStats);\n      setStats(newStats);\n    } catch (err: any) {\n      console.error('Failed to fetch data:', err);\n      setError(err.response?.data?.detail || 'Failed to fetch data');\n      setServers([]);\n      setAgents([]);\n      setStats({ total: 0, enabled: 0, disabled: 0, withIssues: 0 });\n    } finally {\n      setLoading(false);\n    }\n  }, [registryConfig]);\n\n  useEffect(() => {\n    fetchData();\n  }, [fetchData]);\n\n  return {\n    stats,\n    servers,\n    agents,\n    setServers,\n    setAgents,\n    activeFilter,\n    setActiveFilter,\n    loading,\n    error,\n    refreshData: fetchData,\n  };\n};\n"
  },
  {
    "path": "frontend/src/hooks/useSkills.ts",
    "content": "import { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\nimport { Skill } from '../types/skill';\n\nexport type { Skill } from '../types/skill';\n\ninterface UseSkillsReturn {\n  skills: Skill[];\n  setSkills: React.Dispatch>;\n  loading: boolean;\n  error: string | null;\n  refreshData: () => Promise;\n}\n\nexport const useSkills = (): UseSkillsReturn => {\n  const [skills, setSkills] = useState([]);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchData = useCallback(async () => {\n    try {\n      setLoading(true);\n      setError(null);\n\n      const response = await axios.get('/api/skills?include_disabled=true');\n\n      // The API returns {\"skills\": [...]}\n      const responseData = response.data || {};\n      const skillsList = responseData.skills || [];\n\n      console.log(`Skills returned from API: ${skillsList.length}`);\n\n      // Transform skill data from backend format to frontend format\n      const transformedSkills: Skill[] = skillsList.map((skillInfo: any) => ({\n        name: skillInfo.name || 'Unknown Skill',\n        path: skillInfo.path,\n        description: skillInfo.description || '',\n        skill_md_url: skillInfo.skill_md_url || '',\n        skill_md_raw_url: skillInfo.skill_md_raw_url || '',\n        repository_url: skillInfo.repository_url,\n        version: skillInfo.version,\n        author: skillInfo.author,\n        visibility: skillInfo.visibility || 'public',\n        is_enabled: skillInfo.is_enabled !== undefined ? skillInfo.is_enabled : true,\n        tags: skillInfo.tags || [],\n        owner: skillInfo.owner,\n        registry_name: skillInfo.registry_name || 'local',\n        target_agents: skillInfo.target_agents || [],\n        allowed_tools: skillInfo.allowed_tools || [],\n        requirements: skillInfo.requirements || [],\n        metadata: skillInfo.metadata || null,\n        auth_scheme: skillInfo.auth_scheme || 'none',\n        auth_header_name: skillInfo.auth_header_name || undefined,\n        num_stars: skillInfo.num_stars || 0,\n        status: skillInfo.status || 'active',\n        health_status: skillInfo.health_status || 'unknown',\n        last_checked_time: skillInfo.last_checked_time,\n        created_at: skillInfo.created_at,\n        updated_at: skillInfo.updated_at,\n      }));\n\n      setSkills(transformedSkills);\n    } catch (err: any) {\n      console.error('Failed to fetch skills data:', err);\n      setError(err.response?.data?.detail || 'Failed to fetch skills');\n      setSkills([]);\n    } finally {\n      setLoading(false);\n    }\n  }, []);\n\n  useEffect(() => {\n    fetchData();\n  }, [fetchData]);\n\n  return {\n    skills,\n    setSkills,\n    loading,\n    error,\n    refreshData: fetchData,\n  };\n};\n"
  },
  {
    "path": "frontend/src/hooks/useToolCatalog.ts",
    "content": "/**\n * Hooks for fetching servers and their tools.\n *\n * Fetches all servers from /api/servers with descriptions\n * for use in searchable select components.\n */\n\nimport { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\n\n\nexport interface ServerInfo {\n  path: string;\n  name: string;\n  description: string;\n  type: 'mcp' | 'virtual';\n}\n\nexport interface ToolInfo {\n  name: string;\n  description: string;\n  serverPath: string;\n}\n\ninterface ServerListResponse {\n  servers: Array<{\n    path: string;\n    server_name?: string;\n    name?: string;\n    description?: string;\n    [key: string]: unknown;\n  }>;\n}\n\ninterface VirtualServerListResponse {\n  virtual_servers: Array<{\n    path: string;\n    name: string;\n    description?: string;\n    enabled?: boolean;\n    [key: string]: unknown;\n  }>;\n}\n\ninterface ToolCatalogResponse {\n  tools: Array<{\n    tool_name: string;\n    server_path: string;\n    server_name: string;\n    description: string;\n  }>;\n  by_server: Record>;\n}\n\ninterface UseServerListReturn {\n  servers: ServerInfo[];\n  isLoading: boolean;\n  error: string | null;\n  refetch: () => Promise;\n}\n\ninterface UseServerToolsReturn {\n  tools: ToolInfo[];\n  isLoading: boolean;\n  error: string | null;\n}\n\n\n/**\n * Hook to fetch all available servers with descriptions.\n * Includes both regular MCP servers and virtual servers.\n */\nexport function useServerList(): UseServerListReturn {\n  const [servers, setServers] = useState([]);\n  const [isLoading, setIsLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchServers = useCallback(async () => {\n    setIsLoading(true);\n    setError(null);\n\n    try {\n      // Fetch both regular servers and virtual servers in parallel\n      const [serversResponse, virtualServersResponse] = await Promise.all([\n        axios.get('/api/servers?limit=500'),\n        axios.get('/api/virtual-servers'),\n      ]);\n\n      // Map regular MCP servers\n      const mcpServers: ServerInfo[] = (serversResponse.data.servers || []).map((s) => ({\n        path: s.path,\n        name: s.server_name || s.name || s.path,\n        description: s.description || '',\n        type: 'mcp' as const,\n      }));\n\n      // Map virtual servers (only enabled ones)\n      const virtualServers: ServerInfo[] = (virtualServersResponse.data.virtual_servers || [])\n        .filter((vs) => vs.enabled !== false)\n        .map((vs) => ({\n          path: vs.path,\n          name: vs.name || vs.path,\n          description: vs.description || '',\n          type: 'virtual' as const,\n        }));\n\n      // Combine and sort by type (MCP first), then by name\n      const allServers = [...mcpServers, ...virtualServers];\n      allServers.sort((a, b) => {\n        // Sort by type first (mcp before virtual)\n        if (a.type !== b.type) {\n          return a.type === 'mcp' ? -1 : 1;\n        }\n        // Then by name\n        return a.name.localeCompare(b.name);\n      });\n\n      setServers(allServers);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : 'Failed to fetch servers';\n      setError(message);\n      setServers([]);\n    } finally {\n      setIsLoading(false);\n    }\n  }, []);\n\n  useEffect(() => {\n    fetchServers();\n  }, [fetchServers]);\n\n  return {\n    servers,\n    isLoading,\n    error,\n    refetch: fetchServers,\n  };\n}\n\n\n/**\n * Hook to fetch tools for a specific server.\n * Returns empty array if serverPath is empty or '*'.\n */\nexport function useServerTools(serverPath: string): UseServerToolsReturn {\n  const [tools, setTools] = useState([]);\n  const [isLoading, setIsLoading] = useState(false);\n  const [error, setError] = useState(null);\n\n  useEffect(() => {\n    // Don't fetch for empty or wildcard\n    if (!serverPath || serverPath === '*') {\n      setTools([]);\n      setIsLoading(false);\n      return;\n    }\n\n    const fetchTools = async () => {\n      setIsLoading(true);\n      setError(null);\n\n      try {\n        const response = await axios.get(\n          `/api/tool-catalog?server_path=${encodeURIComponent(serverPath)}`\n        );\n        const data = response.data;\n\n        // Extract tools from the response\n        const toolList: ToolInfo[] = (data.tools || []).map((t) => ({\n          name: t.tool_name,\n          description: t.description || '',\n          serverPath: t.server_path,\n        }));\n\n        // Sort by name\n        toolList.sort((a, b) => a.name.localeCompare(b.name));\n\n        setTools(toolList);\n      } catch (err) {\n        const message = err instanceof Error ? err.message : 'Failed to fetch tools';\n        setError(message);\n        setTools([]);\n      } finally {\n        setIsLoading(false);\n      }\n    };\n\n    fetchTools();\n  }, [serverPath]);\n\n  return {\n    tools,\n    isLoading,\n    error,\n  };\n}\n"
  },
  {
    "path": "frontend/src/hooks/useVirtualServers.ts",
    "content": "import { useState, useEffect, useCallback } from 'react';\nimport axios from 'axios';\nimport {\n  VirtualServerInfo,\n  VirtualServerConfig,\n  CreateVirtualServerRequest,\n  UpdateVirtualServerRequest,\n  ResolvedTool,\n  ToolCatalogEntry,\n} from '../types/virtualServer';\n\n\n/**\n * Return type for the useVirtualServers hook.\n */\ninterface UseVirtualServersReturn {\n  virtualServers: VirtualServerInfo[];\n  loading: boolean;\n  error: string | null;\n  refreshData: () => Promise;\n  createVirtualServer: (data: CreateVirtualServerRequest) => Promise;\n  updateVirtualServer: (path: string, data: UpdateVirtualServerRequest) => Promise;\n  deleteVirtualServer: (path: string) => Promise;\n  toggleVirtualServer: (path: string, enabled: boolean) => Promise;\n}\n\n\n/**\n * Encode a virtual server path for use in URL segments.\n *\n * Virtual server paths contain slashes (e.g., \"/virtual/dev-essentials\"),\n * so they must be encoded for safe use in API URLs.\n */\nfunction _encodeServerPath(path: string): string {\n  return encodeURIComponent(path);\n}\n\n\n/**\n * Hook for listing and managing virtual servers.\n *\n * Provides the list of virtual servers with create, update, delete,\n * and toggle operations. The list is automatically refreshed after\n * any mutation operation.\n */\nexport const useVirtualServers = (): UseVirtualServersReturn => {\n  const [virtualServers, setVirtualServers] = useState([]);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchData = useCallback(async () => {\n    try {\n      setLoading(true);\n      setError(null);\n\n      const response = await axios.get('/api/virtual-servers');\n      const responseData = response.data || {};\n      const serversList: VirtualServerInfo[] = responseData.virtual_servers || [];\n\n      setVirtualServers(serversList);\n    } catch (err: unknown) {\n      const axiosErr = err as { response?: { data?: { detail?: string } }; message?: string };\n      console.error('Failed to fetch virtual servers:', err);\n      setError(\n        axiosErr.response?.data?.detail ||\n        axiosErr.message ||\n        'Failed to fetch virtual servers'\n      );\n      setVirtualServers([]);\n    } finally {\n      setLoading(false);\n    }\n  }, []);\n\n  const createVirtualServer = useCallback(async (\n    data: CreateVirtualServerRequest,\n  ): Promise => {\n    const response = await axios.post('/api/virtual-servers', data);\n    await fetchData();\n    return response.data;\n  }, [fetchData]);\n\n  const updateVirtualServer = useCallback(async (\n    path: string,\n    data: UpdateVirtualServerRequest,\n  ): Promise => {\n    const response = await axios.put(\n      `/api/virtual-servers/${_encodeServerPath(path)}`,\n      data,\n    );\n    await fetchData();\n    return response.data;\n  }, [fetchData]);\n\n  const deleteVirtualServer = useCallback(async (\n    path: string,\n  ): Promise => {\n    await axios.delete(`/api/virtual-servers/${_encodeServerPath(path)}`);\n    await fetchData();\n  }, [fetchData]);\n\n  const toggleVirtualServer = useCallback(async (\n    path: string,\n    enabled: boolean,\n  ): Promise => {\n    const response = await axios.post(\n      `/api/virtual-servers/${_encodeServerPath(path)}/toggle`,\n      { enabled },\n    );\n    await fetchData();\n    return response.data;\n  }, [fetchData]);\n\n  useEffect(() => {\n    fetchData();\n  }, [fetchData]);\n\n  return {\n    virtualServers,\n    loading,\n    error,\n    refreshData: fetchData,\n    createVirtualServer,\n    updateVirtualServer,\n    deleteVirtualServer,\n    toggleVirtualServer,\n  };\n};\n\n\n/**\n * Return type for the useVirtualServer hook.\n */\ninterface UseVirtualServerReturn {\n  virtualServer: VirtualServerConfig | null;\n  loading: boolean;\n  /** @deprecated Use `loading` instead */\n  isLoading: boolean;\n  error: string | null;\n  refetch: () => Promise;\n}\n\n\n/**\n * Hook for fetching a single virtual server by path.\n *\n * @param path - The virtual server path (e.g., '/virtual/dev-essentials'), or undefined to skip fetching\n */\nexport const useVirtualServer = (path: string | undefined): UseVirtualServerReturn => {\n  const [virtualServer, setVirtualServer] = useState(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState(null);\n\n  const fetchData = useCallback(async () => {\n    if (!path) {\n      setVirtualServer(null);\n      return;\n    }\n\n    try {\n      setLoading(true);\n      setError(null);\n\n      const response = await axios.get(\n        `/api/virtual-servers/${_encodeServerPath(path)}`,\n      );\n      setVirtualServer(response.data);\n    } catch (err: unknown) {\n      const axiosErr = err as { response?: { data?: { detail?: string } }; message?: string };\n      console.error(`Failed to fetch virtual server ${path}:`, err);\n      setError(\n        axiosErr.response?.data?.detail ||\n        axiosErr.message ||\n        'Failed to fetch virtual server'\n      );\n      setVirtualServer(null);\n    } finally {\n      setLoading(false);\n    }\n  }, [path]);\n\n  useEffect(() => {\n    fetchData();\n  }, [fetchData]);\n\n  return {\n    virtualServer,\n    loading,\n    isLoading: loading,\n    error,\n    refetch: fetchData,\n  };\n};\n\n\n/**\n * Return type for the useVirtualServerTools hook.\n */\ninterface UseVirtualServerToolsReturn {\n  tools: ResolvedTool[];\n  loading: boolean;\n  /** @deprecated Use `loading` instead */\n  isLoading: boolean;\n  error: string | null;\n  refetch: () => Promise;\n}\n\n\n/**\n * Hook for fetching resolved tools for a virtual server.\n *\n * @param path - The virtual server path, or undefined to skip fetching\n */\nexport const useVirtualServerTools = (path: string | undefined): UseVirtualServerToolsReturn => {\n  const [tools, setTools] = useState([]);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState(null);\n\n  const fetchData = useCallback(async () => {\n    if (!path) {\n      setTools([]);\n      return;\n    }\n\n    try {\n      setLoading(true);\n      setError(null);\n\n      const response = await axios.get(\n        `/api/virtual-servers/${_encodeServerPath(path)}/tools`,\n      );\n      const responseData = response.data || {};\n      const toolsList: ResolvedTool[] = responseData.tools || [];\n\n      setTools(toolsList);\n    } catch (err: unknown) {\n      const axiosErr = err as { response?: { data?: { detail?: string } }; message?: string };\n      console.error(`Failed to fetch tools for virtual server ${path}:`, err);\n      setError(\n        axiosErr.response?.data?.detail ||\n        axiosErr.message ||\n        'Failed to fetch virtual server tools'\n      );\n      setTools([]);\n    } finally {\n      setLoading(false);\n    }\n  }, [path]);\n\n  useEffect(() => {\n    fetchData();\n  }, [fetchData]);\n\n  return {\n    tools,\n    loading,\n    isLoading: loading,\n    error,\n    refetch: fetchData,\n  };\n};\n\n\n/**\n * Return type for the useToolCatalog hook.\n */\ninterface UseToolCatalogReturn {\n  catalog: ToolCatalogEntry[];\n  loading: boolean;\n  error: string | null;\n  refreshData: () => Promise;\n}\n\n\n/**\n * Hook for fetching the global tool catalog across all enabled backend servers.\n */\nexport const useToolCatalog = (): UseToolCatalogReturn => {\n  const [catalog, setCatalog] = useState([]);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState(null);\n\n  const fetchData = useCallback(async () => {\n    try {\n      setLoading(true);\n      setError(null);\n\n      const response = await axios.get('/api/tool-catalog');\n      const responseData = response.data || {};\n      const toolsList: ToolCatalogEntry[] = responseData.tools || [];\n\n      setCatalog(toolsList);\n    } catch (err: unknown) {\n      const axiosErr = err as { response?: { data?: { detail?: string } }; message?: string };\n      console.error('Failed to fetch tool catalog:', err);\n      setError(\n        axiosErr.response?.data?.detail ||\n        axiosErr.message ||\n        'Failed to fetch tool catalog'\n      );\n      setCatalog([]);\n    } finally {\n      setLoading(false);\n    }\n  }, []);\n\n  useEffect(() => {\n    fetchData();\n  }, [fetchData]);\n\n  return {\n    catalog,\n    loading,\n    error,\n    refreshData: fetchData,\n  };\n};\n\n\n/**\n * Standalone API functions for virtual server management operations.\n * These can be used outside of hooks for one-off operations.\n */\nexport async function createVirtualServer(\n  data: CreateVirtualServerRequest,\n): Promise {\n  const response = await axios.post('/api/virtual-servers', data);\n  return response.data;\n}\n\n\nexport async function updateVirtualServer(\n  path: string,\n  updates: UpdateVirtualServerRequest,\n): Promise {\n  const response = await axios.put(\n    `/api/virtual-servers/${_encodeServerPath(path)}`,\n    updates,\n  );\n  return response.data;\n}\n\n\nexport async function deleteVirtualServer(path: string): Promise {\n  await axios.delete(`/api/virtual-servers/${_encodeServerPath(path)}`);\n}\n\n\nexport async function toggleVirtualServer(\n  path: string,\n  enabled: boolean,\n): Promise {\n  const response = await axios.post(\n    `/api/virtual-servers/${_encodeServerPath(path)}/toggle`,\n    { enabled },\n  );\n  return response.data;\n}\n"
  },
  {
    "path": "frontend/src/index.css",
    "content": "@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');\n\n@layer base {\n  html {\n    font-family: 'Inter', system-ui, sans-serif;\n  }\n  \n  body {\n    margin: 0;\n    -webkit-font-smoothing: antialiased;\n    -moz-osx-font-smoothing: grayscale;\n  }\n}\n\n@layer components {\n  .btn-primary {\n    @apply bg-primary-600 hover:bg-primary-700 text-white font-medium px-4 py-2 rounded-lg transition-colors duration-200;\n  }\n  \n  .btn-secondary {\n    @apply bg-gray-100 hover:bg-gray-200 text-gray-900 font-medium px-4 py-2 rounded-lg transition-colors duration-200;\n  }\n  \n  .card {\n    @apply bg-white dark:bg-gray-800 rounded-xl shadow-sm border border-gray-200 dark:border-gray-700;\n  }\n  \n  .input {\n    @apply block w-full px-3 py-2 border border-gray-300 rounded-lg placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-primary-500 focus:border-transparent;\n  }\n  \n  /* Line clamp utilities for text truncation */\n  .line-clamp-2 {\n    display: -webkit-box;\n    -webkit-line-clamp: 2;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n  }\n  \n  .line-clamp-3 {\n    display: -webkit-box;\n    -webkit-line-clamp: 3;\n    -webkit-box-orient: vertical;\n    overflow: hidden;\n  }\n\n  /* Toast animations */\n  @keyframes slide-in-top {\n    0% {\n      transform: translateY(-100%);\n      opacity: 0;\n    }\n    100% {\n      transform: translateY(0);\n      opacity: 1;\n    }\n  }\n\n  .animate-slide-in-top {\n    animation: slide-in-top 0.3s ease-out;\n  }\n\n  /* Thin auto-hiding scrollbar for Discover tab */\n  .discover-scroll {\n    scrollbar-width: thin;\n    scrollbar-color: transparent transparent;\n  }\n  .discover-scroll:hover {\n    scrollbar-color: rgba(100, 100, 140, 0.3) transparent;\n  }\n  .discover-scroll::-webkit-scrollbar {\n    width: 6px;\n  }\n  .discover-scroll::-webkit-scrollbar-track {\n    background: transparent;\n  }\n  .discover-scroll::-webkit-scrollbar-thumb {\n    background: transparent;\n    border-radius: 3px;\n  }\n  .discover-scroll:hover::-webkit-scrollbar-thumb {\n    background: rgba(100, 100, 140, 0.3);\n  }\n  .discover-scroll::-webkit-scrollbar-thumb:hover {\n    background: rgba(100, 100, 140, 0.5);\n  }\n} "
  },
  {
    "path": "frontend/src/index.tsx",
    "content": "import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport './index.css';\nimport App from './App';\n\nconst root = ReactDOM.createRoot(\n  document.getElementById('root') as HTMLElement\n);\n\nroot.render(\n  \n    \n  \n); "
  },
  {
    "path": "frontend/src/pages/AuditLogsPage.tsx",
    "content": "import React, { useState, useCallback } from 'react';\nimport { useAuth } from '../contexts/AuthContext';\nimport AuditFilterBar, { AuditFilters } from '../components/AuditFilterBar';\nimport AuditLogTable, { AuditEvent } from '../components/AuditLogTable';\nimport AuditEventDetail from '../components/AuditEventDetail';\nimport AuditStatistics from '../components/AuditStatistics';\nimport { ShieldExclamationIcon, ArrowDownTrayIcon } from '@heroicons/react/24/outline';\n\ninterface AuditLogsPageProps {\n  embedded?: boolean;\n}\n\nconst AuditLogsPage: React.FC = ({ embedded = false }) => {\n  const { user } = useAuth();\n  const [filters, setFilters] = useState({\n    stream: 'registry_api',\n  });\n  const [selectedEvent, setSelectedEvent] = useState(null);\n  const [refreshKey, setRefreshKey] = useState(0);\n\n  const handleFilterChange = useCallback((newFilters: AuditFilters) => {\n    setFilters(newFilters);\n    setSelectedEvent(null);\n  }, []);\n\n  const handleRefresh = useCallback(() => {\n    setRefreshKey((prev) => prev + 1);\n  }, []);\n\n  const handleEventSelect = useCallback((event: AuditEvent) => {\n    setSelectedEvent(event);\n  }, []);\n\n  const handleCloseDetail = useCallback(() => {\n    setSelectedEvent(null);\n  }, []);\n\n  const handleExport = useCallback((format: 'jsonl' | 'csv') => {\n    const params = new URLSearchParams();\n    params.set('stream', filters.stream);\n    params.set('format', format);\n    \n    if (filters.from) {\n      params.set('from', new Date(filters.from).toISOString());\n    }\n    if (filters.to) {\n      params.set('to', new Date(filters.to).toISOString());\n    }\n    if (filters.username) {\n      params.set('username', filters.username);\n    }\n    if (filters.operation) {\n      params.set('operation', filters.operation);\n    }\n    if (filters.resourceType) {\n      params.set('resource_type', filters.resourceType);\n    }\n    if (filters.statusMin !== undefined) {\n      params.set('status_min', filters.statusMin.toString());\n    }\n    if (filters.statusMax !== undefined) {\n      params.set('status_max', filters.statusMax.toString());\n    }\n    \n    // Trigger download by opening the export URL\n    window.open(`/api/audit/export?${params.toString()}`, '_blank');\n  }, [filters]);\n\n  // Check if user is admin\n  if (!user?.is_admin) {\n    return (\n      
\n        
\n          \n          
\n            Access Denied\n          
\n          
\n            You need administrator privileges to view audit logs.\n          
\n        
\n      
\n    );\n  }\n\n  // Embedded mode - no outer container\n  if (embedded) {\n    return (\n      
\n        {/* Page Header */}\n        
\n          
\n            
\n              Audit Logs\n            
\n            
\n              View and search system audit events for compliance and security monitoring.\n            
\n          
\n          
\n             handleExport('jsonl')}\n              className=\"flex items-center gap-2 px-3 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 transition-colors\"\n              title=\"Export as JSONL\"\n            >\n              \n              JSONL\n            \n             handleExport('csv')}\n              className=\"flex items-center gap-2 px-3 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 transition-colors\"\n              title=\"Export as CSV\"\n            >\n              \n              CSV\n            \n          
\n        
\n\n        {/* Filter Bar */}\n        
\n          \n        
\n\n        {/* Statistics Dashboard */}\n        \n\n        {/* Main Content */}\n        
\n          {/* Table - takes 2 columns when detail is shown, full width otherwise */}\n          
\n            \n          
\n\n          {/* Event Detail Panel */}\n          {selectedEvent && (\n            
\n              
\n                \n              
\n            
\n          )}\n        
\n      
\n    );\n  }\n\n  return (\n    
\n      
\n        {/* Page Header */}\n        
\n          
\n            
\n              Audit Logs\n            
\n            
\n              View and search system audit events for compliance and security monitoring.\n            
\n          
\n          
\n             handleExport('jsonl')}\n              className=\"flex items-center gap-2 px-3 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 transition-colors\"\n              title=\"Export as JSONL\"\n            >\n              \n              JSONL\n            \n             handleExport('csv')}\n              className=\"flex items-center gap-2 px-3 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 transition-colors\"\n              title=\"Export as CSV\"\n            >\n              \n              CSV\n            \n          
\n        
\n\n        {/* Filter Bar */}\n        
\n          \n        
\n\n        {/* Statistics Dashboard */}\n        \n\n        {/* Main Content */}\n        
\n          {/* Table - takes 2 columns when detail is shown, full width otherwise */}\n          
\n            \n          
\n\n          {/* Event Detail Panel */}\n          {selectedEvent && (\n            
\n              
\n                \n              
\n            
\n          )}\n        
\n      
\n    
\n  );\n};\n\nexport default AuditLogsPage;\n"
  },
  {
    "path": "frontend/src/pages/Dashboard.tsx",
    "content": "import React, { useState, useMemo, useCallback, useEffect } from 'react';\nimport { useNavigate } from 'react-router-dom';\nimport { MagnifyingGlassIcon, PlusIcon, XMarkIcon, ArrowPathIcon, CheckCircleIcon, ExclamationCircleIcon, ChevronDownIcon, ChevronRightIcon } from '@heroicons/react/24/outline';\nimport { useServerStats } from '../hooks/useServerStats';\nimport { useSkills, Skill } from '../hooks/useSkills';\nimport { useAuth } from '../contexts/AuthContext';\nimport { useRegistryConfig } from '../hooks/useRegistryConfig';\nimport ServerCard from '../components/ServerCard';\nimport AgentCard from '../components/AgentCard';\nimport SkillCard from '../components/SkillCard';\nimport VirtualServerCard from '../components/VirtualServerCard';\nimport SemanticSearchResults from '../components/SemanticSearchResults';\nimport { useSemanticSearch } from '../hooks/useSemanticSearch';\nimport { useVirtualServers, useVirtualServer } from '../hooks/useVirtualServers';\nimport {\n  VirtualServerInfo,\n  CreateVirtualServerRequest,\n  UpdateVirtualServerRequest,\n} from '../types/virtualServer';\nimport VirtualServerForm from '../components/VirtualServerForm';\nimport DiscoverTab from '../components/DiscoverTab';\nimport axios from 'axios';\n\n\ninterface SyncMetadata {\n  is_federated?: boolean;\n  source_peer_id?: string;\n  upstream_path?: string;\n  last_synced_at?: string;\n  is_read_only?: boolean;\n  is_orphaned?: boolean;\n  orphaned_at?: string;\n}\n\ninterface Server {\n  name: string;\n  path: string;\n  description?: string;\n  official?: boolean;\n  enabled: boolean;\n  tags?: string[];\n  last_checked_time?: string;\n  usersCount?: number;\n  rating?: number;\n  status?: 'healthy' | 'healthy-auth-expired' | 'unhealthy' | 'unknown';\n  num_tools?: number;\n  proxy_pass_url?: string;\n  license?: string;\n  mcp_endpoint?: string;\n  metadata?: Record;\n  sync_metadata?: SyncMetadata;\n  auth_scheme?: string;\n  auth_header_name?: string;\n}\n\ninterface Agent {\n  name: string;\n  path: string;\n  url?: string;\n  description?: string;\n  version?: string;\n  visibility?: 'public' | 'private' | 'group-restricted';\n  trust_level?: 'community' | 'verified' | 'trusted' | 'unverified';\n  supported_protocol?: string | null;\n  enabled: boolean;\n  tags?: string[];\n  last_checked_time?: string;\n  usersCount?: number;\n  rating?: number;\n  status?: 'healthy' | 'healthy-auth-expired' | 'unhealthy' | 'unknown';\n  lifecycle_status?: 'active' | 'draft' | 'deprecated' | 'beta';\n  sync_metadata?: SyncMetadata;\n  ans_metadata?: {\n    ans_agent_id: string;\n    status: 'verified' | 'expired' | 'revoked' | 'not_found' | 'pending';\n    domain?: string;\n    organization?: string;\n    certificate?: {\n      not_after?: string;\n      subject_dn?: string;\n      issuer_dn?: string;\n    };\n    last_verified?: string;\n  };\n  registered_by?: string | null;\n}\n\n// Toast notification component\ninterface ToastProps {\n  message: string;\n  type: 'success' | 'error';\n  onClose: () => void;\n}\n\nconst Toast: React.FC = ({ message, type, onClose }) => {\n  useEffect(() => {\n    const timer = setTimeout(() => {\n      onClose();\n    }, 4000);\n    return () => clearTimeout(timer);\n  }, [onClose]);\n\n  return (\n    
\n      
\n        {type === 'success' ? (\n          \n        ) : (\n          \n        )}\n        
{message}
\n        \n          \n        \n      
\n    
\n  );\n};\n\nconst normalizeAgentStatus = (status?: string | null): Agent['status'] => {\n  if (status === 'healthy' || status === 'healthy-auth-expired') {\n    return status;\n  }\n  if (status === 'unhealthy') {\n    return 'unhealthy';\n  }\n  return 'unknown';\n};\n\nconst buildAgentAuthHeaders = (token?: string | null) =>\n  token ? { Authorization: `Bearer ${token}` } : undefined;\n\ninterface DashboardProps {\n  activeFilter?: string;\n  setActiveFilter?: (filter: string) => void;\n  selectedTags?: string[];\n}\n\nconst Dashboard: React.FC = ({ activeFilter = 'all', setActiveFilter, selectedTags = [] }) => {\n  const navigate = useNavigate();\n  const { servers, agents: agentsFromStats, loading, error, refreshData, setServers, setAgents } = useServerStats();\n  const { skills, setSkills, loading: skillsLoading, error: skillsError, refreshData: refreshSkills } = useSkills();\n  const {\n    virtualServers,\n    loading: virtualServersLoading,\n    error: virtualServersError,\n    toggleVirtualServer,\n    deleteVirtualServer,\n    updateVirtualServer,\n    refreshData: refreshVirtualServers,\n  } = useVirtualServers();\n\n  // Virtual server edit modal state\n  const [editingVirtualServerPath, setEditingVirtualServerPath] = useState(undefined);\n  const [showVirtualServerForm, setShowVirtualServerForm] = useState(false);\n  const { virtualServer: editingVirtualServer, loading: editingVirtualServerLoading } = useVirtualServer(editingVirtualServerPath);\n  const { user } = useAuth();\n  const { config: registryConfig } = useRegistryConfig();\n  const [searchTerm, setSearchTerm] = useState('');\n  const [committedQuery, setCommittedQuery] = useState('');\n  const [showRegisterModal, setShowRegisterModal] = useState(false);\n  const [registerForm, setRegisterForm] = useState({\n    name: '',\n    path: '',\n    proxyPass: '',\n    description: '',\n    official: false,\n    tags: [] as string[]\n  });\n  const [registerLoading, setRegisterLoading] = useState(false);\n  const [refreshing, setRefreshing] = useState(false);\n  const [editingServer, setEditingServer] = useState(null);\n  const [editForm, setEditForm] = useState({\n    name: '',\n    path: '',\n    proxyPass: '',\n    description: '',\n    tags: [] as string[],\n    license: 'N/A',\n    num_tools: 0,\n    mcp_endpoint: '',\n    metadata: '',\n    auth_scheme: 'none',\n    auth_credential: '',\n    auth_header_name: 'X-API-Key',\n    status: 'active' as 'active' | 'draft' | 'deprecated' | 'beta',\n  });\n  const [editLoading, setEditLoading] = useState(false);\n  const [toast, setToast] = useState<{ message: string; type: 'success' | 'error' } | null>(null);\n\n  // Agent state management - using agents from useServerStats hook instead of separate fetch\n  // Agents loading state is now handled by the useServerStats hook's 'loading' state\n  const [agentsError, setAgentsError] = useState(null);\n  const [editingAgent, setEditingAgent] = useState(null);\n  const [agentApiToken, setAgentApiToken] = useState(null);\n\n  // View filter state\n  const [viewFilter, setViewFilter] = useState<'discover' | 'servers' | 'agents' | 'skills' | 'virtual' | 'external'>('discover');\n\n  // Reset viewFilter to 'discover' when the active tab is hidden by config\n  useEffect(() => {\n    if (viewFilter === 'virtual' && registryConfig?.features.virtual_servers === false) {\n      setViewFilter('discover');\n    }\n    if (viewFilter === 'agents' && registryConfig?.features.agents === false) {\n      setViewFilter('discover');\n    }\n    if (viewFilter === 'skills' && registryConfig?.features.skills === false) {\n      setViewFilter('discover');\n    }\n    if (viewFilter === 'servers' && registryConfig?.features.mcp_servers === false) {\n      setViewFilter('discover');\n    }\n  }, [viewFilter, registryConfig]);\n\n  // Collapsible state for registry groups (tracks which groups are expanded)\n  // Key is registry name: 'local' or peer registry ID like 'peer-registry-lob-1'\n  const [expandedRegistries, setExpandedRegistries] = useState>({\n    'local': true  // Local registry expanded by default\n  });\n\n  // Toggle a registry group's expanded state\n  const toggleRegistryGroup = useCallback((registryId: string) => {\n    setExpandedRegistries(prev => ({\n      ...prev,\n      [registryId]: !prev[registryId]\n    }));\n  }, []);\n\n  // Store peer registry endpoints for display\n  // Maps peer_id to endpoint URL: { 'peer-registry-lob-1': 'https://mcpregistry.ddns.net', ... }\n  const [peerRegistryEndpoints, setPeerRegistryEndpoints] = useState>({});\n\n  // Track which peer is currently being synced\n  const [syncingPeer, setSyncingPeer] = useState(null);\n\n  // Active source tab within External Registries (null = show all)\n  const [externalSourceTab, setExternalSourceTab] = useState(null);\n\n  // Fetch peer registry configs to get their endpoints\n  useEffect(() => {\n    const fetchPeerEndpoints = async () => {\n      try {\n        const response = await axios.get('/api/peers');\n        const peers = response.data?.peers || response.data || [];\n        const endpoints: Record = {};\n        peers.forEach((peer: { peer_id: string; endpoint: string }) => {\n          if (peer.peer_id && peer.endpoint) {\n            endpoints[peer.peer_id] = peer.endpoint;\n          }\n        });\n        setPeerRegistryEndpoints(endpoints);\n      } catch (error) {\n        // Silently fail - peer endpoints are optional display info\n        console.debug('Could not fetch peer registry endpoints:', error);\n      }\n    };\n    fetchPeerEndpoints();\n  }, []);\n\n  // Get the local registry URL\n  const localRegistryUrl = useMemo(() => {\n    return window.location.origin;\n  }, []);\n\n  const [editAgentForm, setEditAgentForm] = useState({\n    name: '',\n    path: '',\n    url: '',\n    description: '',\n    version: '',\n    visibility: 'private' as 'public' | 'private' | 'group-restricted',\n    allowed_groups: '',\n    trust_level: 'community' as 'community' | 'verified' | 'trusted' | 'unverified',\n    supported_protocol: 'other' as 'a2a' | 'other',\n    tags: [] as string[],\n    skillsJson: '[]',\n    metadata: '',\n    status: 'active' as 'active' | 'draft' | 'deprecated' | 'beta',\n  });\n  const [editAgentLoading, setEditAgentLoading] = useState(false);\n  const [skillsJsonError, setSkillsJsonError] = useState(null);\n\n  // Skill state management\n  const [showSkillModal, setShowSkillModal] = useState(false);\n  const [editingSkill, setEditingSkill] = useState(null);\n  const [skillForm, setSkillForm] = useState({\n    name: '',\n    description: '',\n    skill_md_url: '',\n    repository_url: '',\n    version: '',\n    visibility: 'public' as 'public' | 'private' | 'group',\n    tags: '',  // Raw string, parsed on save\n    target_agents: '',  // Raw string, parsed on save\n    metadata: '',  // JSON string for custom metadata\n    status: 'draft' as 'active' | 'draft' | 'deprecated' | 'beta',\n    auth_scheme: 'none' as 'none' | 'global_credentials' | 'bearer' | 'api_key',\n    auth_credential: '',\n    auth_header_name: '',\n  });\n  const [skillFormLoading, setSkillFormLoading] = useState(false);\n  const [showDeleteSkillConfirm, setShowDeleteSkillConfirm] = useState(null);\n  const [skillAutoFill, setSkillAutoFill] = useState(true);  // Auto-fill from SKILL.md\n  const [skillParseLoading, setSkillParseLoading] = useState(false);\n\n  const handleAgentUpdate = useCallback((path: string, updates: Partial) => {\n    setAgents(prevAgents =>\n      prevAgents.map(agent =>\n        agent.path === path\n          ? { ...agent, ...updates }\n          : agent\n      )\n    );\n  }, [setAgents]);\n\n  const performAgentHealthCheck = useCallback(async (agent: Agent, token?: string | null) => {\n    if (!agent?.path) return;\n\n    const headers = buildAgentAuthHeaders(token);\n    try {\n      const response = await axios.post(\n        `/api/agents${agent.path}/health`,\n        undefined,\n        headers ? { headers } : undefined\n      );\n\n      handleAgentUpdate(agent.path, {\n        status: normalizeAgentStatus(response.data?.status),\n        last_checked_time: response.data?.last_checked_iso || null\n      });\n    } catch (error) {\n      console.error(`Failed to check health for agent ${agent.name}:`, error);\n      handleAgentUpdate(agent.path, {\n        status: 'unhealthy',\n        last_checked_time: new Date().toISOString()\n      });\n    }\n  }, [handleAgentUpdate]);\n\n  const runInitialAgentHealthChecks = useCallback((agentsList: Agent[], token?: string | null) => {\n    const candidates = agentsList.filter(agent => agent.enabled);\n    if (!candidates.length) return;\n\n    Promise.allSettled(candidates.map(agent => performAgentHealthCheck(agent, token))).catch((error) => {\n      console.error('Failed to run agent health checks:', error);\n    });\n  }, [performAgentHealthCheck]);\n\n  // Note: Agents data now comes from useServerStats hook\n  // JWT token generation moved to after agents definition\n\n  // Helper function to check if user has a specific UI permission for a service\n  const hasUiPermission = useCallback((permission: string, servicePath: string): boolean => {\n    const permissions = user?.ui_permissions?.[permission];\n    if (!permissions) return false;\n\n    // Extract service name from path (remove leading slash)\n    const serviceName = servicePath.replace(/^\\//, '');\n\n    // Check if user has 'all' permission or specific service permission\n    return permissions.includes('all') || permissions.includes(serviceName);\n  }, [user?.ui_permissions]);\n\n  // External registry tags - can be configured via environment or constants\n  // Default tags that identify servers from external registries\n  const EXTERNAL_REGISTRY_TAGS = ['anthropic-registry', 'workday-asor', 'asor', 'federated'];\n\n  // Separate internal and external registry servers\n  const internalServers = useMemo(() => {\n    return servers.filter(s => {\n      const serverTags = s.tags || [];\n      return !EXTERNAL_REGISTRY_TAGS.some(tag => serverTags.includes(tag));\n    });\n  }, [servers]);\n\n  const externalServers = useMemo(() => {\n    return servers.filter(s => {\n      const serverTags = s.tags || [];\n      return EXTERNAL_REGISTRY_TAGS.some(tag => serverTags.includes(tag));\n    });\n  }, [servers]);\n\n  // Separate internal and external registry agents\n  // Transform Server[] to Agent[] for agents from useServerStats\n  const agents = useMemo(() => {\n    return agentsFromStats.map((a): Agent => ({\n      name: a.name,\n      path: a.path,\n      description: a.description,\n      enabled: a.enabled,\n      tags: a.tags,\n      rating: a.rating,\n      status: a.status,\n      last_checked_time: a.last_checked_time,\n      usersCount: a.usersCount,\n      url: '',  // Will be populated if needed\n      version: '',\n      visibility: (a.visibility || 'public') as 'public' | 'private' | 'group-restricted',\n      trust_level: (a.trust_level || 'community') as 'community' | 'verified' | 'trusted' | 'unverified',\n      supported_protocol: a.supported_protocol || null,\n      sync_metadata: a.sync_metadata,\n      ans_metadata: a.ans_metadata,\n      registered_by: a.registered_by,\n    }));\n  }, [agentsFromStats]);\n\n  const internalAgents = useMemo(() => {\n    return agents.filter(a => {\n      const agentTags = a.tags || [];\n      return !EXTERNAL_REGISTRY_TAGS.some(tag => agentTags.includes(tag));\n    });\n  }, [agents]);\n\n  const externalAgents = useMemo(() => {\n    return agents.filter(a => {\n      const agentTags = a.tags || [];\n      return EXTERNAL_REGISTRY_TAGS.some(tag => agentTags.includes(tag));\n    });\n  }, [agents]);\n\n  // Separate internal and external skills\n  const externalSkills = useMemo(() => {\n    return skills.filter(s => {\n      const skillTags = s.tags || [];\n      return EXTERNAL_REGISTRY_TAGS.some(tag => skillTags.includes(tag));\n    });\n  }, [skills]);\n\n  // Tag-to-source mapping: which tag identifies which federation source\n  const SOURCE_TAG_MAP: Record = {\n    'anthropic-registry': 'anthropic',\n    'agentcore': 'aws_registry',\n    'asor': 'asor',\n    'workday-asor': 'asor',\n  };\n\n  // Display labels for each source\n  const SOURCE_LABELS: Record = {\n    'anthropic': 'Anthropic',\n    'aws_registry': 'AWS Agent Registry',\n    'asor': 'ASOR',\n  };\n\n  // Detect which external sources exist based on tags in the data\n  const availableExternalSources = useMemo(() => {\n    const sources = new Set();\n    const allExternalItems = [\n      ...externalServers.map(s => s.tags || []),\n      ...externalAgents.map(a => a.tags || []),\n      ...externalSkills.map(s => s.tags || []),\n    ];\n    for (const tags of allExternalItems) {\n      for (const tag of tags) {\n        const source = SOURCE_TAG_MAP[tag];\n        if (source) {\n          sources.add(source);\n        }\n      }\n    }\n    // If AWS Registry has content, show it first; otherwise default order\n    const order = sources.has('aws_registry')\n      ? ['aws_registry', 'anthropic', 'asor']\n      : ['anthropic', 'asor'];\n    return order.filter(s => sources.has(s));\n  }, [externalServers, externalAgents, externalSkills]);\n\n  // Helper: check if an item belongs to a given source based on its tags\n  const _itemMatchesSource = useCallback((tags: string[] | undefined, source: string): boolean => {\n    if (!tags) return false;\n    return tags.some(tag => SOURCE_TAG_MAP[tag] === source);\n  }, []);\n\n  // Auto-select the first available tab when switching to external view\n  // or when available sources change\n  useEffect(() => {\n    if (viewFilter === 'external' && availableExternalSources.length > 0) {\n      if (externalSourceTab === null || !availableExternalSources.includes(externalSourceTab)) {\n        setExternalSourceTab(availableExternalSources[0]);\n      }\n    }\n  }, [viewFilter, availableExternalSources, externalSourceTab]);\n\n  // Group servers by source registry (local vs peer registries) using sync_metadata\n  // Returns a map of registry ID to servers: { 'local': [...], 'peer-registry-lob-1': [...], ... }\n  const serversByRegistry = useMemo(() => {\n    const groups: Record = { 'local': [] };\n\n    internalServers.forEach(server => {\n      // Check if server is from a peer registry using sync_metadata\n      if (server.sync_metadata?.is_federated && server.sync_metadata?.source_peer_id) {\n        const registryId = server.sync_metadata.source_peer_id;\n        if (!groups[registryId]) {\n          groups[registryId] = [];\n        }\n        groups[registryId].push(server);\n      } else {\n        groups['local'].push(server);\n      }\n    });\n\n    return groups;\n  }, [internalServers]);\n\n  // Get sorted list of registry IDs (local first, then peer registries alphabetically)\n  const registryIds = useMemo(() => {\n    const ids = Object.keys(serversByRegistry);\n    return ['local', ...ids.filter(id => id !== 'local').sort()];\n  }, [serversByRegistry]);\n\n  // Group agents by source registry similarly using sync_metadata\n  const agentsByRegistry = useMemo(() => {\n    const groups: Record = { 'local': [] };\n\n    internalAgents.forEach(agent => {\n      // Check if agent is from a peer registry using sync_metadata\n      if (agent.sync_metadata?.is_federated && agent.sync_metadata?.source_peer_id) {\n        const registryId = agent.sync_metadata.source_peer_id;\n        if (!groups[registryId]) {\n          groups[registryId] = [];\n        }\n        groups[registryId].push(agent);\n      } else {\n        groups['local'].push(agent);\n      }\n    });\n\n    return groups;\n  }, [internalAgents]);\n\n  const agentRegistryIds = useMemo(() => {\n    const ids = Object.keys(agentsByRegistry);\n    return ['local', ...ids.filter(id => id !== 'local').sort()];\n  }, [agentsByRegistry]);\n\n  // Semantic search\n  const semanticEnabled = committedQuery.trim().length >= 2;\n  const {\n    results: semanticResults,\n    loading: semanticLoading,\n    error: semanticError\n  } = useSemanticSearch(committedQuery, {\n    minLength: 2,\n    maxResults: 10,\n    enabled: semanticEnabled,\n    tags: selectedTags.length > 0 ? selectedTags : undefined,\n  });\n\n  const semanticServers = semanticResults?.servers ?? [];\n  const semanticTools = semanticResults?.tools ?? [];\n  const semanticAgents = semanticResults?.agents ?? [];\n  const semanticSkills = semanticResults?.skills ?? [];\n  const semanticVirtualServers = semanticResults?.virtual_servers ?? [];\n  const semanticDisplayQuery = semanticResults?.query || committedQuery || searchTerm;\n  const semanticSectionVisible = semanticEnabled;\n  const shouldShowFallbackGrid =\n    semanticSectionVisible &&\n    (Boolean(semanticError) ||\n      (!semanticLoading &&\n        semanticServers.length === 0 &&\n        semanticTools.length === 0 &&\n        semanticAgents.length === 0 &&\n        semanticSkills.length === 0 &&\n        semanticVirtualServers.length === 0));\n\n  // Helper: check if entity has all selected tags (case-insensitive)\n  const matchesSelectedTags = useCallback((entityTags: string[] | undefined) => {\n    if (selectedTags.length === 0) return true;\n    if (!entityTags || entityTags.length === 0) return false;\n    const lowerTags = entityTags.map(t => t.toLowerCase());\n    return selectedTags.every(st => lowerTags.includes(st.toLowerCase()));\n  }, [selectedTags]);\n\n  // Parse #tag tokens from the search term for local filtering\n  const parsedSearch = useMemo(() => {\n    const hashtagPattern = /#([\\w-]+)/g;\n    const hashTags: string[] = [];\n    let match;\n    while ((match = hashtagPattern.exec(searchTerm)) !== null) {\n      hashTags.push(match[1].toLowerCase());\n    }\n    // Remove matched #tag tokens AND any trailing/leading lone # characters\n    const textQuery = searchTerm\n      .replace(/#[\\w-]+/g, '')\n      .replace(/#/g, '')\n      .replace(/\\s+/g, ' ')\n      .trim()\n      .toLowerCase();\n    return { textQuery, hashTags };\n  }, [searchTerm]);\n\n  // Helper: check if entity matches #tag tokens from search term (prefix match while typing)\n  const matchesHashTags = useCallback((entityTags: string[] | undefined) => {\n    if (parsedSearch.hashTags.length === 0) return true;\n    if (!entityTags || entityTags.length === 0) return false;\n    const lowerTags = entityTags.map(t => t.toLowerCase());\n    return parsedSearch.hashTags.every(ht =>\n      lowerTags.some(tag => tag.startsWith(ht))\n    );\n  }, [parsedSearch.hashTags]);\n\n  // Filter servers based on activeFilter, searchTerm, and selectedTags\n  const filteredServers = useMemo(() => {\n    let filtered = internalServers;\n\n    // Apply filter first\n    if (activeFilter === 'enabled') filtered = filtered.filter(s => s.enabled);\n    else if (activeFilter === 'disabled') filtered = filtered.filter(s => !s.enabled);\n    else if (activeFilter === 'unhealthy') filtered = filtered.filter(s => s.status === 'unhealthy');\n\n    // Hide deprecated by default; show all when deprecated toggle is active\n    if (activeFilter !== 'deprecated') {\n      filtered = filtered.filter(s => s.lifecycle_status !== 'deprecated');\n    }\n\n    // Apply sidebar tag filter\n    if (selectedTags.length > 0) {\n      filtered = filtered.filter(s => matchesSelectedTags(s.tags));\n    }\n\n    // Apply #tag and text search from search box\n    if (parsedSearch.hashTags.length > 0) {\n      filtered = filtered.filter(s => matchesHashTags(s.tags));\n    }\n    if (parsedSearch.textQuery) {\n      const query = parsedSearch.textQuery;\n      filtered = filtered.filter(server =>\n        server.name.toLowerCase().includes(query) ||\n        (server.description || '').toLowerCase().includes(query) ||\n        server.path.toLowerCase().includes(query) ||\n        (server.tags || []).some(tag => tag.toLowerCase().includes(query))\n      );\n    }\n\n    return filtered;\n  }, [internalServers, activeFilter, selectedTags, matchesSelectedTags, parsedSearch, matchesHashTags]);\n\n  // Filter external servers based on source tab, searchTerm, and selectedTags\n  const filteredExternalServers = useMemo(() => {\n    let filtered = externalServers;\n\n    // Filter by active source tab\n    if (externalSourceTab) {\n      filtered = filtered.filter(s => _itemMatchesSource(s.tags, externalSourceTab));\n    }\n\n    if (selectedTags.length > 0) {\n      filtered = filtered.filter(s => matchesSelectedTags(s.tags));\n    }\n\n    if (parsedSearch.hashTags.length > 0) {\n      filtered = filtered.filter(s => matchesHashTags(s.tags));\n    }\n    if (parsedSearch.textQuery) {\n      const query = parsedSearch.textQuery;\n      filtered = filtered.filter(server =>\n        server.name.toLowerCase().includes(query) ||\n        (server.description || '').toLowerCase().includes(query) ||\n        server.path.toLowerCase().includes(query) ||\n        (server.tags || []).some(tag => tag.toLowerCase().includes(query))\n      );\n    }\n\n    return filtered;\n  }, [externalServers, externalSourceTab, _itemMatchesSource, selectedTags, matchesSelectedTags, parsedSearch, matchesHashTags]);\n\n  // Filter external agents based on source tab, searchTerm, and selectedTags\n  const filteredExternalAgents = useMemo(() => {\n    let filtered = externalAgents;\n\n    // Filter by active source tab\n    if (externalSourceTab) {\n      filtered = filtered.filter(a => _itemMatchesSource(a.tags, externalSourceTab));\n    }\n\n    if (selectedTags.length > 0) {\n      filtered = filtered.filter(a => matchesSelectedTags(a.tags));\n    }\n\n    if (parsedSearch.hashTags.length > 0) {\n      filtered = filtered.filter(a => matchesHashTags(a.tags));\n    }\n    if (parsedSearch.textQuery) {\n      const query = parsedSearch.textQuery;\n      filtered = filtered.filter(agent =>\n        agent.name.toLowerCase().includes(query) ||\n        (agent.description || '').toLowerCase().includes(query) ||\n        agent.path.toLowerCase().includes(query) ||\n        (agent.tags || []).some(tag => tag.toLowerCase().includes(query))\n      );\n    }\n\n    return filtered;\n  }, [externalAgents, externalSourceTab, _itemMatchesSource, selectedTags, matchesSelectedTags, parsedSearch, matchesHashTags]);\n\n  // Filter external skills based on source tab, searchTerm, and selectedTags\n  const filteredExternalSkills = useMemo(() => {\n    let filtered = externalSkills;\n\n    // Filter by active source tab\n    if (externalSourceTab) {\n      filtered = filtered.filter(s => _itemMatchesSource(s.tags, externalSourceTab));\n    }\n\n    if (selectedTags.length > 0) {\n      filtered = filtered.filter(s => matchesSelectedTags(s.tags));\n    }\n\n    if (parsedSearch.hashTags.length > 0) {\n      filtered = filtered.filter(s => matchesHashTags(s.tags));\n    }\n    if (parsedSearch.textQuery) {\n      const query = parsedSearch.textQuery;\n      filtered = filtered.filter(skill =>\n        skill.name.toLowerCase().includes(query) ||\n        (skill.description || '').toLowerCase().includes(query) ||\n        skill.path.toLowerCase().includes(query) ||\n        (skill.tags || []).some(tag => tag.toLowerCase().includes(query))\n      );\n    }\n\n    return filtered;\n  }, [externalSkills, externalSourceTab, _itemMatchesSource, selectedTags, matchesSelectedTags, parsedSearch, matchesHashTags]);\n\n  // Filter agents based on activeFilter, searchTerm, and selectedTags\n  const filteredAgents = useMemo(() => {\n    let filtered = internalAgents;\n\n    // Apply filter first\n    if (activeFilter === 'enabled') filtered = filtered.filter(a => a.enabled);\n    else if (activeFilter === 'disabled') filtered = filtered.filter(a => !a.enabled);\n    else if (activeFilter === 'unhealthy') filtered = filtered.filter(a => a.status === 'unhealthy');\n\n    // Hide deprecated by default; show all when deprecated toggle is active\n    if (activeFilter !== 'deprecated') {\n      filtered = filtered.filter(a => a.lifecycle_status !== 'deprecated');\n    }\n\n    // Apply sidebar tag filter\n    if (selectedTags.length > 0) {\n      filtered = filtered.filter(a => matchesSelectedTags(a.tags));\n    }\n\n    // Apply #tag and text search from search box\n    if (parsedSearch.hashTags.length > 0) {\n      filtered = filtered.filter(a => matchesHashTags(a.tags));\n    }\n    if (parsedSearch.textQuery) {\n      const query = parsedSearch.textQuery;\n      filtered = filtered.filter(agent =>\n        agent.name.toLowerCase().includes(query) ||\n        (agent.description || '').toLowerCase().includes(query) ||\n        agent.path.toLowerCase().includes(query) ||\n        (agent.tags || []).some(tag => tag.toLowerCase().includes(query))\n      );\n    }\n\n    return filtered;\n  }, [internalAgents, activeFilter, selectedTags, matchesSelectedTags, parsedSearch, matchesHashTags]);\n\n  // Filter skills based on activeFilter, searchTerm, and selectedTags\n  const filteredSkills = useMemo(() => {\n    let filtered = skills;\n\n    // Apply filter first\n    if (activeFilter === 'enabled') filtered = filtered.filter(s => s.is_enabled);\n    else if (activeFilter === 'disabled') filtered = filtered.filter(s => !s.is_enabled);\n\n    // Hide deprecated by default; show all when deprecated toggle is active\n    if (activeFilter !== 'deprecated') {\n      filtered = filtered.filter(s => s.status !== 'deprecated');\n    }\n\n    // Apply sidebar tag filter\n    if (selectedTags.length > 0) {\n      filtered = filtered.filter(s => matchesSelectedTags(s.tags));\n    }\n\n    // Apply #tag and text search from search box\n    if (parsedSearch.hashTags.length > 0) {\n      filtered = filtered.filter(s => matchesHashTags(s.tags));\n    }\n    if (parsedSearch.textQuery) {\n      const query = parsedSearch.textQuery;\n      filtered = filtered.filter(skill =>\n        skill.name.toLowerCase().includes(query) ||\n        (skill.description || '').toLowerCase().includes(query) ||\n        skill.path.toLowerCase().includes(query) ||\n        (skill.tags || []).some(tag => tag.toLowerCase().includes(query)) ||\n        (skill.author || '').toLowerCase().includes(query)\n      );\n    }\n\n    return filtered;\n  }, [skills, activeFilter, selectedTags, matchesSelectedTags, parsedSearch, matchesHashTags]);\n\n  // Filter virtual servers based on activeFilter, searchTerm, and selectedTags\n  const filteredVirtualServers = useMemo(() => {\n    let filtered = virtualServers;\n\n    // Apply filter\n    if (activeFilter === 'enabled') filtered = filtered.filter(s => s.is_enabled);\n    else if (activeFilter === 'disabled') filtered = filtered.filter(s => !s.is_enabled);\n\n    // Apply sidebar tag filter\n    if (selectedTags.length > 0) {\n      filtered = filtered.filter(vs => matchesSelectedTags(vs.tags));\n    }\n\n    // Apply #tag and text search from search box\n    if (parsedSearch.hashTags.length > 0) {\n      filtered = filtered.filter(vs => matchesHashTags(vs.tags));\n    }\n    if (parsedSearch.textQuery) {\n      const query = parsedSearch.textQuery;\n      filtered = filtered.filter(vs =>\n        vs.server_name.toLowerCase().includes(query) ||\n        (vs.description || '').toLowerCase().includes(query) ||\n        vs.path.toLowerCase().includes(query) ||\n        (vs.tags || []).some(tag => tag.toLowerCase().includes(query))\n      );\n    }\n\n    return filtered;\n  }, [virtualServers, activeFilter, selectedTags, matchesSelectedTags, parsedSearch, matchesHashTags]);\n\n  // Virtual server action handlers\n  const handleToggleVirtualServer = useCallback(async (path: string, enabled: boolean) => {\n    try {\n      await toggleVirtualServer(path, enabled);\n      showToast(`Virtual server ${enabled ? 'enabled' : 'disabled'} successfully`, 'success');\n    } catch (err) {\n      console.error('Failed to toggle virtual server:', err);\n      showToast('Failed to toggle virtual server', 'error');\n    }\n  }, [toggleVirtualServer]);\n\n  // State for virtual server delete confirmation on Dashboard\n  const [deleteVirtualServerTarget, setDeleteVirtualServerTarget] = useState(null);\n  const [deleteVirtualServerTypedName, setDeleteVirtualServerTypedName] = useState('');\n  const [deletingVirtualServer, setDeletingVirtualServer] = useState(false);\n\n  const handleDeleteVirtualServer = useCallback((path: string) => {\n    const target = virtualServers.find((vs) => vs.path === path);\n    if (target) {\n      setDeleteVirtualServerTarget(target);\n      setDeleteVirtualServerTypedName('');\n    }\n  }, [virtualServers]);\n\n  const confirmDeleteVirtualServer = useCallback(async () => {\n    if (!deleteVirtualServerTarget || deleteVirtualServerTypedName !== deleteVirtualServerTarget.server_name) return;\n\n    setDeletingVirtualServer(true);\n    try {\n      await deleteVirtualServer(deleteVirtualServerTarget.path);\n      showToast('Virtual server deleted successfully', 'success');\n      notifyDataChanged();\n      setDeleteVirtualServerTarget(null);\n      setDeleteVirtualServerTypedName('');\n    } catch (err) {\n      console.error('Failed to delete virtual server:', err);\n      showToast('Failed to delete virtual server', 'error');\n    } finally {\n      setDeletingVirtualServer(false);\n    }\n  }, [deleteVirtualServerTarget, deleteVirtualServerTypedName, deleteVirtualServer]);\n\n  const handleEditVirtualServer = useCallback((vs: VirtualServerInfo) => {\n    setEditingVirtualServerPath(vs.path);\n    setShowVirtualServerForm(true);\n  }, []);\n\n  const handleSaveVirtualServer = useCallback(async (\n    data: CreateVirtualServerRequest | UpdateVirtualServerRequest\n  ) => {\n    if (!editingVirtualServerPath) return;\n    try {\n      await updateVirtualServer(editingVirtualServerPath, data as UpdateVirtualServerRequest);\n      showToast('Virtual server updated successfully', 'success');\n      notifyDataChanged();\n      setShowVirtualServerForm(false);\n      setEditingVirtualServerPath(undefined);\n      refreshVirtualServers();\n    } catch (err: unknown) {\n      const message = err instanceof Error ? err.message : 'An unexpected error occurred';\n      showToast(`Failed to save virtual server: ${message}`, 'error');\n    }\n  }, [editingVirtualServerPath, updateVirtualServer, refreshVirtualServers]);\n\n  const handleCancelVirtualServerEdit = useCallback(() => {\n    setShowVirtualServerForm(false);\n    setEditingVirtualServerPath(undefined);\n  }, []);\n\n  // Debug logging for filtering\n  console.log('Dashboard filtering debug:');\n  console.log(`Current user:`, user);\n  console.log(`Total servers from hook: ${servers.length}`);\n  console.log(`Total agents from API: ${agents.length}`);\n  console.log(`Active filter: ${activeFilter}`);\n  console.log(`Search term: \"${searchTerm}\"`);\n  console.log(`Filtered servers: ${filteredServers.length}`);\n  console.log(`Filtered agents: ${filteredAgents.length}`);\n\n  useEffect(() => {\n    if (searchTerm.trim().length === 0 && committedQuery.length > 0) {\n      setCommittedQuery('');\n    }\n  }, [searchTerm, committedQuery]);\n\n  // Close any open inline modal on Escape key\n  useEffect(() => {\n    const handleKeyDown = (e: KeyboardEvent) => {\n      if (e.key !== 'Escape') return;\n      if (showVirtualServerForm) { handleCancelVirtualServerEdit(); return; }\n      if (deleteVirtualServerTarget) { setDeleteVirtualServerTarget(null); setDeleteVirtualServerTypedName(''); return; }\n      if (showDeleteSkillConfirm) { setShowDeleteSkillConfirm(null); return; }\n      if (showSkillModal) { setShowSkillModal(false); return; }\n      if (editingAgent) { setEditingAgent(null); return; }\n      if (editingServer) { setEditingServer(null); return; }\n      if (showRegisterModal) { setShowRegisterModal(false); return; }\n    };\n    document.addEventListener('keydown', handleKeyDown);\n    return () => document.removeEventListener('keydown', handleKeyDown);\n  }, [showVirtualServerForm, deleteVirtualServerTarget, showDeleteSkillConfirm, showSkillModal, editingAgent, editingServer, showRegisterModal, handleCancelVirtualServerEdit]);\n\n  const handleSemanticSearch = useCallback(() => {\n    const trimmed = searchTerm.trim();\n    setCommittedQuery(trimmed);\n  }, [searchTerm]);\n\n  const handleClearSearch = useCallback(() => {\n    setSearchTerm('');\n    setCommittedQuery('');\n  }, []);\n\n  const handleChangeViewFilter = useCallback(\n    (filter: typeof viewFilter) => {\n      setViewFilter(filter);\n      if (semanticSectionVisible) {\n        setSearchTerm('');\n        setCommittedQuery('');\n      }\n    },\n    [semanticSectionVisible]\n  );\n\n  // Notify Layout to refresh the sidebar tag list after data changes\n  const notifyDataChanged = useCallback(() => {\n    window.dispatchEvent(new Event('registry-data-changed'));\n  }, []);\n\n  const handleRefreshHealth = async () => {\n    setRefreshing(true);\n    try {\n      await refreshData(); // Refresh both servers and agents from useServerStats\n    } finally {\n      setRefreshing(false);\n    }\n  };\n\n  // Sync a peer registry to fetch latest servers/agents\n  const handleSyncPeer = async (peerId: string, event: React.MouseEvent) => {\n    event.stopPropagation(); // Prevent collapsing the section\n    setSyncingPeer(peerId);\n    try {\n      const response = await axios.post(`/api/peers/${peerId}/sync`);\n      const result = response.data;\n\n      // Check the success field in the response body\n      if (result.success) {\n        setToast({\n          message: `Synced ${result.servers_synced || 0} servers and ${result.agents_synced || 0} agents from ${peerId}`,\n          type: 'success'\n        });\n      } else {\n        // Sync failed - show error message from response\n        setToast({\n          message: result.error_message || `Failed to sync from ${peerId}`,\n          type: 'error'\n        });\n      }\n\n      // Refresh the server list to show updated data\n      await refreshData();\n      notifyDataChanged();\n    } catch (error) {\n      console.error('Failed to sync peer:', error);\n      setToast({ message: `Failed to sync from ${peerId}`, type: 'error' });\n    } finally {\n      setSyncingPeer(null);\n    }\n  };\n\n  const handleEditServer = useCallback(async (server: Server) => {\n    try {\n      // Fetch full server details including proxy_pass_url and tags\n      const response = await axios.get(`/api/server_details${server.path}`);\n      const serverDetails = response.data;\n\n      setEditingServer(server);\n      setEditForm({\n        name: serverDetails.server_name || server.name,\n        path: server.path,\n        proxyPass: serverDetails.proxy_pass_url || '',\n        description: serverDetails.description || '',\n        tags: serverDetails.tags || [],\n        license: serverDetails.license || 'N/A',\n        num_tools: serverDetails.num_tools || 0,\n        mcp_endpoint: serverDetails.mcp_endpoint || '',\n        metadata: serverDetails.metadata ? JSON.stringify(serverDetails.metadata, null, 2) : '',\n        auth_scheme: serverDetails.auth_scheme || 'none',\n        auth_credential: '',\n        auth_header_name: serverDetails.auth_header_name || 'X-API-Key',\n        status: serverDetails.status || 'active',\n      });\n    } catch (error) {\n      console.error('Failed to fetch server details:', error);\n      // Fallback to basic server data\n      setEditingServer(server);\n      setEditForm({\n        name: server.name,\n        path: server.path,\n        proxyPass: '',\n        description: server.description || '',\n        tags: server.tags || [],\n        license: 'N/A',\n        num_tools: server.num_tools || 0,\n        mcp_endpoint: server.mcp_endpoint || '',\n        metadata: server.metadata ? JSON.stringify(server.metadata, null, 2) : '',\n        auth_scheme: server.auth_scheme || 'none',\n        auth_credential: '',\n        auth_header_name: server.auth_header_name || 'X-API-Key',\n        status: (server as any).status || 'active',\n      });\n    }\n  }, []);\n\n  const handleEditAgent = useCallback(async (agent: Agent) => {\n    setEditingAgent(agent);\n    setSkillsJsonError(null);\n\n    // Fetch full agent details to get skills and url\n    try {\n      const headers = agentApiToken ? { Authorization: `Bearer ${agentApiToken}` } : undefined;\n      const response = await axios.get(\n        `/api/agents${agent.path}`,\n        headers ? { headers } : undefined\n      );\n      const fullAgent = response.data;\n\n      setEditAgentForm({\n        name: fullAgent.name || agent.name,\n        path: fullAgent.path || agent.path,\n        url: fullAgent.url || '',\n        description: fullAgent.description || agent.description || '',\n        version: fullAgent.version || agent.version || '1.0.0',\n        visibility: fullAgent.visibility || agent.visibility || 'private',\n        allowed_groups: (fullAgent.allowedGroups || fullAgent.allowed_groups || []).join(', '),\n        trust_level: fullAgent.trust_level || agent.trust_level || 'community',\n        supported_protocol: (fullAgent.supported_protocol || agent.supported_protocol || 'other') as 'a2a' | 'other',\n        tags: fullAgent.tags || agent.tags || [],\n        skillsJson: fullAgent.skills && fullAgent.skills.length > 0\n          ? JSON.stringify(fullAgent.skills, null, 2)\n          : '[]',\n        metadata: fullAgent.metadata && Object.keys(fullAgent.metadata).length > 0\n          ? JSON.stringify(fullAgent.metadata, null, 2)\n          : '',\n        status: (fullAgent.status || agent.lifecycle_status || 'active') as 'active' | 'draft' | 'deprecated' | 'beta',\n      });\n    } catch (error) {\n      console.error('Failed to fetch agent details for editing:', error);\n      // Fall back to basic data from the card\n      setEditAgentForm({\n        name: agent.name,\n        path: agent.path,\n        url: '',\n        description: agent.description || '',\n        version: agent.version || '1.0.0',\n        visibility: agent.visibility || 'private',\n        allowed_groups: '',\n        trust_level: agent.trust_level || 'community',\n        supported_protocol: (agent.supported_protocol || 'other') as 'a2a' | 'other',\n        tags: agent.tags || [],\n        skillsJson: '[]',\n        metadata: '',\n        status: agent.lifecycle_status || 'active',\n      });\n    }\n  }, [agentApiToken]);\n\n  const handleCloseEdit = () => {\n    setEditingServer(null);\n    setEditingAgent(null);\n  };\n\n  const showToast = useCallback((message: string, type: 'success' | 'error' | 'info') => {\n    setToast({ message, type: type === 'info' ? 'success' : type });\n  }, []);\n\n  const hideToast = useCallback(() => {\n    setToast(null);\n  }, []);\n\n  const handleSaveEdit = async () => {\n    if (editLoading || !editingServer) return;\n\n    try {\n      setEditLoading(true);\n\n      const params = new URLSearchParams();\n      params.append('name', editForm.name);\n      params.append('description', editForm.description);\n      params.append('proxy_pass_url', editForm.proxyPass);\n      params.append('tags', editForm.tags.join(','));\n      params.append('license', editForm.license);\n      params.append('num_tools', editForm.num_tools.toString());\n      if (editForm.mcp_endpoint) {\n        params.append('mcp_endpoint', editForm.mcp_endpoint);\n      }\n      if (editForm.metadata) {\n        params.append('metadata', editForm.metadata);\n      }\n      if (editForm.auth_scheme !== 'none') {\n        params.append('auth_scheme', editForm.auth_scheme);\n        if (editForm.auth_credential) {\n          params.append('auth_credential', editForm.auth_credential);\n        }\n        if (editForm.auth_scheme === 'api_key' && editForm.auth_header_name) {\n          params.append('auth_header_name', editForm.auth_header_name);\n        }\n      } else {\n        params.append('auth_scheme', 'none');\n      }\n      params.append('status', editForm.status);\n\n      // Use the correct edit endpoint with the server path\n      await axios.post(`/api/edit${editingServer.path}`, params, {\n        headers: {\n          'Accept': 'application/json',\n          'Content-Type': 'application/x-www-form-urlencoded',\n        },\n      });\n\n      // Refresh server list\n      await refreshData();\n      setEditingServer(null);\n\n      showToast('Server updated successfully!', 'success');\n      notifyDataChanged();\n    } catch (error: any) {\n      console.error('Failed to update server:', error);\n      showToast(error.response?.data?.detail || 'Failed to update server', 'error');\n    } finally {\n      setEditLoading(false);\n    }\n  };\n\n  const handleSaveEditAgent = async () => {\n    if (editAgentLoading || !editingAgent) return;\n\n    // Validate skills JSON before sending\n    let parsedSkills: any[] = [];\n    try {\n      parsedSkills = JSON.parse(editAgentForm.skillsJson);\n      if (!Array.isArray(parsedSkills)) {\n        setSkillsJsonError('Skills must be a JSON array');\n        return;\n      }\n      setSkillsJsonError(null);\n    } catch {\n      setSkillsJsonError('Invalid JSON format');\n      return;\n    }\n\n    try {\n      setEditAgentLoading(true);\n\n      const headers: Record = {\n        'Content-Type': 'application/json',\n      };\n      if (agentApiToken) {\n        headers['Authorization'] = `Bearer ${agentApiToken}`;\n      }\n\n      const payload = {\n        name: editAgentForm.name,\n        description: editAgentForm.description,\n        url: editAgentForm.url,\n        version: editAgentForm.version,\n        visibility: editAgentForm.visibility,\n        allowedGroups: editAgentForm.visibility === 'group-restricted'\n          ? editAgentForm.allowed_groups.split(',').map(g => g.trim()).filter(g => g)\n          : [],\n        trustLevel: editAgentForm.trust_level,\n        supportedProtocol: editAgentForm.supported_protocol,\n        tags: editAgentForm.tags,\n        skills: parsedSkills,\n        status: editAgentForm.status,\n        ...(editAgentForm.metadata.trim() ? { metadata: JSON.parse(editAgentForm.metadata) } : {}),\n      };\n\n      await axios.put(\n        `/api/agents${editingAgent.path}`,\n        payload,\n        { headers },\n      );\n\n      // Trigger security rescan after successful update\n      try {\n        await axios.post(\n          `/api/agents${editingAgent.path}/rescan`,\n          undefined,\n          agentApiToken ? { headers: { Authorization: `Bearer ${agentApiToken}` } } : undefined,\n        );\n      } catch {\n        // Rescan failure is non-blocking (may lack admin privileges)\n      }\n\n      // Refresh the agents list\n      await refreshData();\n\n      setEditingAgent(null);\n      showToast('Agent updated successfully!', 'success');\n    } catch (error: any) {\n      console.error('Failed to update agent:', error);\n      const detail = error.response?.data?.detail;\n      const message = typeof detail === 'object' ? detail.message || JSON.stringify(detail) : detail || 'Failed to update agent';\n      showToast(message, 'error');\n    } finally {\n      setEditAgentLoading(false);\n    }\n  };\n\n  const handleToggleServer = useCallback(async (path: string, enabled: boolean) => {\n    // Optimistically update the UI first\n    setServers(prevServers =>\n      prevServers.map(server =>\n        server.path === path\n          ? { ...server, enabled }\n          : server\n      )\n    );\n\n    try {\n      const formData = new FormData();\n      formData.append('enabled', enabled ? 'on' : 'off');\n\n      await axios.post(`/api/toggle${path}`, formData, {\n        headers: {\n          'Content-Type': 'application/x-www-form-urlencoded',\n        },\n      });\n\n      // No need to refresh all data - the optimistic update is enough\n      showToast(`Server ${enabled ? 'enabled' : 'disabled'} successfully!`, 'success');\n    } catch (error: any) {\n      console.error('Failed to toggle server:', error);\n\n      // Revert the optimistic update on error\n      setServers(prevServers =>\n        prevServers.map(server =>\n          server.path === path\n            ? { ...server, enabled: !enabled }\n            : server\n        )\n      );\n\n      showToast(error.response?.data?.detail || 'Failed to toggle server', 'error');\n    }\n  }, [setServers, showToast]);\n\n  const handleDeleteServer = useCallback(async (path: string) => {\n    const formData = new FormData();\n    formData.append('path', path);\n\n    await axios.post('/api/servers/remove', formData, {\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n    });\n\n    // Remove from local state immediately for responsive UI\n    setServers(prevServers => prevServers.filter(s => s.path !== path));\n    showToast('Server deleted successfully', 'success');\n    notifyDataChanged();\n  }, [setServers, showToast]);\n\n  const handleDeleteAgent = useCallback(async (path: string) => {\n    await axios.delete(`/api/agents${path}`);\n\n    // Remove from local state immediately for responsive UI\n    setAgents(prevAgents => prevAgents.filter(a => a.path !== path));\n    showToast('Agent deleted successfully', 'success');\n    notifyDataChanged();\n  }, [setAgents, showToast]);\n\n  const handleToggleAgent = useCallback(async (path: string, enabled: boolean) => {\n    // Optimistically update the UI first\n    setAgents(prevAgents =>\n      prevAgents.map(agent =>\n        agent.path === path\n          ? { ...agent, enabled }\n          : agent\n      )\n    );\n\n    try {\n      await axios.post(`/api/agents${path}/toggle?enabled=${enabled}`);\n\n      showToast(`Agent ${enabled ? 'enabled' : 'disabled'} successfully!`, 'success');\n    } catch (error: any) {\n      console.error('Failed to toggle agent:', error);\n\n      // Revert the optimistic update on error\n      setAgents(prevAgents =>\n        prevAgents.map(agent =>\n          agent.path === path\n            ? { ...agent, enabled: !enabled }\n            : agent\n        )\n      );\n\n      showToast(error.response?.data?.detail || 'Failed to toggle agent', 'error');\n    }\n  }, [setAgents, showToast]);\n\n  const handleServerUpdate = useCallback((path: string, updates: Partial) => {\n    setServers(prevServers =>\n      prevServers.map(server =>\n        server.path === path\n          ? { ...server, ...updates }\n          : server\n      )\n    );\n  }, [setServers]);\n\n  const handleToggleSkill = useCallback(async (path: string, enabled: boolean) => {\n    // Optimistically update the UI first\n    setSkills(prevSkills =>\n      prevSkills.map(skill =>\n        skill.path === path\n          ? { ...skill, is_enabled: enabled }\n          : skill\n      )\n    );\n\n    try {\n      // Convert full path to API path (e.g., /skills/pdf -> /pdf)\n      const apiPath = path.startsWith('/skills/') ? path.replace('/skills/', '/') : path;\n      await axios.post(`/api/skills${apiPath}/toggle`, { enabled });\n\n      showToast(`Skill ${enabled ? 'enabled' : 'disabled'} successfully!`, 'success');\n    } catch (error: any) {\n      console.error('Failed to toggle skill:', error);\n\n      // Revert the optimistic update on error\n      setSkills(prevSkills =>\n        prevSkills.map(skill =>\n          skill.path === path\n            ? { ...skill, is_enabled: !enabled }\n            : skill\n        )\n      );\n\n      showToast(error.response?.data?.detail || 'Failed to toggle skill', 'error');\n    }\n  }, [setSkills, showToast]);\n\n  const handleSkillUpdate = useCallback((path: string, updates: Partial) => {\n    setSkills(prevSkills =>\n      prevSkills.map(skill =>\n        skill.path === path\n          ? { ...skill, ...updates }\n          : skill\n      )\n    );\n  }, [setSkills]);\n\n  // Skill CRUD handlers\n  const handleOpenSkillModal = useCallback((skill?: Skill) => {\n    if (skill) {\n      // Edit mode - populate form with existing data\n      setEditingSkill(skill);\n      setSkillAutoFill(false);  // Manual mode for editing\n      setSkillForm({\n        name: skill.name,\n        description: skill.description || '',\n        skill_md_url: skill.skill_md_url || '',\n        repository_url: skill.repository_url || '',\n        version: skill.version || '',\n        visibility: skill.visibility || 'public',\n        tags: (skill.tags || []).join(', '),\n        target_agents: (skill.target_agents || []).join(', '),\n        metadata: skill.metadata?.extra ? JSON.stringify(skill.metadata.extra, null, 2) : '',\n        status: (skill.status || 'active') as 'active' | 'draft' | 'deprecated' | 'beta',\n        auth_scheme: (skill.auth_scheme || 'none') as 'none' | 'global_credentials' | 'bearer' | 'api_key',\n        auth_credential: '',\n        auth_header_name: skill.auth_header_name || '',\n      });\n    } else {\n      // Create mode - reset form\n      setEditingSkill(null);\n      setSkillAutoFill(true);  // Auto-fill enabled for new skills\n      setSkillForm({\n        name: '',\n        description: '',\n        skill_md_url: '',\n        repository_url: '',\n        version: '',\n        visibility: 'public',\n        tags: '',\n        target_agents: '',\n        metadata: '',\n        status: 'draft',\n        auth_scheme: 'none',\n        auth_credential: '',\n        auth_header_name: '',\n      });\n    }\n    setShowSkillModal(true);\n  }, []);\n\n  const handleCloseSkillModal = useCallback(() => {\n    setShowSkillModal(false);\n    setEditingSkill(null);\n  }, []);\n\n  const handleParseSkillMd = useCallback(async () => {\n    if (!skillForm.skill_md_url || skillParseLoading) return;\n\n    try {\n      setSkillParseLoading(true);\n      const params = new URLSearchParams({ url: skillForm.skill_md_url });\n      if (skillForm.auth_scheme !== 'none') {\n        params.set('auth_scheme', skillForm.auth_scheme);\n      }\n      if (skillForm.auth_credential && skillForm.auth_scheme !== 'none' && skillForm.auth_scheme !== 'global_credentials') {\n        params.set('auth_credential', skillForm.auth_credential);\n      }\n      if (skillForm.auth_header_name && skillForm.auth_scheme === 'api_key') {\n        params.set('auth_header_name', skillForm.auth_header_name);\n      }\n      const response = await axios.post(`/api/skills/parse-skill-md?${params.toString()}`);\n      const data = response.data;\n\n      if (data.success) {\n        setSkillForm(prev => ({\n          ...prev,\n          name: data.name_slug || prev.name,\n          description: data.description || prev.description,\n          version: data.version || prev.version,\n          tags: data.tags?.length > 0 ? data.tags.join(', ') : prev.tags,\n          repository_url: data.repository_url || prev.repository_url,\n        }));\n        showToast('Parsed SKILL.md successfully!', 'success');\n      } else {\n        showToast('Failed to parse SKILL.md', 'error');\n      }\n    } catch (error: any) {\n      console.error('Failed to parse SKILL.md:', error);\n      showToast(error.response?.data?.detail || 'Failed to parse SKILL.md', 'error');\n    } finally {\n      setSkillParseLoading(false);\n    }\n  }, [skillForm.skill_md_url, skillForm.auth_scheme, skillForm.auth_credential, skillForm.auth_header_name, skillParseLoading, showToast]);\n\n  const handleSaveSkill = useCallback(async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (skillFormLoading) return;\n\n    // Validate name format (lowercase, numbers, hyphens only)\n    const nameRegex = /^[a-z0-9]+(-[a-z0-9]+)*$/;\n    if (!nameRegex.test(skillForm.name)) {\n      showToast('Name must be lowercase letters, numbers, and hyphens only (e.g., \"my-skill-name\")', 'error');\n      return;\n    }\n\n    try {\n      setSkillFormLoading(true);\n\n      // Parse comma-separated strings into arrays\n      const parseTags = (str: string): string[] =>\n        str.split(',').map(t => t.trim()).filter(t => t.length > 0);\n\n      // Parse optional metadata JSON\n      let parsedMetadata: Record | undefined = undefined;\n      if (skillForm.metadata.trim()) {\n        try {\n          parsedMetadata = JSON.parse(skillForm.metadata);\n        } catch {\n          showToast('Invalid JSON in metadata field', 'error');\n          setSkillFormLoading(false);\n          return;\n        }\n      }\n\n      const payload: Record = {\n        name: skillForm.name,\n        description: skillForm.description,\n        skill_md_url: skillForm.skill_md_url,\n        repository_url: skillForm.repository_url || undefined,\n        version: skillForm.version || undefined,\n        visibility: skillForm.visibility,\n        tags: parseTags(skillForm.tags),\n        target_agents: parseTags(skillForm.target_agents),\n        metadata: parsedMetadata,\n        status: skillForm.status,\n        auth_scheme: skillForm.auth_scheme,\n      };\n\n      if (skillForm.auth_scheme !== 'none' && skillForm.auth_scheme !== 'global_credentials') {\n        if (skillForm.auth_credential) {\n          payload.auth_credential = skillForm.auth_credential;\n        }\n        if (skillForm.auth_scheme === 'api_key' && skillForm.auth_header_name) {\n          payload.auth_header_name = skillForm.auth_header_name;\n        }\n      }\n\n      if (editingSkill) {\n        // Update existing skill\n        const skillPath = editingSkill.path.replace(/^\\/skills\\//, '');\n        await axios.put(`/api/skills/${skillPath}`, payload);\n        showToast('Skill updated successfully!', 'success');\n        notifyDataChanged();\n      } else {\n        // Create new skill\n        await axios.post('/api/skills', payload);\n        showToast('Skill registered successfully!', 'success');\n        notifyDataChanged();\n      }\n\n      // Refresh skills list\n      await refreshSkills();\n      handleCloseSkillModal();\n    } catch (error: any) {\n      console.error('Failed to save skill:', error);\n      const errorMsg = error.response?.data?.detail || 'Failed to save skill';\n      showToast(errorMsg, 'error');\n    } finally {\n      setSkillFormLoading(false);\n    }\n  }, [skillForm, skillFormLoading, editingSkill, refreshSkills, showToast, handleCloseSkillModal]);\n\n  const handleEditSkill = useCallback((skill: Skill) => {\n    handleOpenSkillModal(skill);\n  }, [handleOpenSkillModal]);\n\n  const handleDeleteSkill = useCallback(async (path: string) => {\n    try {\n      await axios.delete(`/api/skills${path}`);\n\n      // Remove from local state immediately for responsive UI\n      // path may be shortened (e.g. \"/add\") while s.path is full (e.g. \"/skills/add\")\n      const fullPath = path.startsWith('/skills/') ? path : `/skills${path}`;\n      setSkills(prevSkills => prevSkills.filter(s => s.path !== path && s.path !== fullPath));\n      showToast('Skill deleted successfully', 'success');\n      notifyDataChanged();\n      setShowDeleteSkillConfirm(null);\n    } catch (error: any) {\n      console.error('Failed to delete skill:', error);\n      showToast(error.response?.data?.detail || 'Failed to delete skill', 'error');\n    }\n  }, [setSkills, showToast]);\n\n  const handleRegisterServer = useCallback(() => {\n    navigate('/servers/register');\n  }, [navigate]);\n\n  const handleRegisterSubmit = useCallback(async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (registerLoading) return; // Prevent double submission\n\n    try {\n      setRegisterLoading(true);\n\n      const formData = new FormData();\n      formData.append('name', registerForm.name);\n      formData.append('description', registerForm.description);\n      formData.append('path', registerForm.path);\n      formData.append('proxy_pass_url', registerForm.proxyPass);\n      formData.append('tags', registerForm.tags.join(','));\n      formData.append('license', 'MIT');\n\n      await axios.post('/api/register', formData, {\n        headers: {\n          'Content-Type': 'application/x-www-form-urlencoded',\n        },\n      });\n\n      // Reset form and close modal\n      setRegisterForm({\n        name: '',\n        path: '',\n        proxyPass: '',\n        description: '',\n        official: false,\n        tags: []\n      });\n      setShowRegisterModal(false);\n\n      // Refresh server list\n      await refreshData();\n\n      showToast('Server registered successfully!', 'success');\n      notifyDataChanged();\n    } catch (error: any) {\n      console.error('Failed to register server:', error);\n      showToast(error.response?.data?.detail || 'Failed to register server', 'error');\n    } finally {\n      setRegisterLoading(false);\n    }\n  }, [registerForm, registerLoading, refreshData, showToast]);\n\n  const renderServerGrid = (\n    list: Server[],\n    options?: { emptyTitle?: string; emptySubtitle?: string; showRegisterCta?: boolean }\n  ) => {\n    if (list.length === 0) {\n      const title = options?.emptyTitle ?? 'No servers found';\n      const subtitle =\n        options?.emptySubtitle ??\n        (searchTerm || activeFilter !== 'all'\n          ? 'Press Enter in the search bar to search semantically'\n          : 'No servers are registered yet');\n      const shouldShowCta =\n        options?.showRegisterCta ?? (!searchTerm && activeFilter === 'all');\n\n      return (\n        
\n          
{title}
\n          
{subtitle}
\n          {shouldShowCta && (\n            \n              \n              Register Server\n            \n          )}\n        
\n      );\n    }\n\n    return (\n      \n        {list.map((server) => (\n          \n        ))}\n
\n );\n };\n\n const renderDashboardCollections = () => (\n <>\n {/* MCP Servers Section - Grouped by Registry */}\n {registryConfig?.features.mcp_servers !== false &&\n (viewFilter === 'servers') && (\n
\n
\n

\n MCP Servers\n

\n\n {/* Registry Quick Navigation - Only show if there are multiple registries */}\n {registryIds.length > 1 && filteredServers.length > 0 && (\n
\n Jump to:\n {registryIds.map(registryId => {\n const count = (serversByRegistry[registryId] || []).length;\n if (count === 0) return null;\n const displayName = registryId === 'local'\n ? 'Local'\n : registryId.replace('peer-registry-', '').replace('peer-', '').toUpperCase();\n const isLocal = registryId === 'local';\n\n return (\n {\n // Expand this registry, collapse others (for both servers and agents)\n const newExpanded: Record = {};\n // Update server registry states\n registryIds.forEach(id => {\n newExpanded[id] = (id === registryId);\n });\n // Also update agent registry states to keep them in sync\n agentRegistryIds.forEach(id => {\n newExpanded[`agents-${id}`] = (id === registryId);\n });\n setExpandedRegistries(prev => ({ ...prev, ...newExpanded }));\n // Scroll to the section\n const element = document.getElementById(`server-registry-${registryId}`);\n if (element) {\n element.scrollIntoView({ behavior: 'smooth', block: 'start' });\n }\n }}\n className={`px-3 py-1.5 text-xs font-medium rounded-full transition-all hover:scale-105 ${\n isLocal\n ? 'bg-green-100 text-green-700 hover:bg-green-200 dark:bg-green-900/30 dark:text-green-300 dark:hover:bg-green-900/50 border border-green-200 dark:border-green-700'\n : 'bg-cyan-100 text-cyan-700 hover:bg-cyan-200 dark:bg-cyan-900/30 dark:text-cyan-300 dark:hover:bg-cyan-900/50 border border-cyan-200 dark:border-cyan-700'\n }`}\n >\n {displayName}\n \n {count}\n \n \n );\n })}\n {/* Expand All / Collapse All */}\n
\n {\n const allExpanded = registryIds.every(id => expandedRegistries[id] !== false);\n const newExpanded: Record = {};\n registryIds.forEach(id => {\n newExpanded[id] = !allExpanded;\n });\n setExpandedRegistries(prev => ({ ...prev, ...newExpanded }));\n }}\n className=\"px-2 py-1 text-xs text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 rounded transition-colors\"\n title={registryIds.every(id => expandedRegistries[id] !== false) ? 'Collapse all' : 'Expand all'}\n >\n {registryIds.every(id => expandedRegistries[id] !== false) ? 'Collapse All' : 'Expand All'}\n \n
\n
\n )}\n
\n\n {filteredServers.length === 0 ? (\n
\n
No servers found
\n

\n {selectedTags.length > 0\n ? `No servers match the selected tag${selectedTags.length > 1 ? 's' : ''}`\n : searchTerm || activeFilter !== 'all'\n ? 'Press Enter in the search bar to search semantically'\n : 'No servers are registered yet'}\n

\n {!searchTerm && activeFilter === 'all' && selectedTags.length === 0 && (\n \n \n Register Server\n \n )}\n
\n ) : (\n
\n {registryIds.map(registryId => {\n const registryServers = serversByRegistry[registryId] || [];\n // Apply active filter to registry servers\n let filteredRegistryServers = registryServers;\n if (activeFilter === 'enabled') filteredRegistryServers = registryServers.filter(s => s.enabled);\n else if (activeFilter === 'disabled') filteredRegistryServers = registryServers.filter(s => !s.enabled);\n else if (activeFilter === 'unhealthy') filteredRegistryServers = registryServers.filter(s => s.status === 'unhealthy');\n\n // Apply sidebar tag filter\n if (selectedTags.length > 0) {\n filteredRegistryServers = filteredRegistryServers.filter(s => matchesSelectedTags(s.tags));\n }\n\n // Apply #tag and text search from search box\n if (parsedSearch.hashTags.length > 0) {\n filteredRegistryServers = filteredRegistryServers.filter(s => matchesHashTags(s.tags));\n }\n if (parsedSearch.textQuery) {\n const query = parsedSearch.textQuery;\n filteredRegistryServers = filteredRegistryServers.filter(server =>\n server.name.toLowerCase().includes(query) ||\n (server.description || '').toLowerCase().includes(query) ||\n server.path.toLowerCase().includes(query) ||\n (server.tags || []).some(tag => tag.toLowerCase().includes(query))\n );\n }\n\n if (filteredRegistryServers.length === 0) return null;\n\n const isExpanded = expandedRegistries[registryId] !== false; // Default to expanded\n const displayName = registryId === 'local'\n ? 'Local Registry'\n : registryId.replace('peer-registry-', '').replace('peer-', '').toUpperCase() + ' (Federated)';\n\n // When there's only one registry (local), skip the collapsible wrapper\n const showRegistryHeader = registryIds.length > 1 || registryId !== 'local';\n\n // Render servers without registry header when it's the only registry\n if (!showRegistryHeader) {\n return (\n
\n \n {filteredRegistryServers.map((server) => (\n \n ))}\n {/* Virtual MCP Servers in Local Registry */}\n {filteredVirtualServers.map((vs) => (\n \n ))}\n
\n
\n );\n }\n\n return (\n
\n {/* Collapsible Header */}\n toggleRegistryGroup(registryId)}\n className={`w-full flex items-center justify-between px-4 py-3 text-left transition-colors ${\n registryId === 'local'\n ? 'bg-gradient-to-r from-green-50 to-emerald-50 dark:from-green-900/20 dark:to-emerald-900/20 hover:from-green-100 hover:to-emerald-100 dark:hover:from-green-900/30 dark:hover:to-emerald-900/30'\n : 'bg-gradient-to-r from-cyan-50 to-blue-50 dark:from-cyan-900/20 dark:to-blue-900/20 hover:from-cyan-100 hover:to-blue-100 dark:hover:from-cyan-900/30 dark:hover:to-blue-900/30'\n }`}\n >\n
\n {isExpanded ? (\n \n ) : (\n \n )}\n \n {displayName}\n \n {/* Registry URL */}\n \n | {registryId === 'local' ? localRegistryUrl : (peerRegistryEndpoints[registryId] || 'Loading...')}\n \n \n {registryId === 'local'\n ? `${filteredRegistryServers.length + filteredVirtualServers.length} server${(filteredRegistryServers.length + filteredVirtualServers.length) !== 1 ? 's' : ''}`\n : `${filteredRegistryServers.length} server${filteredRegistryServers.length !== 1 ? 's' : ''}`\n }\n \n {/* Resync button for federated registries */}\n {registryId !== 'local' && (\n handleSyncPeer(registryId, e)}\n disabled={syncingPeer === registryId}\n className=\"ml-2 p-1 text-cyan-600 dark:text-cyan-400 hover:text-cyan-800 dark:hover:text-cyan-200 hover:bg-cyan-100 dark:hover:bg-cyan-900/30 rounded-lg transition-colors disabled:opacity-50\"\n title={`Resync from ${peerRegistryEndpoints[registryId] || registryId}`}\n >\n \n \n )}\n
\n \n\n {/* Collapsible Content */}\n {isExpanded && (\n
\n \n {filteredRegistryServers.map((server) => (\n \n ))}\n {/* Virtual MCP Servers in Local Registry (collapsible view) */}\n {registryId === 'local' && filteredVirtualServers.map((vs) => (\n \n ))}\n
\n
\n )}\n
\n );\n })}\n
\n )}\n
\n )}\n\n {/* Agents Section - Grouped by Registry */}\n {registryConfig?.features.agents !== false &&\n (viewFilter === 'agents') && (\n
\n
\n

\n Agents\n

\n\n {/* Registry Quick Navigation for Agents - Only show if there are multiple registries */}\n {agentRegistryIds.length > 1 && filteredAgents.length > 0 && (\n
\n Jump to:\n {agentRegistryIds.map(registryId => {\n const count = (agentsByRegistry[registryId] || []).length;\n if (count === 0) return null;\n const displayName = registryId === 'local'\n ? 'Local'\n : registryId.replace('peer-registry-', '').replace('peer-', '').toUpperCase();\n const isLocal = registryId === 'local';\n\n return (\n {\n // Expand this registry, collapse others (for both agents and servers)\n const newExpanded: Record = {};\n // Update agent registry states\n agentRegistryIds.forEach(id => {\n newExpanded[`agents-${id}`] = (id === registryId);\n });\n // Also update server registry states to keep them in sync\n registryIds.forEach(id => {\n newExpanded[id] = (id === registryId);\n });\n setExpandedRegistries(prev => ({ ...prev, ...newExpanded }));\n // Scroll to the section\n const element = document.getElementById(`agent-registry-${registryId}`);\n if (element) {\n element.scrollIntoView({ behavior: 'smooth', block: 'start' });\n }\n }}\n className={`px-3 py-1.5 text-xs font-medium rounded-full transition-all hover:scale-105 ${\n isLocal\n ? 'bg-green-100 text-green-700 hover:bg-green-200 dark:bg-green-900/30 dark:text-green-300 dark:hover:bg-green-900/50 border border-green-200 dark:border-green-700'\n : 'bg-violet-100 text-violet-700 hover:bg-violet-200 dark:bg-violet-900/30 dark:text-violet-300 dark:hover:bg-violet-900/50 border border-violet-200 dark:border-violet-700'\n }`}\n >\n {displayName}\n \n {count}\n \n \n );\n })}\n
\n )}\n
\n\n {agentsError ? (\n
\n
Failed to load agents
\n

{agentsError}

\n
\n ) : loading ? (\n
\n
\n
\n ) : filteredAgents.length === 0 ? (\n
\n
No agents found
\n

\n {searchTerm || activeFilter !== 'all'\n ? 'Press Enter in the search bar to search semantically'\n : 'No agents are registered yet'}\n

\n
\n ) : (\n
\n {agentRegistryIds.map(registryId => {\n const registryAgents = agentsByRegistry[registryId] || [];\n // Apply active filter to registry agents\n let filteredRegistryAgents = registryAgents;\n if (activeFilter === 'enabled') filteredRegistryAgents = registryAgents.filter(a => a.enabled);\n else if (activeFilter === 'disabled') filteredRegistryAgents = registryAgents.filter(a => !a.enabled);\n else if (activeFilter === 'unhealthy') filteredRegistryAgents = registryAgents.filter(a => a.status === 'unhealthy');\n\n // Apply sidebar tag filter\n if (selectedTags.length > 0) {\n filteredRegistryAgents = filteredRegistryAgents.filter(a => matchesSelectedTags(a.tags));\n }\n\n // Apply #tag and text search from search box\n if (parsedSearch.hashTags.length > 0) {\n filteredRegistryAgents = filteredRegistryAgents.filter(a => matchesHashTags(a.tags));\n }\n if (parsedSearch.textQuery) {\n const query = parsedSearch.textQuery;\n filteredRegistryAgents = filteredRegistryAgents.filter(agent =>\n agent.name.toLowerCase().includes(query) ||\n (agent.description || '').toLowerCase().includes(query) ||\n agent.path.toLowerCase().includes(query) ||\n (agent.tags || []).some(tag => tag.toLowerCase().includes(query))\n );\n }\n\n if (filteredRegistryAgents.length === 0) return null;\n\n const isExpanded = expandedRegistries[`agents-${registryId}`] !== false; // Default to expanded\n const displayName = registryId === 'local'\n ? 'Local Registry'\n : registryId.replace('peer-registry-', '').replace('peer-', '').toUpperCase() + ' (Federated)';\n\n // When there's only one registry (local), skip the collapsible wrapper\n const showRegistryHeader = agentRegistryIds.length > 1 || registryId !== 'local';\n\n // Render agents without registry header when it's the only registry\n if (!showRegistryHeader) {\n return (\n
\n \n {filteredRegistryAgents.map((agent) => (\n \n ))}\n
\n
\n );\n }\n\n return (\n
\n {/* Collapsible Header */}\n toggleRegistryGroup(`agents-${registryId}`)}\n className={`w-full flex items-center justify-between px-4 py-3 text-left transition-colors ${\n registryId === 'local'\n ? 'bg-gradient-to-r from-green-50 to-emerald-50 dark:from-green-900/20 dark:to-emerald-900/20 hover:from-green-100 hover:to-emerald-100 dark:hover:from-green-900/30 dark:hover:to-emerald-900/30'\n : 'bg-gradient-to-r from-violet-50 to-purple-50 dark:from-violet-900/20 dark:to-purple-900/20 hover:from-violet-100 hover:to-purple-100 dark:hover:from-violet-900/30 dark:hover:to-purple-900/30'\n }`}\n >\n
\n {isExpanded ? (\n \n ) : (\n \n )}\n \n {displayName}\n \n {/* Registry URL */}\n \n | {registryId === 'local' ? localRegistryUrl : (peerRegistryEndpoints[registryId] || 'Loading...')}\n \n \n {filteredRegistryAgents.length} agent{filteredRegistryAgents.length !== 1 ? 's' : ''}\n \n {/* Resync button for federated registries */}\n {registryId !== 'local' && (\n handleSyncPeer(registryId, e)}\n disabled={syncingPeer === registryId}\n className=\"ml-2 p-1 text-violet-600 dark:text-violet-400 hover:text-violet-800 dark:hover:text-violet-200 hover:bg-violet-100 dark:hover:bg-violet-900/30 rounded-lg transition-colors disabled:opacity-50\"\n title={`Resync from ${peerRegistryEndpoints[registryId] || registryId}`}\n >\n \n \n )}\n
\n \n\n {/* Collapsible Content */}\n {isExpanded && (\n
\n \n {filteredRegistryAgents.map((agent) => (\n \n ))}\n
\n
\n )}\n
\n );\n })}\n
\n )}\n \n )}\n\n {/* Agent Skills Section */}\n {registryConfig?.features.skills !== false &&\n (viewFilter === 'skills') && (\n
\n
\n

\n Agent Skills\n

\n {user?.can_modify_servers && (\n handleOpenSkillModal()}\n className=\"inline-flex items-center px-3 py-1.5 text-sm font-medium text-white bg-amber-600 hover:bg-amber-700 rounded-lg transition-colors\"\n >\n \n Add Skill\n \n )}\n
\n\n {skillsError ? (\n
\n
Failed to load skills
\n

{skillsError}

\n
\n ) : skillsLoading ? (\n
\n
\n
\n ) : filteredSkills.length === 0 ? (\n
\n
No skills found
\n

\n {searchTerm || activeFilter !== 'all'\n ? 'Press Enter in the search bar to search semantically'\n : 'No skills are registered yet'}\n

\n {!searchTerm && activeFilter === 'all' && user?.can_modify_servers && (\n handleOpenSkillModal()}\n className=\"mt-4 inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-lg text-white bg-amber-600 hover:bg-amber-700 transition-colors\"\n >\n \n Register Skill\n \n )}\n
\n ) : (\n \n {filteredSkills.map((skill) => (\n setShowDeleteSkillConfirm(path)}\n canModify={user?.can_modify_servers || false}\n canToggle={user?.is_admin || hasUiPermission('toggle_skill', skill.path)}\n onRefreshSuccess={refreshSkills}\n onShowToast={showToast}\n onSkillUpdate={handleSkillUpdate}\n authToken={agentApiToken}\n />\n ))}\n
\n )}\n \n )}\n\n {/* Virtual MCP Servers Section */}\n {registryConfig?.features.virtual_servers !== false &&\n (viewFilter === 'virtual') &&\n (filteredVirtualServers.length > 0 || viewFilter === 'virtual') && (\n
\n
\n

\n Virtual MCP Servers\n

\n {(user?.can_modify_servers || user?.is_admin) && (\n navigate('/settings/virtual-mcp/servers')}\n className=\"inline-flex items-center px-4 py-2 text-sm font-medium text-white bg-teal-600 hover:bg-teal-700 rounded-lg transition-colors\"\n >\n \n Add Virtual Server\n \n )}\n
\n\n {virtualServersError ? (\n
\n
Failed to load virtual servers
\n

{virtualServersError}

\n
\n ) : virtualServersLoading ? (\n
\n
\n
\n ) : filteredVirtualServers.length === 0 ? (\n
\n
No virtual servers found
\n

\n {searchTerm || activeFilter !== 'all'\n ? 'Try adjusting your search or filter'\n : 'No virtual servers are configured yet'}\n

\n
\n ) : (\n \n {filteredVirtualServers.map((vs) => (\n \n ))}\n
\n )}\n \n )}\n\n {/* External Registries Section */}\n {registryConfig?.features.federation !== false && viewFilter === 'external' && (\n
\n

\n External Registries\n

\n\n {/* Source tabs - only show when there are sources */}\n {availableExternalSources.length > 0 && (\n
\n {availableExternalSources.map((source) => (\n setExternalSourceTab(source)}\n className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors ${\n externalSourceTab === source\n ? 'border-green-500 text-green-600 dark:text-green-400'\n : 'border-transparent text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-300 hover:border-gray-300 dark:hover:border-gray-600'\n }`}\n >\n {SOURCE_LABELS[source] || source}\n \n ))}\n
\n )}\n\n {filteredExternalServers.length === 0 && filteredExternalAgents.length === 0 && filteredExternalSkills.length === 0 ? (\n
\n
\n {externalServers.length === 0 && externalAgents.length === 0 && externalSkills.length === 0\n ? 'No External Registries Available'\n : 'No Results Found'}\n
\n

\n {externalServers.length === 0 && externalAgents.length === 0 && externalSkills.length === 0\n ? 'External registry integrations (Anthropic, AWS Agents, and more) will appear here when configured'\n : 'Press Enter in the search bar to search semantically'}\n

\n
\n ) : (\n
\n {/* External Servers */}\n {filteredExternalServers.length > 0 && (\n
\n

\n Servers\n

\n \n {filteredExternalServers.map((server) => (\n \n ))}\n
\n
\n )}\n\n {/* External Agents */}\n {filteredExternalAgents.length > 0 && (\n
\n

\n Agents\n

\n \n {filteredExternalAgents.map((agent) => (\n \n ))}\n
\n
\n )}\n\n {/* External Skills */}\n {filteredExternalSkills.length > 0 && (\n
\n

\n Skills\n

\n \n {filteredExternalSkills.map((skill) => (\n setShowDeleteSkillConfirm(path)}\n canModify={user?.can_modify_servers || false}\n canToggle={user?.is_admin || hasUiPermission('toggle_skill', skill.path)}\n onRefreshSuccess={refreshSkills}\n onShowToast={showToast}\n onSkillUpdate={handleSkillUpdate}\n />\n ))}\n
\n \n )}\n \n )}\n \n )}\n\n {/* Empty state when all are filtered out */}\n {((viewFilter === 'servers' && filteredServers.length === 0) ||\n (viewFilter === 'agents' && filteredAgents.length === 0) ||\n (viewFilter === 'skills' && filteredSkills.length === 0) ||\n (viewFilter === 'virtual' && filteredVirtualServers.length === 0)) &&\n (searchTerm || activeFilter !== 'all' || selectedTags.length > 0) && (\n
\n
No items found
\n

\n {selectedTags.length > 0\n ? `No items match the selected tag${selectedTags.length > 1 ? 's' : ''}: ${selectedTags.join(', ')}`\n : 'Press Enter in the search bar to search semantically'}\n

\n
\n )}\n \n );\n\n // Show error state\n if (error && agentsError) {\n return (\n
\n
Failed to load servers and agents
\n

{error}

\n

{agentsError}

\n \n Try Again\n \n
\n );\n }\n\n // Show loading state\n if (loading) {\n return (\n
\n
\n
\n );\n }\n\n return (\n <>\n {/* Toast Notification */}\n {toast && (\n \n )}\n\n
\n {/* Fixed Header Section */}\n
\n {/* View Filter Tabs - conditionally show based on registry mode */}\n {/* Calculate if multiple features are enabled to determine if \"All\" tab is needed */}\n
\n handleChangeViewFilter('discover')}\n className={`px-4 py-2 text-sm font-medium whitespace-nowrap transition-colors border-b-2 ${\n viewFilter === 'discover'\n ? 'border-indigo-500 text-indigo-600 dark:text-indigo-400'\n : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'\n }`}\n >\n Discover\n \n {registryConfig?.features.mcp_servers !== false && (\n handleChangeViewFilter('servers')}\n className={`px-4 py-2 text-sm font-medium whitespace-nowrap transition-colors border-b-2 ${\n viewFilter === 'servers'\n ? 'border-blue-500 text-blue-600 dark:text-blue-400'\n : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'\n }`}\n >\n MCP Servers\n \n )}\n {registryConfig?.features.virtual_servers !== false && (\n handleChangeViewFilter('virtual')}\n className={`px-4 py-2 text-sm font-medium whitespace-nowrap transition-colors border-b-2 ${\n viewFilter === 'virtual'\n ? 'border-teal-500 text-teal-600 dark:text-teal-400'\n : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'\n }`}\n >\n Virtual MCP Servers\n \n )}\n {registryConfig?.features.agents !== false && (\n handleChangeViewFilter('agents')}\n className={`px-4 py-2 text-sm font-medium whitespace-nowrap transition-colors border-b-2 ${\n viewFilter === 'agents'\n ? 'border-cyan-500 text-cyan-600 dark:text-cyan-400'\n : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'\n }`}\n >\n Agents\n \n )}\n {registryConfig?.features.skills !== false && (\n handleChangeViewFilter('skills')}\n className={`px-4 py-2 text-sm font-medium whitespace-nowrap transition-colors border-b-2 ${\n viewFilter === 'skills'\n ? 'border-amber-500 text-amber-600 dark:text-amber-400'\n : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'\n }`}\n >\n Agent Skills\n \n )}\n {registryConfig?.features.federation !== false && (\n handleChangeViewFilter('external')}\n className={`px-4 py-2 text-sm font-medium whitespace-nowrap transition-colors border-b-2 ${\n viewFilter === 'external'\n ? 'border-green-500 text-green-600 dark:text-green-400'\n : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'\n }`}\n >\n External Registries\n \n )}\n
\n\n {viewFilter !== 'discover' && (\n <>\n {/* Search Bar and Refresh Button */}\n
\n
\n
\n \n
\n setSearchTerm(e.target.value)}\n onKeyDown={(e) => {\n if (e.key === 'Enter') {\n e.preventDefault();\n handleSemanticSearch();\n }\n }}\n />\n {searchTerm && (\n \n \n \n )}\n
\n\n {viewFilter !== 'skills' && viewFilter !== 'virtual' && (\n \n \n Register\n \n )}\n\n \n \n Refresh Health\n \n
\n\n {/* Results count and lifecycle filter chips */}\n
\n
\n

\n {semanticSectionVisible ? (\n <>\n Showing {semanticServers.length} servers, {semanticAgents.length} agents\n \n ) : (\n <>\n Showing{' '}\n {registryConfig?.features.mcp_servers !== false && (\n <>{filteredServers.length} servers\n )}\n {registryConfig?.features.mcp_servers !== false && registryConfig?.features.agents !== false && ', '}\n {registryConfig?.features.agents !== false && (\n <>{filteredAgents.length} agents\n )}\n {(registryConfig?.features.mcp_servers !== false || registryConfig?.features.agents !== false) && registryConfig?.features.skills !== false && ', '}\n {registryConfig?.features.skills !== false && (\n <>{filteredSkills.length} skills\n )}\n \n )}\n

\n
\n

\n Press Enter to run semantic search; typing filters locally.\n

\n
\n \n )}\n
\n\n {/* Scrollable Content Area */}\n
\n {viewFilter === 'discover' ? (\n \n ) : (\n <>\n {semanticSectionVisible ? (\n <>\n \n\n {shouldShowFallbackGrid && (\n
\n
\n

\n Keyword search fallback\n

\n {semanticError && (\n \n Showing local matches because semantic search is unavailable\n \n )}\n
\n {renderDashboardCollections()}\n
\n )}\n \n ) : (\n renderDashboardCollections()\n )}\n \n )}\n
\n\n {/* Padding at bottom for scroll */}\n
\n
\n\n {/* Register Server Modal */}\n {showRegisterModal && (\n
\n
\n
\n
\n

\n Register New Server\n

\n setShowRegisterModal(false)}\n className=\"text-gray-400 hover:text-gray-600 dark:hover:text-gray-300\"\n >\n \n \n
\n\n
\n
\n \n setRegisterForm(prev => ({ ...prev, name: e.target.value }))}\n placeholder=\"e.g., My Custom Server\"\n />\n
\n\n
\n \n setRegisterForm(prev => ({ ...prev, path: e.target.value }))}\n placeholder=\"/my-server\"\n />\n
\n\n
\n \n setRegisterForm(prev => ({ ...prev, proxyPass: e.target.value }))}\n placeholder=\"http://localhost:8080\"\n />\n
\n\n
\n \n setRegisterForm(prev => ({ ...prev, description: e.target.value }))}\n placeholder=\"Brief description of the server\"\n />\n
\n\n
\n \n setRegisterForm(prev => ({ ...prev, tags: e.target.value.split(',').map(t => t.trim()).filter(t => t) }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n placeholder=\"tag1,tag2,tag3\"\n />\n
\n
\n\n
\n setShowRegisterModal(false)}\n className=\"flex-1 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-md transition-colors\"\n >\n Cancel\n \n \n {registerLoading ? 'Registering...' : 'Register Server'}\n \n
\n
\n
\n
\n )}\n\n {/* Edit Server Modal */}\n {editingServer && (\n
\n
\n

\n Edit Server: {editingServer.name}\n

\n\n {\n e.preventDefault();\n await handleSaveEdit();\n }}\n className=\"space-y-4\"\n >\n
\n \n setEditForm(prev => ({ ...prev, name: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n required\n />\n
\n\n
\n \n setEditForm(prev => ({ ...prev, proxyPass: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n placeholder=\"http://localhost:8080\"\n required\n />\n
\n\n
\n \n setEditForm(prev => ({ ...prev, description: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n rows={3}\n placeholder=\"Brief description of the server\"\n />\n
\n\n
\n \n setEditForm(prev => ({ ...prev, status: e.target.value as 'active' | 'draft' | 'deprecated' | 'beta' }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n >\n \n \n \n \n \n
\n\n
\n \n setEditForm(prev => ({ ...prev, tags: e.target.value.split(',').map(t => t.trim()).filter(t => t) }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n placeholder=\"tag1,tag2,tag3\"\n />\n
\n\n
\n
\n \n setEditForm(prev => ({ ...prev, num_tools: parseInt(e.target.value) || 0 }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n min=\"0\"\n />\n
\n
\n\n
\n \n setEditForm(prev => ({ ...prev, license: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n placeholder=\"MIT, Apache-2.0, etc.\"\n />\n
\n\n
\n \n setEditForm(prev => ({ ...prev, mcp_endpoint: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n placeholder=\"Custom MCP endpoint URL (overrides default)\"\n />\n
\n\n
\n \n setEditForm(prev => ({ ...prev, metadata: e.target.value }))}\n rows={4}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500 font-mono text-sm\"\n placeholder='{\"team\": \"platform\", \"owner\": \"alice@example.com\"}'\n />\n
\n\n {/* Backend Authentication */}\n
\n

\n Backend Authentication\n

\n\n
\n
\n \n {\n const newScheme = e.target.value;\n setEditForm(prev => ({\n ...prev,\n auth_scheme: newScheme,\n auth_credential: newScheme === 'none' ? '' : prev.auth_credential,\n auth_header_name: newScheme === 'api_key' ? prev.auth_header_name : 'X-API-Key',\n }));\n }}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n >\n \n \n \n \n
\n\n {editForm.auth_scheme !== 'none' && (\n
\n \n setEditForm(prev => ({ ...prev, auth_credential: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n placeholder=\"Leave blank to keep current credential\"\n />\n

\n Leave blank to keep the existing credential unchanged.\n

\n
\n )}\n\n {editForm.auth_scheme === 'api_key' && (\n
\n \n setEditForm(prev => ({ ...prev, auth_header_name: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\"\n placeholder=\"X-API-Key\"\n />\n
\n )}\n
\n
\n\n
\n \n \n
\n\n
\n \n {editLoading ? 'Saving...' : 'Save Changes'}\n \n \n Cancel\n \n
\n \n
\n
\n )}\n\n {/* Edit Agent Modal */}\n {editingAgent && (\n
\n
\n

\n Edit Agent: {editingAgent.name}\n

\n\n {\n e.preventDefault();\n await handleSaveEditAgent();\n }}\n className=\"space-y-4\"\n >\n
\n \n setEditAgentForm(prev => ({ ...prev, name: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n required\n />\n
\n\n
\n \n setEditAgentForm(prev => ({ ...prev, description: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n rows={3}\n placeholder=\"Brief description of the agent\"\n />\n
\n\n
\n \n setEditAgentForm(prev => ({ ...prev, status: e.target.value as 'active' | 'draft' | 'deprecated' | 'beta' }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n >\n \n \n \n \n \n
\n\n
\n \n setEditAgentForm(prev => ({ ...prev, version: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n placeholder=\"1.0.0\"\n />\n
\n\n
\n \n setEditAgentForm(prev => ({ ...prev, visibility: e.target.value as 'public' | 'private' | 'group-restricted' }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n >\n \n \n \n \n
\n\n {editAgentForm.visibility === 'group-restricted' && (\n
\n \n setEditAgentForm(prev => ({ ...prev, allowed_groups: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n placeholder=\"e.g. finance-team, engineering\"\n />\n

\n Comma-separated list of groups that can access this agent\n

\n {editAgentForm.allowed_groups.trim() === '' && (\n

\n At least one group is required for group-restricted visibility\n

\n )}\n
\n )}\n\n
\n \n setEditAgentForm(prev => ({ ...prev, trust_level: e.target.value as 'community' | 'verified' | 'trusted' | 'unverified' }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n >\n \n \n \n \n \n
\n\n
\n \n setEditAgentForm(prev => ({ ...prev, supported_protocol: e.target.value as 'a2a' | 'other' }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n >\n \n \n \n
\n\n
\n \n setEditAgentForm(prev => ({ ...prev, tags: e.target.value.split(',').map(t => t.trim()).filter(t => t) }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500\"\n placeholder=\"tag1,tag2,tag3\"\n />\n
\n\n
\n \n setEditAgentForm(prev => ({ ...prev, metadata: e.target.value }))}\n rows={4}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-cyan-500 focus:border-cyan-500 font-mono text-sm\"\n placeholder='{\"team\": \"platform\", \"owner\": \"alice@example.com\", \"cost_center\": \"CC-1001\"}'\n />\n

\n Custom key-value pairs for organization, compliance, or integration purposes\n

\n
\n\n
\n \n {\n setEditAgentForm(prev => ({ ...prev, skillsJson: e.target.value }));\n setSkillsJsonError(null);\n }}\n className={`block w-full px-3 py-2 border rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white font-mono text-xs focus:ring-cyan-500 focus:border-cyan-500 ${\n skillsJsonError\n ? 'border-red-500 dark:border-red-400'\n : 'border-gray-300 dark:border-gray-600'\n }`}\n rows={8}\n placeholder='[{\"id\": \"skill-1\", \"name\": \"My Skill\", \"description\": \"What this skill does\"}]'\n />\n {skillsJsonError && (\n

{skillsJsonError}

\n )}\n

\n Each skill needs at least: id, name, description. Saving triggers a security rescan.\n

\n
\n\n
\n \n \n
\n\n
\n \n {editAgentLoading ? 'Saving...' : 'Save Changes'}\n \n \n Cancel\n \n
\n \n
\n
\n )}\n\n {/* Register/Edit Skill Modal */}\n {showSkillModal && (\n
\n
\n

\n {editingSkill ? `Edit Skill: ${editingSkill.name}` : 'Register New Skill'}\n

\n\n \n {/* Auto-fill toggle - only for new skills */}\n {!editingSkill && (\n
\n
\n \n Auto-fill from SKILL.md\n \n

\n Parse name and description from the SKILL.md file\n

\n
\n setSkillAutoFill(!skillAutoFill)}\n className={`relative inline-flex h-6 w-11 items-center rounded-full transition-colors ${\n skillAutoFill ? 'bg-amber-600' : 'bg-gray-300 dark:bg-gray-600'\n }`}\n >\n \n \n
\n )}\n\n {/* SKILL.md URL with Parse button */}\n
\n \n
\n setSkillForm(prev => ({ ...prev, skill_md_url: e.target.value }))}\n className=\"flex-1 px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder=\"https://raw.githubusercontent.com/org/repo/main/SKILL.md\"\n required\n />\n {skillAutoFill && !editingSkill && (\n \n {skillParseLoading ? 'Parsing...' : 'Parse'}\n \n )}\n
\n

\n Use raw content URL (e.g., raw.githubusercontent.com)\n

\n
\n\n {/* Name field */}\n
\n \n {\n const formatted = e.target.value\n .toLowerCase()\n .replace(/[^a-z0-9-]/g, '-')\n .replace(/-+/g, '-')\n .replace(/^-|-$/g, '');\n setSkillForm(prev => ({ ...prev, name: formatted }));\n }}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder=\"my-skill-name\"\n pattern=\"^[a-z0-9]+(-[a-z0-9]+)*$\"\n title=\"Lowercase alphanumeric with hyphens (e.g., my-skill-name)\"\n required\n disabled={!!editingSkill}\n />\n

\n Lowercase letters, numbers, and hyphens only\n

\n
\n\n {/* Description field */}\n
\n \n setSkillForm(prev => ({ ...prev, description: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n rows={3}\n placeholder=\"Describe what this skill does and when to use it\"\n required\n />\n
\n\n {/* Repository URL */}\n
\n \n setSkillForm(prev => ({ ...prev, repository_url: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder=\"https://github.com/org/repo\"\n />\n
\n\n {/* Version field */}\n
\n \n setSkillForm(prev => ({ ...prev, version: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder=\"1.0.0\"\n />\n
\n\n
\n \n setSkillForm(prev => ({ ...prev, visibility: e.target.value as 'public' | 'private' | 'group' }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n >\n \n \n \n \n
\n\n
\n \n setSkillForm(prev => ({ ...prev, status: e.target.value as 'active' | 'draft' | 'deprecated' | 'beta' }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n >\n \n \n \n \n \n
\n\n
\n \n setSkillForm(prev => ({ ...prev, tags: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder=\"automation, productivity, code-review\"\n />\n

\n Comma-separated tags for categorization\n

\n
\n\n
\n \n setSkillForm(prev => ({ ...prev, target_agents: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder=\"claude-code, cursor, windsurf\"\n />\n

\n Comma-separated list of compatible coding assistants\n

\n
\n\n {/* Source Authentication */}\n
\n \n {\n const newScheme = e.target.value as 'none' | 'global_credentials' | 'bearer' | 'api_key';\n setSkillForm(prev => ({\n ...prev,\n auth_scheme: newScheme,\n auth_credential: (newScheme === 'none' || newScheme === 'global_credentials') ? '' : prev.auth_credential,\n auth_header_name: newScheme === 'api_key' ? prev.auth_header_name : '',\n }));\n }}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n >\n \n \n \n \n \n

\n How the registry authenticates when fetching SKILL.md from the source\n

\n {skillAutoFill && skillForm.auth_scheme === 'global_credentials' && skillForm.skill_md_url && (\n \n {skillParseLoading ? 'Parsing...' : 'Re-parse with global credentials'}\n \n )}\n
\n\n {(skillForm.auth_scheme === 'bearer' || skillForm.auth_scheme === 'api_key') && (\n
\n \n
\n setSkillForm(prev => ({ ...prev, auth_credential: e.target.value }))}\n className=\"flex-1 px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder={editingSkill ? 'Leave blank to keep existing credential' : (skillForm.auth_scheme === 'bearer' ? 'Enter bearer token (e.g., ghp_...)' : 'Enter API key')}\n />\n {skillAutoFill && skillForm.skill_md_url && skillForm.auth_credential && (\n \n {skillParseLoading ? 'Parsing...' : 'Re-parse'}\n \n )}\n
\n

\n Encrypted before storage. Never displayed after saving.\n

\n
\n )}\n\n {skillForm.auth_scheme === 'api_key' && (\n
\n \n setSkillForm(prev => ({ ...prev, auth_header_name: e.target.value }))}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500\"\n placeholder=\"PRIVATE-TOKEN\"\n />\n

\n HTTP header name for the API key (default: PRIVATE-TOKEN)\n

\n
\n )}\n\n
\n \n setSkillForm(prev => ({ ...prev, metadata: e.target.value }))}\n rows={4}\n className=\"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-amber-500 focus:border-amber-500 font-mono text-sm\"\n placeholder='{\"category\": \"data-processing\", \"framework\": \"langchain\"}'\n />\n

\n Key-value pairs in JSON format for searchable custom metadata\n

\n
\n\n {editingSkill && (\n
\n \n \n
\n )}\n\n
\n \n {skillFormLoading\n ? (editingSkill ? 'Saving...' : 'Registering & Scanning...')\n : (editingSkill ? 'Save Changes' : 'Register Skill')}\n \n \n Cancel\n \n
\n {!editingSkill && (\n

\n Registration includes a security scan and may take a few seconds\n

\n )}\n \n
\n
\n )}\n\n {/* Delete Skill Confirmation Modal */}\n {showDeleteSkillConfirm && (\n
\n
\n

\n Delete Skill\n

\n

\n Are you sure you want to delete this skill? This action cannot be undone.\n

\n
\n handleDeleteSkill(showDeleteSkillConfirm)}\n className=\"flex-1 px-4 py-2 text-sm font-medium text-white bg-red-600 hover:bg-red-700 rounded-md transition-colors\"\n >\n Delete\n \n setShowDeleteSkillConfirm(null)}\n className=\"flex-1 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-md transition-colors\"\n >\n Cancel\n \n
\n
\n
\n )}\n\n {/* Virtual Server Delete Confirmation Modal */}\n {deleteVirtualServerTarget && (\n \n
\n

\n Delete Virtual Server\n

\n

\n This action is irreversible. The virtual server and all its tool\n mappings will be permanently removed.\n

\n

\n Type {deleteVirtualServerTarget.server_name} to confirm:\n

\n setDeleteVirtualServerTypedName(e.target.value)}\n placeholder={deleteVirtualServerTarget.server_name}\n disabled={deletingVirtualServer}\n className=\"w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg\n bg-white dark:bg-gray-900 text-gray-900 dark:text-white mb-4\"\n onKeyDown={(e) => {\n if (e.key === 'Escape') {\n setDeleteVirtualServerTarget(null);\n setDeleteVirtualServerTypedName('');\n }\n }}\n autoFocus\n />\n
\n {\n setDeleteVirtualServerTarget(null);\n setDeleteVirtualServerTypedName('');\n }}\n disabled={deletingVirtualServer}\n className=\"px-4 py-2 bg-gray-200 dark:bg-gray-700 text-gray-800 dark:text-gray-200\n rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600 disabled:opacity-50\"\n >\n Cancel\n \n \n {deletingVirtualServer && (\n \n )}\n Delete\n \n
\n
\n \n )}\n\n {/* Virtual Server Edit Modal */}\n {showVirtualServerForm && (\n \n
\n {editingVirtualServerLoading ? (\n
\n
\n Loading virtual server...\n
\n ) : editingVirtualServer ? (\n \n ) : (\n
\n

Failed to load virtual server

\n \n Close\n \n
\n )}\n
\n \n )}\n\n \n );\n};\n\nexport default Dashboard;\n" }, { "path": "frontend/src/pages/Login.tsx", "content": "import React, { useState, useEffect } from 'react';\nimport { useSearchParams } from 'react-router-dom';\nimport axios from 'axios';\nimport { ExclamationTriangleIcon } from '@heroicons/react/24/outline';\n\ninterface OAuthProvider {\n name: string;\n display_name: string;\n icon?: string;\n}\n\nconst Login: React.FC = () => {\n const [error, setError] = useState('');\n const [oauthProviders, setOauthProviders] = useState([]);\n const [authServerUrl, setAuthServerUrl] = useState('');\n const [searchParams] = useSearchParams();\n\n useEffect(() => {\n console.log('[Login] Component mounted, fetching OAuth providers...');\n fetchAuthConfig();\n fetchOAuthProviders();\n\n // Check for error parameter from URL (e.g., from OAuth callback)\n const urlError = searchParams.get('error');\n if (urlError) {\n setError(decodeURIComponent(urlError));\n }\n }, [searchParams]);\n\n const fetchAuthConfig = async () => {\n try {\n const response = await axios.get('/api/auth/config');\n setAuthServerUrl(response.data.auth_server_url || '');\n } catch (error) {\n console.error('Failed to fetch auth config:', error);\n // Fallback to localhost for development\n setAuthServerUrl('http://localhost:8888');\n }\n };\n\n // Log when oauthProviders state changes\n useEffect(() => {\n console.log('[Login] oauthProviders state changed:', oauthProviders);\n }, [oauthProviders]);\n\n const fetchOAuthProviders = async () => {\n try {\n console.log('[Login] Fetching OAuth providers from /api/auth/providers');\n // Call the registry auth providers endpoint\n const response = await axios.get('/api/auth/providers');\n console.log('[Login] Response received:', response.data);\n console.log('[Login] Providers:', response.data.providers);\n setOauthProviders(response.data.providers || []);\n console.log('[Login] State updated with', response.data.providers?.length || 0, 'providers');\n } catch (error) {\n console.error('[Login] Failed to fetch OAuth providers:', error);\n }\n };\n\n const handleOAuthLogin = (provider: string) => {\n const currentOrigin = window.location.origin;\n // Get the base path from the tag or default to '/'\n const baseElement = document.querySelector('base');\n const basePath = baseElement?.getAttribute('href') || '/';\n const redirectUri = encodeURIComponent(currentOrigin + basePath);\n\n // Use the auth server URL from config, fallback to localhost if not loaded yet\n const authUrl = authServerUrl || 'http://localhost:8888';\n window.location.href = `${authUrl}/oauth2/login/${provider}?redirect_uri=${redirectUri}`;\n };\n\n return (\n
\n
\n

\n Sign in to AI Gateway & Registry\n

\n

\n Access your AI management dashboard\n

\n
\n\n
\n
\n {error && (\n
\n \n {error}\n
\n )}\n\n {/* OAuth Providers */}\n {oauthProviders.length > 0 && (\n
\n {oauthProviders.map((provider) => (\n handleOAuthLogin(provider.name)}\n className=\"w-full flex items-center justify-center px-4 py-3 border border-gray-300 dark:border-gray-600 rounded-lg shadow-sm text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 hover:bg-gray-50 dark:hover:bg-gray-600 transition-all duration-200 hover:shadow-md\"\n >\n Continue with {provider.display_name}\n \n ))}\n
\n )}\n\n {/* Fallback when no providers are configured */}\n {oauthProviders.length === 0 && (\n
\n

\n No login methods are currently configured.\n

\n

\n Please contact your administrator.\n

\n
\n )}\n
\n
\n
\n );\n};\n\nexport default Login;\n" }, { "path": "frontend/src/pages/Logout.tsx", "content": "import React, { useEffect } from 'react';\nimport { useNavigate } from 'react-router-dom';\nimport { CheckCircleIcon } from '@heroicons/react/24/outline';\n\nconst Logout: React.FC = () => {\n const navigate = useNavigate();\n\n useEffect(() => {\n // Auto redirect to login after 5 seconds\n const timer = setTimeout(() => {\n navigate('/login');\n }, 5000);\n\n return () => clearTimeout(timer);\n }, [navigate]);\n\n return (\n
\n
\n
\n \n
\n

\n Successfully Logged Out\n

\n

\n You have been logged out from all sessions\n

\n
\n\n
\n
\n
\n

\n Your session has been terminated and you've been logged out from the identity provider.\n

\n\n
\n navigate('/login')}\n className=\"w-full flex justify-center py-3 px-4 border border-transparent rounded-lg shadow-sm text-sm font-medium text-white bg-purple-600 hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-purple-500 transition-all duration-200 hover:shadow-md\"\n >\n Return to Login\n \n
\n\n

\n Redirecting to login in 5 seconds...\n

\n
\n
\n\n
\n

\n AI Gateway & Registry - Secure Access Management\n

\n
\n
\n
\n );\n};\n\nexport default Logout;\n" }, { "path": "frontend/src/pages/OAuthCallback.tsx", "content": "import React, { useEffect } from 'react';\nimport { useNavigate, useSearchParams } from 'react-router-dom';\nimport { useAuth } from '../contexts/AuthContext';\n\nconst OAuthCallback: React.FC = () => {\n const navigate = useNavigate();\n const [searchParams] = useSearchParams();\n const { user, loading } = useAuth();\n\n useEffect(() => {\n // Check if there's an error parameter from the auth server\n const error = searchParams.get('error');\n const errorDetails = searchParams.get('details');\n\n if (error) {\n // Redirect to login with error message\n const errorMessage = errorDetails ? `${error}: ${errorDetails}` : error;\n navigate(`/login?error=${encodeURIComponent(errorMessage)}`, { replace: true });\n return;\n }\n\n // If no error and not loading, check authentication status\n if (!loading) {\n if (user) {\n // User is authenticated, redirect to dashboard\n navigate('/', { replace: true });\n } else {\n // User is not authenticated, redirect to login\n navigate('/login?error=oauth2_session_invalid', { replace: true });\n }\n }\n }, [user, loading, navigate, searchParams]);\n\n // Show loading spinner while checking authentication\n return (\n
\n
\n

\n Completing authentication...\n

\n
\n );\n};\n\nexport default OAuthCallback; " }, { "path": "frontend/src/pages/RegisterPage.tsx", "content": "import React, { useState, useCallback, useEffect } from 'react';\nimport { useNavigate } from 'react-router-dom';\nimport {\n ArrowLeftIcon,\n CloudArrowUpIcon,\n DocumentTextIcon,\n ServerIcon,\n CpuChipIcon,\n CheckCircleIcon,\n ExclamationCircleIcon,\n XMarkIcon,\n InformationCircleIcon,\n} from '@heroicons/react/24/outline';\nimport axios from 'axios';\nimport { useAuth } from '../contexts/AuthContext';\n\n\n// Toast notification component\ninterface ToastProps {\n message: string;\n type: 'success' | 'error';\n onClose: () => void;\n}\n\nconst Toast: React.FC = ({ message, type, onClose }) => {\n useEffect(() => {\n const timer = setTimeout(() => {\n onClose();\n }, 4000);\n return () => clearTimeout(timer);\n }, [onClose]);\n\n return (\n
\n
\n {type === 'success' ? (\n \n ) : (\n \n )}\n

{message}

\n \n \n \n
\n
\n );\n};\n\n\ntype RegistrationType = 'server' | 'agent';\ntype RegistrationMode = 'form' | 'json';\n\n\ninterface ServerFormData {\n name: string;\n description: string;\n path: string;\n proxy_pass_url: string;\n tags: string;\n visibility: string;\n repository_url: string;\n mcp_endpoint: string;\n sse_endpoint: string;\n metadata: string;\n auth_scheme: string;\n auth_credential: string;\n auth_header_name: string;\n status: string;\n provider_organization: string;\n provider_url: string;\n source_created_at: string;\n source_updated_at: string;\n}\n\n\ninterface AgentFormData {\n name: string;\n description: string;\n url: string;\n path: string;\n protocol_version: string;\n version: string;\n tags: string;\n capabilities: string;\n visibility: string;\n allowed_groups: string;\n repository_url: string;\n streaming: boolean;\n status: string;\n provider_organization: string;\n provider_url: string;\n ans_agent_id: string;\n source_created_at: string;\n source_updated_at: string;\n skills: Record[];\n default_input_modes: string[];\n default_output_modes: string[];\n security_schemes: Record | null;\n supported_protocol: string;\n trust_level: string;\n metadata: string;\n}\n\n\ninterface FormErrors {\n [key: string]: string;\n}\n\n\nconst initialServerForm: ServerFormData = {\n name: '',\n description: '',\n path: '',\n proxy_pass_url: '',\n tags: '',\n visibility: 'public',\n repository_url: '',\n mcp_endpoint: '',\n sse_endpoint: '',\n metadata: '',\n auth_scheme: 'none',\n auth_credential: '',\n auth_header_name: 'X-API-Key',\n status: 'active',\n provider_organization: '',\n provider_url: '',\n source_created_at: '',\n source_updated_at: '',\n};\n\n\nconst initialAgentForm: AgentFormData = {\n name: '',\n description: '',\n url: '',\n path: '',\n protocol_version: '1.0',\n version: '1.0.0',\n tags: '',\n capabilities: '',\n visibility: 'public',\n allowed_groups: '',\n repository_url: '',\n streaming: false,\n status: 'active',\n provider_organization: '',\n provider_url: '',\n ans_agent_id: '',\n source_created_at: '',\n source_updated_at: '',\n skills: [],\n default_input_modes: [],\n default_output_modes: [],\n security_schemes: null,\n supported_protocol: 'other',\n trust_level: 'community',\n metadata: '',\n};\n\n\nconst RegisterPage: React.FC = () => {\n const navigate = useNavigate();\n const { user } = useAuth();\n const [registrationType, setRegistrationType] = useState('server');\n const [registrationMode, setRegistrationMode] = useState('form');\n const [serverForm, setServerForm] = useState(initialServerForm);\n const [agentForm, setAgentForm] = useState(initialAgentForm);\n const [jsonContent, setJsonContent] = useState('');\n const [errors, setErrors] = useState({});\n const [loading, setLoading] = useState(false);\n const [toast, setToast] = useState<{ message: string; type: 'success' | 'error' } | null>(null);\n\n\n const generatePath = useCallback((name: string): string => {\n if (!name) return '';\n const slug = name\n .toLowerCase()\n .replace(/[^a-z0-9]+/g, '-')\n .replace(/^-|-$/g, '');\n return `/${slug}`;\n }, []);\n\n\n const handleServerNameChange = useCallback((name: string) => {\n setServerForm(prev => ({\n ...prev,\n name,\n path: prev.path || generatePath(name),\n }));\n }, [generatePath]);\n\n\n const handleAgentNameChange = useCallback((name: string) => {\n setAgentForm(prev => ({\n ...prev,\n name,\n path: prev.path || generatePath(name),\n }));\n }, [generatePath]);\n\n\n const validateServerForm = useCallback((): boolean => {\n const newErrors: FormErrors = {};\n\n if (!serverForm.name.trim()) {\n newErrors.name = 'Server name is required';\n }\n\n if (!serverForm.description.trim()) {\n newErrors.description = 'Description is required';\n }\n\n if (!serverForm.path.trim()) {\n newErrors.path = 'Path is required';\n } else if (!serverForm.path.startsWith('/')) {\n newErrors.path = 'Path must start with /';\n }\n\n if (!serverForm.proxy_pass_url.trim()) {\n newErrors.proxy_pass_url = 'Proxy URL is required';\n } else {\n try {\n new URL(serverForm.proxy_pass_url);\n } catch {\n newErrors.proxy_pass_url = 'Invalid URL format';\n }\n }\n\n setErrors(newErrors);\n return Object.keys(newErrors).length === 0;\n }, [serverForm]);\n\n\n const validateAgentForm = useCallback((): boolean => {\n const newErrors: FormErrors = {};\n\n if (!agentForm.name.trim()) {\n newErrors.name = 'Agent name is required';\n }\n\n if (!agentForm.description.trim()) {\n newErrors.description = 'Description is required';\n }\n\n if (!agentForm.url.trim()) {\n newErrors.url = 'Agent URL is required';\n } else {\n try {\n const url = new URL(agentForm.url);\n if (!['http:', 'https:'].includes(url.protocol)) {\n newErrors.url = 'URL must use HTTP or HTTPS protocol';\n }\n } catch {\n newErrors.url = 'Invalid URL format';\n }\n }\n\n if (agentForm.path && !agentForm.path.startsWith('/')) {\n newErrors.path = 'Path must start with /';\n }\n\n setErrors(newErrors);\n return Object.keys(newErrors).length === 0;\n }, [agentForm]);\n\n\n const handleFileUpload = useCallback((event: React.ChangeEvent) => {\n const file = event.target.files?.[0];\n if (!file) return;\n\n const reader = new FileReader();\n reader.onload = (e) => {\n try {\n const content = e.target?.result as string;\n const parsed = JSON.parse(content);\n setJsonContent(JSON.stringify(parsed, null, 2));\n\n // Auto-populate form fields from JSON\n if (registrationType === 'server') {\n // Helper to convert ISO timestamp to datetime-local format\n const toDatetimeLocal = (isoString: string) => {\n if (!isoString) return '';\n try {\n const date = new Date(isoString);\n return date.toISOString().slice(0, 16);\n } catch {\n return '';\n }\n };\n\n setServerForm(prev => ({\n ...prev,\n name: parsed.server_name || parsed.name || prev.name,\n description: parsed.description || prev.description,\n path: parsed.path || prev.path,\n proxy_pass_url: parsed.proxy_pass_url || parsed.proxyPassUrl || prev.proxy_pass_url,\n tags: Array.isArray(parsed.tags) ? parsed.tags.join(',') : (parsed.tags || prev.tags),\n visibility: parsed.visibility || prev.visibility,\n repository_url: parsed.repository_url || parsed.repositoryUrl || prev.repository_url,\n mcp_endpoint: parsed.mcp_endpoint || parsed.mcpEndpoint || prev.mcp_endpoint,\n sse_endpoint: parsed.sse_endpoint || parsed.sseEndpoint || prev.sse_endpoint,\n metadata: parsed.metadata ? JSON.stringify(parsed.metadata, null, 2) : prev.metadata,\n status: parsed.status || prev.status,\n provider_organization: parsed.provider_organization || prev.provider_organization,\n provider_url: parsed.provider_url || prev.provider_url,\n source_created_at: toDatetimeLocal(parsed.source_created_at) || prev.source_created_at,\n source_updated_at: toDatetimeLocal(parsed.source_updated_at) || prev.source_updated_at,\n }));\n } else {\n // Helper to convert ISO timestamp to datetime-local format\n const toDatetimeLocal = (isoString: string) => {\n if (!isoString) return '';\n try {\n const date = new Date(isoString);\n return date.toISOString().slice(0, 16);\n } catch {\n return '';\n }\n };\n\n // Extract URL: top-level \"url\" or from \"supportedInterfaces[0].url\"\n const agentUrl = parsed.url\n || parsed.supportedInterfaces?.[0]?.url\n || '';\n\n // Extract protocol version from top-level or supportedInterfaces\n const protoVersion = parsed.protocol_version\n || parsed.protocolVersion\n || parsed.supportedInterfaces?.[0]?.protocolVersion\n || '';\n\n setAgentForm(prev => ({\n ...prev,\n name: parsed.name || prev.name,\n description: parsed.description || prev.description,\n url: agentUrl || prev.url,\n path: parsed.path || prev.path,\n protocol_version: protoVersion || prev.protocol_version,\n version: parsed.version || prev.version,\n tags: Array.isArray(parsed.tags) ? parsed.tags.join(',') : (parsed.tags || prev.tags),\n capabilities: parsed.capabilities ? JSON.stringify(parsed.capabilities) : prev.capabilities,\n metadata: parsed.metadata ? JSON.stringify(parsed.metadata, null, 2) : prev.metadata,\n visibility: parsed.visibility || prev.visibility,\n allowed_groups: Array.isArray(parsed.allowedGroups || parsed.allowed_groups)\n ? (parsed.allowedGroups || parsed.allowed_groups).join(', ')\n : prev.allowed_groups,\n repository_url: parsed.repository_url || parsed.repositoryUrl || prev.repository_url,\n streaming: parsed.streaming || parsed.capabilities?.streaming || prev.streaming,\n status: parsed.status || prev.status,\n provider_organization: parsed.provider?.organization || parsed.provider_organization || prev.provider_organization,\n provider_url: parsed.provider?.url || parsed.provider_url || prev.provider_url,\n ans_agent_id: parsed.ans_agent_id || prev.ans_agent_id,\n source_created_at: toDatetimeLocal(parsed.source_created_at) || prev.source_created_at,\n source_updated_at: toDatetimeLocal(parsed.source_updated_at) || prev.source_updated_at,\n skills: Array.isArray(parsed.skills) ? parsed.skills : prev.skills,\n default_input_modes: parsed.defaultInputModes || parsed.default_input_modes || prev.default_input_modes,\n default_output_modes: parsed.defaultOutputModes || parsed.default_output_modes || prev.default_output_modes,\n security_schemes: parsed.securitySchemes || parsed.security_schemes || prev.security_schemes,\n supported_protocol: parsed.supportedProtocol || parsed.supported_protocol || prev.supported_protocol,\n }));\n }\n\n setToast({ message: 'JSON file loaded successfully', type: 'success' });\n } catch {\n setToast({ message: 'Invalid JSON file', type: 'error' });\n }\n };\n reader.readAsText(file);\n }, [registrationType]);\n\n\n const handleServerSubmit = useCallback(async (e: React.FormEvent) => {\n e.preventDefault();\n if (loading) return;\n\n if (!validateServerForm()) return;\n\n setLoading(true);\n\n try {\n const formData = new FormData();\n formData.append('name', serverForm.name);\n formData.append('description', serverForm.description);\n formData.append('path', serverForm.path);\n formData.append('proxy_pass_url', serverForm.proxy_pass_url);\n formData.append('tags', serverForm.tags);\n if (serverForm.mcp_endpoint) {\n formData.append('mcp_endpoint', serverForm.mcp_endpoint);\n }\n if (serverForm.sse_endpoint) {\n formData.append('sse_endpoint', serverForm.sse_endpoint);\n }\n if (serverForm.metadata) {\n formData.append('metadata', serverForm.metadata);\n }\n if (serverForm.auth_scheme !== 'none') {\n formData.append('auth_scheme', serverForm.auth_scheme);\n if (serverForm.auth_credential) {\n formData.append('auth_credential', serverForm.auth_credential);\n }\n if (serverForm.auth_scheme === 'api_key' && serverForm.auth_header_name) {\n formData.append('auth_header_name', serverForm.auth_header_name);\n }\n }\n\n // Add new lifecycle and federation fields\n if (serverForm.status) {\n formData.append('status', serverForm.status);\n }\n if (serverForm.provider_organization) {\n formData.append('provider_organization', serverForm.provider_organization);\n }\n if (serverForm.provider_url) {\n formData.append('provider_url', serverForm.provider_url);\n }\n if (serverForm.source_created_at) {\n formData.append('source_created_at', serverForm.source_created_at);\n }\n if (serverForm.source_updated_at) {\n formData.append('source_updated_at', serverForm.source_updated_at);\n }\n\n await axios.post('/api/register', formData, {\n headers: {\n 'Content-Type': 'application/x-www-form-urlencoded',\n },\n });\n\n setToast({ message: 'Server registered successfully!', type: 'success' });\n setTimeout(() => navigate('/'), 1500);\n } catch (error: unknown) {\n const axiosError = error as { response?: { data?: { detail?: string; error?: string; reason?: string } } };\n const message = axiosError.response?.data?.error\n || axiosError.response?.data?.reason\n || axiosError.response?.data?.detail\n || 'Failed to register server';\n setToast({ message, type: 'error' });\n } finally {\n setLoading(false);\n }\n }, [loading, serverForm, validateServerForm, navigate]);\n\n\n const handleAgentSubmit = useCallback(async (e: React.FormEvent) => {\n e.preventDefault();\n if (loading) return;\n\n if (!validateAgentForm()) return;\n\n setLoading(true);\n\n try {\n const payload = {\n name: agentForm.name,\n description: agentForm.description,\n url: agentForm.url,\n path: agentForm.path || undefined,\n protocolVersion: agentForm.protocol_version,\n version: agentForm.version,\n tags: agentForm.tags,\n visibility: agentForm.visibility,\n allowedGroups: agentForm.visibility === 'group-restricted'\n ? agentForm.allowed_groups.split(',').map(g => g.trim()).filter(g => g)\n : [],\n streaming: agentForm.streaming,\n status: agentForm.status || 'active',\n provider: agentForm.provider_organization ? {\n organization: agentForm.provider_organization,\n url: agentForm.provider_url || agentForm.url,\n } : undefined,\n source_created_at: agentForm.source_created_at || undefined,\n source_updated_at: agentForm.source_updated_at || undefined,\n ans_agent_id: agentForm.ans_agent_id || undefined,\n skills: agentForm.skills.length > 0 ? agentForm.skills : undefined,\n defaultInputModes: agentForm.default_input_modes.length > 0 ? agentForm.default_input_modes : undefined,\n defaultOutputModes: agentForm.default_output_modes.length > 0 ? agentForm.default_output_modes : undefined,\n securitySchemes: agentForm.security_schemes || undefined,\n supportedProtocol: agentForm.supported_protocol,\n trustLevel: agentForm.trust_level,\n ...(agentForm.metadata.trim() ? { metadata: JSON.parse(agentForm.metadata) } : {}),\n };\n\n await axios.post('/api/agents/register', payload, {\n headers: {\n 'Content-Type': 'application/json',\n },\n });\n\n setToast({ message: 'Agent registered successfully!', type: 'success' });\n setTimeout(() => navigate('/'), 1500);\n } catch (error: unknown) {\n const axiosError = error as { response?: { data?: { detail?: string | { message?: string } } } };\n let message = 'Failed to register agent';\n if (axiosError.response?.data?.detail) {\n if (typeof axiosError.response.data.detail === 'string') {\n message = axiosError.response.data.detail;\n } else if (axiosError.response.data.detail.message) {\n message = axiosError.response.data.detail.message;\n }\n }\n setToast({ message, type: 'error' });\n } finally {\n setLoading(false);\n }\n }, [loading, agentForm, validateAgentForm, navigate]);\n\n\n const inputClass = \"block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-700 text-gray-900 dark:text-white focus:ring-purple-500 focus:border-purple-500\";\n const labelClass = \"block text-sm font-medium text-gray-700 dark:text-gray-200 mb-1\";\n const errorClass = \"mt-1 text-sm text-red-500 dark:text-red-400\";\n\n\n const renderServerForm = () => (\n
\n
\n {/* Required Fields */}\n
\n

\n Required\n Basic Information\n

\n
\n\n
\n \n handleServerNameChange(e.target.value)}\n placeholder=\"e.g., My Custom Server\"\n />\n {errors.name &&

{errors.name}

}\n
\n\n
\n \n setServerForm(prev => ({ ...prev, path: e.target.value }))}\n placeholder=\"/my-server\"\n />\n

Auto-generated from name, but can be customized

\n {errors.path &&

{errors.path}

}\n
\n\n
\n \n setServerForm(prev => ({ ...prev, proxy_pass_url: e.target.value }))}\n placeholder=\"http://localhost:8080\"\n />\n {errors.proxy_pass_url &&

{errors.proxy_pass_url}

}\n
\n\n
\n \n setServerForm(prev => ({ ...prev, description: e.target.value }))}\n placeholder=\"Brief description of the server and its capabilities\"\n />\n {errors.description &&

{errors.description}

}\n
\n\n {/* Optional Fields */}\n
\n

\n Optional\n Additional Settings\n

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, tags: e.target.value }))}\n placeholder=\"tag1, tag2, tag3\"\n />\n

Comma-separated list

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, visibility: e.target.value }))}\n >\n \n \n \n \n
\n\n
\n \n setServerForm(prev => ({ ...prev, repository_url: e.target.value }))}\n placeholder=\"https://github.com/username/repo\"\n />\n
\n\n {/* Backend Authentication */}\n
\n

\n Optional\n Backend Authentication\n

\n

\n Configure credentials the gateway will use when proxying requests to your backend MCP server.\n

\n
\n\n
\n \n {\n const newScheme = e.target.value;\n setServerForm(prev => ({\n ...prev,\n auth_scheme: newScheme,\n auth_credential: newScheme === 'none' ? '' : prev.auth_credential,\n auth_header_name: newScheme === 'api_key' ? prev.auth_header_name : 'X-API-Key',\n }));\n }}\n >\n \n \n \n \n
\n\n {serverForm.auth_scheme !== 'none' && (\n
\n \n setServerForm(prev => ({ ...prev, auth_credential: e.target.value }))}\n placeholder={serverForm.auth_scheme === 'bearer' ? 'Enter bearer token' : 'Enter API key'}\n />\n

\n This credential is stored securely and never displayed after saving.\n

\n
\n )}\n\n {serverForm.auth_scheme === 'api_key' && (\n
\n \n setServerForm(prev => ({ ...prev, auth_header_name: e.target.value }))}\n placeholder=\"X-API-Key\"\n />\n

\n The HTTP header name used to send the API key (default: X-API-Key)\n

\n
\n )}\n\n {/* Advanced Settings */}\n
\n

\n Advanced\n Custom Endpoints & Metadata\n

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, mcp_endpoint: e.target.value }))}\n placeholder=\"http://server.com/custom-mcp-path\"\n />\n

Override default /mcp endpoint path

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, sse_endpoint: e.target.value }))}\n placeholder=\"http://server.com/custom-sse-path\"\n />\n

Override default /sse endpoint path

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, metadata: e.target.value }))}\n placeholder='{\"team\": \"platform\", \"owner\": \"alice@example.com\", \"cost_center\": \"CC-1001\"}'\n />\n

Custom key-value pairs for organization, compliance, or integration purposes

\n
\n
\n\n {/* Lifecycle & Provider Information */}\n
\n
\n

\n Lifecycle & Provider Information\n

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, status: e.target.value }))}\n >\n \n \n \n \n \n

Lifecycle status of this server

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, provider_organization: e.target.value }))}\n placeholder=\"ACME Inc.\"\n />\n

Organization providing this server

\n
\n\n
\n \n setServerForm(prev => ({ ...prev, provider_url: e.target.value }))}\n placeholder=\"https://example.com\"\n />\n

Provider's website or documentation URL

\n
\n\n
\n\n
\n navigate('/')}\n className=\"px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-md transition-colors\"\n >\n Cancel\n \n \n {loading ? 'Registering...' : 'Register Server'}\n \n
\n
\n );\n\n\n const renderAgentForm = () => (\n
\n
\n {/* Required Fields */}\n
\n

\n Required\n Basic Information\n

\n
\n\n
\n \n handleAgentNameChange(e.target.value)}\n placeholder=\"e.g., My AI Agent\"\n />\n {errors.name &&

{errors.name}

}\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, path: e.target.value }))}\n placeholder=\"/my-agent\"\n />\n

Leave empty to auto-generate from name

\n {errors.path &&

{errors.path}

}\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, url: e.target.value }))}\n placeholder=\"https://my-agent.example.com\"\n />\n

The endpoint URL where the agent can be reached

\n {errors.url &&

{errors.url}

}\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, description: e.target.value }))}\n placeholder=\"Describe what your agent does and its capabilities\"\n />\n {errors.description &&

{errors.description}

}\n
\n\n {/* Supported Protocol */}\n
\n \n
\n \n
\n

\n Check if this agent implements the\n \n A2A (Agent-to-Agent) protocol\n .\n The A2A agent card schema is used for all agents as a standardized representation.\n

\n
\n\n {/* Optional Fields */}\n
\n

\n Optional\n Additional Settings\n

\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, protocol_version: e.target.value }))}\n placeholder=\"1.0\"\n />\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, version: e.target.value }))}\n placeholder=\"1.0.0\"\n />\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, tags: e.target.value }))}\n placeholder=\"ai, assistant, nlp\"\n />\n

Comma-separated list

\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, metadata: e.target.value }))}\n placeholder='{\"team\": \"platform\", \"owner\": \"alice@example.com\", \"cost_center\": \"CC-1001\"}'\n />\n

\n Custom key-value pairs for organization, compliance, or integration purposes\n

\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, visibility: e.target.value }))}\n >\n \n \n \n \n
\n\n {agentForm.visibility === 'group-restricted' && (\n
\n \n setAgentForm(prev => ({ ...prev, allowed_groups: e.target.value }))}\n placeholder=\"e.g. finance-team, engineering\"\n />\n

\n Comma-separated list of groups that can access this agent\n

\n {agentForm.allowed_groups.trim() === '' && (\n

\n At least one group is required for group-restricted visibility\n

\n )}\n
\n )}\n\n {/* Trust Level */}\n
\n \n setAgentForm(prev => ({ ...prev, trust_level: e.target.value }))}\n className={inputClass}\n >\n \n \n \n \n \n
\n\n
\n \n
\n\n
\n \n setAgentForm(prev => ({ ...prev, repository_url: e.target.value }))}\n placeholder=\"https://github.com/username/repo\"\n />\n
\n
\n\n {/* Lifecycle & Provider Information */}\n
\n
\n

\n Lifecycle & Provider Information\n

\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, status: e.target.value }))}\n >\n \n \n \n \n \n

Lifecycle status of this agent

\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, provider_organization: e.target.value }))}\n placeholder=\"ACME Inc.\"\n />\n

Organization providing this agent

\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, provider_url: e.target.value }))}\n placeholder=\"https://example.com\"\n />\n

Provider's website or documentation URL

\n
\n\n
\n \n setAgentForm(prev => ({ ...prev, ans_agent_id: e.target.value }))}\n placeholder=\"ans://v1.0.0.myagent.example.com\"\n />\n

\n If your agent is registered with GoDaddy ANS (Agent Name Service), enter the ANS Agent ID to display a verification badge.\n The ID will be verified against the ANS registry during registration.\n

\n
\n\n
\n\n
\n navigate('/')}\n className=\"px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-md transition-colors\"\n >\n Cancel\n \n \n {loading ? 'Registering...' : 'Register Agent'}\n \n
\n
\n );\n\n\n const renderJsonUpload = () => (\n
\n {/* File Upload Area */}\n
\n \n
\n \n \n
\n

\n {registrationType === 'server' ? 'modelcard.json' : 'agentcard.json'} (JSON format)\n

\n
\n\n {/* JSON Preview */}\n {jsonContent && (\n
\n \n
\n 
\n              {jsonContent}\n
\n
\n
\n )}\n\n {/* Info Box */}\n
\n
\n \n
\n

\n About JSON Upload\n

\n

\n Upload a {registrationType === 'server' ? 'modelcard.json' : 'agentcard.json'} file to automatically populate the form fields.\n You can then review and modify the values before submitting.\n

\n
\n
\n
\n\n {/* Render the appropriate form below */}\n {jsonContent && (\n
\n

\n Review and Submit\n

\n {registrationType === 'server' ? renderServerForm() : renderAgentForm()}\n
\n )}\n\n {/* Cancel button when no JSON loaded */}\n {!jsonContent && (\n
\n navigate('/')}\n className=\"px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-md transition-colors\"\n >\n Cancel\n \n
\n )}\n
\n );\n\n\n // Check permissions\n const canRegisterServer = (user?.ui_permissions?.register_service?.length ?? 0) > 0;\n const canRegisterAgent = (user?.ui_permissions?.publish_agent?.length ?? 0) > 0;\n\n if (!canRegisterServer && !canRegisterAgent) {\n return (\n
\n
\n \n

\n Permission Required\n

\n

\n You do not have permission to register servers or agents.\n Please contact an administrator to request access.\n

\n navigate('/')}\n className=\"mt-4 px-4 py-2 text-sm font-medium text-yellow-800 dark:text-yellow-200 bg-yellow-100 dark:bg-yellow-900 hover:bg-yellow-200 dark:hover:bg-yellow-800 rounded-md transition-colors\"\n >\n Return to Dashboard\n \n
\n
\n );\n }\n\n\n return (\n
\n {toast && (\n setToast(null)}\n />\n )}\n\n {/* Header */}\n
\n navigate('/')}\n className=\"flex items-center text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white mb-4 transition-colors\"\n >\n \n Back to Dashboard\n \n

\n Register New Service\n

\n

\n Register a new MCP server or A2A agent to the gateway registry.\n

\n
\n\n {/* Registration Type Selector */}\n
\n \n
\n setRegistrationType('server')}\n className={`relative flex items-center p-4 border-2 rounded-lg transition-all ${\n registrationType === 'server'\n ? 'border-purple-500 bg-purple-50 dark:bg-purple-900/30'\n : 'border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600'\n } ${!canRegisterServer ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'}`}\n >\n \n
\n

\n MCP Server\n

\n

\n Model Context Protocol server\n

\n
\n {registrationType === 'server' && (\n \n )}\n \n\n setRegistrationType('agent')}\n className={`relative flex items-center p-4 border-2 rounded-lg transition-all ${\n registrationType === 'agent'\n ? 'border-purple-500 bg-purple-50 dark:bg-purple-900/30'\n : 'border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600'\n } ${!canRegisterAgent ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'}`}\n >\n \n
\n

\n A2A Agent\n

\n

\n Agent-to-Agent protocol agent\n

\n
\n {registrationType === 'agent' && (\n \n )}\n \n
\n
\n\n {/* Registration Mode Selector */}\n
\n \n
\n setRegistrationMode('form')}\n className={`flex items-center px-4 py-2 rounded-lg border transition-all ${\n registrationMode === 'form'\n ? 'border-purple-500 bg-purple-50 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300'\n : 'border-gray-200 dark:border-gray-700 text-gray-700 dark:text-gray-300 hover:border-gray-300 dark:hover:border-gray-600'\n }`}\n >\n \n Quick Form\n \n setRegistrationMode('json')}\n className={`flex items-center px-4 py-2 rounded-lg border transition-all ${\n registrationMode === 'json'\n ? 'border-purple-500 bg-purple-50 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300'\n : 'border-gray-200 dark:border-gray-700 text-gray-700 dark:text-gray-300 hover:border-gray-300 dark:hover:border-gray-600'\n }`}\n >\n \n JSON Upload\n \n
\n
\n\n {/* Form Content */}\n
\n {registrationMode === 'form' ? (\n registrationType === 'server' ? renderServerForm() : renderAgentForm()\n ) : (\n renderJsonUpload()\n )}\n
\n
\n );\n};\n\n\nexport default RegisterPage;\n" }, { "path": "frontend/src/pages/SettingsPage.tsx", "content": "import React, { useState, useEffect } from 'react';\nimport { useNavigate, useLocation } from 'react-router-dom';\nimport {\n ChevronDownIcon,\n ChevronRightIcon,\n UsersIcon,\n GlobeAltIcon,\n ArrowLeftIcon,\n ClipboardDocumentListIcon,\n CogIcon,\n ServerStackIcon,\n IdentificationIcon,\n DocumentTextIcon,\n ArrowDownTrayIcon,\n} from '@heroicons/react/24/outline';\nimport FederationPeers from '../components/FederationPeers';\nimport FederationPeerForm from '../components/FederationPeerForm';\nimport ConfigPanel from '../components/ConfigPanel';\nimport VirtualServerList from '../components/VirtualServerList';\nimport AuditLogsPage from './AuditLogsPage';\nimport IAMGroups from '../components/IAMGroups';\nimport IAMUsers from '../components/IAMUsers';\nimport IAMM2M from '../components/IAMM2M';\nimport RegistryCardSettings from '../components/RegistryCardSettings';\nimport ApplicationLogs from '../components/ApplicationLogs';\nimport ExternalRegistries from '../components/ExternalRegistries';\nimport DataExport from '../components/DataExport';\nimport { useAuth } from '../contexts/AuthContext';\nimport { canAccessSettings } from '../utils/permissions';\n\n\ninterface ToastState {\n show: boolean;\n message: string;\n type: 'success' | 'error' | 'info';\n}\n\ninterface SettingsItem {\n id: string;\n label: string;\n path: string;\n}\n\ninterface SettingsCategory {\n id: string;\n label: string;\n icon: React.ReactNode;\n items: SettingsItem[];\n disabled?: boolean; // Greyed out, not clickable -- for future categories\n adminOnly?: boolean; // Visible only to admins\n}\n\n/**\n * Settings categories configuration.\n * All active categories require admin access -- gated at the page level.\n * Disabled categories are shown greyed out as a preview of upcoming features.\n *\n * Known issue: Hard-refreshing or directly navigating to a sub-path like\n * /settings/iam/groups causes a blank page because Create React App\n * (homepage: \".\") generates relative asset paths. The browser resolves\n * ./static/js/main.xxx.js relative to the current URL, requesting\n * /settings/iam/static/js/main.xxx.js which returns HTML from the SPA\n * catch-all instead of JavaScript.\n * Root fix: inject in registry/main.py _build_cached_index_html().\n */\nconst SETTINGS_CATEGORIES: SettingsCategory[] = [\n {\n id: 'registry',\n label: 'Registry',\n icon: ,\n items: [\n { id: 'card', label: 'Registry Card', path: '/settings/registry/card' },\n ],\n },\n {\n id: 'audit',\n label: 'Audit',\n icon: ,\n items: [\n { id: 'logs', label: 'Audit Logs', path: '/settings/audit/logs' },\n ],\n },\n {\n id: 'app-logs',\n label: 'Application Logs',\n icon: ,\n items: [\n { id: 'viewer', label: 'Log Viewer', path: '/settings/app-logs/viewer' },\n ],\n },\n {\n id: 'federation',\n label: 'Federation',\n icon: ,\n items: [\n { id: 'peers', label: 'Peers', path: '/settings/federation/peers' },\n { id: 'external-registries', label: 'External Registries', path: '/settings/federation/external-registries' },\n ],\n },\n {\n id: 'virtual-mcp',\n label: 'Virtual MCP',\n icon: ,\n items: [\n { id: 'servers', label: 'Virtual Servers', path: '/settings/virtual-mcp/servers' },\n ],\n },\n {\n id: 'iam',\n label: 'IAM',\n icon: ,\n items: [\n { id: 'groups', label: 'Groups', path: '/settings/iam/groups' },\n { id: 'users', label: 'Users', path: '/settings/iam/users' },\n { id: 'm2m', label: 'M2M Accounts', path: '/settings/iam/m2m' },\n ],\n },\n {\n id: 'notifications',\n label: 'Notifications',\n icon: ,\n items: [],\n disabled: true,\n },\n {\n id: 'system-config',\n label: 'System Config',\n icon: ,\n items: [\n { id: 'configuration', label: 'Configuration', path: '/settings/system-config/configuration' },\n ],\n adminOnly: true,\n },\n {\n id: 'data-export',\n label: 'Data Export',\n icon: ,\n items: [\n { id: 'export', label: 'Export', path: '/settings/data-export/export' },\n ],\n adminOnly: true,\n },\n];\n\n\n/**\n * SettingsPage component provides a VS Code-style settings interface.\n *\n * Features a collapsible sidebar with categories and a main content area\n * that renders the appropriate component based on the current route.\n */\nconst SettingsPage: React.FC = () => {\n const navigate = useNavigate();\n const location = useLocation();\n const { user, loading } = useAuth();\n\n // All settings categories require admin -- no per-category filtering\n const visibleCategories = canAccessSettings(user) ? SETTINGS_CATEGORIES : [];\n\n // Track which categories are expanded - auto-expand based on current path\n const [expandedCategories, setExpandedCategories] = useState>(() => {\n const initial = new Set(['registry']);\n // Auto-expand the category matching the current route\n for (const category of SETTINGS_CATEGORIES) {\n for (const item of category.items) {\n if (location.pathname.startsWith(item.path) || location.pathname.startsWith(`/settings/${category.id}`)) {\n initial.add(category.id);\n }\n }\n }\n return initial;\n });\n\n // Toast notification state\n const [toast, setToast] = useState({\n show: false,\n message: '',\n type: 'success',\n });\n\n // Redirect non-admin users to home (only after auth has loaded)\n useEffect(() => {\n if (!loading && !canAccessSettings(user)) {\n navigate('/', { replace: true });\n }\n }, [user, loading, navigate]);\n\n // Auto-dismiss toast after 4 seconds\n useEffect(() => {\n if (toast.show) {\n const timer = setTimeout(() => {\n setToast((prev) => ({ ...prev, show: false }));\n }, 4000);\n return () => clearTimeout(timer);\n }\n }, [toast.show]);\n\n // Show spinner while auth is loading.\n // Must return a valid element (not null) because Layout uses cloneElement.\n if (loading) {\n return (\n
\n
\n
\n );\n }\n\n /**\n * Show a toast notification.\n */\n const showToast = (message: string, type: 'success' | 'error' | 'info' = 'success') => {\n setToast({ show: true, message, type });\n };\n\n /**\n * Toggle category expansion.\n */\n const toggleCategory = (categoryId: string) => {\n setExpandedCategories((prev) => {\n const next = new Set(prev);\n if (next.has(categoryId)) next.delete(categoryId);\n else next.add(categoryId);\n return next;\n });\n };\n\n /**\n * Check if a path is currently active.\n */\n const isActivePath = (path: string): boolean => {\n return location.pathname.startsWith(path);\n };\n\n /**\n * Get the current active item ID.\n */\n const getActiveItemId = (): string | null => {\n for (const category of SETTINGS_CATEGORIES) {\n for (const item of category.items) {\n if (isActivePath(item.path)) {\n return item.id;\n }\n }\n }\n return null;\n };\n\n /**\n * Render the content area based on current route.\n */\n const renderContent = () => {\n const path = location.pathname;\n\n // Audit > Logs\n if (path === '/settings/audit/logs' || path === '/settings/audit') {\n return ;\n }\n\n // Application Logs > Viewer\n if (path === '/settings/app-logs/viewer' || path === '/settings/app-logs') {\n return ;\n }\n\n // Registry > Card\n if (path === '/settings/registry/card' || path === '/settings/registry') {\n return ;\n }\n\n // Federation > External Registries\n if (path === '/settings/federation/external-registries') {\n return ;\n }\n\n // Federation > Peers list\n if (path === '/settings/federation/peers' || path === '/settings/federation') {\n return ;\n }\n\n // Federation > Add peer\n if (path === '/settings/federation/peers/add') {\n return ;\n }\n\n // Federation > Edit peer\n const editMatch = path.match(/^\\/settings\\/federation\\/peers\\/([^/]+)\\/edit$/);\n if (editMatch) {\n return ;\n }\n\n // Virtual MCP > Servers\n if (path === '/settings/virtual-mcp/servers' || path === '/settings/virtual-mcp') {\n return ;\n }\n\n // System Config > Configuration\n if (path === '/settings/system-config/configuration' || path === '/settings/system-config') {\n return ;\n }\n\n // Data Export > Export\n if (path === '/settings/data-export/export' || path === '/settings/data-export') {\n return ;\n }\n\n // IAM > Groups\n if (path === '/settings/iam/groups' || path === '/settings/iam') {\n return ;\n }\n\n // IAM > Users\n if (path === '/settings/iam/users') {\n return ;\n }\n\n // IAM > M2M Accounts\n if (path === '/settings/iam/m2m') {\n return ;\n }\n\n // Default to Audit Logs (all settings require admin)\n return ;\n };\n\n const activeItemId = getActiveItemId();\n\n\n return (\n
\n {/* Header with back button */}\n
\n navigate('/')}\n className=\"p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800\n text-gray-500 dark:text-gray-400 transition-colors\"\n title=\"Back to Dashboard\"\n >\n \n \n

Settings

\n
\n\n {/* Main content area with sidebar */}\n
\n {/* Sidebar */}\n
\n
\n \n
\n
\n\n {/* Content area */}\n
\n
\n {renderContent()}\n
\n
\n
\n\n {/* Toast notification */}\n {toast.show && (\n \n {toast.message}\n
\n )}\n \n );\n};\n\nexport default SettingsPage;\n" }, { "path": "frontend/src/pages/TokenGeneration.tsx", "content": "import React, { useState } from 'react';\nimport { KeyIcon, ClipboardIcon, CheckIcon, ExclamationTriangleIcon } from '@heroicons/react/24/outline';\nimport axios from 'axios';\nimport { useAuth } from '../contexts/AuthContext';\n\nconst TokenGeneration: React.FC = () => {\n const { user } = useAuth();\n const [formData, setFormData] = useState({\n description: '',\n expires_in_hours: 8,\n scopeMethod: 'current' as 'current' | 'custom',\n customScopes: '',\n });\n const [generatedToken, setGeneratedToken] = useState('');\n const [tokenDetails, setTokenDetails] = useState(null);\n const [loading, setLoading] = useState(false);\n const [copied, setCopied] = useState(false);\n const [error, setError] = useState('');\n\n const expirationOptions = [\n { value: 1, label: '1 hour' },\n { value: 8, label: '8 hours' },\n { value: 24, label: '24 hours' },\n ];\n\n const handleGenerateToken = async (e: React.FormEvent) => {\n e.preventDefault();\n setLoading(true);\n setError('');\n \n try {\n const requestData: any = {\n description: formData.description,\n expires_in_hours: formData.expires_in_hours,\n };\n\n // Handle scopes based on the selected method\n if (formData.scopeMethod === 'custom') {\n const customScopesText = formData.customScopes.trim();\n if (customScopesText) {\n try {\n const parsedScopes = JSON.parse(customScopesText);\n if (!Array.isArray(parsedScopes)) {\n throw new Error('Custom scopes must be a JSON array');\n }\n requestData.requested_scopes = parsedScopes;\n } catch (e) {\n setError('Invalid JSON format for custom scopes. Please provide a valid JSON array.');\n return;\n }\n }\n }\n // If using current scopes, we don't need to set requested_scopes - it will default to user's current scopes\n \n const response = await axios.post('/api/tokens/generate', requestData, {\n headers: {\n 'Content-Type': 'application/json',\n },\n });\n \n if (response.data.success) {\n setGeneratedToken(response.data.token_data.access_token);\n setTokenDetails(response.data);\n } else {\n throw new Error('Token generation failed');\n }\n } catch (error: any) {\n console.error('Failed to generate token:', error);\n setError(error.response?.data?.detail || 'Failed to generate token');\n } finally {\n setLoading(false);\n }\n };\n\n const handleCopyToken = async () => {\n try {\n await navigator.clipboard.writeText(generatedToken);\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n } catch (error) {\n // Fallback for older browsers\n const textArea = document.createElement('textarea');\n textArea.value = generatedToken;\n textArea.style.position = 'fixed';\n textArea.style.left = '-999999px';\n textArea.style.top = '-999999px';\n document.body.appendChild(textArea);\n textArea.focus();\n textArea.select();\n \n try {\n document.execCommand('copy');\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n } catch (err) {\n console.error('Failed to copy token:', err);\n }\n \n document.body.removeChild(textArea);\n }\n };\n\n const validateCustomScopes = () => {\n if (formData.scopeMethod === 'custom' && formData.customScopes.trim()) {\n try {\n const parsed = JSON.parse(formData.customScopes);\n if (!Array.isArray(parsed)) {\n return 'Custom scopes must be a JSON array';\n }\n return null;\n } catch (e) {\n return 'Invalid JSON format';\n }\n }\n return null;\n };\n\n const scopeValidationError = validateCustomScopes();\n\n return (\n
\n {/* Compact Header Section */}\n
\n
\n
\n \n
\n

Generate JWT Token

\n

\n Generate a personal access token for programmatic access to MCP servers\n

\n
\n
\n\n {/* Scrollable Content Area */}\n
\n
\n {/* Current User Permissions - Compact */}\n
\n

Your Current Permissions

\n
\n Current Scopes:\n
\n {user?.scopes && user.scopes.length > 0 ? (\n user.scopes.map((scope) => (\n \n {scope}\n \n ))\n ) : (\n No scopes available\n )}\n
\n
\n

\n Generated tokens can have the same or fewer permissions than your current scopes.\n

\n
\n\n {/* Token Configuration Form */}\n
\n
\n

Token Configuration

\n \n {/* Form Fields - Responsive Grid */}\n
\n {/* Left Column */}\n
\n {/* Description */}\n
\n \n setFormData(prev => ({ ...prev, description: e.target.value }))}\n />\n
\n\n {/* Expiration */}\n
\n \n setFormData(prev => ({ ...prev, expires_in_hours: parseInt(e.target.value) }))}\n >\n {expirationOptions.map((option) => (\n \n ))}\n \n
\n
\n\n {/* Right Column */}\n
\n {/* Scope Configuration */}\n
\n

Scope Configuration

\n \n
\n \n \n \n
\n\n {/* Custom Scopes JSON Input */}\n {formData.scopeMethod === 'custom' && (\n
\n \n setFormData(prev => ({ ...prev, customScopes: e.target.value }))}\n />\n

\n Enter a JSON array of scope names. Must be a subset of your current scopes.\n

\n {scopeValidationError && (\n

\n {scopeValidationError}\n

\n )}\n
\n )}\n
\n
\n
\n\n {/* Submit Button */}\n \n {loading ? (\n <>\n
\n Generating...\n \n ) : (\n <>\n \n Generate Token\n \n )}\n \n\n {/* Error Display */}\n {error && (\n
\n
\n \n {error}\n
\n
\n )}\n \n
\n\n {/* Generated Token Result */}\n {generatedToken && tokenDetails && (\n
\n
\n \n

\n Token Generated Successfully\n

\n
\n \n {/* Token Display */}\n
\n
\n \n {generatedToken}\n \n
\n \n \n {copied ? (\n \n ) : (\n \n )}\n \n
\n\n {/* Token Details */}\n
\n

Expires: {new Date(Date.now() + tokenDetails.token_data.expires_in * 1000).toLocaleString()}

\n

Scopes: {tokenDetails.requested_scopes.join(', ')}

\n {tokenDetails.token_data.description && (\n

Description: {tokenDetails.token_data.description}

\n )}\n
\n\n {/* Usage Instructions */}\n
\n

📋 Usage Instructions

\n

Use this token in your API requests:

\n \n Authorization: Bearer YOUR_TOKEN_HERE\n \n

Replace YOUR_TOKEN_HERE with the token above.

\n
\n \n {/* Security Warning */}\n
\n

\n ⚠️ Important: This token will not be shown again. Save it securely!\n

\n
\n
\n )}\n
\n
\n
\n );\n};\n\nexport default TokenGeneration; " }, { "path": "frontend/src/react-app-env.d.ts", "content": "/// \n\ndeclare module \"*.png\" {\n const value: string;\n export default value;\n}\n\ndeclare module \"*.jpg\" {\n const value: string;\n export default value;\n}\n\ndeclare module \"*.jpeg\" {\n const value: string;\n export default value;\n}\n\ndeclare module \"*.gif\" {\n const value: string;\n export default value;\n}\n\ndeclare module \"*.svg\" {\n const value: string;\n export default value;\n} " }, { "path": "frontend/src/setupTests.ts", "content": "import '@testing-library/jest-dom';\n" }, { "path": "frontend/src/types/skill.ts", "content": "/**\n * Shared Skill type definitions for the MCP Gateway Registry frontend.\n */\n\n/**\n * Represents a tool allowed by a skill.\n */\nexport interface AllowedTool {\n tool_name: string;\n server_path?: string;\n capabilities?: string[];\n}\n\n\n/**\n * Represents a requirement for a skill.\n */\nexport interface SkillRequirement {\n type: string;\n target: string;\n min_version?: string;\n required?: boolean;\n}\n\n\n/**\n * Skill interface representing an Agent Skill.\n */\n/**\n * Skill metadata with author, version, and custom key-value pairs.\n */\nexport interface SkillMetadata {\n author?: string | null;\n version?: string | null;\n extra?: Record;\n}\n\n\nexport interface Skill {\n name: string;\n path: string;\n description?: string;\n skill_md_url: string;\n skill_md_raw_url?: string;\n version?: string;\n author?: string;\n visibility: 'public' | 'private' | 'group';\n is_enabled: boolean;\n tags?: string[];\n owner?: string;\n registry_name?: string;\n target_agents?: string[];\n allowed_tools?: AllowedTool[];\n requirements?: SkillRequirement[];\n metadata?: SkillMetadata | null;\n repository_url?: string;\n auth_scheme?: 'none' | 'global_credentials' | 'bearer' | 'api_key';\n auth_header_name?: string;\n num_stars?: number;\n status?: 'active' | 'draft' | 'deprecated' | 'beta';\n health_status?: 'healthy' | 'unhealthy' | 'unknown';\n last_checked_time?: string;\n created_at?: string;\n updated_at?: string;\n}\n" }, { "path": "frontend/src/types/stats.ts", "content": "/**\n * Shared system statistics type definitions for the MCP Gateway Registry frontend.\n *\n * These interfaces match the backend API response from /api/stats endpoint.\n */\n\n\n/**\n * Database health status.\n */\nexport interface DatabaseStatus {\n backend: string; // \"file\" | \"documentdb\" | \"mongodb-ce\"\n status: string; // \"Healthy\" | \"Unhealthy\" | \"N/A\"\n host: string; // Database host (e.g., \"localhost:27017\")\n}\n\n\n/**\n * Authentication server health status.\n */\nexport interface AuthStatus {\n provider: string; // \"cognito\" | \"keycloak\" | \"entra\" | \"github\"\n status: string; // \"Healthy\" | \"Unhealthy\"\n url: string; // Auth server URL\n}\n\n\n/**\n * Registry resource counts.\n */\nexport interface RegistryStatsData {\n servers: number;\n agents: number;\n skills: number;\n}\n\n\n/**\n * Complete system statistics response from /api/stats.\n */\nexport interface SystemStats {\n uptime_seconds: number;\n started_at: string; // ISO 8601 timestamp\n version: string;\n deployment_type: string; // \"Kubernetes\" | \"ECS\" | \"EC2\" | \"Local\"\n deployment_mode: string; // \"with-gateway\" | \"registry-only\"\n registry_stats: RegistryStatsData;\n database_status: DatabaseStatus;\n auth_status: AuthStatus;\n}\n" }, { "path": "frontend/src/types/virtualServer.ts", "content": "/**\n * Shared Virtual MCP Server type definitions for the MCP Gateway Registry frontend.\n *\n * These interfaces mirror the backend Pydantic models defined in\n * registry/schemas/virtual_server_models.py.\n */\n\n\n/**\n * Maps a tool from a backend server into a virtual server.\n *\n * Each mapping selects a specific tool from a backend MCP server,\n * optionally renaming it (alias) and pinning it to a specific version.\n */\nexport interface ToolMapping {\n tool_name: string;\n alias?: string | null;\n backend_server_path: string;\n backend_version?: string | null;\n description_override?: string | null;\n}\n\n\n/**\n * Per-tool scope override for fine-grained access control.\n *\n * Allows requiring additional scopes to see or call specific tools\n * beyond the virtual server's base required_scopes.\n */\nexport interface ToolScopeOverride {\n tool_alias: string;\n required_scopes: string[];\n}\n\n\n/**\n * Full virtual MCP server configuration.\n *\n * A virtual server aggregates tools from multiple backend MCP servers\n * into a single endpoint. It supports tool aliasing, version pinning,\n * and scope-based access control.\n */\nexport interface VirtualServerConfig {\n path: string;\n server_name: string;\n description: string;\n tool_mappings: ToolMapping[];\n required_scopes: string[];\n tool_scope_overrides: ToolScopeOverride[];\n is_enabled: boolean;\n tags: string[];\n supported_transports: string[];\n created_by?: string | null;\n created_at?: string | null;\n updated_at?: string | null;\n}\n\n\n/**\n * Lightweight virtual server summary for listings.\n *\n * Optionally includes detailed fields (tool_mappings, required_scopes, etc.)\n * when the full configuration is needed for display purposes.\n */\n/**\n * Rating detail for a virtual server.\n */\nexport interface RatingDetail {\n user: string;\n rating: number;\n}\n\n\n/**\n * Lightweight virtual server summary for listings.\n *\n * Optionally includes detailed fields (tool_mappings, required_scopes, etc.)\n * when the full configuration is needed for display purposes.\n */\nexport interface VirtualServerInfo {\n path: string;\n server_name: string;\n description: string;\n tool_count: number;\n backend_count: number;\n backend_paths: string[];\n is_enabled: boolean;\n tags: string[];\n num_stars?: number;\n rating_details?: RatingDetail[];\n created_by?: string | null;\n created_at?: string | null;\n updated_at?: string | null;\n // Optional detailed fields for modal display\n tool_mappings?: ToolMapping[];\n required_scopes?: string[];\n supported_transports?: string[];\n}\n\n\n/**\n * Request model for creating a virtual server.\n */\nexport interface CreateVirtualServerRequest {\n server_name: string;\n path?: string | null;\n description?: string;\n tool_mappings?: ToolMapping[];\n required_scopes?: string[];\n tool_scope_overrides?: ToolScopeOverride[];\n tags?: string[];\n supported_transports?: string[];\n}\n\n\n/**\n * Request model for updating a virtual server.\n * All fields are optional; only provided fields are updated.\n */\nexport interface UpdateVirtualServerRequest {\n server_name?: string | null;\n description?: string | null;\n tool_mappings?: ToolMapping[] | null;\n required_scopes?: string[] | null;\n tool_scope_overrides?: ToolScopeOverride[] | null;\n tags?: string[] | null;\n supported_transports?: string[] | null;\n}\n\n\n/**\n * A tool available in the registry, from the global tool catalog.\n *\n * Aggregates tool information across all enabled backend servers.\n */\nexport interface ToolCatalogEntry {\n tool_name: string;\n server_path: string;\n server_name: string;\n description: string;\n input_schema: Record;\n available_versions: string[];\n}\n\n\n/**\n * A tool resolved from a virtual server's tool mappings.\n *\n * Contains the final tool name (alias or original), its source backend,\n * and the full tool metadata for serving in tools/list responses.\n */\nexport interface ResolvedTool {\n name: string;\n original_name: string;\n backend_server_path: string;\n backend_version?: string | null;\n description: string;\n input_schema: Record;\n required_scopes: string[];\n}\n" }, { "path": "frontend/src/utils/dateUtils.ts", "content": "import { formatDistanceToNow, parseISO, isValid } from 'date-fns';\n\n/**\n * Format a date string or Date object as relative time (e.g., \"2 hours ago\", \"3 days ago\").\n *\n * @param date - ISO 8601 date string or Date object\n * @returns Formatted relative time string, or \"Unknown\" if invalid\n */\nexport function formatRelativeTime(date: string | Date | null | undefined): string {\n if (!date) {\n return 'Unknown';\n }\n\n try {\n const dateObj = typeof date === 'string' ? parseISO(date) : date;\n\n if (!isValid(dateObj)) {\n return 'Unknown';\n }\n\n return formatDistanceToNow(dateObj, { addSuffix: true });\n } catch (error) {\n console.error('Error formatting relative time:', error);\n return 'Unknown';\n }\n}\n\n/**\n * Format a date string or Date object as absolute date (e.g., \"Jan 15, 2025, 3:30 PM\").\n *\n * @param date - ISO 8601 date string or Date object\n * @returns Formatted absolute date string, or \"Unknown\" if invalid\n */\nexport function formatAbsoluteDate(date: string | Date | null | undefined): string {\n if (!date) {\n return 'Unknown';\n }\n\n try {\n const dateObj = typeof date === 'string' ? parseISO(date) : date;\n\n if (!isValid(dateObj)) {\n return 'Unknown';\n }\n\n return new Intl.DateTimeFormat('en-US', {\n year: 'numeric',\n month: 'short',\n day: 'numeric',\n hour: '2-digit',\n minute: '2-digit',\n }).format(dateObj);\n } catch (error) {\n console.error('Error formatting absolute date:', error);\n return 'Unknown';\n }\n}\n\n/**\n * Format a date with both relative and absolute time for tooltips.\n *\n * @param date - ISO 8601 date string or Date object\n * @returns Object with relative and absolute formatted dates\n */\nexport function formatDateWithTooltip(date: string | Date | null | undefined): {\n relative: string;\n absolute: string;\n} {\n return {\n relative: formatRelativeTime(date),\n absolute: formatAbsoluteDate(date),\n };\n}\n" }, { "path": "frontend/src/utils/permissions.ts", "content": "/**\n * Settings page access control utility.\n *\n * All Settings categories (Audit, Federation, IAM) require admin access.\n * The backend enforces this on every endpoint. The frontend mirrors it\n * as a UX convenience layer.\n *\n * The ui_permissions from scopes.yml control server/agent access\n * (e.g., list_service, toggle_service, list_agents, publish_agent)\n */\n\ninterface SettingsUser {\n is_admin?: boolean;\n}\n\n/**\n * Check if a user can access the Settings page.\n * Returns true only when is_admin === true.\n */\nexport function canAccessSettings(user: SettingsUser | null): boolean {\n if (!user) return false;\n return user.is_admin === true;\n}\n" }, { "path": "frontend/tailwind.config.js", "content": "/** @type {import('tailwindcss').Config} */\nmodule.exports = {\n content: [\n \"./src/**/*.{js,jsx,ts,tsx}\",\n ],\n darkMode: 'class',\n theme: {\n extend: {\n colors: {\n primary: {\n 50: '#f7f5ff',\n 100: '#f0edff',\n 200: '#e2dcff',\n 300: '#cdc0ff',\n 400: '#b199ff',\n 500: '#9573ff',\n 600: '#7a00cc',\n 700: '#6b46c1',\n 800: '#553c9a',\n 900: '#483177',\n },\n gray: {\n 50: '#f8f9fa',\n 100: '#f1f3f4',\n 200: '#e8eaed',\n 300: '#dadce0',\n 400: '#bdc1c6',\n 500: '#9aa0a6',\n 600: '#80868b',\n 700: '#5f6368',\n 800: '#3c4043',\n 900: '#202124',\n }\n },\n fontFamily: {\n sans: ['Inter', 'system-ui', 'sans-serif'],\n },\n animation: {\n 'fade-in': 'fadeIn 0.2s ease-in-out',\n 'slide-up': 'slideUp 0.2s ease-out',\n },\n keyframes: {\n fadeIn: {\n '0%': { opacity: '0' },\n '100%': { opacity: '1' },\n },\n slideUp: {\n '0%': { transform: 'translateY(10px)', opacity: '0' },\n '100%': { transform: 'translateY(0)', opacity: '1' },\n },\n },\n },\n },\n plugins: [\n require('@tailwindcss/forms'),\n require('@tailwindcss/typography'),\n ],\n} " }, { "path": "frontend/tests/reports/report.html", "content": "\n\n \n \n report.html\n \n \n \n \n

report.html

\n

Report generated on 23-Feb-2026 at 18:00:22 by pytest-html\n v4.1.1

\n
\n

Environment

\n
\n
\n \n \n \n \n \n
\n
\n

Summary

\n
\n
\n

0 test took 0 ms.

\n

(Un)check the boxes to filter the results.

\n
\n
\n
There are still tests running.
Reload this page to get the latest results!
\n
\n
\n
\n
\n
\n \n 0 Failed,\n \n 0 Passed,\n \n 0 Skipped,\n \n 0 Expected failures,\n \n 0 Unexpected passes,\n \n 0 Errors,\n \n 0 Reruns\n
\n
\n  / \n
\n
\n
\n
\n
\n
\n
\n
\n \n \n \n \n \n \n \n \n \n
ResultTestDurationLinks
\n \n
\n
\n \n
\n" }, { "path": "frontend/tests/reports/report.json", "content": "{\"created\": 1771869622.4034302, \"duration\": 0.05739283561706543, \"exitcode\": 1, \"root\": \"/home/ubuntu/repos/mcp-gateway-registry\", \"environment\": {}, \"summary\": {\"total\": 0, \"collected\": 0}, \"collectors\": [{\"nodeid\": \"\", \"outcome\": \"passed\", \"result\": [{\"nodeid\": \"frontend/tests\", \"type\": \"Dir\"}]}, {\"nodeid\": \"frontend/tests/reports\", \"outcome\": \"passed\", \"result\": []}, {\"nodeid\": \"frontend/tests\", \"outcome\": \"passed\", \"result\": [{\"nodeid\": \"frontend/tests/reports\", \"type\": \"Dir\"}]}], \"tests\": []}" }, { "path": "frontend/tsconfig.e2e.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"es2020\",\n \"module\": \"esnext\",\n \"moduleResolution\": \"node\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"noEmit\": true\n },\n \"include\": [\n \"e2e/**/*.ts\",\n \"playwright.config.ts\"\n ]\n}\n" }, { "path": "frontend/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"es5\",\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"es6\"\n ],\n \"allowJs\": true,\n \"skipLibCheck\": true,\n \"esModuleInterop\": true,\n \"allowSyntheticDefaultImports\": true,\n \"strict\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"module\": \"esnext\",\n \"moduleResolution\": \"node\",\n \"resolveJsonModule\": true,\n \"isolatedModules\": true,\n \"noEmit\": true,\n \"jsx\": \"react-jsx\"\n },\n \"include\": [\n \"src\"\n ]\n} " }, { "path": "get_asor_token.py", "content": "#!/usr/bin/env python3\n\"\"\"\nHelper script to get ASOR access token for federation.\n\nThis script performs the 3-legged OAuth flow to get an access token\nthat can be used for ASOR federation in the MCP Gateway.\n\"\"\"\n\nimport os\nimport urllib.parse\n\nimport requests\n\n# Configuration from environment or defaults\nCLIENT_ID = os.getenv(\"ASOR_CLIENT_ID\")\nCLIENT_SECRET = os.getenv(\"ASOR_CLIENT_SECRET\")\nTENANT_NAME = os.getenv(\"ASOR_TENANT_NAME\")\nHOSTNAME = os.getenv(\"ASOR_HOSTNAME\")\n\n\ndef get_asor_token():\n \"\"\"Get ASOR access token via 3-legged OAuth flow\"\"\"\n print(\"🔑 ASOR Token Generator for MCP Gateway Federation\")\n print(\"=\" * 60)\n print(f\"Tenant: {TENANT_NAME}\")\n print(f\"Hostname: {HOSTNAME}\")\n print()\n\n # Generate auth URL\n auth_url = f\"https://wcpdev.wd103.myworkday.com/{TENANT_NAME}/authorize\"\n params = {\n \"response_type\": \"code\",\n \"client_id\": CLIENT_ID,\n \"redirect_uri\": \"https://localhost:7860/callback\",\n \"scope\": \"Agent System of Record\",\n }\n\n print(\"Step 1: Get Authorization Code\")\n print(\"-\" * 30)\n print(\"Visit this URL in your browser:\")\n print(f\"{auth_url}?{urllib.parse.urlencode(params)}\")\n print()\n\n auth_code = input(\"Enter the authorization code from the callback URL: \").strip()\n\n if not auth_code:\n print(\"❌ No authorization code provided\")\n return None\n\n print(\"\\nStep 2: Exchange Code for Token\")\n print(\"-\" * 30)\n\n # Exchange code for token\n token_url = f\"https://{HOSTNAME}/ccx/oauth2/{TENANT_NAME}/token\"\n data = {\n \"grant_type\": \"authorization_code\",\n \"client_id\": CLIENT_ID,\n \"client_secret\": CLIENT_SECRET,\n \"code\": auth_code,\n \"redirect_uri\": \"https://localhost:7860/callback\",\n }\n\n try:\n response = requests.post(token_url, data=data, timeout=15)\n if response.status_code == 200:\n tokens = response.json()\n access_token = tokens.get(\"access_token\")\n expires_in = tokens.get(\"expires_in\", \"unknown\")\n\n print(\"✅ Successfully obtained access token!\")\n print(f\" Token: {access_token}\")\n print(f\" Expires in: {expires_in} seconds\")\n print()\n\n print(\"Step 3: Configure MCP Gateway\")\n print(\"-\" * 30)\n print(\"Add this to your .env file:\")\n print(f\"ASOR_ACCESS_TOKEN={access_token}\")\n print()\n print(\"Then restart the MCP Gateway with:\")\n print(\"./build_and_run.sh --prebuilt\")\n print()\n\n return access_token\n else:\n print(f\"❌ Token exchange failed: {response.status_code}\")\n print(f\"Response: {response.text}\")\n return None\n except Exception as e:\n print(f\"❌ Error during token exchange: {e}\")\n return None\n\n\nif __name__ == \"__main__\":\n get_asor_token()\n" }, { "path": "keycloak/README.md", "content": "# Keycloak Setup for MCP Gateway\n\n## Quick Start - Set Up Keycloak in 4 Steps\n\n### Prerequisites\n- Docker and Docker Compose installed\n- Port 8080 available (Keycloak) and 5432 (PostgreSQL)\n\n### Step 1: Set Required Passwords\n```bash\n# MANDATORY - Set these before starting containers\nexport KEYCLOAK_ADMIN_PASSWORD=\"your-secure-admin-password\"\nexport KEYCLOAK_DB_PASSWORD=\"your-secure-database-password\"\n```\n\n### Step 2: Start Keycloak Services\n```bash\n# Start PostgreSQL and Keycloak containers\ndocker-compose up -d postgres keycloak\n\n# Wait for Keycloak to be ready (takes ~2 minutes)\necho \"Waiting for Keycloak to start...\"\nsleep 120\n\n# Verify Keycloak is running\ncurl -f http://localhost:8080/health/ready || echo \"Keycloak not ready yet\"\n```\n\n### Step 3: Initialize Keycloak\n```bash\n# This creates the realm, groups, and M2M client\n./keycloak/setup/init-keycloak.sh\n```\n\n### Step 4: Create Service Accounts for Your Agents\n\n**Option A: Production Setup (Individual Agents)**\n```bash\n# Create a service account for each AI agent\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id sre-agent \\\n --group mcp-servers-unrestricted\n```\n\n**Option B: Development Setup (Shared Account)**\n```bash\n# Create one shared service account for all agents\n./keycloak/setup/setup-m2m-service-account.sh\n```\n\n**That's it!** Keycloak is now configured for the MCP Gateway.\n\n---\n\n## What Each Script Does\n\n### Available Scripts\n\n| Script | Purpose | When to Use |\n|--------|---------|------------|\n| `init-keycloak.sh` | Creates realm, groups, and M2M client | **Always run first** during initial setup |\n| `setup-agent-service-account.sh` | Creates individual service account for one AI agent | When adding a new AI agent (production) |\n| `setup-m2m-service-account.sh` | Creates shared service account | For development/testing only |\n| `clean-keycloak.sh` | Removes all Keycloak configuration | For complete reset (use with caution) |\n\n### Script Details\n\n#### init-keycloak.sh\n**What it does:**\n- Creates the `mcp-gateway` realm\n- Creates two groups: `mcp-servers-unrestricted` and `mcp-servers-restricted`\n- Creates the M2M client (`mcp-gateway-m2m`)\n- Configures group mappers for JWT tokens\n- Sets up proper client scopes\n\n**Required Environment Variables:**\n- `KEYCLOAK_ADMIN_PASSWORD` - Admin password for Keycloak\n- `KEYCLOAK_DB_PASSWORD` - Database password\n\n**Usage:**\n```bash\nexport KEYCLOAK_ADMIN_PASSWORD=\"secure-password\"\nexport KEYCLOAK_DB_PASSWORD=\"secure-db-password\"\n./keycloak/setup/init-keycloak.sh\n```\n\n#### setup-agent-service-account.sh\n**What it does:**\n- Creates an individual service account for a specific AI agent\n- Assigns the account to either restricted or unrestricted group\n- Enables individual audit trails per agent\n\n**Required Environment Variables:**\n- `KEYCLOAK_ADMIN_PASSWORD` - Admin password for Keycloak\n\n**Usage:**\n```bash\n# For an agent with full access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id my-agent \\\n --group mcp-servers-unrestricted\n\n# For an agent with limited access\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id my-limited-agent \\\n --group mcp-servers-restricted\n```\n\n**Options:**\n- `--agent-id` - Unique identifier for the agent (required)\n- `--group` - Either `mcp-servers-unrestricted` or `mcp-servers-restricted` (required)\n\n#### setup-m2m-service-account.sh\n**What it does:**\n- Creates a single shared service account\n- Used for development/testing when you don't need individual agent tracking\n- Assigns to unrestricted group by default\n\n**Required Environment Variables:**\n- `KEYCLOAK_ADMIN_PASSWORD` - Admin password for Keycloak\n\n**Usage:**\n```bash\n./keycloak/setup/setup-m2m-service-account.sh\n```\n\n---\n\n## Common Tasks\n\n### Adding a New AI Agent\n```bash\n# 1. Create the service account\n./keycloak/setup/setup-agent-service-account.sh \\\n --agent-id new-agent \\\n --group mcp-servers-restricted\n\n# 2. Generate token (using Python script)\ncd credentials-provider\npython token_refresher.py --agent-id new-agent\n\n# 3. Test the setup\n./test-keycloak-mcp.sh --agent-id new-agent\n```\n\n### Changing Agent Permissions\n1. Login to Keycloak Admin Console: http://localhost:8080/admin\n2. Navigate to Users → `agent--m2m`\n3. Go to Groups tab\n4. Leave current group and join new group\n5. Regenerate token: `python token_refresher.py --agent-id `\n\n### Viewing All Agents\n1. Login to Keycloak Admin Console\n2. Navigate to Users\n3. Search for \"agent-\" to see all service accounts\n\n---\n\n## Troubleshooting\n\n### Script Fails with \"KEYCLOAK_ADMIN_PASSWORD not set\"\n**Solution:** Set the required environment variable:\n```bash\nexport KEYCLOAK_ADMIN_PASSWORD=\"your-password\"\n```\n\n### Can't Access Admin Console\n**Check Keycloak is running:**\n```bash\ndocker-compose ps keycloak\n```\n\n**Check logs:**\n```bash\ndocker-compose logs keycloak\n```\n\n### Token Generation Fails\n**Verify service account exists:**\n1. Check in Keycloak Admin Console under Users\n2. Or regenerate: `./keycloak/setup/setup-agent-service-account.sh --agent-id --group `\n\n#### clean-keycloak.sh\n**What it does:**\n- Removes the entire `mcp-gateway` realm\n- Deletes all service accounts and groups\n- Provides a complete reset for testing or troubleshooting\n\n**Required Environment Variables:**\n- `KEYCLOAK_ADMIN_PASSWORD` - Admin password for Keycloak\n\n**Usage:**\n```bash\n# WARNING: This will delete all Keycloak configuration\n./keycloak/setup/clean-keycloak.sh\n```\n\n**When to use:**\n- Starting fresh after configuration errors\n- Testing setup scripts from scratch\n- Removing all MCP Gateway configuration from Keycloak\n\n---\n\n## Next Steps\n\nAfter setting up Keycloak:\n1. Generate tokens for your agents: See [Token Management](../credentials-provider/README.md)\n2. Configure your AI agents: See [Agent Configuration](../agents/README.md)\n3. Test the integration: See [Testing Guide](../docs/testing.md)\n\nFor detailed documentation, see [Keycloak Integration Guide](../docs/keycloak-integration.md)" }, { "path": "keycloak/import/realm-config.json", "content": "{\n \"realm\": \"mcp-gateway\",\n \"enabled\": true,\n \"sslRequired\": \"external\",\n \"registrationAllowed\": false,\n \"loginWithEmailAllowed\": true,\n \"duplicateEmailsAllowed\": false,\n \"resetPasswordAllowed\": true,\n \"editUsernameAllowed\": false,\n \"bruteForceProtected\": true,\n \"permanentLockout\": false,\n \"maxFailureWaitSeconds\": 900,\n \"minimumQuickLoginWaitSeconds\": 60,\n \"waitIncrementSeconds\": 60,\n \"quickLoginCheckMilliSeconds\": 1000,\n \"maxDeltaTimeSeconds\": 43200,\n \"failureFactor\": 5,\n \n \"defaultSignatureAlgorithm\": \"RS256\",\n \"offlineSessionMaxLifespanEnabled\": false,\n \"offlineSessionMaxLifespan\": 5184000,\n \n \"clients\": [\n {\n \"clientId\": \"mcp-gateway-web\",\n \"name\": \"MCP Gateway Web Client\",\n \"description\": \"Web UI authentication client for MCP Gateway Registry\",\n \"rootUrl\": \"${env.REGISTRY_URL}\",\n \"adminUrl\": \"${env.REGISTRY_URL}\",\n \"baseUrl\": \"${env.REGISTRY_URL}\",\n \"surrogateAuthRequired\": false,\n \"enabled\": true,\n \"alwaysDisplayInConsole\": false,\n \"clientAuthenticatorType\": \"client-secret\",\n \"redirectUris\": [\n \"${env.AUTH_SERVER_EXTERNAL_URL}/oauth2/callback/keycloak\",\n \"${env.REGISTRY_URL}/*\",\n \"http://localhost:7860/*\",\n \"http://localhost:8888/*\"\n ],\n \"webOrigins\": [\n \"${env.REGISTRY_URL}\",\n \"http://localhost:7860\",\n \"+\"\n ],\n \"protocol\": \"openid-connect\",\n \"fullScopeAllowed\": false,\n \"standardFlowEnabled\": true,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": true,\n \"serviceAccountsEnabled\": false,\n \"publicClient\": false,\n \"frontchannelLogout\": true,\n \"attributes\": {\n \"saml.assertion.signature\": \"false\",\n \"saml.force.post.binding\": \"false\",\n \"saml.multivalued.roles\": \"false\",\n \"saml.encrypt\": \"false\",\n \"post.logout.redirect.uris\": \"+\",\n \"oauth2.device.authorization.grant.enabled\": \"false\",\n \"oidc.ciba.grant.enabled\": \"false\",\n \"backchannel.logout.session.required\": \"true\",\n \"backchannel.logout.revoke.offline.tokens\": \"false\"\n },\n \"defaultClientScopes\": [\n \"web-origins\",\n \"profile\",\n \"roles\",\n \"email\",\n \"mcp-groups\"\n ],\n \"optionalClientScopes\": [\n \"address\",\n \"phone\",\n \"offline_access\",\n \"microprofile-jwt\"\n ]\n },\n {\n \"clientId\": \"mcp-gateway-m2m\",\n \"name\": \"MCP Gateway M2M Client\",\n \"description\": \"Machine-to-machine authentication client for MCP Gateway services\",\n \"enabled\": true,\n \"clientAuthenticatorType\": \"client-secret\",\n \"protocol\": \"openid-connect\",\n \"standardFlowEnabled\": false,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": false,\n \"serviceAccountsEnabled\": true,\n \"authorizationServicesEnabled\": false,\n \"publicClient\": false,\n \"fullScopeAllowed\": false,\n \"attributes\": {\n \"saml.assertion.signature\": \"false\",\n \"saml.force.post.binding\": \"false\",\n \"saml.multivalued.roles\": \"false\",\n \"saml.encrypt\": \"false\",\n \"oauth2.device.authorization.grant.enabled\": \"false\",\n \"oidc.ciba.grant.enabled\": \"false\",\n \"backchannel.logout.session.required\": \"true\",\n \"backchannel.logout.revoke.offline.tokens\": \"false\"\n },\n \"defaultClientScopes\": [\n \"web-origins\",\n \"profile\",\n \"roles\",\n \"email\",\n \"mcp-groups\"\n ],\n \"optionalClientScopes\": [\n \"address\",\n \"phone\",\n \"offline_access\",\n \"microprofile-jwt\"\n ]\n }\n ],\n \n \"clientScopes\": [\n {\n \"name\": \"mcp-groups\",\n \"description\": \"MCP Groups mapper for including group membership in tokens\",\n \"protocol\": \"openid-connect\",\n \"attributes\": {\n \"include.in.token.scope\": \"true\",\n \"display.on.consent.screen\": \"true\",\n \"gui.order\": \"100\",\n \"consent.screen.text\": \"Access to your group memberships\"\n },\n \"protocolMappers\": [\n {\n \"name\": \"groups\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-group-membership-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"full.path\": \"false\",\n \"id.token.claim\": \"true\",\n \"access.token.claim\": \"true\",\n \"claim.name\": \"groups\",\n \"userinfo.token.claim\": \"true\"\n }\n },\n {\n \"name\": \"audience\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-audience-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"included.client.audience\": \"mcp-gateway-web\",\n \"id.token.claim\": \"false\",\n \"access.token.claim\": \"true\"\n }\n }\n ]\n }\n ],\n \n \"defaultDefaultClientScopes\": [\n \"profile\",\n \"email\",\n \"roles\",\n \"web-origins\"\n ],\n \n \"groups\": [\n {\n \"name\": \"mcp-registry-admin\",\n \"path\": \"/mcp-registry-admin\",\n \"attributes\": {\n \"description\": [\"Full administrative access to MCP Gateway Registry\"]\n }\n },\n {\n \"name\": \"mcp-registry-user\",\n \"path\": \"/mcp-registry-user\",\n \"attributes\": {\n \"description\": [\"Standard user access to MCP Gateway Registry\"]\n }\n },\n {\n \"name\": \"mcp-registry-developer\",\n \"path\": \"/mcp-registry-developer\",\n \"attributes\": {\n \"description\": [\"Developer access to MCP Gateway Registry\"]\n }\n },\n {\n \"name\": \"mcp-registry-operator\",\n \"path\": \"/mcp-registry-operator\",\n \"attributes\": {\n \"description\": [\"Operator access to MCP Gateway Registry\"]\n }\n },\n {\n \"name\": \"mcp-servers-unrestricted\",\n \"path\": \"/mcp-servers-unrestricted\",\n \"attributes\": {\n \"description\": [\"Unrestricted access to all MCP servers\"]\n }\n },\n {\n \"name\": \"mcp-servers-restricted\",\n \"path\": \"/mcp-servers-restricted\",\n \"attributes\": {\n \"description\": [\"Restricted access to specific MCP servers\"]\n }\n }\n ],\n \n \"roles\": {\n \"realm\": [\n {\n \"name\": \"mcp-admin\",\n \"description\": \"MCP Administrator Role\",\n \"composite\": false,\n \"clientRole\": false,\n \"containerId\": \"mcp-gateway\"\n },\n {\n \"name\": \"mcp-user\",\n \"description\": \"MCP User Role\",\n \"composite\": false,\n \"clientRole\": false,\n \"containerId\": \"mcp-gateway\"\n },\n {\n \"name\": \"mcp-developer\",\n \"description\": \"MCP Developer Role\",\n \"composite\": false,\n \"clientRole\": false,\n \"containerId\": \"mcp-gateway\"\n },\n {\n \"name\": \"mcp-operator\",\n \"description\": \"MCP Operator Role\",\n \"composite\": false,\n \"clientRole\": false,\n \"containerId\": \"mcp-gateway\"\n }\n ]\n },\n \n \"users\": [\n {\n \"username\": \"admin\",\n \"email\": \"admin@example.com\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"firstName\": \"Admin\",\n \"lastName\": \"User\",\n \"credentials\": [\n {\n \"type\": \"password\",\n \"value\": \"${env.INITIAL_ADMIN_PASSWORD:changeme}\",\n \"temporary\": true\n }\n ],\n \"groups\": [\n \"mcp-registry-admin\",\n \"mcp-servers-unrestricted\"\n ],\n \"realmRoles\": [\n \"mcp-admin\"\n ]\n },\n {\n \"username\": \"testuser\",\n \"email\": \"testuser@example.com\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"firstName\": \"Test\",\n \"lastName\": \"User\",\n \"credentials\": [\n {\n \"type\": \"password\",\n \"value\": \"${env.INITIAL_USER_PASSWORD:testpass}\",\n \"temporary\": true\n }\n ],\n \"groups\": [\n \"mcp-registry-user\",\n \"mcp-servers-restricted\"\n ],\n \"realmRoles\": [\n \"mcp-user\"\n ]\n }\n ],\n \n \"eventsConfig\": {\n \"eventsEnabled\": true,\n \"eventsListeners\": [\n \"jboss-logging\"\n ],\n \"enabledEventTypes\": [\n \"LOGIN\",\n \"LOGIN_ERROR\",\n \"LOGOUT\",\n \"LOGOUT_ERROR\",\n \"CODE_TO_TOKEN\",\n \"CODE_TO_TOKEN_ERROR\",\n \"CLIENT_LOGIN\",\n \"CLIENT_LOGIN_ERROR\",\n \"REFRESH_TOKEN\",\n \"REFRESH_TOKEN_ERROR\"\n ],\n \"adminEventsEnabled\": true,\n \"adminEventsDetailsEnabled\": true\n },\n \n \"internationalizationEnabled\": false,\n \"supportedLocales\": [],\n \n \"browserSecurityHeaders\": {\n \"contentSecurityPolicyReportOnly\": \"\",\n \"xContentTypeOptions\": \"nosniff\",\n \"xRobotsTag\": \"none\",\n \"xFrameOptions\": \"SAMEORIGIN\",\n \"xXSSProtection\": \"1; mode=block\",\n \"contentSecurityPolicy\": \"frame-ancestors 'self'; frame-src 'self'; object-src 'none';\"\n },\n \n \"smtpServer\": {},\n \n \"loginTheme\": \"keycloak\",\n \"accountTheme\": \"keycloak\",\n \"adminTheme\": \"keycloak\",\n \"emailTheme\": \"keycloak\"\n}" }, { "path": "keycloak/setup/clean-keycloak.sh", "content": "#!/bin/bash\n# Clean Keycloak configuration and data\n# This script removes all Keycloak configuration and database data for a fresh start\n\nset -e\n\nKEYCLOAK_URL=\"${KEYCLOAK_URL:-http://localhost:8080}\"\nREALM=\"mcp-gateway\"\nKEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\nKEYCLOAK_ADMIN_PASSWORD=\"${KEYCLOAK_ADMIN_PASSWORD}\"\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\necho -e \"${YELLOW}Keycloak cleanup script for MCP Gateway Registry${NC}\"\necho \"==============================================\"\n\n# Get script directory and find .env file\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\nPROJECT_ROOT=\"$( cd \"$SCRIPT_DIR/../..\" && pwd )\"\nENV_FILE=\"$PROJECT_ROOT/.env\"\n\n# Load environment variables from .env file if it exists\nif [ -f \"$ENV_FILE\" ]; then\n echo \"Loading environment variables from $ENV_FILE...\"\n set -a # Automatically export all variables\n source \"$ENV_FILE\"\n set +a # Turn off automatic export\n echo \"Environment variables loaded successfully\"\nelse\n echo -e \"${YELLOW}No .env file found at $ENV_FILE${NC}\"\nfi\n\n# Function to get admin token\nget_admin_token() {\n local response=$(curl -s -X POST \"${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\")\n \n echo \"$response\" | grep -o '\"access_token\":\"[^\"]*' | cut -d'\"' -f4\n}\n\n# Function to check if Keycloak is accessible\ncheck_keycloak_accessible() {\n if curl -f -s \"${KEYCLOAK_URL}/admin/\" > /dev/null 2>&1; then\n return 0\n else\n return 1\n fi\n}\n\n# Function to delete realm via API\ndelete_realm_via_api() {\n echo -e \"${BLUE}Attempting to delete realm via Keycloak Admin API...${NC}\"\n \n if ! check_keycloak_accessible; then\n echo -e \"${YELLOW}Keycloak is not accessible. Skipping API cleanup.${NC}\"\n return 1\n fi\n \n # Check if admin password is set\n if [ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ]; then\n echo -e \"${YELLOW}KEYCLOAK_ADMIN_PASSWORD not set. Skipping API cleanup.${NC}\"\n return 1\n fi\n \n # Get admin token\n echo \"Getting admin token...\"\n TOKEN=$(get_admin_token)\n \n if [ -z \"$TOKEN\" ]; then\n echo -e \"${YELLOW}Failed to get admin token. Skipping API cleanup.${NC}\"\n return 1\n fi\n \n # Check if realm exists\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -H \"Authorization: Bearer ${TOKEN}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}\")\n \n if [ \"$response\" = \"200\" ]; then\n echo \"Deleting ${REALM} realm...\"\n local delete_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X DELETE \"${KEYCLOAK_URL}/admin/realms/${REALM}\" \\\n -H \"Authorization: Bearer ${TOKEN}\")\n \n if [ \"$delete_response\" = \"204\" ]; then\n echo -e \"${GREEN}Realm '${REALM}' deleted successfully via API!${NC}\"\n return 0\n else\n echo -e \"${YELLOW}Failed to delete realm via API (HTTP ${delete_response})${NC}\"\n return 1\n fi\n else\n echo -e \"${YELLOW}Realm '${REALM}' does not exist or is not accessible${NC}\"\n return 0\n fi\n}\n\n# Function to stop and remove containers\nstop_containers() {\n echo -e \"${BLUE}Stopping Keycloak containers...${NC}\"\n \n cd \"$PROJECT_ROOT\"\n \n # Stop Keycloak and database containers specifically\n if docker-compose ps | grep -q keycloak; then\n echo \"Stopping keycloak container...\"\n docker-compose stop keycloak || echo \"Keycloak container was not running\"\n fi\n \n if docker-compose ps | grep -q keycloak-db; then\n echo \"Stopping keycloak-db container...\"\n docker-compose stop keycloak-db || echo \"Keycloak-db container was not running\"\n fi\n \n # Remove the containers (but keep volumes for now)\n echo \"Removing keycloak containers...\"\n docker-compose rm -f keycloak keycloak-db 2>/dev/null || echo \"Containers already removed\"\n \n echo -e \"${GREEN}Containers stopped and removed${NC}\"\n}\n\n# Function to remove database volume\nremove_database_volume() {\n echo -e \"${BLUE}Removing Keycloak database volume...${NC}\"\n \n cd \"$PROJECT_ROOT\"\n \n # Get the volume name (it will be prefixed with the project name)\n local volume_name=$(docker volume ls | grep keycloak_db_data | awk '{print $2}')\n \n if [ ! -z \"$volume_name\" ]; then\n echo \"Removing volume: $volume_name\"\n docker volume rm \"$volume_name\" 2>/dev/null || {\n echo -e \"${YELLOW}Volume might be in use. Forcing removal...${NC}\"\n docker volume rm -f \"$volume_name\" 2>/dev/null || echo -e \"${YELLOW}Could not remove volume $volume_name${NC}\"\n }\n echo -e \"${GREEN}Database volume removed${NC}\"\n else\n echo -e \"${YELLOW}Keycloak database volume not found${NC}\"\n fi\n}\n\n# Function to clean environment variables from .env\nclean_env_secrets() {\n echo -e \"${BLUE}Cleaning Keycloak secrets from .env file...${NC}\"\n \n if [ -f \"$ENV_FILE\" ]; then\n # Reset client secrets to placeholder values\n sed -i 's/^KEYCLOAK_CLIENT_SECRET=.*/KEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret/' \"$ENV_FILE\" 2>/dev/null || true\n sed -i 's/^KEYCLOAK_M2M_CLIENT_SECRET=.*/KEYCLOAK_M2M_CLIENT_SECRET=your-keycloak-m2m-secret/' \"$ENV_FILE\" 2>/dev/null || true\n \n echo -e \"${GREEN}Client secrets reset to placeholder values in .env${NC}\"\n else\n echo -e \"${YELLOW}.env file not found, skipping secret cleanup${NC}\"\n fi\n}\n\n# Main cleanup function\nmain() {\n echo -e \"${RED}WARNING: This will completely remove all Keycloak configuration and data!${NC}\"\n echo \"This includes:\"\n echo \" - All realms, clients, and users\"\n echo \" - All groups and group assignments\" \n echo \" - All client secrets and configuration\"\n echo \" - Database volume with all persistent data\"\n echo \"\"\n \n read -p \"Are you sure you want to proceed? (y/N): \" -n 1 -r\n echo\n if [[ ! $REPLY =~ ^[Yy]$ ]]; then\n echo \"Cleanup cancelled\"\n exit 0\n fi\n \n echo \"\"\n echo -e \"${BLUE}Starting Keycloak cleanup...${NC}\"\n \n # Step 1: Try to delete realm via API (graceful cleanup)\n delete_realm_via_api || echo -e \"${YELLOW}API cleanup failed or skipped${NC}\"\n \n # Step 2: Stop and remove containers\n stop_containers\n \n # Step 3: Remove database volume (nuclear option)\n remove_database_volume\n \n # Step 4: Clean environment secrets\n clean_env_secrets\n \n echo \"\"\n echo -e \"${GREEN}Keycloak cleanup completed!${NC}\"\n echo \"\"\n echo \"Next steps:\"\n echo \"1. Run 'docker-compose up -d keycloak keycloak-db' to start fresh containers\"\n echo \"2. Wait for Keycloak to initialize (check with 'docker-compose logs keycloak')\"\n echo \"3. Run './keycloak/setup/init-keycloak.sh' to set up fresh configuration\"\n echo \"\"\n echo -e \"${YELLOW}Note: You'll need to update your .env file with new client secrets after running init-keycloak.sh${NC}\"\n}\n\n# Run main function\nmain" }, { "path": "keycloak/setup/disable-ssl.sh", "content": "#!/bin/bash\n\n# Script to disable SSL requirement for Keycloak realms\n# This allows both HTTP and HTTPS connections without requiring HTTPS\n#\n# Usage:\n# ./disable-ssl.sh # Uses AWS Secrets Manager to fetch password\n# ./disable-ssl.sh \"your-password\" # Uses provided password\n# KEYCLOAK_URL=http://custom:8080 ./disable-ssl.sh\n# VERBOSE=1 ./disable-ssl.sh # Enable verbose logging with password display\n#\n# Prerequisites:\n# - AWS CLI configured with appropriate credentials\n# - jq installed for JSON processing\n# - curl installed for API requests\n# - Keycloak running and accessible\n\nset -e\n\n# Configure logging with basicConfig\nlogging_format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\"\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\n# Default values\nKEYCLOAK_URL=\"${KEYCLOAK_URL:-http://localhost:8080}\"\nKEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\nAWS_REGION=\"${AWS_REGION:-us-east-1}\"\nKEYCLOAK_ADMIN_PASSWORD=\"${1:-}\"\nVERBOSE=\"${VERBOSE:-0}\"\n\nlog_info() {\n echo -e \"${GREEN}✓${NC} $1\"\n}\n\nlog_warn() {\n echo -e \"${YELLOW}⚠${NC} $1\"\n}\n\nlog_error() {\n echo -e \"${RED}✗${NC} $1\"\n}\n\nlog_debug() {\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo -e \"${BLUE}[DEBUG]${NC} $1\"\n fi\n}\n\nlog_trace() {\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo -e \"${BLUE}[TRACE]${NC} $1\"\n fi\n}\n\n_fetch_keycloak_password_from_secrets_manager() {\n local secret_name\n local secret_value\n local raw_response\n\n log_info \"Fetching Keycloak admin password from AWS Secrets Manager...\" >&2\n log_debug \"AWS Region: $AWS_REGION\" >&2\n log_debug \"Searching for secrets matching pattern: mcp-gateway-keycloak-admin-password\" >&2\n\n # Get the secret name that matches the pattern\n log_trace \"Executing: aws secretsmanager list-secrets --region $AWS_REGION --filters Key=name,Values=mcp-gateway-keycloak-admin-password\" >&2\n secret_name=$(aws secretsmanager list-secrets \\\n --region \"$AWS_REGION\" \\\n --filters Key=name,Values=\"mcp-gateway-keycloak-admin-password\" \\\n --query 'SecretList[0].Name' \\\n --output text)\n\n log_debug \"Secret name lookup result: $secret_name\" >&2\n\n if [[ -z \"$secret_name\" || \"$secret_name\" == \"None\" ]]; then\n log_error \"Could not find Keycloak admin password secret in AWS Secrets Manager\" >&2\n echo \"Searched for secrets matching pattern: mcp-gateway-keycloak-admin-password\" >&2\n echo \"\" >&2\n echo \"Available secrets:\" >&2\n log_trace \"Executing: aws secretsmanager list-secrets --region $AWS_REGION\" >&2\n aws secretsmanager list-secrets --region \"$AWS_REGION\" --query 'SecretList[].Name' --output text >&2\n return 1\n fi\n\n log_info \"Found secret: $secret_name\" >&2\n log_debug \"Retrieving secret value from: $secret_name\" >&2\n\n # Get the secret value directly using jq query\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n log_trace \"Executing: aws secretsmanager get-secret-value --secret-id $secret_name --region $AWS_REGION --query SecretString --output text\" >&2\n fi\n\n secret_value=$(aws secretsmanager get-secret-value \\\n --secret-id \"$secret_name\" \\\n --region \"$AWS_REGION\" \\\n --query 'SecretString' \\\n --output text)\n\n # Remove any trailing newlines or whitespace\n secret_value=\"$(echo -n \"$secret_value\")\"\n\n log_debug \"Secret value retrieved (length: ${#secret_value} characters)\" >&2\n\n if [[ -z \"$secret_value\" ]]; then\n log_error \"Failed to retrieve SecretString from AWS response\" >&2\n log_error \"Secret name was: $secret_name\" >&2\n return 1\n fi\n\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo \"[TRACE] Keycloak admin password (first 4 chars): ${secret_value:0:4}***\" >&2\n echo \"[TRACE] Keycloak admin password (full): $secret_value\" >&2\n echo \"[TRACE] Password length verified: ${#secret_value} characters\" >&2\n fi\n\n echo \"$secret_value\"\n}\n\n_extract_hostname_from_url() {\n local url=\"$1\"\n # Extract hostname from URL like http://mcp-gateway-kc-alb-xxx.us-east-1.elb.amazonaws.com:8080\n # Remove protocol\n url=\"${url#*://}\"\n # Remove port\n url=\"${url%%:*}\"\n echo \"$url\"\n}\n\n_get_admin_token() {\n local keycloak_url=\"$1\"\n local admin_user=\"$2\"\n local admin_password=\"$3\"\n local token\n local token_url\n local http_code\n local response\n\n log_info \"Getting admin token from Keycloak...\"\n log_debug \"Keycloak URL: $keycloak_url\"\n log_debug \"Admin User: $admin_user\"\n\n token_url=\"$keycloak_url/realms/master/protocol/openid-connect/token\"\n log_trace \"Token URL: $token_url\"\n\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n log_trace \"Admin password (first 4 chars): ${admin_password:0:4}***\"\n fi\n\n log_trace \"Executing token request...\"\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo \"[TRACE] Full curl command:\" >&2\n echo \"[TRACE] curl -s -w \\\"\\\\n%{http_code}\\\" -X POST \\\"$token_url\\\" -H \\\"Content-Type: application/x-www-form-urlencoded\\\" -d \\\"username=$admin_user\\\" -d \\\"password=***\\\" -d \\\"grant_type=password\\\" -d \\\"client_id=admin-cli\\\"\" >&2\n fi\n\n response=$(curl -s -w \"\\n%{http_code}\" -X POST \"$token_url\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=$admin_user\" \\\n -d \"password=$admin_password\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\")\n\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo \"[TRACE] Raw curl response length: ${#response}\" >&2\n echo \"[TRACE] Raw curl response (first 500 chars): ${response:0:500}\" >&2\n fi\n\n http_code=$(echo \"$response\" | tail -1)\n log_debug \"HTTP Status Code: $http_code\"\n\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo \"[TRACE] Response body (without http code):\" >&2\n echo \"$response\" | sed '$d' >&2\n fi\n\n token=$(echo \"$response\" | sed '$d' | jq -r '.access_token // .error // \"unknown\"')\n log_debug \"Token extraction result: $token\"\n log_debug \"Token response status: $(echo \"$response\" | sed '$d' | jq -r '.access_token // .error // \"unknown\"')\"\n\n if [[ -z \"$token\" || \"$token\" == \"null\" || \"$token\" == \"unknown\" ]]; then\n log_error \"Failed to obtain admin token\"\n log_debug \"Full response: $(echo \"$response\" | sed '$d' | jq '.')\"\n log_error \"Check that Keycloak is running and credentials are correct\"\n return 1\n fi\n\n log_debug \"Token obtained (length: ${#token} characters)\"\n log_trace \"Admin token (first 50 chars): ${token:0:50}...\"\n\n echo \"$token\"\n}\n\n_configure_hostname() {\n local keycloak_url=\"$1\"\n local admin_token=\"$2\"\n local hostname=\"$3\"\n\n log_info \"Configuring Keycloak hostname to: $hostname\"\n log_debug \"Setting frontendUrl in realm attributes to: http://$hostname:8080\"\n\n local api_url=\"$keycloak_url/admin/realms/master\"\n log_trace \"API URL: $api_url\"\n log_trace \"Request body: {\\\"attributes\\\": {\\\"frontendUrl\\\": \\\"http://$hostname:8080\\\"}}\"\n\n log_trace \"Executing API request to configure hostname...\"\n local response\n response=$(curl -s -w \"\\n%{http_code}\" -X PUT \"$api_url\" \\\n -H \"Authorization: Bearer $admin_token\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"attributes\\\": {\\\"frontendUrl\\\": \\\"http://$hostname:8080\\\"}}\")\n\n local http_code\n http_code=$(echo \"$response\" | tail -1)\n log_debug \"HTTP Status Code: $http_code\"\n\n if [[ \"$http_code\" == \"204\" ]]; then\n log_info \"Successfully configured hostname: $hostname\"\n return 0\n else\n log_error \"Failed to configure hostname (HTTP $http_code)\"\n log_trace \"Full response: $(echo \"$response\" | sed '$d')\"\n log_debug \"Note: Frontend URL configuration may not be supported via REST API in all Keycloak versions\"\n return 1\n fi\n}\n\n_disable_ssl_for_realm() {\n local keycloak_url=\"$1\"\n local admin_token=\"$2\"\n local realm_name=\"$3\"\n local http_code\n local api_url\n local response\n\n log_info \"Disabling SSL requirement for realm: $realm_name\"\n log_debug \"Realm Name: $realm_name\"\n\n api_url=\"$keycloak_url/admin/realms/$realm_name\"\n log_trace \"API URL: $api_url\"\n log_trace \"Request method: PUT\"\n log_trace \"Request body: {\\\"sslRequired\\\": \\\"none\\\"}\"\n\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n log_trace \"Admin token (first 50 chars): ${admin_token:0:50}...\"\n fi\n\n log_trace \"Executing API request to disable SSL...\"\n response=$(curl -s -w \"\\n%{http_code}\" -X PUT \"$api_url\" \\\n -H \"Authorization: Bearer $admin_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sslRequired\": \"none\"}')\n\n http_code=$(echo \"$response\" | tail -1)\n log_debug \"HTTP Status Code: $http_code\"\n log_debug \"Response body: $(echo \"$response\" | sed '$d')\"\n\n if [[ \"$http_code\" == \"204\" ]]; then\n log_info \"Successfully disabled SSL requirement for realm: $realm_name\"\n return 0\n else\n log_error \"Failed to disable SSL for realm: $realm_name (HTTP $http_code)\"\n log_trace \"Full response: $(echo \"$response\" | sed '$d')\"\n return 1\n fi\n}\n\n_verify_ssl_disabled() {\n local keycloak_url=\"$1\"\n local admin_token=\"$2\"\n local realm_name=\"$3\"\n local ssl_required\n local api_url\n local response\n local http_code\n\n log_info \"Verifying SSL requirement is disabled for realm: $realm_name\"\n log_debug \"Realm Name: $realm_name\"\n\n api_url=\"$keycloak_url/admin/realms/$realm_name\"\n log_trace \"Verification API URL: $api_url\"\n log_trace \"Request method: GET\"\n\n log_trace \"Executing API request to verify SSL configuration...\"\n response=$(curl -s -w \"\\n%{http_code}\" -X GET \"$api_url\" \\\n -H \"Authorization: Bearer $admin_token\")\n\n http_code=$(echo \"$response\" | tail -1)\n log_debug \"HTTP Status Code: $http_code\"\n\n ssl_required=$(echo \"$response\" | sed '$d' | jq -r '.sslRequired')\n log_debug \"Current sslRequired value: $ssl_required\"\n log_trace \"Full realm config: $(echo \"$response\" | sed '$d' | jq '.')\"\n\n if [[ \"$ssl_required\" == \"none\" ]]; then\n log_info \"Verified: SSL requirement is disabled (sslRequired = 'none')\"\n return 0\n else\n log_warn \"Current sslRequired value: $ssl_required\"\n log_warn \"Expected: 'none', Got: '$ssl_required'\"\n return 1\n fi\n}\n\nmain() {\n echo \"==========================================\"\n echo \"Keycloak SSL Configuration Script\"\n echo \"==========================================\"\n echo \"\"\n\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n log_debug \"VERBOSE mode enabled\"\n log_debug \"Passwords will be partially displayed for debugging\"\n fi\n\n echo \"\"\n\n # Get password from argument or fetch from Secrets Manager\n if [[ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ]]; then\n log_info \"No password provided as argument\"\n log_debug \"Attempting to fetch from AWS Secrets Manager...\"\n # Capture only stdout (password), send logs to stderr\n KEYCLOAK_ADMIN_PASSWORD=$(_fetch_keycloak_password_from_secrets_manager)\n if [[ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ]]; then\n log_error \"Failed to fetch password from AWS Secrets Manager\"\n exit 1\n fi\n log_info \"Password fetched successfully from AWS Secrets Manager\"\n else\n log_info \"Using provided password\"\n log_debug \"Password provided as argument\"\n fi\n\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo \"[TRACE] Password length: ${#KEYCLOAK_ADMIN_PASSWORD} characters\" >&2\n echo \"[TRACE] Password first 4 chars: ${KEYCLOAK_ADMIN_PASSWORD:0:4}***\" >&2\n echo \"[TRACE] Full password: $KEYCLOAK_ADMIN_PASSWORD\" >&2\n fi\n\n # Extract hostname from KEYCLOAK_URL if not explicitly provided\n local KEYCLOAK_HOSTNAME\n KEYCLOAK_HOSTNAME=$(_extract_hostname_from_url \"$KEYCLOAK_URL\")\n log_debug \"Extracted hostname from URL: $KEYCLOAK_HOSTNAME\"\n\n echo \"\"\n echo \"Configuration:\"\n echo \" Keycloak URL: $KEYCLOAK_URL\"\n echo \" Keycloak Hostname: $KEYCLOAK_HOSTNAME\"\n echo \" Admin User: $KEYCLOAK_ADMIN\"\n echo \" AWS Region: $AWS_REGION\"\n if [[ \"$VERBOSE\" == \"1\" ]]; then\n echo \" Verbose Mode: ENABLED\"\n fi\n echo \"\"\n\n log_debug \"Starting Keycloak SSL and hostname configuration process...\"\n log_trace \"Step 1: Obtaining admin token\"\n\n # Get admin token\n local admin_token\n admin_token=$(_get_admin_token \"$KEYCLOAK_URL\" \"$KEYCLOAK_ADMIN\" \"$KEYCLOAK_ADMIN_PASSWORD\")\n if [[ $? -ne 0 ]]; then\n log_error \"Failed to obtain admin token. Aborting.\"\n exit 1\n fi\n\n echo \"\"\n log_trace \"Step 2: Configuring hostname\"\n\n # Configure hostname for master realm (fixes HTTPS redirect loop)\n if _configure_hostname \"$KEYCLOAK_URL\" \"$admin_token\" \"$KEYCLOAK_HOSTNAME\"; then\n log_info \"Hostname configuration successful\"\n else\n log_warn \"Failed to configure hostname, continuing...\"\n fi\n\n echo \"\"\n log_trace \"Step 3: Processing master realm\"\n\n # Disable SSL for master realm\n if _disable_ssl_for_realm \"$KEYCLOAK_URL\" \"$admin_token\" \"master\"; then\n _verify_ssl_disabled \"$KEYCLOAK_URL\" \"$admin_token\" \"master\"\n else\n log_warn \"Failed to disable SSL for master realm, continuing...\"\n fi\n\n echo \"\"\n log_trace \"Step 4: Processing mcp-gateway realm\"\n\n # Disable SSL for mcp-gateway realm\n if _disable_ssl_for_realm \"$KEYCLOAK_URL\" \"$admin_token\" \"mcp-gateway\"; then\n _verify_ssl_disabled \"$KEYCLOAK_URL\" \"$admin_token\" \"mcp-gateway\"\n else\n log_warn \"Failed to disable SSL for mcp-gateway realm\"\n log_warn \"Make sure the mcp-gateway realm exists before running this script\"\n fi\n\n echo \"\"\n echo \"==========================================\"\n log_info \"Keycloak SSL and hostname configuration completed\"\n echo \"==========================================\"\n echo \"\"\n echo \"Next steps:\"\n echo \"1. Clear your browser cache/cookies for the Keycloak domain\"\n echo \"2. Try accessing Keycloak at: $KEYCLOAK_URL\"\n echo \"3. If still seeing HTTPS error, restart Keycloak container:\"\n echo \" docker-compose restart keycloak\"\n echo \"\"\n log_debug \"Script exit status: $?\"\n}\n\nmain \"$@\"\n" }, { "path": "keycloak/setup/generate-agent-token.sh", "content": "#!/bin/bash\n\n# Generate OAuth2 access token for MCP agents\n# Usage: ./generate-agent-token.sh [agent-name] [--client-id ID] [--client-secret SECRET] [--keycloak-url URL] [--realm REALM]\n\nset -e\n\n# Default values\nAGENT_NAME=\"mcp-gateway-m2m\"\nCLIENT_ID=\"\"\nCLIENT_SECRET=\"\"\nKEYCLOAK_URL=\"\"\nKEYCLOAK_REALM=\"mcp-gateway\"\n\n# Determine the project root directory (parent of keycloak/setup directory)\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nPROJECT_ROOT=\"$(dirname \"$(dirname \"$SCRIPT_DIR\")\")\"\nOAUTH_TOKENS_DIR=\"${PROJECT_ROOT}/.oauth-tokens\"\nVERBOSE=false\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\nusage() {\n echo \"Usage: $0 [agent-name] [options]\"\n echo \"\"\n echo \"Generate OAuth2 access token for MCP agents\"\n echo \"\"\n echo \"Arguments:\"\n echo \" agent-name Agent name (default: mcp-gateway-m2m)\"\n echo \"\"\n echo \"Options:\"\n echo \" --client-id ID OAuth2 client ID\"\n echo \" --client-secret SECRET OAuth2 client secret\"\n echo \" --keycloak-url URL Keycloak server URL\"\n echo \" --realm REALM Keycloak realm (default: mcp-gateway)\"\n echo \" --oauth-dir DIR OAuth tokens directory (default: ../../.oauth-tokens)\"\n echo \" --verbose, -v Verbose output\"\n echo \" --help, -h Show this help\"\n echo \"\"\n echo \"Examples:\"\n echo \" # Use default agent (mcp-gateway-m2m) with config from .oauth-tokens/mcp-gateway-m2m.json\"\n echo \" $0\"\n echo \"\"\n echo \" # Use specific agent with config from .oauth-tokens/my-agent.json\"\n echo \" $0 my-agent\"\n echo \"\"\n echo \" # Override specific parameters\"\n echo \" $0 my-agent --client-id custom-client --keycloak-url http://localhost:8080\"\n echo \"\"\n echo \" # Specify all parameters manually\"\n echo \" $0 test-agent --client-id test-client --client-secret secret123 --keycloak-url http://localhost:8080\"\n}\n\nlog() {\n if [ \"$VERBOSE\" = true ]; then\n echo -e \"${BLUE}[INFO]${NC} $1\"\n fi\n}\n\nerror() {\n echo -e \"${RED}[ERROR]${NC} $1\" >&2\n}\n\nsuccess() {\n echo -e \"${GREEN}[SUCCESS]${NC} $1\"\n}\n\nwarning() {\n echo -e \"${YELLOW}[WARNING]${NC} $1\"\n}\n\n# Parse command line arguments\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --client-id)\n CLIENT_ID=\"$2\"\n shift 2\n ;;\n --client-secret)\n CLIENT_SECRET=\"$2\"\n shift 2\n ;;\n --keycloak-url)\n KEYCLOAK_URL=\"$2\"\n shift 2\n ;;\n --realm)\n KEYCLOAK_REALM=\"$2\"\n shift 2\n ;;\n --oauth-dir)\n OAUTH_TOKENS_DIR=\"$2\"\n shift 2\n ;;\n --verbose|-v)\n VERBOSE=true\n shift\n ;;\n --help|-h)\n usage\n exit 0\n ;;\n -*)\n error \"Unknown option: $1\"\n usage\n exit 1\n ;;\n *)\n # First positional argument is agent name\n if [ -z \"$AGENT_NAME\" ] || [ \"$AGENT_NAME\" = \"mcp-gateway-m2m\" ]; then\n AGENT_NAME=\"$1\"\n else\n error \"Unexpected argument: $1\"\n usage\n exit 1\n fi\n shift\n ;;\n esac\ndone\n\nlog \"Using agent name: $AGENT_NAME\"\nlog \"OAuth tokens directory: $OAUTH_TOKENS_DIR\"\n\n# Function to load config from JSON file\nload_config_from_json() {\n local config_file=\"$OAUTH_TOKENS_DIR/${AGENT_NAME}.json\"\n\n if [ ! -f \"$config_file\" ]; then\n error \"Config file not found: $config_file\"\n return 1\n fi\n\n log \"Loading config from: $config_file\"\n\n # Check if jq is available\n if ! command -v jq &> /dev/null; then\n error \"jq is required to parse JSON config files. Please install jq.\"\n return 1\n fi\n\n # Extract values from JSON if not already provided\n if [ -z \"$CLIENT_ID\" ]; then\n CLIENT_ID=$(jq -r '.client_id // empty' \"$config_file\")\n log \"Loaded CLIENT_ID from config: $CLIENT_ID\"\n fi\n\n if [ -z \"$CLIENT_SECRET\" ]; then\n CLIENT_SECRET=$(jq -r '.client_secret // empty' \"$config_file\")\n log \"Loaded CLIENT_SECRET from config: ${CLIENT_SECRET:0:10}...\"\n fi\n\n if [ -z \"$KEYCLOAK_URL\" ]; then\n KEYCLOAK_URL=$(jq -r '.keycloak_url // .gateway_url // empty' \"$config_file\" | sed 's|/realms/.*||')\n log \"Loaded KEYCLOAK_URL from config: $KEYCLOAK_URL\"\n fi\n\n # Also try to get realm from config\n local config_realm=$(jq -r '.keycloak_realm // .realm // empty' \"$config_file\")\n if [ -n \"$config_realm\" ] && [ \"$KEYCLOAK_REALM\" = \"mcp-gateway\" ]; then\n KEYCLOAK_REALM=\"$config_realm\"\n log \"Loaded KEYCLOAK_REALM from config: $KEYCLOAK_REALM\"\n fi\n}\n\n# Load config from JSON if available\nif [ -z \"$CLIENT_ID\" ] || [ -z \"$CLIENT_SECRET\" ] || [ -z \"$KEYCLOAK_URL\" ]; then\n load_config_from_json\nfi\n\n# Validate required parameters\nif [ -z \"$CLIENT_ID\" ]; then\n error \"CLIENT_ID is required. Provide via --client-id or in config file.\"\n exit 1\nfi\n\nif [ -z \"$CLIENT_SECRET\" ]; then\n error \"CLIENT_SECRET is required. Provide via --client-secret or in config file.\"\n exit 1\nfi\n\nif [ -z \"$KEYCLOAK_URL\" ]; then\n error \"KEYCLOAK_URL is required. Provide via --keycloak-url or in config file.\"\n exit 1\nfi\n\n# Construct token URL\nTOKEN_URL=\"$KEYCLOAK_URL/realms/$KEYCLOAK_REALM/protocol/openid-connect/token\"\n\nlog \"Token URL: $TOKEN_URL\"\nlog \"Client ID: $CLIENT_ID\"\nlog \"Realm: $KEYCLOAK_REALM\"\n\n# Make token request\necho \"Requesting access token for agent: $AGENT_NAME\"\n\nresponse=$(curl -s -X POST \"$TOKEN_URL\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=$CLIENT_ID\" \\\n -d \"client_secret=$CLIENT_SECRET\" \\\n -d \"scope=openid email profile\")\n\n# Check if curl succeeded\nif [ $? -ne 0 ]; then\n error \"Failed to make token request to Keycloak\"\n exit 1\nfi\n\n# Parse response\nif command -v jq &> /dev/null; then\n # Check for error in response\n error_description=$(echo \"$response\" | jq -r '.error_description // empty')\n if [ -n \"$error_description\" ]; then\n error \"Token request failed: $error_description\"\n exit 1\n fi\n\n # Extract access token\n access_token=$(echo \"$response\" | jq -r '.access_token // empty')\n expires_in=$(echo \"$response\" | jq -r '.expires_in // empty')\n\n if [ -z \"$access_token\" ]; then\n error \"No access token in response\"\n echo \"Response: $response\"\n exit 1\n fi\n\n success \"Access token generated successfully!\"\n echo \"\"\n\n # Mask token for security - show only first and last portions\n token_preview=\"${access_token:0:20}....[MASKED FOR SECURITY]....${access_token: -20}\"\n echo \"Access Token: $token_preview\"\n echo \"\"\n\n if [ -n \"$expires_in\" ]; then\n echo \"Expires in: $expires_in seconds\"\n expiry_time=$(date -d \"+$expires_in seconds\" 2>/dev/null || date -r $(($(date +%s) + expires_in)) 2>/dev/null || echo \"Unknown\")\n echo \"Expires at: $expiry_time\"\n echo \"\"\n fi\n\n # Offer to save as environment file\n env_file=\"$OAUTH_TOKENS_DIR/${AGENT_NAME}.env\"\n echo \"Environment variables saved to: $env_file\"\n echo \"(Full token and credentials have been saved securely - not displayed in terminal)\"\n echo \"\"\n\n # Save to .env file\n mkdir -p \"$OAUTH_TOKENS_DIR\"\n cat > \"$env_file\" << EOF\n# Generated access token for $AGENT_NAME\n# Generated at: $(date)\nexport ACCESS_TOKEN=\"$access_token\"\nexport CLIENT_ID=\"$CLIENT_ID\"\nexport CLIENT_SECRET=\"$CLIENT_SECRET\"\nexport KEYCLOAK_URL=\"$KEYCLOAK_URL\"\nexport KEYCLOAK_REALM=\"$KEYCLOAK_REALM\"\nexport AUTH_PROVIDER=\"keycloak\"\nEOF\n\n # Save to JSON file with metadata\n json_file=\"$OAUTH_TOKENS_DIR/${AGENT_NAME}-token.json\"\n generated_at=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\n expires_at=\"\"\n if [ -n \"$expires_in\" ]; then\n expires_at=$(date -u -d \"+$expires_in seconds\" +\"%Y-%m-%dT%H:%M:%SZ\" 2>/dev/null || date -u -r $(($(date +%s) + expires_in)) +\"%Y-%m-%dT%H:%M:%SZ\" 2>/dev/null || echo \"\")\n fi\n\n cat > \"$json_file\" << EOF\n{\n \"agent_name\": \"$AGENT_NAME\",\n \"access_token\": \"$access_token\",\n \"token_type\": \"Bearer\",\n \"expires_in\": ${expires_in:-null},\n \"generated_at\": \"$generated_at\",\n \"expires_at\": ${expires_at:+\"\\\"$expires_at\\\"\"},\n \"provider\": \"keycloak\",\n \"keycloak_url\": \"$KEYCLOAK_URL\",\n \"keycloak_realm\": \"$KEYCLOAK_REALM\",\n \"client_id\": \"$CLIENT_ID\",\n \"scope\": \"openid email profile\",\n \"metadata\": {\n \"generated_by\": \"generate-agent-token.sh\",\n \"script_version\": \"1.0\",\n \"token_format\": \"JWT\",\n \"auth_method\": \"client_credentials\"\n }\n}\nEOF\n\n success \"Token saved to: $env_file\"\n success \"Token JSON saved to: $json_file\"\n echo \"\"\n echo \"Token has been saved securely to files (not displayed in terminal for security).\"\n echo \"\"\n echo \"To use the token, reference the saved files:\"\n echo \" - Token file: $json_file\"\n echo \" - Env file: $env_file\"\n echo \"\"\n echo \"Use with mcp_client.py:\"\n echo \" uv run python cli/mcp_client.py --token-file $json_file ...\"\n\nelse\n warning \"jq not available, showing raw response:\"\n echo \"$response\"\nfi" }, { "path": "keycloak/setup/get-all-client-credentials.sh", "content": "#!/bin/bash\n\n# Script to retrieve and save ALL client credentials from Keycloak\n# Usage: ./get-all-client-credentials.sh\n# This will fetch credentials for all clients in the mcp-gateway realm\n\nset -e\n\n# Color codes for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m' # No Color\n\n# Function to print colored output\nprint_success() { echo -e \"${GREEN}✓${NC} $1\"; }\nprint_error() { echo -e \"${RED}✗${NC} $1\"; }\nprint_info() { echo -e \"${YELLOW}ℹ${NC} $1\"; }\n\n# Get the directory where the script is being run from (should be project root)\nOUTPUT_DIR=\"$(pwd)/.oauth-tokens\"\n\n# Load environment variables\nif [ -f .env ]; then\n set -a\n source .env\n set +a\nfi\n\n# Set Keycloak connection details\nKEYCLOAK_URL=\"${KEYCLOAK_ADMIN_URL:-http://localhost:8080}\"\nKEYCLOAK_REALM=\"${KEYCLOAK_REALM:-mcp-gateway}\"\nKEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\nKEYCLOAK_ADMIN_PASSWORD=\"${KEYCLOAK_ADMIN_PASSWORD}\"\n\n# Check if admin password is set\nif [ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ]; then\n print_error \"KEYCLOAK_ADMIN_PASSWORD not set. Please export it or add it to .env file\"\n exit 1\nfi\n\nprint_info \"Retrieving all client credentials from realm: $KEYCLOAK_REALM\"\n\n# Get admin access token\nprint_info \"Getting admin token...\"\nTOKEN_RESPONSE=$(curl -s -X POST \\\n \"${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\")\n\nADMIN_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.access_token')\n\nif [ \"$ADMIN_TOKEN\" == \"null\" ] || [ -z \"$ADMIN_TOKEN\" ]; then\n print_error \"Failed to get admin token. Check your admin credentials.\"\n exit 1\nfi\nprint_success \"Admin token obtained\"\n\n# Create output directory if it doesn't exist\nmkdir -p \"$OUTPUT_DIR\"\n\n# Create the main credentials file\nOUTPUT_FILE=\"$OUTPUT_DIR/keycloak-client-secrets.txt\"\necho \"# Keycloak Client Credentials - Generated $(date)\" > \"$OUTPUT_FILE\"\necho \"# Realm: $KEYCLOAK_REALM\" >> \"$OUTPUT_FILE\"\necho \"# Keycloak URL: $KEYCLOAK_URL\" >> \"$OUTPUT_FILE\"\necho \"#\" >> \"$OUTPUT_FILE\"\necho \"# Add these to your .env file or use them in your applications\" >> \"$OUTPUT_FILE\"\necho \"\" >> \"$OUTPUT_FILE\"\n\n# Get all clients in the realm\nprint_info \"Fetching all clients in realm...\"\nCLIENTS_RESPONSE=$(curl -s -X GET \\\n \"${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/clients\" \\\n -H \"Authorization: Bearer ${ADMIN_TOKEN}\" \\\n -H \"Content-Type: application/json\")\n\n# Parse client IDs and filter out system clients\nCLIENT_COUNT=0\nCREDENTIAL_COUNT=0\n\n# First, specifically look for and process the main clients\nprint_info \"Processing main clients...\"\nfor MAIN_CLIENT in \"mcp-gateway-web\" \"mcp-gateway-m2m\"; do\n print_info \"Looking for main client: $MAIN_CLIENT\"\n\n # Get specific client by clientId\n CLIENT_DATA=$(echo \"$CLIENTS_RESPONSE\" | jq -r \".[] | select(.clientId == \\\"$MAIN_CLIENT\\\")\")\n\n if [ -n \"$CLIENT_DATA\" ] && [ \"$CLIENT_DATA\" != \"null\" ]; then\n CLIENT_UUID=$(echo \"$CLIENT_DATA\" | jq -r '.id')\n\n # Get client secret\n SECRET_RESPONSE=$(curl -s -X GET \\\n \"${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/clients/${CLIENT_UUID}/client-secret\" \\\n -H \"Authorization: Bearer ${ADMIN_TOKEN}\" \\\n -H \"Content-Type: application/json\")\n\n CLIENT_SECRET=$(echo $SECRET_RESPONSE | jq -r '.value // \"N/A\"')\n\n if [ \"$CLIENT_SECRET\" != \"N/A\" ] && [ \"$CLIENT_SECRET\" != \"null\" ]; then\n if [[ \"$MAIN_CLIENT\" == \"mcp-gateway-web\" ]]; then\n echo \"KEYCLOAK_CLIENT_ID=${MAIN_CLIENT}\" >> \"$OUTPUT_FILE\"\n echo \"KEYCLOAK_CLIENT_SECRET=${CLIENT_SECRET}\" >> \"$OUTPUT_FILE\"\n echo \"\" >> \"$OUTPUT_FILE\"\n print_success \" Found and saved: $MAIN_CLIENT\"\n elif [[ \"$MAIN_CLIENT\" == \"mcp-gateway-m2m\" ]]; then\n echo \"KEYCLOAK_M2M_CLIENT_ID=${MAIN_CLIENT}\" >> \"$OUTPUT_FILE\"\n echo \"KEYCLOAK_M2M_CLIENT_SECRET=${CLIENT_SECRET}\" >> \"$OUTPUT_FILE\"\n echo \"\" >> \"$OUTPUT_FILE\"\n print_success \" Found and saved: $MAIN_CLIENT\"\n fi\n\n # Also create individual files for these\n CLIENT_JSON_FILE=\"$OUTPUT_DIR/${MAIN_CLIENT}.json\"\n cat > \"$CLIENT_JSON_FILE\" <> \"$OUTPUT_FILE\"\n CLIENT_VAR_NAME=$(echo \"$CLIENT_ID\" | tr '[:lower:]' '[:upper:]' | tr '-' '_')\n echo \"${CLIENT_VAR_NAME}_CLIENT_ID=${CLIENT_ID}\" >> \"$OUTPUT_FILE\"\n echo \"${CLIENT_VAR_NAME}_CLIENT_SECRET=${CLIENT_SECRET}\" >> \"$OUTPUT_FILE\"\n echo \"\" >> \"$OUTPUT_FILE\"\n\n # Create individual JSON file for each client\n CLIENT_JSON_FILE=\"$OUTPUT_DIR/${CLIENT_ID}.json\"\n cat > \"$CLIENT_JSON_FILE\" <> \"$OUTPUT_FILE\"\necho \"# Summary\" >> \"$OUTPUT_FILE\"\necho \"# Total clients with credentials: $CREDENTIAL_COUNT\" >> \"$OUTPUT_FILE\"\necho \"# Generated on: $(date)\" >> \"$OUTPUT_FILE\"\n\n# Set secure permissions\nchmod 600 \"$OUTPUT_FILE\"\nchmod 600 \"$OUTPUT_DIR\"/*.json 2>/dev/null || true\n\nprint_success \"All client credentials retrieved and saved\"\necho \"\"\necho \"==================== Summary ====================\"\necho \"Main credentials file: $OUTPUT_FILE\"\necho \"Individual JSON files: $OUTPUT_DIR/.json\"\necho \"\"\necho \"Files created in: $OUTPUT_DIR/\"\nls -la \"$OUTPUT_DIR/\" | grep -E \"\\.(txt|json)$\"\necho \"==================================================\"\necho \"\"\nprint_info \"Note: These files contain sensitive credentials. Keep them secure!\"" }, { "path": "keycloak/setup/init-keycloak.sh", "content": "#!/bin/bash\n# Initialize Keycloak with MCP Gateway configuration\n# This script sets up the initial realm, clients, groups, and users\n\nset -e\n\n# These will be set properly after loading .env in main()\nKEYCLOAK_URL=\"\" # Will be overridden with KEYCLOAK_ADMIN_URL after .env is loaded\nREALM=\"mcp-gateway\"\nKEYCLOAK_ADMIN=\"\"\nKEYCLOAK_ADMIN_PASSWORD=\"\"\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m' # No Color\n\necho -e \"${YELLOW}Keycloak initialization script for MCP Gateway Registry${NC}\"\necho \"==============================================\"\n\n# Function to wait for Keycloak to be ready\nwait_for_keycloak() {\n echo -n \"Waiting for Keycloak to be ready...\"\n local max_attempts=60\n local attempt=0\n \n while [ $attempt -lt $max_attempts ]; do\n # Try to access the admin console which indicates Keycloak is ready\n if curl -f -s \"${KEYCLOAK_URL}/admin/\" > /dev/null 2>&1; then\n echo -e \" ${GREEN}Ready!${NC}\"\n return 0\n fi\n echo -n \".\"\n sleep 5\n attempt=$((attempt + 1))\n done\n \n echo -e \" ${RED}Timeout!${NC}\"\n echo \"Keycloak did not become ready within 5 minutes\"\n exit 1\n}\n\n# Function to get admin token\nget_admin_token() {\n local response=$(curl -s -X POST \"${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${KEYCLOAK_ADMIN}\" \\\n -d \"password=${KEYCLOAK_ADMIN_PASSWORD}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\")\n \n echo \"$response\" | grep -o '\"access_token\":\"[^\"]*' | cut -d'\"' -f4\n}\n\n# Function to check if realm exists\nrealm_exists() {\n local token=$1\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}\")\n \n [ \"$response\" = \"200\" ]\n}\n\n# Function to create realm step by step\ncreate_realm() {\n local token=$1\n \n echo \"Creating MCP Gateway realm...\"\n \n # Check if realm already exists\n if realm_exists \"$token\"; then\n echo -e \"${YELLOW}Realm already exists. Skipping creation...${NC}\"\n return 0\n fi\n \n # Create basic realm\n local realm_json='{\n \"realm\": \"mcp-gateway\",\n \"enabled\": true,\n \"registrationAllowed\": false,\n \"loginWithEmailAllowed\": true,\n \"duplicateEmailsAllowed\": false,\n \"resetPasswordAllowed\": true,\n \"editUsernameAllowed\": false\n }'\n \n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$realm_json\")\n \n if [ \"$response\" = \"201\" ]; then\n echo -e \"${GREEN}Realm created successfully!${NC}\"\n return 0\n elif [ \"$response\" = \"409\" ]; then\n echo -e \"${YELLOW}Realm already exists. Continuing...${NC}\"\n return 0\n else\n echo -e \"${RED}Failed to create realm. HTTP status: ${response}${NC}\"\n echo \"Response body:\"\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$realm_json\"\n echo \"\"\n return 1\n fi\n}\n\n# Function to create clients\ncreate_clients() {\n local token=$1\n \n echo \"Creating OAuth2 clients...\"\n \n # Create web client\n local web_client_json='{\n \"clientId\": \"mcp-gateway-web\",\n \"name\": \"MCP Gateway Web Client\",\n \"enabled\": true,\n \"clientAuthenticatorType\": \"client-secret\",\n \"redirectUris\": [\n \"'${AUTH_SERVER_EXTERNAL_URL:-http://localhost:8888}'/oauth2/callback/keycloak\",\n \"'${REGISTRY_URL:-http://localhost:7860}'/*\",\n \"http://localhost:7860/*\",\n \"http://localhost:8888/*\"\n ],\n \"webOrigins\": [\n \"'${REGISTRY_URL:-http://localhost:7860}'\",\n \"http://localhost:7860\",\n \"+\"\n ],\n \"protocol\": \"openid-connect\",\n \"standardFlowEnabled\": true,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": true,\n \"serviceAccountsEnabled\": false,\n \"publicClient\": false\n }'\n \n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$web_client_json\" > /dev/null\n \n # Create M2M client\n local m2m_client_json='{\n \"clientId\": \"mcp-gateway-m2m\",\n \"name\": \"MCP Gateway M2M Client\",\n \"enabled\": true,\n \"clientAuthenticatorType\": \"client-secret\",\n \"protocol\": \"openid-connect\",\n \"standardFlowEnabled\": false,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": false,\n \"serviceAccountsEnabled\": true,\n \"publicClient\": false\n }'\n \n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$m2m_client_json\" > /dev/null\n \n echo -e \"${GREEN}Clients created successfully!${NC}\"\n}\n\n# Function to create groups\ncreate_groups() {\n local token=$1\n \n echo \"Creating user groups...\"\n \n local groups=(\"mcp-registry-admin\" \"mcp-registry-user\" \"mcp-registry-developer\" \"mcp-registry-operator\" \"mcp-servers-unrestricted\" \"mcp-servers-restricted\" \"a2a-agent-admin\" \"a2a-agent-publisher\" \"a2a-agent-user\")\n \n for group in \"${groups[@]}\"; do\n local group_json='{\n \"name\": \"'$group'\",\n \"attributes\": {\n \"description\": [\"'$group' group for MCP Gateway access\"]\n }\n }'\n \n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/mcp-gateway/groups\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$group_json\" > /dev/null\n done\n \n echo -e \"${GREEN}Groups created successfully!${NC}\"\n}\n\n# Function to create custom scopes\ncreate_scopes() {\n local token=$1\n \n echo \"Creating custom MCP scopes...\"\n \n local scopes=(\"mcp-servers-unrestricted/read\" \"mcp-servers-unrestricted/execute\" \"mcp-servers-restricted/read\" \"mcp-servers-restricted/execute\")\n \n for scope in \"${scopes[@]}\"; do\n local scope_json='{\n \"name\": \"'$scope'\",\n \"description\": \"MCP Gateway scope for '$scope' access\",\n \"protocol\": \"openid-connect\"\n }'\n \n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/client-scopes\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$scope_json\")\n \n if [ \"$response\" = \"201\" ]; then\n echo \" - Created scope: $scope\"\n elif [ \"$response\" = \"409\" ]; then\n echo \" - Scope already exists: $scope\"\n else\n echo -e \"${RED} - Failed to create scope: $scope (HTTP $response)${NC}\"\n fi\n done\n \n echo -e \"${GREEN}Custom scopes created successfully!${NC}\"\n}\n\n# Function to assign scopes to M2M client\nsetup_m2m_scopes() {\n local token=$1\n \n echo \"Setting up M2M client scopes...\"\n \n # Get M2M client ID\n local m2m_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-m2m\" | \\\n jq -r '.[0].id')\n \n if [ -z \"$m2m_client_id\" ] || [ \"$m2m_client_id\" = \"null\" ]; then\n echo -e \"${RED}Error: Could not find mcp-gateway-m2m client${NC}\"\n return 1\n fi\n \n # Get all available client scopes\n local scopes=(\"mcp-servers-unrestricted/read\" \"mcp-servers-unrestricted/execute\" \"mcp-servers-restricted/read\" \"mcp-servers-restricted/execute\")\n \n for scope in \"${scopes[@]}\"; do\n # Get scope ID\n local scope_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/client-scopes\" | \\\n jq -r '.[] | select(.name==\"'$scope'\") | .id')\n \n if [ ! -z \"$scope_id\" ] && [ \"$scope_id\" != \"null\" ]; then\n # Add scope as default client scope\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/default-client-scopes/${scope_id}\" \\\n -H \"Authorization: Bearer ${token}\")\n \n if [ \"$response\" = \"204\" ]; then\n echo \" - Assigned scope: $scope\"\n else\n echo -e \"${YELLOW} - Warning: Could not assign scope $scope (HTTP $response)${NC}\"\n fi\n else\n echo -e \"${RED} - Error: Could not find scope: $scope${NC}\"\n fi\n done\n \n echo -e \"${GREEN}M2M client scopes configured successfully!${NC}\"\n}\n\n# Function to create service account user for M2M client\ncreate_service_account_user() {\n local token=$1\n local service_account_username=\"service-account-mcp-gateway-m2m\"\n \n echo \"Creating service account user: $service_account_username\"\n \n # Check if user already exists\n local existing_user=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$service_account_username\" | \\\n jq -r '.[0].id // empty')\n \n if [ ! -z \"$existing_user\" ]; then\n echo -e \"${YELLOW}Service account user already exists with ID: $existing_user${NC}\"\n return 0\n fi\n \n # Create service account user\n local user_json='{\n \"username\": \"'$service_account_username'\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"serviceAccountClientId\": \"mcp-gateway-m2m\"\n }'\n \n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/users\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$user_json\")\n \n if [ \"$response\" = \"201\" ]; then\n echo -e \"${GREEN}Service account user created successfully!${NC}\"\n \n # Get the newly created user ID\n local user_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$service_account_username\" | \\\n jq -r '.[0].id')\n \n echo \"Created service account user with ID: $user_id\"\n \n # Assign user to mcp-servers-unrestricted group\n local group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-servers-unrestricted\") | .id')\n\n if [ ! -z \"$group_id\" ] && [ \"$group_id\" != \"null\" ]; then\n local group_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$user_id/groups/$group_id\" \\\n -H \"Authorization: Bearer ${token}\")\n\n if [ \"$group_response\" = \"204\" ]; then\n echo -e \"${GREEN}Service account assigned to mcp-servers-unrestricted group!${NC}\"\n else\n echo -e \"${YELLOW}Warning: Could not assign service account to mcp-servers-unrestricted group (HTTP $group_response)${NC}\"\n fi\n else\n echo -e \"${RED}Error: Could not find mcp-servers-unrestricted group${NC}\"\n fi\n\n # Assign user to a2a-agent-admin group for A2A agent access\n local a2a_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"a2a-agent-admin\") | .id')\n\n if [ ! -z \"$a2a_group_id\" ] && [ \"$a2a_group_id\" != \"null\" ]; then\n local a2a_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$user_id/groups/$a2a_group_id\" \\\n -H \"Authorization: Bearer ${token}\")\n\n if [ \"$a2a_response\" = \"204\" ]; then\n echo -e \"${GREEN}Service account assigned to a2a-agent-admin group!${NC}\"\n else\n echo -e \"${YELLOW}Warning: Could not assign service account to a2a-agent-admin group (HTTP $a2a_response)${NC}\"\n fi\n else\n echo -e \"${YELLOW}Warning: a2a-agent-admin group not found. Create it manually if A2A agent support is needed.${NC}\"\n fi\n \n return 0\n elif [ \"$response\" = \"409\" ]; then\n echo -e \"${YELLOW}Service account user already exists. Continuing...${NC}\"\n return 0\n else\n echo -e \"${RED}Failed to create service account user. HTTP status: ${response}${NC}\"\n return 1\n fi\n}\n\n# Function to create test users\ncreate_users() {\n local token=$1\n \n echo \"Creating test users...\"\n \n # Define usernames for consistency\n local admin_username=\"admin\"\n local test_username=\"testuser\"\n \n # Create admin user\n local admin_user_json='{\n \"username\": \"'$admin_username'\",\n \"email\": \"'$admin_username'@example.com\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"firstName\": \"Admin\",\n \"lastName\": \"User\",\n \"credentials\": [\n {\n \"type\": \"password\",\n \"value\": \"'${INITIAL_ADMIN_PASSWORD:-changeme}'\",\n \"temporary\": false\n }\n ]\n }'\n \n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/users\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$admin_user_json\" > /dev/null\n \n # Create test user\n local test_user_json='{\n \"username\": \"'$test_username'\",\n \"email\": \"'$test_username'@example.com\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"firstName\": \"Test\",\n \"lastName\": \"User\",\n \"credentials\": [\n {\n \"type\": \"password\",\n \"value\": \"'${INITIAL_USER_PASSWORD:-testpass}'\",\n \"temporary\": false\n }\n ]\n }'\n \n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/users\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$test_user_json\" > /dev/null\n \n echo \"Assigning users to groups...\"\n \n # Get user IDs\n local admin_user_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$admin_username\" | \\\n jq -r '.[0].id')\n \n local test_user_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=$test_username\" | \\\n jq -r '.[0].id')\n \n # Get all group IDs\n local admin_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-admin\") | .id')\n \n local user_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-user\") | .id')\n \n local developer_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-developer\") | .id')\n \n local operator_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-registry-operator\") | .id')\n \n local unrestricted_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-servers-unrestricted\") | .id')\n \n local restricted_group_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r '.[] | select(.name==\"mcp-servers-restricted\") | .id')\n \n # Define usernames for consistent logging\n local admin_username=\"admin\"\n local test_username=\"testuser\"\n \n # Assign admin user to admin group and unrestricted servers group\n if [ ! -z \"$admin_user_id\" ] && [ ! -z \"$admin_group_id\" ]; then\n curl -s -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$admin_user_id/groups/$admin_group_id\" \\\n -H \"Authorization: Bearer ${token}\" > /dev/null\n echo \" - $admin_username assigned to mcp-registry-admin group\"\n fi\n \n # Also assign admin to unrestricted servers group for full access\n if [ ! -z \"$admin_user_id\" ] && [ ! -z \"$unrestricted_group_id\" ]; then\n curl -s -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$admin_user_id/groups/$unrestricted_group_id\" \\\n -H \"Authorization: Bearer ${token}\" > /dev/null\n echo \" - $admin_username assigned to mcp-servers-unrestricted group\"\n fi\n \n # Assign test user to all groups except admin\n if [ ! -z \"$test_user_id\" ]; then\n # Arrays of group IDs and names for loop processing\n local group_ids=(\"$user_group_id\" \"$developer_group_id\" \"$operator_group_id\" \"$unrestricted_group_id\" \"$restricted_group_id\")\n local group_names=(\"mcp-registry-user\" \"mcp-registry-developer\" \"mcp-registry-operator\" \"mcp-servers-unrestricted\" \"mcp-servers-restricted\")\n \n # Loop through groups and assign test user to each\n for i in \"${!group_ids[@]}\"; do\n local group_id=\"${group_ids[$i]}\"\n local group_name=\"${group_names[$i]}\"\n \n if [ ! -z \"$group_id\" ]; then\n curl -s -X PUT \"${KEYCLOAK_URL}/admin/realms/${REALM}/users/$test_user_id/groups/$group_id\" \\\n -H \"Authorization: Bearer ${token}\" > /dev/null\n echo \" - $test_username assigned to $group_name group\"\n fi\n done\n fi\n \n echo -e \"${GREEN}Users created and assigned to groups successfully!${NC}\"\n}\n\n# Function to create client secrets\nsetup_client_secrets() {\n local token=$1\n \n echo \"Setting up client secrets...\"\n \n # Get web client ID\n local web_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-web\" | \\\n jq -r '.[0].id')\n \n # Generate secret for web client\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${web_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" > /dev/null\n \n local web_secret_response=$(curl -s \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${web_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\")\n web_secret=$(echo \"$web_secret_response\" | jq -r '.value // empty')\n \n # Get M2M client ID\n local m2m_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-m2m\" | \\\n jq -r '.[0].id')\n \n # Generate secret for M2M client\n curl -s -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" > /dev/null\n \n local m2m_secret_response=$(curl -s \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/client-secret\" \\\n -H \"Authorization: Bearer ${token}\")\n m2m_secret=$(echo \"$m2m_secret_response\" | jq -r '.value // empty')\n \n echo -e \"${GREEN}Client secrets generated!${NC}\"\n echo \"\"\n echo \"==============================================\"\n echo -e \"${YELLOW}Client credentials have been created.${NC}\"\n echo \"==============================================\"\n echo \"\"\n echo -e \"${GREEN}To retrieve all client credentials, run:${NC}\"\n echo \" ./keycloak/setup/get-all-client-credentials.sh\"\n echo \"\"\n echo \"This will save all credentials to .oauth-tokens/\"\n echo \"==============================================\"\n}\n\n# Function to setup groups mapper for OAuth2 clients\nsetup_groups_mapper() {\n local token=$1\n\n echo \"Setting up groups mapper for OAuth2 clients...\"\n\n # Create groups mapper JSON\n local groups_mapper_json='{\n \"name\": \"groups\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-group-membership-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"full.path\": \"false\",\n \"id.token.claim\": \"true\",\n \"access.token.claim\": \"true\",\n \"claim.name\": \"groups\",\n \"userinfo.token.claim\": \"true\"\n }\n }'\n\n # Setup groups mapper for mcp-gateway-web client\n echo \"Setting up groups mapper for mcp-gateway-web client...\"\n local web_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-web\" | \\\n jq -r '.[0].id')\n\n if [ -z \"$web_client_id\" ] || [ \"$web_client_id\" = \"null\" ]; then\n echo -e \"${RED}Error: Could not find mcp-gateway-web client${NC}\"\n return 1\n fi\n\n local response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${web_client_id}/protocol-mappers/models\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$groups_mapper_json\")\n\n if [ \"$response\" = \"201\" ]; then\n echo -e \"${GREEN}Groups mapper created for mcp-gateway-web!${NC}\"\n elif [ \"$response\" = \"409\" ]; then\n echo -e \"${YELLOW}Groups mapper already exists for mcp-gateway-web. Continuing...${NC}\"\n else\n echo -e \"${RED}Failed to create groups mapper for mcp-gateway-web. HTTP status: ${response}${NC}\"\n return 1\n fi\n\n # Setup groups mapper for mcp-gateway-m2m client\n echo \"Setting up groups mapper for mcp-gateway-m2m client...\"\n local m2m_client_id=$(curl -s -H \"Authorization: Bearer ${token}\" \\\n \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=mcp-gateway-m2m\" | \\\n jq -r '.[0].id')\n\n if [ -z \"$m2m_client_id\" ] || [ \"$m2m_client_id\" = \"null\" ]; then\n echo -e \"${RED}Error: Could not find mcp-gateway-m2m client${NC}\"\n return 1\n fi\n\n local m2m_response=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${m2m_client_id}/protocol-mappers/models\" \\\n -H \"Authorization: Bearer ${token}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$groups_mapper_json\")\n\n if [ \"$m2m_response\" = \"201\" ]; then\n echo -e \"${GREEN}Groups mapper created for mcp-gateway-m2m!${NC}\"\n elif [ \"$m2m_response\" = \"409\" ]; then\n echo -e \"${YELLOW}Groups mapper already exists for mcp-gateway-m2m. Continuing...${NC}\"\n else\n echo -e \"${RED}Failed to create groups mapper for mcp-gateway-m2m. HTTP status: ${m2m_response}${NC}\"\n return 1\n fi\n}\n\n# Main execution\nmain() {\n # Get script directory and find .env file\n SCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" && pwd )\"\n PROJECT_ROOT=\"$( cd \"$SCRIPT_DIR/../..\" && pwd )\"\n ENV_FILE=\"$PROJECT_ROOT/.env\"\n \n # Load environment variables from .env file if it exists\n if [ -f \"$ENV_FILE\" ]; then\n echo \"Loading environment variables from $ENV_FILE...\"\n set -a # Automatically export all variables\n source \"$ENV_FILE\"\n set +a # Turn off automatic export\n echo \"Environment variables loaded successfully\"\n else\n echo \"No .env file found at $ENV_FILE\"\n echo \"Current directory: $(pwd)\"\n echo \"Script directory: $SCRIPT_DIR\"\n echo \"Project root: $PROJECT_ROOT\"\n fi\n \n # Override KEYCLOAK_URL with KEYCLOAK_ADMIN_URL for API calls\n KEYCLOAK_URL=\"${KEYCLOAK_ADMIN_URL:-http://localhost:8080}\"\n KEYCLOAK_ADMIN=\"${KEYCLOAK_ADMIN:-admin}\"\n echo \"Using Keycloak API URL: $KEYCLOAK_URL\"\n\n # Check if admin password is set\n if [ -z \"$KEYCLOAK_ADMIN_PASSWORD\" ]; then\n echo -e \"${RED}Error: KEYCLOAK_ADMIN_PASSWORD environment variable is not set${NC}\"\n echo \"Please set it in .env file or export it before running this script\"\n exit 1\n fi\n \n # Wait for Keycloak to be ready\n wait_for_keycloak\n \n # Get admin token\n echo \"Authenticating with Keycloak...\"\n TOKEN=$(get_admin_token)\n \n if [ -z \"$TOKEN\" ]; then\n echo -e \"${RED}Error: Failed to authenticate with Keycloak${NC}\"\n echo \"Please check your admin credentials\"\n exit 1\n fi\n \n echo -e \"${GREEN}Authentication successful!${NC}\"\n \n # Create realm and configure it step by step\n if create_realm \"$TOKEN\"; then\n create_clients \"$TOKEN\"\n create_scopes \"$TOKEN\"\n create_groups \"$TOKEN\"\n create_users \"$TOKEN\"\n create_service_account_user \"$TOKEN\"\n setup_client_secrets \"$TOKEN\"\n setup_groups_mapper \"$TOKEN\"\n setup_m2m_scopes \"$TOKEN\"\n else\n exit 1\n fi\n \n echo \"\"\n echo -e \"${GREEN}Keycloak initialization complete!${NC}\"\n echo \"\"\n echo \"You can now access Keycloak at: ${KEYCLOAK_URL}\"\n echo \"Admin console: ${KEYCLOAK_URL}/admin\"\n echo \"Realm: ${REALM}\"\n echo \"\"\n echo \"Default users created:\"\n echo \" - admin/changeme (admin access)\"\n echo \" - testuser/testpass (user access)\"\n echo \"\"\n echo -e \"${YELLOW}Remember to change the default passwords!${NC}\"\n}\n\n# Run main function\nmain" }, { "path": "keycloak/setup/setup-agent-service-account.sh", "content": "#!/bin/bash\n# Agent-Specific M2M Service Account Setup Script\n# This script creates individual service accounts for AI agents with proper audit trails\n\nset -e\n\n# Configuration\nADMIN_URL=\"http://localhost:8080\"\nREALM=\"mcp-gateway\"\nADMIN_USER=\"admin\"\nADMIN_PASS=\"${KEYCLOAK_ADMIN_PASSWORD}\"\n\n# Check required environment variables\nif [ -z \"$ADMIN_PASS\" ]; then\n echo -e \"${RED}Error: KEYCLOAK_ADMIN_PASSWORD environment variable is required${NC}\"\n echo \"Please set it before running this script:\"\n echo \"export KEYCLOAK_ADMIN_PASSWORD=\\\"your-secure-password\\\"\"\n exit 1\nfi\nM2M_CLIENT=\"mcp-gateway-m2m\"\n\n# Colors for output\nGREEN='\\033[0;32m'\nRED='\\033[0;31m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\n# Usage function\nusage() {\n echo \"Usage: $0 [OPTIONS]\"\n echo \"\"\n echo \"Create a Keycloak service account for an AI agent with proper audit trails\"\n echo \"\"\n echo \"Options:\"\n echo \" -a, --agent-id AGENT_ID Agent identifier (required)\"\n echo \" -g, --group GROUP Group assignment (default: mcp-servers-restricted)\"\n echo \" -c, --client CLIENT M2M client name (default: mcp-gateway-m2m)\"\n echo \" -h, --help Show this help message\"\n echo \"\"\n echo \"Examples:\"\n echo \" $0 --agent-id claude-001\"\n echo \" $0 --agent-id bedrock-claude --group mcp-servers-unrestricted\"\n echo \" $0 -a gpt4-turbo -g mcp-servers-restricted\"\n echo \" $0 -a finance-agent -g mcp-servers-finance/read\"\n echo \"\"\n echo \"Service Account Naming: agent-{agent-id}-m2m\"\n echo \"\"\n echo \"Common Groups:\"\n echo \" - mcp-servers-restricted (limited access)\"\n echo \" - mcp-servers-unrestricted (full access)\"\n echo \" - mcp-servers-finance/read (finance read access)\"\n echo \" - mcp-servers-finance/execute (finance execute access)\"\n echo \"\"\n echo \"Note: Group must exist in Keycloak. Script will validate and show available groups if invalid.\"\n}\n\n# Parse command line arguments\nAGENT_ID=\"\"\nTARGET_GROUP=\"mcp-servers-restricted\"\n\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n -a|--agent-id)\n AGENT_ID=\"$2\"\n shift 2\n ;;\n -g|--group)\n TARGET_GROUP=\"$2\"\n shift 2\n ;;\n -c|--client)\n M2M_CLIENT=\"$2\"\n shift 2\n ;;\n -h|--help)\n usage\n exit 0\n ;;\n *)\n echo -e \"${RED}Unknown option: $1${NC}\"\n usage\n exit 1\n ;;\n esac\ndone\n\n# Validate required parameters\nif [ -z \"$AGENT_ID\" ]; then\n echo -e \"${RED}Error: Agent ID is required${NC}\"\n usage\n exit 1\nfi\n\n# Generate service account name and client ID\nSERVICE_ACCOUNT=\"agent-${AGENT_ID}-m2m\"\nAGENT_CLIENT_ID=\"agent-${AGENT_ID}-m2m\"\n\necho -e \"${BLUE}Setting up Agent-Specific M2M Client and Service Account${NC}\"\necho \"==============================================\"\necho \"Agent ID: $AGENT_ID\"\necho \"Agent Client ID: $AGENT_CLIENT_ID\"\necho \"Service Account: $SERVICE_ACCOUNT\"\necho \"Target Group: $TARGET_GROUP\"\necho \"\"\n\n# Function to get admin token\nget_admin_token() {\n echo \"Getting admin token...\"\n TOKEN=$(curl -s -X POST \"$ADMIN_URL/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=$ADMIN_USER\" \\\n -d \"password=$ADMIN_PASS\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token // empty')\n\n if [ -z \"$TOKEN\" ]; then\n echo -e \"${RED}Failed to get admin token${NC}\"\n exit 1\n fi\n echo -e \"${GREEN}✓ Admin token obtained${NC}\"\n}\n\n# Function to validate group exists\nvalidate_group_exists() {\n echo \"Validating group exists: $TARGET_GROUP...\"\n\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$TARGET_GROUP\\\") | .id\")\n\n if [ -z \"$GROUP_ID\" ] || [ \"$GROUP_ID\" = \"null\" ]; then\n echo -e \"${RED}Error: Group '$TARGET_GROUP' does not exist in Keycloak${NC}\"\n echo -e \"${YELLOW}Available groups:${NC}\"\n curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r '.[].name' | sed 's/^/ - /'\n exit 1\n fi\n\n echo -e \"${GREEN}✓ Group '$TARGET_GROUP' exists${NC}\"\n}\n\n# Function to create agent-specific M2M client\ncreate_agent_m2m_client() {\n echo \"Creating agent-specific M2M client...\"\n \n # Check if client already exists\n EXISTING_CLIENT=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients?clientId=$AGENT_CLIENT_ID\" | \\\n jq -r '.[0].id // empty')\n \n if [ ! -z \"$EXISTING_CLIENT\" ] && [ \"$EXISTING_CLIENT\" != \"null\" ]; then\n echo -e \"${YELLOW}Agent M2M client already exists with ID: $EXISTING_CLIENT${NC}\"\n CLIENT_ID=\"$EXISTING_CLIENT\"\n return 0\n fi\n \n # Create the M2M client\n CLIENT_JSON='{\n \"clientId\": \"'$AGENT_CLIENT_ID'\",\n \"name\": \"Agent M2M Client for '$AGENT_ID'\",\n \"description\": \"Machine-to-Machine client for AI agent '$AGENT_ID' with individual audit trails\",\n \"enabled\": true,\n \"clientAuthenticatorType\": \"client-secret\",\n \"serviceAccountsEnabled\": true,\n \"standardFlowEnabled\": false,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": false,\n \"publicClient\": false,\n \"protocol\": \"openid-connect\",\n \"attributes\": {\n \"agent_id\": \"'$AGENT_ID'\",\n \"client_type\": \"agent_m2m\",\n \"created_by\": \"keycloak_setup_script\"\n },\n \"defaultClientScopes\": [\n \"web-origins\",\n \"acr\",\n \"profile\",\n \"roles\",\n \"email\"\n ]\n }'\n \n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/clients\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$CLIENT_JSON\")\n \n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ Agent M2M client created successfully${NC}\"\n \n # Get the client ID\n CLIENT_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients?clientId=$AGENT_CLIENT_ID\" | \\\n jq -r '.[0].id')\n \n echo \"Client UUID: $CLIENT_ID\"\n else\n echo -e \"${RED}Failed to create agent M2M client. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n# Function to check if service account user exists\ncheck_service_account() {\n echo \"Checking if service account exists...\"\n USER_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$SERVICE_ACCOUNT\" | \\\n jq -r '.[0].id // empty')\n \n if [ -n \"$USER_ID\" ] && [ \"$USER_ID\" != \"null\" ]; then\n echo -e \"${GREEN}✓ Service account already exists with ID: $USER_ID${NC}\"\n return 0\n else\n echo \"Service account does not exist\"\n return 1\n fi\n}\n\n# Function to create service account user\ncreate_service_account() {\n echo \"Creating service account user...\"\n \n USER_JSON='{\n \"username\": \"'$SERVICE_ACCOUNT'\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"serviceAccountClientId\": \"'$AGENT_CLIENT_ID'\",\n \"attributes\": {\n \"agent_id\": [\"'$AGENT_ID'\"],\n \"agent_client_id\": [\"'$AGENT_CLIENT_ID'\"],\n \"account_type\": [\"agent_service_account\"],\n \"created_by\": [\"keycloak_setup_script\"]\n }\n }'\n \n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/users\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$USER_JSON\")\n \n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ Service account user created successfully${NC}\"\n \n # Get the user ID\n USER_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$SERVICE_ACCOUNT\" | \\\n jq -r '.[0].id')\n \n echo \"User ID: $USER_ID\"\n else\n echo -e \"${RED}Failed to create user. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n# Function to get or create target group\nensure_target_group() {\n echo \"Checking if target group exists...\"\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$TARGET_GROUP\\\") | .id\")\n \n if [ -n \"$GROUP_ID\" ] && [ \"$GROUP_ID\" != \"null\" ]; then\n echo -e \"${GREEN}✓ Target group '$TARGET_GROUP' exists with ID: $GROUP_ID${NC}\"\n else\n echo \"Creating target group '$TARGET_GROUP'...\"\n \n GROUP_JSON='{\n \"name\": \"'$TARGET_GROUP'\",\n \"path\": \"/'$TARGET_GROUP'\"\n }'\n \n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/groups\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$GROUP_JSON\")\n \n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ Target group created successfully${NC}\"\n \n # Get the group ID\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$TARGET_GROUP\\\") | .id\")\n \n echo \"Group ID: $GROUP_ID\"\n else\n echo -e \"${RED}Failed to create group. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n fi\n}\n\n# Function to assign service account to group\nassign_to_group() {\n echo \"Assigning service account to target group...\"\n \n # Check if already assigned\n CURRENT_GROUPS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users/$USER_ID/groups\" | \\\n jq -r \".[].name\")\n \n if echo \"$CURRENT_GROUPS\" | grep -q \"$TARGET_GROUP\"; then\n echo -e \"${GREEN}✓ Service account already assigned to '$TARGET_GROUP' group${NC}\"\n return 0\n fi\n \n # Assign to group\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"$ADMIN_URL/admin/realms/$REALM/users/$USER_ID/groups/$GROUP_ID\" \\\n -H \"Authorization: Bearer $TOKEN\")\n \n if [ \"$RESPONSE\" = \"204\" ]; then\n echo -e \"${GREEN}✓ Service account assigned to '$TARGET_GROUP' group${NC}\"\n else\n echo -e \"${RED}Failed to assign to group. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n# Function to get agent M2M client secret\nget_agent_client_secret() {\n echo \"Retrieving agent M2M client secret...\"\n \n if [ -z \"$CLIENT_ID\" ]; then\n echo -e \"${RED}Error: CLIENT_ID not set${NC}\"\n exit 1\n fi\n \n # Get the client secret\n SECRET_RESPONSE=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$CLIENT_ID/client-secret\")\n \n AGENT_CLIENT_SECRET=$(echo \"$SECRET_RESPONSE\" | jq -r '.value // empty')\n \n if [ -z \"$AGENT_CLIENT_SECRET\" ]; then\n echo -e \"${RED}Failed to retrieve agent client secret${NC}\"\n exit 1\n fi\n \n echo -e \"${GREEN}✓ Agent client secret retrieved${NC}\"\n}\n\n# Function to ensure groups mapper exists\nensure_groups_mapper() {\n echo \"Checking for groups mapper on M2M client...\"\n \n # Check if groups mapper already exists\n EXISTING_MAPPER=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$CLIENT_ID/protocol-mappers/models\" | \\\n jq -r '.[] | select(.name==\"groups\") | .id')\n \n if [ -n \"$EXISTING_MAPPER\" ] && [ \"$EXISTING_MAPPER\" != \"null\" ]; then\n echo -e \"${GREEN}✓ Groups mapper already exists${NC}\"\n return 0\n fi\n \n echo \"Adding groups mapper to M2M client...\"\n \n GROUPS_MAPPER='{\n \"name\": \"groups\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-group-membership-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"full.path\": \"false\",\n \"id.token.claim\": \"true\",\n \"access.token.claim\": \"true\",\n \"claim.name\": \"groups\",\n \"userinfo.token.claim\": \"true\"\n }\n }'\n \n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/clients/$CLIENT_ID/protocol-mappers/models\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$GROUPS_MAPPER\")\n \n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ Groups mapper added successfully${NC}\"\n elif [ \"$RESPONSE\" = \"409\" ]; then\n echo -e \"${GREEN}✓ Groups mapper already exists${NC}\"\n else\n echo -e \"${RED}Failed to add groups mapper. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n# Function to verify setup\nverify_setup() {\n echo \"\"\n echo \"Verifying setup...\"\n \n # Check service account exists and is in the right group\n GROUPS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users/$USER_ID/groups\" | \\\n jq -r '.[].name')\n \n echo \"Service account groups: $GROUPS\"\n \n if echo \"$GROUPS\" | grep -q \"$TARGET_GROUP\"; then\n echo -e \"${GREEN}✓ Service account is in '$TARGET_GROUP' group${NC}\"\n else\n echo -e \"${RED}✗ Service account is NOT in '$TARGET_GROUP' group${NC}\"\n exit 1\n fi\n \n # Check groups mapper exists\n MAPPER_EXISTS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$CLIENT_ID/protocol-mappers/models\" | \\\n jq -r '.[] | select(.name==\"groups\") | .name')\n \n if [ \"$MAPPER_EXISTS\" = \"groups\" ]; then\n echo -e \"${GREEN}✓ Groups mapper is configured${NC}\"\n else\n echo -e \"${RED}✗ Groups mapper is NOT configured${NC}\"\n exit 1\n fi\n}\n\n# Function to generate agent-specific token\ngenerate_agent_token() {\n echo \"\"\n echo \"Generating agent-specific token configuration...\"\n \n # Create agent-specific token file\n AGENT_TOKEN_DIR=\".oauth-tokens\"\n AGENT_TOKEN_FILE=\"$AGENT_TOKEN_DIR/agent-${AGENT_ID}.json\"\n \n mkdir -p \"$AGENT_TOKEN_DIR\"\n \n cat > \"$AGENT_TOKEN_FILE\" << EOF\n{\n \"provider\": \"keycloak_m2m\",\n \"agent_id\": \"$AGENT_ID\",\n \"service_account\": \"$SERVICE_ACCOUNT\",\n \"group\": \"$TARGET_GROUP\",\n \"client_id\": \"$AGENT_CLIENT_ID\",\n \"client_secret\": \"$AGENT_CLIENT_SECRET\",\n \"keycloak_url\": \"https://mcpgateway.ddns.net/keycloak\",\n \"realm\": \"$REALM\",\n \"saved_at\": \"$(date -u '+%Y-%m-%d %H:%M:%S UTC')\",\n \"usage_notes\": \"Individual M2M client credentials for agent $AGENT_ID with complete audit trails\"\n}\nEOF\n \n echo -e \"${GREEN}✓ Agent token configuration created: $AGENT_TOKEN_FILE${NC}\"\n}\n\n# Main execution\nmain() {\n get_admin_token\n\n # Step 0: Validate group exists in Keycloak\n validate_group_exists\n\n # Step 1: Create agent-specific M2M client\n create_agent_m2m_client\n \n # Step 2: Get agent client secret\n get_agent_client_secret\n \n # Step 3: Create service account linked to agent client\n if ! check_service_account; then\n create_service_account\n fi\n \n # Step 4: Ensure target group exists\n ensure_target_group\n \n # Step 5: Assign service account to group\n assign_to_group\n \n # Step 6: Ensure groups mapper exists on agent client\n ensure_groups_mapper\n \n # Step 7: Verify everything is set up correctly\n verify_setup\n \n # Step 8: Generate agent-specific token configuration\n generate_agent_token\n \n echo \"\"\n echo -e \"${GREEN}SUCCESS! Agent service account setup complete.${NC}\"\n echo \"\"\n echo -e \"${YELLOW}Agent Details:${NC}\"\n echo \"- Agent ID: $AGENT_ID\"\n echo \"- Agent Client ID: $AGENT_CLIENT_ID\"\n echo \"- Agent Client Secret: ${AGENT_CLIENT_SECRET:0:10}...\"\n echo \"- Service Account: $SERVICE_ACCOUNT\"\n echo \"- Group: $TARGET_GROUP\"\n echo \"- Token Config: .oauth-tokens/agent-${AGENT_ID}.json\"\n echo \"\"\n echo -e \"${YELLOW}Next steps:${NC}\"\n echo \"1. Generate agent-specific M2M token:\"\n echo \" cd keycloak/setup && ./generate-agent-token.sh --agent-id $AGENT_ID --save\"\n echo \"\"\n echo \"2. Test the authentication:\"\n echo \" ./test-keycloak-mcp.sh --agent-id $AGENT_ID\"\n echo \"\"\n echo -e \"${BLUE}Audit Trail Features:${NC}\"\n echo \"- All actions by this agent will be logged with agent ID: $AGENT_ID\"\n echo \"- Individual M2M client: $AGENT_CLIENT_ID\"\n echo \"- Service account username: $SERVICE_ACCOUNT\"\n echo \"- Group-based authorization: $TARGET_GROUP\"\n}\n\n# Run main function\nmain" }, { "path": "keycloak/setup/setup-federation-service-account.sh", "content": "#!/bin/bash\n# Setup Federation Service Account in Keycloak\n#\n# Creates a dedicated M2M client for peer-to-peer federation with a\n# 6-month access token lifetime. This client is separate from the main\n# mcp-gateway-m2m client so it does not affect other token lifetimes.\n#\n# The service account is assigned to the federation-service group, which\n# grants read-only access to servers and agents for peer sync.\n#\n# Prerequisites:\n# - Keycloak running and initialized (init-keycloak.sh completed)\n# - KEYCLOAK_ADMIN_PASSWORD environment variable set\n# - jq installed\n#\n# Usage:\n# export KEYCLOAK_ADMIN_PASSWORD=\"your-password\"\n# bash keycloak/setup/setup-federation-service-account.sh\n\nset -e\n\n# Configuration\nADMIN_URL=\"${KEYCLOAK_ADMIN_URL:-http://localhost:8080}\"\nREALM=\"mcp-gateway\"\nADMIN_USER=\"${KEYCLOAK_ADMIN:-admin}\"\nADMIN_PASS=\"${KEYCLOAK_ADMIN_PASSWORD}\"\n\nFEDERATION_CLIENT_ID=\"federation-peer-m2m\"\nFEDERATION_GROUP=\"federation-service\"\nSERVICE_ACCOUNT=\"service-account-${FEDERATION_CLIENT_ID}\"\n\n# Token lifetime: 6 months in seconds (180 days * 24 hours * 60 minutes * 60 seconds)\nTOKEN_LIFETIME_SECONDS=15552000\n\n# Colors for output\nGREEN='\\033[0;32m'\nRED='\\033[0;31m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m'\n\necho \"Setting up Federation Service Account for Keycloak\"\necho \"==============================================\"\necho \"Client ID: $FEDERATION_CLIENT_ID\"\necho \"Group: $FEDERATION_GROUP\"\necho \"Token Lifetime: 180 days (6 months)\"\necho \"\"\n\n\n# --- Private functions ---\n\n\n_get_admin_token() {\n echo \"Getting admin token...\"\n TOKEN=$(curl -s -X POST \"${ADMIN_URL}/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=${ADMIN_USER}\" \\\n -d \"password=${ADMIN_PASS}\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token // empty')\n\n if [ -z \"$TOKEN\" ]; then\n echo -e \"${RED}Failed to get admin token. Check KEYCLOAK_ADMIN_PASSWORD.${NC}\"\n exit 1\n fi\n echo -e \"${GREEN}Admin token obtained${NC}\"\n}\n\n\n_ensure_federation_group() {\n echo \"Checking if federation-service group exists...\"\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r \".[] | select(.name==\\\"${FEDERATION_GROUP}\\\") | .id\")\n\n if [ -n \"$GROUP_ID\" ] && [ \"$GROUP_ID\" != \"null\" ]; then\n echo -e \"${GREEN}Group '${FEDERATION_GROUP}' exists (ID: ${GROUP_ID})${NC}\"\n return 0\n fi\n\n echo \"Creating group '${FEDERATION_GROUP}'...\"\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${ADMIN_URL}/admin/realms/${REALM}/groups\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"name\\\": \\\"${FEDERATION_GROUP}\\\"}\")\n\n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}Group created${NC}\"\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/groups\" | \\\n jq -r \".[] | select(.name==\\\"${FEDERATION_GROUP}\\\") | .id\")\n else\n echo -e \"${RED}Failed to create group. HTTP: ${RESPONSE}${NC}\"\n exit 1\n fi\n}\n\n\n_create_federation_client() {\n echo \"Checking if federation client exists...\"\n EXISTING_CLIENT=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/clients?clientId=${FEDERATION_CLIENT_ID}\" | \\\n jq -r '.[0].id // empty')\n\n if [ -n \"$EXISTING_CLIENT\" ] && [ \"$EXISTING_CLIENT\" != \"null\" ]; then\n echo -e \"${GREEN}Client '${FEDERATION_CLIENT_ID}' already exists (ID: ${EXISTING_CLIENT})${NC}\"\n CLIENT_UUID=\"$EXISTING_CLIENT\"\n return 0\n fi\n\n echo \"Creating federation M2M client...\"\n CLIENT_JSON='{\n \"clientId\": \"'\"${FEDERATION_CLIENT_ID}\"'\",\n \"name\": \"Federation Peer M2M Client\",\n \"description\": \"Machine-to-machine client for peer registry federation sync with extended token lifetime\",\n \"enabled\": true,\n \"clientAuthenticatorType\": \"client-secret\",\n \"serviceAccountsEnabled\": true,\n \"standardFlowEnabled\": false,\n \"implicitFlowEnabled\": false,\n \"directAccessGrantsEnabled\": false,\n \"publicClient\": false,\n \"protocol\": \"openid-connect\",\n \"attributes\": {\n \"access.token.lifespan\": \"'\"${TOKEN_LIFETIME_SECONDS}\"'\"\n }\n }'\n\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${ADMIN_URL}/admin/realms/${REALM}/clients\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$CLIENT_JSON\")\n\n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}Federation client created${NC}\"\n else\n echo -e \"${RED}Failed to create client. HTTP: ${RESPONSE}${NC}\"\n exit 1\n fi\n\n # Get the client UUID\n CLIENT_UUID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/clients?clientId=${FEDERATION_CLIENT_ID}\" | \\\n jq -r '.[0].id')\n echo \"Client UUID: $CLIENT_UUID\"\n}\n\n\n_get_client_secret() {\n echo \"Retrieving client secret...\"\n CLIENT_SECRET=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/clients/${CLIENT_UUID}/client-secret\" | \\\n jq -r '.value // empty')\n\n if [ -z \"$CLIENT_SECRET\" ] || [ \"$CLIENT_SECRET\" = \"null\" ]; then\n echo \"Generating new client secret...\"\n CLIENT_SECRET=$(curl -s -X POST \\\n -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/clients/${CLIENT_UUID}/client-secret\" | \\\n jq -r '.value // empty')\n fi\n\n if [ -z \"$CLIENT_SECRET\" ] || [ \"$CLIENT_SECRET\" = \"null\" ]; then\n echo -e \"${RED}Failed to retrieve client secret${NC}\"\n exit 1\n fi\n echo -e \"${GREEN}Client secret retrieved${NC}\"\n}\n\n\n_setup_service_account() {\n echo \"Setting up service account...\"\n\n # Get the service account user for this client\n SA_USER=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/clients/${CLIENT_UUID}/service-account-user\")\n SA_USER_ID=$(echo \"$SA_USER\" | jq -r '.id // empty')\n\n if [ -z \"$SA_USER_ID\" ] || [ \"$SA_USER_ID\" = \"null\" ]; then\n echo -e \"${RED}Service account user not found for client${NC}\"\n exit 1\n fi\n echo \"Service account user ID: $SA_USER_ID\"\n\n # Assign to federation-service group\n echo \"Assigning service account to '${FEDERATION_GROUP}' group...\"\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"${ADMIN_URL}/admin/realms/${REALM}/users/${SA_USER_ID}/groups/${GROUP_ID}\" \\\n -H \"Authorization: Bearer $TOKEN\")\n\n if [ \"$RESPONSE\" = \"204\" ]; then\n echo -e \"${GREEN}Service account assigned to '${FEDERATION_GROUP}' group${NC}\"\n else\n echo -e \"${RED}Failed to assign to group. HTTP: ${RESPONSE}${NC}\"\n exit 1\n fi\n}\n\n\n_add_groups_mapper() {\n echo \"Adding groups mapper to federation client...\"\n\n # Check if mapper already exists\n EXISTING_MAPPER=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"${ADMIN_URL}/admin/realms/${REALM}/clients/${CLIENT_UUID}/protocol-mappers/models\" | \\\n jq -r '.[] | select(.name==\"groups\") | .id')\n\n if [ -n \"$EXISTING_MAPPER\" ] && [ \"$EXISTING_MAPPER\" != \"null\" ]; then\n echo -e \"${GREEN}Groups mapper already exists${NC}\"\n return 0\n fi\n\n GROUPS_MAPPER='{\n \"name\": \"groups\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-group-membership-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"full.path\": \"false\",\n \"id.token.claim\": \"true\",\n \"access.token.claim\": \"true\",\n \"claim.name\": \"groups\",\n \"userinfo.token.claim\": \"true\"\n }\n }'\n\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"${ADMIN_URL}/admin/realms/${REALM}/clients/${CLIENT_UUID}/protocol-mappers/models\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$GROUPS_MAPPER\")\n\n if [ \"$RESPONSE\" = \"201\" ] || [ \"$RESPONSE\" = \"409\" ]; then\n echo -e \"${GREEN}Groups mapper configured${NC}\"\n else\n echo -e \"${RED}Failed to add groups mapper. HTTP: ${RESPONSE}${NC}\"\n exit 1\n fi\n}\n\n\n_save_credentials() {\n # Save credentials to .oauth-tokens directory\n CREDS_DIR=\"$(dirname \"$(dirname \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\")\")/.oauth-tokens\"\n mkdir -p \"$CREDS_DIR\"\n\n CREDS_FILE=\"${CREDS_DIR}/${FEDERATION_CLIENT_ID}.json\"\n cat > \"$CREDS_FILE\" </dev/null | jq -r '.groups // empty')\n\n echo -e \"${GREEN}Token verification successful${NC}\"\n echo \" Token expires_in: ${EXPIRES_IN}s\"\n echo \" Token groups: ${TOKEN_GROUPS}\"\n}\n\n\n# --- Main function ---\n\n\nmain() {\n # Check required environment variables\n if [ -z \"$ADMIN_PASS\" ]; then\n echo -e \"${RED}Error: KEYCLOAK_ADMIN_PASSWORD environment variable is required${NC}\"\n echo \"Usage: export KEYCLOAK_ADMIN_PASSWORD=\\\"your-password\\\"\"\n exit 1\n fi\n\n _get_admin_token\n _ensure_federation_group\n _create_federation_client\n _get_client_secret\n _setup_service_account\n _add_groups_mapper\n _save_credentials\n _verify_token\n\n echo \"\"\n echo \"==============================================\"\n echo -e \"${GREEN}Federation service account setup complete${NC}\"\n echo \"\"\n echo \"Client ID: ${FEDERATION_CLIENT_ID}\"\n echo \"Client Secret: ${CLIENT_SECRET}\"\n echo \"Token Endpoint: ${ADMIN_URL}/realms/${REALM}/protocol/openid-connect/token\"\n echo \"Token Lifetime: 180 days (${TOKEN_LIFETIME_SECONDS}s)\"\n echo \"\"\n echo \"Add these to your registry .env file:\"\n echo \" FEDERATION_TOKEN_ENDPOINT=${ADMIN_URL}/realms/${REALM}/protocol/openid-connect/token\"\n echo \" FEDERATION_CLIENT_ID=${FEDERATION_CLIENT_ID}\"\n echo \" FEDERATION_CLIENT_SECRET=${CLIENT_SECRET}\"\n}\n\n\nmain\n" }, { "path": "keycloak/setup/setup-m2m-service-account.sh", "content": "#!/bin/bash\n# Complete M2M Service Account Setup Script\n# This script handles all aspects of setting up the M2M service account for Keycloak\n\nset -e\n\n# Configuration\nADMIN_URL=\"http://localhost:8080\"\nREALM=\"mcp-gateway\"\nADMIN_USER=\"admin\"\nADMIN_PASS=\"${KEYCLOAK_ADMIN_PASSWORD}\"\n\n# Check required environment variables\nif [ -z \"$ADMIN_PASS\" ]; then\n echo -e \"${RED}Error: KEYCLOAK_ADMIN_PASSWORD environment variable is required${NC}\"\n echo \"Please set it before running this script:\"\n echo \"export KEYCLOAK_ADMIN_PASSWORD=\\\"your-secure-password\\\"\"\n exit 1\nfi\nSERVICE_ACCOUNT=\"service-account-mcp-gateway-m2m\"\nM2M_CLIENT=\"mcp-gateway-m2m\"\nTARGET_GROUP=\"mcp-servers-unrestricted\"\n\n# Colors for output\nGREEN='\\033[0;32m'\nRED='\\033[0;31m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m' # No Color\n\necho -e \"${YELLOW}Setting up M2M Service Account for Keycloak${NC}\"\necho \"==============================================\"\necho \"Service Account: $SERVICE_ACCOUNT\"\necho \"Target Group: $TARGET_GROUP\"\necho \"M2M Client: $M2M_CLIENT\"\necho \"\"\n\n# Function to get admin token\nget_admin_token() {\n echo \"Getting admin token...\"\n TOKEN=$(curl -s -X POST \"$ADMIN_URL/realms/master/protocol/openid-connect/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"username=$ADMIN_USER\" \\\n -d \"password=$ADMIN_PASS\" \\\n -d \"grant_type=password\" \\\n -d \"client_id=admin-cli\" | jq -r '.access_token // empty')\n \n if [ -z \"$TOKEN\" ]; then\n echo -e \"${RED}Failed to get admin token${NC}\"\n exit 1\n fi\n echo -e \"${GREEN}✓ Admin token obtained${NC}\"\n}\n\n# Function to check if service account user exists\ncheck_service_account() {\n echo \"Checking if service account exists...\"\n USER_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$SERVICE_ACCOUNT\" | \\\n jq -r '.[0].id // empty')\n \n if [ -n \"$USER_ID\" ] && [ \"$USER_ID\" != \"null\" ]; then\n echo -e \"${GREEN}✓ Service account already exists with ID: $USER_ID${NC}\"\n return 0\n else\n echo \"Service account does not exist\"\n return 1\n fi\n}\n\n# Function to create service account user\ncreate_service_account() {\n echo \"Creating service account user...\"\n \n USER_JSON='{\n \"username\": \"'$SERVICE_ACCOUNT'\",\n \"enabled\": true,\n \"emailVerified\": true,\n \"serviceAccountClientId\": \"'$M2M_CLIENT'\"\n }'\n \n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/users\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$USER_JSON\")\n \n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ Service account user created successfully${NC}\"\n \n # Get the user ID\n USER_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users?username=$SERVICE_ACCOUNT\" | \\\n jq -r '.[0].id')\n \n echo \"User ID: $USER_ID\"\n else\n echo -e \"${RED}Failed to create user. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n# Function to get or create target group\nensure_target_group() {\n echo \"Checking if target group exists...\"\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$TARGET_GROUP\\\") | .id\")\n \n if [ -n \"$GROUP_ID\" ] && [ \"$GROUP_ID\" != \"null\" ]; then\n echo -e \"${GREEN}✓ Target group '$TARGET_GROUP' exists with ID: $GROUP_ID${NC}\"\n else\n echo \"Creating target group '$TARGET_GROUP'...\"\n \n GROUP_JSON='{\n \"name\": \"'$TARGET_GROUP'\",\n \"path\": \"/'$TARGET_GROUP'\"\n }'\n \n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/groups\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$GROUP_JSON\")\n \n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ Target group created successfully${NC}\"\n \n # Get the group ID\n GROUP_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/groups\" | \\\n jq -r \".[] | select(.name==\\\"$TARGET_GROUP\\\") | .id\")\n \n echo \"Group ID: $GROUP_ID\"\n else\n echo -e \"${RED}Failed to create group. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n fi\n}\n\n# Function to assign service account to group\nassign_to_group() {\n echo \"Assigning service account to target group...\"\n \n # Check if already assigned\n CURRENT_GROUPS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users/$USER_ID/groups\" | \\\n jq -r \".[].name\")\n \n if echo \"$CURRENT_GROUPS\" | grep -q \"$TARGET_GROUP\"; then\n echo -e \"${GREEN}✓ Service account already assigned to '$TARGET_GROUP' group${NC}\"\n return 0\n fi\n \n # Assign to group\n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X PUT \"$ADMIN_URL/admin/realms/$REALM/users/$USER_ID/groups/$GROUP_ID\" \\\n -H \"Authorization: Bearer $TOKEN\")\n \n if [ \"$RESPONSE\" = \"204\" ]; then\n echo -e \"${GREEN}✓ Service account assigned to '$TARGET_GROUP' group${NC}\"\n else\n echo -e \"${RED}Failed to assign to group. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n# Function to get M2M client ID\nget_m2m_client_id() {\n echo \"Finding M2M client...\"\n CLIENT_ID=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients?clientId=$M2M_CLIENT\" | \\\n jq -r '.[0].id // empty')\n \n if [ -z \"$CLIENT_ID\" ] || [ \"$CLIENT_ID\" = \"null\" ]; then\n echo -e \"${RED}M2M client '$M2M_CLIENT' not found${NC}\"\n exit 1\n fi\n \n echo -e \"${GREEN}✓ Found M2M client with ID: $CLIENT_ID${NC}\"\n}\n\n# Function to add groups mapper to M2M client\nadd_groups_mapper() {\n echo \"Checking for groups mapper on M2M client...\"\n \n # Check if groups mapper already exists\n EXISTING_MAPPER=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$CLIENT_ID/protocol-mappers/models\" | \\\n jq -r '.[] | select(.name==\"groups\") | .id')\n \n if [ -n \"$EXISTING_MAPPER\" ] && [ \"$EXISTING_MAPPER\" != \"null\" ]; then\n echo -e \"${GREEN}✓ Groups mapper already exists${NC}\"\n return 0\n fi\n \n echo \"Adding groups mapper to M2M client...\"\n \n GROUPS_MAPPER='{\n \"name\": \"groups\",\n \"protocol\": \"openid-connect\",\n \"protocolMapper\": \"oidc-group-membership-mapper\",\n \"consentRequired\": false,\n \"config\": {\n \"full.path\": \"false\",\n \"id.token.claim\": \"true\",\n \"access.token.claim\": \"true\",\n \"claim.name\": \"groups\",\n \"userinfo.token.claim\": \"true\"\n }\n }'\n \n RESPONSE=$(curl -s -o /dev/null -w \"%{http_code}\" \\\n -X POST \"$ADMIN_URL/admin/realms/$REALM/clients/$CLIENT_ID/protocol-mappers/models\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$GROUPS_MAPPER\")\n \n if [ \"$RESPONSE\" = \"201\" ]; then\n echo -e \"${GREEN}✓ Groups mapper added successfully${NC}\"\n elif [ \"$RESPONSE\" = \"409\" ]; then\n echo -e \"${GREEN}✓ Groups mapper already exists${NC}\"\n else\n echo -e \"${RED}Failed to add groups mapper. HTTP: $RESPONSE${NC}\"\n exit 1\n fi\n}\n\n# Function to verify setup\nverify_setup() {\n echo \"\"\n echo \"Verifying setup...\"\n \n # Check service account exists and is in the right group\n GROUPS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/users/$USER_ID/groups\" | \\\n jq -r '.[].name')\n \n echo \"Service account groups: $GROUPS\"\n \n if echo \"$GROUPS\" | grep -q \"$TARGET_GROUP\"; then\n echo -e \"${GREEN}✓ Service account is in '$TARGET_GROUP' group${NC}\"\n else\n echo -e \"${RED}✗ Service account is NOT in '$TARGET_GROUP' group${NC}\"\n exit 1\n fi\n \n # Check groups mapper exists\n MAPPER_EXISTS=$(curl -s -H \"Authorization: Bearer $TOKEN\" \\\n \"$ADMIN_URL/admin/realms/$REALM/clients/$CLIENT_ID/protocol-mappers/models\" | \\\n jq -r '.[] | select(.name==\"groups\") | .name')\n \n if [ \"$MAPPER_EXISTS\" = \"groups\" ]; then\n echo -e \"${GREEN}✓ Groups mapper is configured${NC}\"\n else\n echo -e \"${RED}✗ Groups mapper is NOT configured${NC}\"\n exit 1\n fi\n}\n\n# Main execution\nmain() {\n get_admin_token\n \n # Step 1: Ensure service account exists\n if ! check_service_account; then\n create_service_account\n fi\n \n # Step 2: Ensure target group exists\n ensure_target_group\n \n # Step 3: Assign service account to group\n assign_to_group\n \n # Step 4: Get M2M client ID\n get_m2m_client_id\n \n # Step 5: Add groups mapper\n add_groups_mapper\n \n # Step 6: Verify everything is set up correctly\n verify_setup\n \n echo \"\"\n echo -e \"${GREEN}SUCCESS! M2M service account setup complete.${NC}\"\n echo \"\"\n echo -e \"${YELLOW}Next steps:${NC}\"\n echo \"1. Generate a new M2M token to get the group membership:\"\n echo \" python credentials-provider/token_refresher.py\"\n echo \"\"\n echo \"2. Test the authentication:\"\n echo \" ./test-keycloak-mcp.sh\"\n echo \"\"\n echo -e \"${YELLOW}Summary:${NC}\"\n echo \"- Service Account: $SERVICE_ACCOUNT\"\n echo \"- Group: $TARGET_GROUP\"\n echo \"- Client: $M2M_CLIENT\"\n echo \"- Groups Mapper: ✓ Configured\"\n}\n\n# Run main function\nmain" }, { "path": "metrics-service/.env.example", "content": "# Metrics Service Configuration\n\n# Service Settings\nMETRICS_SERVICE_PORT=8890\nMETRICS_SERVICE_HOST=0.0.0.0\n\n# Database Settings (Container-based SQLite)\nDATABASE_URL=sqlite:///var/lib/sqlite/metrics.db\nSQLITE_DB_PATH=/var/lib/sqlite/metrics.db\nMETRICS_RETENTION_DAYS=90\nDB_CONNECTION_TIMEOUT=30\nDB_MAX_RETRIES=5\n\n# OpenTelemetry Settings\nOTEL_SERVICE_NAME=mcp-metrics-service\nOTEL_PROMETHEUS_ENABLED=true\nOTEL_PROMETHEUS_PORT=9465\nOTEL_OTLP_ENDPOINT=http://jaeger:14250\n\n# API Security\nMETRICS_RATE_LIMIT=1000\nAPI_KEY_HASH_ALGORITHM=sha256\n\n# Performance Settings\nBATCH_SIZE=100\nFLUSH_INTERVAL_SECONDS=30\nMAX_REQUEST_SIZE=10MB" }, { "path": "metrics-service/Dockerfile", "content": "FROM public.ecr.aws/docker/library/python:3.14-slim\n\nENV PYTHONUNBUFFERED=1 \\\n PIP_NO_CACHE_DIR=1\n\nWORKDIR /app\n\n# Install system dependencies\nRUN apt-get update && apt-get install -y \\\n curl \\\n && rm -rf /var/lib/apt/lists/*\n\n# Install dependencies\nCOPY pyproject.toml .\nRUN pip install uv && uv pip install --system -e .\n\n# Copy application\nCOPY app/ app/\nCOPY create_api_key.py ./\n\n# Create data directory\nRUN mkdir -p /var/lib/sqlite\n\n# Create non-root user for security (UID 1000 to match metrics-db)\nRUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser appuser\n\n# Set ownership of application files and data directory\nRUN chown -R appuser:appuser /app /var/lib/sqlite\n\n# Expose port\nEXPOSE 8890\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \\\n CMD curl -f http://localhost:8890/health || exit 1\n\n# Switch to non-root user\nUSER appuser\n\nCMD [\"python\", \"-m\", \"app.main\"]" }, { "path": "metrics-service/add_test_key.py", "content": "#!/usr/bin/env python3\n\"\"\"Add a test API key to the database\"\"\"\n\nimport asyncio\nimport aiosqlite\nimport sys\nfrom pathlib import Path\n\n\nasync def add_test_key():\n db_path = \"/var/lib/sqlite/metrics.db\"\n key_hash = (\n \"1f8e8c97805e4ad56c611029fbba4c04dab40bf05d18c46655696357705cc136\" # hash of \"test_key_123\"\n )\n\n async with aiosqlite.connect(db_path) as db:\n await db.execute(\n \"\"\"\n INSERT INTO api_keys (key_hash, service_name, created_at, is_active)\n VALUES (?, ?, datetime('now'), 1)\n \"\"\",\n (key_hash, \"test-service\"),\n )\n await db.commit()\n print(f\"Added test API key for service: test-service\")\n print(f\"API Key: test_key_123\")\n print(f\"Key Hash: {key_hash}\")\n\n\nif __name__ == \"__main__\":\n asyncio.run(add_test_key())\n" }, { "path": "metrics-service/app/__init__.py", "content": "" }, { "path": "metrics-service/app/api/__init__.py", "content": "" }, { "path": "metrics-service/app/api/auth.py", "content": "from fastapi import HTTPException, Request\nfrom fastapi.security import HTTPBearer, HTTPAuthorizationCredentials\nimport logging\nfrom ..storage.database import MetricsStorage\nfrom ..utils.helpers import hash_api_key\nfrom ..core.rate_limiter import rate_limiter\n\nlogger = logging.getLogger(__name__)\nsecurity = HTTPBearer()\n\n\nasync def verify_api_key(request: Request) -> str:\n \"\"\"Verify API key from X-API-Key header and check rate limits.\"\"\"\n api_key = request.headers.get(\"X-API-Key\")\n\n if not api_key:\n raise HTTPException(status_code=401, detail=\"API key required in X-API-Key header\")\n\n # Hash the provided API key\n key_hash = hash_api_key(api_key)\n\n # Verify against database\n storage = MetricsStorage()\n key_info = await storage.get_api_key(key_hash)\n\n if not key_info:\n raise HTTPException(status_code=401, detail=\"Invalid API key\")\n\n if not key_info[\"is_active\"]:\n raise HTTPException(status_code=401, detail=\"API key is inactive\")\n\n # Check rate limit\n rate_limit = key_info.get(\"rate_limit\", 1000)\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, rate_limit)\n\n if not allowed:\n raise HTTPException(\n status_code=429,\n detail=f\"Rate limit exceeded. Limit: {rate_limit} requests/minute\",\n headers={\n \"X-RateLimit-Limit\": str(rate_limit),\n \"X-RateLimit-Remaining\": \"0\",\n \"Retry-After\": \"60\",\n },\n )\n\n # Update last used timestamp\n await storage.update_api_key_usage(key_hash)\n\n # Add rate limit headers\n request.state.rate_limit_remaining = remaining\n request.state.rate_limit_limit = rate_limit\n\n logger.debug(\n f\"API key verified for service: {key_info['service_name']}, remaining: {remaining}\"\n )\n return key_info[\"service_name\"]\n\n\nasync def get_rate_limit_status(api_key: str) -> dict:\n \"\"\"Get current rate limit status for an API key.\"\"\"\n key_hash = hash_api_key(api_key)\n\n # Get key info from database\n storage = MetricsStorage()\n key_info = await storage.get_api_key(key_hash)\n\n if not key_info:\n raise HTTPException(status_code=401, detail=\"Invalid API key\")\n\n rate_limit = key_info.get(\"rate_limit\", 1000)\n status = await rate_limiter.get_bucket_status(key_hash, rate_limit)\n\n return {\n \"service\": key_info[\"service_name\"],\n \"rate_limit\": status[\"rate_limit\"],\n \"available_tokens\": status[\"available_tokens\"],\n \"reset_time_seconds\": status[\"reset_time_seconds\"],\n }\n" }, { "path": "metrics-service/app/api/routes.py", "content": "from fastapi import APIRouter, HTTPException, Depends, Request, Response\nfrom typing import List, Dict, Any, Optional\nimport uuid\nimport logging\nfrom ..core.models import MetricRequest, MetricResponse, ErrorResponse\nfrom ..core.processor import MetricsProcessor\nfrom ..core.retention import retention_manager\nfrom ..api.auth import verify_api_key, get_rate_limit_status\nfrom ..utils.helpers import generate_request_id, generate_api_key, hash_api_key\nfrom ..storage.database import MetricsStorage\n\nrouter = APIRouter()\nlogger = logging.getLogger(__name__)\nprocessor = MetricsProcessor()\n\n\n@router.post(\"/metrics\", response_model=MetricResponse)\nasync def collect_metrics(\n metric_request: MetricRequest,\n request: Request,\n response: Response,\n api_key: str = Depends(verify_api_key),\n):\n \"\"\"Collect metrics from MCP components.\"\"\"\n request_id = generate_request_id()\n\n try:\n # Add rate limit headers\n if hasattr(request.state, \"rate_limit_remaining\") and hasattr(\n request.state, \"rate_limit_limit\"\n ):\n response.headers[\"X-RateLimit-Limit\"] = str(request.state.rate_limit_limit)\n response.headers[\"X-RateLimit-Remaining\"] = str(request.state.rate_limit_remaining)\n\n # Process metrics\n result = await processor.process_metrics(metric_request, request_id, api_key)\n\n logger.info(\n f\"Processed {result.accepted} metrics from {metric_request.service} (request: {request_id})\"\n )\n\n return MetricResponse(\n status=\"success\",\n accepted=result.accepted,\n rejected=result.rejected,\n errors=result.errors,\n request_id=request_id,\n )\n\n except Exception as e:\n logger.exception(\"Error processing metrics\")\n raise HTTPException(status_code=500, detail=\"Internal server error\")\n\n\n@router.post(\"/flush\")\nasync def flush_metrics(\n request: Request, response: Response, api_key: str = Depends(verify_api_key)\n):\n \"\"\"Force flush buffered metrics to storage.\"\"\"\n try:\n # Add rate limit headers\n if hasattr(request.state, \"rate_limit_remaining\") and hasattr(\n request.state, \"rate_limit_limit\"\n ):\n response.headers[\"X-RateLimit-Limit\"] = str(request.state.rate_limit_limit)\n response.headers[\"X-RateLimit-Remaining\"] = str(request.state.rate_limit_remaining)\n\n await processor.force_flush()\n return {\"status\": \"success\", \"message\": \"Metrics flushed to storage\"}\n except Exception as e:\n logger.exception(\"Error flushing metrics\")\n raise HTTPException(status_code=500, detail=\"Failed to flush metrics\")\n\n\n@router.get(\"/rate-limit\")\nasync def get_rate_limit(request: Request):\n \"\"\"Get current rate limit status for the API key.\"\"\"\n api_key = request.headers.get(\"X-API-Key\")\n\n if not api_key:\n raise HTTPException(status_code=401, detail=\"API key required in X-API-Key header\")\n\n try:\n status = await get_rate_limit_status(api_key)\n return status\n except Exception as e:\n logger.exception(\"Error getting rate limit status\")\n raise HTTPException(status_code=500, detail=\"Failed to get rate limit status\")\n\n\n@router.get(\"/admin/retention/preview\")\nasync def get_cleanup_preview(\n table_name: str | None = None, api_key: str = Depends(verify_api_key)\n):\n \"\"\"Preview what would be cleaned up by retention policies.\n\n Args:\n table_name: Optional table name to preview. Must be a valid table\n with a configured retention policy.\n api_key: API key for authentication.\n\n Raises:\n HTTPException: 400 if table_name is not in the allowlist.\n HTTPException: 404 if table_name has no retention policy.\n HTTPException: 500 for other errors.\n \"\"\"\n try:\n preview = await retention_manager.get_cleanup_preview(table_name)\n return preview\n except ValueError as e:\n # Security: Invalid table name - not in allowlist\n logger.warning(f\"Invalid table name in cleanup preview request: {e}\")\n raise HTTPException(status_code=400, detail=str(e))\n except KeyError as e:\n logger.warning(f\"Table not found in cleanup preview request: {e}\")\n raise HTTPException(status_code=404, detail=str(e))\n except Exception as e:\n logger.exception(\"Error getting cleanup preview\")\n raise HTTPException(status_code=500, detail=\"Failed to get cleanup preview\")\n\n\n@router.post(\"/admin/retention/cleanup\")\nasync def run_cleanup(\n table_name: str | None = None, dry_run: bool = True, api_key: str = Depends(verify_api_key)\n):\n \"\"\"Run data cleanup according to retention policies.\n\n Args:\n table_name: Optional table name to clean. Must be in the allowlist.\n dry_run: If True, only preview what would be deleted.\n api_key: API key for authentication.\n\n Raises:\n HTTPException: 400 if table_name is not in the allowlist.\n HTTPException: 500 for other errors.\n \"\"\"\n try:\n if table_name:\n result = await retention_manager.cleanup_table(table_name, dry_run)\n else:\n result = await retention_manager.cleanup_all_tables(dry_run)\n return result\n except ValueError as e:\n # Security: Invalid table name - not in allowlist\n logger.warning(f\"Invalid table name in cleanup request: {e}\")\n raise HTTPException(status_code=400, detail=str(e))\n except Exception as e:\n logger.exception(\"Error running cleanup\")\n raise HTTPException(status_code=500, detail=\"Failed to run cleanup\")\n\n\n@router.get(\"/admin/retention/policies\")\nasync def get_retention_policies(api_key: str = Depends(verify_api_key)):\n \"\"\"Get current retention policies.\"\"\"\n try:\n policies = {}\n for name, policy in retention_manager.policies.items():\n policies[name] = {\n \"table_name\": policy.table_name,\n \"retention_days\": policy.retention_days,\n \"is_active\": policy.is_active,\n \"timestamp_column\": policy.timestamp_column,\n }\n return policies\n except Exception as e:\n logger.exception(\"Error getting retention policies\")\n raise HTTPException(status_code=500, detail=\"Failed to get retention policies\")\n\n\n@router.put(\"/admin/retention/policies/{table_name}\")\nasync def update_retention_policy(\n table_name: str,\n retention_days: int,\n is_active: bool = True,\n api_key: str = Depends(verify_api_key),\n):\n \"\"\"Update retention policy for a table.\n\n Args:\n table_name: The table name. Must be in the allowlist of valid tables.\n retention_days: Number of days to retain data.\n is_active: Whether the policy is active.\n api_key: API key for authentication.\n\n Raises:\n HTTPException: 400 if table_name is not in the allowlist.\n HTTPException: 500 for other errors.\n \"\"\"\n try:\n await retention_manager.update_policy(table_name, retention_days, is_active)\n return {\n \"status\": \"success\",\n \"message\": f\"Updated retention policy for {table_name}\",\n \"table_name\": table_name,\n \"retention_days\": retention_days,\n \"is_active\": is_active,\n }\n except ValueError as e:\n # Security: Invalid table name - not in allowlist\n logger.warning(f\"Invalid table name in update policy request: {e}\")\n raise HTTPException(status_code=400, detail=str(e))\n except Exception as e:\n logger.exception(\"Error updating retention policy\")\n raise HTTPException(status_code=500, detail=\"Failed to update retention policy\")\n\n\n@router.get(\"/admin/database/stats\")\nasync def get_database_stats(api_key: str = Depends(verify_api_key)):\n \"\"\"Get database table statistics.\"\"\"\n try:\n stats = await retention_manager.get_table_stats()\n return stats\n except Exception as e:\n logger.exception(\"Error getting database stats\")\n raise HTTPException(status_code=500, detail=\"Failed to get database stats\")\n\n\n@router.get(\"/admin/database/size\")\nasync def get_database_size(api_key: str = Depends(verify_api_key)):\n \"\"\"Get database size information.\"\"\"\n try:\n size_info = await retention_manager.get_database_size()\n return size_info\n except Exception as e:\n logger.exception(\"Error getting database size\")\n raise HTTPException(status_code=500, detail=\"Failed to get database size\")\n" }, { "path": "metrics-service/app/config.py", "content": "import os\nfrom typing import Optional\n\n\nclass Settings:\n # Database settings\n SQLITE_DB_PATH: str = os.getenv(\"SQLITE_DB_PATH\", \"/var/lib/sqlite/metrics.db\")\n DATABASE_URL: str = os.getenv(\"DATABASE_URL\", f\"sqlite:///{SQLITE_DB_PATH}\")\n METRICS_RETENTION_DAYS: int = int(os.getenv(\"METRICS_RETENTION_DAYS\", \"90\"))\n DB_CONNECTION_TIMEOUT: int = int(os.getenv(\"DB_CONNECTION_TIMEOUT\", \"30\"))\n DB_MAX_RETRIES: int = int(os.getenv(\"DB_MAX_RETRIES\", \"5\"))\n\n # Service settings\n METRICS_SERVICE_PORT: int = int(os.getenv(\"METRICS_SERVICE_PORT\", \"8890\"))\n # Service binds to 0.0.0.0 for container/K8s deployment where network isolation\n # is provided by container runtime and ingress controllers.\n METRICS_SERVICE_HOST: str = os.getenv(\"METRICS_SERVICE_HOST\", \"0.0.0.0\") # nosec B104 - intentional for containerized deployment\n\n # OpenTelemetry settings\n OTEL_SERVICE_NAME: str = os.getenv(\"OTEL_SERVICE_NAME\", \"mcp-metrics-service\")\n OTEL_PROMETHEUS_ENABLED: bool = os.getenv(\"OTEL_PROMETHEUS_ENABLED\", \"true\").lower() == \"true\"\n OTEL_PROMETHEUS_PORT: int = int(os.getenv(\"OTEL_PROMETHEUS_PORT\", \"9465\"))\n OTEL_OTLP_ENDPOINT: Optional[str] = os.getenv(\"OTEL_OTLP_ENDPOINT\")\n OTEL_OTLP_EXPORT_INTERVAL_MS: int = int(os.getenv(\"OTEL_OTLP_EXPORT_INTERVAL_MS\", \"30000\"))\n\n # API Security\n METRICS_RATE_LIMIT: int = int(os.getenv(\"METRICS_RATE_LIMIT\", \"1000\"))\n API_KEY_HASH_ALGORITHM: str = os.getenv(\"API_KEY_HASH_ALGORITHM\", \"sha256\")\n\n # Histogram bucket boundaries for duration metrics (seconds)\n HISTOGRAM_BUCKET_BOUNDARIES: list = [\n float(x)\n for x in os.getenv(\n \"HISTOGRAM_BUCKET_BOUNDARIES\",\n \"0.005,0.01,0.025,0.05,0.1,0.25,0.5,1.0,2.5,5.0,10.0,30.0,60.0,120.0,300.0\",\n ).split(\",\")\n ]\n\n # Performance\n BATCH_SIZE: int = int(os.getenv(\"BATCH_SIZE\", \"100\"))\n FLUSH_INTERVAL_SECONDS: int = int(os.getenv(\"FLUSH_INTERVAL_SECONDS\", \"30\"))\n MAX_REQUEST_SIZE: str = os.getenv(\"MAX_REQUEST_SIZE\", \"10MB\")\n\n\nsettings = Settings()\n" }, { "path": "metrics-service/app/core/__init__.py", "content": "" }, { "path": "metrics-service/app/core/models.py", "content": "from pydantic import BaseModel, Field\nfrom datetime import datetime\nfrom typing import Dict, Any, Optional, List\nfrom enum import StrEnum\n\n\nclass MetricType(StrEnum):\n AUTH_REQUEST = \"auth_request\"\n TOOL_DISCOVERY = \"tool_discovery\"\n TOOL_EXECUTION = \"tool_execution\"\n REGISTRY_OPERATION = \"registry_operation\"\n HEALTH_CHECK = \"health_check\"\n PROTOCOL_LATENCY = \"protocol_latency\"\n CUSTOM = \"custom\"\n\n\nclass Metric(BaseModel):\n type: MetricType\n timestamp: datetime | None = Field(default_factory=datetime.utcnow)\n value: float\n duration_ms: float | None = None\n dimensions: Dict[str, Any] = Field(default_factory=dict)\n metadata: Dict[str, Any] = Field(default_factory=dict)\n\n\nclass MetricRequest(BaseModel):\n service: str = Field(..., max_length=50)\n version: str | None = Field(None, max_length=20)\n instance_id: str | None = Field(None, max_length=50)\n metrics: List[Metric]\n\n\nclass MetricResponse(BaseModel):\n status: str\n accepted: int\n rejected: int\n errors: List[str] = []\n request_id: str\n\n\nclass ErrorResponse(BaseModel):\n status: str\n error: str\n message: str\n request_id: str\n" }, { "path": "metrics-service/app/core/processor.py", "content": "import asyncio\nimport logging\nfrom datetime import datetime\nfrom typing import List, Dict, Any\nfrom ..core.models import MetricRequest, Metric, MetricType\nfrom ..storage.database import MetricsStorage\nfrom ..core.validator import validator\n\nlogger = logging.getLogger(__name__)\n\n\ndef _normalize_label_value(value: object) -> str:\n \"\"\"Normalize a label value for Prometheus compatibility.\n\n Python's str(True) produces \"True\" (capital T), but Prometheus convention\n is lowercase \"true\"/\"false\". Lua's tostring() already produces lowercase,\n so without normalization the same metric gets split into two timeseries.\n \"\"\"\n if isinstance(value, bool):\n return \"true\" if value else \"false\"\n return str(value)\n\n\nclass ProcessingResult:\n def __init__(self):\n self.accepted = 0\n self.rejected = 0\n self.errors = []\n\n\nclass MetricsProcessor:\n \"\"\"Core metrics processing engine.\"\"\"\n\n def __init__(self):\n self.storage = MetricsStorage()\n self._buffer = []\n self._buffer_lock = asyncio.Lock()\n\n # Try to initialize OTel instruments, but don't fail if it doesn't work\n self.otel = None\n try:\n from ..otel.instruments import MetricsInstruments\n\n self.otel = MetricsInstruments()\n logger.info(\"OpenTelemetry instruments initialized\")\n except Exception as e:\n logger.warning(f\"OpenTelemetry instruments not available: {e}\")\n\n async def process_metrics(\n self, request: MetricRequest, request_id: str, api_key: str\n ) -> ProcessingResult:\n \"\"\"Process incoming metrics request.\"\"\"\n result = ProcessingResult()\n\n # Validate the entire request first\n validation_result = validator.validate_metric_request(request)\n if not validation_result.is_valid:\n result.rejected = len(request.metrics)\n result.errors.extend(validation_result.get_error_messages())\n return result\n\n # Log any validation warnings\n for warning in validation_result.warnings:\n logger.warning(f\"Metrics validation warning: {warning}\")\n\n for metric in request.metrics:\n try:\n # Additional runtime validation\n if not self._validate_metric(metric):\n result.rejected += 1\n result.errors.append(f\"Invalid metric: {metric.type}\")\n continue\n\n # Emit to OpenTelemetry if available\n if self.otel:\n try:\n await self._emit_to_otel(metric, request.service)\n except Exception as e:\n logger.warning(f\"Failed to emit to OTel: {e}\")\n\n # Store in SQLite (buffered)\n await self._buffer_for_storage(metric, request, request_id)\n\n result.accepted += 1\n\n except Exception as e:\n result.rejected += 1\n result.errors.append(f\"Error processing metric: {str(e)}\")\n logger.error(f\"Error processing metric: {e}\")\n\n return result\n\n def _validate_metric(self, metric: Metric) -> bool:\n \"\"\"Validate metric data.\"\"\"\n if metric.value is None:\n return False\n if metric.type not in MetricType:\n return False\n return True\n\n async def _emit_to_otel(self, metric: Metric, service: str):\n \"\"\"Emit metric to OpenTelemetry instruments.\"\"\"\n if not self.otel:\n return\n\n labels = {\n \"service\": service,\n \"metric_type\": metric.type.value,\n **{k: _normalize_label_value(v) for k, v in metric.dimensions.items()},\n }\n\n # Route to appropriate OTel instrument\n if metric.type == MetricType.AUTH_REQUEST:\n self.otel.auth_counter.add(metric.value, labels)\n if metric.duration_ms:\n self.otel.auth_histogram.record(metric.duration_ms / 1000, labels)\n\n elif metric.type == MetricType.TOOL_DISCOVERY:\n self.otel.discovery_counter.add(metric.value, labels)\n if metric.duration_ms:\n self.otel.discovery_histogram.record(metric.duration_ms / 1000, labels)\n\n elif metric.type == MetricType.TOOL_EXECUTION:\n self.otel.tool_counter.add(metric.value, labels)\n if metric.duration_ms:\n self.otel.tool_histogram.record(metric.duration_ms / 1000, labels)\n\n elif metric.type == MetricType.PROTOCOL_LATENCY:\n # For protocol latency, record the value as latency seconds\n self.otel.latency_histogram.record(metric.value, labels)\n\n elif metric.type == MetricType.HEALTH_CHECK:\n self.otel.health_counter.add(metric.value, labels)\n if metric.duration_ms:\n self.otel.health_histogram.record(metric.duration_ms / 1000, labels)\n\n async def _buffer_for_storage(self, metric: Metric, request: MetricRequest, request_id: str):\n \"\"\"Buffer metric for batch SQLite storage.\"\"\"\n async with self._buffer_lock:\n self._buffer.append({\"metric\": metric, \"request\": request, \"request_id\": request_id})\n\n # Flush buffer if it's full\n if len(self._buffer) >= 100:\n await self._flush_buffer()\n\n async def _flush_buffer(self):\n \"\"\"Flush buffered metrics to SQLite.\"\"\"\n if not self._buffer:\n return\n\n buffer_copy = self._buffer.copy()\n self._buffer.clear()\n\n try:\n await self.storage.store_metrics_batch(buffer_copy)\n logger.debug(f\"Flushed {len(buffer_copy)} metrics to storage\")\n except Exception as e:\n logger.error(f\"Failed to flush metrics buffer: {e}\")\n # Re-add to buffer for retry\n self._buffer.extend(buffer_copy)\n\n async def force_flush(self):\n \"\"\"Force flush all buffered metrics.\"\"\"\n async with self._buffer_lock:\n await self._flush_buffer()\n" }, { "path": "metrics-service/app/core/rate_limiter.py", "content": "\"\"\"Rate limiting implementation for API keys.\"\"\"\n\nimport asyncio\nimport time\nimport logging\nfrom typing import Dict, Tuple\nfrom datetime import datetime, timedelta\nfrom ..storage.database import MetricsStorage\n\nlogger = logging.getLogger(__name__)\n\n\nclass RateLimiter:\n \"\"\"Token bucket rate limiter for API keys.\"\"\"\n\n def __init__(self):\n # In-memory token buckets: {key_hash: (tokens, last_refill, rate_limit)}\n self._buckets: Dict[str, Tuple[int, float, int]] = {}\n self._lock = asyncio.Lock()\n\n async def check_rate_limit(self, key_hash: str, rate_limit: int) -> Tuple[bool, int]:\n \"\"\"\n Check if request is allowed under rate limit.\n\n Args:\n key_hash: The hashed API key\n rate_limit: Requests per minute limit\n\n Returns:\n Tuple of (is_allowed, remaining_tokens)\n \"\"\"\n async with self._lock:\n now = time.time()\n\n # Get or create bucket\n if key_hash not in self._buckets:\n # New bucket starts full, consume one token for this request\n tokens = rate_limit - 1\n self._buckets[key_hash] = (tokens, now, rate_limit)\n return True, tokens\n else:\n tokens, last_refill, limit = self._buckets[key_hash]\n\n # Update rate limit if it changed\n if limit != rate_limit:\n # Scale existing tokens proportionally\n tokens = int(tokens * (rate_limit / limit))\n limit = rate_limit\n\n # Refill tokens based on elapsed time\n time_elapsed = now - last_refill\n minutes_elapsed = time_elapsed / 60.0\n\n # Add tokens for elapsed time (rate_limit tokens per minute)\n tokens_to_add = int(minutes_elapsed * rate_limit)\n tokens = min(tokens + tokens_to_add, rate_limit)\n\n # Update last refill time if we added tokens\n if tokens_to_add > 0:\n last_refill = now\n\n # Check if request is allowed\n if tokens > 0:\n tokens -= 1\n self._buckets[key_hash] = (tokens, last_refill, rate_limit)\n logger.debug(f\"Rate limit check passed. Remaining: {tokens}\")\n return True, tokens\n else:\n self._buckets[key_hash] = (tokens, last_refill, rate_limit)\n logger.warning(f\"Rate limit exceeded for key: {key_hash[:8]}...\")\n return False, 0\n\n async def get_bucket_status(self, key_hash: str, rate_limit: int) -> Dict[str, int]:\n \"\"\"Get current bucket status without consuming a token.\"\"\"\n async with self._lock:\n now = time.time()\n\n if key_hash not in self._buckets:\n return {\n \"available_tokens\": rate_limit,\n \"rate_limit\": rate_limit,\n \"reset_time_seconds\": 0,\n }\n\n tokens, last_refill, limit = self._buckets[key_hash]\n\n # Calculate tokens after refill\n time_elapsed = now - last_refill\n minutes_elapsed = time_elapsed / 60.0\n tokens_to_add = int(minutes_elapsed * rate_limit)\n current_tokens = min(tokens + tokens_to_add, rate_limit)\n\n # Calculate time until bucket is full\n if current_tokens < rate_limit:\n tokens_needed = rate_limit - current_tokens\n reset_time_seconds = int((tokens_needed / rate_limit) * 60)\n else:\n reset_time_seconds = 0\n\n return {\n \"available_tokens\": current_tokens,\n \"rate_limit\": rate_limit,\n \"reset_time_seconds\": reset_time_seconds,\n }\n\n async def cleanup_old_buckets(self, max_age_hours: int = 24):\n \"\"\"Remove buckets that haven't been used recently.\"\"\"\n async with self._lock:\n now = time.time()\n cutoff = now - (max_age_hours * 3600)\n\n old_keys = []\n for key_hash, (_, last_refill, _) in self._buckets.items():\n if last_refill < cutoff:\n old_keys.append(key_hash)\n\n for key in old_keys:\n del self._buckets[key]\n\n if old_keys:\n logger.info(f\"Cleaned up {len(old_keys)} old rate limit buckets\")\n\n\n# Global rate limiter instance\nrate_limiter = RateLimiter()\n" }, { "path": "metrics-service/app/core/retention.py", "content": "\"\"\"Data retention and cleanup policies for metrics service.\"\"\"\n\nimport asyncio\nimport logging\nimport re\nfrom datetime import datetime, timedelta\nfrom typing import List, Dict, Any, Optional, Set\nfrom ..storage.database import MetricsStorage\nfrom ..config import settings\nimport aiosqlite\n\nlogger = logging.getLogger(__name__)\n\n\n# Security: Allowlist of valid table names for retention policies\n# Only these tables can have retention policies applied\nALLOWED_TABLE_NAMES: Set[str] = {\n \"metrics\",\n \"auth_metrics\",\n \"discovery_metrics\",\n \"tool_metrics\",\n \"metrics_hourly\",\n \"metrics_daily\",\n \"api_key_usage_log\",\n}\n\n# Test table names - only used in test environments\n# These are added to the allowlist during testing\n_TEST_TABLE_NAMES: Set[str] = {\n \"test_metrics\",\n \"test_table\",\n \"custom_table\",\n}\n\n# Security: Allowlist of valid timestamp column names\nALLOWED_TIMESTAMP_COLUMNS: Set[str] = {\n \"created_at\",\n \"timestamp\",\n \"updated_at\",\n}\n\n# Security: Regex pattern for valid SQL identifiers (alphanumeric and underscore only)\n_VALID_IDENTIFIER_PATTERN = re.compile(r\"^[a-zA-Z_][a-zA-Z0-9_]*$\")\n\n# Flag to enable test tables - should only be set in test environments\n_test_tables_enabled: bool = False\n\n\ndef _enable_test_tables() -> None:\n \"\"\"Enable test table names in the allowlist.\n\n This should only be called from test code to allow test-specific\n table names to be used in retention policies.\n \"\"\"\n global _test_tables_enabled\n _test_tables_enabled = True\n\n\ndef _disable_test_tables() -> None:\n \"\"\"Disable test table names in the allowlist.\n\n This restores the production behavior after tests complete.\n \"\"\"\n global _test_tables_enabled\n _test_tables_enabled = False\n\n\ndef _get_allowed_table_names() -> Set[str]:\n \"\"\"Get the current set of allowed table names.\n\n Returns:\n Set of allowed table names, including test tables if enabled.\n \"\"\"\n if _test_tables_enabled:\n return ALLOWED_TABLE_NAMES | _TEST_TABLE_NAMES\n return ALLOWED_TABLE_NAMES\n\n\ndef _validate_table_name(table_name: str) -> str:\n \"\"\"Validate table name against allowlist to prevent SQL injection.\n\n Args:\n table_name: The table name to validate\n\n Returns:\n The validated table name\n\n Raises:\n ValueError: If table name is not in the allowlist\n \"\"\"\n allowed = _get_allowed_table_names()\n if table_name not in allowed:\n raise ValueError(\n f\"Invalid table name: '{table_name}'. Allowed tables: {sorted(ALLOWED_TABLE_NAMES)}\"\n )\n return table_name\n\n\ndef _validate_timestamp_column(column_name: str) -> str:\n \"\"\"Validate timestamp column name against allowlist to prevent SQL injection.\n\n Args:\n column_name: The column name to validate\n\n Returns:\n The validated column name\n\n Raises:\n ValueError: If column name is not in the allowlist\n \"\"\"\n if column_name not in ALLOWED_TIMESTAMP_COLUMNS:\n raise ValueError(\n f\"Invalid timestamp column: '{column_name}'. \"\n f\"Allowed columns: {sorted(ALLOWED_TIMESTAMP_COLUMNS)}\"\n )\n return column_name\n\n\ndef _validate_identifier(identifier: str) -> str:\n \"\"\"Validate that an identifier matches safe SQL identifier pattern.\n\n This is a secondary validation for identifiers that come from\n sqlite_master (system tables), which are not in our allowlists\n but need to be validated for safe use.\n\n Args:\n identifier: The identifier to validate\n\n Returns:\n The validated identifier\n\n Raises:\n ValueError: If identifier contains invalid characters\n \"\"\"\n if not identifier or not _VALID_IDENTIFIER_PATTERN.match(identifier):\n raise ValueError(\n f\"Invalid SQL identifier: '{identifier}'. \"\n \"Identifiers must start with a letter or underscore and \"\n \"contain only alphanumeric characters and underscores.\"\n )\n return identifier\n\n\nclass RetentionPolicy:\n \"\"\"Represents a data retention policy for a table.\"\"\"\n\n def __init__(\n self,\n table_name: str,\n retention_days: int,\n is_active: bool = True,\n cleanup_query: str | None = None,\n timestamp_column: str = \"created_at\",\n ):\n # Security: Validate table_name and timestamp_column against allowlists\n self.table_name = _validate_table_name(table_name)\n self.timestamp_column = _validate_timestamp_column(timestamp_column)\n self.retention_days = retention_days\n self.is_active = is_active\n self.cleanup_query = cleanup_query\n\n def get_cleanup_query(self) -> tuple[str, tuple]:\n \"\"\"Get the cleanup query and parameters for this policy.\n\n Security note: table_name and timestamp_column are validated\n against allowlists during __init__, preventing SQL injection.\n The cutoff date is passed as a parameterized value.\n\n Returns:\n Tuple of (query_string, parameters)\n \"\"\"\n if self.cleanup_query:\n return self.cleanup_query, ()\n\n cutoff = (datetime.now() - timedelta(days=self.retention_days)).isoformat()\n # nosec B608 - table_name and timestamp_column validated against allowlists in __init__\n query = f\"DELETE FROM {self.table_name} WHERE {self.timestamp_column} < ?\" # nosec B608\n return query, (cutoff,)\n\n def get_count_query(self) -> tuple[str, tuple]:\n \"\"\"Get query and parameters to count records that would be deleted.\n\n Security note: table_name and timestamp_column are validated\n against allowlists during __init__, preventing SQL injection.\n The cutoff date is passed as a parameterized value.\n\n Returns:\n Tuple of (query_string, parameters)\n \"\"\"\n cutoff = (datetime.now() - timedelta(days=self.retention_days)).isoformat()\n # nosec B608 - table_name and timestamp_column validated against allowlists in __init__\n query = f\"SELECT COUNT(*) FROM {self.table_name} WHERE {self.timestamp_column} < ?\" # nosec B608\n return query, (cutoff,)\n\n\nclass RetentionManager:\n \"\"\"Manages data retention policies and cleanup operations.\"\"\"\n\n def __init__(self):\n self.storage = MetricsStorage()\n self.policies: Dict[str, RetentionPolicy] = {}\n self._load_default_policies()\n\n def _load_default_policies(self):\n \"\"\"Load default retention policies.\"\"\"\n # Raw metrics tables\n self.policies[\"metrics\"] = RetentionPolicy(\n table_name=\"metrics\", retention_days=90, timestamp_column=\"created_at\"\n )\n\n self.policies[\"auth_metrics\"] = RetentionPolicy(\n table_name=\"auth_metrics\", retention_days=90, timestamp_column=\"created_at\"\n )\n\n self.policies[\"discovery_metrics\"] = RetentionPolicy(\n table_name=\"discovery_metrics\", retention_days=90, timestamp_column=\"created_at\"\n )\n\n self.policies[\"tool_metrics\"] = RetentionPolicy(\n table_name=\"tool_metrics\", retention_days=90, timestamp_column=\"created_at\"\n )\n\n # Aggregated metrics - longer retention\n self.policies[\"metrics_hourly\"] = RetentionPolicy(\n table_name=\"metrics_hourly\",\n retention_days=365, # 1 year\n timestamp_column=\"created_at\",\n )\n\n self.policies[\"metrics_daily\"] = RetentionPolicy(\n table_name=\"metrics_daily\",\n retention_days=1095, # 3 years\n timestamp_column=\"created_at\",\n )\n\n # API usage logs\n self.policies[\"api_key_usage_log\"] = RetentionPolicy(\n table_name=\"api_key_usage_log\", retention_days=90, timestamp_column=\"created_at\"\n )\n\n # Note: api_keys table uses 'created_at', not 'timestamp'\n # Schema_migrations table may not have created_at in all environments\n\n async def load_policies_from_database(self):\n \"\"\"Load retention policies from database.\"\"\"\n try:\n async with aiosqlite.connect(self.storage.db_path) as db:\n cursor = await db.execute(\"\"\"\n SELECT table_name, retention_days, is_active\n FROM retention_policies\n WHERE is_active = 1\n \"\"\")\n\n db_policies = await cursor.fetchall()\n\n for row in db_policies:\n table_name, retention_days, is_active = row\n\n # Update existing policy or create new one\n if table_name in self.policies:\n self.policies[table_name].retention_days = retention_days\n self.policies[table_name].is_active = bool(is_active)\n else:\n self.policies[table_name] = RetentionPolicy(\n table_name=table_name,\n retention_days=retention_days,\n is_active=bool(is_active),\n )\n\n logger.info(f\"Loaded {len(db_policies)} retention policies from database\")\n\n except Exception as e:\n logger.error(f\"Failed to load retention policies from database: {e}\")\n logger.info(\"Using default retention policies\")\n\n async def save_policies_to_database(self):\n \"\"\"Save current policies to database.\"\"\"\n try:\n async with aiosqlite.connect(self.storage.db_path) as db:\n await db.execute(\"BEGIN TRANSACTION\")\n\n for policy in self.policies.values():\n await db.execute(\n \"\"\"\n INSERT OR REPLACE INTO retention_policies \n (table_name, retention_days, is_active, updated_at)\n VALUES (?, ?, ?, datetime('now'))\n \"\"\",\n (policy.table_name, policy.retention_days, 1 if policy.is_active else 0),\n )\n\n await db.commit()\n logger.info(f\"Saved {len(self.policies)} retention policies to database\")\n\n except Exception as e:\n logger.error(f\"Failed to save retention policies: {e}\")\n raise\n\n async def get_cleanup_preview(self, table_name: str | None = None) -> Dict[str, Dict[str, Any]]:\n \"\"\"Get preview of what would be cleaned up without actually deleting.\n\n Args:\n table_name: Optional table name to preview. Must be in the allowlist.\n\n Returns:\n Dictionary with preview information for each table.\n\n Raises:\n ValueError: If table_name is not in the allowlist.\n KeyError: If table_name has no retention policy configured.\n \"\"\"\n preview = {}\n\n # Security: Validate table_name against allowlist if provided\n if table_name is not None:\n _validate_table_name(table_name)\n if table_name not in self.policies:\n raise KeyError(f\"No retention policy found for table: {table_name}\")\n policies_to_check = [self.policies[table_name]]\n else:\n policies_to_check = list(self.policies.values())\n\n for policy in policies_to_check:\n if not policy.is_active:\n continue\n\n try:\n async with aiosqlite.connect(self.storage.db_path) as db:\n # Count records to be deleted\n count_query, count_params = policy.get_count_query()\n cursor = await db.execute(count_query, count_params)\n count_result = await cursor.fetchone()\n records_to_delete = count_result[0] if count_result else 0\n\n # Get oldest and newest timestamps that would be deleted\n cutoff = (datetime.now() - timedelta(days=policy.retention_days)).isoformat()\n # nosec B608 - table_name and timestamp_column validated in RetentionPolicy.__init__\n cursor = await db.execute(\n f\"SELECT MIN({policy.timestamp_column}) as oldest,\" # nosec B608\n f\" MAX({policy.timestamp_column}) as newest\"\n f\" FROM {policy.table_name}\"\n f\" WHERE {policy.timestamp_column} < ?\",\n (cutoff,),\n )\n\n time_range = await cursor.fetchone()\n oldest_record = time_range[0] if time_range else None\n newest_record = time_range[1] if time_range else None\n\n # Get total table size\n # nosec B608 - table_name validated in RetentionPolicy.__init__\n cursor = await db.execute(\n f\"SELECT COUNT(*) FROM {policy.table_name}\", # nosec B608\n )\n total_records = (await cursor.fetchone())[0]\n\n preview[policy.table_name] = {\n \"retention_days\": policy.retention_days,\n \"records_to_delete\": records_to_delete,\n \"total_records\": total_records,\n \"oldest_record_to_delete\": oldest_record,\n \"newest_record_to_delete\": newest_record,\n \"cutoff_date\": datetime.now() - timedelta(days=policy.retention_days),\n \"percentage_to_delete\": (records_to_delete / total_records * 100)\n if total_records > 0\n else 0,\n }\n\n except Exception as e:\n logger.error(f\"Failed to preview cleanup for {policy.table_name}: {e}\")\n preview[policy.table_name] = {\"error\": str(e)}\n\n return preview\n\n async def cleanup_table(self, table_name: str, dry_run: bool = False) -> Dict[str, Any]:\n \"\"\"Clean up a specific table according to its retention policy.\"\"\"\n if table_name not in self.policies:\n raise ValueError(f\"No retention policy found for table: {table_name}\")\n\n policy = self.policies[table_name]\n\n if not policy.is_active:\n return {\"table\": table_name, \"status\": \"skipped\", \"reason\": \"policy_inactive\"}\n\n try:\n async with aiosqlite.connect(self.storage.db_path) as db:\n # Get preview first\n count_query, count_params = policy.get_count_query()\n cursor = await db.execute(count_query, count_params)\n count_result = await cursor.fetchone()\n records_to_delete = count_result[0] if count_result else 0\n\n if records_to_delete == 0:\n return {\n \"table\": table_name,\n \"status\": \"completed\",\n \"records_deleted\": 0,\n \"reason\": \"no_records_to_delete\",\n }\n\n if dry_run:\n return {\n \"table\": table_name,\n \"status\": \"dry_run\",\n \"records_would_delete\": records_to_delete,\n }\n\n # Execute cleanup\n start_time = datetime.now()\n\n await db.execute(\"BEGIN IMMEDIATE\")\n try:\n cleanup_query, cleanup_params = policy.get_cleanup_query()\n cursor = await db.execute(cleanup_query, cleanup_params)\n records_deleted = cursor.rowcount\n await db.commit()\n\n end_time = datetime.now()\n duration = (end_time - start_time).total_seconds()\n\n logger.info(\n f\"Cleaned up {records_deleted} records from {table_name} in {duration:.2f}s\"\n )\n\n return {\n \"table\": table_name,\n \"status\": \"completed\",\n \"records_deleted\": records_deleted,\n \"duration_seconds\": duration,\n \"retention_days\": policy.retention_days,\n }\n\n except Exception as e:\n await db.rollback()\n raise e\n\n except Exception as e:\n logger.error(f\"Failed to cleanup table {table_name}: {e}\")\n return {\"table\": table_name, \"status\": \"error\", \"error\": str(e)}\n\n async def cleanup_all_tables(self, dry_run: bool = False) -> Dict[str, Any]:\n \"\"\"Run cleanup on all tables with active retention policies.\"\"\"\n results = {}\n total_deleted = 0\n start_time = datetime.now()\n\n logger.info(f\"Starting {'dry run' if dry_run else 'cleanup'} for all tables\")\n\n for policy in self.policies.values():\n if not policy.is_active:\n continue\n\n result = await self.cleanup_table(policy.table_name, dry_run)\n results[policy.table_name] = result\n\n if result[\"status\"] == \"completed\" and \"records_deleted\" in result:\n total_deleted += result[\"records_deleted\"]\n\n # Run VACUUM after cleanup to reclaim space\n if not dry_run and total_deleted > 0:\n try:\n async with aiosqlite.connect(self.storage.db_path) as db:\n logger.info(\"Running VACUUM to reclaim disk space...\")\n await db.execute(\"VACUUM\")\n logger.info(\"VACUUM completed successfully\")\n except Exception as e:\n logger.error(f\"Failed to run VACUUM: {e}\")\n\n end_time = datetime.now()\n duration = (end_time - start_time).total_seconds()\n\n summary = {\n \"operation\": \"dry_run\" if dry_run else \"cleanup\",\n \"total_records_processed\": total_deleted,\n \"tables_processed\": len(\n [r for r in results.values() if r[\"status\"] in [\"completed\", \"dry_run\"]]\n ),\n \"duration_seconds\": duration,\n \"started_at\": start_time.isoformat(),\n \"completed_at\": end_time.isoformat(),\n \"table_results\": results,\n }\n\n logger.info(\n f\"Cleanup {'dry run' if dry_run else 'operation'} completed: \"\n f\"{total_deleted} records processed in {duration:.2f}s\"\n )\n\n return summary\n\n async def update_policy(self, table_name: str, retention_days: int, is_active: bool = True):\n \"\"\"Update retention policy for a table.\n\n Args:\n table_name: The table name. Must be in the allowlist.\n retention_days: Number of days to retain data.\n is_active: Whether the policy is active.\n\n Raises:\n ValueError: If table_name is not in the allowlist.\n \"\"\"\n # Security: Validate table_name against allowlist\n _validate_table_name(table_name)\n\n if table_name in self.policies:\n self.policies[table_name].retention_days = retention_days\n self.policies[table_name].is_active = is_active\n else:\n # RetentionPolicy constructor also validates, but we validate early\n # to provide better error messages\n self.policies[table_name] = RetentionPolicy(\n table_name=table_name, retention_days=retention_days, is_active=is_active\n )\n\n # Save to database\n await self.save_policies_to_database()\n logger.info(\n f\"Updated retention policy for {table_name}: {retention_days} days, active: {is_active}\"\n )\n\n async def get_table_stats(self) -> Dict[str, Dict[str, Any]]:\n \"\"\"Get storage statistics for all tables.\n\n Returns:\n Dictionary mapping table names to their statistics.\n\n Note:\n Table names come from sqlite_master (system catalog) and are\n validated before use in SQL queries as a defense-in-depth measure.\n \"\"\"\n stats = {}\n\n try:\n async with aiosqlite.connect(self.storage.db_path) as db:\n # Get all table names from sqlite_master\n cursor = await db.execute(\"\"\"\n SELECT name FROM sqlite_master\n WHERE type='table' AND name NOT LIKE 'sqlite_%'\n \"\"\")\n tables = await cursor.fetchall()\n\n for (raw_table_name,) in tables:\n try:\n # Security: Validate identifier even though it comes from\n # sqlite_master (defense in depth)\n table_name = _validate_identifier(raw_table_name)\n\n # Get record count\n # nosec B608 - table_name validated by _validate_identifier above\n cursor = await db.execute(\n f\"SELECT COUNT(*) FROM {table_name}\", # nosec B608\n )\n count = (await cursor.fetchone())[0]\n\n # Get approximate size and date range\n # table_name validated by _validate_identifier above\n cursor = await db.execute(\n f\"SELECT\" # nosec B608\n f\" COUNT(*) as records,\"\n f\" COALESCE(\"\n f\" (SELECT MIN(created_at) FROM {table_name}\"\n f\" WHERE created_at IS NOT NULL),\"\n f\" (SELECT MIN(timestamp) FROM {table_name}\"\n f\" WHERE timestamp IS NOT NULL)\"\n f\" ) as oldest_record,\"\n f\" COALESCE(\"\n f\" (SELECT MAX(created_at) FROM {table_name}\"\n f\" WHERE created_at IS NOT NULL),\"\n f\" (SELECT MAX(timestamp) FROM {table_name}\"\n f\" WHERE timestamp IS NOT NULL)\"\n f\" ) as newest_record\",\n )\n\n result = await cursor.fetchone()\n\n stats[table_name] = {\n \"record_count\": count,\n \"oldest_record\": result[1] if result else None,\n \"newest_record\": result[2] if result else None,\n \"has_retention_policy\": table_name in self.policies,\n \"retention_days\": (\n self.policies[table_name].retention_days\n if table_name in self.policies\n else None\n ),\n \"policy_active\": (\n self.policies[table_name].is_active\n if table_name in self.policies\n else None\n ),\n }\n\n except ValueError as e:\n # Invalid identifier - skip this table\n logger.warning(f\"Skipping table with invalid name: {raw_table_name}: {e}\")\n except Exception as e:\n logger.warning(f\"Failed to get stats for table {raw_table_name}: {e}\")\n stats[raw_table_name] = {\"error\": str(e)}\n\n except Exception as e:\n logger.error(f\"Failed to get table statistics: {e}\")\n raise\n\n return stats\n\n async def get_database_size(self) -> Dict[str, Any]:\n \"\"\"Get database file size information.\"\"\"\n try:\n import os\n\n db_path = self.storage.db_path\n\n size_info = {}\n\n if os.path.exists(db_path):\n # Main database file\n size_info[\"main_db_bytes\"] = os.path.getsize(db_path)\n size_info[\"main_db_mb\"] = round(size_info[\"main_db_bytes\"] / 1024 / 1024, 2)\n\n # WAL file\n wal_path = db_path + \"-wal\"\n if os.path.exists(wal_path):\n size_info[\"wal_bytes\"] = os.path.getsize(wal_path)\n size_info[\"wal_mb\"] = round(size_info[\"wal_bytes\"] / 1024 / 1024, 2)\n else:\n size_info[\"wal_bytes\"] = 0\n size_info[\"wal_mb\"] = 0\n\n # SHM file\n shm_path = db_path + \"-shm\"\n if os.path.exists(shm_path):\n size_info[\"shm_bytes\"] = os.path.getsize(shm_path)\n size_info[\"shm_mb\"] = round(size_info[\"shm_bytes\"] / 1024 / 1024, 2)\n else:\n size_info[\"shm_bytes\"] = 0\n size_info[\"shm_mb\"] = 0\n\n # Total size\n total_bytes = (\n size_info[\"main_db_bytes\"] + size_info[\"wal_bytes\"] + size_info[\"shm_bytes\"]\n )\n size_info[\"total_bytes\"] = total_bytes\n size_info[\"total_mb\"] = round(total_bytes / 1024 / 1024, 2)\n size_info[\"total_gb\"] = round(total_bytes / 1024 / 1024 / 1024, 3)\n\n else:\n size_info = {\"error\": \"Database file not found\"}\n\n # Get SQLite page info\n async with aiosqlite.connect(self.storage.db_path) as db:\n cursor = await db.execute(\"PRAGMA page_count\")\n page_count = (await cursor.fetchone())[0]\n\n cursor = await db.execute(\"PRAGMA page_size\")\n page_size = (await cursor.fetchone())[0]\n\n cursor = await db.execute(\"PRAGMA freelist_count\")\n free_pages = (await cursor.fetchone())[0]\n\n size_info[\"page_count\"] = page_count\n size_info[\"page_size\"] = page_size\n size_info[\"free_pages\"] = free_pages\n size_info[\"used_pages\"] = page_count - free_pages\n size_info[\"database_efficiency\"] = (\n round((size_info[\"used_pages\"] / page_count * 100), 2) if page_count > 0 else 0\n )\n\n return size_info\n\n except Exception as e:\n logger.error(f\"Failed to get database size: {e}\")\n return {\"error\": str(e)}\n\n\n# Global retention manager instance\nretention_manager = RetentionManager()\n" }, { "path": "metrics-service/app/core/validator.py", "content": "\"\"\"Data validation module for metrics service.\"\"\"\n\nimport re\nimport logging\nfrom typing import List, Dict, Any, Optional, Union\nfrom datetime import datetime, timezone\nfrom ..core.models import MetricType, Metric, MetricRequest\n\nlogger = logging.getLogger(__name__)\n\n\nclass ValidationError(Exception):\n \"\"\"Custom validation error with detailed messages.\"\"\"\n\n def __init__(self, field: str, message: str, value: Any = None):\n self.field = field\n self.message = message\n self.value = value\n super().__init__(f\"{field}: {message}\")\n\n\nclass ValidationResult:\n \"\"\"Result of validation with errors and warnings.\"\"\"\n\n def __init__(self):\n self.errors: List[ValidationError] = []\n self.warnings: List[str] = []\n self.is_valid: bool = True\n\n def add_error(self, field: str, message: str, value: Any = None):\n \"\"\"Add a validation error.\"\"\"\n self.errors.append(ValidationError(field, message, value))\n self.is_valid = False\n\n def add_warning(self, message: str):\n \"\"\"Add a validation warning.\"\"\"\n self.warnings.append(message)\n\n def get_error_messages(self) -> List[str]:\n \"\"\"Get list of error messages.\"\"\"\n return [str(error) for error in self.errors]\n\n\nclass MetricsValidator:\n \"\"\"Comprehensive validator for metrics data.\"\"\"\n\n # Service name validation\n SERVICE_NAME_PATTERN = re.compile(r\"^[a-zA-Z0-9_-]+$\")\n SERVICE_NAME_MAX_LENGTH = 100\n\n # Instance ID validation\n INSTANCE_ID_PATTERN = re.compile(r\"^[a-zA-Z0-9_.-]+$\")\n INSTANCE_ID_MAX_LENGTH = 100\n\n # Version validation\n VERSION_PATTERN = re.compile(r\"^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?$\")\n\n # Dimension key/value validation\n DIMENSION_KEY_PATTERN = re.compile(r\"^[a-zA-Z_][a-zA-Z0-9_]*$\")\n DIMENSION_KEY_MAX_LENGTH = 50\n DIMENSION_VALUE_MAX_LENGTH = 200\n MAX_DIMENSIONS = 20\n\n # Metadata validation\n MAX_METADATA_FIELDS = 30\n METADATA_KEY_MAX_LENGTH = 50\n METADATA_VALUE_MAX_LENGTH = 1000\n\n # Value validation\n MIN_METRIC_VALUE = -1e12\n MAX_METRIC_VALUE = 1e12\n MIN_DURATION_MS = 0.0\n MAX_DURATION_MS = 86400000.0 # 24 hours in milliseconds\n\n def validate_metric_request(self, request: MetricRequest) -> ValidationResult:\n \"\"\"Validate a complete metric request.\"\"\"\n result = ValidationResult()\n\n # Validate service name\n self._validate_service_name(request.service, result)\n\n # Validate version (optional)\n if request.version:\n self._validate_version(request.version, result)\n\n # Validate instance ID (optional)\n if request.instance_id:\n self._validate_instance_id(request.instance_id, result)\n\n # Validate metrics array\n if not request.metrics:\n result.add_error(\"metrics\", \"At least one metric is required\")\n elif len(request.metrics) > 100:\n result.add_error(\n \"metrics\", f\"Too many metrics in request: {len(request.metrics)}, max 100\"\n )\n else:\n for i, metric in enumerate(request.metrics):\n self._validate_metric(metric, f\"metrics[{i}]\", result)\n\n return result\n\n def _validate_service_name(self, service: str, result: ValidationResult):\n \"\"\"Validate service name.\"\"\"\n if not service:\n result.add_error(\"service\", \"Service name is required\")\n return\n\n if not isinstance(service, str):\n result.add_error(\n \"service\", f\"Service name must be string, got {type(service).__name__}\"\n )\n return\n\n if len(service) > self.SERVICE_NAME_MAX_LENGTH:\n result.add_error(\n \"service\",\n f\"Service name too long: {len(service)} chars, max {self.SERVICE_NAME_MAX_LENGTH}\",\n )\n return\n\n if not self.SERVICE_NAME_PATTERN.match(service):\n result.add_error(\n \"service\",\n \"Service name must contain only alphanumeric characters, underscores, and hyphens\",\n )\n\n def _validate_version(self, version: str, result: ValidationResult):\n \"\"\"Validate version string.\"\"\"\n if not isinstance(version, str):\n result.add_error(\"version\", f\"Version must be string, got {type(version).__name__}\")\n return\n\n if not self.VERSION_PATTERN.match(version):\n result.add_warning(f\"Version '{version}' does not follow semantic versioning (x.y.z)\")\n\n def _validate_instance_id(self, instance_id: str, result: ValidationResult):\n \"\"\"Validate instance ID.\"\"\"\n if not isinstance(instance_id, str):\n result.add_error(\n \"instance_id\", f\"Instance ID must be string, got {type(instance_id).__name__}\"\n )\n return\n\n if len(instance_id) > self.INSTANCE_ID_MAX_LENGTH:\n result.add_error(\n \"instance_id\",\n f\"Instance ID too long: {len(instance_id)} chars, max {self.INSTANCE_ID_MAX_LENGTH}\",\n )\n return\n\n if not self.INSTANCE_ID_PATTERN.match(instance_id):\n result.add_error(\n \"instance_id\",\n \"Instance ID must contain only alphanumeric characters, underscores, dots, and hyphens\",\n )\n\n def _validate_metric(self, metric: Metric, field_prefix: str, result: ValidationResult):\n \"\"\"Validate a single metric.\"\"\"\n # Validate metric type\n if not isinstance(metric.type, MetricType):\n result.add_error(f\"{field_prefix}.type\", f\"Invalid metric type: {metric.type}\")\n\n # Validate timestamp\n self._validate_timestamp(metric.timestamp, f\"{field_prefix}.timestamp\", result)\n\n # Validate value\n self._validate_metric_value(metric.value, f\"{field_prefix}.value\", result)\n\n # Validate duration (optional)\n if metric.duration_ms is not None:\n self._validate_duration(metric.duration_ms, f\"{field_prefix}.duration_ms\", result)\n\n # Validate dimensions\n if metric.dimensions:\n self._validate_dimensions(metric.dimensions, f\"{field_prefix}.dimensions\", result)\n\n # Validate metadata\n if metric.metadata:\n self._validate_metadata(metric.metadata, f\"{field_prefix}.metadata\", result)\n\n def _validate_timestamp(self, timestamp: datetime, field: str, result: ValidationResult):\n \"\"\"Validate timestamp.\"\"\"\n if not isinstance(timestamp, datetime):\n result.add_error(\n field, f\"Timestamp must be datetime object, got {type(timestamp).__name__}\"\n )\n return\n\n # Check if timestamp is in the future (allow 5 minutes skew)\n now = datetime.now(timezone.utc)\n max_future = now.timestamp() + 300 # 5 minutes\n\n if timestamp.timestamp() > max_future:\n result.add_error(field, f\"Timestamp is too far in the future: {timestamp.isoformat()}\")\n\n # Check if timestamp is too old (more than 7 days)\n min_past = now.timestamp() - (7 * 24 * 3600) # 7 days\n\n if timestamp.timestamp() < min_past:\n result.add_warning(f\"Timestamp is very old: {timestamp.isoformat()}\")\n\n def _validate_metric_value(self, value: float, field: str, result: ValidationResult):\n \"\"\"Validate metric value.\"\"\"\n if value is None:\n result.add_error(field, \"Metric value is required\")\n return\n\n if not isinstance(value, (int, float)):\n result.add_error(field, f\"Metric value must be numeric, got {type(value).__name__}\")\n return\n\n if not (self.MIN_METRIC_VALUE <= value <= self.MAX_METRIC_VALUE):\n result.add_error(\n field,\n f\"Metric value out of range: {value}, must be between {self.MIN_METRIC_VALUE} and {self.MAX_METRIC_VALUE}\",\n )\n\n # Check for NaN or infinity\n if isinstance(value, float):\n import math\n\n if math.isnan(value):\n result.add_error(field, \"Metric value cannot be NaN\")\n elif math.isinf(value):\n result.add_error(field, \"Metric value cannot be infinite\")\n\n def _validate_duration(self, duration: float, field: str, result: ValidationResult):\n \"\"\"Validate duration in milliseconds.\"\"\"\n if not isinstance(duration, (int, float)):\n result.add_error(field, f\"Duration must be numeric, got {type(duration).__name__}\")\n return\n\n if duration < self.MIN_DURATION_MS:\n result.add_error(field, f\"Duration cannot be negative: {duration}\")\n\n if duration > self.MAX_DURATION_MS:\n result.add_error(\n field, f\"Duration too large: {duration}ms, max {self.MAX_DURATION_MS}ms\"\n )\n\n def _validate_dimensions(\n self, dimensions: Dict[str, Any], field: str, result: ValidationResult\n ):\n \"\"\"Validate dimensions dictionary.\"\"\"\n if not isinstance(dimensions, dict):\n result.add_error(\n field, f\"Dimensions must be dictionary, got {type(dimensions).__name__}\"\n )\n return\n\n if len(dimensions) > self.MAX_DIMENSIONS:\n result.add_error(\n field, f\"Too many dimensions: {len(dimensions)}, max {self.MAX_DIMENSIONS}\"\n )\n\n for key, value in dimensions.items():\n self._validate_dimension_key(key, f\"{field}.{key}\", result)\n self._validate_dimension_value(value, f\"{field}.{key}\", result)\n\n def _validate_dimension_key(self, key: str, field: str, result: ValidationResult):\n \"\"\"Validate dimension key.\"\"\"\n if not isinstance(key, str):\n result.add_error(field, f\"Dimension key must be string, got {type(key).__name__}\")\n return\n\n if len(key) > self.DIMENSION_KEY_MAX_LENGTH:\n result.add_error(\n field,\n f\"Dimension key too long: {len(key)} chars, max {self.DIMENSION_KEY_MAX_LENGTH}\",\n )\n return\n\n if not self.DIMENSION_KEY_PATTERN.match(key):\n result.add_error(\n field,\n \"Dimension key must start with letter/underscore and contain only alphanumeric/underscore characters\",\n )\n\n def _validate_dimension_value(self, value: Any, field: str, result: ValidationResult):\n \"\"\"Validate dimension value.\"\"\"\n if value is None:\n return # None values are allowed\n\n # Convert to string for length validation\n str_value = str(value)\n\n if len(str_value) > self.DIMENSION_VALUE_MAX_LENGTH:\n result.add_error(\n field,\n f\"Dimension value too long: {len(str_value)} chars, max {self.DIMENSION_VALUE_MAX_LENGTH}\",\n )\n\n # Warn about non-string values that will be converted\n if not isinstance(value, (str, int, float, bool)):\n result.add_warning(\n f\"Dimension value at {field} will be converted to string: {type(value).__name__}\"\n )\n\n def _validate_metadata(self, metadata: Dict[str, Any], field: str, result: ValidationResult):\n \"\"\"Validate metadata dictionary.\"\"\"\n if not isinstance(metadata, dict):\n result.add_error(field, f\"Metadata must be dictionary, got {type(metadata).__name__}\")\n return\n\n if len(metadata) > self.MAX_METADATA_FIELDS:\n result.add_error(\n field, f\"Too many metadata fields: {len(metadata)}, max {self.MAX_METADATA_FIELDS}\"\n )\n\n for key, value in metadata.items():\n self._validate_metadata_key(key, f\"{field}.{key}\", result)\n self._validate_metadata_value(value, f\"{field}.{key}\", result)\n\n def _validate_metadata_key(self, key: str, field: str, result: ValidationResult):\n \"\"\"Validate metadata key.\"\"\"\n if not isinstance(key, str):\n result.add_error(field, f\"Metadata key must be string, got {type(key).__name__}\")\n return\n\n if len(key) > self.METADATA_KEY_MAX_LENGTH:\n result.add_error(\n field,\n f\"Metadata key too long: {len(key)} chars, max {self.METADATA_KEY_MAX_LENGTH}\",\n )\n\n def _validate_metadata_value(self, value: Any, field: str, result: ValidationResult):\n \"\"\"Validate metadata value.\"\"\"\n if value is None:\n return # None values are allowed\n\n # Convert to string for length validation if not already serializable\n if isinstance(value, (dict, list)):\n try:\n import json\n\n str_value = json.dumps(value)\n except (TypeError, ValueError):\n result.add_error(field, f\"Metadata value at {field} is not JSON serializable\")\n return\n else:\n str_value = str(value)\n\n if len(str_value) > self.METADATA_VALUE_MAX_LENGTH:\n result.add_error(\n field,\n f\"Metadata value too long: {len(str_value)} chars, max {self.METADATA_VALUE_MAX_LENGTH}\",\n )\n\n\n# Global validator instance\nvalidator = MetricsValidator()\n" }, { "path": "metrics-service/app/main.py", "content": "from fastapi import FastAPI, HTTPException, Depends\nfrom contextlib import asynccontextmanager\nimport logging\nimport asyncio\nfrom .config import settings\nfrom .api.routes import router as api_router\nfrom .storage.database import init_database, wait_for_database, MetricsStorage\nfrom .core.rate_limiter import rate_limiter\nfrom .core.retention import retention_manager\nfrom .utils.helpers import hash_api_key\nimport os\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n \"\"\"Application startup and shutdown lifecycle.\"\"\"\n logger.info(\"Starting Metrics Collection Service...\")\n\n # Wait for database container to be ready\n logger.info(\"Waiting for database container...\")\n await wait_for_database()\n logger.info(\"Database container is ready\")\n\n # Initialize database\n await init_database()\n logger.info(\"Database initialized\")\n\n # Setup pre-shared API keys from environment variables\n await setup_preshared_api_keys()\n logger.info(\"Pre-shared API keys configured\")\n\n # Load retention policies from database\n try:\n await retention_manager.load_policies_from_database()\n logger.info(\"Retention policies loaded\")\n except Exception as e:\n logger.warning(f\"Failed to load retention policies: {e}, using defaults\")\n\n # Setup OpenTelemetry (optional, continue if it fails)\n try:\n from .otel.exporters import setup_otel\n\n setup_otel()\n logger.info(\"OpenTelemetry configured\")\n except Exception as e:\n logger.warning(f\"OpenTelemetry setup skipped: {e}\")\n\n # Start background tasks\n cleanup_task = asyncio.create_task(rate_limit_cleanup_task())\n retention_task = asyncio.create_task(retention_cleanup_task())\n flush_task = asyncio.create_task(metrics_flush_task())\n logger.info(\"Background tasks started\")\n\n yield\n\n # Cancel background tasks\n cleanup_task.cancel()\n retention_task.cancel()\n flush_task.cancel()\n try:\n await cleanup_task\n await retention_task\n await flush_task\n except asyncio.CancelledError:\n pass\n\n logger.info(\"Shutting down Metrics Collection Service\")\n\n\nasync def rate_limit_cleanup_task():\n \"\"\"Background task to clean up old rate limit buckets.\"\"\"\n while True:\n try:\n await asyncio.sleep(3600) # Run every hour\n await rate_limiter.cleanup_old_buckets(max_age_hours=24)\n except asyncio.CancelledError:\n break\n except Exception as e:\n logger.error(f\"Error in rate limit cleanup task: {e}\")\n await asyncio.sleep(60) # Wait a minute before retry\n\n\nasync def retention_cleanup_task():\n \"\"\"Background task to run data retention cleanup.\"\"\"\n while True:\n try:\n await asyncio.sleep(86400) # Run once per day (24 hours)\n logger.info(\"Starting scheduled data retention cleanup...\")\n result = await retention_manager.cleanup_all_tables(dry_run=False)\n\n total_deleted = result.get(\"total_records_processed\", 0)\n duration = result.get(\"duration_seconds\", 0)\n\n if total_deleted > 0:\n logger.info(\n f\"Retention cleanup completed: {total_deleted} records deleted in {duration:.2f}s\"\n )\n else:\n logger.info(\"Retention cleanup completed: no records to delete\")\n\n except asyncio.CancelledError:\n break\n except Exception as e:\n logger.error(f\"Error in retention cleanup task: {e}\")\n await asyncio.sleep(3600) # Wait an hour before retry\n\n\nasync def metrics_flush_task():\n \"\"\"Background task to flush metrics buffer every 5 seconds.\"\"\"\n # Import the shared processor instance from routes\n from .api.routes import processor\n\n while True:\n try:\n await asyncio.sleep(5) # Flush every 5 seconds\n await processor.force_flush()\n logger.debug(\"Metrics buffer flushed to database\")\n except asyncio.CancelledError:\n break\n except Exception as e:\n logger.error(f\"Error in metrics flush task: {e}\")\n await asyncio.sleep(5) # Wait 5 seconds before retry\n\n\nasync def setup_preshared_api_keys():\n \"\"\"Setup pre-shared API keys from environment variables dynamically.\"\"\"\n storage = MetricsStorage()\n\n # Dynamically discover all METRICS_API_KEY_* environment variables\n api_key_count = 0\n for key, value in os.environ.items():\n if key.startswith(\"METRICS_API_KEY_\") and value:\n # Extract service name from environment variable\n # METRICS_API_KEY_AUTH -> auth\n # METRICS_API_KEY_REGISTRY -> registry\n # METRICS_API_KEY_CURRENTTIME_SERVER -> currenttime-server\n service_suffix = key.replace(\"METRICS_API_KEY_\", \"\")\n service_name = service_suffix.lower().replace(\"_\", \"-\")\n\n try:\n key_hash = hash_api_key(value)\n success = await storage.create_api_key(key_hash, service_name, rate_limit=1000)\n if success:\n logger.info(f\"Configured API key for service: {service_name}\")\n api_key_count += 1\n else:\n logger.debug(f\"API key for {service_name} already exists\")\n api_key_count += 1\n except Exception as e:\n logger.error(f\"Failed to setup API key for {service_name}: {e}\")\n\n if api_key_count == 0:\n logger.warning(\"No METRICS_API_KEY_* environment variables found\")\n else:\n logger.info(f\"Configured {api_key_count} API keys from environment variables\")\n\n\napp = FastAPI(\n title=\"MCP Metrics Collection Service\",\n description=\"Centralized metrics collection for MCP Gateway Registry components\",\n version=\"1.0.0\",\n lifespan=lifespan,\n)\n\n# Include API routes\napp.include_router(api_router)\n\n\n@app.get(\"/health\")\nasync def health_check():\n \"\"\"Health check endpoint.\"\"\"\n return {\"status\": \"healthy\", \"service\": \"metrics-collection\"}\n\n\n@app.get(\"/\")\nasync def root():\n \"\"\"Root endpoint with service information.\"\"\"\n return {\n \"service\": \"MCP Metrics Collection Service\",\n \"version\": \"1.0.0\",\n \"status\": \"running\",\n \"endpoints\": {\n \"metrics\": \"/metrics\",\n \"health\": \"/health\",\n \"flush\": \"/flush\",\n \"rate-limit\": \"/rate-limit\",\n },\n }\n\n\nif __name__ == \"__main__\":\n import uvicorn\n\n uvicorn.run(app, host=settings.METRICS_SERVICE_HOST, port=settings.METRICS_SERVICE_PORT)\n" }, { "path": "metrics-service/app/otel/__init__.py", "content": "" }, { "path": "metrics-service/app/otel/exporters.py", "content": "from opentelemetry import metrics\nfrom opentelemetry.sdk.metrics import MeterProvider\nfrom opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader\nfrom opentelemetry.sdk.metrics.view import View, ExplicitBucketHistogramAggregation\nfrom opentelemetry.exporter.prometheus import PrometheusMetricReader\nfrom opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter\nfrom opentelemetry.sdk.resources import SERVICE_NAME, Resource\nfrom prometheus_client import start_http_server, PROCESS_COLLECTOR, PLATFORM_COLLECTOR, GC_COLLECTOR\nfrom prometheus_client import REGISTRY as PROM_REGISTRY\nimport logging\nfrom ..config import settings\n\nlogger = logging.getLogger(__name__)\n\n# Unregister default Prometheus collectors that emit process/platform/gc\n# metrics with timestamps. These cause \"out of order samples\" rejections\n# in AMP when the container restarts (new timestamps < stored timestamps).\nfor collector in [PROCESS_COLLECTOR, PLATFORM_COLLECTOR, GC_COLLECTOR]:\n try:\n PROM_REGISTRY.unregister(collector)\n except Exception:\n pass\n\n\ndef setup_otel():\n \"\"\"Setup OpenTelemetry metric providers and exporters.\"\"\"\n readers = []\n\n try:\n # Create resource with service name\n resource = Resource.create(attributes={SERVICE_NAME: settings.OTEL_SERVICE_NAME})\n\n # Create a View for duration histograms with configurable boundaries\n duration_view = View(\n instrument_name=\"*_duration_seconds\",\n aggregation=ExplicitBucketHistogramAggregation(\n boundaries=settings.HISTOGRAM_BUCKET_BOUNDARIES,\n ),\n )\n\n # Setup Prometheus exporter if enabled\n if settings.OTEL_PROMETHEUS_ENABLED:\n # Start Prometheus HTTP server\n start_http_server(\n port=settings.OTEL_PROMETHEUS_PORT, addr=settings.METRICS_SERVICE_HOST\n ) # nosec B104\n\n # Create PrometheusMetricReader (no endpoint parameter needed)\n prometheus_reader = PrometheusMetricReader()\n readers.append(prometheus_reader)\n logger.info(\n f\"Prometheus metrics exporter enabled on port {settings.OTEL_PROMETHEUS_PORT}\"\n )\n\n # Setup OTLP exporter if endpoint configured\n if settings.OTEL_OTLP_ENDPOINT:\n otlp_exporter = OTLPMetricExporter(endpoint=f\"{settings.OTEL_OTLP_ENDPOINT}/v1/metrics\")\n otlp_reader = PeriodicExportingMetricReader(\n exporter=otlp_exporter, export_interval_millis=settings.OTEL_OTLP_EXPORT_INTERVAL_MS\n )\n readers.append(otlp_reader)\n logger.info(\n f\"OTLP metrics exporter enabled for {settings.OTEL_OTLP_ENDPOINT} (interval: {settings.OTEL_OTLP_EXPORT_INTERVAL_MS}ms)\"\n )\n\n # Create MeterProvider with configured readers and resource\n if readers:\n meter_provider = MeterProvider(\n resource=resource,\n metric_readers=readers,\n views=[duration_view],\n )\n metrics.set_meter_provider(meter_provider)\n logger.info(\"OpenTelemetry metrics configured successfully\")\n else:\n logger.warning(\"No OpenTelemetry exporters configured\")\n\n except Exception as e:\n logger.error(f\"Failed to setup OpenTelemetry: {e}\")\n # Don't fail startup, just log the error\n pass\n" }, { "path": "metrics-service/app/otel/instruments.py", "content": "from opentelemetry import metrics\nfrom opentelemetry.sdk.metrics import MeterProvider\nfrom opentelemetry.sdk.metrics.export import MetricReader\nimport logging\n\nlogger = logging.getLogger(__name__)\n\n\nclass MetricsInstruments:\n \"\"\"OpenTelemetry metric instruments for MCP metrics.\"\"\"\n\n def __init__(self):\n self.meter = metrics.get_meter(\"mcp-metrics-service\")\n\n # Counter instruments\n self.auth_counter = self.meter.create_counter(\n name=\"mcp_auth_requests_total\",\n description=\"Total number of authentication requests\",\n unit=\"1\",\n )\n\n self.discovery_counter = self.meter.create_counter(\n name=\"mcp_tool_discovery_total\",\n description=\"Total number of tool discovery requests\",\n unit=\"1\",\n )\n\n self.tool_counter = self.meter.create_counter(\n name=\"mcp_tool_executions_total\",\n description=\"Total number of tool executions\",\n unit=\"1\",\n )\n\n # Histogram instruments for duration tracking\n self.auth_histogram = self.meter.create_histogram(\n name=\"mcp_auth_request_duration_seconds\",\n description=\"Duration of authentication requests in seconds\",\n unit=\"s\",\n )\n\n self.discovery_histogram = self.meter.create_histogram(\n name=\"mcp_tool_discovery_duration_seconds\",\n description=\"Duration of tool discovery requests in seconds\",\n unit=\"s\",\n )\n\n self.tool_histogram = self.meter.create_histogram(\n name=\"mcp_tool_execution_duration_seconds\",\n description=\"Duration of tool executions in seconds\",\n unit=\"s\",\n )\n\n self.latency_histogram = self.meter.create_histogram(\n name=\"mcp_protocol_latency_seconds\",\n description=\"Latency between MCP protocol steps in seconds\",\n unit=\"s\",\n )\n\n # Health check instruments\n self.health_counter = self.meter.create_counter(\n name=\"mcp_health_checks_total\",\n description=\"Total number of health checks performed\",\n unit=\"1\",\n )\n\n self.health_histogram = self.meter.create_histogram(\n name=\"mcp_health_check_duration_seconds\",\n description=\"Duration of health checks in seconds\",\n unit=\"s\",\n )\n\n logger.info(\"OpenTelemetry metric instruments initialized\")\n" }, { "path": "metrics-service/app/storage/__init__.py", "content": "" }, { "path": "metrics-service/app/storage/database.py", "content": "import aiosqlite\nimport asyncio\nimport logging\nimport json\nfrom pathlib import Path\nfrom datetime import datetime, timedelta\nfrom typing import List, Dict, Any\nfrom ..config import settings\n\nlogger = logging.getLogger(__name__)\n\n\nasync def wait_for_database(max_retries: int = 10, delay: float = 2.0):\n \"\"\"Wait for SQLite database container to be ready.\"\"\"\n db_path = settings.SQLITE_DB_PATH\n\n for attempt in range(max_retries):\n try:\n # Ensure directory exists first\n Path(db_path).parent.mkdir(parents=True, exist_ok=True)\n\n # Try to connect to database\n async with aiosqlite.connect(db_path) as db:\n await db.execute(\"SELECT 1\")\n logger.info(f\"Database connection successful on attempt {attempt + 1}\")\n return\n except Exception as e:\n logger.warning(f\"Database connection attempt {attempt + 1} failed: {e}\")\n if attempt < max_retries - 1:\n await asyncio.sleep(delay)\n else:\n raise Exception(f\"Failed to connect to database after {max_retries} attempts\")\n\n\nasync def _migrate_schema_if_needed(db):\n \"\"\"Migrate database schema if needed.\"\"\"\n try:\n # Check if tool_metrics table exists and has the new columns\n cursor = await db.execute(\"PRAGMA table_info(tool_metrics)\")\n columns = await cursor.fetchall()\n existing_columns = [col[1] for col in columns] if columns else []\n\n # If table doesn't exist, creation will handle it\n if not existing_columns:\n return\n\n # Check if we need to add new columns\n required_columns = [\"client_name\", \"client_version\", \"method\", \"user_hash\"]\n missing_columns = [col for col in required_columns if col not in existing_columns]\n\n if missing_columns:\n logger.info(f\"Adding missing columns to tool_metrics: {missing_columns}\")\n\n # Define allowed columns for security (defense in depth)\n ALLOWED_COLUMNS = {\n \"client_name\",\n \"client_version\",\n \"method\",\n \"user_hash\",\n \"server_name\",\n \"tool_name\",\n \"status\",\n \"error_type\",\n \"duration_ms\",\n \"timestamp\",\n \"success\",\n \"user_id\",\n \"session_id\",\n }\n\n for column in missing_columns:\n # Validate column name against allowlist before use in SQL\n if column not in ALLOWED_COLUMNS:\n logger.warning(f\"Skipping unexpected column name: {column}\")\n continue\n\n # Column name validated against allowlist - safe to use in SQL\n await db.execute( # nosemgrep: python.lang.security.audit.formatted-sql-query.formatted-sql-query\n f\"ALTER TABLE tool_metrics ADD COLUMN {column} TEXT\"\n )\n\n # Add indexes for new columns\n if \"client_name\" in missing_columns:\n await db.execute(\n \"CREATE INDEX IF NOT EXISTS idx_tool_client ON tool_metrics(client_name, timestamp)\"\n )\n if \"method\" in missing_columns:\n await db.execute(\n \"CREATE INDEX IF NOT EXISTS idx_tool_method ON tool_metrics(method, timestamp)\"\n )\n\n await db.commit()\n logger.info(\"Schema migration completed successfully\")\n\n except Exception as e:\n logger.warning(f\"Schema migration failed, will recreate tables: {e}\")\n\n\nasync def init_database():\n \"\"\"Initialize database with schema migrations.\"\"\"\n db_path = settings.SQLITE_DB_PATH\n\n # Ensure directory exists\n Path(db_path).parent.mkdir(parents=True, exist_ok=True)\n\n async with aiosqlite.connect(db_path) as db:\n # Enable WAL mode for better concurrency\n await db.execute(\"PRAGMA journal_mode=WAL\")\n await db.execute(\"PRAGMA synchronous=NORMAL\")\n await db.execute(\"PRAGMA cache_size=10000\")\n await db.execute(\"PRAGMA temp_store=MEMORY\")\n\n # Check if we need to migrate existing schema\n await _migrate_schema_if_needed(db)\n\n # Create tables\n await db.executescript(\"\"\"\n -- API Keys table\n CREATE TABLE IF NOT EXISTS api_keys (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n key_hash TEXT UNIQUE NOT NULL,\n service_name TEXT NOT NULL,\n created_at TEXT NOT NULL,\n last_used_at TEXT,\n is_active BOOLEAN DEFAULT 1,\n rate_limit INTEGER DEFAULT 1000\n );\n\n -- Main metrics table\n CREATE TABLE IF NOT EXISTS metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n service TEXT NOT NULL,\n service_version TEXT,\n instance_id TEXT,\n metric_type TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n value REAL NOT NULL,\n duration_ms REAL,\n dimensions TEXT, -- JSON\n metadata TEXT, -- JSON\n created_at TEXT DEFAULT (datetime('now'))\n );\n\n -- Auth metrics table\n CREATE TABLE IF NOT EXISTS auth_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n success BOOLEAN,\n method TEXT,\n server TEXT,\n user_hash TEXT,\n error_code TEXT,\n created_at TEXT DEFAULT (datetime('now'))\n );\n\n -- Discovery metrics table\n CREATE TABLE IF NOT EXISTS discovery_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n query TEXT,\n results_count INTEGER,\n top_k_services INTEGER,\n top_n_tools INTEGER,\n embedding_time_ms REAL,\n faiss_search_time_ms REAL,\n created_at TEXT DEFAULT (datetime('now'))\n );\n\n -- Tool metrics table\n CREATE TABLE IF NOT EXISTS tool_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n tool_name TEXT,\n server_path TEXT,\n server_name TEXT,\n success BOOLEAN,\n error_code TEXT,\n input_size_bytes INTEGER,\n output_size_bytes INTEGER,\n client_name TEXT,\n client_version TEXT,\n method TEXT,\n user_hash TEXT,\n created_at TEXT DEFAULT (datetime('now'))\n );\n \"\"\")\n\n # Create indexes for performance\n await db.executescript(\"\"\"\n CREATE INDEX IF NOT EXISTS idx_metrics_timestamp ON metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_metrics_service_type ON metrics(service, metric_type);\n CREATE INDEX IF NOT EXISTS idx_metrics_type_timestamp ON metrics(metric_type, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_auth_timestamp ON auth_metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_auth_success ON auth_metrics(success, timestamp);\n CREATE INDEX IF NOT EXISTS idx_auth_user ON auth_metrics(user_hash, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_discovery_timestamp ON discovery_metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_discovery_results ON discovery_metrics(results_count, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_tool_timestamp ON tool_metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_tool_name ON tool_metrics(tool_name, timestamp);\n CREATE INDEX IF NOT EXISTS idx_tool_success ON tool_metrics(success, timestamp);\n CREATE INDEX IF NOT EXISTS idx_tool_client ON tool_metrics(client_name, timestamp);\n CREATE INDEX IF NOT EXISTS idx_tool_method ON tool_metrics(method, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_api_keys_hash ON api_keys(key_hash);\n CREATE INDEX IF NOT EXISTS idx_api_keys_service ON api_keys(service_name);\n \"\"\")\n\n await db.commit()\n logger.info(\"Database tables and indexes created successfully\")\n\n\nclass MetricsStorage:\n \"\"\"SQLite storage handler for containerized database.\"\"\"\n\n def __init__(self):\n self.db_path = settings.SQLITE_DB_PATH\n\n async def store_metrics_batch(self, metrics_batch: List[Dict[str, Any]]):\n \"\"\"Store a batch of metrics in the containerized database.\"\"\"\n if not metrics_batch:\n return\n\n async with aiosqlite.connect(self.db_path) as db:\n try:\n for metric_data in metrics_batch:\n metric = metric_data[\"metric\"]\n request = metric_data[\"request\"]\n request_id = metric_data[\"request_id\"]\n\n # Store in main metrics table\n await db.execute(\n \"\"\"\n INSERT INTO metrics (\n request_id, service, service_version, instance_id,\n metric_type, timestamp, value, duration_ms,\n dimensions, metadata\n ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n \"\"\",\n (\n request_id,\n request.service,\n request.version,\n request.instance_id,\n metric.type.value,\n metric.timestamp.isoformat(),\n metric.value,\n metric.duration_ms,\n json.dumps(metric.dimensions),\n json.dumps(metric.metadata),\n ),\n )\n\n # Store in specialized table based on type\n await self._store_specialized_metric(db, metric, request, request_id)\n\n await db.commit()\n logger.debug(f\"Stored batch of {len(metrics_batch)} metrics to container DB\")\n\n except Exception as e:\n await db.rollback()\n logger.error(f\"Failed to store metrics batch: {e}\")\n raise\n\n async def _store_specialized_metric(self, db, metric, request, request_id):\n \"\"\"Store metric in specialized table based on type.\"\"\"\n if metric.type.value == \"auth_request\":\n await db.execute(\n \"\"\"\n INSERT INTO auth_metrics (\n request_id, timestamp, service, duration_ms,\n success, method, server, user_hash, error_code\n ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\n \"\"\",\n (\n request_id,\n metric.timestamp.isoformat(),\n request.service,\n metric.duration_ms,\n metric.dimensions.get(\"success\"),\n metric.dimensions.get(\"method\"),\n metric.dimensions.get(\"server\"),\n metric.dimensions.get(\"user_hash\"),\n metric.metadata.get(\"error_code\"),\n ),\n )\n\n elif metric.type.value == \"tool_discovery\":\n await db.execute(\n \"\"\"\n INSERT INTO discovery_metrics (\n request_id, timestamp, service, duration_ms,\n query, results_count, top_k_services, top_n_tools,\n embedding_time_ms, faiss_search_time_ms\n ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n \"\"\",\n (\n request_id,\n metric.timestamp.isoformat(),\n request.service,\n metric.duration_ms,\n metric.dimensions.get(\"query\"),\n metric.dimensions.get(\"results_count\"),\n metric.dimensions.get(\"top_k_services\"),\n metric.dimensions.get(\"top_n_tools\"),\n metric.metadata.get(\"embedding_time_ms\"),\n metric.metadata.get(\"faiss_search_time_ms\"),\n ),\n )\n\n elif metric.type.value == \"tool_execution\":\n await db.execute(\n \"\"\"\n INSERT INTO tool_metrics (\n request_id, timestamp, service, duration_ms,\n tool_name, server_path, server_name, success,\n error_code, input_size_bytes, output_size_bytes,\n client_name, client_version, method, user_hash\n ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n \"\"\",\n (\n request_id,\n metric.timestamp.isoformat(),\n request.service,\n metric.duration_ms,\n metric.dimensions.get(\"tool_name\"),\n metric.dimensions.get(\"server_path\"),\n metric.dimensions.get(\"server_name\"),\n metric.dimensions.get(\"success\"),\n metric.metadata.get(\"error_code\"),\n metric.metadata.get(\"input_size_bytes\"),\n metric.metadata.get(\"output_size_bytes\"),\n metric.dimensions.get(\"client_name\"),\n metric.dimensions.get(\"client_version\"),\n metric.dimensions.get(\"method\"),\n metric.dimensions.get(\"user_hash\"),\n ),\n )\n\n async def get_api_key(self, key_hash: str) -> Dict[str, Any] | None:\n \"\"\"Get API key details from database.\"\"\"\n async with aiosqlite.connect(self.db_path) as db:\n async with db.execute(\n \"\"\"\n SELECT service_name, is_active, rate_limit, last_used_at\n FROM api_keys \n WHERE key_hash = ?\n \"\"\",\n (key_hash,),\n ) as cursor:\n row = await cursor.fetchone()\n if row:\n return {\n \"service_name\": row[0],\n \"is_active\": bool(row[1]),\n \"rate_limit\": row[2],\n \"last_used_at\": row[3],\n }\n return None\n\n async def update_api_key_usage(self, key_hash: str):\n \"\"\"Update last_used_at timestamp for API key.\"\"\"\n async with aiosqlite.connect(self.db_path) as db:\n await db.execute(\n \"\"\"\n UPDATE api_keys \n SET last_used_at = datetime('now') \n WHERE key_hash = ?\n \"\"\",\n (key_hash,),\n )\n await db.commit()\n\n async def create_api_key(\n self, key_hash: str, service_name: str, rate_limit: int = 1000\n ) -> bool:\n \"\"\"Create a new API key in the database.\"\"\"\n try:\n async with aiosqlite.connect(self.db_path) as db:\n await db.execute(\n \"\"\"\n INSERT INTO api_keys (key_hash, service_name, created_at, is_active, rate_limit)\n VALUES (?, ?, datetime('now'), 1, ?)\n \"\"\",\n (key_hash, service_name, rate_limit),\n )\n await db.commit()\n return True\n except Exception as e:\n logger.error(f\"Failed to create API key: {e}\")\n return False\n" }, { "path": "metrics-service/app/storage/migrations.py", "content": "\"\"\"Database schema migration system for metrics service.\"\"\"\n\nimport asyncio\nimport logging\nimport json\nfrom datetime import datetime\nfrom typing import List, Dict, Any, Callable, Optional\nfrom pathlib import Path\nfrom ..config import settings\nfrom .database import MetricsStorage\nimport aiosqlite\n\nlogger = logging.getLogger(__name__)\n\n\nclass Migration:\n \"\"\"Represents a single database migration.\"\"\"\n\n def __init__(\n self,\n version: int,\n name: str,\n up_sql: str,\n down_sql: str = None,\n python_up: Callable | None = None,\n python_down: Callable | None = None,\n ):\n self.version = version\n self.name = name\n self.up_sql = up_sql\n self.down_sql = down_sql\n self.python_up = python_up\n self.python_down = python_down\n\n def __str__(self):\n return f\"Migration {self.version:04d}: {self.name}\"\n\n\nclass MigrationManager:\n \"\"\"Manages database schema migrations.\"\"\"\n\n def __init__(self, db_path: str = None):\n self.db_path = db_path or settings.SQLITE_DB_PATH\n self.migrations: List[Migration] = []\n self._register_migrations()\n\n def _register_migrations(self):\n \"\"\"Register all available migrations in order.\"\"\"\n\n # Migration 0001: Initial schema (this is what we already have)\n self.migrations.append(\n Migration(\n version=1,\n name=\"initial_schema\",\n up_sql=\"\"\"\n -- Migration 0001: Initial schema\n -- This represents the current schema in database.py\n \n -- Schema version tracking table\n CREATE TABLE IF NOT EXISTS schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n );\n \n -- API Keys table (already exists, but ensure consistency)\n CREATE TABLE IF NOT EXISTS api_keys (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n key_hash TEXT UNIQUE NOT NULL,\n service_name TEXT NOT NULL,\n created_at TEXT NOT NULL,\n last_used_at TEXT,\n is_active BOOLEAN DEFAULT 1,\n rate_limit INTEGER DEFAULT 1000\n );\n\n -- Main metrics table\n CREATE TABLE IF NOT EXISTS metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n service TEXT NOT NULL,\n service_version TEXT,\n instance_id TEXT,\n metric_type TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n value REAL NOT NULL,\n duration_ms REAL,\n dimensions TEXT, -- JSON\n metadata TEXT, -- JSON\n created_at TEXT DEFAULT (datetime('now'))\n );\n\n -- Auth metrics table\n CREATE TABLE IF NOT EXISTS auth_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n success BOOLEAN,\n method TEXT,\n server TEXT,\n user_hash TEXT,\n error_code TEXT,\n created_at TEXT DEFAULT (datetime('now'))\n );\n\n -- Discovery metrics table\n CREATE TABLE IF NOT EXISTS discovery_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n query TEXT,\n results_count INTEGER,\n top_k_services INTEGER,\n top_n_tools INTEGER,\n embedding_time_ms REAL,\n faiss_search_time_ms REAL,\n created_at TEXT DEFAULT (datetime('now'))\n );\n\n -- Tool metrics table\n CREATE TABLE IF NOT EXISTS tool_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n tool_name TEXT,\n server_path TEXT,\n server_name TEXT,\n success BOOLEAN,\n error_code TEXT,\n input_size_bytes INTEGER,\n output_size_bytes INTEGER,\n created_at TEXT DEFAULT (datetime('now'))\n );\n\n -- Indexes for performance\n CREATE INDEX IF NOT EXISTS idx_metrics_timestamp ON metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_metrics_service_type ON metrics(service, metric_type);\n CREATE INDEX IF NOT EXISTS idx_metrics_type_timestamp ON metrics(metric_type, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_auth_timestamp ON auth_metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_auth_success ON auth_metrics(success, timestamp);\n CREATE INDEX IF NOT EXISTS idx_auth_user ON auth_metrics(user_hash, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_discovery_timestamp ON discovery_metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_discovery_results ON discovery_metrics(results_count, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_tool_timestamp ON tool_metrics(timestamp);\n CREATE INDEX IF NOT EXISTS idx_tool_name ON tool_metrics(tool_name, timestamp);\n CREATE INDEX IF NOT EXISTS idx_tool_success ON tool_metrics(success, timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_api_keys_hash ON api_keys(key_hash);\n CREATE INDEX IF NOT EXISTS idx_api_keys_service ON api_keys(service_name);\n \"\"\",\n down_sql=\"\"\"\n -- Cannot rollback initial schema safely\n SELECT 'Initial schema rollback not supported' as error;\n \"\"\",\n )\n )\n\n # Migration 0002: Add metrics aggregation tables\n self.migrations.append(\n Migration(\n version=2,\n name=\"add_aggregation_tables\",\n up_sql=\"\"\"\n -- Migration 0002: Add aggregation tables for better performance\n \n -- Hourly aggregated metrics\n CREATE TABLE IF NOT EXISTS metrics_hourly (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n service TEXT NOT NULL,\n metric_type TEXT NOT NULL,\n hour_timestamp TEXT NOT NULL, -- ISO timestamp truncated to hour\n count INTEGER DEFAULT 0,\n sum_value REAL DEFAULT 0.0,\n avg_value REAL DEFAULT 0.0,\n min_value REAL,\n max_value REAL,\n sum_duration_ms REAL DEFAULT 0.0,\n avg_duration_ms REAL DEFAULT 0.0,\n created_at TEXT DEFAULT (datetime('now')),\n updated_at TEXT DEFAULT (datetime('now')),\n UNIQUE(service, metric_type, hour_timestamp)\n );\n \n -- Daily aggregated metrics \n CREATE TABLE IF NOT EXISTS metrics_daily (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n service TEXT NOT NULL,\n metric_type TEXT NOT NULL,\n date TEXT NOT NULL, -- YYYY-MM-DD format\n count INTEGER DEFAULT 0,\n sum_value REAL DEFAULT 0.0,\n avg_value REAL DEFAULT 0.0,\n min_value REAL,\n max_value REAL,\n sum_duration_ms REAL DEFAULT 0.0,\n avg_duration_ms REAL DEFAULT 0.0,\n created_at TEXT DEFAULT (datetime('now')),\n updated_at TEXT DEFAULT (datetime('now')),\n UNIQUE(service, metric_type, date)\n );\n \n -- Indexes for aggregation tables\n CREATE INDEX IF NOT EXISTS idx_hourly_service_type_hour ON metrics_hourly(service, metric_type, hour_timestamp);\n CREATE INDEX IF NOT EXISTS idx_hourly_hour ON metrics_hourly(hour_timestamp);\n \n CREATE INDEX IF NOT EXISTS idx_daily_service_type_date ON metrics_daily(service, metric_type, date);\n CREATE INDEX IF NOT EXISTS idx_daily_date ON metrics_daily(date);\n \"\"\",\n down_sql=\"\"\"\n -- Rollback aggregation tables\n DROP INDEX IF EXISTS idx_daily_date;\n DROP INDEX IF EXISTS idx_daily_service_type_date;\n DROP INDEX IF EXISTS idx_hourly_hour;\n DROP INDEX IF EXISTS idx_hourly_service_type_hour;\n DROP TABLE IF EXISTS metrics_daily;\n DROP TABLE IF EXISTS metrics_hourly;\n \"\"\",\n )\n )\n\n # Migration 0003: Add retention policies table\n self.migrations.append(\n Migration(\n version=3,\n name=\"add_retention_policies\",\n up_sql=\"\"\"\n -- Migration 0003: Add retention policies management\n \n CREATE TABLE IF NOT EXISTS retention_policies (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n table_name TEXT NOT NULL,\n retention_days INTEGER NOT NULL,\n is_active BOOLEAN DEFAULT 1,\n created_at TEXT DEFAULT (datetime('now')),\n updated_at TEXT DEFAULT (datetime('now')),\n UNIQUE(table_name)\n );\n \n -- Insert default retention policies\n INSERT OR IGNORE INTO retention_policies (table_name, retention_days) VALUES \n ('metrics', 90), -- Keep raw metrics for 90 days\n ('auth_metrics', 90), -- Keep auth metrics for 90 days \n ('discovery_metrics', 90), -- Keep discovery metrics for 90 days\n ('tool_metrics', 90), -- Keep tool metrics for 90 days\n ('metrics_hourly', 365), -- Keep hourly aggregates for 1 year\n ('metrics_daily', 1095); -- Keep daily aggregates for 3 years\n \"\"\",\n down_sql=\"\"\"\n -- Rollback retention policies\n DROP TABLE IF EXISTS retention_policies;\n \"\"\",\n )\n )\n\n # Migration 0004: Add API key usage tracking\n self.migrations.append(\n Migration(\n version=4,\n name=\"add_api_key_usage_tracking\",\n up_sql=\"\"\"\n -- Migration 0004: Enhanced API key usage tracking\n \n -- Add columns to api_keys table\n ALTER TABLE api_keys ADD COLUMN usage_count INTEGER DEFAULT 0;\n ALTER TABLE api_keys ADD COLUMN daily_usage_limit INTEGER DEFAULT NULL;\n ALTER TABLE api_keys ADD COLUMN monthly_usage_limit INTEGER DEFAULT NULL;\n ALTER TABLE api_keys ADD COLUMN description TEXT DEFAULT NULL;\n \n -- API key usage log table\n CREATE TABLE IF NOT EXISTS api_key_usage_log (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n key_hash TEXT NOT NULL,\n service_name TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n endpoint TEXT NOT NULL,\n request_count INTEGER DEFAULT 1,\n bytes_processed INTEGER DEFAULT 0,\n duration_ms REAL DEFAULT 0,\n status_code INTEGER DEFAULT 200,\n FOREIGN KEY (key_hash) REFERENCES api_keys(key_hash)\n );\n \n -- Indexes for usage tracking\n CREATE INDEX IF NOT EXISTS idx_usage_key_timestamp ON api_key_usage_log(key_hash, timestamp);\n CREATE INDEX IF NOT EXISTS idx_usage_timestamp ON api_key_usage_log(timestamp);\n CREATE INDEX IF NOT EXISTS idx_usage_endpoint ON api_key_usage_log(endpoint, timestamp);\n \"\"\",\n down_sql=\"\"\"\n -- Rollback API key usage tracking\n DROP INDEX IF EXISTS idx_usage_endpoint;\n DROP INDEX IF EXISTS idx_usage_timestamp;\n DROP INDEX IF EXISTS idx_usage_key_timestamp;\n DROP TABLE IF EXISTS api_key_usage_log;\n \n -- Note: Cannot easily remove columns from SQLite, would need table recreation\n -- For now, just mark as rolled back\n \"\"\",\n )\n )\n\n # Migration 5: Fix missing tables and timestamp columns\n self.migrations.append(\n Migration(\n version=5,\n name=\"fix_missing_tables_and_columns\",\n up_sql=\"\"\"\n -- Create aggregated metrics tables that retention policies expect\n CREATE TABLE IF NOT EXISTS metrics_hourly (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n hour_timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n metric_type TEXT NOT NULL,\n total_count INTEGER DEFAULT 0,\n avg_duration_ms REAL DEFAULT 0,\n success_count INTEGER DEFAULT 0,\n failure_count INTEGER DEFAULT 0,\n created_at TEXT DEFAULT (datetime('now')),\n UNIQUE(hour_timestamp, service, metric_type)\n );\n \n CREATE TABLE IF NOT EXISTS metrics_daily (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n date TEXT NOT NULL,\n service TEXT NOT NULL,\n metric_type TEXT NOT NULL,\n total_count INTEGER DEFAULT 0,\n avg_duration_ms REAL DEFAULT 0,\n success_count INTEGER DEFAULT 0,\n failure_count INTEGER DEFAULT 0,\n created_at TEXT DEFAULT (datetime('now')),\n UNIQUE(date, service, metric_type)\n );\n \n -- Create retention policies table\n CREATE TABLE IF NOT EXISTS retention_policies (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n table_name TEXT UNIQUE NOT NULL,\n retention_days INTEGER NOT NULL,\n is_active BOOLEAN DEFAULT 1,\n cleanup_query TEXT,\n timestamp_column TEXT DEFAULT 'created_at',\n created_at TEXT DEFAULT (datetime('now')),\n updated_at TEXT DEFAULT (datetime('now'))\n );\n \n -- Add missing indexes\n CREATE INDEX IF NOT EXISTS idx_metrics_hourly_timestamp ON metrics_hourly(hour_timestamp);\n CREATE INDEX IF NOT EXISTS idx_metrics_hourly_service ON metrics_hourly(service, metric_type);\n CREATE INDEX IF NOT EXISTS idx_metrics_daily_date ON metrics_daily(date);\n CREATE INDEX IF NOT EXISTS idx_metrics_daily_service ON metrics_daily(service, metric_type);\n CREATE INDEX IF NOT EXISTS idx_retention_policies_table ON retention_policies(table_name);\n \"\"\",\n down_sql=\"\"\"\n DROP TABLE IF EXISTS metrics_hourly;\n DROP TABLE IF EXISTS metrics_daily;\n DROP TABLE IF EXISTS retention_policies;\n DROP INDEX IF EXISTS idx_metrics_hourly_timestamp;\n DROP INDEX IF EXISTS idx_metrics_hourly_service;\n DROP INDEX IF EXISTS idx_metrics_daily_date;\n DROP INDEX IF EXISTS idx_metrics_daily_service;\n DROP INDEX IF EXISTS idx_retention_policies_table;\n \"\"\",\n )\n )\n\n async def get_current_version(self) -> int:\n \"\"\"Get the current schema version from the database.\"\"\"\n try:\n async with aiosqlite.connect(self.db_path) as db:\n # First check if migrations table exists\n cursor = await db.execute(\"\"\"\n SELECT name FROM sqlite_master \n WHERE type='table' AND name='schema_migrations'\n \"\"\")\n table_exists = await cursor.fetchone()\n\n if not table_exists:\n return 0 # No migrations have been applied\n\n # Get the highest version number\n cursor = await db.execute(\"\"\"\n SELECT MAX(version) FROM schema_migrations\n \"\"\")\n result = await cursor.fetchone()\n return result[0] if result[0] else 0\n\n except Exception as e:\n logger.error(f\"Failed to get current schema version: {e}\")\n return 0\n\n async def get_applied_migrations(self) -> List[Dict[str, Any]]:\n \"\"\"Get list of applied migrations.\"\"\"\n try:\n async with aiosqlite.connect(self.db_path) as db:\n cursor = await db.execute(\"\"\"\n SELECT version, name, applied_at \n FROM schema_migrations \n ORDER BY version\n \"\"\")\n rows = await cursor.fetchall()\n return [{\"version\": row[0], \"name\": row[1], \"applied_at\": row[2]} for row in rows]\n except Exception as e:\n logger.error(f\"Failed to get applied migrations: {e}\")\n return []\n\n async def apply_migration(self, migration: Migration) -> bool:\n \"\"\"Apply a single migration.\"\"\"\n logger.info(f\"Applying {migration}\")\n\n try:\n async with aiosqlite.connect(self.db_path) as db:\n await db.execute(\"BEGIN TRANSACTION\")\n\n try:\n # Execute the SQL migration\n if migration.up_sql:\n await db.executescript(migration.up_sql)\n\n # Execute Python migration if provided\n if migration.python_up:\n await migration.python_up(db)\n\n # Record the migration as applied\n await db.execute(\n \"\"\"\n INSERT INTO schema_migrations (version, name, applied_at)\n VALUES (?, ?, ?)\n \"\"\",\n (migration.version, migration.name, datetime.now().isoformat()),\n )\n\n await db.commit()\n logger.info(f\"Successfully applied {migration}\")\n return True\n\n except Exception as e:\n await db.rollback()\n logger.error(f\"Failed to apply {migration}: {e}\")\n return False\n\n except Exception as e:\n logger.error(f\"Database connection error during migration: {e}\")\n return False\n\n async def rollback_migration(self, migration: Migration) -> bool:\n \"\"\"Rollback a single migration.\"\"\"\n logger.info(f\"Rolling back {migration}\")\n\n try:\n async with aiosqlite.connect(self.db_path) as db:\n await db.execute(\"BEGIN TRANSACTION\")\n\n try:\n # Execute Python rollback if provided\n if migration.python_down:\n await migration.python_down(db)\n\n # Execute the SQL rollback\n if migration.down_sql:\n await db.executescript(migration.down_sql)\n\n # Remove the migration record\n await db.execute(\n \"\"\"\n DELETE FROM schema_migrations WHERE version = ?\n \"\"\",\n (migration.version,),\n )\n\n await db.commit()\n logger.info(f\"Successfully rolled back {migration}\")\n return True\n\n except Exception as e:\n await db.rollback()\n logger.error(f\"Failed to rollback {migration}: {e}\")\n return False\n\n except Exception as e:\n logger.error(f\"Database connection error during rollback: {e}\")\n return False\n\n async def migrate_up(self, target_version: int | None = None) -> bool:\n \"\"\"Apply all pending migrations up to target version.\"\"\"\n current_version = await self.get_current_version()\n target_version = target_version or max(m.version for m in self.migrations)\n\n logger.info(f\"Current schema version: {current_version}\")\n logger.info(f\"Target schema version: {target_version}\")\n\n if current_version >= target_version:\n logger.info(\"Database schema is up to date\")\n return True\n\n # Find migrations to apply\n pending_migrations = [\n m for m in self.migrations if current_version < m.version <= target_version\n ]\n\n if not pending_migrations:\n logger.info(\"No migrations to apply\")\n return True\n\n logger.info(f\"Applying {len(pending_migrations)} migrations...\")\n\n for migration in sorted(pending_migrations, key=lambda x: x.version):\n success = await self.apply_migration(migration)\n if not success:\n logger.error(f\"Migration failed at {migration}, aborting\")\n return False\n\n logger.info(\"All migrations applied successfully\")\n return True\n\n async def migrate_down(self, target_version: int) -> bool:\n \"\"\"Rollback migrations down to target version.\"\"\"\n current_version = await self.get_current_version()\n\n logger.info(f\"Current schema version: {current_version}\")\n logger.info(f\"Target schema version: {target_version}\")\n\n if current_version <= target_version:\n logger.info(\"No rollback needed\")\n return True\n\n # Find migrations to rollback\n rollback_migrations = [\n m for m in self.migrations if target_version < m.version <= current_version\n ]\n\n if not rollback_migrations:\n logger.info(\"No migrations to rollback\")\n return True\n\n logger.info(f\"Rolling back {len(rollback_migrations)} migrations...\")\n\n # Rollback in reverse order\n for migration in sorted(rollback_migrations, key=lambda x: x.version, reverse=True):\n success = await self.rollback_migration(migration)\n if not success:\n logger.error(f\"Rollback failed at {migration}, aborting\")\n return False\n\n logger.info(\"All rollbacks completed successfully\")\n return True\n\n def list_migrations(self) -> List[Migration]:\n \"\"\"List all available migrations.\"\"\"\n return sorted(self.migrations, key=lambda x: x.version)\n\n async def get_migration_status(self) -> Dict[str, Any]:\n \"\"\"Get comprehensive migration status.\"\"\"\n current_version = await self.get_current_version()\n applied_migrations = await self.get_applied_migrations()\n all_migrations = self.list_migrations()\n\n pending_migrations = [m for m in all_migrations if m.version > current_version]\n\n return {\n \"current_version\": current_version,\n \"latest_version\": max(m.version for m in all_migrations),\n \"applied_count\": len(applied_migrations),\n \"pending_count\": len(pending_migrations),\n \"applied_migrations\": applied_migrations,\n \"pending_migrations\": [\n {\"version\": m.version, \"name\": m.name} for m in pending_migrations\n ],\n }\n\n\n# Global migration manager instance\nmigration_manager = MigrationManager()\n" }, { "path": "metrics-service/app/utils/__init__.py", "content": "" }, { "path": "metrics-service/app/utils/helpers.py", "content": "import hashlib\nimport hmac\nimport secrets\nfrom datetime import datetime\n\n# Application-level key for HMAC-based API key hashing.\n# This adds a layer of domain separation beyond plain SHA-256.\n_HASH_KEY: bytes = b\"mcp-gateway-metrics-api-key-v1\"\n\n\ndef generate_api_key() -> str:\n \"\"\"Generate a new API key.\"\"\"\n return f\"mcp_metrics_{secrets.token_urlsafe(32)}\"\n\n\ndef hash_api_key(api_key: str) -> str:\n \"\"\"Hash API key for storage using HMAC-SHA256.\"\"\"\n return hmac.new(_HASH_KEY, api_key.encode(), hashlib.sha256).hexdigest()\n\n\ndef generate_request_id() -> str:\n \"\"\"Generate a unique request ID.\"\"\"\n return f\"req_{secrets.token_hex(8)}\"\n" }, { "path": "metrics-service/create_api_key.py", "content": "#!/usr/bin/env python3\n\"\"\"\nScript to create API keys for the metrics service.\nRun this script to generate API keys for different services.\n\"\"\"\n\nimport asyncio\nimport sys\nfrom pathlib import Path\n\n# Add the app directory to the path\nsys.path.insert(0, str(Path(__file__).parent / \"app\"))\n\nfrom app.storage.database import init_database, MetricsStorage\nfrom app.utils.helpers import generate_api_key, hash_api_key\n\n\nasync def create_api_key_for_service(service_name: str):\n \"\"\"Create an API key for a service.\"\"\"\n # Initialize database\n await init_database()\n\n # Generate API key\n api_key = generate_api_key()\n key_hash = hash_api_key(api_key)\n\n # Store in database\n storage = MetricsStorage()\n success = await storage.create_api_key(key_hash, service_name)\n\n if success:\n masked_key = f\"{api_key[:12]}...{api_key[-4:]}\" if len(api_key) > 16 else \"***\"\n print(f\"API Key created for service '{service_name}':\")\n print(f\"API Key (masked): {masked_key}\")\n print(f\"Hash: {key_hash}\")\n\n # Write full key to a file so it is not logged in plain text\n key_file = Path(f\".api_key_{service_name}.txt\")\n key_file.write_text(f\"METRICS_API_KEY={api_key}\\n\")\n print(f\"\\nFull API key written to: {key_file}\")\n print(\"Store the key securely and delete the file after use.\")\n return api_key\n else:\n print(f\"Failed to create API key for service '{service_name}'\")\n return None\n\n\nasync def main():\n \"\"\"Main function to create API keys for common services.\"\"\"\n services = [\"auth-server\", \"registry-service\", \"mcpgw-server\", \"test-client\"]\n\n print(\"Creating API keys for MCP services...\\n\")\n\n for service in services:\n api_key = await create_api_key_for_service(service)\n if api_key:\n print(\"-\" * 80)\n print()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "metrics-service/docs/README.md", "content": "# MCP Metrics Collection Service\n\nThe MCP Metrics Collection Service is a centralized, high-performance metrics collection and aggregation system designed specifically for the MCP Gateway Registry ecosystem. It provides real-time metrics collection, validation, rate limiting, and OpenTelemetry integration.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Quick Start](#quick-start)\n- [API Reference](#api-reference)\n- [Database Schema](#database-schema)\n- [Data Retention](#data-retention)\n- [Configuration](#configuration)\n- [Development](#development)\n- [Deployment](#deployment)\n- [Monitoring](#monitoring)\n\n## Overview\n\n### Purpose\n\nThe metrics service serves as the central hub for collecting, validating, and storing performance and usage metrics from all MCP Gateway Registry components including:\n\n- Authentication servers\n- Registry services \n- MCP servers and tools\n- Client applications\n\n### Key Features\n\n- **High Performance**: Async/await architecture with connection pooling\n- **Data Validation**: Comprehensive input validation with detailed error reporting\n- **Rate Limiting**: Token bucket rate limiting (1000 requests/minute per API key)\n- **Schema Evolution**: Version-controlled database migrations\n- **OpenTelemetry Integration**: Native OTLP and Prometheus export\n- **Secure Authentication**: SHA256-hashed API keys with usage tracking\n- **Data Retention**: Configurable retention policies for different metric types\n- **Containerized Deployment**: Docker-ready with SQLite persistence\n\n## Architecture\n\n### System Components\n\n```\n┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n│ Auth Server │ │ Registry Service│ │ MCP Servers │\n│ │ │ │ │ │\n└─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘\n │ │ │\n └──────────────────────┼──────────────────────┘\n │\n ┌─────────────▼──────────────┐\n │ Metrics Collection API │\n │ │\n │ • Rate Limiting │\n │ • Data Validation │\n │ • API Key Auth │\n └─────────────┬──────────────┘\n │\n ┌─────────────▼──────────────┐\n │ Metrics Processor │\n │ │\n │ • Buffered Processing │\n │ • OTel Integration │\n │ • Error Handling │\n └─────────────┬──────────────┘\n │\n ┌────────────────────────┼────────────────────────┐\n │ │ │\n┌───────▼────────┐ ┌─────────▼─────────┐ ┌────────▼────────┐\n│ SQLite Store │ │ Prometheus Export │ │ OTLP Export │\n│ │ │ │ │ │\n│ • Raw Metrics │ │ • Real-time │ │ • External │\n│ • Aggregates │ │ • Histograms │ │ • APM Systems │\n│ • Retention │ │ • Counters │ │ • Observability │\n└────────────────┘ └───────────────────┘ └─────────────────┘\n```\n\n### Data Flow\n\n1. **Collection**: Services send metrics via HTTP POST to `/metrics` endpoint\n2. **Authentication**: API key validation with rate limiting check\n3. **Validation**: Comprehensive data validation using custom validator\n4. **Processing**: Metrics processor handles buffering and format conversion\n5. **Storage**: Atomic writes to SQLite with transaction safety\n6. **Export**: Real-time export to Prometheus and optional OTLP endpoints\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.14+\n- Docker and Docker Compose\n- uv package manager (recommended)\n\n### Installation\n\n1. **Clone and setup**:\n```bash\ncd metrics-service\nuv sync\n```\n\n2. **Start dependencies**:\n```bash\ndocker-compose up -d metrics-db\n```\n\n3. **Initialize database**:\n```bash\nuv run python migrate.py up\n```\n\n4. **Create API keys**:\n```bash\nuv run python create_api_key.py\n```\n\n5. **Start the service**:\n```bash\nuv run python -m app.main\n```\n\nThe service will be available at:\n- HTTP API: `http://localhost:8890`\n- Prometheus metrics: `http://localhost:9465/metrics`\n\n### First Metrics Submission\n\n```bash\ncurl -X POST http://localhost:8890/metrics \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-api-key-here\" \\\n -d '{\n \"service\": \"test-service\",\n \"version\": \"1.0.0\",\n \"instance_id\": \"test-01\",\n \"metrics\": [\n {\n \"type\": \"auth_request\",\n \"value\": 1.0,\n \"duration_ms\": 45.2,\n \"dimensions\": {\n \"method\": \"jwt\",\n \"success\": true,\n \"server\": \"auth-01\"\n }\n }\n ]\n }'\n```\n\n## API Reference\n\n### Authentication\n\nAll API endpoints require authentication via the `X-API-Key` header:\n\n```http\nX-API-Key: your-api-key-here\n```\n\nAPI keys are:\n- SHA256 hashed for secure storage\n- Rate limited to 1000 requests/minute by default\n- Tracked for usage analytics\n- Service-specific for isolation\n\n### Rate Limiting\n\nRate limits are enforced per API key with the following headers returned:\n\n```http\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 999\n```\n\nWhen rate limit is exceeded, you'll receive a `429 Too Many Requests` response with:\n\n```http\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 0\nRetry-After: 60\n```\n\n### Endpoints\n\n#### POST /metrics\n\nSubmit metrics data for collection and processing.\n\n**Request Body**:\n```json\n{\n \"service\": \"string\", // Required: Service name (alphanumeric, -, _)\n \"version\": \"string\", // Optional: Semantic version (x.y.z)\n \"instance_id\": \"string\", // Optional: Instance identifier\n \"metrics\": [ // Required: Array of metrics (max 100)\n {\n \"type\": \"metric_type\", // Required: One of supported metric types\n \"value\": 1.0, // Required: Numeric value\n \"duration_ms\": 150.5, // Optional: Duration in milliseconds\n \"timestamp\": \"2024-01-01T00:00:00Z\", // Optional: ISO timestamp\n \"dimensions\": { // Optional: Key-value dimensions (max 20)\n \"key\": \"value\"\n },\n \"metadata\": { // Optional: Additional metadata (max 30)\n \"key\": \"value\"\n }\n }\n ]\n}\n```\n\n**Supported Metric Types**:\n- `auth_request`: Authentication requests\n- `tool_discovery`: Tool discovery operations\n- `tool_execution`: Tool execution events\n\n**Response**:\n```json\n{\n \"status\": \"success\",\n \"accepted\": 1,\n \"rejected\": 0,\n \"errors\": [],\n \"request_id\": \"req_123\"\n}\n```\n\n**Validation Rules**:\n- Service name: 100 chars max, alphanumeric with `-` and `_`\n- Metric value: Required, numeric, range ±1e12\n- Duration: Non-negative, max 24 hours in milliseconds\n- Dimensions: Max 20 keys, 50 char key length, 200 char value length\n- Metadata: Max 30 fields, 50 char key length, 1000 char value length\n\n#### POST /flush\n\nForce flush buffered metrics to storage.\n\n**Response**:\n```json\n{\n \"status\": \"success\",\n \"message\": \"Metrics flushed to storage\"\n}\n```\n\n#### GET /rate-limit\n\nGet current rate limit status for your API key.\n\n**Response**:\n```json\n{\n \"service\": \"your-service\",\n \"rate_limit\": 1000,\n \"available_tokens\": 950,\n \"reset_time_seconds\": 30\n}\n```\n\n#### GET /health\n\nHealth check endpoint.\n\n**Response**:\n```json\n{\n \"status\": \"healthy\",\n \"service\": \"metrics-collection\"\n}\n```\n\n#### GET /\n\nService information and available endpoints.\n\n**Response**:\n```json\n{\n \"service\": \"MCP Metrics Collection Service\",\n \"version\": \"1.0.0\",\n \"status\": \"running\",\n \"endpoints\": {\n \"metrics\": \"/metrics\",\n \"health\": \"/health\",\n \"flush\": \"/flush\",\n \"rate-limit\": \"/rate-limit\"\n }\n}\n```\n\n### Error Responses\n\nAll error responses follow this format:\n\n```json\n{\n \"detail\": \"Error description\",\n \"status_code\": 400\n}\n```\n\nCommon error codes:\n- `400`: Bad Request - Invalid data format\n- `401`: Unauthorized - Missing or invalid API key\n- `422`: Validation Error - Data validation failed\n- `429`: Too Many Requests - Rate limit exceeded\n- `500`: Internal Server Error - Processing failure\n\n## Database Schema\n\n### Schema Overview\n\nThe database uses SQLite with the following table structure:\n\n```sql\n-- API key management\napi_keys (\n id, key_hash, service_name, created_at, last_used_at,\n is_active, rate_limit, usage_count, daily_usage_limit,\n monthly_usage_limit, description\n)\n\n-- Raw metrics storage\nmetrics (\n id, request_id, service, service_version, instance_id,\n metric_type, timestamp, value, duration_ms, dimensions,\n metadata, created_at\n)\n\n-- Specialized metric tables\nauth_metrics (...)\ndiscovery_metrics (...)\ntool_metrics (...)\n\n-- Aggregation tables\nmetrics_hourly (...)\nmetrics_daily (...)\n\n-- System tables\nschema_migrations (...)\nretention_policies (...)\napi_key_usage_log (...)\n```\n\n### Schema Migrations\n\nThe service uses a version-controlled migration system:\n\n```bash\n# Check migration status\nuv run python migrate.py status\n\n# Apply pending migrations\nuv run python migrate.py up\n\n# Rollback to version\nuv run python migrate.py down 2\n\n# List all migrations\nuv run python migrate.py list\n```\n\nCurrent migrations:\n- **0001**: Initial schema with core tables\n- **0002**: Aggregation tables for performance\n- **0003**: Retention policies management\n- **0004**: Enhanced API key usage tracking\n\n## Data Retention\n\nThe service includes a comprehensive data retention system that automatically manages the lifecycle of metrics data to prevent unbounded database growth while maintaining optimal performance.\n\n### Key Features\n\n- **Automated Cleanup**: Daily background tasks remove old data based on configurable retention policies\n- **Configurable Policies**: Different retention periods for raw metrics vs. aggregated data\n- **Safe Operations**: Dry-run capabilities and atomic transactions prevent data loss\n- **Administrative APIs**: Full control over retention policies and cleanup operations\n- **Space Reclamation**: Automatic VACUUM operations after cleanup to reclaim disk space\n\n### Default Retention Policies\n\n```\nRaw metrics: 90 days\n├── metrics (auth requests, tool executions, etc.)\n├── auth_metrics (authentication events)\n├── discovery_metrics (tool discovery operations)\n└── tool_metrics (individual tool usage)\n\nAggregated metrics: 1-3 years \n├── metrics_hourly (365 days)\n└── metrics_daily (1095 days)\n\nSystem data: 90 days\n└── api_key_usage_log (API usage tracking)\n```\n\n### Quick Operations\n\n```bash\n# Preview what would be cleaned up\ncurl -H \"X-API-Key: your-key\" http://localhost:8890/admin/retention/preview\n\n# Execute cleanup (dry-run by default)\ncurl -X POST -H \"X-API-Key: your-key\" http://localhost:8890/admin/retention/cleanup\n\n# View current policies\ncurl -H \"X-API-Key: your-key\" http://localhost:8890/admin/retention/policies\n\n# Update retention period for a table\ncurl -X PUT -H \"X-API-Key: your-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"retention_days\": 120, \"is_active\": true}' \\\n http://localhost:8890/admin/retention/policies/metrics\n```\n\n**📖 For comprehensive documentation on data retention, see [data-retention.md](data-retention.md)**\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Database\nSQLITE_DB_PATH=\"/var/lib/sqlite/metrics.db\"\nMETRICS_RETENTION_DAYS=\"90\"\nDB_CONNECTION_TIMEOUT=\"30\"\n\n# Service\nMETRICS_SERVICE_PORT=\"8890\"\nMETRICS_SERVICE_HOST=\"0.0.0.0\"\n\n# OpenTelemetry\nOTEL_SERVICE_NAME=\"mcp-metrics-service\"\nOTEL_PROMETHEUS_ENABLED=\"true\"\nOTEL_PROMETHEUS_PORT=\"9465\"\nOTEL_OTLP_ENDPOINT=\"\"\n\n# Security\nMETRICS_RATE_LIMIT=\"1000\"\nAPI_KEY_HASH_ALGORITHM=\"sha256\"\n\n# Performance\nBATCH_SIZE=\"100\"\nFLUSH_INTERVAL_SECONDS=\"30\"\nMAX_REQUEST_SIZE=\"10MB\"\n```\n\n### Docker Configuration\n\nThe service includes Docker configuration for containerized deployment:\n\n```yaml\n# docker-compose.yml\nmetrics-service:\n build: ./metrics-service\n ports:\n - \"8890:8890\" # HTTP API\n - \"9465:9465\" # Prometheus metrics\n environment:\n - SQLITE_DB_PATH=/var/lib/sqlite/metrics.db\n volumes:\n - metrics-db-data:/var/lib/sqlite\n depends_on:\n - metrics-db\n\nmetrics-db:\n image: nouchka/sqlite3:latest\n volumes:\n - metrics-db-data:/var/lib/sqlite\n```\n\n## Development\n\n### Setting Up Development Environment\n\n1. **Install dependencies**:\n```bash\nuv sync --dev\n```\n\n2. **Run tests**:\n```bash\nuv run pytest -v\n```\n\n3. **Run with hot reload**:\n```bash\nuv run uvicorn app.main:app --reload --port 8890\n```\n\n### Project Structure\n\n```\nmetrics-service/\n├── app/\n│ ├── api/\n│ │ ├── auth.py # API key authentication\n│ │ └── routes.py # HTTP endpoints\n│ ├── core/\n│ │ ├── models.py # Pydantic data models\n│ │ ├── processor.py # Metrics processing engine\n│ │ ├── rate_limiter.py # Rate limiting implementation\n│ │ └── validator.py # Data validation\n│ ├── otel/\n│ │ ├── exporters.py # OpenTelemetry setup\n│ │ └── instruments.py # OTel instruments\n│ ├── storage/\n│ │ ├── database.py # SQLite storage layer\n│ │ └── migrations.py # Schema migration system\n│ ├── utils/\n│ │ └── helpers.py # Utility functions\n│ ├── config.py # Configuration management\n│ └── main.py # FastAPI application\n├── tests/\n│ ├── test_api.py # API endpoint tests\n│ ├── test_migrations.py # Migration system tests\n│ ├── test_processor.py # Processing logic tests\n│ ├── test_rate_limiter.py # Rate limiting tests\n│ └── test_validator.py # Validation tests\n├── docs/ # Documentation\n├── migrate.py # Migration CLI tool\n├── create_api_key.py # API key creation script\n├── pyproject.toml # Project configuration\n└── README.md\n```\n\n### Testing\n\nThe service includes comprehensive test coverage:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=app\n\n# Run specific test file\nuv run pytest tests/test_api.py -v\n\n# Run specific test\nuv run pytest tests/test_validator.py::TestValidationResult::test_add_error -v\n```\n\nTest categories:\n- **API Tests**: HTTP endpoint functionality\n- **Validation Tests**: Data validation logic\n- **Rate Limiting Tests**: Token bucket algorithm\n- **Migration Tests**: Database schema evolution\n- **Processor Tests**: Metrics processing pipeline\n\n### Code Quality\n\nThe project uses modern Python tooling:\n\n```bash\n# Format code\nuv run black app/ tests/\n\n# Sort imports\nuv run isort app/ tests/\n\n# Type checking\nuv run mypy app/\n\n# Linting\nuv run ruff check app/ tests/\n```\n\n## Deployment\n\n### Production Deployment\n\n1. **Build and deploy with Docker**:\n```bash\ndocker-compose up -d\n```\n\n2. **Initialize database**:\n```bash\ndocker-compose exec metrics-service python migrate.py up\n```\n\n3. **Create production API keys**:\n```bash\ndocker-compose exec metrics-service python create_api_key.py\n```\n\n4. **Verify health**:\n```bash\ncurl http://localhost:8890/health\n```\n\n### Environment-Specific Configuration\n\n**Development**:\n```bash\nSQLITE_DB_PATH=\"./dev.db\"\nMETRICS_SERVICE_HOST=\"127.0.0.1\"\nOTEL_PROMETHEUS_ENABLED=\"true\"\n```\n\n**Production**:\n```bash\nSQLITE_DB_PATH=\"/var/lib/sqlite/metrics.db\"\nMETRICS_SERVICE_HOST=\"0.0.0.0\"\nOTEL_OTLP_ENDPOINT=\"https://otel-collector.example.com\"\nMETRICS_RATE_LIMIT=\"5000\"\n```\n\n### Security Considerations\n\n- **API Keys**: Never log API keys in plaintext\n- **Database**: Ensure SQLite file permissions are restricted\n- **Network**: Use HTTPS in production environments\n- **Rate Limiting**: Adjust limits based on expected traffic\n- **Monitoring**: Set up alerts for authentication failures\n\n## Monitoring\n\n### Built-in Metrics\n\nThe service exposes Prometheus metrics at `/metrics` (port 9465):\n\n```\n# HTTP request metrics\nhttp_requests_total{method=\"POST\", endpoint=\"/metrics\", status=\"200\"}\nhttp_request_duration_seconds{method=\"POST\", endpoint=\"/metrics\"}\n\n# Application metrics\nmetrics_processed_total{service=\"auth-server\", type=\"auth_request\"}\nmetrics_validation_errors_total{field=\"service\", error_type=\"invalid\"}\napi_key_requests_total{service=\"auth-server\", status=\"success\"}\n\n# Rate limiting metrics\nrate_limit_hits_total{service=\"auth-server\"}\nrate_limit_available_tokens{service=\"auth-server\"}\n\n# Database metrics\ndatabase_operations_total{operation=\"insert\", table=\"metrics\"}\ndatabase_query_duration_seconds{operation=\"select\", table=\"metrics\"}\n```\n\n### Health Checks\n\nThe service provides multiple health check endpoints:\n\n```bash\n# Basic health\ncurl http://localhost:8890/health\n\n# Database connectivity\ncurl http://localhost:8890/health/db\n\n# Rate limiter status\ncurl -H \"X-API-Key: your-key\" http://localhost:8890/rate-limit\n```\n\n### Alerting\n\nRecommended alerts:\n\n```yaml\n# High error rate\n- alert: MetricsHighErrorRate\n expr: rate(http_requests_total{status=~\"5..\"}[5m]) > 0.1\n \n# Rate limit exhaustion\n- alert: RateLimitExhausted\n expr: rate_limit_available_tokens < 10\n\n# Database errors\n- alert: DatabaseErrors\n expr: increase(database_errors_total[5m]) > 0\n```\n\n### Log Analysis\n\nThe service uses structured logging:\n\n```json\n{\n \"timestamp\": \"2024-01-01T00:00:00Z\",\n \"level\": \"INFO\",\n \"logger\": \"app.api.routes\",\n \"message\": \"Processed 5 metrics from auth-server\",\n \"request_id\": \"req_123\",\n \"service\": \"auth-server\",\n \"accepted\": 5,\n \"rejected\": 0\n}\n```\n\nThis documentation provides a comprehensive guide to understanding, deploying, and maintaining the MCP Metrics Collection Service." }, { "path": "metrics-service/docs/api-reference.md", "content": "# API Reference\n\nThis document provides detailed API reference for the MCP Metrics Collection Service.\n\n## Table of Contents\n\n- [Authentication](#authentication)\n- [Rate Limiting](#rate-limiting)\n- [Endpoints](#endpoints)\n- [Data Models](#data-models)\n- [Error Handling](#error-handling)\n- [Examples](#examples)\n\n## Authentication\n\n### API Key Authentication\n\nAll API endpoints require authentication using the `X-API-Key` header.\n\n```http\nX-API-Key: your-api-key-here\n```\n\n#### API Key Properties\n\n- **Format**: Alphanumeric string (e.g., `mcp_key_1a2b3c4d5e6f`)\n- **Hashing**: SHA256 hashed for secure storage\n- **Scope**: Service-specific isolation\n- **Tracking**: Usage analytics and rate limiting\n\n#### Creating API Keys\n\nUse the provided script to create API keys:\n\n```bash\nuv run python create_api_key.py\n```\n\nOr create for specific service:\n\n```python\nfrom app.utils.helpers import generate_api_key, hash_api_key\nfrom app.storage.database import MetricsStorage\n\napi_key = generate_api_key()\nkey_hash = hash_api_key(api_key)\n\nstorage = MetricsStorage()\nawait storage.create_api_key(key_hash, \"your-service-name\")\n```\n\n## Rate Limiting\n\n### Rate Limit Policy\n\n- **Default Limit**: 1000 requests per minute per API key\n- **Algorithm**: Token bucket with refill rate\n- **Scope**: Per API key (service isolation)\n- **Granularity**: Per-minute windows\n\n### Rate Limit Headers\n\nEvery response includes rate limit information:\n\n```http\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 999\n```\n\n### Rate Limit Exceeded\n\nWhen rate limit is exceeded (HTTP 429):\n\n```http\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 0\nRetry-After: 60\nContent-Type: application/json\n\n{\n \"detail\": \"Rate limit exceeded. Limit: 1000 requests/minute\"\n}\n```\n\n### Rate Limit Status Endpoint\n\nCheck current rate limit status:\n\n```http\nGET /rate-limit\nX-API-Key: your-api-key-here\n```\n\nResponse:\n```json\n{\n \"service\": \"auth-server\",\n \"rate_limit\": 1000,\n \"available_tokens\": 950,\n \"reset_time_seconds\": 30\n}\n```\n\n## Endpoints\n\n### Core Endpoints\n\n#### POST /metrics\n\nSubmit metrics data for collection and processing.\n\n#### Request\n\n```http\nPOST /metrics\nContent-Type: application/json\nX-API-Key: your-api-key-here\n\n{\n \"service\": \"auth-server\",\n \"version\": \"1.0.0\",\n \"instance_id\": \"auth-01\",\n \"metrics\": [\n {\n \"type\": \"auth_request\",\n \"value\": 1.0,\n \"duration_ms\": 45.2,\n \"timestamp\": \"2024-01-01T12:00:00Z\",\n \"dimensions\": {\n \"method\": \"jwt\",\n \"success\": true,\n \"server\": \"auth-01\",\n \"user_hash\": \"user_abc123\"\n },\n \"metadata\": {\n \"error_code\": null,\n \"request_size\": 1024,\n \"response_size\": 512\n }\n }\n ]\n}\n```\n\n#### Request Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `service` | string | Yes | Service name (alphanumeric, `-`, `_`, max 100 chars) |\n| `version` | string | No | Semantic version (e.g., \"1.0.0\") |\n| `instance_id` | string | No | Instance identifier (alphanumeric, `-`, `_`, `.`, max 100 chars) |\n| `metrics` | array | Yes | Array of metric objects (max 100) |\n\n#### Metric Object Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | string | Yes | Metric type (see [Metric Types](#metric-types)) |\n| `value` | number | Yes | Numeric value (range: ±1e12) |\n| `duration_ms` | number | No | Duration in milliseconds (0-86400000) |\n| `timestamp` | string | No | ISO 8601 timestamp (defaults to current time) |\n| `dimensions` | object | No | Key-value dimensions (max 20 fields) |\n| `metadata` | object | No | Additional metadata (max 30 fields) |\n\n#### Response\n\n```json\n{\n \"status\": \"success\",\n \"accepted\": 1,\n \"rejected\": 0,\n \"errors\": [],\n \"request_id\": \"req_8a7b6c5d\"\n}\n```\n\n#### Response Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `status` | string | \"success\" or \"error\" |\n| `accepted` | integer | Number of metrics successfully processed |\n| `rejected` | integer | Number of metrics rejected due to validation |\n| `errors` | array | Array of error messages for rejected metrics |\n| `request_id` | string | Unique request identifier for tracking |\n\n### POST /flush\n\nForce flush buffered metrics to storage.\n\n#### Request\n\n```http\nPOST /flush\nX-API-Key: your-api-key-here\n```\n\n#### Response\n\n```json\n{\n \"status\": \"success\",\n \"message\": \"Metrics flushed to storage\"\n}\n```\n\n### GET /rate-limit\n\nGet current rate limit status for the authenticated API key.\n\n#### Request\n\n```http\nGET /rate-limit\nX-API-Key: your-api-key-here\n```\n\n#### Response\n\n```json\n{\n \"service\": \"auth-server\",\n \"rate_limit\": 1000,\n \"available_tokens\": 950,\n \"reset_time_seconds\": 30\n}\n```\n\n### GET /health\n\nHealth check endpoint (no authentication required).\n\n#### Request\n\n```http\nGET /health\n```\n\n#### Response\n\n```json\n{\n \"status\": \"healthy\",\n \"service\": \"metrics-collection\"\n}\n```\n\n### GET /\n\nService information endpoint (no authentication required).\n\n#### Request\n\n```http\nGET /\n```\n\n#### Response\n\n```json\n{\n \"service\": \"MCP Metrics Collection Service\",\n \"version\": \"1.0.0\",\n \"status\": \"running\",\n \"endpoints\": {\n \"metrics\": \"/metrics\",\n \"health\": \"/health\",\n \"flush\": \"/flush\",\n \"rate-limit\": \"/rate-limit\",\n \"admin\": {\n \"retention\": \"/admin/retention/*\",\n \"database\": \"/admin/database/*\"\n }\n }\n}\n```\n\n### Administrative Endpoints\n\nAll administrative endpoints require API key authentication and are designed for operational management of the metrics service.\n\n#### GET /admin/retention/preview\n\nPreview data cleanup operations without executing them.\n\n**Parameters:**\n- `table_name` (optional): Specific table to preview\n\n**Response:**\n```json\n{\n \"metrics\": {\n \"retention_days\": 90,\n \"records_to_delete\": 1250,\n \"total_records\": 5000,\n \"oldest_record_to_delete\": \"2024-01-01T00:00:00Z\",\n \"newest_record_to_delete\": \"2024-03-15T23:59:59Z\",\n \"cutoff_date\": \"2024-06-15T00:00:00Z\",\n \"percentage_to_delete\": 25.0\n }\n}\n```\n\n#### POST /admin/retention/cleanup\n\nExecute data cleanup operations with optional dry-run mode.\n\n**Request:**\n```json\n{\n \"table_name\": \"metrics\", // Optional: specific table\n \"dry_run\": true // Optional: default true\n}\n```\n\n**Response:**\n```json\n{\n \"table\": \"metrics\",\n \"status\": \"completed\",\n \"records_deleted\": 1250,\n \"duration_seconds\": 2.34,\n \"retention_days\": 90\n}\n```\n\n#### GET /admin/retention/policies\n\nView current retention policies for all tables.\n\n**Response:**\n```json\n{\n \"metrics\": {\n \"table_name\": \"metrics\",\n \"retention_days\": 90,\n \"is_active\": true,\n \"timestamp_column\": \"created_at\"\n }\n}\n```\n\n#### PUT /admin/retention/policies/{table_name}\n\nUpdate retention policy for a specific table.\n\n**Request:**\n```json\n{\n \"retention_days\": 120,\n \"is_active\": true\n}\n```\n\n**Response:**\n```json\n{\n \"status\": \"success\",\n \"message\": \"Updated retention policy for metrics\",\n \"table_name\": \"metrics\",\n \"retention_days\": 120,\n \"is_active\": true\n}\n```\n\n#### GET /admin/database/stats\n\nGet comprehensive database table statistics.\n\n**Response:**\n```json\n{\n \"metrics\": {\n \"record_count\": 50000,\n \"oldest_record\": \"2024-01-01T00:00:00Z\",\n \"newest_record\": \"2024-06-15T23:59:59Z\",\n \"has_retention_policy\": true,\n \"retention_days\": 90,\n \"policy_active\": true\n }\n}\n```\n\n#### GET /admin/database/size\n\nGet detailed database size and efficiency metrics.\n\n**Response:**\n```json\n{\n \"main_db_bytes\": 104857600,\n \"main_db_mb\": 100.0,\n \"wal_bytes\": 1048576,\n \"wal_mb\": 1.0,\n \"total_bytes\": 105938944,\n \"total_mb\": 101.03,\n \"total_gb\": 0.099,\n \"page_count\": 25600,\n \"page_size\": 4096,\n \"free_pages\": 128,\n \"used_pages\": 25472,\n \"database_efficiency\": 99.5\n}\n```\n\n**📖 For detailed retention management documentation, see [data-retention.md](data-retention.md)**\n\n## Data Models\n\n### Metric Types\n\nThe service supports the following metric types:\n\n#### auth_request\nAuthentication request metrics.\n\n**Dimensions**:\n- `method` (string): Authentication method (\"jwt\", \"oauth\", \"basic\")\n- `success` (boolean): Whether authentication succeeded\n- `server` (string): Server handling the request\n- `user_hash` (string): Hashed user identifier\n\n**Metadata**:\n- `error_code` (string): Error code if authentication failed\n- `request_size` (integer): Request size in bytes\n- `response_size` (integer): Response size in bytes\n\n#### tool_discovery\nTool discovery operation metrics.\n\n**Dimensions**:\n- `query` (string): Search query or pattern\n- `results_count` (integer): Number of results returned\n- `top_k_services` (integer): Number of top services considered\n- `top_n_tools` (integer): Number of top tools returned\n\n**Metadata**:\n- `embedding_time_ms` (number): Time to generate embeddings\n- `faiss_search_time_ms` (number): FAISS search time\n- `cache_hit` (boolean): Whether results came from cache\n\n#### tool_execution\nTool execution event metrics.\n\n**Dimensions**:\n- `tool_name` (string): Name of the executed tool\n- `server_path` (string): Server path or endpoint\n- `server_name` (string): Server identifier\n- `success` (boolean): Whether execution succeeded\n\n**Metadata**:\n- `error_code` (string): Error code if execution failed\n- `input_size_bytes` (integer): Input payload size\n- `output_size_bytes` (integer): Output payload size\n- `tool_version` (string): Tool version if available\n\n### Validation Rules\n\n#### Service Name Validation\n- **Pattern**: `^[a-zA-Z0-9_-]+$`\n- **Length**: 1-100 characters\n- **Examples**: ✅ `auth-server`, `metrics_service`, `tool123`\n- **Invalid**: ❌ `auth server` (space), `auth@server` (special char)\n\n#### Version Validation\n- **Recommended**: Semantic versioning (`x.y.z`)\n- **Examples**: ✅ `1.0.0`, `2.1.0-beta`, `0.1.0-alpha.1`\n- **Warnings**: `v1.0.0`, `latest`, `1.0` (non-semantic)\n\n#### Instance ID Validation\n- **Pattern**: `^[a-zA-Z0-9_.-]+$`\n- **Length**: 1-100 characters\n- **Examples**: ✅ `auth-01`, `server_1`, `pod.123`\n\n#### Dimensions Validation\n- **Max Count**: 20 key-value pairs\n- **Key Pattern**: `^[a-zA-Z_][a-zA-Z0-9_]*$`\n- **Key Length**: 1-50 characters\n- **Value Length**: 0-200 characters\n- **Value Types**: string, number, boolean (converted to string)\n\n#### Metadata Validation\n- **Max Count**: 30 key-value pairs\n- **Key Length**: 1-50 characters\n- **Value Length**: 0-1000 characters\n- **Value Types**: Any JSON-serializable type\n\n#### Timestamp Validation\n- **Format**: ISO 8601 with timezone\n- **Future Limit**: Max 5 minutes in the future\n- **Past Warning**: Warns if older than 7 days\n- **Examples**: ✅ `2024-01-01T12:00:00Z`, `2024-01-01T12:00:00+00:00`\n\n#### Value Validation\n- **Type**: Number (integer or float)\n- **Range**: -1e12 to +1e12\n- **Invalid**: NaN, Infinity, null/undefined\n\n#### Duration Validation\n- **Type**: Number (integer or float)\n- **Range**: 0 to 86400000 milliseconds (24 hours)\n- **Unit**: Milliseconds\n\n## Error Handling\n\n### Error Response Format\n\nAll errors return a consistent JSON format:\n\n```json\n{\n \"detail\": \"Error description\",\n \"status_code\": 400\n}\n```\n\n### Error Codes\n\n#### 400 Bad Request\nInvalid request format or structure.\n\n```json\n{\n \"detail\": \"Invalid JSON in request body\",\n \"status_code\": 400\n}\n```\n\n#### 401 Unauthorized\nMissing or invalid API key.\n\n```json\n{\n \"detail\": \"API key required in X-API-Key header\",\n \"status_code\": 401\n}\n```\n\n```json\n{\n \"detail\": \"Invalid API key\",\n \"status_code\": 401\n}\n```\n\n```json\n{\n \"detail\": \"API key is inactive\",\n \"status_code\": 401\n}\n```\n\n#### 422 Unprocessable Entity\nData validation failed.\n\n```json\n{\n \"detail\": [\n {\n \"type\": \"string_pattern_mismatch\",\n \"loc\": [\"service\"],\n \"msg\": \"String should match pattern '^[a-zA-Z0-9_-]+$'\",\n \"input\": \"invalid service name\"\n }\n ],\n \"status_code\": 422\n}\n```\n\n#### 429 Too Many Requests\nRate limit exceeded.\n\n```json\n{\n \"detail\": \"Rate limit exceeded. Limit: 1000 requests/minute\",\n \"status_code\": 429\n}\n```\n\n#### 500 Internal Server Error\nServer-side processing error.\n\n```json\n{\n \"detail\": \"Internal server error: Database connection failed\",\n \"status_code\": 500\n}\n```\n\n### Validation Errors\n\nWhen data validation fails, detailed error messages are provided:\n\n```json\n{\n \"status\": \"error\",\n \"accepted\": 0,\n \"rejected\": 2,\n \"errors\": [\n \"metrics[0].dimensions.invalid-key: Dimension key must start with letter/underscore\",\n \"metrics[1].value: Metric value is required\"\n ],\n \"request_id\": \"req_error_123\"\n}\n```\n\nError message format: `{field_path}: {error_description}`\n\n## Examples\n\n### Authentication Request Metrics\n\n```bash\ncurl -X POST http://localhost:8890/metrics \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-api-key\" \\\n -d '{\n \"service\": \"auth-server\",\n \"version\": \"1.2.0\",\n \"instance_id\": \"auth-pod-01\",\n \"metrics\": [\n {\n \"type\": \"auth_request\",\n \"value\": 1.0,\n \"duration_ms\": 45.2,\n \"dimensions\": {\n \"method\": \"jwt\",\n \"success\": true,\n \"server\": \"auth-01\",\n \"user_hash\": \"user_abc123\"\n },\n \"metadata\": {\n \"error_code\": null,\n \"request_size\": 1024,\n \"response_size\": 512,\n \"user_agent\": \"Mozilla/5.0...\"\n }\n }\n ]\n }'\n```\n\n### Tool Discovery Metrics\n\n```bash\ncurl -X POST http://localhost:8890/metrics \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-api-key\" \\\n -d '{\n \"service\": \"registry-service\",\n \"version\": \"2.1.0\",\n \"metrics\": [\n {\n \"type\": \"tool_discovery\",\n \"value\": 1.0,\n \"duration_ms\": 125.7,\n \"dimensions\": {\n \"query\": \"file operations\",\n \"results_count\": 15,\n \"top_k_services\": 5,\n \"top_n_tools\": 10\n },\n \"metadata\": {\n \"embedding_time_ms\": 12.3,\n \"faiss_search_time_ms\": 8.9,\n \"cache_hit\": false\n }\n }\n ]\n }'\n```\n\n### Tool Execution Metrics\n\n```bash\ncurl -X POST http://localhost:8890/metrics \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-api-key\" \\\n -d '{\n \"service\": \"mcpgw-server\",\n \"version\": \"1.0.0\",\n \"instance_id\": \"mcpgw-01\",\n \"metrics\": [\n {\n \"type\": \"tool_execution\",\n \"value\": 1.0,\n \"duration_ms\": 1250.5,\n \"dimensions\": {\n \"tool_name\": \"file_reader\",\n \"server_path\": \"/tools/file/read\",\n \"server_name\": \"file-server\",\n \"success\": true\n },\n \"metadata\": {\n \"error_code\": null,\n \"input_size_bytes\": 256,\n \"output_size_bytes\": 1024,\n \"tool_version\": \"1.2.0\"\n }\n }\n ]\n }'\n```\n\n### Batch Metrics Submission\n\n```bash\ncurl -X POST http://localhost:8890/metrics \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-api-key\" \\\n -d '{\n \"service\": \"multi-service\",\n \"version\": \"1.0.0\",\n \"metrics\": [\n {\n \"type\": \"auth_request\",\n \"value\": 1.0,\n \"duration_ms\": 45.2,\n \"dimensions\": {\n \"method\": \"jwt\",\n \"success\": true\n }\n },\n {\n \"type\": \"tool_discovery\",\n \"value\": 1.0,\n \"duration_ms\": 125.7,\n \"dimensions\": {\n \"query\": \"search tools\",\n \"results_count\": 10\n }\n },\n {\n \"type\": \"tool_execution\",\n \"value\": 1.0,\n \"duration_ms\": 890.3,\n \"dimensions\": {\n \"tool_name\": \"calculator\",\n \"success\": true\n }\n }\n ]\n }'\n```\n\n### Error Example\n\nRequest with validation errors:\n\n```bash\ncurl -X POST http://localhost:8890/metrics \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-api-key\" \\\n -d '{\n \"service\": \"invalid service name\",\n \"metrics\": [\n {\n \"type\": \"auth_request\",\n \"value\": null,\n \"dimensions\": {\n \"invalid-key\": \"value\"\n }\n }\n ]\n }'\n```\n\nResponse:\n```json\n{\n \"status\": \"error\",\n \"accepted\": 0,\n \"rejected\": 1,\n \"errors\": [\n \"service: Service name must contain only alphanumeric characters, underscores, and hyphens\",\n \"metrics[0].value: Metric value is required\",\n \"metrics[0].dimensions.invalid-key: Dimension key must start with letter/underscore and contain only alphanumeric/underscore characters\"\n ],\n \"request_id\": \"req_error_abc123\"\n}\n```\n\n### Rate Limit Check\n\n```bash\n# Check rate limit status\ncurl -H \"X-API-Key: your-api-key\" http://localhost:8890/rate-limit\n\n# Response\n{\n \"service\": \"auth-server\",\n \"rate_limit\": 1000,\n \"available_tokens\": 995,\n \"reset_time_seconds\": 45\n}\n```\n\n### Health Check\n\n```bash\ncurl http://localhost:8890/health\n\n# Response\n{\n \"status\": \"healthy\",\n \"service\": \"metrics-collection\"\n}\n```" }, { "path": "metrics-service/docs/data-retention.md", "content": "# Data Retention and Cleanup\n\nThis document provides comprehensive guidance on the data retention and cleanup system for the MCP Metrics Collection Service.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Retention Policies](#retention-policies)\n- [API Reference](#api-reference)\n- [Background Tasks](#background-tasks)\n- [Configuration](#configuration)\n- [Operations Guide](#operations-guide)\n- [Monitoring](#monitoring)\n- [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThe data retention system automatically manages the lifecycle of metrics data by:\n\n- **Automated Cleanup**: Daily background tasks remove old data based on retention policies\n- **Configurable Policies**: Different retention periods for raw vs. aggregated data\n- **Safe Operations**: Dry-run capabilities and atomic transactions\n- **Space Reclamation**: Automatic VACUUM operations after cleanup\n- **Administrative APIs**: Full control over policies and cleanup operations\n\n### Key Benefits\n\n- **Storage Optimization**: Prevents unbounded database growth\n- **Performance Maintenance**: Keeps query performance optimal by managing table sizes\n- **Compliance Support**: Configurable retention periods for data governance requirements\n- **Operational Safety**: Preview and dry-run capabilities before actual cleanup\n\n## Retention Policies\n\n### Default Policies\n\nThe service comes with predefined retention policies optimized for different data types:\n\n```python\n# Raw metrics - shorter retention\nmetrics: 90 days\nauth_metrics: 90 days \ndiscovery_metrics: 90 days\ntool_metrics: 90 days\n\n# Aggregated metrics - longer retention\nmetrics_hourly: 365 days (1 year)\nmetrics_daily: 1095 days (3 years)\n\n# System data\napi_key_usage_log: 90 days\n```\n\n### Policy Configuration\n\nEach retention policy consists of:\n\n| Property | Description | Default |\n|----------|-------------|---------|\n| `table_name` | Target table name | Required |\n| `retention_days` | Days to retain data | Required |\n| `is_active` | Whether policy is enabled | `true` |\n| `timestamp_column` | Column for age calculation | `created_at` |\n| `cleanup_query` | Custom cleanup SQL | Auto-generated |\n\n### Policy Types\n\n#### Standard Policies\nUse automatic cleanup queries based on timestamp columns:\n```sql\nDELETE FROM {table_name} WHERE {timestamp_column} < datetime('now', '-{retention_days} days')\n```\n\n#### Custom Policies\nDefine specific cleanup logic for complex scenarios:\n```python\nRetentionPolicy(\n table_name=\"complex_metrics\",\n retention_days=30,\n cleanup_query=\"DELETE FROM complex_metrics WHERE status = 'processed' AND created_at < datetime('now', '-30 days')\"\n)\n```\n\n## API Reference\n\n### Preview Cleanup Operations\n\nGet a preview of what would be cleaned up without executing the operation.\n\n```http\nGET /admin/retention/preview?table_name={table}\nX-API-Key: your-api-key\n```\n\n**Parameters:**\n- `table_name` (optional): Specific table to preview, or all tables if omitted\n\n**Response:**\n```json\n{\n \"metrics\": {\n \"retention_days\": 90,\n \"records_to_delete\": 1250,\n \"total_records\": 5000,\n \"oldest_record_to_delete\": \"2024-01-01T00:00:00Z\",\n \"newest_record_to_delete\": \"2024-03-15T23:59:59Z\",\n \"cutoff_date\": \"2024-06-15T00:00:00Z\",\n \"percentage_to_delete\": 25.0\n }\n}\n```\n\n### Execute Cleanup\n\nRun data cleanup operations with optional dry-run mode.\n\n```http\nPOST /admin/retention/cleanup\nX-API-Key: your-api-key\nContent-Type: application/json\n\n{\n \"table_name\": \"metrics\", // Optional: specific table\n \"dry_run\": false // Optional: default true\n}\n```\n\n**Response (Single Table):**\n```json\n{\n \"table\": \"metrics\",\n \"status\": \"completed\",\n \"records_deleted\": 1250,\n \"duration_seconds\": 2.34,\n \"retention_days\": 90\n}\n```\n\n**Response (All Tables):**\n```json\n{\n \"operation\": \"cleanup\",\n \"total_records_processed\": 3500,\n \"tables_processed\": 5,\n \"duration_seconds\": 8.92,\n \"started_at\": \"2024-01-15T10:00:00Z\",\n \"completed_at\": \"2024-01-15T10:00:08Z\",\n \"table_results\": {\n \"metrics\": {\n \"status\": \"completed\",\n \"records_deleted\": 1250\n },\n \"auth_metrics\": {\n \"status\": \"completed\", \n \"records_deleted\": 2250\n }\n }\n}\n```\n\n### Manage Retention Policies\n\n#### View Current Policies\n\n```http\nGET /admin/retention/policies\nX-API-Key: your-api-key\n```\n\n**Response:**\n```json\n{\n \"metrics\": {\n \"table_name\": \"metrics\",\n \"retention_days\": 90,\n \"is_active\": true,\n \"timestamp_column\": \"created_at\"\n },\n \"metrics_hourly\": {\n \"table_name\": \"metrics_hourly\", \n \"retention_days\": 365,\n \"is_active\": true,\n \"timestamp_column\": \"created_at\"\n }\n}\n```\n\n#### Update Policy\n\n```http\nPUT /admin/retention/policies/metrics\nX-API-Key: your-api-key\nContent-Type: application/json\n\n{\n \"retention_days\": 120,\n \"is_active\": true\n}\n```\n\n**Response:**\n```json\n{\n \"status\": \"success\",\n \"message\": \"Updated retention policy for metrics\",\n \"table_name\": \"metrics\",\n \"retention_days\": 120,\n \"is_active\": true\n}\n```\n\n### Database Statistics\n\n#### Table Statistics\n\nGet detailed statistics for all tables:\n\n```http\nGET /admin/database/stats \nX-API-Key: your-api-key\n```\n\n**Response:**\n```json\n{\n \"metrics\": {\n \"record_count\": 50000,\n \"oldest_record\": \"2024-01-01T00:00:00Z\",\n \"newest_record\": \"2024-06-15T23:59:59Z\", \n \"has_retention_policy\": true,\n \"retention_days\": 90,\n \"policy_active\": true\n },\n \"auth_metrics\": {\n \"record_count\": 25000,\n \"oldest_record\": \"2024-02-01T00:00:00Z\",\n \"newest_record\": \"2024-06-15T23:59:59Z\",\n \"has_retention_policy\": true,\n \"retention_days\": 90,\n \"policy_active\": true\n }\n}\n```\n\n#### Database Size Information\n\nGet comprehensive database size metrics:\n\n```http\nGET /admin/database/size\nX-API-Key: your-api-key\n```\n\n**Response:**\n```json\n{\n \"main_db_bytes\": 104857600,\n \"main_db_mb\": 100.0,\n \"wal_bytes\": 1048576,\n \"wal_mb\": 1.0,\n \"shm_bytes\": 32768,\n \"shm_mb\": 0.03,\n \"total_bytes\": 105938944,\n \"total_mb\": 101.03,\n \"total_gb\": 0.099,\n \"page_count\": 25600,\n \"page_size\": 4096,\n \"free_pages\": 128,\n \"used_pages\": 25472,\n \"database_efficiency\": 99.5\n}\n```\n\n## Background Tasks\n\n### Automatic Cleanup Task\n\nThe service runs a daily background task for automatic data cleanup:\n\n```python\nasync def retention_cleanup_task():\n \"\"\"Background task to run data retention cleanup.\"\"\"\n while True:\n try:\n await asyncio.sleep(86400) # Run once per day (24 hours)\n logger.info(\"Starting scheduled data retention cleanup...\")\n result = await retention_manager.cleanup_all_tables(dry_run=False)\n \n total_deleted = result.get('total_records_processed', 0)\n duration = result.get('duration_seconds', 0)\n \n if total_deleted > 0:\n logger.info(f\"Retention cleanup completed: {total_deleted} records deleted in {duration:.2f}s\")\n else:\n logger.info(\"Retention cleanup completed: no records to delete\")\n \n except Exception as e:\n logger.error(f\"Error in retention cleanup task: {e}\")\n await asyncio.sleep(3600) # Wait an hour before retry\n```\n\n### Task Characteristics\n\n- **Frequency**: Every 24 hours\n- **Execution**: Non-blocking background operation\n- **Error Handling**: Automatic retry with exponential backoff\n- **Logging**: Comprehensive operation logging\n- **Safety**: Uses configured retention policies only\n\n### Manual Task Control\n\nStart manual cleanup outside of scheduled runs:\n\n```bash\n# Using API\ncurl -X POST http://localhost:8890/admin/retention/cleanup \\\n -H \"X-API-Key: your-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": false}'\n\n# Using Python directly\nuv run python -c \"\nimport asyncio\nfrom app.core.retention import retention_manager\n\nasync def main():\n result = await retention_manager.cleanup_all_tables(dry_run=False)\n print(f'Cleaned up {result[\\\"total_records_processed\\\"]} records')\n\nasyncio.run(main())\n\"\n```\n\n## Configuration\n\n### Environment Variables\n\nConfigure retention behavior through environment variables:\n\n```bash\n# Default retention period (days)\nMETRICS_RETENTION_DAYS=90\n\n# Background task frequency (seconds)\nRETENTION_CLEANUP_INTERVAL=86400\n\n# Enable/disable automatic cleanup\nRETENTION_CLEANUP_ENABLED=true\n\n# Database vacuum after cleanup\nRETENTION_VACUUM_ENABLED=true\n```\n\n### Database Configuration\n\nRetention policies are stored in the `retention_policies` table:\n\n```sql\nCREATE TABLE retention_policies (\n table_name TEXT PRIMARY KEY,\n retention_days INTEGER NOT NULL,\n is_active BOOLEAN DEFAULT 1,\n cleanup_query TEXT,\n timestamp_column TEXT DEFAULT 'created_at',\n created_at TEXT DEFAULT CURRENT_TIMESTAMP,\n updated_at TEXT DEFAULT CURRENT_TIMESTAMP\n);\n```\n\n### Policy Management\n\n#### Add New Policy\n\n```python\nfrom app.core.retention import retention_manager\n\nawait retention_manager.update_policy(\n table_name=\"custom_metrics\",\n retention_days=60,\n is_active=True\n)\n```\n\n#### Disable Policy\n\n```python\nawait retention_manager.update_policy(\n table_name=\"important_metrics\", \n retention_days=365,\n is_active=False # Disable cleanup\n)\n```\n\n## Operations Guide\n\n### Daily Operations\n\n#### Morning Check\nReview overnight cleanup results:\n\n```bash\n# Check recent cleanup logs\ndocker logs metrics-service | grep \"retention cleanup\"\n\n# Get current database size\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/database/size\n```\n\n#### Weekly Review\nAnalyze retention effectiveness:\n\n```bash\n# Get table statistics\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/database/stats\n\n# Preview next cleanup\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/retention/preview\n```\n\n### Emergency Procedures\n\n#### Immediate Space Reclamation\n\nWhen database size becomes critical:\n\n```bash\n# 1. Emergency cleanup (shorter retention)\ncurl -X PUT http://localhost:8890/admin/retention/policies/metrics \\\n -H \"X-API-Key: $API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"retention_days\": 30, \"is_active\": true}'\n\n# 2. Execute immediate cleanup\ncurl -X POST http://localhost:8890/admin/retention/cleanup \\\n -H \"X-API-Key: $API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": false}'\n\n# 3. Manual VACUUM for maximum space reclamation\nuv run python -c \"\nimport asyncio\nimport aiosqlite\nfrom app.config import settings\n\nasync def vacuum():\n async with aiosqlite.connect(settings.SQLITE_DB_PATH) as db:\n await db.execute('VACUUM')\n print('VACUUM completed')\n\nasyncio.run(vacuum())\n\"\n```\n\n#### Disable All Cleanup\n\nIn case of data issues:\n\n```bash\n# Disable all policies\nfor table in metrics auth_metrics discovery_metrics tool_metrics; do\n curl -X PUT http://localhost:8890/admin/retention/policies/$table \\\n -H \"X-API-Key: $API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"retention_days\": 999, \"is_active\": false}'\ndone\n```\n\n### Maintenance Windows\n\n#### Pre-Maintenance\n```bash\n# 1. Preview cleanup scope\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/retention/preview\n\n# 2. Backup critical data if needed\nsqlite3 /var/lib/sqlite/metrics.db \".backup /backup/metrics_$(date +%Y%m%d).db\"\n\n# 3. Execute cleanup\ncurl -X POST http://localhost:8890/admin/retention/cleanup \\\n -H \"X-API-Key: $API_KEY\" \\\n -d '{\"dry_run\": false}'\n```\n\n#### Post-Maintenance\n```bash\n# 1. Verify cleanup results\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/database/stats\n\n# 2. Check database integrity\nuv run python -c \"\nimport asyncio\nimport aiosqlite\nfrom app.config import settings\n\nasync def check():\n async with aiosqlite.connect(settings.SQLITE_DB_PATH) as db:\n result = await db.execute('PRAGMA integrity_check')\n print(await result.fetchone())\n\nasyncio.run(check())\n\"\n```\n\n## Monitoring\n\n### Key Metrics to Monitor\n\n#### Database Size Trends\n```bash\n# Daily size tracking\ncurl -s -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/database/size | \\\n jq '{date: now | todateiso8601, size_mb: .total_mb, efficiency: .database_efficiency}'\n```\n\n#### Cleanup Effectiveness\n```bash\n# Records deleted per cleanup\ngrep \"retention cleanup completed\" /var/log/metrics-service.log | \\\n tail -7 | sed 's/.*: \\([0-9]*\\) records.*/\\1/'\n```\n\n#### Policy Compliance\n```bash\n# Tables exceeding retention period\ncurl -s -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/retention/preview | \\\n jq 'to_entries[] | select(.value.records_to_delete > 0) | {table: .key, overdue: .value.records_to_delete}'\n```\n\n### Alerting Rules\n\n#### Prometheus Alerts\n\n```yaml\n# Database size growth\n- alert: DatabaseSizeGrowth\n expr: increase(database_size_bytes[24h]) > 100MB\n labels:\n severity: warning\n annotations:\n summary: \"Database growing faster than expected\"\n\n# Cleanup failures \n- alert: RetentionCleanupFailed\n expr: increase(retention_cleanup_errors_total[24h]) > 0\n labels:\n severity: critical\n annotations:\n summary: \"Data retention cleanup failing\"\n\n# Large cleanup operations\n- alert: LargeCleanupOperation\n expr: retention_records_deleted > 100000\n labels:\n severity: info\n annotations:\n summary: \"Large cleanup operation detected\"\n```\n\n#### Log-Based Alerts\n\n```bash\n# Setup log monitoring for cleanup failures\ntail -f /var/log/metrics-service.log | grep -E \"(ERROR|CRITICAL).*retention\" | \\\n while read line; do\n echo \"ALERT: Retention system error - $line\"\n # Send notification\n done\n```\n\n### Performance Impact\n\n#### Cleanup Operation Metrics\n- **Duration**: Typical cleanup takes 1-10 seconds per 10K records\n- **I/O Impact**: Moderate during cleanup, high during VACUUM\n- **CPU Usage**: Low-moderate during operation\n- **Memory Usage**: Minimal additional memory required\n\n#### Optimization Tips\n- **Schedule During Low Traffic**: Run cleanup during off-peak hours\n- **Batch Size Tuning**: Adjust retention periods to avoid massive single cleanups \n- **Index Maintenance**: Ensure timestamp columns are indexed\n- **WAL Mode**: Use WAL mode for concurrent operations during cleanup\n\n## Troubleshooting\n\n### Common Issues\n\n#### Cleanup Not Running\n\n**Symptoms:**\n- Database size keeps growing\n- No cleanup logs in recent history\n- Old data still present\n\n**Diagnosis:**\n```bash\n# Check if policies are active\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/retention/policies | \\\n jq '.[] | select(.is_active == false)'\n\n# Check background task status\ndocker logs metrics-service | grep -E \"(retention|cleanup)\" | tail -10\n\n# Manual cleanup test\ncurl -X POST http://localhost:8890/admin/retention/cleanup \\\n -H \"X-API-Key: $API_KEY\" \\\n -d '{\"dry_run\": true}'\n```\n\n**Solutions:**\n- Enable inactive policies\n- Restart service if background task stopped\n- Check for blocking database locks\n\n#### Cleanup Errors\n\n**Symptoms:**\n- Error logs during cleanup operations\n- Partial cleanup results\n- Database integrity issues\n\n**Diagnosis:**\n```bash\n# Check recent errors\ngrep -E \"(ERROR|exception).*retention\" /var/log/metrics-service.log | tail -5\n\n# Test database connectivity\nuv run python -c \"\nimport asyncio\nimport aiosqlite\nfrom app.config import settings\n\nasync def test():\n try:\n async with aiosqlite.connect(settings.SQLITE_DB_PATH) as db:\n await db.execute('SELECT 1')\n print('Database connection OK')\n except Exception as e:\n print(f'Database error: {e}')\n\nasyncio.run(test())\n\"\n\n# Check database integrity\nsqlite3 /var/lib/sqlite/metrics.db \"PRAGMA integrity_check\"\n```\n\n**Solutions:**\n- Fix database permissions\n- Resolve disk space issues\n- Repair database corruption if found\n\n#### Performance Issues\n\n**Symptoms:**\n- Slow cleanup operations\n- High CPU/I/O during cleanup\n- Service timeouts\n\n**Diagnosis:**\n```bash\n# Check table sizes\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/database/stats | \\\n jq 'to_entries[] | {table: .key, records: .value.record_count}' | \\\n sort -k2 -nr\n\n# Monitor cleanup duration\ncurl -X POST http://localhost:8890/admin/retention/cleanup \\\n -H \"X-API-Key: $API_KEY\" \\\n -d '{\"table_name\": \"metrics\", \"dry_run\": true}' | \\\n jq '.duration_seconds'\n```\n\n**Solutions:**\n- Add indexes on timestamp columns\n- Implement incremental cleanup\n- Adjust retention periods to reduce batch sizes\n\n### Recovery Procedures\n\n#### Restore from Backup\n\nIf cleanup removes needed data:\n\n```bash\n# 1. Stop service\ndocker stop metrics-service\n\n# 2. Restore database\ncp /backup/metrics_YYYYMMDD.db /var/lib/sqlite/metrics.db\n\n# 3. Adjust retention policies before restart\nsqlite3 /var/lib/sqlite/metrics.db \"\nUPDATE retention_policies \nSET retention_days = retention_days * 2\nWHERE table_name IN ('metrics', 'auth_metrics');\n\"\n\n# 4. Restart service\ndocker start metrics-service\n```\n\n#### Reset Retention System\n\nTo completely reset retention configuration:\n\n```bash\n# 1. Clear all policies\nsqlite3 /var/lib/sqlite/metrics.db \"DELETE FROM retention_policies;\"\n\n# 2. Restart service (will reload defaults)\ndocker restart metrics-service\n\n# 3. Verify default policies loaded\ncurl -H \"X-API-Key: $API_KEY\" http://localhost:8890/admin/retention/policies\n```\n\n### Debug Mode\n\nEnable detailed retention logging:\n\n```bash\n# Add to environment\nexport RETENTION_DEBUG=true\nexport LOG_LEVEL=DEBUG\n\n# Restart service\ndocker restart metrics-service\n\n# Monitor detailed logs\ndocker logs -f metrics-service | grep retention\n```\n\nThis comprehensive documentation provides all the information needed to effectively manage the data retention system in production environments." }, { "path": "metrics-service/docs/database-schema.md", "content": "# Database Schema Documentation\n\nThis document provides comprehensive documentation of the database schema, migration system, and data management for the MCP Metrics Collection Service.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Schema Architecture](#schema-architecture)\n- [Table Definitions](#table-definitions)\n- [Migration System](#migration-system)\n- [Data Retention](#data-retention)\n- [Performance Considerations](#performance-considerations)\n- [Backup and Recovery](#backup-and-recovery)\n\n## Overview\n\nThe metrics service uses SQLite as its primary data store with a carefully designed schema optimized for:\n\n- **High-volume writes**: Optimized for metric ingestion\n- **Time-series data**: Efficient timestamp-based queries\n- **Aggregation support**: Pre-computed summaries for performance\n- **Data retention**: Automatic cleanup of old data\n- **Schema evolution**: Version-controlled migrations\n\n### Design Principles\n\n1. **Write Optimization**: Tables designed for fast inserts\n2. **Query Performance**: Strategic indexing for common queries\n3. **Data Integrity**: Foreign key constraints and validation\n4. **Storage Efficiency**: Normalized structure with JSON for flexible data\n5. **Horizontal Scaling**: Partitionable by time and service\n\n## Schema Architecture\n\n### Entity Relationship Diagram\n\n```\n┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n│ api_keys │ │ metrics │ │ schema_migrations│\n│ │ │ │ │ │\n│ • id (PK) │ │ • id (PK) │ │ • version (PK) │\n│ • key_hash │────▶│ • request_id │ │ • name │\n│ • service_name │ │ • service │ │ • applied_at │\n│ • rate_limit │ │ • metric_type │ └─────────────────┘\n│ • usage_count │ │ • timestamp │ \n│ • created_at │ │ • value │ ┌─────────────────┐\n└─────────────────┘ │ • duration_ms │ │retention_policies│\n │ • dimensions │ │ │\n┌─────────────────┐ │ • metadata │ │ • id (PK) │\n│ api_key_usage │ └─────────────────┘ │ • table_name │\n│ │ │ │ • retention_days│\n│ • id (PK) │ │ │ • is_active │\n│ • key_hash │──────────────┘ └─────────────────┘\n│ • timestamp │ │\n│ • endpoint │ │\n│ • request_count │ ▼\n│ • status_code │ ┌─────────────────┐\n└─────────────────┘ │ Specialized │\n │ Metric Tables │\n┌─────────────────┐ │ │\n│ metrics_hourly │ │ • auth_metrics │\n│ │ │ • discovery_ │\n│ • id (PK) │◀────│ metrics │\n│ • service │ │ • tool_metrics │\n│ • metric_type │ └─────────────────┘\n│ • hour_timestamp│\n│ • count │ ┌─────────────────┐\n│ • sum_value │ │ metrics_daily │\n│ • avg_value │ │ │\n│ • min_value │ │ • id (PK) │\n│ • max_value │ │ • service │\n└─────────────────┘ │ • metric_type │\n │ • date │\n │ • count │\n │ • aggregates... │\n └─────────────────┘\n```\n\n## Table Definitions\n\n### Core Tables\n\n#### api_keys\nStores API key information and configuration.\n\n```sql\nCREATE TABLE api_keys (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n key_hash TEXT UNIQUE NOT NULL, -- SHA256 hash of API key\n service_name TEXT NOT NULL, -- Associated service name\n created_at TEXT NOT NULL, -- ISO timestamp\n last_used_at TEXT, -- Last request timestamp\n is_active BOOLEAN DEFAULT 1, -- Key status\n rate_limit INTEGER DEFAULT 1000, -- Requests per minute\n usage_count INTEGER DEFAULT 0, -- Total requests made\n daily_usage_limit INTEGER DEFAULT NULL, -- Optional daily limit\n monthly_usage_limit INTEGER DEFAULT NULL,-- Optional monthly limit\n description TEXT DEFAULT NULL -- Optional description\n);\n\n-- Indexes\nCREATE INDEX idx_api_keys_hash ON api_keys(key_hash);\nCREATE INDEX idx_api_keys_service ON api_keys(service_name);\n```\n\n**Sample Data**:\n```sql\nINSERT INTO api_keys VALUES (\n 1,\n 'a1b2c3d4e5f6...', \n 'auth-server',\n '2024-01-01T00:00:00Z',\n '2024-01-01T12:30:15Z',\n 1,\n 1000,\n 15842,\n NULL,\n NULL,\n 'Production auth server API key'\n);\n```\n\n#### metrics\nPrimary table for all metrics data.\n\n```sql\nCREATE TABLE metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL, -- Request correlation ID\n service TEXT NOT NULL, -- Source service\n service_version TEXT, -- Service version\n instance_id TEXT, -- Service instance ID\n metric_type TEXT NOT NULL, -- Type of metric\n timestamp TEXT NOT NULL, -- Metric timestamp (ISO)\n value REAL NOT NULL, -- Metric value\n duration_ms REAL, -- Optional duration\n dimensions TEXT, -- JSON key-value pairs\n metadata TEXT, -- JSON additional data\n created_at TEXT DEFAULT (datetime('now')) -- Row creation time\n);\n\n-- Indexes\nCREATE INDEX idx_metrics_timestamp ON metrics(timestamp);\nCREATE INDEX idx_metrics_service_type ON metrics(service, metric_type);\nCREATE INDEX idx_metrics_type_timestamp ON metrics(metric_type, timestamp);\n```\n\n**Sample Data**:\n```sql\nINSERT INTO metrics VALUES (\n 1,\n 'req_abc123',\n 'auth-server',\n '1.2.0',\n 'auth-pod-01',\n 'auth_request',\n '2024-01-01T12:30:15.123Z',\n 1.0,\n 45.2,\n '{\"method\":\"jwt\",\"success\":true,\"server\":\"auth-01\"}',\n '{\"error_code\":null,\"request_size\":1024}',\n '2024-01-01T12:30:15.500Z'\n);\n```\n\n### Specialized Metric Tables\n\n#### auth_metrics\nAuthentication-specific metrics with optimized schema.\n\n```sql\nCREATE TABLE auth_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n success BOOLEAN, -- Authentication result\n method TEXT, -- Auth method (jwt, oauth, etc)\n server TEXT, -- Handling server\n user_hash TEXT, -- Hashed user identifier\n error_code TEXT, -- Error code if failed\n created_at TEXT DEFAULT (datetime('now'))\n);\n\n-- Indexes\nCREATE INDEX idx_auth_timestamp ON auth_metrics(timestamp);\nCREATE INDEX idx_auth_success ON auth_metrics(success, timestamp);\nCREATE INDEX idx_auth_user ON auth_metrics(user_hash, timestamp);\n```\n\n#### discovery_metrics\nTool discovery operation metrics.\n\n```sql\nCREATE TABLE discovery_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n query TEXT, -- Search query\n results_count INTEGER, -- Number of results\n top_k_services INTEGER, -- Services considered\n top_n_tools INTEGER, -- Tools returned\n embedding_time_ms REAL, -- Vector generation time\n faiss_search_time_ms REAL, -- Search engine time\n created_at TEXT DEFAULT (datetime('now'))\n);\n\n-- Indexes\nCREATE INDEX idx_discovery_timestamp ON discovery_metrics(timestamp);\nCREATE INDEX idx_discovery_results ON discovery_metrics(results_count, timestamp);\n```\n\n#### tool_metrics\nTool execution metrics.\n\n```sql\nCREATE TABLE tool_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n request_id TEXT NOT NULL,\n timestamp TEXT NOT NULL,\n service TEXT NOT NULL,\n duration_ms REAL,\n tool_name TEXT, -- Executed tool name\n server_path TEXT, -- Server endpoint\n server_name TEXT, -- Server identifier\n success BOOLEAN, -- Execution result\n error_code TEXT, -- Error code if failed\n input_size_bytes INTEGER, -- Input payload size\n output_size_bytes INTEGER, -- Output payload size\n created_at TEXT DEFAULT (datetime('now'))\n);\n\n-- Indexes\nCREATE INDEX idx_tool_timestamp ON tool_metrics(timestamp);\nCREATE INDEX idx_tool_name ON tool_metrics(tool_name, timestamp);\nCREATE INDEX idx_tool_success ON tool_metrics(success, timestamp);\n```\n\n### Aggregation Tables\n\n#### metrics_hourly\nPre-computed hourly aggregates for performance.\n\n```sql\nCREATE TABLE metrics_hourly (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n service TEXT NOT NULL,\n metric_type TEXT NOT NULL,\n hour_timestamp TEXT NOT NULL, -- Truncated to hour\n count INTEGER DEFAULT 0, -- Number of metrics\n sum_value REAL DEFAULT 0.0, -- Sum of values\n avg_value REAL DEFAULT 0.0, -- Average value\n min_value REAL, -- Minimum value\n max_value REAL, -- Maximum value\n sum_duration_ms REAL DEFAULT 0.0, -- Sum of durations\n avg_duration_ms REAL DEFAULT 0.0, -- Average duration\n created_at TEXT DEFAULT (datetime('now')),\n updated_at TEXT DEFAULT (datetime('now')),\n UNIQUE(service, metric_type, hour_timestamp)\n);\n\n-- Indexes\nCREATE INDEX idx_hourly_service_type_hour ON metrics_hourly(service, metric_type, hour_timestamp);\nCREATE INDEX idx_hourly_hour ON metrics_hourly(hour_timestamp);\n```\n\n#### metrics_daily\nPre-computed daily aggregates for long-term analysis.\n\n```sql\nCREATE TABLE metrics_daily (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n service TEXT NOT NULL,\n metric_type TEXT NOT NULL,\n date TEXT NOT NULL, -- YYYY-MM-DD format\n count INTEGER DEFAULT 0,\n sum_value REAL DEFAULT 0.0,\n avg_value REAL DEFAULT 0.0,\n min_value REAL,\n max_value REAL,\n sum_duration_ms REAL DEFAULT 0.0,\n avg_duration_ms REAL DEFAULT 0.0,\n created_at TEXT DEFAULT (datetime('now')),\n updated_at TEXT DEFAULT (datetime('now')),\n UNIQUE(service, metric_type, date)\n);\n\n-- Indexes\nCREATE INDEX idx_daily_service_type_date ON metrics_daily(service, metric_type, date);\nCREATE INDEX idx_daily_date ON metrics_daily(date);\n```\n\n### System Tables\n\n#### schema_migrations\nTracks applied database migrations.\n\n```sql\nCREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY, -- Migration version number\n name TEXT NOT NULL, -- Migration name\n applied_at TEXT NOT NULL -- Application timestamp\n);\n```\n\n#### retention_policies\nConfigures data retention for different tables.\n\n```sql\nCREATE TABLE retention_policies (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n table_name TEXT NOT NULL, -- Target table\n retention_days INTEGER NOT NULL, -- Retention period\n is_active BOOLEAN DEFAULT 1, -- Policy status\n created_at TEXT DEFAULT (datetime('now')),\n updated_at TEXT DEFAULT (datetime('now')),\n UNIQUE(table_name)\n);\n\n-- Default policies\nINSERT INTO retention_policies (table_name, retention_days) VALUES \n ('metrics', 90), -- Raw metrics: 90 days\n ('auth_metrics', 90), -- Auth metrics: 90 days \n ('discovery_metrics', 90), -- Discovery metrics: 90 days\n ('tool_metrics', 90), -- Tool metrics: 90 days\n ('metrics_hourly', 365), -- Hourly aggregates: 1 year\n ('metrics_daily', 1095); -- Daily aggregates: 3 years\n```\n\n#### api_key_usage_log\nDetailed API key usage tracking.\n\n```sql\nCREATE TABLE api_key_usage_log (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n key_hash TEXT NOT NULL, -- API key hash\n service_name TEXT NOT NULL, -- Service making request\n timestamp TEXT NOT NULL, -- Request timestamp\n endpoint TEXT NOT NULL, -- API endpoint called\n request_count INTEGER DEFAULT 1, -- Number of requests\n bytes_processed INTEGER DEFAULT 0, -- Data processed\n duration_ms REAL DEFAULT 0, -- Request duration\n status_code INTEGER DEFAULT 200, -- HTTP status code\n FOREIGN KEY (key_hash) REFERENCES api_keys(key_hash)\n);\n\n-- Indexes\nCREATE INDEX idx_usage_key_timestamp ON api_key_usage_log(key_hash, timestamp);\nCREATE INDEX idx_usage_timestamp ON api_key_usage_log(timestamp);\nCREATE INDEX idx_usage_endpoint ON api_key_usage_log(endpoint, timestamp);\n```\n\n## Migration System\n\n### Migration Architecture\n\nThe migration system provides:\n- **Version Control**: Sequential migration numbering\n- **Rollback Support**: Down migrations for reverting changes\n- **Transaction Safety**: Atomic migration application\n- **Python Integration**: Support for data migrations alongside DDL\n\n### Migration CLI\n\n```bash\n# Check migration status\npython migrate.py status\n\n# Apply all pending migrations\npython migrate.py up\n\n# Apply up to specific version\npython migrate.py up --to 3\n\n# Rollback to specific version\npython migrate.py down 2\n\n# List all available migrations\npython migrate.py list\n\n# Create new migration template\npython migrate.py create \"add_user_preferences\"\n```\n\n### Migration Versions\n\n#### Migration 0001: Initial Schema\n- Creates all core tables\n- Establishes indexes\n- Sets up initial constraints\n\n#### Migration 0002: Aggregation Tables\n- Adds `metrics_hourly` table\n- Adds `metrics_daily` table\n- Creates aggregation indexes\n\n#### Migration 0003: Retention Policies\n- Creates `retention_policies` table\n- Inserts default retention settings\n- Enables automated cleanup\n\n#### Migration 0004: API Key Usage Tracking\n- Extends `api_keys` table with usage fields\n- Creates `api_key_usage_log` table\n- Adds usage tracking indexes\n\n### Migration Example\n\n```python\n# Example migration structure\nfrom app.storage.migrations import Migration\n\nmigration = Migration(\n version=5,\n name=\"add_metric_labels\",\n up_sql=\"\"\"\n -- Add labels column to metrics table\n ALTER TABLE metrics ADD COLUMN labels TEXT;\n \n -- Create index on labels\n CREATE INDEX idx_metrics_labels ON metrics(labels);\n \n -- Update existing metrics with empty labels\n UPDATE metrics SET labels = '{}' WHERE labels IS NULL;\n \"\"\",\n down_sql=\"\"\"\n -- Remove labels functionality\n DROP INDEX idx_metrics_labels;\n \n -- Note: Cannot drop column in SQLite easily\n -- Would require table recreation in production\n \"\"\",\n python_up=async_migrate_labels, # Optional Python function\n python_down=async_rollback_labels # Optional Python rollback\n)\n```\n\n## Data Retention\n\n### Retention Strategy\n\nThe service implements a multi-tiered retention strategy:\n\n1. **Raw Data**: 90 days for detailed analysis\n2. **Hourly Aggregates**: 365 days for trend analysis \n3. **Daily Aggregates**: 3 years for historical reporting\n4. **Audit Logs**: 90 days for compliance\n\n### Automated Cleanup\n\n```sql\n-- Example cleanup procedures (run via cron)\n\n-- Clean old raw metrics\nDELETE FROM metrics \nWHERE created_at < datetime('now', '-90 days');\n\n-- Clean old hourly aggregates\nDELETE FROM metrics_hourly \nWHERE hour_timestamp < datetime('now', '-365 days');\n\n-- Clean old daily aggregates\nDELETE FROM metrics_daily \nWHERE date < date('now', '-1095 days');\n\n-- Clean old API usage logs\nDELETE FROM api_key_usage_log \nWHERE timestamp < datetime('now', '-90 days');\n```\n\n### Retention Policy Management\n\n```python\n# Python API for managing retention\nfrom app.storage.database import MetricsStorage\n\nstorage = MetricsStorage()\n\n# Update retention policy\nawait storage.update_retention_policy('metrics', 120) # 120 days\n\n# Get all policies\npolicies = await storage.get_retention_policies()\n\n# Apply cleanup based on policies\nawait storage.apply_retention_cleanup()\n```\n\n## Performance Considerations\n\n### Query Optimization\n\n#### Common Query Patterns\n\n```sql\n-- Time-range queries (most common)\nSELECT * FROM metrics \nWHERE timestamp BETWEEN ? AND ?\n AND service = ?;\n\n-- Aggregation queries\nSELECT service, metric_type, COUNT(*), AVG(value)\nFROM metrics \nWHERE timestamp > datetime('now', '-1 hour')\nGROUP BY service, metric_type;\n\n-- Recent metrics by type\nSELECT * FROM auth_metrics\nWHERE timestamp > datetime('now', '-5 minutes')\n AND success = 1\nORDER BY timestamp DESC\nLIMIT 100;\n```\n\n#### Index Strategy\n\n```sql\n-- Primary indexes for time-series queries\nCREATE INDEX idx_metrics_timestamp ON metrics(timestamp);\nCREATE INDEX idx_metrics_service_timestamp ON metrics(service, timestamp);\nCREATE INDEX idx_metrics_type_timestamp ON metrics(metric_type, timestamp);\n\n-- Composite indexes for common filters\nCREATE INDEX idx_auth_success_timestamp ON auth_metrics(success, timestamp);\nCREATE INDEX idx_tool_name_timestamp ON tool_metrics(tool_name, timestamp);\n\n-- Covering indexes for aggregations\nCREATE INDEX idx_metrics_service_type_time_value ON metrics(service, metric_type, timestamp, value);\n```\n\n### SQLite Optimizations\n\n#### PRAGMA Settings\n\n```sql\n-- WAL mode for better concurrency\nPRAGMA journal_mode = WAL;\n\n-- Optimize for write performance\nPRAGMA synchronous = NORMAL;\n\n-- Large cache for read performance\nPRAGMA cache_size = 10000;\n\n-- Memory temp store\nPRAGMA temp_store = MEMORY;\n\n-- Auto-vacuum for space management\nPRAGMA auto_vacuum = INCREMENTAL;\n```\n\n#### Connection Pool Settings\n\n```python\n# Connection configuration\nSQLITE_CONFIG = {\n 'database': '/var/lib/sqlite/metrics.db',\n 'timeout': 30.0,\n 'isolation_level': None, # Autocommit mode\n 'check_same_thread': False,\n 'factory': sqlite3.Row, # Row factory for dict-like access\n}\n\n# Connection pool\nconnection_pool = aiosqlite.connect(**SQLITE_CONFIG)\n```\n\n### Write Performance\n\n#### Batch Processing\n\n```python\n# Efficient batch inserts\nasync def batch_insert_metrics(metrics_batch):\n async with aiosqlite.connect(db_path) as db:\n await db.execute('BEGIN IMMEDIATE')\n try:\n await db.executemany(\n 'INSERT INTO metrics (...) VALUES (...)',\n metrics_batch\n )\n await db.commit()\n except Exception:\n await db.rollback()\n raise\n```\n\n#### Prepared Statements\n\n```python\n# Reuse prepared statements\nINSERT_METRIC = \"\"\"\n INSERT INTO metrics (\n request_id, service, metric_type, timestamp, \n value, duration_ms, dimensions, metadata\n ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)\n\"\"\"\n\nasync def insert_metrics(db, metrics):\n await db.executemany(INSERT_METRIC, metrics)\n```\n\n### Read Performance\n\n#### Aggregation Queries\n\n```sql\n-- Use pre-computed aggregates when possible\nSELECT sum_value, avg_value, count\nFROM metrics_hourly\nWHERE service = 'auth-server'\n AND metric_type = 'auth_request'\n AND hour_timestamp >= '2024-01-01T00:00:00Z';\n\n-- Fallback to raw data for recent metrics\nSELECT SUM(value), AVG(value), COUNT(*)\nFROM metrics\nWHERE service = 'auth-server'\n AND metric_type = 'auth_request'\n AND timestamp >= '2024-01-01T23:00:00Z';\n```\n\n#### Query Plan Analysis\n\n```sql\n-- Analyze query performance\nEXPLAIN QUERY PLAN \nSELECT COUNT(*) FROM metrics \nWHERE timestamp > '2024-01-01T00:00:00Z' \n AND service = 'auth-server';\n\n-- Expected plan should use index\n-- SEARCH TABLE metrics USING INDEX idx_metrics_service_timestamp\n```\n\n## Backup and Recovery\n\n### Backup Strategy\n\n#### Hot Backup (Online)\n\n```bash\n#!/bin/bash\n# hot-backup.sh - SQLite online backup\n\nDB_PATH=\"/var/lib/sqlite/metrics.db\"\nBACKUP_PATH=\"/backups/metrics/$(date +%Y%m%d_%H%M%S).db\"\n\n# Use SQLite's online backup API\nsqlite3 \"$DB_PATH\" \".backup $BACKUP_PATH\"\n\n# Verify backup integrity\nif sqlite3 \"$BACKUP_PATH\" \"PRAGMA integrity_check;\" | grep -q \"ok\"; then\n echo \"Backup completed successfully: $BACKUP_PATH\"\n gzip \"$BACKUP_PATH\"\nelse\n echo \"Backup verification failed!\"\n rm \"$BACKUP_PATH\"\n exit 1\nfi\n```\n\n#### Cold Backup (Offline)\n\n```bash\n#!/bin/bash\n# cold-backup.sh - File system level backup\n\nsystemctl stop metrics-service\n\n# Copy database files\ncp /var/lib/sqlite/metrics.db /backups/\ncp /var/lib/sqlite/metrics.db-wal /backups/\ncp /var/lib/sqlite/metrics.db-shm /backups/\n\nsystemctl start metrics-service\n```\n\n### Recovery Procedures\n\n#### Point-in-Time Recovery\n\n```bash\n# Restore from backup\nsystemctl stop metrics-service\n\n# Restore database\ngunzip -c /backups/metrics/20240101_120000.db.gz > /var/lib/sqlite/metrics.db\n\n# Verify integrity\nsqlite3 /var/lib/sqlite/metrics.db \"PRAGMA integrity_check;\"\n\n# Restart service\nsystemctl start metrics-service\n```\n\n#### Corruption Recovery\n\n```sql\n-- Check for corruption\nPRAGMA integrity_check;\nPRAGMA foreign_key_check;\n\n-- Recover from corruption\n.output /tmp/recovery.sql\n.dump\n.quit\n\n-- Create new database\nrm metrics.db\nsqlite3 metrics.db < /tmp/recovery.sql\n```\n\n### Disaster Recovery\n\n#### Full System Recovery\n\n1. **Provision new server**\n2. **Install application**\n3. **Restore latest backup**\n4. **Apply any missing migrations**\n5. **Verify data integrity**\n6. **Update DNS/load balancers**\n\n```bash\n# Recovery script\n#!/bin/bash\nset -e\n\n# Download latest backup\naws s3 cp s3://backups/metrics/latest.db.gz ./\n\n# Restore database\ngunzip latest.db.gz\nmv latest.db /var/lib/sqlite/metrics.db\n\n# Apply migrations\nuv run python migrate.py up\n\n# Verify\nsqlite3 /var/lib/sqlite/metrics.db \"PRAGMA integrity_check;\"\n\n# Start service\nsystemctl start metrics-service\n```\n\nThis documentation provides a complete reference for understanding and managing the database schema, migrations, and data lifecycle of the MCP Metrics Collection Service." }, { "path": "metrics-service/docs/deployment.md", "content": "# Deployment Guide\n\nThis guide covers deploying the MCP Metrics Collection Service in various environments, from development to production.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Prerequisites](#prerequisites)\n- [Development Deployment](#development-deployment)\n- [Production Deployment](#production-deployment)\n- [Container Deployment](#container-deployment)\n- [Environment Configuration](#environment-configuration)\n- [Database Setup](#database-setup)\n- [Security Considerations](#security-considerations)\n- [Monitoring Setup](#monitoring-setup)\n- [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThe metrics service can be deployed in several ways:\n\n1. **Local Development**: Direct Python execution with local SQLite\n2. **Docker Compose**: Containerized development environment\n3. **Production Container**: Docker deployment with external database\n4. **Kubernetes**: Scalable cloud deployment (configuration provided)\n\n## Prerequisites\n\n### System Requirements\n\n- **CPU**: 1 core minimum, 2+ cores recommended\n- **Memory**: 512MB minimum, 1GB+ recommended \n- **Storage**: 10GB minimum for database growth\n- **Network**: HTTP/HTTPS access on configured ports\n\n### Software Dependencies\n\n- **Python**: 3.11+ (for direct deployment)\n- **Docker**: 20.10+ (for container deployment)\n- **Docker Compose**: 2.0+ (for development)\n- **uv**: Latest version (recommended package manager)\n\n### Network Ports\n\n- **8890**: HTTP API (configurable via `METRICS_SERVICE_PORT`)\n- **9465**: Prometheus metrics (configurable via `OTEL_PROMETHEUS_PORT`)\n\n## Development Deployment\n\n### Quick Start\n\n1. **Clone and setup**:\n```bash\ncd metrics-service\nuv sync --dev\n```\n\n2. **Initialize database**:\n```bash\nuv run python migrate.py up\n```\n\n3. **Create development API key**:\n```bash\nuv run python create_api_key.py\n# Save the generated API key for testing\n```\n\n4. **Start development server**:\n```bash\nuv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8890\n```\n\n5. **Verify deployment**:\n```bash\ncurl http://localhost:8890/health\n```\n\n### Development Configuration\n\nCreate a `.env` file for local development:\n\n```bash\n# .env\nSQLITE_DB_PATH=\"./dev_metrics.db\"\nMETRICS_SERVICE_HOST=\"127.0.0.1\"\nMETRICS_SERVICE_PORT=\"8890\"\nOTEL_PROMETHEUS_ENABLED=\"true\"\nOTEL_PROMETHEUS_PORT=\"9465\"\nMETRICS_RATE_LIMIT=\"100\" # Lower for development\n```\n\nLoad environment:\n```bash\nuv run --env-file .env uvicorn app.main:app --reload\n```\n\n### Hot Reload Development\n\nFor active development with auto-reload:\n\n```bash\n# Terminal 1: Start service with reload\nuv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8890\n\n# Terminal 2: Watch tests\nuv run pytest --watch\n\n# Terminal 3: Test API changes\ncurl -X POST http://localhost:8890/metrics \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-dev-key\" \\\n -d '{\"service\": \"test\", \"metrics\": [{\"type\": \"auth_request\", \"value\": 1.0}]}'\n```\n\n## Production Deployment\n\n### Production Checklist\n\nBefore deploying to production, ensure:\n\n- ✅ Database backup strategy in place\n- ✅ SSL/TLS certificates configured\n- ✅ API keys generated and securely stored\n- ✅ Monitoring and alerting configured\n- ✅ Log aggregation setup\n- ✅ Rate limits configured for expected load\n- ✅ Data retention policies defined\n- ✅ Disaster recovery plan documented\n\n### Direct Production Deployment\n\n1. **System setup**:\n```bash\n# Create dedicated user\nsudo useradd -m -s /bin/bash metrics\nsudo su - metrics\n\n# Install uv and dependencies\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nsource ~/.bashrc\n```\n\n2. **Application setup**:\n```bash\ncd /opt/metrics-service\nuv sync --no-dev\n```\n\n3. **Database initialization**:\n```bash\n# Ensure data directory exists with proper permissions\nsudo mkdir -p /var/lib/sqlite\nsudo chown metrics:metrics /var/lib/sqlite\nsudo chmod 750 /var/lib/sqlite\n\n# Initialize database\nuv run python migrate.py up\n```\n\n4. **Create production API keys**:\n```bash\nuv run python create_api_key.py\n# Store keys securely in your secrets management system\n```\n\n5. **Create systemd service**:\n```ini\n# /etc/systemd/system/metrics-service.service\n[Unit]\nDescription=MCP Metrics Collection Service\nAfter=network.target\nWants=network.target\n\n[Service]\nType=exec\nUser=metrics\nGroup=metrics\nWorkingDirectory=/opt/metrics-service\nEnvironment=PATH=/home/metrics/.local/bin:/usr/local/bin:/usr/bin:/bin\nEnvironmentFile=/etc/metrics-service/config\nExecStart=/home/metrics/.local/bin/uv run python -m app.main\nExecReload=/bin/kill -HUP $MAINPID\nKillMode=mixed\nRestart=always\nRestartSec=5\nStandardOutput=journal\nStandardError=journal\nSyslogIdentifier=metrics-service\n\n[Install]\nWantedBy=multi-user.target\n```\n\n6. **Production configuration**:\n```bash\n# /etc/metrics-service/config\nSQLITE_DB_PATH=\"/var/lib/sqlite/metrics.db\"\nMETRICS_SERVICE_HOST=\"0.0.0.0\"\nMETRICS_SERVICE_PORT=\"8890\"\nOTEL_PROMETHEUS_ENABLED=\"true\"\nOTEL_PROMETHEUS_PORT=\"9465\"\nMETRICS_RATE_LIMIT=\"5000\"\nMETRICS_RETENTION_DAYS=\"90\"\nBATCH_SIZE=\"500\"\nFLUSH_INTERVAL_SECONDS=\"10\"\n```\n\n7. **Start and enable service**:\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable metrics-service\nsudo systemctl start metrics-service\nsudo systemctl status metrics-service\n```\n\n### Reverse Proxy Configuration\n\n#### Nginx Configuration\n\n```nginx\n# /etc/nginx/sites-available/metrics-service\nupstream metrics_backend {\n server 127.0.0.1:8890;\n}\n\nserver {\n listen 80;\n server_name metrics.yourdomain.com;\n \n # Redirect HTTP to HTTPS\n return 301 https://$server_name$request_uri;\n}\n\nserver {\n listen 443 ssl http2;\n server_name metrics.yourdomain.com;\n \n # SSL Configuration\n ssl_certificate /etc/ssl/certs/metrics.crt;\n ssl_certificate_key /etc/ssl/private/metrics.key;\n ssl_protocols TLSv1.2 TLSv1.3;\n ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;\n ssl_prefer_server_ciphers off;\n \n # Security Headers\n add_header X-Frame-Options DENY;\n add_header X-Content-Type-Options nosniff;\n add_header X-XSS-Protection \"1; mode=block\";\n add_header Strict-Transport-Security \"max-age=63072000; includeSubDomains; preload\";\n \n # Rate limiting\n limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;\n limit_req zone=api burst=20 nodelay;\n \n # Main API\n location / {\n proxy_pass http://metrics_backend;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n \n # Timeouts\n proxy_connect_timeout 30s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n \n # Buffer settings\n proxy_buffering on;\n proxy_buffer_size 4k;\n proxy_buffers 8 4k;\n }\n \n # Prometheus metrics (separate location for monitoring)\n location /prometheus {\n proxy_pass http://127.0.0.1:9465/metrics;\n allow 10.0.0.0/8; # Internal network\n allow 172.16.0.0/12; # Docker networks\n allow 192.168.0.0/16; # Private networks\n deny all;\n }\n \n # Health check (no auth required)\n location /health {\n proxy_pass http://metrics_backend/health;\n access_log off;\n }\n}\n```\n\n#### Apache Configuration\n\n```apache\n# /etc/apache2/sites-available/metrics-service.conf\n\n ServerName metrics.yourdomain.com\n Redirect permanent / https://metrics.yourdomain.com/\n\n\n\n ServerName metrics.yourdomain.com\n \n # SSL Configuration\n SSLEngine on\n SSLCertificateFile /etc/ssl/certs/metrics.crt\n SSLCertificateKeyFile /etc/ssl/private/metrics.key\n SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1\n SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384\n \n # Security Headers\n Header always set X-Frame-Options DENY\n Header always set X-Content-Type-Options nosniff\n Header always set X-XSS-Protection \"1; mode=block\"\n Header always set Strict-Transport-Security \"max-age=63072000; includeSubDomains; preload\"\n \n # Proxy Configuration\n ProxyPreserveHost On\n ProxyPass /health http://127.0.0.1:8890/health\n ProxyPassReverse /health http://127.0.0.1:8890/health\n \n ProxyPass / http://127.0.0.1:8890/\n ProxyPassReverse / http://127.0.0.1:8890/\n\n```\n\n## Container Deployment\n\n### Docker Compose Production\n\n```yaml\n# docker-compose.prod.yml\nversion: '3.8'\n\nservices:\n metrics-db:\n image: nouchka/sqlite3:latest\n volumes:\n - metrics-db-data:/var/lib/sqlite\n restart: unless-stopped\n \n metrics-service:\n build: \n context: .\n target: production\n ports:\n - \"8890:8890\"\n - \"9465:9465\"\n environment:\n - SQLITE_DB_PATH=/var/lib/sqlite/metrics.db\n - METRICS_SERVICE_HOST=0.0.0.0\n - METRICS_RATE_LIMIT=5000\n - BATCH_SIZE=500\n - FLUSH_INTERVAL_SECONDS=10\n volumes:\n - metrics-db-data:/var/lib/sqlite\n depends_on:\n - metrics-db\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8890/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n \n nginx:\n image: nginx:alpine\n ports:\n - \"80:80\"\n - \"443:443\"\n volumes:\n - ./nginx.conf:/etc/nginx/nginx.conf:ro\n - ./ssl:/etc/ssl:ro\n depends_on:\n - metrics-service\n restart: unless-stopped\n\nvolumes:\n metrics-db-data:\n driver: local\n```\n\n### Multi-stage Dockerfile\n\n```dockerfile\n# Dockerfile\nFROM python:3.14-slim as base\n\n# Install system dependencies\nRUN apt-get update && apt-get install -y \\\n curl \\\n && rm -rf /var/lib/apt/lists/*\n\n# Install uv\nRUN curl -LsSf https://astral.sh/uv/install.sh | sh\nENV PATH=\"/root/.local/bin:$PATH\"\n\nWORKDIR /app\n\n# Copy dependency files\nCOPY pyproject.toml uv.lock ./\n\n# Development stage\nFROM base as development\nRUN uv sync --dev\nCOPY . .\nCMD [\"uv\", \"run\", \"uvicorn\", \"app.main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8890\", \"--reload\"]\n\n# Production stage\nFROM base as production\nRUN uv sync --no-dev\nCOPY . .\n\n# Create non-root user\nRUN useradd -m -u 1001 metrics\nUSER metrics\n\n# Initialize database on startup\nRUN uv run python migrate.py up\n\nEXPOSE 8890 9465\n\nHEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \\\n CMD curl -f http://localhost:8890/health || exit 1\n\nCMD [\"uv\", \"run\", \"python\", \"-m\", \"app.main\"]\n```\n\n### Kubernetes Deployment\n\n```yaml\n# k8s/namespace.yaml\napiVersion: v1\nkind: Namespace\nmetadata:\n name: metrics-system\n\n---\n# k8s/configmap.yaml\napiVersion: v1\nkind: ConfigMap\nmetadata:\n name: metrics-config\n namespace: metrics-system\ndata:\n METRICS_SERVICE_HOST: \"0.0.0.0\"\n METRICS_SERVICE_PORT: \"8890\"\n OTEL_PROMETHEUS_ENABLED: \"true\"\n OTEL_PROMETHEUS_PORT: \"9465\"\n METRICS_RATE_LIMIT: \"5000\"\n BATCH_SIZE: \"500\"\n FLUSH_INTERVAL_SECONDS: \"10\"\n\n---\n# k8s/secret.yaml\napiVersion: v1\nkind: Secret\nmetadata:\n name: metrics-secrets\n namespace: metrics-system\ntype: Opaque\ndata:\n # Base64 encoded values\n database-url: c3FsaXRlOi8vL3Zhci9saWIvc3FsaXRlL21ldHJpY3MuZGI=\n\n---\n# k8s/pvc.yaml\napiVersion: v1\nkind: PersistentVolumeClaim\nmetadata:\n name: metrics-storage\n namespace: metrics-system\nspec:\n accessModes:\n - ReadWriteOnce\n resources:\n requests:\n storage: 10Gi\n\n---\n# k8s/deployment.yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: metrics-service\n namespace: metrics-system\n labels:\n app: metrics-service\nspec:\n replicas: 2\n selector:\n matchLabels:\n app: metrics-service\n template:\n metadata:\n labels:\n app: metrics-service\n spec:\n containers:\n - name: metrics-service\n image: metrics-service:latest\n ports:\n - containerPort: 8890\n name: http\n - containerPort: 9465\n name: metrics\n envFrom:\n - configMapRef:\n name: metrics-config\n - secretRef:\n name: metrics-secrets\n volumeMounts:\n - name: data\n mountPath: /var/lib/sqlite\n resources:\n requests:\n memory: \"256Mi\"\n cpu: \"250m\"\n limits:\n memory: \"512Mi\"\n cpu: \"500m\"\n livenessProbe:\n httpGet:\n path: /health\n port: 8890\n initialDelaySeconds: 30\n periodSeconds: 10\n readinessProbe:\n httpGet:\n path: /health\n port: 8890\n initialDelaySeconds: 5\n periodSeconds: 5\n volumes:\n - name: data\n persistentVolumeClaim:\n claimName: metrics-storage\n\n---\n# k8s/service.yaml\napiVersion: v1\nkind: Service\nmetadata:\n name: metrics-service\n namespace: metrics-system\n labels:\n app: metrics-service\nspec:\n selector:\n app: metrics-service\n ports:\n - name: http\n port: 80\n targetPort: 8890\n - name: metrics\n port: 9465\n targetPort: 9465\n\n---\n# k8s/ingress.yaml\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: metrics-ingress\n namespace: metrics-system\n annotations:\n kubernetes.io/ingress.class: nginx\n cert-manager.io/cluster-issuer: letsencrypt-prod\n nginx.ingress.kubernetes.io/rate-limit: \"100\"\n nginx.ingress.kubernetes.io/rate-limit-window: \"1m\"\nspec:\n tls:\n - hosts:\n - metrics.yourdomain.com\n secretName: metrics-tls\n rules:\n - host: metrics.yourdomain.com\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: metrics-service\n port:\n number: 80\n```\n\nDeploy to Kubernetes:\n```bash\nkubectl apply -f k8s/\n```\n\n## Environment Configuration\n\n### Environment Variables Reference\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SQLITE_DB_PATH` | `/var/lib/sqlite/metrics.db` | SQLite database file path |\n| `METRICS_SERVICE_HOST` | `0.0.0.0` | Service bind address |\n| `METRICS_SERVICE_PORT` | `8890` | Service port |\n| `OTEL_PROMETHEUS_ENABLED` | `true` | Enable Prometheus metrics |\n| `OTEL_PROMETHEUS_PORT` | `9465` | Prometheus metrics port |\n| `OTEL_OTLP_ENDPOINT` | `\"\"` | OTLP endpoint URL |\n| `METRICS_RATE_LIMIT` | `1000` | Requests per minute per API key |\n| `METRICS_RETENTION_DAYS` | `90` | Data retention in days |\n| `BATCH_SIZE` | `100` | Metrics batch size |\n| `FLUSH_INTERVAL_SECONDS` | `30` | Buffer flush interval |\n| `MAX_REQUEST_SIZE` | `10MB` | Maximum request size |\n\n### Environment-Specific Configurations\n\n#### Development\n```bash\nSQLITE_DB_PATH=\"./dev.db\"\nMETRICS_SERVICE_HOST=\"127.0.0.1\"\nMETRICS_RATE_LIMIT=\"100\"\nOTEL_PROMETHEUS_ENABLED=\"true\"\nBATCH_SIZE=\"10\"\nFLUSH_INTERVAL_SECONDS=\"5\"\n```\n\n#### Staging\n```bash\nSQLITE_DB_PATH=\"/var/lib/sqlite/staging_metrics.db\"\nMETRICS_SERVICE_HOST=\"0.0.0.0\"\nMETRICS_RATE_LIMIT=\"1000\"\nOTEL_OTLP_ENDPOINT=\"https://staging-otel.company.com\"\nBATCH_SIZE=\"100\"\nFLUSH_INTERVAL_SECONDS=\"15\"\n```\n\n#### Production\n```bash\nSQLITE_DB_PATH=\"/var/lib/sqlite/metrics.db\"\nMETRICS_SERVICE_HOST=\"0.0.0.0\"\nMETRICS_RATE_LIMIT=\"5000\"\nOTEL_OTLP_ENDPOINT=\"https://otel.company.com\"\nBATCH_SIZE=\"500\"\nFLUSH_INTERVAL_SECONDS=\"10\"\n```\n\n## Database Setup\n\n### Database Initialization\n\n1. **Run migrations**:\n```bash\nuv run python migrate.py status\nuv run python migrate.py up\n```\n\n2. **Verify schema**:\n```bash\nsqlite3 /var/lib/sqlite/metrics.db \".schema\"\n```\n\n3. **Create initial API keys**:\n```bash\nuv run python create_api_key.py\n```\n\n### Database Maintenance\n\n#### Backup Strategy\n\n```bash\n#!/bin/bash\n# backup-metrics-db.sh\n\nDB_PATH=\"/var/lib/sqlite/metrics.db\"\nBACKUP_DIR=\"/backups/metrics\"\nDATE=$(date +%Y%m%d_%H%M%S)\n\n# Create backup directory\nmkdir -p \"$BACKUP_DIR\"\n\n# Create backup with vacuum\nsqlite3 \"$DB_PATH\" \".backup $BACKUP_DIR/metrics_$DATE.db\"\n\n# Compress backup\ngzip \"$BACKUP_DIR/metrics_$DATE.db\"\n\n# Clean old backups (keep 30 days)\nfind \"$BACKUP_DIR\" -name \"*.gz\" -mtime +30 -delete\n\necho \"Backup completed: metrics_$DATE.db.gz\"\n```\n\nSchedule backups:\n```bash\n# Add to crontab\n0 2 * * * /opt/scripts/backup-metrics-db.sh\n```\n\n#### Database Optimization\n\n```bash\n# Vacuum and analyze (run weekly)\nsqlite3 /var/lib/sqlite/metrics.db \"VACUUM; ANALYZE;\"\n\n# Check database integrity\nsqlite3 /var/lib/sqlite/metrics.db \"PRAGMA integrity_check;\"\n\n# View database statistics\nsqlite3 /var/lib/sqlite/metrics.db \"PRAGMA table_info(metrics);\"\n```\n\n## Security Considerations\n\n### API Key Security\n\n1. **Generation**: Use cryptographically secure random generators\n2. **Storage**: Store only SHA256 hashes, never plaintext\n3. **Transmission**: Always use HTTPS in production\n4. **Rotation**: Implement key rotation policies\n5. **Monitoring**: Log and alert on authentication failures\n\n### Network Security\n\n1. **TLS/SSL**: Enforce HTTPS with strong cipher suites\n2. **Firewalls**: Restrict access to necessary ports only\n3. **Rate Limiting**: Implement both application and network-level limiting\n4. **IP Allowlisting**: Consider IP restrictions for sensitive environments\n\n### File System Security\n\n```bash\n# Set proper permissions\nsudo chown -R metrics:metrics /var/lib/sqlite\nsudo chmod 750 /var/lib/sqlite\nsudo chmod 640 /var/lib/sqlite/metrics.db\n\n# SELinux context (if enabled)\nsudo setsebool -P httpd_can_network_connect 1\nsudo semanage fcontext -a -t httpd_exec_t \"/opt/metrics-service(/.*)?\"\nsudo restorecon -R /opt/metrics-service\n```\n\n### Container Security\n\n```dockerfile\n# Use non-root user\nUSER 1001\n\n# Read-only filesystem\nRUN chmod -R a-w /app\n\n# Drop capabilities\nUSER 1001:1001\n```\n\n## Monitoring Setup\n\n### Prometheus Configuration\n\n```yaml\n# prometheus.yml\nglobal:\n scrape_interval: 15s\n\nscrape_configs:\n - job_name: 'metrics-service'\n static_configs:\n - targets: ['localhost:9465']\n metrics_path: /metrics\n scrape_interval: 15s\n```\n\n### Grafana Dashboard\n\n```json\n{\n \"dashboard\": {\n \"title\": \"MCP Metrics Service\",\n \"panels\": [\n {\n \"title\": \"Request Rate\",\n \"type\": \"graph\",\n \"targets\": [\n {\n \"expr\": \"rate(http_requests_total[5m])\",\n \"legendFormat\": \"{{method}} {{endpoint}}\"\n }\n ]\n },\n {\n \"title\": \"Error Rate\",\n \"type\": \"graph\", \n \"targets\": [\n {\n \"expr\": \"rate(http_requests_total{status=~\\\"4..|5..\\\"}[5m])\",\n \"legendFormat\": \"{{status}}\"\n }\n ]\n },\n {\n \"title\": \"Rate Limit Usage\",\n \"type\": \"graph\",\n \"targets\": [\n {\n \"expr\": \"rate_limit_available_tokens\",\n \"legendFormat\": \"{{service}}\"\n }\n ]\n }\n ]\n }\n}\n```\n\n### Alerting Rules\n\n```yaml\n# alerts.yml\ngroups:\n - name: metrics-service\n rules:\n - alert: MetricsServiceDown\n expr: up{job=\"metrics-service\"} == 0\n for: 1m\n labels:\n severity: critical\n annotations:\n summary: \"Metrics service is down\"\n \n - alert: HighErrorRate\n expr: rate(http_requests_total{status=~\"5..\"}[5m]) > 0.1\n for: 5m\n labels:\n severity: warning\n annotations:\n summary: \"High error rate detected\"\n \n - alert: RateLimitExhaustion\n expr: rate_limit_available_tokens < 10\n for: 1m\n labels:\n severity: warning\n annotations:\n summary: \"Rate limit nearly exhausted\"\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Service Won't Start\n\n1. **Check logs**:\n```bash\njournalctl -u metrics-service -f\n```\n\n2. **Verify database permissions**:\n```bash\nls -la /var/lib/sqlite/\nsudo chown metrics:metrics /var/lib/sqlite/metrics.db\n```\n\n3. **Test database connection**:\n```bash\nsqlite3 /var/lib/sqlite/metrics.db \"SELECT 1;\"\n```\n\n#### High Memory Usage\n\n1. **Check SQLite cache settings**:\n```sql\nPRAGMA cache_size; -- Should be reasonable\nPRAGMA temp_store; -- Should be MEMORY\n```\n\n2. **Monitor buffer sizes**:\n```bash\n# Check if batch size is too large\ngrep BATCH_SIZE /etc/metrics-service/config\n```\n\n#### Rate Limiting Issues\n\n1. **Check rate limiter status**:\n```bash\ncurl -H \"X-API-Key: your-key\" http://localhost:8890/rate-limit\n```\n\n2. **Review rate limit logs**:\n```bash\njournalctl -u metrics-service | grep \"rate limit\"\n```\n\n#### Database Lock Issues\n\n1. **Check for long-running transactions**:\n```sql\nPRAGMA wal_checkpoint;\n```\n\n2. **Monitor WAL file size**:\n```bash\nls -la /var/lib/sqlite/metrics.db-wal\n```\n\n### Log Analysis\n\n#### Structured Logging Format\n\n```json\n{\n \"timestamp\": \"2024-01-01T12:00:00Z\",\n \"level\": \"INFO\",\n \"logger\": \"app.api.routes\",\n \"message\": \"Processed metrics\",\n \"request_id\": \"req_123\",\n \"service\": \"auth-server\",\n \"accepted\": 5,\n \"rejected\": 0,\n \"duration_ms\": 45.2\n}\n```\n\n#### Log Aggregation with ELK Stack\n\n```yaml\n# filebeat.yml\nfilebeat.inputs:\n- type: log\n enabled: true\n paths:\n - /var/log/metrics-service/*.log\n json.keys_under_root: true\n json.add_error_key: true\n\noutput.elasticsearch:\n hosts: [\"elasticsearch:9200\"]\n \nlogging.level: info\n```\n\n### Performance Tuning\n\n#### Database Optimization\n\n```sql\n-- Analyze query performance\nEXPLAIN QUERY PLAN SELECT * FROM metrics WHERE timestamp > '2024-01-01';\n\n-- Update statistics\nANALYZE;\n\n-- Optimize settings\nPRAGMA optimize;\n```\n\n#### Application Tuning\n\n```bash\n# Increase batch size for high throughput\nBATCH_SIZE=1000\n\n# Reduce flush interval for low latency\nFLUSH_INTERVAL_SECONDS=5\n\n# Adjust rate limits based on capacity\nMETRICS_RATE_LIMIT=10000\n```\n\nThis deployment guide provides comprehensive instructions for deploying the metrics service across different environments with proper security, monitoring, and maintenance procedures." }, { "path": "metrics-service/metrics_client.py", "content": "\"\"\"\nMetrics client library for sending metrics to the MCP Metrics Collection Service.\n\nThis module provides an HTTP client that other services can use to emit metrics\nto the centralized metrics collection service.\n\"\"\"\n\nimport httpx\nimport asyncio\nimport logging\nimport os\nfrom datetime import datetime\nfrom typing import Dict, Any, Optional, List\nimport json\n\nlogger = logging.getLogger(__name__)\n\n\nclass MetricsClient:\n \"\"\"HTTP client for sending metrics to collection service.\"\"\"\n\n def __init__(\n self,\n metrics_url: str = None,\n api_key: str = None,\n service_name: str = \"unknown\",\n service_version: str = \"1.0.0\",\n instance_id: str = None,\n timeout: float = 5.0,\n max_retries: int = 3,\n enabled: bool = True,\n ):\n self.metrics_url = metrics_url or os.getenv(\"METRICS_SERVICE_URL\", \"http://localhost:8890\")\n self.metrics_endpoint = f\"{self.metrics_url}/metrics\"\n self.api_key = api_key or os.getenv(\"METRICS_API_KEY\", \"\")\n self.service_name = service_name\n self.service_version = service_version\n self.instance_id = instance_id or f\"{service_name}-{os.getpid()}\"\n self.timeout = timeout\n self.max_retries = max_retries\n self.enabled = enabled and bool(self.api_key)\n self._client = None\n\n if not self.enabled:\n logger.warning(f\"Metrics client disabled for {service_name} - no API key provided\")\n\n async def _get_client(self):\n \"\"\"Get or create HTTP client.\"\"\"\n if self._client is None:\n self._client = httpx.AsyncClient(timeout=self.timeout)\n return self._client\n\n async def _emit_metric(\n self,\n metric_type: str,\n value: float = 1.0,\n duration_ms: float | None = None,\n dimensions: Dict[str, Any] | None = None,\n metadata: Dict[str, Any] | None = None,\n timestamp: datetime | None = None,\n ) -> bool:\n \"\"\"Internal method to emit a single metric.\"\"\"\n if not self.enabled:\n return False\n\n try:\n client = await self._get_client()\n\n payload = {\n \"service\": self.service_name,\n \"version\": self.service_version,\n \"instance_id\": self.instance_id,\n \"metrics\": [\n {\n \"type\": metric_type,\n \"timestamp\": (timestamp or datetime.utcnow()).isoformat(),\n \"value\": value,\n \"duration_ms\": duration_ms,\n \"dimensions\": dimensions or {},\n \"metadata\": metadata or {},\n }\n ],\n }\n\n headers = {\"X-API-Key\": self.api_key}\n\n for attempt in range(self.max_retries + 1):\n try:\n response = await client.post(\n self.metrics_endpoint, json=payload, headers=headers\n )\n\n if response.status_code == 200:\n logger.debug(f\"Metric {metric_type} sent successfully\")\n return True\n else:\n logger.warning(\n f\"Metrics API error: {response.status_code} - {response.text}\"\n )\n return False\n\n except (httpx.ConnectError, httpx.TimeoutException) as e:\n if attempt < self.max_retries:\n wait_time = 2**attempt # Exponential backoff\n logger.warning(\n f\"Metrics API connection failed (attempt {attempt + 1}), retrying in {wait_time}s: {e}\"\n )\n await asyncio.sleep(wait_time)\n else:\n logger.error(\n f\"Failed to emit metric after {self.max_retries + 1} attempts: {e}\"\n )\n return False\n\n except Exception as e:\n # Never fail the main operation due to metrics\n logger.error(f\"Failed to emit metric {metric_type}: {e}\")\n return False\n\n def emit_metric_sync(self, *args, **kwargs):\n \"\"\"Synchronous wrapper that creates a task for async emission.\"\"\"\n if not self.enabled:\n return\n asyncio.create_task(self._emit_metric(*args, **kwargs))\n\n # Auth Server Metrics\n async def emit_auth_metric(\n self,\n success: bool,\n method: str,\n duration_ms: float,\n server_name: str | None = None,\n user_hash: str | None = None,\n error_code: str | None = None,\n ) -> bool:\n \"\"\"Emit authentication metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"auth_request\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\n \"success\": success,\n \"method\": method,\n \"server\": server_name or \"unknown\",\n \"user_hash\": user_hash or \"\",\n },\n metadata={\"error_code\": error_code},\n )\n\n def emit_auth_metric_sync(self, *args, **kwargs):\n \"\"\"Synchronous wrapper for auth metrics.\"\"\"\n asyncio.create_task(self.emit_auth_metric(*args, **kwargs))\n\n # Registry Service Metrics\n async def emit_registry_metric(\n self,\n operation: str, # create, read, update, delete, list, search\n resource_type: str, # server, config, etc.\n success: bool,\n duration_ms: float,\n resource_id: str | None = None,\n user_id: str | None = None,\n error_code: str | None = None,\n ) -> bool:\n \"\"\"Emit registry operation metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"registry_operation\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\n \"operation\": operation,\n \"resource_type\": resource_type,\n \"success\": success,\n \"resource_id\": resource_id or \"\",\n \"user_id\": user_id or \"\",\n },\n metadata={\"error_code\": error_code},\n )\n\n def emit_registry_metric_sync(self, *args, **kwargs):\n \"\"\"Synchronous wrapper for registry metrics.\"\"\"\n asyncio.create_task(self.emit_registry_metric(*args, **kwargs))\n\n # Tool Discovery Metrics\n async def emit_discovery_metric(\n self,\n query: str,\n results_count: int,\n duration_ms: float,\n top_k_services: int | None = None,\n top_n_tools: int | None = None,\n embedding_time_ms: float | None = None,\n faiss_search_time_ms: float | None = None,\n ) -> bool:\n \"\"\"Emit tool discovery metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"tool_discovery\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\n \"query\": query[:100], # Truncate long queries\n \"results_count\": results_count,\n \"top_k_services\": top_k_services,\n \"top_n_tools\": top_n_tools,\n },\n metadata={\n \"embedding_time_ms\": embedding_time_ms,\n \"faiss_search_time_ms\": faiss_search_time_ms,\n },\n )\n\n def emit_discovery_metric_sync(self, *args, **kwargs):\n \"\"\"Synchronous wrapper for discovery metrics.\"\"\"\n asyncio.create_task(self.emit_discovery_metric(*args, **kwargs))\n\n # Tool Execution Metrics\n async def emit_tool_execution_metric(\n self,\n tool_name: str,\n server_path: str,\n server_name: str,\n success: bool,\n duration_ms: float,\n input_size_bytes: int | None = None,\n output_size_bytes: int | None = None,\n error_code: str | None = None,\n ) -> bool:\n \"\"\"Emit tool execution metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"tool_execution\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\n \"tool_name\": tool_name,\n \"server_path\": server_path,\n \"server_name\": server_name,\n \"success\": success,\n },\n metadata={\n \"error_code\": error_code,\n \"input_size_bytes\": input_size_bytes,\n \"output_size_bytes\": output_size_bytes,\n },\n )\n\n def emit_tool_execution_metric_sync(self, *args, **kwargs):\n \"\"\"Synchronous wrapper for tool execution metrics.\"\"\"\n asyncio.create_task(self.emit_tool_execution_metric(*args, **kwargs))\n\n # Health Check Metrics\n async def emit_health_metric(\n self, endpoint: str, status_code: int, duration_ms: float, healthy: bool = True\n ) -> bool:\n \"\"\"Emit health check metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"health_check\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\"endpoint\": endpoint, \"status_code\": status_code, \"healthy\": healthy},\n )\n\n def emit_health_metric_sync(self, *args, **kwargs):\n \"\"\"Synchronous wrapper for health metrics.\"\"\"\n asyncio.create_task(self.emit_health_metric(*args, **kwargs))\n\n # Custom Metrics\n async def emit_custom_metric(\n self,\n metric_name: str,\n value: float,\n duration_ms: float | None = None,\n dimensions: Dict[str, Any] | None = None,\n metadata: Dict[str, Any] | None = None,\n ) -> bool:\n \"\"\"Emit custom metric with arbitrary data.\"\"\"\n custom_dimensions = {\"metric_name\": metric_name}\n if dimensions:\n custom_dimensions.update(dimensions)\n\n return await self._emit_metric(\n metric_type=\"custom\",\n value=value,\n duration_ms=duration_ms,\n dimensions=custom_dimensions,\n metadata=metadata,\n )\n\n def emit_custom_metric_sync(self, *args, **kwargs):\n \"\"\"Synchronous wrapper for custom metrics.\"\"\"\n asyncio.create_task(self.emit_custom_metric(*args, **kwargs))\n\n # Batch Metrics\n async def emit_metrics_batch(self, metrics: List[Dict[str, Any]]) -> bool:\n \"\"\"Emit multiple metrics in a single request.\"\"\"\n if not self.enabled or not metrics:\n return False\n\n try:\n client = await self._get_client()\n\n # Format metrics for API\n formatted_metrics = []\n for metric in metrics:\n formatted_metric = {\n \"type\": metric.get(\"type\", \"custom\"),\n \"timestamp\": (metric.get(\"timestamp\") or datetime.utcnow()).isoformat(),\n \"value\": metric.get(\"value\", 1.0),\n \"duration_ms\": metric.get(\"duration_ms\"),\n \"dimensions\": metric.get(\"dimensions\", {}),\n \"metadata\": metric.get(\"metadata\", {}),\n }\n formatted_metrics.append(formatted_metric)\n\n payload = {\n \"service\": self.service_name,\n \"version\": self.service_version,\n \"instance_id\": self.instance_id,\n \"metrics\": formatted_metrics,\n }\n\n headers = {\"X-API-Key\": self.api_key}\n\n response = await client.post(self.metrics_endpoint, json=payload, headers=headers)\n\n if response.status_code == 200:\n logger.debug(f\"Batch of {len(metrics)} metrics sent successfully\")\n return True\n else:\n logger.warning(f\"Metrics API error: {response.status_code} - {response.text}\")\n return False\n\n except Exception as e:\n logger.error(f\"Failed to emit metrics batch: {e}\")\n return False\n\n async def close(self):\n \"\"\"Close HTTP client.\"\"\"\n if self._client:\n await self._client.aclose()\n\n async def __aenter__(self):\n \"\"\"Async context manager entry.\"\"\"\n return self\n\n async def __aexit__(self, exc_type, exc_val, exc_tb):\n \"\"\"Async context manager exit.\"\"\"\n await self.close()\n\n\n# Global client instances for each service (to be configured per service)\ndef create_metrics_client(\n service_name: str, service_version: str = \"1.0.0\", **kwargs\n) -> MetricsClient:\n \"\"\"Factory function to create a configured metrics client.\"\"\"\n return MetricsClient(service_name=service_name, service_version=service_version, **kwargs)\n\n\n# Convenience functions for services that prefer functional interface\nasync def emit_auth_metric(success: bool, method: str, duration_ms: float, **kwargs):\n \"\"\"Convenience function for auth metrics.\"\"\"\n client = create_metrics_client(\"auth-server\")\n try:\n return await client.emit_auth_metric(success, method, duration_ms, **kwargs)\n finally:\n await client.close()\n\n\nasync def emit_registry_metric(\n operation: str, resource_type: str, success: bool, duration_ms: float, **kwargs\n):\n \"\"\"Convenience function for registry metrics.\"\"\"\n client = create_metrics_client(\"registry\")\n try:\n return await client.emit_registry_metric(\n operation, resource_type, success, duration_ms, **kwargs\n )\n finally:\n await client.close()\n\n\nasync def emit_discovery_metric(query: str, results_count: int, duration_ms: float, **kwargs):\n \"\"\"Convenience function for discovery metrics.\"\"\"\n client = create_metrics_client(\"registry\")\n try:\n return await client.emit_discovery_metric(query, results_count, duration_ms, **kwargs)\n finally:\n await client.close()\n\n\nasync def emit_tool_execution_metric(\n tool_name: str, server_path: str, server_name: str, success: bool, duration_ms: float, **kwargs\n):\n \"\"\"Convenience function for tool execution metrics.\"\"\"\n client = create_metrics_client(\"mcp-server\")\n try:\n return await client.emit_tool_execution_metric(\n tool_name, server_path, server_name, success, duration_ms, **kwargs\n )\n finally:\n await client.close()\n" }, { "path": "metrics-service/migrate.py", "content": "#!/usr/bin/env python3\n\"\"\"Migration management CLI for metrics service.\"\"\"\n\nimport asyncio\nimport sys\nimport argparse\nimport json\nfrom pathlib import Path\n\n# Add the app directory to the path\nsys.path.insert(0, str(Path(__file__).parent / \"app\"))\n\nfrom app.storage.migrations import migration_manager\nfrom app.storage.database import wait_for_database\n\n\nasync def cmd_status():\n \"\"\"Show migration status.\"\"\"\n print(\"Checking migration status...\")\n\n try:\n await wait_for_database()\n status = await migration_manager.get_migration_status()\n\n print(f\"\\nDatabase Migration Status:\")\n print(f\" Current Version: {status['current_version']}\")\n print(f\" Latest Version: {status['latest_version']}\")\n print(f\" Applied: {status['applied_count']} migrations\")\n print(f\" Pending: {status['pending_count']} migrations\")\n\n if status[\"applied_migrations\"]:\n print(f\"\\nApplied Migrations:\")\n for migration in status[\"applied_migrations\"]:\n print(\n f\" {migration['version']:04d}: {migration['name']} (applied {migration['applied_at']})\"\n )\n\n if status[\"pending_migrations\"]:\n print(f\"\\nPending Migrations:\")\n for migration in status[\"pending_migrations\"]:\n print(f\" {migration['version']:04d}: {migration['name']}\")\n else:\n print(\"\\n✅ Database schema is up to date!\")\n\n except Exception as e:\n print(f\"❌ Error checking migration status: {e}\")\n sys.exit(1)\n\n\nasync def cmd_up(target_version: int = None):\n \"\"\"Apply pending migrations.\"\"\"\n print(\"Applying migrations...\")\n\n try:\n await wait_for_database()\n\n if target_version:\n print(f\"Migrating to version {target_version}\")\n else:\n print(\"Migrating to latest version\")\n\n success = await migration_manager.migrate_up(target_version)\n\n if success:\n print(\"✅ Migrations applied successfully!\")\n else:\n print(\"❌ Migration failed!\")\n sys.exit(1)\n\n except Exception as e:\n print(f\"❌ Error applying migrations: {e}\")\n sys.exit(1)\n\n\nasync def cmd_down(target_version: int):\n \"\"\"Rollback migrations.\"\"\"\n print(f\"Rolling back to version {target_version}...\")\n\n try:\n await wait_for_database()\n\n # Confirm dangerous operation\n current_version = await migration_manager.get_current_version()\n if target_version >= current_version:\n print(\n f\"Target version {target_version} is not lower than current version {current_version}\"\n )\n return\n\n response = input(\n f\"⚠️ This will rollback {current_version - target_version} migration(s). Continue? (y/N): \"\n )\n if response.lower() != \"y\":\n print(\"Rollback cancelled\")\n return\n\n success = await migration_manager.migrate_down(target_version)\n\n if success:\n print(\"✅ Rollback completed successfully!\")\n else:\n print(\"❌ Rollback failed!\")\n sys.exit(1)\n\n except Exception as e:\n print(f\"❌ Error rolling back migrations: {e}\")\n sys.exit(1)\n\n\nasync def cmd_list():\n \"\"\"List all available migrations.\"\"\"\n print(\"Available migrations:\")\n\n try:\n await wait_for_database()\n applied_migrations = {\n m[\"version\"] for m in await migration_manager.get_applied_migrations()\n }\n\n for migration in migration_manager.list_migrations():\n status = \"✅\" if migration.version in applied_migrations else \"⏳\"\n print(f\" {status} {migration.version:04d}: {migration.name}\")\n\n except Exception as e:\n print(f\"❌ Error listing migrations: {e}\")\n sys.exit(1)\n\n\nasync def cmd_create(name: str):\n \"\"\"Create a new migration template.\"\"\"\n print(f\"Creating migration: {name}\")\n\n try:\n # Get current max version\n migrations = migration_manager.list_migrations()\n next_version = max(m.version for m in migrations) + 1 if migrations else 1\n\n # Create migration template\n template = f'''\"\"\"Migration {next_version:04d}: {name}\"\"\"\nfrom app.storage.migrations import Migration\n\n# Define your migration\nmigration = Migration(\n version={next_version},\n name=\"{name}\",\n up_sql=\"\"\"\n -- Migration {next_version:04d}: {name}\n -- Add your schema changes here\n \n \"\"\",\n down_sql=\"\"\"\n -- Rollback for migration {next_version:04d}: {name}\n -- Add rollback statements here\n \n \"\"\"\n)\n'''\n\n # Save to migrations directory\n migrations_dir = Path(__file__).parent / \"migrations\"\n migrations_dir.mkdir(exist_ok=True)\n\n migration_file = (\n migrations_dir / f\"{next_version:04d}_{name.replace(' ', '_').replace('-', '_')}.py\"\n )\n\n with open(migration_file, \"w\") as f:\n f.write(template)\n\n print(f\"✅ Created migration: {migration_file}\")\n print(f\" Edit the file and then register it in migrations.py\")\n\n except Exception as e:\n print(f\"❌ Error creating migration: {e}\")\n sys.exit(1)\n\n\nasync def main():\n \"\"\"Main CLI entry point.\"\"\"\n parser = argparse.ArgumentParser(description=\"Database migration manager for metrics service\")\n subparsers = parser.add_subparsers(dest=\"command\", help=\"Available commands\")\n\n # Status command\n status_parser = subparsers.add_parser(\"status\", help=\"Show migration status\")\n\n # Up command\n up_parser = subparsers.add_parser(\"up\", help=\"Apply pending migrations\")\n up_parser.add_argument(\"--to\", type=int, help=\"Target version (default: latest)\")\n\n # Down command\n down_parser = subparsers.add_parser(\"down\", help=\"Rollback migrations\")\n down_parser.add_argument(\"to\", type=int, help=\"Target version\")\n\n # List command\n list_parser = subparsers.add_parser(\"list\", help=\"List all migrations\")\n\n # Create command\n create_parser = subparsers.add_parser(\"create\", help=\"Create new migration\")\n create_parser.add_argument(\"name\", help=\"Migration name\")\n\n args = parser.parse_args()\n\n if not args.command:\n parser.print_help()\n return\n\n try:\n if args.command == \"status\":\n await cmd_status()\n elif args.command == \"up\":\n await cmd_up(args.to)\n elif args.command == \"down\":\n await cmd_down(args.to)\n elif args.command == \"list\":\n await cmd_list()\n elif args.command == \"create\":\n await cmd_create(args.name)\n else:\n parser.print_help()\n\n except KeyboardInterrupt:\n print(\"\\n⚠️ Operation cancelled by user\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "metrics-service/pyproject.toml", "content": "[project]\nname = \"mcp-metrics-service\"\nversion = \"1.0.0\"\ndescription = \"Centralized metrics collection service for MCP Gateway Registry\"\nauthors = [{name = \"MCP Gateway Registry\", email = \"noreply@example.com\"}]\nrequires-python = \">=3.14\"\ndependencies = [\n \"fastapi>=0.104.0\",\n \"uvicorn[standard]>=0.24.0\",\n \"pydantic>=2.5.0\",\n \"aiosqlite>=0.19.0\",\n \"httpx>=0.25.0\",\n \"opentelemetry-api>=1.20.0\",\n \"opentelemetry-sdk>=1.20.0\",\n \"opentelemetry-exporter-prometheus>=0.45b0\",\n \"opentelemetry-exporter-otlp>=1.20.0\",\n \"python-multipart>=0.0.26\",\n]\n\n[project.optional-dependencies]\ndev = [\n \"pytest>=9.0.3\",\n \"pytest-asyncio>=0.21.0\",\n \"pytest-mock>=3.11.0\",\n \"pytest-cov>=4.1.0\",\n \"httpx>=0.25.0\",\n \"black>=23.0.0\",\n \"isort>=5.12.0\",\n \"mypy>=1.5.0\",\n]\ntest = [\n \"pytest>=9.0.3\",\n \"pytest-asyncio>=0.21.0\",\n \"pytest-mock>=3.11.0\",\n \"pytest-cov>=4.1.0\",\n \"httpx>=0.25.0\",\n]\n\n[build-system]\nrequires = [\"setuptools>=61.0\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[tool.black]\nline-length = 88\ntarget-version = ['py311']\n\n[tool.isort]\nprofile = \"black\"\nline_length = 88\n\n[tool.mypy]\npython_version = \"3.14\"\nwarn_return_any = true\nwarn_unused_configs = true\ndisallow_untyped_defs = true\n\n[tool.ruff]\nline-length = 100\ntarget-version = \"py311\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"W\", \"F\", \"I\", \"B\", \"C4\", \"UP\"]\nignore = [\"E501\", \"B008\", \"B904\", \"B019\", \"C401\", \"B007\", \"E402\", \"F841\", \"F823\", \"E722\", \"F811\", \"W293\", \"W291\", \"F821\", \"I001\", \"F401\", \"F541\", \"W292\", \"UP035\", \"UP045\", \"UP006\", \"UP017\"]\n\n[tool.ruff.format]\nquote-style = \"double\"\nindent-style = \"space\"\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\nasyncio_default_fixture_loop_scope = \"function\"\n\n[tool.uv]\n# Local-only project - never resolve from PyPI\npackage = false" }, { "path": "metrics-service/pytest.ini", "content": "[pytest]\nminversion = 7.4\naddopts = -ra -q --strict-markers\ntestpaths = tests\npython_files = test_*.py\npython_classes = Test*\npython_functions = test_*\nmarkers =\n asyncio: marks tests as async (deferred)\nasyncio_mode = auto\nasyncio_default_fixture_loop_scope = function\n" }, { "path": "metrics-service/tests/__init__.py", "content": "" }, { "path": "metrics-service/tests/conftest.py", "content": "\"\"\"Test configuration and fixtures.\"\"\"\n\nimport pytest\nimport asyncio\nimport tempfile\nimport os\nfrom pathlib import Path\nfrom unittest.mock import AsyncMock, MagicMock\n\n# Import the app modules\nimport sys\n\nsys.path.insert(0, str(Path(__file__).parent.parent))\n\nfrom app.config import Settings\nfrom app.storage.database import init_database, MetricsStorage\nfrom app.core.models import MetricType, Metric, MetricRequest\nfrom app.utils.helpers import hash_api_key\nfrom datetime import datetime\n\n\n@pytest.fixture(scope=\"session\")\ndef event_loop():\n \"\"\"Create an instance of the default event loop for the test session.\"\"\"\n loop = asyncio.get_event_loop_policy().new_event_loop()\n yield loop\n loop.close()\n\n\n@pytest.fixture\ndef temp_db():\n \"\"\"Create a temporary database for testing.\"\"\"\n with tempfile.NamedTemporaryFile(suffix=\".db\", delete=False) as tmp:\n db_path = tmp.name\n\n # Override the settings to use temp database\n original_db_path = Settings.SQLITE_DB_PATH\n Settings.SQLITE_DB_PATH = db_path\n\n yield db_path\n\n # Cleanup\n Settings.SQLITE_DB_PATH = original_db_path\n try:\n os.unlink(db_path)\n except FileNotFoundError:\n pass\n\n\n@pytest.fixture\nasync def initialized_db(temp_db):\n \"\"\"Initialize a temporary database with schema.\"\"\"\n await init_database()\n return temp_db\n\n\n@pytest.fixture\ndef test_settings():\n \"\"\"Test settings configuration.\"\"\"\n return Settings(\n SQLITE_DB_PATH=\"/tmp/test_metrics.db\",\n OTEL_PROMETHEUS_ENABLED=False,\n OTEL_OTLP_ENDPOINT=None,\n METRICS_RATE_LIMIT=100,\n BATCH_SIZE=10,\n )\n\n\n@pytest.fixture\ndef sample_metric():\n \"\"\"Sample metric for testing.\"\"\"\n return Metric(\n type=MetricType.AUTH_REQUEST,\n timestamp=datetime(2024, 1, 15, 10, 30, 0),\n value=1.0,\n duration_ms=45.2,\n dimensions={\n \"method\": \"jwt\",\n \"success\": True,\n \"server\": \"mcpgw\",\n \"user_hash\": \"user_abc123\",\n },\n metadata={\"error_code\": None, \"request_size\": 1024, \"response_size\": 512},\n )\n\n\n@pytest.fixture\ndef sample_metric_request(sample_metric):\n \"\"\"Sample metric request for testing.\"\"\"\n return MetricRequest(\n service=\"auth-server\", version=\"1.0.0\", instance_id=\"auth-01\", metrics=[sample_metric]\n )\n\n\n@pytest.fixture\ndef test_api_key():\n \"\"\"Test API key and its hash.\"\"\"\n api_key = \"test_api_key_12345\"\n key_hash = hash_api_key(api_key)\n return {\"key\": api_key, \"hash\": key_hash, \"service\": \"test-service\"}\n\n\n@pytest.fixture\nasync def storage_with_api_key(initialized_db, test_api_key):\n \"\"\"Storage instance with a test API key inserted.\"\"\"\n storage = MetricsStorage()\n\n # Insert test API key\n await storage.create_api_key(test_api_key[\"hash\"], test_api_key[\"service\"])\n\n return storage, test_api_key\n\n\n@pytest.fixture\ndef mock_otel_instruments():\n \"\"\"Mock OpenTelemetry instruments.\"\"\"\n mock_instruments = MagicMock()\n mock_instruments.auth_counter = MagicMock()\n mock_instruments.auth_histogram = MagicMock()\n mock_instruments.discovery_counter = MagicMock()\n mock_instruments.discovery_histogram = MagicMock()\n mock_instruments.tool_counter = MagicMock()\n mock_instruments.tool_histogram = MagicMock()\n return mock_instruments\n" }, { "path": "metrics-service/tests/test_api.py", "content": "\"\"\"Tests for API endpoints.\"\"\"\n\nimport pytest\nimport json\nfrom unittest.mock import AsyncMock, patch\nfrom fastapi.testclient import TestClient\n\nfrom app.main import app\nfrom app.core.models import MetricType, Metric, MetricRequest\nfrom app.utils.helpers import hash_api_key\n\n\n@pytest.fixture\ndef client():\n \"\"\"Test client for API endpoints.\"\"\"\n return TestClient(app)\n\n\n@pytest.fixture\ndef valid_metric_request():\n \"\"\"Valid metric request payload.\"\"\"\n return {\n \"service\": \"auth-server\",\n \"version\": \"1.0.0\",\n \"instance_id\": \"auth-01\",\n \"metrics\": [\n {\n \"type\": \"auth_request\",\n \"value\": 1.0,\n \"duration_ms\": 45.2,\n \"dimensions\": {\n \"method\": \"jwt\",\n \"success\": True,\n \"server\": \"mcpgw\",\n \"user_hash\": \"user_abc123\",\n },\n \"metadata\": {\"error_code\": None, \"request_size\": 1024, \"response_size\": 512},\n }\n ],\n }\n\n\nclass TestHealthEndpoints:\n \"\"\"Test health and info endpoints.\"\"\"\n\n def test_health_endpoint(self, client):\n \"\"\"Test health check endpoint.\"\"\"\n response = client.get(\"/health\")\n assert response.status_code == 200\n assert response.json() == {\"status\": \"healthy\", \"service\": \"metrics-collection\"}\n\n def test_root_endpoint(self, client):\n \"\"\"Test root info endpoint.\"\"\"\n response = client.get(\"/\")\n assert response.status_code == 200\n data = response.json()\n assert data[\"service\"] == \"MCP Metrics Collection Service\"\n assert data[\"version\"] == \"1.0.0\"\n assert data[\"status\"] == \"running\"\n assert \"endpoints\" in data\n\n\nclass TestMetricsEndpoint:\n \"\"\"Test metrics collection endpoint.\"\"\"\n\n def test_metrics_without_api_key(self, client, valid_metric_request):\n \"\"\"Test metrics endpoint without API key.\"\"\"\n response = client.post(\"/metrics\", json=valid_metric_request)\n assert response.status_code == 401\n assert \"API key required\" in response.json()[\"detail\"]\n\n @patch(\"app.api.auth.MetricsStorage\")\n def test_metrics_with_invalid_api_key(self, mock_storage_class, client, valid_metric_request):\n \"\"\"Test metrics endpoint with invalid API key.\"\"\"\n # Mock storage to return None for key lookup (key not found)\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = None\n mock_storage_class.return_value = mock_storage\n\n headers = {\"X-API-Key\": \"invalid_key\"}\n response = client.post(\"/metrics\", json=valid_metric_request, headers=headers)\n assert response.status_code == 401\n assert \"Invalid API key\" in response.json()[\"detail\"]\n\n @patch(\"app.api.auth.MetricsStorage\")\n @patch(\"app.api.routes.MetricsProcessor\")\n def test_metrics_with_valid_api_key(\n self, mock_processor_class, mock_storage_class, client, valid_metric_request\n ):\n \"\"\"Test metrics endpoint with valid API key.\"\"\"\n # Mock storage for API key validation\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n \"last_used_at\": None,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n # Mock processor for metrics processing\n mock_processor = AsyncMock()\n mock_result = AsyncMock()\n mock_result.accepted = 1\n mock_result.rejected = 0\n mock_result.errors = []\n mock_processor.process_metrics.return_value = mock_result\n mock_processor_class.return_value = mock_processor\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n response = client.post(\"/metrics\", json=valid_metric_request, headers=headers)\n\n assert response.status_code == 200\n data = response.json()\n assert data[\"status\"] == \"success\"\n assert data[\"accepted\"] == 1\n assert data[\"rejected\"] == 0\n assert data[\"errors\"] == []\n assert \"request_id\" in data\n\n @patch(\"app.api.auth.MetricsStorage\")\n def test_metrics_with_invalid_payload(self, mock_storage_class, client):\n \"\"\"Test metrics endpoint with invalid payload.\"\"\"\n # Mock storage to allow auth to pass\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n invalid_payload = {\"invalid\": \"payload\"}\n\n response = client.post(\"/metrics\", json=invalid_payload, headers=headers)\n assert response.status_code == 422 # Validation error\n\n @patch(\"app.api.auth.MetricsStorage\")\n def test_metrics_with_missing_required_fields(self, mock_storage_class, client):\n \"\"\"Test metrics endpoint with missing required fields.\"\"\"\n # Mock storage to allow auth to pass\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n invalid_payload = {\n \"service\": \"test-service\",\n # Missing metrics array\n }\n\n response = client.post(\"/metrics\", json=invalid_payload, headers=headers)\n assert response.status_code == 422 # Validation error\n\n @patch(\"app.api.auth.MetricsStorage\")\n def test_metrics_with_invalid_metric_type(self, mock_storage_class, client):\n \"\"\"Test metrics endpoint with invalid metric type.\"\"\"\n # Mock storage to allow auth to pass\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n invalid_payload = {\n \"service\": \"test-service\",\n \"metrics\": [\n {\n \"type\": \"invalid_type\", # Invalid metric type\n \"value\": 1.0,\n }\n ],\n }\n\n response = client.post(\"/metrics\", json=invalid_payload, headers=headers)\n assert response.status_code == 422 # Validation error\n\n @patch(\"app.api.auth.MetricsStorage\")\n @patch(\"app.api.routes.processor\")\n def test_metrics_processor_error(\n self, mock_processor, mock_storage_class, client, valid_metric_request\n ):\n \"\"\"Test metrics endpoint when processor raises an error.\"\"\"\n # Mock storage for API key validation\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n \"last_used_at\": None,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n # Mock processor's process_metrics to raise an error\n mock_processor.process_metrics = AsyncMock(side_effect=Exception(\"Processing error\"))\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n response = client.post(\"/metrics\", json=valid_metric_request, headers=headers)\n\n assert response.status_code == 500\n assert \"Internal server error\" in response.json()[\"detail\"]\n\n @patch(\"app.api.auth.MetricsStorage\")\n @patch(\"app.api.routes.MetricsProcessor\")\n def test_metrics_with_multiple_metrics(self, mock_processor_class, mock_storage_class, client):\n \"\"\"Test metrics endpoint with multiple metrics in one request.\"\"\"\n # Mock storage for API key validation\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n # Mock processor for metrics processing\n mock_processor = AsyncMock()\n mock_result = AsyncMock()\n mock_result.accepted = 3\n mock_result.rejected = 0\n mock_result.errors = []\n mock_processor.process_metrics.return_value = mock_result\n mock_processor_class.return_value = mock_processor\n\n payload = {\n \"service\": \"multi-service\",\n \"metrics\": [\n {\"type\": \"auth_request\", \"value\": 1.0, \"dimensions\": {\"success\": True}},\n {\"type\": \"tool_discovery\", \"value\": 1.0, \"dimensions\": {\"query\": \"test\"}},\n {\"type\": \"tool_execution\", \"value\": 1.0, \"dimensions\": {\"tool_name\": \"calculator\"}},\n ],\n }\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n response = client.post(\"/metrics\", json=payload, headers=headers)\n assert response.status_code == 200\n data = response.json()\n assert data[\"accepted\"] == 3\n assert data[\"rejected\"] == 0\n\n\nclass TestFlushEndpoint:\n \"\"\"Test metrics flush endpoint.\"\"\"\n\n def test_flush_without_api_key(self, client):\n \"\"\"Test flush endpoint without API key.\"\"\"\n response = client.post(\"/flush\")\n assert response.status_code == 401\n assert \"API key required\" in response.json()[\"detail\"]\n\n @patch(\"app.api.auth.MetricsStorage\")\n @patch(\"app.api.routes.MetricsProcessor\")\n def test_flush_with_valid_api_key(self, mock_processor_class, mock_storage_class, client):\n \"\"\"Test flush endpoint with valid API key.\"\"\"\n # Mock storage for API key validation\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n \"last_used_at\": None,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n # Mock processor for flush\n mock_processor = AsyncMock()\n mock_processor.force_flush.return_value = None\n mock_processor_class.return_value = mock_processor\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n response = client.post(\"/flush\", headers=headers)\n\n assert response.status_code == 200\n data = response.json()\n assert data[\"status\"] == \"success\"\n assert \"flushed\" in data[\"message\"]\n" }, { "path": "metrics-service/tests/test_auth.py", "content": "\"\"\"Tests for API authentication.\"\"\"\n\nimport pytest\nfrom unittest.mock import AsyncMock, patch\nfrom fastapi import HTTPException\nfrom fastapi.testclient import TestClient\n\nfrom app.api.auth import verify_api_key\nfrom app.utils.helpers import hash_api_key\nfrom app.main import app\n\n\nclass TestAPIKeyVerification:\n \"\"\"Test API key verification logic.\"\"\"\n\n @patch(\"app.api.auth.MetricsStorage\")\n async def test_verify_valid_api_key(self, mock_storage_class):\n \"\"\"Test verification of valid API key.\"\"\"\n # Mock storage\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n \"last_used_at\": None,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n # Mock request with API key header\n from unittest.mock import MagicMock\n\n mock_request = MagicMock()\n mock_request.headers = {\"X-API-Key\": \"test_key_123\"}\n\n result = await verify_api_key(mock_request)\n\n assert result == \"test-service\"\n mock_storage.get_api_key.assert_called_once_with(hash_api_key(\"test_key_123\"))\n mock_storage.update_api_key_usage.assert_called_once()\n\n @patch(\"app.api.auth.MetricsStorage\")\n async def test_verify_missing_api_key(self, mock_storage_class):\n \"\"\"Test verification when API key is missing.\"\"\"\n from unittest.mock import MagicMock\n\n mock_request = MagicMock()\n mock_request.headers = {} # No API key header\n\n with pytest.raises(HTTPException) as exc_info:\n await verify_api_key(mock_request)\n\n assert exc_info.value.status_code == 401\n assert \"API key required\" in str(exc_info.value.detail)\n\n @patch(\"app.api.auth.MetricsStorage\")\n async def test_verify_invalid_api_key(self, mock_storage_class):\n \"\"\"Test verification of invalid API key.\"\"\"\n # Mock storage to return None (key not found)\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = None\n mock_storage_class.return_value = mock_storage\n\n from unittest.mock import MagicMock\n\n mock_request = MagicMock()\n mock_request.headers = {\"X-API-Key\": \"invalid_key\"}\n\n with pytest.raises(HTTPException) as exc_info:\n await verify_api_key(mock_request)\n\n assert exc_info.value.status_code == 401\n assert \"Invalid API key\" in str(exc_info.value.detail)\n\n @patch(\"app.api.auth.MetricsStorage\")\n async def test_verify_inactive_api_key(self, mock_storage_class):\n \"\"\"Test verification of inactive API key.\"\"\"\n # Mock storage to return inactive key\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": False, # Inactive\n \"rate_limit\": 1000,\n \"last_used_at\": None,\n }\n mock_storage_class.return_value = mock_storage\n\n from unittest.mock import MagicMock\n\n mock_request = MagicMock()\n mock_request.headers = {\"X-API-Key\": \"inactive_key\"}\n\n with pytest.raises(HTTPException) as exc_info:\n await verify_api_key(mock_request)\n\n assert exc_info.value.status_code == 401\n assert \"API key is inactive\" in str(exc_info.value.detail)\n\n @patch(\"app.api.auth.MetricsStorage\")\n async def test_verify_api_key_updates_usage(self, mock_storage_class):\n \"\"\"Test that API key verification updates usage timestamp.\"\"\"\n # Mock storage\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1000,\n \"last_used_at\": \"2024-01-01T00:00:00\",\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n from unittest.mock import MagicMock\n\n mock_request = MagicMock()\n mock_request.headers = {\"X-API-Key\": \"test_key_123\"}\n\n result = await verify_api_key(mock_request)\n\n # Verify usage was updated with correct key hash\n expected_hash = hash_api_key(\"test_key_123\")\n mock_storage.update_api_key_usage.assert_called_once_with(expected_hash)\n\n\nclass TestAPIKeyHashingHelpers:\n \"\"\"Test API key hashing helper functions.\"\"\"\n\n def test_hash_api_key_consistency(self):\n \"\"\"Test that hashing the same key produces consistent results.\"\"\"\n key = \"test_key_12345\"\n hash1 = hash_api_key(key)\n hash2 = hash_api_key(key)\n\n assert hash1 == hash2\n assert len(hash1) == 64 # SHA256 hex length\n\n def test_hash_different_keys_produce_different_hashes(self):\n \"\"\"Test that different keys produce different hashes.\"\"\"\n key1 = \"test_key_1\"\n key2 = \"test_key_2\"\n\n hash1 = hash_api_key(key1)\n hash2 = hash_api_key(key2)\n\n assert hash1 != hash2\n\n def test_hash_empty_string(self):\n \"\"\"Test hashing empty string.\"\"\"\n hash_result = hash_api_key(\"\")\n assert len(hash_result) == 64\n assert hash_result == \"8fce0c4373343f1d2652389a9d3b0e9d9997b4f701063df5582a0b894700f439\"\n\n\nclass TestAuthenticationIntegration:\n \"\"\"Test authentication integration with API endpoints.\"\"\"\n\n @patch(\"app.api.auth.MetricsStorage\")\n def test_metrics_endpoint_auth_integration(self, mock_storage_class):\n \"\"\"Test that metrics endpoint properly integrates with auth.\"\"\"\n # Mock storage to return None for key lookup (key not found)\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = None\n mock_storage_class.return_value = mock_storage\n\n client = TestClient(app)\n\n # Test without API key\n response = client.post(\"/metrics\", json={\"service\": \"test\", \"metrics\": []})\n assert response.status_code == 401\n\n # Test with invalid API key\n headers = {\"X-API-Key\": \"invalid_key\"}\n response = client.post(\"/metrics\", json={\"service\": \"test\", \"metrics\": []}, headers=headers)\n assert response.status_code == 401\n\n @patch(\"app.api.auth.MetricsStorage\")\n def test_flush_endpoint_auth_integration(self, mock_storage_class):\n \"\"\"Test that flush endpoint properly integrates with auth.\"\"\"\n # Mock storage to return None for key lookup (key not found)\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = None\n mock_storage_class.return_value = mock_storage\n\n client = TestClient(app)\n\n # Test without API key\n response = client.post(\"/flush\")\n assert response.status_code == 401\n\n # Test with invalid API key\n headers = {\"X-API-Key\": \"invalid_key\"}\n response = client.post(\"/flush\", headers=headers)\n assert response.status_code == 401\n\n def test_health_endpoint_no_auth_required(self):\n \"\"\"Test that health endpoint doesn't require authentication.\"\"\"\n client = TestClient(app)\n\n response = client.get(\"/health\")\n assert response.status_code == 200\n\n def test_root_endpoint_no_auth_required(self):\n \"\"\"Test that root endpoint doesn't require authentication.\"\"\"\n client = TestClient(app)\n\n response = client.get(\"/\")\n assert response.status_code == 200\n\n\nclass TestSecurityBestPractices:\n \"\"\"Test security best practices in authentication.\"\"\"\n\n @patch(\"app.api.auth.MetricsStorage\")\n async def test_api_key_not_logged_in_error_messages(self, mock_storage_class):\n \"\"\"Test that API keys are not exposed in error messages.\"\"\"\n # Mock storage to return None (key not found)\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = None\n mock_storage_class.return_value = mock_storage\n\n from unittest.mock import MagicMock\n\n mock_request = MagicMock()\n mock_request.headers = {\"X-API-Key\": \"secret_key_should_not_appear_in_logs\"}\n\n with pytest.raises(HTTPException) as exc_info:\n await verify_api_key(mock_request)\n\n # Error message should not contain the actual API key\n error_detail = str(exc_info.value.detail)\n assert \"secret_key_should_not_appear_in_logs\" not in error_detail\n\n @patch(\"app.api.auth.MetricsStorage\")\n async def test_api_key_hashed_before_storage_lookup(self, mock_storage_class):\n \"\"\"Test that API key is hashed before database lookup.\"\"\"\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = None # Will cause auth failure\n mock_storage_class.return_value = mock_storage\n\n from unittest.mock import MagicMock\n\n mock_request = MagicMock()\n api_key = \"plaintext_key_123\"\n mock_request.headers = {\"X-API-Key\": api_key}\n\n try:\n await verify_api_key(mock_request)\n except HTTPException:\n pass # Expected to fail\n\n # Verify storage was called with hashed key, not plaintext\n expected_hash = hash_api_key(api_key)\n mock_storage.get_api_key.assert_called_once_with(expected_hash)\n\n # Verify plaintext key was not passed to storage\n call_args = mock_storage.get_api_key.call_args[0][0]\n assert call_args != api_key\n assert call_args == expected_hash\n" }, { "path": "metrics-service/tests/test_database.py", "content": "\"\"\"Tests for database storage layer.\"\"\"\n\nimport pytest\nimport asyncio\nimport json\nfrom datetime import datetime\n\nfrom app.storage.database import init_database, MetricsStorage, wait_for_database\nfrom app.core.models import MetricType, Metric, MetricRequest\nfrom app.utils.helpers import hash_api_key\n\n\nclass TestDatabaseInitialization:\n \"\"\"Test database initialization and schema creation.\"\"\"\n\n async def test_wait_for_database_success(self, temp_db):\n \"\"\"Test successful database connection.\"\"\"\n # Should succeed without raising an exception\n await wait_for_database(max_retries=1, delay=0.1)\n\n async def test_init_database_succeeds(self, temp_db):\n \"\"\"Test that init_database runs without errors.\"\"\"\n # Should not raise any exceptions\n await init_database()\n\n # Verify we can create a storage instance\n storage = MetricsStorage()\n assert storage is not None\n\n\nclass TestAPIKeyManagement:\n \"\"\"Test API key storage and validation.\"\"\"\n\n async def test_create_api_key(self, initialized_db):\n \"\"\"Test creating a new API key.\"\"\"\n storage = MetricsStorage()\n key_hash = hash_api_key(\"test_key_123\")\n\n result = await storage.create_api_key(key_hash, \"test-service\")\n assert result is True\n\n # Verify key was stored\n key_info = await storage.get_api_key(key_hash)\n assert key_info is not None\n assert key_info[\"service_name\"] == \"test-service\"\n assert key_info[\"is_active\"] is True\n\n async def test_get_api_key_nonexistent(self, initialized_db):\n \"\"\"Test retrieving a non-existent API key.\"\"\"\n storage = MetricsStorage()\n result = await storage.get_api_key(\"nonexistent_hash\")\n assert result is None\n\n async def test_update_api_key_usage(self, storage_with_api_key):\n \"\"\"Test updating API key last usage timestamp.\"\"\"\n storage, api_key_info = storage_with_api_key\n\n # Get initial state\n initial_info = await storage.get_api_key(api_key_info[\"hash\"])\n initial_last_used = initial_info[\"last_used_at\"]\n\n # Update usage\n await storage.update_api_key_usage(api_key_info[\"hash\"])\n\n # Check that last_used_at was updated\n updated_info = await storage.get_api_key(api_key_info[\"hash\"])\n assert updated_info[\"last_used_at\"] != initial_last_used\n\n\nclass TestMetricsStorage:\n \"\"\"Test metrics storage functionality.\"\"\"\n\n async def test_store_single_metric_batch(self, initialized_db, sample_metric_request):\n \"\"\"Test storing a single metric in a batch.\"\"\"\n storage = MetricsStorage()\n\n metrics_batch = [\n {\n \"metric\": sample_metric_request.metrics[0],\n \"request\": sample_metric_request,\n \"request_id\": \"test_req_123\",\n }\n ]\n\n # Should not raise an exception\n await storage.store_metrics_batch(metrics_batch)\n\n # Test passes if no exception is raised - we can't verify internal state\n # without exposing unauthorized database access\n\n async def test_store_empty_batch(self, initialized_db):\n \"\"\"Test storing an empty metrics batch.\"\"\"\n storage = MetricsStorage()\n\n # Should handle empty batch gracefully\n await storage.store_metrics_batch([])\n\n # Test passes if no exception is raised\n\n async def test_store_multiple_metrics_batch(self, initialized_db):\n \"\"\"Test storing multiple metrics in a single batch.\"\"\"\n storage = MetricsStorage()\n\n auth_metric = Metric(\n type=MetricType.AUTH_REQUEST,\n value=1.0,\n duration_ms=100.0,\n dimensions={\"success\": True, \"method\": \"oauth\"},\n )\n\n tool_metric = Metric(\n type=MetricType.TOOL_EXECUTION,\n value=1.0,\n duration_ms=200.0,\n dimensions={\"tool_name\": \"calculator\", \"success\": True},\n )\n\n request = MetricRequest(service=\"multi-service\", metrics=[auth_metric, tool_metric])\n\n metrics_batch = [\n {\"metric\": auth_metric, \"request\": request, \"request_id\": \"batch_1\"},\n {\"metric\": tool_metric, \"request\": request, \"request_id\": \"batch_1\"},\n ]\n\n # Should store both metrics without raising exceptions\n await storage.store_metrics_batch(metrics_batch)\n\n async def test_store_discovery_metric(self, initialized_db):\n \"\"\"Test storing discovery metrics.\"\"\"\n storage = MetricsStorage()\n\n discovery_metric = Metric(\n type=MetricType.TOOL_DISCOVERY,\n value=1.0,\n duration_ms=50.2,\n dimensions={\n \"query\": \"search tools\",\n \"results_count\": 25,\n \"top_k_services\": 10,\n \"top_n_tools\": 50,\n },\n metadata={\"embedding_time_ms\": 15.3, \"faiss_search_time_ms\": 12.1},\n )\n\n request = MetricRequest(\n service=\"registry-service\", version=\"1.0.0\", metrics=[discovery_metric]\n )\n\n metrics_batch = [\n {\"metric\": discovery_metric, \"request\": request, \"request_id\": \"test_req_discovery\"}\n ]\n\n # Should store discovery metric without exceptions\n await storage.store_metrics_batch(metrics_batch)\n" }, { "path": "metrics-service/tests/test_migrations.py", "content": "\"\"\"Tests for database migration system.\"\"\"\n\nimport pytest\nimport tempfile\nimport os\nimport aiosqlite\nfrom unittest.mock import patch, AsyncMock\nfrom pathlib import Path\n\nfrom app.storage.migrations import Migration, MigrationManager\n\n\nclass TestMigration:\n \"\"\"Test Migration class.\"\"\"\n\n def test_migration_creation(self):\n \"\"\"Test creating a Migration object.\"\"\"\n migration = Migration(\n version=1,\n name=\"test_migration\",\n up_sql=\"CREATE TABLE test (id INTEGER);\",\n down_sql=\"DROP TABLE test;\",\n )\n\n assert migration.version == 1\n assert migration.name == \"test_migration\"\n assert migration.up_sql == \"CREATE TABLE test (id INTEGER);\"\n assert migration.down_sql == \"DROP TABLE test;\"\n assert str(migration) == \"Migration 0001: test_migration\"\n\n def test_migration_with_python_functions(self):\n \"\"\"Test migration with Python functions.\"\"\"\n\n async def python_up(db):\n pass\n\n async def python_down(db):\n pass\n\n migration = Migration(\n version=2,\n name=\"python_migration\",\n up_sql=\"\",\n python_up=python_up,\n python_down=python_down,\n )\n\n assert migration.python_up is not None\n assert migration.python_down is not None\n\n\nclass TestMigrationManager:\n \"\"\"Test MigrationManager class.\"\"\"\n\n @pytest.fixture\n def temp_db(self):\n \"\"\"Create a temporary database file.\"\"\"\n fd, path = tempfile.mkstemp(suffix=\".db\")\n os.close(fd)\n yield path\n os.unlink(path)\n\n @pytest.fixture\n def migration_manager(self, temp_db):\n \"\"\"Create a migration manager with temp database.\"\"\"\n return MigrationManager(db_path=temp_db)\n\n @pytest.mark.asyncio\n async def test_get_current_version_no_table(self, migration_manager):\n \"\"\"Test getting version when migrations table doesn't exist.\"\"\"\n version = await migration_manager.get_current_version()\n assert version == 0\n\n @pytest.mark.asyncio\n async def test_get_current_version_empty_table(self, migration_manager, temp_db):\n \"\"\"Test getting version from empty migrations table.\"\"\"\n # Create empty migrations table\n async with aiosqlite.connect(temp_db) as db:\n await db.execute(\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n )\n \"\"\")\n await db.commit()\n\n version = await migration_manager.get_current_version()\n assert version == 0\n\n @pytest.mark.asyncio\n async def test_get_current_version_with_data(self, migration_manager, temp_db):\n \"\"\"Test getting version with existing migrations.\"\"\"\n # Setup migrations table with data\n async with aiosqlite.connect(temp_db) as db:\n await db.execute(\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n )\n \"\"\")\n await db.execute(\"\"\"\n INSERT INTO schema_migrations (version, name, applied_at)\n VALUES (1, 'initial', '2024-01-01T00:00:00')\n \"\"\")\n await db.execute(\"\"\"\n INSERT INTO schema_migrations (version, name, applied_at)\n VALUES (2, 'second', '2024-01-01T00:00:01')\n \"\"\")\n await db.commit()\n\n version = await migration_manager.get_current_version()\n assert version == 2\n\n @pytest.mark.asyncio\n async def test_get_applied_migrations(self, migration_manager, temp_db):\n \"\"\"Test getting list of applied migrations.\"\"\"\n # Setup migrations table with data\n async with aiosqlite.connect(temp_db) as db:\n await db.execute(\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n )\n \"\"\")\n await db.execute(\"\"\"\n INSERT INTO schema_migrations (version, name, applied_at)\n VALUES (1, 'initial', '2024-01-01T00:00:00')\n \"\"\")\n await db.commit()\n\n migrations = await migration_manager.get_applied_migrations()\n\n assert len(migrations) == 1\n assert migrations[0][\"version\"] == 1\n assert migrations[0][\"name\"] == \"initial\"\n assert migrations[0][\"applied_at\"] == \"2024-01-01T00:00:00\"\n\n @pytest.mark.asyncio\n async def test_apply_migration_sql_only(self, migration_manager, temp_db):\n \"\"\"Test applying a SQL-only migration.\"\"\"\n migration = Migration(\n version=1,\n name=\"test_migration\",\n up_sql=\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n );\n CREATE TABLE test_table (\n id INTEGER PRIMARY KEY,\n name TEXT NOT NULL\n );\n \"\"\",\n )\n\n success = await migration_manager.apply_migration(migration)\n assert success\n\n # Verify table was created\n async with aiosqlite.connect(temp_db) as db:\n cursor = await db.execute(\"\"\"\n SELECT name FROM sqlite_master \n WHERE type='table' AND name='test_table'\n \"\"\")\n result = await cursor.fetchone()\n assert result is not None\n\n # Verify migration was recorded\n version = await migration_manager.get_current_version()\n assert version == 1\n\n @pytest.mark.asyncio\n async def test_apply_migration_with_python(self, migration_manager, temp_db):\n \"\"\"Test applying migration with Python function.\"\"\"\n python_executed = False\n\n async def python_migration(db):\n nonlocal python_executed\n python_executed = True\n await db.execute(\"INSERT INTO test_data (value) VALUES (?)\", (\"test_value\",))\n\n migration = Migration(\n version=1,\n name=\"python_migration\",\n up_sql=\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n );\n CREATE TABLE test_data (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n value TEXT NOT NULL\n );\n \"\"\",\n python_up=python_migration,\n )\n\n success = await migration_manager.apply_migration(migration)\n assert success\n assert python_executed\n\n # Verify Python function executed\n async with aiosqlite.connect(temp_db) as db:\n cursor = await db.execute(\"SELECT value FROM test_data\")\n result = await cursor.fetchone()\n assert result[0] == \"test_value\"\n\n @pytest.mark.asyncio\n async def test_apply_migration_failure(self, migration_manager):\n \"\"\"Test migration failure handling.\"\"\"\n migration = Migration(version=1, name=\"failing_migration\", up_sql=\"INVALID SQL STATEMENT;\")\n\n success = await migration_manager.apply_migration(migration)\n assert not success\n\n # Verify no migration was recorded\n version = await migration_manager.get_current_version()\n assert version == 0\n\n @pytest.mark.asyncio\n async def test_rollback_migration(self, migration_manager, temp_db):\n \"\"\"Test rolling back a migration.\"\"\"\n # First apply a migration\n up_migration = Migration(\n version=1,\n name=\"test_migration\",\n up_sql=\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n );\n CREATE TABLE test_table (id INTEGER);\n \"\"\",\n down_sql=\"DROP TABLE test_table;\",\n )\n\n await migration_manager.apply_migration(up_migration)\n assert await migration_manager.get_current_version() == 1\n\n # Now rollback\n success = await migration_manager.rollback_migration(up_migration)\n assert success\n\n # Verify table was dropped\n async with aiosqlite.connect(temp_db) as db:\n cursor = await db.execute(\"\"\"\n SELECT name FROM sqlite_master \n WHERE type='table' AND name='test_table'\n \"\"\")\n result = await cursor.fetchone()\n assert result is None\n\n # Verify migration record was removed\n version = await migration_manager.get_current_version()\n assert version == 0\n\n def test_list_migrations(self, migration_manager):\n \"\"\"Test listing all migrations.\"\"\"\n migrations = migration_manager.list_migrations()\n\n # Should have the registered migrations\n assert len(migrations) >= 4 # We registered 4 migrations\n assert all(isinstance(m, Migration) for m in migrations)\n\n # Should be sorted by version\n versions = [m.version for m in migrations]\n assert versions == sorted(versions)\n\n @pytest.mark.asyncio\n async def test_migrate_up_all(self, migration_manager, temp_db):\n \"\"\"Test migrating up to latest version.\"\"\"\n # Mock the registered migrations with simpler ones for testing\n simple_migrations = [\n Migration(\n 1,\n \"first\",\n \"CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, name TEXT, applied_at TEXT);\",\n ),\n Migration(2, \"second\", \"CREATE TABLE table2 (id INTEGER);\"),\n Migration(3, \"third\", \"CREATE TABLE table3 (id INTEGER);\"),\n ]\n\n migration_manager.migrations = simple_migrations\n\n success = await migration_manager.migrate_up()\n assert success\n\n version = await migration_manager.get_current_version()\n assert version == 3\n\n # Verify all tables exist\n async with aiosqlite.connect(temp_db) as db:\n for table_name in [\"schema_migrations\", \"table2\", \"table3\"]:\n cursor = await db.execute(\n \"\"\"\n SELECT name FROM sqlite_master \n WHERE type='table' AND name=?\n \"\"\",\n (table_name,),\n )\n result = await cursor.fetchone()\n assert result is not None, f\"Table {table_name} should exist\"\n\n @pytest.mark.asyncio\n async def test_migrate_up_to_target(self, migration_manager, temp_db):\n \"\"\"Test migrating up to specific target version.\"\"\"\n simple_migrations = [\n Migration(\n 1,\n \"first\",\n \"CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, name TEXT, applied_at TEXT);\",\n ),\n Migration(2, \"second\", \"CREATE TABLE table2 (id INTEGER);\"),\n Migration(3, \"third\", \"CREATE TABLE table3 (id INTEGER);\"),\n ]\n\n migration_manager.migrations = simple_migrations\n\n success = await migration_manager.migrate_up(target_version=2)\n assert success\n\n version = await migration_manager.get_current_version()\n assert version == 2\n\n # Verify only first two tables exist\n async with aiosqlite.connect(temp_db) as db:\n cursor = await db.execute(\"\"\"\n SELECT name FROM sqlite_master \n WHERE type='table' AND name='table3'\n \"\"\")\n result = await cursor.fetchone()\n assert result is None # table3 should not exist\n\n @pytest.mark.asyncio\n async def test_migrate_up_already_current(self, migration_manager, temp_db):\n \"\"\"Test migrate up when already at current version.\"\"\"\n # Setup database at version 1\n async with aiosqlite.connect(temp_db) as db:\n await db.execute(\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n )\n \"\"\")\n await db.execute(\"\"\"\n INSERT INTO schema_migrations (version, name, applied_at)\n VALUES (1, 'test', '2024-01-01T00:00:00')\n \"\"\")\n await db.commit()\n\n # Try to migrate to version 1 (current)\n success = await migration_manager.migrate_up(target_version=1)\n assert success # Should succeed but do nothing\n\n @pytest.mark.asyncio\n async def test_migrate_down(self, migration_manager, temp_db):\n \"\"\"Test migrating down to target version.\"\"\"\n # Setup migrations\n simple_migrations = [\n Migration(\n 1,\n \"first\",\n \"CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, name TEXT, applied_at TEXT);\",\n \"SELECT 'Cannot rollback initial' as error;\",\n ),\n Migration(2, \"second\", \"CREATE TABLE table2 (id INTEGER);\", \"DROP TABLE table2;\"),\n Migration(3, \"third\", \"CREATE TABLE table3 (id INTEGER);\", \"DROP TABLE table3;\"),\n ]\n\n migration_manager.migrations = simple_migrations\n\n # First migrate up to version 3\n await migration_manager.migrate_up()\n assert await migration_manager.get_current_version() == 3\n\n # Now migrate down to version 1\n success = await migration_manager.migrate_down(target_version=1)\n assert success\n\n version = await migration_manager.get_current_version()\n assert version == 1\n\n # Verify tables 2 and 3 were dropped\n async with aiosqlite.connect(temp_db) as db:\n for table_name in [\"table2\", \"table3\"]:\n cursor = await db.execute(\n \"\"\"\n SELECT name FROM sqlite_master \n WHERE type='table' AND name=?\n \"\"\",\n (table_name,),\n )\n result = await cursor.fetchone()\n assert result is None, f\"Table {table_name} should be dropped\"\n\n @pytest.mark.asyncio\n async def test_get_migration_status(self, migration_manager, temp_db):\n \"\"\"Test getting comprehensive migration status.\"\"\"\n # Setup some applied migrations\n async with aiosqlite.connect(temp_db) as db:\n await db.execute(\"\"\"\n CREATE TABLE schema_migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n )\n \"\"\")\n await db.execute(\"\"\"\n INSERT INTO schema_migrations (version, name, applied_at)\n VALUES (1, 'first', '2024-01-01T00:00:00')\n \"\"\")\n await db.commit()\n\n status = await migration_manager.get_migration_status()\n\n assert status[\"current_version\"] == 1\n assert status[\"applied_count\"] == 1\n assert status[\"pending_count\"] > 0 # There should be pending migrations\n assert len(status[\"applied_migrations\"]) == 1\n assert status[\"applied_migrations\"][0][\"name\"] == \"first\"\n assert len(status[\"pending_migrations\"]) > 0\n" }, { "path": "metrics-service/tests/test_processor.py", "content": "\"\"\"Tests for metrics processing logic.\"\"\"\n\nimport pytest\nimport asyncio\nfrom unittest.mock import AsyncMock, MagicMock, patch\n\nfrom app.core.processor import MetricsProcessor, ProcessingResult\nfrom app.core.models import MetricType, Metric, MetricRequest\nfrom datetime import datetime\n\n\nclass TestProcessingResult:\n \"\"\"Test ProcessingResult class.\"\"\"\n\n def test_processing_result_initialization(self):\n \"\"\"Test ProcessingResult initializes correctly.\"\"\"\n result = ProcessingResult()\n assert result.accepted == 0\n assert result.rejected == 0\n assert result.errors == []\n\n def test_processing_result_modification(self):\n \"\"\"Test ProcessingResult can be modified.\"\"\"\n result = ProcessingResult()\n result.accepted = 5\n result.rejected = 2\n result.errors = [\"error1\", \"error2\"]\n\n assert result.accepted == 5\n assert result.rejected == 2\n assert len(result.errors) == 2\n\n\nclass TestMetricsProcessor:\n \"\"\"Test MetricsProcessor class.\"\"\"\n\n @patch(\"app.core.processor.MetricsStorage\")\n def test_processor_initialization(self, mock_storage_class):\n \"\"\"Test processor initializes correctly.\"\"\"\n mock_storage = MagicMock()\n mock_storage_class.return_value = mock_storage\n\n processor = MetricsProcessor()\n assert processor.storage is not None\n assert processor._buffer == []\n assert processor._buffer_lock is not None\n\n @patch(\"app.core.processor.MetricsStorage\")\n def test_processor_initialization_with_otel(self, mock_storage_class):\n \"\"\"Test processor initialization with OpenTelemetry.\"\"\"\n with patch(\"app.otel.instruments.MetricsInstruments\") as mock_otel_class:\n mock_otel = MagicMock()\n mock_otel_class.return_value = mock_otel\n\n processor = MetricsProcessor()\n assert processor.otel is not None\n\n @patch(\"app.core.processor.MetricsStorage\")\n def test_processor_initialization_without_otel(self, mock_storage_class):\n \"\"\"Test processor initialization when OTel is not available.\"\"\"\n with patch.dict(\"sys.modules\", {\"app.otel.instruments\": None}):\n # Temporarily make the import fail\n processor = MetricsProcessor()\n # Note: This test may not work as expected since the module is already imported\n # The processor catches any Exception during OTel init, so otel should be None\n # if the instruments can't be initialized\n pass # Just verify it doesn't crash\n\n\nclass TestMetricValidation:\n \"\"\"Test metric validation logic.\"\"\"\n\n @patch(\"app.core.processor.MetricsStorage\")\n def test_validate_valid_metric(self, mock_storage_class):\n \"\"\"Test validation of valid metric.\"\"\"\n processor = MetricsProcessor()\n\n metric = Metric(type=MetricType.AUTH_REQUEST, value=1.0, duration_ms=100.0)\n\n assert processor._validate_metric(metric) is True\n\n @patch(\"app.core.processor.MetricsStorage\")\n def test_validate_metric_with_null_value(self, mock_storage_class):\n \"\"\"Test validation of metric with null value.\"\"\"\n processor = MetricsProcessor()\n\n # Use model_construct() to bypass Pydantic validation and create invalid metric\n metric = Metric.model_construct(\n type=MetricType.AUTH_REQUEST,\n value=None, # Invalid - would fail normal Pydantic validation\n duration_ms=100.0,\n )\n\n assert processor._validate_metric(metric) is False\n\n @patch(\"app.core.processor.MetricsStorage\")\n def test_validate_metric_with_zero_value(self, mock_storage_class):\n \"\"\"Test validation of metric with zero value.\"\"\"\n processor = MetricsProcessor()\n\n metric = Metric(\n type=MetricType.AUTH_REQUEST,\n value=0.0, # Valid\n duration_ms=100.0,\n )\n\n assert processor._validate_metric(metric) is True\n\n\nclass TestMetricsProcessing:\n \"\"\"Test metrics processing logic.\"\"\"\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_process_single_valid_metric(self, mock_storage_class):\n \"\"\"Test processing a single valid metric.\"\"\"\n mock_storage = AsyncMock()\n mock_storage.store_metrics_batch = AsyncMock()\n mock_storage_class.return_value = mock_storage\n\n processor = MetricsProcessor()\n processor.otel = None # Disable OTel for this test\n\n metric = Metric(type=MetricType.AUTH_REQUEST, value=1.0, duration_ms=100.0)\n\n request = MetricRequest(service=\"test-service\", metrics=[metric])\n\n result = await processor.process_metrics(request, \"test_req_123\", \"test-service\")\n\n assert result.accepted == 1\n assert result.rejected == 0\n assert len(result.errors) == 0\n\n @patch(\"app.core.processor.validator\")\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_process_invalid_metric(self, mock_storage_class, mock_validator):\n \"\"\"Test processing an invalid metric.\"\"\"\n mock_storage = AsyncMock()\n mock_storage_class.return_value = mock_storage\n\n # Mock validator to pass request validation\n from app.core.validator import ValidationResult\n\n mock_result = ValidationResult()\n mock_validator.validate_metric_request.return_value = mock_result\n\n processor = MetricsProcessor()\n processor.otel = None\n\n # Use model_construct() to bypass Pydantic validation and create invalid metric\n metric = Metric.model_construct(\n type=MetricType.AUTH_REQUEST,\n value=None, # Invalid - would fail normal Pydantic validation\n duration_ms=100.0,\n dimensions={},\n metadata={},\n )\n\n # Need to construct MetricRequest with model_construct to include invalid metric\n request = MetricRequest.model_construct(service=\"test-service\", metrics=[metric])\n\n result = await processor.process_metrics(request, \"test_req_123\", \"test-service\")\n\n assert result.accepted == 0\n assert result.rejected == 1\n assert len(result.errors) == 1\n assert \"Invalid metric\" in result.errors[0]\n\n @patch(\"app.core.processor.validator\")\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_process_mixed_valid_invalid_metrics(self, mock_storage_class, mock_validator):\n \"\"\"Test processing a mix of valid and invalid metrics.\"\"\"\n mock_storage = AsyncMock()\n mock_storage.store_metrics_batch = AsyncMock()\n mock_storage_class.return_value = mock_storage\n\n # Mock validator to pass request validation\n from app.core.validator import ValidationResult\n\n mock_result = ValidationResult()\n mock_validator.validate_metric_request.return_value = mock_result\n\n processor = MetricsProcessor()\n processor.otel = None\n\n valid_metric = Metric(type=MetricType.AUTH_REQUEST, value=1.0, duration_ms=100.0)\n\n # Use model_construct() to bypass Pydantic validation and create invalid metric\n invalid_metric = Metric.model_construct(\n type=MetricType.AUTH_REQUEST,\n value=None, # Invalid - would fail normal Pydantic validation\n duration_ms=100.0,\n dimensions={},\n metadata={},\n )\n\n # Need to construct MetricRequest with model_construct to include invalid metric\n request = MetricRequest.model_construct(\n service=\"test-service\", metrics=[valid_metric, invalid_metric]\n )\n\n result = await processor.process_metrics(request, \"test_req_123\", \"test-service\")\n\n assert result.accepted == 1\n assert result.rejected == 1\n assert len(result.errors) == 1\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_process_metrics_with_otel_emission(self, mock_storage_class):\n \"\"\"Test processing metrics with OpenTelemetry emission.\"\"\"\n mock_storage = AsyncMock()\n mock_storage.store_metrics_batch = AsyncMock()\n mock_storage_class.return_value = mock_storage\n\n processor = MetricsProcessor()\n # Mock OTel instruments\n processor.otel = MagicMock()\n processor.otel.auth_counter = MagicMock()\n processor.otel.auth_histogram = MagicMock()\n\n metric = Metric(\n type=MetricType.AUTH_REQUEST,\n value=1.0,\n duration_ms=100.0,\n dimensions={\"success\": True, \"method\": \"jwt\"},\n )\n\n request = MetricRequest(service=\"test-service\", metrics=[metric])\n\n result = await processor.process_metrics(request, \"test_req_123\", \"test-service\")\n\n assert result.accepted == 1\n assert result.rejected == 0\n\n # Verify OTel methods were called\n processor.otel.auth_counter.add.assert_called_once()\n processor.otel.auth_histogram.record.assert_called_once()\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_process_metrics_storage_error(self, mock_storage_class):\n \"\"\"Test processing metrics when storage fails during flush.\n\n Note: Metrics are buffered and the storage error only occurs during flush.\n The metric is still accepted into the buffer before storage failure.\n \"\"\"\n mock_storage = AsyncMock()\n mock_storage.store_metrics_batch = AsyncMock(side_effect=Exception(\"Storage error\"))\n mock_storage_class.return_value = mock_storage\n\n processor = MetricsProcessor()\n processor.otel = None\n\n metric = Metric(type=MetricType.AUTH_REQUEST, value=1.0, duration_ms=100.0)\n\n request = MetricRequest(service=\"test-service\", metrics=[metric])\n\n result = await processor.process_metrics(request, \"test_req_123\", \"test-service\")\n\n # Metric is accepted into buffer before storage - buffer flush is async\n assert result.accepted == 1\n assert result.rejected == 0\n\n # Force flush to trigger the storage error\n await processor.force_flush()\n\n # After failed flush, metrics are re-added to buffer for retry\n assert len(processor._buffer) == 1\n\n\nclass TestOTelEmission:\n \"\"\"Test OpenTelemetry emission logic.\"\"\"\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_emit_auth_metric_to_otel(self, mock_storage_class):\n \"\"\"Test emitting auth metric to OpenTelemetry.\"\"\"\n processor = MetricsProcessor()\n processor.otel = MagicMock()\n processor.otel.auth_counter = MagicMock()\n processor.otel.auth_histogram = MagicMock()\n\n metric = Metric(\n type=MetricType.AUTH_REQUEST,\n value=1.0,\n duration_ms=150.0,\n dimensions={\"success\": True, \"method\": \"oauth\"},\n )\n\n await processor._emit_to_otel(metric, \"test-service\")\n\n # Verify counter was called\n processor.otel.auth_counter.add.assert_called_once_with(\n 1.0,\n {\n \"service\": \"test-service\",\n \"metric_type\": \"auth_request\",\n \"success\": \"true\",\n \"method\": \"oauth\",\n },\n )\n\n # Verify histogram was called (duration converted to seconds)\n processor.otel.auth_histogram.record.assert_called_once_with(\n 0.15, # 150ms converted to seconds\n {\n \"service\": \"test-service\",\n \"metric_type\": \"auth_request\",\n \"success\": \"true\",\n \"method\": \"oauth\",\n },\n )\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_emit_discovery_metric_to_otel(self, mock_storage_class):\n \"\"\"Test emitting discovery metric to OpenTelemetry.\"\"\"\n processor = MetricsProcessor()\n processor.otel = MagicMock()\n processor.otel.discovery_counter = MagicMock()\n processor.otel.discovery_histogram = MagicMock()\n\n metric = Metric(\n type=MetricType.TOOL_DISCOVERY,\n value=1.0,\n duration_ms=50.0,\n dimensions={\"query\": \"test search\"},\n )\n\n await processor._emit_to_otel(metric, \"registry-service\")\n\n processor.otel.discovery_counter.add.assert_called_once()\n processor.otel.discovery_histogram.record.assert_called_once()\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_emit_tool_metric_to_otel(self, mock_storage_class):\n \"\"\"Test emitting tool execution metric to OpenTelemetry.\"\"\"\n processor = MetricsProcessor()\n processor.otel = MagicMock()\n processor.otel.tool_counter = MagicMock()\n processor.otel.tool_histogram = MagicMock()\n\n metric = Metric(\n type=MetricType.TOOL_EXECUTION,\n value=1.0,\n duration_ms=250.0,\n dimensions={\"tool_name\": \"calculator\", \"success\": True},\n )\n\n await processor._emit_to_otel(metric, \"mcpgw-service\")\n\n processor.otel.tool_counter.add.assert_called_once()\n processor.otel.tool_histogram.record.assert_called_once()\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_emit_without_otel(self, mock_storage_class):\n \"\"\"Test emission when OTel is not available.\"\"\"\n processor = MetricsProcessor()\n processor.otel = None\n\n metric = Metric(type=MetricType.AUTH_REQUEST, value=1.0)\n\n # Should not raise any exceptions\n await processor._emit_to_otel(metric, \"test-service\")\n\n\nclass TestBufferedStorage:\n \"\"\"Test buffered storage logic.\"\"\"\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_buffer_for_storage(self, mock_storage_class):\n \"\"\"Test buffering metrics for storage.\"\"\"\n mock_storage = AsyncMock()\n mock_storage_class.return_value = mock_storage\n\n processor = MetricsProcessor()\n\n metric = Metric(type=MetricType.AUTH_REQUEST, value=1.0)\n request = MetricRequest(service=\"test\", metrics=[metric])\n\n await processor._buffer_for_storage(metric, request, \"req_123\")\n\n assert len(processor._buffer) == 1\n assert processor._buffer[0][\"metric\"] == metric\n assert processor._buffer[0][\"request\"] == request\n assert processor._buffer[0][\"request_id\"] == \"req_123\"\n\n @patch(\"app.core.processor.MetricsStorage\")\n async def test_force_flush(self, mock_storage_class):\n \"\"\"Test force flushing buffered metrics.\"\"\"\n mock_storage = AsyncMock()\n mock_storage.store_metrics_batch = AsyncMock()\n mock_storage_class.return_value = mock_storage\n\n processor = MetricsProcessor()\n\n # Add some metrics to buffer\n metric = Metric(type=MetricType.AUTH_REQUEST, value=1.0)\n request = MetricRequest(service=\"test\", metrics=[metric])\n processor._buffer = [\n {\"metric\": metric, \"request\": request, \"request_id\": \"req_1\"},\n {\"metric\": metric, \"request\": request, \"request_id\": \"req_2\"},\n ]\n\n await processor.force_flush()\n\n # Buffer should be cleared after flush\n assert len(processor._buffer) == 0\n\n # Storage should have been called\n mock_storage.store_metrics_batch.assert_called_once()\n" }, { "path": "metrics-service/tests/test_rate_limiter.py", "content": "\"\"\"Tests for rate limiting functionality.\"\"\"\n\nimport pytest\nimport asyncio\nimport time\nfrom unittest.mock import AsyncMock, patch\n\nfrom app.core.rate_limiter import RateLimiter\nfrom app.api.auth import verify_api_key, get_rate_limit_status\nfrom app.utils.helpers import hash_api_key\nfrom fastapi import HTTPException, Request\nfrom fastapi.testclient import TestClient\n\nfrom app.main import app\n\n\nclass TestRateLimiter:\n \"\"\"Test the RateLimiter class.\"\"\"\n\n @pytest.fixture\n def rate_limiter(self):\n \"\"\"Create a fresh rate limiter for each test.\"\"\"\n return RateLimiter()\n\n @pytest.mark.asyncio\n async def test_rate_limiter_initialization(self, rate_limiter):\n \"\"\"Test rate limiter initializes correctly.\"\"\"\n assert rate_limiter._buckets == {}\n assert rate_limiter._lock is not None\n\n @pytest.mark.asyncio\n async def test_first_request_allowed(self, rate_limiter):\n \"\"\"Test first request is allowed.\"\"\"\n key_hash = \"test_key_hash\"\n rate_limit = 1000\n\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, rate_limit)\n\n assert allowed is True\n assert remaining == rate_limit - 1 # Started with rate_limit, used 1\n\n @pytest.mark.asyncio\n async def test_rate_limit_enforcement(self, rate_limiter):\n \"\"\"Test rate limit is enforced when exceeded.\"\"\"\n key_hash = \"test_key_hash\"\n rate_limit = 2 # Very low limit for testing\n\n # First request allowed\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, rate_limit)\n assert allowed is True\n assert remaining == 1\n\n # Second request allowed\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, rate_limit)\n assert allowed is True\n assert remaining == 0\n\n # Third request blocked\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, rate_limit)\n assert allowed is False\n assert remaining == 0\n\n @pytest.mark.asyncio\n async def test_token_refill_over_time(self, rate_limiter):\n \"\"\"Test tokens are refilled over time.\"\"\"\n key_hash = \"test_key_hash\"\n rate_limit = 60 # 60 tokens per minute = 1 per second\n\n # Use up all tokens\n for _ in range(60):\n await rate_limiter.check_rate_limit(key_hash, rate_limit)\n\n # Should be blocked now\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, rate_limit)\n assert allowed is False\n\n # Simulate time passing by directly modifying the bucket\n # In real scenario, tokens would refill naturally\n rate_limiter._buckets[key_hash] = (10, time.time() - 10, rate_limit) # 10 seconds ago\n\n # Should have tokens now\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, rate_limit)\n assert allowed is True\n assert remaining > 0\n\n @pytest.mark.asyncio\n async def test_different_keys_independent_limits(self, rate_limiter):\n \"\"\"Test different API keys have independent rate limits.\"\"\"\n key1 = \"key_hash_1\"\n key2 = \"key_hash_2\"\n rate_limit = 2\n\n # Use up key1's limit\n await rate_limiter.check_rate_limit(key1, rate_limit)\n await rate_limiter.check_rate_limit(key1, rate_limit)\n\n # key1 should be blocked\n allowed, _ = await rate_limiter.check_rate_limit(key1, rate_limit)\n assert allowed is False\n\n # key2 should still be allowed\n allowed, remaining = await rate_limiter.check_rate_limit(key2, rate_limit)\n assert allowed is True\n assert remaining == 1\n\n @pytest.mark.asyncio\n async def test_rate_limit_change(self, rate_limiter):\n \"\"\"Test changing rate limits for existing keys.\"\"\"\n key_hash = \"test_key_hash\"\n\n # Start with low limit\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, 2)\n assert allowed is True\n assert remaining == 1\n\n # Change to higher limit\n allowed, remaining = await rate_limiter.check_rate_limit(key_hash, 1000)\n assert allowed is True\n # Should scale up the remaining tokens\n assert remaining > 1\n\n @pytest.mark.asyncio\n async def test_get_bucket_status(self, rate_limiter):\n \"\"\"Test getting bucket status without consuming tokens.\"\"\"\n key_hash = \"test_key_hash\"\n rate_limit = 100\n\n # Use some tokens\n await rate_limiter.check_rate_limit(key_hash, rate_limit)\n await rate_limiter.check_rate_limit(key_hash, rate_limit)\n\n status = await rate_limiter.get_bucket_status(key_hash, rate_limit)\n\n assert status[\"rate_limit\"] == rate_limit\n assert status[\"available_tokens\"] == 98 # Used 2 tokens\n assert \"reset_time_seconds\" in status\n\n @pytest.mark.asyncio\n async def test_get_bucket_status_new_key(self, rate_limiter):\n \"\"\"Test getting bucket status for new key.\"\"\"\n key_hash = \"new_key_hash\"\n rate_limit = 100\n\n status = await rate_limiter.get_bucket_status(key_hash, rate_limit)\n\n assert status[\"rate_limit\"] == rate_limit\n assert status[\"available_tokens\"] == rate_limit\n assert status[\"reset_time_seconds\"] == 0\n\n @pytest.mark.asyncio\n async def test_cleanup_old_buckets(self, rate_limiter):\n \"\"\"Test cleanup of old unused buckets.\"\"\"\n key_hash = \"test_key_hash\"\n rate_limit = 100\n\n # Create a bucket\n await rate_limiter.check_rate_limit(key_hash, rate_limit)\n assert len(rate_limiter._buckets) == 1\n\n # Simulate old bucket (25 hours ago)\n old_time = time.time() - (25 * 3600)\n rate_limiter._buckets[key_hash] = (50, old_time, rate_limit)\n\n # Clean up old buckets (max age 24 hours)\n await rate_limiter.cleanup_old_buckets(max_age_hours=24)\n\n # Bucket should be removed\n assert len(rate_limiter._buckets) == 0\n\n\nclass TestRateLimitIntegration:\n \"\"\"Test rate limiting integration with API authentication.\"\"\"\n\n @pytest.fixture(autouse=True)\n def clear_rate_limiter(self):\n \"\"\"Clear rate limiter state before each test.\"\"\"\n from app.core.rate_limiter import rate_limiter\n\n rate_limiter._buckets.clear()\n\n @pytest.fixture\n def client(self):\n \"\"\"Test client for API endpoints.\"\"\"\n return TestClient(app)\n\n @pytest.fixture\n def mock_request(self):\n \"\"\"Mock request object.\"\"\"\n request = AsyncMock(spec=Request)\n request.headers = {\"X-API-Key\": \"test_key_123\"}\n request.state = AsyncMock()\n return request\n\n @patch(\"app.api.auth.MetricsStorage\")\n @pytest.mark.asyncio\n async def test_auth_with_rate_limiting(self, mock_storage_class, mock_request):\n \"\"\"Test API key verification with rate limiting.\"\"\"\n # Mock storage\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 10,\n \"last_used_at\": None,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n # First request should be allowed\n service_name = await verify_api_key(mock_request)\n assert service_name == \"test-service\"\n assert hasattr(mock_request.state, \"rate_limit_remaining\")\n assert hasattr(mock_request.state, \"rate_limit_limit\")\n assert mock_request.state.rate_limit_limit == 10\n assert mock_request.state.rate_limit_remaining == 9\n\n @patch(\"app.api.auth.MetricsStorage\")\n @pytest.mark.asyncio\n async def test_rate_limit_exceeded(self, mock_storage_class, mock_request):\n \"\"\"Test rate limit exceeded scenario.\"\"\"\n # Mock storage\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 1, # Very low limit\n \"last_used_at\": None,\n }\n mock_storage.update_api_key_usage.return_value = None\n mock_storage_class.return_value = mock_storage\n\n # First request allowed\n service_name = await verify_api_key(mock_request)\n assert service_name == \"test-service\"\n\n # Second request should be blocked\n with pytest.raises(HTTPException) as exc_info:\n await verify_api_key(mock_request)\n\n assert exc_info.value.status_code == 429\n assert \"Rate limit exceeded\" in exc_info.value.detail\n assert exc_info.value.headers[\"X-RateLimit-Limit\"] == \"1\"\n assert exc_info.value.headers[\"X-RateLimit-Remaining\"] == \"0\"\n assert exc_info.value.headers[\"Retry-After\"] == \"60\"\n\n @patch(\"app.api.auth.MetricsStorage\")\n @pytest.mark.asyncio\n async def test_get_rate_limit_status_function(self, mock_storage_class):\n \"\"\"Test get_rate_limit_status function.\"\"\"\n # Mock storage\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = {\n \"service_name\": \"test-service\",\n \"is_active\": True,\n \"rate_limit\": 100,\n \"last_used_at\": None,\n }\n mock_storage_class.return_value = mock_storage\n\n status = await get_rate_limit_status(\"test_key_123\")\n\n assert status[\"service\"] == \"test-service\"\n assert status[\"rate_limit\"] == 100\n assert status[\"available_tokens\"] == 100\n assert \"reset_time_seconds\" in status\n\n @patch(\"app.api.auth.MetricsStorage\")\n @pytest.mark.asyncio\n async def test_get_rate_limit_status_invalid_key(self, mock_storage_class):\n \"\"\"Test get_rate_limit_status with invalid key.\"\"\"\n # Mock storage returning None\n mock_storage = AsyncMock()\n mock_storage.get_api_key.return_value = None\n mock_storage_class.return_value = mock_storage\n\n with pytest.raises(HTTPException) as exc_info:\n await get_rate_limit_status(\"invalid_key\")\n\n assert exc_info.value.status_code == 401\n assert \"Invalid API key\" in exc_info.value.detail\n\n\nclass TestRateLimitEndpoint:\n \"\"\"Test the rate limit status endpoint.\"\"\"\n\n @pytest.fixture(autouse=True)\n def clear_rate_limiter(self):\n \"\"\"Clear rate limiter state before each test.\"\"\"\n from app.core.rate_limiter import rate_limiter\n\n rate_limiter._buckets.clear()\n\n @pytest.fixture\n def client(self):\n \"\"\"Test client for API endpoints.\"\"\"\n return TestClient(app)\n\n def test_rate_limit_endpoint_without_key(self, client):\n \"\"\"Test rate limit endpoint without API key.\"\"\"\n response = client.get(\"/rate-limit\")\n assert response.status_code == 401\n assert \"API key required\" in response.json()[\"detail\"]\n\n @patch(\"app.api.routes.get_rate_limit_status\")\n def test_rate_limit_endpoint_with_key(self, mock_get_status, client):\n \"\"\"Test rate limit endpoint with valid API key.\"\"\"\n mock_get_status.return_value = {\n \"service\": \"test-service\",\n \"rate_limit\": 1000,\n \"available_tokens\": 950,\n \"reset_time_seconds\": 30,\n }\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n response = client.get(\"/rate-limit\", headers=headers)\n\n assert response.status_code == 200\n data = response.json()\n assert data[\"service\"] == \"test-service\"\n assert data[\"rate_limit\"] == 1000\n assert data[\"available_tokens\"] == 950\n assert data[\"reset_time_seconds\"] == 30\n\n @patch(\"app.api.routes.get_rate_limit_status\")\n def test_rate_limit_endpoint_error(self, mock_get_status, client):\n \"\"\"Test rate limit endpoint when status check fails.\"\"\"\n mock_get_status.side_effect = Exception(\"Database error\")\n\n headers = {\"X-API-Key\": \"test_key_123\"}\n response = client.get(\"/rate-limit\", headers=headers)\n\n assert response.status_code == 500\n assert \"Failed to get rate limit status\" in response.json()[\"detail\"]\n" }, { "path": "metrics-service/tests/test_retention.py", "content": "\"\"\"Tests for data retention and cleanup functionality.\"\"\"\n\nimport pytest\nimport pytest_asyncio\nimport asyncio\nimport tempfile\nimport os\nfrom datetime import datetime, timedelta\nfrom app.core.retention import (\n RetentionPolicy,\n RetentionManager,\n ALLOWED_TABLE_NAMES,\n ALLOWED_TIMESTAMP_COLUMNS,\n _enable_test_tables,\n _disable_test_tables,\n _validate_table_name,\n _validate_timestamp_column,\n _validate_identifier,\n)\nfrom app.storage.database import MetricsStorage\nfrom app.storage.migrations import MigrationManager\nimport aiosqlite\n\n\n@pytest.fixture(autouse=True)\ndef enable_test_tables():\n \"\"\"Enable test table names for all tests in this module.\"\"\"\n _enable_test_tables()\n yield\n _disable_test_tables()\n\n\n@pytest_asyncio.fixture\nasync def temp_db():\n \"\"\"Create temporary database for testing.\"\"\"\n fd, db_path = tempfile.mkstemp(suffix=\".db\")\n os.close(fd)\n\n try:\n # Initialize database with schema using migrations\n migration_manager = MigrationManager(db_path)\n await migration_manager.migrate_up()\n\n # Add sample data\n async with aiosqlite.connect(db_path) as db:\n # Create test tables\n await db.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS test_metrics (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n created_at TEXT NOT NULL,\n value REAL NOT NULL\n )\n \"\"\")\n\n # Insert test data with various timestamps\n now = datetime.now()\n await db.execute(\n \"INSERT INTO test_metrics (created_at, value) VALUES (?, ?)\",\n ((now - timedelta(days=100)).isoformat(), 1.0),\n )\n await db.execute(\n \"INSERT INTO test_metrics (created_at, value) VALUES (?, ?)\",\n ((now - timedelta(days=50)).isoformat(), 2.0),\n )\n await db.execute(\n \"INSERT INTO test_metrics (created_at, value) VALUES (?, ?)\",\n ((now - timedelta(days=10)).isoformat(), 3.0),\n )\n await db.execute(\n \"INSERT INTO test_metrics (created_at, value) VALUES (?, ?)\", (now.isoformat(), 4.0)\n )\n await db.commit()\n\n yield db_path\n finally:\n if os.path.exists(db_path):\n os.unlink(db_path)\n\n\nclass TestRetentionPolicy:\n \"\"\"Test retention policy functionality.\"\"\"\n\n def test_policy_creation(self):\n \"\"\"Test retention policy creation.\"\"\"\n policy = RetentionPolicy(table_name=\"metrics\", retention_days=90, is_active=True)\n\n assert policy.table_name == \"metrics\"\n assert policy.retention_days == 90\n assert policy.is_active is True\n assert policy.timestamp_column == \"created_at\"\n\n def test_custom_cleanup_query(self):\n \"\"\"Test custom cleanup query.\"\"\"\n custom_query = \"DELETE FROM metrics WHERE timestamp < datetime('now', '-30 days')\"\n policy = RetentionPolicy(\n table_name=\"metrics\", retention_days=30, cleanup_query=custom_query\n )\n\n query, params = policy.get_cleanup_query()\n assert query == custom_query\n assert params == ()\n\n def test_default_cleanup_query(self):\n \"\"\"Test default cleanup query generation.\"\"\"\n policy = RetentionPolicy(table_name=\"metrics\", retention_days=90)\n\n query, params = policy.get_cleanup_query()\n assert \"DELETE FROM metrics\" in query\n assert \"created_at < ?\" in query\n assert len(params) == 1\n # Verify param is an ISO formatted date string\n assert isinstance(params[0], str)\n\n def test_count_query(self):\n \"\"\"Test count query generation.\"\"\"\n policy = RetentionPolicy(table_name=\"metrics\", retention_days=30)\n\n query, params = policy.get_count_query()\n assert \"SELECT COUNT(*)\" in query\n assert \"FROM metrics\" in query\n assert \"created_at < ?\" in query\n assert len(params) == 1\n # Verify param is an ISO formatted date string\n assert isinstance(params[0], str)\n\n\nclass TestRetentionManager:\n \"\"\"Test retention manager functionality.\"\"\"\n\n @pytest_asyncio.fixture\n async def manager(self, temp_db):\n \"\"\"Create retention manager with temporary database.\"\"\"\n manager = RetentionManager()\n manager.storage.db_path = temp_db\n return manager\n\n @pytest.mark.asyncio\n async def test_load_default_policies(self, manager):\n \"\"\"Test loading default policies.\"\"\"\n assert len(manager.policies) > 0\n assert \"metrics\" in manager.policies\n assert \"auth_metrics\" in manager.policies\n assert manager.policies[\"metrics\"].retention_days == 90\n\n @pytest.mark.asyncio\n async def test_update_policy(self, manager):\n \"\"\"Test updating retention policy.\"\"\"\n await manager.update_policy(\"test_table\", 60, True)\n\n assert \"test_table\" in manager.policies\n assert manager.policies[\"test_table\"].retention_days == 60\n assert manager.policies[\"test_table\"].is_active is True\n\n @pytest.mark.asyncio\n async def test_get_cleanup_preview(self, manager, temp_db):\n \"\"\"Test cleanup preview functionality.\"\"\"\n # Add test policy\n manager.policies[\"test_metrics\"] = RetentionPolicy(\n table_name=\"test_metrics\", retention_days=30\n )\n\n preview = await manager.get_cleanup_preview(\"test_metrics\")\n\n assert \"test_metrics\" in preview\n preview_data = preview[\"test_metrics\"]\n assert \"retention_days\" in preview_data\n assert \"records_to_delete\" in preview_data\n assert \"total_records\" in preview_data\n assert preview_data[\"retention_days\"] == 30\n assert preview_data[\"total_records\"] == 4 # From test data\n\n # Should have 2 records older than 30 days\n assert preview_data[\"records_to_delete\"] == 2\n\n @pytest.mark.asyncio\n async def test_cleanup_table_dry_run(self, manager, temp_db):\n \"\"\"Test table cleanup in dry run mode.\"\"\"\n # Add test policy\n manager.policies[\"test_metrics\"] = RetentionPolicy(\n table_name=\"test_metrics\", retention_days=30\n )\n\n result = await manager.cleanup_table(\"test_metrics\", dry_run=True)\n\n assert result[\"table\"] == \"test_metrics\"\n assert result[\"status\"] == \"dry_run\"\n assert result[\"records_would_delete\"] == 2\n\n # Verify no records were actually deleted\n async with aiosqlite.connect(temp_db) as db:\n cursor = await db.execute(\"SELECT COUNT(*) FROM test_metrics\")\n count = (await cursor.fetchone())[0]\n assert count == 4\n\n @pytest.mark.asyncio\n async def test_cleanup_table_actual(self, manager, temp_db):\n \"\"\"Test actual table cleanup.\"\"\"\n # Add test policy\n manager.policies[\"test_metrics\"] = RetentionPolicy(\n table_name=\"test_metrics\", retention_days=30\n )\n\n result = await manager.cleanup_table(\"test_metrics\", dry_run=False)\n\n assert result[\"table\"] == \"test_metrics\"\n assert result[\"status\"] == \"completed\"\n assert result[\"records_deleted\"] == 2\n\n # Verify records were actually deleted\n async with aiosqlite.connect(temp_db) as db:\n cursor = await db.execute(\"SELECT COUNT(*) FROM test_metrics\")\n count = (await cursor.fetchone())[0]\n assert count == 2\n\n @pytest.mark.asyncio\n async def test_cleanup_inactive_policy(self, manager):\n \"\"\"Test cleanup with inactive policy.\"\"\"\n manager.policies[\"test_table\"] = RetentionPolicy(\n table_name=\"test_table\", retention_days=30, is_active=False\n )\n\n result = await manager.cleanup_table(\"test_table\", dry_run=False)\n\n assert result[\"status\"] == \"skipped\"\n assert result[\"reason\"] == \"policy_inactive\"\n\n @pytest.mark.asyncio\n async def test_cleanup_no_policy(self, manager):\n \"\"\"Test cleanup for table without policy.\"\"\"\n with pytest.raises(ValueError, match=\"No retention policy found\"):\n await manager.cleanup_table(\"nonexistent_table\")\n\n @pytest.mark.asyncio\n async def test_cleanup_all_tables(self, manager, temp_db):\n \"\"\"Test cleanup of all tables.\"\"\"\n # Add test policy\n manager.policies[\"test_metrics\"] = RetentionPolicy(\n table_name=\"test_metrics\", retention_days=30\n )\n\n result = await manager.cleanup_all_tables(dry_run=True)\n\n assert result[\"operation\"] == \"dry_run\"\n assert \"test_metrics\" in result[\"table_results\"]\n assert result[\"table_results\"][\"test_metrics\"][\"status\"] == \"dry_run\"\n\n @pytest.mark.asyncio\n async def test_get_table_stats(self, manager, temp_db):\n \"\"\"Test getting table statistics.\"\"\"\n stats = await manager.get_table_stats()\n\n # Check that we get stats for some tables\n assert len(stats) > 0\n\n # Check that real metrics tables have proper stats\n if \"metrics\" in stats and \"error\" not in stats[\"metrics\"]:\n assert \"record_count\" in stats[\"metrics\"]\n assert \"has_retention_policy\" in stats[\"metrics\"]\n\n # For test table that might have errors, just verify it exists\n assert \"test_metrics\" in stats\n\n @pytest.mark.asyncio\n async def test_get_database_size(self, manager):\n \"\"\"Test getting database size information.\"\"\"\n size_info = await manager.get_database_size()\n\n assert \"main_db_bytes\" in size_info\n assert \"main_db_mb\" in size_info\n assert \"total_bytes\" in size_info\n assert \"page_count\" in size_info\n assert \"page_size\" in size_info\n assert size_info[\"main_db_bytes\"] > 0\n\n @pytest.mark.asyncio\n async def test_save_and_load_policies(self, manager, temp_db):\n \"\"\"Test saving and loading policies to/from database.\"\"\"\n # Add custom policy\n manager.policies[\"custom_table\"] = RetentionPolicy(\n table_name=\"custom_table\", retention_days=120, is_active=True\n )\n\n # Save policies\n await manager.save_policies_to_database()\n\n # Create new manager and load policies\n new_manager = RetentionManager()\n new_manager.storage.db_path = temp_db\n await new_manager.load_policies_from_database()\n\n # Verify custom policy was loaded\n assert \"custom_table\" in new_manager.policies\n assert new_manager.policies[\"custom_table\"].retention_days == 120\n assert new_manager.policies[\"custom_table\"].is_active is True\n\n\nclass TestRetentionIntegration:\n \"\"\"Integration tests for retention system.\"\"\"\n\n @pytest.mark.asyncio\n async def test_end_to_end_cleanup(self, temp_db):\n \"\"\"Test complete end-to-end cleanup process.\"\"\"\n manager = RetentionManager()\n manager.storage.db_path = temp_db\n\n # Add metrics with old timestamps\n async with aiosqlite.connect(temp_db) as db:\n old_date = (datetime.now() - timedelta(days=120)).isoformat()\n recent_date = (datetime.now() - timedelta(days=10)).isoformat()\n\n await db.execute(\n \"INSERT INTO metrics (request_id, service, metric_type, value, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?)\",\n (\"req_1\", \"test\", \"auth_request\", 1.0, old_date, old_date),\n )\n await db.execute(\n \"INSERT INTO metrics (request_id, service, metric_type, value, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?)\",\n (\"req_2\", \"test\", \"auth_request\", 1.0, recent_date, recent_date),\n )\n await db.commit()\n\n # Preview cleanup\n preview = await manager.get_cleanup_preview(\"metrics\")\n assert preview[\"metrics\"][\"records_to_delete\"] == 1\n\n # Run actual cleanup\n result = await manager.cleanup_table(\"metrics\", dry_run=False)\n assert result[\"records_deleted\"] == 1\n\n # Verify only recent record remains\n async with aiosqlite.connect(temp_db) as db:\n cursor = await db.execute(\"SELECT COUNT(*) FROM metrics\")\n count = (await cursor.fetchone())[0]\n assert count == 1\n\n cursor = await db.execute(\"SELECT request_id FROM metrics\")\n remaining_id = (await cursor.fetchone())[0]\n assert remaining_id == \"req_2\"\n\n\nclass TestSQLInjectionPrevention:\n \"\"\"Security tests for SQL injection prevention.\n\n These tests verify that the retention system properly rejects\n malicious input that could be used for SQL injection attacks.\n CVE reference: Security vulnerability reported 2026-02-05.\n \"\"\"\n\n def test_table_name_with_sql_injection_rejected(self):\n \"\"\"Test that SQL injection attempts in table_name are rejected.\"\"\"\n # Test cases from the security report\n malicious_table_names = [\n \"metrics WHERE 1=1--\",\n \"metrics; DROP TABLE api_keys;--\",\n \"metrics UNION SELECT * FROM sqlite_master--\",\n \"metrics) INSERT INTO api_keys VALUES ('hack');--\",\n \"metrics' OR '1'='1\",\n 'metrics\"; DELETE FROM metrics; --',\n \"metrics`; DROP TABLE users; --\",\n ]\n\n for malicious_name in malicious_table_names:\n with pytest.raises(ValueError, match=\"Invalid table name\"):\n _validate_table_name(malicious_name)\n\n def test_table_name_with_spaces_rejected(self):\n \"\"\"Test that table names with spaces are rejected.\"\"\"\n with pytest.raises(ValueError, match=\"Invalid table name\"):\n _validate_table_name(\"metrics table\")\n\n def test_table_name_with_special_chars_rejected(self):\n \"\"\"Test that table names with special characters are rejected.\"\"\"\n invalid_names = [\n \"metrics;\",\n \"metrics--\",\n \"metrics/*\",\n \"metrics'\",\n 'metrics\"',\n \"metrics`\",\n \"metrics(\",\n \"metrics)\",\n \"metrics=\",\n ]\n\n for invalid_name in invalid_names:\n with pytest.raises(ValueError, match=\"Invalid table name\"):\n _validate_table_name(invalid_name)\n\n def test_timestamp_column_with_sql_injection_rejected(self):\n \"\"\"Test that SQL injection in timestamp_column is rejected.\"\"\"\n malicious_columns = [\n \"created_at; DROP TABLE--\",\n \"created_at UNION SELECT--\",\n \"created_at' OR '1'='1\",\n ]\n\n for malicious_col in malicious_columns:\n with pytest.raises(ValueError, match=\"Invalid timestamp column\"):\n _validate_timestamp_column(malicious_col)\n\n def test_identifier_validation_rejects_invalid_patterns(self):\n \"\"\"Test that identifier validation rejects invalid SQL identifiers.\"\"\"\n invalid_identifiers = [\n \"\", # Empty string\n \"123table\", # Starts with number\n \"table name\", # Contains space\n \"table;drop\", # Contains semicolon\n \"table--comment\", # Contains SQL comment\n \"table'quote\", # Contains quote\n 'table\"double', # Contains double quote\n \"table`backtick\", # Contains backtick\n ]\n\n for invalid_id in invalid_identifiers:\n with pytest.raises(ValueError, match=\"Invalid SQL identifier\"):\n _validate_identifier(invalid_id)\n\n def test_identifier_validation_accepts_valid_patterns(self):\n \"\"\"Test that identifier validation accepts valid SQL identifiers.\"\"\"\n valid_identifiers = [\n \"metrics\",\n \"auth_metrics\",\n \"table_123\",\n \"_private_table\",\n \"CamelCaseTable\",\n \"table_with_many_underscores_123\",\n ]\n\n for valid_id in valid_identifiers:\n result = _validate_identifier(valid_id)\n assert result == valid_id\n\n def test_valid_table_names_accepted(self):\n \"\"\"Test that valid table names from allowlist are accepted.\"\"\"\n for table_name in ALLOWED_TABLE_NAMES:\n result = _validate_table_name(table_name)\n assert result == table_name\n\n def test_valid_timestamp_columns_accepted(self):\n \"\"\"Test that valid timestamp columns from allowlist are accepted.\"\"\"\n for column_name in ALLOWED_TIMESTAMP_COLUMNS:\n result = _validate_timestamp_column(column_name)\n assert result == column_name\n\n def test_retention_policy_rejects_invalid_table(self):\n \"\"\"Test that RetentionPolicy constructor rejects invalid table names.\"\"\"\n # Temporarily disable test tables to test production behavior\n _disable_test_tables()\n try:\n with pytest.raises(ValueError, match=\"Invalid table name\"):\n RetentionPolicy(table_name=\"malicious; DROP TABLE--\", retention_days=30)\n finally:\n _enable_test_tables()\n\n def test_retention_policy_rejects_invalid_timestamp_column(self):\n \"\"\"Test that RetentionPolicy rejects invalid timestamp columns.\"\"\"\n with pytest.raises(ValueError, match=\"Invalid timestamp column\"):\n RetentionPolicy(\n table_name=\"metrics\", retention_days=30, timestamp_column=\"invalid_column; DROP--\"\n )\n\n @pytest.mark.asyncio\n async def test_update_policy_rejects_invalid_table(self, temp_db):\n \"\"\"Test that update_policy rejects invalid table names.\"\"\"\n manager = RetentionManager()\n manager.storage.db_path = temp_db\n\n # Temporarily disable test tables\n _disable_test_tables()\n try:\n with pytest.raises(ValueError, match=\"Invalid table name\"):\n await manager.update_policy(\"metrics WHERE 1=1--\", retention_days=30)\n finally:\n _enable_test_tables()\n\n @pytest.mark.asyncio\n async def test_get_cleanup_preview_rejects_invalid_table(self, temp_db):\n \"\"\"Test that get_cleanup_preview rejects invalid table names.\"\"\"\n manager = RetentionManager()\n manager.storage.db_path = temp_db\n\n # Temporarily disable test tables\n _disable_test_tables()\n try:\n with pytest.raises(ValueError, match=\"Invalid table name\"):\n await manager.get_cleanup_preview(\"metrics; DROP TABLE--\")\n finally:\n _enable_test_tables()\n\n @pytest.mark.asyncio\n async def test_cleanup_table_rejects_invalid_table(self, temp_db):\n \"\"\"Test that cleanup_table rejects invalid table names via policy check.\"\"\"\n manager = RetentionManager()\n manager.storage.db_path = temp_db\n\n # cleanup_table checks if table is in policies first\n # For a table not in policies, it raises ValueError\n with pytest.raises(ValueError, match=\"No retention policy found\"):\n await manager.cleanup_table(\"nonexistent_malicious_table\")\n\n\nclass TestAllowlistConfiguration:\n \"\"\"Tests for allowlist configuration.\"\"\"\n\n def test_allowlist_contains_expected_tables(self):\n \"\"\"Test that the allowlist contains all expected production tables.\"\"\"\n expected_tables = {\n \"metrics\",\n \"auth_metrics\",\n \"discovery_metrics\",\n \"tool_metrics\",\n \"metrics_hourly\",\n \"metrics_daily\",\n \"api_key_usage_log\",\n }\n\n assert ALLOWED_TABLE_NAMES == expected_tables\n\n def test_allowlist_contains_expected_timestamp_columns(self):\n \"\"\"Test that the timestamp column allowlist contains expected values.\"\"\"\n expected_columns = {\n \"created_at\",\n \"timestamp\",\n \"updated_at\",\n }\n\n assert ALLOWED_TIMESTAMP_COLUMNS == expected_columns\n\n def test_allowlist_is_immutable_set(self):\n \"\"\"Test that the allowlist is a set (for O(1) lookups).\"\"\"\n assert isinstance(ALLOWED_TABLE_NAMES, set)\n assert isinstance(ALLOWED_TIMESTAMP_COLUMNS, set)\n" }, { "path": "metrics-service/tests/test_validator.py", "content": "\"\"\"Tests for the data validation module.\"\"\"\n\nimport pytest\nimport math\nfrom datetime import datetime, timezone, timedelta\n\nfrom app.core.validator import MetricsValidator, ValidationResult, ValidationError\nfrom app.core.models import MetricType, Metric, MetricRequest\n\n\nclass TestValidationResult:\n \"\"\"Test ValidationResult class.\"\"\"\n\n def test_validation_result_initialization(self):\n \"\"\"Test ValidationResult initializes correctly.\"\"\"\n result = ValidationResult()\n assert result.errors == []\n assert result.warnings == []\n assert result.is_valid is True\n\n def test_add_error(self):\n \"\"\"Test adding validation errors.\"\"\"\n result = ValidationResult()\n result.add_error(\"field1\", \"error message\", \"bad_value\")\n\n assert len(result.errors) == 1\n assert result.errors[0].field == \"field1\"\n assert result.errors[0].message == \"error message\"\n assert result.errors[0].value == \"bad_value\"\n assert result.is_valid is False\n\n def test_add_warning(self):\n \"\"\"Test adding validation warnings.\"\"\"\n result = ValidationResult()\n result.add_warning(\"warning message\")\n\n assert len(result.warnings) == 1\n assert result.warnings[0] == \"warning message\"\n assert result.is_valid is True # Warnings don't affect validity\n\n def test_get_error_messages(self):\n \"\"\"Test getting error message strings.\"\"\"\n result = ValidationResult()\n result.add_error(\"field1\", \"error1\")\n result.add_error(\"field2\", \"error2\")\n\n messages = result.get_error_messages()\n assert len(messages) == 2\n assert \"field1: error1\" in messages\n assert \"field2: error2\" in messages\n\n\nclass TestValidationError:\n \"\"\"Test ValidationError class.\"\"\"\n\n def test_validation_error_creation(self):\n \"\"\"Test ValidationError creation and string representation.\"\"\"\n error = ValidationError(\"test_field\", \"test message\", \"test_value\")\n\n assert error.field == \"test_field\"\n assert error.message == \"test message\"\n assert error.value == \"test_value\"\n assert str(error) == \"test_field: test message\"\n\n\nclass TestServiceValidation:\n \"\"\"Test service name validation.\"\"\"\n\n @pytest.fixture\n def validator(self):\n \"\"\"Create a validator instance.\"\"\"\n return MetricsValidator()\n\n def test_valid_service_names(self, validator):\n \"\"\"Test valid service names.\"\"\"\n result = ValidationResult()\n\n valid_names = [\n \"auth-server\",\n \"metrics_service\",\n \"my-service-123\",\n \"ServiceName\",\n \"service123\",\n ]\n\n for name in valid_names:\n validator._validate_service_name(name, result)\n\n assert result.is_valid\n assert len(result.errors) == 0\n\n def test_invalid_service_names(self, validator):\n \"\"\"Test invalid service names.\"\"\"\n invalid_cases = [\n (\"\", \"Service name is required\"),\n (\"service with spaces\", \"must contain only alphanumeric\"),\n (\"service@domain\", \"must contain only alphanumeric\"),\n (\"service.name\", \"must contain only alphanumeric\"),\n (\"a\" * 101, \"Service name too long\"),\n ]\n\n for name, expected_error in invalid_cases:\n result = ValidationResult()\n validator._validate_service_name(name, result)\n\n assert not result.is_valid\n assert any(expected_error in error.message for error in result.errors)\n\n def test_non_string_service_name(self, validator):\n \"\"\"Test non-string service name.\"\"\"\n result = ValidationResult()\n validator._validate_service_name(123, result)\n\n assert not result.is_valid\n assert \"must be string\" in result.errors[0].message\n\n\nclass TestVersionValidation:\n \"\"\"Test version validation.\"\"\"\n\n @pytest.fixture\n def validator(self):\n \"\"\"Create a validator instance.\"\"\"\n return MetricsValidator()\n\n def test_valid_versions(self, validator):\n \"\"\"Test valid semantic versions.\"\"\"\n result = ValidationResult()\n\n valid_versions = [\n \"1.0.0\",\n \"10.20.30\",\n \"1.0.0-alpha\",\n \"1.0.0-alpha.1\",\n \"1.0.0-beta.2\",\n \"2.0.0-rc.1\",\n ]\n\n for version in valid_versions:\n validator._validate_version(version, result)\n\n assert result.is_valid\n assert len(result.errors) == 0\n\n def test_invalid_versions(self, validator):\n \"\"\"Test versions that generate warnings.\"\"\"\n warning_cases = [\"1.0\", \"v1.0.0\", \"latest\", \"1.0.0.0\", \"1.0-SNAPSHOT\"]\n\n for version in warning_cases:\n result = ValidationResult()\n validator._validate_version(version, result)\n\n assert result.is_valid # Warnings don't make it invalid\n assert len(result.warnings) > 0\n assert \"semantic versioning\" in result.warnings[0]\n\n\nclass TestMetricValueValidation:\n \"\"\"Test metric value validation.\"\"\"\n\n @pytest.fixture\n def validator(self):\n \"\"\"Create a validator instance.\"\"\"\n return MetricsValidator()\n\n def test_valid_metric_values(self, validator):\n \"\"\"Test valid metric values.\"\"\"\n result = ValidationResult()\n\n valid_values = [0, 1, -1, 0.5, -0.5, 1000, 1000.5, 1e6, -1e6]\n\n for value in valid_values:\n validator._validate_metric_value(value, \"test_field\", result)\n\n assert result.is_valid\n assert len(result.errors) == 0\n\n def test_invalid_metric_values(self, validator):\n \"\"\"Test invalid metric values.\"\"\"\n invalid_cases = [\n (None, \"required\"),\n (\"not_a_number\", \"must be numeric\"),\n (float(\"nan\"), \"cannot be NaN\"),\n (float(\"inf\"), \"cannot be infinite\"),\n (-float(\"inf\"), \"cannot be infinite\"),\n (1e15, \"out of range\"),\n (-1e15, \"out of range\"),\n ]\n\n for value, expected_error in invalid_cases:\n result = ValidationResult()\n validator._validate_metric_value(value, \"test_field\", result)\n\n assert not result.is_valid\n assert any(expected_error in error.message for error in result.errors)\n\n\nclass TestDimensionsValidation:\n \"\"\"Test dimensions validation.\"\"\"\n\n @pytest.fixture\n def validator(self):\n \"\"\"Create a validator instance.\"\"\"\n return MetricsValidator()\n\n def test_valid_dimensions(self, validator):\n \"\"\"Test valid dimensions.\"\"\"\n result = ValidationResult()\n\n valid_dimensions = {\n \"success\": True,\n \"method\": \"GET\",\n \"status_code\": 200,\n \"user_id\": \"user123\",\n \"_private\": \"value\",\n }\n\n validator._validate_dimensions(valid_dimensions, \"dimensions\", result)\n\n assert result.is_valid\n assert len(result.errors) == 0\n\n def test_invalid_dimension_keys(self, validator):\n \"\"\"Test invalid dimension keys.\"\"\"\n invalid_cases = [\n ({\"123key\": \"value\"}, \"must start with letter\"),\n ({\"key-name\": \"value\"}, \"must start with letter\"),\n ({\"key.name\": \"value\"}, \"must start with letter\"),\n ({\"a\" * 51: \"value\"}, \"too long\"),\n ]\n\n for dimensions, expected_error in invalid_cases:\n result = ValidationResult()\n validator._validate_dimensions(dimensions, \"dimensions\", result)\n\n assert not result.is_valid\n assert any(expected_error in error.message for error in result.errors)\n\n def test_too_many_dimensions(self, validator):\n \"\"\"Test too many dimensions.\"\"\"\n result = ValidationResult()\n\n # Create more than MAX_DIMENSIONS\n too_many_dims = {f\"key_{i}\": f\"value_{i}\" for i in range(25)}\n\n validator._validate_dimensions(too_many_dims, \"dimensions\", result)\n\n assert not result.is_valid\n assert \"Too many dimensions\" in result.errors[0].message\n\n def test_dimension_value_length(self, validator):\n \"\"\"Test dimension value length validation.\"\"\"\n result = ValidationResult()\n\n long_value = \"x\" * 201 # Exceeds DIMENSION_VALUE_MAX_LENGTH\n dimensions = {\"key\": long_value}\n\n validator._validate_dimensions(dimensions, \"dimensions\", result)\n\n assert not result.is_valid\n assert \"too long\" in result.errors[0].message\n\n\nclass TestTimestampValidation:\n \"\"\"Test timestamp validation.\"\"\"\n\n @pytest.fixture\n def validator(self):\n \"\"\"Create a validator instance.\"\"\"\n return MetricsValidator()\n\n def test_valid_timestamps(self, validator):\n \"\"\"Test valid timestamps.\"\"\"\n result = ValidationResult()\n\n now = datetime.now(timezone.utc)\n past = now - timedelta(hours=1)\n near_future = now + timedelta(minutes=2)\n\n for timestamp in [now, past, near_future]:\n validator._validate_timestamp(timestamp, \"timestamp\", result)\n\n assert result.is_valid\n assert len(result.errors) == 0\n\n def test_future_timestamp(self, validator):\n \"\"\"Test timestamp too far in future.\"\"\"\n result = ValidationResult()\n\n far_future = datetime.now(timezone.utc) + timedelta(hours=1)\n validator._validate_timestamp(far_future, \"timestamp\", result)\n\n assert not result.is_valid\n assert \"too far in the future\" in result.errors[0].message\n\n def test_old_timestamp(self, validator):\n \"\"\"Test very old timestamp generates warning.\"\"\"\n result = ValidationResult()\n\n old_timestamp = datetime.now(timezone.utc) - timedelta(days=8)\n validator._validate_timestamp(old_timestamp, \"timestamp\", result)\n\n assert result.is_valid # Old timestamps are warnings, not errors\n assert len(result.warnings) > 0\n assert \"very old\" in result.warnings[0]\n\n\nclass TestFullRequestValidation:\n \"\"\"Test complete request validation.\"\"\"\n\n @pytest.fixture\n def validator(self):\n \"\"\"Create a validator instance.\"\"\"\n return MetricsValidator()\n\n def test_valid_request(self, validator):\n \"\"\"Test completely valid request.\"\"\"\n request = MetricRequest(\n service=\"test-service\",\n version=\"1.0.0\",\n instance_id=\"instance-01\",\n metrics=[\n Metric(\n type=MetricType.AUTH_REQUEST,\n value=1.0,\n duration_ms=150.5,\n dimensions={\"success\": True, \"method\": \"oauth\"},\n metadata={\"user_agent\": \"test-client\"},\n )\n ],\n )\n\n result = validator.validate_metric_request(request)\n\n assert result.is_valid\n assert len(result.errors) == 0\n\n def test_empty_metrics_array(self, validator):\n \"\"\"Test request with empty metrics array.\"\"\"\n request = MetricRequest(service=\"test-service\", metrics=[])\n\n result = validator.validate_metric_request(request)\n\n assert not result.is_valid\n assert \"At least one metric is required\" in result.errors[0].message\n\n def test_too_many_metrics(self, validator):\n \"\"\"Test request with too many metrics.\"\"\"\n # Create 101 metrics (exceeds limit of 100)\n metrics = []\n for i in range(101):\n metrics.append(Metric(type=MetricType.AUTH_REQUEST, value=1.0))\n\n request = MetricRequest(service=\"test-service\", metrics=metrics)\n\n result = validator.validate_metric_request(request)\n\n assert not result.is_valid\n assert \"Too many metrics\" in result.errors[0].message\n\n def test_invalid_service_propagates(self, validator):\n \"\"\"Test that invalid service name propagates to result.\"\"\"\n request = MetricRequest(\n service=\"invalid service name\", # Contains space\n metrics=[Metric(type=MetricType.AUTH_REQUEST, value=1.0)],\n )\n\n result = validator.validate_metric_request(request)\n\n assert not result.is_valid\n assert any(\"alphanumeric\" in error.message for error in result.errors)\n\n def test_metric_validation_with_index(self, validator):\n \"\"\"Test that metric validation includes array index in error messages.\"\"\"\n # Create a mock metric with invalid dimensions to test indexing\n metric1 = Metric(type=MetricType.AUTH_REQUEST, value=1.0) # Valid\n metric2 = Metric(\n type=MetricType.AUTH_REQUEST,\n value=1.0,\n dimensions={\"invalid-key\": \"value\"}, # Invalid key format\n )\n\n request = MetricRequest(service=\"test-service\", metrics=[metric1, metric2])\n\n result = validator.validate_metric_request(request)\n\n assert not result.is_valid\n assert any(\"metrics[1]\" in error.field for error in result.errors)\n" }, { "path": "mkdocs.yml", "content": "site_name: MCP Gateway & Registry\nsite_description: Enterprise-grade MCP server registry and reverse proxy with OAuth authentication and fine-grained access control\nsite_author: Agentic Community\nsite_url: https://agentic-community.github.io/mcp-gateway-registry/\n\n# Repository\nrepo_name: agentic-community/mcp-gateway-registry\nrepo_url: https://github.com/agentic-community/mcp-gateway-registry\n\n# Copyright\ncopyright: Copyright © 2025 Agentic Community\n\n# Configuration\ntheme:\n name: material\n palette:\n # Palette toggle for light mode\n - scheme: default\n primary: blue\n accent: blue\n toggle:\n icon: material/brightness-7\n name: Switch to dark mode\n # Palette toggle for dark mode\n - scheme: slate\n primary: blue\n accent: blue\n toggle:\n icon: material/brightness-4\n name: Switch to light mode\n font:\n text: Roboto\n code: Roboto Mono\n features:\n - navigation.tabs\n - navigation.sections\n - navigation.expand\n - navigation.top\n - search.highlight\n - search.share\n - toc.follow\n - toc.integrate\n - content.code.copy\n - content.code.annotate\n logo: img/mcp_gateway_horizontal_white_logo.png\n favicon: img/registry.png\n\n# Plugins\nplugins:\n - search:\n lang: en\n - git-revision-date-localized:\n enable_creation_date: true\n - minify:\n minify_html: true\n\n# Extensions\nmarkdown_extensions:\n - abbr\n - admonition\n - attr_list\n - def_list\n - footnotes\n - md_in_html\n - toc:\n permalink: true\n - pymdownx.arithmatex:\n generic: true\n - pymdownx.betterem:\n smart_enable: all\n - pymdownx.caret\n - pymdownx.details\n - pymdownx.emoji:\n emoji_generator: !!python/name:material.extensions.emoji.to_svg\n emoji_index: !!python/name:material.extensions.emoji.twemoji\n - pymdownx.highlight:\n anchor_linenums: true\n - pymdownx.inlinehilite\n - pymdownx.keys\n - pymdownx.magiclink:\n repo_url_shorthand: true\n user: agentic-community\n repo: mcp-gateway-registry\n - pymdownx.mark\n - pymdownx.smartsymbols\n - pymdownx.superfences:\n custom_fences:\n - name: mermaid\n class: mermaid\n format: !!python/name:pymdownx.superfences.fence_code_format\n - pymdownx.tabbed:\n alternate_style: true\n - pymdownx.tasklist:\n custom_checkbox: true\n - pymdownx.tilde\n\n# Page tree\nnav:\n - Home: index.md\n - Getting Started:\n - Complete Setup Guide: complete-setup-guide.md\n - Installation: installation.md\n - Configuration: configuration.md\n - FAQ: faq/index.md\n - Authentication & Security:\n - Authentication Guide: auth.md\n - Registry API Authentication: registry-api-auth.md\n - IAM Settings UI: iam-settings-ui.md\n - Amazon Cognito Setup: cognito.md\n - Access Control & Scopes: scopes.md\n - JWT Token Vending: jwt-token-vending.md\n - Security Policy: SECURITY.md\n - Architecture & Development:\n - Registry API: registry_api.md\n - Dynamic Tool Discovery: dynamic-tool-discovery.md\n - Architecture Overview: registry-auth-architecture.md\n - Detailed Architecture: registry-auth-detailed.md\n - Integration:\n - AI Coding Assistants: ai-coding-assistants-setup.md\n - MCP-Gateway CLI Guide: mcp-registry-cli.md\n - Contributing:\n - Contributing Guide: CONTRIBUTING.md\n - Code of Conduct: CODE_OF_CONDUCT.md\n - Legal:\n - License: LICENSE.md\n - Notice: NOTICE.md\n\n# Extra\nextra:\n social:\n - icon: fontawesome/brands/github\n link: https://github.com/agentic-community/mcp-gateway-registry\n - icon: fontawesome/brands/discord\n link: https://discord.gg/agentic-community\n generator: false\n\n# Analytics (optional - add your Google Analytics ID if needed)\n# extra:\n# analytics:\n# provider: google\n# property: G-XXXXXXXXXX" }, { "path": "package.json", "content": "{\n \"dependencies\": {\n \"@tailwindcss/forms\": \"^0.5.10\",\n \"autoprefixer\": \"^10.4.21\",\n \"postcss\": \"^8.5.10\",\n \"tailwindcss\": \"^4.1.10\"\n }\n}\n" }, { "path": "pyproject.toml", "content": "[build-system]\nrequires = [\"setuptools>=68.0\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"mcp-registry\"\nversion = \"0.1.0\"\ndescription = \"A registry for MCP servers\"\nreadme = \"README.md\"\nrequires-python = \">=3.14\"\ndependencies = [\n \"aiofiles>=24.1.0\",\n \"fastapi>=0.115.12\",\n \"itsdangerous>=2.2.0\",\n \"jinja2>=3.1.6\",\n \"mcp>=1.9.3\",\n \"pydantic>=2.11.3\",\n \"pydantic-settings>=2.0.0\",\n \"httpx>=0.27.0\",\n \"python-dotenv>=1.2.2\",\n \"python-multipart>=0.0.26\",\n \"uvicorn[standard]>=0.34.2\",\n \"faiss-cpu>=1.7.4\",\n \"sentence-transformers>=3.0.0\",\n \"websockets>=15.0.1\",\n \"scikit-learn>=1.3.0\",\n \"torch>=1.6.0\",\n \"huggingface-hub>=0.31.1\",\n \"bandit>=1.8.3\",\n \"langchain-core>=1.2.28\",\n \"langchain-mcp-adapters>=0.0.11\",\n \"langgraph>=0.4.3\",\n \"langchain-aws>=0.2.23\",\n \"pytz>=2025.2\",\n \"strands-agents>=0.1.6\",\n \"strands-agents-tools>=0.1.4\",\n \"pyjwt>=2.12.0\",\n \"typing-extensions>=4.8.0\",\n \"httpcore[asyncio]>=1.0.9\",\n \"pyyaml>=6.0.0\",\n \"langchain-anthropic>=0.3.17\",\n \"matplotlib>=3.10.5\",\n \"psutil>=6.1.0\",\n \"email-validator>=2.2.0\",\n \"aiohttp>=3.8.0\",\n \"rich>=13.0.0\",\n \"requests>=2.31.0\",\n \"cisco-ai-a2a-scanner @ git+https://github.com/cisco-ai-defense/a2a-scanner.git@8f6e27f\",\n \"cisco-ai-skill-scanner>=1.0.0\",\n \"cisco-ai-mcp-scanner>=3.0.1\",\n \"awscli>=1.36.0\",\n \"boto3>=1.42.87\",\n \"motor>=3.3.0\",\n \"pymongo>=4.6.0\",\n \"dnspython>=2.4.0\",\n \"litellm==1.83.0\",\n \"cryptography>=46.0.7\",\n \"prometheus-client>=0.20.0\",\n]\n\n[project.optional-dependencies]\ndev = [\n \"pytest>=9.0.3\",\n \"pytest-asyncio>=0.23.0\",\n \"pytest-cov>=4.1.0\",\n \"pytest-mock>=3.12.0\",\n \"pytest-xdist>=3.5.0\",\n \"coverage[toml]>=7.4.0\",\n \"httpx>=0.27.0\", # For testing HTTP clients\n \"pytest-html>=4.1.1\",\n \"pytest-json-report>=1.5.0\",\n \"factory-boy>=3.3.0\",\n \"faker>=24.0.0\",\n \"freezegun>=1.4.0\",\n \"hypothesis>=6.100.0\",\n]\ndocs = [\n \"mkdocs>=1.5.0\",\n \"mkdocs-material>=9.4.0\",\n \"mkdocs-git-revision-date-localized-plugin>=1.2.0\",\n \"mkdocs-minify-plugin>=0.7.0\",\n \"pymdown-extensions>=10.0.0\",\n]\n\n[tool.setuptools]\npackages = [\"registry\"]\n\n# Pytest Configuration\n[tool.pytest.ini_options]\nminversion = \"8.0\"\naddopts = [\n \"--strict-markers\",\n \"--strict-config\",\n \"--cov=registry\",\n \"--cov-report=term-missing\",\n \"--cov-report=html:htmlcov\",\n \"--cov-report=xml:coverage.xml\",\n \"--cov-fail-under=35\",\n \"--html=tests/reports/report.html\",\n \"--self-contained-html\",\n \"--json-report\",\n \"--json-report-file=tests/reports/report.json\",\n # Memory management for EC2 instances\n # By default, run tests serially to avoid OOM crashes\n # Use -n 2 or -n auto explicitly if you have enough memory\n]\ntestpaths = [\"tests\"]\npython_files = [\"test_*.py\", \"*_test.py\"]\npython_classes = [\"Test*\"]\npython_functions = [\"test_*\"]\nasyncio_mode = \"auto\"\nasyncio_default_fixture_loop_scope = \"function\"\nmarkers = [\n \"unit: Unit tests\",\n \"integration: Integration tests\",\n \"e2e: End-to-end tests\",\n \"auth: Authentication tests\",\n \"servers: Server management tests\",\n \"search: Search and AI tests\",\n \"health: Health monitoring tests\",\n \"core: Core infrastructure tests\",\n \"repositories: Repository layer tests\",\n \"slow: Slow running tests\",\n \"requires_models: Tests that require real ML models (will load heavy dependencies)\",\n \"live: Tests that require live AWS infrastructure (collector endpoint, CloudWatch)\",\n]\n\n# Coverage Configuration\n[tool.coverage.run]\nsource = [\"registry\"]\nbranch = true\nparallel = true\nomit = [\n \"*/tests/*\",\n \"*/test_*\",\n \"*/__pycache__/*\",\n \"*/migrations/*\",\n \"*/venv/*\",\n \"*/.venv/*\",\n \"registry/main_old.py\",\n]\n\n[tool.coverage.paths]\nsource = [\n \"registry/\",\n \"*/site-packages/registry/\",\n]\n\n[tool.coverage.report]\nshow_missing = true\nskip_covered = false\nskip_empty = true\nsort = \"cover\"\nexclude_lines = [\n \"pragma: no cover\",\n \"def __repr__\",\n \"if self.debug:\",\n \"if settings.DEBUG\",\n \"raise AssertionError\",\n \"raise NotImplementedError\",\n \"if 0:\",\n \"if __name__ == .__main__.:\",\n \"class .*\\\\bProtocol\\\\):\",\n \"@(abc\\\\.)?abstractmethod\",\n]\n\n[tool.coverage.html]\ndirectory = \"htmlcov\"\ntitle = \"MCP Registry Coverage Report\"\n\n[tool.uv]\n# Local-only project - never resolve from PyPI\npackage = false\n\n# Bandit Configuration\n# B101 (assert_used): exclude test directories where assert is expected\n# Requires: bandit -c pyproject.toml -r .\n# See: https://bandit.readthedocs.io/en/latest/plugins/b101_assert_used.html\n# NOTE: cli/ and scripts/ are NOT excluded - they contain operational code that should be scanned\n[tool.bandit]\nexclude_dirs = [\"tests\", \"*/test/*\", \"*/tests/*\", \".venv\"]\n\n# Ruff Configuration\n[tool.ruff]\nline-length = 100\ntarget-version = \"py311\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"W\", \"F\", \"I\", \"B\", \"C4\", \"UP\"]\nignore = [\"E501\", \"B008\", \"B904\", \"B019\", \"C401\", \"B007\", \"E402\", \"F841\", \"F823\", \"E722\", \"F811\", \"W293\", \"W291\", \"F821\"]\n\n[tool.ruff.format]\nquote-style = \"double\"\nindent-style = \"space\"\n\n[dependency-groups]\ndev = [\n \"factory-boy>=3.3.3\",\n \"hypothesis>=6.151.4\",\n \"pytest-asyncio>=1.3.0\",\n \"pytest-cov>=7.0.0\",\n \"pytest-html>=4.1.1\",\n \"pytest-json-report>=1.5.0\",\n \"pytest-xdist>=3.8.0\",\n \"qrcode[pil]>=8.2\",\n]\n" }, { "path": "registry/api/__init__.py", "content": "" }, { "path": "registry/api/agent_routes.py", "content": "\"\"\"\nA2A Agent API routes for MCP Gateway Registry.\n\nThis module provides REST API endpoints for agent registration, discovery,\nand management following the A2A protocol specification.\n\nBased on: docs/design/a2a-protocol-integration.md\n\"\"\"\n\nimport asyncio\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Annotated, Any\n\nimport httpx\nfrom fastapi import (\n APIRouter,\n Depends,\n HTTPException,\n Query,\n Request,\n status,\n)\nfrom fastapi.responses import JSONResponse\nfrom pydantic import BaseModel\n\nfrom ..audit import set_audit_action\nfrom ..auth.csrf import verify_csrf_token_flexible\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..core.config import settings\nfrom ..repositories.factory import get_search_repository\nfrom ..repositories.interfaces import SearchRepositoryBase\nfrom ..schemas.agent_models import (\n AgentCard,\n AgentInfo,\n AgentProvider,\n AgentRegistrationRequest,\n)\nfrom ..services.agent_service import agent_service\nfrom ..services.registration_gate_service import check_registration_gate\nfrom ..utils.metadata import flatten_metadata_to_text\nfrom ..services.webhook_service import send_registration_webhook\nfrom ..utils.request_utils import get_client_ip\n\n\ndef get_search_repo() -> SearchRepositoryBase:\n \"\"\"Get search repository instance.\"\"\"\n return get_search_repository()\n\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nrouter = APIRouter()\n\n\nasync def _perform_agent_security_scan_on_registration(\n path: str,\n agent_card: AgentCard,\n agent_card_dict: dict,\n) -> bool:\n \"\"\"Perform security scan on newly registered agent.\n\n Handles the complete security scan workflow including:\n - Running the security scan with configured analyzers\n - Adding security-pending tag if scan fails\n - Disabling agent if configured and scan fails\n - Updating FAISS with disabled state if agent disabled\n\n All scan failures are non-fatal and will be logged but not raised.\n\n Args:\n path: Agent path (e.g., /code-reviewer)\n agent_card: AgentCard Pydantic model instance\n agent_card_dict: Agent card as dictionary for scanning\n\n Returns:\n bool: True if agent should remain enabled, False if disabled due to scan\n \"\"\"\n from ..repositories.factory import get_search_repository\n from ..services.agent_scanner import agent_scanner_service\n\n scan_config = agent_scanner_service.get_scan_config()\n if not (scan_config.enabled and scan_config.scan_on_registration):\n return True # Agent remains enabled\n\n logger.info(f\"Running A2A security scan for newly registered agent: {path}\")\n\n try:\n # Run the security scan\n scan_result = await agent_scanner_service.scan_agent(\n agent_card=agent_card_dict,\n agent_path=path,\n analyzers=scan_config.analyzers,\n api_key=scan_config.llm_api_key,\n timeout=scan_config.scan_timeout_seconds,\n )\n\n # Handle unsafe agents\n if not scan_result.is_safe:\n logger.warning(\n f\"Agent {path} failed security scan. \"\n f\"Critical: {scan_result.critical_issues}, High: {scan_result.high_severity}\"\n )\n\n # Add security-pending tag if configured\n if scan_config.add_security_pending_tag:\n current_tags = agent_card.tags or []\n if \"security-pending\" not in current_tags:\n current_tags.append(\"security-pending\")\n agent_card.tags = current_tags\n # Update agent with new tags\n agent_info = await agent_service.get_agent_info(path)\n if agent_info:\n updated_card = agent_info.model_dump()\n updated_card[\"tags\"] = current_tags\n from ..schemas.agent_models import AgentCard as AgentCardModel\n\n await agent_service.register_agent(AgentCardModel(**updated_card))\n logger.info(f\"Added 'security-pending' tag to agent {path}\")\n\n # Disable agent if configured\n if scan_config.block_unsafe_agents:\n await agent_service.toggle_agent(path, False)\n logger.warning(f\"Disabled agent {path} due to failed security scan\")\n\n # Update search index with disabled state\n search_repo = get_search_repository()\n await search_repo.index_agent(path, agent_card_dict, is_enabled=False)\n return False # Agent disabled\n\n else:\n logger.info(f\"Agent {path} passed security scan\")\n\n return True # Agent remains enabled\n\n except Exception as e:\n logger.error(f\"Failed to run security scan for agent {path}: {e}\")\n # Non-fatal error - agent is registered but not scanned\n return True # Agent remains enabled on scan error\n\n\nclass RatingRequest(BaseModel):\n rating: int\n\n\ndef _build_agent_health_urls(\n base_url: str,\n) -> list[str]:\n \"\"\"Build health check URLs for an A2A agent in priority order.\n\n Per the A2A spec, there is no /ping endpoint. Agent availability\n is determined by fetching the agent card at /.well-known/agent-card.json.\n Falls back to the registered URL for non-A2A agents.\n\n Args:\n base_url: The agent's registered URL (e.g., https://agent.example.com/a2a)\n\n Returns:\n List of URLs to try in order (agent card first, then registered URL)\n \"\"\"\n from urllib.parse import urlparse\n\n parsed = urlparse(base_url)\n agent_card_url = f\"{parsed.scheme}://{parsed.netloc}/.well-known/agent-card.json\"\n return [agent_card_url, base_url]\n\n\ndef _normalize_path(\n path: str | None,\n agent_name: str | None = None,\n) -> str:\n \"\"\"\n Normalize agent path format.\n\n If path is None, derives it from agent_name by converting to lowercase\n and replacing spaces with hyphens.\n\n Args:\n path: Agent path to normalize, or None to auto-generate\n agent_name: Agent name used for auto-generating path if needed\n\n Returns:\n Normalized path string\n\n Raises:\n ValueError: If path is None and agent_name is not provided\n \"\"\"\n if path is None:\n if not agent_name:\n raise ValueError(\"Path is required or agent_name must be provided for auto-generation\")\n path = agent_name.lower().replace(\" \", \"-\")\n\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n if path.endswith(\"/\") and len(path) > 1:\n path = path.rstrip(\"/\")\n\n return path\n\n\ndef _check_agent_permission(\n permission: str,\n agent_name: str,\n user_context: dict[str, Any],\n) -> None:\n \"\"\"\n Check if user has permission for agent operation.\n\n Args:\n permission: Permission to check\n agent_name: Name of the agent\n user_context: User context from auth\n\n Raises:\n HTTPException: If user lacks permission\n \"\"\"\n from ..auth.dependencies import user_has_ui_permission_for_service\n\n if not user_has_ui_permission_for_service(\n permission,\n agent_name,\n user_context.get(\"ui_permissions\", {}),\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to perform {permission} \"\n f\"on agent {agent_name} without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"You do not have permission to {permission} for {agent_name}\",\n )\n\n\ndef _has_delete_agent_permission(user_context: dict[str, Any], agent_path: str) -> bool:\n \"\"\"\n Check if user has permission to delete an agent.\n\n Permission hierarchy:\n 1. Admin users can delete any agent\n 2. Users with delete_agent UI permission for \"all\" can delete any agent\n 3. Users with delete_agent UI permission for the specific agent path can delete it\n\n Note: Agent ownership is checked separately in the delete endpoint.\n\n Args:\n user_context: User context from auth containing is_admin and ui_permissions\n agent_path: Path of the agent to delete (e.g., \"/code-reviewer\")\n\n Returns:\n bool: True if user has delete permission, False otherwise\n \"\"\"\n # Admin users can delete any agent\n if user_context.get(\"is_admin\", False):\n return True\n\n # Check delete_agent UI permission\n ui_permissions = user_context.get(\"ui_permissions\", {})\n delete_perms = ui_permissions.get(\"delete_agent\", [])\n\n # \"all\" grants permission to delete any agent\n if \"all\" in delete_perms:\n return True\n\n # Check if user has permission for this specific agent path\n # Normalize path for comparison (remove leading slash if present)\n normalized_path = agent_path.lstrip(\"/\")\n if agent_path in delete_perms or normalized_path in delete_perms:\n return True\n\n return False\n\n\ndef _filter_agents_by_access(\n agents: list[AgentCard],\n user_context: dict[str, Any],\n) -> list[AgentCard]:\n \"\"\"\n Filter agents based on user access permissions.\n\n Args:\n agents: List of agent cards\n user_context: User context from auth\n\n Returns:\n Filtered list of agents user can access\n \"\"\"\n accessible = []\n user_groups = set(user_context.get(\"groups\", []))\n username = user_context[\"username\"]\n is_admin = user_context.get(\"is_admin\", False)\n\n # Get accessible agents from user context (UI-Scopes)\n accessible_agent_list = user_context.get(\"accessible_agents\", [])\n logger.debug(f\"User {username} accessible agents from UI-Scopes: {accessible_agent_list}\")\n\n for agent in agents:\n if is_admin:\n accessible.append(agent)\n continue\n\n # Check if user has agent-level restrictions from UI-Scopes\n if \"all\" not in accessible_agent_list and agent.path not in accessible_agent_list:\n logger.debug(\n f\"Agent {agent.path} filtered out: not in accessible agents {accessible_agent_list}\"\n )\n continue\n\n if agent.visibility == \"public\":\n accessible.append(agent)\n continue\n\n if agent.visibility == \"private\":\n if agent.registered_by == username:\n accessible.append(agent)\n continue\n\n if agent.visibility == \"group-restricted\":\n agent_groups = set(agent.allowed_groups)\n if agent_groups & user_groups:\n accessible.append(agent)\n continue\n\n return accessible\n\n\n@router.post(\"/agents/register\")\nasync def register_agent(\n http_request: Request,\n request: AgentRegistrationRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Register a new A2A agent in the registry.\n\n Requires publish_agent scope/permission.\n\n Args:\n request: Agent registration request data\n user_context: Authenticated user context\n\n Returns:\n 201 with agent card and registration metadata\n\n Raises:\n HTTPException: 409 if path exists, 422 if validation fails, 403 if unauthorized\n \"\"\"\n # Set audit action for agent registration\n set_audit_action(\n http_request,\n \"create\",\n \"agent\",\n resource_id=request.path,\n description=f\"Register agent {request.name}\",\n )\n\n ui_permissions = user_context.get(\"ui_permissions\", {})\n publish_permissions = ui_permissions.get(\"publish_agent\", [])\n\n if not publish_permissions:\n logger.warning(\n f\"User {user_context['username']} attempted to register agent without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have permission to register agents\",\n )\n\n logger.info(f\"Agent registration request from user '{user_context['username']}'\")\n logger.info(f\"Name: {request.name}, Path: {request.path}, URL: {request.url}\")\n\n path = _normalize_path(request.path, request.name)\n\n if await agent_service.get_agent_info(path):\n logger.error(f\"Agent registration failed: path '{path}' already exists\")\n return JSONResponse(\n status_code=status.HTTP_409_CONFLICT,\n content={\n \"detail\": f\"Agent with path '{path}' already exists\",\n \"suggestion\": \"Use a different path or update the existing agent\",\n },\n )\n\n tag_list = [tag.strip() for tag in request.tags.split(\",\") if tag.strip()]\n\n # Parse external_tags\n external_tag_list = []\n if request.external_tags:\n if isinstance(request.external_tags, str):\n external_tag_list = [\n tag.strip() for tag in request.external_tags.split(\",\") if tag.strip()\n ]\n elif isinstance(request.external_tags, list):\n external_tag_list = [tag.strip() for tag in request.external_tags if tag.strip()]\n\n # Convert provider dict to AgentProvider object if provided\n provider_obj = None\n if request.provider:\n provider_obj = AgentProvider(\n organization=request.provider.get(\"organization\", \"\"),\n url=request.provider.get(\"url\", \"\"),\n )\n\n # Parse source timestamps\n source_created_dt = None\n if request.source_created_at:\n try:\n source_created_dt = datetime.fromisoformat(\n request.source_created_at.replace(\"Z\", \"+00:00\")\n )\n except ValueError:\n logger.warning(f\"Invalid source_created_at format: {request.source_created_at}\")\n\n source_updated_dt = None\n if request.source_updated_at:\n try:\n source_updated_dt = datetime.fromisoformat(\n request.source_updated_at.replace(\"Z\", \"+00:00\")\n )\n except ValueError:\n logger.warning(f\"Invalid source_updated_at format: {request.source_updated_at}\")\n\n try:\n from ..utils.agent_validator import agent_validator\n\n # Build optional kwargs for fields that have defaults on AgentCard\n optional_card_kwargs: dict[str, Any] = {}\n if request.default_input_modes:\n optional_card_kwargs[\"default_input_modes\"] = request.default_input_modes\n if request.default_output_modes:\n optional_card_kwargs[\"default_output_modes\"] = request.default_output_modes\n if request.metadata:\n optional_card_kwargs[\"metadata\"] = request.metadata\n # Build capabilities: merge explicit capabilities dict with streaming bool\n capabilities = dict(request.capabilities) if request.capabilities else {}\n if request.streaming and \"streaming\" not in capabilities:\n capabilities[\"streaming\"] = request.streaming\n if capabilities:\n optional_card_kwargs[\"capabilities\"] = capabilities\n\n agent_card = AgentCard(\n protocol_version=request.protocol_version,\n name=request.name,\n description=request.description,\n url=request.url,\n path=path,\n version=request.version,\n status=request.status,\n provider=provider_obj,\n security_schemes=request.security_schemes or {},\n skills=request.skills or [],\n tags=tag_list,\n license=request.license,\n visibility=request.visibility,\n allowed_groups=request.allowed_groups,\n trust_level=request.trust_level,\n supported_protocol=request.supported_protocol,\n registered_by=user_context[\"username\"],\n source_created_at=source_created_dt,\n source_updated_at=source_updated_dt,\n external_tags=external_tag_list,\n **optional_card_kwargs,\n )\n\n validation_result = await agent_validator.validate_agent_card(\n agent_card,\n verify_endpoint=True,\n )\n\n if not validation_result.is_valid:\n logger.error(f\"Agent validation failed: {validation_result.errors}\")\n raise HTTPException(\n status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n detail={\n \"message\": \"Agent card validation failed\",\n \"errors\": validation_result.errors,\n \"warnings\": validation_result.warnings,\n },\n )\n\n except ValueError as e:\n logger.error(f\"Invalid agent card data: {e}\")\n raise HTTPException(\n status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n detail=f\"Invalid agent card: {str(e)}\",\n )\n\n # Registration gate check (admission control, issue #809)\n gate_result = await check_registration_gate(\n asset_type=\"agent\",\n operation=\"register\",\n source_api=\"/api/agents/register\",\n registration_payload=request.model_dump(mode=\"json\"),\n raw_headers=http_request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied agent '{request.name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n success = await agent_service.register_agent(agent_card)\n\n if not success:\n return JSONResponse(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n content={\n \"detail\": \"Failed to save agent data\",\n \"suggestion\": \"Check server logs for details\",\n },\n )\n\n from ..search.service import faiss_service\n\n is_enabled = await agent_service.is_agent_enabled(path)\n await faiss_service.add_or_update_entity(\n path,\n agent_card.model_dump(),\n \"a2a_agent\",\n is_enabled,\n )\n\n logger.info(\n f\"New agent registered: '{request.name}' at path '{path}' \"\n f\"by user '{user_context['username']}'\"\n )\n\n # Agent security scanning if enabled\n agent_card_dict = agent_card.model_dump()\n is_enabled = await _perform_agent_security_scan_on_registration(\n path, agent_card, agent_card_dict\n )\n\n # Best-effort ANS linking if ans_agent_id is provided\n if request.ans_agent_id and settings.ans_integration_enabled:\n try:\n from ..services.ans_service import link_ans_to_agent\n\n ans_result = await link_ans_to_agent(\n agent_path=path,\n ans_agent_id=request.ans_agent_id,\n username=user_context[\"username\"],\n )\n if ans_result.get(\"success\"):\n logger.info(f\"ANS ID '{request.ans_agent_id}' linked to agent '{path}'\")\n else:\n logger.warning(\n f\"Failed to link ANS ID '{request.ans_agent_id}' to agent '{path}': \"\n f\"{ans_result.get('message', 'Unknown error')}\"\n )\n except Exception as e:\n logger.warning(\n f\"ANS linking failed for agent '{path}' with ANS ID '{request.ans_agent_id}': {e}\"\n )\n\n # Registration webhook (Issue #742)\n asyncio.create_task(\n send_registration_webhook(\n event_type=\"registration\",\n registration_type=\"agent\",\n card_data=agent_card.model_dump(mode=\"json\"),\n performed_by=user_context[\"username\"],\n )\n )\n\n return JSONResponse(\n status_code=status.HTTP_201_CREATED,\n content={\n \"message\": \"Agent registered successfully\",\n \"agent\": {\n \"name\": agent_card.name,\n \"path\": agent_card.path,\n \"url\": str(agent_card.url),\n \"num_skills\": len(agent_card.skills),\n \"registered_at\": (\n agent_card.registered_at.isoformat() if agent_card.registered_at else None\n ),\n \"is_enabled\": is_enabled,\n },\n },\n )\n\n\n@router.get(\"/agents\")\nasync def list_agents(\n request: Request,\n query: str | None = Query(\n None,\n description=\"Lexical substring search across agent name, description, tags, skill names, and metadata\",\n ),\n enabled_only: bool = Query(False, description=\"Show only enabled agents\"),\n visibility: str | None = Query(None, description=\"Filter by visibility\"),\n allowed_groups: str | None = Query(\n None,\n alias=\"allowed_groups\",\n description=\"Filter by allowed_groups (comma-separated). Returns only group-restricted agents whose allowed_groups intersect with the given values.\",\n ),\n limit: int = Query(20, ge=1, le=500, description=\"Number of agents to return (max 500)\"),\n offset: int = Query(0, ge=0, description=\"Number of agents to skip\"),\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n List all agents filtered by user permissions with pagination.\n\n Uses lexical (substring) search, not hybrid/semantic. For vector-based\n search, use POST /api/search/semantic instead.\n\n Args:\n query: Lexical substring filter across name, description, tags, skill names, and metadata\n enabled_only: Only return enabled agents\n visibility: Filter by visibility level\n limit: Number of agents to return (1-500, default 20)\n offset: Number of agents to skip (default 0)\n user_context: Authenticated user context\n\n Returns:\n Paginated list of agent info objects with metadata\n \"\"\"\n # Set audit action for agent list\n set_audit_action(request, \"list\", \"agent\", description=\"List all agents\")\n\n logger.debug(\n f\"list_agents called: limit={limit}, offset={offset}, \"\n f\"query={query!r}, enabled_only={enabled_only}, visibility={visibility}\"\n )\n\n # CRITICAL DIAGNOSTIC: Log that we reached this endpoint\n logger.info(f\"[GET_AGENTS_ENTRY] GET /api/agents called from {get_client_ip(request)}\")\n logger.info(f\"[GET_AGENTS_ENTRY] Request headers: {dict(request.headers)}\")\n\n # CRITICAL DIAGNOSTIC: Log user_context received by endpoint (for comparison with /servers)\n logger.info(f\"[GET_AGENTS_DEBUG] Received user_context: {user_context}\")\n logger.info(f\"[GET_AGENTS_DEBUG] user_context type: {type(user_context)}\")\n if user_context:\n logger.info(f\"[GET_AGENTS_DEBUG] Username: {user_context.get('username', 'NOT PRESENT')}\")\n logger.info(f\"[GET_AGENTS_DEBUG] Scopes: {user_context.get('scopes', 'NOT PRESENT')}\")\n logger.info(\n f\"[GET_AGENTS_DEBUG] Auth method: {user_context.get('auth_method', 'NOT PRESENT')}\"\n )\n logger.info(\n f\"[GET_AGENTS_DEBUG] Accessible agents: {user_context.get('accessible_agents', 'NOT PRESENT')}\"\n )\n\n # Determine if user has unrestricted access (no agents will be filtered out)\n is_admin = user_context.get(\"is_admin\", False) if user_context else False\n accessible_agent_list = user_context.get(\"accessible_agents\", []) if user_context else []\n has_field_filters = bool(query or enabled_only or visibility or allowed_groups)\n # Admins skip all filtering. Non-admin users with \"all\" in accessible_agents\n # still need _filter_agents_by_access to enforce group-restricted visibility.\n is_unrestricted = is_admin\n\n # Dual-path pagination:\n # - Fast path: DB-level skip/limit for unrestricted users without field filters\n # - Fallback: full fetch + Python filter + slice for restricted users or when field filters active\n if is_unrestricted and not has_field_filters:\n # FAST PATH: DB-level pagination — correct because no agents are filtered out\n # and no field filters need a full scan for accurate total_count\n all_agents, db_total = await agent_service.get_agents_paginated(skip=offset, limit=limit)\n accessible_agents = all_agents\n else:\n # FALLBACK PATH: full fetch needed\n all_agents = await agent_service.get_all_agents()\n if is_unrestricted:\n accessible_agents = all_agents\n else:\n accessible_agents = _filter_agents_by_access(all_agents, user_context)\n\n filtered_agents = []\n search_query = query.lower() if query else \"\"\n\n for agent in accessible_agents:\n if enabled_only and not await agent_service.is_agent_enabled(agent.path):\n continue\n\n if visibility and agent.visibility != visibility:\n continue\n\n if allowed_groups:\n requested_groups = {g.strip() for g in allowed_groups.split(\",\") if g.strip()}\n agent_groups = set(getattr(agent, \"allowed_groups\", []))\n if not requested_groups.intersection(agent_groups):\n continue\n\n metadata_text = flatten_metadata_to_text(agent.metadata) if agent.metadata else \"\"\n searchable_text = (\n f\"{agent.name.lower()} {agent.description.lower()} \"\n f\"{' '.join(agent.tags)} {' '.join([s.name for s in agent.skills])} \"\n f\"{metadata_text.lower()}\"\n )\n\n if not search_query or search_query in searchable_text:\n # Extract streaming capability from agent capabilities dict\n streaming = agent.capabilities.get(\"streaming\", False) if agent.capabilities else False\n\n # Extract provider organization name (provider is AgentProvider object)\n provider_name = agent.provider.organization if agent.provider else None\n\n agent_info = AgentInfo(\n name=agent.name,\n description=agent.description,\n path=agent.path,\n url=str(agent.url),\n tags=agent.tags,\n skills=[s.name for s in agent.skills],\n num_skills=len(agent.skills),\n num_stars=agent.num_stars,\n is_enabled=await agent_service.is_agent_enabled(agent.path),\n provider=provider_name,\n streaming=streaming,\n trust_level=agent.trust_level,\n sync_metadata=agent.sync_metadata,\n ans_metadata=agent.ans_metadata,\n registered_by=agent.registered_by,\n status=agent.status if hasattr(agent, \"status\") and agent.status else \"active\",\n provider_organization=agent.provider.organization if agent.provider else None,\n provider_url=agent.provider.url if agent.provider else None,\n source_created_at=agent.source_created_at.isoformat()\n if agent.source_created_at\n else None,\n source_updated_at=agent.source_updated_at.isoformat()\n if agent.source_updated_at\n else None,\n registered_at=agent.registered_at.isoformat() if agent.registered_at else None,\n updated_at=agent.updated_at.isoformat() if agent.updated_at else None,\n health_status=agent.health_status or \"unknown\",\n last_health_check=agent.last_health_check.isoformat()\n if agent.last_health_check\n else None,\n visibility=getattr(agent, \"visibility\", \"public\"),\n allowed_groups=getattr(agent, \"allowed_groups\", []),\n supported_protocol=getattr(agent, \"supported_protocol\", None),\n metadata=agent.metadata if agent.metadata else {},\n )\n filtered_agents.append(agent_info)\n\n # Compute pagination metadata\n if is_unrestricted and not has_field_filters:\n # Fast path: total from DB, agents already paginated\n total_count = db_total\n page_agents = filtered_agents\n else:\n # Fallback path: slice the fully-filtered list\n total_count = len(filtered_agents)\n page_agents = filtered_agents[offset : offset + limit]\n\n has_next = (offset + limit) < total_count\n\n logger.info(\n f\"User {user_context['username']} listed {len(page_agents)} agents \"\n f\"(total: {total_count}, offset: {offset}, limit: {limit})\"\n )\n\n return {\n \"agents\": [agent.model_dump() for agent in page_agents],\n \"total_count\": total_count,\n \"limit\": limit,\n \"offset\": offset,\n \"has_next\": has_next,\n }\n\n\n# IMPORTANT: Specific routes with path suffixes (/health, /rate, /rating, /toggle)\n# must come BEFORE catch-all {path:path} routes to prevent FastAPI from matching them incorrectly\n\n\n@router.post(\"/agents/{path:path}/health\")\nasync def check_agent_health(\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"Perform a health check against an A2A agent.\n\n Per the A2A spec, there is no /ping endpoint. Agent availability is\n determined by fetching the agent card from /.well-known/agent-card.json\n on the agent's host. Falls back to the registered URL if the agent card\n endpoint is not available.\n \"\"\"\n path = _normalize_path(path)\n\n agent_card = await agent_service.get_agent_info(path)\n if not agent_card:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n accessible = _filter_agents_by_access([agent_card], user_context)\n if not accessible:\n logger.warning(\n f\"User {user_context['username']} attempted to health check agent {path} without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this agent\",\n )\n\n if not await agent_service.is_agent_enabled(path):\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Cannot perform health check on a disabled agent\",\n )\n\n base_url = str(agent_card.url).rstrip(\"/\")\n health_urls = _build_agent_health_urls(base_url)\n timeout_seconds = max(1, settings.health_check_timeout_seconds)\n\n status_label = \"unhealthy\"\n detail = None\n status_code = None\n response_time_ms = None\n health_check_url = health_urls[0]\n\n for url in health_urls:\n health_check_url = url\n start_time = datetime.now(UTC)\n\n try:\n async with httpx.AsyncClient(timeout=timeout_seconds) as client:\n response = await client.get(url)\n status_code = response.status_code\n response_time_ms = int((datetime.now(UTC) - start_time).total_seconds() * 1000)\n\n if response.status_code == 200:\n status_label = \"healthy\"\n detail = None\n logger.info(f\"Agent health check for {path} succeeded via GET on {url}\")\n break\n\n detail = f\"Agent responded with HTTP {response.status_code}\"\n logger.debug(f\"Agent health check for {path} got HTTP {response.status_code} on {url}\")\n\n except httpx.TimeoutException:\n detail = f\"Health check timed out on {url}\"\n logger.debug(f\"Agent health check for {path} timed out on {url}\")\n except httpx.HTTPError as exc:\n detail = f\"Health check failed on {url}\"\n logger.debug(f\"Agent health check for {path} failed on {url}: {exc}\")\n except Exception as exc:\n detail = f\"Unexpected health check error on {url}\"\n logger.debug(f\"Agent health check for {path} unexpected error on {url}: {exc}\")\n\n # Fallback: if GET-based checks failed, try HEAD on the base URL.\n # A non-connection-error response (even 401/403) means the server is reachable.\n if status_label == \"unhealthy\":\n logger.info(f\"Agent {path} GET checks failed, falling back to HEAD ping on {base_url}\")\n try:\n start_time = datetime.now(UTC)\n async with httpx.AsyncClient(timeout=timeout_seconds) as client:\n response = await client.head(base_url)\n status_code = response.status_code\n response_time_ms = int((datetime.now(UTC) - start_time).total_seconds() * 1000)\n health_check_url = base_url\n\n # Any HTTP response means the server is reachable\n status_label = \"healthy\"\n detail = f\"Reachable via HEAD (HTTP {response.status_code})\"\n logger.info(\n f\"Agent health check for {path} succeeded via HEAD ping \"\n f\"(HTTP {response.status_code})\"\n )\n except httpx.TimeoutException:\n logger.debug(f\"Agent {path} HEAD ping timed out on {base_url}\")\n except httpx.HTTPError as exc:\n logger.debug(f\"Agent {path} HEAD ping failed on {base_url}: {exc}\")\n except Exception as exc:\n logger.debug(f\"Agent {path} HEAD ping unexpected error on {base_url}: {exc}\")\n\n last_checked = datetime.now(UTC)\n last_checked_iso = last_checked.isoformat()\n\n # Persist health status to MongoDB\n try:\n await agent_service.update_agent(\n path,\n {\n \"health_status\": status_label,\n \"last_health_check\": last_checked,\n },\n )\n except Exception as e:\n logger.warning(f\"Failed to persist health status for agent {path}: {e}\")\n\n logger.info(\n f\"Agent health check for {path} completed with status {status_label} \"\n f\"(last URL tried: {health_check_url})\"\n )\n\n return {\n \"agent_path\": path,\n \"health_check_url\": health_check_url,\n \"status\": status_label,\n \"status_code\": status_code,\n \"detail\": detail,\n \"response_time_ms\": response_time_ms,\n \"last_checked_iso\": last_checked_iso,\n }\n\n\n@router.post(\"/agents/{path:path}/rate\")\nasync def rate_agent(\n request: Request,\n path: str,\n rating_request: RatingRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"Save integer ratings to agent card.\"\"\"\n # Set audit action for agent rating\n set_audit_action(\n request,\n \"rate\",\n \"agent\",\n resource_id=path,\n description=f\"Rate agent with {rating_request.rating}\",\n )\n\n path = _normalize_path(path)\n\n agent_card = await agent_service.get_agent_info(path)\n if not agent_card:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n accessible = _filter_agents_by_access([agent_card], user_context)\n if not accessible:\n logger.warning(\n f\"User {user_context['username']} attempted to rate agent {path} without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this agent\",\n )\n\n try:\n avg_rating = await agent_service.update_rating(\n path, user_context[\"username\"], rating_request.rating\n )\n except ValueError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=str(e),\n )\n except Exception as e:\n logger.error(f\"Unexpected error updating rating: {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to save rating\",\n )\n\n return {\n \"message\": \"Rating added successfully\",\n \"average_rating\": avg_rating,\n }\n\n\n@router.get(\"/agents/{path:path}/rating\")\nasync def get_agent_rating(\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"Get agent rating information.\"\"\"\n path = _normalize_path(path)\n\n agent_card = await agent_service.get_agent_info(path)\n if not agent_card:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n accessible = _filter_agents_by_access([agent_card], user_context)\n if not accessible:\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this agent\",\n )\n\n return {\n \"num_stars\": agent_card.num_stars,\n \"rating_details\": agent_card.rating_details,\n }\n\n\n@router.post(\"/agents/{path:path}/toggle\")\nasync def toggle_agent(\n request: Request,\n path: str,\n enabled: bool,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n _csrf: Annotated[None, Depends(verify_csrf_token_flexible)] = None,\n):\n \"\"\"\n Enable or disable an agent.\n\n Requires toggle_service permission for the agent.\n\n Args:\n path: Agent path\n enabled: New enabled state\n user_context: Authenticated user context\n\n Returns:\n Updated agent status\n\n Raises:\n HTTPException: 404 if not found, 403 if unauthorized\n \"\"\"\n # Set audit action for agent toggle\n set_audit_action(\n request, \"toggle\", \"agent\", resource_id=path, description=f\"Toggle agent to {enabled}\"\n )\n\n path = _normalize_path(path)\n\n agent_card = await agent_service.get_agent_info(path)\n if not agent_card:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n _check_agent_permission(\"toggle_service\", agent_card.name, user_context)\n\n success = await agent_service.toggle_agent(path, enabled)\n\n if not success:\n return JSONResponse(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n content={\"detail\": \"Failed to toggle agent state\"},\n )\n\n from ..search.service import faiss_service\n\n await faiss_service.add_or_update_entity(\n path,\n agent_card.model_dump(),\n \"a2a_agent\",\n enabled,\n )\n\n logger.info(\n f\"Agent '{agent_card.name}' ({path}) toggled to {enabled} by user \"\n f\"'{user_context['username']}'\"\n )\n\n return {\n \"message\": f\"Agent {'enabled' if enabled else 'disabled'} successfully\",\n \"path\": path,\n \"is_enabled\": enabled,\n }\n\n\n@router.get(\"/agents/{path:path}/security-scan\")\nasync def get_agent_security_scan(\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Get security scan results for an A2A agent.\n\n Returns the latest security scan results for the specified agent,\n including threat analysis, severity levels, and detailed findings\n from YARA, specification validation, and heuristic analyzers.\n\n **Authentication:** JWT Bearer token or session cookie\n **Authorization:** Requires admin privileges or access to the agent\n\n **Path Parameters:**\n - `path` (required): Agent path (e.g., /code-reviewer)\n\n **Response:**\n Returns security scan results with analysis_results and findings.\n\n **Example:**\n ```bash\n curl -X GET http://localhost/api/agents/code-reviewer/security-scan \\\\\n --cookie-jar .cookies --cookie .cookies\n ```\n \"\"\"\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Check if agent exists\n agent_info = await agent_service.get_agent_info(path)\n if not agent_info:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n # Check user permissions\n if not user_context[\"is_admin\"]:\n # Allow all authenticated users to view agent scan results\n pass\n\n # Get scan results\n from ..services.agent_scanner import agent_scanner_service\n\n scan_result = await agent_scanner_service.get_scan_result(path)\n if not scan_result:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"No security scan results found for agent '{path}'. \"\n \"The agent may not have been scanned yet.\",\n )\n\n return scan_result\n\n\n@router.post(\"/agents/{path:path}/rescan\")\nasync def rescan_agent(\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Trigger a manual security scan for an A2A agent.\n\n Initiates a new security scan for the specified agent and returns\n the results. This endpoint is useful for re-scanning agents after\n updates or for on-demand security assessments.\n\n **Authentication:** JWT Bearer token or session cookie\n **Authorization:** Requires admin privileges\n\n **Path Parameters:**\n - `path` (required): Agent path (e.g., /code-reviewer)\n\n **Response:**\n Returns the newly generated security scan results.\n\n **Example:**\n ```bash\n curl -X POST http://localhost/api/agents/code-reviewer/rescan \\\\\n --cookie-jar .cookies --cookie .cookies\n ```\n \"\"\"\n # Only admins can trigger manual scans\n if not user_context[\"is_admin\"]:\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Only administrators can trigger security scans\",\n )\n\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Check if agent exists\n agent_info = await agent_service.get_agent_info(path)\n if not agent_info:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n # Get agent card from agent info\n agent_card_dict = agent_info.model_dump()\n\n logger.info(\n f\"Manual security scan requested by user '{user_context.get('username')}' \"\n f\"for agent '{path}'\"\n )\n\n try:\n # Trigger security scan\n from ..services.agent_scanner import agent_scanner_service\n\n scan_result = await agent_scanner_service.scan_agent(\n agent_card=agent_card_dict,\n agent_path=path,\n analyzers=None, # Use default analyzers from config\n api_key=None, # Use default API key from config\n timeout=None, # Use default timeout from config\n )\n\n # Return the full scan result including raw_output for detailed findings\n return scan_result.model_dump(mode=\"json\")\n\n except Exception as e:\n logger.exception(f\"Manual security scan failed for agent '{path}'\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Security scan failed\",\n )\n\n\n@router.get(\"/agents/{path:path}\")\nasync def get_agent(\n request: Request,\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Get a single agent by path.\n\n Public agents are visible without special permissions.\n Private and group-restricted agents require authorization.\n\n Args:\n request: HTTP request object\n path: Agent path\n user_context: Authenticated user context\n\n Returns:\n Complete agent card\n\n Raises:\n HTTPException: 404 if not found, 403 if not authorized\n \"\"\"\n path = _normalize_path(path)\n\n # Set audit action for agent read\n set_audit_action(request, \"read\", \"agent\", resource_id=path, description=f\"Read agent {path}\")\n\n agent_card = await agent_service.get_agent_info(path)\n if not agent_card:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n accessible = _filter_agents_by_access([agent_card], user_context)\n\n if not accessible:\n logger.warning(\n f\"User {user_context['username']} attempted to access agent {path} without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this agent\",\n )\n\n return agent_card.model_dump()\n\n\n@router.put(\"/agents/{path:path}\")\nasync def update_agent(\n http_request: Request,\n path: str,\n request: AgentRegistrationRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Update an existing agent card.\n\n Requires modify_service permission for the agent.\n User must be agent owner or admin.\n\n Args:\n path: Agent path\n request: Updated agent data\n user_context: Authenticated user context\n\n Returns:\n Updated agent card\n\n Raises:\n HTTPException: 404 if not found, 403 if unauthorized\n \"\"\"\n # Set audit action for agent update\n set_audit_action(\n http_request,\n \"update\",\n \"agent\",\n resource_id=path,\n description=f\"Update agent {request.name}\",\n )\n\n path = _normalize_path(path)\n\n existing_agent = await agent_service.get_agent_info(path)\n if not existing_agent:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n _check_agent_permission(\"modify_service\", existing_agent.name, user_context)\n\n if not user_context[\"is_admin\"] and existing_agent.registered_by != user_context[\"username\"]:\n logger.warning(\n f\"User {user_context['username']} attempted to update agent {path} \"\n f\"owned by {existing_agent.registered_by}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You can only update agents you registered\",\n )\n\n tag_list = [tag.strip() for tag in request.tags.split(\",\") if tag.strip()]\n\n try:\n # Build optional kwargs for fields that have defaults on AgentCard\n update_optional_kwargs: dict[str, Any] = {}\n if request.default_input_modes:\n update_optional_kwargs[\"default_input_modes\"] = request.default_input_modes\n if request.default_output_modes:\n update_optional_kwargs[\"default_output_modes\"] = request.default_output_modes\n\n updated_agent = AgentCard(\n protocol_version=request.protocol_version,\n name=request.name,\n description=request.description,\n url=request.url,\n path=path,\n version=request.version,\n provider=request.provider,\n security_schemes=request.security_schemes or {},\n skills=request.skills or [],\n tags=tag_list,\n license=request.license,\n visibility=request.visibility,\n allowed_groups=request.allowed_groups,\n trust_level=request.trust_level,\n supported_protocol=request.supported_protocol,\n registered_by=existing_agent.registered_by,\n registered_at=existing_agent.registered_at,\n is_enabled=existing_agent.is_enabled,\n num_stars=existing_agent.num_stars,\n metadata=request.metadata if request.metadata else existing_agent.metadata,\n capabilities=request.capabilities\n if request.capabilities\n else existing_agent.capabilities,\n ans_metadata=existing_agent.ans_metadata,\n health_status=existing_agent.health_status,\n last_health_check=existing_agent.last_health_check,\n rating_details=existing_agent.rating_details,\n sync_metadata=existing_agent.sync_metadata,\n status=request.status if request.status else existing_agent.status,\n **update_optional_kwargs,\n )\n\n from ..utils.agent_validator import agent_validator\n\n validation_result = await agent_validator.validate_agent_card(\n updated_agent,\n verify_endpoint=False,\n )\n\n if not validation_result.is_valid:\n raise HTTPException(\n status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n detail={\n \"message\": \"Agent card validation failed\",\n \"errors\": validation_result.errors,\n },\n )\n\n except ValueError as e:\n raise HTTPException(\n status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n detail=f\"Invalid agent card: {str(e)}\",\n )\n\n # Registration gate check for update (admission control, issue #809)\n gate_result = await check_registration_gate(\n asset_type=\"agent\",\n operation=\"update\",\n source_api=f\"/api/agents/{path}\",\n registration_payload=request.model_dump(mode=\"json\"),\n raw_headers=http_request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied agent update '{request.name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n success = await agent_service.update_agent(path, updated_agent)\n\n if not success:\n return JSONResponse(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n content={\"detail\": \"Failed to save updated agent data\"},\n )\n\n from ..search.service import faiss_service\n\n is_enabled = await agent_service.is_agent_enabled(path)\n await faiss_service.add_or_update_entity(\n path,\n updated_agent.model_dump(),\n \"a2a_agent\",\n is_enabled,\n )\n\n logger.info(\n f\"Agent '{updated_agent.name}' ({path}) updated by user '{user_context['username']}'\"\n )\n\n return updated_agent.model_dump()\n\n\n@router.delete(\"/agents/{path:path}\")\nasync def delete_agent(\n request: Request,\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Delete an agent from the registry.\n\n Requires admin permission, delete_agent UI permission, or agent ownership.\n\n Args:\n path: Agent path\n user_context: Authenticated user context\n\n Returns:\n 204 No Content\n\n Raises:\n HTTPException: 404 if not found, 403 if unauthorized\n \"\"\"\n # Set audit action for agent deletion\n set_audit_action(\n request, \"delete\", \"agent\", resource_id=path, description=f\"Delete agent at {path}\"\n )\n\n path = _normalize_path(path)\n\n existing_agent = await agent_service.get_agent_info(path)\n if not existing_agent:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent not found at path '{path}'\",\n )\n\n # Block deletion of federated (read-only) agents from peer registries\n sync_metadata = existing_agent.sync_metadata or {}\n if sync_metadata.get(\"is_federated\") or sync_metadata.get(\"is_read_only\"):\n source_peer = sync_metadata.get(\"source_peer_id\", \"unknown peer registry\")\n logger.warning(\n f\"User {user_context['username']} attempted to delete federated agent {path} \"\n f\"from {source_peer}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Agent '{path}' is synced from {source_peer} and cannot be deleted locally. \"\n f\"Delete this agent from its source registry, or remove the peer federation.\",\n )\n\n # Check delete permission: admin, delete_agent permission, or owner\n if (\n not _has_delete_agent_permission(user_context, path)\n and existing_agent.registered_by != user_context[\"username\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to delete agent {path} without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Only admins, agent owners, or users with delete_agent permission can delete agents\",\n )\n\n success = await agent_service.remove_agent(path)\n\n if not success:\n return JSONResponse(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n content={\"detail\": \"Failed to delete agent\"},\n )\n\n from ..search.service import faiss_service\n\n await faiss_service.remove_entity(path)\n\n logger.info(f\"Agent at path '{path}' deleted by user '{user_context['username']}'\")\n\n asyncio.create_task(\n send_registration_webhook(\n event_type=\"deletion\",\n registration_type=\"agent\",\n card_data=existing_agent.model_dump(mode=\"json\"),\n performed_by=user_context.get(\"username\"),\n )\n )\n\n return JSONResponse(\n status_code=status.HTTP_204_NO_CONTENT,\n content=None,\n )\n\n\n@router.post(\"/agents/discover\")\nasync def discover_agents_by_skills(\n skills: list[str],\n tags: list[str] | None = None,\n max_results: int = Query(10, ge=1, le=100),\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Discover agents by required skills.\n\n Returns agents that have the specified skills, ranked by relevance.\n\n Args:\n skills: Required skill names or IDs\n tags: Optional tag filters\n max_results: Maximum number of results\n user_context: Authenticated user context\n\n Returns:\n List of matching agents with relevance scores\n\n Raises:\n HTTPException: 400 if no skills provided\n \"\"\"\n if not skills:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"At least one skill must be specified\",\n )\n\n logger.info(f\"User {user_context['username']} discovering agents with skills: {skills}\")\n\n all_agents = await agent_service.get_all_agents()\n accessible_agents = _filter_agents_by_access(all_agents, user_context)\n\n matched_agents = []\n required_skills = set(s.lower() for s in skills)\n required_tags = set(t.lower() for t in tags) if tags else set()\n\n for agent in accessible_agents:\n if not await agent_service.is_agent_enabled(agent.path):\n continue\n\n agent_skills = set(skill.id.lower() for skill in agent.skills) | set(\n skill.name.lower() for skill in agent.skills\n )\n\n skill_matches = required_skills & agent_skills\n if not skill_matches:\n continue\n\n agent_tags = set(t.lower() for t in agent.tags)\n tag_matches = required_tags & agent_tags if required_tags else set()\n\n skill_match_score = len(skill_matches) / len(required_skills)\n tag_match_score = len(tag_matches) / len(required_tags) if required_tags else 0.0\n\n trust_boost = {\n \"unverified\": 0.0,\n \"community\": 0.2,\n \"verified\": 0.5,\n \"trusted\": 1.0,\n }.get(agent.trust_level, 0.0)\n\n relevance_score = 0.6 * skill_match_score + 0.2 * tag_match_score + 0.2 * trust_boost\n\n # Extract streaming capability -- check capabilities dict first, fall back to\n # top-level field for agents registered before the capabilities dict change\n streaming = (\n agent.capabilities.get(\"streaming\", False)\n if agent.capabilities\n else getattr(agent, \"streaming\", False)\n )\n\n # Extract provider organization name (provider is AgentProvider object)\n provider_name = agent.provider.organization if agent.provider else None\n\n agent_info = AgentInfo(\n name=agent.name,\n description=agent.description,\n path=agent.path,\n url=str(agent.url),\n tags=agent.tags,\n skills=[s.name for s in agent.skills],\n num_skills=len(agent.skills),\n num_stars=agent.num_stars,\n is_enabled=True,\n provider=provider_name,\n streaming=streaming,\n trust_level=agent.trust_level,\n visibility=getattr(agent, \"visibility\", \"public\"),\n supported_protocol=getattr(agent, \"supported_protocol\", None),\n metadata=agent.metadata if agent.metadata else {},\n )\n\n matched_agents.append(\n {\n **agent_info.model_dump(),\n \"relevance_score\": round(relevance_score, 2),\n \"matched_skills\": list(skill_matches),\n }\n )\n\n matched_agents.sort(key=lambda x: x[\"relevance_score\"], reverse=True)\n matched_agents = matched_agents[:max_results]\n\n logger.info(f\"Found {len(matched_agents)} agents matching skills: {skills}\")\n\n return {\n \"agents\": matched_agents,\n \"query\": {\n \"skills\": skills,\n \"tags\": tags,\n },\n }\n\n\n@router.post(\"/agents/discover/semantic\")\nasync def discover_agents_semantic(\n query: str,\n max_results: int = Query(10, ge=1, le=100),\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n search_repo: SearchRepositoryBase = Depends(get_search_repo),\n):\n \"\"\"\n Discover agents using natural language semantic search.\n\n Uses search repository (FAISS or DocumentDB) to find agents matching the query intent.\n\n Args:\n query: Natural language query describing needed capabilities\n max_results: Maximum number of results\n user_context: Authenticated user context\n search_repo: Search repository dependency\n\n Returns:\n List of matching agents with relevance scores\n\n Raises:\n HTTPException: 400 if query is empty\n \"\"\"\n if not query or not query.strip():\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Query cannot be empty\",\n )\n\n logger.info(f\"User {user_context['username']} semantic search for agents: {query}\")\n\n try:\n search_results = await search_repo.search(\n query=query,\n entity_types=[\"a2a_agent\"],\n max_results=max_results,\n )\n\n # Extract agents from search results\n results = search_results.get(\"agents\", [])\n\n all_agents = await agent_service.get_all_agents()\n agent_map = {agent.path: agent for agent in all_agents}\n\n accessible_results = []\n for result in results:\n agent_card = agent_map.get(result.get(\"path\"))\n if not agent_card:\n continue\n\n if not _filter_agents_by_access([agent_card], user_context):\n continue\n\n # Return full agent card with relevance score\n agent_data = agent_card.model_dump()\n agent_data[\"relevance_score\"] = result.get(\"relevance_score\", 0.0)\n\n accessible_results.append(agent_data)\n\n logger.info(f\"Semantic search returned {len(accessible_results)} agents for query: {query}\")\n\n # Increment semantic search counter (fail-silent)\n from registry.repositories.stats_repository import increment_search_counter\n\n await increment_search_counter()\n\n return {\n \"agents\": accessible_results,\n \"query\": query,\n }\n\n except Exception as e:\n logger.error(f\"Error in semantic agent search: {e}\", exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Semantic search failed\",\n )\n" }, { "path": "registry/api/ans_routes.py", "content": "# registry/api/ans_routes.py\n\nimport logging\nimport time\nfrom collections import defaultdict\nfrom typing import (\n Annotated,\n Any,\n)\n\nimport httpx\nfrom fastapi import (\n APIRouter,\n Depends,\n HTTPException,\n Request,\n status,\n)\n\nfrom registry.audit import set_audit_action\nfrom registry.auth.csrf import verify_csrf_token_flexible\nfrom registry.auth.dependencies import nginx_proxied_auth\nfrom registry.core.config import settings\nfrom registry.schemas.ans_models import LinkANSRequest\nfrom registry.services.ans_service import (\n get_ans_metrics,\n get_sync_history,\n link_ans_to_agent,\n link_ans_to_server,\n sync_all_ans_status,\n unlink_ans_from_agent,\n unlink_ans_from_server,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\nRATE_LIMIT_MAX_REQUESTS: int = 10\nRATE_LIMIT_WINDOW_SECONDS: int = 3600\n_rate_limit_store: dict[str, list[float]] = defaultdict(list)\n\n\ndef _check_rate_limit(\n username: str,\n) -> None:\n \"\"\"Check per-user rate limit for ANS link operations.\n\n Args:\n username: Authenticated user's username\n\n Raises:\n HTTPException 429 if rate limit exceeded\n \"\"\"\n now = time.time()\n window_start = now - RATE_LIMIT_WINDOW_SECONDS\n\n _rate_limit_store[username] = [t for t in _rate_limit_store[username] if t > window_start]\n\n if len(_rate_limit_store[username]) >= RATE_LIMIT_MAX_REQUESTS:\n raise HTTPException(\n status_code=status.HTTP_429_TOO_MANY_REQUESTS,\n detail=f\"Rate limit exceeded: max {RATE_LIMIT_MAX_REQUESTS} ANS link operations per hour\",\n )\n\n _rate_limit_store[username].append(now)\n\n\ndef _check_ans_enabled() -> None:\n \"\"\"Raise 404 if ANS integration is disabled.\"\"\"\n if not settings.ans_integration_enabled:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=\"ANS integration is not enabled\",\n )\n\n\ndef _get_username(\n user_context: dict | None,\n) -> str:\n \"\"\"Extract username from user context.\n\n Args:\n user_context: Auth context dict\n\n Returns:\n Username string\n \"\"\"\n if not user_context:\n return \"unknown\"\n return user_context.get(\"username\", user_context.get(\"sub\", \"unknown\"))\n\n\ndef _check_admin(\n user_context: dict | None,\n) -> None:\n \"\"\"Verify user has admin role/scope.\n\n Args:\n user_context: Auth context dict\n\n Raises:\n HTTPException 403 if not admin\n \"\"\"\n if not user_context:\n raise HTTPException(status_code=403, detail=\"Admin access required\")\n\n scopes = user_context.get(\"scopes\", [])\n groups = user_context.get(\"groups\", [])\n is_admin = (\n \"admin\" in groups\n or \"ans-admin/manage\" in scopes\n or any(\"unrestricted\" in s for s in scopes)\n )\n if not is_admin:\n raise HTTPException(status_code=403, detail=\"Admin access required\")\n\n\ndef _normalize_path(path: str) -> str:\n \"\"\"Normalize entity path to ensure leading slash.\"\"\"\n if not path.startswith(\"/\"):\n path = \"/\" + path\n if path.endswith(\"/\") and len(path) > 1:\n path = path.rstrip(\"/\")\n return path\n\n\n# --- Agent ANS endpoints ---\n\n\n@router.post(\"/agents/{path:path}/ans/link\")\nasync def link_ans_to_agent_endpoint(\n request: Request,\n path: str,\n body: LinkANSRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Link an ANS Agent ID to an agent.\"\"\"\n _check_ans_enabled()\n path = _normalize_path(path)\n await verify_csrf_token_flexible(request)\n username = _get_username(user_context)\n _check_rate_limit(username)\n set_audit_action(\n request,\n \"create\",\n \"ans_link\",\n resource_id=path,\n description=f\"Link ANS ID to agent {path}\",\n )\n result = await link_ans_to_agent(path, body.ans_agent_id, username=username)\n if not result[\"success\"]:\n status_code = status.HTTP_400_BAD_REQUEST\n if \"Not authorized\" in result.get(\"message\", \"\"):\n status_code = status.HTTP_403_FORBIDDEN\n raise HTTPException(status_code=status_code, detail=result[\"message\"])\n return result\n\n\n@router.get(\"/agents/{path:path}/ans/status\")\nasync def get_agent_ans_status(\n request: Request,\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Get ANS verification status for an agent.\"\"\"\n _check_ans_enabled()\n path = _normalize_path(path)\n from registry.repositories.factory import get_agent_repository\n\n repo = get_agent_repository()\n agent = await repo.get(path)\n if not agent:\n raise HTTPException(status_code=404, detail=\"Agent not found\")\n\n ans_metadata = agent.ans_metadata\n if not ans_metadata:\n raise HTTPException(status_code=404, detail=\"No ANS link found\")\n\n return ans_metadata\n\n\n@router.delete(\"/agents/{path:path}/ans/link\")\nasync def unlink_ans_from_agent_endpoint(\n request: Request,\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Remove ANS link from an agent.\"\"\"\n _check_ans_enabled()\n path = _normalize_path(path)\n await verify_csrf_token_flexible(request)\n username = _get_username(user_context)\n set_audit_action(\n request,\n \"delete\",\n \"ans_link\",\n resource_id=path,\n description=f\"Unlink ANS ID from agent {path}\",\n )\n result = await unlink_ans_from_agent(path, username=username)\n if not result[\"success\"]:\n status_code = 404\n if \"Not authorized\" in result.get(\"message\", \"\"):\n status_code = 403\n raise HTTPException(status_code=status_code, detail=result[\"message\"])\n return result\n\n\n# --- Server ANS endpoints ---\n\n\n@router.post(\"/servers/{path:path}/ans/link\")\nasync def link_ans_to_server_endpoint(\n request: Request,\n path: str,\n body: LinkANSRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Link an ANS Agent ID to an MCP server.\"\"\"\n _check_ans_enabled()\n path = _normalize_path(path)\n await verify_csrf_token_flexible(request)\n username = _get_username(user_context)\n _check_rate_limit(username)\n set_audit_action(\n request,\n \"create\",\n \"ans_link\",\n resource_id=path,\n description=f\"Link ANS ID to server {path}\",\n )\n result = await link_ans_to_server(path, body.ans_agent_id, username=username)\n if not result[\"success\"]:\n status_code = status.HTTP_400_BAD_REQUEST\n if \"Not authorized\" in result.get(\"message\", \"\"):\n status_code = status.HTTP_403_FORBIDDEN\n raise HTTPException(status_code=status_code, detail=result[\"message\"])\n return result\n\n\n@router.get(\"/servers/{path:path}/ans/status\")\nasync def get_server_ans_status(\n request: Request,\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Get ANS verification status for a server.\"\"\"\n _check_ans_enabled()\n path = _normalize_path(path)\n from registry.repositories.factory import get_server_repository\n\n repo = get_server_repository()\n server = await repo.get(path)\n if not server:\n raise HTTPException(status_code=404, detail=\"Server not found\")\n\n ans_metadata = server.get(\"ans_metadata\")\n if not ans_metadata:\n raise HTTPException(status_code=404, detail=\"No ANS link found\")\n\n return ans_metadata\n\n\n@router.delete(\"/servers/{path:path}/ans/link\")\nasync def unlink_ans_from_server_endpoint(\n request: Request,\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Remove ANS link from a server.\"\"\"\n _check_ans_enabled()\n path = _normalize_path(path)\n await verify_csrf_token_flexible(request)\n username = _get_username(user_context)\n set_audit_action(\n request,\n \"delete\",\n \"ans_link\",\n resource_id=path,\n description=f\"Unlink ANS ID from server {path}\",\n )\n result = await unlink_ans_from_server(path, username=username)\n if not result[\"success\"]:\n status_code = 404\n if \"Not authorized\" in result.get(\"message\", \"\"):\n status_code = 403\n raise HTTPException(status_code=status_code, detail=result[\"message\"])\n return result\n\n\n# --- Admin ANS endpoints ---\n\n\n@router.post(\"/admin/ans/sync\")\nasync def trigger_ans_sync(\n request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Manually trigger ANS status sync (admin only).\"\"\"\n _check_ans_enabled()\n _check_admin(user_context)\n set_audit_action(\n request,\n \"execute\",\n \"ans_sync\",\n description=\"Manual ANS sync triggered\",\n )\n stats = await sync_all_ans_status()\n return stats.model_dump()\n\n\n@router.get(\"/admin/ans/metrics\")\nasync def get_ans_metrics_endpoint(\n request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Get ANS integration metrics (admin only).\"\"\"\n _check_ans_enabled()\n _check_admin(user_context)\n metrics = await get_ans_metrics()\n result = metrics.model_dump(mode=\"json\")\n result[\"sync_history\"] = get_sync_history()\n return result\n\n\n@router.get(\"/admin/ans/health\")\nasync def get_ans_health(\n request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> dict[str, Any]:\n \"\"\"Check ANS API reachability (admin only).\"\"\"\n _check_ans_enabled()\n _check_admin(user_context)\n\n from registry.services.ans_client import _check_circuit_breaker\n\n circuit_ok = _check_circuit_breaker()\n if not circuit_ok:\n return {\n \"status\": \"degraded\",\n \"message\": \"ANS API circuit breaker is open\",\n \"api_reachable\": False,\n }\n\n try:\n headers = {\n \"Authorization\": f\"sso-key {settings.ans_api_key}:{settings.ans_api_secret}\",\n \"Accept\": \"application/json\",\n }\n async with httpx.AsyncClient(timeout=10) as client:\n resp = await client.get(\n f\"{settings.ans_api_endpoint}/v1/agents?limit=1\",\n headers=headers,\n )\n return {\n \"status\": \"healthy\" if resp.status_code == 200 else \"degraded\",\n \"api_reachable\": resp.status_code == 200,\n \"api_status_code\": resp.status_code,\n }\n except Exception as e:\n return {\n \"status\": \"unhealthy\",\n \"api_reachable\": False,\n \"error\": str(e),\n }\n" }, { "path": "registry/api/auth0_m2m_routes.py", "content": "\"\"\"API routes for Auth0 M2M client management.\n\nThis module provides endpoints for syncing Auth0 M2M applications to MongoDB\nand managing their group mappings.\n\"\"\"\n\nimport logging\nfrom typing import Annotated\n\nfrom fastapi import APIRouter, Depends, HTTPException\nfrom pydantic import BaseModel\n\nfrom registry.auth.dependencies import nginx_proxied_auth\nfrom registry.repositories.documentdb.client import get_documentdb_client\nfrom registry.schemas.idp_m2m_client import (\n IdPM2MClient,\n IdPM2MClientUpdate,\n)\nfrom registry.services.auth0_m2m_sync import get_auth0_m2m_sync\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n\nclass Auth0SyncRequest(BaseModel):\n \"\"\"Request payload for Auth0 M2M sync.\"\"\"\n\n force_full_sync: bool = False\n\n\nclass Auth0SyncResponse(BaseModel):\n \"\"\"Response from Auth0 M2M sync operation.\"\"\"\n\n synced_count: int\n added_count: int\n updated_count: int\n removed_count: int\n errors: list[str]\n\n\ndef _require_admin(user_context: dict | None) -> None:\n \"\"\"Check if user is admin.\n\n Args:\n user_context: User context from authentication\n\n Raises:\n HTTPException: If user is not admin\n \"\"\"\n if not user_context:\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n\n groups = user_context.get(\"groups\", [])\n if \"registry-admins\" not in groups:\n raise HTTPException(\n status_code=403,\n detail=\"Admin access required\",\n )\n\n\n@router.post(\"/iam/auth0/m2m/sync\", response_model=Auth0SyncResponse)\nasync def sync_auth0_m2m_clients(\n request: Auth0SyncRequest = Auth0SyncRequest(),\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Sync M2M clients from Auth0 to MongoDB (admin only).\n\n This endpoint queries the Auth0 Management API to fetch all M2M applications\n and stores/updates their information in MongoDB for authorization decisions.\n\n Args:\n request: Sync request parameters\n user_context: Authenticated user context\n\n\n Returns:\n Sync statistics including number of clients added/updated\n\n Raises:\n HTTPException: If user is not admin or sync fails\n \"\"\"\n _require_admin(user_context)\n\n db = await get_documentdb_client()\n auth0_sync = get_auth0_m2m_sync(db)\n if not auth0_sync:\n raise HTTPException(\n status_code=503,\n detail=\"Auth0 sync not configured (missing AUTH0_DOMAIN, AUTH0_M2M_CLIENT_ID, or AUTH0_M2M_CLIENT_SECRET)\",\n )\n\n try:\n result = await auth0_sync.sync_from_auth0(force_full_sync=request.force_full_sync)\n return Auth0SyncResponse(**result)\n\n except Exception as e:\n logger.exception(f\"Failed to sync Auth0 M2M clients: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Sync failed: {str(e)}\",\n )\n\n\n@router.get(\"/iam/auth0/m2m/clients\", response_model=list[IdPM2MClient])\nasync def list_auth0_m2m_clients(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"List all Auth0 M2M clients from MongoDB.\n\n Returns all M2M service accounts synced from Auth0, including their\n client IDs and group mappings.\n\n Args:\n user_context: Authenticated user context\n\n\n Returns:\n List of Auth0 M2M clients\n\n Raises:\n HTTPException: If user is not authenticated\n \"\"\"\n if not user_context:\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n\n db = await get_documentdb_client()\n auth0_sync = get_auth0_m2m_sync(db)\n if not auth0_sync:\n # Return empty list if Auth0 not configured\n return []\n\n try:\n clients = await auth0_sync.get_all_clients()\n return clients\n\n except Exception as e:\n logger.exception(f\"Failed to list Auth0 M2M clients: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to retrieve clients: {str(e)}\",\n )\n\n\n@router.get(\"/iam/auth0/m2m/clients/{client_id}/groups\", response_model=list[str])\nasync def get_client_groups(\n client_id: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Get groups for a specific Auth0 M2M client.\n\n Args:\n client_id: Auth0 client ID\n user_context: Authenticated user context\n\n\n Returns:\n List of group names\n\n Raises:\n HTTPException: If user is not authenticated or client not found\n \"\"\"\n if not user_context:\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n\n db = await get_documentdb_client()\n auth0_sync = get_auth0_m2m_sync(db)\n if not auth0_sync:\n return []\n\n try:\n groups = await auth0_sync.get_client_groups(client_id)\n return groups\n\n except Exception as e:\n logger.exception(f\"Failed to get groups for client {client_id}: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to retrieve groups: {str(e)}\",\n )\n\n\n@router.patch(\"/iam/auth0/m2m/clients/{client_id}/groups\")\nasync def update_client_groups(\n client_id: str,\n payload: IdPM2MClientUpdate,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Update groups for an Auth0 M2M client (admin only).\n\n This allows administrators to change which groups a service account belongs to.\n\n Args:\n client_id: Auth0 client ID\n payload: Update payload with new groups\n user_context: Authenticated user context\n\n\n Returns:\n Success message\n\n Raises:\n HTTPException: If user is not admin or update fails\n \"\"\"\n _require_admin(user_context)\n\n db = await get_documentdb_client()\n auth0_sync = get_auth0_m2m_sync(db)\n if not auth0_sync:\n raise HTTPException(\n status_code=503,\n detail=\"Auth0 sync not configured\",\n )\n\n try:\n success = await auth0_sync.update_client_groups(client_id, payload.groups)\n\n if not success:\n raise HTTPException(\n status_code=404,\n detail=f\"Client {client_id} not found\",\n )\n\n return {\n \"client_id\": client_id,\n \"groups\": payload.groups,\n \"message\": \"Groups updated successfully\",\n }\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(f\"Failed to update groups for client {client_id}: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to update groups: {str(e)}\",\n )\n" }, { "path": "registry/api/config_routes.py", "content": "\"\"\"Configuration API endpoint for deployment mode awareness.\"\"\"\n\nimport json\nimport logging\nimport time\nfrom datetime import UTC\nfrom enum import Enum\nfrom typing import Annotated, Any\n\nfrom fastapi import APIRouter, Depends, HTTPException, Query, Request\nfrom fastapi.responses import PlainTextResponse\n\nfrom ..auth.dependencies import enhanced_auth\nfrom ..core.config import DeploymentMode, RegistryMode, settings\nfrom ..core.metrics import CONFIG_EXPORT_REQUESTS, CONFIG_VIEW_REQUESTS\nfrom ..schemas.registry_card import LifecycleStatus\n\nlogger = logging.getLogger(__name__)\nrouter = APIRouter()\n\n\n# ---------------------------------------------------------------------------\n# Rate limiting state (in-memory sliding window, per-user)\n# ---------------------------------------------------------------------------\n_rate_limit_cache: dict[str, list[float]] = {}\nRATE_LIMIT_REQUESTS = 10\nRATE_LIMIT_WINDOW_SECONDS = 60\n\n\n# ---------------------------------------------------------------------------\n# Configuration group definitions — 16 groups, ordered 1-16\n# Groups may contain optional \"subgroups\" for nested display (e.g. Identity Providers)\n# Each field tuple: (settings_attr_name, display_label, is_sensitive)\n# ---------------------------------------------------------------------------\nCONFIG_GROUPS: dict[str, dict[str, Any]] = {\n \"deployment\": {\n \"title\": \"Deployment Mode\",\n \"order\": 1,\n \"fields\": [\n (\"deployment_mode\", \"Deployment Mode\", False),\n (\"registry_mode\", \"Registry Mode\", False),\n (\"nginx_updates_enabled\", \"Nginx Updates Enabled\", False),\n (\"show_servers_tab\", \"Show MCP Servers Tab\", False),\n (\"show_virtual_servers_tab\", \"Show Virtual MCP Servers Tab\", False),\n (\"show_skills_tab\", \"Show Skills Tab\", False),\n (\"show_agents_tab\", \"Show Agents Tab\", False),\n ],\n },\n \"storage\": {\n \"title\": \"Storage Backend\",\n \"order\": 2,\n \"fields\": [\n (\"storage_backend\", \"Storage Backend\", False),\n (\"documentdb_host\", \"DocumentDB Host\", False),\n (\"documentdb_port\", \"DocumentDB Port\", False),\n (\"documentdb_database\", \"DocumentDB Database\", False),\n (\"documentdb_namespace\", \"DocumentDB Namespace\", False),\n (\"documentdb_use_tls\", \"Use TLS\", False),\n (\"documentdb_use_iam\", \"Use IAM Auth\", False),\n (\"documentdb_username\", \"Username\", True),\n (\"documentdb_password\", \"Password\", True),\n ],\n },\n \"auth\": {\n \"title\": \"Authentication\",\n \"order\": 3,\n \"fields\": [\n (\"auth_provider\", \"Auth Provider\", False),\n (\"auth_server_url\", \"Auth Server URL\", False),\n (\"auth_server_external_url\", \"Auth Server External URL\", False),\n (\"session_max_age_seconds\", \"Session Max Age\", False),\n (\"session_cookie_secure\", \"Secure Cookie\", False),\n (\"session_cookie_domain\", \"Cookie Domain\", False),\n (\"oauth_store_tokens_in_session\", \"Store OAuth IdP Tokens in Session Cookie\", False),\n (\"registry_static_token_auth_enabled\", \"Static Token Auth Enabled\", False),\n (\"registry_api_token\", \"Registry API Token\", True),\n (\"registry_api_keys\", \"Registry API Keys\", True),\n (\"max_tokens_per_user_per_hour\", \"JWT Token Vending Rate Limit (per user/hour)\", False),\n (\"m2m_direct_registration_enabled\", \"M2M Direct Registration Enabled\", False),\n (\"secret_key\", \"Secret Key\", True),\n ],\n },\n \"identity_providers\": {\n \"title\": \"Identity Providers\",\n \"order\": 4,\n \"fields\": [\n (\"idp_group_filter_prefix\", \"Group Filter Prefixes (comma-separated)\", False),\n ],\n \"subgroups\": [\n {\n \"id\": \"keycloak\",\n \"title\": \"Keycloak\",\n \"fields\": [\n (\"keycloak_enabled\", \"Enabled\", False),\n (\"keycloak_url\", \"Internal URL\", False),\n (\"keycloak_external_url\", \"External URL\", False),\n (\"keycloak_realm\", \"Realm\", False),\n (\"keycloak_client_id\", \"Client ID\", True),\n (\"keycloak_client_secret\", \"Client Secret\", True),\n (\"keycloak_admin\", \"Admin Username\", True),\n (\"keycloak_admin_password\", \"Admin Password\", True),\n (\"keycloak_m2m_client_id\", \"M2M Client ID\", True),\n (\"keycloak_m2m_client_secret\", \"M2M Client Secret\", True),\n ],\n },\n {\n \"id\": \"okta\",\n \"title\": \"Okta\",\n \"fields\": [\n (\"okta_enabled\", \"Enabled\", False),\n (\"okta_domain\", \"Domain\", False),\n (\"okta_client_id\", \"Client ID\", True),\n (\"okta_client_secret\", \"Client Secret\", True),\n (\"okta_m2m_client_id\", \"M2M Client ID\", True),\n (\"okta_m2m_client_secret\", \"M2M Client Secret\", True),\n (\"okta_api_token\", \"API Token\", True),\n (\"okta_auth_server_id\", \"Auth Server ID\", False),\n ],\n },\n {\n \"id\": \"entra\",\n \"title\": \"Microsoft Entra ID\",\n \"fields\": [\n (\"entra_enabled\", \"Enabled\", False),\n (\"entra_tenant_id\", \"Tenant ID\", False),\n (\"entra_client_id\", \"Client ID\", True),\n (\"entra_client_secret\", \"Client Secret\", True),\n (\"entra_group_admin_id\", \"Admin Group ID\", False),\n ],\n },\n ],\n },\n \"embeddings\": {\n \"title\": \"Embeddings / Vector Search\",\n \"order\": 5,\n \"fields\": [\n (\"embeddings_provider\", \"Provider\", False),\n (\"embeddings_model_name\", \"Model Name\", False),\n (\"embeddings_model_dimensions\", \"Dimensions\", False),\n (\"embeddings_aws_region\", \"AWS Region\", False),\n (\"vector_search_ef_search\", \"Vector Search EF\", False),\n (\"embeddings_api_key\", \"API Key\", True),\n (\"embeddings_secret_key\", \"Secret Key\", True),\n ],\n },\n \"health_check\": {\n \"title\": \"Health Checks\",\n \"order\": 6,\n \"fields\": [\n (\"health_check_interval_seconds\", \"Check Interval\", False),\n (\"health_check_timeout_seconds\", \"Check Timeout\", False),\n ],\n },\n \"websocket\": {\n \"title\": \"WebSocket Settings\",\n \"order\": 7,\n \"fields\": [\n (\"max_websocket_connections\", \"Max Connections\", False),\n (\"websocket_send_timeout_seconds\", \"Send Timeout\", False),\n (\"websocket_broadcast_interval_ms\", \"Broadcast Interval\", False),\n (\"websocket_max_batch_size\", \"Max Batch Size\", False),\n (\"websocket_cache_ttl_seconds\", \"Cache TTL\", False),\n ],\n },\n \"security_servers\": {\n \"title\": \"Security Scanning (MCP Servers)\",\n \"order\": 8,\n \"fields\": [\n (\"security_scan_enabled\", \"Scan Enabled\", False),\n (\"security_scan_on_registration\", \"Scan on Registration\", False),\n (\"security_block_unsafe_servers\", \"Block Unsafe\", False),\n (\"security_analyzers\", \"Analyzers\", False),\n (\"security_scan_timeout\", \"Scan Timeout\", False),\n (\"security_add_pending_tag\", \"Add Pending Tag\", False),\n (\"mcp_scanner_llm_api_key\", \"LLM API Key\", True),\n ],\n },\n \"security_agents\": {\n \"title\": \"Security Scanning (Agents)\",\n \"order\": 9,\n \"fields\": [\n (\"agent_security_scan_enabled\", \"Scan Enabled\", False),\n (\"agent_security_scan_on_registration\", \"Scan on Registration\", False),\n (\"agent_security_block_unsafe_agents\", \"Block Unsafe\", False),\n (\"agent_security_analyzers\", \"Analyzers\", False),\n (\"agent_security_scan_timeout\", \"Scan Timeout\", False),\n (\"agent_security_add_pending_tag\", \"Add Pending Tag\", False),\n (\"a2a_scanner_llm_api_key\", \"LLM API Key\", True),\n ],\n },\n \"audit\": {\n \"title\": \"Audit Logging\",\n \"order\": 10,\n \"fields\": [\n (\"audit_log_enabled\", \"Enabled\", False),\n (\"audit_log_dir\", \"Log Directory\", False),\n (\"audit_log_rotation_hours\", \"Rotation Hours\", False),\n (\"audit_log_rotation_max_mb\", \"Max Size (MB)\", False),\n (\"audit_log_local_retention_hours\", \"Local Retention Hours\", False),\n (\"audit_log_mongodb_enabled\", \"MongoDB Enabled\", False),\n (\"audit_log_mongodb_ttl_days\", \"MongoDB TTL Days\", False),\n (\"audit_log_health_checks\", \"Log Health Checks\", False),\n (\"audit_log_static_assets\", \"Log Static Assets\", False),\n ],\n },\n \"federation\": {\n \"title\": \"Federation\",\n \"order\": 11,\n \"fields\": [\n (\"registry_id\", \"Registry ID\", False),\n (\"federation_static_token_auth_enabled\", \"Static Token Auth Enabled\", False),\n (\"federation_static_token\", \"Federation Static Token\", True),\n ],\n },\n \"ans\": {\n \"title\": \"ANS (Agent Name Service)\",\n \"order\": 12,\n \"fields\": [\n (\"ans_integration_enabled\", \"ANS Enabled\", False),\n (\"ans_api_endpoint\", \"API Endpoint\", False),\n (\"ans_api_key\", \"API Key\", True),\n (\"ans_api_secret\", \"API Secret\", True),\n (\"ans_api_timeout_seconds\", \"API Timeout (s)\", False),\n (\"ans_sync_interval_hours\", \"Sync Interval (hours)\", False),\n (\"ans_verification_cache_ttl_seconds\", \"Cache TTL (s)\", False),\n ],\n },\n \"discovery\": {\n \"title\": \"Well-Known Discovery\",\n \"order\": 13,\n \"fields\": [\n (\"enable_wellknown_discovery\", \"Enabled\", False),\n (\"wellknown_cache_ttl\", \"Cache TTL\", False),\n ],\n },\n \"otel\": {\n \"title\": \"OpenTelemetry / OTLP\",\n \"order\": 14,\n \"fields\": [\n (\"otel_otlp_endpoint\", \"OTLP Endpoint\", False),\n (\"otel_otlp_export_interval_ms\", \"Export Interval (ms)\", False),\n (\"otel_exporter_otlp_metrics_temporality_preference\", \"Metrics Temporality\", False),\n ],\n },\n \"telemetry\": {\n \"title\": \"Telemetry\",\n \"order\": 15,\n \"fields\": [\n (\"telemetry_enabled\", \"Telemetry Enabled\", False),\n (\"telemetry_opt_out\", \"Heartbeat Opt-Out\", False),\n (\"telemetry_heartbeat_interval_minutes\", \"Heartbeat Interval (minutes)\", False),\n (\"telemetry_debug\", \"Debug Mode\", False),\n (\"telemetry_endpoint\", \"Collector Endpoint\", False),\n ],\n },\n \"demo_server\": {\n \"title\": \"Demo Server Configuration\",\n \"order\": 16,\n \"fields\": [\n (\"disable_ai_registry_tools_server\", \"Disable AI Registry Tools Server\", False),\n ],\n },\n \"registration_gate\": {\n \"title\": \"Registration Gate (Admission Control)\",\n \"order\": 17,\n \"fields\": [\n (\"registration_gate_enabled\", \"Gate Enabled\", False),\n (\"registration_gate_url\", \"Gate URL\", False),\n (\"registration_gate_auth_type\", \"Auth Type\", False),\n (\"registration_gate_auth_credential\", \"Auth Credential\", True),\n (\"registration_gate_auth_header_name\", \"Auth Header Name\", False),\n (\"registration_gate_timeout_seconds\", \"Timeout (s)\", False),\n (\"registration_gate_max_retries\", \"Max Retries\", False),\n ],\n },\n \"app_log\": {\n \"title\": \"Application Logging\",\n \"order\": 18,\n \"fields\": [\n (\"app_log_centralized_enabled\", \"Centralized Enabled\", False),\n (\"app_log_centralized_ttl_days\", \"Centralized TTL Days\", False),\n (\"app_log_level\", \"Log Level\", False),\n (\"app_log_excluded_loggers\", \"Excluded Loggers\", False),\n ],\n },\n \"github_auth\": {\n \"title\": \"GitHub Private Repo Auth\",\n \"order\": 19,\n \"fields\": [\n (\"github_pat\", \"Personal Access Token\", True),\n (\"github_app_id\", \"GitHub App ID\", False),\n (\"github_app_installation_id\", \"GitHub App Installation ID\", False),\n (\"github_app_private_key\", \"GitHub App Private Key\", True),\n (\"github_extra_hosts\", \"Extra GitHub Hosts\", False),\n (\"github_api_base_url\", \"API Base URL\", False),\n ],\n },\n}\n\n\n# ---------------------------------------------------------------------------\n# Sensitive field patterns for automatic detection (defense-in-depth)\n# ---------------------------------------------------------------------------\nSENSITIVE_PATTERNS = (\n \"_password\",\n \"_secret\",\n \"_api_key\",\n \"_token\",\n \"_key\",\n \"_credential\",\n)\n\n\ndef _is_sensitive_field(field_name: str) -> bool:\n \"\"\"Check if a field should be treated as sensitive based on its name.\"\"\"\n field_lower = field_name.lower()\n return any(pattern in field_lower for pattern in SENSITIVE_PATTERNS)\n\n\ndef _mask_sensitive_value(value: Any) -> str:\n \"\"\"Mask a sensitive value for display.\n\n Returns \"(not set)\" for None/empty, \"****\" for ≤4 chars,\n first 4 chars + up to 8 asterisks for longer values.\n \"\"\"\n if value is None or value == \"\":\n return \"(not set)\"\n str_value = str(value)\n if len(str_value) <= 4:\n return \"****\"\n return str_value[:4] + \"*\" * min(len(str_value) - 4, 8)\n\n\ndef _format_value(\n field_name: str,\n value: Any,\n is_sensitive: bool,\n) -> dict[str, Any]:\n \"\"\"Format a configuration value for the API response.\n\n Returns dict with keys: raw, display, is_masked, unit.\n Handles _seconds/_ms/_hours/_days/_mb suffixes and human-readable time.\n \"\"\"\n if is_sensitive:\n return {\n \"raw\": None,\n \"display\": _mask_sensitive_value(value),\n \"is_masked\": True,\n \"unit\": None,\n }\n\n display = str(value)\n unit = None\n\n if field_name.endswith(\"_seconds\"):\n unit = \"seconds\"\n if isinstance(value, (int, float)) and value >= 3600:\n hours = value / 3600\n display = f\"{value} ({hours:.1f} hours)\"\n elif isinstance(value, (int, float)) and value >= 60:\n minutes = value / 60\n display = f\"{value} ({minutes:.0f} minutes)\"\n elif field_name.endswith(\"_ms\"):\n unit = \"ms\"\n elif field_name.endswith(\"_hours\"):\n unit = \"hours\"\n elif field_name.endswith(\"_days\"):\n unit = \"days\"\n elif field_name.endswith(\"_mb\"):\n unit = \"MB\"\n\n return {\n \"raw\": value,\n \"display\": display,\n \"is_masked\": False,\n \"unit\": unit,\n }\n\n\ndef _get_field_value(field_name: str) -> Any:\n \"\"\"Read a field value from the global settings instance.\n\n Extracts .value from Enum instances and handles the computed\n nginx_updates_enabled property.\n \"\"\"\n value = getattr(settings, field_name, None)\n\n # Extract primitive from Enum\n if hasattr(value, \"value\"):\n value = value.value\n\n return value\n\n\n# ---------------------------------------------------------------------------\n# Rate limiter (in-memory sliding window)\n# ---------------------------------------------------------------------------\n\n\ndef _check_rate_limit(user_id: str) -> bool:\n \"\"\"Return True if the request is within the rate limit, False otherwise.\n\n Uses a per-user sliding window of RATE_LIMIT_WINDOW_SECONDS with a max\n of RATE_LIMIT_REQUESTS.\n \"\"\"\n now = time.time()\n window_start = now - RATE_LIMIT_WINDOW_SECONDS\n\n if user_id not in _rate_limit_cache:\n _rate_limit_cache[user_id] = []\n\n # Prune timestamps outside the window\n _rate_limit_cache[user_id] = [t for t in _rate_limit_cache[user_id] if t > window_start]\n\n if len(_rate_limit_cache[user_id]) >= RATE_LIMIT_REQUESTS:\n return False\n\n _rate_limit_cache[user_id].append(now)\n return True\n\n\n# ---------------------------------------------------------------------------\n# Response cache (60-second TTL)\n# ---------------------------------------------------------------------------\n_config_cache: dict[str, Any] = {}\n_config_cache_time: float = 0\nCONFIG_CACHE_TTL_SECONDS = 60\n\n\ndef _get_cached_config_response() -> dict[str, Any]:\n \"\"\"Return cached config response, rebuilding if TTL has expired.\"\"\"\n global _config_cache, _config_cache_time\n\n now = time.time()\n if _config_cache and (now - _config_cache_time) < CONFIG_CACHE_TTL_SECONDS:\n return _config_cache\n\n _config_cache = _build_config_response()\n _config_cache_time = now\n return _config_cache\n\n\ndef _build_fields_list(\n field_defs: list[tuple[str, str, bool]],\n) -> list[dict[str, Any]]:\n \"\"\"Build a list of formatted field dicts from field definitions.\"\"\"\n fields = []\n for field_name, display_name, is_sensitive in field_defs:\n value = _get_field_value(field_name)\n actual_sensitive = is_sensitive or _is_sensitive_field(field_name)\n formatted = _format_value(field_name, value, actual_sensitive)\n\n fields.append(\n {\n \"key\": field_name,\n \"label\": display_name,\n \"value\": formatted[\"display\"],\n \"raw_value\": formatted[\"raw\"],\n \"is_masked\": formatted[\"is_masked\"],\n \"unit\": formatted[\"unit\"],\n }\n )\n return fields\n\n\ndef _build_config_response() -> dict[str, Any]:\n \"\"\"Build the full configuration response with grouped settings.\"\"\"\n groups = []\n\n for group_id, group_def in sorted(\n CONFIG_GROUPS.items(),\n key=lambda x: x[1][\"order\"],\n ):\n fields = _build_fields_list(group_def[\"fields\"])\n\n group_entry: dict[str, Any] = {\n \"id\": group_id,\n \"title\": group_def[\"title\"],\n \"order\": group_def[\"order\"],\n \"fields\": fields,\n }\n\n if \"subgroups\" in group_def:\n subgroups = []\n for sg in group_def[\"subgroups\"]:\n sg_fields = _build_fields_list(sg[\"fields\"])\n subgroups.append(\n {\n \"id\": sg[\"id\"],\n \"title\": sg[\"title\"],\n \"fields\": sg_fields,\n }\n )\n group_entry[\"subgroups\"] = subgroups\n\n groups.append(group_entry)\n\n return {\n \"groups\": groups,\n \"total_groups\": len(groups),\n \"is_local_dev\": settings.is_local_dev,\n }\n\n\n# ---------------------------------------------------------------------------\n# GET /api/config/full — admin-only full configuration view\n# ---------------------------------------------------------------------------\n\n\n@router.get(\n \"/full\",\n summary=\"Get full registry configuration\",\n description=\"Returns all configuration parameters grouped by category. Admin only.\",\n)\nasync def get_full_config(\n request: Request,\n user_context: Annotated[dict, Depends(enhanced_auth)],\n) -> dict[str, Any]:\n \"\"\"Get full configuration with grouped parameters.\"\"\"\n if not user_context.get(\"is_admin\", False):\n raise HTTPException(\n status_code=403,\n detail=\"Admin access required to view full configuration\",\n )\n\n username = user_context.get(\"username\", \"unknown\")\n\n if not _check_rate_limit(username):\n raise HTTPException(\n status_code=429,\n detail=\"Rate limit exceeded. Try again later.\",\n )\n\n CONFIG_VIEW_REQUESTS.labels(user_type=\"admin\").inc()\n\n # Audit log\n client_ip = request.client.host if request.client else \"unknown\"\n logger.info(\n \"Config view requested by user=%s ip=%s groups=%s\",\n username,\n client_ip,\n list(CONFIG_GROUPS.keys()),\n )\n\n audit_logger = getattr(request.app.state, \"audit_logger\", None)\n if audit_logger:\n try:\n import uuid\n from datetime import datetime\n\n from ..audit.models import (\n Action,\n Identity,\n RegistryApiAccessRecord,\n )\n from ..audit.models import (\n Request as AuditRequest,\n )\n from ..audit.models import (\n Response as AuditResponse,\n )\n\n record = RegistryApiAccessRecord(\n timestamp=datetime.now(UTC),\n request_id=str(uuid.uuid4()),\n identity=Identity(\n username=username,\n auth_method=user_context.get(\"auth_method\", \"unknown\"),\n is_admin=True,\n credential_type=\"session_cookie\",\n ),\n request=AuditRequest(\n method=\"GET\",\n path=\"/api/config/full\",\n client_ip=client_ip,\n ),\n response=AuditResponse(status_code=200, duration_ms=0),\n action=Action(\n operation=\"read\",\n resource_type=\"config\",\n description=\"Viewed full system configuration\",\n ),\n )\n await audit_logger.log_event(record)\n except Exception:\n logger.debug(\"Could not write structured audit event for config_view\", exc_info=True)\n\n return _get_cached_config_response()\n\n\n# ---------------------------------------------------------------------------\n# Existing endpoint (unchanged)\n# ---------------------------------------------------------------------------\n\n\n@router.get(\n \"\",\n summary=\"Get registry configuration\",\n description=\"Returns the current deployment mode, registry mode, and enabled features\",\n)\nasync def get_config() -> dict[str, Any]:\n \"\"\"Get current registry configuration.\"\"\"\n return {\n \"deployment_mode\": settings.deployment_mode.value,\n \"registry_mode\": settings.registry_mode.value,\n \"nginx_updates_enabled\": settings.nginx_updates_enabled,\n \"registration_gate_enabled\": settings.registration_gate_enabled,\n \"asset_lifecycle_statuses\": [s.value for s in LifecycleStatus],\n \"features\": {\n \"mcp_servers\": (\n settings.registry_mode in (RegistryMode.FULL, RegistryMode.MCP_SERVERS_ONLY)\n and settings.show_servers_tab\n ),\n \"agents\": (\n settings.registry_mode in (RegistryMode.FULL, RegistryMode.AGENTS_ONLY)\n and settings.show_agents_tab\n ),\n \"skills\": (\n settings.registry_mode in (RegistryMode.FULL, RegistryMode.SKILLS_ONLY)\n and settings.show_skills_tab\n ),\n \"virtual_servers\": (\n settings.registry_mode in (RegistryMode.FULL, RegistryMode.MCP_SERVERS_ONLY)\n and settings.show_virtual_servers_tab\n ),\n \"federation\": settings.registry_mode == RegistryMode.FULL,\n \"gateway_proxy\": settings.deployment_mode == DeploymentMode.WITH_GATEWAY,\n },\n }\n\n\n# ---------------------------------------------------------------------------\n# Export format enum and export helpers\n# ---------------------------------------------------------------------------\n\n\nclass ExportFormat(str, Enum):\n \"\"\"Supported configuration export formats.\"\"\"\n\n ENV = \"env\"\n JSON = \"json\"\n TFVARS = \"tfvars\"\n YAML = \"yaml\"\n\n\ndef _iter_group_fields(\n group_def: dict[str, Any],\n) -> list[tuple[str, str, bool, str | None]]:\n \"\"\"Yield (field_name, display_name, is_sensitive, subgroup_title) for all fields in a group.\n\n For groups without subgroups, subgroup_title is None.\n For groups with subgroups, top-level fields come first, then subgroup fields.\n \"\"\"\n results: list[tuple[str, str, bool, str | None]] = []\n for field_name, display_name, is_sensitive in group_def[\"fields\"]:\n results.append((field_name, display_name, is_sensitive, None))\n for sg in group_def.get(\"subgroups\", []):\n for field_name, display_name, is_sensitive in sg[\"fields\"]:\n results.append((field_name, display_name, is_sensitive, sg[\"title\"]))\n return results\n\n\ndef _export_as_env(include_sensitive: bool = False) -> str:\n \"\"\"Export configuration as .env file format.\n\n Uppercased keys, group header comments, commented-out sensitive fields\n when include_sensitive is False, lowercase booleans, commented-out None values.\n \"\"\"\n lines = [\n \"# MCP Gateway Registry Configuration\",\n f\"# Exported: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime())}\",\n \"# WARNING: Sensitive values are masked unless explicitly included\",\n \"\",\n ]\n\n for group_id, group_def in sorted(CONFIG_GROUPS.items(), key=lambda x: x[1][\"order\"]):\n lines.append(f\"# === {group_def['title']} ===\")\n current_sg = None\n for field_name, _display_name, is_sensitive, sg_title in _iter_group_fields(group_def):\n if sg_title and sg_title != current_sg:\n lines.append(f\"# --- {sg_title} ---\")\n current_sg = sg_title\n value = _get_field_value(field_name)\n env_key = field_name.upper()\n sensitive = is_sensitive or _is_sensitive_field(field_name)\n\n if sensitive:\n if include_sensitive:\n lines.append(f\"{env_key}={value}\")\n else:\n lines.append(f\"# {env_key}=\")\n elif value is None:\n lines.append(f\"# {env_key}=\")\n elif isinstance(value, bool):\n lines.append(f\"{env_key}={str(value).lower()}\")\n else:\n lines.append(f\"{env_key}={value}\")\n lines.append(\"\")\n\n return \"\\n\".join(lines)\n\n\ndef _export_as_json(include_sensitive: bool = False) -> str:\n \"\"\"Export configuration as JSON with _metadata and configuration sections.\n\n Uses json.dumps with default=str for non-serialisable types.\n \"\"\"\n config: dict[str, dict[str, Any]] = {}\n for group_id, group_def in CONFIG_GROUPS.items():\n group_config: dict[str, Any] = {}\n for field_name, _display_name, is_sensitive, _sg_title in _iter_group_fields(group_def):\n value = _get_field_value(field_name)\n sensitive = is_sensitive or _is_sensitive_field(field_name)\n\n if sensitive and not include_sensitive:\n group_config[field_name] = \"\"\n else:\n group_config[field_name] = value\n config[group_id] = group_config\n\n return json.dumps(\n {\n \"_metadata\": {\n \"exported_at\": time.strftime(\"%Y-%m-%dT%H:%M:%SZ\", time.gmtime()),\n \"registry_mode\": settings.registry_mode.value,\n \"includes_sensitive\": include_sensitive,\n },\n \"configuration\": config,\n },\n indent=2,\n default=str,\n )\n\n\ndef _export_as_tfvars(include_sensitive: bool = False) -> str:\n \"\"\"Export configuration as Terraform .tfvars format.\n\n Lowercase keys, quoted strings, unquoted booleans/numbers,\n commented-out sensitive/None values.\n \"\"\"\n lines = [\n \"# MCP Gateway Registry - Terraform Variables\",\n f\"# Exported: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime())}\",\n \"\",\n ]\n\n for group_id, group_def in sorted(CONFIG_GROUPS.items(), key=lambda x: x[1][\"order\"]):\n lines.append(f\"# {group_def['title']}\")\n current_sg = None\n for field_name, _display_name, is_sensitive, sg_title in _iter_group_fields(group_def):\n if sg_title and sg_title != current_sg:\n lines.append(f\"# {sg_title}\")\n current_sg = sg_title\n value = _get_field_value(field_name)\n tf_key = field_name.lower()\n sensitive = is_sensitive or _is_sensitive_field(field_name)\n\n if sensitive:\n if include_sensitive:\n if isinstance(value, str):\n lines.append(f'{tf_key} = \"{value}\"')\n else:\n lines.append(f\"{tf_key} = {value}\")\n else:\n lines.append(f'# {tf_key} = \"\"')\n elif value is None:\n lines.append(f\"# {tf_key} = null\")\n elif isinstance(value, bool):\n lines.append(f\"{tf_key} = {str(value).lower()}\")\n elif isinstance(value, (int, float)):\n lines.append(f\"{tf_key} = {value}\")\n elif isinstance(value, str):\n lines.append(f'{tf_key} = \"{value}\"')\n else:\n lines.append(f'{tf_key} = \"{value}\"')\n lines.append(\"\")\n\n return \"\\n\".join(lines)\n\n\ndef _export_as_yaml(include_sensitive: bool = False) -> str:\n \"\"\"Export configuration as YAML with metadata and configuration sections.\n\n Lowercase booleans, multi-line string handling with block scalar (|).\n \"\"\"\n lines = [\n \"# MCP Gateway Registry Configuration\",\n f\"# Exported: {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}\",\n \"\",\n \"metadata:\",\n f\" exported_at: {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}\",\n f\" registry_mode: {settings.registry_mode.value}\",\n f\" includes_sensitive: {str(include_sensitive).lower()}\",\n \"\",\n \"configuration:\",\n ]\n\n for group_id, group_def in sorted(CONFIG_GROUPS.items(), key=lambda x: x[1][\"order\"]):\n lines.append(f\" # {group_def['title']}\")\n lines.append(f\" {group_id}:\")\n current_sg = None\n for field_name, _display_name, is_sensitive, sg_title in _iter_group_fields(group_def):\n if sg_title and sg_title != current_sg:\n lines.append(f\" # {sg_title}\")\n current_sg = sg_title\n value = _get_field_value(field_name)\n sensitive = is_sensitive or _is_sensitive_field(field_name)\n\n if sensitive:\n if include_sensitive:\n if isinstance(value, str):\n lines.append(f' {field_name}: \"{value}\"')\n else:\n lines.append(f\" {field_name}: {value}\")\n else:\n lines.append(f' {field_name}: \"\"')\n elif value is None:\n lines.append(f\" {field_name}: null\")\n elif isinstance(value, bool):\n lines.append(f\" {field_name}: {str(value).lower()}\")\n elif isinstance(value, str):\n if \"\\n\" in value:\n lines.append(f\" {field_name}: |\")\n for line in value.split(\"\\n\"):\n lines.append(f\" {line}\")\n else:\n lines.append(f' {field_name}: \"{value}\"')\n else:\n lines.append(f\" {field_name}: {value}\")\n lines.append(\"\")\n\n return \"\\n\".join(lines)\n\n\n# ---------------------------------------------------------------------------\n# GET /api/config/export — admin-only configuration export\n# ---------------------------------------------------------------------------\n\n_EXPORT_CONTENT_TYPES = {\n ExportFormat.ENV: \"text/plain\",\n ExportFormat.JSON: \"application/json\",\n ExportFormat.TFVARS: \"text/plain\",\n ExportFormat.YAML: \"application/x-yaml\",\n}\n\n_EXPORT_FILENAMES = {\n ExportFormat.ENV: \"mcp-registry.env\",\n ExportFormat.JSON: \"mcp-registry-config.json\",\n ExportFormat.TFVARS: \"mcp-registry.tfvars\",\n ExportFormat.YAML: \"mcp-registry-config.yaml\",\n}\n\n_EXPORT_FUNCTIONS = {\n ExportFormat.ENV: _export_as_env,\n ExportFormat.JSON: _export_as_json,\n ExportFormat.TFVARS: _export_as_tfvars,\n ExportFormat.YAML: _export_as_yaml,\n}\n\n\n@router.get(\n \"/export\",\n summary=\"Export registry configuration\",\n description=\"Export configuration in various formats. Admin only.\",\n)\nasync def export_config(\n request: Request,\n user_context: Annotated[dict, Depends(enhanced_auth)],\n format: ExportFormat = Query(\n ExportFormat.ENV,\n description=\"Export format: env, json, tfvars, yaml\",\n ),\n include_sensitive: bool = Query(\n False,\n description=\"Include sensitive values (use with caution)\",\n ),\n) -> PlainTextResponse:\n \"\"\"Export configuration in the specified format.\"\"\"\n if not user_context.get(\"is_admin\", False):\n raise HTTPException(\n status_code=403,\n detail=\"Admin access required to export configuration\",\n )\n\n username = user_context.get(\"username\", \"unknown\")\n\n if not _check_rate_limit(username):\n raise HTTPException(\n status_code=429,\n detail=\"Rate limit exceeded. Try again later.\",\n )\n\n CONFIG_EXPORT_REQUESTS.labels(\n format=format.value,\n includes_sensitive=str(include_sensitive),\n ).inc()\n\n # Audit log\n client_ip = request.client.host if request.client else \"unknown\"\n logger.info(\n \"Config export requested by user=%s format=%s include_sensitive=%s ip=%s\",\n username,\n format.value,\n include_sensitive,\n client_ip,\n )\n\n audit_logger = getattr(request.app.state, \"audit_logger\", None)\n if audit_logger:\n try:\n import uuid\n from datetime import datetime\n\n from ..audit.models import (\n Action,\n Identity,\n RegistryApiAccessRecord,\n )\n from ..audit.models import (\n Request as AuditRequest,\n )\n from ..audit.models import (\n Response as AuditResponse,\n )\n\n record = RegistryApiAccessRecord(\n timestamp=datetime.now(UTC),\n request_id=str(uuid.uuid4()),\n identity=Identity(\n username=username,\n auth_method=user_context.get(\"auth_method\", \"unknown\"),\n is_admin=True,\n credential_type=\"session_cookie\",\n ),\n request=AuditRequest(\n method=\"GET\",\n path=\"/api/config/export\",\n client_ip=client_ip,\n query_params={\n \"format\": format.value,\n \"include_sensitive\": include_sensitive,\n },\n ),\n response=AuditResponse(status_code=200, duration_ms=0),\n action=Action(\n operation=\"read\",\n resource_type=\"config\",\n description=f\"Exported configuration as {format.value}\",\n ),\n )\n await audit_logger.log_event(record)\n except Exception:\n logger.debug(\"Could not write structured audit event for config_export\", exc_info=True)\n\n content = _EXPORT_FUNCTIONS[format](include_sensitive)\n media_type = _EXPORT_CONTENT_TYPES[format]\n filename = _EXPORT_FILENAMES[format]\n\n return PlainTextResponse(\n content=content,\n media_type=media_type,\n headers={\"Content-Disposition\": f'attachment; filename=\"{filename}\"'},\n )\n" }, { "path": "registry/api/export_routes.py", "content": "\"\"\"Routes for data export audit events and admin data dumps.\"\"\"\n\nimport logging\nfrom typing import (\n Annotated,\n Any,\n)\n\nfrom fastapi import (\n APIRouter,\n Depends,\n HTTPException,\n Request,\n status,\n)\nfrom pydantic import (\n BaseModel,\n Field,\n)\n\nfrom ..audit import set_audit_action\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..repositories.factory import get_scope_repository\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/api/export\", tags=[\"Data Export\"])\n\n\nclass ExportAuditRequest(BaseModel):\n \"\"\"Request body for recording a data export audit event.\"\"\"\n\n export_type: str = Field(\n ...,\n description=\"Type of export: 'single' for one collection, 'all' for bulk ZIP\",\n pattern=\"^(single|all)$\",\n )\n collections: list[str] = Field(\n ...,\n description=\"List of collection IDs that were exported\",\n min_length=1,\n )\n\n\ndef _require_admin(\n user_context: dict[str, Any] = Depends(nginx_proxied_auth),\n) -> dict[str, Any]:\n \"\"\"Dependency that requires admin access.\"\"\"\n if not user_context.get(\"is_admin\", False):\n logger.warning(\n f\"Non-admin user '{user_context.get('username', 'unknown')}' \"\n \"attempted to record export audit event\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Admin access required\",\n )\n return user_context\n\n\n@router.post(\"/audit-event\")\nasync def record_export_audit_event(\n request: Request,\n body: ExportAuditRequest,\n user_context: Annotated[dict, Depends(_require_admin)],\n) -> dict[str, str]:\n \"\"\"Record an audit event for a data export action.\n\n This endpoint emits a dedicated audit event so that export activity\n is easily searchable in the audit log (operation='export', resource_type='data').\n \"\"\"\n collections_str = \", \".join(body.collections)\n set_audit_action(\n request,\n \"export\",\n \"data\",\n description=f\"Data export ({body.export_type}): {collections_str}\",\n )\n logger.info(\n f\"Data export audit event recorded: type={body.export_type}, \"\n f\"collections={collections_str}, user={user_context.get('username', 'unknown')}\"\n )\n return {\"status\": \"ok\"}\n\n\n@router.get(\"/scopes\")\nasync def export_scopes(\n user_context: Annotated[dict, Depends(_require_admin)],\n) -> dict[str, Any]:\n \"\"\"Export all scope documents from the mcp_scopes collection.\n\n Returns the raw scope documents with full server_access rules,\n group_mappings, ui_permissions, and agent_access details.\n \"\"\"\n scope_repo = get_scope_repository()\n collection = await scope_repo._get_collection()\n cursor = collection.find({})\n scopes = []\n async for doc in cursor:\n doc[\"scope_name\"] = doc.pop(\"_id\", None)\n scopes.append(doc)\n logger.info(\n f\"Exported {len(scopes)} scope documents for user \"\n f\"'{user_context.get('username', 'unknown')}'\"\n )\n return {\"scopes\": scopes, \"total_count\": len(scopes)}\n" }, { "path": "registry/api/federation_export_routes.py", "content": "\"\"\"\nFederation Export API routes for MCP Gateway Registry.\n\nThis module provides REST API endpoints for exporting servers and agents to peer\nregistries in a federated mesh topology. Endpoints enforce visibility-based\naccess control and support incremental sync via generation numbers.\n\nBased on: docs/federation.md\n\"\"\"\n\nimport logging\nimport socket\nfrom typing import Annotated, Any\n\nfrom fastapi import APIRouter, Depends, HTTPException, Query, status\n\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..core.config import settings\nfrom ..repositories.factory import get_security_scan_repository\nfrom ..schemas.peer_federation_schema import FederationExportResponse\nfrom ..services.agent_service import agent_service\nfrom ..services.federation_audit_service import get_federation_audit_service\nfrom ..services.peer_federation_service import get_peer_federation_service\nfrom ..services.server_service import server_service\n\nlogger = logging.getLogger(__name__)\n\n\nrouter = APIRouter(prefix=\"/api/federation\", tags=[\"federation\"])\n\n\n# Constants\nDEFAULT_PAGE_LIMIT: int = 100\nMAX_PAGE_LIMIT: int = 1000\n\n\nasync def _get_current_sync_generation() -> int:\n \"\"\"\n Compute the current sync generation dynamically.\n\n Uses the total count of enabled servers and agents as a generation proxy.\n When items are added, removed, or toggled, the count changes, signaling\n peers that a re-sync may be needed. Returns at least 1 so that peers\n with generation 0 always get all items on their first sync.\n\n Returns:\n Current sync generation number (minimum 1)\n \"\"\"\n try:\n all_servers = await server_service.get_all_servers()\n enabled_server_count = 0\n for path in all_servers:\n if await server_service.is_service_enabled(path):\n enabled_server_count += 1\n\n agent_states = await agent_service.get_all_agent_states()\n enabled_agent_count = sum(1 for enabled in agent_states.values() if enabled)\n\n generation = max(1, enabled_server_count + enabled_agent_count)\n return generation\n except Exception as e:\n logger.warning(f\"Failed to compute sync generation, defaulting to 1: {e}\")\n return 1\n\n\ndef _get_registry_id() -> str:\n \"\"\"\n Get the unique identifier for this registry instance.\n\n Uses REGISTRY_ID from settings if configured, otherwise falls back\n to hostname-based ID.\n\n Returns:\n Registry identifier string\n \"\"\"\n # Use configured registry_id if available\n if settings.registry_id:\n return settings.registry_id\n\n # Fallback to hostname-based ID\n try:\n hostname = socket.gethostname()\n return f\"registry-{hostname}\"\n except Exception as e:\n logger.warning(f\"Failed to get hostname: {e}, using default\")\n return \"registry-unknown\"\n\n\ndef _check_federation_scope(\n user_context: dict[str, Any],\n) -> None:\n \"\"\"Check if user has federation access scope.\n\n Accepts either:\n - 'federation-service' scope (OAuth2 JWT from Keycloak service account)\n - 'federation/read' scope (federation static token)\n\n Args:\n user_context: User context from auth dependency\n\n Raises:\n HTTPException: 403 if no federation scope is present\n \"\"\"\n scopes = user_context.get(\"scopes\", [])\n has_federation_scope = \"federation-service\" in scopes or \"federation/read\" in scopes\n if not has_federation_scope:\n logger.warning(\n f\"User {user_context.get('username')} attempted federation access \"\n f\"without federation scope. Scopes: {scopes}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Federation access requires 'federation-service' or 'federation/read' scope\",\n )\n\n\ndef _get_item_attr(\n item: Any,\n attr: str,\n default: Any = None,\n) -> Any:\n \"\"\"\n Get attribute from item, supporting both dict and object types.\n\n Args:\n item: Dict or object to get attribute from\n attr: Attribute name\n default: Default value if not found\n\n Returns:\n Attribute value or default\n \"\"\"\n if isinstance(item, dict):\n return item.get(attr, default)\n return getattr(item, attr, default)\n\n\ndef _is_federated_item(\n item: Any,\n) -> bool:\n \"\"\"\n Check if an item was synced from another peer registry.\n\n This is used for chain prevention: items synced from A to B should not\n be re-exported from B to C. Only locally-created items should be exported.\n\n Args:\n item: Dict or object to check\n\n Returns:\n True if the item has sync_metadata.is_federated == True\n \"\"\"\n sync_metadata = _get_item_attr(item, \"sync_metadata\", None)\n if not sync_metadata:\n return False\n\n if isinstance(sync_metadata, dict):\n return sync_metadata.get(\"is_federated\", False) is True\n\n return getattr(sync_metadata, \"is_federated\", False) is True\n\n\ndef _filter_by_visibility(\n items: list[Any],\n peer_groups: list[str],\n) -> list[Any]:\n \"\"\"\n Filter items based on visibility and peer's group membership.\n\n Filtering rules:\n - Federated items (synced from another peer): NEVER included (chain prevention)\n - visibility=public: Always included (default if not specified)\n - visibility=group-restricted: Include only if peer is in allowed_groups\n - visibility=private: NEVER included (also matches legacy \"internal\")\n\n Args:\n items: List of items (dict or object) to filter\n peer_groups: Groups the peer registry belongs to (from JWT)\n\n Returns:\n Filtered list of items\n \"\"\"\n filtered = []\n peer_group_set = set(peer_groups)\n federated_count = 0\n\n for item in items:\n # Chain prevention: Never re-export items synced from another peer\n # This prevents A->B->C propagation where items from A would be\n # re-exported from B to C\n if _is_federated_item(item):\n federated_count += 1\n continue\n\n # Default to \"public\" if visibility not specified (backwards compatibility)\n visibility = _get_item_attr(item, \"visibility\", \"public\")\n\n # Never export private items (also handles legacy \"internal\" via normalization)\n if visibility in (\"private\", \"internal\"):\n continue\n\n # Always export public items\n if visibility == \"public\":\n filtered.append(item)\n continue\n\n # Export group-restricted only if peer is in allowed_groups\n if visibility == \"group-restricted\":\n allowed_groups = set(_get_item_attr(item, \"allowed_groups\", []))\n if allowed_groups & peer_group_set:\n filtered.append(item)\n continue\n\n logger.debug(\n f\"Filtered {len(items)} items to {len(filtered)} based on visibility. \"\n f\"Excluded {federated_count} federated items (chain prevention). \"\n f\"Peer groups: {peer_groups}\"\n )\n\n return filtered\n\n\ndef _filter_by_generation(\n items: list[Any],\n since_generation: int | None,\n) -> list[Any]:\n \"\"\"\n Filter items by sync generation for incremental sync.\n\n Args:\n items: List of items (dict or object) to filter\n since_generation: Minimum generation number (exclusive).\n If None, returns all items (full sync).\n If 0, returns only items with generation > 0.\n\n Returns:\n Filtered list of items with generation > since_generation,\n plus all items without sync_metadata (local items never synced).\n \"\"\"\n # Full sync: return all items if since_generation is None\n if since_generation is None:\n return items\n\n filtered = []\n for item in items:\n sync_metadata = _get_item_attr(item, \"sync_metadata\", None)\n if sync_metadata:\n if isinstance(sync_metadata, dict):\n item_generation = sync_metadata.get(\"sync_generation\", 0)\n else:\n item_generation = getattr(sync_metadata, \"sync_generation\", 0)\n\n # Include if item's generation is newer than requested\n if item_generation > since_generation:\n filtered.append(item)\n else:\n # Items without sync_metadata are local items that have never been\n # synced - always include them as they're \"new\" to the peer\n filtered.append(item)\n\n logger.debug(\n f\"Filtered {len(items)} items to {len(filtered)} with generation > {since_generation} \"\n f\"(includes items without sync_metadata)\"\n )\n\n return filtered\n\n\ndef _item_to_dict(\n item: Any,\n) -> dict[str, Any]:\n \"\"\"\n Convert item to dictionary, supporting both dict and object types.\n\n Args:\n item: Dict or Pydantic model\n\n Returns:\n Dictionary representation\n \"\"\"\n if isinstance(item, dict):\n return item\n if hasattr(item, \"model_dump\"):\n return item.model_dump()\n return dict(item)\n\n\ndef _paginate(\n items: list[Any],\n limit: int,\n offset: int,\n) -> tuple[list[Any], bool]:\n \"\"\"\n Paginate items list.\n\n Args:\n items: List of items to paginate\n limit: Maximum items per page\n offset: Number of items to skip\n\n Returns:\n Tuple of (paginated items, has_more flag)\n \"\"\"\n start = offset\n end = offset + limit\n paginated = items[start:end]\n has_more = len(items) > end\n\n return paginated, has_more\n\n\nasync def federation_auth(\n user_context: Annotated[dict[str, Any], Depends(nginx_proxied_auth)],\n) -> dict[str, Any]:\n \"\"\"\n Authentication dependency for federation endpoints.\n\n Validates that the requester has federation-service scope in their JWT\n and identifies the peer by matching their client_id (azp claim) to a\n registered peer's expected_client_id.\n\n Args:\n user_context: User context from nginx_proxied_auth\n\n Returns:\n User context enriched with peer_id and peer_name if peer is identified\n\n Raises:\n HTTPException: 403 if federation-service scope not present\n \"\"\"\n _check_federation_scope(user_context)\n\n # Extract client_id from token (azp claim)\n client_id = user_context.get(\"client_id\", \"\")\n\n # Look up peer by client_id\n if client_id:\n peer_service = get_peer_federation_service()\n peer = await peer_service.get_peer_by_client_id(client_id)\n if peer:\n user_context[\"peer_id\"] = peer.peer_id\n user_context[\"peer_name\"] = peer.name\n logger.info(f\"Identified federation peer: {peer.peer_id} (client_id: {client_id})\")\n else:\n logger.debug(f\"Federation request from unregistered client_id: {client_id}\")\n\n return user_context\n\n\n@router.get(\"/health\")\nasync def federation_health():\n \"\"\"\n Federation health check endpoint.\n\n This endpoint does NOT require authentication and is used by peer registries\n to check if the federation API is available before attempting sync.\n\n Returns:\n 200 OK with status message\n \"\"\"\n return {\n \"status\": \"healthy\",\n \"federation_api_version\": \"1.0\",\n \"registry_id\": _get_registry_id(),\n }\n\n\n@router.get(\n \"/servers\",\n response_model=FederationExportResponse,\n)\nasync def export_servers(\n limit: int = Query(\n DEFAULT_PAGE_LIMIT,\n ge=1,\n le=MAX_PAGE_LIMIT,\n description=f\"Maximum items per page (default {DEFAULT_PAGE_LIMIT}, max {MAX_PAGE_LIMIT})\",\n ),\n offset: int = Query(\n 0,\n ge=0,\n description=\"Number of items to skip (default 0)\",\n ),\n since_generation: int | None = Query(\n None,\n ge=0,\n description=\"Return only items with generation > this value (for incremental sync)\",\n ),\n user_context: Annotated[dict[str, Any], Depends(federation_auth)] = None,\n):\n \"\"\"\n Export servers for federation sync.\n\n Returns servers with visibility filtering based on the peer's group membership.\n Supports pagination and incremental sync via generation numbers.\n\n **Authentication:** Requires JWT with 'federation-service' scope\n\n **Visibility filtering:**\n - public: Returned to all peers\n - group-restricted: Returned only if peer is in allowed_groups\n - internal: NEVER returned\n\n **Pagination:**\n - Use limit and offset for pagination\n - Check has_more to determine if more pages exist\n\n **Incremental sync:**\n - Use since_generation to get only changed items\n - Track sync_generation from response for next sync\n\n Args:\n limit: Maximum items per page\n offset: Number of items to skip\n since_generation: Minimum generation for incremental sync\n user_context: Authenticated peer context\n\n Returns:\n FederationExportResponse with filtered servers\n\n Raises:\n HTTPException: 401 if unauthenticated, 403 if missing federation scope\n \"\"\"\n logger.info(\n f\"Federation export request for servers from peer '{user_context['username']}' \"\n f\"(limit={limit}, offset={offset}, since_generation={since_generation})\"\n )\n\n # Get all servers (enabled and disabled) - returns Dict[str, Dict[str, Any]]\n all_servers_dict = await server_service.get_all_servers()\n\n # Convert to list and filter out disabled servers - never sync disabled servers\n # Each server is a dict with 'path' key\n enabled_servers = []\n for path, server_data in all_servers_dict.items():\n if await server_service.is_service_enabled(path):\n enabled_servers.append(server_data)\n\n # Extract peer groups from JWT for visibility filtering\n peer_groups = user_context.get(\"groups\", [])\n\n # Apply visibility filtering\n visible_servers = _filter_by_visibility(enabled_servers, peer_groups)\n\n # Apply generation filtering for incremental sync\n if since_generation is not None:\n visible_servers = _filter_by_generation(visible_servers, since_generation)\n\n # Apply pagination\n total_count = len(visible_servers)\n paginated_servers, has_more = _paginate(visible_servers, limit, offset)\n\n # Convert to dict format (servers are already dicts from service)\n items = [_item_to_dict(server) for server in paginated_servers]\n\n logger.info(\n f\"Exporting {len(items)} servers to peer '{user_context['username']}' \"\n f\"(total visible: {total_count}, has_more: {has_more})\"\n )\n\n # Log the connection for audit trail\n audit_service = get_federation_audit_service()\n await audit_service.log_connection(\n peer_id=user_context.get(\"peer_id\", user_context.get(\"username\", \"unknown\")),\n peer_name=user_context.get(\"peer_name\", \"\"),\n client_id=user_context.get(\"client_id\", \"\"),\n endpoint=\"/api/federation/servers\",\n items_requested=len(items),\n success=True,\n )\n\n return FederationExportResponse(\n items=items,\n sync_generation=await _get_current_sync_generation(),\n total_count=total_count,\n has_more=has_more,\n registry_id=_get_registry_id(),\n )\n\n\n@router.get(\n \"/agents\",\n response_model=FederationExportResponse,\n)\nasync def export_agents(\n limit: int = Query(\n DEFAULT_PAGE_LIMIT,\n ge=1,\n le=MAX_PAGE_LIMIT,\n description=f\"Maximum items per page (default {DEFAULT_PAGE_LIMIT}, max {MAX_PAGE_LIMIT})\",\n ),\n offset: int = Query(\n 0,\n ge=0,\n description=\"Number of items to skip (default 0)\",\n ),\n since_generation: int | None = Query(\n None,\n ge=0,\n description=\"Return only items with generation > this value (for incremental sync)\",\n ),\n user_context: Annotated[dict[str, Any], Depends(federation_auth)] = None,\n):\n \"\"\"\n Export agents for federation sync.\n\n Returns agents with visibility filtering based on the peer's group membership.\n Supports pagination and incremental sync via generation numbers.\n\n **Authentication:** Requires JWT with 'federation-service' scope\n\n **Visibility filtering:**\n - public: Returned to all peers\n - group-restricted: Returned only if peer is in allowed_groups\n - internal: NEVER returned\n\n **Pagination:**\n - Use limit and offset for pagination\n - Check has_more to determine if more pages exist\n\n **Incremental sync:**\n - Use since_generation to get only changed items\n - Track sync_generation from response for next sync\n\n Args:\n limit: Maximum items per page\n offset: Number of items to skip\n since_generation: Minimum generation for incremental sync\n user_context: Authenticated peer context\n\n Returns:\n FederationExportResponse with filtered agents\n\n Raises:\n HTTPException: 401 if unauthenticated, 403 if missing federation scope\n \"\"\"\n logger.info(\n f\"Federation export request for agents from peer '{user_context['username']}' \"\n f\"(limit={limit}, offset={offset}, since_generation={since_generation})\"\n )\n\n # Get all agents (enabled and disabled)\n all_agents = await agent_service.get_all_agents()\n\n # Filter out disabled agents, never sync disabled agents\n agent_states = await agent_service.get_all_agent_states()\n enabled_agents = [a for a in all_agents if agent_states.get(a.path, False)]\n\n # Extract peer groups from JWT for visibility filtering\n peer_groups = user_context.get(\"groups\", [])\n\n # Apply visibility filtering\n visible_agents = _filter_by_visibility(enabled_agents, peer_groups)\n\n # Apply generation filtering for incremental sync\n if since_generation is not None:\n visible_agents = _filter_by_generation(visible_agents, since_generation)\n\n # Apply pagination\n total_count = len(visible_agents)\n paginated_agents, has_more = _paginate(visible_agents, limit, offset)\n\n # Convert to dict format (agents are AgentCard objects)\n items = [_item_to_dict(agent) for agent in paginated_agents]\n\n logger.info(\n f\"Exporting {len(items)} agents to peer '{user_context['username']}' \"\n f\"(total visible: {total_count}, has_more: {has_more})\"\n )\n\n # Log the connection for audit trail\n audit_service = get_federation_audit_service()\n await audit_service.log_connection(\n peer_id=user_context.get(\"peer_id\", user_context.get(\"username\", \"unknown\")),\n peer_name=user_context.get(\"peer_name\", \"\"),\n client_id=user_context.get(\"client_id\", \"\"),\n endpoint=\"/api/federation/agents\",\n items_requested=len(items),\n success=True,\n )\n\n return FederationExportResponse(\n items=items,\n sync_generation=await _get_current_sync_generation(),\n total_count=total_count,\n has_more=has_more,\n registry_id=_get_registry_id(),\n )\n\n\n@router.get(\n \"/security-scans\",\n response_model=FederationExportResponse,\n)\nasync def export_security_scans(\n limit: int = Query(\n DEFAULT_PAGE_LIMIT,\n ge=1,\n le=MAX_PAGE_LIMIT,\n description=f\"Maximum items per page (default {DEFAULT_PAGE_LIMIT}, max {MAX_PAGE_LIMIT})\",\n ),\n offset: int = Query(\n 0,\n ge=0,\n description=\"Number of items to skip (default 0)\",\n ),\n user_context: Annotated[dict[str, Any], Depends(federation_auth)] = None,\n):\n \"\"\"\n Export security scan results for federation sync.\n\n Returns security scan results only for servers that are visible to the peer\n based on the server's visibility settings. This ensures peers only receive\n security information for servers they can access.\n\n **Authentication:** Requires JWT with 'federation-service' or 'federation/read' scope\n\n **Visibility filtering:**\n - Only returns scans for servers with visibility=public\n - Returns scans for group-restricted servers only if peer is in allowed_groups\n - Never returns scans for internal servers\n\n **Pagination:**\n - Use limit and offset for pagination\n - Check has_more to determine if more pages exist\n\n Args:\n limit: Maximum items per page\n offset: Number of items to skip\n user_context: Authenticated peer context\n\n Returns:\n FederationExportResponse with security scan results\n\n Raises:\n HTTPException: 401 if unauthenticated, 403 if missing federation scope\n \"\"\"\n logger.info(\n f\"Federation export request for security scans from peer '{user_context['username']}' \"\n f\"(limit={limit}, offset={offset})\"\n )\n\n # Get all servers to build visibility map\n all_servers_dict = await server_service.get_all_servers()\n\n # Build a set of visible server paths for this peer\n peer_groups = user_context.get(\"groups\", [])\n peer_group_set = set(peer_groups)\n visible_server_paths: set[str] = set()\n\n for path, server_data in all_servers_dict.items():\n # Check if server is enabled\n if not await server_service.is_service_enabled(path):\n continue\n\n # Check visibility\n visibility = server_data.get(\"visibility\", \"public\")\n\n if visibility in (\"private\", \"internal\"):\n continue\n\n if visibility == \"public\":\n visible_server_paths.add(path)\n continue\n\n if visibility == \"group-restricted\":\n allowed_groups = set(server_data.get(\"allowed_groups\", []))\n if allowed_groups & peer_group_set:\n visible_server_paths.add(path)\n\n logger.debug(f\"Visible server paths for peer: {len(visible_server_paths)} servers\")\n\n # Get all security scans from repository\n scan_repo = get_security_scan_repository()\n all_scans = await scan_repo.list_all()\n\n # Filter scans to only include those for visible servers\n visible_scans = []\n for scan in all_scans:\n server_path = scan.get(\"server_path\", \"\")\n if server_path in visible_server_paths:\n visible_scans.append(scan)\n\n logger.debug(f\"Filtered {len(all_scans)} scans to {len(visible_scans)} for visible servers\")\n\n # Apply pagination\n total_count = len(visible_scans)\n paginated_scans, has_more = _paginate(visible_scans, limit, offset)\n\n # Convert to dict format (scans are already dicts)\n items = [_item_to_dict(scan) for scan in paginated_scans]\n\n logger.info(\n f\"Exporting {len(items)} security scans to peer '{user_context['username']}' \"\n f\"(total visible: {total_count}, has_more: {has_more})\"\n )\n\n # Log the connection for audit trail\n audit_service = get_federation_audit_service()\n await audit_service.log_connection(\n peer_id=user_context.get(\"peer_id\", user_context.get(\"username\", \"unknown\")),\n peer_name=user_context.get(\"peer_name\", \"\"),\n client_id=user_context.get(\"client_id\", \"\"),\n endpoint=\"/api/federation/security-scans\",\n items_requested=len(items),\n success=True,\n )\n\n return FederationExportResponse(\n items=items,\n sync_generation=await _get_current_sync_generation(),\n total_count=total_count,\n has_more=has_more,\n registry_id=_get_registry_id(),\n )\n" }, { "path": "registry/api/federation_routes.py", "content": "\"\"\"\nFederation configuration API routes.\n\nProvides endpoints to manage federation configurations.\n\"\"\"\n\nimport logging\nfrom datetime import UTC\nfrom typing import Annotated, Any\nfrom uuid import uuid4\n\nfrom fastapi import APIRouter, Depends, HTTPException, Request, status\n\nfrom ..audit import set_audit_action\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..repositories.factory import get_federation_config_repository\nfrom ..repositories.interfaces import FederationConfigRepositoryBase\nfrom ..schemas.federation_schema import (\n AwsRegistryConfig,\n FederationConfig,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n\ndef _get_federation_repo() -> FederationConfigRepositoryBase:\n \"\"\"Get federation config repository dependency.\"\"\"\n return get_federation_config_repository()\n\n\n@router.get(\"/federation/config\", tags=[\"federation\"], summary=\"Get federation configuration\")\nasync def get_federation_config(\n request: Request,\n config_id: str = \"default\",\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Get federation configuration by ID.\n\n Args:\n config_id: Configuration ID (default: \"default\")\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Federation configuration\n\n Raises:\n 404: Configuration not found\n \"\"\"\n # Set audit action for federation config read\n set_audit_action(\n request,\n \"read\",\n \"federation\",\n resource_id=config_id,\n description=f\"Read federation config {config_id}\",\n )\n\n logger.info(f\"User {user_context['username']} retrieving federation config: {config_id}\")\n\n config = await repo.get_config(config_id)\n\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n return config.model_dump()\n\n\n@router.post(\n \"/federation/config\",\n tags=[\"federation\"],\n summary=\"Create or update federation configuration\",\n status_code=status.HTTP_201_CREATED,\n)\nasync def save_federation_config(\n request: Request,\n config: FederationConfig,\n config_id: str = \"default\",\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Create or update federation configuration.\n\n Args:\n config: Federation configuration to save\n config_id: Configuration ID (default: \"default\")\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Saved configuration\n\n Example:\n ```json\n {\n \"anthropic\": {\n \"enabled\": true,\n \"endpoint\": \"https://registry.modelcontextprotocol.io\",\n \"sync_on_startup\": false,\n \"servers\": [\n {\"name\": \"io.github.jgador/websharp\"},\n {\"name\": \"modelcontextprotocol/filesystem\"}\n ]\n },\n \"asor\": {\n \"enabled\": false,\n \"endpoint\": \"\",\n \"auth_env_var\": \"ASOR_ACCESS_TOKEN\",\n \"sync_on_startup\": false,\n \"agents\": []\n }\n }\n ```\n \"\"\"\n # Set audit action for federation config create/update\n set_audit_action(\n request,\n \"create\",\n \"federation\",\n resource_id=config_id,\n description=f\"Save federation config {config_id}\",\n )\n\n logger.info(\n f\"User {user_context['username']} saving federation config: {config_id} \"\n f\"(anthropic: {config.anthropic.enabled}, asor: {config.asor.enabled})\"\n )\n\n try:\n saved_config = await repo.save_config(config, config_id)\n logger.info(f\"Federation config saved successfully: {config_id}\")\n\n # Reconcile: remove stale federated servers\n reconciliation_result = None\n try:\n from ..core.nginx_service import nginx_service\n from ..repositories.factory import get_server_repository\n from ..services.federation_reconciliation import reconcile_anthropic_servers\n from ..services.server_service import server_service\n\n server_repo = get_server_repository()\n reconciliation_result = await reconcile_anthropic_servers(\n config=saved_config,\n server_service=server_service,\n server_repo=server_repo,\n nginx_service=nginx_service,\n audit_username=user_context.get(\"username\"),\n )\n if reconciliation_result.get(\"removed\"):\n logger.info(\n f\"Reconciliation removed {reconciliation_result['removed_count']} stale servers: \"\n f\"{reconciliation_result['removed']}\"\n )\n except Exception as e:\n logger.error(f\"Reconciliation failed (non-fatal): {e}\")\n\n response = {\n \"message\": \"Federation configuration saved successfully\",\n \"config_id\": config_id,\n \"config\": saved_config.model_dump(),\n }\n if reconciliation_result:\n response[\"reconciliation\"] = reconciliation_result\n\n return response\n\n except Exception as e:\n logger.error(f\"Failed to save federation config: {e}\", exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to save federation config\",\n )\n\n\n@router.put(\n \"/federation/config/{config_id}\",\n tags=[\"federation\"],\n summary=\"Update specific federation configuration\",\n)\nasync def update_federation_config(\n request: Request,\n config_id: str,\n config: FederationConfig,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Update a specific federation configuration.\n\n Args:\n config_id: Configuration ID to update\n config: Updated federation configuration\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Updated configuration\n \"\"\"\n # Set audit action for federation config update\n set_audit_action(\n request,\n \"update\",\n \"federation\",\n resource_id=config_id,\n description=f\"Update federation config {config_id}\",\n )\n\n logger.info(f\"User {user_context['username']} updating federation config: {config_id}\")\n\n try:\n saved_config = await repo.save_config(config, config_id)\n logger.info(f\"Federation config updated successfully: {config_id}\")\n\n # Reconcile: remove stale federated servers\n reconciliation_result = None\n try:\n from ..core.nginx_service import nginx_service\n from ..repositories.factory import get_server_repository\n from ..services.federation_reconciliation import reconcile_anthropic_servers\n from ..services.server_service import server_service\n\n server_repo = get_server_repository()\n reconciliation_result = await reconcile_anthropic_servers(\n config=saved_config,\n server_service=server_service,\n server_repo=server_repo,\n nginx_service=nginx_service,\n audit_username=user_context.get(\"username\"),\n )\n if reconciliation_result.get(\"removed\"):\n logger.info(\n f\"Reconciliation removed {reconciliation_result['removed_count']} stale servers: \"\n f\"{reconciliation_result['removed']}\"\n )\n except Exception as e:\n logger.error(f\"Reconciliation failed (non-fatal): {e}\")\n\n response = {\n \"message\": \"Federation configuration updated successfully\",\n \"config_id\": config_id,\n \"config\": saved_config.model_dump(),\n }\n if reconciliation_result:\n response[\"reconciliation\"] = reconciliation_result\n\n return response\n\n except Exception as e:\n logger.error(f\"Failed to update federation config: {e}\", exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to update federation config\",\n )\n\n\n@router.delete(\n \"/federation/config/{config_id}\", tags=[\"federation\"], summary=\"Delete federation configuration\"\n)\nasync def delete_federation_config(\n config_id: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, str]:\n \"\"\"\n Delete a federation configuration.\n\n Args:\n config_id: Configuration ID to delete\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Deletion confirmation\n\n Raises:\n 404: Configuration not found\n \"\"\"\n logger.info(f\"User {user_context['username']} deleting federation config: {config_id}\")\n\n deleted = await repo.delete_config(config_id)\n\n if not deleted:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n logger.info(f\"Federation config deleted successfully: {config_id}\")\n return {\n \"message\": f\"Federation configuration '{config_id}' deleted successfully\",\n \"config_id\": config_id,\n }\n\n\n@router.get(\n \"/federation/configs\", tags=[\"federation\"], summary=\"List all federation configurations\"\n)\nasync def list_federation_configs(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n List all federation configurations.\n\n Args:\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n List of configuration summaries with id, created_at, updated_at\n \"\"\"\n logger.info(f\"User {user_context['username']} listing federation configs\")\n\n configs = await repo.list_configs()\n\n return {\"configs\": configs, \"total\": len(configs)}\n\n\n@router.post(\n \"/federation/config/{config_id}/anthropic/servers\",\n tags=[\"federation\"],\n summary=\"Add Anthropic server to config\",\n)\nasync def add_anthropic_server(\n config_id: str,\n server_name: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Add a server to Anthropic federation configuration.\n\n Args:\n config_id: Configuration ID\n server_name: Server name to add (e.g., \"io.github.jgador/websharp\")\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Updated configuration\n \"\"\"\n logger.info(f\"User {user_context['username']} adding Anthropic server: {server_name}\")\n\n config = await repo.get_config(config_id)\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n # Check if server already exists\n from ..schemas.federation_schema import AnthropicServerConfig\n\n for server in config.anthropic.servers:\n if server.name == server_name:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=f\"Server '{server_name}' already exists in configuration\",\n )\n\n # Add new server\n config.anthropic.servers.append(AnthropicServerConfig(name=server_name))\n\n # Save updated config\n saved_config = await repo.save_config(config, config_id)\n\n return {\n \"message\": f\"Server '{server_name}' added to Anthropic configuration\",\n \"config\": saved_config.model_dump(),\n }\n\n\n@router.delete(\n \"/federation/config/{config_id}/anthropic/servers/{server_name:path}\",\n tags=[\"federation\"],\n summary=\"Remove Anthropic server from config\",\n)\nasync def remove_anthropic_server(\n config_id: str,\n server_name: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Remove a server from Anthropic federation configuration.\n\n Also removes the server from mcp_servers_default if it was\n previously synced.\n\n Args:\n config_id: Configuration ID\n server_name: Server name to remove (e.g., \"io.github.jgador/websharp\")\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Updated configuration with removal details\n \"\"\"\n logger.info(f\"User {user_context['username']} removing Anthropic server: {server_name}\")\n\n config = await repo.get_config(config_id)\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n # Find and remove server from config\n original_count = len(config.anthropic.servers)\n config.anthropic.servers = [s for s in config.anthropic.servers if s.name != server_name]\n\n if len(config.anthropic.servers) == original_count:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Server '{server_name}' not found in configuration\",\n )\n\n # Save updated config\n saved_config = await repo.save_config(config, config_id)\n\n # Remove the server from mcp_servers_default if it exists\n server_path = f\"/{server_name.replace('/', '-')}\"\n server_removed = False\n try:\n from ..services.server_service import server_service\n\n server_info = await server_service.get_server_info(server_path)\n if server_info and server_info.get(\"source\") == \"anthropic\":\n server_removed = await server_service.remove_server(server_path)\n if server_removed:\n logger.info(\n f\"Removed server '{server_name}' from mcp_servers_default ({server_path})\"\n )\n\n # Regenerate nginx config\n from ..core.nginx_service import nginx_service\n\n all_servers = await server_service.get_all_servers(\n include_inactive=False,\n )\n enabled_servers = {\n p: info for p, info in all_servers.items() if info.get(\"is_enabled\", False)\n }\n await nginx_service.generate_config_async(enabled_servers)\n except Exception as e:\n logger.error(f\"Failed to remove server from mcp_servers_default: {e}\")\n\n return {\n \"message\": f\"Server '{server_name}' removed from Anthropic configuration\",\n \"config\": saved_config.model_dump(),\n \"server_removed_from_registry\": server_removed,\n }\n\n\n@router.post(\n \"/federation/config/{config_id}/asor/agents\",\n tags=[\"federation\"],\n summary=\"Add ASOR agent to config\",\n)\nasync def add_asor_agent(\n config_id: str,\n agent_id: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Add an agent to ASOR federation configuration.\n\n Args:\n config_id: Configuration ID\n agent_id: Agent ID to add (e.g., \"aws_assistant\")\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Updated configuration\n \"\"\"\n logger.info(f\"User {user_context['username']} adding ASOR agent: {agent_id}\")\n\n config = await repo.get_config(config_id)\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n # Check if agent already exists\n from ..schemas.federation_schema import AsorAgentConfig\n\n for agent in config.asor.agents:\n if agent.id == agent_id:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=f\"Agent '{agent_id}' already exists in configuration\",\n )\n\n # Add new agent\n config.asor.agents.append(AsorAgentConfig(id=agent_id))\n\n # Save updated config\n saved_config = await repo.save_config(config, config_id)\n\n return {\n \"message\": f\"Agent '{agent_id}' added to ASOR configuration\",\n \"config\": saved_config.model_dump(),\n }\n\n\n@router.delete(\n \"/federation/config/{config_id}/asor/agents/{agent_id}\",\n tags=[\"federation\"],\n summary=\"Remove ASOR agent from config\",\n)\nasync def remove_asor_agent(\n config_id: str,\n agent_id: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Remove an agent from ASOR federation configuration.\n\n Args:\n config_id: Configuration ID\n agent_id: Agent ID to remove\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Updated configuration\n \"\"\"\n logger.info(f\"User {user_context['username']} removing ASOR agent: {agent_id}\")\n\n config = await repo.get_config(config_id)\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n # Find and remove agent\n original_count = len(config.asor.agents)\n config.asor.agents = [a for a in config.asor.agents if a.id != agent_id]\n\n if len(config.asor.agents) == original_count:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Agent '{agent_id}' not found in configuration\",\n )\n\n # Save updated config\n saved_config = await repo.save_config(config, config_id)\n\n return {\n \"message\": f\"Agent '{agent_id}' removed from ASOR configuration\",\n \"config\": saved_config.model_dump(),\n }\n\n\n@router.post(\n \"/federation/config/{config_id}/aws_registry/registries\",\n tags=[\"federation\"],\n summary=\"Add AWS registry to config\",\n)\nasync def add_aws_registry(\n request: Request,\n config_id: str,\n registry_config: AwsRegistryConfig,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Add a registry to AWS Registry federation configuration.\n\n Args:\n config_id: Configuration ID\n registry_config: AWS registry configuration (JSON body)\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Updated configuration\n \"\"\"\n set_audit_action(\n request,\n \"create\",\n \"federation\",\n resource_id=config_id,\n description=f\"Add AWS registry {registry_config.registry_id}\",\n )\n\n logger.info(\n f\"User {user_context['username']} adding AWS registry: {registry_config.registry_id}\"\n )\n\n config = await repo.get_config(config_id)\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n # Check if registry already exists\n for reg in config.aws_registry.registries:\n if reg.registry_id == registry_config.registry_id:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=f\"Registry '{registry_config.registry_id}' already exists in configuration\",\n )\n\n # Add new registry\n config.aws_registry.registries.append(registry_config)\n\n # Save updated config\n saved_config = await repo.save_config(config, config_id)\n\n return {\n \"message\": f\"Registry '{registry_config.registry_id}' added to AWS Registry configuration\",\n \"config\": saved_config.model_dump(),\n }\n\n\n@router.delete(\n \"/federation/config/{config_id}/aws_registry/registries/{registry_id:path}\",\n tags=[\"federation\"],\n summary=\"Remove AWS registry from config\",\n)\nasync def remove_aws_registry(\n request: Request,\n config_id: str,\n registry_id: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Remove a registry from AWS Registry federation configuration.\n\n Args:\n config_id: Configuration ID\n registry_id: Registry ID to remove (e.g., ARN)\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Updated configuration\n \"\"\"\n set_audit_action(\n request,\n \"delete\",\n \"federation\",\n resource_id=config_id,\n description=f\"Remove AWS registry {registry_id}\",\n )\n\n logger.info(f\"User {user_context['username']} removing AWS registry: {registry_id}\")\n\n config = await repo.get_config(config_id)\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n # Find and remove registry\n original_count = len(config.aws_registry.registries)\n config.aws_registry.registries = [\n r for r in config.aws_registry.registries if r.registry_id != registry_id\n ]\n\n if len(config.aws_registry.registries) == original_count:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Registry '{registry_id}' not found in configuration\",\n )\n\n # Save updated config\n saved_config = await repo.save_config(config, config_id)\n\n # Deregister all entities synced from this registry\n cleanup = await _deregister_entities_from_registry(registry_id)\n\n total = cleanup[\"servers_count\"] + cleanup[\"agents_count\"] + cleanup[\"skills_count\"]\n message = f\"Registry '{registry_id}' removed from AWS Registry configuration\"\n if total > 0:\n parts = []\n if cleanup[\"servers_count\"]:\n parts.append(f\"{cleanup['servers_count']} server(s)\")\n if cleanup[\"agents_count\"]:\n parts.append(f\"{cleanup['agents_count']} agent(s)\")\n if cleanup[\"skills_count\"]:\n parts.append(f\"{cleanup['skills_count']} skill(s)\")\n message += f\" and {', '.join(parts)} deregistered\"\n\n return {\n \"message\": message,\n \"deregistered\": cleanup,\n \"config\": saved_config.model_dump(),\n }\n\n\nasync def _deregister_entities_from_registry(\n registry_id: str,\n) -> dict[str, Any]:\n \"\"\"\n Find and remove all servers, agents, and skills synced from a specific AWS registry.\n\n Matches entities where metadata.agentcore_registry_id equals the given registry_id.\n\n Args:\n registry_id: The AWS registry ARN to match\n\n Returns:\n Dict with deregistered servers, agents, skills lists and counts\n \"\"\"\n servers = await _deregister_servers_from_registry(registry_id)\n agents = await _deregister_agents_from_registry(registry_id)\n skills = await _deregister_skills_from_registry(registry_id)\n\n return {\n \"servers\": servers,\n \"servers_count\": len(servers),\n \"agents\": agents,\n \"agents_count\": len(agents),\n \"skills\": skills,\n \"skills_count\": len(skills),\n }\n\n\nasync def _deregister_servers_from_registry(\n registry_id: str,\n) -> list[str]:\n \"\"\"\n Remove all servers synced from a specific AWS registry.\n\n Args:\n registry_id: The AWS registry ARN to match\n\n Returns:\n List of server paths that were deregistered\n \"\"\"\n from ..repositories.factory import get_server_repository\n from ..services.server_service import server_service\n\n server_repo = get_server_repository()\n all_agentcore_servers = await server_repo.list_by_source(\"agentcore\")\n\n deregistered = []\n for path, server_info in all_agentcore_servers.items():\n metadata = server_info.get(\"metadata\", {})\n if metadata.get(\"agentcore_registry_id\") == registry_id:\n try:\n removed = await server_service.remove_server(path)\n if removed:\n deregistered.append(path)\n logger.info(f\"Deregistered server {path} from registry {registry_id}\")\n except Exception as e:\n logger.error(f\"Failed to deregister server {path}: {e}\")\n\n logger.info(f\"Deregistered {len(deregistered)} server(s) from registry {registry_id}\")\n return deregistered\n\n\nasync def _deregister_agents_from_registry(\n registry_id: str,\n) -> list[str]:\n \"\"\"\n Remove all agents synced from a specific AWS registry.\n\n Matches agents by:\n 1. metadata.agentcore_registry_id (primary)\n 2. 'agentcore' tag + path starting with /agents/agentcore- (fallback for older records)\n\n Args:\n registry_id: The AWS registry ARN to match\n\n Returns:\n List of agent paths that were deregistered\n \"\"\"\n from ..repositories.factory import get_agent_repository\n from ..services.agent_service import agent_service\n\n agent_repo = get_agent_repository()\n\n # Primary: query by metadata\n matching_paths = set()\n by_metadata = await agent_repo.find_with_filter({\"metadata.agentcore_registry_id\": registry_id})\n matching_paths.update(by_metadata.keys())\n\n # Fallback: query by tag + path pattern for older records without metadata\n by_tag = await agent_repo.find_with_filter(\n {\"tags\": \"agentcore\", \"_id\": {\"$regex\": \"^/agents/agentcore-\"}}\n )\n matching_paths.update(by_tag.keys())\n\n deregistered = []\n for path in matching_paths:\n try:\n removed = await agent_service.remove_agent(path)\n if removed:\n deregistered.append(path)\n logger.info(f\"Deregistered agent {path} from registry {registry_id}\")\n except Exception as e:\n logger.error(f\"Failed to deregister agent {path}: {e}\")\n\n logger.info(f\"Deregistered {len(deregistered)} agent(s) from registry {registry_id}\")\n return deregistered\n\n\nasync def _deregister_skills_from_registry(\n registry_id: str,\n) -> list[str]:\n \"\"\"\n Remove all skills synced from a specific AWS registry.\n\n Matches skills by:\n 1. metadata.agentcore_registry_id (newer skills)\n 2. 'agentcore' tag + path starting with /skills/agentcore- (older skills without metadata)\n\n Args:\n registry_id: The AWS registry ARN to match\n\n Returns:\n List of skill paths that were deregistered\n \"\"\"\n from ..repositories.factory import get_skill_repository\n\n skill_repo = get_skill_repository()\n all_skills = await skill_repo.list_all()\n\n matching_paths = set()\n for skill in all_skills:\n meta = skill.metadata or {}\n extra = meta.extra if hasattr(meta, \"extra\") else {}\n meta_dict = meta if isinstance(meta, dict) else {}\n\n # Match by metadata.agentcore_registry_id\n if meta_dict.get(\"agentcore_registry_id\") == registry_id:\n matching_paths.add(skill.path)\n continue\n if extra.get(\"agentcore_registry_id\") == registry_id:\n matching_paths.add(skill.path)\n continue\n\n # Fallback: match by 'agentcore' tag + path pattern\n tags = skill.tags or []\n if \"agentcore\" in tags and str(skill.path).startswith(\"/skills/agentcore-\"):\n matching_paths.add(skill.path)\n\n deregistered = []\n for path in matching_paths:\n try:\n removed = await skill_repo.delete(path)\n if removed:\n deregistered.append(path)\n logger.info(f\"Deregistered skill {path} from registry {registry_id}\")\n except Exception as e:\n logger.error(f\"Failed to deregister skill {path}: {e}\")\n\n logger.info(f\"Deregistered {len(deregistered)} skill(s) from registry {registry_id}\")\n return deregistered\n\n\n@router.post(\"/federation/sync\", tags=[\"federation\"], summary=\"Trigger manual federation sync\")\nasync def sync_federation(\n request: Request,\n config_id: str = \"default\",\n source: str | None = None,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n repo: FederationConfigRepositoryBase = Depends(_get_federation_repo),\n) -> dict[str, Any]:\n \"\"\"\n Manually trigger federation sync to import servers/agents from configured sources.\n\n Args:\n config_id: Configuration ID to use for sync (default: \"default\")\n source: Optional source filter (\"anthropic\", \"asor\", or \"aws_registry\"). If None, syncs all enabled sources.\n user_context: Authenticated user context\n repo: Federation config repository\n\n Returns:\n Sync results with counts of synced items\n\n Example:\n Sync all enabled federations:\n ```bash\n POST /api/federation/sync\n ```\n\n Sync only Anthropic:\n ```bash\n POST /api/federation/sync?source=anthropic\n ```\n \"\"\"\n # Set audit action for federation sync\n set_audit_action(\n request,\n \"sync\",\n \"federation\",\n resource_id=config_id,\n description=f\"Sync federation from {source or 'all sources'}\",\n )\n\n logger.info(f\"User {user_context['username']} triggering federation sync: {config_id}\")\n\n # Get federation config\n config = await repo.get_config(config_id)\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Federation config '{config_id}' not found\",\n )\n\n try:\n # Import federation clients\n from ..services.federation.anthropic_client import AnthropicFederationClient\n from ..services.federation.asor_client import AsorFederationClient\n\n results: dict[str, Any] = {\n \"anthropic\": {\"servers\": [], \"count\": 0},\n \"asor\": {\"agents\": [], \"count\": 0},\n \"aws_registry\": {\"servers\": [], \"agents\": [], \"skills\": [], \"count\": 0},\n }\n\n # Sync Anthropic servers if enabled and requested\n if (source is None or source == \"anthropic\") and config.anthropic.enabled:\n logger.info(\"Syncing servers from Anthropic MCP Registry...\")\n\n anthropic_client = AnthropicFederationClient(endpoint=config.anthropic.endpoint)\n\n servers = anthropic_client.fetch_all_servers(config.anthropic.servers)\n\n # Register servers via server service\n from ..services.server_service import server_service\n\n for server_data in servers:\n try:\n server_path = server_data.get(\"path\")\n if not server_path:\n logger.warning(\n f\"Server missing path: {server_data.get('server_name')}, skipping\"\n )\n continue\n\n # Ensure UUID id field exists for federation sync\n if \"id\" not in server_data or not server_data[\"id\"]:\n server_data[\"id\"] = str(uuid4())\n\n # Register server\n # server_data already includes the \"path\" field\n result = await server_service.register_server(server_data)\n success = result[\"success\"]\n\n if not success and not result.get(\"is_new_version\"):\n logger.warning(\n f\"Server already exists or failed to register: {server_path}\"\n )\n # Ensure UUID exists before updating (for servers registered before UUID feature)\n if \"id\" not in server_data or not server_data[\"id\"]:\n server_data[\"id\"] = str(uuid4())\n # Try updating instead\n success = await server_service.update_server(server_path, server_data)\n\n if success:\n # Enable the server\n await server_service.toggle_service(server_path, True)\n\n server_name = server_data.get(\"server_name\", server_path)\n logger.info(f\"Synced Anthropic server: {server_name} at {server_path}\")\n results[\"anthropic\"][\"servers\"].append(server_name)\n else:\n logger.error(f\"Failed to register or update server: {server_path}\")\n\n except Exception as e:\n logger.error(\n f\"Failed to sync Anthropic server {server_data.get('server_name', 'unknown')}: {e}\"\n )\n\n results[\"anthropic\"][\"count\"] = len(results[\"anthropic\"][\"servers\"])\n logger.info(f\"Synced {results['anthropic']['count']} servers from Anthropic\")\n\n # Sync ASOR agents if enabled and requested\n if (source is None or source == \"asor\") and config.asor.enabled:\n logger.info(\"Syncing agents from ASOR...\")\n\n tenant_url = (\n config.asor.endpoint.split(\"/api\")[0]\n if \"/api\" in config.asor.endpoint\n else config.asor.endpoint\n )\n\n asor_client = AsorFederationClient(\n endpoint=config.asor.endpoint,\n auth_env_var=config.asor.auth_env_var,\n tenant_url=tenant_url,\n )\n\n agents = asor_client.fetch_all_agents(config.asor.agents)\n\n # Register agents\n from datetime import datetime\n\n from ..schemas.agent_models import AgentCard\n from ..services.agent_service import agent_service\n\n for agent_data in agents:\n try:\n agent_name = agent_data.get(\"name\", \"Unknown ASOR Agent\")\n agent_path = f\"/{agent_name.lower().replace('_', '-')}\"\n\n # Extract skills\n skills_data = agent_data.get(\"skills\", [])\n skills = []\n for skill in skills_data:\n skills.append(\n {\n \"name\": skill.get(\"name\", \"\"),\n \"description\": skill.get(\"description\", \"\"),\n \"id\": skill.get(\"id\", \"\"),\n }\n )\n\n agent_card = AgentCard(\n protocol_version=\"1.0\",\n name=agent_name,\n path=agent_path,\n url=agent_data.get(\"url\", \"\"),\n description=agent_data.get(\"description\", f\"ASOR agent: {agent_name}\"),\n version=agent_data.get(\"version\", \"1.0.0\"),\n provider=\"ASOR\",\n author=\"ASOR\",\n license=\"Unknown\",\n skills=skills,\n tags=[\"asor\", \"federated\", \"workday\"],\n visibility=\"public\",\n registered_by=\"asor-federation\",\n registered_at=datetime.now(UTC),\n )\n\n if await agent_service.get_agent_info(agent_path) is None:\n await agent_service.register_agent(agent_card)\n logger.info(f\"Synced ASOR agent: {agent_name}\")\n results[\"asor\"][\"agents\"].append(agent_name)\n\n except Exception as e:\n logger.error(\n f\"Failed to sync ASOR agent {agent_data.get('name', 'unknown')}: {e}\"\n )\n\n results[\"asor\"][\"count\"] = len(results[\"asor\"][\"agents\"])\n logger.info(f\"Synced {results['asor']['count']} agents from ASOR\")\n\n # Sync AgentCore records if enabled and requested\n if (source is None or source == \"aws_registry\") and config.aws_registry.enabled:\n logger.info(\"Syncing from AWS Agent Registry...\")\n\n from ..repositories.factory import (\n get_skill_repository,\n )\n from ..schemas.agent_models import AgentCard\n from ..schemas.skill_models import SkillCard\n from ..services.agent_service import agent_service\n from ..services.federation.agentcore_client import AgentCoreFederationClient\n from ..services.server_service import server_service\n from ..services.skill_service import get_skill_service\n\n agentcore_client = AgentCoreFederationClient(aws_region=config.aws_registry.aws_region)\n records = agentcore_client.fetch_all_records(\n registry_configs=config.aws_registry.registries,\n sync_timeout_seconds=config.aws_registry.sync_timeout_seconds,\n max_concurrent_fetches=config.aws_registry.max_concurrent_fetches,\n )\n\n # Register servers (MCP records)\n for srv in records[\"servers\"]:\n try:\n srv_path = srv.get(\"path\")\n if not srv_path:\n continue\n if \"id\" not in srv or not srv[\"id\"]:\n srv[\"id\"] = str(uuid4())\n\n result = await server_service.register_server(srv)\n if not result[\"success\"]:\n if \"id\" not in srv or not srv[\"id\"]:\n srv[\"id\"] = str(uuid4())\n await server_service.update_server(srv_path, srv)\n\n await server_service.toggle_service(srv_path, True)\n results[\"aws_registry\"][\"servers\"].append(srv.get(\"server_name\", srv_path))\n except Exception as e:\n logger.error(\n f\"Failed to sync AgentCore server {srv.get('server_name', 'unknown')}: {e}\"\n )\n\n # Register agents (A2A + CUSTOM records)\n for agent_data in records[\"agents\"]:\n try:\n agent_path = agent_data.get(\"path\")\n if not agent_path:\n continue\n try:\n agent_card = AgentCard(**agent_data)\n await agent_service.register_agent(agent_card)\n except ValueError:\n await agent_service.update_agent(agent_path, agent_data)\n results[\"aws_registry\"][\"agents\"].append(agent_data.get(\"name\", agent_path))\n except Exception as e:\n logger.error(\n f\"Failed to sync AgentCore agent {agent_data.get('name', 'unknown')}: {e}\"\n )\n\n # Register skills (AGENT_SKILLS records)\n skill_service = get_skill_service()\n skill_repo = get_skill_repository()\n for skill_data in records[\"skills\"]:\n try:\n skill_path = skill_data.get(\"path\")\n if not skill_path:\n continue\n try:\n skill_card = SkillCard(**skill_data)\n await skill_repo.create(skill_card)\n except Exception as create_err:\n logger.debug(\n f\"Skill create failed for {skill_path}, trying update: {create_err}\"\n )\n update_fields = {\n k: v\n for k, v in skill_data.items()\n if k not in (\"path\", \"id\", \"created_at\")\n }\n await skill_repo.update(skill_path, update_fields)\n results[\"aws_registry\"][\"skills\"].append(skill_data.get(\"name\", skill_path))\n except Exception as e:\n logger.error(\n f\"Failed to sync AgentCore skill {skill_data.get('name', 'unknown')}: {e}\"\n )\n\n agentcore_total = (\n len(results[\"aws_registry\"][\"servers\"])\n + len(results[\"aws_registry\"][\"agents\"])\n + len(results[\"aws_registry\"][\"skills\"])\n )\n results[\"aws_registry\"][\"count\"] = agentcore_total\n logger.info(\n f\"Synced from AWS Agent Registry: \"\n f\"{len(results['aws_registry']['servers'])} servers, \"\n f\"{len(results['aws_registry']['agents'])} agents, \"\n f\"{len(results['aws_registry']['skills'])} skills\"\n )\n\n # Reconcile: remove stale federated servers after sync\n reconciliation_result = None\n try:\n from ..core.nginx_service import nginx_service as nginx_svc\n from ..repositories.factory import get_server_repository\n from ..services.federation_reconciliation import reconcile_anthropic_servers\n\n server_repo = get_server_repository()\n reconciliation_result = await reconcile_anthropic_servers(\n config=config,\n server_service=server_service,\n server_repo=server_repo,\n nginx_service=nginx_svc,\n audit_username=user_context.get(\"username\"),\n )\n if reconciliation_result.get(\"removed\"):\n logger.info(\n f\"Reconciliation removed {reconciliation_result['removed_count']} stale servers: \"\n f\"{reconciliation_result['removed']}\"\n )\n except Exception as reconcile_error:\n logger.warning(f\"Reconciliation failed after sync: {reconcile_error}\")\n\n return {\n \"message\": \"Federation sync completed\",\n \"config_id\": config_id,\n \"results\": results,\n \"total_synced\": (\n results[\"anthropic\"][\"count\"]\n + results[\"asor\"][\"count\"]\n + results[\"aws_registry\"][\"count\"]\n ),\n \"reconciliation\": reconciliation_result,\n }\n\n except Exception as e:\n logger.error(f\"Federation sync failed: {e}\", exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Federation sync failed\",\n )\n" }, { "path": "registry/api/internal_routes.py", "content": "\"\"\"\nInternal API routes for virtual MCP server session management.\n\nThese endpoints are called by the Lua router via ngx.location.capture\nand are protected by nginx 'internal' directive -- they are NOT accessible\nfrom external clients.\n\"\"\"\n\nimport logging\nimport uuid\n\nfrom fastapi import APIRouter, HTTPException\n\nfrom registry.repositories.factory import get_backend_session_repository\nfrom registry.schemas.backend_session_models import (\n CreateClientSessionRequest,\n CreateClientSessionResponse,\n GetBackendSessionResponse,\n StoreSessionRequest,\n)\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n\ndef _get_repo():\n \"\"\"Get backend session repository or raise 503.\"\"\"\n repo = get_backend_session_repository()\n if repo is None:\n raise HTTPException(\n status_code=503,\n detail=\"Backend session repository not available\",\n )\n return repo\n\n\n@router.post(\n \"/internal/sessions/client\",\n response_model=CreateClientSessionResponse,\n status_code=201,\n)\nasync def create_client_session(\n request: CreateClientSessionRequest,\n):\n \"\"\"Create a new client session and return the generated session ID.\n\n Called by Lua router on MCP 'initialize' requests.\n Generates a vs- client session ID, stores it in MongoDB,\n and returns it to be set as the Mcp-Session-Id response header.\n \"\"\"\n repo = _get_repo()\n\n client_session_id = f\"vs-{uuid.uuid4().hex}\"\n\n await repo.create_client_session(\n client_session_id=client_session_id,\n user_id=request.user_id,\n virtual_server_path=request.virtual_server_path,\n )\n\n logger.info(\n f\"Created client session {client_session_id} \"\n f\"for user={request.user_id} path={request.virtual_server_path}\"\n )\n\n return CreateClientSessionResponse(client_session_id=client_session_id)\n\n\n@router.get(\n \"/internal/sessions/client/{client_session_id}\",\n status_code=200,\n)\nasync def validate_client_session(\n client_session_id: str,\n):\n \"\"\"Validate that a client session exists.\n\n Returns 200 if valid, 404 if not found or expired.\n Also bumps last_used_at to keep the session alive.\n \"\"\"\n repo = _get_repo()\n\n is_valid = await repo.validate_client_session(client_session_id)\n if not is_valid:\n raise HTTPException(status_code=404, detail=\"Client session not found\")\n\n return {\"status\": \"valid\"}\n\n\n@router.get(\n \"/internal/sessions/backend/{session_key:path}\",\n response_model=GetBackendSessionResponse,\n)\nasync def get_backend_session(\n session_key: str,\n):\n \"\"\"Look up a backend session by compound key.\n\n The session_key is ':'.\n Returns the backend_session_id if found, 404 otherwise.\n Also bumps last_used_at atomically.\n \"\"\"\n repo = _get_repo()\n\n # Split compound key at first ':'\n parts = session_key.split(\":\", 1)\n if len(parts) != 2:\n raise HTTPException(\n status_code=400,\n detail=\"Invalid session key format. Expected ':'\",\n )\n\n client_session_id, backend_key = parts\n\n backend_session_id = await repo.get_backend_session(\n client_session_id=client_session_id,\n backend_key=backend_key,\n )\n\n if backend_session_id is None:\n raise HTTPException(status_code=404, detail=\"Backend session not found\")\n\n return GetBackendSessionResponse(backend_session_id=backend_session_id)\n\n\n@router.put(\n \"/internal/sessions/backend/{session_key:path}\",\n status_code=200,\n)\nasync def store_backend_session(\n session_key: str,\n request: StoreSessionRequest,\n):\n \"\"\"Store or update a backend session.\n\n The session_key is ':'.\n Upserts the session document in MongoDB.\n \"\"\"\n repo = _get_repo()\n\n # Split compound key at first ':'\n parts = session_key.split(\":\", 1)\n if len(parts) != 2:\n raise HTTPException(\n status_code=400,\n detail=\"Invalid session key format. Expected ':'\",\n )\n\n client_session_id, backend_key = parts\n\n await repo.store_backend_session(\n client_session_id=client_session_id,\n backend_key=backend_key,\n backend_session_id=request.backend_session_id,\n user_id=request.user_id,\n virtual_server_path=request.virtual_server_path,\n )\n\n return {\"status\": \"stored\"}\n\n\n@router.delete(\n \"/internal/sessions/backend/{session_key:path}\",\n status_code=200,\n)\nasync def delete_backend_session(\n session_key: str,\n):\n \"\"\"Delete a stale backend session.\n\n Called by Lua router when a backend rejects a cached session ID\n (e.g., after backend restart). The router will then re-initialize.\n \"\"\"\n repo = _get_repo()\n\n # Split compound key at first ':'\n parts = session_key.split(\":\", 1)\n if len(parts) != 2:\n raise HTTPException(\n status_code=400,\n detail=\"Invalid session key format. Expected ':'\",\n )\n\n client_session_id, backend_key = parts\n\n await repo.delete_backend_session(\n client_session_id=client_session_id,\n backend_key=backend_key,\n )\n\n return {\"status\": \"deleted\"}\n" }, { "path": "registry/api/log_routes.py", "content": "\"\"\"Admin API routes for querying centralized application logs.\n\nAll endpoints require admin access.\n\"\"\"\n\nimport json\nimport logging\nimport re\nimport time\nfrom datetime import UTC, datetime\nfrom typing import Annotated, Any\n\nfrom fastapi import APIRouter, Depends, HTTPException, Query, status\nfrom fastapi.responses import StreamingResponse\nfrom pydantic import BaseModel, Field\n\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..repositories.app_log_repository import AppLogRepository\nfrom ..repositories.factory import get_app_log_repository\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/admin/logs\", tags=[\"Application Logs\"])\n\nLEVEL_MAP = {\n \"DEBUG\": 10,\n \"INFO\": 20,\n \"WARNING\": 30,\n \"ERROR\": 40,\n \"CRITICAL\": 50,\n}\n\nRATE_LIMIT_WINDOW_SECONDS = 60\nRATE_LIMIT_MAX_REQUESTS = 10\n_rate_limit_cache: dict[str, list[float]] = {}\nMAX_SEARCH_LENGTH = 200\n\n\ndef _check_rate_limit(user_id: str) -> bool:\n \"\"\"Allow up to RATE_LIMIT_MAX_REQUESTS per user per window.\"\"\"\n now = time.time()\n window_start = now - RATE_LIMIT_WINDOW_SECONDS\n\n if user_id not in _rate_limit_cache:\n _rate_limit_cache[user_id] = []\n\n _rate_limit_cache[user_id] = [t for t in _rate_limit_cache[user_id] if t > window_start]\n\n if len(_rate_limit_cache[user_id]) >= RATE_LIMIT_MAX_REQUESTS:\n return False\n\n _rate_limit_cache[user_id].append(now)\n return True\n\n\ndef _sanitize_search(search: str | None) -> str | None:\n \"\"\"Escape regex metacharacters for safe MongoDB $regex use.\"\"\"\n if not search:\n return None\n return re.escape(search[:MAX_SEARCH_LENGTH])\n\n\ndef _require_admin(\n user_context: dict[str, Any] = Depends(nginx_proxied_auth),\n) -> dict[str, Any]:\n \"\"\"Dependency that requires admin access.\"\"\"\n if not user_context.get(\"is_admin\", False):\n logger.warning(\n f\"Non-admin user '{user_context.get('username', 'unknown')}' \"\n \"attempted to access application logs API\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Admin access required\",\n )\n return user_context\n\n\ndef _get_repo() -> AppLogRepository:\n \"\"\"Get the application log repository or raise 503.\"\"\"\n repo = get_app_log_repository()\n if repo is None:\n raise HTTPException(\n status_code=status.HTTP_503_SERVICE_UNAVAILABLE,\n detail=\"Application log storage not available (requires MongoDB backend)\",\n )\n return repo\n\n\nclass LogEntry(BaseModel):\n \"\"\"Single application log entry.\"\"\"\n\n timestamp: datetime\n hostname: str\n service: str\n level: str\n level_no: int = 0\n logger: str = \"\"\n filename: str = \"\"\n lineno: int = 0\n process: int = 0\n message: str = \"\"\n\n\nclass LogQueryResponse(BaseModel):\n \"\"\"Paginated response for log queries.\"\"\"\n\n entries: list[LogEntry]\n total_count: int\n limit: int\n offset: int\n has_next: bool\n\n\nclass LogMetadataResponse(BaseModel):\n \"\"\"Available filter values for log queries.\"\"\"\n\n services: list[str] = Field(default_factory=list)\n hostnames: list[str] = Field(default_factory=list)\n levels: list[str] = Field(\n default_factory=lambda: [\"DEBUG\", \"INFO\", \"WARNING\", \"ERROR\", \"CRITICAL\"]\n )\n\n\n@router.get(\n \"\",\n response_model=LogQueryResponse,\n summary=\"Query application logs\",\n description=\"Query centralized application logs with filtering, pagination, and time range support.\",\n)\nasync def query_logs(\n user_context: Annotated[dict, Depends(_require_admin)],\n service: Annotated[str | None, Query(description=\"Filter by service name\")] = None,\n level: Annotated[\n str | None, Query(description=\"Minimum log level: DEBUG, INFO, WARNING, ERROR, CRITICAL\")\n ] = None,\n hostname: Annotated[str | None, Query(description=\"Filter by pod/hostname\")] = None,\n start: Annotated[datetime | None, Query(description=\"Start of time range (ISO 8601)\")] = None,\n end: Annotated[datetime | None, Query(description=\"End of time range (ISO 8601)\")] = None,\n search: Annotated[\n str | None, Query(description=\"Substring search in message (max 200 chars)\")\n ] = None,\n limit: Annotated[int, Query(ge=1, le=10000, description=\"Max entries to return\")] = 100,\n offset: Annotated[int, Query(ge=0, description=\"Number of entries to skip\")] = 0,\n) -> LogQueryResponse:\n username = user_context.get(\"username\", \"unknown\")\n if not _check_rate_limit(username):\n raise HTTPException(\n status_code=status.HTTP_429_TOO_MANY_REQUESTS,\n detail=\"Rate limit exceeded\",\n )\n\n repo = _get_repo()\n\n level_no = LEVEL_MAP.get(level.upper()) if level else None\n sanitized_search = _sanitize_search(search)\n\n entries, total = await repo.query(\n service=service,\n level_no=level_no,\n hostname=hostname,\n start=start,\n end=end,\n search=sanitized_search,\n skip=offset,\n limit=limit,\n )\n\n return LogQueryResponse(\n entries=[LogEntry(**e) for e in entries],\n total_count=total,\n limit=limit,\n offset=offset,\n has_next=(offset + limit) < total,\n )\n\n\n@router.get(\n \"/export\",\n summary=\"Export application logs as JSONL\",\n description=\"Stream application logs as newline-delimited JSON for download.\",\n response_class=StreamingResponse,\n)\nasync def export_logs(\n user_context: Annotated[dict, Depends(_require_admin)],\n service: Annotated[str | None, Query(description=\"Filter by service name\")] = None,\n level: Annotated[str | None, Query(description=\"Minimum log level\")] = None,\n hostname: Annotated[str | None, Query(description=\"Filter by pod/hostname\")] = None,\n start: Annotated[datetime | None, Query(description=\"Start of time range (ISO 8601)\")] = None,\n end: Annotated[datetime | None, Query(description=\"End of time range (ISO 8601)\")] = None,\n search: Annotated[\n str | None, Query(description=\"Substring search in message (max 200 chars)\")\n ] = None,\n limit: Annotated[int, Query(ge=1, le=50000, description=\"Max entries to export\")] = 10000,\n) -> StreamingResponse:\n username = user_context.get(\"username\", \"unknown\")\n if not _check_rate_limit(username):\n raise HTTPException(\n status_code=status.HTTP_429_TOO_MANY_REQUESTS,\n detail=\"Rate limit exceeded\",\n )\n\n repo = _get_repo()\n\n level_no = LEVEL_MAP.get(level.upper()) if level else None\n sanitized_search = _sanitize_search(search)\n\n entries, _ = await repo.query(\n service=service,\n level_no=level_no,\n hostname=hostname,\n start=start,\n end=end,\n search=sanitized_search,\n skip=0,\n limit=limit,\n )\n\n def _generate():\n for entry in entries:\n if \"timestamp\" in entry and hasattr(entry[\"timestamp\"], \"isoformat\"):\n entry[\"timestamp\"] = entry[\"timestamp\"].isoformat()\n yield json.dumps(entry, default=str) + \"\\n\"\n\n svc_label = service or \"all\"\n ts = datetime.now(UTC).strftime(\"%Y%m%d-%H%M%S\")\n filename = f\"logs-{svc_label}-{ts}.jsonl\"\n\n return StreamingResponse(\n _generate(),\n media_type=\"application/x-ndjson\",\n headers={\n \"Content-Disposition\": f'attachment; filename=\"{filename}\"',\n },\n )\n\n\n@router.get(\n \"/metadata\",\n response_model=LogMetadataResponse,\n summary=\"Get log filter metadata\",\n description=\"Returns available service names, hostnames, and log levels for building filter UIs.\",\n)\nasync def get_log_metadata(\n user_context: Annotated[dict, Depends(_require_admin)],\n) -> LogMetadataResponse:\n repo = _get_repo()\n\n services = await repo.get_distinct_services()\n hostnames = await repo.get_distinct_hostnames()\n\n return LogMetadataResponse(\n services=services,\n hostnames=hostnames,\n )\n" }, { "path": "registry/api/m2m_management_routes.py", "content": "\"\"\"Direct CRUD endpoints for M2M client registration.\n\nThese endpoints write directly to the ``idp_m2m_clients`` MongoDB collection\nwithout calling any IdP Admin API. Operators without ``OKTA_API_TOKEN`` (or\nequivalent) can register M2M ``client_id`` values and their group mappings so\nthe auth server can enrich M2M tokens during authorization.\n\nTracked by issue #851.\n\"\"\"\n\nimport logging\nfrom typing import Annotated\n\nfrom fastapi import APIRouter, Depends, HTTPException, Query, Request, status\nfrom prometheus_client import Counter\n\nfrom registry.audit.context import set_audit_action\nfrom registry.auth.dependencies import nginx_proxied_auth\nfrom registry.repositories.documentdb.client import get_documentdb_client\nfrom registry.schemas.idp_m2m_client import (\n IdPM2MClient,\n IdPM2MClientCreate,\n IdPM2MClientPatch,\n M2MClientListResponse,\n)\nfrom registry.services.m2m_management_service import (\n M2MClientConflict,\n M2MClientImmutable,\n M2MClientNotFound,\n M2MManagementService,\n)\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n_RESOURCE_TYPE: str = \"m2m_client\"\n_LIST_DEFAULT_LIMIT: int = 500\n_LIST_MAX_LIMIT: int = 1000\n\n\nm2m_management_requests_total = Counter(\n \"m2m_management_requests_total\",\n \"Count of direct M2M client registration API calls\",\n [\"operation\", \"outcome\"],\n)\n\n\ndef _require_admin(\n user_context: dict | None,\n operation: str,\n) -> None:\n \"\"\"Enforce admin permission or raise 401/403 and increment metrics.\"\"\"\n if not user_context:\n m2m_management_requests_total.labels(operation=operation, outcome=\"auth_error\").inc()\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n if not user_context.get(\"is_admin\"):\n m2m_management_requests_total.labels(operation=operation, outcome=\"forbidden\").inc()\n raise HTTPException(status_code=403, detail=\"Administrator permissions are required\")\n\n\nasync def _get_service() -> M2MManagementService:\n db = await get_documentdb_client()\n return M2MManagementService(db)\n\n\n@router.post(\n \"/iam/m2m-clients\",\n response_model=IdPM2MClient,\n status_code=status.HTTP_201_CREATED,\n)\nasync def create_m2m_client(\n payload: IdPM2MClientCreate,\n request: Request,\n user_context: Annotated[dict | None, Depends(nginx_proxied_auth)] = None,\n) -> IdPM2MClient:\n \"\"\"Register a new M2M client with its group mappings (admin only).\"\"\"\n _require_admin(user_context, operation=\"create\")\n service = await _get_service()\n created_by = user_context.get(\"username\") if user_context else None\n try:\n result = await service.create(payload, created_by=created_by)\n except M2MClientConflict:\n m2m_management_requests_total.labels(operation=\"create\", outcome=\"conflict\").inc()\n raise HTTPException(\n status_code=status.HTTP_409_CONFLICT,\n detail=f\"M2M client {payload.client_id} already exists\",\n )\n set_audit_action(\n request,\n \"create\",\n _RESOURCE_TYPE,\n resource_id=payload.client_id,\n description=f\"Created M2M client {payload.client_name}\",\n )\n m2m_management_requests_total.labels(operation=\"create\", outcome=\"success\").inc()\n return result\n\n\n@router.get(\"/iam/m2m-clients\", response_model=M2MClientListResponse)\nasync def list_m2m_clients(\n provider: str | None = None,\n limit: int = Query(default=_LIST_DEFAULT_LIMIT, ge=1, le=_LIST_MAX_LIMIT),\n skip: int = Query(default=0, ge=0),\n user_context: Annotated[dict | None, Depends(nginx_proxied_auth)] = None,\n) -> M2MClientListResponse:\n \"\"\"List M2M clients (any authenticated user).\"\"\"\n if not user_context:\n m2m_management_requests_total.labels(operation=\"list\", outcome=\"auth_error\").inc()\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n service = await _get_service()\n items, total = await service.list_paged(provider=provider, limit=limit, skip=skip)\n m2m_management_requests_total.labels(operation=\"list\", outcome=\"success\").inc()\n return M2MClientListResponse(total=total, limit=limit, skip=skip, items=items)\n\n\n@router.get(\"/iam/m2m-clients/{client_id}\", response_model=IdPM2MClient)\nasync def get_m2m_client(\n client_id: str,\n user_context: Annotated[dict | None, Depends(nginx_proxied_auth)] = None,\n) -> IdPM2MClient:\n \"\"\"Get a specific M2M client (any authenticated user).\"\"\"\n if not user_context:\n m2m_management_requests_total.labels(operation=\"get\", outcome=\"auth_error\").inc()\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n service = await _get_service()\n try:\n result = await service.get(client_id)\n except M2MClientNotFound:\n m2m_management_requests_total.labels(operation=\"get\", outcome=\"not_found\").inc()\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"M2M client {client_id} not found\",\n )\n m2m_management_requests_total.labels(operation=\"get\", outcome=\"success\").inc()\n return result\n\n\n@router.patch(\"/iam/m2m-clients/{client_id}\", response_model=IdPM2MClient)\nasync def patch_m2m_client(\n client_id: str,\n payload: IdPM2MClientPatch,\n request: Request,\n user_context: Annotated[dict | None, Depends(nginx_proxied_auth)] = None,\n) -> IdPM2MClient:\n \"\"\"Update fields of an existing manual M2M client (admin only).\"\"\"\n _require_admin(user_context, operation=\"patch\")\n service = await _get_service()\n try:\n result = await service.patch(client_id, payload)\n except M2MClientNotFound:\n m2m_management_requests_total.labels(operation=\"patch\", outcome=\"not_found\").inc()\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"M2M client {client_id} not found\",\n )\n except M2MClientImmutable:\n m2m_management_requests_total.labels(operation=\"patch\", outcome=\"forbidden\").inc()\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=(\n f\"M2M client {client_id} was registered by IdP sync and \"\n \"cannot be modified via this API\"\n ),\n )\n set_audit_action(\n request,\n \"update\",\n _RESOURCE_TYPE,\n resource_id=client_id,\n description=f\"Updated M2M client {client_id}\",\n )\n m2m_management_requests_total.labels(operation=\"patch\", outcome=\"success\").inc()\n return result\n\n\n@router.delete(\"/iam/m2m-clients/{client_id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_m2m_client(\n client_id: str,\n request: Request,\n user_context: Annotated[dict | None, Depends(nginx_proxied_auth)] = None,\n) -> None:\n \"\"\"Delete a manual M2M client (admin only).\"\"\"\n _require_admin(user_context, operation=\"delete\")\n service = await _get_service()\n try:\n await service.delete(client_id)\n except M2MClientNotFound:\n m2m_management_requests_total.labels(operation=\"delete\", outcome=\"not_found\").inc()\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"M2M client {client_id} not found\",\n )\n except M2MClientImmutable:\n m2m_management_requests_total.labels(operation=\"delete\", outcome=\"forbidden\").inc()\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=(\n f\"M2M client {client_id} was registered by IdP sync and \"\n \"cannot be deleted via this API\"\n ),\n )\n set_audit_action(\n request,\n \"delete\",\n _RESOURCE_TYPE,\n resource_id=client_id,\n description=f\"Deleted M2M client {client_id}\",\n )\n m2m_management_requests_total.labels(operation=\"delete\", outcome=\"success\").inc()\n" }, { "path": "registry/api/management_routes.py", "content": "from __future__ import annotations\n\nimport logging\nimport os\nfrom typing import Annotated\n\nfrom fastapi import APIRouter, Depends, HTTPException, status\n\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..schemas.management import (\n GroupCreateRequest,\n GroupDeleteResponse,\n GroupDetailResponse,\n GroupListResponse,\n GroupSummary,\n GroupUpdateRequest,\n HumanUserRequest,\n M2MAccountRequest,\n UpdateUserGroupsRequest,\n UpdateUserGroupsResponse,\n UserDeleteResponse,\n UserListResponse,\n UserSummary,\n)\nfrom ..services import scope_service\nfrom ..utils.iam_manager import get_iam_manager\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/management\", tags=[\"Management API\"])\n\nAUTH_PROVIDER: str = os.environ.get(\"AUTH_PROVIDER\", \"keycloak\")\n\n\ndef _translate_iam_error(exc: Exception) -> HTTPException:\n \"\"\"\n Map IAM admin errors to HTTP responses.\n\n Works for both Keycloak and Entra ID error messages.\n\n Args:\n exc: The exception from IAM operations\n\n Returns:\n HTTPException with appropriate status code\n \"\"\"\n detail = str(exc)\n lowered = detail.lower()\n status_code = status.HTTP_502_BAD_GATEWAY\n\n if any(keyword in lowered for keyword in (\"already exists\", \"not found\", \"provided\")):\n status_code = status.HTTP_400_BAD_REQUEST\n\n return HTTPException(status_code=status_code, detail=detail)\n\n\ndef _normalize_agent_path(path: str) -> str:\n \"\"\"\n Normalize agent path to ensure it has a leading slash.\n\n Args:\n path: Agent path to normalize\n\n Returns:\n Normalized path with leading slash\n \"\"\"\n if not path:\n return path\n path = path.strip()\n if not path.startswith(\"/\"):\n path = \"/\" + path\n if path.endswith(\"/\") and len(path) > 1:\n path = path.rstrip(\"/\")\n return path\n\n\ndef _normalize_agent_paths_in_scope_config(\n agent_access: list | None,\n ui_permissions: dict | None,\n) -> tuple[list | None, dict | None]:\n \"\"\"\n Normalize agent paths in agent_access and ui_permissions.\n\n Ensures all agent paths have leading slashes for consistent matching.\n\n Args:\n agent_access: List of agent paths\n ui_permissions: Dict of UI permissions\n\n Returns:\n Tuple of (normalized_agent_access, normalized_ui_permissions)\n \"\"\"\n # Normalize agent_access\n if agent_access:\n agent_access = [_normalize_agent_path(p) for p in agent_access if p]\n\n # Normalize agent-related ui_permissions\n if ui_permissions:\n for key in [\"list_agents\", \"get_agent\", \"publish_agent\", \"modify_agent\", \"delete_agent\"]:\n if key in ui_permissions and isinstance(ui_permissions[key], list):\n # Don't normalize \"all\" - it's a special value\n ui_permissions[key] = [\n p if p == \"all\" else _normalize_agent_path(p) for p in ui_permissions[key] if p\n ]\n\n return agent_access, ui_permissions\n\n\ndef _require_admin(user_context: dict) -> None:\n \"\"\"\n Verify user has admin permissions.\n\n Args:\n user_context: User context from authentication\n\n Raises:\n HTTPException: If user is not an admin\n \"\"\"\n if not user_context.get(\"is_admin\"):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Administrator permissions are required for this operation\",\n )\n\n\n@router.get(\"/iam/users\", response_model=UserListResponse)\nasync def management_list_users(\n search: str | None = None,\n limit: int = 500,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"List users from the configured identity provider (admin only).\"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n try:\n raw_users = await iam.list_users(search=search, max_results=limit)\n logger.debug(f\"[LIST_USERS] Retrieved {len(raw_users)} users from IAM\")\n except Exception as exc:\n logger.error(f\"[LIST_USERS] Exception calling list_users: {type(exc).__name__}: {exc}\")\n raise _translate_iam_error(exc) from exc\n\n # Include M2M clients from MongoDB for all providers\n try:\n from registry.repositories.documentdb.client import get_documentdb_client\n\n db = await get_documentdb_client()\n collection = db[\"idp_m2m_clients\"]\n\n # Query M2M clients from MongoDB\n cursor = collection.find({})\n m2m_docs = await cursor.to_list(length=None)\n\n # Add M2M clients as users with special email pattern\n for doc in m2m_docs:\n client_id = doc.get(\"client_id\", \"\")\n raw_users.append(\n {\n \"id\": client_id,\n \"username\": doc.get(\"name\", client_id),\n \"email\": f\"{client_id}@service-account.local\", # Special email pattern for M2M\n \"firstName\": None,\n \"lastName\": None,\n \"enabled\": doc.get(\"enabled\", True),\n \"groups\": doc.get(\"groups\", []),\n }\n )\n\n logger.debug(f\"[LIST_USERS] Added {len(m2m_docs)} M2M clients from MongoDB\")\n except Exception as e:\n logger.warning(f\"Failed to retrieve M2M clients from MongoDB: {e}\")\n # Don't fail the entire operation if MongoDB query fails\n\n summaries = [\n UserSummary(\n id=user.get(\"id\", \"\"),\n username=user.get(\"username\", \"\"),\n email=user.get(\"email\"),\n firstName=user.get(\"firstName\"),\n lastName=user.get(\"lastName\"),\n enabled=user.get(\"enabled\", True),\n groups=user.get(\"groups\", []),\n )\n for user in raw_users\n ]\n return UserListResponse(users=summaries, total=len(summaries))\n\n\n@router.post(\"/iam/users/m2m\")\nasync def management_create_m2m_user(\n payload: M2MAccountRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Create a service account client and return its credentials (admin only).\"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n try:\n result = await iam.create_service_account(\n client_id=payload.name,\n groups=payload.groups,\n description=payload.description,\n )\n\n # Store M2M client in MongoDB for all providers (authorization database)\n try:\n from datetime import datetime\n from os import environ\n\n from registry.repositories.documentdb.client import get_documentdb_client\n\n db = await get_documentdb_client()\n collection = db[\"idp_m2m_clients\"]\n\n provider = environ.get(\"AUTH_PROVIDER\", \"keycloak\").lower()\n\n client_doc = {\n \"client_id\": result.get(\"client_id\"),\n \"name\": payload.name,\n \"description\": payload.description,\n \"groups\": payload.groups,\n \"enabled\": True,\n \"provider\": provider,\n \"idp_app_id\": result.get(\"okta_app_id\") or result.get(\"client_id\"),\n \"created_at\": datetime.utcnow(),\n \"updated_at\": datetime.utcnow(),\n }\n\n await collection.insert_one(client_doc)\n client_id_val = result.get(\"client_id\", \"\")\n masked_client_id = f\"{client_id_val[:8]}...\" if client_id_val else \"\"\n logger.info(f\"Stored M2M client in MongoDB: {masked_client_id} (provider: {provider})\")\n except Exception as e:\n logger.warning(f\"Failed to store M2M client in MongoDB: {e}\")\n # Don't fail the entire operation if MongoDB storage fails\n\n except Exception as exc:\n raise _translate_iam_error(exc) from exc\n\n return result\n\n\n@router.post(\"/iam/users/human\")\nasync def management_create_human_user(\n payload: HumanUserRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Create a human user and assign groups (admin only).\"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n try:\n user_doc = await iam.create_human_user(\n username=payload.username,\n email=payload.email,\n first_name=payload.first_name,\n last_name=payload.last_name,\n groups=payload.groups,\n password=payload.password,\n )\n except Exception as exc:\n raise _translate_iam_error(exc) from exc\n\n return UserSummary(\n id=user_doc.get(\"id\", \"\"),\n username=user_doc.get(\"username\", payload.username),\n email=user_doc.get(\"email\"),\n firstName=user_doc.get(\"firstName\"),\n lastName=user_doc.get(\"lastName\"),\n enabled=user_doc.get(\"enabled\", True),\n groups=user_doc.get(\"groups\", payload.groups),\n )\n\n\n@router.delete(\"/iam/users/{username}\", response_model=UserDeleteResponse)\nasync def management_delete_user(\n username: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Delete a user by username (admin only).\"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n try:\n await iam.delete_user(username=username)\n except Exception as exc:\n raise _translate_iam_error(exc) from exc\n\n return UserDeleteResponse(username=username)\n\n\n@router.patch(\"/iam/users/{username}/groups\", response_model=UpdateUserGroupsResponse)\nasync def management_update_user_groups(\n username: str,\n payload: UpdateUserGroupsRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Update a user's group memberships (admin only).\n\n This endpoint calculates the diff between current and desired groups,\n then adds or removes group memberships as needed.\n\n For M2M accounts (service accounts), updates the DocumentDB record directly.\n For human users, delegates to the IdP manager.\n \"\"\"\n from datetime import datetime\n\n _require_admin(user_context)\n\n # Check if this is an M2M account by looking it up in DocumentDB\n try:\n from registry.repositories.documentdb.client import get_documentdb_client\n\n db = await get_documentdb_client()\n collection = db[\"idp_m2m_clients\"]\n\n # Try to find M2M client by name (username is the name for M2M accounts in the UI)\n m2m_doc = await collection.find_one({\"name\": username})\n\n if m2m_doc:\n # This is an M2M account - update DocumentDB directly\n logger.info(f\"Updating groups for M2M account: {username}\")\n\n current_groups = m2m_doc.get(\"groups\", [])\n new_groups = payload.groups\n\n added = list(set(new_groups) - set(current_groups))\n removed = list(set(current_groups) - set(new_groups))\n\n # Update the groups in DocumentDB\n await collection.update_one(\n {\"name\": username},\n {\n \"$set\": {\n \"groups\": new_groups,\n \"updated_at\": datetime.utcnow(),\n }\n },\n )\n\n logger.info(f\"Updated M2M account {username}: added {added}, removed {removed}\")\n\n return UpdateUserGroupsResponse(\n username=username,\n groups=new_groups,\n added=added,\n removed=removed,\n )\n except Exception as e:\n logger.warning(f\"Error checking/updating M2M account in DocumentDB: {e}\")\n # Continue to IdP update if DocumentDB check fails\n\n # If not an M2M account, update through IdP\n iam = get_iam_manager()\n\n try:\n result = await iam.update_user_groups(\n username=username,\n groups=payload.groups,\n )\n except Exception as exc:\n raise _translate_iam_error(exc) from exc\n\n return UpdateUserGroupsResponse(\n username=result.get(\"username\", username),\n groups=result.get(\"groups\", []),\n added=result.get(\"added\", []),\n removed=result.get(\"removed\", []),\n )\n\n\n@router.get(\"/iam/groups\", response_model=GroupListResponse)\nasync def management_list_groups(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"List IAM groups from the configured identity provider (admin only).\"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n try:\n raw_groups = await iam.list_groups()\n summaries = [\n GroupSummary(\n id=group.get(\"id\", \"\"),\n name=group.get(\"name\", \"\"),\n path=group.get(\"path\", \"\"),\n attributes=group.get(\"attributes\"),\n )\n for group in raw_groups\n ]\n return GroupListResponse(groups=summaries, total=len(summaries))\n except Exception as exc:\n logger.error(\"Failed to list IAM groups: %s\", exc)\n raise HTTPException(\n status_code=status.HTTP_502_BAD_GATEWAY,\n detail=\"Unable to list IAM groups\",\n ) from exc\n\n\n@router.post(\"/iam/groups\", response_model=GroupSummary)\nasync def management_create_group(\n payload: GroupCreateRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Create a new group in the identity provider and/or MongoDB (admin only).\n\n When create_in_idp is True, creates in both the configured\n identity provider and MongoDB scopes collection.\n When create_in_idp is False, creates only in MongoDB scopes collection.\n \"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n # Extract create_in_idp from scope_config (frontend sends it there)\n create_in_idp = False # default: do not create in IdP\n if payload.scope_config and \"create_in_idp\" in payload.scope_config:\n create_in_idp = bool(payload.scope_config[\"create_in_idp\"])\n logger.debug(\n \"create_in_idp=%s for group '%s' (from scope_config)\",\n create_in_idp,\n payload.name,\n )\n\n try:\n result = {}\n group_mapping_id = payload.name # default for local-only groups\n\n # Step 1: Create group in identity provider (only if requested)\n if create_in_idp:\n result = await iam.create_group(\n group_name=payload.name,\n description=payload.description or \"\",\n )\n\n # For Entra ID: use Object ID for group mapping\n # For Keycloak/Okta: use group name\n provider = AUTH_PROVIDER.lower()\n if provider == \"entra\":\n group_mapping_id = result.get(\"id\", payload.name)\n else:\n # Local-only group: build a result dict without calling IdP\n result = {\n \"id\": payload.name,\n \"name\": payload.name,\n \"path\": f\"/{payload.name}\",\n \"attributes\": {\"description\": [payload.description or \"\"]},\n }\n logger.info(\n \"Group '%s' created locally only (create_in_idp=False)\",\n payload.name,\n )\n\n # Step 2: Create in MongoDB scopes collection (always)\n server_access = []\n ui_permissions = {}\n agent_access = []\n if payload.scope_config:\n server_access = payload.scope_config.get(\"server_access\", [])\n ui_permissions = payload.scope_config.get(\"ui_permissions\", {})\n agent_access = payload.scope_config.get(\"agent_access\", [])\n\n # Normalize agent paths to ensure they have leading slashes\n agent_access, ui_permissions = _normalize_agent_paths_in_scope_config(\n agent_access, ui_permissions\n )\n\n import_success = await scope_service.import_group(\n scope_name=payload.name,\n description=payload.description or \"\",\n group_mappings=[group_mapping_id],\n server_access=server_access,\n ui_permissions=ui_permissions,\n agent_access=agent_access,\n )\n\n if not import_success:\n logger.warning(\n \"Group %s in IdP but failed to create in MongoDB: %s\",\n \"created\" if create_in_idp else \"skipped\",\n payload.name,\n )\n\n return GroupSummary(\n id=result.get(\"id\", \"\"),\n name=result.get(\"name\", \"\"),\n path=result.get(\"path\", \"\"),\n attributes=result.get(\"attributes\"),\n )\n\n except Exception as exc:\n logger.error(\"Failed to create group: %s\", exc)\n detail = str(exc).lower()\n\n if \"already exists\" in detail:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=str(exc),\n ) from exc\n\n raise _translate_iam_error(exc) from exc\n\n\n@router.delete(\"/iam/groups/{group_name}\", response_model=GroupDeleteResponse)\nasync def management_delete_group(\n group_name: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Delete a group from the identity provider and/or MongoDB (admin only).\n\n Attempts to delete from IdP first. If the group does not exist in the IdP\n (e.g., it was created with create_in_idp=False), the IdP error is logged\n and the MongoDB deletion proceeds.\n \"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n try:\n # Step 1: Attempt to delete from identity provider\n try:\n await iam.delete_group(group_name=group_name)\n except Exception as idp_exc:\n idp_detail = str(idp_exc).lower()\n if \"not found\" in idp_detail or \"404\" in idp_detail:\n logger.info(\n \"Group '%s' not found in IdP (may be local-only), \"\n \"proceeding with MongoDB deletion\",\n group_name,\n )\n else:\n raise\n\n # Step 2: Delete from MongoDB scopes collection\n delete_success = await scope_service.delete_group(\n group_name=group_name, remove_from_mappings=True\n )\n\n if not delete_success:\n logger.warning(\n \"Group deleted from IdP but failed to delete from MongoDB: %s\",\n group_name,\n )\n\n return GroupDeleteResponse(name=group_name)\n\n except Exception as exc:\n logger.error(\"Failed to delete group: %s\", exc)\n detail = str(exc).lower()\n\n if \"not found\" in detail:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Group '{group_name}' not found\",\n ) from exc\n\n raise _translate_iam_error(exc) from exc\n\n\n@router.get(\"/iam/groups/{group_name}\", response_model=GroupDetailResponse)\nasync def management_get_group(\n group_name: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Get detailed information about a group (admin only).\n\n Returns both identity provider data and MongoDB scope data.\n \"\"\"\n _require_admin(user_context)\n\n try:\n # Get group details from MongoDB scopes\n group_data = await scope_service.get_group(group_name)\n\n if not group_data:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Group '{group_name}' not found\",\n )\n\n return GroupDetailResponse(\n id=group_data.get(\"id\", \"\"),\n name=group_data.get(\"name\", group_name),\n path=group_data.get(\"path\"),\n description=group_data.get(\"description\"),\n server_access=group_data.get(\"server_access\"),\n group_mappings=group_data.get(\"group_mappings\"),\n ui_permissions=group_data.get(\"ui_permissions\"),\n agent_access=group_data.get(\"agent_access\"),\n )\n\n except HTTPException:\n raise\n\n except Exception as exc:\n logger.error(\"Failed to get group: %s\", exc)\n raise HTTPException(\n status_code=status.HTTP_502_BAD_GATEWAY,\n detail=f\"Failed to get group details: {exc}\",\n ) from exc\n\n\n@router.patch(\"/iam/groups/{group_name}\", response_model=GroupDetailResponse)\nasync def management_update_group(\n group_name: str,\n payload: GroupUpdateRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Update a group's properties and scope configuration (admin only).\n\n This updates the group in both:\n 1. The configured identity provider (Keycloak or Entra ID)\n 2. MongoDB scopes collection for authorization\n \"\"\"\n _require_admin(user_context)\n\n iam = get_iam_manager()\n\n try:\n # Step 1: Get existing group data to preserve group_mappings if not provided\n existing_group = await scope_service.get_group(group_name)\n if not existing_group:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Group '{group_name}' not found\",\n )\n\n # Step 2: Update group in identity provider (description only)\n if payload.description is not None:\n await iam.update_group(\n group_name=group_name,\n description=payload.description,\n )\n\n # Step 3: Update in MongoDB scopes collection\n # Extract server_access, ui_permissions, and agent_access from scope_config\n server_access = None\n ui_permissions = None\n group_mappings = None\n agent_access = None\n\n if payload.scope_config:\n server_access = payload.scope_config.get(\"server_access\")\n ui_permissions = payload.scope_config.get(\"ui_permissions\")\n group_mappings = payload.scope_config.get(\"group_mappings\")\n agent_access = payload.scope_config.get(\"agent_access\")\n\n # Preserve existing group_mappings if not provided in payload\n # This is critical for Entra ID where group_mappings contains Object IDs\n if group_mappings is None:\n group_mappings = existing_group.get(\"group_mappings\", [group_name])\n\n # Preserve existing agent_access if not provided in payload\n if agent_access is None:\n agent_access = existing_group.get(\"agent_access\", [])\n\n # Normalize agent paths to ensure they have leading slashes\n agent_access, ui_permissions = _normalize_agent_paths_in_scope_config(\n agent_access, ui_permissions\n )\n\n # Use import_group to update the scope data\n import_success = await scope_service.import_group(\n scope_name=group_name,\n description=payload.description or \"\",\n server_access=server_access,\n group_mappings=group_mappings,\n ui_permissions=ui_permissions,\n agent_access=agent_access,\n )\n\n if not import_success:\n logger.warning(\n \"Group updated in IdP but failed to update in MongoDB: %s\",\n group_name,\n )\n\n # Step 3: Fetch and return updated group details\n group_data = await scope_service.get_group(group_name)\n\n if not group_data:\n # Fall back to basic response if scope data not available\n return GroupDetailResponse(\n id=\"\",\n name=group_name,\n description=payload.description,\n )\n\n return GroupDetailResponse(\n id=group_data.get(\"id\", \"\"),\n name=group_data.get(\"name\", group_name),\n path=group_data.get(\"path\"),\n description=group_data.get(\"description\"),\n server_access=group_data.get(\"server_access\"),\n group_mappings=group_data.get(\"group_mappings\"),\n ui_permissions=group_data.get(\"ui_permissions\"),\n agent_access=group_data.get(\"agent_access\"),\n )\n\n except Exception as exc:\n logger.error(\"Failed to update group: %s\", exc)\n detail = str(exc).lower()\n\n if \"not found\" in detail:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Group '{group_name}' not found\",\n ) from exc\n\n raise _translate_iam_error(exc) from exc\n" }, { "path": "registry/api/okta_m2m_routes.py", "content": "\"\"\"API routes for Okta M2M client management.\n\nThis module provides endpoints for syncing Okta M2M applications to MongoDB\nand managing their group mappings.\n\"\"\"\n\nimport logging\nfrom typing import Annotated\n\nfrom fastapi import APIRouter, Depends, HTTPException\n\nfrom registry.auth.dependencies import nginx_proxied_auth\nfrom registry.repositories.documentdb.client import get_documentdb_client\nfrom registry.schemas.okta_m2m_client import (\n OktaM2MClient,\n OktaM2MClientUpdate,\n OktaSyncRequest,\n OktaSyncResponse,\n)\nfrom registry.services.okta_m2m_sync import get_okta_m2m_sync\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n\ndef _require_admin(user_context: dict | None) -> None:\n \"\"\"Check if user is admin.\n\n Args:\n user_context: User context from authentication\n\n Raises:\n HTTPException: If user is not admin\n \"\"\"\n if not user_context:\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n\n groups = user_context.get(\"groups\", [])\n if \"registry-admins\" not in groups:\n raise HTTPException(\n status_code=403,\n detail=\"Admin access required\",\n )\n\n\n@router.post(\"/iam/okta/m2m/sync\", response_model=OktaSyncResponse)\nasync def sync_okta_m2m_clients(\n request: OktaSyncRequest = OktaSyncRequest(),\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Sync M2M clients from Okta to MongoDB (admin only).\n\n This endpoint queries the Okta Admin API to fetch all M2M service applications\n and stores/updates their information in MongoDB for authorization decisions.\n\n Args:\n request: Sync request parameters\n user_context: Authenticated user context\n\n\n Returns:\n Sync statistics including number of clients added/updated\n\n Raises:\n HTTPException: If user is not admin or sync fails\n \"\"\"\n _require_admin(user_context)\n\n db = await get_documentdb_client()\n okta_sync = get_okta_m2m_sync(db)\n if not okta_sync:\n raise HTTPException(\n status_code=503,\n detail=\"Okta sync not configured (missing OKTA_DOMAIN or OKTA_API_TOKEN)\",\n )\n\n try:\n result = await okta_sync.sync_from_okta(force_full_sync=request.force_full_sync)\n return OktaSyncResponse(**result)\n\n except Exception as e:\n logger.exception(f\"Failed to sync Okta M2M clients: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Sync failed: {str(e)}\",\n )\n\n\n@router.get(\"/iam/okta/m2m/clients\", response_model=list[OktaM2MClient])\nasync def list_okta_m2m_clients(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"List all Okta M2M clients from MongoDB.\n\n Returns all M2M service accounts synced from Okta, including their\n client IDs and group mappings.\n\n Args:\n user_context: Authenticated user context\n\n\n Returns:\n List of Okta M2M clients\n\n Raises:\n HTTPException: If user is not authenticated\n \"\"\"\n if not user_context:\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n\n db = await get_documentdb_client()\n okta_sync = get_okta_m2m_sync(db)\n if not okta_sync:\n # Return empty list if Okta not configured\n return []\n\n try:\n clients = await okta_sync.get_all_clients()\n return clients\n\n except Exception as e:\n logger.exception(f\"Failed to list Okta M2M clients: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to retrieve clients: {str(e)}\",\n )\n\n\n@router.get(\"/iam/okta/m2m/clients/{client_id}/groups\", response_model=list[str])\nasync def get_client_groups(\n client_id: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Get groups for a specific Okta M2M client.\n\n Args:\n client_id: Okta client ID\n user_context: Authenticated user context\n\n\n Returns:\n List of group names\n\n Raises:\n HTTPException: If user is not authenticated or client not found\n \"\"\"\n if not user_context:\n raise HTTPException(status_code=401, detail=\"Not authenticated\")\n\n db = await get_documentdb_client()\n okta_sync = get_okta_m2m_sync(db)\n if not okta_sync:\n return []\n\n try:\n groups = await okta_sync.get_client_groups(client_id)\n return groups\n\n except Exception as e:\n logger.exception(f\"Failed to get groups for client {client_id}: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to retrieve groups: {str(e)}\",\n )\n\n\n@router.patch(\"/iam/okta/m2m/clients/{client_id}/groups\")\nasync def update_client_groups(\n client_id: str,\n payload: OktaM2MClientUpdate,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Update groups for an Okta M2M client (admin only).\n\n This allows administrators to change which groups a service account belongs to\n without modifying the Okta authorization server expression.\n\n Args:\n client_id: Okta client ID\n payload: Update payload with new groups\n user_context: Authenticated user context\n\n\n Returns:\n Success message\n\n Raises:\n HTTPException: If user is not admin or update fails\n \"\"\"\n _require_admin(user_context)\n\n db = await get_documentdb_client()\n okta_sync = get_okta_m2m_sync(db)\n if not okta_sync:\n raise HTTPException(\n status_code=503,\n detail=\"Okta sync not configured\",\n )\n\n try:\n success = await okta_sync.update_client_groups(client_id, payload.groups)\n\n if not success:\n raise HTTPException(\n status_code=404,\n detail=f\"Client {client_id} not found\",\n )\n\n return {\n \"client_id\": client_id,\n \"groups\": payload.groups,\n \"message\": \"Groups updated successfully\",\n }\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(f\"Failed to update groups for client {client_id}: {e}\")\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to update groups: {str(e)}\",\n )\n" }, { "path": "registry/api/peer_management_routes.py", "content": "\"\"\"\nPeer management API routes.\n\nProvides REST endpoints for managing peer registry configurations\nand triggering synchronization operations.\n\nIMPORTANT: Route ordering matters in FastAPI. All specific-path routes\n(e.g., /connections/all, /shared-resources, /sync) MUST be defined BEFORE\nany parameterized routes (e.g., /{peer_id}) to prevent the catch-all\nparameter from shadowing the specific paths.\n\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import Any\n\nfrom fastapi import APIRouter, Body, Depends, HTTPException, Query, status\n\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..schemas.peer_federation_schema import (\n PeerRegistryConfig,\n PeerSyncStatus,\n SyncResult,\n)\nfrom ..services.federation_audit_service import (\n FederationConnectionLog,\n PeerSyncSummary,\n get_federation_audit_service,\n)\nfrom ..services.peer_federation_service import get_peer_federation_service\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_peer_management_scope(\n user_context: dict[str, Any],\n) -> None:\n \"\"\"Check if user has permission to manage peers.\n\n Allows access for:\n - Admin users (network-trusted or mcp-registry-admin group)\n - Federation-static token users (have federation/peers scope)\n\n Args:\n user_context: User context from auth dependency\n\n Raises:\n HTTPException: 403 if user lacks peer management permission\n \"\"\"\n # Admins always have access\n if user_context.get(\"is_admin\", False):\n return\n\n # Check for federation/peers scope (federation static token)\n scopes = user_context.get(\"scopes\", [])\n if \"federation/peers\" in scopes:\n return\n\n # Check for admin group\n groups = user_context.get(\"groups\", [])\n if \"mcp-registry-admin\" in groups:\n return\n\n logger.warning(\n f\"User {user_context.get('username')} attempted peer management \"\n f\"without required scope. Scopes: {scopes}, Groups: {groups}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Peer management requires admin privileges or federation/peers scope\",\n )\n\n\nrouter = APIRouter(\n prefix=\"/api/peers\",\n tags=[\"peer-management\"],\n)\n\n\n# ============================================================================\n# SECTION 1: Routes with FIXED paths (no path parameters)\n# These MUST come before any /{peer_id} routes to avoid shadowing.\n# ============================================================================\n\n\n@router.get(\"\", response_model=list[PeerRegistryConfig])\nasync def list_peers(\n enabled: bool | None = None,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> list[PeerRegistryConfig]:\n \"\"\"\n List all peer registries with optional filtering by enabled status.\n\n Args:\n enabled: If True, return only enabled peers. If False, return only disabled peers.\n If None, return all peers.\n user_context: Authenticated user context\n\n Returns:\n List of peer registry configurations\n\n Example:\n GET /api/peers\n GET /api/peers?enabled=true\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' listing peers (enabled={enabled})\")\n\n service = get_peer_federation_service()\n peers = await service.list_peers(enabled=enabled)\n\n logger.info(f\"Returning {len(peers)} peer configs\")\n return peers\n\n\n@router.post(\"\", response_model=PeerRegistryConfig, status_code=status.HTTP_201_CREATED)\nasync def create_peer(\n config: PeerRegistryConfig,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> PeerRegistryConfig:\n \"\"\"\n Create a new peer registry configuration.\n\n Args:\n config: Peer registry configuration to create\n user_context: Authenticated user context\n\n Returns:\n Created peer registry configuration\n\n Raises:\n HTTPException: 409 if peer_id already exists\n HTTPException: 400 if validation fails\n\n Example:\n POST /api/peers\n {\n \"peer_id\": \"central-registry\",\n \"name\": \"Central MCP Registry\",\n \"endpoint\": \"https://central.registry.company.com\",\n \"enabled\": true,\n \"sync_mode\": \"all\",\n \"sync_interval_minutes\": 30\n }\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' creating peer '{config.peer_id}'\")\n\n service = get_peer_federation_service()\n\n try:\n created_peer = await service.add_peer(config)\n logger.info(f\"Successfully created peer '{config.peer_id}'\")\n return created_peer\n except ValueError as e:\n error_msg = str(e)\n if \"already exists\" in error_msg:\n logger.error(f\"Peer ID already exists: {config.peer_id}\")\n raise HTTPException(\n status_code=status.HTTP_409_CONFLICT,\n detail=error_msg,\n )\n else:\n logger.error(f\"Invalid peer config: {error_msg}\")\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=error_msg,\n )\n\n\n@router.post(\"/sync\", response_model=dict[str, SyncResult])\nasync def sync_all_peers(\n enabled_only: bool = Query(True, description=\"If True, only sync enabled peers\"),\n user_context: dict = Depends(nginx_proxied_auth),\n) -> dict[str, SyncResult]:\n \"\"\"\n Trigger synchronization for all (or enabled) peers.\n\n Args:\n enabled_only: If True, only sync enabled peers (default: True)\n user_context: Authenticated user context\n\n Returns:\n Dictionary mapping peer_id to SyncResult\n\n Example:\n POST /api/peers/sync\n POST /api/peers/sync?enabled_only=false\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(\n f\"User '{user_context.get('username')}' triggering sync for all peers \"\n f\"(enabled_only={enabled_only})\"\n )\n\n service = get_peer_federation_service()\n\n results = await service.sync_all_peers(enabled_only=enabled_only)\n\n # Count successes and failures\n successful = sum(1 for r in results.values() if r.success)\n failed = len(results) - successful\n total_servers = sum(r.servers_synced for r in results.values())\n total_agents = sum(r.agents_synced for r in results.values())\n\n logger.info(\n f\"Sync all completed: {successful} succeeded, {failed} failed. \"\n f\"Total: {total_servers} servers, {total_agents} agents\"\n )\n\n return results\n\n\n@router.get(\"/connections/all\", response_model=list[FederationConnectionLog])\nasync def get_all_connections(\n since: datetime | None = Query(\n None, description=\"Only return connections after this timestamp\"\n ),\n limit: int = Query(100, ge=1, le=1000, description=\"Maximum entries to return\"),\n user_context: dict = Depends(nginx_proxied_auth),\n) -> list[FederationConnectionLog]:\n \"\"\"\n Get all federation connection history.\n\n Returns a list of all federation connections from all peers, useful for\n monitoring overall federation activity.\n\n Args:\n since: Only return connections after this timestamp\n limit: Maximum entries to return (default: 100, max: 1000)\n user_context: Authenticated user context\n\n Returns:\n List of all connection logs\n\n Example:\n GET /api/peers/connections/all\n GET /api/peers/connections/all?limit=50\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' retrieving all federation connections\")\n\n audit_service = get_federation_audit_service()\n connections = await audit_service.get_all_connections(\n since=since,\n limit=limit,\n )\n\n logger.info(f\"Returning {len(connections)} total connection logs\")\n return connections\n\n\n@router.get(\"/shared-resources\", response_model=dict[str, PeerSyncSummary])\nasync def get_shared_resources(\n user_context: dict = Depends(nginx_proxied_auth),\n) -> dict[str, PeerSyncSummary]:\n \"\"\"\n Get summary of resources shared with each peer.\n\n Returns statistics about what has been shared with each peer,\n including connection counts and resource totals.\n\n Args:\n user_context: Authenticated user context\n\n Returns:\n Dictionary mapping peer_id to PeerSyncSummary\n\n Example:\n GET /api/peers/shared-resources\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' retrieving shared resources summary\")\n\n audit_service = get_federation_audit_service()\n summaries = await audit_service.get_shared_resources_summary()\n\n logger.info(f\"Returning shared resources summary for {len(summaries)} peers\")\n return summaries\n\n\n# ============================================================================\n# SECTION 2: Routes with /{peer_id} path parameter\n# These MUST come after all fixed-path routes above.\n# ============================================================================\n\n\n@router.get(\"/{peer_id}\", response_model=PeerRegistryConfig)\nasync def get_peer(\n peer_id: str,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> PeerRegistryConfig:\n \"\"\"\n Get a specific peer by ID.\n\n Args:\n peer_id: Peer identifier\n user_context: Authenticated user context\n\n Returns:\n Peer registry configuration\n\n Raises:\n HTTPException: 404 if peer not found\n\n Example:\n GET /api/peers/central-registry\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' retrieving peer '{peer_id}'\")\n\n service = get_peer_federation_service()\n\n try:\n peer = await service.get_peer(peer_id)\n return peer\n except ValueError as e:\n logger.error(f\"Peer not found: {peer_id}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=str(e),\n )\n\n\n@router.put(\"/{peer_id}\", response_model=PeerRegistryConfig)\nasync def update_peer(\n peer_id: str,\n updates: dict[str, Any] = Body(...),\n user_context: dict = Depends(nginx_proxied_auth),\n) -> PeerRegistryConfig:\n \"\"\"\n Update an existing peer configuration.\n\n Args:\n peer_id: Peer identifier\n updates: Dictionary of fields to update\n user_context: Authenticated user context\n\n Returns:\n Updated peer registry configuration\n\n Raises:\n HTTPException: 404 if peer not found\n HTTPException: 400 if validation fails\n\n Example:\n PUT /api/peers/central-registry\n {\n \"enabled\": false,\n \"sync_interval_minutes\": 60\n }\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(\n f\"User '{user_context.get('username')}' updating peer '{peer_id}' with updates: {updates}\"\n )\n\n service = get_peer_federation_service()\n\n try:\n updated_peer = await service.update_peer(peer_id, updates)\n logger.info(f\"Successfully updated peer '{peer_id}'\")\n return updated_peer\n except ValueError as e:\n error_msg = str(e)\n if \"not found\" in error_msg:\n logger.error(f\"Peer not found: {peer_id}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=error_msg,\n )\n else:\n logger.error(f\"Invalid peer update: {error_msg}\")\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=error_msg,\n )\n\n\n@router.patch(\"/{peer_id}/token\")\nasync def update_peer_token(\n peer_id: str,\n federation_token: str = Body(..., embed=True),\n user_context: dict = Depends(nginx_proxied_auth),\n) -> dict[str, str]:\n \"\"\"\n Update federation token for a peer without triggering full update.\n\n This endpoint specifically updates only the federation token, bypassing\n the regular update_peer() flow. This is useful for recovering from\n issue #561 where tokens were lost during peer updates, or for rotating\n tokens without modifying other peer configuration.\n\n Args:\n peer_id: Peer identifier\n federation_token: New federation token value\n user_context: Authenticated user context\n\n Returns:\n Success message with peer ID\n\n Raises:\n HTTPException: 404 if peer not found\n HTTPException: 400 if token update fails\n\n Example:\n PATCH /api/peers/central-registry/token\n {\n \"federation_token\": \"new-token-value-here\"\n }\n \"\"\"\n _check_peer_management_scope(user_context)\n username = user_context.get(\"username\", \"unknown\")\n logger.info(f\"User '{username}' updating federation token for peer '{peer_id}'\")\n\n service = get_peer_federation_service()\n\n try:\n # Get peer info before update for audit context\n peer_name = \"unknown\"\n try:\n existing_peer = await service.get_peer_by_id(peer_id)\n peer_name = existing_peer.name\n except Exception:\n pass # Continue even if we can't get peer name\n\n # Use the standard update_peer with only the token field\n # This goes through the now-fixed update flow\n await service.update_peer(peer_id, {\"federation_token\": federation_token})\n\n logger.info(\n f\"AUDIT: Federation token update successful via PATCH endpoint. \"\n f\"Peer: '{peer_id}' (name='{peer_name}'), User: '{username}'\"\n )\n\n return {\n \"message\": \"Federation token updated successfully\",\n \"peer_id\": peer_id,\n }\n except ValueError as e:\n error_msg = str(e)\n if \"not found\" in error_msg:\n logger.error(f\"Peer not found: {peer_id}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=error_msg,\n )\n else:\n logger.error(f\"Failed to update token: {error_msg}\")\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=error_msg,\n )\n\n\n@router.delete(\"/{peer_id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_peer(\n peer_id: str,\n user_context: dict = Depends(nginx_proxied_auth),\n):\n \"\"\"\n Delete a peer registry configuration.\n\n Args:\n peer_id: Peer identifier\n user_context: Authenticated user context\n\n Raises:\n HTTPException: 404 if peer not found\n\n Example:\n DELETE /api/peers/central-registry\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' deleting peer '{peer_id}'\")\n\n service = get_peer_federation_service()\n\n try:\n await service.remove_peer(peer_id)\n logger.info(f\"Successfully deleted peer '{peer_id}'\")\n # Return None for 204 No Content\n return None\n except ValueError as e:\n logger.error(f\"Failed to delete peer '{peer_id}': {e}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=str(e),\n )\n\n\n@router.post(\"/{peer_id}/sync\", response_model=SyncResult)\nasync def sync_peer(\n peer_id: str,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> SyncResult:\n \"\"\"\n Trigger synchronization for a specific peer.\n\n Args:\n peer_id: Peer identifier\n user_context: Authenticated user context\n\n Returns:\n Sync result with statistics\n\n Raises:\n HTTPException: 404 if peer not found\n HTTPException: 400 if peer is disabled\n\n Example:\n POST /api/peers/central-registry/sync\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' triggering sync for peer '{peer_id}'\")\n\n service = get_peer_federation_service()\n\n try:\n result = await service.sync_peer(peer_id)\n logger.info(\n f\"Sync completed for peer '{peer_id}': \"\n f\"success={result.success}, servers={result.servers_synced}, \"\n f\"agents={result.agents_synced}\"\n )\n return result\n except ValueError as e:\n error_msg = str(e)\n if \"not found\" in error_msg:\n logger.error(f\"Peer not found: {peer_id}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=error_msg,\n )\n else:\n logger.error(f\"Sync failed: {error_msg}\")\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=error_msg,\n )\n\n\n@router.get(\"/{peer_id}/status\", response_model=PeerSyncStatus)\nasync def get_peer_status(\n peer_id: str,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> PeerSyncStatus:\n \"\"\"\n Get sync status for a specific peer.\n\n Args:\n peer_id: Peer identifier\n user_context: Authenticated user context\n\n Returns:\n Peer sync status with health and history\n\n Raises:\n HTTPException: 404 if peer not found\n\n Example:\n GET /api/peers/central-registry/status\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' retrieving status for peer '{peer_id}'\")\n\n service = get_peer_federation_service()\n\n sync_status = await service.get_sync_status(peer_id)\n\n if not sync_status:\n logger.error(f\"Sync status not found for peer: {peer_id}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Sync status not found for peer: {peer_id}\",\n )\n\n return sync_status\n\n\n@router.post(\"/{peer_id}/enable\", response_model=PeerRegistryConfig)\nasync def enable_peer(\n peer_id: str,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> PeerRegistryConfig:\n \"\"\"\n Enable a peer registry.\n\n Args:\n peer_id: Peer identifier\n user_context: Authenticated user context\n\n Returns:\n Updated peer registry configuration\n\n Raises:\n HTTPException: 404 if peer not found\n\n Example:\n POST /api/peers/central-registry/enable\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' enabling peer '{peer_id}'\")\n\n service = get_peer_federation_service()\n\n try:\n updated_peer = await service.update_peer(peer_id, {\"enabled\": True})\n logger.info(f\"Successfully enabled peer '{peer_id}'\")\n return updated_peer\n except ValueError as e:\n logger.error(f\"Failed to enable peer '{peer_id}': {e}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=str(e),\n )\n\n\n@router.post(\"/{peer_id}/disable\", response_model=PeerRegistryConfig)\nasync def disable_peer(\n peer_id: str,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> PeerRegistryConfig:\n \"\"\"\n Disable a peer registry.\n\n Args:\n peer_id: Peer identifier\n user_context: Authenticated user context\n\n Returns:\n Updated peer registry configuration\n\n Raises:\n HTTPException: 404 if peer not found\n\n Example:\n POST /api/peers/central-registry/disable\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(f\"User '{user_context.get('username')}' disabling peer '{peer_id}'\")\n\n service = get_peer_federation_service()\n\n try:\n updated_peer = await service.update_peer(peer_id, {\"enabled\": False})\n logger.info(f\"Successfully disabled peer '{peer_id}'\")\n return updated_peer\n except ValueError as e:\n logger.error(f\"Failed to disable peer '{peer_id}': {e}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=str(e),\n )\n\n\n@router.get(\"/{peer_id}/connections\", response_model=list[FederationConnectionLog])\nasync def get_peer_connections(\n peer_id: str,\n since: datetime | None = Query(\n None, description=\"Only return connections after this timestamp\"\n ),\n limit: int = Query(100, ge=1, le=1000, description=\"Maximum entries to return\"),\n user_context: dict = Depends(nginx_proxied_auth),\n) -> list[FederationConnectionLog]:\n \"\"\"\n Get connection history for a specific peer.\n\n Returns a list of federation connections from this peer, useful for\n debugging and monitoring federation sync operations.\n\n Args:\n peer_id: Peer identifier\n since: Only return connections after this timestamp\n limit: Maximum entries to return (default: 100, max: 1000)\n user_context: Authenticated user context\n\n Returns:\n List of connection logs for the peer\n\n Example:\n GET /api/peers/central-registry/connections\n GET /api/peers/central-registry/connections?since=2024-01-01T00:00:00Z\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(\n f\"User '{user_context.get('username')}' retrieving connections for peer '{peer_id}'\"\n )\n\n audit_service = get_federation_audit_service()\n connections = await audit_service.get_peer_connections(\n peer_id=peer_id,\n since=since,\n limit=limit,\n )\n\n logger.info(f\"Returning {len(connections)} connection logs for peer '{peer_id}'\")\n return connections\n\n\n@router.get(\"/{peer_id}/shared-resources\", response_model=PeerSyncSummary)\nasync def get_peer_shared_resources(\n peer_id: str,\n user_context: dict = Depends(nginx_proxied_auth),\n) -> PeerSyncSummary:\n \"\"\"\n Get summary of resources shared with a specific peer.\n\n Args:\n peer_id: Peer identifier\n user_context: Authenticated user context\n\n Returns:\n PeerSyncSummary for the specified peer\n\n Raises:\n HTTPException: 404 if peer has no connection history\n\n Example:\n GET /api/peers/central-registry/shared-resources\n \"\"\"\n _check_peer_management_scope(user_context)\n logger.info(\n f\"User '{user_context.get('username')}' retrieving shared resources for peer '{peer_id}'\"\n )\n\n audit_service = get_federation_audit_service()\n summary = await audit_service.get_peer_summary(peer_id)\n\n if not summary:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"No connection history found for peer: {peer_id}\",\n )\n\n return summary\n" }, { "path": "registry/api/registry_management_routes.py", "content": "\"\"\"\nRegistry management routes for administrative operations.\n\nProvides endpoints for registry operators to manage telemetry,\ndiagnostics, and other internal registry functions.\n\"\"\"\n\nimport logging\nfrom typing import Annotated\n\nfrom fastapi import APIRouter, Depends, HTTPException, status\n\nfrom registry.auth.dependencies import nginx_proxied_auth\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/registry-management\", tags=[\"Registry Management\"])\n\n\ndef _require_admin(user_context: dict) -> None:\n \"\"\"\n Verify user has admin permissions.\n\n Args:\n user_context: User context from authentication\n\n Raises:\n HTTPException: If user is not an admin\n \"\"\"\n if not user_context.get(\"is_admin\"):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Administrator permissions are required for this operation\",\n )\n\n\n@router.post(\"/telemetry/heartbeat\")\nasync def force_heartbeat(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Force an immediate heartbeat telemetry event (admin only).\n\n Bypasses the 24-hour lock and sends a heartbeat event immediately.\n Useful for verifying telemetry pipeline or after configuration changes.\n\n Returns:\n Status of the heartbeat send attempt.\n \"\"\"\n _require_admin(user_context)\n\n from registry.core.telemetry import send_forced_heartbeat\n\n result = await send_forced_heartbeat()\n\n if result[\"status\"] == \"disabled\":\n raise HTTPException(\n status_code=status.HTTP_409_CONFLICT,\n detail=\"Telemetry is disabled. Set MCP_TELEMETRY_DISABLED=0 to enable.\",\n )\n\n return result\n\n\n@router.post(\"/telemetry/startup\")\nasync def force_startup_ping(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Force an immediate startup telemetry event (admin only).\n\n Bypasses the 60-second lock and sends a startup ping immediately.\n Useful for verifying telemetry pipeline connectivity.\n\n Returns:\n Status of the startup send attempt.\n \"\"\"\n _require_admin(user_context)\n\n from registry.core.telemetry import send_forced_startup\n\n result = await send_forced_startup()\n\n if result[\"status\"] == \"disabled\":\n raise HTTPException(\n status_code=status.HTTP_409_CONFLICT,\n detail=\"Telemetry is disabled. Set MCP_TELEMETRY_DISABLED=0 to enable.\",\n )\n\n return result\n" }, { "path": "registry/api/registry_routes.py", "content": "\"\"\"\n\nAnthropic MCP Registry API endpoints.\n\nImplements the standard MCP Registry REST API for compatibility with\nAnthropic's official registry specification.\n\nSpec: https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/api/openapi.yaml\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Annotated\nfrom urllib.parse import unquote\n\nfrom fastapi import APIRouter, Depends, HTTPException, Query, status\n\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..constants import REGISTRY_CONSTANTS\nfrom ..health.service import health_service\nfrom ..repositories.factory import get_registry_card_repository\nfrom ..schemas.anthropic_schema import ErrorResponse, ServerList, ServerResponse\nfrom ..schemas.registry_card import RegistryCard\nfrom ..services.server_service import server_service\nfrom ..services.transform_service import (\n transform_to_server_list,\n transform_to_server_response,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(\n prefix=f\"/{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION}\",\n tags=[\"Anthropic Registry API\"],\n)\n\n\n@router.get(\n \"/servers\",\n response_model=ServerList,\n summary=\"List MCP servers\",\n description=\"Returns a paginated list of all registered MCP servers that the authenticated user can access.\",\n)\nasync def list_servers(\n cursor: Annotated[str | None, Query(description=\"Pagination cursor\")] = None,\n limit: Annotated[\n int | None, Query(description=\"Maximum number of items\", ge=1, le=1000)\n ] = None,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> ServerList:\n \"\"\"\n List all MCP servers with pagination.\n\n This endpoint respects user permissions - users only see servers they have access to.\n\n Args:\n cursor: Pagination cursor (opaque string from previous response)\n limit: Max results per page (default: 100, max: 1000)\n user_context: Authenticated user context from enhanced_auth\n\n Returns:\n ServerList with servers and pagination metadata\n \"\"\"\n logger.info(\n f\"{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION} API: Listing servers for user '{user_context['username']}' (cursor={cursor}, limit={limit})\"\n )\n\n # Get servers based on user permissions (same logic as existing /servers endpoint)\n if user_context[\"is_admin\"]:\n # Admin sees all servers\n all_servers = await server_service.get_all_servers()\n logger.debug(f\"Admin user accessing all {len(all_servers)} servers\")\n else:\n # Regular user sees only accessible servers\n all_servers = await server_service.get_all_servers_with_permissions(\n user_context[\"accessible_servers\"]\n )\n logger.debug(f\"User accessing {len(all_servers)} accessible servers\")\n\n # For API, we don't need UI service filtering - accessible_servers already handles MCP server permissions\n # No additional filtering needed here - the get_all_servers_with_permissions already filtered by accessible_servers\n filtered_servers = []\n\n for path, server_info in all_servers.items():\n # Fetch enabled status before health check to avoid race condition (Issue #612)\n is_enabled = await server_service.is_service_enabled(path)\n\n # Add health status with current enabled state\n health_data = health_service._get_service_health_data(\n path,\n {**server_info, \"is_enabled\": is_enabled},\n )\n\n server_info_with_status = server_info.copy()\n server_info_with_status[\"health_status\"] = health_data[\"status\"]\n server_info_with_status[\"last_checked_iso\"] = health_data[\"last_checked_iso\"]\n server_info_with_status[\"is_enabled\"] = is_enabled\n\n filtered_servers.append(server_info_with_status)\n\n # Transform to Anthropic format with pagination\n server_list = transform_to_server_list(filtered_servers, cursor=cursor, limit=limit or 100)\n\n logger.info(\n f\"{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION} API: Returning {len(server_list.servers)} servers (hasMore={server_list.metadata.nextCursor is not None})\"\n )\n\n return server_list\n\n\n@router.get(\n \"/servers/{serverName:path}/versions\",\n response_model=ServerList,\n summary=\"List server versions\",\n description=\"Returns all available versions for a specific MCP server.\",\n responses={404: {\"model\": ErrorResponse, \"description\": \"Server not found\"}},\n)\nasync def list_server_versions(\n serverName: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> ServerList:\n \"\"\"\n List all versions of a specific server.\n\n Currently, we only maintain one version per server, so this returns a single-item list.\n\n Args:\n serverName: URL-encoded server name in reverse-DNS format (e.g., \"io.mcpgateway%2Fexample-server\")\n user_context: Authenticated user context\n\n Returns:\n ServerList with single version\n\n Raises:\n HTTPException: 404 if server not found or user lacks access\n \"\"\"\n # URL-decode the server name\n decoded_name = unquote(serverName)\n logger.info(\n f\"{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION} API: Listing versions for server '{decoded_name}' (user='{user_context['username']}')\"\n )\n\n # Extract path from reverse-DNS name\n # Expected format: \"io.mcpgateway/example-server\"\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n expected_prefix = f\"{namespace}/\"\n\n if not decoded_name.startswith(expected_prefix):\n logger.warning(f\"Invalid server name format: {decoded_name}\")\n raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=\"Server not found\")\n\n # Construct initial path for lookup\n lookup_path = \"/\" + decoded_name.replace(expected_prefix, \"\")\n\n # Get server info - try with and without trailing slash\n server_info = await server_service.get_server_info(lookup_path)\n if not server_info:\n # Try with trailing slash\n server_info = await server_service.get_server_info(lookup_path + \"/\")\n\n if not server_info:\n logger.warning(f\"Server not found: {lookup_path}\")\n raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=\"Server not found\")\n\n # Use the actual path from server_info (has correct trailing slash)\n path = server_info.get(\"path\", lookup_path)\n\n # Check user permissions - use accessible_servers (MCP scopes) not accessible_services (UI scopes)\n accessible_servers = user_context.get(\"accessible_servers\", [])\n server_name = server_info[\"server_name\"]\n\n if not user_context[\"is_admin\"]:\n # Check if user can access this server\n if server_name not in accessible_servers:\n logger.warning(\n f\"User '{user_context['username']}' attempted to access unauthorized server: {server_name}\"\n )\n raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=\"Server not found\")\n\n # Fetch enabled status before health check to avoid race condition (Issue #612)\n is_enabled = await server_service.is_service_enabled(path)\n\n # Add health and status info using the correct path\n health_data = health_service._get_service_health_data(\n path,\n {**server_info, \"is_enabled\": is_enabled},\n )\n\n server_info_with_status = server_info.copy()\n server_info_with_status[\"health_status\"] = health_data[\"status\"]\n server_info_with_status[\"last_checked_iso\"] = health_data[\"last_checked_iso\"]\n server_info_with_status[\"is_enabled\"] = is_enabled\n\n # Since we only have one version, return a list with one item\n server_list = transform_to_server_list([server_info_with_status])\n\n logger.info(\n f\"{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION} API: Returning version info for {decoded_name}\"\n )\n\n return server_list\n\n\n@router.get(\n \"/servers/{serverName:path}/versions/{version}\",\n response_model=ServerResponse,\n summary=\"Get server version details\",\n description=\"Returns detailed information about a specific version of an MCP server. Use 'latest' to get the most recent version.\",\n responses={404: {\"model\": ErrorResponse, \"description\": \"Server or version not found\"}},\n)\nasync def get_server_version(\n serverName: str,\n version: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n) -> ServerResponse:\n \"\"\"\n Get detailed information about a specific server version.\n\n Args:\n serverName: URL-encoded server name (e.g., \"io.mcpgateway%2Fexample-server\")\n version: Version string (e.g., \"1.0.0\" or \"latest\")\n user_context: Authenticated user context\n\n Returns:\n ServerResponse with full server details\n\n Raises:\n HTTPException: 404 if server not found or user lacks access\n \"\"\"\n # URL-decode parameters\n decoded_name = unquote(serverName)\n decoded_version = unquote(version)\n\n logger.info(\n f\"{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION} API: Getting server '{decoded_name}' version '{decoded_version}' (user='{user_context['username']}')\"\n )\n\n # Extract path from reverse-DNS name\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n expected_prefix = f\"{namespace}/\"\n\n if not decoded_name.startswith(expected_prefix):\n logger.warning(f\"Invalid server name format: {decoded_name}\")\n raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=\"Server not found\")\n\n # Construct initial path for lookup\n lookup_path = \"/\" + decoded_name.replace(expected_prefix, \"\")\n\n # Get server info - try with and without trailing slash\n server_info = await server_service.get_server_info(lookup_path)\n if not server_info:\n # Try with trailing slash\n server_info = await server_service.get_server_info(lookup_path + \"/\")\n\n if not server_info:\n logger.warning(f\"Server not found: {lookup_path}\")\n raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=\"Server not found\")\n\n # Use the actual path from server_info (has correct trailing slash)\n path = server_info.get(\"path\", lookup_path)\n\n # Check user permissions - use accessible_servers (MCP scopes) not accessible_services (UI scopes)\n accessible_servers = user_context.get(\"accessible_servers\", [])\n server_name = server_info[\"server_name\"]\n\n if not user_context[\"is_admin\"]:\n if server_name not in accessible_servers:\n logger.warning(\n f\"User '{user_context['username']}' attempted to access unauthorized server: {server_name}\"\n )\n raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=\"Server not found\")\n\n # Currently we only support \"latest\" or \"1.0.0\" since we don't version servers\n if decoded_version not in [\"latest\", \"1.0.0\"]:\n logger.warning(f\"Unsupported version requested: {decoded_version}\")\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Version {decoded_version} not found\",\n )\n\n # Fetch enabled status before health check to avoid race condition (Issue #612)\n is_enabled = await server_service.is_service_enabled(path)\n\n # Add health and status info\n health_data = health_service._get_service_health_data(\n path,\n {**server_info, \"is_enabled\": is_enabled},\n )\n\n server_info_with_status = server_info.copy()\n server_info_with_status[\"health_status\"] = health_data[\"status\"]\n server_info_with_status[\"last_checked_iso\"] = health_data[\"last_checked_iso\"]\n server_info_with_status[\"is_enabled\"] = is_enabled\n\n # Transform to Anthropic format\n server_response = transform_to_server_response(\n server_info_with_status, include_registry_meta=True\n )\n\n logger.info(\n f\"{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION} API: Returning details for {decoded_name} v{decoded_version}\"\n )\n\n return server_response\n\n\nasync def _auto_initialize_registry_card():\n \"\"\"\n Auto-initialize registry card from config defaults if it doesn't exist.\n\n Returns the existing or newly created card.\n \"\"\"\n repo = get_registry_card_repository()\n card = await repo.get()\n\n if card is None:\n # Auto-initialize from config defaults\n import random\n from uuid import uuid4\n\n from registry.core.config import settings\n from registry.schemas.registry_card import RegistryContact\n from registry.version import __version__\n\n logger.info(\"Registry card not found, auto-initializing from config\")\n\n # Generate UUID for registry_id if not configured\n if settings.registry_id:\n registry_id = settings.registry_id\n else:\n registry_id = str(uuid4())\n logger.info(f\"Generated UUID for registry_id: {registry_id}\")\n\n # Generate random Docker-style registry name if using default\n if settings.registry_name != \"AI Registry\":\n registry_name = settings.registry_name\n else:\n adjectives = [\"brave\", \"clever\", \"swift\", \"bright\", \"noble\", \"wise\", \"bold\", \"keen\"]\n nouns = [\"falcon\", \"dolphin\", \"tiger\", \"phoenix\", \"dragon\", \"wolf\", \"eagle\", \"lion\"]\n registry_name = f\"{random.choice(adjectives)}-{random.choice(nouns)}-registry\"\n logger.info(f\"Generated random registry name: {registry_name}\")\n\n # Use organization name from config (defaults to \"ACME Inc.\")\n organization_name = settings.registry_organization_name\n logger.info(f\"Using organization name: {organization_name}\")\n\n # Get full API version from version module (e.g., \"1.0.17\")\n version_str = __version__\n # Remove 'v' prefix if present (e.g., \"v1.0.17\" -> \"1.0.17\")\n if version_str.startswith(\"v\"):\n version_str = version_str[1:]\n # Remove git suffix if present (e.g., \"1.0.17-6-gf5c000c3-main\" -> \"1.0.17\")\n version_parts = version_str.split(\"-\")[0]\n federation_api_version = version_parts\n logger.info(\n f\"Using federation API version: {federation_api_version} (from app version: {__version__})\"\n )\n\n contact = None\n if settings.registry_contact_email or settings.registry_contact_url:\n contact = RegistryContact(\n email=settings.registry_contact_email,\n url=settings.registry_contact_url,\n )\n\n # Build OAuth params based on auth provider\n oauth2_issuer = None\n oauth2_token_endpoint = None\n\n if settings.auth_provider == \"okta\":\n import os\n\n okta_domain = os.getenv(\"OKTA_DOMAIN\")\n okta_auth_server_id = os.getenv(\"OKTA_AUTH_SERVER_ID\", \"default\")\n if okta_domain:\n oauth2_issuer = f\"https://{okta_domain}/oauth2/{okta_auth_server_id}\"\n oauth2_token_endpoint = (\n f\"https://{okta_domain}/oauth2/{okta_auth_server_id}/v1/token\"\n )\n elif settings.auth_provider == \"keycloak\":\n import os\n\n keycloak_external_url = os.getenv(\"KEYCLOAK_EXTERNAL_URL\", \"http://localhost:8080\")\n keycloak_realm = os.getenv(\"KEYCLOAK_REALM\", \"mcp-gateway\")\n oauth2_issuer = f\"{keycloak_external_url}/realms/{keycloak_realm}\"\n oauth2_token_endpoint = (\n f\"{keycloak_external_url}/realms/{keycloak_realm}/protocol/openid-connect/token\"\n )\n elif settings.auth_provider == \"entra\":\n import os\n\n entra_tenant_id = os.getenv(\"ENTRA_TENANT_ID\")\n if entra_tenant_id:\n oauth2_issuer = f\"https://login.microsoftonline.com/{entra_tenant_id}/v2.0\"\n oauth2_token_endpoint = (\n f\"https://login.microsoftonline.com/{entra_tenant_id}/oauth2/v2.0/token\"\n )\n elif settings.auth_provider == \"cognito\":\n import os\n\n cognito_user_pool_id = os.getenv(\"COGNITO_USER_POOL_ID\")\n cognito_domain = os.getenv(\"COGNITO_DOMAIN\")\n aws_region = os.getenv(\"AWS_REGION\", \"us-east-1\")\n if cognito_user_pool_id:\n oauth2_issuer = (\n f\"https://cognito-idp.{aws_region}.amazonaws.com/{cognito_user_pool_id}\"\n )\n if cognito_domain:\n oauth2_token_endpoint = (\n f\"https://{cognito_domain}.auth.{aws_region}.amazoncognito.com/oauth2/token\"\n )\n\n from registry.schemas.registry_card import RegistryAuthConfig\n\n auth_config = RegistryAuthConfig(\n oauth2_issuer=oauth2_issuer,\n oauth2_token_endpoint=oauth2_token_endpoint,\n )\n\n card = RegistryCard(\n id=registry_id,\n name=registry_name,\n description=settings.registry_description,\n registry_url=settings.registry_url,\n organization_name=organization_name,\n federation_api_version=federation_api_version,\n federation_endpoint=f\"{settings.registry_url}/api/v1/federation\",\n authentication=auth_config,\n contact=contact,\n )\n\n # Save the auto-initialized card\n card = await repo.save(card)\n logger.info(f\"Auto-initialized registry card: {card.id}\")\n\n return card\n\n\n@router.get(\"/card\")\nasync def get_registry_card():\n \"\"\"\n Get the Registry Card for this instance.\n\n Auto-initializes from config if not found.\n Public endpoint for federation discovery.\n Returns flattened contact fields for frontend compatibility.\n \"\"\"\n card = await _auto_initialize_registry_card()\n\n # Serialize to dict and flatten contact fields for frontend\n card_dict = card.model_dump(mode=\"json\")\n contact = card_dict.pop(\"contact\", None)\n if contact:\n card_dict[\"contact_email\"] = contact.get(\"email\")\n card_dict[\"contact_url\"] = contact.get(\"url\")\n else:\n card_dict[\"contact_email\"] = None\n card_dict[\"contact_url\"] = None\n\n return card_dict\n\n\n@router.post(\"/card\", response_model=dict)\nasync def update_registry_card(\n request: dict,\n user_context: dict = Depends(nginx_proxied_auth),\n):\n \"\"\"\n Create or update the Registry Card.\n\n Requires admin role. All updates are audit logged.\n \"\"\"\n # Check admin permissions\n username = user_context.get(\"username\", \"unknown\")\n is_admin = user_context.get(\"is_admin\", False)\n\n if not is_admin:\n logger.warning(\n \"Unauthorized registry card update attempt\",\n extra={\"username\": username, \"is_admin\": is_admin},\n )\n raise HTTPException(\n status_code=403,\n detail=\"Admin role required to update registry card\",\n )\n\n repo = get_registry_card_repository()\n\n # Get existing card or create new\n existing = await repo.get()\n operation = \"update\" if existing else \"create\"\n\n # Handle nested contact fields from frontend (flat) to backend (nested)\n from registry.core.config import settings\n from registry.schemas.registry_card import RegistryContact\n\n if existing:\n # Update existing card\n card_data = existing.model_dump()\n old_values = {k: v for k, v in card_data.items() if k in request}\n\n if \"contact_email\" in request or \"contact_url\" in request:\n # Build contact object from flat fields\n existing_contact = card_data.get(\"contact\") or {}\n contact_data = {\n \"email\": request.get(\"contact_email\", existing_contact.get(\"email\")),\n \"url\": request.get(\"contact_url\", existing_contact.get(\"url\")),\n }\n # Only create contact if at least one field is non-null\n if contact_data[\"email\"] or contact_data[\"url\"]:\n card_data[\"contact\"] = RegistryContact(**contact_data).model_dump()\n else:\n card_data[\"contact\"] = None\n\n # Remove flat fields\n request_cleaned = {\n k: v for k, v in request.items() if k not in [\"contact_email\", \"contact_url\"]\n }\n card_data.update(request_cleaned)\n else:\n card_data.update(request)\n\n card = RegistryCard(**card_data)\n else:\n # Create new card\n request_cleaned = request.copy()\n\n if \"contact_email\" in request or \"contact_url\" in request:\n # Build contact object from flat fields\n contact_data = {\n \"email\": request.get(\"contact_email\"),\n \"url\": request.get(\"contact_url\"),\n }\n if contact_data[\"email\"] or contact_data[\"url\"]:\n request_cleaned[\"contact\"] = RegistryContact(**contact_data)\n\n # Remove flat fields\n request_cleaned.pop(\"contact_email\", None)\n request_cleaned.pop(\"contact_url\", None)\n\n card = RegistryCard(\n registry_id=settings.registry_id or \"default\",\n federation_endpoint=settings.registry_url + \"/api\",\n **request_cleaned,\n )\n old_values = {}\n\n saved = await repo.save(card)\n\n # Audit log\n logger.info(\n f\"Registry card {operation} by admin\",\n extra={\n \"operation\": operation,\n \"username\": username,\n \"timestamp\": datetime.now(UTC).isoformat(),\n \"registry_id\": str(saved.id),\n \"changed_fields\": list(request.keys()),\n \"old_values\": old_values if operation == \"update\" else None,\n },\n )\n\n # Flatten contact fields for frontend response\n saved_dict = saved.model_dump(mode=\"json\")\n contact = saved_dict.pop(\"contact\", None)\n if contact:\n saved_dict[\"contact_email\"] = contact.get(\"email\")\n saved_dict[\"contact_url\"] = contact.get(\"url\")\n else:\n saved_dict[\"contact_email\"] = None\n saved_dict[\"contact_url\"] = None\n\n return {\n \"message\": f\"Registry card {operation}d successfully\",\n \"registry_card\": saved_dict,\n }\n\n\n@router.patch(\"/card\", response_model=dict)\nasync def patch_registry_card(\n request: dict,\n user_context: dict = Depends(nginx_proxied_auth),\n):\n \"\"\"\n Partially update the Registry Card.\n\n Requires admin role. Only updates provided fields.\n \"\"\"\n # Check admin permissions\n username = user_context.get(\"username\", \"unknown\")\n is_admin = user_context.get(\"is_admin\", False)\n\n if not is_admin:\n logger.warning(\n \"Unauthorized registry card update attempt\",\n extra={\"username\": username, \"is_admin\": is_admin},\n )\n raise HTTPException(\n status_code=403,\n detail=\"Admin role required to update registry card\",\n )\n\n repo = get_registry_card_repository()\n\n # Get existing card\n existing = await repo.get()\n if not existing:\n raise HTTPException(\n status_code=404,\n detail=\"Registry card not found. Use POST to create.\",\n )\n\n # Partial update\n card_data = existing.model_dump()\n old_values = {k: v for k, v in card_data.items() if k in request}\n\n # Handle nested contact fields from frontend (flat) to backend (nested)\n from registry.schemas.registry_card import RegistryContact\n\n if \"contact_email\" in request or \"contact_url\" in request:\n # Build contact object from flat fields\n existing_contact = card_data.get(\"contact\") or {}\n contact_data = {\n \"email\": request.get(\"contact_email\", existing_contact.get(\"email\")),\n \"url\": request.get(\"contact_url\", existing_contact.get(\"url\")),\n }\n # Only create contact if at least one field is non-null\n if contact_data[\"email\"] or contact_data[\"url\"]:\n card_data[\"contact\"] = RegistryContact(**contact_data).model_dump()\n else:\n card_data[\"contact\"] = None\n\n # Remove flat fields from request before updating\n request_cleaned = {\n k: v for k, v in request.items() if k not in [\"contact_email\", \"contact_url\"]\n }\n card_data.update(request_cleaned)\n else:\n card_data.update(request)\n\n card = RegistryCard(**card_data)\n\n saved = await repo.save(card)\n\n # Audit log\n logger.info(\n \"Registry card partially updated by admin\",\n extra={\n \"operation\": \"patch\",\n \"username\": username,\n \"timestamp\": datetime.now(UTC).isoformat(),\n \"registry_id\": str(saved.id),\n \"changed_fields\": list(request.keys()),\n \"old_values\": old_values,\n },\n )\n\n # Flatten contact fields for frontend response\n saved_dict = saved.model_dump(mode=\"json\")\n contact = saved_dict.pop(\"contact\", None)\n if contact:\n saved_dict[\"contact_email\"] = contact.get(\"email\")\n saved_dict[\"contact_url\"] = contact.get(\"url\")\n else:\n saved_dict[\"contact_email\"] = None\n saved_dict[\"contact_url\"] = None\n\n return {\n \"message\": \"Registry card updated successfully\",\n \"registry_card\": saved_dict,\n }\n" }, { "path": "registry/api/search_routes.py", "content": "import logging\nimport re\nfrom typing import (\n Annotated,\n Literal,\n)\n\nfrom fastapi import APIRouter, Depends, HTTPException, Request, status\nfrom pydantic import BaseModel, Field\n\nfrom ..audit import set_audit_action\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..core.config import DeploymentMode, RegistryMode, settings\nfrom ..repositories.factory import get_search_repository\nfrom ..repositories.interfaces import SearchRepositoryBase\nfrom ..services.agent_service import agent_service\nfrom ..services.server_service import server_service\nfrom ..services.virtual_server_service import get_virtual_server_service\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\nEntityType = Literal[\"mcp_server\", \"tool\", \"a2a_agent\", \"skill\", \"virtual_server\"]\n\n\ndef get_search_repo() -> SearchRepositoryBase:\n \"\"\"Dependency injection function for search repository.\"\"\"\n return get_search_repository()\n\n\nclass MatchingToolResult(BaseModel):\n \"\"\"Tool matching result with optional schema for display.\"\"\"\n\n tool_name: str\n description: str | None = None\n relevance_score: float = Field(0.0, ge=0.0, le=1.0)\n match_context: str | None = None\n inputSchema: dict | None = Field(\n default=None, description=\"JSON Schema for tool input parameters\"\n )\n\n\nclass SyncMetadata(BaseModel):\n \"\"\"Metadata for items synced from peer registries.\"\"\"\n\n is_federated: bool = False\n source_peer_id: str | None = None\n synced_at: str | None = None\n original_path: str | None = None\n is_orphaned: bool = False\n orphaned_at: str | None = None\n is_read_only: bool = True\n\n\ndef _compute_endpoint_url(\n path: str,\n proxy_pass_url: str | None,\n mcp_endpoint: str | None,\n base_url: str | None,\n) -> str | None:\n \"\"\"Compute the endpoint URL for an MCP server.\n\n URL determination with fallback chain:\n 1. mcp_endpoint (custom override) - always takes precedence\n 2. proxy_pass_url (in registry-only mode)\n 3. Constructed gateway URL (default/fallback in with-gateway mode)\n\n Args:\n path: Server path (e.g., /context7)\n proxy_pass_url: Internal backend URL\n mcp_endpoint: Custom endpoint override\n base_url: Base URL from request (e.g., https://mcpgateway.ddns.net)\n\n Returns:\n The computed endpoint URL, or None if not determinable\n \"\"\"\n # Priority 1: Explicit mcp_endpoint override\n if mcp_endpoint:\n return mcp_endpoint\n\n # Priority 2: In registry-only mode, use proxy_pass_url directly\n if settings.deployment_mode == DeploymentMode.REGISTRY_ONLY:\n return proxy_pass_url\n\n # Priority 3: Construct gateway URL\n if base_url:\n clean_path = path.rstrip(\"/\")\n if not clean_path.startswith(\"/\"):\n clean_path = f\"/{clean_path}\"\n return f\"{base_url}{clean_path}/mcp\"\n\n # Fallback: return proxy_pass_url if nothing else works\n return proxy_pass_url\n\n\nclass ServerSearchResult(BaseModel):\n path: str\n server_name: str\n description: str | None = None\n tags: list[str] = Field(default_factory=list)\n num_tools: int = 0\n is_enabled: bool = False\n relevance_score: float = Field(..., ge=0.0, le=1.0)\n match_context: str | None = None\n matching_tools: list[MatchingToolResult] = Field(default_factory=list)\n sync_metadata: SyncMetadata | None = None\n # Endpoint URL for agent connectivity (computed based on deployment mode)\n endpoint_url: str | None = Field(\n default=None, description=\"URL for agents to connect to this MCP server\"\n )\n # Raw endpoint fields (for advanced use cases)\n proxy_pass_url: str | None = Field(\n default=None, description=\"Base URL for the MCP server backend (internal)\"\n )\n mcp_endpoint: str | None = Field(\n default=None, description=\"Explicit streamable-http endpoint URL (if set)\"\n )\n sse_endpoint: str | None = Field(default=None, description=\"Explicit SSE endpoint URL (if set)\")\n supported_transports: list[str] = Field(\n default_factory=list, description=\"Supported transport types (e.g., streamable-http, sse)\"\n )\n trust_verified: str = Field(\n default=\"none\",\n description=\"Trust verification status: none, verified, expired, revoked, not_found, pending\",\n )\n\n\nclass ToolSearchResult(BaseModel):\n server_path: str\n server_name: str\n tool_name: str\n description: str | None = None\n inputSchema: dict | None = Field(default=None, description=\"JSON Schema for tool input\")\n relevance_score: float = Field(..., ge=0.0, le=1.0)\n match_context: str | None = None\n # Endpoint URL for the parent MCP server\n endpoint_url: str | None = Field(\n default=None, description=\"URL for agents to connect to the parent MCP server\"\n )\n\n\nclass AgentSearchResult(BaseModel):\n \"\"\"Agent search result with minimal top-level fields to avoid duplication.\n\n Only search-specific fields are at the top level. All agent details\n (name, description, url, skills, etc.) are in the agent_card.\n \"\"\"\n\n path: str = Field(..., description=\"Agent path for identification\")\n relevance_score: float = Field(..., ge=0.0, le=1.0)\n match_context: str | None = None\n agent_card: dict = Field(..., description=\"Full agent card with all details\")\n trust_verified: str = Field(\n default=\"none\",\n description=\"Trust verification status: none, verified, expired, revoked, not_found, pending\",\n )\n\n\nclass SkillSearchResult(BaseModel):\n path: str\n skill_name: str\n description: str | None = None\n tags: list[str] = Field(default_factory=list)\n skill_md_url: str | None = None\n skill_md_raw_url: str | None = None\n version: str | None = None\n author: str | None = None\n visibility: str | None = None\n owner: str | None = None\n is_enabled: bool = False\n health_status: Literal[\"healthy\", \"unhealthy\", \"unknown\"] = \"unknown\"\n last_checked_time: str | None = None\n status: str = Field(default=\"active\", description=\"Lifecycle status\")\n relevance_score: float = Field(..., ge=0.0, le=1.0)\n match_context: str | None = None\n\n\nclass VirtualServerSearchResult(BaseModel):\n path: str\n server_name: str\n description: str | None = None\n tags: list[str] = Field(default_factory=list)\n num_tools: int = 0\n backend_count: int = 0\n backend_paths: list[str] = Field(default_factory=list)\n is_enabled: bool = False\n relevance_score: float = Field(..., ge=0.0, le=1.0)\n match_context: str | None = None\n matching_tools: list[MatchingToolResult] = Field(default_factory=list)\n # Endpoint URL for agent connectivity (computed based on deployment mode)\n endpoint_url: str | None = Field(\n default=None, description=\"URL for agents to connect to this virtual MCP server\"\n )\n\n\nclass SemanticSearchRequest(BaseModel):\n query: str = Field(\n default=\"\",\n max_length=512,\n description=\"Natural language query. Can be empty when filtering by tags only.\",\n )\n entity_types: list[EntityType] | None = Field(\n default=None, description=\"Optional entity filters\"\n )\n tags: list[str] | None = Field(\n default=None,\n description=\"Exact tag filters. Only return entities that have ALL specified tags.\",\n )\n max_results: int = Field(\n default=10, ge=1, le=50, description=\"Maximum results per entity collection\"\n )\n include_draft: bool = Field(\n default=False,\n description=\"Include draft assets in search results\",\n )\n include_deprecated: bool = Field(\n default=False,\n description=\"Include deprecated assets in search results\",\n )\n include_disabled: bool = Field(\n default=False,\n description=\"Include disabled assets (is_enabled=False) in search results\",\n )\n\n\nclass SemanticSearchResponse(BaseModel):\n query: str\n search_mode: str = Field(\n default=\"hybrid\", description=\"Search mode: 'hybrid' (semantic+lexical) or 'lexical-only'\"\n )\n servers: list[ServerSearchResult] = Field(default_factory=list)\n tools: list[ToolSearchResult] = Field(default_factory=list)\n agents: list[AgentSearchResult] = Field(default_factory=list)\n skills: list[SkillSearchResult] = Field(default_factory=list)\n virtual_servers: list[VirtualServerSearchResult] = Field(default_factory=list)\n total_servers: int = 0\n total_tools: int = 0\n total_agents: int = 0\n total_skills: int = 0\n total_virtual_servers: int = 0\n\n\nasync def _get_tool_schema_for_virtual_server(\n vs_path: str,\n tool_name: str,\n) -> dict | None:\n \"\"\"Look up tool schema from backend server for a virtual server's tool.\n\n Args:\n vs_path: Virtual server path\n tool_name: Name of the tool to look up (can be the original name or alias)\n\n Returns:\n Tool inputSchema dict if found, None otherwise\n \"\"\"\n try:\n vs_service = get_virtual_server_service()\n vs_config = await vs_service.get_virtual_server(vs_path)\n\n if not vs_config:\n return None\n\n # Find the tool mapping for this tool (check both tool_name and alias)\n tool_mapping = None\n for tm in vs_config.tool_mappings:\n if tm.tool_name == tool_name or tm.alias == tool_name:\n tool_mapping = tm\n break\n\n if not tool_mapping:\n return None\n\n # Get the backend server info\n backend_path = tool_mapping.backend_server_path\n if tool_mapping.backend_version:\n backend_path = f\"{backend_path}:{tool_mapping.backend_version}\"\n\n server_info = await server_service.get_server_info(backend_path)\n if not server_info:\n return None\n\n # Find the tool in the backend's tool list using the original tool name\n tool_list = server_info.get(\"tool_list\", [])\n for tool in tool_list:\n if tool.get(\"name\") == tool_mapping.tool_name:\n return tool.get(\"schema\") or tool.get(\"inputSchema\")\n\n return None\n except Exception as e:\n logger.warning(f\"Failed to get tool schema for {vs_path}/{tool_name}: {e}\")\n return None\n\n\nasync def _user_can_access_server(path: str, server_name: str, user_context: dict) -> bool:\n \"\"\"Validate whether the current user can view the specified server.\"\"\"\n if user_context.get(\"is_admin\"):\n return True\n\n accessible_servers = user_context.get(\"accessible_servers\") or []\n if \"all\" in accessible_servers:\n return True\n\n if not accessible_servers:\n return False\n\n try:\n if await server_service.user_can_access_server_path(path, accessible_servers):\n return True\n except Exception:\n # Fall through to string comparisons if server lookup failed\n logger.debug(\"Unable to validate server path via service for %s\", path, exc_info=True)\n\n technical_name = path.strip(\"/\")\n return technical_name in accessible_servers or (\n server_name and server_name in accessible_servers\n )\n\n\nasync def _user_can_access_agent(agent_path: str, user_context: dict) -> bool:\n \"\"\"Validate user access for a given agent.\"\"\"\n if user_context.get(\"is_admin\"):\n return True\n\n accessible_agents = user_context.get(\"accessible_agents\") or []\n if \"all\" not in accessible_agents and agent_path not in accessible_agents:\n return False\n\n agent_card = await agent_service.get_agent_info(agent_path)\n if not agent_card:\n return False\n\n if agent_card.visibility == \"public\":\n return True\n\n if agent_card.visibility == \"private\":\n return agent_card.registered_by == user_context.get(\"username\")\n\n if agent_card.visibility == \"group-restricted\":\n allowed_groups = set(agent_card.allowed_groups)\n user_groups = set(user_context.get(\"groups\", []))\n return bool(allowed_groups & user_groups)\n\n return False\n\n\nasync def _user_can_access_skill(\n skill_path: str,\n visibility: str,\n owner: str,\n allowed_groups: list,\n user_context: dict,\n) -> bool:\n \"\"\"Validate user access for a given skill based on visibility.\n\n Args:\n skill_path: The skill path\n visibility: Skill visibility (public, private, group)\n owner: Skill owner username\n allowed_groups: Groups allowed to access the skill\n user_context: User context with username, groups, is_admin\n\n Returns:\n True if user can access the skill, False otherwise\n \"\"\"\n if user_context.get(\"is_admin\"):\n return True\n\n if visibility == \"public\":\n return True\n\n if visibility == \"private\":\n return owner == user_context.get(\"username\")\n\n if visibility == \"group\":\n user_groups = set(user_context.get(\"groups\", []))\n skill_groups = set(allowed_groups or [])\n return bool(user_groups & skill_groups)\n\n return False\n\n\ndef _compute_trust_verified(\n ans_metadata: dict | None,\n) -> str:\n \"\"\"Derive the trust_verified label from ANS metadata.\n\n Args:\n ans_metadata: ANS metadata dict from the agent card, or None.\n\n Returns:\n \"none\" when there is no ANS metadata, otherwise the ANS status\n value (verified, expired, revoked, not_found, pending).\n \"\"\"\n if not ans_metadata:\n return \"none\"\n\n return ans_metadata.get(\"status\", \"none\")\n\n\n_HASHTAG_PATTERN = re.compile(r\"#([\\w-]+)\")\n\n\ndef _parse_hashtags(\n query: str,\n) -> tuple[str, list[str]]:\n \"\"\"Extract #tag tokens from the query string.\n\n Returns:\n Tuple of (remaining_query, extracted_tags).\n Tags are lowercased for case-insensitive matching.\n \"\"\"\n tags = [m.group(1).lower() for m in _HASHTAG_PATTERN.finditer(query)]\n remaining = _HASHTAG_PATTERN.sub(\"\", query).strip()\n # Collapse multiple spaces left after removal\n remaining = re.sub(r\"\\s+\", \" \", remaining).strip()\n return remaining, tags\n\n\ndef _entity_has_all_tags(\n entity_tags: list[str],\n required_tags: list[str],\n) -> bool:\n \"\"\"Check if an entity has ALL required tags (case-insensitive).\"\"\"\n entity_tags_lower = {t.lower() for t in entity_tags}\n return all(tag in entity_tags_lower for tag in required_tags)\n\n\n@router.post(\n \"/semantic\",\n response_model=SemanticSearchResponse,\n summary=\"Unified semantic search for MCP servers and tools\",\n)\nasync def semantic_search(\n http_request: Request,\n request: SemanticSearchRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n search_repo: SearchRepositoryBase = Depends(get_search_repo),\n) -> SemanticSearchResponse:\n \"\"\"\n Run a semantic search against MCP servers (and their tools) using FAISS embeddings.\n \"\"\"\n # Parse #tag tokens from query for exact tag matching\n search_query, hashtag_tags = _parse_hashtags(request.query)\n\n # Merge hashtag-extracted tags with explicitly provided tags\n required_tags: list[str] = list({t.lower() for t in (request.tags or []) + hashtag_tags})\n\n # Set audit action for search\n set_audit_action(\n http_request, \"search\", \"search\", description=f\"Semantic search: {request.query[:50]}...\"\n )\n\n logger.info(\n \"Semantic search requested by %s (entities=%s, max=%s, tags=%s)\",\n user_context.get(\"username\"),\n request.entity_types or [\"mcp_server\", \"tool\"],\n request.max_results,\n required_tags or None,\n )\n\n # Determine the effective text query after removing #tag tokens\n effective_query = search_query.strip()\n\n # Validate: must have either a text query or tags\n if not effective_query and not required_tags:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Provide a search query, tags, or both.\",\n )\n\n try:\n if not effective_query and required_tags:\n # Tag-only search: query DB directly by tags\n raw_results = await search_repo.search_by_tags(\n tags=required_tags,\n entity_types=request.entity_types,\n max_results=request.max_results,\n include_draft=request.include_draft,\n include_deprecated=request.include_deprecated,\n include_disabled=request.include_disabled,\n )\n else:\n # Text search (possibly combined with tags filtered after)\n raw_results = await search_repo.search(\n query=effective_query,\n entity_types=request.entity_types,\n max_results=request.max_results,\n include_draft=request.include_draft,\n include_deprecated=request.include_deprecated,\n include_disabled=request.include_disabled,\n )\n except ValueError as exc:\n raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc\n except RuntimeError as exc:\n logger.error(\"FAISS search service unavailable: %s\", exc, exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_503_SERVICE_UNAVAILABLE,\n detail=\"Semantic search is temporarily unavailable. Please try again later.\",\n ) from exc\n\n # Extract base URL from request for endpoint URL computation\n # Use X-Forwarded-Proto and X-Forwarded-Host if behind proxy, otherwise use request URL\n forwarded_proto = http_request.headers.get(\"x-forwarded-proto\", \"https\")\n forwarded_host = http_request.headers.get(\"x-forwarded-host\") or http_request.headers.get(\n \"host\"\n )\n if forwarded_host:\n base_url = f\"{forwarded_proto}://{forwarded_host}\"\n else:\n base_url = str(http_request.base_url).rstrip(\"/\")\n\n filtered_servers: list[ServerSearchResult] = []\n for server in raw_results.get(\"servers\", []):\n if not await _user_can_access_server(\n server.get(\"path\", \"\"),\n server.get(\"server_name\", \"\"),\n user_context,\n ):\n continue\n\n matching_tools = [\n MatchingToolResult(\n tool_name=tool.get(\"tool_name\", \"\"),\n description=tool.get(\"description\"),\n relevance_score=tool.get(\"relevance_score\", 0.0),\n match_context=tool.get(\"match_context\"),\n )\n for tool in server.get(\"matching_tools\", [])\n ]\n\n # Parse sync_metadata if present\n raw_sync = server.get(\"sync_metadata\")\n sync_meta = SyncMetadata(**raw_sync) if raw_sync else None\n\n # Compute endpoint URL based on deployment mode\n server_path = server.get(\"path\", \"\")\n server_proxy_url = server.get(\"proxy_pass_url\")\n server_mcp_endpoint = server.get(\"mcp_endpoint\")\n endpoint_url = _compute_endpoint_url(\n path=server_path,\n proxy_pass_url=server_proxy_url,\n mcp_endpoint=server_mcp_endpoint,\n base_url=base_url,\n )\n\n # Look up ANS metadata from server info for trust verification\n server_full_info = await server_service.get_server_info(server_path)\n server_ans_meta = server_full_info.get(\"ans_metadata\") if server_full_info else None\n server_trust = _compute_trust_verified(server_ans_meta)\n\n filtered_servers.append(\n ServerSearchResult(\n path=server_path,\n server_name=server.get(\"server_name\", \"\"),\n description=server.get(\"description\"),\n tags=server.get(\"tags\", []),\n num_tools=server.get(\"num_tools\", 0),\n is_enabled=server.get(\"is_enabled\", False),\n relevance_score=server.get(\"relevance_score\", 0.0),\n match_context=server.get(\"match_context\"),\n matching_tools=matching_tools,\n sync_metadata=sync_meta,\n endpoint_url=endpoint_url,\n proxy_pass_url=server_proxy_url,\n mcp_endpoint=server_mcp_endpoint,\n sse_endpoint=server.get(\"sse_endpoint\"),\n supported_transports=server.get(\"supported_transports\", []),\n trust_verified=server_trust,\n )\n )\n\n # Build a map of server_path -> endpoint_url for tool results\n server_endpoint_map: dict[str, str | None] = {\n server.path: server.endpoint_url for server in filtered_servers\n }\n\n filtered_tools: list[ToolSearchResult] = []\n for tool in raw_results.get(\"tools\", []):\n server_path = tool.get(\"server_path\", \"\")\n server_name = tool.get(\"server_name\", \"\")\n if not await _user_can_access_server(server_path, server_name, user_context):\n continue\n\n # Get endpoint_url from filtered servers, or compute it if not available\n tool_endpoint_url = server_endpoint_map.get(server_path)\n if tool_endpoint_url is None:\n # Server not in filtered results, compute endpoint_url\n tool_endpoint_url = _compute_endpoint_url(\n path=server_path,\n proxy_pass_url=None, # We don't have this info for tools\n mcp_endpoint=None,\n base_url=base_url,\n )\n\n filtered_tools.append(\n ToolSearchResult(\n server_path=server_path,\n server_name=server_name,\n tool_name=tool.get(\"tool_name\", \"\"),\n description=tool.get(\"description\"),\n inputSchema=tool.get(\"inputSchema\"),\n relevance_score=tool.get(\"relevance_score\", 0.0),\n match_context=tool.get(\"match_context\"),\n endpoint_url=tool_endpoint_url,\n )\n )\n\n filtered_agents: list[AgentSearchResult] = []\n for agent in raw_results.get(\"agents\", []):\n agent_path = agent.get(\"path\", \"\")\n if not agent_path:\n continue\n\n if not await _user_can_access_agent(agent_path, user_context):\n continue\n\n agent_card_obj = await agent_service.get_agent_info(agent_path)\n agent_card_dict = (\n agent_card_obj.model_dump() if agent_card_obj else agent.get(\"agent_card\", {})\n )\n\n # Ensure agent_card has the path for consistency\n if agent_card_dict and \"path\" not in agent_card_dict:\n agent_card_dict[\"path\"] = agent_path\n\n # Compute trust verification status from ANS metadata\n ans_meta = agent_card_dict.get(\"ans_metadata\") if agent_card_dict else None\n trust_verified = _compute_trust_verified(ans_meta)\n\n filtered_agents.append(\n AgentSearchResult(\n path=agent_path,\n relevance_score=agent.get(\"relevance_score\", 0.0),\n match_context=agent.get(\"match_context\") or agent_card_dict.get(\"description\"),\n agent_card=agent_card_dict or {},\n trust_verified=trust_verified,\n )\n )\n\n filtered_skills: list[SkillSearchResult] = []\n for skill in raw_results.get(\"skills\", []):\n skill_path = skill.get(\"path\", \"\")\n if not skill_path:\n continue\n\n visibility = skill.get(\"visibility\", \"public\")\n owner = skill.get(\"owner\", \"\")\n allowed_groups = skill.get(\"allowed_groups\", [])\n\n if not await _user_can_access_skill(\n skill_path, visibility, owner, allowed_groups, user_context\n ):\n continue\n\n filtered_skills.append(\n SkillSearchResult(\n path=skill_path,\n skill_name=skill.get(\"skill_name\", skill_path.strip(\"/\")),\n description=skill.get(\"description\"),\n tags=skill.get(\"tags\", []),\n skill_md_url=skill.get(\"skill_md_url\"),\n skill_md_raw_url=skill.get(\"skill_md_raw_url\"),\n version=skill.get(\"version\"),\n author=skill.get(\"author\"),\n visibility=visibility,\n owner=owner,\n is_enabled=skill.get(\"is_enabled\", False),\n health_status=skill.get(\"health_status\", \"unknown\"),\n last_checked_time=skill.get(\"last_checked_time\"),\n status=skill.get(\"status\", \"active\"),\n relevance_score=skill.get(\"relevance_score\", 0.0),\n match_context=skill.get(\"match_context\"),\n )\n )\n\n # Process virtual servers\n filtered_virtual_servers: list[VirtualServerSearchResult] = []\n for vs in raw_results.get(\"virtual_servers\", []):\n vs_path = vs.get(\"path\", \"\")\n if not vs_path:\n continue\n\n # Virtual servers use the same access control as regular servers\n if not await _user_can_access_server(\n vs_path,\n vs.get(\"server_name\", \"\"),\n user_context,\n ):\n continue\n\n # Build matching tools with schema lookup from backend servers\n # Only include tools that matched the search query\n matching_tools: list[MatchingToolResult] = []\n for tool in vs.get(\"matching_tools\", []):\n tool_name = tool.get(\"tool_name\", \"\")\n # Look up the tool schema from the backend server\n input_schema = await _get_tool_schema_for_virtual_server(vs_path, tool_name)\n matching_tools.append(\n MatchingToolResult(\n tool_name=tool_name,\n description=tool.get(\"description\"),\n relevance_score=tool.get(\"relevance_score\", 0.0),\n match_context=tool.get(\"match_context\"),\n inputSchema=input_schema,\n )\n )\n\n # Compute endpoint URL for virtual server\n vs_endpoint_url = _compute_endpoint_url(\n path=vs_path,\n proxy_pass_url=None, # Virtual servers don't have proxy_pass_url\n mcp_endpoint=None,\n base_url=base_url,\n )\n\n metadata = vs.get(\"metadata\", {})\n filtered_virtual_servers.append(\n VirtualServerSearchResult(\n path=vs_path,\n server_name=vs.get(\"server_name\", \"\"),\n description=vs.get(\"description\"),\n tags=vs.get(\"tags\", []),\n num_tools=metadata.get(\"num_tools\", 0),\n backend_count=metadata.get(\"backend_count\", 0),\n backend_paths=metadata.get(\"backend_paths\", []),\n is_enabled=vs.get(\"is_enabled\", False),\n relevance_score=vs.get(\"relevance_score\", 0.0),\n match_context=vs.get(\"match_context\"),\n matching_tools=matching_tools,\n endpoint_url=vs_endpoint_url,\n )\n )\n\n # Filter results by required tags (from #tag syntax or explicit tags param)\n if required_tags:\n filtered_servers = [\n s for s in filtered_servers if _entity_has_all_tags(s.tags, required_tags)\n ]\n filtered_tools = [\n t\n for t in filtered_tools\n if _entity_has_all_tags(\n # Tools don't have tags directly; filter by parent server tags\n next(\n (s.tags for s in filtered_servers if s.path == t.server_path),\n [],\n ),\n required_tags,\n )\n ]\n filtered_agents = [\n a\n for a in filtered_agents\n if _entity_has_all_tags(\n a.agent_card.get(\"tags\", []),\n required_tags,\n )\n ]\n filtered_skills = [\n s for s in filtered_skills if _entity_has_all_tags(s.tags, required_tags)\n ]\n filtered_virtual_servers = [\n vs for vs in filtered_virtual_servers if _entity_has_all_tags(vs.tags, required_tags)\n ]\n\n # Filter results based on registry mode\n # In skills-only mode, only return skills; in servers-only mode, only return servers, etc.\n mode = settings.registry_mode\n\n if mode == RegistryMode.SKILLS_ONLY:\n # Only skills are enabled\n filtered_servers = []\n filtered_tools = []\n filtered_agents = []\n filtered_virtual_servers = []\n elif mode == RegistryMode.MCP_SERVERS_ONLY:\n # Only servers, tools, and virtual servers are enabled\n filtered_agents = []\n filtered_skills = []\n elif mode == RegistryMode.AGENTS_ONLY:\n # Only agents are enabled\n filtered_servers = []\n filtered_tools = []\n filtered_skills = []\n filtered_virtual_servers = []\n # In FULL mode, return all results (no filtering needed)\n\n # Increment semantic search counter (fail-silent)\n from registry.repositories.stats_repository import increment_search_counter\n\n await increment_search_counter()\n\n return SemanticSearchResponse(\n query=request.query.strip(),\n servers=filtered_servers,\n tools=filtered_tools,\n agents=filtered_agents,\n skills=filtered_skills,\n virtual_servers=filtered_virtual_servers,\n total_servers=len(filtered_servers),\n total_tools=len(filtered_tools),\n total_agents=len(filtered_agents),\n total_skills=len(filtered_skills),\n total_virtual_servers=len(filtered_virtual_servers),\n )\n\n\n@router.get(\n \"/tags\",\n summary=\"Get all unique tags across all indexed entities\",\n)\nasync def get_all_tags(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n search_repo: SearchRepositoryBase = Depends(get_search_repo),\n) -> dict[str, list[str]]:\n \"\"\"Return a sorted list of all unique tags across servers, agents, skills, and virtual servers.\"\"\"\n try:\n tags = await search_repo.get_all_tags()\n return {\"tags\": tags}\n except Exception as e:\n logger.error(\"Failed to retrieve tags: %s\", e, exc_info=True)\n return {\"tags\": []}\n" }, { "path": "registry/api/server_routes.py", "content": "import asyncio\nimport json\nimport logging\nimport os\nfrom typing import Annotated\n\nimport httpx\nfrom fastapi import APIRouter, Cookie, Depends, Form, HTTPException, Query, Request, status\nfrom fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse\nfrom fastapi.templating import Jinja2Templates\nfrom pydantic import BaseModel\n\nfrom ..audit import set_audit_action\nfrom ..auth.csrf import generate_csrf_token, verify_csrf_token_flexible\nfrom ..auth.dependencies import enhanced_auth, nginx_proxied_auth\nfrom ..auth.internal import validate_internal_auth\nfrom ..constants import VALID_AUTH_SCHEMES\nfrom ..core.config import DeploymentMode, settings\nfrom ..core.schemas import AuthCredentialUpdateRequest\nfrom ..services.security_scanner import security_scanner_service\nfrom ..services.server_service import server_service\nfrom ..services.registration_gate_service import check_registration_gate\nfrom ..services.webhook_service import send_registration_webhook\nfrom ..utils.credential_encryption import encrypt_credential_in_server_dict\nfrom ..utils.metadata import flatten_metadata_to_text\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n\nclass RatingRequest(BaseModel):\n rating: int\n\n\n# Templates\ntemplates = Jinja2Templates(directory=settings.templates_dir)\n\n\ndef _build_scan_headers_from_credentials(\n server_info: dict,\n) -> str | None:\n \"\"\"Build headers JSON for the security scanner from stored server credentials.\n\n Decrypts the stored credential and formats it as a JSON headers string\n that the scanner's _extract_bearer_token_from_headers() expects.\n\n Args:\n server_info: Server info dict with include_credentials=True.\n\n Returns:\n JSON string with X-Authorization header, or None if no credentials.\n \"\"\"\n auth_scheme = server_info.get(\"auth_scheme\", \"none\")\n encrypted_credential = server_info.get(\"auth_credential_encrypted\")\n\n if auth_scheme == \"none\" or not encrypted_credential:\n return None\n\n from ..utils.credential_encryption import decrypt_credential\n\n credential = decrypt_credential(encrypted_credential)\n if not credential:\n logger.warning(\n f\"Could not decrypt credential for '{server_info.get('path', 'unknown')}'. \"\n f\"Security scan will proceed without auth.\"\n )\n return None\n\n if auth_scheme == \"bearer\":\n header_name = server_info.get(\"auth_header_name\", \"Authorization\")\n headers_dict = {\"X-Authorization\": f\"Bearer {credential}\"}\n logger.info(\n f\"Passing bearer token to security scanner for '{server_info.get('path', 'unknown')}'\"\n )\n return json.dumps(headers_dict)\n elif auth_scheme == \"api_key\":\n header_name = server_info.get(\"auth_header_name\", \"X-API-Key\")\n headers_dict = {\"X-Authorization\": f\"Bearer {credential}\"}\n logger.info(\n f\"Passing API key as bearer token to security scanner for \"\n f\"'{server_info.get('path', 'unknown')}'\"\n )\n return json.dumps(headers_dict)\n\n return None\n\n\nasync def _perform_security_scan_on_registration(\n path: str,\n proxy_pass_url: str,\n server_entry: dict,\n headers_list: list | None = None,\n) -> None:\n \"\"\"Perform security scan on newly registered server.\n\n Handles the complete security scan workflow including:\n - Running the security scan with configured analyzers\n - Adding security-pending tag if scan fails\n - Disabling server if configured and scan fails\n - Updating FAISS and regenerating Nginx config if server disabled\n\n All scan failures are non-fatal and will be logged but not raised.\n\n Args:\n path: Server path (e.g., /mcpgw)\n proxy_pass_url: URL to scan\n server_entry: Server metadata dictionary\n headers_list: Optional headers for authenticated endpoints\n \"\"\"\n scan_config = security_scanner_service.get_scan_config()\n if not (scan_config.enabled and scan_config.scan_on_registration):\n return\n\n logger.info(f\"Running security scan for newly registered server: {path}\")\n\n try:\n # Prepare headers if needed (for authenticated endpoints)\n headers_json = None\n if headers_list:\n headers_json = json.dumps(headers_list)\n\n # If no explicit headers, try to build from stored credentials\n if not headers_json:\n headers_json = _build_scan_headers_from_credentials(server_entry)\n\n # Run the security scan\n scan_result = await security_scanner_service.scan_server(\n server_url=proxy_pass_url,\n server_path=path,\n analyzers=scan_config.analyzers,\n api_key=scan_config.llm_api_key,\n headers=headers_json,\n timeout=scan_config.scan_timeout_seconds,\n mcp_endpoint=server_entry.get(\"mcp_endpoint\"),\n )\n\n # Handle unsafe servers\n if not scan_result.is_safe:\n logger.warning(\n f\"Server {path} failed security scan. \"\n f\"Critical: {scan_result.critical_issues}, High: {scan_result.high_severity}\"\n )\n\n # Add security-pending tag if configured\n if scan_config.add_security_pending_tag:\n current_tags = server_entry.get(\"tags\", [])\n if \"security-pending\" not in current_tags:\n current_tags.append(\"security-pending\")\n server_entry[\"tags\"] = current_tags\n await server_service.update_server(path, server_entry)\n logger.info(f\"Added 'security-pending' tag to {path}\")\n\n # Disable server if configured\n if scan_config.block_unsafe_servers:\n from ..core.nginx_service import nginx_service\n from ..repositories.factory import get_search_repository\n\n await server_service.toggle_service(path, False)\n logger.warning(f\"Disabled server {path} due to failed security scan\")\n\n # Update search index with disabled state\n search_repo = get_search_repository()\n await search_repo.index_server(path, server_entry, is_enabled=False)\n\n # Regenerate Nginx config to remove disabled server\n enabled_servers = {}\n\n for server_path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(server_path)\n\n if server_info:\n enabled_servers[server_path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n else:\n logger.info(f\"Server {path} passed security scan\")\n\n except Exception as e:\n logger.error(f\"Security scan failed for {path}: {e}\")\n # Non-fatal error - server is registered but scan failed\n\n\n@router.get(\"/\", response_class=HTMLResponse)\nasync def read_root(\n request: Request,\n query: str | None = None,\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n):\n \"\"\"Main dashboard page showing services based on user permissions.\"\"\"\n # Check authentication first and redirect if not authenticated\n if not session:\n logger.info(\"No session cookie at root route, redirecting to login\")\n return RedirectResponse(url=\"/login\", status_code=302)\n\n try:\n # Get user context\n user_context = enhanced_auth(session)\n except HTTPException as e:\n logger.info(f\"Authentication failed at root route: {e.detail}, redirecting to login\")\n return RedirectResponse(url=\"/login\", status_code=302)\n\n from ..auth.dependencies import user_has_ui_permission_for_service\n\n # Helper function for templates\n def can_perform_action(permission: str, service_name: str) -> bool:\n \"\"\"Check if user has UI permission for a specific service\"\"\"\n return user_has_ui_permission_for_service(\n permission, service_name, user_context.get(\"ui_permissions\", {})\n )\n\n service_data = []\n search_query = query.lower() if query else \"\"\n\n # Get servers based on user permissions\n if user_context[\"is_admin\"]:\n # Admin users see all servers\n all_servers = await server_service.get_all_servers()\n logger.info(\n f\"Admin user {user_context['username']} accessing all {len(all_servers)} servers\"\n )\n else:\n # Filtered users see only accessible servers\n all_servers = await server_service.get_all_servers_with_permissions(\n user_context[\"accessible_servers\"]\n )\n all_servers_count = await server_service.get_all_servers()\n logger.info(\n f\"User {user_context['username']} accessing {len(all_servers)} of {len(all_servers_count)} total servers\"\n )\n\n sorted_server_paths = sorted(all_servers.keys(), key=lambda p: all_servers[p][\"server_name\"])\n\n # Filter services based on UI permissions\n accessible_services = user_context.get(\"accessible_services\", [])\n # Normalize accessible_services by stripping slashes for comparison\n normalized_accessible_services = [s.strip(\"/\") for s in accessible_services]\n logger.info(\n f\"DEBUG: User {user_context['username']} accessible_services: {accessible_services}\"\n )\n logger.info(\n f\"DEBUG: User {user_context['username']} ui_permissions: {user_context.get('ui_permissions', {})}\"\n )\n logger.info(f\"DEBUG: User {user_context['username']} scopes: {user_context.get('scopes', [])}\")\n\n for path in sorted_server_paths:\n server_info = all_servers[path]\n server_name = server_info[\"server_name\"]\n # Extract technical name from path (remove leading and trailing slashes)\n technical_name = path.strip(\"/\")\n\n # Check if user can list this service using technical name\n if (\n \"all\" not in accessible_services\n and technical_name not in normalized_accessible_services\n ):\n logger.debug(\n f\"Filtering out service '{server_name}' (path={path}) - user doesn't have list_service permission\"\n )\n continue\n\n # Include description, tags, and metadata in search\n server_metadata = server_info.get(\"metadata\", {})\n metadata_text = flatten_metadata_to_text(server_metadata) if server_metadata else \"\"\n searchable_text = (\n f\"{server_name.lower()} \"\n f\"{server_info.get('description', '').lower()} \"\n f\"{' '.join(server_info.get('tags', []))} \"\n f\"{metadata_text.lower()}\"\n )\n if not search_query or search_query in searchable_text:\n # Fetch enabled status before health check to avoid race condition (Issue #612)\n is_enabled = await server_service.is_service_enabled(path)\n\n # Get real health status from health service\n from ..health.service import health_service\n\n health_data = health_service._get_service_health_data(\n path,\n {**server_info, \"is_enabled\": is_enabled},\n )\n\n # Normalize health status to enum values only (strip error messages)\n raw_status = health_data[\"status\"]\n if isinstance(raw_status, str):\n if \"unhealthy\" in raw_status.lower():\n normalized_status = \"unhealthy\"\n elif \"healthy\" in raw_status.lower():\n normalized_status = \"healthy\"\n elif \"disabled\" in raw_status.lower():\n normalized_status = \"disabled\"\n elif \"checking\" in raw_status.lower():\n normalized_status = \"unknown\"\n elif \"error\" in raw_status.lower():\n normalized_status = \"unhealthy\"\n else:\n normalized_status = raw_status\n else:\n normalized_status = raw_status\n\n service_data.append(\n {\n \"display_name\": server_name,\n \"path\": path,\n \"description\": server_info.get(\"description\", \"\"),\n \"proxy_pass_url\": server_info.get(\"proxy_pass_url\", \"\"),\n \"is_enabled\": is_enabled,\n \"tags\": server_info.get(\"tags\", []),\n \"num_tools\": server_info.get(\"num_tools\", 0),\n \"license\": server_info.get(\"license\", \"N/A\"),\n \"health_status\": normalized_status,\n \"last_checked_iso\": health_data[\"last_checked_iso\"],\n \"mcp_endpoint\": server_info.get(\"mcp_endpoint\"),\n }\n )\n\n return templates.TemplateResponse(\n \"index.html\",\n {\n \"request\": request,\n \"services\": service_data,\n \"username\": user_context[\"username\"],\n \"user_context\": user_context, # Pass full user context to template\n \"can_perform_action\": can_perform_action, # Helper function for permission checks\n \"csrf_token\": generate_csrf_token(session) if session else \"\",\n },\n )\n\n\n@router.get(\"/servers\")\nasync def get_servers_json(\n request: Request,\n query: str | None = Query(\n None,\n description=\"Lexical substring search across server name, description, tags, and metadata\",\n ),\n limit: int = Query(20, ge=1, le=500, description=\"Number of servers to return (max 500)\"),\n offset: int = Query(0, ge=0, description=\"Number of servers to skip\"),\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"Get servers data as JSON for React frontend and external API.\n\n Uses lexical (substring) search, not hybrid/semantic. For vector-based\n search, use POST /api/search/semantic instead.\n \"\"\"\n logger.debug(f\"get_servers_json called: limit={limit}, offset={offset}, query={query!r}\")\n\n # Set audit action for server list\n set_audit_action(request, \"list\", \"server\", description=\"List all servers\")\n\n # CRITICAL DIAGNOSTIC: Log user_context received by endpoint\n logger.debug(f\"[GET_SERVERS_DEBUG] Received user_context: {user_context}\")\n logger.debug(f\"[GET_SERVERS_DEBUG] user_context type: {type(user_context)}\")\n if user_context:\n logger.debug(f\"[GET_SERVERS_DEBUG] Username: {user_context.get('username', 'NOT PRESENT')}\")\n logger.debug(f\"[GET_SERVERS_DEBUG] Scopes: {user_context.get('scopes', 'NOT PRESENT')}\")\n logger.debug(\n f\"[GET_SERVERS_DEBUG] Auth method: {user_context.get('auth_method', 'NOT PRESENT')}\"\n )\n\n service_data = []\n search_query = query.lower() if query else \"\"\n\n # Determine if user has unrestricted access (no servers will be filtered out)\n is_admin = user_context.get(\"is_admin\", False) if user_context else False\n accessible_servers_list = user_context.get(\"accessible_servers\", []) if user_context else []\n accessible_services = user_context.get(\"accessible_services\", []) if user_context else []\n is_unrestricted = is_admin or \"all\" in accessible_servers_list or \"all\" in accessible_services\n has_field_filters = bool(query)\n\n # Dual-path pagination:\n # - Fast path: DB-level skip/limit for unrestricted users without field filters\n # - Fallback: full fetch + Python filter + slice for restricted users or when field filters active\n if is_unrestricted and not has_field_filters:\n # FAST PATH: DB-level pagination -- correct because no servers are filtered out\n # and no field filters need a full scan for accurate total_count\n all_servers, db_total = await server_service.get_servers_paginated(skip=offset, limit=limit)\n else:\n # FALLBACK PATH: full fetch needed\n if is_admin:\n all_servers = await server_service.get_all_servers()\n else:\n all_servers = await server_service.get_all_servers_with_permissions(\n accessible_servers_list\n )\n\n sorted_server_paths = sorted(all_servers.keys(), key=lambda p: all_servers[p][\"server_name\"])\n\n # Normalize accessible_services by stripping slashes for comparison\n normalized_accessible_services = [s.strip(\"/\") for s in accessible_services]\n\n for path in sorted_server_paths:\n server_info = all_servers[path]\n server_name = server_info[\"server_name\"]\n # Extract technical name from path (remove leading and trailing slashes)\n technical_name = path.strip(\"/\")\n\n # Check if user can list this service using technical name\n if (\n not is_unrestricted\n and \"all\" not in accessible_services\n and technical_name not in normalized_accessible_services\n ):\n continue\n\n # Include description, tags, and metadata in search\n server_metadata = server_info.get(\"metadata\", {})\n metadata_text = flatten_metadata_to_text(server_metadata) if server_metadata else \"\"\n searchable_text = (\n f\"{server_name.lower()} \"\n f\"{server_info.get('description', '').lower()} \"\n f\"{' '.join(server_info.get('tags', []))} \"\n f\"{metadata_text.lower()}\"\n )\n if not search_query or search_query in searchable_text:\n # Fetch enabled status before health check to avoid race condition (Issue #612)\n is_enabled = await server_service.is_service_enabled(path)\n\n # Get real health status from health service\n from ..health.service import health_service\n\n health_data = health_service._get_service_health_data(\n path,\n {**server_info, \"is_enabled\": is_enabled},\n )\n\n # Normalize health status to enum values only (strip error messages)\n raw_status = health_data[\"status\"]\n if isinstance(raw_status, str):\n if \"unhealthy\" in raw_status.lower():\n normalized_status = \"unhealthy\"\n elif \"healthy\" in raw_status.lower():\n normalized_status = \"healthy\"\n elif \"disabled\" in raw_status.lower():\n normalized_status = \"disabled\"\n elif \"checking\" in raw_status.lower():\n normalized_status = \"unknown\"\n elif \"error\" in raw_status.lower():\n normalized_status = \"unhealthy\"\n else:\n normalized_status = raw_status\n else:\n normalized_status = raw_status\n\n # Build versions list if this server has other versions\n versions = []\n current_version = server_info.get(\"version\", \"v1.0.0\")\n current_status = server_info.get(\"status\", \"stable\")\n\n # Add current (active) version first\n versions.append(\n {\n \"version\": current_version,\n \"proxy_pass_url\": server_info.get(\"proxy_pass_url\", \"\"),\n \"status\": current_status,\n \"is_default\": True,\n }\n )\n\n # Add other versions if they exist\n other_version_ids = server_info.get(\"other_version_ids\", [])\n for version_id in other_version_ids:\n version_info = await server_service.get_server_info(version_id)\n if version_info:\n versions.append(\n {\n \"version\": version_info.get(\"version\", \"unknown\"),\n \"proxy_pass_url\": version_info.get(\"proxy_pass_url\", \"\"),\n \"status\": version_info.get(\"status\", \"stable\"),\n \"is_default\": False,\n }\n )\n\n service_data.append(\n {\n \"id\": server_info.get(\"id\"),\n \"display_name\": server_name,\n \"path\": path,\n \"description\": server_info.get(\"description\", \"\"),\n \"proxy_pass_url\": server_info.get(\"proxy_pass_url\", \"\"),\n \"is_enabled\": is_enabled,\n \"tags\": server_info.get(\"tags\", []),\n \"num_tools\": server_info.get(\"num_tools\", 0),\n \"license\": server_info.get(\"license\", \"N/A\"),\n \"health_status\": normalized_status,\n \"last_checked_iso\": health_data[\"last_checked_iso\"],\n \"mcp_endpoint\": server_info.get(\"mcp_endpoint\"),\n \"metadata\": server_info.get(\"metadata\", {}),\n \"version\": current_version,\n \"versions\": versions if len(versions) > 1 else None,\n \"default_version\": current_version,\n \"mcp_server_version\": server_info.get(\"mcp_server_version\"),\n \"mcp_server_version_previous\": server_info.get(\"mcp_server_version_previous\"),\n \"mcp_server_version_updated_at\": server_info.get(\n \"mcp_server_version_updated_at\"\n ),\n \"sync_metadata\": server_info.get(\"sync_metadata\"),\n \"auth_scheme\": server_info.get(\"auth_scheme\", \"none\"),\n \"auth_header_name\": server_info.get(\"auth_header_name\"),\n \"tool_list\": server_info.get(\"tool_list\"),\n # Federation and lifecycle metadata\n \"status\": server_info.get(\"status\", \"active\"),\n \"provider_organization\": (\n server_info.get(\"provider\", {}).get(\"organization\")\n if isinstance(server_info.get(\"provider\"), dict)\n else None\n ),\n \"provider_url\": (\n server_info.get(\"provider\", {}).get(\"url\")\n if isinstance(server_info.get(\"provider\"), dict)\n else None\n ),\n \"source_created_at\": server_info.get(\"source_created_at\"),\n \"source_updated_at\": server_info.get(\"source_updated_at\"),\n \"registered_at\": server_info.get(\"registered_at\"),\n \"updated_at\": server_info.get(\"updated_at\"),\n \"ans_metadata\": server_info.get(\"ans_metadata\"),\n \"num_stars\": server_info.get(\"num_stars\", 0),\n \"rating_details\": server_info.get(\"rating_details\", []),\n }\n )\n\n # Compute pagination metadata\n if is_unrestricted and not has_field_filters:\n # Fast path: total from DB, servers already paginated\n total_count = db_total\n page_services = service_data\n else:\n # Fallback path: slice the fully-filtered list\n total_count = len(service_data)\n page_services = service_data[offset : offset + limit]\n\n has_next = (offset + limit) < total_count\n\n return {\n \"servers\": page_services,\n \"total_count\": total_count,\n \"limit\": limit,\n \"offset\": offset,\n \"has_next\": has_next,\n }\n\n\n@router.post(\"/toggle/{service_path:path}\")\nasync def toggle_service_route(\n request: Request,\n service_path: str,\n enabled: Annotated[str | None, Form()] = None,\n user_context: Annotated[dict, Depends(enhanced_auth)] = None,\n _csrf: Annotated[None, Depends(verify_csrf_token_flexible)] = None,\n):\n \"\"\"Toggle a service on/off (requires toggle_service UI permission).\"\"\"\n from ..auth.dependencies import user_has_ui_permission_for_service\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service path not registered\")\n\n service_name = server_info[\"server_name\"]\n\n # Check if user has toggle_service permission for this specific service\n if not user_has_ui_permission_for_service(\n \"toggle_service\", service_name, user_context.get(\"ui_permissions\", {})\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to toggle service {service_name} without toggle_service permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"You do not have permission to toggle {service_name}\",\n )\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n service_path, user_context[\"accessible_servers\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to toggle service {service_path} without access\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n new_state = enabled == \"on\"\n success = await server_service.toggle_service(service_path, new_state)\n\n if not success:\n raise HTTPException(status_code=500, detail=\"Failed to toggle service\")\n\n server_name = server_info[\"server_name\"]\n logger.info(\n f\"Toggled '{server_name}' ({service_path}) to {new_state} by user '{user_context['username']}'\"\n )\n\n # If enabling, perform immediate health check\n status = \"disabled\"\n last_checked_iso = None\n if new_state:\n logger.info(f\"Performing immediate health check for {service_path} upon toggle ON...\")\n try:\n (\n status,\n last_checked_dt,\n ) = await health_service.perform_immediate_health_check(service_path)\n last_checked_iso = last_checked_dt.isoformat() if last_checked_dt else None\n logger.info(f\"Immediate health check for {service_path} completed. Status: {status}\")\n except Exception as e:\n logger.error(f\"ERROR during immediate health check for {service_path}: {e}\")\n status = f\"error: immediate check failed ({type(e).__name__})\"\n else:\n # When disabling, set status to disabled\n status = \"disabled\"\n logger.info(f\"Service {service_path} toggled OFF. Status set to disabled.\")\n\n # Update FAISS metadata with new enabled state\n await faiss_service.add_or_update_service(service_path, server_info, new_state)\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(path)\n\n if server_info:\n enabled_servers[path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n # Broadcast health status update to WebSocket clients\n await health_service.broadcast_health_update(service_path)\n\n return JSONResponse(\n status_code=200,\n content={\n \"message\": f\"Toggle request for {service_path} processed.\",\n \"service_path\": service_path,\n \"new_enabled_state\": new_state,\n \"status\": status,\n \"last_checked_iso\": last_checked_iso,\n \"num_tools\": server_info.get(\"num_tools\", 0),\n },\n )\n\n\n@router.post(\"/register\")\nasync def register_service(\n request: Request,\n name: Annotated[str, Form()],\n description: Annotated[str, Form()],\n path: Annotated[str, Form()],\n proxy_pass_url: Annotated[str, Form()],\n tags: Annotated[str, Form()] = \"\",\n num_tools: Annotated[int, Form()] = 0,\n license_str: Annotated[str, Form(alias=\"license\")] = \"N/A\",\n mcp_endpoint: Annotated[str | None, Form()] = None,\n sse_endpoint: Annotated[str | None, Form()] = None,\n metadata: Annotated[str | None, Form()] = None,\n visibility: Annotated[str, Form()] = \"public\",\n allowed_groups: Annotated[str | None, Form()] = None,\n auth_scheme: Annotated[str, Form()] = \"none\",\n auth_credential: Annotated[str | None, Form()] = None,\n auth_header_name: Annotated[str | None, Form()] = None,\n service_status: Annotated[str | None, Form(alias=\"status\")] = None,\n provider_organization: Annotated[str | None, Form()] = None,\n provider_url: Annotated[str | None, Form()] = None,\n source_created_at: Annotated[str | None, Form()] = None,\n source_updated_at: Annotated[str | None, Form()] = None,\n user_context: Annotated[dict, Depends(enhanced_auth)] = None,\n):\n \"\"\"Register a new service (requires register_service UI permission).\"\"\"\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n # Check if user has register_service permission for any service\n ui_permissions = user_context.get(\"ui_permissions\", {})\n register_permissions = ui_permissions.get(\"register_service\", [])\n\n if not register_permissions:\n logger.warning(\n f\"User {user_context['username']} attempted to register service without register_service permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have permission to register new services\",\n )\n\n logger.info(f\"Service registration request from user '{user_context['username']}'\")\n logger.info(f\"Name: {name}, Path: {path}, URL: {proxy_pass_url}\")\n\n # Ensure path starts with a slash\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Process tags\n tag_list = [tag.strip() for tag in tags.split(\",\") if tag.strip()]\n\n # Validate and normalize visibility value\n from registry.utils.visibility import (\n VALID_VISIBILITY_VALUES,\n _normalize_visibility,\n )\n\n visibility = _normalize_visibility(visibility)\n if visibility not in VALID_VISIBILITY_VALUES:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=f\"Invalid visibility value. Must be one of: {', '.join(VALID_VISIBILITY_VALUES)}\",\n )\n\n # Process allowed_groups (comma-separated string to list)\n allowed_groups_list = []\n if allowed_groups:\n allowed_groups_list = [g.strip() for g in allowed_groups.split(\",\") if g.strip()]\n\n # Validate group-restricted requires allowed_groups\n if visibility == \"group-restricted\" and not allowed_groups_list:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"group-restricted visibility requires at least one allowed_group\",\n )\n\n # Create server entry with auto-generated UUID\n from uuid import uuid4\n\n server_entry = {\n \"id\": str(uuid4()),\n \"server_name\": name,\n \"description\": description,\n \"path\": path,\n \"proxy_pass_url\": proxy_pass_url,\n \"tags\": tag_list,\n \"num_tools\": num_tools,\n \"license\": license_str,\n \"tool_list\": [],\n \"visibility\": visibility,\n \"allowed_groups\": allowed_groups_list,\n }\n\n # Add custom endpoint fields if provided\n if mcp_endpoint:\n server_entry[\"mcp_endpoint\"] = mcp_endpoint\n if sse_endpoint:\n server_entry[\"sse_endpoint\"] = sse_endpoint\n\n # Add metadata if provided (expects JSON string)\n if metadata:\n try:\n import json\n\n server_entry[\"metadata\"] = json.loads(metadata)\n except json.JSONDecodeError:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Invalid JSON in metadata field\",\n )\n\n # Registration gate check (admission control, issue #809)\n # Called BEFORE credential encryption so sanitize() can strip plaintext fields\n gate_result = await check_registration_gate(\n asset_type=\"server\",\n operation=\"register\",\n source_api=\"/servers/register\",\n registration_payload=server_entry,\n raw_headers=request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied server '{name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n # Add auth fields\n if auth_scheme and auth_scheme in VALID_AUTH_SCHEMES:\n server_entry[\"auth_scheme\"] = auth_scheme\n if auth_header_name:\n server_entry[\"auth_header_name\"] = auth_header_name\n if auth_credential and auth_scheme != \"none\":\n server_entry[\"auth_credential\"] = auth_credential\n try:\n encrypt_credential_in_server_dict(server_entry)\n except Exception as e:\n logger.error(f\"Failed to encrypt credential: {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to encrypt credential\",\n )\n\n # Add lifecycle and federation fields\n if service_status:\n server_entry[\"status\"] = service_status\n\n # Add provider information (stored as nested AgentProvider object)\n if provider_organization or provider_url:\n from registry.schemas.agent_models import AgentProvider\n\n server_entry[\"provider\"] = AgentProvider(\n organization=provider_organization,\n url=provider_url,\n ).model_dump()\n\n # Add source timestamps\n if source_created_at:\n try:\n from datetime import datetime\n\n # Validate ISO format\n datetime.fromisoformat(source_created_at.replace(\"Z\", \"+00:00\"))\n server_entry[\"source_created_at\"] = source_created_at\n except ValueError:\n logger.warning(f\"Invalid source_created_at format: {source_created_at}\")\n\n if source_updated_at:\n try:\n from datetime import datetime\n\n datetime.fromisoformat(source_updated_at.replace(\"Z\", \"+00:00\"))\n server_entry[\"source_updated_at\"] = source_updated_at\n except ValueError:\n logger.warning(f\"Invalid source_updated_at format: {source_updated_at}\")\n\n # Register the server (or new version if path exists with different version)\n result = await server_service.register_server(server_entry)\n\n if not result[\"success\"]:\n # Check if it's a version conflict (same path, same version)\n logger.warning(f\"Server registration failed for path '{path}': {result['message']}\")\n return JSONResponse(\n status_code=409,\n content={\n \"error\": \"Service registration failed\",\n \"detail\": \"Check server logs for more information\",\n },\n )\n\n # Handle new version registration vs new server\n if result.get(\"is_new_version\"):\n logger.info(\n f\"New version registered: '{name}' version '{server_entry.get('version')}' \"\n f\"at path '{path}' by user '{user_context['username']}'\"\n )\n return JSONResponse(\n status_code=201,\n content={\n \"message\": f\"Service '{name}' version registered successfully\",\n \"service\": server_entry,\n \"is_new_version\": True,\n \"existing_version\": result.get(\"existing_version\"),\n },\n )\n\n # New server - proceed with full setup\n # Add to FAISS index with current enabled state\n is_enabled = await server_service.is_service_enabled(path)\n await faiss_service.add_or_update_service(path, server_entry, is_enabled)\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for server_path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(server_path)\n\n if server_info:\n enabled_servers[server_path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n # Broadcast health status update to WebSocket clients\n await health_service.broadcast_health_update(path)\n\n # Security scanning if enabled (non-blocking — scan is non-fatal, don't block response)\n asyncio.create_task(_perform_security_scan_on_registration(path, proxy_pass_url, server_entry))\n\n # Registration webhook (Issue #742)\n asyncio.create_task(\n send_registration_webhook(\n event_type=\"registration\",\n registration_type=\"server\",\n card_data=server_entry,\n performed_by=user_context[\"username\"],\n )\n )\n\n logger.info(\n f\"New service registered: '{name}' at path '{path}' by user '{user_context['username']}'\"\n )\n\n return JSONResponse(\n status_code=201,\n content={\n \"message\": \"Service registered successfully\",\n \"service\": server_entry,\n },\n )\n\n\n@router.post(\"/internal/register\")\nasync def internal_register_service(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n name: Annotated[str, Form()],\n description: Annotated[str, Form()],\n path: Annotated[str, Form()],\n proxy_pass_url: Annotated[str, Form()],\n tags: Annotated[str, Form()] = \"\",\n num_tools: Annotated[int, Form()] = 0,\n license_str: Annotated[str, Form(alias=\"license\")] = \"N/A\",\n overwrite: Annotated[bool, Form()] = True,\n auth_provider: Annotated[str | None, Form()] = None,\n auth_scheme: Annotated[str, Form()] = \"none\",\n auth_credential: Annotated[str | None, Form()] = None,\n auth_header_name: Annotated[str | None, Form()] = None,\n supported_transports: Annotated[str | None, Form()] = None,\n headers: Annotated[str | None, Form()] = None,\n tool_list_json: Annotated[str | None, Form()] = None,\n metadata: Annotated[str | None, Form()] = None,\n visibility: Annotated[str, Form()] = \"public\",\n allowed_groups: Annotated[str | None, Form()] = None,\n):\n \"\"\"Internal service registration endpoint for mcpgw-server (requires admin authentication).\"\"\"\n logger.warning(\n \"INTERNAL REGISTER: Function called - starting execution\"\n ) # TODO: replace with debug\n\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n logger.warning(\n f\"INTERNAL REGISTER: Request parameters - name={name}, path={path}, proxy_pass_url={proxy_pass_url}\"\n ) # TODO: replace with debug\n\n logger.info(f\"Internal service registration request from caller '{caller}'\")\n\n # Validate path format\n if not path.startswith(\"/\"):\n path = \"/\" + path\n logger.warning(f\"INTERNAL REGISTER: Validated path: {path}\") # TODO: replace with debug\n\n # Process tags\n tag_list = [tag.strip() for tag in tags.split(\",\") if tag.strip()] if tags else []\n logger.warning(f\"INTERNAL REGISTER: Processed tags: {tag_list}\") # TODO: replace with debug\n\n # Process supported_transports\n if supported_transports:\n try:\n transports_list = (\n json.loads(supported_transports)\n if supported_transports.startswith(\"[\")\n else [t.strip() for t in supported_transports.split(\",\")]\n )\n except Exception as e:\n logger.warning(\n f\"INTERNAL REGISTER: Failed to parse supported_transports, using default: {e}\"\n )\n transports_list = [\"streamable-http\"]\n else:\n transports_list = [\"streamable-http\"]\n\n # Process headers\n headers_list = []\n if headers:\n try:\n headers_list = json.loads(headers) if isinstance(headers, str) else headers\n except Exception as e:\n logger.warning(f\"INTERNAL REGISTER: Failed to parse headers: {e}\")\n\n # Process tool_list\n tool_list = []\n if tool_list_json:\n try:\n tool_list = (\n json.loads(tool_list_json) if isinstance(tool_list_json, str) else tool_list_json\n )\n except Exception as e:\n logger.warning(f\"INTERNAL REGISTER: Failed to parse tool_list_json: {e}\")\n\n # Process allowed_groups (comma-separated string to list)\n allowed_groups_list = []\n if allowed_groups:\n allowed_groups_list = [g.strip() for g in allowed_groups.split(\",\") if g.strip()]\n\n # Validate and normalize visibility value\n from registry.utils.visibility import (\n VALID_VISIBILITY_VALUES,\n _normalize_visibility,\n )\n\n visibility = _normalize_visibility(visibility)\n if visibility not in VALID_VISIBILITY_VALUES:\n visibility = \"public\" # Default to public for unrecognized values\n\n # Validate auth_scheme\n if auth_scheme not in VALID_AUTH_SCHEMES:\n return JSONResponse(\n status_code=400,\n content={\n \"error\": \"Invalid auth_scheme\",\n \"reason\": f\"auth_scheme must be one of: {VALID_AUTH_SCHEMES}\",\n },\n )\n\n # Create server entry with auto-generated UUID\n from uuid import uuid4\n\n server_entry = {\n \"id\": str(uuid4()),\n \"server_name\": name,\n \"description\": description,\n \"path\": path,\n \"proxy_pass_url\": proxy_pass_url,\n \"supported_transports\": transports_list,\n \"auth_scheme\": auth_scheme,\n \"tags\": tag_list,\n \"num_tools\": num_tools,\n \"license\": license_str,\n \"tool_list\": tool_list,\n \"visibility\": visibility,\n \"allowed_groups\": allowed_groups_list,\n }\n\n # Add optional fields if provided\n if auth_provider:\n server_entry[\"auth_provider\"] = auth_provider\n if headers_list:\n server_entry[\"headers\"] = headers_list\n if auth_header_name:\n server_entry[\"auth_header_name\"] = auth_header_name\n if metadata:\n try:\n server_entry[\"metadata\"] = (\n json.loads(metadata) if isinstance(metadata, str) else metadata\n )\n except json.JSONDecodeError:\n return JSONResponse(\n status_code=400,\n content={\"error\": \"Invalid metadata\", \"reason\": \"metadata must be valid JSON\"},\n )\n\n # Registration gate check (admission control, issue #809)\n gate_result = await check_registration_gate(\n asset_type=\"server\",\n operation=\"register\",\n source_api=\"/internal/register\",\n registration_payload=server_entry,\n raw_headers=request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied internal server '{name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n # Encrypt credential before storage (if provided)\n if auth_credential and auth_scheme != \"none\":\n server_entry[\"auth_credential\"] = auth_credential\n try:\n encrypt_credential_in_server_dict(server_entry)\n except ValueError as e:\n logger.error(f\"Credential encryption failed for server {path}: {e}\")\n return JSONResponse(\n status_code=500,\n content={\n \"error\": \"Credential encryption failed. Please ensure SECRET_KEY is configured.\",\n },\n )\n\n logger.warning(\n f\"INTERNAL REGISTER: Created server entry for path: {path}\"\n ) # TODO: replace with debug\n logger.warning(\n f\"INTERNAL REGISTER: Overwrite parameter: {overwrite}\"\n ) # TODO: replace with debug\n\n # Check if server exists and handle overwrite logic\n existing_server = await server_service.get_server_info(path)\n if existing_server and not overwrite:\n logger.warning(\n f\"INTERNAL REGISTER: Server exists and overwrite=False for path {path}\"\n ) # TODO: replace with debug\n return JSONResponse(\n status_code=409, # Conflict status code for existing resource\n content={\n \"error\": \"Service registration failed\",\n \"reason\": f\"A service with path '{path}' already exists\",\n \"suggestion\": \"Set overwrite=true or use the remove command first\",\n },\n )\n\n # Register the server (this will overwrite if server exists and overwrite=True)\n logger.warning(\n \"INTERNAL REGISTER: Calling server_service.register_server\"\n ) # TODO: replace with debug\n if existing_server and overwrite:\n logger.warning(\n f\"INTERNAL REGISTER: Overwriting existing server at path {path}\"\n ) # TODO: replace with debug\n success = await server_service.update_server(path, server_entry)\n is_new_version = False\n else:\n result = await server_service.register_server(server_entry)\n success = result[\"success\"]\n is_new_version = result.get(\"is_new_version\", False)\n\n if not success:\n logger.warning(\n f\"INTERNAL REGISTER: Registration failed for path {path}: \"\n f\"{result.get('message', 'unknown error')}\"\n )\n return JSONResponse(\n status_code=409, # Conflict status code for existing resource\n content={\n \"error\": \"Service registration failed\",\n \"detail\": \"Check server logs for more information\",\n },\n )\n\n logger.warning(\n \"INTERNAL REGISTER: Auto-enabling newly registered server\"\n ) # TODO: replace with debug\n\n # Automatically enable the newly registered server BEFORE FAISS indexing\n try:\n toggle_success = await server_service.toggle_service(path, True)\n if toggle_success:\n logger.info(f\"Successfully auto-enabled server {path} after registration\")\n else:\n logger.warning(f\"Failed to auto-enable server {path} after registration\")\n except Exception as e:\n logger.error(f\"Error auto-enabling server {path}: {e}\")\n # Non-fatal error - server is registered but not enabled\n\n logger.warning(\n \"INTERNAL REGISTER: Server registered successfully, adding to FAISS index\"\n ) # TODO: replace with debug\n\n # Add to FAISS index with current enabled state (should be True after auto-enable)\n is_enabled = await server_service.is_service_enabled(path)\n await faiss_service.add_or_update_service(path, server_entry, is_enabled)\n\n logger.warning(\n \"INTERNAL REGISTER: Regenerating Nginx configuration\"\n ) # TODO: replace with debug\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for server_path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(server_path)\n\n if server_info:\n enabled_servers[server_path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n logger.warning(\n \"INTERNAL REGISTER: Broadcasting health status update\"\n ) # TODO: replace with debug\n\n # Broadcast health status update to WebSocket clients\n await health_service.broadcast_health_update(path)\n\n logger.warning(\n \"INTERNAL REGISTER: Updating scopes.yml for new server\"\n ) # TODO: replace with debug\n\n # Update scopes.yml with the new server's tools\n from ..services.scope_service import update_server_scopes\n\n # Get the tool list from the server entry\n tool_names = []\n if \"tool_list\" in server_entry and server_entry[\"tool_list\"]:\n tool_names = [tool[\"name\"] for tool in server_entry[\"tool_list\"] if \"name\" in tool]\n\n # Update scopes and reload auth server\n try:\n await update_server_scopes(path, name, tool_names)\n logger.info(f\"Successfully updated scopes for server {path} with {len(tool_names)} tools\")\n except Exception as e:\n logger.error(f\"Failed to update scopes for server {path}: {e}\")\n # Non-fatal error - server is registered but scopes not updated\n\n # Security scanning if enabled (non-blocking — scan is non-fatal, don't block response)\n asyncio.create_task(\n _perform_security_scan_on_registration(path, proxy_pass_url, server_entry, headers_list)\n )\n\n logger.warning(\n \"INTERNAL REGISTER: Registration complete, returning success response\"\n ) # TODO: replace with debug\n logger.info(\n f\"New service registered via internal endpoint: '{name}' at path '{path}' by caller '{caller}'\"\n )\n\n return JSONResponse(\n status_code=201,\n content={\n \"message\": \"Service registered successfully\",\n \"service\": server_entry,\n },\n )\n\n\n@router.post(\"/internal/remove\")\nasync def internal_remove_service(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n service_path: Annotated[str, Form()],\n):\n \"\"\"Internal service removal endpoint for mcpgw-server (requires admin authentication).\"\"\"\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n logger.warning(\n \"INTERNAL REMOVE: Function called - starting execution\"\n ) # TODO: replace with debug\n\n logger.info(\n f\"Internal service removal request from caller '{caller}' for service '{service_path}'\"\n )\n\n # Validate path format\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n logger.warning(\n f\"INTERNAL REMOVE: Normalized service path: {service_path}\"\n ) # TODO: replace with debug\n\n # Check if server exists\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n logger.warning(\n f\"INTERNAL REMOVE: Service not found at path '{service_path}'\"\n ) # TODO: replace with debug\n return JSONResponse(\n status_code=404,\n content={\n \"error\": \"Service not found\",\n \"reason\": f\"No service registered at path '{service_path}'\",\n \"suggestion\": \"Check the service path and ensure it is registered\",\n },\n )\n\n logger.warning(\n \"INTERNAL REMOVE: Service found, proceeding with removal\"\n ) # TODO: replace with debug\n\n # Remove the server\n success = await server_service.remove_server(service_path)\n\n if not success:\n logger.warning(\n f\"INTERNAL REMOVE: Failed to remove service at path '{service_path}'\"\n ) # TODO: replace with debug\n return JSONResponse(\n status_code=500,\n content={\n \"error\": \"Service removal failed\",\n \"reason\": f\"Failed to remove service at path '{service_path}'\",\n \"suggestion\": \"Check server logs for detailed error information\",\n },\n )\n\n logger.warning(\n \"INTERNAL REMOVE: Service removed successfully, updating FAISS index\"\n ) # TODO: replace with debug\n\n # Remove from FAISS index\n await faiss_service.remove_service(service_path)\n\n logger.warning(\"INTERNAL REMOVE: Regenerating Nginx configuration\") # TODO: replace with debug\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for server_path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(server_path)\n\n if server_info:\n enabled_servers[server_path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n logger.warning(\"INTERNAL REMOVE: Broadcasting health status update\") # TODO: replace with debug\n\n # Broadcast health status update to WebSocket clients\n await health_service.broadcast_health_update(service_path)\n\n logger.warning(\"INTERNAL REMOVE: Removing server from scopes.yml\") # TODO: replace with debug\n\n # Remove server from scopes.yml and reload auth server\n from ..services.scope_service import remove_server_scopes\n\n try:\n await remove_server_scopes(service_path)\n logger.info(f\"Successfully removed server {service_path} from scopes\")\n except Exception as e:\n logger.error(f\"Failed to remove server {service_path} from scopes: {e}\")\n # Non-fatal error - server is removed but scopes not updated\n\n logger.warning(\n \"INTERNAL REMOVE: Removal complete, returning success response\"\n ) # TODO: replace with debug\n logger.info(f\"Service removed via internal endpoint: '{service_path}' by caller '{caller}'\")\n\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Service removed successfully\",\n \"service_path\": service_path,\n },\n )\n\n\n@router.post(\"/internal/toggle\")\nasync def internal_toggle_service(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n service_path: Annotated[str, Form()],\n):\n \"\"\"Internal service toggle endpoint for mcpgw-server (requires admin authentication).\"\"\"\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n logger.warning(\n \"INTERNAL TOGGLE: Function called - starting execution\"\n ) # TODO: replace with debug\n\n # Ensure service_path starts with /\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n # Check if server exists\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n logger.warning(\n f\"INTERNAL TOGGLE: Service not found at path '{service_path}'\"\n ) # TODO: replace with debug\n return JSONResponse(\n status_code=404,\n content={\n \"error\": \"Service not found\",\n \"reason\": f\"No service registered at path '{service_path}'\",\n \"suggestion\": \"Check the service path and ensure it is registered\",\n },\n )\n\n logger.warning(\n \"INTERNAL TOGGLE: Service found, proceeding with toggle\"\n ) # TODO: replace with debug\n\n # Get current state and toggle it\n current_state = await server_service.is_service_enabled(service_path)\n new_state = not current_state\n success = await server_service.toggle_service(service_path, new_state)\n\n if not success:\n logger.warning(\n f\"INTERNAL TOGGLE: Failed to toggle service at path '{service_path}'\"\n ) # TODO: replace with debug\n return JSONResponse(\n status_code=500,\n content={\n \"error\": \"Service toggle failed\",\n \"reason\": f\"Failed to toggle service at path '{service_path}'\",\n \"suggestion\": \"Check server logs for detailed error information\",\n },\n )\n\n server_name = server_info[\"server_name\"]\n logger.info(f\"Toggled '{server_name}' ({service_path}) to {new_state} by caller '{caller}'\")\n\n # If enabling, perform immediate health check\n status_result = \"disabled\"\n last_checked_iso = None\n if new_state:\n logger.info(f\"Performing immediate health check for {service_path} upon toggle ON...\")\n try:\n (\n status_result,\n last_checked_dt,\n ) = await health_service.perform_immediate_health_check(service_path)\n last_checked_iso = last_checked_dt.isoformat() if last_checked_dt else None\n logger.info(\n f\"Immediate health check for {service_path} completed. Status: {status_result}\"\n )\n except Exception as e:\n logger.error(f\"ERROR during immediate health check for {service_path}: {e}\")\n status_result = f\"error: immediate check failed ({type(e).__name__})\"\n else:\n # When disabling, set status to disabled\n status_result = \"disabled\"\n logger.info(f\"Service {service_path} toggled OFF. Status set to disabled.\")\n\n # Update FAISS metadata with new enabled state\n await faiss_service.add_or_update_service(service_path, server_info, new_state)\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(path)\n\n if server_info:\n enabled_servers[path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n # Broadcast health status update to WebSocket clients\n await health_service.broadcast_health_update(service_path)\n\n logger.warning(\n \"INTERNAL TOGGLE: Toggle complete, returning success response\"\n ) # TODO: replace with debug\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Service toggled successfully\",\n \"service_path\": service_path,\n \"new_enabled_state\": new_state,\n \"status\": status_result,\n \"last_checked_iso\": last_checked_iso,\n \"num_tools\": server_info.get(\"num_tools\", 0),\n },\n )\n\n\n@router.post(\"/internal/healthcheck\")\nasync def internal_healthcheck(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n):\n \"\"\"Internal health check endpoint for mcpgw-server (requires admin authentication).\"\"\"\n from ..health.service import health_service\n\n logger.warning(\n \"INTERNAL HEALTHCHECK: Function called - starting execution\"\n ) # TODO: replace with debug\n\n logger.info(f\"Internal healthcheck request from caller '{caller}'\")\n\n # Get health status for all servers\n try:\n health_data = await health_service.get_all_health_status()\n logger.info(f\"Retrieved health status for {len(health_data)} servers\")\n\n return JSONResponse(status_code=200, content=health_data)\n\n except Exception as e:\n logger.exception(\"Failed to retrieve health status\")\n raise HTTPException(status_code=500, detail=\"Failed to retrieve health status\")\n\n\n@router.get(\"/edit/{service_path:path}\", response_class=HTMLResponse)\nasync def edit_server_form(\n request: Request,\n service_path: str,\n user_context: Annotated[dict, Depends(enhanced_auth)],\n):\n \"\"\"Show edit form for a service (requires modify_service UI permission).\"\"\"\n from ..auth.dependencies import user_has_ui_permission_for_service\n\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service path not found\")\n\n service_name = server_info[\"server_name\"]\n\n # Check if user has modify_service permission for this specific service\n if not user_has_ui_permission_for_service(\n \"modify_service\", service_name, user_context.get(\"ui_permissions\", {})\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to access edit form for {service_name} without modify_service permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"You do not have permission to modify {service_name}\",\n )\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n service_path, user_context[\"accessible_servers\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to edit service {service_path} without access\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to edit this server\",\n )\n\n session_cookie = request.cookies.get(settings.session_cookie_name, \"\")\n return templates.TemplateResponse(\n \"edit_server.html\",\n {\n \"request\": request,\n \"server\": server_info,\n \"username\": user_context[\"username\"],\n \"user_context\": user_context,\n \"csrf_token\": generate_csrf_token(session_cookie) if session_cookie else \"\",\n },\n )\n\n\n@router.post(\"/edit/{service_path:path}\")\nasync def edit_server_submit(\n request: Request,\n service_path: str,\n name: Annotated[str, Form()],\n proxy_pass_url: Annotated[str, Form()],\n user_context: Annotated[dict, Depends(enhanced_auth)],\n description: Annotated[str, Form()] = \"\",\n tags: Annotated[str, Form()] = \"\",\n num_tools: Annotated[int, Form()] = 0,\n license_str: Annotated[str, Form(alias=\"license\")] = \"N/A\",\n mcp_endpoint: Annotated[str | None, Form()] = None,\n metadata: Annotated[str | None, Form()] = None,\n visibility: Annotated[str, Form()] = \"public\",\n allowed_groups: Annotated[str | None, Form()] = None,\n service_status: Annotated[str | None, Form(alias=\"status\")] = None,\n auth_scheme: Annotated[str, Form()] = \"none\",\n auth_credential: Annotated[str | None, Form()] = None,\n auth_header_name: Annotated[str | None, Form()] = None,\n _csrf: Annotated[None, Depends(verify_csrf_token_flexible)] = None,\n):\n \"\"\"Handle server edit form submission (requires modify_service UI permission).\"\"\"\n from ..auth.dependencies import user_has_ui_permission_for_service\n from ..core.nginx_service import nginx_service\n from ..search.service import faiss_service\n\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n # Check if the server exists and get service name\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service path not found\")\n\n service_name = server_info[\"server_name\"]\n\n # Check if user has modify_service permission for this specific service\n if not user_has_ui_permission_for_service(\n \"modify_service\", service_name, user_context.get(\"ui_permissions\", {})\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to edit service {service_name} without modify_service permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"You do not have permission to modify {service_name}\",\n )\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n service_path, user_context[\"accessible_servers\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to edit service {service_path} without access\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to edit this server\",\n )\n\n # Process tags\n tag_list = [tag.strip() for tag in tags.split(\",\") if tag.strip()]\n\n # Validate and normalize visibility value\n from registry.utils.visibility import (\n VALID_VISIBILITY_VALUES,\n _normalize_visibility,\n )\n\n visibility = _normalize_visibility(visibility)\n if visibility not in VALID_VISIBILITY_VALUES:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=f\"Invalid visibility value. Must be one of: {', '.join(VALID_VISIBILITY_VALUES)}\",\n )\n\n # Process allowed_groups (comma-separated string to list)\n allowed_groups_list = []\n if allowed_groups:\n allowed_groups_list = [g.strip() for g in allowed_groups.split(\",\") if g.strip()]\n\n # Validate group-restricted requires allowed_groups\n if visibility == \"group-restricted\" and not allowed_groups_list:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"group-restricted visibility requires at least one allowed_group\",\n )\n\n # Prepare updated server data\n updated_server_entry = {\n \"server_name\": name,\n \"description\": description,\n \"path\": service_path,\n \"proxy_pass_url\": proxy_pass_url,\n \"tags\": tag_list,\n \"num_tools\": num_tools,\n \"license\": license_str,\n \"tool_list\": [], # Keep existing or initialize\n \"visibility\": visibility,\n \"allowed_groups\": allowed_groups_list,\n }\n\n # Add optional status if provided\n if service_status:\n updated_server_entry[\"status\"] = service_status\n\n # Add optional mcp_endpoint if provided\n if mcp_endpoint:\n updated_server_entry[\"mcp_endpoint\"] = mcp_endpoint\n\n # Parse and add metadata if provided\n if metadata:\n try:\n import json\n\n updated_server_entry[\"metadata\"] = json.loads(metadata)\n except json.JSONDecodeError:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Invalid JSON in metadata field\",\n )\n\n # Registration gate check (admission control, issue #809)\n gate_result = await check_registration_gate(\n asset_type=\"server\",\n operation=\"update\",\n source_api=f\"/edit/{service_path}\",\n registration_payload=updated_server_entry,\n raw_headers=request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied server update '{name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n # Handle auth fields for edit\n if auth_scheme and auth_scheme in VALID_AUTH_SCHEMES:\n updated_server_entry[\"auth_scheme\"] = auth_scheme\n if auth_header_name:\n updated_server_entry[\"auth_header_name\"] = auth_header_name\n if auth_credential and auth_scheme != \"none\":\n updated_server_entry[\"auth_credential\"] = auth_credential\n try:\n encrypt_credential_in_server_dict(updated_server_entry)\n except Exception as e:\n logger.error(f\"Failed to encrypt credential: {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to encrypt credential\",\n )\n elif auth_scheme == \"none\":\n # Clear credentials when switching to no auth\n updated_server_entry[\"auth_scheme\"] = \"none\"\n updated_server_entry.pop(\"auth_credential_encrypted\", None)\n updated_server_entry.pop(\"auth_header_name\", None)\n\n # Update server\n success = await server_service.update_server(service_path, updated_server_entry)\n\n if not success:\n raise HTTPException(status_code=500, detail=\"Failed to save updated server data\")\n\n # Update FAISS metadata (keep current enabled state)\n is_enabled = await server_service.is_service_enabled(service_path)\n await faiss_service.add_or_update_service(service_path, updated_server_entry, is_enabled)\n\n # Update DocumentDB search embeddings\n try:\n from ..repositories.factory import get_search_repository\n\n search_repo = get_search_repository()\n await search_repo.index_server(service_path, updated_server_entry, is_enabled)\n except Exception as e:\n logger.warning(f\"Failed to update search index for '{service_path}': {e}\")\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(path)\n\n if server_info:\n enabled_servers[path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n logger.info(f\"Server '{name}' ({service_path}) updated by user '{user_context['username']}'\")\n\n # Return JSON for API clients (React SPA), redirect for browser form submissions\n accept = request.headers.get(\"accept\", \"\")\n if \"application/json\" in accept:\n return {\"status\": \"ok\", \"message\": f\"Server '{name}' updated successfully\"}\n\n return RedirectResponse(url=\"/\", status_code=status.HTTP_303_SEE_OTHER)\n\n\n@router.get(\"/tokens\", response_class=HTMLResponse)\nasync def token_generation_page(\n request: Request, user_context: Annotated[dict, Depends(enhanced_auth)]\n):\n \"\"\"Show token generation page for authenticated users.\"\"\"\n return templates.TemplateResponse(\n \"token_generation.html\",\n {\n \"request\": request,\n \"username\": user_context[\"username\"],\n \"user_context\": user_context,\n \"user_scopes\": user_context[\"scopes\"],\n \"available_scopes\": user_context[\"scopes\"], # For the UI to show what's available\n },\n )\n\n\n@router.get(\"/server_details/{service_path:path}\")\nasync def get_server_details(\n request: Request, service_path: str, user_context: Annotated[dict, Depends(enhanced_auth)]\n):\n \"\"\"Get server details by path, or all servers if path is 'all' (filtered by permissions).\"\"\"\n # Normalize the path to ensure it starts with '/'\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n # Set audit action for server read\n if service_path == \"/all\":\n set_audit_action(request, \"list\", \"server\", description=\"List all server details\")\n else:\n set_audit_action(\n request,\n \"read\",\n \"server\",\n resource_id=service_path,\n description=f\"Read server details for {service_path}\",\n )\n\n # Special case: if path is 'all' or '/all', return details for all accessible servers\n if service_path == \"/all\":\n if user_context[\"is_admin\"]:\n return await server_service.get_all_servers()\n else:\n return await server_service.get_all_servers_with_permissions(\n user_context[\"accessible_servers\"]\n )\n\n # Regular case: return details for a specific server\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service path not registered\")\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n service_path, user_context[\"accessible_servers\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to access server details for {service_path} without access\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n # Build versions list if this server has version routing enabled\n versions = []\n current_version = server_info.get(\"version\", \"v1.0.0\")\n current_status = server_info.get(\"status\", \"stable\")\n\n # Add current (active) version first\n versions.append(\n {\n \"version\": current_version,\n \"proxy_pass_url\": server_info.get(\"proxy_pass_url\", \"\"),\n \"status\": current_status,\n \"is_default\": True,\n }\n )\n\n # Add other versions if they exist\n other_version_ids = server_info.get(\"other_version_ids\", [])\n for version_id in other_version_ids:\n version_info = await server_service.get_server_info(version_id)\n if version_info:\n versions.append(\n {\n \"version\": version_info.get(\"version\", \"unknown\"),\n \"proxy_pass_url\": version_info.get(\"proxy_pass_url\", \"\"),\n \"status\": version_info.get(\"status\", \"stable\"),\n \"is_default\": False,\n }\n )\n\n # Add versions to response if there are multiple versions\n if len(versions) > 1 or server_info.get(\"version_group\"):\n server_info[\"versions\"] = versions\n server_info[\"default_version\"] = current_version\n\n return server_info\n\n\n@router.get(\"/tools/{service_path:path}\")\nasync def get_service_tools(\n service_path: str, user_context: Annotated[dict, Depends(enhanced_auth)]\n):\n \"\"\"Get tool list for a service (filtered by permissions).\"\"\"\n from ..core.mcp_client import mcp_client_service\n from ..search.service import faiss_service\n\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n # Handle special case for '/all' to return tools from all accessible servers\n if service_path == \"/all\":\n all_tools = []\n all_servers_tools = {}\n\n # Get servers based on user permissions\n if user_context[\"is_admin\"]:\n all_servers = await server_service.get_all_servers()\n else:\n all_servers = await server_service.get_all_servers_with_permissions(\n user_context[\"accessible_servers\"]\n )\n\n for path, server_info in all_servers.items():\n # For '/all', we can use cached data to avoid too many MCP calls\n tool_list = server_info.get(\"tool_list\")\n\n if tool_list is not None and isinstance(tool_list, list):\n # Add server information to each tool\n server_tools = []\n for tool in tool_list:\n # Create a copy of the tool with server info added\n tool_with_server = dict(tool)\n tool_with_server[\"server_path\"] = path\n tool_with_server[\"server_name\"] = server_info.get(\"server_name\", \"Unknown\")\n server_tools.append(tool_with_server)\n\n all_tools.extend(server_tools)\n all_servers_tools[path] = server_tools\n\n return {\"service_path\": \"all\", \"tools\": all_tools, \"servers\": all_servers_tools}\n\n # Handle specific server case - fetch live tools from MCP server\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service path not registered\")\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n service_path, user_context[\"accessible_servers\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to access tools for {service_path} without access\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n # Check if service is enabled and healthy\n is_enabled = await server_service.is_service_enabled(service_path)\n if not is_enabled:\n raise HTTPException(status_code=400, detail=\"Cannot fetch tools from disabled service\")\n\n proxy_pass_url = server_info.get(\"proxy_pass_url\")\n if not proxy_pass_url:\n raise HTTPException(status_code=500, detail=\"Service has no proxy URL configured\")\n\n logger.info(f\"Fetching live tools for {service_path} from {proxy_pass_url}\")\n\n try:\n # Call MCP client to fetch fresh tools using server configuration\n tool_list = await mcp_client_service.get_tools_from_server_with_server_info(\n proxy_pass_url, server_info\n )\n\n if tool_list is None:\n # If live fetch fails but we have cached tools, use those\n cached_tools = server_info.get(\"tool_list\")\n if cached_tools is not None and isinstance(cached_tools, list):\n logger.warning(f\"Failed to fetch live tools for {service_path}, using cached tools\")\n return {\n \"service_path\": service_path,\n \"tools\": cached_tools,\n \"cached\": True,\n }\n raise HTTPException(\n status_code=503,\n detail=\"Failed to fetch tools from MCP server. Service may be unhealthy.\",\n )\n\n # Update the server registry with the fresh tools\n new_tool_count = len(tool_list)\n current_tool_count = server_info.get(\"num_tools\", 0)\n\n if current_tool_count != new_tool_count or server_info.get(\"tool_list\") != tool_list:\n logger.info(f\"Updating tool list for {service_path}. New count: {new_tool_count}\")\n\n # Update server info with fresh tools\n updated_server_info = server_info.copy()\n updated_server_info[\"tool_list\"] = tool_list\n updated_server_info[\"num_tools\"] = new_tool_count\n\n # Save updated server info\n success = await server_service.update_server(service_path, updated_server_info)\n if success:\n logger.info(f\"Successfully updated tool list for {service_path}\")\n\n # Update FAISS index with new tool data\n await faiss_service.add_or_update_service(\n service_path, updated_server_info, is_enabled\n )\n logger.info(f\"Updated FAISS index for {service_path}\")\n else:\n logger.error(f\"Failed to save updated tool list for {service_path}\")\n\n return {\"service_path\": service_path, \"tools\": tool_list, \"cached\": False}\n\n except HTTPException:\n # Re-raise HTTP exceptions as-is\n raise\n except Exception as e:\n logger.error(f\"Error fetching tools for {service_path}: {e}\")\n # Try to return cached tools if available\n cached_tools = server_info.get(\"tool_list\")\n if cached_tools is not None and isinstance(cached_tools, list):\n logger.warning(\n f\"Error fetching live tools for {service_path}, falling back to cached tools: {e}\"\n )\n return {\"service_path\": service_path, \"tools\": cached_tools, \"cached\": True}\n raise HTTPException(status_code=500, detail=\"Error fetching tools\")\n\n\n@router.post(\"/refresh/{service_path:path}\")\nasync def refresh_service(service_path: str, user_context: Annotated[dict, Depends(enhanced_auth)]):\n \"\"\"Refresh service health and tool information (requires health_check_service permission).\"\"\"\n from ..auth.dependencies import user_has_ui_permission_for_service\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n if not service_path.startswith(\"/\"):\n service_path = \"/\" + service_path\n\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service path not registered\")\n\n service_name = server_info[\"server_name\"]\n\n # Check if user has health_check_service permission for this specific service\n if not user_has_ui_permission_for_service(\n \"health_check_service\", service_name, user_context.get(\"ui_permissions\", {})\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to refresh service {service_name} without health_check_service permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"You do not have permission to refresh {service_name}\",\n )\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n service_path, user_context[\"accessible_servers\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to refresh service {service_path} without access\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n # Check if service is enabled\n is_enabled = await server_service.is_service_enabled(service_path)\n if not is_enabled:\n raise HTTPException(status_code=400, detail=\"Cannot refresh disabled service\")\n\n proxy_pass_url = server_info.get(\"proxy_pass_url\")\n if not proxy_pass_url:\n raise HTTPException(status_code=500, detail=\"Service has no proxy URL configured\")\n\n logger.info(\n f\"Refreshing service {service_path} at {proxy_pass_url} by user '{user_context['username']}'\"\n )\n\n try:\n # Perform immediate health check\n status, last_checked_dt = await health_service.perform_immediate_health_check(service_path)\n last_checked_iso = last_checked_dt.isoformat() if last_checked_dt else None\n logger.info(f\"Manual refresh health check for {service_path} completed. Status: {status}\")\n\n # Regenerate Nginx config after manual refresh\n logger.info(f\"Regenerating Nginx config after manual refresh for {service_path}...\")\n enabled_servers = {}\n\n for path in await server_service.get_enabled_services():\n path_server_info = await server_service.get_server_info(path)\n\n if path_server_info:\n enabled_servers[path] = path_server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n except Exception as e:\n logger.error(f\"ERROR during manual refresh check for {service_path}: {e}\")\n # Still broadcast the error state\n await health_service.broadcast_health_update(service_path)\n raise HTTPException(status_code=500, detail=f\"Refresh check failed: {e}\")\n\n # Update FAISS index\n await faiss_service.add_or_update_service(service_path, server_info, is_enabled)\n\n # Broadcast the updated status\n await health_service.broadcast_health_update(service_path)\n\n logger.info(f\"Service '{service_path}' refreshed by user '{user_context['username']}'\")\n return {\n \"message\": f\"Service {service_path} refreshed successfully\",\n \"service_path\": service_path,\n \"status\": status,\n \"last_checked_iso\": last_checked_iso,\n \"num_tools\": server_info.get(\"num_tools\", 0),\n }\n\n\nasync def _add_server_to_groups_impl(\n server_name: str,\n group_names: str,\n) -> JSONResponse:\n \"\"\"\n Internal implementation for adding server to groups.\n\n This function contains the business logic for adding a server to groups\n and can be called from both Basic Auth and JWT endpoints.\n \"\"\"\n from ..services.scope_service import add_server_to_groups\n\n # Parse group names from comma-separated string\n groups = [group.strip() for group in group_names.split(\",\") if group.strip()]\n if not groups:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"No valid group names provided\",\n )\n\n # Convert server name to path format\n server_path = f\"/{server_name}\" if not server_name.startswith(\"/\") else server_name\n\n try:\n success = await add_server_to_groups(server_path, groups)\n\n if success:\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Server successfully added to groups\",\n \"server_path\": server_path,\n \"groups\": groups,\n },\n )\n else:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Failed to add server to groups\",\n )\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(f\"Error adding server {server_path} to groups {groups}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server error\",\n )\n\n\n@router.post(\"/internal/add-to-groups\")\nasync def internal_add_server_to_groups(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n server_name: Annotated[str, Form()],\n group_names: Annotated[str, Form()], # Comma-separated list\n):\n \"\"\"Internal endpoint to add a server to specific scopes groups (requires admin authentication).\"\"\"\n logger.info(f\"Adding server to groups via internal endpoint by caller '{caller}'\")\n\n # Call the shared implementation\n return await _add_server_to_groups_impl(server_name, group_names)\n\n\nasync def _remove_server_from_groups_impl(\n server_name: str,\n group_names: str,\n) -> JSONResponse:\n \"\"\"\n Internal implementation for removing server from groups.\n\n This function contains the business logic for removing a server from groups\n and can be called from both Basic Auth and JWT endpoints.\n \"\"\"\n from ..services.scope_service import remove_server_from_groups\n\n # Parse group names from comma-separated string\n groups = [group.strip() for group in group_names.split(\",\") if group.strip()]\n if not groups:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"No valid group names provided\",\n )\n\n # Convert server name to path format\n server_path = f\"/{server_name}\" if not server_name.startswith(\"/\") else server_name\n\n try:\n success = await remove_server_from_groups(server_path, groups)\n\n if success:\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Server successfully removed from groups\",\n \"server_path\": server_path,\n \"groups\": groups,\n },\n )\n else:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Failed to remove server from groups\",\n )\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(f\"Error removing server {server_path} from groups {groups}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server error\",\n )\n\n\n@router.post(\"/internal/remove-from-groups\")\nasync def internal_remove_server_from_groups(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n server_name: Annotated[str, Form()],\n group_names: Annotated[str, Form()], # Comma-separated list\n):\n \"\"\"Internal endpoint to remove a server from specific scopes groups (requires admin authentication).\"\"\"\n logger.info(f\"Removing server from groups via internal endpoint by caller '{caller}'\")\n\n # Call the shared implementation\n return await _remove_server_from_groups_impl(server_name, group_names)\n\n\n@router.get(\"/internal/list\")\nasync def internal_list_services(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n):\n \"\"\"Internal service listing endpoint for mcpgw-server (requires admin authentication).\"\"\"\n logger.warning(\n \"INTERNAL LIST: Function called - starting execution\"\n ) # TODO: replace with debug\n\n logger.info(f\"Internal service list request from caller '{caller}'\")\n\n # Get all servers (admin access - no permission filtering)\n all_servers = await server_service.get_all_servers()\n\n logger.warning(f\"INTERNAL LIST: Found {len(all_servers)} servers\") # TODO: replace with debug\n\n # Transform the data to include enabled status and health information\n services = []\n for service_path, server_info in all_servers.items():\n from ..health.service import health_service\n\n # Fetch enabled status before health check to avoid race condition (Issue #612)\n is_enabled = await server_service.is_service_enabled(service_path)\n\n # Get real health status from health service\n health_data = health_service._get_service_health_data(\n service_path,\n {**server_info, \"is_enabled\": is_enabled},\n )\n\n service_data = {\n \"server_name\": server_info.get(\"server_name\", \"Unknown\"),\n \"path\": service_path,\n \"description\": server_info.get(\"description\", \"\"),\n \"proxy_pass_url\": server_info.get(\"proxy_pass_url\", \"\"),\n \"is_enabled\": is_enabled,\n \"tags\": server_info.get(\"tags\", []),\n \"num_tools\": server_info.get(\"num_tools\", 0),\n \"license\": server_info.get(\"license\", \"N/A\"),\n \"health_status\": health_data[\"status\"],\n \"last_checked_iso\": health_data[\"last_checked_iso\"],\n \"tool_list\": server_info.get(\"tool_list\", []),\n }\n services.append(service_data)\n\n logger.warning(f\"INTERNAL LIST: Returning {len(services)} services\") # TODO: replace with debug\n logger.info(\n f\"Internal service list completed for caller '{caller}' - returned {len(services)} services\"\n )\n\n return JSONResponse(\n status_code=200,\n content={\"services\": services, \"total_count\": len(services)},\n )\n\n\n@router.post(\"/internal/create-group\")\nasync def internal_create_group(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n group_name: Annotated[str, Form()],\n description: Annotated[str, Form()] = \"\",\n create_in_idp: Annotated[bool, Form()] = False,\n):\n \"\"\"Internal endpoint to create a new group in both IdP and scopes.yml (requires admin authentication).\"\"\"\n logger.info(f\"Creating group '{group_name}' via internal endpoint by caller '{caller}'\")\n\n # Call the shared implementation\n return await _create_group_impl(group_name, description, create_in_idp)\n\n\n@router.post(\"/internal/delete-group\")\nasync def internal_delete_group(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n group_name: Annotated[str, Form()],\n delete_from_keycloak: Annotated[bool, Form()] = True,\n force: Annotated[bool, Form()] = False,\n):\n \"\"\"Internal endpoint to delete a group from both Keycloak and scopes (requires admin authentication).\"\"\"\n logger.info(f\"Deleting group '{group_name}' via internal endpoint by caller '{caller}'\")\n\n # Call the shared implementation\n return await _delete_group_impl(group_name, delete_from_idp=delete_from_keycloak, force=force)\n\n\nasync def _list_groups_impl(\n include_idp: bool = True,\n include_scopes: bool = True,\n) -> JSONResponse:\n \"\"\"\n Internal implementation for listing groups.\n\n This function contains the business logic for listing groups\n and can be called from both Basic Auth and JWT endpoints.\n Uses the IAMManager abstraction to support any identity provider.\n \"\"\"\n from ..services.scope_service import list_groups\n from ..utils.iam_manager import get_iam_manager\n\n try:\n result = {\n \"keycloak_groups\": [],\n \"scopes_groups\": {},\n \"synchronized\": [],\n \"keycloak_only\": [],\n \"scopes_only\": [],\n }\n\n # Get groups from identity provider (Keycloak, Entra ID, etc.)\n idp_group_names = set()\n if include_idp:\n try:\n iam = get_iam_manager()\n idp_groups = await iam.list_groups()\n result[\"keycloak_groups\"] = [\n {\n \"name\": group.get(\"name\"),\n \"id\": group.get(\"id\"),\n \"path\": group.get(\"path\", \"\"),\n }\n for group in idp_groups\n ]\n idp_group_names = {group.get(\"name\") for group in idp_groups}\n logger.info(f\"Found {len(idp_groups)} groups in identity provider\")\n except Exception as e:\n logger.error(f\"Failed to list identity provider groups: {e}\")\n result[\"keycloak_error\"] = \"Failed to list identity provider groups\"\n\n # Get groups from scopes (file or OpenSearch based on STORAGE_BACKEND)\n scopes_group_names = set()\n if include_scopes:\n try:\n scopes_data = await list_groups()\n result[\"scopes_groups\"] = scopes_data\n scopes_group_names = set(scopes_data.keys())\n logger.info(f\"Found {len(scopes_group_names)} groups in scopes\")\n except Exception as e:\n logger.error(f\"Failed to list scopes groups: {e}\")\n result[\"scopes_error\"] = \"Failed to list scopes groups\"\n\n # Find synchronized and out-of-sync groups\n if include_idp and include_scopes:\n result[\"synchronized\"] = list(idp_group_names & scopes_group_names)\n result[\"keycloak_only\"] = list(idp_group_names - scopes_group_names)\n result[\"scopes_only\"] = list(scopes_group_names - idp_group_names)\n\n return JSONResponse(status_code=200, content=result)\n\n except Exception as e:\n logger.exception(\"Error listing groups\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server error\",\n )\n\n\n@router.get(\"/internal/list-groups\")\nasync def internal_list_groups(\n request: Request,\n caller: Annotated[str, Depends(validate_internal_auth)],\n include_keycloak: bool = True,\n include_scopes: bool = True,\n):\n \"\"\"Internal endpoint to list groups from Keycloak and/or scopes (requires admin authentication).\"\"\"\n logger.info(f\"Listing groups via internal endpoint by caller '{caller}'\")\n\n # Call the shared implementation\n return await _list_groups_impl(include_idp=include_keycloak, include_scopes=include_scopes)\n\n\n@router.post(\"/tokens/generate\")\nasync def generate_user_token(\n request: Request, user_context: Annotated[dict, Depends(enhanced_auth)]\n):\n \"\"\"\n Generate a JWT token for the authenticated user.\n\n Request body should contain:\n {\n \"requested_scopes\": [\"scope1\", \"scope2\"], // Optional, defaults to user's current scopes\n \"expires_in_hours\": 8, // Optional, defaults to 8 hours\n \"description\": \"Token for automation\" // Optional description\n }\n\n Returns:\n Generated JWT token with expiration info\n\n Raises:\n HTTPException: If request fails or user lacks permissions\n \"\"\"\n try:\n # Parse request body\n try:\n body = await request.json()\n except Exception as e:\n logger.warning(f\"Invalid JSON in token generation request: {e}\")\n raise HTTPException(status_code=400, detail=\"Invalid JSON in request body\")\n\n requested_scopes = body.get(\"requested_scopes\", [])\n expires_in_hours = body.get(\"expires_in_hours\", 8)\n description = body.get(\"description\", \"\")\n\n # Validate expires_in_hours\n if not isinstance(expires_in_hours, int) or expires_in_hours <= 0 or expires_in_hours > 24:\n raise HTTPException(\n status_code=400,\n detail=\"expires_in_hours must be an integer between 1 and 24\",\n )\n\n # Validate requested_scopes\n if requested_scopes and not isinstance(requested_scopes, list):\n raise HTTPException(\n status_code=400, detail=\"requested_scopes must be a list of strings\"\n )\n\n # Get full session data to include stored OAuth tokens\n from ..auth.dependencies import get_user_session_data\n\n try:\n session_cookie = request.cookies.get(settings.session_cookie_name)\n logger.info(f\"Session cookie present: {bool(session_cookie)}\")\n session_data = get_user_session_data(session_cookie)\n logger.info(\n f\"Session data extracted: auth_method={session_data.get('auth_method')}, \"\n f\"provider={session_data.get('provider')}, \"\n f\"has_id_token={bool(session_data.get('id_token'))}\"\n )\n except Exception as e:\n logger.warning(f\"Could not get session data for tokens: {e}\")\n session_data = {}\n\n # Prepare request to auth server\n # Include user identity info for self-signed JWT generation\n auth_request = {\n \"user_context\": {\n \"username\": user_context[\"username\"],\n \"email\": user_context.get(\"email\", session_data.get(\"email\", \"\")),\n \"scopes\": user_context[\"scopes\"],\n \"groups\": user_context[\"groups\"],\n \"provider\": user_context.get(\"provider\", session_data.get(\"provider\")),\n \"auth_method\": user_context.get(\"auth_method\", session_data.get(\"auth_method\")),\n },\n \"requested_scopes\": requested_scopes,\n \"expires_in_hours\": expires_in_hours,\n \"description\": description,\n }\n\n # Call auth server internal API (no authentication needed since both are trusted internal services)\n async with httpx.AsyncClient() as client:\n headers = {\"Content-Type\": \"application/json\"}\n\n auth_server_url = settings.auth_server_url\n response = await client.post(\n f\"{auth_server_url}/internal/tokens\",\n json=auth_request,\n headers=headers,\n timeout=10.0,\n )\n\n if response.status_code == 200:\n token_data = response.json()\n logger.info(f\"Successfully generated token for user '{user_context['username']}'\")\n\n # Format response to match expected structure (including refresh token)\n formatted_response = {\n \"success\": True,\n \"tokens\": {\n \"access_token\": token_data.get(\"access_token\"),\n \"refresh_token\": token_data.get(\"refresh_token\"),\n \"expires_in\": token_data.get(\"expires_in\"),\n \"refresh_expires_in\": token_data.get(\"refresh_expires_in\"),\n \"token_type\": token_data.get(\"token_type\", \"Bearer\"), # nosec B105 - OAuth2 standard token type per RFC 6750\n \"scope\": token_data.get(\"scope\", \"\"),\n },\n \"client_id\": \"user-generated\",\n # Legacy fields for backward compatibility\n \"token_data\": token_data,\n \"user_scopes\": user_context[\"scopes\"],\n \"requested_scopes\": requested_scopes or user_context[\"scopes\"],\n }\n\n # Add provider-specific metadata\n auth_provider = getattr(settings, \"auth_provider\", \"\").lower()\n if auth_provider == \"keycloak\":\n formatted_response[\"keycloak_url\"] = (\n getattr(settings, \"keycloak_url\", None) or \"http://keycloak:8080\"\n )\n formatted_response[\"realm\"] = (\n getattr(settings, \"keycloak_realm\", None) or \"mcp-gateway\"\n )\n elif auth_provider == \"auth0\":\n formatted_response[\"auth0_domain\"] = getattr(settings, \"auth0_domain\", None)\n elif auth_provider == \"cognito\":\n formatted_response[\"cognito_user_pool_id\"] = getattr(\n settings, \"cognito_user_pool_id\", None\n )\n elif auth_provider == \"entra\":\n formatted_response[\"entra_tenant_id\"] = getattr(\n settings, \"entra_tenant_id\", None\n )\n\n return formatted_response\n else:\n error_detail = \"Unknown error\"\n try:\n error_response = response.json()\n error_detail = error_response.get(\"detail\", \"Unknown error\")\n except:\n error_detail = response.text\n\n logger.warning(f\"Auth server returned error {response.status_code}: {error_detail}\")\n raise HTTPException(\n status_code=response.status_code,\n detail=f\"Token generation failed: {error_detail}\",\n )\n\n except HTTPException:\n raise\n except Exception as e:\n logger.error(\n f\"Unexpected error generating token for user '{user_context['username']}': {e}\"\n )\n raise HTTPException(status_code=500, detail=\"Internal error generating token\")\n\n\n# ============================================================================\n# NEW API: /api/servers/* endpoints with JWT Bearer Token Authentication\n# ============================================================================\n# These are the modern, JWT-authenticated equivalents of the /api/internal/*\n# endpoints. They use Depends(nginx_proxied_auth) for authentication and\n# support fine-grained permission checks via user context.\n#\n# Architecture:\n# - Both /api/internal/* and /api/servers/* call the same internal functions\n# - No code duplication; external API simply wraps existing endpoints\n# - User context from JWT is passed through for audit logging\n#\n# Migration Path:\n# Phase 1 (Now): Both endpoints work identically with same business logic\n# Phase 2 (Future): Clients migrate to /api/servers/*\n# Phase 3 (Future): /api/internal/* deprecated with sunset headers\n# Phase 4 (Future): /api/internal/* removed in major version\n\n\n@router.post(\"/servers/register\")\nasync def register_service_api(\n request: Request,\n name: Annotated[str, Form()],\n description: Annotated[str, Form()],\n path: Annotated[str, Form()],\n proxy_pass_url: Annotated[str, Form()],\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n tags: Annotated[str, Form()] = \"\",\n num_tools: Annotated[int, Form()] = 0,\n license_str: Annotated[str, Form(alias=\"license\")] = \"N/A\",\n overwrite: Annotated[bool, Form()] = True,\n auth_provider: Annotated[str | None, Form()] = None,\n auth_scheme: Annotated[str, Form()] = \"none\",\n auth_credential: Annotated[str | None, Form()] = None,\n auth_header_name: Annotated[str | None, Form()] = None,\n supported_transports: Annotated[str | None, Form()] = None,\n headers: Annotated[str | None, Form()] = None,\n tool_list_json: Annotated[str | None, Form()] = None,\n mcp_endpoint: Annotated[str | None, Form()] = None,\n sse_endpoint: Annotated[str | None, Form()] = None,\n metadata: Annotated[str | None, Form()] = None,\n version: Annotated[str | None, Form()] = None,\n status: Annotated[str | None, Form()] = None,\n provider_organization: Annotated[str | None, Form()] = None,\n provider_url: Annotated[str | None, Form()] = None,\n source_created_at: Annotated[str | None, Form()] = None,\n source_updated_at: Annotated[str | None, Form()] = None,\n external_tags: Annotated[str | None, Form()] = None,\n):\n \"\"\"\n Register a service via JWT Bearer Token authentication (External API).\n\n This endpoint provides the same functionality as POST /api/internal/register\n but uses modern JWT Bearer token authentication via nginx headers, making it\n suitable for external service-to-service communication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request body (form data):**\n - `name` (required): Service name\n - `description` (required): Service description\n - `path` (required): Service path (e.g., /myservice)\n - `proxy_pass_url` (required): Proxy URL (e.g., http://localhost:8000)\n - `tags` (optional): Comma-separated tags\n - `num_tools` (optional): Number of tools\n - `license` (optional): License name\n - `overwrite` (optional): Overwrite if exists (boolean, default true)\n - `auth_provider` (optional): Auth provider name\n - `auth_scheme` (optional): Auth scheme (none, bearer, api_key)\n - `auth_credential` (optional): Plaintext credential (encrypted before storage)\n - `auth_header_name` (optional): Custom header name for API key auth\n - `supported_transports` (optional): JSON array of transports\n - `headers` (optional): JSON object of headers\n - `tool_list_json` (optional): JSON array of tool definitions\n - `mcp_endpoint` (optional): Full URL for custom MCP endpoint (overrides /mcp suffix)\n - `sse_endpoint` (optional): Full URL for custom SSE endpoint (overrides /sse suffix)\n - `version` (optional): Server version (e.g., v1.0.0, v2.0.0)\n - `status` (optional): Lifecycle status (active, deprecated, draft, beta)\n - `provider_organization` (optional): Provider organization name\n - `provider_url` (optional): Provider URL\n - `source_created_at` (optional): Original creation timestamp (ISO format)\n - `source_updated_at` (optional): Last update timestamp (ISO format)\n - `external_tags` (optional): Comma-separated tags from external system\n\n **Response:**\n - `201 Created`: Service registered successfully\n - `400 Bad Request`: Invalid input data\n - `401 Unauthorized`: Missing or invalid JWT token\n - `409 Conflict`: Service already exists with same version (different version auto-creates new version)\n - `500 Internal Server Error`: Server error\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/register \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -F \"name=My Service\" \\\\\n -F \"description=My MCP Service\" \\\\\n -F \"path=/myservice\" \\\\\n -F \"proxy_pass_url=http://localhost:8000\"\n ```\n \"\"\"\n # Set audit action for server registration\n set_audit_action(\n request, \"create\", \"server\", resource_id=path, description=f\"Register server {name}\"\n )\n\n logger.info(\n f\"API register service request from user '{user_context.get('username')}' for service '{name}'\"\n )\n\n # Implementation extracted from internal_register_service to avoid duplicating auth logic\n # Auth is already validated by nginx_proxied_auth dependency\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n # Validate path format\n if not path.startswith(\"/\"):\n path = \"/\" + path\n logger.warning(f\"SERVERS REGISTER: Validated path: {path}\")\n\n # Process tags\n tag_list = [tag.strip() for tag in tags.split(\",\") if tag.strip()] if tags else []\n\n # Process supported_transports\n if supported_transports:\n try:\n transports_list = (\n json.loads(supported_transports)\n if supported_transports.startswith(\"[\")\n else [t.strip() for t in supported_transports.split(\",\")]\n )\n except Exception as e:\n logger.warning(\n f\"SERVERS REGISTER: Failed to parse supported_transports, using default: {e}\"\n )\n transports_list = [\"streamable-http\"]\n else:\n transports_list = [\"streamable-http\"]\n\n # Process headers\n headers_list = []\n if headers:\n try:\n headers_list = json.loads(headers) if isinstance(headers, str) else headers\n except Exception as e:\n logger.warning(f\"SERVERS REGISTER: Failed to parse headers: {e}\")\n\n # Process tool_list\n tool_list = []\n if tool_list_json:\n try:\n tool_list = (\n json.loads(tool_list_json) if isinstance(tool_list_json, str) else tool_list_json\n )\n except Exception as e:\n logger.warning(f\"SERVERS REGISTER: Failed to parse tool_list_json: {e}\")\n\n # Validate auth_scheme\n if auth_scheme not in VALID_AUTH_SCHEMES:\n return JSONResponse(\n status_code=400,\n content={\n \"error\": \"Invalid auth_scheme\",\n \"reason\": f\"auth_scheme must be one of: {VALID_AUTH_SCHEMES}\",\n },\n )\n\n # Create server entry with auto-generated UUID\n from uuid import uuid4\n\n server_entry = {\n \"id\": str(uuid4()),\n \"server_name\": name,\n \"description\": description,\n \"path\": path,\n \"proxy_pass_url\": proxy_pass_url,\n \"supported_transports\": transports_list,\n \"auth_scheme\": auth_scheme,\n \"tags\": tag_list,\n \"num_tools\": num_tools,\n \"license\": license_str,\n \"tool_list\": tool_list,\n }\n\n # Add optional fields if provided\n if auth_provider:\n server_entry[\"auth_provider\"] = auth_provider\n if headers_list:\n server_entry[\"headers\"] = headers_list\n if auth_header_name:\n server_entry[\"auth_header_name\"] = auth_header_name\n if mcp_endpoint:\n server_entry[\"mcp_endpoint\"] = mcp_endpoint\n if sse_endpoint:\n server_entry[\"sse_endpoint\"] = sse_endpoint\n if version:\n server_entry[\"version\"] = version\n if status:\n server_entry[\"status\"] = status\n\n # Add provider information\n if provider_organization or provider_url:\n from registry.schemas.agent_models import AgentProvider\n\n server_entry[\"provider\"] = AgentProvider(\n organization=provider_organization,\n url=provider_url,\n ).model_dump()\n\n # Add source timestamps\n if source_created_at:\n try:\n from datetime import datetime\n\n # Validate ISO format\n datetime.fromisoformat(source_created_at.replace(\"Z\", \"+00:00\"))\n server_entry[\"source_created_at\"] = source_created_at\n except ValueError:\n logger.warning(f\"Invalid source_created_at format: {source_created_at}\")\n\n if source_updated_at:\n try:\n from datetime import datetime\n\n datetime.fromisoformat(source_updated_at.replace(\"Z\", \"+00:00\"))\n server_entry[\"source_updated_at\"] = source_updated_at\n except ValueError:\n logger.warning(f\"Invalid source_updated_at format: {source_updated_at}\")\n\n # Add external tags\n if external_tags:\n external_tags_list = [tag.strip() for tag in external_tags.split(\",\") if tag.strip()]\n if external_tags_list:\n server_entry[\"external_tags\"] = external_tags_list\n\n # Registration gate check (admission control, issue #809)\n gate_result = await check_registration_gate(\n asset_type=\"server\",\n operation=\"register\",\n source_api=\"/api/servers/register\",\n registration_payload=server_entry,\n raw_headers=request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied server '{name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=403,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n # Encrypt credential before storage (if provided)\n if auth_credential and auth_scheme != \"none\":\n server_entry[\"auth_credential\"] = auth_credential\n try:\n encrypt_credential_in_server_dict(server_entry)\n except ValueError as e:\n logger.error(f\"Credential encryption failed for server {path}: {e}\")\n return JSONResponse(\n status_code=500,\n content={\n \"error\": \"Credential encryption failed. Please ensure SECRET_KEY is configured.\",\n },\n )\n\n if metadata:\n try:\n server_entry[\"metadata\"] = (\n json.loads(metadata) if isinstance(metadata, str) else metadata\n )\n except json.JSONDecodeError:\n return JSONResponse(\n status_code=400,\n content={\n \"error\": \"Invalid metadata\",\n \"reason\": \"metadata must be valid JSON\",\n \"detail\": \"Provide metadata as a JSON string\",\n },\n )\n\n # Check if server exists and handle overwrite/version logic\n existing_server = await server_service.get_server_info(path)\n\n # If server exists with a different version, register_server will auto-create new version\n # Only reject if overwrite=False AND it's the same version (or no version specified)\n if existing_server and not overwrite:\n existing_version = existing_server.get(\"version\", \"v1.0.0\")\n new_version = version\n # If versions are different, let register_server handle it as a new version\n if not new_version or new_version == existing_version:\n logger.warning(\n f\"SERVERS REGISTER: Server exists with same version and overwrite=False for path {path}\"\n )\n return JSONResponse(\n status_code=409,\n content={\n \"error\": \"Service registration failed\",\n \"reason\": f\"A service with path '{path}' already exists with version {existing_version}\",\n \"detail\": \"Use overwrite=true to replace, or specify a different version\",\n },\n )\n\n try:\n # Register service (use update_server if overwriting, otherwise register_server)\n if existing_server and overwrite:\n logger.info(\n f\"Overwriting existing server at path {path} by user {user_context.get('username')}\"\n )\n success = await server_service.update_server(path, server_entry)\n is_new_version = False\n else:\n result = await server_service.register_server(server_entry)\n success = result[\"success\"]\n is_new_version = result.get(\"is_new_version\", False)\n\n if not success:\n logger.error(\n f\"Service registration failed for {path}: {result.get('message', 'unknown error')}\"\n )\n return JSONResponse(\n status_code=409,\n content={\n \"error\": \"Service registration failed\",\n \"detail\": \"Check server logs for more information\",\n },\n )\n\n if is_new_version:\n logger.info(f\"New version registered for {path} by user {user_context.get('username')}\")\n else:\n logger.info(\n f\"Service registered successfully via API: {path} by user {user_context.get('username')}\"\n )\n\n # Security scanning if enabled (non-blocking — scan is non-fatal, don't block response)\n asyncio.create_task(\n _perform_security_scan_on_registration(path, proxy_pass_url, server_entry, headers_list)\n )\n\n # Trigger async tasks for health check and FAISS sync\n asyncio.create_task(health_service.perform_immediate_health_check(path))\n asyncio.create_task(faiss_service.save_data())\n\n # Registration webhook (Issue #742)\n asyncio.create_task(\n send_registration_webhook(\n event_type=\"registration\",\n registration_type=\"server\",\n card_data=server_entry,\n performed_by=user_context.get(\"username\"),\n )\n )\n\n return JSONResponse(\n status_code=201,\n content={\n \"path\": path,\n \"name\": name,\n \"message\": f\"Service '{name}' registered successfully at path '{path}'\",\n },\n )\n\n except Exception as e:\n logger.error(f\"Service registration failed for {path}: {e}\", exc_info=True)\n raise HTTPException(status_code=500, detail=\"Service registration failed\")\n\n\n@router.patch(\"/servers/{server_path:path}/auth-credential\")\nasync def update_server_auth_credential(\n request: Request,\n server_path: str,\n body: AuthCredentialUpdateRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Update the authentication credential for a registered server.\n\n Allows updating the auth scheme, credential, and custom header name\n for a backend MCP server without re-registering the entire server.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n\n **Path parameter:**\n - `server_path`: Server path (e.g., /my-server)\n\n **Request body (JSON):**\n - `auth_scheme` (required): Authentication scheme (none, bearer, api_key)\n - `auth_credential` (optional): New credential. Required if auth_scheme is not 'none'.\n - `auth_header_name` (optional): Custom header name. Default: X-API-Key for api_key.\n \"\"\"\n set_audit_action(\n request,\n \"update\",\n \"server_credential\",\n resource_id=server_path,\n description=f\"Update auth credential for server {server_path}\",\n )\n\n username = user_context.get(\"username\", \"unknown\")\n logger.info(f\"Auth credential update request for '{server_path}' by user '{username}'\")\n\n # Normalize path\n if not server_path.startswith(\"/\"):\n server_path = \"/\" + server_path\n\n # Validate auth_scheme\n if body.auth_scheme not in VALID_AUTH_SCHEMES:\n return JSONResponse(\n status_code=400,\n content={\n \"error\": \"Invalid auth_scheme\",\n \"reason\": f\"auth_scheme must be one of: {VALID_AUTH_SCHEMES}\",\n },\n )\n\n # Require credential when scheme is not 'none'\n if body.auth_scheme != \"none\" and not body.auth_credential:\n return JSONResponse(\n status_code=400,\n content={\n \"error\": \"Missing credential\",\n \"reason\": \"auth_credential is required when auth_scheme is not 'none'\",\n },\n )\n\n # Look up existing server (with credentials so we can update properly)\n existing_server = await server_service.get_server_info(server_path, include_credentials=True)\n if not existing_server:\n return JSONResponse(\n status_code=404,\n content={\n \"error\": \"Server not found\",\n \"reason\": f\"No server registered at path '{server_path}'\",\n },\n )\n\n # Build update dict\n existing_server[\"auth_scheme\"] = body.auth_scheme\n\n if body.auth_scheme == \"none\":\n # Clear credential fields when switching to none\n existing_server.pop(\"auth_credential_encrypted\", None)\n existing_server.pop(\"auth_header_name\", None)\n existing_server.pop(\"credential_updated_at\", None)\n else:\n # Set credential for encryption\n existing_server[\"auth_credential\"] = body.auth_credential\n if body.auth_header_name:\n existing_server[\"auth_header_name\"] = body.auth_header_name\n elif body.auth_scheme == \"api_key\":\n existing_server[\"auth_header_name\"] = \"X-API-Key\"\n\n try:\n encrypt_credential_in_server_dict(existing_server)\n except ValueError as e:\n logger.error(f\"Credential encryption failed for server {server_path}: {e}\")\n return JSONResponse(\n status_code=500,\n content={\n \"error\": \"Credential encryption failed. Please ensure SECRET_KEY is configured.\",\n },\n )\n\n # Save updated server\n success = await server_service.update_server(server_path, existing_server)\n if not success:\n return JSONResponse(\n status_code=500,\n content={\n \"error\": \"Update failed\",\n \"reason\": \"Failed to save updated server credentials\",\n },\n )\n\n logger.info(\n f\"Auth credential updated for '{server_path}' \"\n f\"(scheme={body.auth_scheme}) by user '{username}'\"\n )\n\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Auth credentials updated successfully\",\n \"path\": server_path,\n \"auth_scheme\": body.auth_scheme,\n \"auth_header_name\": existing_server.get(\"auth_header_name\"),\n },\n )\n\n\n@router.post(\"/servers/toggle\")\nasync def toggle_service_api(\n request: Request,\n path: Annotated[str, Form()],\n new_state: Annotated[bool, Form()],\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Toggle a service's enabled/disabled state via JWT authentication (External API).\n\n This endpoint provides the same functionality as POST /api/internal/toggle\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request body (form data):**\n - `path` (required): Service path\n - `new_state` (required): New state (true=enabled, false=disabled)\n\n **Response:**\n Returns the updated service status.\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/toggle \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -F \"path=/myservice\" \\\\\n -F \"new_state=true\"\n ```\n \"\"\"\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n\n # Set audit action for server toggle\n set_audit_action(\n request, \"toggle\", \"server\", resource_id=path, description=f\"Toggle server to {new_state}\"\n )\n\n logger.info(\n f\"API toggle service request from user '{user_context.get('username')}' for path '{path}' to {new_state}\"\n )\n\n # Normalize path\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Check if server exists\n server_info = await server_service.get_server_info(path)\n if not server_info:\n raise HTTPException(status_code=404, detail=\"Service path not registered\")\n\n # Toggle the service\n success = await server_service.toggle_service(path, new_state)\n\n if not success:\n raise HTTPException(status_code=500, detail=\"Failed to toggle service\")\n\n logger.info(\n f\"Toggled '{server_info['server_name']}' ({path}) to {new_state} by user '{user_context.get('username')}'\"\n )\n\n # If enabling, perform immediate health check\n status = \"disabled\"\n last_checked_iso = None\n if new_state:\n logger.info(f\"Performing immediate health check for {path} upon toggle ON...\")\n try:\n (\n status,\n last_checked_dt,\n ) = await health_service.perform_immediate_health_check(path)\n last_checked_iso = last_checked_dt.isoformat() if last_checked_dt else None\n logger.info(f\"Immediate health check for {path} completed. Status: {status}\")\n except Exception as e:\n logger.error(f\"ERROR during immediate health check for {path}: {e}\")\n status = f\"error: immediate check failed ({type(e).__name__})\"\n else:\n # When disabling, set status to disabled\n status = \"disabled\"\n logger.info(f\"Service {path} toggled OFF. Status set to disabled.\")\n\n # Update FAISS metadata with new enabled state\n await faiss_service.add_or_update_service(path, server_info, new_state)\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for server_path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(server_path)\n\n if server_info:\n enabled_servers[server_path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n # Broadcast health status update to WebSocket clients\n await health_service.broadcast_health_update(path)\n\n return JSONResponse(\n status_code=200,\n content={\n \"message\": f\"Toggle request for {path} processed.\",\n \"service_path\": path,\n \"new_enabled_state\": new_state,\n \"status\": status,\n \"last_checked_iso\": last_checked_iso,\n \"num_tools\": server_info.get(\"num_tools\", 0),\n },\n )\n\n\n@router.post(\"/servers/remove\")\nasync def remove_service_api(\n request: Request,\n path: Annotated[str, Form()],\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Remove a service via JWT Bearer Token authentication (External API).\n\n This endpoint provides the same functionality as POST /api/internal/remove\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request body (form data):**\n - `path` (required): Service path to remove\n\n **Response:**\n Returns confirmation of removal.\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/remove \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -F \"path=/myservice\"\n ```\n \"\"\"\n from ..core.nginx_service import nginx_service\n from ..health.service import health_service\n from ..search.service import faiss_service\n from ..services.scope_service import remove_server_scopes\n\n # Set audit action for server removal\n set_audit_action(\n request, \"delete\", \"server\", resource_id=path, description=f\"Remove server at {path}\"\n )\n\n logger.info(\n f\"API remove service request from user '{user_context.get('username')}' for path '{path}'\"\n )\n\n # Normalize path\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Check if server exists\n server_info = await server_service.get_server_info(path)\n if not server_info:\n logger.warning(f\"Service not found at path '{path}'\")\n return JSONResponse(\n status_code=404,\n content={\n \"error\": \"Service not found\",\n \"reason\": f\"No service registered at path '{path}'\",\n \"suggestion\": \"Check the service path and ensure it is registered\",\n },\n )\n\n # Block deletion of federated (read-only) servers from peer registries\n sync_metadata = server_info.get(\"sync_metadata\", {})\n if sync_metadata.get(\"is_federated\") or sync_metadata.get(\"is_read_only\"):\n source_peer = sync_metadata.get(\"source_peer_id\", \"unknown peer registry\")\n logger.warning(\n f\"User {user_context.get('username')} attempted to delete federated server {path} \"\n f\"from {source_peer}\"\n )\n return JSONResponse(\n status_code=403,\n content={\n \"error\": \"Cannot delete federated server\",\n \"reason\": f\"Server '{path}' is synced from {source_peer} and cannot be deleted locally\",\n \"suggestion\": \"Delete this server from its source registry, or remove the peer federation\",\n },\n )\n\n # Fine-grained delete permission check (gateway already validated api.servers access)\n if not user_context.get(\"is_admin\", False):\n ui_permissions = user_context.get(\"ui_permissions\", {})\n delete_service_perms = ui_permissions.get(\"delete_service\", [])\n server_name = path.strip(\"/\")\n if \"all\" not in delete_service_perms and server_name not in delete_service_perms:\n logger.warning(f\"User {user_context.get('username')} denied delete for server {path}\")\n return JSONResponse(\n status_code=403,\n content={\n \"error\": \"Permission denied\",\n \"reason\": f\"User does not have delete_service permission for '{path}'\",\n },\n )\n\n # Remove the server\n success = await server_service.remove_server(path)\n\n if not success:\n logger.warning(f\"Failed to remove service at path '{path}'\")\n return JSONResponse(\n status_code=500,\n content={\n \"error\": \"Service removal failed\",\n \"reason\": f\"Failed to remove service at path '{path}'\",\n \"suggestion\": \"Check server logs for detailed error information\",\n },\n )\n\n logger.info(f\"Service removed successfully: {path} by user {user_context.get('username')}\")\n\n # Remove from FAISS index\n await faiss_service.remove_service(path)\n\n # Regenerate Nginx configuration\n enabled_servers = {}\n\n for server_path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(server_path)\n\n if server_info:\n enabled_servers[server_path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n\n # Broadcast health status update to WebSocket clients\n await health_service.broadcast_health_update(path)\n\n # Remove server from scopes.yml and reload auth server\n try:\n await remove_server_scopes(path)\n logger.info(f\"Successfully removed server {path} from scopes\")\n except Exception as e:\n logger.warning(f\"Failed to remove server {path} from scopes: {e}\")\n\n # Deletion webhook (Issue #742): server_info was fetched before removal\n asyncio.create_task(\n send_registration_webhook(\n event_type=\"deletion\",\n registration_type=\"server\",\n card_data=server_info,\n performed_by=user_context.get(\"username\"),\n )\n )\n\n return JSONResponse(\n status_code=200,\n content={\"message\": \"Service removed successfully\", \"path\": path},\n )\n\n\n# IMPORTANT: Specific routes with path suffixes (/health, /rate, /rating, /toggle)\n# must come BEFORE catch-all /servers/ routes to prevent FastAPI from matching them incorrectly\n\n\n@router.get(\"/servers/health\")\nasync def healthcheck_api(\n request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Get health status for all registered services via JWT authentication (External API).\n\n This endpoint provides the same functionality as GET /api/internal/healthcheck\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Response:**\n Returns health status for all services.\n\n **Example:**\n ```bash\n curl -X GET https://registry.example.com/api/servers/health \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n ```\n \"\"\"\n from ..health.service import health_service\n\n logger.info(\n f\"API healthcheck request from user '{user_context.get('username') if user_context else 'unknown'}'\"\n )\n\n # Get health status for all servers using JWT authentication\n try:\n health_data = await health_service.get_all_health_status()\n logger.info(f\"Retrieved health status for {len(health_data)} servers\")\n\n return JSONResponse(status_code=200, content=health_data)\n\n except Exception as e:\n logger.exception(\"Failed to retrieve health status\")\n raise HTTPException(status_code=500, detail=\"Failed to retrieve health status\")\n\n\n@router.post(\"/servers/groups/add\")\nasync def add_server_to_groups_api(\n request: Request,\n server_name: Annotated[str, Form()],\n group_names: Annotated[str, Form()],\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Add a service to scope groups via JWT authentication (External API).\n\n This endpoint provides the same functionality as POST /api/internal/add-to-groups\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request body (form data):**\n - `server_name` (required): Service name\n - `group_names` (required): Comma-separated list of group names\n\n **Response:**\n Returns confirmation of group assignment.\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/groups/add \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -F \"server_name=myservice\" \\\\\n -F \"group_names=admin,developers\"\n ```\n \"\"\"\n logger.info(\n f\"API add to groups request from user '{user_context.get('username')}' for server '{server_name}'\"\n )\n\n # Call the shared implementation\n return await _add_server_to_groups_impl(server_name, group_names)\n\n\n@router.post(\"/servers/groups/remove\")\nasync def remove_server_from_groups_api(\n request: Request,\n server_name: Annotated[str, Form()],\n group_names: Annotated[str, Form()],\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Remove a service from scope groups via JWT authentication (External API).\n\n This endpoint provides the same functionality as POST /api/internal/remove-from-groups\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request body (form data):**\n - `server_name` (required): Service name\n - `group_names` (required): Comma-separated list of group names to remove\n\n **Response:**\n Returns confirmation of removal from groups.\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/groups/remove \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -F \"server_name=myservice\" \\\\\n -F \"group_names=developers\"\n ```\n \"\"\"\n logger.info(\n f\"API remove from groups request from user '{user_context.get('username')}' for server '{server_name}'\"\n )\n\n # Call the shared implementation\n return await _remove_server_from_groups_impl(server_name, group_names)\n\n\nasync def _create_group_impl(\n group_name: str,\n description: str = \"\",\n create_in_idp: bool = False,\n) -> JSONResponse:\n \"\"\"\n Internal implementation for group creation.\n\n This function contains the business logic for creating a group\n and can be called from both Basic Auth and JWT endpoints.\n \"\"\"\n from ..services.scope_service import create_group\n from ..utils.iam_manager import get_iam_manager\n\n # Validate group name\n if not group_name or not group_name.strip():\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST, detail=\"Group name is required\"\n )\n\n try:\n # Create in IdP first if requested\n idp_created = False\n if create_in_idp:\n try:\n iam_manager = get_iam_manager()\n # Check if group already exists in IdP\n existing_groups = await iam_manager.list_groups()\n group_exists = any(\n g.get(\"name\", \"\").lower() == group_name.lower() for g in existing_groups\n )\n if group_exists:\n logger.warning(f\"Group '{group_name}' already exists in IdP\")\n else:\n await iam_manager.create_group(group_name, description)\n idp_created = True\n logger.info(f\"Group '{group_name}' created in IdP\")\n except Exception as e:\n logger.exception(\"Failed to create group in IdP\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to create group in IdP\",\n )\n\n # Create in scopes (file or OpenSearch based on STORAGE_BACKEND)\n scopes_success = await create_group(group_name, description)\n\n if scopes_success:\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Group successfully created\",\n \"group_name\": group_name,\n \"created_in_idp\": idp_created,\n \"created_in_scopes\": True,\n },\n )\n else:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Failed to create group in scopes (may already exist)\",\n )\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(f\"Error creating group '{group_name}'\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server error\",\n )\n\n\n@router.post(\"/servers/groups/create\")\nasync def create_group_api(\n request: Request,\n group_name: Annotated[str, Form()],\n description: Annotated[str, Form()] = \"\",\n create_in_idp: Annotated[bool, Form()] = False,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Create a new scope group via JWT authentication (External API).\n\n This endpoint provides the same functionality as POST /api/internal/create-group\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request body (form data):**\n - `group_name` (required): Name of the new group\n - `description` (optional): Group description\n - `create_in_idp` (optional): Whether to create in IdP (default: false)\n\n **Response:**\n Returns confirmation of group creation.\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/groups/create \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -F \"group_name=new-team\" \\\\\n -F \"description=Team for new project\" \\\\\n -F \"create_in_idp=true\"\n ```\n \"\"\"\n logger.info(\n f\"API create group request from user '{user_context.get('username')}' for group '{group_name}'\"\n )\n\n # Call the shared implementation\n return await _create_group_impl(group_name, description, create_in_idp)\n\n\nasync def _delete_group_impl(\n group_name: str,\n delete_from_idp: bool = True,\n force: bool = False,\n) -> JSONResponse:\n \"\"\"\n Internal implementation for group deletion.\n\n This function contains the business logic for deleting a group\n and can be called from both Basic Auth and JWT endpoints.\n Uses the IAMManager abstraction to support any identity provider.\n \"\"\"\n from ..services.scope_service import delete_group\n from ..utils.iam_manager import get_iam_manager\n\n # Validate group name\n if not group_name or not group_name.strip():\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST, detail=\"Group name is required\"\n )\n\n # Prevent deletion of system groups unless force=True\n if not force:\n system_groups = [\n \"UI-Scopes\",\n \"group_mappings\",\n \"mcp-registry-admin\",\n \"mcp-registry-user\",\n \"mcp-registry-developer\",\n \"mcp-registry-operator\",\n ]\n\n if group_name in system_groups:\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Cannot delete system group '{group_name}'. Use force=true to override.\",\n )\n\n try:\n # Delete from scopes (file or OpenSearch)\n scopes_success = await delete_group(group_name, remove_from_mappings=True)\n\n if not scopes_success:\n logger.warning(f\"Group '{group_name}' not found in scopes or deletion failed\")\n\n # Delete from identity provider if requested\n idp_deleted = False\n if delete_from_idp:\n try:\n iam = get_iam_manager()\n if await iam.group_exists(group_name):\n await iam.delete_group(group_name)\n idp_deleted = True\n logger.info(f\"Group '{group_name}' deleted from identity provider\")\n else:\n logger.warning(f\"Group '{group_name}' not found in identity provider\")\n except Exception as e:\n logger.error(f\"Failed to delete group from identity provider: {e}\")\n # Continue anyway - scopes deletion might have succeeded\n\n if scopes_success or idp_deleted:\n return JSONResponse(\n status_code=200,\n content={\n \"message\": \"Group deletion completed\",\n \"group_name\": group_name,\n \"deleted_from_keycloak\": idp_deleted,\n \"deleted_from_scopes\": scopes_success,\n },\n )\n else:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Group '{group_name}' not found in either identity provider or scopes\",\n )\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(f\"Error deleting group '{group_name}'\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server error\",\n )\n\n\n@router.post(\"/servers/groups/delete\")\nasync def delete_group_api(\n request: Request,\n group_name: Annotated[str, Form()],\n delete_from_keycloak: Annotated[bool, Form()] = True,\n force: Annotated[bool, Form()] = False,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Delete a scope group via JWT authentication (External API).\n\n This endpoint provides the same functionality as POST /api/internal/delete-group\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request body (form data):**\n - `group_name` (required): Name of the group to delete\n - `delete_from_keycloak` (optional): Whether to delete from Keycloak (default: true)\n - `force` (optional): Force deletion of system groups (default: false)\n\n **Response:**\n Returns confirmation of group deletion.\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/groups/delete \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -F \"group_name=old-team\" \\\\\n -F \"delete_from_keycloak=true\" \\\\\n -F \"force=false\"\n ```\n \"\"\"\n logger.info(\n f\"API delete group request from user '{user_context.get('username')}' for group '{group_name}'\"\n )\n\n # Call the shared implementation\n return await _delete_group_impl(group_name, delete_from_idp=delete_from_keycloak, force=force)\n\n\n@router.get(\"/servers/groups\")\nasync def list_groups_api(\n request: Request,\n include_keycloak: bool = True,\n include_scopes: bool = True,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n List all scope groups via JWT Bearer Token authentication (External API).\n\n This endpoint provides the same functionality as GET /api/internal/list-groups\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Response:**\n Returns a list of all groups and their synchronization status.\n\n **Example:**\n ```bash\n curl -X GET https://registry.example.com/api/servers/groups \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n ```\n \"\"\"\n logger.info(\n f\"API list groups request from user '{user_context.get('username') if user_context else 'unknown'}'\"\n )\n\n # Call the shared implementation\n return await _list_groups_impl(include_idp=include_keycloak, include_scopes=include_scopes)\n\n\n@router.get(\"/servers/groups/{group_name}\")\nasync def get_group_api(\n group_name: str,\n request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Get full details of a specific group via JWT Bearer Token authentication (External API).\n\n This endpoint retrieves complete information about a group including server_access,\n group_mappings, and ui_permissions from the scopes storage backend.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Response:**\n Returns complete group definition including:\n - scope_name: Name of the scope/group\n - scope_type: Type of scope (e.g., \"server_scope\")\n - description: Description of the group\n - server_access: List of server access definitions\n - group_mappings: List of group mappings\n - ui_permissions: UI permissions configuration\n - created_at: Creation timestamp\n - updated_at: Last update timestamp\n\n **Example:**\n ```bash\n curl -X GET https://registry.example.com/api/servers/groups/currenttime-users \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n ```\n \"\"\"\n from ..services.scope_service import get_group\n\n logger.info(\n f\"API get group request from user '{user_context.get('username') if user_context else 'unknown'}' \"\n f\"for group '{group_name}'\"\n )\n\n try:\n group_data = await get_group(group_name)\n\n if not group_data:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Group '{group_name}' not found\",\n )\n\n return JSONResponse(status_code=200, content=group_data)\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(f\"Error getting group {group_name}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server error\",\n )\n\n\n@router.post(\"/servers/groups/import\")\nasync def import_group_definition(\n request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Import a complete group definition via JSON (External API).\n\n This endpoint accepts a complete group definition including all three document types\n (server_scope, group_mapping, ui_scope) and creates/updates them in the storage backend.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Request Body:**\n ```json\n {\n \"scope_name\": \"group-name\",\n \"scope_type\": \"server_scope\",\n \"description\": \"Group description\",\n \"server_access\": [\n {\n \"server\": \"currenttime\",\n \"methods\": [\"initialize\", \"tools/list\", \"tools/call\"],\n \"tools\": [\"current_time_by_timezone\"]\n }\n ],\n \"group_mappings\": [\"group-name\", \"other-group\"],\n \"ui_permissions\": {\n \"list_service\": [\"currenttime\", \"mcpgw\"],\n \"list_agents\": [\"/code-reviewer\"],\n \"health_check_service\": [\"currenttime\"]\n },\n \"create_in_idp\": true\n }\n ```\n\n **Required Fields:**\n - `scope_name`: Name of the scope/group\n\n **Optional Fields:**\n - `scope_type`: Type of scope (default: \"server_scope\")\n - `description`: Description of the group\n - `server_access`: List of server access definitions\n - `group_mappings`: List of group names this group maps to\n - `ui_permissions`: Dictionary of UI permissions\n - `create_in_idp`: Whether to create the group in IdP (default: true)\n\n **Example:**\n ```bash\n curl -X POST https://registry.example.com/api/servers/groups/import \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\" \\\\\n -H \"Content-Type: application/json\" \\\\\n -d @group-definition.json\n ```\n \"\"\"\n from ..services.scope_service import import_group\n from ..utils.iam_manager import get_iam_manager\n\n try:\n # Parse request body\n body = await request.json()\n\n # Required field\n scope_name = body.get(\"scope_name\")\n if not scope_name:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"scope_name is required\",\n )\n\n # Optional fields\n scope_type = body.get(\"scope_type\", \"server_scope\")\n description = body.get(\"description\", \"\")\n server_access = body.get(\"server_access\")\n group_mappings = body.get(\"group_mappings\")\n ui_permissions = body.get(\"ui_permissions\")\n # Support both create_in_idp (new) and create_in_keycloak (legacy)\n create_in_idp = body.get(\"create_in_idp\", body.get(\"create_in_keycloak\", True))\n\n logger.info(\n f\"API import group request from user '{user_context.get('username') if user_context else 'unknown'}' \"\n f\"for group '{scope_name}'\"\n )\n\n # Import group definition\n success = await import_group(\n scope_name=scope_name,\n scope_type=scope_type,\n description=description,\n server_access=server_access,\n group_mappings=group_mappings,\n ui_permissions=ui_permissions,\n )\n\n if not success:\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=f\"Failed to import group {scope_name}\",\n )\n\n # Create in IdP if requested\n idp_created = False\n idp_group_id = None\n if create_in_idp:\n try:\n iam_manager = get_iam_manager()\n result = await iam_manager.create_group(scope_name, description)\n if result:\n idp_created = True\n idp_group_id = result.get(\"id\")\n logger.info(f\"Created group {scope_name} in IdP with ID: {idp_group_id}\")\n\n # For Entra ID only: add group ID (GUID) to group_mappings\n # Entra returns GUIDs in tokens, while Keycloak returns group names\n # This ensures token group claims match scope group_mappings\n auth_provider = os.environ.get(\"AUTH_PROVIDER\", \"keycloak\").lower()\n if auth_provider == \"entra\" and idp_group_id:\n from ..services.scope_service import (\n add_group_mapping_to_scope,\n )\n\n mapping_success = await add_group_mapping_to_scope(scope_name, idp_group_id)\n if mapping_success:\n logger.info(\n f\"Added Entra group ID {idp_group_id} to scope \"\n f\"{scope_name} group_mappings\"\n )\n else:\n logger.warning(f\"Failed to add Entra group ID to scope {scope_name}\")\n else:\n logger.warning(\n f\"Failed to create group {scope_name} in IdP (may already exist)\"\n )\n except Exception as e:\n logger.error(f\"Error creating IdP group {scope_name}: {e}\")\n\n # Trigger auth server reload\n from ..services.scope_service import trigger_auth_server_reload\n\n reload_success = await trigger_auth_server_reload()\n\n return JSONResponse(\n status_code=200,\n content={\n \"message\": f\"Group {scope_name} imported successfully\",\n \"group_name\": scope_name,\n \"idp_created\": idp_created,\n \"auth_server_reloaded\": reload_success,\n },\n )\n\n except HTTPException:\n raise\n except Exception as e:\n logger.exception(\"Error importing group definition\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server error\",\n )\n\n\n@router.post(\"/servers/{path:path}/rate\")\nasync def rate_server(\n request: Request,\n path: str,\n rating_request: RatingRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"Save integer ratings to server.\"\"\"\n # Set audit action for server rating\n set_audit_action(\n request,\n \"rate\",\n \"server\",\n resource_id=path,\n description=f\"Rate server with {rating_request.rating}\",\n )\n\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n server_info = await server_service.get_server_info(path)\n # Try with trailing slash if not found (path normalization)\n if not server_info and not path.endswith(\"/\"):\n path_with_slash = path + \"/\"\n server_info = await server_service.get_server_info(path_with_slash)\n if server_info:\n path = path_with_slash\n if not server_info:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Server not found at path '{path}'\",\n )\n\n # Use the actual path from the server (handles trailing slash normalization)\n actual_path = server_info.get(\"path\", path)\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n actual_path, user_context[\"accessible_servers\"]\n ):\n logger.warning(\n f\"User {user_context['username']} attempted to rate server {actual_path} without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n try:\n avg_rating = await server_service.update_rating(\n actual_path, user_context[\"username\"], rating_request.rating\n )\n except ValueError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=str(e),\n )\n except Exception as e:\n logger.error(f\"Unexpected error updating rating: {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to save rating\",\n )\n\n return {\n \"message\": \"Rating added successfully\",\n \"average_rating\": avg_rating,\n }\n\n\n@router.get(\"/servers/{path:path}/rating\")\nasync def get_server_rating(\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"Get server rating information.\"\"\"\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n server_info = await server_service.get_server_info(path)\n # Try with trailing slash if not found (path normalization)\n if not server_info and not path.endswith(\"/\"):\n path_with_slash = path + \"/\"\n server_info = await server_service.get_server_info(path_with_slash)\n if server_info:\n path = path_with_slash\n if not server_info:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Server not found at path '{path}'\",\n )\n\n # For non-admin users, check if they have access to this specific server\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n path, user_context[\"accessible_servers\"]\n ):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n return {\n \"num_stars\": server_info.get(\"num_stars\", 0),\n \"rating_details\": server_info.get(\"rating_details\", []),\n }\n\n\n@router.get(\"/servers/{path:path}/security-scan\")\nasync def get_server_security_scan(\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Get security scan results for a server.\n\n Returns the latest security scan results for the specified server,\n including threat analysis, severity levels, and detailed findings.\n\n **Authentication:** JWT Bearer token or session cookie\n **Authorization:** Requires admin privileges or access to the server\n\n **Path Parameters:**\n - `path` (required): Server path (e.g., /cloudflare-docs)\n\n **Response:**\n Returns security scan results with analysis_results and tool_results.\n\n **Example:**\n ```bash\n curl -X GET http://localhost/api/servers/cloudflare-docs/security-scan \\\\\n --cookie-jar .cookies --cookie .cookies\n ```\n \"\"\"\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Check if server exists\n server_info = await server_service.get_server_info(path)\n if not server_info:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Server not found at path '{path}'\",\n )\n\n # Check user permissions\n if not user_context[\"is_admin\"]:\n if not await server_service.user_can_access_server_path(\n path, user_context[\"accessible_servers\"]\n ):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n # Get scan results\n scan_result = await security_scanner_service.get_scan_result(path)\n if not scan_result:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"No security scan results found for server '{path}'. \"\n \"The server may not have been scanned yet.\",\n )\n\n return scan_result\n\n\n@router.post(\"/servers/{path:path}/rescan\")\nasync def rescan_server(\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Trigger a manual security scan for a server.\n\n Initiates a new security scan for the specified server and returns\n the results. This endpoint is useful for re-scanning servers after\n updates or for on-demand security assessments.\n\n **Authentication:** JWT Bearer token or session cookie\n **Authorization:** Requires admin privileges\n\n **Path Parameters:**\n - `path` (required): Server path (e.g., /cloudflare-docs)\n\n **Response:**\n Returns the newly generated security scan results.\n\n **Example:**\n ```bash\n curl -X POST http://localhost/api/servers/cloudflare-docs/rescan \\\\\n --cookie-jar .cookies --cookie .cookies\n ```\n \"\"\"\n # Only admins can trigger manual scans\n if not user_context[\"is_admin\"]:\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Only administrators can trigger security scans\",\n )\n\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Check if server exists (include credentials for authenticated scans)\n server_info = await server_service.get_server_info(path, include_credentials=True)\n if not server_info:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Server not found at path '{path}'\",\n )\n\n # Get server URL from server info\n server_url = server_info.get(\"proxy_pass_url\")\n if not server_url:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=f\"Server '{path}' does not have a proxy_pass_url configured\",\n )\n\n # Build auth headers for the scanner if server has stored credentials\n headers_json = _build_scan_headers_from_credentials(server_info)\n\n logger.info(\n f\"Manual security scan requested by user '{user_context.get('username')}' \"\n f\"for server '{path}' at URL '{server_url}'\"\n )\n\n try:\n # Trigger security scan\n scan_result = await security_scanner_service.scan_server(\n server_url=server_url,\n server_path=path,\n analyzers=None,\n api_key=None,\n headers=headers_json,\n timeout=None,\n mcp_endpoint=server_info.get(\"mcp_endpoint\"),\n )\n\n # Return the scan result data\n return {\n \"server_url\": scan_result.server_url,\n \"server_path\": path,\n \"scan_timestamp\": scan_result.scan_timestamp,\n \"is_safe\": scan_result.is_safe,\n \"critical_issues\": scan_result.critical_issues,\n \"high_severity\": scan_result.high_severity,\n \"medium_severity\": scan_result.medium_severity,\n \"low_severity\": scan_result.low_severity,\n \"analyzers_used\": scan_result.analyzers_used,\n \"scan_failed\": scan_result.scan_failed,\n \"error_message\": scan_result.error_message,\n \"raw_output\": scan_result.raw_output,\n }\n except Exception as e:\n logger.exception(f\"Failed to scan server '{path}': {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to scan server\",\n )\n\n\n@router.get(\"/servers/tools/{service_path:path}\")\nasync def get_service_tools_api(\n service_path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Get tool list for a service via JWT Bearer Token authentication (External API).\n\n This endpoint provides the same functionality as GET /tools/{service_path}\n but uses modern JWT Bearer token authentication.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n **Authorization:** Requires valid JWT token from auth system\n\n **Path Parameters:**\n - `service_path` (required): Service path (e.g., /myservice or /all for all services)\n\n **Response:**\n Returns the list of tools available on the service, filtered by user permissions.\n\n **Example:**\n ```bash\n curl -X GET https://registry.example.com/api/servers/tools/myservice \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n\n # Get tools from all accessible services\n curl -X GET https://registry.example.com/api/servers/tools/all \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n ```\n \"\"\"\n logger.info(\n f\"API get tools request from user '{user_context.get('username') if user_context else 'unknown'}' for path '{service_path}'\"\n )\n\n # Call the existing get_service_tools function\n return await get_service_tools(service_path=service_path, user_context=user_context)\n\n\n# ============================================================================\n# Server Version Management Endpoints\n# ============================================================================\n\n\nclass SetDefaultVersion(BaseModel):\n \"\"\"Request model for setting default version.\"\"\"\n\n version: str\n\n\n@router.delete(\"/servers/{service_path:path}/versions/{version}\")\nasync def remove_server_version(\n service_path: str,\n version: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Remove a version from a server.\n\n Args:\n service_path: Server path (URL encoded)\n version: Version to remove\n\n Returns:\n Success message\n \"\"\"\n decoded_path = \"/\" + service_path if not service_path.startswith(\"/\") else service_path\n\n try:\n result = await server_service.remove_server_version(path=decoded_path, version=version)\n\n if result:\n return {\n \"status\": \"success\",\n \"message\": f\"Version {version} removed from {decoded_path}\",\n }\n else:\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=\"Failed to remove version\"\n )\n\n except ValueError as e:\n raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))\n\n\n@router.put(\"/servers/{service_path:path}/versions/default\")\nasync def set_default_version(\n service_path: str,\n version_data: SetDefaultVersion,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Set the default (latest) version for a server.\n\n Args:\n service_path: Server path (URL encoded)\n version_data: Contains version to set as default\n\n Returns:\n Success message\n \"\"\"\n decoded_path = \"/\" + service_path if not service_path.startswith(\"/\") else service_path\n\n try:\n result = await server_service.set_default_version(\n path=decoded_path, version=version_data.version\n )\n\n if result:\n return {\n \"status\": \"success\",\n \"message\": f\"Default version set to {version_data.version} for {decoded_path}\",\n }\n else:\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to set default version\",\n )\n\n except ValueError as e:\n raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))\n\n\n@router.get(\"/servers/{service_path:path}/versions\")\nasync def get_server_versions(\n service_path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)] = None,\n):\n \"\"\"\n Get all versions for a server.\n\n Args:\n service_path: Server path (URL encoded)\n\n Returns:\n Version information\n \"\"\"\n decoded_path = \"/\" + service_path if not service_path.startswith(\"/\") else service_path\n\n try:\n return await server_service.get_server_versions(decoded_path)\n\n except ValueError as e:\n raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))\n\n\n# IMPORTANT: This catch-all route must remain AFTER all /servers/{path}/... suffixed routes\n@router.get(\"/servers/{path:path}\")\nasync def get_server(\n request: Request,\n path: str,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n):\n \"\"\"\n Get detailed information about a single MCP server.\n\n Returns the server card including tools, versions, and health status.\n Mirrors the GET /api/agents/{path} endpoint pattern.\n\n **Authentication:** JWT Bearer token (via nginx X-User header)\n\n **Path parameter:**\n - `path`: Server path (e.g., /my-server)\n\n **Response:**\n - `200 OK`: Server details\n - `403 Forbidden`: User lacks access\n - `404 Not Found`: Server not found\n\n **Example:**\n ```bash\n curl -X GET https://registry.example.com/api/servers/my-server \\\\\n -H \"Authorization: Bearer $JWT_TOKEN\"\n ```\n \"\"\"\n set_audit_action(\n request,\n \"read\",\n \"server\",\n resource_id=path,\n description=f\"Read server {path}\",\n )\n\n # Normalize path — add leading slash if missing\n if not path.startswith(\"/\"):\n path = \"/\" + path\n\n # Look up server\n server_info = await server_service.get_server_info(path)\n if not server_info:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Server not found at path '{path}'\",\n )\n\n # Access control — admin users bypass checks\n if not user_context.get(\"is_admin\"):\n accessible_servers = user_context.get(\"accessible_servers\", [])\n has_access = await server_service.user_can_access_server_path(path, accessible_servers)\n if not has_access:\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"You do not have access to this server\",\n )\n\n # Strip proxy_pass_url for non-admin users in with-gateway mode.\n # In registry-only mode, users need the URL to connect directly.\n if not user_context.get(\"is_admin\"):\n if settings.deployment_mode != DeploymentMode.REGISTRY_ONLY:\n server_info.pop(\"proxy_pass_url\", None)\n\n return JSONResponse(\n status_code=200,\n content=json.loads(json.dumps(server_info, default=str)),\n )\n" }, { "path": "registry/api/skill_routes.py", "content": "\"\"\"\nAPI routes for skill management.\n\nAll recommendations implemented:\n- Authentication required on all endpoints\n- Visibility filtering in list operations\n- Path normalization via dependency\n- Domain-specific exception handling\n- Discovery endpoint for coding assistants\n- Resource content served via the /content endpoint\n\"\"\"\n\nimport asyncio\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import (\n Annotated,\n Any,\n)\n\nfrom fastapi import (\n APIRouter,\n Depends,\n HTTPException,\n Path,\n Query,\n Request,\n status,\n)\nfrom pydantic import BaseModel\n\nfrom ..audit.context import set_audit_action\nfrom ..auth.csrf import verify_csrf_token_flexible\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..exceptions import (\n SkillAlreadyExistsError,\n SkillServiceError,\n SkillUrlValidationError,\n SkillValidationError,\n)\nfrom ..schemas.skill_models import (\n DiscoveryResponse,\n SkillCard,\n SkillInfo,\n SkillMetadata,\n SkillRegistrationRequest,\n SkillTier1_Metadata,\n ToggleStateRequest,\n ToolValidationResult,\n VisibilityEnum,\n)\nfrom ..exceptions import (\n SkillContentFetchError,\n SkillContentSSRFError,\n SkillContentTooLargeError,\n)\nfrom ..services.skill_service import (\n _build_fetch_headers,\n _check_drift_inline,\n _decrypt_skill_auth,\n _discover_skill_resources,\n _fetch_authenticated_content,\n _is_safe_url,\n get_skill_service,\n)\nfrom ..services.registration_gate_service import check_registration_gate\nfrom ..services.tool_validation_service import get_tool_validation_service\nfrom ..services.webhook_service import send_registration_webhook\nfrom ..utils.metadata import flatten_metadata_to_text\nfrom ..utils.path_utils import normalize_skill_path\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass RatingRequest(BaseModel):\n \"\"\"Request model for rating a skill.\"\"\"\n\n rating: int\n\n\nrouter = APIRouter(prefix=\"/skills\", tags=[\"skills\"])\n\n_SKILL_CARD_EXCLUDE = {\"auth_credential_encrypted\"}\n\n\n# Dependency for normalized path\ndef get_normalized_path(\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> str:\n \"\"\"Normalize skill path.\"\"\"\n return normalize_skill_path(skill_path)\n\n\n@router.get(\n \"/discovery\",\n response_model=DiscoveryResponse,\n summary=\"Discovery endpoint for coding assistants\",\n)\nasync def discover_skills(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n query: str | None = Query(None, description=\"Search query\"),\n tags: list[str] | None = Query(None, description=\"Filter by tags\"),\n compatibility: str | None = Query(None, description=\"Filter by compatibility\"),\n page: int = Query(0, ge=0),\n page_size: int = Query(100, ge=1, le=500),\n) -> DiscoveryResponse:\n \"\"\"Discovery endpoint optimized for coding assistants.\n\n Returns lightweight metadata for efficient loading.\n \"\"\"\n service = get_skill_service()\n skills = await service.list_skills_for_user(user_context)\n\n # Apply filters\n if tags:\n skills = [s for s in skills if any(t in s.tags for t in tags)]\n\n if compatibility:\n skills = [\n s\n for s in skills\n if s.compatibility and compatibility.lower() in s.compatibility.lower()\n ]\n\n # Pagination\n total = len(skills)\n start = page * page_size\n end = start + page_size\n paginated = skills[start:end]\n\n # Convert to Tier1 metadata\n tier1_skills = [\n SkillTier1_Metadata(\n path=s.path,\n name=s.name,\n description=s.description,\n skill_md_url=s.skill_md_url,\n skill_md_raw_url=s.skill_md_raw_url,\n tags=s.tags,\n compatibility=s.compatibility,\n target_agents=s.target_agents,\n )\n for s in paginated\n ]\n\n return DiscoveryResponse(\n skills=tier1_skills,\n total_count=total,\n page=page,\n page_size=page_size,\n )\n\n\n@router.get(\"\", summary=\"List all skills\")\nasync def list_skills(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n include_disabled: bool = Query(False, description=\"Include disabled skills\"),\n tag: str | None = Query(None, description=\"Filter by tag\"),\n limit: int = Query(20, ge=1, le=500, description=\"Number of skills to return (max 500)\"),\n offset: int = Query(0, ge=0, description=\"Number of skills to skip\"),\n) -> dict:\n \"\"\"List all registered skills with visibility filtering and pagination.\"\"\"\n logger.debug(\n f\"list_skills called: limit={limit}, offset={offset}, \"\n f\"tag={tag!r}, include_disabled={include_disabled}\"\n )\n\n service = get_skill_service()\n\n # Determine if user has unrestricted access (no skills will be filtered out)\n is_admin = user_context.get(\"is_admin\", False) if user_context else False\n accessible_agent_list = user_context.get(\"accessible_agents\", []) if user_context else []\n is_unrestricted = is_admin or \"all\" in accessible_agent_list\n # include_disabled=False (default) means \"exclude disabled\" which IS a filter.\n # Only include_disabled=True (show all) with no tag requires no filtering.\n has_field_filters = bool(tag or not include_disabled)\n\n # Dual-path pagination:\n # - Fast path: DB-level skip/limit for unrestricted users without field filters\n # - Fallback: full fetch + Python filter + slice for restricted users or field filters\n if is_unrestricted and not has_field_filters:\n # FAST PATH: DB-level pagination -- correct because no skills are filtered out\n # and no field filters need a full scan for accurate total_count\n skill_cards, db_total = await service.get_skills_paginated(\n skip=offset,\n limit=limit,\n )\n skills = [\n SkillInfo(\n id=s.id,\n path=s.path,\n name=s.name,\n description=s.description,\n skill_md_url=str(s.skill_md_url),\n skill_md_raw_url=str(s.skill_md_raw_url) if s.skill_md_raw_url else None,\n repository_url=s.repository_url,\n tags=s.tags,\n author=s.metadata.author if s.metadata else None,\n version=s.metadata.version if s.metadata else None,\n metadata=s.metadata,\n compatibility=s.compatibility,\n target_agents=s.target_agents,\n is_enabled=s.is_enabled,\n visibility=s.visibility,\n allowed_groups=s.allowed_groups,\n registry_name=s.registry_name,\n owner=s.owner,\n auth_scheme=s.auth_scheme,\n auth_header_name=s.auth_header_name,\n num_stars=s.num_stars,\n health_status=s.health_status,\n last_checked_time=s.last_checked_time,\n status=s.status,\n )\n for s in skill_cards\n ]\n total_count = db_total\n page_skills = skills\n else:\n # FALLBACK PATH: full fetch needed for filtering or restricted users\n all_skills = await service.list_skills_for_user(\n user_context=user_context,\n include_disabled=include_disabled,\n tag=tag,\n )\n total_count = len(all_skills)\n page_skills = all_skills[offset : offset + limit]\n\n has_next = (offset + limit) < total_count\n\n logger.info(\n f\"Returning {len(page_skills)} skills for user \"\n f\"{user_context.get('username', 'unknown')} \"\n f\"(total: {total_count}, offset: {offset}, limit: {limit})\"\n )\n return {\n \"skills\": [skill.model_dump(mode=\"json\") for skill in page_skills],\n \"total_count\": total_count,\n \"limit\": limit,\n \"offset\": offset,\n \"has_next\": has_next,\n }\n\n\n@router.post(\"/parse-skill-md\", summary=\"Parse SKILL.md content from URL\")\nasync def parse_skill_md(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n url: str = Query(..., description=\"URL to SKILL.md file\"),\n auth_scheme: str = Query(\"none\", description=\"Auth scheme: none, global_credentials, bearer, api_key\"),\n auth_credential: str | None = Query(None, description=\"Plaintext credential for bearer/api_key\"),\n auth_header_name: str | None = Query(None, description=\"Custom header name for api_key scheme\"),\n) -> dict:\n \"\"\"Parse SKILL.md content and extract metadata.\n\n Returns name, description, version, and tags from the SKILL.md file.\n Useful for auto-populating the skill registration form.\n Accepts optional auth parameters for parsing private repo SKILL.md files.\n \"\"\"\n service = get_skill_service()\n try:\n result = await service.parse_skill_md(\n url,\n auth_scheme=auth_scheme,\n auth_credential=auth_credential,\n auth_header_name=auth_header_name,\n )\n return {\n \"success\": True,\n \"name\": result.get(\"name\"),\n \"name_slug\": result.get(\"name_slug\"),\n \"description\": result.get(\"description\"),\n \"version\": result.get(\"version\"),\n \"tags\": result.get(\"tags\", []),\n \"content_version\": result.get(\"content_version\"),\n \"skill_md_url\": result.get(\"skill_md_url\"),\n \"skill_md_raw_url\": result.get(\"skill_md_raw_url\"),\n \"repository_url\": result.get(\"repository_url\"),\n }\n except SkillUrlValidationError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST, detail=f\"Failed to parse SKILL.md: {e.reason}\"\n )\n\n\n@router.get(\"/search\", summary=\"Search skills\")\nasync def search_skills(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n q: str = Query(\n ...,\n description=\"Lexical substring search across skill name, description, tags, and metadata\",\n ),\n tags: str | None = Query(None, description=\"Comma-separated tags to filter by\"),\n include_deprecated: bool = Query(False, description=\"Include deprecated skills in results\"),\n include_draft: bool = Query(False, description=\"Include draft skills in results\"),\n) -> dict:\n \"\"\"Search for skills by name, description, tags, and metadata.\n\n Uses lexical (substring) search with basic relevance scoring, not\n hybrid/semantic. For vector-based search, use POST /api/search/semantic instead.\n Deprecated and draft skills are excluded by default.\n \"\"\"\n service = get_skill_service()\n skills = await service.list_skills_for_user(user_context)\n\n query_lower = q.lower()\n tag_list = [t.strip() for t in tags.split(\",\")] if tags else []\n\n # Build set of excluded lifecycle statuses\n excluded_statuses: set[str] = set()\n if not include_deprecated:\n excluded_statuses.add(\"deprecated\")\n if not include_draft:\n excluded_statuses.add(\"draft\")\n\n matching_skills = []\n for skill in skills:\n # Filter by lifecycle status\n skill_status = getattr(skill, \"status\", \"active\") or \"active\"\n if skill_status in excluded_statuses:\n continue\n\n score = 0.0\n\n # Match in name (highest priority)\n if query_lower in skill.name.lower():\n score += 0.5\n\n # Match in description\n if skill.description and query_lower in skill.description.lower():\n score += 0.3\n\n # Match in tags\n skill_tags_lower = [t.lower() for t in (skill.tags or [])]\n if any(query_lower in t for t in skill_tags_lower):\n score += 0.2\n\n # Match in metadata (author, version, extra key-value pairs)\n skill_meta_dict: dict[str, Any] = {}\n if skill.metadata:\n if skill.metadata.author:\n skill_meta_dict[\"author\"] = skill.metadata.author\n if skill.metadata.version:\n skill_meta_dict[\"version\"] = skill.metadata.version\n if skill.metadata.extra:\n skill_meta_dict.update(skill.metadata.extra)\n metadata_text = flatten_metadata_to_text(skill_meta_dict)\n if metadata_text and query_lower in metadata_text.lower():\n score += 0.1\n\n # Filter by specified tags\n if tag_list:\n if not all(t.lower() in skill_tags_lower for t in tag_list):\n continue\n\n if score > 0:\n matching_skills.append(\n {\n \"path\": skill.path,\n \"name\": skill.name,\n \"description\": skill.description,\n \"tags\": skill.tags,\n \"visibility\": skill.visibility,\n \"is_enabled\": skill.is_enabled,\n \"status\": skill_status,\n \"relevance_score\": score,\n }\n )\n\n # Sort by relevance score descending\n matching_skills.sort(key=lambda x: x[\"relevance_score\"], reverse=True)\n\n return {\n \"query\": q,\n \"skills\": matching_skills,\n \"total_count\": len(matching_skills),\n }\n\n\n@router.get(\"/{skill_path:path}/integrity\", summary=\"Get content integrity status\")\nasync def get_integrity_status(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> dict:\n \"\"\"Return the stored content integrity record for a skill.\n\n This is a read-only view of the baseline hashes and drift state\n that were computed at registration and updated on every content fetch.\n No external requests are made.\n \"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n skill = await service.get_skill(normalized_path)\n\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Skill not found: {normalized_path}\",\n )\n\n if not _user_can_access_skill(skill, user_context):\n raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Access denied\")\n\n integrity = skill.content_integrity\n if not integrity:\n return {\n \"path\": normalized_path,\n \"has_baseline\": False,\n \"message\": \"No integrity baseline. Re-register the skill to compute one.\",\n }\n\n return {\n \"path\": normalized_path,\n \"has_baseline\": True,\n \"composite_hash\": integrity.composite_hash,\n \"computed_at\": integrity.computed_at.isoformat() if integrity.computed_at else None,\n \"drift_detected\": integrity.drift_detected,\n \"last_drift_check\": integrity.last_drift_check.isoformat() if integrity.last_drift_check else None,\n \"drifted_files\": integrity.drifted_files,\n \"file_count\": len(integrity.file_hashes),\n \"files\": [\n {\"path\": fh.path, \"sha256\": fh.sha256, \"size_bytes\": fh.size_bytes}\n for fh in integrity.file_hashes\n ],\n }\n\n\n@router.get(\"/{skill_path:path}/health\", summary=\"Check skill health\")\nasync def check_skill_health(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> dict:\n \"\"\"Check skill health by performing HEAD request to SKILL.md URL.\n\n Returns health status, HTTP status code, and response time.\n \"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n result = await service.check_skill_health(normalized_path)\n return {\n \"path\": normalized_path,\n \"healthy\": result[\"healthy\"],\n \"status_code\": result[\"status_code\"],\n \"error\": result[\"error\"],\n \"response_time_ms\": result[\"response_time_ms\"],\n }\n\n\nMAX_RESOURCE_SIZE = 512 * 1024 # 512 KB\n\n\n@router.get(\"/{skill_path:path}/content\", summary=\"Get SKILL.md content\")\nasync def get_skill_content(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n resource: str | None = Query(\n None,\n description=\"Optional relative path to a companion resource file. \"\n \"When omitted, returns SKILL.md content.\",\n ),\n) -> dict:\n \"\"\"Fetch skill content.\n\n Without ``resource``: returns SKILL.md markdown and the resource manifest.\n With ``resource``: returns the content of the specified companion file\n (validated against the stored manifest to prevent path traversal).\n \"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n skill = await service.get_skill(normalized_path)\n\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Skill not found: {normalized_path}\",\n )\n\n if not _user_can_access_skill(skill, user_context):\n raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Access denied\")\n\n if (\n skill.content_integrity\n and skill.content_integrity.drift_detected\n ):\n raise HTTPException(\n status_code=status.HTTP_409_CONFLICT,\n detail=(\n f\"Content drift detected for {normalized_path}. \"\n f\"Drifted files: {', '.join(skill.content_integrity.drifted_files)}. \"\n \"The skill has been disabled. Re-register to update the baseline.\"\n ),\n )\n\n # For federated skills with inline content, serve directly from DB\n if skill.skill_md_content:\n return {\n \"content\": skill.skill_md_content,\n \"source\": \"inline\",\n \"path\": normalized_path,\n }\n\n raw_url = skill.skill_md_raw_url or skill.skill_md_url\n if not raw_url:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=\"No SKILL.md URL configured for this skill\",\n )\n\n try:\n if resource is not None:\n manifest = skill.resource_manifest\n if not manifest:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=\"No resource manifest available for this skill\",\n )\n all_resources = manifest.references + manifest.scripts + manifest.agents + manifest.assets\n matched = [r for r in all_resources if r.path == resource]\n if not matched:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Resource '{resource}' not found in manifest\",\n )\n\n from ..utils.url_utils import derive_resource_url\n\n resource_url = derive_resource_url(str(raw_url), resource)\n response = await _fetch_authenticated_content(\n resource_url, skill, max_size=MAX_RESOURCE_SIZE,\n )\n\n drift_task = asyncio.create_task(\n _check_drift_inline(service, normalized_path, skill, resource, response.content)\n )\n drift_task.add_done_callback(_log_task_exception)\n\n return {\n \"content\": response.text,\n \"path\": resource,\n \"type\": matched[0].type,\n \"url\": resource_url,\n }\n\n response = await _fetch_authenticated_content(str(raw_url), skill)\n\n drift_task = asyncio.create_task(\n _check_drift_inline(service, normalized_path, skill, \"SKILL.md\", response.content)\n )\n drift_task.add_done_callback(_log_task_exception)\n\n result: dict[str, Any] = {\n \"content\": response.text,\n \"url\": str(raw_url),\n }\n if skill.resource_manifest:\n result[\"resource_manifest\"] = skill.resource_manifest.model_dump()\n if skill.content_integrity:\n result[\"drift_detected\"] = skill.content_integrity.drift_detected\n return result\n\n except SkillContentSSRFError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=f\"URL failed SSRF validation: {e.url}\",\n )\n except SkillContentTooLargeError as e:\n raise HTTPException(\n status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,\n detail=str(e),\n )\n except SkillContentFetchError as e:\n raise HTTPException(\n status_code=status.HTTP_502_BAD_GATEWAY,\n detail=str(e),\n )\n\n\n@router.get(\n \"/{skill_path:path}/tools\",\n response_model=ToolValidationResult,\n summary=\"Get required tools with availability\",\n)\nasync def get_skill_tools(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> ToolValidationResult:\n \"\"\"Get required tools for a skill with availability status.\"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n skill = await service.get_skill(normalized_path)\n\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n tool_service = get_tool_validation_service()\n return await tool_service.validate_tools_available(skill)\n\n\n@router.get(\"/{skill_path:path}/rating\", response_model=dict, summary=\"Get skill rating\")\nasync def get_skill_rating(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> dict:\n \"\"\"Get rating information for a skill.\n\n Returns the average rating and list of individual ratings.\n \"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n\n # Check skill exists and user has access\n skill = await service.get_skill(normalized_path)\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n if not _user_can_access_skill(skill, user_context):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN, detail=\"You do not have access to this skill\"\n )\n\n return {\n \"num_stars\": skill.num_stars,\n \"rating_details\": skill.rating_details,\n }\n\n\n# ---------------------------------------------------------------------------\n# Security scan endpoints (must be before catch-all GET /{skill_path:path})\n# ---------------------------------------------------------------------------\n\n\n@router.get(\n \"/{skill_path:path}/security-scan\",\n response_model=dict,\n summary=\"Get skill security scan results\",\n)\nasync def get_skill_security_scan(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path\"),\n) -> dict:\n \"\"\"Get the latest security scan results for a skill.\"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n\n skill = await service.get_skill(normalized_path)\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Skill not found: {normalized_path}\",\n )\n\n if not _user_can_access_skill(skill, user_context):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Access denied\",\n )\n\n from ..services.skill_scanner import skill_scanner_service\n\n scan_result = await skill_scanner_service.get_scan_result(normalized_path)\n if not scan_result:\n return {\"message\": \"No security scan results available\", \"skill_path\": normalized_path}\n\n return scan_result\n\n\n@router.post(\n \"/{skill_path:path}/rescan\",\n response_model=dict,\n summary=\"Trigger manual security scan\",\n)\nasync def rescan_skill(\n http_request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path\"),\n) -> dict:\n \"\"\"Trigger a manual security scan for a skill. Admin only.\"\"\"\n if not user_context.get(\"is_admin\"):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Admin access required\",\n )\n\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n\n skill = await service.get_skill(normalized_path)\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Skill not found: {normalized_path}\",\n )\n\n set_audit_action(\n http_request,\n \"rescan\",\n \"skill\",\n resource_id=normalized_path,\n description=f\"Manual security scan for skill {normalized_path}\",\n )\n\n from ..services.skill_scanner import skill_scanner_service\n\n try:\n result = await skill_scanner_service.scan_skill(\n skill_path=normalized_path,\n skill_md_url=str(skill.skill_md_raw_url or skill.skill_md_url),\n )\n return result.model_dump()\n\n except Exception as e:\n logger.error(f\"Manual security scan failed for skill '{normalized_path}': {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=f\"Security scan failed: {str(e)}\",\n )\n\n\n\n@router.post(\n \"/{skill_path:path}/refresh-resources\",\n response_model=dict,\n summary=\"Refresh skill resource manifest\",\n)\nasync def refresh_skill_resources(\n http_request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> dict:\n \"\"\"Re-discover companion resource files and update the stored manifest.\n\n Useful when new files have been added to the skill's repository directory\n without re-registering the skill.\n \"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n skill = await service.get_skill(normalized_path)\n\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n if not _user_can_modify_skill(skill, user_context):\n raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Access denied\")\n\n set_audit_action(\n http_request,\n \"refresh_resources\",\n \"skill\",\n resource_id=normalized_path,\n description=f\"Refresh resource manifest for {normalized_path}\",\n )\n\n raw_url = str(skill.skill_md_raw_url or skill.skill_md_url)\n auth_scheme, credential, auth_header_name = _decrypt_skill_auth(skill)\n\n manifest = await _discover_skill_resources(\n raw_url,\n auth_scheme=auth_scheme,\n auth_credential=credential,\n auth_header_name=auth_header_name,\n )\n\n updates = {\"resource_manifest\": manifest.model_dump() if manifest else None}\n await service.update_skill(normalized_path, updates)\n\n total = 0\n if manifest:\n total = len(manifest.references) + len(manifest.scripts) + len(manifest.agents) + len(manifest.assets)\n\n return {\n \"path\": normalized_path,\n \"resources_discovered\": total,\n \"resource_manifest\": manifest.model_dump() if manifest else None,\n }\n\n\n@router.get(\"/{skill_path:path}\", response_model=SkillCard, response_model_exclude=_SKILL_CARD_EXCLUDE, summary=\"Get a skill by path\")\nasync def get_skill(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> SkillCard:\n \"\"\"Get a specific skill by its path.\"\"\"\n normalized_path = normalize_skill_path(skill_path)\n service = get_skill_service()\n skill = await service.get_skill(normalized_path)\n\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n # Check visibility\n if not _user_can_access_skill(skill, user_context):\n raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Access denied\")\n\n return skill\n\n\n@router.post(\n \"\",\n response_model=SkillCard,\n response_model_exclude=_SKILL_CARD_EXCLUDE,\n status_code=status.HTTP_201_CREATED,\n summary=\"Register a new skill\",\n)\nasync def register_skill(\n http_request: Request,\n request: SkillRegistrationRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n) -> SkillCard:\n \"\"\"Register a new skill in the registry.\"\"\"\n # Set audit action for skill registration\n # Note: path is derived from name, so use name as resource_id\n set_audit_action(\n http_request,\n \"create\",\n \"skill\",\n resource_id=request.name,\n description=f\"Register skill {request.name}\",\n )\n\n # Registration gate check (admission control, issue #809)\n gate_result = await check_registration_gate(\n asset_type=\"skill\",\n operation=\"register\",\n source_api=\"/api/skills\",\n registration_payload=request.model_dump(mode=\"json\"),\n raw_headers=http_request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied skill '{request.name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n service = get_skill_service()\n owner = user_context.get(\"username\")\n\n try:\n skill = await service.register_skill(request=request, owner=owner, validate_url=True)\n logger.info(f\"Registered skill: {skill.name} by {owner}\")\n\n # Security scanning if enabled (non-blocking — mirrors server registration pattern)\n scan_task = asyncio.create_task(\n _perform_skill_security_scan_on_registration(skill, service)\n )\n scan_task.add_done_callback(_log_task_exception)\n\n asyncio.create_task(\n send_registration_webhook(\n event_type=\"registration\",\n registration_type=\"skill\",\n card_data=skill.model_dump(mode=\"json\"),\n performed_by=owner,\n )\n )\n\n return skill\n\n except SkillUrlValidationError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST, detail=f\"Invalid SKILL.md URL: {e.reason}\"\n )\n except SkillAlreadyExistsError as e:\n raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e))\n except SkillValidationError as e:\n raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))\n except SkillServiceError as e:\n logger.error(f\"Failed to register skill: {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=\"Failed to register skill\"\n )\n\n\n@router.put(\"/{skill_path:path}\", response_model=SkillCard, response_model_exclude=_SKILL_CARD_EXCLUDE, summary=\"Update a skill\")\nasync def update_skill(\n http_request: Request,\n request: SkillRegistrationRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> SkillCard:\n \"\"\"Update an existing skill.\"\"\"\n normalized_path = normalize_skill_path(skill_path)\n\n # Set audit action for skill update\n set_audit_action(\n http_request,\n \"update\",\n \"skill\",\n resource_id=normalized_path,\n description=f\"Update skill {request.name}\",\n )\n\n service = get_skill_service()\n\n # Check ownership\n existing = await service.get_skill(normalized_path)\n if not existing:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n if not _user_can_modify_skill(existing, user_context):\n raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Access denied\")\n\n # Registration gate check for update (admission control, issue #809)\n gate_result = await check_registration_gate(\n asset_type=\"skill\",\n operation=\"update\",\n source_api=f\"/api/skills/{normalized_path}\",\n registration_payload=request.model_dump(mode=\"json\"),\n raw_headers=http_request.scope.get(\"headers\", []),\n )\n if not gate_result.allowed:\n logger.warning(\n f\"Registration gate denied skill update '{request.name}': \"\n f\"{gate_result.error_message}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Registration denied by policy gate: {gate_result.error_message}\",\n )\n\n updates = request.model_dump(exclude_unset=True, mode=\"json\")\n\n # Convert raw metadata dict to SkillMetadata structure for consistent storage\n if \"metadata\" in updates and updates[\"metadata\"] is not None:\n raw_meta = updates[\"metadata\"]\n updates[\"metadata\"] = SkillMetadata(\n author=raw_meta.get(\"author\"),\n version=raw_meta.get(\"version\"),\n extra={k: v for k, v in raw_meta.items() if k not in (\"author\", \"version\")},\n ).model_dump(mode=\"json\")\n\n # Encrypt credential if provided on update\n auth_credential = updates.pop(\"auth_credential\", None)\n auth_scheme = updates.get(\"auth_scheme\", existing.auth_scheme)\n if auth_credential and auth_scheme not in (\"none\", \"global_credentials\"):\n from ..utils.credential_encryption import encrypt_credential\n\n updates[\"auth_credential_encrypted\"] = encrypt_credential(auth_credential)\n updates[\"credential_updated_at\"] = datetime.now(UTC).isoformat()\n elif auth_scheme in (\"none\", \"global_credentials\"):\n updates[\"auth_credential_encrypted\"] = None\n updates[\"auth_header_name\"] = None\n updates[\"credential_updated_at\"] = None\n\n updated = await service.update_skill(normalized_path, updates)\n\n if not updated:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n return updated\n\n\n@router.delete(\n \"/{skill_path:path}\", status_code=status.HTTP_204_NO_CONTENT, summary=\"Delete a skill\"\n)\nasync def delete_skill(\n http_request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> None:\n \"\"\"Delete a skill from the registry.\"\"\"\n normalized_path = normalize_skill_path(skill_path)\n\n # Set audit action for skill deletion\n set_audit_action(\n http_request,\n \"delete\",\n \"skill\",\n resource_id=normalized_path,\n description=f\"Delete skill at {normalized_path}\",\n )\n\n service = get_skill_service()\n\n # Check ownership\n existing = await service.get_skill(normalized_path)\n if not existing:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n if not _user_can_modify_skill(existing, user_context):\n raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Access denied\")\n\n success = await service.delete_skill(normalized_path)\n\n if not success:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n asyncio.create_task(\n send_registration_webhook(\n event_type=\"deletion\",\n registration_type=\"skill\",\n card_data=existing.model_dump(mode=\"json\"),\n performed_by=user_context.get(\"username\"),\n )\n )\n\n\n@router.post(\"/{skill_path:path}/toggle\", response_model=dict, summary=\"Toggle skill enabled state\")\nasync def toggle_skill(\n http_request: Request,\n request: ToggleStateRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n _csrf: Annotated[None, Depends(verify_csrf_token_flexible)] = None,\n) -> dict:\n \"\"\"Toggle a skill's enabled state.\"\"\"\n normalized_path = normalize_skill_path(skill_path)\n\n # Set audit action for skill toggle\n set_audit_action(\n http_request,\n \"toggle\",\n \"skill\",\n resource_id=normalized_path,\n description=f\"Toggle skill to {request.enabled}\",\n )\n\n service = get_skill_service()\n\n # Check ownership\n existing = await service.get_skill(normalized_path)\n if not existing:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n if not _user_can_modify_skill(existing, user_context):\n raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Access denied\")\n\n success = await service.toggle_skill(normalized_path, request.enabled)\n\n if not success:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n return {\"path\": normalized_path, \"is_enabled\": request.enabled}\n\n\n@router.post(\"/{skill_path:path}/rate\", response_model=dict, summary=\"Rate a skill\")\nasync def rate_skill(\n http_request: Request,\n rating_request: RatingRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n skill_path: str = Path(..., description=\"Skill path or name\"),\n) -> dict:\n \"\"\"Submit a rating for a skill.\n\n Users can rate skills from 1-5 stars. Each user can only have one\n rating per skill - submitting a new rating updates the previous one.\n \"\"\"\n normalized_path = normalize_skill_path(skill_path)\n\n # Set audit action for skill rating\n set_audit_action(\n http_request,\n \"rate\",\n \"skill\",\n resource_id=normalized_path,\n description=f\"Rate skill with {rating_request.rating}\",\n )\n\n service = get_skill_service()\n\n # Check skill exists and user has access\n skill = await service.get_skill(normalized_path)\n if not skill:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND, detail=f\"Skill not found: {normalized_path}\"\n )\n\n if not _user_can_access_skill(skill, user_context):\n logger.warning(\n f\"User {user_context.get('username')} attempted to rate skill \"\n f\"{normalized_path} without permission\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN, detail=\"You do not have access to this skill\"\n )\n\n try:\n avg_rating = await service.update_rating(\n normalized_path, user_context[\"username\"], rating_request.rating\n )\n except ValueError as e:\n raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))\n\n return {\n \"message\": \"Rating added successfully\",\n \"average_rating\": avg_rating,\n }\n\n\n# Helper functions\n\n\ndef _log_task_exception(task: asyncio.Task) -> None:\n \"\"\"Done-callback that surfaces unhandled exceptions from background tasks.\n\n Without this, exceptions raised inside ``asyncio.create_task(...)``\n fire-and-forget calls are only visible when the garbage collector\n finalises the task, which is too late for production debugging.\n \"\"\"\n if task.cancelled():\n return\n exc = task.exception()\n if exc is not None:\n logger.error(\"Background task failed: %s\", exc, exc_info=exc)\n\n\ndef _user_can_access_skill(\n skill: SkillCard,\n user_context: dict,\n) -> bool:\n \"\"\"Check if user can access skill based on visibility.\"\"\"\n if user_context.get(\"is_admin\"):\n return True\n\n visibility = skill.visibility\n\n if visibility == VisibilityEnum.PUBLIC:\n return True\n\n if visibility == VisibilityEnum.PRIVATE:\n return skill.owner == user_context.get(\"username\")\n\n if visibility == VisibilityEnum.GROUP:\n user_groups = set(user_context.get(\"groups\", []))\n return bool(user_groups & set(skill.allowed_groups))\n\n return False\n\n\ndef _user_can_modify_skill(\n skill: SkillCard,\n user_context: dict,\n) -> bool:\n \"\"\"Check if user can modify skill.\"\"\"\n if user_context.get(\"is_admin\"):\n return True\n\n return skill.owner == user_context.get(\"username\")\n\n\nasync def _perform_skill_security_scan_on_registration(\n skill: SkillCard,\n service,\n) -> None:\n \"\"\"Perform security scan on newly registered skill.\n\n Mirrors the MCP server registration scan pattern:\n - Builds auth headers from the skill's encrypted credential\n - Passes headers to the scanner for authenticated downloads\n - Adds security-pending tag if scan fails\n - Disables skill if configured and scan fails\n - All scan failures are non-fatal and logged but not raised.\n\n Args:\n skill: The registered skill card\n service: The skill service instance\n \"\"\"\n from ..services.skill_scanner import skill_scanner_service\n\n config = skill_scanner_service.get_scan_config()\n\n if not config.enabled or not config.scan_on_registration:\n logger.info(\"Skill security scanning disabled, skipping\")\n return\n\n logger.info(f\"Performing security scan for skill: {skill.path}\")\n\n try:\n raw_url = str(skill.skill_md_raw_url or skill.skill_md_url)\n auth_scheme, credential, auth_header_name = _decrypt_skill_auth(skill)\n fetch_headers: dict[str, str] = {}\n if credential:\n raw_url, fetch_headers = _build_fetch_headers(\n raw_url, auth_scheme, credential, auth_header_name,\n )\n\n result = await skill_scanner_service.scan_skill(\n skill_path=skill.path,\n skill_md_url=raw_url,\n headers=fetch_headers or None,\n )\n\n if not result.is_safe and config.block_unsafe_skills:\n logger.warning(f\"Disabling unsafe skill: {skill.path}\")\n await service.toggle_skill(skill.path, enabled=False)\n\n if config.add_security_pending_tag:\n current_tags = skill.tags or []\n if \"security-pending\" not in current_tags:\n await service.update_skill(\n skill.path, {\"tags\": current_tags + [\"security-pending\"]}\n )\n\n except Exception as e:\n logger.error(f\"Security scan failed for skill {skill.path}: {e}\")\n if config.add_security_pending_tag:\n try:\n current_tags = skill.tags or []\n if \"security-pending\" not in current_tags:\n await service.update_skill(\n skill.path, {\"tags\": current_tags + [\"security-pending\"]}\n )\n except Exception as tag_err:\n logger.error(f\"Failed to add security-pending tag: {tag_err}\")\n\n\n" }, { "path": "registry/api/system_routes.py", "content": "\"\"\"\nSystem information and operational API routes.\n\nThese endpoints provide system-level information for monitoring and display.\n\"\"\"\n\nimport logging\nimport os\nfrom datetime import UTC, datetime\n\nfrom fastapi import APIRouter, HTTPException\n\nfrom ..core.config import settings\nfrom ..version import __version__\n\nlogger = logging.getLogger(__name__)\nrouter = APIRouter()\n\n\n# Global variables for server start time and stats caching\n_server_start_time: datetime | None = None\n_stats_cache: dict | None = None\n_stats_cache_time: datetime | None = None\nSTATS_CACHE_TTL_SECONDS = 30 # Cache stats for 30 seconds\n\n\ndef set_server_start_time(\n start_time: datetime,\n) -> None:\n \"\"\"Set the server start time (called from main.py lifespan).\"\"\"\n global _server_start_time\n _server_start_time = start_time\n logger.info(f\"System routes: Server start time set to {start_time.isoformat()}\")\n\n\ndef get_server_start_time() -> datetime | None:\n \"\"\"Get the server start time.\n\n Returns:\n Server start time if set, None otherwise\n \"\"\"\n return _server_start_time\n\n\ndef _detect_deployment_type() -> str:\n \"\"\"Auto-detect deployment environment based on environment variables.\n\n Detection order:\n 1. Kubernetes - Check for KUBERNETES_SERVICE_HOST\n 2. ECS - Check for ECS_CONTAINER_METADATA_URI\n 3. EC2 - Check for AWS_EXECUTION_ENV\n 4. Local - Default fallback\n\n Returns:\n Deployment type: \"Kubernetes\", \"ECS\", \"EC2\", or \"Local\"\n \"\"\"\n # Check for Kubernetes\n if os.getenv(\"KUBERNETES_SERVICE_HOST\"):\n return \"Kubernetes\"\n\n # Check for ECS\n if os.getenv(\"ECS_CONTAINER_METADATA_URI\") or os.getenv(\"ECS_CONTAINER_METADATA_URI_V4\"):\n return \"ECS\"\n\n # Check for EC2\n if os.getenv(\"AWS_EXECUTION_ENV\") == \"AWS_ECS_EC2\":\n return \"EC2\"\n\n # Default to Local\n return \"Local\"\n\n\nasync def _get_registry_stats() -> dict:\n \"\"\"Get current registry statistics (servers, agents, skills counts).\n\n Uses efficient count() methods instead of loading all resources.\n\n Returns:\n Dictionary with servers, agents, skills counts\n \"\"\"\n try:\n # Import repositories\n from registry.repositories.factory import (\n get_agent_repository,\n get_server_repository,\n get_skill_repository,\n )\n\n # Get repository instances\n server_repo = get_server_repository()\n agent_repo = get_agent_repository()\n skill_repo = get_skill_repository()\n\n # Count resources efficiently using count() methods\n servers_count = await server_repo.count()\n agents_count = await agent_repo.count()\n skills_count = await skill_repo.count()\n\n return {\n \"servers\": servers_count,\n \"agents\": agents_count,\n \"skills\": skills_count,\n }\n except Exception as e:\n logger.error(f\"Failed to get registry stats: {e}\")\n # Return zeros on error\n return {\n \"servers\": 0,\n \"agents\": 0,\n \"skills\": 0,\n }\n\n\nasync def _get_auth_status() -> dict:\n \"\"\"Check authentication server health and connection status.\n\n Returns:\n Dictionary with provider, status, and URL information\n \"\"\"\n provider = settings.auth_provider\n auth_url = settings.auth_server_url\n\n # Try to ping the auth server health endpoint\n try:\n import httpx\n\n async with httpx.AsyncClient(timeout=5.0) as client:\n # Try common health check endpoints\n health_endpoints = [\n f\"{auth_url}/health\",\n f\"{auth_url}/healthcheck\",\n f\"{auth_url}/.well-known/openid-configuration\",\n ]\n\n for endpoint in health_endpoints:\n try:\n response = await client.get(endpoint)\n if response.status_code < 500: # 2xx, 3xx, 4xx are all \"reachable\"\n return {\n \"provider\": provider,\n \"status\": \"Healthy\",\n \"url\": auth_url,\n }\n except Exception:\n continue\n\n # If all endpoints failed, auth server is unhealthy\n return {\n \"provider\": provider,\n \"status\": \"Unhealthy\",\n \"url\": auth_url,\n }\n\n except Exception as e:\n logger.error(f\"Auth server health check failed: {e}\")\n return {\n \"provider\": provider,\n \"status\": \"Unhealthy\",\n \"url\": auth_url,\n }\n\n\nasync def _get_database_status() -> dict:\n \"\"\"Check database health and connection status.\n\n Returns:\n Dictionary with backend, status, and host information\n \"\"\"\n backend = settings.storage_backend\n\n # File backend has no database to check\n if backend == \"file\":\n return {\n \"backend\": \"file\",\n \"status\": \"N/A\",\n \"host\": \"N/A\",\n }\n\n # DocumentDB/MongoDB backend - check connection\n try:\n from registry.repositories.documentdb.client import get_documentdb_client\n\n db = await get_documentdb_client()\n\n # Try to ping the database (db is AsyncIOMotorDatabase, not client)\n await db.command(\"ping\")\n\n # Get host information\n host_str = f\"{settings.documentdb_host}:{settings.documentdb_port}\"\n\n return {\n \"backend\": backend,\n \"status\": \"Healthy\",\n \"host\": host_str,\n }\n except Exception as e:\n logger.error(f\"Database health check failed: {e}\")\n host_str = f\"{settings.documentdb_host}:{settings.documentdb_port}\"\n return {\n \"backend\": backend,\n \"status\": \"Unhealthy\",\n \"host\": host_str,\n }\n\n\nasync def _get_registry_card_status() -> dict:\n \"\"\"Get registry card initialization status.\n\n Returns:\n Dictionary with registry card status information\n \"\"\"\n try:\n from registry.repositories.factory import get_registry_card_repository\n\n repo = get_registry_card_repository()\n card = await repo.get()\n\n if card:\n return {\n \"initialized\": True,\n \"registry_id\": str(card.id),\n \"name\": card.name,\n }\n else:\n return {\n \"initialized\": False,\n \"registry_id\": None,\n \"name\": None,\n }\n except Exception as e:\n logger.error(f\"Failed to get registry card status: {e}\")\n return {\n \"initialized\": False,\n \"registry_id\": None,\n \"name\": None,\n }\n\n\nasync def _get_cached_stats() -> dict:\n \"\"\"Get system stats with caching to reduce load.\n\n Cache TTL: 30 seconds\n\n Returns:\n Cached or freshly computed stats dictionary\n \"\"\"\n global _stats_cache, _stats_cache_time\n\n now = datetime.now(UTC)\n\n # Check if cache is valid\n if (\n _stats_cache is not None\n and _stats_cache_time is not None\n and (now - _stats_cache_time).total_seconds() < STATS_CACHE_TTL_SECONDS\n ):\n return _stats_cache\n\n # Compute fresh stats\n registry_stats = await _get_registry_stats()\n database_status = await _get_database_status()\n auth_status = await _get_auth_status()\n registry_card_status = await _get_registry_card_status()\n\n # Calculate uptime\n if _server_start_time:\n uptime_seconds = int((now - _server_start_time).total_seconds())\n started_at = _server_start_time\n else:\n # Fallback if start time not set (shouldn't happen)\n uptime_seconds = 0\n started_at = now\n\n stats = {\n \"uptime_seconds\": uptime_seconds,\n \"started_at\": started_at.isoformat(),\n \"version\": __version__,\n \"deployment_type\": _detect_deployment_type(),\n \"deployment_mode\": settings.deployment_mode.value,\n \"registry_stats\": registry_stats,\n \"database_status\": database_status,\n \"auth_status\": auth_status,\n \"registry_card_status\": registry_card_status,\n }\n\n # Update cache\n _stats_cache = stats\n _stats_cache_time = now\n\n return stats\n\n\n@router.get(\"/api/version\")\nasync def get_version():\n \"\"\"Get application version.\n\n Returns:\n Dictionary with version string\n \"\"\"\n return {\"version\": __version__}\n\n\n@router.get(\"/api/stats\")\nasync def get_system_stats():\n \"\"\"Get system statistics including uptime, deployment info, and registry metrics.\n\n This endpoint provides operational information for monitoring and display:\n - Application uptime since last restart\n - Deployment environment and mode\n - Registry resource counts (servers, agents, skills)\n - Database health status\n - Registry card initialization status\n\n Response is cached for 30 seconds to reduce load.\n\n Returns:\n System statistics dictionary with:\n - uptime_seconds: Time since server started\n - started_at: ISO 8601 timestamp of server start\n - version: Application version\n - deployment_type: Kubernetes/ECS/EC2/Local\n - deployment_mode: with-gateway/registry-only\n - registry_stats: Object with servers, agents, skills counts\n - database_status: Object with backend, status, host\n - auth_status: Object with provider, status, url\n - registry_card_status: Object with initialized, registry_id, name\n \"\"\"\n try:\n stats = await _get_cached_stats()\n return stats\n except Exception as e:\n logger.error(f\"Failed to get system stats: {e}\", exc_info=True)\n raise HTTPException(status_code=500, detail=\"Failed to compute system statistics\")\n" }, { "path": "registry/api/virtual_server_routes.py", "content": "\"\"\"\nAPI routes for virtual MCP server management.\n\nProvides CRUD endpoints for virtual servers that aggregate tools\nfrom multiple backend MCP servers, plus a global tool catalog endpoint.\n\"\"\"\n\nimport logging\nimport re\nfrom typing import Annotated\n\nfrom fastapi import (\n APIRouter,\n Depends,\n HTTPException,\n Path,\n Query,\n Request,\n status,\n)\nfrom pydantic import BaseModel\n\nfrom ..audit.context import set_audit_action\nfrom ..auth.csrf import verify_csrf_token_flexible\nfrom ..auth.dependencies import nginx_proxied_auth\nfrom ..exceptions import (\n VirtualServerAlreadyExistsError,\n VirtualServerNotFoundError,\n VirtualServerServiceError,\n VirtualServerValidationError,\n)\nfrom ..schemas.virtual_server_models import (\n CreateVirtualServerRequest,\n ToggleVirtualServerRequest,\n UpdateVirtualServerRequest,\n VirtualServerConfig,\n)\nfrom ..services.tool_catalog_service import get_tool_catalog_service\nfrom ..services.virtual_server_service import get_virtual_server_service\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nrouter = APIRouter()\n\n\ndef _require_admin(\n user_context: dict,\n) -> None:\n \"\"\"Check that user has admin or server-modify permissions.\n\n Args:\n user_context: Authenticated user context\n\n Raises:\n HTTPException: 403 if user lacks permissions\n \"\"\"\n is_admin = user_context.get(\"is_admin\", False)\n can_modify = user_context.get(\"can_modify_servers\", False)\n\n # Also check groups and scopes for mcp-registry-admin\n groups = user_context.get(\"groups\", [])\n scopes = user_context.get(\"scopes\", [])\n has_admin_group = \"mcp-registry-admin\" in groups\n has_admin_scope = \"mcp-registry-admin\" in scopes\n\n if not (is_admin or can_modify or has_admin_group or has_admin_scope):\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Admin or server-modify permissions required\",\n )\n\n\n_VALID_VIRTUAL_PATH_RE = re.compile(r\"^/virtual/[a-z0-9]+(-[a-z0-9]+)*$\")\n\n\ndef _normalize_virtual_path(\n raw_path: str,\n) -> str:\n \"\"\"Normalize and validate a virtual server path from URL path parameter.\n\n Rejects paths containing '..', special characters, or anything that\n doesn't match the expected /virtual/ format.\n\n Args:\n raw_path: Raw path from URL (may not have /virtual/ prefix)\n\n Returns:\n Normalized path with /virtual/ prefix\n\n Raises:\n HTTPException: 400 if path contains invalid characters or format\n \"\"\"\n if \"..\" in raw_path:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=\"Invalid virtual server path: path traversal not allowed\",\n )\n\n if raw_path.startswith(\"/virtual/\"):\n normalized = raw_path\n elif raw_path.startswith(\"virtual/\"):\n normalized = f\"/{raw_path}\"\n else:\n normalized = f\"/virtual/{raw_path}\"\n\n if not _VALID_VIRTUAL_PATH_RE.match(normalized):\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=(\n \"Invalid virtual server path: must match /virtual/ \"\n \"where slug is lowercase alphanumeric with hyphens\"\n ),\n )\n\n return normalized\n\n\n# --- Virtual Server CRUD Endpoints ---\n# NOTE: Route order matters! Sub-resource routes (tools, toggle) must be\n# declared before the catch-all {vs_path:path} GET route to avoid the\n# :path parameter consuming \"tools\" or \"toggle\" as part of the path.\n\n\n@router.get(\n \"/virtual-servers\",\n response_model=dict,\n summary=\"List all virtual servers\",\n)\nasync def list_virtual_servers(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n) -> dict:\n \"\"\"List all virtual servers with summary information.\"\"\"\n service = get_virtual_server_service()\n all_servers = await service.list_virtual_servers()\n\n # Filter based on list_virtual_server permission\n ui_permissions = user_context.get(\"ui_permissions\", {})\n list_virtual_perms = ui_permissions.get(\"list_virtual_server\", [])\n\n # Admin users or users with \"all\" permission see everything\n if user_context.get(\"is_admin\") or \"all\" in list_virtual_perms:\n filtered_servers = all_servers\n else:\n # Filter to only virtual servers the user has explicit permission for\n # Permission values are virtual server paths like \"/virtual/my-server\"\n normalized_perms = [p.strip(\"/\") for p in list_virtual_perms]\n filtered_servers = [s for s in all_servers if s.path.strip(\"/\") in normalized_perms]\n\n logger.info(\n f\"Returning {len(filtered_servers)} virtual servers for user \"\n f\"{user_context.get('username', 'unknown')} (filtered from {len(all_servers)} total)\"\n )\n return {\n \"virtual_servers\": [s.model_dump(mode=\"json\") for s in filtered_servers],\n \"total_count\": len(filtered_servers),\n }\n\n\n@router.get(\n \"/virtual-servers/{vs_path:path}/tools\",\n response_model=dict,\n summary=\"List resolved tools for a virtual server\",\n)\nasync def get_virtual_server_tools(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n vs_path: str = Path(..., description=\"Virtual server path\"),\n) -> dict:\n \"\"\"Get the resolved tool list for a virtual server.\n\n Returns all tools with their final names, sources, and metadata.\n \"\"\"\n normalized = _normalize_virtual_path(vs_path)\n service = get_virtual_server_service()\n\n try:\n tools = await service.resolve_tools(normalized)\n return {\n \"path\": normalized,\n \"tools\": [t.model_dump(mode=\"json\") for t in tools],\n \"total_count\": len(tools),\n }\n except VirtualServerNotFoundError:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n\n\n# --- Rating Endpoints (must be before catch-all GET) ---\n\n\nclass RatingRequest(BaseModel):\n \"\"\"Request model for rating a virtual server.\"\"\"\n\n rating: int\n\n\n@router.post(\n \"/virtual-servers/{vs_path:path}/rate\",\n response_model=dict,\n summary=\"Rate a virtual server\",\n)\nasync def rate_virtual_server(\n http_request: Request,\n rating_request: RatingRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n vs_path: str = Path(..., description=\"Virtual server path\"),\n) -> dict:\n \"\"\"Submit or update a rating for a virtual server.\n\n Requires authentication. Each user can have one rating per server.\n \"\"\"\n normalized = _normalize_virtual_path(vs_path)\n username = user_context.get(\"username\", \"anonymous\")\n\n set_audit_action(\n http_request,\n \"rate\",\n \"virtual_server\",\n resource_id=normalized,\n description=f\"Rate virtual server with {rating_request.rating} stars\",\n )\n\n service = get_virtual_server_service()\n\n try:\n result = await service.rate_virtual_server(\n path=normalized,\n username=username,\n rating=rating_request.rating,\n )\n return result\n except VirtualServerNotFoundError:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n except ValueError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=str(e),\n )\n\n\n@router.get(\n \"/virtual-servers/{vs_path:path}/rating\",\n response_model=dict,\n summary=\"Get virtual server rating\",\n)\nasync def get_virtual_server_rating(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n vs_path: str = Path(..., description=\"Virtual server path\"),\n) -> dict:\n \"\"\"Get rating information for a virtual server.\"\"\"\n normalized = _normalize_virtual_path(vs_path)\n service = get_virtual_server_service()\n\n try:\n return await service.get_virtual_server_rating(normalized)\n except VirtualServerNotFoundError:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n\n\n@router.get(\n \"/virtual-servers/{vs_path:path}\",\n response_model=VirtualServerConfig,\n summary=\"Get a virtual server by path\",\n)\nasync def get_virtual_server(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n vs_path: str = Path(..., description=\"Virtual server path\"),\n) -> VirtualServerConfig:\n \"\"\"Get detailed configuration for a virtual server.\"\"\"\n normalized = _normalize_virtual_path(vs_path)\n service = get_virtual_server_service()\n config = await service.get_virtual_server(normalized)\n\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n\n return config\n\n\n@router.post(\n \"/virtual-servers\",\n response_model=VirtualServerConfig,\n status_code=status.HTTP_201_CREATED,\n summary=\"Create a virtual server\",\n)\nasync def create_virtual_server(\n http_request: Request,\n request: CreateVirtualServerRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n) -> VirtualServerConfig:\n \"\"\"Create a new virtual MCP server.\n\n Requires admin or server-modify permissions.\n \"\"\"\n _require_admin(user_context)\n\n set_audit_action(\n http_request,\n \"create\",\n \"virtual_server\",\n resource_id=request.server_name,\n description=f\"Create virtual server '{request.server_name}'\",\n )\n\n service = get_virtual_server_service()\n created_by = user_context.get(\"username\")\n\n try:\n config = await service.create_virtual_server(\n request=request,\n created_by=created_by,\n )\n logger.info(\n f\"Created virtual server '{config.server_name}' at {config.path} by {created_by}\"\n )\n return config\n\n except VirtualServerAlreadyExistsError as e:\n raise HTTPException(\n status_code=status.HTTP_409_CONFLICT,\n detail=str(e),\n )\n except VirtualServerValidationError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=str(e),\n )\n except VirtualServerServiceError as e:\n logger.error(f\"Failed to create virtual server: {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to create virtual server\",\n )\n\n\n@router.put(\n \"/virtual-servers/{vs_path:path}\",\n response_model=VirtualServerConfig,\n summary=\"Update a virtual server\",\n)\nasync def update_virtual_server(\n http_request: Request,\n request: UpdateVirtualServerRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n vs_path: str = Path(..., description=\"Virtual server path\"),\n) -> VirtualServerConfig:\n \"\"\"Update an existing virtual MCP server.\n\n Requires admin or server-modify permissions.\n \"\"\"\n _require_admin(user_context)\n normalized = _normalize_virtual_path(vs_path)\n\n set_audit_action(\n http_request,\n \"update\",\n \"virtual_server\",\n resource_id=normalized,\n description=f\"Update virtual server at {normalized}\",\n )\n\n service = get_virtual_server_service()\n\n try:\n config = await service.update_virtual_server(\n path=normalized,\n request=request,\n )\n\n if not config:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n\n return config\n\n except VirtualServerNotFoundError:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n except VirtualServerValidationError as e:\n logger.error(f\"Virtual server validation error: {e}\")\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=str(e),\n )\n except VirtualServerServiceError as e:\n logger.error(f\"Failed to update virtual server: {e}\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to update virtual server\",\n )\n\n\n@router.delete(\n \"/virtual-servers/{vs_path:path}\",\n status_code=status.HTTP_204_NO_CONTENT,\n summary=\"Delete a virtual server\",\n)\nasync def delete_virtual_server(\n http_request: Request,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n vs_path: str = Path(..., description=\"Virtual server path\"),\n) -> None:\n \"\"\"Delete a virtual MCP server.\n\n Requires admin or server-modify permissions.\n \"\"\"\n _require_admin(user_context)\n normalized = _normalize_virtual_path(vs_path)\n\n set_audit_action(\n http_request,\n \"delete\",\n \"virtual_server\",\n resource_id=normalized,\n description=f\"Delete virtual server at {normalized}\",\n )\n\n service = get_virtual_server_service()\n\n try:\n success = await service.delete_virtual_server(normalized)\n if not success:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n except VirtualServerNotFoundError:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n\n\n@router.post(\n \"/virtual-servers/{vs_path:path}/toggle\",\n response_model=dict,\n summary=\"Toggle virtual server enabled state\",\n)\nasync def toggle_virtual_server(\n http_request: Request,\n request: ToggleVirtualServerRequest,\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n vs_path: str = Path(..., description=\"Virtual server path\"),\n _csrf: Annotated[None, Depends(verify_csrf_token_flexible)] = None,\n) -> dict:\n \"\"\"Enable or disable a virtual MCP server.\n\n Requires admin or server-modify permissions.\n Enabling triggers nginx configuration regeneration.\n \"\"\"\n _require_admin(user_context)\n normalized = _normalize_virtual_path(vs_path)\n\n set_audit_action(\n http_request,\n \"toggle\",\n \"virtual_server\",\n resource_id=normalized,\n description=f\"Toggle virtual server to {request.enabled}\",\n )\n\n service = get_virtual_server_service()\n\n try:\n success = await service.toggle_virtual_server(\n path=normalized,\n enabled=request.enabled,\n )\n\n if not success:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n\n return {\"path\": normalized, \"is_enabled\": request.enabled}\n\n except VirtualServerNotFoundError:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=f\"Virtual server not found: {normalized}\",\n )\n except VirtualServerValidationError as e:\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=str(e),\n )\n\n\n# --- Tool Catalog Endpoint ---\n\n\n@router.get(\n \"/tool-catalog\",\n response_model=dict,\n summary=\"Browse all available tools across servers\",\n)\nasync def get_tool_catalog(\n user_context: Annotated[dict, Depends(nginx_proxied_auth)],\n server_path: str | None = Query(\n None,\n description=\"Filter by server path\",\n ),\n) -> dict:\n \"\"\"Get the global tool catalog from all enabled MCP servers.\n\n Returns tools the authenticated user has access to, filtered by\n their scopes. Includes source server, description, input schema,\n and available versions.\n \"\"\"\n service = get_tool_catalog_service()\n # Admin users bypass scope filtering (consistent with /api/servers)\n user_scopes = None if user_context.get(\"is_admin\") else user_context.get(\"scopes\", [])\n catalog = await service.get_tool_catalog(\n server_path_filter=server_path,\n user_scopes=user_scopes,\n )\n\n # Group by server for convenience\n servers: dict[str, list[dict]] = {}\n for entry in catalog:\n server_key = entry.server_path\n if server_key not in servers:\n servers[server_key] = []\n servers[server_key].append(entry.model_dump(mode=\"json\"))\n\n return {\n \"tools\": [e.model_dump(mode=\"json\") for e in catalog],\n \"total_count\": len(catalog),\n \"server_count\": len(servers),\n \"by_server\": servers,\n }\n" }, { "path": "registry/api/wellknown_routes.py", "content": "import logging\n\nfrom fastapi import APIRouter, HTTPException, Request\nfrom fastapi.responses import JSONResponse\n\nfrom ..constants import HealthStatus\nfrom ..core.config import RegistryMode, settings\nfrom ..health.service import health_service\nfrom ..repositories.factory import get_registry_card_repository\nfrom ..schemas.registry_card import RegistryCard, RegistryContact\nfrom ..services.server_service import server_service\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n\n@router.get(\"/mcp-servers\")\nasync def get_wellknown_mcp_servers(\n request: Request, user_context: dict | None = None\n) -> JSONResponse:\n \"\"\"\n Main endpoint handler for /.well-known/mcp-servers\n Returns JSON with all discoverable MCP servers\n \"\"\"\n # Step 1: Check if discovery is enabled\n if not settings.enable_wellknown_discovery:\n raise HTTPException(status_code=404, detail=\"Well-known discovery is disabled\")\n\n # Step 1.5: In skills-only mode, return empty server list\n if settings.registry_mode == RegistryMode.SKILLS_ONLY:\n response_data = {\n \"version\": \"1.0\",\n \"servers\": [],\n \"registry\": {\n \"name\": \"Enterprise MCP Gateway (Skills Only)\",\n \"description\": \"Skills-only registry mode - no MCP servers available\",\n \"version\": \"1.0.0\",\n \"contact\": {\n \"url\": str(request.base_url).rstrip(\"/\"),\n \"support\": \"mcp-support@company.com\",\n },\n },\n }\n headers = {\n \"Cache-Control\": f\"public, max-age={settings.wellknown_cache_ttl}\",\n \"Content-Type\": \"application/json\",\n }\n logger.info(\"Returning empty server list - skills-only mode\")\n return JSONResponse(content=response_data, headers=headers)\n\n # Step 2: Get all servers from server_service\n all_servers = await server_service.get_all_servers()\n\n # Step 3: Filter based on discoverability and permissions\n discoverable_servers = []\n for server_path, server_info in all_servers.items():\n # For now, include all enabled servers\n # TODO: Add discoverability flag to server configs if needed\n if await server_service.is_service_enabled(server_path):\n formatted_server = _format_server_discovery(server_info, request)\n discoverable_servers.append(formatted_server)\n\n # Step 4: Format response\n response_data = {\n \"version\": \"1.0\",\n \"servers\": discoverable_servers,\n \"registry\": {\n \"name\": \"Enterprise MCP Gateway\",\n \"description\": \"Centralized MCP server registry for enterprise tools\",\n \"version\": \"1.0.0\",\n \"contact\": {\n \"url\": str(request.base_url).rstrip(\"/\"),\n \"support\": \"mcp-support@company.com\",\n },\n },\n }\n\n # Step 5: Return JSONResponse with cache headers\n headers = {\n \"Cache-Control\": f\"public, max-age={settings.wellknown_cache_ttl}\",\n \"Content-Type\": \"application/json\",\n }\n\n logger.info(f\"Returned {len(discoverable_servers)} servers for well-known discovery\")\n return JSONResponse(content=response_data, headers=headers)\n\n\ndef _format_server_discovery(server_info: dict, request: Request) -> dict:\n \"\"\"Format individual server for discovery response\"\"\"\n server_path = server_info.get(\"path\", \"\")\n server_name = server_info.get(\"server_name\", server_path)\n description = server_info.get(\"description\", \"MCP Server\")\n\n # Generate dynamic URL based on request host and server config\n server_url = _get_server_url(server_path, request, server_info)\n\n # Get transport type from config\n transport_type = _get_transport_type(server_info)\n\n # Get authentication requirements\n auth_info = _get_authentication_info(server_info)\n\n # Get first 5 tools as preview\n tools_preview = _get_tools_preview(server_info, max_tools=5)\n\n # Get actual health status from health service\n health_status = _get_normalized_health_status(server_path)\n\n return {\n \"name\": server_name,\n \"description\": description,\n \"url\": server_url,\n \"transport\": transport_type,\n \"authentication\": auth_info,\n \"capabilities\": [\"tools\", \"resources\"],\n \"health_status\": health_status,\n \"tools_preview\": tools_preview,\n }\n\n\ndef _get_server_url(server_path: str, request: Request, server_info: dict = None) -> str:\n \"\"\"Generate full URL for MCP server based on request host and server config.\n\n Priority:\n 1. If server_info has mcp_endpoint, use it as the full URL\n 2. Otherwise, construct URL from request host + server_path + /mcp\n \"\"\"\n # Check if server has explicit mcp_endpoint configured\n if server_info and server_info.get(\"mcp_endpoint\"):\n return server_info.get(\"mcp_endpoint\")\n\n # Get host from request headers\n host = request.headers.get(\"host\", \"localhost:7860\")\n\n # Get protocol (http/https) from X-Forwarded-Proto or scheme\n proto = request.headers.get(\"x-forwarded-proto\", request.url.scheme)\n\n # Clean up server path (remove leading and trailing slashes)\n clean_path = server_path.strip(\"/\")\n\n # Return formatted URL with default /mcp suffix\n return f\"{proto}://{host}/{clean_path}/mcp\"\n\n\ndef _get_transport_type(server_config: dict) -> str:\n \"\"\"Determine transport type (sse or streamable-http)\"\"\"\n # Check server configuration for transport setting\n # Default to \"streamable-http\" if not specified\n return server_config.get(\"transport\", \"streamable-http\")\n\n\ndef _get_authentication_info(server_info: dict) -> dict:\n \"\"\"Extract authentication requirements for server.\n\n Reads auth_scheme (the new field). Legacy auth_type is migrated to\n auth_scheme at read time by the service layer, so we only need to\n check auth_scheme here.\n \"\"\"\n auth_scheme = server_info.get(\"auth_scheme\", \"none\")\n auth_provider = server_info.get(\"auth_provider\", \"default\")\n\n if auth_scheme == \"bearer\":\n return {\n \"type\": \"oauth2\",\n \"required\": True,\n \"authorization_url\": \"/auth/oauth/authorize\",\n \"provider\": auth_provider,\n \"scopes\": [\"mcp:read\", f\"{auth_provider}:read\"],\n }\n elif auth_scheme == \"api_key\":\n header_name = server_info.get(\"auth_header_name\", \"X-API-Key\")\n return {\"type\": \"api-key\", \"required\": True, \"header\": header_name}\n else:\n return {\"type\": \"none\", \"required\": False}\n\n\ndef _get_tools_preview(server_info: dict, max_tools: int = 5) -> list:\n \"\"\"Get limited list of tools for discovery preview\"\"\"\n # Extract tools from server_info\n tools = server_info.get(\"tool_list\", [])\n\n # Return first N tools with name and description\n preview_tools = []\n for tool in tools[:max_tools]:\n if isinstance(tool, dict):\n # Try to get description from parsed_description.main first, then fall back to description field\n description = tool.get(\"parsed_description\", {}).get(\n \"main\", tool.get(\"description\", \"No description available\")\n )\n preview_tools.append({\"name\": tool.get(\"name\", \"unknown\"), \"description\": description})\n elif isinstance(tool, str):\n # Handle case where tools are just strings\n preview_tools.append({\"name\": tool, \"description\": \"No description available\"})\n\n return preview_tools\n\n\ndef _get_normalized_health_status(server_path: str) -> str:\n \"\"\"\n Get normalized health status for a server from health service.\n\n Normalizes detailed status strings (e.g., \"unhealthy: timeout\") to simple\n values (\"unhealthy\") for cleaner client consumption in discovery responses.\n\n Args:\n server_path: The server path to get health status for\n\n Returns:\n Normalized health status string: \"healthy\", \"unhealthy\", \"disabled\", or \"unknown\"\n \"\"\"\n # Get raw status from health service\n raw_status = health_service.server_health_status.get(server_path, HealthStatus.UNKNOWN)\n\n # Normalize status to clean values for client consumption\n if isinstance(raw_status, str):\n status_lower = raw_status.lower()\n if \"unhealthy\" in status_lower or \"error\" in status_lower:\n return \"unhealthy\"\n elif \"healthy\" in status_lower:\n return \"healthy\"\n elif \"disabled\" in status_lower:\n return \"disabled\"\n elif \"checking\" in status_lower:\n return \"unknown\"\n else:\n return raw_status\n\n return str(raw_status) if raw_status else \"unknown\"\n\n\nasync def _auto_initialize_registry_card():\n \"\"\"\n Auto-initialize registry card from config defaults if it doesn't exist.\n\n Returns the existing or newly created card.\n \"\"\"\n repo = get_registry_card_repository()\n card = await repo.get()\n\n if card is None:\n # Auto-initialize from config defaults\n import random\n\n from registry.version import __version__\n\n logger.info(\"Registry card not found, auto-initializing from config\")\n\n # Generate random Docker-style registry name if using default\n if settings.registry_name != \"AI Registry\":\n registry_name = settings.registry_name\n else:\n adjectives = [\"brave\", \"clever\", \"swift\", \"bright\", \"noble\", \"wise\", \"bold\", \"keen\"]\n nouns = [\"falcon\", \"dolphin\", \"tiger\", \"phoenix\", \"dragon\", \"wolf\", \"eagle\", \"lion\"]\n registry_name = f\"{random.choice(adjectives)}-{random.choice(nouns)}-registry\"\n logger.info(f\"Generated random registry name: {registry_name}\")\n\n # Use organization name from config (defaults to \"ACME Inc.\")\n organization_name = settings.registry_organization_name\n logger.info(f\"Using organization name: {organization_name}\")\n\n # Get full API version from version module (e.g., \"1.0.17\")\n version_str = __version__\n # Remove 'v' prefix if present (e.g., \"v1.0.17\" -> \"1.0.17\")\n if version_str.startswith(\"v\"):\n version_str = version_str[1:]\n # Remove git suffix if present (e.g., \"1.0.17-6-gf5c000c3-main\" -> \"1.0.17\")\n version_parts = version_str.split(\"-\")[0]\n federation_api_version = version_parts\n logger.info(\n f\"Using federation API version: {federation_api_version} (from app version: {__version__})\"\n )\n\n contact = None\n if settings.registry_contact_email or settings.registry_contact_url:\n contact = RegistryContact(\n email=settings.registry_contact_email,\n url=settings.registry_contact_url,\n )\n\n # Build OAuth params based on auth provider\n import os\n\n oauth2_issuer = None\n oauth2_token_endpoint = None\n\n if settings.auth_provider == \"okta\":\n okta_domain = os.getenv(\"OKTA_DOMAIN\")\n okta_auth_server_id = os.getenv(\"OKTA_AUTH_SERVER_ID\", \"default\")\n if okta_domain:\n oauth2_issuer = f\"https://{okta_domain}/oauth2/{okta_auth_server_id}\"\n oauth2_token_endpoint = (\n f\"https://{okta_domain}/oauth2/{okta_auth_server_id}/v1/token\"\n )\n elif settings.auth_provider == \"keycloak\":\n keycloak_external_url = os.getenv(\"KEYCLOAK_EXTERNAL_URL\", \"http://localhost:8080\")\n keycloak_realm = os.getenv(\"KEYCLOAK_REALM\", \"mcp-gateway\")\n oauth2_issuer = f\"{keycloak_external_url}/realms/{keycloak_realm}\"\n oauth2_token_endpoint = (\n f\"{keycloak_external_url}/realms/{keycloak_realm}/protocol/openid-connect/token\"\n )\n elif settings.auth_provider == \"entra\":\n entra_tenant_id = os.getenv(\"ENTRA_TENANT_ID\")\n if entra_tenant_id:\n oauth2_issuer = f\"https://login.microsoftonline.com/{entra_tenant_id}/v2.0\"\n oauth2_token_endpoint = (\n f\"https://login.microsoftonline.com/{entra_tenant_id}/oauth2/v2.0/token\"\n )\n elif settings.auth_provider == \"cognito\":\n cognito_user_pool_id = os.getenv(\"COGNITO_USER_POOL_ID\")\n cognito_domain = os.getenv(\"COGNITO_DOMAIN\")\n aws_region = os.getenv(\"AWS_REGION\", \"us-east-1\")\n if cognito_user_pool_id:\n oauth2_issuer = (\n f\"https://cognito-idp.{aws_region}.amazonaws.com/{cognito_user_pool_id}\"\n )\n if cognito_domain:\n oauth2_token_endpoint = (\n f\"https://{cognito_domain}.auth.{aws_region}.amazoncognito.com/oauth2/token\"\n )\n\n from registry.schemas.registry_card import RegistryAuthConfig\n\n auth_config = RegistryAuthConfig(\n oauth2_issuer=oauth2_issuer,\n oauth2_token_endpoint=oauth2_token_endpoint,\n )\n\n # Don't pass id - let RegistryCard auto-generate UUID via default_factory\n # registry_id was for the old implementation, now we use auto-generated UUIDs\n card = RegistryCard(\n name=registry_name,\n description=settings.registry_description,\n registry_url=settings.registry_url,\n organization_name=organization_name,\n federation_api_version=federation_api_version,\n federation_endpoint=f\"{settings.registry_url}/api/v1/federation\",\n authentication=auth_config,\n contact=contact,\n )\n\n # Save the auto-initialized card\n card = await repo.save(card)\n logger.info(f\"Auto-initialized registry card: {card.id}\")\n\n return card\n\n\n@router.get(\"/registry-card\", response_model=RegistryCard)\nasync def get_well_known_registry_card():\n \"\"\"\n Get the Registry Card via .well-known discovery endpoint.\n\n This is the standard discovery endpoint for registry federation.\n Public endpoint - no authentication required.\n \"\"\"\n card = await _auto_initialize_registry_card()\n return card\n" }, { "path": "registry/audit/__init__.py", "content": "\"\"\"\nAudit and Compliance Logging Package.\n\nThis package provides audit logging capabilities for the MCP Gateway Registry,\ncapturing API access and MCP server access events for compliance and security review.\n\nComponents:\n- models: Pydantic models for audit log records\n- service: AuditLogger class for async writing and rotation\n- middleware: FastAPI middleware for request/response capture\n- mcp_logger: MCPLogger class for MCP protocol-level logging\n- routes: API endpoints for querying and exporting audit logs\n\"\"\"\n\nfrom .context import set_audit_action, set_audit_authorization\nfrom .mcp_logger import MCPLogger\nfrom .middleware import AuditMiddleware, add_audit_middleware\nfrom .models import (\n SENSITIVE_QUERY_PARAMS,\n Action,\n Authorization,\n Identity,\n MCPRequest,\n MCPResponse,\n MCPServer,\n MCPServerAccessRecord,\n RegistryApiAccessRecord,\n Request,\n Response,\n mask_credential,\n)\nfrom .service import AuditLogger\n\n__all__ = [\n # Models\n \"RegistryApiAccessRecord\",\n \"MCPServerAccessRecord\",\n \"MCPServer\",\n \"MCPRequest\",\n \"MCPResponse\",\n \"Identity\",\n \"Request\",\n \"Response\",\n \"Action\",\n \"Authorization\",\n \"mask_credential\",\n \"SENSITIVE_QUERY_PARAMS\",\n # Service\n \"AuditLogger\",\n # MCP Logger\n \"MCPLogger\",\n # Middleware\n \"AuditMiddleware\",\n \"add_audit_middleware\",\n # Context utilities\n \"set_audit_action\",\n \"set_audit_authorization\",\n]\n" }, { "path": "registry/audit/context.py", "content": "\"\"\"\nAudit context utilities for route handlers.\n\nThis module provides helper functions for setting audit action context\nin route handlers, which is then captured by the AuditMiddleware.\n\"\"\"\n\nfrom fastapi import Request\n\n\ndef set_audit_action(\n request: Request,\n operation: str,\n resource_type: str,\n resource_id: str | None = None,\n description: str | None = None,\n) -> None:\n \"\"\"\n Set audit action context on the request for the AuditMiddleware.\n\n This function should be called at the beginning of route handlers\n to provide semantic context about the operation being performed.\n\n Args:\n request: The FastAPI request object\n operation: The operation type (create, read, update, delete, list, toggle, rate, login, logout, search)\n resource_type: The resource type (server, agent, auth, federation, health, search, scope, user, group)\n resource_id: Optional identifier of the resource being acted upon\n description: Optional human-readable description of the action\n\n Example:\n @router.post(\"/servers\")\n async def create_server(request: Request, ...):\n set_audit_action(request, \"create\", \"server\", description=\"Register new MCP server\")\n ...\n \"\"\"\n request.state.audit_action = {\n \"operation\": operation,\n \"resource_type\": resource_type,\n \"resource_id\": resource_id,\n \"description\": description,\n }\n\n\ndef set_audit_authorization(\n request: Request,\n decision: str,\n required_permission: str | None = None,\n evaluated_scopes: list | None = None,\n) -> None:\n \"\"\"\n Set authorization decision context on the request for the AuditMiddleware.\n\n This function can be called by authorization dependencies to record\n the authorization decision for audit purposes.\n\n Args:\n request: The FastAPI request object\n decision: The authorization decision (ALLOW, DENY, NOT_REQUIRED)\n required_permission: The permission that was required\n evaluated_scopes: List of scopes that were evaluated\n\n Example:\n def check_permission(request: Request, user_context: dict):\n if user_context.get(\"is_admin\"):\n set_audit_authorization(request, \"ALLOW\", \"admin\", user_context.get(\"scopes\", []))\n else:\n set_audit_authorization(request, \"DENY\", \"admin\", user_context.get(\"scopes\", []))\n raise HTTPException(status_code=403)\n \"\"\"\n request.state.audit_authorization = {\n \"decision\": decision,\n \"required_permission\": required_permission,\n \"evaluated_scopes\": evaluated_scopes or [],\n }\n" }, { "path": "registry/audit/mcp_logger.py", "content": "\"\"\"\nMCP Logger for protocol-level audit logging.\n\nThis module provides the MCPLogger class that handles logging of\nMCP (Model Context Protocol) server access events, including\nJSON-RPC request parsing and tool/resource invocation tracking.\n\"\"\"\n\nimport json\nimport logging\nfrom datetime import UTC, datetime\n\nfrom .models import (\n Identity,\n MCPRequest,\n MCPResponse,\n MCPServer,\n MCPServerAccessRecord,\n Request,\n)\nfrom .service import AuditLogger\n\nlogger = logging.getLogger(__name__)\n\n\nclass MCPLogger:\n \"\"\"\n MCP protocol-level audit logger.\n\n Handles logging of MCP server access events by parsing JSON-RPC\n request bodies and creating structured audit records. Delegates\n actual file/MongoDB writing to the AuditLogger service.\n\n Attributes:\n audit_logger: The underlying AuditLogger service for writing events\n \"\"\"\n\n def __init__(self, audit_logger: AuditLogger):\n \"\"\"\n Initialize the MCPLogger.\n\n Args:\n audit_logger: The AuditLogger service to use for writing events\n \"\"\"\n self.audit_logger = audit_logger\n\n def parse_jsonrpc_body(self, body: bytes | str) -> dict:\n \"\"\"\n Parse JSON-RPC request body to extract method and params.\n\n Extracts the JSON-RPC method name and relevant parameters\n based on the method type:\n - For 'tools/call': extracts tool_name from params.name\n - For 'resources/read': extracts resource_uri from params.uri\n\n Args:\n body: The JSON-RPC request body as bytes or string\n\n Returns:\n Dictionary containing:\n - method: The JSON-RPC method name (or 'unknown' if parsing fails)\n - jsonrpc_id: The JSON-RPC request ID as string\n - tool_name: (optional) The tool name for tools/call requests\n - resource_uri: (optional) The resource URI for resources/read requests\n \"\"\"\n try:\n # Handle both bytes and string input\n if isinstance(body, bytes):\n body_str = body.decode(\"utf-8\")\n else:\n body_str = body\n\n # Handle empty body\n if not body_str or not body_str.strip():\n return {\"method\": \"unknown\", \"jsonrpc_id\": \"\"}\n\n data = json.loads(body_str)\n\n # Handle non-dict responses (e.g., arrays for batch requests)\n if not isinstance(data, dict):\n return {\"method\": \"unknown\", \"jsonrpc_id\": \"\"}\n\n method = data.get(\"method\", \"\")\n params = data.get(\"params\", {})\n\n # Ensure params is a dict\n if not isinstance(params, dict):\n params = {}\n\n result = {\n \"method\": method if method else \"unknown\",\n \"jsonrpc_id\": str(data.get(\"id\", \"\")),\n }\n\n # Extract tool_name for tools/call\n if method == \"tools/call\":\n tool_name = params.get(\"name\")\n if tool_name:\n result[\"tool_name\"] = str(tool_name)\n\n # Extract resource_uri for resources/read\n if method == \"resources/read\":\n resource_uri = params.get(\"uri\")\n if resource_uri:\n result[\"resource_uri\"] = str(resource_uri)\n\n return result\n\n except json.JSONDecodeError as e:\n logger.warning(f\"Failed to parse JSON-RPC body: {e}\")\n return {\"method\": \"unknown\", \"jsonrpc_id\": \"\"}\n except Exception as e:\n logger.warning(f\"Unexpected error parsing JSON-RPC body: {e}\")\n return {\"method\": \"unknown\", \"jsonrpc_id\": \"\"}\n\n async def log_mcp_access(\n self,\n request_id: str,\n identity: Identity,\n mcp_server: MCPServer,\n request_body: bytes | str,\n response_status: str,\n duration_ms: float,\n mcp_session_id: str | None = None,\n transport: str = \"streamable-http\",\n error_code: int | None = None,\n error_message: str | None = None,\n client_ip: str = \"unknown\",\n forwarded_for: str | None = None,\n user_agent: str | None = None,\n correlation_id: str | None = None,\n ) -> None:\n \"\"\"\n Log an MCP server access event.\n\n Creates an MCPServerAccessRecord from the provided parameters\n and writes it to the audit log via the AuditLogger service.\n\n Args:\n request_id: Unique identifier for this request\n identity: Identity of the user making the request\n mcp_server: Information about the target MCP server\n request_body: The JSON-RPC request body (for method/tool extraction)\n response_status: Response status: 'success', 'error', or 'timeout'\n duration_ms: Request duration in milliseconds\n mcp_session_id: Optional MCP session identifier\n transport: Transport protocol (default: 'streamable-http')\n error_code: JSON-RPC error code (if status is 'error')\n error_message: Error message (if status is 'error')\n client_ip: Client IP address\n forwarded_for: X-Forwarded-For header value\n user_agent: User-Agent header value\n correlation_id: Optional correlation ID for tracing\n \"\"\"\n # Parse the JSON-RPC body to extract method and tool/resource info\n parsed = self.parse_jsonrpc_body(request_body)\n\n # Build the MCP request model\n mcp_request = MCPRequest(\n method=parsed.get(\"method\", \"unknown\"),\n tool_name=parsed.get(\"tool_name\"),\n resource_uri=parsed.get(\"resource_uri\"),\n mcp_session_id=mcp_session_id,\n transport=transport,\n jsonrpc_id=parsed.get(\"jsonrpc_id\"),\n )\n\n # Build the MCP response model\n mcp_response = MCPResponse(\n status=response_status,\n duration_ms=duration_ms,\n error_code=error_code,\n error_message=error_message,\n )\n\n # Build optional HTTP request info\n request_info = None\n if client_ip != \"unknown\" or forwarded_for or user_agent:\n request_info = Request(\n method=\"POST\", # MCP requests are typically POST\n path=mcp_server.path,\n client_ip=client_ip,\n forwarded_for=forwarded_for,\n user_agent=user_agent,\n )\n\n # Create the complete audit record\n record = MCPServerAccessRecord(\n timestamp=datetime.now(UTC),\n request_id=request_id,\n correlation_id=correlation_id,\n identity=identity,\n mcp_server=mcp_server,\n mcp_request=mcp_request,\n mcp_response=mcp_response,\n request=request_info,\n )\n\n # Write to audit log\n await self.audit_logger.log_event(record)\n" }, { "path": "registry/audit/middleware.py", "content": "\"\"\"\nFastAPI middleware for audit logging.\n\nThis module provides middleware that captures request/response\nenvelope and identity context for every API request, creating\nstructured audit records.\n\"\"\"\n\nimport logging\nimport time\nimport uuid\nfrom collections.abc import Callable\nfrom datetime import UTC, datetime\n\nfrom fastapi import Request, Response\nfrom starlette.middleware.base import BaseHTTPMiddleware\nfrom starlette.types import ASGIApp\n\nfrom ..utils.request_utils import get_client_ip\nfrom .models import (\n Action,\n Authorization,\n Identity,\n RegistryApiAccessRecord,\n)\nfrom .models import (\n Request as AuditRequest,\n)\nfrom .models import (\n Response as AuditResponse,\n)\nfrom .service import AuditLogger\n\nlogger = logging.getLogger(__name__)\n\n\nclass AuditMiddleware(BaseHTTPMiddleware):\n \"\"\"\n Middleware that captures request/response data for audit logging.\n\n Creates structured audit records for every API request, including\n identity context, request/response details, and optional action context.\n\n Attributes:\n audit_logger: The AuditLogger service for writing events\n exclude_paths: List of paths to exclude from logging\n log_health_checks: Whether to log health check requests\n log_static_assets: Whether to log static asset requests\n \"\"\"\n\n def __init__(\n self,\n app: ASGIApp,\n audit_logger: AuditLogger,\n exclude_paths: list[str] | None = None,\n log_health_checks: bool = False,\n log_static_assets: bool = False,\n ):\n \"\"\"\n Initialize the AuditMiddleware.\n\n Args:\n app: The ASGI application\n audit_logger: AuditLogger service instance\n exclude_paths: List of paths to exclude from audit logging\n log_health_checks: Whether to log health check endpoints (default: False)\n log_static_assets: Whether to log static asset requests (default: False)\n \"\"\"\n super().__init__(app)\n self.audit_logger = audit_logger\n self.exclude_paths = exclude_paths or []\n self.log_health_checks = log_health_checks\n self.log_static_assets = log_static_assets\n\n def _should_log(self, path: str) -> bool:\n \"\"\"\n Determine if a request should be logged.\n\n Args:\n path: The request path\n\n Returns:\n True if the request should be logged, False otherwise\n \"\"\"\n # Check explicit exclusions\n if path in self.exclude_paths:\n return False\n\n # Check health check endpoints\n if not self.log_health_checks and \"/health\" in path.lower():\n return False\n\n # Check static assets\n if not self.log_static_assets:\n if path.startswith(\"/static\"):\n return False\n if path.startswith(\"/favicon\"):\n return False\n # Common static file extensions\n static_extensions = (\n \".css\",\n \".js\",\n \".png\",\n \".jpg\",\n \".jpeg\",\n \".gif\",\n \".ico\",\n \".svg\",\n \".woff\",\n \".woff2\",\n \".ttf\",\n )\n if path.endswith(static_extensions):\n return False\n\n return True\n\n def _get_credential_type(self, request: Request) -> str:\n \"\"\"\n Determine the type of credential used for authentication.\n\n Args:\n request: The FastAPI request object\n\n Returns:\n Credential type: 'session_cookie', 'bearer_token', or 'none'\n \"\"\"\n from ..core.config import settings\n\n # Check for session cookie (use configured cookie name)\n if request.cookies.get(settings.session_cookie_name):\n return \"session_cookie\"\n\n # Check for bearer token\n auth_header = request.headers.get(\"Authorization\", \"\")\n if auth_header.startswith(\"Bearer \"):\n return \"bearer_token\"\n\n return \"none\"\n\n def _get_credential_hint(self, request: Request) -> str | None:\n \"\"\"\n Extract credential hint for audit logging.\n\n The hint will be masked by the Identity model validator.\n\n Args:\n request: The FastAPI request object\n\n Returns:\n Raw credential value (will be masked), or None\n \"\"\"\n from ..core.config import settings\n\n # Check for session cookie (use configured cookie name)\n session = request.cookies.get(settings.session_cookie_name)\n if session:\n return session # Will be masked by validator\n\n # Check for bearer token\n auth_header = request.headers.get(\"Authorization\", \"\")\n if auth_header.startswith(\"Bearer \"):\n return auth_header[7:] # Will be masked by validator\n\n return None\n\n def _extract_identity(self, request: Request) -> Identity:\n \"\"\"\n Extract identity information from the request.\n\n Looks for user context in request.state (set by auth dependency)\n or falls back to anonymous identity.\n\n Args:\n request: The FastAPI request object\n\n Returns:\n Identity model with user information\n \"\"\"\n # Try to get user context from request state (set by auth dependency)\n user_context = getattr(request.state, \"user_context\", None)\n\n if user_context and isinstance(user_context, dict):\n return Identity(\n username=user_context.get(\"username\", \"anonymous\"),\n auth_method=user_context.get(\"auth_method\", \"anonymous\"),\n provider=user_context.get(\"provider\"),\n groups=user_context.get(\"groups\", []),\n scopes=user_context.get(\"scopes\", []),\n is_admin=user_context.get(\"is_admin\", False),\n credential_type=self._get_credential_type(request),\n credential_hint=self._get_credential_hint(request),\n )\n\n # Fallback to anonymous identity\n return Identity(\n username=\"anonymous\",\n auth_method=\"anonymous\",\n credential_type=self._get_credential_type(request),\n credential_hint=self._get_credential_hint(request),\n )\n\n def _extract_action(self, request: Request) -> Action | None:\n \"\"\"\n Extract action context from the request.\n\n Route handlers can set audit_action in request.state to provide\n semantic context about the operation being performed.\n\n Args:\n request: The FastAPI request object\n\n Returns:\n Action model if audit_action is set, None otherwise\n \"\"\"\n audit_action = getattr(request.state, \"audit_action\", None)\n\n if audit_action and isinstance(audit_action, dict):\n return Action(\n operation=audit_action.get(\"operation\", \"unknown\"),\n resource_type=audit_action.get(\"resource_type\", \"unknown\"),\n resource_id=audit_action.get(\"resource_id\"),\n description=audit_action.get(\"description\"),\n )\n\n return None\n\n def _extract_authorization(self, request: Request) -> Authorization | None:\n \"\"\"\n Extract authorization decision from the request.\n\n Route handlers can set audit_authorization in request.state to\n record the authorization decision for the request.\n\n Args:\n request: The FastAPI request object\n\n Returns:\n Authorization model if audit_authorization is set, None otherwise\n \"\"\"\n audit_auth = getattr(request.state, \"audit_authorization\", None)\n\n if audit_auth and isinstance(audit_auth, dict):\n return Authorization(\n decision=audit_auth.get(\"decision\", \"NOT_REQUIRED\"),\n required_permission=audit_auth.get(\"required_permission\"),\n evaluated_scopes=audit_auth.get(\"evaluated_scopes\", []),\n )\n\n return None\n\n async def dispatch(self, request: Request, call_next: Callable) -> Response:\n \"\"\"\n Process the request and create an audit record.\n\n Args:\n request: The FastAPI request object\n call_next: The next middleware/handler in the chain\n\n Returns:\n The response from the next handler\n \"\"\"\n # Check if this request should be logged\n if not self._should_log(request.url.path):\n return await call_next(request)\n\n # Generate or extract request ID\n request_id = request.headers.get(\"X-Request-ID\", str(uuid.uuid4()))\n correlation_id = request.headers.get(\"X-Correlation-ID\")\n\n # Start timing\n start_time = time.perf_counter()\n\n # Process the request\n response = await call_next(request)\n\n # Work around Starlette BaseHTTPMiddleware bug: call_next wraps\n # the response in a StreamingResponse which can send body bytes\n # for 204 No Content, causing \"Response content longer than\n # Content-Length\" errors. Return a plain Response instead.\n if response.status_code == 204:\n response = Response(status_code=204, headers=dict(response.headers))\n\n # Calculate duration\n duration_ms = (time.perf_counter() - start_time) * 1000\n\n # Extract client IP (validated against spoofed/malformed headers)\n client_ip = get_client_ip(request)\n\n # Get content length from request headers (may be None)\n request_content_length = None\n if \"content-length\" in request.headers:\n try:\n request_content_length = int(request.headers[\"content-length\"])\n except (ValueError, TypeError):\n pass\n\n # Get content length from response headers (may be None)\n response_content_length = None\n if \"content-length\" in response.headers:\n try:\n response_content_length = int(response.headers[\"content-length\"])\n except (ValueError, TypeError):\n pass\n\n # Build the audit record\n try:\n record = RegistryApiAccessRecord(\n timestamp=datetime.now(UTC),\n request_id=request_id,\n correlation_id=correlation_id,\n identity=self._extract_identity(request),\n request=AuditRequest(\n method=request.method,\n path=request.url.path,\n query_params=dict(request.query_params),\n client_ip=client_ip,\n forwarded_for=request.headers.get(\"X-Forwarded-For\"),\n user_agent=request.headers.get(\"User-Agent\"),\n content_length=request_content_length,\n ),\n response=AuditResponse(\n status_code=response.status_code,\n duration_ms=duration_ms,\n content_length=response_content_length,\n ),\n action=self._extract_action(request),\n authorization=self._extract_authorization(request),\n )\n\n # Log the event asynchronously\n await self.audit_logger.log_event(record)\n\n except Exception as e:\n # Don't let audit logging failures break the request\n logger.error(f\"Failed to create audit record: {e}\")\n\n return response\n\n\ndef add_audit_middleware(\n app,\n audit_logger: AuditLogger,\n exclude_paths: list[str] | None = None,\n log_health_checks: bool = False,\n log_static_assets: bool = False,\n) -> None:\n \"\"\"\n Convenience function to add audit middleware to a FastAPI app.\n\n Args:\n app: FastAPI application instance\n audit_logger: AuditLogger service instance\n exclude_paths: List of paths to exclude from audit logging\n log_health_checks: Whether to log health check endpoints\n log_static_assets: Whether to log static asset requests\n \"\"\"\n app.add_middleware(\n AuditMiddleware,\n audit_logger=audit_logger,\n exclude_paths=exclude_paths,\n log_health_checks=log_health_checks,\n log_static_assets=log_static_assets,\n )\n logger.info(\"Audit middleware added to application\")\n" }, { "path": "registry/audit/models.py", "content": "\"\"\"\nPydantic models for audit log records.\n\nThis module defines the structured data models for audit events,\nincluding credential masking validators to ensure sensitive data\nis never logged in plain text.\n\"\"\"\n\nfrom datetime import datetime\nfrom typing import Any\n\nfrom pydantic import BaseModel, Field, field_validator\n\n\ndef mask_credential(value: str) -> str:\n \"\"\"\n Mask credential to show only last 6 characters.\n\n Args:\n value: The credential string to mask\n\n Returns:\n Masked string in format \"***\" + last 6 chars, or \"***\" if too short\n \"\"\"\n if not value or len(value) <= 6:\n return \"***\"\n return \"***\" + value[-6:]\n\n\n# Set of sensitive query parameter keys that should be masked\nSENSITIVE_QUERY_PARAMS = frozenset(\n {\n \"token\",\n \"password\",\n \"key\",\n \"secret\",\n \"api_key\",\n \"apikey\",\n \"access_token\",\n \"refresh_token\",\n \"auth\",\n \"authorization\",\n \"credential\",\n \"credentials\",\n }\n)\n\n\nclass Identity(BaseModel):\n \"\"\"\n Identity information for the user making the request.\n\n Captures authentication context including username, auth method,\n provider, groups, scopes, and credential hints (masked).\n \"\"\"\n\n username: str = Field(description=\"Username or identifier of the requester\")\n auth_method: str = Field(description=\"Authentication method: oauth2, jwt_bearer, anonymous\")\n provider: str | None = Field(\n default=None, description=\"Identity provider: cognito, entra_id, keycloak\"\n )\n groups: list[str] = Field(default_factory=list, description=\"Groups the user belongs to\")\n scopes: list[str] = Field(default_factory=list, description=\"OAuth scopes granted to the user\")\n is_admin: bool = Field(default=False, description=\"Whether the user has admin privileges\")\n credential_type: str = Field(\n description=\"Type of credential: session_cookie, bearer_token, none\"\n )\n credential_hint: str | None = Field(\n default=None, description=\"Masked hint of the credential (last 6 chars)\"\n )\n\n @field_validator(\"credential_hint\", mode=\"before\")\n @classmethod\n def mask_credential_hint(cls, v: str | None) -> str | None:\n \"\"\"Mask the credential hint to protect sensitive data.\"\"\"\n if v:\n return mask_credential(v)\n return v\n\n\nclass Request(BaseModel):\n \"\"\"\n HTTP request information captured for audit logging.\n\n Includes method, path, query parameters (with sensitive values masked),\n client IP, and other request metadata.\n \"\"\"\n\n method: str = Field(description=\"HTTP method: GET, POST, PUT, DELETE, etc.\")\n path: str = Field(description=\"Request path\")\n query_params: dict[str, Any] = Field(\n default_factory=dict, description=\"Query parameters (sensitive values masked)\"\n )\n client_ip: str = Field(description=\"Client IP address\")\n forwarded_for: str | None = Field(default=None, description=\"X-Forwarded-For header value\")\n user_agent: str | None = Field(default=None, description=\"User-Agent header value\")\n content_length: int | None = Field(\n default=None, description=\"Content-Length of the request body\"\n )\n\n @field_validator(\"query_params\", mode=\"before\")\n @classmethod\n def mask_sensitive_params(cls, v: dict[str, Any] | None) -> dict[str, Any]:\n \"\"\"Mask sensitive query parameter values.\"\"\"\n if not v:\n return {}\n return {\n k: mask_credential(str(val)) if k.lower() in SENSITIVE_QUERY_PARAMS else val\n for k, val in v.items()\n }\n\n\nclass Response(BaseModel):\n \"\"\"\n HTTP response information captured for audit logging.\n \"\"\"\n\n status_code: int = Field(description=\"HTTP status code\")\n duration_ms: float = Field(description=\"Request duration in milliseconds\")\n content_length: int | None = Field(\n default=None, description=\"Content-Length of the response body\"\n )\n\n\nclass Action(BaseModel):\n \"\"\"\n Business-level action information set by route handlers.\n\n Provides semantic context about what operation was performed\n on what resource.\n \"\"\"\n\n operation: str = Field(\n description=\"Operation type: create, read, update, delete, list, toggle, rate, login, logout, search\"\n )\n resource_type: str = Field(\n description=\"Resource type: server, agent, auth, federation, health, search\"\n )\n resource_id: str | None = Field(\n default=None, description=\"Identifier of the resource being acted upon\"\n )\n description: str | None = Field(\n default=None, description=\"Human-readable description of the action\"\n )\n\n\nclass Authorization(BaseModel):\n \"\"\"\n Authorization decision information for the request.\n \"\"\"\n\n decision: str = Field(description=\"Authorization decision: ALLOW, DENY, NOT_REQUIRED\")\n required_permission: str | None = Field(\n default=None, description=\"Permission required for the action\"\n )\n evaluated_scopes: list[str] = Field(\n default_factory=list, description=\"Scopes that were evaluated for authorization\"\n )\n\n\nclass RegistryApiAccessRecord(BaseModel):\n \"\"\"\n Complete audit record for a Registry API access event.\n\n This is the primary audit log record type for Phase 1,\n capturing all relevant information about an API request\n for compliance and security review.\n \"\"\"\n\n timestamp: datetime = Field(description=\"When the event occurred (UTC)\")\n log_type: str = Field(default=\"registry_api_access\", description=\"Type of audit log record\")\n version: str = Field(default=\"1.0\", description=\"Schema version for this record type\")\n request_id: str = Field(description=\"Unique identifier for this request\")\n correlation_id: str | None = Field(\n default=None, description=\"Correlation ID for tracing across services\"\n )\n identity: Identity = Field(description=\"Identity of the requester\")\n request: Request = Field(description=\"HTTP request details\")\n response: Response = Field(description=\"HTTP response details\")\n action: Action | None = Field(default=None, description=\"Business-level action context\")\n authorization: Authorization | None = Field(\n default=None, description=\"Authorization decision details\"\n )\n\n\n# =============================================================================\n# MCP Server Access Log Models (Phase 4)\n# =============================================================================\n\n\nclass MCPServer(BaseModel):\n \"\"\"\n MCP server information for audit logging.\n\n Captures details about the target MCP server being accessed\n through the gateway proxy.\n \"\"\"\n\n name: str = Field(description=\"Name of the MCP server\")\n path: str = Field(description=\"Path/route to the MCP server\")\n version: str | None = Field(default=None, description=\"Version of the MCP server\")\n proxy_target: str = Field(description=\"Target URL the request is proxied to\")\n\n\nclass MCPRequest(BaseModel):\n \"\"\"\n MCP protocol request information for audit logging.\n\n Captures JSON-RPC method details including tool invocations\n and resource access requests.\n \"\"\"\n\n method: str = Field(description=\"JSON-RPC method name (e.g., tools/call, resources/read)\")\n tool_name: str | None = Field(\n default=None, description=\"Name of the tool being called (for tools/call method)\"\n )\n resource_uri: str | None = Field(\n default=None, description=\"URI of the resource being accessed (for resources/read method)\"\n )\n mcp_session_id: str | None = Field(default=None, description=\"MCP session identifier\")\n transport: str = Field(\n default=\"streamable-http\", description=\"Transport protocol: streamable-http, sse, stdio\"\n )\n jsonrpc_id: str | None = Field(default=None, description=\"JSON-RPC request ID\")\n\n\nclass MCPResponse(BaseModel):\n \"\"\"\n MCP protocol response information for audit logging.\n\n Captures the outcome of an MCP request including success/error\n status and timing information.\n \"\"\"\n\n status: str = Field(description=\"Response status: success, error, timeout\")\n duration_ms: float = Field(description=\"Request duration in milliseconds\")\n error_code: int | None = Field(\n default=None, description=\"JSON-RPC error code (if status is error)\"\n )\n error_message: str | None = Field(\n default=None, description=\"Error message (if status is error)\"\n )\n\n\nclass MCPServerAccessRecord(BaseModel):\n \"\"\"\n Complete audit record for an MCP server access event.\n\n This is the audit log record type for Phase 4,\n capturing all relevant information about an MCP protocol\n request proxied through the gateway for compliance and\n security review.\n \"\"\"\n\n timestamp: datetime = Field(description=\"When the event occurred (UTC)\")\n log_type: str = Field(default=\"mcp_server_access\", description=\"Type of audit log record\")\n version: str = Field(default=\"1.0\", description=\"Schema version for this record type\")\n request_id: str = Field(description=\"Unique identifier for this request\")\n correlation_id: str | None = Field(\n default=None, description=\"Correlation ID for tracing across services\"\n )\n identity: Identity = Field(description=\"Identity of the requester\")\n mcp_server: MCPServer = Field(description=\"Target MCP server details\")\n mcp_request: MCPRequest = Field(description=\"MCP protocol request details\")\n mcp_response: MCPResponse = Field(description=\"MCP protocol response details\")\n request: Request | None = Field(\n default=None, description=\"HTTP request details (client_ip, forwarded_for, user_agent)\"\n )\n" }, { "path": "registry/audit/routes.py", "content": "\"\"\"\nAudit API routes for querying and exporting audit logs.\n\nThis module provides REST endpoints for administrators to query,\nview, and export audit events from MongoDB storage.\n\nAll endpoints require admin access (is_admin=True in user context).\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport csv\nimport io\nimport logging\nimport re\nimport time\nfrom datetime import UTC, datetime, timedelta\nfrom typing import Annotated, Any\n\nfrom fastapi import APIRouter, Depends, HTTPException, Query, status\nfrom fastapi.responses import StreamingResponse\nfrom pydantic import BaseModel, Field\n\nfrom ..auth.dependencies import enhanced_auth\nfrom ..repositories.audit_repository import DocumentDBAuditRepository\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/audit\", tags=[\"Audit Logs\"])\n\n# Singleton repository instance\n_audit_repository: DocumentDBAuditRepository | None = None\n\n\ndef get_audit_repository() -> DocumentDBAuditRepository:\n \"\"\"Get or create the audit repository singleton.\"\"\"\n global _audit_repository\n if _audit_repository is None:\n _audit_repository = DocumentDBAuditRepository()\n return _audit_repository\n\n\ndef require_admin(user_context: dict[str, Any] = Depends(enhanced_auth)) -> dict[str, Any]:\n \"\"\"\n Dependency that requires admin access for audit endpoints.\n\n Args:\n user_context: User context from enhanced_auth dependency\n\n Returns:\n The user context if admin access is granted\n\n Raises:\n HTTPException: 403 Forbidden if user is not an admin\n \"\"\"\n if not user_context.get(\"is_admin\", False):\n logger.warning(\n f\"Non-admin user '{user_context.get('username', 'unknown')}' \"\n \"attempted to access audit API\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Admin access required\",\n )\n return user_context\n\n\n# Response models\nclass AuditEventSummary(BaseModel):\n \"\"\"Summary of an audit event for list responses.\"\"\"\n\n timestamp: datetime\n request_id: str\n log_type: str = \"registry_api_access\"\n username: str\n auth_method: str\n is_admin: bool\n method: str\n path: str\n status_code: int\n duration_ms: float\n operation: str | None = None\n resource_type: str | None = None\n resource_id: str | None = None\n\n\nclass AuditEventsResponse(BaseModel):\n \"\"\"Response model for paginated audit events.\"\"\"\n\n total: int = Field(description=\"Total number of matching events\")\n limit: int = Field(description=\"Maximum events per page\")\n offset: int = Field(description=\"Number of events skipped\")\n events: list[dict[str, Any]] = Field(description=\"List of audit events\")\n\n\nclass AuditEventDetail(BaseModel):\n \"\"\"Full audit event detail.\"\"\"\n\n event: dict[str, Any] = Field(description=\"Complete audit event record\")\n\n\nclass AuditFilterOptions(BaseModel):\n \"\"\"Available filter values for audit log dropdowns.\"\"\"\n\n usernames: list[str] = Field(\n default_factory=list,\n description=\"Distinct usernames found in audit events\",\n )\n server_names: list[str] = Field(\n default_factory=list,\n description=\"Distinct MCP server names (MCP stream only)\",\n )\n\n\nclass UsageSummaryItem(BaseModel):\n \"\"\"A single row in a usage summary.\"\"\"\n\n name: str = Field(description=\"Username, server name, or category\")\n count: int = Field(description=\"Number of events\")\n\n\nclass TimeSeriesBucket(BaseModel):\n \"\"\"A single time bucket for the activity chart.\"\"\"\n\n period: str = Field(description=\"Time period label (e.g., '2026-02-28')\")\n count: int = Field(description=\"Number of events in this period\")\n\n\nclass StatusDistribution(BaseModel):\n \"\"\"Status code distribution.\"\"\"\n\n status_2xx: int = Field(default=0, description=\"2xx success count\")\n status_4xx: int = Field(default=0, description=\"4xx client error count\")\n status_5xx: int = Field(default=0, description=\"5xx server error count\")\n\n\nclass UserActivityItem(BaseModel):\n \"\"\"Per-user activity breakdown showing top operations.\"\"\"\n\n username: str = Field(description=\"Username\")\n total: int = Field(description=\"Total requests by this user\")\n operations: list[UsageSummaryItem] = Field(\n default_factory=list,\n description=\"Top operations for this user\",\n )\n\n\nclass AuditStatisticsResponse(BaseModel):\n \"\"\"Aggregated audit statistics.\"\"\"\n\n total_events: int = Field(description=\"Total events in time range\")\n top_users: list[UsageSummaryItem] = Field(\n default_factory=list,\n description=\"Top 10 users by event count\",\n )\n top_servers: list[UsageSummaryItem] = Field(\n default_factory=list,\n description=\"Top 10 MCP servers (MCP stream only)\",\n )\n top_operations: list[UsageSummaryItem] = Field(\n default_factory=list,\n description=\"Top 10 operations by event count\",\n )\n activity_timeline: list[TimeSeriesBucket] = Field(\n default_factory=list,\n description=\"Daily event counts for the time range\",\n )\n status_distribution: StatusDistribution = Field(\n default_factory=StatusDistribution,\n description=\"Distribution of HTTP status codes\",\n )\n user_activity: list[UserActivityItem] = Field(\n default_factory=list,\n description=\"Per-user breakdown of top operations\",\n )\n\n\ndef _build_query(\n stream: str,\n from_time: datetime | None,\n to_time: datetime | None,\n username: str | None,\n operation: str | None,\n resource_type: str | None,\n resource_id: str | None,\n status_min: int | None,\n status_max: int | None,\n auth_decision: str | None,\n) -> dict[str, Any]:\n \"\"\"\n Build MongoDB query from filter parameters.\n\n Args:\n stream: Log stream type (registry_api or mcp_access)\n from_time: Start of time range filter\n to_time: End of time range filter\n username: Filter by username\n operation: Filter by operation type\n resource_type: Filter by resource type\n resource_id: Filter by resource ID\n status_min: Minimum HTTP status code\n status_max: Maximum HTTP status code\n auth_decision: Filter by authorization decision\n\n Returns:\n MongoDB query dictionary\n \"\"\"\n # Map stream parameter to log_type\n log_type_map = {\n \"registry_api\": \"registry_api_access\",\n \"mcp_access\": \"mcp_server_access\",\n }\n query: dict[str, Any] = {\"log_type\": log_type_map.get(stream, stream)}\n\n # Time range filter\n if from_time or to_time:\n query[\"timestamp\"] = {}\n if from_time:\n query[\"timestamp\"][\"$gte\"] = from_time\n if to_time:\n query[\"timestamp\"][\"$lte\"] = to_time\n\n # Identity filters - use case-insensitive regex for partial matching\n if username:\n # Escape special regex characters in the username\n escaped_username = re.escape(username)\n query[\"identity.username\"] = {\"$regex\": escaped_username, \"$options\": \"i\"}\n\n # Action filters - different fields per stream\n if stream == \"mcp_access\":\n # MCP records use mcp_request.method and mcp_server.name\n if operation:\n query[\"mcp_request.method\"] = operation\n if resource_type:\n escaped_resource = re.escape(resource_type)\n query[\"mcp_server.name\"] = {\"$regex\": escaped_resource, \"$options\": \"i\"}\n else:\n # Registry API records use action.* fields\n if operation:\n query[\"action.operation\"] = operation\n if resource_type:\n query[\"action.resource_type\"] = resource_type\n if resource_id:\n query[\"action.resource_id\"] = resource_id\n\n # Response status filter\n # For registry_api: use numeric response.status_code\n # For mcp_access: use string mcp_response.status (\"success\" or \"error\")\n if status_min is not None or status_max is not None:\n if stream == \"mcp_access\":\n # Map numeric ranges to MCP status strings\n # 2xx (200-299) -> success, 4xx/5xx (400-599) -> error\n if (\n status_min is not None\n and status_min >= 200\n and (status_max is None or status_max < 400)\n ):\n # 2xx range = success\n query[\"mcp_response.status\"] = \"success\"\n elif status_min is not None and status_min >= 400:\n # 4xx/5xx range = error\n query[\"mcp_response.status\"] = \"error\"\n # If \"All Errors\" (400-599), also map to error\n elif status_min == 400 and status_max == 599:\n query[\"mcp_response.status\"] = \"error\"\n else:\n # Registry API uses numeric status codes\n query[\"response.status_code\"] = {}\n if status_min is not None:\n query[\"response.status_code\"][\"$gte\"] = status_min\n if status_max is not None:\n query[\"response.status_code\"][\"$lte\"] = status_max\n\n # Authorization filter\n if auth_decision:\n query[\"authorization.decision\"] = auth_decision\n\n return query\n\n\n@router.get(\"/filter-options\", response_model=AuditFilterOptions)\nasync def get_filter_options(\n user_context: Annotated[dict[str, Any], Depends(require_admin)],\n stream: str = Query(\n \"registry_api\",\n pattern=\"^(registry_api|mcp_access)$\",\n description=\"Log stream type\",\n ),\n) -> AuditFilterOptions:\n \"\"\"Get distinct filter values for audit log dropdowns. Requires admin access.\"\"\"\n start_time = time.time()\n\n log_type_map = {\n \"registry_api\": \"registry_api_access\",\n \"mcp_access\": \"mcp_server_access\",\n }\n log_type = log_type_map.get(stream, stream)\n query = {\"log_type\": log_type}\n\n repository = get_audit_repository()\n\n usernames = await repository.distinct(\"identity.username\", query)\n\n server_names: list[str] = []\n if stream == \"mcp_access\":\n server_names = await repository.distinct(\"mcp_server.name\", query)\n\n elapsed = time.time() - start_time\n logger.info(\n f\"Filter options fetched in {elapsed:.2f}s (stream={stream}, \"\n f\"usernames={len(usernames)}, servers={len(server_names)})\"\n )\n\n return AuditFilterOptions(\n usernames=usernames,\n server_names=server_names,\n )\n\n\n@router.get(\"/statistics\", response_model=AuditStatisticsResponse)\nasync def get_statistics(\n user_context: Annotated[dict[str, Any], Depends(require_admin)],\n stream: str = Query(\n \"registry_api\",\n pattern=\"^(registry_api|mcp_access)$\",\n description=\"Log stream type\",\n ),\n days: int = Query(\n 7,\n ge=1,\n le=30,\n description=\"Number of days to include in statistics\",\n ),\n username: str | None = Query(\n None,\n description=\"Filter statistics to a specific username\",\n ),\n) -> AuditStatisticsResponse:\n \"\"\"Get aggregated audit statistics for the dashboard. Requires admin access.\"\"\"\n start_time = time.time()\n\n log_type_map = {\n \"registry_api\": \"registry_api_access\",\n \"mcp_access\": \"mcp_server_access\",\n }\n log_type = log_type_map.get(stream, stream)\n cutoff = datetime.now(UTC) - timedelta(days=days)\n base_match: dict[str, Any] = {\"log_type\": log_type, \"timestamp\": {\"$gte\": cutoff}}\n\n if username:\n escaped_username = re.escape(username)\n base_match[\"identity.username\"] = {\"$regex\": f\"^{escaped_username}$\", \"$options\": \"i\"}\n\n repository = get_audit_repository()\n\n # Build all pipelines upfront\n op_field = \"$mcp_request.method\" if stream == \"mcp_access\" else \"$action.operation\"\n\n # Status distribution pipeline differs by stream\n if stream == \"mcp_access\":\n status_pipeline: list[dict[str, Any]] = [\n {\"$match\": base_match},\n {\"$group\": {\"_id\": \"$mcp_response.status\", \"count\": {\"$sum\": 1}}},\n ]\n else:\n status_pipeline = [\n {\"$match\": base_match},\n {\n \"$project\": {\n \"bucket\": {\n \"$switch\": {\n \"branches\": [\n {\n \"case\": {\n \"$and\": [\n {\"$gte\": [\"$response.status_code\", 200]},\n {\"$lt\": [\"$response.status_code\", 300]},\n ]\n },\n \"then\": \"2xx\",\n },\n {\n \"case\": {\n \"$and\": [\n {\"$gte\": [\"$response.status_code\", 400]},\n {\"$lt\": [\"$response.status_code\", 500]},\n ]\n },\n \"then\": \"4xx\",\n },\n {\n \"case\": {\"$gte\": [\"$response.status_code\", 500]},\n \"then\": \"5xx\",\n },\n ],\n \"default\": \"other\",\n }\n }\n }\n },\n {\"$group\": {\"_id\": \"$bucket\", \"count\": {\"$sum\": 1}}},\n ]\n\n # Run ALL pipelines concurrently with asyncio.gather()\n # Note: audit data is bounded by TTL (default 7 days), so collection size is naturally limited\n tasks = [\n repository.count(base_match),\n repository.aggregate(\n [\n {\"$match\": base_match},\n {\"$group\": {\"_id\": \"$identity.username\", \"count\": {\"$sum\": 1}}},\n {\"$sort\": {\"count\": -1}},\n {\"$limit\": 10},\n ]\n ),\n repository.aggregate(\n [\n {\"$match\": base_match},\n {\"$group\": {\"_id\": op_field, \"count\": {\"$sum\": 1}}},\n {\"$sort\": {\"count\": -1}},\n {\"$limit\": 10},\n ]\n ),\n repository.aggregate(\n [\n {\"$match\": base_match},\n {\n \"$group\": {\n \"_id\": {\"$dateToString\": {\"format\": \"%Y-%m-%d\", \"date\": \"$timestamp\"}},\n \"count\": {\"$sum\": 1},\n }\n },\n {\"$sort\": {\"_id\": 1}},\n ]\n ),\n repository.aggregate(status_pipeline),\n # Per-user activity breakdown: group by (username, operation), then re-group by username\n repository.aggregate(\n [\n {\"$match\": base_match},\n {\n \"$group\": {\n \"_id\": {\n \"user\": \"$identity.username\",\n \"op\": op_field,\n },\n \"count\": {\"$sum\": 1},\n }\n },\n {\"$sort\": {\"count\": -1}},\n {\n \"$group\": {\n \"_id\": \"$_id.user\",\n \"total\": {\"$sum\": \"$count\"},\n \"operations\": {\"$push\": {\"name\": \"$_id.op\", \"count\": \"$count\"}},\n }\n },\n {\"$sort\": {\"total\": -1}},\n {\"$limit\": 10},\n ]\n ),\n ]\n\n # Conditionally add MCP server aggregation\n if stream == \"mcp_access\":\n tasks.append(\n repository.aggregate(\n [\n {\"$match\": base_match},\n {\"$group\": {\"_id\": \"$mcp_server.name\", \"count\": {\"$sum\": 1}}},\n {\"$sort\": {\"count\": -1}},\n {\"$limit\": 10},\n ]\n )\n )\n\n results = await asyncio.gather(*tasks)\n\n # Unpack results\n total_events = results[0]\n top_users_raw = results[1]\n top_ops_raw = results[2]\n timeline_raw = results[3]\n status_raw = results[4]\n user_activity_raw = results[5]\n top_servers_raw = results[6] if stream == \"mcp_access\" else []\n\n # Transform results\n top_users = [\n UsageSummaryItem(name=r[\"_id\"] or \"unknown\", count=r[\"count\"])\n for r in top_users_raw\n if r.get(\"_id\")\n ]\n\n top_servers = (\n [\n UsageSummaryItem(name=r[\"_id\"] or \"unknown\", count=r[\"count\"])\n for r in top_servers_raw\n if r.get(\"_id\")\n ]\n if top_servers_raw\n else []\n )\n\n top_operations = [\n UsageSummaryItem(name=r[\"_id\"] or \"unknown\", count=r[\"count\"])\n for r in top_ops_raw\n if r.get(\"_id\")\n ]\n\n activity_timeline = [TimeSeriesBucket(period=r[\"_id\"], count=r[\"count\"]) for r in timeline_raw]\n\n status_dist = StatusDistribution()\n if stream == \"mcp_access\":\n for r in status_raw:\n if r[\"_id\"] == \"success\":\n status_dist.status_2xx = r[\"count\"]\n elif r[\"_id\"] == \"error\":\n status_dist.status_5xx = r[\"count\"]\n else:\n for r in status_raw:\n if r.get(\"_id\") == \"2xx\":\n status_dist.status_2xx = r[\"count\"]\n elif r.get(\"_id\") == \"4xx\":\n status_dist.status_4xx = r[\"count\"]\n elif r.get(\"_id\") == \"5xx\":\n status_dist.status_5xx = r[\"count\"]\n\n # Transform per-user activity breakdown\n if user_activity_raw:\n logger.debug(f\"Raw user_activity sample: {user_activity_raw[0]}\")\n user_activity = []\n for r in user_activity_raw:\n if not r.get(\"_id\"):\n continue\n ops = []\n for op in (r.get(\"operations\") or [])[:5]:\n op_name = (\n op.get(\"name\") or op.get(\"_id\", {}).get(\"op\") if isinstance(op, dict) else None\n )\n op_count = op.get(\"count\", 0) if isinstance(op, dict) else 0\n if op_name:\n ops.append(UsageSummaryItem(name=str(op_name), count=op_count))\n user_activity.append(\n UserActivityItem(\n username=r[\"_id\"] or \"unknown\",\n total=r.get(\"total\", 0),\n operations=ops,\n )\n )\n\n elapsed = time.time() - start_time\n logger.info(f\"Audit statistics computed in {elapsed:.2f}s (stream={stream}, days={days})\")\n\n return AuditStatisticsResponse(\n total_events=total_events,\n top_users=top_users,\n top_servers=top_servers,\n top_operations=top_operations,\n activity_timeline=activity_timeline,\n status_distribution=status_dist,\n user_activity=user_activity,\n )\n\n\n@router.get(\"/events\", response_model=AuditEventsResponse)\nasync def get_audit_events(\n user_context: Annotated[dict[str, Any], Depends(require_admin)],\n stream: str = Query(\n \"registry_api\",\n pattern=\"^(registry_api|mcp_access)$\",\n description=\"Log stream type\",\n ),\n from_time: datetime | None = Query(\n None,\n alias=\"from\",\n description=\"Start of time range (ISO 8601)\",\n ),\n to_time: datetime | None = Query(\n None,\n alias=\"to\",\n description=\"End of time range (ISO 8601)\",\n ),\n username: str | None = Query(\n None,\n description=\"Filter by username\",\n ),\n operation: str | None = Query(\n None,\n description=\"Filter by operation type\",\n ),\n resource_type: str | None = Query(\n None,\n description=\"Filter by resource type\",\n ),\n resource_id: str | None = Query(\n None,\n description=\"Filter by resource ID\",\n ),\n status_min: int | None = Query(\n None,\n ge=100,\n le=599,\n description=\"Minimum HTTP status code\",\n ),\n status_max: int | None = Query(\n None,\n ge=100,\n le=599,\n description=\"Maximum HTTP status code\",\n ),\n auth_decision: str | None = Query(\n None,\n pattern=\"^(ALLOW|DENY|NOT_REQUIRED)$\",\n description=\"Filter by authorization decision\",\n ),\n limit: int = Query(\n 50,\n ge=1,\n le=500,\n description=\"Maximum events per page\",\n ),\n offset: int = Query(\n 0,\n ge=0,\n description=\"Number of events to skip\",\n ),\n sort_order: int = Query(\n -1,\n ge=-1,\n le=1,\n description=\"Sort order: -1 for descending (newest first), 1 for ascending (oldest first)\",\n ),\n) -> AuditEventsResponse:\n \"\"\"\n Query recent audit events from MongoDB.\n\n Returns paginated audit events matching the specified filters.\n All filters are optional and can be combined.\n\n Requires admin access.\n \"\"\"\n logger.info(\n f\"Admin '{user_context.get('username')}' querying audit events: \"\n f\"stream={stream}, limit={limit}, offset={offset}\"\n )\n\n query = _build_query(\n stream=stream,\n from_time=from_time,\n to_time=to_time,\n username=username,\n operation=operation,\n resource_type=resource_type,\n resource_id=resource_id,\n status_min=status_min,\n status_max=status_max,\n auth_decision=auth_decision,\n )\n\n repository = get_audit_repository()\n\n try:\n # Get total count for pagination\n total = await repository.count(query)\n\n # Get events\n events = await repository.find(\n query=query,\n limit=limit,\n offset=offset,\n sort_field=\"timestamp\",\n sort_order=sort_order,\n )\n\n logger.debug(f\"Found {len(events)} audit events (total: {total})\")\n\n return AuditEventsResponse(\n total=total,\n limit=limit,\n offset=offset,\n events=events,\n )\n except Exception as e:\n logger.error(f\"Error querying audit events: {e}\", exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to query audit events\",\n )\n\n\n@router.get(\"/events/{request_id}\")\nasync def get_audit_event(\n request_id: str,\n user_context: Annotated[dict[str, Any], Depends(require_admin)],\n log_type: str | None = Query(\n default=None,\n description=\"Filter by log type: registry_api_access or mcp_server_access\",\n ),\n) -> dict[str, Any]:\n \"\"\"\n Get audit events by request_id.\n\n Returns all audit event records matching the request_id,\n optionally filtered by log_type. A single request may have\n multiple audit events (e.g., MCP server access + registry API access).\n\n Requires admin access.\n \"\"\"\n logger.info(\n f\"Admin '{user_context.get('username')}' retrieving audit events: \"\n f\"request_id={request_id}, log_type={log_type}\"\n )\n\n repository = get_audit_repository()\n\n try:\n query: dict[str, Any] = {\"request_id\": request_id}\n if log_type is not None:\n query[\"log_type\"] = log_type\n\n events = await repository.find(query, limit=10)\n\n if not events:\n raise HTTPException(\n status_code=status.HTTP_404_NOT_FOUND,\n detail=\"Event not found\",\n )\n\n return {\n \"request_id\": request_id,\n \"events\": events,\n }\n except HTTPException:\n raise\n except Exception as e:\n logger.error(f\"Error retrieving audit events: {e}\", exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to retrieve audit events\",\n )\n\n\ndef _generate_jsonl(events: list[dict[str, Any]]):\n \"\"\"Generate JSONL output from events.\"\"\"\n import json\n\n for event in events:\n # Convert datetime objects to ISO format strings\n if \"timestamp\" in event and isinstance(event[\"timestamp\"], datetime):\n event[\"timestamp\"] = event[\"timestamp\"].isoformat()\n yield json.dumps(event) + \"\\n\"\n\n\ndef _generate_csv(events: list[dict[str, Any]]):\n \"\"\"Generate CSV output from events.\"\"\"\n if not events:\n yield \"\"\n return\n\n output = io.StringIO()\n\n # Define CSV columns (flattened structure)\n fieldnames = [\n \"timestamp\",\n \"request_id\",\n \"log_type\",\n \"username\",\n \"auth_method\",\n \"is_admin\",\n \"method\",\n \"path\",\n \"status_code\",\n \"duration_ms\",\n \"operation\",\n \"resource_type\",\n \"resource_id\",\n \"auth_decision\",\n ]\n\n writer = csv.DictWriter(output, fieldnames=fieldnames)\n writer.writeheader()\n\n for event in events:\n # Flatten nested structure\n row = {\n \"timestamp\": event.get(\"timestamp\", \"\"),\n \"request_id\": event.get(\"request_id\", \"\"),\n \"log_type\": event.get(\"log_type\", \"\"),\n \"username\": event.get(\"identity\", {}).get(\"username\", \"\"),\n \"auth_method\": event.get(\"identity\", {}).get(\"auth_method\", \"\"),\n \"is_admin\": event.get(\"identity\", {}).get(\"is_admin\", False),\n \"method\": event.get(\"request\", {}).get(\"method\", \"\"),\n \"path\": event.get(\"request\", {}).get(\"path\", \"\"),\n \"status_code\": event.get(\"response\", {}).get(\"status_code\", \"\"),\n \"duration_ms\": event.get(\"response\", {}).get(\"duration_ms\", \"\"),\n \"operation\": event.get(\"action\", {}).get(\"operation\", \"\")\n if event.get(\"action\")\n else \"\",\n \"resource_type\": event.get(\"action\", {}).get(\"resource_type\", \"\")\n if event.get(\"action\")\n else \"\",\n \"resource_id\": event.get(\"action\", {}).get(\"resource_id\", \"\")\n if event.get(\"action\")\n else \"\",\n \"auth_decision\": event.get(\"authorization\", {}).get(\"decision\", \"\")\n if event.get(\"authorization\")\n else \"\",\n }\n\n # Convert datetime to string if needed\n if isinstance(row[\"timestamp\"], datetime):\n row[\"timestamp\"] = row[\"timestamp\"].isoformat()\n\n writer.writerow(row)\n\n yield output.getvalue()\n\n\n@router.get(\"/export\")\nasync def export_audit_events(\n user_context: Annotated[dict[str, Any], Depends(require_admin)],\n format: str = Query(\n \"jsonl\",\n pattern=\"^(jsonl|csv)$\",\n description=\"Export format: jsonl or csv\",\n ),\n stream: str = Query(\n \"registry_api\",\n pattern=\"^(registry_api|mcp_access)$\",\n description=\"Log stream type\",\n ),\n from_time: datetime | None = Query(\n None,\n alias=\"from\",\n description=\"Start of time range (ISO 8601)\",\n ),\n to_time: datetime | None = Query(\n None,\n alias=\"to\",\n description=\"End of time range (ISO 8601)\",\n ),\n username: str | None = Query(\n None,\n description=\"Filter by username\",\n ),\n operation: str | None = Query(\n None,\n description=\"Filter by operation type\",\n ),\n resource_type: str | None = Query(\n None,\n description=\"Filter by resource type\",\n ),\n resource_id: str | None = Query(\n None,\n description=\"Filter by resource ID\",\n ),\n status_min: int | None = Query(\n None,\n ge=100,\n le=599,\n description=\"Minimum HTTP status code\",\n ),\n status_max: int | None = Query(\n None,\n ge=100,\n le=599,\n description=\"Maximum HTTP status code\",\n ),\n auth_decision: str | None = Query(\n None,\n pattern=\"^(ALLOW|DENY|NOT_REQUIRED)$\",\n description=\"Filter by authorization decision\",\n ),\n limit: int = Query(\n 10000,\n ge=1,\n le=100000,\n description=\"Maximum events to export\",\n ),\n) -> StreamingResponse:\n \"\"\"\n Export filtered audit events as JSONL or CSV file.\n\n Returns a downloadable file containing audit events matching\n the specified filters.\n\n Requires admin access.\n \"\"\"\n logger.info(\n f\"Admin '{user_context.get('username')}' exporting audit events: \"\n f\"format={format}, stream={stream}, limit={limit}\"\n )\n\n query = _build_query(\n stream=stream,\n from_time=from_time,\n to_time=to_time,\n username=username,\n operation=operation,\n resource_type=resource_type,\n resource_id=resource_id,\n status_min=status_min,\n status_max=status_max,\n auth_decision=auth_decision,\n )\n\n repository = get_audit_repository()\n\n try:\n # Get events for export (no offset, just limit)\n events = await repository.find(\n query=query,\n limit=limit,\n offset=0,\n sort_field=\"timestamp\",\n sort_order=-1,\n )\n\n # Generate timestamp for filename\n timestamp = datetime.now(UTC).strftime(\"%Y%m%d-%H%M%S\")\n filename = f\"audit-export-{timestamp}.{format}\"\n\n if format == \"jsonl\":\n return StreamingResponse(\n _generate_jsonl(events),\n media_type=\"application/x-ndjson\",\n headers={\n \"Content-Disposition\": f\"attachment; filename={filename}\",\n },\n )\n else: # csv\n return StreamingResponse(\n _generate_csv(events),\n media_type=\"text/csv\",\n headers={\n \"Content-Disposition\": f\"attachment; filename={filename}\",\n },\n )\n except Exception as e:\n logger.error(f\"Error exporting audit events: {e}\", exc_info=True)\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Failed to export audit events\",\n )\n" }, { "path": "registry/audit/service.py", "content": "\"\"\"\nAuditLogger service for writing audit events to MongoDB.\n\nThis module provides the core audit logging service that writes\naudit events to MongoDB for persistent storage and querying.\n\"\"\"\n\nimport asyncio\nimport logging\nfrom typing import TYPE_CHECKING, Optional, Union\n\nfrom .models import RegistryApiAccessRecord\n\nif TYPE_CHECKING:\n from ..repositories.audit_repository import AuditRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass AuditLogger:\n \"\"\"\n Async audit logger for MongoDB storage.\n\n Writes audit events to MongoDB for persistent storage. Events can be\n queried through the audit API endpoints.\n\n Attributes:\n stream_name: Name of the audit stream for categorization\n mongodb_enabled: Whether MongoDB logging is enabled\n \"\"\"\n\n def __init__(\n self,\n log_dir: str = \"logs/audit\",\n rotation_hours: int = 1,\n rotation_max_mb: int = 100,\n local_retention_hours: int = 24,\n stream_name: str = \"registry-api-access\",\n mongodb_enabled: bool = False,\n audit_repository: Optional[\"AuditRepositoryBase\"] = None,\n ):\n \"\"\"\n Initialize the AuditLogger.\n\n Args:\n log_dir: Deprecated - no longer used (kept for backward compatibility)\n rotation_hours: Deprecated - no longer used (kept for backward compatibility)\n rotation_max_mb: Deprecated - no longer used (kept for backward compatibility)\n local_retention_hours: Deprecated - no longer used (kept for backward compatibility)\n stream_name: Name of the audit stream for categorization\n mongodb_enabled: Whether to write audit events to MongoDB\n audit_repository: Repository for MongoDB writes (required if mongodb_enabled)\n \"\"\"\n self.stream_name = stream_name\n self.mongodb_enabled = mongodb_enabled\n self._audit_repository = audit_repository\n\n # Lock for thread-safe operations\n self._lock = asyncio.Lock()\n\n if mongodb_enabled and audit_repository:\n logger.info(f\"Audit logging enabled for stream: {stream_name} (MongoDB)\")\n elif not mongodb_enabled:\n logger.warning(f\"Audit logging disabled for stream: {stream_name}\")\n\n async def log_event(\n self,\n record: Union[RegistryApiAccessRecord, \"MCPServerAccessRecord\"],\n ) -> None:\n \"\"\"\n Write an audit record to MongoDB.\n\n This method is thread-safe. If MongoDB is not enabled or not\n available, the event is silently dropped to avoid impacting\n request processing.\n\n Args:\n record: The audit record to log (RegistryApiAccessRecord or MCPServerAccessRecord)\n \"\"\"\n if not self.mongodb_enabled or not self._audit_repository:\n return\n\n async with self._lock:\n try:\n await self._audit_repository.insert(record)\n except Exception as e:\n logger.error(f\"Failed to write audit event to MongoDB: {e}\")\n # Don't raise - audit logging should not break request processing\n\n async def close(self) -> None:\n \"\"\"\n Close the audit logger.\n\n This method exists for backward compatibility and cleanup.\n \"\"\"\n logger.debug(f\"Audit logger closed for stream: {self.stream_name}\")\n\n @property\n def current_file_path(self) -> str | None:\n \"\"\"Deprecated - returns None (no local files).\"\"\"\n return None\n\n @property\n def is_open(self) -> bool:\n \"\"\"Check if the audit logger is operational.\"\"\"\n return self.mongodb_enabled and self._audit_repository is not None\n" }, { "path": "registry/auth/__init__.py", "content": "" }, { "path": "registry/auth/csrf.py", "content": "\"\"\"CSRF token generation and validation utilities.\n\nProvides signed CSRF tokens bound to user sessions using itsdangerous.\nTokens are validated against the session ID and expire based on session max age.\n\"\"\"\n\nimport logging\n\nfrom fastapi import Form, HTTPException, Request, status\nfrom itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer\n\nfrom ..core.config import settings\n\nlogger = logging.getLogger(__name__)\n\nCSRF_SALT: str = \"csrf-salt\"\n\n_csrf_signer = URLSafeTimedSerializer(settings.secret_key)\n\n\ndef generate_csrf_token(\n session_id: str,\n) -> str:\n \"\"\"Generate a signed CSRF token bound to the given session ID.\n\n Args:\n session_id: The session cookie value to bind the token to.\n\n Returns:\n A signed CSRF token string.\n \"\"\"\n token = _csrf_signer.dumps(session_id, salt=CSRF_SALT)\n logger.debug(\"Generated CSRF token for session\")\n return token\n\n\ndef validate_csrf_token(\n token: str,\n session_id: str,\n) -> bool:\n \"\"\"Validate a CSRF token against the session ID.\n\n Args:\n token: The CSRF token to validate.\n session_id: The session cookie value the token should be bound to.\n\n Returns:\n True if the token is valid, False otherwise.\n \"\"\"\n try:\n data = _csrf_signer.loads(\n token,\n salt=CSRF_SALT,\n max_age=settings.session_max_age_seconds,\n )\n if data != session_id:\n logger.warning(\"CSRF token session mismatch\")\n return False\n logger.debug(\"CSRF token validated successfully\")\n return True\n except SignatureExpired:\n logger.warning(\"CSRF token has expired\")\n return False\n except BadSignature:\n logger.warning(\"CSRF token has invalid signature\")\n return False\n except Exception as e:\n logger.error(f\"Unexpected error validating CSRF token: {e}\")\n return False\n\n\nasync def verify_csrf_token(\n request: Request,\n csrf_token: str = Form(...),\n) -> None:\n \"\"\"FastAPI dependency that validates the CSRF token from form data.\n\n Reads the session cookie from the request and validates the submitted\n CSRF token against it.\n\n Args:\n request: The incoming FastAPI request.\n csrf_token: The CSRF token submitted via form data.\n\n Raises:\n HTTPException: If the CSRF token is missing, invalid, or the session\n cookie is not present.\n \"\"\"\n session_id = request.cookies.get(settings.session_cookie_name)\n if not session_id:\n logger.warning(\"CSRF validation failed: no session cookie present\")\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"CSRF validation failed: no session\",\n )\n\n if not validate_csrf_token(csrf_token, session_id):\n logger.warning(\"CSRF validation failed: invalid token\")\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"CSRF validation failed: invalid token\",\n )\n\n logger.debug(\"CSRF token verified via dependency\")\n\n\nasync def verify_csrf_token_flexible(\n request: Request,\n) -> None:\n \"\"\"FastAPI dependency that validates CSRF token from multiple sources.\n\n Accepts CSRF token from:\n - Form data (for traditional HTML forms)\n - X-CSRF-Token header (for React/SPA applications)\n\n Skips CSRF validation when no session cookie is present, as the request\n is from a non-browser client (e.g. Bearer token auth) and CSRF attacks\n require a browser session with cookies.\n\n Args:\n request: The incoming FastAPI request.\n\n Raises:\n HTTPException: If CSRF token is missing or invalid for session-based requests.\n \"\"\"\n session_id = request.cookies.get(settings.session_cookie_name)\n if not session_id:\n logger.debug(\"No session cookie present, skipping CSRF check (non-browser client)\")\n return\n\n # Try to get token from header first (for JSON requests)\n csrf_token = request.headers.get(\"X-CSRF-Token\")\n\n # If not in header, try form data (for HTML form requests)\n if not csrf_token:\n try:\n form_data = await request.form()\n csrf_token = form_data.get(\"csrf_token\")\n except Exception:\n pass\n\n if not csrf_token:\n logger.warning(\"CSRF validation failed: no token provided (session-based request)\")\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"CSRF validation failed: no token provided\",\n )\n\n if not validate_csrf_token(csrf_token, session_id):\n logger.warning(\"CSRF validation failed: invalid token\")\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"CSRF validation failed: invalid token\",\n )\n\n logger.debug(\"CSRF token verified via flexible dependency\")\n" }, { "path": "registry/auth/dependencies.py", "content": "import logging\nfrom typing import Annotated, Any\n\nfrom fastapi import Cookie, Depends, Header, HTTPException, Request, status\nfrom itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer\n\nfrom ..core.config import settings\n\nlogger = logging.getLogger(__name__)\n\n# Initialize session signer\nsigner = URLSafeTimedSerializer(settings.secret_key)\n\n\ndef get_current_user(\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n) -> str:\n \"\"\"\n Get the current authenticated user from session cookie.\n\n Returns:\n str: Username of the authenticated user\n\n Raises:\n HTTPException: If user is not authenticated\n \"\"\"\n if not session:\n logger.warning(\"No session cookie provided\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Authentication required\"\n )\n\n try:\n data = signer.loads(session, max_age=settings.session_max_age_seconds)\n username = data.get(\"username\")\n\n if not username:\n logger.warning(\"No username found in session data\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Invalid session data\"\n )\n\n logger.debug(f\"Authentication successful for user: {username}\")\n return username\n\n except SignatureExpired:\n logger.warning(\"Session cookie has expired\")\n raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Session has expired\")\n except BadSignature:\n logger.warning(\"Invalid session cookie signature\")\n raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Invalid session\")\n except Exception as e:\n logger.error(f\"Session validation error: {e}\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Authentication failed\"\n )\n\n\ndef get_user_session_data(\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n) -> dict[str, Any]:\n \"\"\"\n Get the full session data for the authenticated user.\n\n Returns:\n Dict containing username, groups, auth_method, provider, etc.\n\n Raises:\n HTTPException: If user is not authenticated\n \"\"\"\n if not session:\n logger.warning(\"No session cookie provided for session data extraction\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Authentication required\"\n )\n\n try:\n data = signer.loads(session, max_age=settings.session_max_age_seconds)\n\n if not data.get(\"username\"):\n logger.warning(\"No username found in session data\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Invalid session data\"\n )\n\n # All sessions must be OAuth2 - reject legacy \"traditional\" sessions\n if data.get(\"auth_method\") != \"oauth2\":\n logger.warning(\n f\"Rejecting non-OAuth2 session for user {data.get('username')} \"\n f\"(auth_method={data.get('auth_method')}). Please re-login via OAuth2.\"\n )\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED,\n detail=\"Session expired. Please login again via OAuth2.\",\n )\n\n logger.debug(f\"Session data extracted for user: {data.get('username')}\")\n return data\n\n except SignatureExpired:\n logger.warning(\"Session cookie has expired\")\n raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Session has expired\")\n except BadSignature:\n logger.warning(\"Invalid session cookie signature\")\n raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Invalid session\")\n except Exception as e:\n logger.error(f\"Session data extraction error: {e}\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED, detail=\"Authentication failed\"\n )\n\n\n# Global scopes configuration - will be loaded during app startup\nSCOPES_CONFIG = {}\n\n\nasync def reload_scopes_from_repository():\n \"\"\"\n Async function to reload scopes from repository during app startup.\n Uses shared scopes loader from common module.\n \"\"\"\n global SCOPES_CONFIG\n\n try:\n from ..common.scopes_loader import reload_scopes_config\n\n config = await reload_scopes_config()\n\n SCOPES_CONFIG.clear()\n SCOPES_CONFIG.update(config)\n\n group_mappings = config.get(\"group_mappings\", {})\n ui_scopes = config.get(\"UI-Scopes\", {})\n scope_defs = len([k for k in config.keys() if k not in [\"group_mappings\", \"UI-Scopes\"]])\n\n logger.info(\n f\"Loaded scopes configuration: {len(group_mappings)} group mappings, \"\n f\"{scope_defs} scope definitions, {len(ui_scopes)} UI scopes\"\n )\n\n except Exception as e:\n logger.error(f\"Failed to reload scopes from repository: {e}\", exc_info=True)\n\n\nasync def map_cognito_groups_to_scopes(groups: list[str]) -> list[str]:\n \"\"\"\n Map Cognito groups to MCP scopes - queries repository directly.\n\n Args:\n groups: List of Cognito group names\n\n Returns:\n List of MCP scopes\n \"\"\"\n from ..repositories.factory import get_scope_repository\n\n scopes = []\n scope_repo = get_scope_repository()\n\n for group in groups:\n group_scopes = await scope_repo.get_group_mappings(group)\n if group_scopes:\n scopes.extend(group_scopes)\n logger.debug(f\"Mapped group '{group}' to scopes: {group_scopes}\")\n else:\n logger.debug(f\"No scope mapping found for group: {group}\")\n\n # Remove duplicates while preserving order\n seen = set()\n unique_scopes = []\n for scope in scopes:\n if scope not in seen:\n seen.add(scope)\n unique_scopes.append(scope)\n\n logger.info(f\"Final mapped scopes: {unique_scopes}\")\n return unique_scopes\n\n\nasync def get_ui_permissions_for_user(user_scopes: list[str]) -> dict[str, list[str]]:\n \"\"\"\n Get UI permissions for a user based on their scopes - queries repository directly.\n\n Args:\n user_scopes: List of user's scopes (includes UI scope names like 'mcp-registry-admin')\n\n Returns:\n Dict mapping UI actions to lists of services they can perform the action on\n Example: {'list_service': ['mcpgw', 'auth_server'], 'toggle_service': ['mcpgw']}\n \"\"\"\n from ..repositories.factory import get_scope_repository\n\n ui_permissions = {}\n scope_repo = get_scope_repository()\n\n for scope in user_scopes:\n scope_config = await scope_repo.get_ui_scopes(scope)\n if scope_config:\n logger.debug(f\"Processing UI scope '{scope}' with config: {scope_config}\")\n\n # Process each permission in the scope\n for permission, services in scope_config.items():\n if permission not in ui_permissions:\n ui_permissions[permission] = set()\n\n # Handle \"all\" case\n if services == [\"all\"] or (isinstance(services, list) and \"all\" in services):\n ui_permissions[permission].add(\"all\")\n logger.debug(f\"UI permission '{permission}' granted for all services\")\n else:\n # Add specific services\n if isinstance(services, list):\n ui_permissions[permission].update(services)\n logger.debug(\n f\"UI permission '{permission}' granted for services: {services}\"\n )\n\n # Convert sets back to lists\n result = {k: list(v) for k, v in ui_permissions.items()}\n logger.info(f\"Final UI permissions for user: {result}\")\n return result\n\n\ndef user_has_ui_permission_for_service(\n permission: str, service_name: str, user_ui_permissions: dict[str, list[str]]\n) -> bool:\n \"\"\"\n Check if user has a specific UI permission for a specific service.\n\n Args:\n permission: The UI permission to check (e.g., 'list_service', 'toggle_service')\n service_name: The service name to check permission for\n user_ui_permissions: User's UI permissions dict from get_ui_permissions_for_user()\n\n Returns:\n True if user has the permission for the service, False otherwise\n \"\"\"\n if permission not in user_ui_permissions:\n return False\n\n allowed_services = user_ui_permissions[permission]\n\n # Check if user has permission for all services or the specific service\n has_permission = \"all\" in allowed_services or service_name in allowed_services\n\n logger.debug(\n f\"Permission check: {permission} for {service_name} = {has_permission} (allowed: {allowed_services})\"\n )\n return has_permission\n\n\ndef get_accessible_services_for_user(user_ui_permissions: dict[str, list[str]]) -> list[str]:\n \"\"\"\n Get list of services the user can see based on their list_service permission.\n\n Args:\n user_ui_permissions: User's UI permissions dict from get_ui_permissions_for_user()\n\n Returns:\n List of service names the user can see, or ['all'] if they can see all services\n \"\"\"\n list_permissions = user_ui_permissions.get(\"list_service\", [])\n\n if \"all\" in list_permissions:\n return [\"all\"]\n\n return list_permissions\n\n\ndef get_accessible_agents_for_user(user_ui_permissions: dict[str, list[str]]) -> list[str]:\n \"\"\"\n Get list of agents the user can see based on their list_agents permission.\n\n Args:\n user_ui_permissions: User's UI permissions dict from get_ui_permissions_for_user()\n\n Returns:\n List of agent paths the user can see, or ['all'] if they can see all agents\n \"\"\"\n list_permissions = user_ui_permissions.get(\"list_agents\", [])\n\n if \"all\" in list_permissions:\n return [\"all\"]\n\n return list_permissions\n\n\nasync def get_servers_for_scope(scope: str) -> list[str]:\n \"\"\"\n Get list of server names that a scope provides access to - queries repository directly.\n\n Args:\n scope: The scope to check (e.g., 'mcp-servers-restricted/read')\n\n Returns:\n List of server names the scope grants access to\n \"\"\"\n from ..repositories.factory import get_scope_repository\n\n scope_repo = get_scope_repository()\n scope_config = await scope_repo.get_server_scopes(scope)\n server_names = []\n\n for server_config in scope_config:\n if isinstance(server_config, dict) and \"server\" in server_config:\n server_names.append(server_config[\"server\"])\n\n return list(set(server_names)) # Remove duplicates\n\n\nasync def user_has_wildcard_access(user_scopes: list[str]) -> bool:\n \"\"\"\n Check if user has wildcard access to all servers via their scopes - queries repository directly.\n\n A user has wildcard access if any of their scopes includes server: '*'.\n This is determined dynamically from the scopes configuration, not hardcoded group names.\n\n Note: This function checks server access only. It is NOT used to determine\n admin status. See _user_is_admin() for admin determination.\n\n Args:\n user_scopes: List of user's scopes\n\n Returns:\n True if user has wildcard access to all servers, False otherwise\n \"\"\"\n for scope in user_scopes:\n servers = await get_servers_for_scope(scope)\n if \"*\" in servers:\n logger.debug(f\"User scope '{scope}' grants wildcard access to all servers\")\n return True\n\n return False\n\n\n# Prefixes for mutating (management) UI-Scopes actions.\n# Any action starting with these prefixes is a management action.\n# A user with any such action for \"all\" resources is considered an admin.\n# Read-only prefixes (list_, get_, health_check_) are NOT included.\n#\n# SECURITY BOUNDARY: Changes to this tuple affect who is considered an admin.\n# Reference: scripts/registry-admins.json for the complete admin permissions set.\n_ADMIN_ACTION_PREFIXES: tuple[str, ...] = (\n \"register_\",\n \"modify_\",\n \"toggle_\",\n \"delete_\",\n \"publish_\",\n \"create_\",\n)\n\n\ndef _user_is_admin(\n ui_permissions: dict[str, list[str]],\n) -> bool:\n \"\"\"Check if user has admin privileges based on UI-Scopes management actions.\n\n Admin status is determined by whether the user has any mutating\n (write/delete) UI-Scopes action with wildcard (\"all\") access.\n This decouples admin status from server: '*' wildcard access, allowing\n consumer roles to access all servers without gaining admin privileges.\n\n Mutating actions are identified by prefix: register_, modify_, toggle_,\n delete_, publish_, create_. Read-only actions (list_, get_, health_check_)\n do not grant admin status.\n\n See GitHub issue #663 for the motivation behind this design.\n\n Args:\n ui_permissions: Dict mapping UI actions to lists of allowed resources.\n Example: {'list_service': ['all'], 'register_service': ['all']}\n\n Returns:\n True if user has admin-level management permissions, False otherwise.\n \"\"\"\n for action, resources in ui_permissions.items():\n if action.startswith(_ADMIN_ACTION_PREFIXES) and \"all\" in resources:\n logger.debug(f\"Admin check: action '{action}' with 'all' grants admin status\")\n return True\n\n return False\n\n\nasync def get_user_accessible_servers(user_scopes: list[str]) -> list[str]:\n \"\"\"\n Get list of all servers the user has access to based on their scopes - queries repository directly.\n\n Args:\n user_scopes: List of user's scopes\n\n Returns:\n List of server names the user can access\n \"\"\"\n accessible_servers = set()\n\n logger.info(f\"DEBUG: get_user_accessible_servers called with scopes: {user_scopes}\")\n\n for scope in user_scopes:\n logger.info(f\"DEBUG: Processing scope: {scope}\")\n server_names = await get_servers_for_scope(scope)\n logger.info(f\"DEBUG: Scope {scope} maps to servers: {server_names}\")\n accessible_servers.update(server_names)\n\n logger.info(f\"DEBUG: Final accessible servers: {list(accessible_servers)}\")\n logger.debug(\n f\"User with scopes {user_scopes} has access to servers: {list(accessible_servers)}\"\n )\n return list(accessible_servers)\n\n\ndef user_can_modify_servers(user_groups: list[str], user_scopes: list[str]) -> bool:\n \"\"\"\n Check if user can modify servers (toggle, edit).\n\n Args:\n user_groups: List of user's groups\n user_scopes: List of user's scopes\n\n Returns:\n True if user can modify servers, False otherwise\n \"\"\"\n # Admin users can always modify (check both groups and scopes)\n if \"mcp-registry-admin\" in user_groups or \"mcp-registry-admin\" in user_scopes:\n return True\n if \"registry-admins\" in user_groups or \"registry-admins\" in user_scopes:\n return True\n\n # Users with unrestricted execute access can modify\n if \"mcp-servers-unrestricted/execute\" in user_scopes:\n return True\n\n # mcp-registry-user group cannot modify servers (unless they're also admin)\n is_admin = \"mcp-registry-admin\" in user_groups or \"mcp-registry-admin\" in user_scopes\n if \"mcp-registry-user\" in user_groups and not is_admin:\n return False\n\n # For other cases, check if they have any execute permissions\n execute_scopes = [scope for scope in user_scopes if \"/execute\" in scope]\n return len(execute_scopes) > 0\n\n\nasync def user_can_access_server(server_name: str, user_scopes: list[str]) -> bool:\n \"\"\"\n Check if user can access a specific server - queries repository directly.\n\n Args:\n server_name: Name of the server to check\n user_scopes: List of user's scopes\n\n Returns:\n True if user can access the server, False otherwise\n \"\"\"\n accessible_servers = await get_user_accessible_servers(user_scopes)\n return server_name in accessible_servers\n\n\ndef api_auth(\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n) -> str:\n \"\"\"\n API authentication dependency that returns the username.\n Used for API endpoints that need authentication.\n \"\"\"\n return get_current_user(session)\n\n\ndef web_auth(\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n) -> str:\n \"\"\"\n Web authentication dependency that returns the username.\n Used for web pages that need authentication.\n \"\"\"\n return get_current_user(session)\n\n\nasync def enhanced_auth(\n request: Request,\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n) -> dict[str, Any]:\n \"\"\"\n Enhanced authentication dependency that returns full user context.\n Returns username, groups, scopes, and permission flags.\n Also sets request.state.user_context for audit logging middleware.\n \"\"\"\n session_data = get_user_session_data(session)\n\n username = session_data[\"username\"]\n groups = session_data.get(\"groups\", [])\n auth_method = session_data.get(\"auth_method\", \"oauth2\")\n\n logger.info(f\"Enhanced auth debug for {username}: groups={groups}, auth_method={auth_method}\")\n\n # Map groups to scopes via OAuth2 group-to-scope mapping\n scopes = await map_cognito_groups_to_scopes(groups)\n logger.info(f\"OAuth2 user {username} with groups {groups} mapped to scopes: {scopes}\")\n if not groups:\n logger.warning(\n f\"OAuth2 user {username} has no groups! This user may not have proper group assignments.\"\n )\n\n # Get UI permissions\n ui_permissions = await get_ui_permissions_for_user(scopes)\n\n # Get accessible servers (from server scopes)\n accessible_servers = await get_user_accessible_servers(scopes)\n\n # Get accessible services (from UI permissions)\n accessible_services = get_accessible_services_for_user(ui_permissions)\n\n # Get accessible agents (from UI permissions)\n accessible_agents = get_accessible_agents_for_user(ui_permissions)\n\n # Check modification permissions\n can_modify = user_can_modify_servers(groups, scopes)\n\n user_context = {\n \"username\": username,\n \"groups\": groups,\n \"scopes\": scopes,\n \"auth_method\": auth_method,\n \"provider\": session_data.get(\"provider\", \"local\"),\n \"accessible_servers\": accessible_servers,\n \"accessible_services\": accessible_services,\n \"accessible_agents\": accessible_agents,\n \"ui_permissions\": ui_permissions,\n \"can_modify_servers\": can_modify,\n \"is_admin\": _user_is_admin(ui_permissions),\n }\n\n # Set user context on request state for audit logging middleware\n request.state.user_context = user_context\n\n logger.debug(f\"Enhanced auth context for {username}: {user_context}\")\n return user_context\n\n\nasync def nginx_proxied_auth(\n request: Request,\n session: Annotated[\n str | None, Cookie(alias=settings.session_cookie_name, include_in_schema=False)\n ] = None,\n x_user: Annotated[str | None, Header(alias=\"X-User\", include_in_schema=False)] = None,\n x_username: Annotated[str | None, Header(alias=\"X-Username\", include_in_schema=False)] = None,\n x_scopes: Annotated[str | None, Header(alias=\"X-Scopes\", include_in_schema=False)] = None,\n x_auth_method: Annotated[\n str | None, Header(alias=\"X-Auth-Method\", include_in_schema=False)\n ] = None,\n x_client_id: Annotated[str | None, Header(alias=\"X-Client-Id\", include_in_schema=False)] = None,\n x_groups: Annotated[str | None, Header(alias=\"X-Groups\", include_in_schema=False)] = None,\n) -> dict[str, Any]:\n \"\"\"\n Authentication dependency that works with both nginx-proxied requests and direct requests.\n\n For nginx-proxied requests: Reads user context from headers set by nginx after auth validation\n For direct requests: Falls back to session cookie authentication\n\n This allows Anthropic Registry API endpoints to work both when accessed through nginx (with JWT tokens)\n and when accessed directly (with session cookies).\n\n Returns:\n Dict containing username, groups, scopes, and permission flags\n \"\"\"\n # CRITICAL DIAGNOSTIC: Log ALL incoming headers and auth parameters\n logger.debug(f\"[NGINX_AUTH_DEBUG] Request path: {request.url.path}\")\n logger.debug(f\"[NGINX_AUTH_DEBUG] Request method: {request.method}\")\n logger.debug(f\"[NGINX_AUTH_DEBUG] X-User header: '{x_user}' (type: {type(x_user).__name__})\")\n logger.debug(\n f\"[NGINX_AUTH_DEBUG] X-Username header: '{x_username}' (type: {type(x_username).__name__})\"\n )\n logger.debug(\n f\"[NGINX_AUTH_DEBUG] X-Scopes header: '{x_scopes}' (type: {type(x_scopes).__name__})\"\n )\n logger.debug(\n f\"[NGINX_AUTH_DEBUG] X-Auth-Method header: '{x_auth_method}' (type: {type(x_auth_method).__name__})\"\n )\n logger.debug(f\"[NGINX_AUTH_DEBUG] Session cookie present: {session is not None}\")\n logger.debug(\n f\"[NGINX_AUTH_DEBUG] Authorization header: {request.headers.get('authorization', 'NOT PRESENT')[:50] if request.headers.get('authorization') else 'NOT PRESENT'}\"\n )\n\n # Log ALL headers for complete diagnostic\n all_headers = dict(request.headers)\n logger.debug(f\"[NGINX_AUTH_DEBUG] ALL REQUEST HEADERS: {all_headers}\")\n\n # First, try to get user context from nginx headers (JWT Bearer token flow)\n if x_user or x_username:\n username = x_username or x_user\n\n # Parse scopes from space-separated header\n scopes = x_scopes.split() if x_scopes else []\n\n # Parse groups from X-Groups header (set by auth server from JWT claims)\n groups = x_groups.split() if x_groups else []\n\n # If auth server did not forward groups, fall back to admin/user classification\n if not groups and x_auth_method in [\n \"keycloak\",\n \"entra\",\n \"cognito\",\n \"okta\",\n \"auth0\",\n \"network-trusted\",\n \"federation-static\",\n ]:\n if (\n \"mcp-servers-unrestricted/read\" in scopes\n and \"mcp-servers-unrestricted/execute\" in scopes\n ):\n groups = [\"mcp-registry-admin\"]\n else:\n groups = [\"mcp-registry-user\"]\n\n logger.info(\n f\"nginx-proxied auth for user: {username}, method: {x_auth_method}, \"\n f\"groups: {groups}, scopes: {scopes}\"\n )\n\n if x_auth_method == \"federation-static\":\n # Federation static token: scoped access to federation/peer endpoints only\n accessible_servers = []\n accessible_services = []\n accessible_agents = []\n ui_permissions = {}\n can_modify = False\n is_admin = False\n else:\n # Standard resolution for all auth methods including network-trusted\n # (Issue #779: network-trusted now carries per-key scopes from the\n # auth server instead of hard-coded admin).\n accessible_servers = await get_user_accessible_servers(scopes)\n\n ui_permissions = await get_ui_permissions_for_user(scopes)\n\n accessible_services = get_accessible_services_for_user(ui_permissions)\n\n accessible_agents = get_accessible_agents_for_user(ui_permissions)\n\n can_modify = user_can_modify_servers(groups, scopes)\n\n is_admin = _user_is_admin(ui_permissions)\n\n user_context = {\n \"username\": username,\n \"client_id\": x_client_id or \"\",\n \"groups\": groups,\n \"scopes\": scopes,\n \"auth_method\": x_auth_method or \"keycloak\",\n \"provider\": x_auth_method or \"keycloak\", # Use actual auth method as provider\n \"accessible_servers\": accessible_servers,\n \"accessible_services\": accessible_services,\n \"accessible_agents\": accessible_agents,\n \"ui_permissions\": ui_permissions,\n \"can_modify_servers\": can_modify,\n \"is_admin\": is_admin,\n }\n\n # Set user context on request state for audit logging middleware\n request.state.user_context = user_context\n\n logger.debug(\n f\"nginx-proxied auth context for {username} (is_admin={is_admin}): {user_context}\"\n )\n return user_context\n\n # Fallback to session cookie authentication\n logger.info(\n \"[NGINX_AUTH_FALLBACK] No nginx auth headers found, falling back to session cookie auth\"\n )\n logger.info(\n f\"[NGINX_AUTH_FALLBACK] Session cookie value: {session[:20] if session else 'None'}...\"\n )\n logger.info(f\"[NGINX_AUTH_FALLBACK] Request path: {request.url.path}\")\n try:\n return await enhanced_auth(request, session)\n except HTTPException as e:\n logger.error(\n f\"[NGINX_AUTH_FALLBACK] enhanced_auth raised HTTPException: status={e.status_code}, detail={e.detail}\"\n )\n raise\n except Exception as e:\n logger.error(\n f\"[NGINX_AUTH_FALLBACK] enhanced_auth raised unexpected exception: {type(e).__name__}: {str(e)}\"\n )\n raise\n\n\ndef create_session_cookie(\n username: str, auth_method: str = \"oauth2\", provider: str = \"local\"\n) -> str:\n \"\"\"Create a session cookie for a user.\"\"\"\n session_data = {\"username\": username, \"auth_method\": auth_method, \"provider\": provider}\n return signer.dumps(session_data)\n\n\ndef ui_permission_required(permission: str, service_name: str = None):\n \"\"\"\n Decorator to require a specific UI permission for a route.\n\n Args:\n permission: The UI permission required (e.g., 'register_service')\n service_name: Optional service name to check permission for. If None, checks if user has permission for any service.\n\n Returns:\n Dependency function that checks the permission\n \"\"\"\n\n def check_permission(user_context: dict[str, Any] = Depends(enhanced_auth)) -> dict[str, Any]:\n ui_permissions = user_context.get(\"ui_permissions\", {})\n\n if service_name:\n # Check permission for specific service\n if not user_has_ui_permission_for_service(permission, service_name, ui_permissions):\n logger.warning(\n f\"User {user_context.get('username')} lacks UI permission '{permission}' for service '{service_name}'\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Insufficient permissions. Required: {permission} for {service_name}\",\n )\n else:\n # Check if user has permission for any service\n if permission not in ui_permissions or not ui_permissions[permission]:\n logger.warning(\n f\"User {user_context.get('username')} lacks UI permission: {permission}\"\n )\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=f\"Insufficient permissions. Required: {permission}\",\n )\n\n return user_context\n\n return check_permission\n" }, { "path": "registry/auth/internal.py", "content": "\"\"\"\nInternal service-to-service authentication using self-signed JWTs.\n\nThis module provides utilities for authenticating internal API calls\nbetween services (e.g., mcpgw -> registry, registry -> auth-server)\nusing JWTs signed with the shared SECRET_KEY.\n\"\"\"\n\nimport logging\nimport os\nimport time\n\nimport jwt as pyjwt\nfrom fastapi import HTTPException, Request, status\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n# JWT constants (must match auth_server/server.py)\n_INTERNAL_JWT_ISSUER: str = \"mcp-auth-server\"\n_INTERNAL_JWT_AUDIENCE: str = \"mcp-registry\"\n_INTERNAL_JWT_TTL_SECONDS: int = 60\n\n\ndef generate_internal_token(\n subject: str = \"internal-service\",\n purpose: str = \"internal-api\",\n) -> str:\n \"\"\"\n Generate a short-lived self-signed JWT for internal service-to-service auth.\n\n Uses the shared SECRET_KEY that both services have access to.\n\n Args:\n subject: Identity of the calling service\n purpose: Purpose of the request (for audit logging)\n\n Returns:\n Encoded JWT string\n\n Raises:\n ValueError: If SECRET_KEY is not configured\n \"\"\"\n secret_key = os.environ.get(\"SECRET_KEY\")\n if not secret_key:\n raise ValueError(\"SECRET_KEY environment variable not set\")\n\n now = int(time.time())\n claims = {\n \"iss\": _INTERNAL_JWT_ISSUER,\n \"aud\": _INTERNAL_JWT_AUDIENCE,\n \"sub\": subject,\n \"purpose\": purpose,\n \"token_use\": \"access\",\n \"iat\": now,\n \"exp\": now + _INTERNAL_JWT_TTL_SECONDS,\n }\n return pyjwt.encode(claims, secret_key, algorithm=\"HS256\")\n\n\nasync def validate_internal_auth(request: Request) -> str:\n \"\"\"\n FastAPI dependency that validates internal service authentication.\n\n Accepts Bearer JWT signed with the shared SECRET_KEY.\n\n Args:\n request: The FastAPI request object\n\n Returns:\n Caller identity string (e.g., 'registry-service')\n\n Raises:\n HTTPException: If authentication fails\n \"\"\"\n auth_header = request.headers.get(\"Authorization\")\n\n if not auth_header:\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED,\n detail=\"Missing authorization header\",\n headers={\"WWW-Authenticate\": \"Bearer\"},\n )\n\n if auth_header.startswith(\"Bearer \"):\n return _validate_bearer_token(auth_header)\n\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED,\n detail=\"Unsupported authentication scheme. Use Bearer token.\",\n )\n\n\ndef _validate_bearer_token(auth_header: str) -> str:\n \"\"\"Validate a Bearer JWT token signed with SECRET_KEY.\"\"\"\n token = auth_header.split(\" \", 1)[1]\n\n secret_key = os.environ.get(\"SECRET_KEY\")\n if not secret_key:\n logger.error(\"SECRET_KEY not set, cannot validate internal JWT\")\n raise HTTPException(\n status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n detail=\"Internal server configuration error\",\n )\n\n try:\n claims = pyjwt.decode(\n token,\n secret_key,\n algorithms=[\"HS256\"],\n issuer=_INTERNAL_JWT_ISSUER,\n audience=_INTERNAL_JWT_AUDIENCE,\n options={\n \"verify_exp\": True,\n \"verify_iat\": True,\n \"verify_iss\": True,\n \"verify_aud\": True,\n },\n leeway=30,\n )\n\n token_use = claims.get(\"token_use\")\n if token_use != \"access\": # nosec B105 - OAuth2 token type validation per RFC 6749, not a password\n raise ValueError(f\"Invalid token_use: {token_use}\")\n\n caller = claims.get(\"sub\", \"service\")\n logger.debug(f\"Internal auth via JWT for: {caller}\")\n return caller\n\n except pyjwt.ExpiredSignatureError:\n logger.warning(\"Expired JWT token for internal request\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED,\n detail=\"Token has expired\",\n )\n except (pyjwt.InvalidTokenError, ValueError) as e:\n logger.warning(f\"JWT validation failed for internal request: {e}\")\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED,\n detail=\"Invalid token\",\n )\n" }, { "path": "registry/auth/routes.py", "content": "import logging\nimport re\nimport urllib.parse\nfrom typing import Annotated\n\nimport httpx\nfrom fastapi import APIRouter, Cookie, Depends, Request, status\nfrom fastapi.responses import HTMLResponse, RedirectResponse\nfrom fastapi.templating import Jinja2Templates\nfrom prometheus_client import Counter\n\nfrom ..audit.context import set_audit_action\nfrom ..core.config import settings\nfrom .csrf import generate_csrf_token, verify_csrf_token_flexible\n\nlogger = logging.getLogger(__name__)\n\n\n# Prometheus metrics for logout observability\nlogout_id_token_hint_present = Counter(\n \"registry_logout_id_token_hint_present_total\",\n \"Number of Registry logout requests where id_token was successfully extracted and forwarded\",\n)\n\nlogout_id_token_hint_missing = Counter(\n \"registry_logout_id_token_hint_missing_total\",\n \"Number of Registry logout requests where id_token was missing from session\",\n)\n\nlogout_jwt_validation_failed = Counter(\n \"registry_logout_jwt_validation_failed_total\",\n \"Number of Registry logout requests where id_token failed JWT format validation\",\n)\n\nlogout_url_length_warning = Counter(\n \"registry_logout_url_length_warning_total\",\n \"Number of Registry logout requests where the logout URL exceeded recommended length\",\n)\n\nrouter = APIRouter()\n\n# Templates (will be injected via dependency later, but for now keep it simple)\ntemplates = Jinja2Templates(directory=settings.templates_dir)\n\n\ndef _validate_jwt_format(token: str) -> bool:\n \"\"\"Validate that a token matches JWT format (header.payload.signature).\n\n Args:\n token: The token string to validate\n\n Returns:\n True if token matches JWT format, False otherwise\n \"\"\"\n jwt_pattern = r\"^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+$\"\n return bool(re.match(jwt_pattern, token))\n\n\nasync def get_oauth2_providers():\n \"\"\"Fetch available OAuth2 providers from auth server\"\"\"\n try:\n async with httpx.AsyncClient() as client:\n logger.info(\n f\"Fetching OAuth2 providers from {settings.auth_server_url}/oauth2/providers\"\n )\n response = await client.get(f\"{settings.auth_server_url}/oauth2/providers\", timeout=5.0)\n logger.info(f\"OAuth2 providers response: status={response.status_code}\")\n if response.status_code == 200:\n data = response.json()\n providers = data.get(\"providers\", [])\n logger.info(f\"Successfully fetched {len(providers)} OAuth2 providers: {providers}\")\n return providers\n else:\n logger.warning(\n f\"Auth server returned non-200 status: {response.status_code}, body: {response.text}\"\n )\n except Exception as e:\n logger.warning(f\"Failed to fetch OAuth2 providers from auth server: {e}\", exc_info=True)\n return []\n\n\n@router.get(\"/login\", response_class=HTMLResponse)\nasync def login_form(request: Request, error: str | None = None):\n \"\"\"Show login form with OAuth2 providers\"\"\"\n oauth_providers = await get_oauth2_providers()\n return templates.TemplateResponse(\n \"login.html\", {\"request\": request, \"error\": error, \"oauth_providers\": oauth_providers}\n )\n\n\n@router.get(\"/auth/{provider}\")\nasync def oauth2_login_redirect(provider: str, request: Request):\n \"\"\"Redirect to auth server for OAuth2 login\"\"\"\n try:\n # Build redirect URL to auth server - use external URL for browser redirects\n # When behind CloudFront, request.base_url may have wrong scheme/host\n # Check CloudFront and X-Forwarded headers to build correct URL\n host = request.headers.get(\"host\", \"\")\n cloudfront_proto = request.headers.get(\"x-cloudfront-forwarded-proto\", \"\")\n x_forwarded_proto = request.headers.get(\"x-forwarded-proto\", \"\")\n\n # Determine scheme - prefer CloudFront header, then X-Forwarded-Proto\n if cloudfront_proto.lower() == \"https\" or x_forwarded_proto.lower() == \"https\":\n scheme = \"https\"\n else:\n scheme = request.url.scheme\n\n # Build registry URL from headers (more reliable behind proxies)\n if host:\n registry_url = f\"{scheme}://{host}\"\n else:\n registry_url = str(request.base_url).rstrip(\"/\")\n\n auth_external_url = settings.auth_server_external_url\n auth_url = f\"{auth_external_url}/oauth2/login/{provider}?redirect_uri={registry_url}/\"\n logger.info(\n f\"request.base_url: {request.base_url}, registry_url: {registry_url}, auth_external_url: {auth_external_url}, auth_url: {auth_url}\"\n )\n logger.info(f\"Redirecting to OAuth2 login for provider {provider}: {auth_url}\")\n return RedirectResponse(url=auth_url, status_code=302)\n\n except Exception as e:\n logger.error(f\"Error redirecting to OAuth2 login for {provider}: {e}\")\n return RedirectResponse(url=\"/login?error=oauth2_redirect_failed\", status_code=302)\n\n\n@router.get(\"/auth/callback\")\nasync def oauth2_callback(request: Request, error: str = None, details: str = None):\n \"\"\"Handle OAuth2 callback from auth server\"\"\"\n try:\n if error:\n logger.warning(f\"OAuth2 callback received error: {error}, details: {details}\")\n error_message = \"Authentication failed\"\n if error == \"oauth2_error\":\n # Sanitize user-supplied details to prevent injection\n safe_details = re.sub(r\"[^\\w\\s.:-]\", \"\", str(details or \"\"))[:200]\n error_message = f\"OAuth2 provider error: {safe_details}\"\n elif error == \"oauth2_init_failed\":\n error_message = \"Failed to initiate OAuth2 login\"\n elif error == \"oauth2_callback_failed\":\n error_message = \"OAuth2 authentication failed\"\n\n # Redirect to /login with URL-encoded error message (safe relative URL)\n safe_redirect = f\"/login?error={urllib.parse.quote(error_message)}\"\n return RedirectResponse(url=safe_redirect, status_code=302)\n\n # If we reach here, the auth server should have set the session cookie\n # Verify the session is valid by checking the cookie\n session_cookie = request.cookies.get(settings.session_cookie_name)\n if session_cookie:\n try:\n from .dependencies import signer\n\n # Validate session cookie\n session_data = signer.loads(\n session_cookie, max_age=settings.session_max_age_seconds\n )\n username = session_data.get(\"username\")\n auth_method = session_data.get(\"auth_method\", \"unknown\")\n\n logger.info(f\"OAuth2 callback successful for user {username} via {auth_method}\")\n return RedirectResponse(url=\"/\", status_code=302)\n\n except Exception as e:\n logger.warning(f\"Invalid session cookie in OAuth2 callback: {e}\")\n\n # If no valid session, redirect to login with error\n logger.warning(\"OAuth2 callback completed but no valid session found\")\n return RedirectResponse(url=\"/login?error=oauth2_session_invalid\", status_code=302)\n\n except Exception as e:\n logger.error(f\"Error in OAuth2 callback: {e}\")\n return RedirectResponse(url=\"/login?error=oauth2_callback_error\", status_code=302)\n\n\nasync def logout_handler(\n request: Request,\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n):\n \"\"\"Shared logout logic for both GET and POST requests\"\"\"\n # Set audit action for logout\n set_audit_action(request, \"logout\", \"auth\", description=\"User logged out\")\n\n try:\n # Check if user was logged in via OAuth2\n provider = None\n if session:\n try:\n from itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer\n\n serializer = URLSafeTimedSerializer(settings.secret_key)\n session_data = serializer.loads(session, max_age=settings.session_max_age_seconds)\n\n if session_data.get(\"auth_method\") == \"oauth2\":\n provider = session_data.get(\"provider\")\n logger.info(f\"User was authenticated via OAuth2 provider: {provider}\")\n\n except (SignatureExpired, BadSignature, Exception) as e:\n logger.debug(f\"Could not decode session for logout: {e}\")\n\n # Clear local session cookie\n response = RedirectResponse(url=\"/login\", status_code=status.HTTP_303_SEE_OTHER)\n response.delete_cookie(settings.session_cookie_name)\n\n # If user was logged in via OAuth2, redirect to provider logout\n if provider:\n auth_external_url = settings.auth_server_external_url\n\n # Build redirect URI based on current host\n # Check CloudFront header first, then x-forwarded-proto, then request scheme\n host = request.headers.get(\"host\", \"localhost:7860\")\n cloudfront_proto = request.headers.get(\"x-cloudfront-forwarded-proto\", \"\")\n x_forwarded_proto = request.headers.get(\"x-forwarded-proto\", \"\")\n\n if (\n cloudfront_proto.lower() == \"https\"\n or x_forwarded_proto.lower() == \"https\"\n or request.url.scheme == \"https\"\n ):\n scheme = \"https\"\n else:\n scheme = \"http\"\n\n # Handle localhost specially to ensure correct port\n if \"localhost\" in host and \":\" not in host:\n redirect_uri = f\"{scheme}://localhost:7860/logout\"\n else:\n redirect_uri = f\"{scheme}://{host}/logout\"\n\n logout_url = f\"{auth_external_url}/oauth2/logout/{provider}?redirect_uri={redirect_uri}\"\n\n # Extract id_token from session and append as id_token_hint if present\n # This enables proper SSO session termination for Keycloak and Entra ID\n if session:\n try:\n from itsdangerous import URLSafeTimedSerializer\n\n serializer = URLSafeTimedSerializer(settings.secret_key)\n session_data = serializer.loads(\n session, max_age=settings.session_max_age_seconds\n )\n id_token = session_data.get(\"id_token\")\n\n if id_token:\n # Validate JWT format before forwarding\n if not _validate_jwt_format(id_token):\n logger.debug(\"id_token failed JWT format validation, not forwarding\")\n logout_jwt_validation_failed.inc()\n else:\n # URL encode the token\n encoded_token = urllib.parse.quote(id_token, safe=\"\")\n\n # Append id_token_hint to logout URL\n logout_url = f\"{logout_url}&id_token_hint={encoded_token}\"\n\n # Validate URL length (warn if > 2000 chars)\n if len(logout_url) > 2000:\n logger.debug(\n f\"Logout URL length ({len(logout_url)}) exceeds recommended limit (2000)\"\n )\n logout_url_length_warning.inc()\n\n logger.debug(\"id_token extracted and forwarded, has_id_token=True\")\n logout_id_token_hint_present.inc()\n else:\n logger.debug(\"id_token not found in session, has_id_token=False\")\n logout_id_token_hint_missing.inc()\n\n except Exception as e:\n logger.debug(f\"Could not extract id_token from session: {e}\")\n logout_id_token_hint_missing.inc()\n\n logger.debug(f\"Redirecting to {provider} logout\")\n response = RedirectResponse(url=logout_url, status_code=status.HTTP_303_SEE_OTHER)\n response.delete_cookie(settings.session_cookie_name)\n\n logger.info(\"User logged out.\")\n return response\n\n except Exception as e:\n logger.error(f\"Error during logout: {e}\")\n # Fallback to simple logout\n response = RedirectResponse(url=\"/login\", status_code=status.HTTP_303_SEE_OTHER)\n response.delete_cookie(settings.session_cookie_name)\n return response\n\n\n@router.get(\"/logout\")\nasync def logout_get(\n request: Request,\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n):\n \"\"\"Handle logout via GET request (for URL navigation)\"\"\"\n return await logout_handler(request, session)\n\n\n@router.post(\"/logout\")\nasync def logout_post(\n request: Request,\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n _csrf: Annotated[None, Depends(verify_csrf_token_flexible)] = None,\n):\n \"\"\"Handle logout via POST request (for forms with CSRF validation)\"\"\"\n return await logout_handler(request, session)\n\n\n@router.get(\"/providers\")\nasync def get_providers_api():\n \"\"\"API endpoint to get available OAuth2 providers for React frontend\"\"\"\n providers = await get_oauth2_providers()\n return {\"providers\": providers}\n\n\n@router.get(\"/config\")\nasync def get_auth_config():\n \"\"\"API endpoint to get auth configuration for React frontend\"\"\"\n return {\"auth_server_url\": settings.auth_server_external_url}\n\n\n@router.get(\"/csrf-token\")\nasync def get_csrf_token(\n request: Request,\n session: Annotated[str | None, Cookie(alias=settings.session_cookie_name)] = None,\n):\n \"\"\"API endpoint to get a CSRF token for React/SPA applications.\n\n Returns a CSRF token bound to the current session that can be used\n in X-CSRF-Token headers for API requests.\n \"\"\"\n if not session:\n from fastapi.responses import JSONResponse\n\n return JSONResponse(\n status_code=status.HTTP_401_UNAUTHORIZED, content={\"error\": \"No session found\"}\n )\n\n csrf_token = generate_csrf_token(session)\n return {\"csrf_token\": csrf_token}\n" }, { "path": "registry/common/__init__.py", "content": "\"\"\"Common utilities shared between registry and auth server.\"\"\"\n" }, { "path": "registry/common/scopes_loader.py", "content": "\"\"\"\nShared scopes loader module for loading authorization scopes from repository.\n\nThis module is used by both the auth server and registry to load scopes\nfrom either DocumentDB or YAML file backends.\n\"\"\"\n\nimport asyncio\nimport logging\nimport os\nfrom pathlib import Path\nfrom typing import Any\n\nimport yaml\n\nlogger = logging.getLogger(__name__)\n\n\nasync def load_scopes_from_repository(\n max_retries: int = 5, initial_delay: float = 2.0\n) -> dict[str, Any]:\n \"\"\"\n Load scopes configuration from repository with retry logic.\n\n Args:\n max_retries: Maximum number of retry attempts\n initial_delay: Initial delay in seconds (exponential backoff)\n\n Returns:\n Dict with \"group_mappings\", scope definitions, and \"UI-Scopes\"\n \"\"\"\n last_exception = None\n\n for attempt in range(max_retries):\n try:\n # Import here to avoid circular dependencies\n from ..core.config import settings\n from ..repositories.factory import get_scope_repository\n\n if attempt == 0:\n logger.info(f\"Repository settings - backend: {settings.storage_backend}\")\n\n scope_repo = get_scope_repository()\n\n # Load all scopes\n await scope_repo.load_all()\n\n # Get all groups and build scopes configuration\n groups_dict = await scope_repo.list_groups()\n\n group_mappings = {}\n scopes_config = {}\n ui_scopes = {}\n\n # Build scopes config from repository\n for group_name in groups_dict.keys():\n # Get full group details\n group_data = await scope_repo.get_group(group_name)\n if not group_data:\n continue\n\n # Group mappings: Keycloak group → list of scope names\n keycloak_groups = group_data.get(\"group_mappings\", [])\n for keycloak_group in keycloak_groups:\n if keycloak_group not in group_mappings:\n group_mappings[keycloak_group] = []\n if group_name not in group_mappings[keycloak_group]:\n group_mappings[keycloak_group].append(group_name)\n\n # Server access scopes: scope_name → server_access list\n server_access = group_data.get(\"server_access\", [])\n if server_access:\n scopes_config[group_name] = server_access\n\n # UI permissions: scope_name → ui_permissions dict\n ui_permissions = group_data.get(\"ui_permissions\", {})\n if ui_permissions:\n ui_scopes[group_name] = ui_permissions\n\n logger.info(\n f\"Loaded from repository: {len(group_mappings)} group mappings, \"\n f\"{len(scopes_config)} scope definitions, {len(ui_scopes)} UI scopes\"\n )\n\n # Build the complete config structure\n config = {\"group_mappings\": group_mappings, \"UI-Scopes\": ui_scopes}\n config.update(scopes_config)\n\n return config\n\n except (ConnectionRefusedError, OSError) as e:\n last_exception = e\n if attempt < max_retries - 1:\n delay = initial_delay * (2**attempt)\n logger.warning(\n f\"Repository not ready (attempt {attempt + 1}/{max_retries}), \"\n f\"retrying in {delay}s: {e}\"\n )\n await asyncio.sleep(delay)\n else:\n logger.error(\n f\"Failed to connect to repository after {max_retries} attempts: {e}\",\n exc_info=True,\n )\n except Exception as e:\n # Other exceptions should also be retried (might be transient repository errors)\n last_exception = e\n if attempt < max_retries - 1:\n delay = initial_delay * (2**attempt)\n logger.warning(\n f\"Error loading scopes (attempt {attempt + 1}/{max_retries}), \"\n f\"retrying in {delay}s: {e}\"\n )\n await asyncio.sleep(delay)\n else:\n logger.error(\n f\"Failed to load scopes after {max_retries} attempts: {e}\", exc_info=True\n )\n\n # If we get here, all retries failed\n logger.error(\"Returning empty scopes configuration due to failures\")\n return {\"group_mappings\": {}}\n\n\ndef load_scopes_from_yaml(scopes_path: str | None = None) -> dict[str, Any]:\n \"\"\"\n Load scopes configuration from YAML file.\n\n Args:\n scopes_path: Optional path to scopes.yml file\n\n Returns:\n Dict with scopes configuration\n \"\"\"\n try:\n if scopes_path:\n scopes_file = Path(scopes_path)\n else:\n # Default to auth_server/scopes.yml\n scopes_file = Path(__file__).parent.parent.parent / \"auth_server\" / \"scopes.yml\"\n\n # Check alternative location (EFS mount)\n if not scopes_file.exists():\n alt_scopes_file = (\n Path(__file__).parent.parent.parent / \"auth_server\" / \"auth_config\" / \"scopes.yml\"\n )\n if alt_scopes_file.exists():\n scopes_file = alt_scopes_file\n\n if not scopes_file.exists():\n logger.warning(f\"Scopes config file not found at {scopes_file}\")\n return {\"group_mappings\": {}}\n\n with open(scopes_file) as f:\n config = yaml.safe_load(f)\n logger.info(\n f\"Loaded scopes from YAML with \"\n f\"{len(config.get('group_mappings', {}))} group mappings\"\n )\n return config\n\n except Exception as e:\n logger.error(f\"Failed to load scopes from YAML: {e}\")\n return {\"group_mappings\": {}}\n\n\nasync def reload_scopes_config(storage_backend: str | None = None) -> dict[str, Any]:\n \"\"\"\n Reload scopes configuration from configured backend (async version).\n\n Args:\n storage_backend: Override storage backend (defaults to env var)\n\n Returns:\n Dict with scopes configuration\n \"\"\"\n if storage_backend is None:\n from ..core.config import settings\n\n storage_backend = settings.storage_backend\n\n logger.info(f\"Reloading scopes with storage backend: {storage_backend}\")\n\n if storage_backend in (\"documentdb\", \"mongodb-ce\"):\n return await load_scopes_from_repository()\n else:\n # For file backend, also load into the repository so get_ui_scopes works\n from ..repositories.factory import get_scope_repository\n\n scope_repo = get_scope_repository()\n await scope_repo.load_all()\n\n return load_scopes_from_yaml(os.getenv(\"SCOPES_CONFIG_PATH\"))\n" }, { "path": "registry/config/scopes.yml", "content": "# Scopes Configuration for MCP Gateway Registry\n#\n# This file defines three main top-level groups:\n# 1. UI-Scopes: Agent registry permissions (list, get, publish, modify, delete agents) and MCP service access\n# 2. group_mappings: Maps Keycloak groups to scope names\n# 3. Individual group scopes: Detailed MCP server method/tool access for each group\n#\n# Each group has two types of permissions:\n# - Agent permissions: Actions on agent resources (list_agents, get_agent, publish_agent, modify_agent, delete_agent)\n# - MCP server permissions: Methods and tools accessible on specific MCP servers (currenttime, mcpgw, fininfo, etc.)\n#\n# To add a new group, follow these three steps:\n# 1. Add to UI-Scopes: Define agent and service permissions (what agents/services the group can access)\n# 2. Add to group_mappings: Map the Keycloak group name to the internal scope name\n# 3. Add individual group scope entry: Define detailed MCP server methods/tools and agent actions for the group\n\n# ==================== UI-SCOPES ====================\n# Define agent registry permissions and service listing rights for each group\nUI-Scopes:\n # Admin user for MCP registry (highest privileges)\n mcp-registry-admin:\n list_agents:\n - all\n get_agent:\n - all\n publish_agent:\n - all\n modify_agent:\n - all\n delete_agent:\n - all\n list_service:\n - all\n register_service:\n - all\n health_check_service:\n - all\n toggle_service:\n - all\n modify_service:\n - all\n\n # Registry admin group (wildcard access to all agents and services)\n registry-admins:\n list_agents:\n - all\n get_agent:\n - all\n publish_agent:\n - all\n modify_agent:\n - all\n delete_agent:\n - all\n list_service:\n - all\n register_service:\n - all\n health_check_service:\n - all\n toggle_service:\n - all\n modify_service:\n - all\n\n # LOB1 (Line of Business 1): Restricted to code-reviewer and test-automation agents\n registry-users-lob1:\n list_agents:\n - /code-reviewer\n - /test-automation\n get_agent:\n - /code-reviewer\n - /test-automation\n publish_agent:\n - /code-reviewer\n - /test-automation\n modify_agent:\n - /code-reviewer\n - /test-automation\n delete_agent:\n - /code-reviewer\n - /test-automation\n list_service:\n - currenttime\n - mcpgw\n health_check_service:\n - currenttime\n - mcpgw\n\n # LOB2 (Line of Business 2): Restricted to data-analysis and security-analyzer agents\n registry-users-lob2:\n list_agents:\n - /data-analysis\n - /security-analyzer\n get_agent:\n - /data-analysis\n - /security-analyzer\n publish_agent:\n - /data-analysis\n - /security-analyzer\n modify_agent:\n - /data-analysis\n - /security-analyzer\n delete_agent:\n - /data-analysis\n - /security-analyzer\n list_service:\n - realserverfaketools\n - mcpgw\n - fininfo\n health_check_service:\n - realserverfaketools\n - mcpgw\n - fininfo\n\n# ==================== GROUP MAPPINGS ====================\n# Maps Keycloak groups to internal scope group names\ngroup_mappings:\n mcp-registry-admin:\n - mcp-registry-admin\n - mcp-servers-unrestricted/read\n - mcp-servers-unrestricted/execute\n registry-admins:\n - registry-admins\n registry-users-lob1:\n - registry-users-lob1\n registry-users-lob2:\n - registry-users-lob2\n\n# ==================== MCP SERVER SCOPES ====================\n# Unrestricted read access: Wildcard access to all servers with all methods and tools\nmcp-servers-unrestricted/read:\n- server: '*'\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n - GET\n tools: '*'\n- server: api\n methods:\n - tokens\n - GET\n\n# Unrestricted execute access: Full CRUD operations on all servers (POST, PUT, DELETE in addition to read)\nmcp-servers-unrestricted/execute:\n- server: '*'\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n - GET\n - POST\n - PUT\n - DELETE\n tools: '*'\n- server: api\n methods:\n - tokens\n - GET\n - POST\n\n# LOB1 Group Scope: Read-only access to API; currenttime and mcpgw servers; code-reviewer and test-automation agents\nregistry-users-lob1:\n- server: api\n methods:\n - initialize\n - GET\n- server: currenttime\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - current_time_by_timezone\n- server: mcpgw\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - intelligent_tool_finder\n- agents:\n actions:\n - action: list_agents\n resources:\n - /code-reviewer\n - /test-automation\n - action: get_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: publish_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: modify_agent\n resources:\n - /code-reviewer\n - /test-automation\n - action: delete_agent\n resources:\n - /code-reviewer\n - /test-automation\n\n# LOB2 Group Scope: Read-only access to API; realserverfaketools, mcpgw, fininfo servers; data-analysis and security-analyzer agents\nregistry-users-lob2:\n- server: api\n methods:\n - initialize\n - GET\n- server: realserverfaketools\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - quantum_flux_analyzer\n - neural_pattern_synthesizer\n - hyper_dimensional_mapper\n- server: mcpgw\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - intelligent_tool_finder\n- server: fininfo\n methods:\n - initialize\n - notifications/initialized\n - ping\n - tools/list\n - tools/call\n - resources/list\n - resources/templates/list\n tools:\n - get_stock_aggregates\n - print_stock_data\n- agents:\n actions:\n - action: list_agents\n resources:\n - /data-analysis\n - /security-analyzer\n - action: get_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: publish_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: modify_agent\n resources:\n - /data-analysis\n - /security-analyzer\n - action: delete_agent\n resources:\n - /data-analysis\n - /security-analyzer\n\n# Admin Group Scope: Unrestricted access to all servers with wildcard; unrestricted access to all agents\nregistry-admins:\n- server: '*'\n methods:\n - all\n tools:\n - all\n- agents:\n actions:\n - action: list_agents\n resources:\n - all\n - action: get_agent\n resources:\n - all\n - action: publish_agent\n resources:\n - all\n - action: modify_agent\n resources:\n - all\n - action: delete_agent\n resources:\n - all" }, { "path": "registry/constants.py", "content": "\"\"\"\nConstants and enums for the MCP Gateway Registry.\n\"\"\"\n\nimport os\nfrom enum import Enum\n\nfrom pydantic import BaseModel\n\n\nclass HealthStatus(str, Enum):\n \"\"\"Health status constants for services.\"\"\"\n\n HEALTHY = \"healthy\"\n HEALTHY_AUTH_EXPIRED = \"healthy-auth-expired\"\n UNHEALTHY_TIMEOUT = \"unhealthy: timeout\"\n UNHEALTHY_CONNECTION_ERROR = \"unhealthy: connection error\"\n UNHEALTHY_ENDPOINT_CHECK_FAILED = \"unhealthy: endpoint check failed\"\n UNHEALTHY_MISSING_PROXY_URL = \"unhealthy: missing proxy URL\"\n CHECKING = \"checking\"\n UNKNOWN = \"unknown\"\n\n @classmethod\n def get_healthy_statuses(cls) -> list[str]:\n \"\"\"Get list of statuses that should be considered healthy for nginx inclusion.\"\"\"\n return [cls.HEALTHY, cls.HEALTHY_AUTH_EXPIRED]\n\n @classmethod\n def is_healthy(cls, status: str) -> bool:\n \"\"\"Check if a status should be considered healthy.\"\"\"\n return status in cls.get_healthy_statuses()\n\n\nclass TransportType(str, Enum):\n \"\"\"Supported transport types for MCP servers.\"\"\"\n\n STREAMABLE_HTTP = \"streamable-http\"\n SSE = \"sse\"\n\n\nclass AuthScheme(str, Enum):\n \"\"\"Authentication scheme for backend MCP servers.\"\"\"\n\n NONE = \"none\"\n BEARER = \"bearer\"\n API_KEY = \"api_key\"\n\n\n# Auth header defaults\nDEFAULT_API_KEY_HEADER: str = \"X-API-Key\"\nDEFAULT_BEARER_HEADER: str = \"Authorization\"\nVALID_AUTH_SCHEMES: list = [\"none\", \"bearer\", \"api_key\"]\n\n\nclass RegistryConstants(BaseModel):\n \"\"\"Registry configuration constants.\"\"\"\n\n class Config:\n \"\"\"Pydantic config.\"\"\"\n\n frozen = True\n\n # Health check settings\n DEFAULT_HEALTH_CHECK_TIMEOUT: int = 30\n HEALTH_CHECK_INTERVAL: int = 30\n\n # SSL certificate paths\n SSL_CERT_PATH: str = \"/etc/ssl/certs/fullchain.pem\"\n SSL_KEY_PATH: str = \"/etc/ssl/private/privkey.pem\"\n\n # Nginx settings\n NGINX_CONFIG_PATH: str = \"/etc/nginx/conf.d/nginx_rev_proxy.conf\"\n NGINX_TEMPLATE_HTTP_ONLY: str = \"/app/docker/nginx_rev_proxy_http_only.conf\"\n NGINX_TEMPLATE_HTTP_AND_HTTPS: str = \"/app/docker/nginx_rev_proxy_http_and_https.conf\"\n NGINX_TEMPLATE_HTTP_ONLY_LOCAL: str = \"docker/nginx_rev_proxy_http_only.conf\"\n NGINX_TEMPLATE_HTTP_AND_HTTPS_LOCAL: str = \"docker/nginx_rev_proxy_http_and_https.conf\"\n\n # Server settings\n DEFAULT_TRANSPORT: str = TransportType.STREAMABLE_HTTP\n SUPPORTED_TRANSPORTS: list[str] = [TransportType.STREAMABLE_HTTP, TransportType.SSE]\n\n # Anthropic Registry API constants\n ANTHROPIC_API_VERSION: str = \"v0.1\"\n ANTHROPIC_SERVER_NAMESPACE: str = \"io.mcpgateway\"\n ANTHROPIC_API_DEFAULT_LIMIT: int = 100\n ANTHROPIC_API_MAX_LIMIT: int = 1000\n\n # External Registry Tags\n # Comma-separated list of tags that identify external registry servers\n # Example: \"anthropic-registry,workday-asor,custom-registry\"\n EXTERNAL_REGISTRY_TAGS: str = os.getenv(\n \"EXTERNAL_REGISTRY_TAGS\", \"anthropic-registry,workday-asor\"\n )\n\n\n# Global instance\nREGISTRY_CONSTANTS = RegistryConstants()\n" }, { "path": "registry/core/__init__.py", "content": "" }, { "path": "registry/core/config.py", "content": "import logging\nimport secrets\nfrom datetime import UTC\nfrom enum import Enum\nfrom pathlib import Path\n\nfrom pydantic import ConfigDict, Field\nfrom pydantic_settings import BaseSettings\n\n\nclass DeploymentMode(str, Enum):\n \"\"\"Deployment mode options.\"\"\"\n\n WITH_GATEWAY = \"with-gateway\"\n REGISTRY_ONLY = \"registry-only\"\n\n\nclass RegistryMode(str, Enum):\n \"\"\"Registry operating modes.\"\"\"\n\n FULL = \"full\"\n SKILLS_ONLY = \"skills-only\"\n MCP_SERVERS_ONLY = \"mcp-servers-only\"\n AGENTS_ONLY = \"agents-only\"\n\n\nclass Settings(BaseSettings):\n \"\"\"Application settings with environment variable support.\"\"\"\n\n model_config = ConfigDict(\n env_file=\".env\",\n case_sensitive=False,\n extra=\"ignore\", # Ignore extra environment variables\n )\n\n # Auth settings\n secret_key: str = \"\"\n session_cookie_name: str = \"mcp_gateway_session\"\n session_max_age_seconds: int = 60 * 60 * 8 # 8 hours\n session_cookie_secure: bool = False # Set to True in production with HTTPS\n session_cookie_domain: str | None = None # e.g., \".example.com\" for cross-subdomain sharing\n auth_server_url: str = \"http://localhost:8888\"\n auth_server_external_url: str = \"http://localhost:8888\" # External URL for OAuth redirects\n auth_provider: str = \"cognito\" # Auth provider: cognito, keycloak, entra, github\n oauth_store_tokens_in_session: bool = False # Store OAuth tokens in session cookies\n registry_static_token_auth_enabled: bool = False # Enable static token auth (IdP-independent)\n registry_api_token: str = \"\" # Static API token for registry access\n registry_api_keys: str = \"\" # Multi-key static tokens JSON (Issue #779)\n max_tokens_per_user_per_hour: int = 100 # JWT token vending rate limit\n\n # Registration webhook settings (Issue #742)\n registration_webhook_url: str | None = Field(\n default=None,\n description=\"Webhook URL to POST to on successful registration or deletion. Disabled if not set.\",\n )\n registration_webhook_auth_header: str = Field(\n default=\"Authorization\",\n description=\"Auth header name for webhook requests (e.g., Authorization, X-API-Key)\",\n )\n registration_webhook_auth_token: str | None = Field(\n default=None,\n description=\"Auth token for webhook. If header is Authorization, Bearer is auto-prepended.\",\n )\n registration_webhook_timeout_seconds: int = Field(\n default=10,\n description=\"Timeout for webhook HTTP calls in seconds\",\n )\n\n # Registration Gate Configuration (Admission Control, Issue #809)\n registration_gate_enabled: bool = Field(\n default=False,\n description=\"Enable registration gate (admission control webhook) for all asset registrations and updates\",\n )\n registration_gate_url: str = Field(\n default=\"\",\n description=\"URL of the registration gate endpoint (HTTPS recommended, HTTP triggers warning)\",\n )\n registration_gate_auth_type: str = Field(\n default=\"none\",\n description=\"Auth type for gate endpoint: 'none', 'api_key', or 'bearer'\",\n )\n registration_gate_auth_credential: str = Field(\n default=\"\",\n description=\"API key or Bearer token for authenticating with the gate endpoint\",\n )\n registration_gate_auth_header_name: str = Field(\n default=\"X-Api-Key\",\n description=\"HTTP header name for API key auth (only used when auth_type='api_key')\",\n )\n registration_gate_timeout_seconds: int = Field(\n default=5,\n description=\"HTTP request timeout in seconds for each gate call attempt\",\n )\n registration_gate_max_retries: int = Field(\n default=2,\n description=\"Maximum retry attempts for gate calls on transient failures\",\n )\n\n # Embeddings settings [Default]\n embeddings_provider: str = \"sentence-transformers\" # 'sentence-transformers' or 'litellm'\n embeddings_model_name: str = \"all-MiniLM-L6-v2\"\n embeddings_model_dimensions: int = 384 # 384 for default and 1024 for bedrock titan v2\n\n # HNSW vector search tuning (only used with DocumentDB backend)\n # Higher efSearch improves recall at the cost of query latency.\n # Default 40 may miss documents in small collections; 100 gives near-exact recall.\n vector_search_ef_search: int = 100\n\n # LiteLLM-specific settings (only used when embeddings_provider='litellm')\n # For Bedrock: Set to None and configure AWS credentials via standard methods\n # (IAM roles, AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY env vars, or ~/.aws/credentials)\n embeddings_api_key: str | None = None\n embeddings_secret_key: str | None = None\n embeddings_api_base: str | None = None\n embeddings_aws_region: str | None = \"us-east-1\"\n\n # Health check settings\n health_check_interval_seconds: int = (\n 300 # 5 minutes for automatic background checks (configurable via env var)\n )\n health_check_timeout_seconds: int = 2 # Very fast timeout for user-driven actions\n\n # WebSocket performance settings\n max_websocket_connections: int = 100 # Reasonable limit for development/testing\n websocket_send_timeout_seconds: float = 2.0 # Allow slightly more time per connection\n websocket_broadcast_interval_ms: int = 10 # Very responsive - 10ms minimum between broadcasts\n websocket_max_batch_size: int = 20 # Smaller batches for faster updates\n websocket_cache_ttl_seconds: int = 1 # 1 second cache for near real-time user feedback\n\n # Well-known discovery settings\n enable_wellknown_discovery: bool = True\n wellknown_cache_ttl: int = 300 # 5 minutes\n\n # OpenTelemetry / OTLP settings (metrics-service)\n otel_otlp_endpoint: str | None = None # OTLP HTTP endpoint (e.g. https://otlp.example.com)\n otel_otlp_export_interval_ms: int = 30000 # OTLP export interval in milliseconds\n otel_exporter_otlp_metrics_temporality_preference: str = \"cumulative\" # cumulative or delta\n\n # Security scanning settings (MCP Servers)\n security_scan_enabled: bool = True\n security_scan_on_registration: bool = True\n security_block_unsafe_servers: bool = True\n security_analyzers: str = \"yara\" # Comma-separated: yara, llm, or yara,llm\n security_scan_timeout: int = 60 # 1 minute\n security_add_pending_tag: bool = True\n mcp_scanner_llm_api_key: str = \"\" # Optional LLM API key for advanced analysis\n\n # Agent security scanning settings (A2A Agents)\n agent_security_scan_enabled: bool = True\n agent_security_scan_on_registration: bool = True\n agent_security_block_unsafe_agents: bool = True\n agent_security_analyzers: str = (\n \"yara,spec\" # Comma-separated: yara, spec, heuristic, llm, endpoint\n )\n agent_security_scan_timeout: int = 60 # 1 minute\n agent_security_add_pending_tag: bool = True\n a2a_scanner_llm_api_key: str = \"\" # Optional Azure OpenAI API key for LLM-based analysis\n\n # Skill security scanning settings (AI Agent Skills)\n skill_security_scan_enabled: bool = True\n skill_security_scan_on_registration: bool = True\n skill_security_block_unsafe_skills: bool = True\n skill_security_analyzers: str = (\n \"static\" # Comma-separated: static, behavioral, llm, meta, virustotal, ai-defense\n )\n skill_security_scan_timeout: int = 120 # 2 minutes\n skill_security_add_pending_tag: bool = True\n skill_scanner_llm_api_key: str = \"\" # Optional LLM API key for LLM-based analysis\n skill_scanner_virustotal_api_key: str = \"\" # Optional VirusTotal API key\n skill_scanner_ai_defense_api_key: str = \"\" # Optional Cisco AI Defense API key\n\n # GitHub Private Repository Access (SKILL.md fetching)\n github_pat: str = Field(\n default=\"\",\n description=\"GitHub Personal Access Token for private repo SKILL.md access\",\n )\n github_app_id: str = Field(\n default=\"\",\n description=\"GitHub App ID for installation-based auth\",\n )\n github_app_installation_id: str = Field(\n default=\"\",\n description=\"GitHub App Installation ID\",\n )\n github_app_private_key: str = Field(\n default=\"\",\n description=\"GitHub App private key (PEM format, newlines as \\\\n)\",\n )\n github_extra_hosts: str = Field(\n default=\"\",\n description=\"Comma-separated extra GitHub hosts for auth (e.g. github.mycompany.com,raw.github.mycompany.com)\",\n )\n github_api_base_url: str = Field(\n default=\"https://api.github.com\",\n description=\"GitHub API base URL for App token exchange (for GHES: https://github.mycompany.com/api/v3)\",\n )\n\n # Federation settings\n registry_id: str | None = None # Unique identifier for this registry instance in federation\n federation_static_token_auth_enabled: bool = False # Enable federation static token auth\n federation_static_token: str = \"\" # Federation static token for peer registry access\n workday_token_url: str = Field(\n default=\"https://your-tenant.workday.com/ccx/oauth2/your_instance/token\",\n description=\"Workday OAuth token endpoint URL for ASOR federation (must use HTTPS in production)\",\n )\n\n # Registry Card configuration\n registry_url: str = Field(\n default=\"http://localhost:8000\",\n description=\"Base URL of this registry instance (HTTPS required in production)\",\n )\n registry_organization_name: str = Field(\n default=\"ACME Inc.\",\n description=\"Organization that operates this registry\",\n )\n registry_name: str = Field(\n default=\"AI Registry\",\n description=\"Human-readable display name for this registry instance\",\n )\n registry_description: str | None = Field(\n default=None,\n description=\"Description of this registry instance\",\n )\n registry_contact_email: str | None = Field(\n default=None,\n description=\"Contact email for registry operators\",\n )\n registry_contact_url: str | None = Field(\n default=None,\n description=\"Documentation or support URL\",\n )\n\n # Keycloak Configuration\n keycloak_enabled: bool = Field(\n default=False,\n description=\"Enable Keycloak as the identity provider\",\n )\n keycloak_url: str = Field(\n default=\"http://keycloak:8080\",\n description=\"Internal Keycloak URL\",\n )\n keycloak_external_url: str = Field(\n default=\"http://localhost:8080\",\n description=\"External Keycloak URL for browser redirects\",\n )\n keycloak_realm: str = Field(\n default=\"mcp-gateway\",\n description=\"Keycloak realm name\",\n )\n keycloak_client_id: str = Field(\n default=\"mcp-gateway-web\",\n description=\"Keycloak OAuth2 client ID\",\n )\n keycloak_client_secret: str = Field(\n default=\"\",\n description=\"Keycloak OAuth2 client secret\",\n )\n keycloak_admin: str = Field(\n default=\"admin\",\n description=\"Keycloak admin username\",\n )\n keycloak_admin_password: str = Field(\n default=\"\",\n description=\"Keycloak admin password\",\n )\n keycloak_m2m_client_id: str = Field(\n default=\"\",\n description=\"Keycloak M2M (machine-to-machine) client ID\",\n )\n keycloak_m2m_client_secret: str = Field(\n default=\"\",\n description=\"Keycloak M2M (machine-to-machine) client secret\",\n )\n\n # Okta Configuration\n okta_enabled: bool = Field(\n default=False,\n description=\"Enable Okta as the identity provider\",\n )\n okta_domain: str = Field(\n default=\"\",\n description=\"Okta organization domain (e.g., dev-123456.okta.com)\",\n )\n okta_client_id: str = Field(\n default=\"\",\n description=\"Okta OAuth2 client ID\",\n )\n okta_client_secret: str = Field(\n default=\"\",\n description=\"Okta OAuth2 client secret\",\n )\n okta_m2m_client_id: str = Field(\n default=\"\",\n description=\"Okta M2M (machine-to-machine) client ID\",\n )\n okta_m2m_client_secret: str = Field(\n default=\"\",\n description=\"Okta M2M (machine-to-machine) client secret\",\n )\n okta_api_token: str = Field(\n default=\"\",\n description=\"Okta API token for admin operations\",\n )\n okta_auth_server_id: str = Field(\n default=\"\",\n description=\"Okta authorization server ID\",\n )\n\n # Entra ID Configuration\n entra_enabled: bool = Field(\n default=False,\n description=\"Enable Microsoft Entra ID as the identity provider\",\n )\n entra_tenant_id: str = Field(\n default=\"\",\n description=\"Microsoft Entra ID tenant ID\",\n )\n entra_client_id: str = Field(\n default=\"\",\n description=\"Microsoft Entra ID client ID\",\n )\n entra_client_secret: str = Field(\n default=\"\",\n description=\"Microsoft Entra ID client secret\",\n )\n entra_group_admin_id: str = Field(\n default=\"\",\n description=\"Microsoft Entra ID admin group ID\",\n )\n\n # IdP Group Filtering (applies to all identity providers)\n idp_group_filter_prefix: str = Field(\n default=\"\",\n description=\"Comma-separated prefixes to filter IdP groups in IAM > Groups page\",\n )\n\n # M2M direct registration (issue #851)\n m2m_direct_registration_enabled: bool = Field(\n default=True,\n description=(\n \"Enable direct M2M client registration API at /api/iam/m2m-clients. \"\n \"This feature lets admins register M2M client_ids and group mappings \"\n \"without an IdP Admin API token.\"\n ),\n )\n\n # ANS Integration\n ans_integration_enabled: bool = Field(\n default=False,\n description=\"Enable ANS (Agent Name Service) integration\",\n )\n ans_api_endpoint: str = Field(\n default=\"https://api.godaddy.com\",\n description=\"ANS API base URL\",\n )\n ans_api_key: str = Field(\n default=\"\",\n description=\"GoDaddy API key for ANS\",\n )\n ans_api_secret: str = Field(\n default=\"\",\n description=\"GoDaddy API secret for ANS\",\n )\n ans_api_timeout_seconds: int = Field(\n default=30,\n description=\"ANS API request timeout in seconds\",\n )\n ans_sync_interval_hours: int = Field(\n default=6,\n description=\"ANS background sync interval in hours\",\n )\n ans_verification_cache_ttl_seconds: int = Field(\n default=3600,\n description=\"ANS verification cache TTL in seconds\",\n )\n\n # Application Log Configuration (Issue #886)\n app_log_max_bytes: int = Field(\n default=50 * 1024 * 1024,\n description=\"Max size per log file in bytes before rotation (default 50 MB)\",\n )\n app_log_backup_count: int = Field(\n default=5,\n description=\"Number of rotated backup log files to keep\",\n )\n app_log_centralized_enabled: bool = Field(\n default=True,\n description=\"Write application logs to centralized application_logs collection\",\n )\n app_log_centralized_ttl_days: int = Field(\n default=1,\n description=\"Days to retain application log entries in centralized store (TTL index)\",\n )\n app_log_mongodb_buffer_size: int = Field(\n default=50,\n description=\"Number of log records to buffer before flushing to MongoDB\",\n )\n app_log_mongodb_flush_interval_seconds: float = Field(\n default=5.0,\n description=\"Seconds between periodic flushes of buffered log records to MongoDB\",\n )\n app_log_level: str = Field(\n default=\"INFO\",\n description=\"Application log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\",\n )\n app_log_excluded_loggers: str = Field(\n default=\"uvicorn.access,httpx,pymongo,motor\",\n description=\"Comma-separated logger names to exclude from MongoDB log writes\",\n )\n\n # Audit Logging Configuration\n audit_log_enabled: bool = True # Enable/disable audit logging globally\n audit_log_dir: str = \"logs/audit\" # Directory for local audit log files\n audit_log_rotation_hours: int = 1 # Hours between time-based file rotations\n audit_log_rotation_max_mb: int = 100 # Maximum file size in MB before rotation\n audit_log_local_retention_hours: int = (\n 1 # Hours to retain local files (default 1 hour, configurable)\n )\n audit_log_health_checks: bool = False # Whether to log health check requests\n audit_log_static_assets: bool = False # Whether to log static asset requests\n\n # Audit Logging MongoDB Configuration\n audit_log_mongodb_enabled: bool = True # Enable/disable MongoDB storage for audit logs\n audit_log_mongodb_ttl_days: int = 7 # Days to retain audit events in MongoDB (default 7 days)\n\n # Deployment Mode Configuration\n deployment_mode: DeploymentMode = Field(\n default=DeploymentMode.WITH_GATEWAY,\n description=\"Deployment mode: with-gateway or registry-only\",\n )\n registry_mode: RegistryMode = Field(\n default=RegistryMode.FULL, description=\"Registry operating mode\"\n )\n\n # Tab visibility overrides (AND-ed with REGISTRY_MODE feature flags)\n show_servers_tab: bool = Field(default=True, description=\"Show MCP Servers tab in UI\")\n show_virtual_servers_tab: bool = Field(\n default=True, description=\"Show Virtual MCP Servers tab in UI\"\n )\n show_skills_tab: bool = Field(default=True, description=\"Show Skills tab in UI\")\n show_agents_tab: bool = Field(default=True, description=\"Show Agents tab in UI\")\n\n # Telemetry settings (anonymous usage tracking)\n telemetry_enabled: bool = Field(\n default=True,\n description=\"Enable anonymous telemetry (startup ping). Opt-out: MCP_TELEMETRY_DISABLED=1\",\n )\n telemetry_opt_out: bool = Field(\n default=False,\n description=\"Disable daily heartbeat telemetry only. Opt-out: MCP_TELEMETRY_OPT_OUT=1\",\n )\n telemetry_heartbeat_interval_minutes: int = Field(\n default=1440,\n description=\"Heartbeat telemetry interval in minutes (default: 1440 = 24 hours). MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES=1440\",\n )\n telemetry_endpoint: str = Field(\n default=\"https://m3ijrhd020.execute-api.us-east-1.amazonaws.com/v1/collect\",\n description=\"HTTPS endpoint for telemetry collector (must be HTTPS; supports self-hosted)\",\n )\n telemetry_debug: bool = Field(\n default=False,\n description=\"Log telemetry payloads instead of sending (for debugging)\",\n )\n\n # Demo server configuration\n disable_ai_registry_tools_server: bool = Field(\n default=False,\n description=\"Disable auto-registration of the built-in airegistry-tools server on startup. Set DISABLE_AI_REGISTRY_TOOLS_SERVER=true to opt out.\",\n )\n\n @property\n def nginx_updates_enabled(self) -> bool:\n \"\"\"Check if nginx updates should be performed.\"\"\"\n return self.deployment_mode == DeploymentMode.WITH_GATEWAY\n\n # Storage Backend Configuration\n storage_backend: str = \"file\" # Options: \"file\", \"documentdb\"\n\n # DocumentDB Configuration (only used when storage_backend=\"documentdb\")\n documentdb_host: str = \"localhost\"\n documentdb_port: int = 27017\n documentdb_database: str = \"mcp_registry\"\n documentdb_username: str | None = None\n documentdb_password: str | None = None\n documentdb_use_tls: bool = True\n documentdb_tls_ca_file: str = \"/app/certs/global-bundle.pem\"\n documentdb_use_iam: bool = False\n documentdb_replica_set: str | None = None\n documentdb_read_preference: str = \"secondaryPreferred\"\n documentdb_direct_connection: bool = False # Set to True only for single-node MongoDB (tests)\n\n # DocumentDB Namespace (for multi-tenancy support)\n documentdb_namespace: str = \"default\"\n\n # Container paths - adjust for local development\n container_app_dir: Path = Path(\"/app\")\n container_registry_dir: Path = Path(\"/app/registry\")\n container_log_dir: Path = Path(\"/app/logs\")\n\n # Local development mode detection\n @property\n def is_local_dev(self) -> bool:\n \"\"\"Check if running in local development mode.\"\"\"\n return not Path(\"/app\").exists()\n\n def __init__(self, **kwargs):\n super().__init__(**kwargs)\n # Generate secret key if not provided\n if not self.secret_key:\n self.secret_key = secrets.token_hex(32)\n\n @property\n def embeddings_model_dir(self) -> Path:\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"models\" / self.embeddings_model_name\n return self.container_registry_dir / \"models\" / self.embeddings_model_name\n\n @property\n def servers_dir(self) -> Path:\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"servers\"\n return self.container_registry_dir / \"servers\"\n\n @property\n def static_dir(self) -> Path:\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"static\"\n return self.container_registry_dir / \"static\"\n\n @property\n def templates_dir(self) -> Path:\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"templates\"\n return self.container_registry_dir / \"templates\"\n\n @property\n def nginx_config_path(self) -> Path:\n return Path(\"/etc/nginx/conf.d/nginx_rev_proxy.conf\")\n\n @property\n def state_file_path(self) -> Path:\n return self.servers_dir / \"server_state.json\"\n\n @property\n def log_dir(self) -> Path:\n \"\"\"Get log directory based on environment.\"\"\"\n if self.is_local_dev:\n return Path.cwd() / \"logs\"\n return self.container_log_dir\n\n @property\n def log_file_path(self) -> Path:\n if self.is_local_dev:\n return Path.cwd() / \"logs\" / \"registry.log\"\n return self.container_log_dir / \"registry.log\"\n\n @property\n def faiss_index_path(self) -> Path:\n return self.servers_dir / \"service_index.faiss\"\n\n @property\n def faiss_metadata_path(self) -> Path:\n return self.servers_dir / \"service_index_metadata.json\"\n\n @property\n def dotenv_path(self) -> Path:\n if self.is_local_dev:\n return Path.cwd() / \".env\"\n return self.container_registry_dir / \".env\"\n\n @property\n def agents_dir(self) -> Path:\n \"\"\"Directory for agent card storage.\"\"\"\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"agents\"\n return self.container_registry_dir / \"agents\"\n\n @property\n def agent_state_file_path(self) -> Path:\n \"\"\"Path to agent state file (enabled/disabled tracking).\"\"\"\n return self.agents_dir / \"agent_state.json\"\n\n @property\n def peers_dir(self) -> Path:\n \"\"\"Directory for peer federation config storage.\"\"\"\n home_dir = Path.home()\n return home_dir / \"mcp-gateway\" / \"peers\"\n\n @property\n def peer_sync_state_file_path(self) -> Path:\n \"\"\"Path to peer sync state file.\"\"\"\n home_dir = Path.home()\n return home_dir / \"mcp-gateway\" / \"peer_sync_state.json\"\n\n @property\n def audit_log_path(self) -> Path:\n \"\"\"Get audit log directory based on environment.\"\"\"\n if self.is_local_dev:\n return Path.cwd() / self.audit_log_dir\n return self.container_log_dir / \"audit\"\n\n @property\n def data_dir(self) -> Path:\n \"\"\"Get data directory for persistent storage (telemetry ID, etc.).\"\"\"\n if self.is_local_dev:\n return Path.cwd() / \"registry\" / \"data\"\n return self.container_registry_dir / \"data\"\n\n\nclass EmbeddingConfig:\n \"\"\"Helper class for embedding configuration and metadata generation.\"\"\"\n\n def __init__(self, settings_instance: Settings):\n self.settings = settings_instance\n\n @property\n def model_family(self) -> str:\n \"\"\"Extract model family from model name.\n\n Examples:\n - \"openai/text-embedding-ada-002\" -> \"openai\"\n - \"all-MiniLM-L6-v2\" -> \"sentence-transformers\"\n - \"amazon.titan-embed-text-v2:0\" -> \"amazon-bedrock\"\n \"\"\"\n model_name = self.settings.embeddings_model_name\n\n if \"/\" in model_name:\n # Format: \"provider/model-name\"\n return model_name.split(\"/\")[0]\n elif \"amazon.\" in model_name or \"titan\" in model_name.lower():\n return \"amazon-bedrock\"\n elif self.settings.embeddings_provider == \"litellm\":\n return \"litellm\"\n else:\n return self.settings.embeddings_provider\n\n @property\n def index_name(self) -> str:\n \"\"\"Generate dimension-specific collection/index name.\n\n Returns index name in format: mcp-embeddings-{dimensions}-{namespace}\n Example: mcp-embeddings-1536-default\n \"\"\"\n base_name = \"mcp-embeddings\"\n dimensions = self.settings.embeddings_model_dimensions\n namespace = self.settings.documentdb_namespace\n\n # Replace base name with dimension-specific name\n return f\"{base_name}-{dimensions}-{namespace}\"\n\n def get_embedding_metadata(self) -> dict:\n \"\"\"Generate embedding metadata for document storage.\n\n Returns:\n Dictionary with embedding metadata including:\n - provider: Embedding provider (e.g., \"litellm\", \"sentence-transformers\")\n - model: Full model name\n - model_family: Extracted model family\n - dimensions: Embedding dimension count\n - version: Model version (extracted if available, else \"v1\")\n - created_at: Current timestamp in ISO format\n - indexing_strategy: Search strategy (currently \"hybrid\")\n \"\"\"\n from datetime import datetime\n\n model_name = self.settings.embeddings_model_name\n\n # Extract version if present in model name\n version = \"v1\"\n if \"v2\" in model_name.lower():\n version = \"v2\"\n elif \"v3\" in model_name.lower():\n version = \"v3\"\n elif \"ada-002\" in model_name:\n version = \"ada-002\"\n\n return {\n \"provider\": self.settings.embeddings_provider,\n \"model\": model_name,\n \"model_family\": self.model_family,\n \"dimensions\": self.settings.embeddings_model_dimensions,\n \"version\": version,\n \"created_at\": datetime.now(UTC).isoformat(),\n \"indexing_strategy\": \"hybrid\",\n }\n\n\nlogger = logging.getLogger(__name__)\n\n\ndef _validate_mode_combination(\n deployment_mode: DeploymentMode, registry_mode: RegistryMode\n) -> tuple[DeploymentMode, RegistryMode, bool]:\n \"\"\"\n Validate and potentially correct deployment/registry mode combination.\n\n Args:\n deployment_mode: Current deployment mode setting\n registry_mode: Current registry mode setting\n\n Returns:\n Tuple of (corrected_deployment_mode, corrected_registry_mode, was_corrected)\n \"\"\"\n # Invalid: with-gateway + skills-only\n # Skills don't need gateway, auto-convert to registry-only\n if deployment_mode == DeploymentMode.WITH_GATEWAY and registry_mode == RegistryMode.SKILLS_ONLY:\n return (DeploymentMode.REGISTRY_ONLY, RegistryMode.SKILLS_ONLY, True)\n\n return (deployment_mode, registry_mode, False)\n\n\ndef _print_config_warning_banner(\n original_deployment: DeploymentMode,\n original_registry: RegistryMode,\n corrected_deployment: DeploymentMode,\n corrected_registry: RegistryMode,\n) -> None:\n \"\"\"Print conspicuous warning banner for invalid configuration.\"\"\"\n banner = f\"\"\"\n================================================================================\nWARNING: Invalid configuration detected!\n\nDEPLOYMENT_MODE={original_deployment.value} is incompatible with REGISTRY_MODE={original_registry.value}\nSkills do not require gateway integration.\n\nAuto-converting to:\n DEPLOYMENT_MODE={corrected_deployment.value}\n REGISTRY_MODE={corrected_registry.value}\n================================================================================\n\"\"\"\n logger.warning(banner)\n print(banner)\n\n\ndef log_tab_visibility_warnings(s: Settings) -> None:\n \"\"\"Log warnings for SHOW_*_TAB parameters that are ineffective given REGISTRY_MODE.\"\"\"\n mode = s.registry_mode\n checks = [\n (\n s.show_servers_tab,\n \"SHOW_SERVERS_TAB\",\n mode in (RegistryMode.FULL, RegistryMode.MCP_SERVERS_ONLY),\n ),\n (\n s.show_agents_tab,\n \"SHOW_AGENTS_TAB\",\n mode in (RegistryMode.FULL, RegistryMode.AGENTS_ONLY),\n ),\n (\n s.show_skills_tab,\n \"SHOW_SKILLS_TAB\",\n mode in (RegistryMode.FULL, RegistryMode.SKILLS_ONLY),\n ),\n (\n s.show_virtual_servers_tab,\n \"SHOW_VIRTUAL_SERVERS_TAB\",\n mode in (RegistryMode.FULL, RegistryMode.MCP_SERVERS_ONLY),\n ),\n ]\n for show_tab, param_name, mode_enables in checks:\n if show_tab and not mode_enables:\n logger.warning(\n \"%s is true but REGISTRY_MODE=%s does not enable this feature; \"\n \"the tab will remain hidden.\",\n param_name,\n mode.value,\n )\n\n\n# Global settings instance\nsettings = Settings()\n\n# Global embedding config instance\nembedding_config = EmbeddingConfig(settings)\n" }, { "path": "registry/core/endpoint_utils.py", "content": "\"\"\"Centralized endpoint URL resolution utilities.\n\nThis module provides functions for resolving MCP and SSE endpoint URLs\nfrom server configuration, supporting custom endpoints while maintaining\nbackward compatibility with the default /mcp and /sse suffixes.\n\"\"\"\n\nimport logging\nfrom typing import (\n Any,\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _url_contains_transport_path(url: str) -> bool:\n \"\"\"Check if URL already contains a transport-specific path.\n\n Args:\n url: The URL to check.\n\n Returns:\n True if URL contains /mcp or /sse path segments.\n \"\"\"\n return url.endswith(\"/mcp\") or url.endswith(\"/sse\") or \"/mcp/\" in url or \"/sse/\" in url\n\n\ndef get_endpoint_url(\n proxy_pass_url: str,\n transport_type: str = \"streamable-http\",\n mcp_endpoint: str | None = None,\n sse_endpoint: str | None = None,\n) -> str:\n \"\"\"Resolve the actual endpoint URL for health checks and client connections.\n\n This function follows a priority-based resolution:\n 1. If mcp_endpoint/sse_endpoint is explicitly set, use it directly\n 2. If proxy_pass_url already contains /mcp or /sse, use as-is\n 3. Otherwise, append the default suffix (/mcp or /sse)\n\n Args:\n proxy_pass_url: The base proxy URL for the server.\n transport_type: The transport type - \"streamable-http\" or \"sse\".\n mcp_endpoint: Optional explicit endpoint URL for streamable-http.\n sse_endpoint: Optional explicit endpoint URL for SSE.\n\n Returns:\n The resolved endpoint URL.\n \"\"\"\n # Only strip trailing slash if URL doesn't already contain transport path\n # Some servers like Hydrata require the trailing slash\n if _url_contains_transport_path(proxy_pass_url):\n base_url = proxy_pass_url\n else:\n base_url = proxy_pass_url.rstrip(\"/\")\n\n if transport_type == \"sse\":\n # Priority 1: Explicit sse_endpoint\n if sse_endpoint:\n logger.debug(f\"Using explicit sse_endpoint: {sse_endpoint}\")\n return sse_endpoint\n\n # Priority 2: URL already contains transport path\n if base_url.endswith(\"/sse\") or \"/sse/\" in base_url:\n logger.debug(f\"URL already contains /sse: {base_url}\")\n return base_url\n\n # Priority 3: Append default suffix\n endpoint = f\"{base_url}/sse\"\n logger.debug(f\"Appending /sse suffix: {endpoint}\")\n return endpoint\n\n else:\n # streamable-http (default)\n # Priority 1: Explicit mcp_endpoint\n if mcp_endpoint:\n logger.debug(f\"Using explicit mcp_endpoint: {mcp_endpoint}\")\n return mcp_endpoint\n\n # Priority 2: URL already contains transport path\n if _url_contains_transport_path(base_url):\n logger.debug(f\"URL already contains transport path: {base_url}\")\n return base_url\n\n # Priority 3: Append default suffix\n endpoint = f\"{base_url}/mcp\"\n logger.debug(f\"Appending /mcp suffix: {endpoint}\")\n return endpoint\n\n\ndef get_endpoint_url_from_server_info(\n server_info: dict[str, Any],\n transport_type: str = \"streamable-http\",\n) -> str:\n \"\"\"Resolve endpoint URL from a server_info dictionary.\n\n Convenience wrapper around get_endpoint_url that extracts\n the relevant fields from a server_info dict.\n\n Args:\n server_info: Dictionary containing server configuration.\n transport_type: The transport type - \"streamable-http\" or \"sse\".\n\n Returns:\n The resolved endpoint URL.\n\n Raises:\n ValueError: If proxy_pass_url is missing from server_info.\n \"\"\"\n proxy_pass_url = server_info.get(\"proxy_pass_url\")\n if not proxy_pass_url:\n raise ValueError(\"server_info must contain proxy_pass_url\")\n\n return get_endpoint_url(\n proxy_pass_url=proxy_pass_url,\n transport_type=transport_type,\n mcp_endpoint=server_info.get(\"mcp_endpoint\"),\n sse_endpoint=server_info.get(\"sse_endpoint\"),\n )\n" }, { "path": "registry/core/mcp_client.py", "content": "\"\"\"\nMCP Client Service\n\nHandles connections to MCP servers and tool list retrieval.\nCopied directly from main_old.py working implementation.\n\"\"\"\n\nimport asyncio\nimport logging\nimport re\nfrom typing import (\n TypedDict,\n)\n\n# MCP Client imports\nfrom mcp import ClientSession\nfrom mcp.client.sse import sse_client\nfrom mcp.client.streamable_http import streamablehttp_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass MCPServerInfo(TypedDict, total=False):\n \"\"\"Server info returned from MCP initialize response.\"\"\"\n\n name: str\n version: str\n\n\nclass MCPConnectionResult(TypedDict, total=False):\n \"\"\"Result of connecting to an MCP server.\"\"\"\n\n tools: list[dict]\n server_info: MCPServerInfo\n\n\ndef normalize_sse_endpoint_url(endpoint_url: str) -> str:\n \"\"\"\n Normalize SSE endpoint URLs by removing mount path prefixes.\n\n For example:\n - Input: \"/fininfo/messages/?session_id=123\"\n - Output: \"/messages/?session_id=123\"\n\n Args:\n endpoint_url: The endpoint URL from the SSE event data\n\n Returns:\n The normalized URL with mount path stripped\n \"\"\"\n if not endpoint_url:\n return endpoint_url\n\n # Pattern to match mount paths like /fininfo/, /currenttime/, etc.\n # We look for paths that start with /word/ followed by messages/\n mount_path_pattern = r\"^(/[^/]+)(/messages/.*)\"\n\n match = re.match(mount_path_pattern, endpoint_url)\n if match:\n mount_path = match.group(1) # e.g., \"/fininfo\"\n rest_of_url = match.group(2) # e.g., \"/messages/?session_id=123\"\n\n logger.debug(f\"Stripping mount path '{mount_path}' from endpoint URL: {endpoint_url}\")\n return rest_of_url\n\n # If no mount path pattern detected, return as-is\n return endpoint_url\n\n\nimport httpx\n\n\ndef _build_headers_for_server(server_info: dict = None) -> dict[str, str]:\n \"\"\"\n Build HTTP headers for server requests by merging server-specific headers.\n\n Args:\n server_info: Server configuration dictionary\n\n Returns:\n Headers dictionary with server-specific headers\n \"\"\"\n # Start with default MCP headers (required by some servers like Cloudflare)\n headers = {\"Accept\": \"application/json, text/event-stream\", \"Content-Type\": \"application/json\"}\n\n # Merge server-specific headers if present\n logger.info(\n f\"[AUTH DEBUG] _build_headers_for_server called, server_info is None: {server_info is None}\"\n )\n if server_info:\n logger.info(f\"[AUTH DEBUG] server_info keys: {list(server_info.keys())}\")\n server_headers = server_info.get(\"headers\", [])\n if server_headers and isinstance(server_headers, list):\n for header_dict in server_headers:\n if isinstance(header_dict, dict):\n headers.update(header_dict)\n logger.debug(f\"Added server headers to MCP client: {header_dict}\")\n\n # Inject auth header from encrypted credentials (if present)\n auth_scheme = server_info.get(\"auth_scheme\", \"none\")\n encrypted_credential = server_info.get(\"auth_credential_encrypted\")\n\n logger.debug(\n f\"[AUTH DEBUG] auth_scheme: {auth_scheme}, has_credential: {bool(encrypted_credential)}\"\n )\n\n if auth_scheme != \"none\" and encrypted_credential:\n from ..utils.credential_encryption import decrypt_credential\n\n credential = decrypt_credential(encrypted_credential)\n if credential:\n if auth_scheme == \"bearer\":\n header_name = server_info.get(\"auth_header_name\", \"Authorization\")\n headers[header_name] = f\"Bearer {credential}\"\n logger.debug(\"Added Bearer auth header for MCP client\")\n elif auth_scheme == \"api_key\":\n header_name = server_info.get(\"auth_header_name\", \"X-API-Key\")\n headers[header_name] = credential\n logger.debug(f\"Added API key header '{header_name}' for MCP client\")\n else:\n logger.warning(\n f\"Could not decrypt credential for \"\n f\"'{server_info.get('service_path', 'unknown')}'. \"\n f\"MCP client will proceed without auth.\"\n )\n\n return headers\n\n\ndef normalize_sse_endpoint_url_for_request(url_str: str) -> str:\n \"\"\"\n Normalize URLs in HTTP requests by removing mount paths.\n Example: http://localhost:8000/currenttime/messages/... -> http://localhost:8000/messages/...\n \"\"\"\n if \"/messages/\" not in url_str:\n return url_str\n\n # Pattern to match URLs like http://host:port/mount_path/messages/...\n import re\n\n pattern = r\"(https?://[^/]+)/([^/]+)(/messages/.*)\"\n match = re.match(pattern, url_str)\n\n if match:\n base_url = match.group(1) # http://host:port\n mount_path = match.group(2) # currenttime, fininfo, etc.\n messages_path = match.group(3) # /messages/...\n\n # Skip common paths that aren't mount paths\n if mount_path in [\"api\", \"static\", \"health\"]:\n return url_str\n\n normalized = f\"{base_url}{messages_path}\"\n logger.debug(f\"Normalized request URL: {url_str} -> {normalized}\")\n return normalized\n\n return url_str\n\n\nasync def detect_server_transport_aware(base_url: str, server_info: dict = None) -> str:\n \"\"\"\n Detect which transport a server supports by checking configuration and testing endpoints.\n Uses server_info supported_transports if available, otherwise falls back to auto-detection.\n\n Args:\n base_url: The base URL of the MCP server\n server_info: Optional server configuration dict containing supported_transports\n\n Returns:\n The preferred transport type (\"sse\" or \"streamable-http\")\n \"\"\"\n # If URL already has a transport endpoint, detect from it\n if base_url.endswith(\"/sse\") or \"/sse/\" in base_url:\n logger.debug(f\"Server URL {base_url} already has SSE endpoint\")\n return \"sse\"\n elif base_url.endswith(\"/mcp\") or \"/mcp/\" in base_url:\n logger.debug(f\"Server URL {base_url} already has MCP endpoint\")\n return \"streamable-http\"\n\n # Use server configuration if available\n if server_info:\n supported_transports = server_info.get(\"supported_transports\", [])\n logger.debug(f\"Server configuration specifies supported transports: {supported_transports}\")\n\n # Prefer SSE if it's the only option or explicitly listed first\n if supported_transports == [\"sse\"]:\n logger.debug(\"Server only supports SSE transport\")\n return \"sse\"\n elif (\n supported_transports\n and \"sse\" in supported_transports\n and \"streamable-http\" not in supported_transports\n ):\n logger.debug(\"Server supports SSE but not streamable-http\")\n return \"sse\"\n elif supported_transports and \"streamable-http\" in supported_transports:\n logger.debug(\"Server supports streamable-http (preferred)\")\n return \"streamable-http\"\n\n # Fall back to auto-detection\n return await detect_server_transport(base_url)\n\n\nasync def detect_server_transport(base_url: str) -> str:\n \"\"\"\n Detect which transport a server supports by testing endpoints.\n Returns the preferred transport type.\n \"\"\"\n # If URL already has a transport endpoint, detect from it\n if base_url.endswith(\"/sse\") or \"/sse/\" in base_url:\n logger.debug(f\"Server URL {base_url} already has SSE endpoint\")\n return \"sse\"\n elif base_url.endswith(\"/mcp\") or \"/mcp/\" in base_url:\n logger.debug(f\"Server URL {base_url} already has MCP endpoint\")\n return \"streamable-http\"\n\n # Test streamable-http first (default preference)\n try:\n mcp_url = base_url.rstrip(\"/\") + \"/mcp/\"\n async with streamablehttp_client(url=mcp_url) as connection:\n logger.debug(f\"Server at {base_url} supports streamable-http transport\")\n return \"streamable-http\"\n except Exception as e:\n logger.debug(f\"Streamable-HTTP test failed for {base_url}: {e}\")\n\n # Fallback to SSE\n try:\n sse_url = base_url.rstrip(\"/\") + \"/sse\"\n async with sse_client(sse_url) as connection:\n logger.debug(f\"Server at {base_url} supports SSE transport\")\n return \"sse\"\n except Exception as e:\n logger.debug(f\"SSE test failed for {base_url}: {e}\")\n\n # Default to streamable-http if detection fails\n logger.warning(f\"Could not detect transport for {base_url}, defaulting to streamable-http\")\n return \"streamable-http\"\n\n\nasync def get_tools_from_server_with_transport(\n base_url: str, transport: str = \"auto\"\n) -> list[dict] | None:\n \"\"\"\n Connects to an MCP server using the specified transport, lists tools, and returns their details.\n\n Args:\n base_url: The base URL of the MCP server (e.g., http://localhost:8000).\n transport: Transport type (\"streamable-http\", \"sse\", or \"auto\")\n\n Returns:\n A list of tool detail dictionaries, or None if connection/retrieval fails.\n \"\"\"\n if not base_url:\n logger.error(\"MCP Check Error: Base URL is empty.\")\n return None\n\n # Auto-detect transport if needed\n if transport == \"auto\":\n transport = await detect_server_transport(base_url)\n\n logger.info(f\"Attempting to connect to MCP server at {base_url} using {transport} transport...\")\n\n try:\n if transport == \"streamable-http\":\n return await _get_tools_streamable_http(base_url)\n elif transport == \"sse\":\n return await _get_tools_sse(base_url)\n else:\n logger.error(f\"Unsupported transport type: {transport}\")\n return None\n\n except Exception as e:\n logger.error(\n f\"MCP Check Error: Failed to get tool list from {base_url} with {transport}: {type(e).__name__} - {e}\"\n )\n return None\n\n\nasync def _get_tools_streamable_http(base_url: str, server_info: dict = None) -> list[dict] | None:\n \"\"\"Get tools using streamable-http transport\"\"\"\n # Build headers for the server\n headers = _build_headers_for_server(server_info)\n\n # Check if server_info has explicit mcp_endpoint\n explicit_endpoint = server_info.get(\"mcp_endpoint\") if server_info else None\n\n # If explicit endpoint is provided, use it directly (single attempt)\n if explicit_endpoint:\n mcp_url = explicit_endpoint\n logger.info(f\"MCP Client: Using explicit mcp_endpoint: {mcp_url}\")\n\n # Handle servers imported from anthropic by adding required query parameter\n if (\n server_info\n and \"tags\" in server_info\n and \"anthropic-registry\" in server_info.get(\"tags\", [])\n ):\n if \"?\" not in mcp_url:\n mcp_url += \"?instance_id=default\"\n elif \"instance_id=\" not in mcp_url:\n mcp_url += \"&instance_id=default\"\n\n try:\n async with streamablehttp_client(url=mcp_url, headers=headers) as (\n read,\n write,\n get_session_id,\n ):\n async with ClientSession(read, write) as session:\n await asyncio.wait_for(session.initialize(), timeout=10.0)\n tools_response = await asyncio.wait_for(session.list_tools(), timeout=15.0)\n result = _extract_tool_details(tools_response)\n return result\n except Exception as e:\n logger.error(f\"MCP Check Error: Streamable-HTTP connection failed to {mcp_url}: {e}\")\n return None\n\n # If URL already has MCP endpoint, use it directly\n if base_url.endswith(\"/mcp\") or \"/mcp/\" in base_url:\n mcp_url = base_url\n # Don't add trailing slash - some servers like Cloudflare reject it\n\n # Handle streamable-http and sse servers imported from anthropic by adding required query parameter\n if (\n server_info\n and \"tags\" in server_info\n and \"anthropic-registry\" in server_info.get(\"tags\", [])\n ):\n if \"?\" not in mcp_url:\n mcp_url += \"?instance_id=default\"\n elif \"instance_id=\" not in mcp_url:\n mcp_url += \"&instance_id=default\"\n else:\n logger.info(f\"DEBUG: Not a Strata server, URL unchanged: {mcp_url}\")\n\n logger.info(f\"DEBUG: About to connect to: {mcp_url}\")\n try:\n async with streamablehttp_client(url=mcp_url, headers=headers) as (\n read,\n write,\n get_session_id,\n ):\n async with ClientSession(read, write) as session:\n await asyncio.wait_for(session.initialize(), timeout=10.0)\n tools_response = await asyncio.wait_for(session.list_tools(), timeout=15.0)\n\n result = _extract_tool_details(tools_response)\n return result\n except Exception as e:\n logger.error(f\"MCP Check Error: Streamable-HTTP connection failed to {base_url}: {e}\")\n\n return None\n else:\n # Try with /mcp suffix first, then without if it fails\n endpoints_to_try = [base_url.rstrip(\"/\") + \"/mcp/\", base_url.rstrip(\"/\") + \"/\"]\n\n for mcp_url in endpoints_to_try:\n try:\n logger.info(f\"MCP Client: Trying streamable-http endpoint: {mcp_url}\")\n async with streamablehttp_client(url=mcp_url, headers=headers) as (\n read,\n write,\n get_session_id,\n ):\n async with ClientSession(read, write) as session:\n await asyncio.wait_for(session.initialize(), timeout=10.0)\n tools_response = await asyncio.wait_for(session.list_tools(), timeout=15.0)\n\n logger.info(f\"MCP Client: Successfully connected to {mcp_url}\")\n return _extract_tool_details(tools_response)\n\n except TimeoutError:\n logger.error(\n f\"MCP Check Error: Timeout during streamable-http session with {mcp_url}.\"\n )\n if mcp_url == endpoints_to_try[0]:\n continue\n return None\n except Exception as e:\n logger.error(\n f\"MCP Check Error: Streamable-HTTP connection failed to {mcp_url}: {e}\"\n )\n if mcp_url == endpoints_to_try[0]:\n continue\n return None\n\n return None\n\n\nasync def _get_tools_sse(base_url: str, server_info: dict = None) -> list[dict] | None:\n \"\"\"Get tools using SSE transport (legacy method with patches)\"\"\"\n # Check if server_info has explicit sse_endpoint\n explicit_endpoint = server_info.get(\"sse_endpoint\") if server_info else None\n\n # Resolve SSE endpoint URL\n if explicit_endpoint:\n sse_url = explicit_endpoint\n logger.info(f\"MCP Client: Using explicit sse_endpoint: {sse_url}\")\n elif base_url.endswith(\"/sse\") or \"/sse/\" in base_url:\n sse_url = base_url\n else:\n sse_url = base_url.rstrip(\"/\") + \"/sse\"\n\n secure_prefix = \"s\" if sse_url.startswith(\"https://\") else \"\"\n mcp_server_url = f\"http{secure_prefix}://{sse_url[len(f'http{secure_prefix}://') :]}\"\n\n # Build headers for the server\n headers = _build_headers_for_server(server_info)\n\n try:\n # Monkey patch httpx to fix mount path issues (legacy SSE support)\n original_request = httpx.AsyncClient.request\n\n async def patched_request(self, method, url, **kwargs):\n if isinstance(url, str) and \"/messages/\" in url:\n url = normalize_sse_endpoint_url_for_request(url)\n elif hasattr(url, \"__str__\") and \"/messages/\" in str(url):\n url = normalize_sse_endpoint_url_for_request(str(url))\n return await original_request(self, method, url, **kwargs)\n\n httpx.AsyncClient.request = patched_request\n\n try:\n async with sse_client(mcp_server_url, headers=headers) as (read, write):\n async with ClientSession(read, write, sampling_callback=None) as session:\n await asyncio.wait_for(session.initialize(), timeout=10.0)\n tools_response = await asyncio.wait_for(session.list_tools(), timeout=15.0)\n\n return _extract_tool_details(tools_response)\n finally:\n httpx.AsyncClient.request = original_request\n\n except TimeoutError:\n logger.error(f\"MCP Check Error: Timeout during SSE session with {base_url}.\")\n return None\n except Exception as e:\n logger.error(f\"MCP Check Error: SSE connection failed to {base_url}: {e}\")\n return None\n\n\ndef _extract_tool_details(tools_response) -> list[dict]:\n \"\"\"Extract tool details from MCP tools response.\"\"\"\n tool_details_list = []\n\n if tools_response and hasattr(tools_response, \"tools\"):\n for tool in tools_response.tools:\n tool_name = getattr(tool, \"name\", \"Unknown Name\")\n tool_desc = getattr(tool, \"description\", None) or getattr(tool, \"__doc__\", None)\n\n # Log tool description for debugging\n desc_preview = repr(tool_desc)[:100] if tool_desc else \"None\"\n logger.debug(f\"Tool '{tool_name}' description: {desc_preview}\")\n\n # Parse docstring into sections\n parsed_desc = {\n \"main\": \"No description available.\",\n \"args\": None,\n \"returns\": None,\n \"raises\": None,\n }\n if tool_desc:\n tool_desc = tool_desc.strip()\n lines = tool_desc.split(\"\\n\")\n main_desc_lines = []\n current_section = \"main\"\n section_content = []\n\n for line in lines:\n stripped_line = line.strip()\n if stripped_line.startswith(\"Args:\"):\n parsed_desc[\"main\"] = \"\\n\".join(main_desc_lines).strip()\n current_section = \"args\"\n section_content = [stripped_line[len(\"Args:\") :].strip()]\n elif stripped_line.startswith(\"Returns:\"):\n if current_section != \"main\":\n parsed_desc[current_section] = \"\\n\".join(section_content).strip()\n else:\n parsed_desc[\"main\"] = \"\\n\".join(main_desc_lines).strip()\n current_section = \"returns\"\n section_content = [stripped_line[len(\"Returns:\") :].strip()]\n elif stripped_line.startswith(\"Raises:\"):\n if current_section != \"main\":\n parsed_desc[current_section] = \"\\n\".join(section_content).strip()\n else:\n parsed_desc[\"main\"] = \"\\n\".join(main_desc_lines).strip()\n current_section = \"raises\"\n section_content = [stripped_line[len(\"Raises:\") :].strip()]\n elif current_section == \"main\":\n main_desc_lines.append(line.strip())\n else:\n section_content.append(line.strip())\n\n # Add the last collected section\n if current_section != \"main\":\n parsed_desc[current_section] = \"\\n\".join(section_content).strip()\n elif not parsed_desc[\"main\"] and main_desc_lines:\n parsed_desc[\"main\"] = \"\\n\".join(main_desc_lines).strip()\n\n # Ensure main description has content\n if not parsed_desc[\"main\"] and (\n parsed_desc[\"args\"] or parsed_desc[\"returns\"] or parsed_desc[\"raises\"]\n ):\n parsed_desc[\"main\"] = \"(No primary description provided)\"\n else:\n parsed_desc[\"main\"] = \"No description available.\"\n\n tool_schema = getattr(tool, \"inputSchema\", {})\n\n tool_details_list.append(\n {\n \"name\": tool_name,\n \"description\": tool_desc or \"\",\n \"parsed_description\": parsed_desc,\n \"schema\": tool_schema,\n }\n )\n\n tool_names = [tool[\"name\"] for tool in tool_details_list]\n logger.info(\n f\"Successfully retrieved details for {len(tool_details_list)} tools: {', '.join(tool_names)}\"\n )\n return tool_details_list\n\n\nasync def get_tools_from_server_with_server_info(\n base_url: str, server_info: dict = None\n) -> list[dict] | None:\n \"\"\"\n Get tools from server using server configuration to determine optimal transport.\n\n Args:\n base_url: The base URL of the MCP server (e.g., http://localhost:8000).\n server_info: Optional server configuration dict containing supported_transports\n\n Returns:\n A list of tool detail dictionaries (keys: name, description, schema),\n or None if connection/retrieval fails.\n \"\"\"\n\n if not base_url:\n logger.error(\"MCP Check Error: Base URL is empty.\")\n return None\n\n # Use transport-aware detection\n transport = await detect_server_transport_aware(base_url, server_info)\n\n logger.info(\n f\"Attempting to connect to MCP server at {base_url} using {transport} transport (server-info aware)...\"\n )\n\n try:\n if transport == \"streamable-http\":\n return await _get_tools_streamable_http(base_url, server_info)\n elif transport == \"sse\":\n return await _get_tools_sse(base_url, server_info)\n else:\n logger.error(f\"Unsupported transport type: {transport}\")\n return None\n\n except Exception as e:\n logger.error(\n f\"MCP Check Error: Failed to get tool list from {base_url} with {transport}: {type(e).__name__} - {e}\"\n )\n return None\n\n\nasync def get_mcp_connection_result(\n base_url: str, server_info: dict = None\n) -> MCPConnectionResult | None:\n \"\"\"\n Connect to MCP server and return both tools and server info.\n\n This function performs the MCP initialize handshake and extracts\n the serverInfo (name, version) from the response along with tools.\n\n Args:\n base_url: The base URL of the MCP server\n server_info: Optional server configuration dict\n\n Returns:\n MCPConnectionResult with tools and server_info, or None on failure\n \"\"\"\n if not base_url:\n logger.error(\"MCP Check Error: Base URL is empty.\")\n return None\n\n # Use transport-aware detection\n transport = await detect_server_transport_aware(base_url, server_info)\n\n logger.info(f\"Getting MCP connection result from {base_url} using {transport} transport...\")\n\n # Build headers for the server\n headers = _build_headers_for_server(server_info)\n\n # Determine the MCP endpoint URL\n explicit_endpoint = server_info.get(\"mcp_endpoint\") if server_info else None\n\n if explicit_endpoint:\n mcp_url = explicit_endpoint\n elif base_url.endswith(\"/mcp\") or \"/mcp/\" in base_url:\n mcp_url = base_url\n else:\n mcp_url = base_url.rstrip(\"/\") + \"/mcp/\"\n\n # Handle anthropic-registry servers\n if (\n server_info\n and \"tags\" in server_info\n and \"anthropic-registry\" in server_info.get(\"tags\", [])\n ):\n if \"?\" not in mcp_url:\n mcp_url += \"?instance_id=default\"\n elif \"instance_id=\" not in mcp_url:\n mcp_url += \"&instance_id=default\"\n\n try:\n if transport == \"streamable-http\":\n async with streamablehttp_client(url=mcp_url, headers=headers) as (\n read,\n write,\n get_session_id,\n ):\n async with ClientSession(read, write) as session:\n # Capture the initialize result which contains serverInfo\n init_result = await asyncio.wait_for(session.initialize(), timeout=10.0)\n tools_response = await asyncio.wait_for(session.list_tools(), timeout=15.0)\n\n tools = _extract_tool_details(tools_response)\n\n # Extract server info from initialize result\n mcp_server_info: MCPServerInfo = {}\n if (\n init_result\n and hasattr(init_result, \"serverInfo\")\n and init_result.serverInfo\n ):\n if hasattr(init_result.serverInfo, \"name\"):\n mcp_server_info[\"name\"] = init_result.serverInfo.name\n if hasattr(init_result.serverInfo, \"version\"):\n mcp_server_info[\"version\"] = init_result.serverInfo.version\n\n if mcp_server_info:\n logger.info(\n f\"MCP Server Info from {base_url}: \"\n f\"name={mcp_server_info.get('name')}, \"\n f\"version={mcp_server_info.get('version')}\"\n )\n\n return MCPConnectionResult(tools=tools or [], server_info=mcp_server_info)\n\n elif transport == \"sse\":\n # For SSE transport\n sse_endpoint = server_info.get(\"sse_endpoint\") if server_info else None\n if sse_endpoint:\n sse_url = sse_endpoint\n else:\n sse_url = base_url.rstrip(\"/\") + \"/sse\"\n\n async with sse_client(url=sse_url, headers=headers) as (read, write):\n async with ClientSession(read, write) as session:\n # Capture the initialize result which contains serverInfo\n init_result = await asyncio.wait_for(session.initialize(), timeout=10.0)\n tools_response = await asyncio.wait_for(session.list_tools(), timeout=15.0)\n\n tools = _extract_tool_details(tools_response)\n\n # Extract server info from initialize result\n mcp_server_info: MCPServerInfo = {}\n if (\n init_result\n and hasattr(init_result, \"serverInfo\")\n and init_result.serverInfo\n ):\n if hasattr(init_result.serverInfo, \"name\"):\n mcp_server_info[\"name\"] = init_result.serverInfo.name\n if hasattr(init_result.serverInfo, \"version\"):\n mcp_server_info[\"version\"] = init_result.serverInfo.version\n\n if mcp_server_info:\n logger.info(\n f\"MCP Server Info from {base_url}: \"\n f\"name={mcp_server_info.get('name')}, \"\n f\"version={mcp_server_info.get('version')}\"\n )\n\n return MCPConnectionResult(tools=tools or [], server_info=mcp_server_info)\n\n else:\n logger.error(f\"Unsupported transport type: {transport}\")\n return None\n\n except TimeoutError:\n logger.error(f\"MCP Check Error: Timeout connecting to {mcp_url}\")\n return None\n except Exception as e:\n logger.error(\n f\"MCP Check Error: Failed to get connection result from {base_url}: \"\n f\"{type(e).__name__} - {e}\"\n )\n return None\n\n\nclass MCPClientService:\n \"\"\"Service wrapper for the MCP client function to maintain compatibility.\"\"\"\n\n async def get_tools_from_server_with_server_info(\n self, base_url: str, server_info: dict = None\n ) -> list[dict] | None:\n \"\"\"Wrapper method that uses server configuration for transport selection.\"\"\"\n return await get_tools_from_server_with_server_info(base_url, server_info)\n\n async def get_mcp_connection_result(\n self, base_url: str, server_info: dict = None\n ) -> MCPConnectionResult | None:\n \"\"\"Get both tools and server info from MCP server.\"\"\"\n return await get_mcp_connection_result(base_url, server_info)\n\n\n# Global MCP client service instance\nmcp_client_service = MCPClientService()\n" }, { "path": "registry/core/metrics.py", "content": "\"\"\"Prometheus metrics for deployment mode monitoring.\"\"\"\n\nfrom prometheus_client import Counter, Gauge\n\n# Configuration viewer metrics\nCONFIG_VIEW_REQUESTS = Counter(\n \"mcp_config_view_requests_total\",\n \"Total configuration view requests\",\n [\"user_type\"],\n)\n\nCONFIG_EXPORT_REQUESTS = Counter(\n \"mcp_config_export_requests_total\",\n \"Total configuration export requests\",\n [\"format\", \"includes_sensitive\"],\n)\n\n# Deployment mode info gauge\nDEPLOYMENT_MODE_INFO = Gauge(\n \"registry_deployment_mode_info\",\n \"Current deployment mode configuration\",\n [\"deployment_mode\", \"registry_mode\"],\n)\n\n# Counter for skipped nginx updates\nNGINX_UPDATES_SKIPPED = Counter(\n \"registry_nginx_updates_skipped_total\",\n \"Number of nginx updates skipped due to registry-only mode\",\n [\"operation\"], # generate_config, reload\n)\n\n# Counter for blocked requests due to registry mode\nMODE_BLOCKED_REQUESTS = Counter(\n \"registry_mode_blocked_requests_total\",\n \"Requests blocked due to registry mode restrictions\",\n [\"path_category\", \"mode\"], # servers, agents, skills, federation\n)\n\n# Peer federation metrics (issue #561)\nPEER_SYNC_FAILURES = Counter(\n \"peer_sync_failures_total\",\n \"Total peer sync failures by failure type\",\n [\"peer_id\", \"failure_type\"], # auth_error, network_error, etc.\n)\n\nPEER_TOKEN_MISSING = Gauge(\n \"peer_token_missing_total\",\n \"Number of peers missing federation tokens\",\n)\n\nPEER_SYNC_DURATION_SECONDS = Gauge(\n \"peer_sync_duration_seconds\", \"Duration of peer sync operations\", [\"peer_id\", \"success\"]\n)\n\n# Application log handler metrics (issue #886)\nAPP_LOG_FLUSH_FAILURES = Counter(\n \"app_log_mongodb_flush_failures_total\",\n \"Total MongoDB log handler flush failures\",\n [\"service\"],\n)\n\n# Telemetry metrics (issue #558)\ntelemetry_sends_total = Counter(\n \"telemetry_sends_total\",\n \"Total telemetry events sent\",\n [\"event\", \"status\"], # event: startup/heartbeat, status: success/timeout/error/2xx/4xx/5xx\n)\n" }, { "path": "registry/core/nginx_service.py", "content": "import asyncio\nimport json\nimport logging\nimport os\nimport re\nfrom pathlib import Path\nfrom typing import Any\nfrom urllib.parse import urlparse\n\nimport httpx\n\nfrom registry.constants import REGISTRY_CONSTANTS, HealthStatus\n\nfrom .config import settings\nfrom .metrics import NGINX_UPDATES_SKIPPED\n\nlogger = logging.getLogger(__name__)\n\n\ndef _ensure_mcp_compliant_schema(input_schema: dict[str, Any]) -> dict[str, Any]:\n \"\"\"Ensure inputSchema conforms to MCP spec by adding 'type': 'object' if missing.\n\n The MCP spec requires all tool inputSchema definitions to have \"type\": \"object\"\n at the top level. This function ensures backend tool schemas are compliant.\n\n Args:\n input_schema: The input schema from a backend tool\n\n Returns:\n MCP-compliant schema with \"type\": \"object\" at top level\n \"\"\"\n if not input_schema:\n return {\"type\": \"object\", \"properties\": {}}\n\n # If schema already has \"type\": \"object\", return as-is\n if input_schema.get(\"type\") == \"object\":\n return input_schema\n\n # If schema has \"type\" but it's not \"object\", wrap it\n if \"type\" in input_schema:\n logger.warning(\n f\"Tool inputSchema has non-object type '{input_schema.get('type')}'. \"\n \"Wrapping in object schema to comply with MCP spec.\"\n )\n return {\"type\": \"object\", \"properties\": {\"value\": input_schema}}\n\n # If no \"type\" field but has \"properties\", add \"type\": \"object\"\n if \"properties\" in input_schema or \"additionalProperties\" in input_schema:\n schema_copy = input_schema.copy()\n schema_copy[\"type\"] = \"object\"\n return schema_copy\n\n # Default: wrap unknown schema structure\n logger.warning(\n \"Tool inputSchema missing 'type' field and has unexpected structure. \"\n \"Adding 'type': 'object' to comply with MCP spec.\"\n )\n schema_copy = input_schema.copy()\n schema_copy[\"type\"] = \"object\"\n return schema_copy\n\n\nclass NginxConfigService:\n \"\"\"Service for generating Nginx configuration for registered servers.\"\"\"\n\n def __init__(self):\n # Determine which template to use based on SSL certificate availability\n ssl_cert_path = Path(REGISTRY_CONSTANTS.SSL_CERT_PATH)\n ssl_key_path = Path(REGISTRY_CONSTANTS.SSL_KEY_PATH)\n\n # Check if SSL certificates exist\n if ssl_cert_path.exists() and ssl_key_path.exists():\n # Use HTTP + HTTPS template\n if Path(REGISTRY_CONSTANTS.NGINX_TEMPLATE_HTTP_AND_HTTPS).exists():\n self.nginx_template_path = Path(REGISTRY_CONSTANTS.NGINX_TEMPLATE_HTTP_AND_HTTPS)\n else:\n # Fallback for local development\n self.nginx_template_path = Path(\n REGISTRY_CONSTANTS.NGINX_TEMPLATE_HTTP_AND_HTTPS_LOCAL\n )\n else:\n # Use HTTP-only template\n if Path(REGISTRY_CONSTANTS.NGINX_TEMPLATE_HTTP_ONLY).exists():\n self.nginx_template_path = Path(REGISTRY_CONSTANTS.NGINX_TEMPLATE_HTTP_ONLY)\n else:\n # Fallback for local development\n self.nginx_template_path = Path(REGISTRY_CONSTANTS.NGINX_TEMPLATE_HTTP_ONLY_LOCAL)\n\n async def get_additional_server_names(self) -> str:\n \"\"\"Fetch or determine additional server names for nginx gateway configuration.\n\n Supports multi-platform detection:\n 1. User-provided GATEWAY_ADDITIONAL_SERVER_NAMES env var\n 2. EC2 private IP detection via metadata service\n 3. ECS metadata service detection\n 4. EKS/Kubernetes pod detection\n 5. Generic hostname command fallback\n 6. Backward compatibility with EC2_PUBLIC_DNS env var\n \"\"\"\n import os\n import subprocess # nosec B404\n\n # Priority 1: Check GATEWAY_ADDITIONAL_SERVER_NAMES env var (user-provided)\n gateway_names = os.environ.get(\"GATEWAY_ADDITIONAL_SERVER_NAMES\", \"\")\n if gateway_names:\n logger.info(f\"Using GATEWAY_ADDITIONAL_SERVER_NAMES from environment: {gateway_names}\")\n return gateway_names.strip()\n\n # Priority 2: Try EC2 metadata service for private IP\n try:\n async with httpx.AsyncClient() as client:\n # Get session token for IMDSv2\n token_response = await client.put(\n \"http://169.254.169.254/latest/api/token\",\n headers={\"X-aws-ec2-metadata-token-ttl-seconds\": \"21600\"},\n timeout=2.0,\n )\n\n if token_response.status_code == 200:\n token = token_response.text\n\n # Try to get private IP from EC2 metadata\n ip_response = await client.get(\n \"http://169.254.169.254/latest/meta-data/local-ipv4\",\n headers={\"X-aws-ec2-metadata-token\": token},\n timeout=2.0,\n )\n\n if ip_response.status_code == 200:\n private_ip = ip_response.text.strip()\n logger.info(f\"Auto-detected EC2 private IP: {private_ip}\")\n return private_ip\n\n except (httpx.TimeoutException, httpx.ConnectError):\n logger.debug(\"EC2 metadata service not available - not running on EC2\")\n except Exception as e:\n logger.debug(f\"EC2 metadata detection failed: {e}\")\n\n # Priority 3: Try ECS metadata service\n ecs_uri = os.environ.get(\"ECS_CONTAINER_METADATA_URI\") or os.environ.get(\n \"ECS_CONTAINER_METADATA_URI_V4\"\n )\n if ecs_uri:\n try:\n async with httpx.AsyncClient() as client:\n metadata_response = await client.get(f\"{ecs_uri}\", timeout=2.0)\n if metadata_response.status_code == 200:\n import json\n\n metadata = json.loads(metadata_response.text)\n # Try to extract IP from ECS metadata\n if \"Networks\" in metadata and metadata[\"Networks\"]:\n private_ip = metadata[\"Networks\"][0].get(\"IPv4Addresses\", [None])[0]\n if private_ip:\n logger.info(f\"Auto-detected ECS container IP: {private_ip}\")\n return private_ip\n except Exception as e:\n logger.debug(f\"ECS metadata detection failed: {e}\")\n\n # Priority 4: Try EKS/Kubernetes detection\n pod_ip = os.environ.get(\"POD_IP\")\n if pod_ip:\n logger.info(f\"Auto-detected Kubernetes pod IP: {pod_ip}\")\n return pod_ip\n\n # Priority 5: Try generic hostname command (works on most Linux systems)\n try:\n result = subprocess.run([\"hostname\", \"-I\"], capture_output=True, text=True, timeout=2.0) # nosec B603 B607 - hardcoded command\n if result.returncode == 0:\n ips = result.stdout.strip().split()\n if ips:\n # Use first IP (usually the private IP on single-interface systems)\n private_ip = ips[0]\n logger.info(f\"Auto-detected private IP via hostname command: {private_ip}\")\n return private_ip\n except Exception as e:\n logger.debug(f\"Generic hostname detection failed: {e}\")\n\n # Priority 6: Backward compatibility with old EC2_PUBLIC_DNS env var\n fallback_dns = os.environ.get(\"EC2_PUBLIC_DNS\", \"\")\n if fallback_dns:\n logger.info(f\"Using EC2_PUBLIC_DNS environment variable (deprecated): {fallback_dns}\")\n return fallback_dns\n\n # No additional server names available\n logger.info(\n \"No additional server names available - will use only localhost and mcpgateway.ddns.net\"\n )\n return \"\"\n\n def generate_config(self, servers: dict[str, dict[str, Any]]) -> bool:\n \"\"\"Generate Nginx configuration (synchronous version for non-async contexts).\"\"\"\n if not settings.nginx_updates_enabled:\n logger.info(\n f\"Skipping nginx config generation - \"\n f\"DEPLOYMENT_MODE={settings.deployment_mode.value}\"\n )\n NGINX_UPDATES_SKIPPED.labels(operation=\"generate_config\").inc()\n return True\n\n try:\n # Check if we're in an async context\n try:\n # If we're already in an event loop, we need to run this differently\n loop = asyncio.get_running_loop()\n # We're in an async context, this won't work\n logger.error(\n \"generate_config called from async context - use generate_config_async instead\"\n )\n return False\n except RuntimeError:\n # No running loop, we can use asyncio.run()\n return asyncio.run(self.generate_config_async(servers))\n except Exception as e:\n logger.error(f\"Failed to generate Nginx configuration: {e}\", exc_info=True)\n return False\n\n async def generate_config_async(\n self, servers: dict[str, dict[str, Any]], force_base_config: bool = False\n ) -> bool:\n \"\"\"Generate Nginx configuration with additional server names and dynamic location blocks.\n\n Args:\n servers: Dictionary of server path -> server info for location blocks\n force_base_config: If True, generate base config even in registry-only mode\n (used at startup to ensure nginx has valid config)\n\n In registry-only mode:\n - At startup (force_base_config=True): generates base config with empty location blocks\n - On server changes (force_base_config=False): skips regeneration (no-op)\n \"\"\"\n if not settings.nginx_updates_enabled and not force_base_config:\n logger.info(\n f\"Skipping nginx config generation - \"\n f\"DEPLOYMENT_MODE={settings.deployment_mode.value}\"\n )\n NGINX_UPDATES_SKIPPED.labels(operation=\"generate_config\").inc()\n return True\n\n try:\n # Read template\n if not self.nginx_template_path.exists():\n logger.warning(f\"Nginx template not found at {self.nginx_template_path}\")\n return False\n\n with open(self.nginx_template_path) as f:\n template_content = f.read()\n\n # Local-dev / Podman compatibility:\n # The default nginx templates protect `/api/` via `auth_request /validate` (JWT validation).\n # The React dashboard, however, uses cookie-based session auth for `/api/servers` and\n # `/api/tokens/generate`. When auth_request is enabled but Keycloak/Cognito isn't fully\n # configured, nginx returns 403/500 and the UI cannot load.\n #\n # Set NGINX_DISABLE_API_AUTH_REQUEST=true to bypass `auth_request` for `/api/` and rely\n # on FastAPI's own auth (session cookie or bearer token validation inside the app).\n import os\n\n if os.environ.get(\"NGINX_DISABLE_API_AUTH_REQUEST\", \"false\").lower() in (\n \"1\",\n \"true\",\n \"yes\",\n \"on\",\n ):\n protected_api_block = \"\"\" # Protected API endpoints - require authentication\n location {{ROOT_PATH}}/api/ {\n # Authenticate request via auth server (validates JWT Bearer tokens)\n auth_request /validate;\n\n # Capture auth server response headers\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n\n # Forward validated auth context to FastAPI\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n\n # Pass through original Authorization header\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\"\"\"\n\n unprotected_api_block = \"\"\" # API endpoints - FastAPI handles authentication (session cookie / bearer)\n location {{ROOT_PATH}}/api/ {\n # Proxy to FastAPI service\n proxy_pass http://127.0.0.1:7860/api/;\n proxy_http_version 1.1;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n\n # Pass through original Authorization header (if present)\n proxy_set_header Authorization $http_authorization;\n\n # Pass all request headers and cookies\n proxy_pass_request_headers on;\n\n # Timeouts\n proxy_connect_timeout 10s;\n proxy_send_timeout 30s;\n proxy_read_timeout 30s;\n }\"\"\"\n\n if protected_api_block in template_content:\n template_content = template_content.replace(\n protected_api_block, unprotected_api_block\n )\n logger.warning(\n \"NGINX_DISABLE_API_AUTH_REQUEST enabled: bypassing auth_request for /api/\"\n )\n else:\n logger.warning(\n \"NGINX_DISABLE_API_AUTH_REQUEST enabled but could not find /api/ auth_request block in template\"\n )\n\n # Generate location blocks for enabled and healthy servers with transport support\n # In registry-only mode, skip MCP server location blocks (use empty list)\n location_blocks = []\n if settings.nginx_updates_enabled:\n # Get health service to check server health\n from ..health.service import health_service\n\n for path, server_info in servers.items():\n proxy_pass_url = server_info.get(\"proxy_pass_url\")\n if proxy_pass_url:\n # Check if server is healthy (including auth-expired which is still reachable)\n health_status = health_service.server_health_status.get(\n path, HealthStatus.UNKNOWN\n )\n\n # Include servers that are healthy or just have expired auth (server is up)\n if HealthStatus.is_healthy(health_status):\n # Generate transport-aware location blocks\n transport_blocks = self._generate_transport_location_blocks(\n path, server_info\n )\n location_blocks.extend(transport_blocks)\n logger.debug(f\"Added location blocks for healthy service: {path}\")\n else:\n # Add commented out block for unhealthy services\n commented_block = f\"\"\"\n# location {{{{ROOT_PATH}}}}{path}/ {{\n# # Service currently unhealthy (status: {health_status})\n# # Proxy to MCP server\n# proxy_pass {proxy_pass_url};\n# proxy_http_version 1.1;\n# proxy_set_header Host $host;\n# proxy_set_header X-Real-IP $remote_addr;\n# proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n# proxy_set_header X-Forwarded-Proto $scheme;\n# }}\"\"\"\n location_blocks.append(commented_block)\n logger.debug(\n f\"Added commented location block for unhealthy service {path} (status: {health_status})\"\n )\n else:\n logger.info(\n \"Registry-only mode: generating base nginx config without MCP server location blocks\"\n )\n\n # Fetch additional server names (custom domains/IPs)\n additional_server_names = await self.get_additional_server_names()\n\n # Get API version from constants\n api_version = REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION\n\n # Parse Keycloak configuration from KEYCLOAK_URL environment variable\n import os\n\n auth_provider = os.environ.get(\"AUTH_PROVIDER\", \"keycloak\").lower()\n\n # Strip Keycloak location blocks from nginx config when not using Keycloak\n if auth_provider != \"keycloak\":\n template_content = re.sub(\n r\" # \\{\\{KEYCLOAK_LOCATIONS_START\\}\\}.*?# \\{\\{KEYCLOAK_LOCATIONS_END\\}\\}\\n?\",\n \"\",\n template_content,\n flags=re.DOTALL,\n )\n logger.info(\n f\"AUTH_PROVIDER is '{auth_provider}', removed Keycloak location blocks from nginx config\"\n )\n keycloak_scheme = \"http\"\n keycloak_host = \"keycloak\"\n keycloak_port = \"8080\"\n else:\n keycloak_url = os.environ.get(\"KEYCLOAK_URL\", \"http://keycloak:8080\")\n try:\n parsed_keycloak = urlparse(keycloak_url)\n keycloak_scheme = parsed_keycloak.scheme or \"http\"\n keycloak_host = parsed_keycloak.hostname or \"keycloak\"\n # Use default port based on scheme if not specified\n if parsed_keycloak.port:\n keycloak_port = str(parsed_keycloak.port)\n else:\n keycloak_port = \"443\" if keycloak_scheme == \"https\" else \"8080\"\n\n # Validate that we can actually resolve the hostname\n if not keycloak_host or keycloak_host == \"keycloak\":\n # If we end up with just 'keycloak', use the full URL's netloc instead\n keycloak_host = (\n parsed_keycloak.netloc.split(\":\")[0]\n if parsed_keycloak.netloc\n else \"keycloak\"\n )\n logger.warning(\n f\"Keycloak hostname is 'keycloak', using netloc instead: {keycloak_host}\"\n )\n\n logger.info(\n f\"Using Keycloak configuration from KEYCLOAK_URL '{keycloak_url}': \"\n f\"{keycloak_scheme}://{keycloak_host}:{keycloak_port}\"\n )\n except Exception as e:\n logger.warning(\n f\"Failed to parse KEYCLOAK_URL '{keycloak_url}': {e}. Using defaults.\"\n )\n keycloak_scheme = \"http\"\n keycloak_host = \"keycloak\"\n keycloak_port = \"8080\"\n\n # Generate version map for multi-version servers\n # In registry-only mode, skip version map generation (use empty string)\n if settings.nginx_updates_enabled:\n version_map = await self._generate_version_map(servers)\n else:\n version_map = \"\"\n\n # Replace placeholders in template\n config_content = template_content.replace(\"{{VERSION_MAP}}\", version_map)\n config_content = config_content.replace(\n \"{{LOCATION_BLOCKS}}\", \"\\n\".join(location_blocks)\n )\n config_content = config_content.replace(\n \"{{ADDITIONAL_SERVER_NAMES}}\", additional_server_names\n )\n config_content = config_content.replace(\"{{ANTHROPIC_API_VERSION}}\", api_version)\n config_content = config_content.replace(\"{{KEYCLOAK_SCHEME}}\", keycloak_scheme)\n config_content = config_content.replace(\"{{KEYCLOAK_HOST}}\", keycloak_host)\n config_content = config_content.replace(\"{{KEYCLOAK_PORT}}\", keycloak_port)\n\n # Generate registry-only block (503 response for MCP proxy requests)\n registry_only_block = self._generate_registry_only_block()\n config_content = config_content.replace(\"{{REGISTRY_ONLY_BLOCK}}\", registry_only_block)\n\n # Generate virtual server blocks\n try:\n virtual_server_locations = await self._generate_virtual_server_blocks()\n\n # Get the virtual servers list for backend locations and mappings\n from registry.repositories.factory import get_virtual_server_repository\n\n virtual_repo = get_virtual_server_repository()\n virtual_servers = await virtual_repo.list_enabled()\n\n virtual_backend_locations = await self._generate_virtual_backend_locations(\n virtual_servers\n )\n\n # Combine virtual server and backend location blocks\n virtual_blocks = virtual_server_locations\n if virtual_backend_locations:\n virtual_blocks = (\n virtual_blocks + \"\\n\" + virtual_backend_locations\n if virtual_blocks\n else virtual_backend_locations\n )\n\n config_content = config_content.replace(\"{{VIRTUAL_SERVER_BLOCKS}}\", virtual_blocks)\n\n # Write mapping JSON files for Lua router\n await self._write_virtual_server_mappings(virtual_servers)\n\n logger.info(\n f\"Generated virtual server config with {len(virtual_servers)} virtual servers\"\n )\n except Exception as e:\n logger.error(f\"Failed to generate virtual server config: {e}\", exc_info=True)\n config_content = config_content.replace(\"{{VIRTUAL_SERVER_BLOCKS}}\", \"\")\n\n root_path = os.environ.get(\"ROOT_PATH\", \"\").rstrip(\"/\")\n config_content = config_content.replace(\"{{ROOT_PATH}}\", root_path)\n\n # Write config file\n with open(settings.nginx_config_path, \"w\") as f:\n f.write(config_content)\n\n logger.info(\n f\"Generated Nginx configuration with {len(location_blocks)} location blocks and additional server names: {additional_server_names}\"\n )\n\n # Automatically reload nginx after generating config\n # Use force=True when generating base config to ensure nginx picks up changes\n self.reload_nginx(force=force_base_config)\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to generate Nginx configuration: {e}\", exc_info=True)\n return False\n\n def reload_nginx(self, force: bool = False) -> bool:\n \"\"\"Reload Nginx configuration (if running in appropriate environment).\n\n Args:\n force: If True, reload even in registry-only mode (used after base config generation)\n\n In registry-only mode, skip reload unless force=True.\n \"\"\"\n if not settings.nginx_updates_enabled and not force:\n logger.info(f\"Skipping nginx reload - DEPLOYMENT_MODE={settings.deployment_mode.value}\")\n NGINX_UPDATES_SKIPPED.labels(operation=\"reload\").inc()\n return True\n\n try:\n import subprocess # nosec B404\n\n # Test the configuration first before reloading\n test_result = subprocess.run([\"nginx\", \"-t\"], capture_output=True, text=True) # nosec B603 B607 - hardcoded command\n if test_result.returncode != 0:\n logger.error(f\"Nginx configuration test failed: {test_result.stderr}\")\n logger.info(\"Skipping Nginx reload due to configuration errors\")\n return False\n\n result = subprocess.run([\"nginx\", \"-s\", \"reload\"], capture_output=True, text=True) # nosec B603 B607 - hardcoded command\n if result.returncode == 0:\n logger.info(\"Nginx configuration reloaded successfully\")\n return True\n else:\n logger.error(f\"Failed to reload Nginx: {result.stderr}\")\n return False\n except FileNotFoundError:\n logger.warning(\"Nginx not found - skipping reload\")\n return False\n except Exception as e:\n logger.error(f\"Error reloading Nginx: {e}\")\n return False\n\n def _generate_registry_only_block(self) -> str:\n \"\"\"\n Generate nginx location block for registry-only mode.\n\n In registry-only mode, this block returns 503 for paths that look like\n MCP server requests (paths not matching known API prefixes).\n In with-gateway mode, this returns an empty string.\n\n Returns:\n Nginx location block string or empty string\n \"\"\"\n if settings.nginx_updates_enabled:\n # with-gateway mode: no blocking needed, MCP servers are proxied\n return \"\"\n\n # registry-only mode: block MCP proxy requests with 503\n # This regex matches paths that don't start with known API prefixes\n block = \"\"\"\n # Registry-only mode: block MCP proxy requests with 503\n # Matches paths that don't start with known API/auth prefixes\n location ~ ^{{ROOT_PATH}}/(?!api/|oauth2/|keycloak/|realms/|resources/|v0\\\\.1/|health|static/|assets/|_next/|validate).+ {\n default_type application/json;\n return 503 '{\"error\":\"gateway_proxy_disabled\",\"message\":\"Gateway proxy is disabled in registry-only mode. Connect directly to the MCP server using the proxy_pass_url from server registration.\",\"deployment_mode\":\"registry-only\",\"hint\":\"Use GET /api/servers/{path} to retrieve the proxy_pass_url for direct connection.\"}';\n }\"\"\"\n logger.info(\"Generated registry-only 503 block for MCP proxy requests\")\n return block\n\n async def _generate_version_map(self, servers: dict[str, dict[str, Any]]) -> str:\n \"\"\"\n Generate nginx map directive for version routing.\n\n Args:\n servers: Dictionary of server path -> server info\n\n Returns:\n Nginx map block as string, or empty string if no multi-version servers\n \"\"\"\n from ..services.server_service import server_service\n\n map_entries = []\n\n for path, server_info in servers.items():\n # Check if this server has other versions via other_version_ids\n other_version_ids = server_info.get(\"other_version_ids\", [])\n\n if not other_version_ids:\n # Single-version server - no map entry needed\n continue\n\n # Build versions list from active server and other versions\n versions = []\n\n # Add the current (active) version\n current_version = server_info.get(\"version\", \"v1.0.0\")\n current_proxy_url = server_info.get(\"proxy_pass_url\", \"\")\n if current_proxy_url:\n versions.append(\n {\n \"version\": current_version,\n \"proxy_pass_url\": current_proxy_url,\n \"is_default\": True,\n }\n )\n\n # Add other versions by fetching their info\n for version_id in other_version_ids:\n version_info = await server_service.get_server_info(version_id)\n if version_info:\n versions.append(\n {\n \"version\": version_info.get(\"version\", \"unknown\"),\n \"proxy_pass_url\": version_info.get(\"proxy_pass_url\", \"\"),\n \"is_default\": False,\n }\n )\n\n if len(versions) <= 1:\n # Only one version found, skip\n continue\n\n # Default backend is the active version's URL\n default_backend = current_proxy_url\n\n if not default_backend:\n logger.warning(f\"No default backend found for {path}, skipping version map\")\n continue\n\n # Escape path for nginx regex\n # Handle paths like /context7, /currenttime/, /ai.smithery-xxx\n escaped_path = re.escape(path.rstrip(\"/\"))\n\n # Add map entries for this server\n # Entry for no header (empty string after colon)\n map_entries.append(f' \"~^{escaped_path}(/.*)?:$\" \"{default_backend}\";')\n # Entry for explicit \"latest\"\n map_entries.append(f' \"~^{escaped_path}(/.*)?:latest$\" \"{default_backend}\";')\n\n # Entry for each version\n for v in versions:\n version_str = v.get(\"version\", \"\")\n backend_url = v.get(\"proxy_pass_url\", \"\")\n if version_str and backend_url:\n map_entries.append(\n f' \"~^{escaped_path}(/.*)?:{re.escape(version_str)}$\" \"{backend_url}\";'\n )\n\n logger.info(f\"Generated version map entries for {path} with {len(versions)} versions\")\n\n if not map_entries:\n return \"\" # No multi-version servers configured\n\n return f\"\"\"# Version routing map (auto-generated)\n# Routes requests based on X-MCP-Server-Version header\nmap \"$uri:$http_x_mcp_server_version\" $versioned_backend {{\n default \"\";\n\n{chr(10).join(map_entries)}\n}}\n\n\"\"\"\n\n def _sanitize_path_for_location(\n self,\n path: str,\n ) -> str:\n \"\"\"Sanitize a server path for use as an nginx internal location name.\n\n Replaces /, -, and . with underscores.\n\n Args:\n path: Server path (e.g., '/github')\n\n Returns:\n Sanitized string (e.g., '_github')\n \"\"\"\n return re.sub(r\"[/\\-.]\", \"_\", path)\n\n @staticmethod\n def _sanitize_for_nginx_comment(\n value: str,\n ) -> str:\n \"\"\"Sanitize a string for safe interpolation into an nginx comment.\n\n Strips newlines and carriage returns to prevent header injection\n via multi-line nginx directives.\n\n Args:\n value: Raw string (e.g., server_name from user input)\n\n Returns:\n Sanitized single-line string\n \"\"\"\n return re.sub(r\"[\\r\\n]+\", \" \", value)\n\n @staticmethod\n def _sanitize_for_nginx_set(\n value: str,\n ) -> str:\n \"\"\"Sanitize a string for safe use inside an nginx set directive's double quotes.\n\n Escapes double quotes and backslashes, and strips newlines.\n\n Args:\n value: Raw string (e.g., server_id from URL path)\n\n Returns:\n Escaped string safe for use in: set $var \"value\";\n \"\"\"\n sanitized = re.sub(r\"[\\r\\n]+\", \" \", value)\n sanitized = sanitized.replace(\"\\\\\", \"\\\\\\\\\")\n sanitized = sanitized.replace('\"', '\\\\\"')\n return sanitized\n\n async def _generate_virtual_server_blocks(self) -> str:\n \"\"\"Generate nginx location blocks for enabled virtual servers.\n\n Returns:\n Nginx configuration string with virtual server location blocks\n \"\"\"\n try:\n from registry.repositories.factory import get_virtual_server_repository\n\n virtual_repo = get_virtual_server_repository()\n virtual_servers = await virtual_repo.list_enabled()\n\n if not virtual_servers:\n logger.info(\"No enabled virtual servers found\")\n return \"\"\n\n location_blocks = []\n for vs in virtual_servers:\n # Extract server_id from path (e.g., '/virtual/dev-essentials' -> 'dev-essentials')\n server_id = vs.path.replace(\"/virtual/\", \"\", 1)\n\n # Sanitize values for safe interpolation into nginx config\n safe_name = self._sanitize_for_nginx_comment(vs.server_name)\n safe_id = self._sanitize_for_nginx_set(server_id)\n\n block = f\"\"\"\n # Virtual MCP Server: {safe_name}\n location {{{{ROOT_PATH}}}}{vs.path} {{\n set $virtual_server_id \"{safe_id}\";\n auth_request /validate;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n rewrite_by_lua_file /etc/nginx/lua/capture_body.lua;\n content_by_lua_file /etc/nginx/lua/virtual_router.lua;\n }}\"\"\"\n location_blocks.append(block)\n logger.debug(f\"Generated virtual server location block for {vs.path}\")\n\n logger.info(f\"Generated {len(location_blocks)} virtual server location blocks\")\n return \"\\n\".join(location_blocks)\n\n except Exception as e:\n logger.error(f\"Failed to generate virtual server blocks: {e}\", exc_info=True)\n return \"\"\n\n async def _generate_virtual_backend_locations(\n self,\n virtual_servers: list,\n ) -> str:\n \"\"\"Generate internal nginx location blocks for virtual server backends.\n\n Args:\n virtual_servers: List of VirtualServerConfig objects\n\n Returns:\n Nginx configuration string with internal backend location blocks\n \"\"\"\n try:\n from registry.repositories.factory import get_server_repository\n\n server_repo = get_server_repository()\n\n # Collect unique backend server paths\n backend_paths = set()\n for vs in virtual_servers:\n for tm in vs.tool_mappings:\n backend_paths.add(tm.backend_server_path)\n\n if not backend_paths:\n return \"\"\n\n location_blocks = []\n for backend_path in sorted(backend_paths):\n sanitized = self._sanitize_path_for_location(backend_path)\n server_info = await server_repo.get(backend_path)\n\n if not server_info:\n logger.warning(\n f\"Backend server not found for virtual server mapping: {backend_path}\"\n )\n continue\n\n proxy_pass_url = server_info.get(\"proxy_pass_url\", \"\")\n if not proxy_pass_url:\n logger.warning(f\"No proxy_pass_url for backend server: {backend_path}\")\n continue\n\n # Determine upstream host from proxy_pass_url\n parsed_url = urlparse(proxy_pass_url)\n upstream_host = parsed_url.netloc\n\n # Build MCP endpoint URL from the server's mcp_endpoint or proxy_pass_url\n mcp_endpoint = server_info.get(\"mcp_endpoint\", \"\")\n if mcp_endpoint:\n mcp_parsed = urlparse(mcp_endpoint)\n mcp_path = mcp_parsed.path.rstrip(\"/\")\n # Construct full MCP URL from proxy_pass host + mcp path\n mcp_proxy_url = f\"{parsed_url.scheme}://{parsed_url.netloc}{mcp_path}\"\n else:\n # Fallback: use proxy_pass_url, appending /mcp only if needed\n bare_url = proxy_pass_url.rstrip(\"/\")\n # Check if URL already ends with common MCP endpoint paths\n if bare_url.endswith(\"/mcp\") or bare_url.endswith(\"/sse\"):\n mcp_proxy_url = bare_url\n else:\n mcp_proxy_url = f\"{bare_url}/mcp\"\n\n # Use regular internal location (not named @) so proxy_pass\n # can include a URI path for the MCP endpoint\n location_path = f\"/_vs_backend{sanitized}\"\n\n block = f\"\"\"\n location {location_path} {{\n internal;\n proxy_pass {mcp_proxy_url};\n proxy_http_version 1.1;\n proxy_ssl_server_name on;\n proxy_set_header Host {upstream_host};\n proxy_set_header Authorization $http_authorization;\n proxy_buffering off;\n proxy_set_header Accept \"application/json, text/event-stream\";\n proxy_set_header Content-Type $content_type;\n }}\"\"\"\n location_blocks.append(block)\n logger.debug(\n f\"Generated virtual backend location for {backend_path} -> {location_path}\"\n )\n\n logger.info(f\"Generated {len(location_blocks)} virtual backend location blocks\")\n return \"\\n\".join(location_blocks)\n\n except Exception as e:\n logger.error(f\"Failed to generate virtual backend locations: {e}\", exc_info=True)\n return \"\"\n\n async def _write_virtual_server_mappings(\n self,\n virtual_servers: list,\n ) -> None:\n \"\"\"Write pre-computed mapping JSON files for each virtual server.\n\n These files are consumed by virtual_router.lua at request time.\n\n Args:\n virtual_servers: List of VirtualServerConfig objects\n \"\"\"\n try:\n from registry.repositories.factory import get_server_repository\n\n server_repo = get_server_repository()\n\n mappings_dir = Path(\"/etc/nginx/lua/virtual_mappings\")\n mappings_dir.mkdir(parents=True, exist_ok=True)\n\n for vs in virtual_servers:\n server_id = vs.path.replace(\"/virtual/\", \"\", 1)\n\n # Build scope override lookup\n scope_overrides = {}\n for override in vs.tool_scope_overrides:\n scope_overrides[override.tool_alias] = override.required_scopes\n\n tools = []\n tool_backend_map = {}\n\n for tm in vs.tool_mappings:\n sanitized_backend = self._sanitize_path_for_location(tm.backend_server_path)\n backend_location = f\"/_vs_backend{sanitized_backend}\"\n tool_display_name = tm.alias if tm.alias else tm.tool_name\n\n # Get tool metadata from the backend server\n server_info = await server_repo.get(tm.backend_server_path)\n description = tm.description_override or \"\"\n input_schema: dict[str, Any] = {}\n\n if server_info:\n server_tools = server_info.get(\"tool_list\", [])\n for st in server_tools:\n if st.get(\"name\") == tm.tool_name:\n description = tm.description_override or st.get(\"description\", \"\")\n input_schema = st.get(\"inputSchema\", st.get(\"input_schema\", {}))\n break\n\n input_schema = _ensure_mcp_compliant_schema(input_schema)\n\n # Per-tool scopes\n required_scopes = scope_overrides.get(tool_display_name, [])\n\n tools.append(\n {\n \"name\": tool_display_name,\n \"original_name\": tm.tool_name,\n \"description\": description,\n \"inputSchema\": input_schema,\n \"backend_location\": backend_location,\n \"backend_version\": tm.backend_version,\n \"required_scopes\": required_scopes,\n }\n )\n\n tool_backend_map[tool_display_name] = {\n \"backend_location\": backend_location,\n \"original_name\": tm.tool_name,\n \"backend_version\": tm.backend_version,\n }\n\n mapping_data = {\n \"server_name\": vs.server_name,\n \"required_scopes\": vs.required_scopes,\n \"tools\": tools,\n \"tool_backend_map\": tool_backend_map,\n }\n\n mapping_path = mappings_dir / f\"{server_id}.json\"\n with open(mapping_path, \"w\") as f:\n json.dump(mapping_data, f, indent=2, default=str)\n\n logger.debug(f\"Wrote virtual server mapping: {mapping_path}\")\n\n logger.info(f\"Wrote {len(virtual_servers)} virtual server mapping files\")\n\n except Exception as e:\n logger.error(f\"Failed to write virtual server mappings: {e}\", exc_info=True)\n\n def _generate_transport_location_blocks(self, path: str, server_info: dict[str, Any]) -> list:\n \"\"\"Generate nginx location blocks for different transport types.\"\"\"\n blocks = []\n proxy_pass_url = server_info.get(\"proxy_pass_url\", \"\")\n supported_transports = server_info.get(\"supported_transports\", [\"streamable-http\"])\n\n # Use the proxy_pass_url exactly as specified in the JSON file\n # Users are responsible for including /mcp, /sse, or any other path in the URL\n proxy_url = proxy_pass_url\n\n # Determine transport type based on supported_transports\n if not supported_transports:\n # Default to streamable-http if no transports specified\n transport_type = \"streamable-http\"\n logger.info(\n f\"Server {path}: No supported_transports specified, defaulting to streamable-http\"\n )\n elif \"streamable-http\" in supported_transports and \"sse\" in supported_transports:\n # If both are supported, prefer streamable-http\n transport_type = \"streamable-http\"\n logger.info(\n f\"Server {path}: Both streamable-http and sse supported, preferring streamable-http\"\n )\n elif \"sse\" in supported_transports:\n # SSE only\n transport_type = \"sse\"\n logger.info(f\"Server {path}: Only sse transport supported, using sse\")\n elif \"streamable-http\" in supported_transports:\n # Streamable-http only\n transport_type = \"streamable-http\"\n logger.info(\n f\"Server {path}: Only streamable-http transport supported, using streamable-http\"\n )\n else:\n # Default to streamable-http if unknown transport\n transport_type = \"streamable-http\"\n logger.info(\n f\"Server {path}: Unknown transport types {supported_transports}, defaulting to streamable-http\"\n )\n\n # Create a single location block for this server\n # The proxy_pass URL is used exactly as provided in the server configuration\n logger.info(f\"Server {path}: Using proxy_pass URL as configured: {proxy_url}\")\n\n block = self._create_location_block(path, proxy_url, transport_type, server_info)\n blocks.append(block)\n\n return blocks\n\n def _create_location_block(\n self,\n path: str,\n proxy_pass_url: str,\n transport_type: str,\n server_info: dict[str, Any] | None = None,\n ) -> str:\n \"\"\"Create a single nginx location block with transport-specific configuration.\n\n Args:\n path: Server location path\n proxy_pass_url: Default backend URL\n transport_type: Transport type (streamable-http, sse, direct)\n server_info: Full server info dict (for version support)\n\n Returns:\n Nginx location block as string\n \"\"\"\n # Check if this server has multiple versions\n # The MongoDB document stores linked version IDs in \"other_version_ids\"\n has_versions = False\n if server_info:\n other_version_ids = server_info.get(\"other_version_ids\", [])\n has_versions = len(other_version_ids) > 0\n\n # Extract hostname from proxy_pass_url for external services\n parsed_url = urlparse(proxy_pass_url)\n upstream_host = parsed_url.netloc\n\n # Determine whether to use upstream hostname or preserve original host\n # For external services (https), use the upstream hostname\n # For internal services (http without dots in hostname), preserve original host\n if parsed_url.scheme == \"https\" or \".\" in upstream_host:\n # External service - use upstream hostname\n host_header = upstream_host\n logger.info(f\"Using upstream hostname for Host header: {host_header}\")\n else:\n # Internal service - preserve original host\n host_header = \"$host\"\n logger.info(\"Using original host for Host header: $host\")\n\n # Generate proxy_pass directive based on version routing\n if has_versions:\n # Multi-version server: use map variable with fallback\n proxy_directive = f'''\n # Version routing - use header-based backend selection\n # If X-MCP-Server-Version header matches a version, use that backend\n # Otherwise, use the default backend\n set $backend_url \"{proxy_pass_url}\";\n if ($versioned_backend != \"\") {{\n set $backend_url $versioned_backend;\n }}\n\n # Proxy to selected backend\n proxy_pass $backend_url;'''\n version_headers = \"\"\"\n\n # Add version info to response\n add_header X-MCP-Version-Routing \"enabled\" always;\"\"\"\n else:\n # Single-version server: direct proxy_pass (existing behavior)\n proxy_directive = f\"\"\"\n # Proxy to MCP server\n proxy_pass {proxy_pass_url};\"\"\"\n version_headers = \"\"\n\n # Common proxy settings\n common_settings = f\"\"\"\n # DNS resolver for dynamic proxy_pass upstreams.\n # Default: 8.8.8.8 8.8.4.4 (public DNS).\n # Override with NGINX_DNS_RESOLVER env var for environments where\n # backend servers use internal hostnames (e.g., Kubernetes\n # cluster-local names like *.svc.cluster.local need kube-dns).\n resolver {os.environ.get(\"NGINX_DNS_RESOLVER\", \"8.8.8.8 8.8.4.4\")} valid=10s;\n resolver_timeout {os.environ.get(\"NGINX_DNS_RESOLVER_TIMEOUT\", \"5\")}s;\n\n # Authenticate request - pass entire request to auth server\n auth_request /validate;\n\n # Capture auth server response headers for forwarding\n auth_request_set $auth_user $upstream_http_x_user;\n auth_request_set $auth_username $upstream_http_x_username;\n auth_request_set $auth_client_id $upstream_http_x_client_id;\n auth_request_set $auth_scopes $upstream_http_x_scopes;\n auth_request_set $auth_method $upstream_http_x_auth_method;\n auth_request_set $auth_server_name $upstream_http_x_server_name;\n auth_request_set $auth_tool_name $upstream_http_x_tool_name;\n{proxy_directive}\n proxy_http_version 1.1;\n proxy_ssl_server_name on;\n proxy_set_header Host {host_header};\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n\n # Add original URL for auth server scope validation\n proxy_set_header X-Original-URL $scheme://$host$request_uri;\n\n # Pass through the original authentication headers\n proxy_set_header Authorization $http_authorization;\n proxy_set_header X-Authorization $http_x_authorization;\n proxy_set_header X-User-Pool-Id $http_x_user_pool_id;\n proxy_set_header X-Client-Id $http_x_client_id;\n proxy_set_header X-Region $http_x_region;\n\n # Forward MCP session ID for streamable-http transport\n proxy_set_header Mcp-Session-Id $http_mcp_session_id;\n\n # Forward auth server response headers to backend\n proxy_set_header X-User $auth_user;\n proxy_set_header X-Username $auth_username;\n proxy_set_header X-Client-Id-Auth $auth_client_id;\n proxy_set_header X-Scopes $auth_scopes;\n proxy_set_header X-Auth-Method $auth_method;\n proxy_set_header X-Server-Name $auth_server_name;\n proxy_set_header X-Tool-Name $auth_tool_name;\n\n # Pass all original client headers\n proxy_pass_request_headers on;\n\n # Handle auth errors\n error_page 401 = @auth_error;\n error_page 403 = @forbidden_error;{version_headers}\"\"\"\n\n # Transport-specific settings\n if transport_type == \"sse\":\n transport_settings = \"\"\"\n # Capture request body for auth validation using Lua\n rewrite_by_lua_file /etc/nginx/lua/capture_body.lua;\n log_by_lua_file /etc/nginx/lua/emit_metrics.lua;\n\n # For SSE connections and WebSocket upgrades\n proxy_buffering off;\n proxy_cache off;\n proxy_set_header Connection $http_connection;\n proxy_set_header Upgrade $http_upgrade;\n # Explicitly preserve Accept header for MCP protocol requirements\n proxy_set_header Accept $http_accept;\n chunked_transfer_encoding off;\"\"\"\n\n elif transport_type == \"streamable-http\":\n transport_settings = \"\"\"\n # Capture request body for auth validation using Lua\n rewrite_by_lua_file /etc/nginx/lua/capture_body.lua;\n log_by_lua_file /etc/nginx/lua/emit_metrics.lua;\n\n # HTTP transport configuration\n proxy_buffering off;\n proxy_set_header Connection \"\";\n # Explicitly preserve Accept header for MCP protocol requirements\n proxy_set_header Accept $http_accept;\"\"\"\n\n else: # direct\n transport_settings = \"\"\"\n # Capture request body for auth validation using Lua\n rewrite_by_lua_file /etc/nginx/lua/capture_body.lua;\n log_by_lua_file /etc/nginx/lua/emit_metrics.lua;\n\n # Generic transport configuration\n proxy_buffering off;\n proxy_cache off;\n proxy_set_header Connection $http_connection;\n proxy_set_header Upgrade $http_upgrade;\n chunked_transfer_encoding off;\"\"\"\n\n # Use the location path exactly as specified in the server configuration\n # Users have full control over the location path format (with or without trailing slash)\n location_path = path\n logger.info(f\"Creating location block for {location_path} with {transport_type} transport\")\n\n return f\"\"\"\n location {{{{ROOT_PATH}}}}{location_path} {{{transport_settings}{common_settings}\n }}\"\"\"\n\n\n# Global nginx service instance\nnginx_service = NginxConfigService()\n" }, { "path": "registry/core/schemas.py", "content": "from datetime import datetime\nfrom typing import Any\nfrom uuid import UUID, uuid4\n\nfrom pydantic import BaseModel, Field, field_validator, model_validator\n\nfrom registry.schemas.agent_models import AgentProvider\nfrom registry.schemas.registry_card import LifecycleStatus\n\n\nclass ServerVersion(BaseModel):\n \"\"\"Represents a single version of an MCP server.\n\n Used for multi-version server support where different versions\n can run simultaneously behind a single endpoint.\n \"\"\"\n\n version: str = Field(..., description=\"Version identifier (e.g., 'v2.0.0', 'v1.5.0')\")\n proxy_pass_url: str = Field(..., description=\"Backend URL for this version\")\n status: str = Field(default=\"stable\", description=\"Version status: stable, deprecated, beta\")\n is_default: bool = Field(\n default=False, description=\"Whether this is the default (latest) version\"\n )\n released: str | None = Field(default=None, description=\"Release date (ISO format)\")\n sunset_date: str | None = Field(\n default=None, description=\"Deprecation sunset date (ISO format)\"\n )\n description: str | None = Field(\n default=None, description=\"Version-specific description (if different from main)\"\n )\n\n\nclass ServerInfo(BaseModel):\n \"\"\"Server information model.\"\"\"\n\n id: UUID = Field(\n default_factory=uuid4,\n description=\"Unique identifier (UUID) for this server\",\n )\n server_name: str\n description: str = \"\"\n path: str\n proxy_pass_url: str | None = None\n tags: list[str] = Field(default_factory=list)\n num_tools: int = 0\n license: str = \"N/A\"\n tool_list: list[dict[str, Any]] = Field(default_factory=list)\n is_enabled: bool = False\n transport: str | None = Field(\n default=\"auto\", description=\"Preferred transport: sse, streamable-http, or auto\"\n )\n supported_transports: list[str] = Field(\n default_factory=lambda: [\"streamable-http\"], description=\"List of supported transports\"\n )\n mcp_endpoint: str | None = Field(\n default=None,\n description=\"Full URL for the MCP streamable-http endpoint. If set, used directly for health checks and client connections instead of appending /mcp to proxy_pass_url. Example: 'https://server.com/custom-path'\",\n )\n sse_endpoint: str | None = Field(\n default=None,\n description=\"Full URL for the SSE endpoint. If set, used directly for health checks and client connections instead of appending /sse to proxy_pass_url. Example: 'https://server.com/events'\",\n )\n metadata: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Additional custom metadata for organization, compliance, or integration purposes\",\n )\n # Version routing fields\n version: str | None = Field(\n default=None,\n description=\"Current version identifier (e.g., 'v1.0.0'). None for legacy single-version servers.\",\n )\n versions: list[ServerVersion] | None = Field(\n default=None,\n description=\"List of available versions. None = single-version server (backward compatible).\",\n )\n default_version: str | None = Field(\n default=None, description=\"Default version identifier for routing (e.g., 'v2.0.0')\"\n )\n is_active: bool = Field(\n default=True,\n description=\"Whether this is the active version. False for inactive versions in multi-version setup.\",\n )\n version_group: str | None = Field(\n default=None, description=\"Groups related versions together (derived from path)\"\n )\n other_version_ids: list[str] = Field(\n default_factory=list, description=\"IDs of other versions in this group (for quick lookup)\"\n )\n\n def get_default_proxy_url(self) -> str:\n \"\"\"Get the proxy URL for the default version.\"\"\"\n if not self.versions:\n return self.proxy_pass_url or \"\"\n\n for v in self.versions:\n if v.is_default or v.version == self.default_version:\n return v.proxy_pass_url\n\n # Fallback to first version or original proxy_pass_url\n if self.versions:\n return self.versions[0].proxy_pass_url\n return self.proxy_pass_url or \"\"\n\n def has_multiple_versions(self) -> bool:\n \"\"\"Check if server has multiple versions configured.\"\"\"\n return self.versions is not None and len(self.versions) > 1\n\n # Federation and access control fields\n visibility: str = Field(\n default=\"public\",\n description=\"Federation visibility: public (shared with all peers), group-restricted (shared with allowed_groups only), or private (never shared). 'internal' is accepted as an alias for 'private'.\",\n )\n allowed_groups: list[str] = Field(\n default_factory=list, description=\"Groups with access when visibility is group-restricted\"\n )\n sync_metadata: dict[str, Any] | None = Field(\n default=None, description=\"Metadata for items synced from peer registries\"\n )\n\n # ANS Integration\n ans_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"ansMetadata\",\n description=\"ANS (Agent Name Service) verification metadata\",\n )\n\n # Backend authentication (replaces legacy auth_type)\n auth_scheme: str = Field(\n default=\"none\",\n description=\"Authentication scheme for backend server: none, bearer, api_key\",\n )\n auth_credential_encrypted: str | None = Field(\n default=None,\n description=\"Encrypted auth credential (Fernet). Never returned in API responses.\",\n )\n auth_header_name: str | None = Field(\n default=None,\n description=\"Custom header name. Default: 'Authorization' for bearer, 'X-API-Key' for api_key.\",\n )\n credential_updated_at: str | None = Field(\n default=None, description=\"ISO timestamp of last credential update.\"\n )\n\n # Lifecycle and federation metadata fields\n status: LifecycleStatus = Field(\n default=LifecycleStatus.ACTIVE,\n description=\"Lifecycle status\",\n )\n provider: AgentProvider | None = Field(\n default=None,\n description=\"Provider organization and URL\",\n )\n source_created_at: datetime | None = Field(\n default=None,\n description=\"Original creation timestamp from source system\",\n )\n source_updated_at: datetime | None = Field(\n default=None,\n description=\"Last update timestamp from source system\",\n )\n external_tags: list[str] = Field(\n default_factory=list,\n description=\"Tags from external/source system (separate from local tags)\",\n )\n\n @field_validator(\"visibility\")\n @classmethod\n def _validate_visibility(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate and normalize visibility value.\n\n Accepts \"internal\" as alias for \"private\" and \"group\" as alias\n for \"group-restricted\" for backward compatibility.\n \"\"\"\n from registry.utils.visibility import validate_visibility\n\n return validate_visibility(v)\n\n @model_validator(mode=\"after\")\n def _populate_provider_default(self) -> \"ServerInfo\":\n \"\"\"Populate default provider from config if not set.\"\"\"\n if self.provider is None:\n from registry.core.config import settings\n\n self.provider = AgentProvider(\n organization=settings.registry_organization_name,\n url=settings.registry_url,\n )\n return self\n\n\nclass ToolDescription(BaseModel):\n \"\"\"Parsed tool description sections.\"\"\"\n\n main: str = \"No description available.\"\n args: str | None = None\n returns: str | None = None\n raises: str | None = None\n\n\nclass ToolInfo(BaseModel):\n \"\"\"Tool information model.\"\"\"\n\n name: str\n parsed_description: ToolDescription\n tool_schema: dict[str, Any] = Field(default_factory=dict, alias=\"schema\")\n server_path: str | None = None\n server_name: str | None = None\n\n class Config:\n populate_by_name = True\n\n\nclass HealthStatus(BaseModel):\n \"\"\"Health check status model.\"\"\"\n\n status: str\n last_checked_iso: str | None = None\n num_tools: int = 0\n\n\nclass SessionData(BaseModel):\n \"\"\"Session data model.\"\"\"\n\n username: str\n auth_method: str = \"oauth2\"\n provider: str = \"local\"\n\n\nclass ServiceRegistrationRequest(BaseModel):\n \"\"\"Service registration request model.\"\"\"\n\n name: str = Field(..., min_length=1)\n description: str = \"\"\n path: str = Field(..., min_length=1)\n proxy_pass_url: str = Field(..., min_length=1)\n tags: str = \"\"\n num_tools: int = Field(0, ge=0)\n license: str = \"N/A\"\n transport: str | None = Field(\n default=\"auto\", description=\"Preferred transport: sse, streamable-http, or auto\"\n )\n supported_transports: str = Field(\n default=\"streamable-http\", description=\"Comma-separated list of supported transports\"\n )\n mcp_endpoint: str | None = Field(\n default=None,\n description=\"Full URL for the MCP streamable-http endpoint. If set, used directly for health checks and client connections instead of appending /mcp to proxy_pass_url. Example: 'https://server.com/custom-path'\",\n )\n sse_endpoint: str | None = Field(\n default=None,\n description=\"Full URL for the SSE endpoint. If set, used directly for health checks and client connections instead of appending /sse to proxy_pass_url. Example: 'https://server.com/events'\",\n )\n metadata: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Additional custom metadata for organization, compliance, or integration purposes\",\n )\n visibility: str = Field(\n default=\"public\",\n description=\"Federation visibility: public (shared with all peers), group-restricted (shared with allowed_groups only), or private (never shared). 'internal' is accepted as an alias for 'private'.\",\n )\n allowed_groups: list[str] = Field(\n default_factory=list, description=\"Groups with access when visibility is group-restricted\"\n )\n auth_scheme: str = Field(\n default=\"none\", description=\"Authentication scheme: none, bearer, api_key\"\n )\n auth_credential: str | None = Field(\n default=None,\n description=\"Plaintext credential (encrypted before storage, never stored as-is)\",\n )\n auth_header_name: str | None = Field(\n default=None, description=\"Custom header name for API key auth. Default: X-API-Key\"\n )\n status: LifecycleStatus = Field(\n default=LifecycleStatus.ACTIVE,\n description=\"Lifecycle status: active, deprecated, draft, or beta\",\n )\n\n\nclass AuthCredentialUpdateRequest(BaseModel):\n \"\"\"Request model for updating server auth credentials via PATCH.\"\"\"\n\n auth_scheme: str = Field(..., description=\"Authentication scheme: none, bearer, api_key\")\n auth_credential: str | None = Field(\n default=None, description=\"New credential (required if auth_scheme is not 'none')\"\n )\n auth_header_name: str | None = Field(\n default=None, description=\"Custom header name. Default: X-API-Key for api_key\"\n )\n\n\nclass OAuth2Provider(BaseModel):\n \"\"\"OAuth2 provider information.\"\"\"\n\n name: str\n display_name: str\n icon: str | None = None\n\n\nclass FaissMetadata(BaseModel):\n \"\"\"FAISS metadata model.\"\"\"\n\n id: int\n text_for_embedding: str\n full_server_info: ServerInfo\n" }, { "path": "registry/core/telemetry.py", "content": "\"\"\"\nAnonymous telemetry module for tracking registry adoption.\n\nPrivacy-first design:\n- Opt-out by default (telemetry ON but easy to disable)\n- No PII: no IP addresses, hostnames, file paths, or user data\n- Conspicuous disclosure at every startup\n- Fail-silent: never impact registry operation\n- Cloud-agnostic: no dependency on any specific provider\n\"\"\"\n\nimport asyncio\nimport hashlib\nimport hmac\nimport json\nimport logging\nimport os\nimport platform\nimport sys\nimport uuid\nfrom datetime import UTC, datetime, timedelta\n\nimport httpx\n\nfrom registry.core.config import settings\nfrom registry.version import __version__\n\nlogger = logging.getLogger(__name__)\n\n# Telemetry constants\nSTARTUP_LOCK_INTERVAL_SECONDS = 60 # Don't send startup ping more than once per minute\n# HMAC signing key for telemetry requests.\n# This is NOT a secret — it's embedded in open-source code. Its purpose is to\n# raise the bar against casual abuse (random curl requests) by requiring\n# callers to compute a valid HMAC signature over the request body.\nTELEMETRY_SIGNING_KEY = \"mcp-registry-telemetry-v1-a7f3b9c2e1d4\"\nTELEMETRY_TIMEOUT_SECONDS = 5 # HTTP request timeout\n\n\ndef _detect_cloud_provider() -> str:\n \"\"\"Detect the cloud provider where the registry is running.\n\n Returns:\n One of: aws, gcp, azure, or unknown\n \"\"\"\n # AWS: check for AWS-specific env vars or DMI data\n if os.getenv(\"AWS_REGION\") or os.getenv(\"AWS_DEFAULT_REGION\"):\n return \"aws\"\n try:\n with open(\"/sys/devices/virtual/dmi/id/board_asset_tag\") as f:\n if f.read().strip().startswith(\"i-\"):\n return \"aws\"\n except (FileNotFoundError, PermissionError):\n pass\n\n # GCP: check for GCP-specific env vars\n if os.getenv(\"GOOGLE_CLOUD_PROJECT\") or os.getenv(\"GCLOUD_PROJECT\"):\n return \"gcp\"\n try:\n with open(\"/sys/devices/virtual/dmi/id/product_name\") as f:\n if \"Google\" in f.read():\n return \"gcp\"\n except (FileNotFoundError, PermissionError):\n pass\n\n # Azure: check for Azure-specific env vars\n if os.getenv(\"WEBSITE_INSTANCE_ID\") or os.getenv(\"AZURE_CLIENT_ID\"):\n return \"azure\"\n try:\n with open(\"/sys/devices/virtual/dmi/id/sys_vendor\") as f:\n if \"Microsoft\" in f.read():\n return \"azure\"\n except (FileNotFoundError, PermissionError):\n pass\n\n return \"unknown\"\n\n\ndef _detect_compute_platform() -> str:\n \"\"\"Detect the compute platform where the registry is running.\n\n Returns:\n One of: ecs, eks, kubernetes, docker, ec2, vm, or unknown\n \"\"\"\n # ECS: AWS sets these env vars in ECS task containers\n if os.getenv(\"ECS_CONTAINER_METADATA_URI_V4\") or os.getenv(\"ECS_CONTAINER_METADATA_URI\"):\n return \"ecs\"\n\n # EKS / Kubernetes: k8s injects this env var into every pod\n if os.getenv(\"KUBERNETES_SERVICE_HOST\"):\n return \"kubernetes\"\n\n # Docker (local): /.dockerenv exists in Docker containers\n if os.path.exists(\"/.dockerenv\"):\n return \"docker\"\n\n # EC2: check for AWS hypervisor UUID\n try:\n with open(\"/sys/devices/virtual/dmi/id/board_asset_tag\") as f:\n if f.read().strip().startswith(\"i-\"):\n return \"ec2\"\n except (FileNotFoundError, PermissionError):\n pass\n\n return \"unknown\"\n\n\ndef _compute_signature(body: bytes) -> str:\n \"\"\"Compute HMAC-SHA256 signature for a telemetry request body.\n\n Args:\n body: The JSON-encoded request body as bytes.\n\n Returns:\n Hex-encoded HMAC-SHA256 signature string.\n \"\"\"\n return hmac.new(\n TELEMETRY_SIGNING_KEY.encode(),\n body,\n hashlib.sha256,\n ).hexdigest()\n\n\nasync def _get_registry_id() -> str:\n \"\"\"Get the registry ID for telemetry events.\n\n Tries the registry card UUID first. Falls back to the persistent\n telemetry instance_id if the card hasn't been created yet.\n\n Returns:\n Registry card UUID or telemetry instance_id (never None).\n \"\"\"\n try:\n from registry.repositories.factory import get_registry_card_repository\n\n repo = get_registry_card_repository()\n card = await repo.get()\n if card and card.id:\n return str(card.id)\n except Exception as e:\n logger.warning(f\"[telemetry] Failed to get registry card ID: {e}\")\n\n # Fallback: use the persistent telemetry instance_id\n logger.debug(\"[telemetry] Registry card not found, using telemetry instance_id\")\n return await _get_or_create_instance_id()\n\n\ndef _is_telemetry_enabled() -> bool:\n \"\"\"Check if telemetry is enabled (respects MCP_TELEMETRY_DISABLED env var).\"\"\"\n # Environment variable override takes precedence\n disabled_env = os.getenv(\"MCP_TELEMETRY_DISABLED\", \"\").lower()\n if disabled_env in (\"1\", \"true\", \"yes\"):\n return False\n\n return settings.telemetry_enabled\n\n\ndef _is_heartbeat_enabled() -> bool:\n \"\"\"Check if heartbeat telemetry is enabled (on by default, opt-out).\"\"\"\n if not _is_telemetry_enabled():\n return False\n\n # Check environment variable override for heartbeat opt-out\n opt_out_env = os.getenv(\"MCP_TELEMETRY_OPT_OUT\", \"\").lower()\n if opt_out_env in (\"1\", \"true\", \"yes\"):\n return False\n\n return not settings.telemetry_opt_out\n\n\ndef _get_heartbeat_interval_minutes() -> int:\n \"\"\"Get heartbeat interval from settings (default 1440 minutes = 24 hours).\"\"\"\n # Environment variable override takes precedence\n env_val = os.getenv(\"MCP_TELEMETRY_HEARTBEAT_INTERVAL_MINUTES\", \"\")\n if env_val.isdigit() and int(env_val) > 0:\n return int(env_val)\n\n return settings.telemetry_heartbeat_interval_minutes\n\n\ndef _get_heartbeat_lock_interval_seconds() -> int:\n \"\"\"Get heartbeat lock interval derived from heartbeat interval.\"\"\"\n return _get_heartbeat_interval_minutes() * 60\n\n\nasync def _get_or_create_instance_id() -> str:\n \"\"\"\n Get or create anonymous instance ID.\n\n - For MongoDB/DocumentDB: Store in _telemetry_state collection\n - For file-based storage: Store in {data_dir}/.telemetry_id\n\n Returns:\n UUID v4 string (e.g., \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\")\n \"\"\"\n if settings.storage_backend in (\"mongodb-ce\", \"documentdb\"):\n # MongoDB-based storage\n from registry.repositories.documentdb.client import get_documentdb_client\n\n try:\n db = await get_documentdb_client()\n collection = db[\"_telemetry_state\"]\n\n # Try to get existing document\n doc = await collection.find_one({\"_id\": \"telemetry_config\"})\n\n if doc and \"instance_id\" in doc:\n return doc[\"instance_id\"]\n\n # Create new instance ID\n instance_id = str(uuid.uuid4())\n now = datetime.now(UTC).isoformat()\n\n # Insert or update\n await collection.update_one(\n {\"_id\": \"telemetry_config\"},\n {\"$setOnInsert\": {\"instance_id\": instance_id, \"created_at\": now}},\n upsert=True,\n )\n\n return instance_id\n\n except Exception as e:\n logger.warning(f\"Failed to get instance ID from MongoDB: {e}\")\n # Fall through to file-based fallback\n\n # File-based fallback\n telemetry_file = settings.data_dir / \".telemetry_id\"\n\n try:\n # Ensure data directory exists\n settings.data_dir.mkdir(parents=True, exist_ok=True)\n\n if telemetry_file.exists():\n instance_id = telemetry_file.read_text().strip()\n if instance_id:\n return instance_id\n\n # Create new instance ID\n instance_id = str(uuid.uuid4())\n telemetry_file.write_text(instance_id)\n return instance_id\n\n except Exception as e:\n logger.warning(f\"Failed to read/write telemetry ID file: {e}\")\n # Last resort: generate ephemeral ID (will be different each startup)\n return str(uuid.uuid4())\n\n\nasync def _acquire_telemetry_lock(event_type: str, interval_seconds: int) -> bool:\n \"\"\"\n Acquire a distributed lock for sending telemetry.\n\n Uses MongoDB findOneAndUpdate with a staleness check to ensure\n only one replica sends telemetry within the interval window.\n\n Args:\n event_type: \"startup\" or \"heartbeat\"\n interval_seconds: Lock interval (e.g., 60 for startup, 86400 for heartbeat)\n\n Returns:\n True if lock acquired (caller should send), False if already sent recently\n \"\"\"\n if settings.storage_backend not in (\"mongodb-ce\", \"documentdb\"):\n # File-based storage: no multi-replica concerns, always allow\n return True\n\n try:\n from registry.repositories.documentdb.client import get_documentdb_client\n\n db = await get_documentdb_client()\n collection = db[\"_telemetry_state\"]\n\n now = datetime.now(UTC)\n cutoff = now - timedelta(seconds=interval_seconds)\n\n field_name = f\"last_{event_type}_sent_at\"\n\n # Atomic update: only update if last sent is None or older than cutoff\n # NOTE: Use BSON datetime objects for proper comparison (not ISO-8601 strings)\n result = await collection.find_one_and_update(\n {\n \"_id\": \"telemetry_config\",\n \"$or\": [\n {field_name: {\"$exists\": False}},\n {field_name: None},\n {field_name: {\"$lt\": cutoff}}, # Motor converts datetime to BSON date\n ],\n },\n {\"$set\": {field_name: now}}, # Store as BSON datetime\n upsert=False,\n )\n\n # Lock acquired if document was found and updated\n return result is not None\n\n except Exception as e:\n logger.warning(f\"Failed to acquire telemetry lock: {e}\")\n # If lock mechanism fails, don't block telemetry\n return True\n\n\nasync def _build_startup_payload() -> dict:\n \"\"\"Build the anonymous startup event payload.\"\"\"\n from registry.repositories.stats_repository import get_search_counts\n\n counts = await get_search_counts()\n registry_id = await _get_registry_id()\n\n return {\n \"event\": \"startup\",\n \"schema_version\": \"1\",\n \"registry_id\": registry_id,\n \"v\": __version__,\n \"py\": f\"{sys.version_info.major}.{sys.version_info.minor}\",\n \"os\": platform.system().lower(), # linux, darwin, windows\n \"arch\": platform.machine(), # x86_64, arm64, aarch64\n \"cloud\": _detect_cloud_provider(), # aws, gcp, azure, unknown\n \"compute\": _detect_compute_platform(), # ecs, eks, kubernetes, docker, ec2, unknown\n \"mode\": settings.deployment_mode.value, # with-gateway, registry-only\n \"registry_mode\": settings.registry_mode.value, # full, skills-only, etc.\n \"storage\": settings.storage_backend, # file, documentdb, mongodb-ce\n \"auth\": settings.auth_provider, # cognito, keycloak, entra, github, google\n \"federation\": settings.federation_static_token_auth_enabled,\n \"search_queries_total\": counts[\"total\"],\n \"search_queries_24h\": counts[\"last_24h\"],\n \"search_queries_1h\": counts[\"last_1h\"],\n \"ts\": datetime.now(UTC).isoformat(),\n }\n\n\nasync def _build_heartbeat_payload() -> dict:\n \"\"\"Build the richer opt-in heartbeat payload with aggregate counts.\"\"\"\n from registry.api.system_routes import get_server_start_time\n from registry.repositories.factory import (\n get_agent_repository,\n get_peer_federation_repository,\n get_server_repository,\n get_skill_repository,\n )\n from registry.repositories.stats_repository import get_search_counts\n\n # Calculate uptime\n uptime_hours = 0\n server_start_time = get_server_start_time()\n if server_start_time:\n elapsed = datetime.now(UTC) - server_start_time\n uptime_hours = int(elapsed.total_seconds() / 3600)\n\n # Get aggregate counts (with detailed error logging)\n try:\n server_repo = get_server_repository()\n servers = await server_repo.list_all()\n servers_count = len(servers)\n except Exception as e:\n logger.warning(f\"[telemetry] Failed to get server count: {e}\")\n servers_count = 0\n\n try:\n agent_repo = get_agent_repository()\n agents = await agent_repo.list_all()\n agents_count = len(agents)\n except Exception as e:\n logger.warning(f\"[telemetry] Failed to get agent count: {e}\")\n agents_count = 0\n\n try:\n skill_repo = get_skill_repository()\n skills = await skill_repo.list_all()\n skills_count = len(skills)\n except Exception as e:\n logger.warning(f\"[telemetry] Failed to get skill count: {e}\")\n skills_count = 0\n\n try:\n peer_repo = get_peer_federation_repository()\n peers = await peer_repo.list_peers()\n peers_count = len(peers)\n except Exception as e:\n logger.warning(f\"[telemetry] Failed to get peer count: {e}\")\n peers_count = 0\n\n # Determine search backend from storage backend\n # documentdb/mongodb-ce uses DocumentDB search, file uses FAISS\n search_backend = (\n \"documentdb\" if settings.storage_backend in (\"documentdb\", \"mongodb-ce\") else \"faiss\"\n )\n\n counts = await get_search_counts()\n registry_id = await _get_registry_id()\n\n return {\n \"event\": \"heartbeat\",\n \"schema_version\": \"1\",\n \"registry_id\": registry_id,\n \"v\": __version__,\n \"cloud\": _detect_cloud_provider(),\n \"compute\": _detect_compute_platform(),\n \"servers_count\": servers_count,\n \"agents_count\": agents_count,\n \"skills_count\": skills_count,\n \"peers_count\": peers_count,\n \"search_backend\": search_backend,\n \"embeddings_provider\": settings.embeddings_provider,\n \"uptime_hours\": uptime_hours,\n \"search_queries_total\": counts[\"total\"],\n \"search_queries_24h\": counts[\"last_24h\"],\n \"search_queries_1h\": counts[\"last_1h\"],\n \"ts\": datetime.now(UTC).isoformat(),\n }\n\n\nasync def _send_telemetry(payload: dict) -> None:\n \"\"\"\n Send telemetry payload to the collector endpoint.\n\n - 5-second timeout\n - Fail-silent: log errors but never raise\n - Debug mode: log payload instead of sending\n\n Args:\n payload: Telemetry event payload (startup or heartbeat)\n \"\"\"\n\n # Debug mode: log payload instead of sending\n if settings.telemetry_debug:\n logger.info(f\"[telemetry] Debug mode - payload:\\n{json.dumps(payload, indent=2)}\")\n return\n\n # Serialize payload and compute HMAC signature\n body = json.dumps(payload, separators=(\",\", \":\"), sort_keys=True).encode()\n signature = _compute_signature(body)\n\n # Send telemetry with retry logic\n max_retries = 1 # Single retry\n retry_delay = 1.0 # 1 second delay\n\n for attempt in range(max_retries + 1):\n try:\n async with httpx.AsyncClient(timeout=TELEMETRY_TIMEOUT_SECONDS) as client:\n response = await client.post(\n settings.telemetry_endpoint,\n content=body,\n headers={\n \"Content-Type\": \"application/json\",\n \"X-Telemetry-Signature\": signature,\n },\n )\n\n if response.status_code in (200, 204):\n logger.info(f\"[telemetry] {payload['event']} event sent successfully\")\n\n # Track success in Datadog\n from registry.core.metrics import telemetry_sends_total\n\n telemetry_sends_total.labels(event=payload[\"event\"], status=\"success\").inc()\n\n return # Success, exit\n\n else:\n logger.warning(\n f\"[telemetry] Unexpected response {response.status_code} from collector\"\n )\n\n # Track failure in Datadog\n from registry.core.metrics import telemetry_sends_total\n\n status_category = f\"{response.status_code // 100}xx\"\n telemetry_sends_total.labels(\n event=payload[\"event\"], status=status_category\n ).inc()\n\n except httpx.TimeoutException:\n logger.info(f\"[telemetry] Request timed out (attempt {attempt + 1}/{max_retries + 1})\")\n\n # Track timeout in Datadog\n from registry.core.metrics import telemetry_sends_total\n\n telemetry_sends_total.labels(\n event=payload.get(\"event\", \"unknown\"), status=\"timeout\"\n ).inc()\n\n except Exception as e:\n logger.info(\n f\"[telemetry] Failed to send (attempt {attempt + 1}/{max_retries + 1}): {e}\"\n )\n\n # Track error in Datadog\n from registry.core.metrics import telemetry_sends_total\n\n telemetry_sends_total.labels(\n event=payload.get(\"event\", \"unknown\"), status=\"error\"\n ).inc()\n\n # Retry after delay (but not on last attempt)\n if attempt < max_retries:\n await asyncio.sleep(retry_delay)\n\n\nasync def _initialize_telemetry_collection() -> None:\n \"\"\"\n Proactively create the _telemetry_state collection with proper schema.\n\n Called during application startup to ensure MongoDB permissions are correct\n and avoid silent failures on first telemetry send.\n \"\"\"\n if settings.storage_backend not in (\"mongodb-ce\", \"documentdb\"):\n return # File-based storage, no collection needed\n\n try:\n from registry.repositories.documentdb.client import get_documentdb_client\n\n db = await get_documentdb_client()\n\n # Check if collection exists\n existing_collections = await db.list_collection_names()\n\n if \"_telemetry_state\" not in existing_collections:\n # Create collection\n await db.create_collection(\"_telemetry_state\")\n logger.info(\"[telemetry] Created _telemetry_state collection\")\n\n # Ensure the singleton document exists\n collection = db[\"_telemetry_state\"]\n doc = await collection.find_one({\"_id\": \"telemetry_config\"})\n\n if not doc:\n # Create initial document with instance_id\n instance_id = str(uuid.uuid4())\n now = datetime.now(UTC)\n\n await collection.insert_one(\n {\"_id\": \"telemetry_config\", \"instance_id\": instance_id, \"created_at\": now}\n )\n logger.info(f\"[telemetry] Initialized instance_id: {instance_id}\")\n\n except Exception as e:\n logger.warning(f\"[telemetry] Failed to initialize collection: {e}\")\n # Non-fatal: will fall back to lazy creation or file-based storage\n\n\n# Global scheduler instance\n_telemetry_scheduler: \"TelemetryScheduler | None\" = None\n\n\nasync def initialize_telemetry() -> None:\n \"\"\"\n Initialize telemetry system (create MongoDB collection, etc.).\n\n Called during lifespan startup, before send_startup_ping().\n \"\"\"\n await _initialize_telemetry_collection()\n\n\nasync def send_startup_ping() -> None:\n \"\"\"\n Send anonymous startup ping (Tier 1 - Opt-Out).\n\n Called once during lifespan startup. Checks lock to prevent\n duplicate sends in multi-replica deployments.\n \"\"\"\n if not _is_telemetry_enabled():\n logger.info(\"[telemetry] Telemetry is disabled\")\n return\n\n # Log conspicuous disclosure\n logger.info(\"=\" * 78)\n logger.info(\"[telemetry] Anonymous usage telemetry is ON (startup ping + daily heartbeat)\")\n logger.info(\"[telemetry] No PII is collected (no IPs, hostnames, or user data)\")\n logger.info(f\"[telemetry] Endpoint: {settings.telemetry_endpoint}\")\n logger.info(\"[telemetry] To disable all: set MCP_TELEMETRY_DISABLED=1\")\n logger.info(\n \"[telemetry] Details: https://github.com/agentic-community/\"\n \"mcp-gateway-registry/blob/main/docs/TELEMETRY.md\"\n )\n logger.info(\"=\" * 78)\n\n try:\n # Acquire lock (60-second interval)\n lock_acquired = await _acquire_telemetry_lock(\"startup\", STARTUP_LOCK_INTERVAL_SECONDS)\n\n if not lock_acquired:\n logger.info(\"[telemetry] Startup ping already sent recently by another replica\")\n return\n\n # Build and send payload\n payload = await _build_startup_payload()\n await _send_telemetry(payload)\n\n except Exception as e:\n logger.warning(f\"[telemetry] Startup ping failed: {e}\")\n\n\nasync def start_heartbeat_scheduler() -> None:\n \"\"\"\n Start the heartbeat scheduler (Tier 2 - Opt-Out, default ON).\n\n No-op if heartbeat is disabled. Called during lifespan startup.\n \"\"\"\n global _telemetry_scheduler\n\n if not _is_heartbeat_enabled():\n logger.info(\"[telemetry] Heartbeat scheduler not started (opted out or telemetry disabled)\")\n return\n\n if _telemetry_scheduler is not None:\n logger.warning(\"[telemetry] Heartbeat scheduler already running\")\n return\n\n _telemetry_scheduler = TelemetryScheduler()\n await _telemetry_scheduler.start()\n interval = _get_heartbeat_interval_minutes()\n logger.info(f\"[telemetry] Daily heartbeat telemetry is ON ({interval}-minute interval)\")\n\n\nasync def stop_heartbeat_scheduler() -> None:\n \"\"\"Stop the heartbeat scheduler. Called during lifespan shutdown.\"\"\"\n global _telemetry_scheduler\n\n if _telemetry_scheduler is not None:\n await _telemetry_scheduler.stop()\n _telemetry_scheduler = None\n\n\nasync def send_forced_heartbeat() -> dict:\n \"\"\"\n Force-send a heartbeat event immediately, bypassing the interval lock.\n\n Called from admin API endpoint. Respects telemetry enabled/disabled setting\n but skips the distributed lock so the event is always sent.\n\n Returns:\n Dict with status and optional payload summary.\n \"\"\"\n if not _is_telemetry_enabled():\n return {\"status\": \"disabled\", \"message\": \"Telemetry is disabled\"}\n\n try:\n payload = await _build_heartbeat_payload()\n await _send_telemetry(payload)\n return {\n \"status\": \"sent\",\n \"event\": \"heartbeat\",\n \"servers_count\": payload.get(\"servers_count\", 0),\n \"agents_count\": payload.get(\"agents_count\", 0),\n \"skills_count\": payload.get(\"skills_count\", 0),\n \"peers_count\": payload.get(\"peers_count\", 0),\n \"ts\": payload.get(\"ts\"),\n }\n except Exception as e:\n logger.error(f\"[telemetry] Forced heartbeat failed: {e}\")\n return {\"status\": \"error\", \"message\": str(e)}\n\n\nasync def send_forced_startup() -> dict:\n \"\"\"\n Force-send a startup event immediately, bypassing the 60-second lock.\n\n Called from admin API endpoint. Respects telemetry enabled/disabled setting\n but skips the distributed lock so the event is always sent.\n\n Returns:\n Dict with status and optional payload summary.\n \"\"\"\n if not _is_telemetry_enabled():\n return {\"status\": \"disabled\", \"message\": \"Telemetry is disabled\"}\n\n try:\n payload = await _build_startup_payload()\n await _send_telemetry(payload)\n return {\n \"status\": \"sent\",\n \"event\": \"startup\",\n \"v\": payload.get(\"v\"),\n \"storage\": payload.get(\"storage\"),\n \"mode\": payload.get(\"mode\"),\n \"ts\": payload.get(\"ts\"),\n }\n except Exception as e:\n logger.error(f\"[telemetry] Forced startup ping failed: {e}\")\n return {\"status\": \"error\", \"message\": str(e)}\n\n\nclass TelemetryScheduler:\n \"\"\"\n Background scheduler for daily heartbeat telemetry.\n\n Follows the same pattern as PeerSyncScheduler.\n \"\"\"\n\n def __init__(self):\n self._task: asyncio.Task | None = None\n self._running: bool = False\n\n async def start(self) -> None:\n \"\"\"Start the background scheduler.\"\"\"\n if self._running:\n logger.warning(\"[telemetry] Heartbeat scheduler already running\")\n return\n\n self._running = True\n self._task = asyncio.create_task(self._scheduler_loop())\n logger.info(\"[telemetry] Heartbeat scheduler started\")\n\n async def stop(self) -> None:\n \"\"\"Stop the background scheduler.\"\"\"\n self._running = False\n if self._task:\n self._task.cancel()\n try:\n await self._task\n except asyncio.CancelledError:\n pass\n self._task = None\n logger.info(\"[telemetry] Heartbeat scheduler stopped\")\n\n async def _scheduler_loop(self) -> None:\n \"\"\"Main scheduler loop that sends heartbeat at configured interval.\"\"\"\n interval_minutes = _get_heartbeat_interval_minutes()\n logger.info(f\"[telemetry] Heartbeat loop started ({interval_minutes}-minute interval)\")\n\n while self._running:\n try:\n await self._send_heartbeat()\n except Exception as e:\n logger.error(f\"[telemetry] Error in heartbeat scheduler: {e}\", exc_info=True)\n\n # Wait for configured interval before next heartbeat\n await asyncio.sleep(interval_minutes * 60)\n\n async def _send_heartbeat(self) -> None:\n \"\"\"Send heartbeat event if lock acquired.\"\"\"\n # Acquire lock (interval matches heartbeat frequency)\n lock_acquired = await _acquire_telemetry_lock(\n \"heartbeat\", _get_heartbeat_lock_interval_seconds()\n )\n\n if not lock_acquired:\n logger.info(\"[telemetry] Heartbeat already sent recently by another replica\")\n return\n\n # Build and send payload\n payload = await _build_heartbeat_payload()\n await _send_telemetry(payload)\n" }, { "path": "registry/embeddings/README.md", "content": "# Embeddings Module\n\nVendor-agnostic embeddings generation for MCP Gateway Registry's semantic search functionality.\n\n## Overview\n\nThis module provides a unified interface for generating text embeddings from multiple providers, supporting both local models (sentence-transformers) and cloud-based APIs (via LiteLLM).\n\n## Features\n\n- **Vendor-agnostic**: Switch between embeddings providers with configuration changes\n- **Local & Cloud Support**: Use local models or cloud APIs (OpenAI, Cohere, Amazon Bedrock, etc.)\n- **Backward Compatible**: Works seamlessly with existing FAISS indices\n- **Easy Configuration**: Simple environment variable setup\n- **Extensible**: Easy to add new providers\n\n## Architecture\n\n```\nEmbeddingsClient (Abstract Base Class)\n├── SentenceTransformersClient (Local models)\n└── LiteLLMClient (Cloud APIs via LiteLLM)\n```\n\n## Quick Start\n\n### Using Sentence Transformers (Default)\n\n```bash\n# In .env\nEMBEDDINGS_PROVIDER=sentence-transformers\nEMBEDDINGS_MODEL_NAME=all-MiniLM-L6-v2\nEMBEDDINGS_MODEL_DIMENSIONS=384\n```\n\n```python\nfrom registry.embeddings import create_embeddings_client\n\nclient = create_embeddings_client(\n provider=\"sentence-transformers\",\n model_name=\"all-MiniLM-L6-v2\",\n embedding_dimension=384,\n)\n\nembeddings = client.encode([\"Hello world\", \"This is a test\"])\nprint(embeddings.shape) # (2, 384)\n```\n\n### Using LiteLLM with OpenAI\n\n```bash\n# In .env\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=openai/text-embedding-3-small\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_API_KEY=your_openai_api_key\n```\n\n```python\nfrom registry.embeddings import create_embeddings_client\n\nclient = create_embeddings_client(\n provider=\"litellm\",\n model_name=\"openai/text-embedding-3-small\",\n api_key=\"your_openai_api_key\",\n embedding_dimension=1536,\n)\n\nembeddings = client.encode([\"Hello world\", \"This is a test\"])\nprint(embeddings.shape) # (2, 1536)\n```\n\n### Using LiteLLM with Amazon Bedrock\n\nAmazon Bedrock uses the standard AWS credential chain for authentication.\n\n```bash\n# In .env\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=bedrock/amazon.titan-embed-text-v1\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_AWS_REGION=us-east-1\n```\n\n**Configure AWS credentials via standard methods:**\n\n**Option 1: IAM Roles (Recommended for EC2/EKS)**\n```bash\n# No additional configuration needed\n# EC2 instance or EKS pod automatically uses attached IAM role\n```\n\n**Option 2: Environment Variables**\n```bash\nexport AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nexport AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\nexport AWS_REGION=us-east-1\n```\n\n**Option 3: AWS Credentials File**\n```bash\n# ~/.aws/credentials\n[default]\naws_access_key_id = AKIAIOSFODNN7EXAMPLE\naws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\n\n# ~/.aws/config\n[default]\nregion = us-east-1\n```\n\n**Python Usage:**\n```python\nfrom registry.embeddings import create_embeddings_client\n\n# Uses standard AWS credential chain\nclient = create_embeddings_client(\n provider=\"litellm\",\n model_name=\"bedrock/amazon.titan-embed-text-v1\",\n aws_region=\"us-east-1\",\n embedding_dimension=1536,\n)\n\nembeddings = client.encode([\"Hello world\", \"This is a test\"])\nprint(embeddings.shape) # (2, 1536)\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `EMBEDDINGS_PROVIDER` | Provider type: `sentence-transformers` or `litellm` | `sentence-transformers` | No |\n| `EMBEDDINGS_MODEL_NAME` | Model identifier | `all-MiniLM-L6-v2` | Yes |\n| `EMBEDDINGS_MODEL_DIMENSIONS` | Embedding dimension | `384` | Yes |\n| `EMBEDDINGS_API_KEY` | API key for cloud provider (OpenAI, Cohere, etc.) | - | For cloud* |\n| `EMBEDDINGS_API_BASE` | Custom API endpoint (LiteLLM only) | - | No |\n| `EMBEDDINGS_AWS_REGION` | AWS region for Bedrock (LiteLLM only) | - | For Bedrock |\n\n*Not required for AWS Bedrock - use standard AWS credential chain (IAM roles, environment variables, ~/.aws/credentials)\n\n### Supported Models\n\n#### Sentence Transformers (Local)\n\n- `all-MiniLM-L6-v2` (384 dimensions) - Fast, lightweight\n- `all-mpnet-base-v2` (768 dimensions) - High quality\n- `paraphrase-multilingual-MiniLM-L12-v2` (384 dimensions) - Multilingual\n- Any model from [Hugging Face sentence-transformers](https://huggingface.co/models?library=sentence-transformers)\n\n#### LiteLLM (Cloud-based)\n\n**OpenAI:**\n- `openai/text-embedding-3-small` (1536 dimensions)\n- `openai/text-embedding-3-large` (3072 dimensions)\n- `openai/text-embedding-ada-002` (1536 dimensions)\n\n**Cohere:**\n- `cohere/embed-english-v3.0` (1024 dimensions)\n- `cohere/embed-multilingual-v3.0` (1024 dimensions)\n\n**Amazon Bedrock:**\n- `bedrock/amazon.titan-embed-text-v1` (1536 dimensions)\n- `bedrock/cohere.embed-english-v3` (1024 dimensions)\n- `bedrock/cohere.embed-multilingual-v3` (1024 dimensions)\n\n## API Reference\n\n### EmbeddingsClient (Abstract)\n\nBase class for all embeddings clients.\n\n**Methods:**\n- `encode(texts: List[str]) -> np.ndarray`: Generate embeddings for texts\n- `get_embedding_dimension() -> int`: Get embedding dimension\n\n### SentenceTransformersClient\n\nLocal embeddings using sentence-transformers library.\n\n**Constructor:**\n```python\nSentenceTransformersClient(\n model_name: str,\n model_dir: Optional[Path] = None,\n cache_dir: Optional[Path] = None,\n)\n```\n\n**Parameters:**\n- `model_name`: Hugging Face model identifier\n- `model_dir`: Local directory with pre-downloaded model (optional)\n- `cache_dir`: Cache directory for models (optional)\n\n### LiteLLMClient\n\nCloud-based embeddings via LiteLLM.\n\n**Constructor:**\n```python\nLiteLLMClient(\n model_name: str,\n api_key: Optional[str] = None,\n secret_key: Optional[str] = None,\n api_base: Optional[str] = None,\n aws_region: Optional[str] = None,\n embedding_dimension: Optional[int] = None,\n)\n```\n\n**Parameters:**\n- `model_name`: Provider-prefixed model (e.g., `openai/text-embedding-3-small`, `bedrock/amazon.titan-embed-text-v1`)\n- `api_key`: API key for the provider (OpenAI, Cohere, etc.; not used for Bedrock)\n- `api_base`: Custom API endpoint URL (optional)\n- `aws_region`: AWS region for Bedrock (required for Bedrock)\n- `embedding_dimension`: Expected dimension for validation (optional)\n\n**AWS Bedrock Notes:**\n- Uses standard AWS credential chain for authentication (IAM roles, environment variables, ~/.aws/credentials)\n- The `api_key` parameter is not used for Bedrock authentication\n- The `aws_region` parameter is required for Bedrock\n\n### Factory Function\n\n```python\ncreate_embeddings_client(\n provider: str,\n model_name: str,\n model_dir: Optional[Path] = None,\n cache_dir: Optional[Path] = None,\n api_key: Optional[str] = None,\n secret_key: Optional[str] = None,\n api_base: Optional[str] = None,\n aws_region: Optional[str] = None,\n embedding_dimension: Optional[int] = None,\n) -> EmbeddingsClient\n```\n\nCreates an embeddings client based on the provider type.\n\n**Parameters:**\n- `provider`: \"sentence-transformers\" or \"litellm\"\n- `model_name`: Model identifier\n- `model_dir`: Local model directory (sentence-transformers only)\n- `cache_dir`: Cache directory (sentence-transformers only)\n- `api_key`: API key (litellm only; not used for Bedrock)\n- `api_base`: Custom API endpoint (litellm only)\n- `aws_region`: AWS region (litellm with Bedrock only)\n- `embedding_dimension`: Expected dimension\n\n## Integration with FAISS Service\n\nThe embeddings module integrates seamlessly with the existing FAISS search service:\n\n```python\n# In registry/search/service.py\nfrom registry.embeddings import create_embeddings_client\n\nclass FaissService:\n async def _load_embedding_model(self):\n self.embedding_model = create_embeddings_client(\n provider=settings.embeddings_provider,\n model_name=settings.embeddings_model_name,\n # ... other parameters from settings\n )\n```\n\n## Migration Guide\n\n### From Direct SentenceTransformer Usage\n\n**Before:**\n```python\nfrom sentence_transformers import SentenceTransformer\n\nmodel = SentenceTransformer(\"all-MiniLM-L6-v2\")\nembeddings = model.encode(texts)\n```\n\n**After:**\n```python\nfrom registry.embeddings import create_embeddings_client\n\nclient = create_embeddings_client(\n provider=\"sentence-transformers\",\n model_name=\"all-MiniLM-L6-v2\",\n)\nembeddings = client.encode(texts)\n```\n\n### Switching to Cloud Provider\n\nJust update your `.env` file:\n\n```bash\n# From\nEMBEDDINGS_PROVIDER=sentence-transformers\nEMBEDDINGS_MODEL_NAME=all-MiniLM-L6-v2\nEMBEDDINGS_MODEL_DIMENSIONS=384\n\n# To\nEMBEDDINGS_PROVIDER=litellm\nEMBEDDINGS_MODEL_NAME=openai/text-embedding-3-small\nEMBEDDINGS_MODEL_DIMENSIONS=1536\nEMBEDDINGS_API_KEY=your_openai_api_key\n```\n\nNo code changes required!\n\n## Performance Considerations\n\n### Local Models (Sentence Transformers)\n- **Pros**: No API costs, privacy, no network latency\n- **Cons**: CPU/GPU requirements, model download size\n- **Best for**: High-volume usage, sensitive data, offline operation\n\n### Cloud APIs (LiteLLM)\n- **Pros**: No local resources, higher quality models, instant availability\n- **Cons**: API costs, network dependency, data leaves premises\n- **Best for**: Low-volume usage, rapid prototyping, maximum quality\n\n## Troubleshooting\n\n### LiteLLM Not Installed\n\n```\nRuntimeError: LiteLLM is not installed. Install it with: uv add litellm\n```\n\n**Solution:**\n```bash\nuv add litellm\n```\n\n### Dimension Mismatch\n\n```\nWARNING: Embedding dimension mismatch: expected 384, got 1536\n```\n\n**Solution:** Update `EMBEDDINGS_MODEL_DIMENSIONS` to match your model's actual output.\n\n### API Authentication Errors\n\nFor cloud providers, ensure your API key is correctly set:\n- OpenAI: Set `EMBEDDINGS_API_KEY`\n- Cohere: Set `EMBEDDINGS_API_KEY`\n- Bedrock: Configure AWS credentials via standard AWS methods\n\n## Testing\n\nRun the test suite to verify the integration:\n\n```bash\n# Create a test file\ncat > test_embeddings.py << 'EOF'\nfrom registry.embeddings import create_embeddings_client\n\n# Test sentence-transformers\nclient = create_embeddings_client(\n provider=\"sentence-transformers\",\n model_name=\"all-MiniLM-L6-v2\",\n)\nembeddings = client.encode([\"test\"])\nprint(f\"✓ Embeddings shape: {embeddings.shape}\")\nEOF\n\n# Run test\nuv run python test_embeddings.py\n```\n\n## Contributing\n\nTo add a new embeddings provider:\n\n1. Create a new client class inheriting from `EmbeddingsClient`\n2. Implement `encode()` and `get_embedding_dimension()` methods\n3. Update `create_embeddings_client()` factory function\n4. Add configuration options to `registry/core/config.py`\n5. Document in this README\n\n## License\n\nApache 2.0 - See LICENSE file for details\n" }, { "path": "registry/embeddings/__init__.py", "content": "\"\"\"Embeddings module for vendor-agnostic embeddings generation.\"\"\"\n\nfrom .client import (\n EmbeddingsClient,\n LiteLLMClient,\n SentenceTransformersClient,\n create_embeddings_client,\n)\n\n__all__ = [\n \"EmbeddingsClient\",\n \"SentenceTransformersClient\",\n \"LiteLLMClient\",\n \"create_embeddings_client\",\n]\n" }, { "path": "registry/embeddings/client.py", "content": "\"\"\"\nEmbeddings client abstraction for vendor-agnostic embeddings generation.\n\nThis module provides a unified interface for generating embeddings from multiple\nproviders including local sentence-transformers models and cloud-based APIs via LiteLLM.\n\"\"\"\n\nimport logging\nimport os\nfrom abc import (\n ABC,\n abstractmethod,\n)\nfrom pathlib import Path\n\nimport numpy as np\n\nlogger = logging.getLogger(__name__)\n\n\nclass EmbeddingsClient(ABC):\n \"\"\"Abstract base class for embeddings generation clients.\"\"\"\n\n @abstractmethod\n def encode(\n self,\n texts: list[str],\n ) -> np.ndarray:\n \"\"\"\n Generate embeddings for a list of texts.\n\n Args:\n texts: List of text strings to encode\n\n Returns:\n NumPy array of embeddings with shape (len(texts), embedding_dimension)\n\n Raises:\n RuntimeError: If encoding fails\n \"\"\"\n pass\n\n @abstractmethod\n def get_embedding_dimension(self) -> int:\n \"\"\"\n Get the dimension of embeddings produced by this client.\n\n Returns:\n Integer dimension of embedding vectors\n \"\"\"\n pass\n\n\nclass SentenceTransformersClient(EmbeddingsClient):\n \"\"\"Client for local sentence-transformers models.\"\"\"\n\n def __init__(\n self,\n model_name: str,\n model_dir: Path | None = None,\n cache_dir: Path | None = None,\n ):\n \"\"\"\n Initialize the SentenceTransformers client.\n\n Args:\n model_name: Name of the sentence-transformers model\n model_dir: Optional local directory containing the model\n cache_dir: Optional cache directory for downloaded models\n \"\"\"\n self.model_name = model_name\n self.model_dir = model_dir\n self.cache_dir = cache_dir\n self._model: SentenceTransformer | None = None\n self._dimension: int | None = None\n self._load_error: RuntimeError | None = None\n\n def _load_model(self) -> None:\n \"\"\"Load the sentence-transformers model.\"\"\"\n if self._model is not None:\n return\n\n # If a previous load attempt failed, raise the cached error immediately\n # to avoid repeated download attempts (e.g., hitting HuggingFace on every call)\n if self._load_error is not None:\n raise self._load_error\n\n try:\n from sentence_transformers import SentenceTransformer\n\n # Set cache directory if provided\n original_st_home = os.environ.get(\"SENTENCE_TRANSFORMERS_HOME\")\n if self.cache_dir:\n self.cache_dir.mkdir(parents=True, exist_ok=True)\n os.environ[\"SENTENCE_TRANSFORMERS_HOME\"] = str(self.cache_dir)\n\n # Check if local model exists\n model_exists = (\n self.model_dir.exists() and any(self.model_dir.iterdir())\n if self.model_dir and self.model_dir.exists()\n else False\n )\n\n if model_exists:\n logger.info(f\"Loading SentenceTransformer model from local path: {self.model_dir}\")\n self._model = SentenceTransformer(str(self.model_dir))\n else:\n logger.info(\n f\"Local model not found, downloading from Hugging Face: {self.model_name}\"\n )\n self._model = SentenceTransformer(self.model_name)\n\n # Restore original environment variable\n if original_st_home:\n os.environ[\"SENTENCE_TRANSFORMERS_HOME\"] = original_st_home\n elif \"SENTENCE_TRANSFORMERS_HOME\" in os.environ:\n del os.environ[\"SENTENCE_TRANSFORMERS_HOME\"]\n\n # Get embedding dimension\n self._dimension = self._model.get_sentence_embedding_dimension()\n\n logger.info(\n f\"SentenceTransformer model loaded successfully. Dimension: {self._dimension}\"\n )\n\n except Exception as e:\n logger.error(f\"Failed to load SentenceTransformer model: {e}\", exc_info=True)\n self._load_error = RuntimeError(f\"Failed to load SentenceTransformer model: {e}\")\n raise self._load_error from e\n\n def encode(\n self,\n texts: list[str],\n ) -> np.ndarray:\n \"\"\"\n Generate embeddings using sentence-transformers.\n\n Args:\n texts: List of text strings to encode\n\n Returns:\n NumPy array of embeddings\n\n Raises:\n RuntimeError: If encoding fails\n \"\"\"\n if self._model is None:\n self._load_model()\n\n try:\n embeddings = self._model.encode(texts)\n return np.array(embeddings, dtype=np.float32)\n except Exception as e:\n logger.error(f\"Failed to encode texts: {e}\", exc_info=True)\n raise RuntimeError(f\"Failed to encode texts: {e}\") from e\n\n def get_embedding_dimension(self) -> int:\n \"\"\"\n Get the embedding dimension.\n\n Returns:\n Integer dimension of embedding vectors\n\n Raises:\n RuntimeError: If model is not loaded\n \"\"\"\n if self._dimension is None:\n self._load_model()\n return self._dimension\n\n\nclass LiteLLMClient(EmbeddingsClient):\n \"\"\"Client for cloud-based embeddings via LiteLLM.\"\"\"\n\n def __init__(\n self,\n model_name: str,\n api_key: str | None = None,\n api_base: str | None = None,\n aws_region: str | None = None,\n embedding_dimension: int | None = None,\n ):\n \"\"\"\n Initialize the LiteLLM client.\n\n Args:\n model_name: LiteLLM model identifier (e.g., 'bedrock/amazon.titan-embed-text-v1',\n 'openai/text-embedding-3-small', 'cohere/embed-english-v3.0')\n api_key: Optional API key for the provider\n api_base: Optional API base URL for the provider\n aws_region: Optional AWS region for Bedrock\n embedding_dimension: Expected embedding dimension (will be validated)\n\n Note:\n For AWS Bedrock, this client uses the standard AWS credential chain\n (IAM roles, ~/.aws/credentials, environment variables). The api_key\n parameter is not used for Bedrock authentication.\n \"\"\"\n self.model_name = model_name\n self.api_key = api_key\n self.api_base = api_base\n self.aws_region = aws_region\n self._embedding_dimension = embedding_dimension\n self._validated_dimension: int | None = None\n\n # Set environment variables for LiteLLM\n if self.api_key:\n self._set_api_key_env()\n if self.aws_region:\n os.environ[\"AWS_REGION_NAME\"] = self.aws_region\n\n def _set_api_key_env(self) -> None:\n \"\"\"Set the appropriate API key environment variable based on provider.\"\"\"\n provider = self.model_name.split(\"/\")[0].lower()\n\n # AWS Bedrock uses standard AWS credential chain (IAM roles, env vars, ~/.aws/credentials)\n # No need to set API key environment variable for Bedrock\n if provider == \"bedrock\":\n logger.info(\"Using standard AWS credential chain for Bedrock authentication\")\n return\n\n # Handle other providers with API keys\n env_var_mapping = {\n \"openai\": \"OPENAI_API_KEY\",\n \"cohere\": \"COHERE_API_KEY\",\n \"azure\": \"AZURE_API_KEY\",\n \"anthropic\": \"ANTHROPIC_API_KEY\",\n }\n\n env_var = env_var_mapping.get(provider)\n if env_var and self.api_key:\n os.environ[env_var] = self.api_key\n logger.debug(f\"Set {env_var} environment variable for {provider}\")\n\n def encode(\n self,\n texts: list[str],\n ) -> np.ndarray:\n \"\"\"\n Generate embeddings using LiteLLM.\n\n Args:\n texts: List of text strings to encode\n\n Returns:\n NumPy array of embeddings\n\n Raises:\n RuntimeError: If encoding fails or LiteLLM is not installed\n \"\"\"\n try:\n from litellm import embedding\n except ImportError as e:\n logger.error(\"LiteLLM is not installed. Install it with: uv add litellm\")\n raise RuntimeError(\"LiteLLM is not installed. Install it with: uv add litellm\") from e\n\n try:\n # LiteLLM expects 'input' parameter\n kwargs = {\"model\": self.model_name, \"input\": texts}\n\n if self.api_base:\n kwargs[\"api_base\"] = self.api_base\n\n logger.debug(f\"Calling LiteLLM embedding API with model: {self.model_name}\")\n response = embedding(**kwargs)\n\n # Extract embeddings from response\n embeddings_list = [item[\"embedding\"] for item in response[\"data\"]]\n embeddings_array = np.array(embeddings_list, dtype=np.float32)\n\n # Validate dimension on first call\n if self._validated_dimension is None:\n self._validated_dimension = embeddings_array.shape[1]\n if (\n self._embedding_dimension\n and self._validated_dimension != self._embedding_dimension\n ):\n logger.warning(\n f\"Embedding dimension mismatch: expected {self._embedding_dimension}, \"\n f\"got {self._validated_dimension}\"\n )\n\n logger.debug(\n f\"Generated {len(embeddings_list)} embeddings with dimension {self._validated_dimension}\"\n )\n return embeddings_array\n\n except Exception as e:\n logger.error(f\"Failed to generate embeddings via LiteLLM: {e}\", exc_info=True)\n raise RuntimeError(f\"Failed to generate embeddings via LiteLLM: {e}\") from e\n\n def get_embedding_dimension(self) -> int:\n \"\"\"\n Get the embedding dimension.\n\n Returns:\n Integer dimension of embedding vectors\n\n Raises:\n RuntimeError: If dimension cannot be determined\n \"\"\"\n # If we have a validated dimension from actual API calls, use that\n if self._validated_dimension is not None:\n return self._validated_dimension\n\n # Otherwise, use the configured dimension if provided\n if self._embedding_dimension is not None:\n return self._embedding_dimension\n\n # As a last resort, make a test call with a simple string\n logger.info(\"Embedding dimension not known, making test call to determine dimension\")\n try:\n test_embedding = self.encode([\"test\"])\n return test_embedding.shape[1]\n except Exception as e:\n logger.error(f\"Failed to determine embedding dimension: {e}\", exc_info=True)\n raise RuntimeError(\n f\"Failed to determine embedding dimension: {e}. \"\n \"Consider setting EMBEDDINGS_DIMENSION in configuration.\"\n ) from e\n\n\ndef create_embeddings_client(\n provider: str,\n model_name: str,\n model_dir: Path | None = None,\n cache_dir: Path | None = None,\n api_key: str | None = None,\n api_base: str | None = None,\n aws_region: str | None = None,\n embedding_dimension: int | None = None,\n) -> EmbeddingsClient:\n \"\"\"\n Factory function to create an embeddings client based on provider.\n\n Args:\n provider: Provider type ('sentence-transformers' or 'litellm')\n model_name: Model identifier\n model_dir: Optional local model directory (sentence-transformers only)\n cache_dir: Optional cache directory (sentence-transformers only)\n api_key: Optional API key (litellm only)\n api_base: Optional API base URL (litellm only)\n aws_region: Optional AWS region (litellm with Bedrock only)\n embedding_dimension: Optional embedding dimension\n\n Returns:\n EmbeddingsClient instance\n\n Raises:\n ValueError: If provider is not supported\n\n Note:\n For AWS Bedrock, AWS credentials should be configured via standard AWS\n credential chain (IAM roles, environment variables, ~/.aws/credentials).\n \"\"\"\n provider_lower = provider.lower()\n\n if provider_lower == \"sentence-transformers\":\n logger.info(f\"Creating SentenceTransformersClient with model: {model_name}\")\n return SentenceTransformersClient(\n model_name=model_name,\n model_dir=model_dir,\n cache_dir=cache_dir,\n )\n\n elif provider_lower == \"litellm\":\n # Validate that model name has provider prefix\n if \"/\" not in model_name:\n raise ValueError(\n f\"Invalid model name for LiteLLM provider: '{model_name}'. \"\n f\"LiteLLM requires provider-prefixed model names. \"\n f\"Examples: 'openai/text-embedding-3-small', 'bedrock/amazon.titan-embed-text-v1', \"\n f\"'cohere/embed-english-v3.0'. \"\n f\"If you want to use '{model_name}', set EMBEDDINGS_PROVIDER=sentence-transformers\"\n )\n\n logger.info(f\"Creating LiteLLMClient with model: {model_name}\")\n return LiteLLMClient(\n model_name=model_name,\n api_key=api_key,\n api_base=api_base,\n aws_region=aws_region,\n embedding_dimension=embedding_dimension,\n )\n\n else:\n raise ValueError(\n f\"Unsupported embeddings provider: {provider}. \"\n \"Supported providers: 'sentence-transformers', 'litellm'\"\n )\n" }, { "path": "registry/exceptions.py", "content": "\"\"\"\nDomain-specific exceptions for the MCP Gateway Registry.\n\nThis module contains custom exception classes for various operations\nincluding skill management, agent management, and server operations.\n\"\"\"\n\n\nclass RegistryError(Exception):\n \"\"\"Base exception for all registry operations.\"\"\"\n\n pass\n\n\n# Skill-specific exceptions\n\n\nclass SkillRegistryError(RegistryError):\n \"\"\"Base exception for skill operations.\"\"\"\n\n pass\n\n\nclass SkillNotFoundError(SkillRegistryError):\n \"\"\"Skill does not exist.\"\"\"\n\n def __init__(\n self,\n path: str,\n ):\n self.path = path\n super().__init__(f\"Skill not found: {path}\")\n\n\nclass SkillAlreadyExistsError(SkillRegistryError):\n \"\"\"Skill with this name already exists.\"\"\"\n\n def __init__(\n self,\n name: str,\n ):\n self.name = name\n super().__init__(f\"Skill '{name}' already exists\")\n\n\nclass SkillValidationError(SkillRegistryError):\n \"\"\"Skill data failed validation.\"\"\"\n\n pass\n\n\nclass SkillServiceError(SkillRegistryError):\n \"\"\"Internal service error during skill operation.\"\"\"\n\n pass\n\n\nclass SkillUrlValidationError(SkillRegistryError):\n \"\"\"SKILL.md URL validation failed.\"\"\"\n\n def __init__(\n self,\n url: str,\n reason: str,\n ):\n self.url = url\n self.reason = reason\n super().__init__(f\"Invalid SKILL.md URL '{url}': {reason}\")\n\n\n# Agent-specific exceptions\n\n\nclass AgentRegistryError(RegistryError):\n \"\"\"Base exception for agent operations.\"\"\"\n\n pass\n\n\nclass AgentNotFoundError(AgentRegistryError):\n \"\"\"Agent does not exist.\"\"\"\n\n def __init__(\n self,\n path: str,\n ):\n self.path = path\n super().__init__(f\"Agent not found: {path}\")\n\n\nclass AgentAlreadyExistsError(AgentRegistryError):\n \"\"\"Agent with this path already exists.\"\"\"\n\n def __init__(\n self,\n path: str,\n ):\n self.path = path\n super().__init__(f\"Agent already exists at path: {path}\")\n\n\n# Server-specific exceptions\n\n\nclass ServerRegistryError(RegistryError):\n \"\"\"Base exception for server operations.\"\"\"\n\n pass\n\n\nclass ServerNotFoundError(ServerRegistryError):\n \"\"\"Server does not exist.\"\"\"\n\n def __init__(\n self,\n path: str,\n ):\n self.path = path\n super().__init__(f\"Server not found: {path}\")\n\n\nclass ServerAlreadyExistsError(ServerRegistryError):\n \"\"\"Server with this path already exists.\"\"\"\n\n def __init__(\n self,\n path: str,\n ):\n self.path = path\n super().__init__(f\"Server already exists at path: {path}\")\n\n\n# Virtual Server-specific exceptions\n\n\nclass VirtualServerRegistryError(RegistryError):\n \"\"\"Base exception for virtual server operations.\"\"\"\n\n pass\n\n\nclass VirtualServerNotFoundError(VirtualServerRegistryError):\n \"\"\"Virtual server does not exist.\"\"\"\n\n def __init__(\n self,\n path: str,\n ):\n self.path = path\n super().__init__(f\"Virtual server not found: {path}\")\n\n\nclass VirtualServerAlreadyExistsError(VirtualServerRegistryError):\n \"\"\"Virtual server with this path already exists.\"\"\"\n\n def __init__(\n self,\n path: str,\n ):\n self.path = path\n super().__init__(f\"Virtual server already exists at path: {path}\")\n\n\nclass VirtualServerValidationError(VirtualServerRegistryError):\n \"\"\"Virtual server data failed validation.\"\"\"\n\n pass\n\n\nclass VirtualServerServiceError(VirtualServerRegistryError):\n \"\"\"Internal service error during virtual server operation.\"\"\"\n\n pass\n\n\n# Skill content fetch exceptions\n\n\nclass SkillContentFetchError(SkillRegistryError):\n \"\"\"Failed to fetch skill content from a remote URL.\"\"\"\n\n def __init__(\n self,\n url: str,\n reason: str,\n status_code: int = 502,\n ):\n self.url = url\n self.reason = reason\n self.status_code = status_code\n super().__init__(f\"Failed to fetch content from '{url}': {reason}\")\n\n\nclass SkillContentSSRFError(SkillRegistryError):\n \"\"\"URL failed SSRF validation.\"\"\"\n\n def __init__(\n self,\n url: str,\n ):\n self.url = url\n super().__init__(\n f\"URL failed SSRF validation: {url}\"\n )\n\n\nclass SkillContentTooLargeError(SkillRegistryError):\n \"\"\"Fetched content exceeds the size limit.\"\"\"\n\n def __init__(\n self,\n max_size: int,\n ):\n self.max_size = max_size\n super().__init__(\n f\"Content exceeds {max_size // 1024} KB limit\"\n )\n\n\n# Registration Gate exceptions\n\n\nclass RegistrationGateError(RegistryError):\n \"\"\"Base exception for registration gate operations.\"\"\"\n\n pass\n\n\nclass RegistrationGateDeniedError(RegistrationGateError):\n \"\"\"Registration was denied by the gate endpoint.\"\"\"\n\n def __init__(\n self,\n reason: str,\n ):\n self.reason = reason\n super().__init__(f\"Registration denied by policy gate: {reason}\")\n\n\nclass RegistrationGateUnavailableError(RegistrationGateError):\n \"\"\"Gate endpoint is unreachable or returned an unexpected error.\"\"\"\n\n def __init__(\n self,\n detail: str,\n ):\n self.detail = detail\n super().__init__(\n f\"Registration gate is unavailable: {detail}. \"\n f\"Registration blocked (fail-closed policy).\"\n )\n" }, { "path": "registry/health/__init__.py", "content": "" }, { "path": "registry/health/routes.py", "content": "import asyncio\nimport logging\n\nfrom fastapi import APIRouter, WebSocket, WebSocketDisconnect\nfrom itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer\n\nfrom ..core.config import settings\nfrom .service import health_service\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n# Initialize session signer for WebSocket authentication\nsigner = URLSafeTimedSerializer(settings.secret_key)\n\n\n@router.websocket(\"/ws/health_status\")\nasync def websocket_endpoint(websocket: WebSocket):\n \"\"\"High-performance WebSocket endpoint for real-time health status updates with authentication.\"\"\"\n connection_added = False\n try:\n # WebSocket cookies are automatically included in handshake\n # Validate session before accepting connection\n session_cookie = None\n\n # Debug: Log WebSocket connection attempt\n logger.info(f\"WebSocket connection attempt from {websocket.client}\")\n\n # Try different ways to access cookies from WebSocket\n if hasattr(websocket, \"cookies\") and websocket.cookies:\n session_cookie = websocket.cookies.get(settings.session_cookie_name)\n logger.debug(\n f\"WebSocket cookies found via websocket.cookies: {list(websocket.cookies.keys())}\"\n )\n\n # Alternative: Try to get cookies from headers\n if not session_cookie and hasattr(websocket, \"headers\"):\n cookie_header = websocket.headers.get(\"cookie\", \"\")\n if cookie_header:\n logger.debug(f\"WebSocket cookie header: {cookie_header}\")\n # Parse cookie header manually\n cookies = {}\n for cookie_pair in cookie_header.split(\";\"):\n if \"=\" in cookie_pair:\n name, value = cookie_pair.strip().split(\"=\", 1)\n cookies[name] = value\n session_cookie = cookies.get(settings.session_cookie_name)\n\n # Alternative: Try to get from query parameters as fallback\n if not session_cookie and hasattr(websocket, \"query_params\"):\n session_cookie = websocket.query_params.get(settings.session_cookie_name)\n\n logger.debug(f\"WebSocket session cookie found: {bool(session_cookie)}\")\n\n if session_cookie:\n try:\n # Validate session\n session_data = signer.loads(\n session_cookie, max_age=settings.session_max_age_seconds\n )\n username = session_data.get(\"username\")\n if username:\n logger.info(f\"WebSocket connection from authenticated user: {username}\")\n else:\n raise ValueError(\"No username in session\")\n except (SignatureExpired, BadSignature, ValueError) as e:\n logger.warning(f\"WebSocket authentication failed: {e}\")\n await websocket.close(code=1008, reason=\"Authentication failed\")\n return\n except Exception as e:\n logger.warning(f\"WebSocket authentication error: {e}\")\n await websocket.close(code=1008, reason=\"Authentication failed\")\n return\n else:\n logger.warning(\n f\"WebSocket connection without valid session cookie from {websocket.client}\"\n )\n await websocket.close(code=1008, reason=\"Authentication required\")\n return\n\n # Accept connection after successful authentication\n connection_added = await health_service.add_websocket_connection(websocket)\n if not connection_added:\n return # Connection rejected (server at capacity)\n\n # Keep connection open and handle client messages\n while True:\n # We don't expect messages from client, but keep alive\n # Add timeout to prevent hanging on slow clients\n try:\n await asyncio.wait_for(websocket.receive_text(), timeout=30.0)\n except TimeoutError:\n # Send ping to keep connection alive\n await websocket.ping()\n\n except WebSocketDisconnect:\n logger.debug(f\"WebSocket client disconnected: {websocket.client}\")\n except Exception as e:\n logger.warning(f\"WebSocket error for {websocket.client}: {e}\")\n finally:\n if connection_added:\n await health_service.remove_websocket_connection(websocket)\n\n\n@router.get(\"/ws/health_status\")\nasync def health_status_http():\n \"\"\"HTTP endpoint that returns the same health status data as the WebSocket endpoint.\n\n This handles cases where health checks are done via HTTP GET instead of WebSocket.\n \"\"\"\n return await health_service.get_all_health_status()\n\n\n@router.get(\"/ws/stats\")\nasync def websocket_stats():\n \"\"\"Get WebSocket performance statistics for monitoring.\"\"\"\n return health_service.get_websocket_stats()\n" }, { "path": "registry/health/service.py", "content": "import asyncio\nimport json\nimport logging\nimport os\nfrom datetime import UTC, datetime\nfrom time import time\n\nimport httpx\nfrom fastapi import WebSocket\n\nfrom registry.constants import HealthStatus\n\nfrom ..core.config import settings\nfrom ..core.endpoint_utils import get_endpoint_url_from_server_info\n\nlogger = logging.getLogger(__name__)\n\n\nclass HighPerformanceWebSocketManager:\n \"\"\"High-performance WebSocket manager for 400-1000+ concurrent connections.\"\"\"\n\n def __init__(self):\n self.connections: set[WebSocket] = set()\n self.connection_metadata: dict[WebSocket, dict] = {}\n\n # Rate limiting and batching\n self.pending_updates: dict[str, dict] = {} # service_path -> latest_data\n self.last_broadcast_time = 0\n self.min_broadcast_interval = settings.websocket_broadcast_interval_ms / 1000.0\n self.max_batch_size = settings.websocket_max_batch_size\n\n # Connection health tracking\n self.failed_connections: set[WebSocket] = set()\n self.cleanup_task: asyncio.Task | None = None\n\n # Performance metrics\n self.broadcast_count = 0\n self.failed_send_count = 0\n\n async def add_connection(self, websocket: WebSocket) -> bool:\n \"\"\"Add a new WebSocket connection with connection limits.\"\"\"\n try:\n # Connection limit for memory management\n if len(self.connections) >= settings.max_websocket_connections:\n logger.warning(f\"Connection limit reached: {len(self.connections)}\")\n await websocket.close(code=1008, reason=\"Server at capacity\")\n return False\n\n await websocket.accept()\n self.connections.add(websocket)\n self.connection_metadata[websocket] = {\n \"connected_at\": time(),\n \"last_ping\": time(),\n \"client_ip\": getattr(websocket.client, \"host\", \"unknown\")\n if websocket.client\n else \"unknown\",\n }\n\n logger.debug(f\"WebSocket connected: {len(self.connections)} total connections\")\n\n # Send initial status efficiently\n await self._send_initial_status_optimized(websocket)\n return True\n\n except Exception as e:\n logger.error(f\"Error adding WebSocket connection: {e}\")\n return False\n\n async def remove_connection(self, websocket: WebSocket):\n \"\"\"Remove a WebSocket connection.\"\"\"\n self.connections.discard(websocket)\n self.connection_metadata.pop(websocket, None)\n self.failed_connections.discard(websocket)\n\n logger.debug(f\"WebSocket disconnected: {len(self.connections)} total connections\")\n\n async def _send_initial_status_optimized(self, websocket: WebSocket):\n \"\"\"Send initial status using cached data to avoid blocking.\"\"\"\n try:\n # Use cached health data to avoid blocking on service calls\n cached_data = await health_service._get_cached_health_data()\n if cached_data:\n await websocket.send_text(json.dumps(cached_data))\n except Exception as e:\n logger.warning(f\"Failed to send initial status: {e}\")\n await self.remove_connection(websocket)\n\n async def broadcast_update(\n self, service_path: str | None = None, health_data: dict | None = None\n ):\n \"\"\"High-performance broadcasting with batching and rate limiting.\"\"\"\n if not self.connections:\n return\n\n current_time = time()\n\n # Rate limiting: prevent too frequent broadcasts\n if current_time - self.last_broadcast_time < self.min_broadcast_interval:\n # Queue the update for later batch processing\n if service_path and health_data:\n self.pending_updates[service_path] = health_data\n return\n\n # Prepare broadcast data\n if service_path and health_data:\n # Single service update\n broadcast_data = {service_path: health_data}\n else:\n # Batch updates or full status\n if self.pending_updates:\n # Send pending updates in batches\n batch_data = dict(list(self.pending_updates.items())[: self.max_batch_size])\n broadcast_data = batch_data\n # Remove sent items from pending\n for key in batch_data.keys():\n self.pending_updates.pop(key, None)\n else:\n # Full status update (avoid this when possible)\n broadcast_data = await health_service._get_cached_health_data()\n\n if broadcast_data:\n await self._send_to_connections_optimized(broadcast_data)\n self.last_broadcast_time = current_time\n\n async def _send_to_connections_optimized(self, data: dict):\n \"\"\"Optimized concurrent sending with automatic cleanup.\"\"\"\n if not self.connections:\n return\n\n message = json.dumps(data)\n connections_list = list(self.connections) # Snapshot for safe iteration\n\n # Split into chunks for better memory management with many connections\n chunk_size = 100 # Process 100 connections at a time\n\n for i in range(0, len(connections_list), chunk_size):\n chunk = connections_list[i : i + chunk_size]\n\n # Send to chunk concurrently\n tasks = [self._safe_send_message(conn, message) for conn in chunk]\n results = await asyncio.gather(*tasks, return_exceptions=True)\n\n # Track failed connections\n for conn, result in zip(chunk, results, strict=False):\n if isinstance(result, Exception):\n self.failed_connections.add(conn)\n self.failed_send_count += 1\n\n # Cleanup failed connections in batch (non-blocking)\n if self.failed_connections:\n asyncio.create_task(self._cleanup_failed_connections())\n\n self.broadcast_count += 1\n\n async def _safe_send_message(self, connection: WebSocket, message: str):\n \"\"\"Send message with timeout and error handling.\"\"\"\n try:\n # Use timeout to prevent hanging on slow connections\n await asyncio.wait_for(\n connection.send_text(message), timeout=settings.websocket_send_timeout_seconds\n )\n return True\n except TimeoutError:\n return TimeoutError(\"Send timeout\")\n except Exception as e:\n return e\n\n async def _cleanup_failed_connections(self):\n \"\"\"Cleanup failed connections without blocking main operations.\"\"\"\n failed_count = len(self.failed_connections)\n if failed_count == 0:\n return\n\n for conn in list(self.failed_connections):\n await self.remove_connection(conn)\n\n logger.info(f\"Cleaned up {failed_count} failed WebSocket connections\")\n\n def get_stats(self) -> dict:\n \"\"\"Get performance statistics.\"\"\"\n return {\n \"active_connections\": len(self.connections),\n \"pending_updates\": len(self.pending_updates),\n \"total_broadcasts\": self.broadcast_count,\n \"failed_sends\": self.failed_send_count,\n \"failed_connections\": len(self.failed_connections),\n }\n\n\nclass HealthMonitoringService:\n \"\"\"Optimized health monitoring service for high-scale WebSocket operations.\"\"\"\n\n def __init__(self):\n self.server_health_status: dict[str, str] = {}\n self.server_last_check_time: dict[str, datetime] = {}\n\n # High-performance WebSocket manager\n self.websocket_manager = HighPerformanceWebSocketManager()\n\n # Background task management\n self.health_check_task: asyncio.Task | None = None\n\n # Performance optimizations\n self._cached_health_data: dict = {}\n self._cache_timestamp = 0\n self._cache_ttl = settings.websocket_cache_ttl_seconds\n\n async def _check_secret_key_persistence(self):\n \"\"\"Warn if servers have encrypted credentials but SECRET_KEY is auto-generated.\"\"\"\n if os.environ.get(\"SECRET_KEY\"):\n return\n\n try:\n from ..services.server_service import server_service\n\n all_servers = await server_service.get_all_servers(include_credentials=True)\n servers_with_creds = [\n path for path, info in all_servers.items() if info.get(\"auth_credential_encrypted\")\n ]\n if servers_with_creds:\n logger.warning(\n f\"SECRET_KEY not explicitly set but {len(servers_with_creds)} \"\n f\"server(s) have encrypted credentials. Set SECRET_KEY in .env \"\n f\"to persist credentials across restarts.\"\n )\n except Exception as e:\n logger.debug(f\"Could not check encrypted credentials at startup: {e}\")\n\n async def initialize(self):\n \"\"\"Initialize the health monitoring service.\"\"\"\n logger.info(\"Initializing health monitoring service...\")\n\n # Check SECRET_KEY persistence for servers with encrypted credentials\n await self._check_secret_key_persistence()\n\n # Start background health checks\n self.health_check_task = asyncio.create_task(self._run_health_checks())\n\n logger.info(\"Health monitoring service initialized!\")\n\n async def shutdown(self):\n \"\"\"Shutdown the health monitoring service.\"\"\"\n # Cancel background tasks\n if self.health_check_task:\n self.health_check_task.cancel()\n try:\n await self.health_check_task\n except asyncio.CancelledError:\n pass\n\n # Close all WebSocket connections\n connections = list(self.websocket_manager.connections)\n close_tasks = []\n for conn in connections:\n try:\n close_tasks.append(conn.close())\n except Exception as e:\n logger.debug(f\"Error closing WebSocket connection during shutdown: {e}\")\n\n if close_tasks:\n await asyncio.gather(*close_tasks, return_exceptions=True)\n\n logger.info(\"Health monitoring service shutdown complete\")\n\n async def add_websocket_connection(self, websocket: WebSocket):\n \"\"\"Add a new WebSocket connection and send initial health status.\"\"\"\n success = await self.websocket_manager.add_connection(websocket)\n if success:\n logger.info(f\"WebSocket client connected: {websocket.client}\")\n return success\n\n async def remove_websocket_connection(self, websocket: WebSocket):\n \"\"\"Remove a WebSocket connection.\"\"\"\n await self.websocket_manager.remove_connection(websocket)\n logger.info(f\"WebSocket connection removed: {websocket.client}\")\n\n async def _send_initial_status(self, websocket: WebSocket):\n \"\"\"Send initial health status to a newly connected WebSocket client.\"\"\"\n # This method is kept for compatibility but delegates to the optimized manager\n await self.websocket_manager._send_initial_status_optimized(websocket)\n\n async def broadcast_health_update(self, service_path: str | None = None):\n \"\"\"Broadcast health status updates to all connected WebSocket clients.\"\"\"\n if not self.websocket_manager.connections:\n return\n\n from ..services.server_service import server_service\n\n if service_path:\n # Single service update - get data efficiently\n server_info = await server_service.get_server_info(service_path)\n if server_info:\n health_data = self._get_service_health_data_fast(service_path, server_info)\n await self.websocket_manager.broadcast_update(service_path, health_data)\n else:\n # Full update - use cached data\n await self.websocket_manager.broadcast_update()\n\n async def _get_cached_health_data(self) -> dict:\n \"\"\"Get cached health data to avoid expensive operations during WebSocket sends.\"\"\"\n current_time = time()\n\n # Return cached data if still valid\n if (current_time - self._cache_timestamp) < self._cache_ttl and self._cached_health_data:\n return self._cached_health_data\n\n # Rebuild cache\n from ..services.server_service import server_service\n\n all_servers = await server_service.get_all_servers()\n\n data = {}\n for path, server_info in all_servers.items():\n data[path] = self._get_service_health_data_fast(path, server_info)\n\n self._cached_health_data = data\n self._cache_timestamp = current_time\n return data\n\n def get_websocket_stats(self) -> dict:\n \"\"\"Get WebSocket performance statistics.\"\"\"\n return self.websocket_manager.get_stats()\n\n async def _run_health_checks(self):\n \"\"\"Background task to run periodic health checks.\"\"\"\n logger.info(\"Starting periodic health checks...\")\n\n while True:\n try:\n await self._perform_health_checks()\n await asyncio.sleep(settings.health_check_interval_seconds)\n except asyncio.CancelledError:\n logger.info(\"Health check task cancelled\")\n break\n except Exception as e:\n logger.error(f\"Error in health check loop: {e}\", exc_info=True)\n await asyncio.sleep(60) # Wait a minute before retrying\n\n async def _perform_health_checks(self):\n \"\"\"Perform health checks on all enabled services.\"\"\"\n import httpx\n\n from ..services.server_service import server_service\n\n enabled_services = await server_service.get_enabled_services()\n if not enabled_services:\n return\n\n # Only log if there are many services to avoid spam\n if len(enabled_services) > 1:\n logger.debug(f\"Performing health checks on {len(enabled_services)} enabled services\")\n\n # Track if any status changed to minimize broadcasts\n status_changed = False\n\n # Perform actual health checks concurrently for better performance\n async with httpx.AsyncClient(\n timeout=httpx.Timeout(settings.health_check_timeout_seconds)\n ) as client:\n # Batch process enabled services\n check_tasks = []\n for service_path in enabled_services:\n server_info = await server_service.get_server_info(\n service_path, include_credentials=True\n )\n if server_info and server_info.get(\"proxy_pass_url\"):\n check_tasks.append(\n self._check_single_service(client, service_path, server_info)\n )\n\n # Execute all health checks concurrently\n if check_tasks:\n results = await asyncio.gather(*check_tasks, return_exceptions=True)\n\n # Check if any status changed\n for result in results:\n if isinstance(result, bool) and result: # True indicates status changed\n status_changed = True\n break\n\n # Only broadcast if something actually changed\n if status_changed:\n await self.broadcast_health_update()\n\n # Regenerate nginx configuration when health status changes\n try:\n from ..core.nginx_service import nginx_service\n\n # Build enabled_servers dict with proper async/await\n enabled_servers = {}\n for path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(path)\n if server_info:\n enabled_servers[path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n logger.info(\"Nginx configuration regenerated due to health status changes\")\n except Exception as e:\n logger.error(\n f\"Failed to regenerate nginx configuration after health status change: {e}\"\n )\n\n async def _check_single_service(\n self, client: httpx.AsyncClient, service_path: str, server_info: dict\n ) -> bool:\n \"\"\"Check a single service and return True if status changed.\"\"\"\n\n proxy_pass_url = server_info.get(\"proxy_pass_url\")\n previous_status = self.server_health_status.get(service_path, HealthStatus.UNKNOWN)\n new_status = previous_status\n\n try:\n # Try to reach the service endpoint using transport-aware checking\n is_healthy, status_detail = await self._check_server_endpoint_transport_aware(\n client, proxy_pass_url, server_info\n )\n\n if is_healthy:\n new_status = status_detail # Could be \"healthy\" or \"healthy-auth-expired\"\n\n # Fetch tools in these cases:\n # 1. First health check (previous_status == UNKNOWN)\n # 2. Service transitioned to healthy from unhealthy\n # 3. Service is healthy but has no tools yet (tool_list is empty)\n # Only do this for fully healthy status, not auth-expired\n should_fetch_tools = False\n if status_detail == HealthStatus.HEALTHY:\n if previous_status == HealthStatus.UNKNOWN:\n # First health check - always fetch tools\n should_fetch_tools = True\n logger.info(f\"First health check for {service_path} - will fetch tools\")\n elif previous_status != HealthStatus.HEALTHY:\n # Transitioned to healthy - fetch tools\n should_fetch_tools = True\n logger.info(\n f\"Service {service_path} transitioned to healthy - will fetch tools\"\n )\n else:\n # Already healthy - only fetch if we don't have tools\n current_tool_list = server_info.get(\"tool_list\", [])\n if not current_tool_list:\n should_fetch_tools = True\n logger.info(\n f\"Service {service_path} is healthy but has no tools - will fetch tools\"\n )\n\n if should_fetch_tools:\n asyncio.create_task(self._update_tools_background(service_path, proxy_pass_url))\n else:\n new_status = status_detail # Detailed error message from transport check\n\n except httpx.TimeoutException:\n new_status = HealthStatus.UNHEALTHY_TIMEOUT\n except httpx.ConnectError:\n new_status = HealthStatus.UNHEALTHY_CONNECTION_ERROR\n except Exception as e:\n new_status = f\"error: {type(e).__name__}\"\n\n # Update status and timestamp\n self.server_health_status[service_path] = new_status\n self.server_last_check_time[service_path] = datetime.now(UTC)\n\n # Return True if status changed\n return previous_status != new_status\n\n def _build_headers_for_server(\n self, server_info: dict, include_session_id: bool = False\n ) -> dict[str, str]:\n \"\"\"\n Build HTTP headers for server requests by merging default headers with server-specific headers.\n\n Args:\n server_info: Server configuration dictionary\n include_session_id: Whether to generate and include Mcp-Session-Id header\n\n Returns:\n Merged headers dictionary\n \"\"\"\n import uuid\n\n # Start with default headers for MCP endpoints\n headers = {\n \"Accept\": \"application/json, text/event-stream\",\n \"Content-Type\": \"application/json\",\n }\n\n # Add session ID if requested (required by some MCP servers like Cloudflare)\n if include_session_id:\n session_id = str(uuid.uuid4())\n headers[\"Mcp-Session-Id\"] = session_id\n logger.debug(f\"Generated Mcp-Session-Id: {session_id}\")\n\n # Merge server-specific headers if present\n server_headers = server_info.get(\"headers\", [])\n if server_headers and isinstance(server_headers, list):\n for header_dict in server_headers:\n if isinstance(header_dict, dict):\n headers.update(header_dict)\n logger.debug(f\"Added server headers: {header_dict}\")\n\n # Inject auth header from encrypted credentials (if present)\n auth_scheme = server_info.get(\"auth_scheme\", \"none\")\n encrypted_credential = server_info.get(\"auth_credential_encrypted\")\n\n if auth_scheme != \"none\" and encrypted_credential:\n from ..utils.credential_encryption import decrypt_credential\n\n credential = decrypt_credential(encrypted_credential)\n if credential:\n if auth_scheme == \"bearer\":\n header_name = server_info.get(\"auth_header_name\", \"Authorization\")\n headers[header_name] = f\"Bearer {credential}\"\n logger.debug(\"Added Bearer auth header for health check\")\n elif auth_scheme == \"api_key\":\n header_name = server_info.get(\"auth_header_name\", \"X-API-Key\")\n headers[header_name] = credential\n logger.debug(f\"Added API key header '{header_name}' for health check\")\n else:\n logger.warning(\n f\"Could not decrypt credential for \"\n f\"'{server_info.get('path', 'unknown')}'. \"\n f\"Health check will proceed without auth.\"\n )\n\n return headers\n\n async def _initialize_mcp_session(\n self, client: httpx.AsyncClient, endpoint: str, headers: dict[str, str]\n ) -> str | None:\n \"\"\"\n Initialize an MCP session and retrieve the session ID from the server.\n\n Args:\n client: httpx AsyncClient instance\n endpoint: The MCP endpoint URL\n headers: Headers to send with the request\n\n Returns:\n Session ID string if successful, None otherwise\n \"\"\"\n import uuid\n\n try:\n # Send initialize request without session ID\n # The server will generate and return a session ID in the response header\n init_headers = headers.copy()\n\n initialize_payload = {\n \"jsonrpc\": \"2.0\",\n \"id\": \"0\",\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {},\n \"clientInfo\": {\"name\": \"mcp-gateway-registry\", \"version\": \"1.0.0\"},\n },\n }\n\n response = await client.post(\n endpoint,\n headers=init_headers,\n json=initialize_payload,\n timeout=httpx.Timeout(5.0),\n follow_redirects=True,\n )\n\n # Check if initialize succeeded\n if response.status_code not in [200, 201]:\n logger.warning(\n f\"MCP initialize failed for {endpoint}: \"\n f\"Status {response.status_code}, Response: {response.text[:200]}\"\n )\n return None\n\n # Get session ID from response headers (server-generated)\n server_session_id = response.headers.get(\"Mcp-Session-Id\") or response.headers.get(\n \"mcp-session-id\"\n )\n if server_session_id:\n logger.debug(f\"Server returned session ID: {server_session_id}\")\n return server_session_id\n else:\n # If server doesn't return a session ID, generate one for stateless servers\n client_session_id = str(uuid.uuid4())\n logger.debug(\n f\"Server did not return session ID, using client-generated: {client_session_id}\"\n )\n return client_session_id\n\n except Exception as e:\n logger.warning(f\"MCP initialize failed for {endpoint}: {e}\")\n return None\n\n async def _try_ping_without_auth(self, client: httpx.AsyncClient, endpoint: str) -> bool:\n \"\"\"\n Try a simple ping without authentication headers.\n Used as fallback when auth fails to determine if server is reachable.\n\n Args:\n client: httpx AsyncClient instance\n endpoint: The MCP endpoint URL to ping\n\n Returns:\n bool: True if server responds (indicating it's reachable but auth expired)\n \"\"\"\n import uuid\n\n try:\n # Minimal headers without auth but with session ID (required by some servers)\n headers = {\n \"Accept\": \"application/json\",\n \"Content-Type\": \"application/json\",\n \"Mcp-Session-Id\": str(uuid.uuid4()),\n }\n ping_payload = '{ \"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"ping\" }'\n\n response = await client.post(\n endpoint,\n headers=headers,\n content=ping_payload,\n timeout=httpx.Timeout(5.0),\n follow_redirects=True,\n )\n\n # Check if we get any valid response (even auth errors indicate server is up)\n if response.status_code in [200, 400, 401, 403]:\n logger.info(\n f\"Ping without auth succeeded for {endpoint} - server is reachable but auth may have expired\"\n )\n return True\n else:\n logger.warning(\n f\"Ping without auth failed for {endpoint}: Status {response.status_code}\"\n )\n return False\n\n except Exception as e:\n logger.warning(f\"Ping without auth failed for {endpoint}: {type(e).__name__} - {e}\")\n return False\n\n async def _check_server_endpoint_transport_aware(\n self, client: httpx.AsyncClient, proxy_pass_url: str, server_info: dict\n ) -> tuple[bool, str]:\n \"\"\"Check server endpoint using transport-aware logic.\n\n Returns:\n tuple[bool, str]: (is_healthy, status_detail)\n \"\"\"\n if not proxy_pass_url:\n return False, HealthStatus.UNHEALTHY_MISSING_PROXY_URL\n\n # Get transport information from server_info\n supported_transports = server_info.get(\"supported_transports\", [\"streamable-http\"])\n\n # If URL already has transport endpoint, use it directly\n # BUT skip this shortcut for streamable-http to ensure proper POST ping is used\n has_transport_in_url = (\n proxy_pass_url.endswith(\"/mcp\")\n or proxy_pass_url.endswith(\"/sse\")\n or \"/mcp/\" in proxy_pass_url\n or \"/sse/\" in proxy_pass_url\n )\n\n if has_transport_in_url and \"streamable-http\" not in supported_transports:\n logger.info(f\"[TRACE] Found transport endpoint in URL: {proxy_pass_url}\")\n logger.info(\n f\"[TRACE] URL contains /mcp: {'/mcp' in proxy_pass_url}, URL contains /sse: {'/sse' in proxy_pass_url}\"\n )\n try:\n # Build headers including server-specific headers\n headers = self._build_headers_for_server(server_info)\n # For SSE endpoints, use a shorter timeout since they start streaming immediately\n if proxy_pass_url.endswith(\"/sse\") or \"/sse/\" in proxy_pass_url:\n logger.info(\"[TRACE] Detected SSE endpoint in URL, using SSE-specific handling\")\n timeout = httpx.Timeout(connect=5.0, read=2.0, write=5.0, pool=5.0)\n try:\n response = await client.get(\n proxy_pass_url, headers=headers, follow_redirects=True, timeout=timeout\n )\n return self._is_mcp_endpoint_healthy(response)\n except (TimeoutError, httpx.TimeoutException) as e:\n # For SSE endpoints, timeout while reading streaming response is normal after getting 200 OK\n logger.debug(\n f\"SSE endpoint {proxy_pass_url} timed out while streaming (expected): {e}\"\n )\n # If we can extract status code from response, check if it was 200\n if hasattr(e, \"response\") and e.response and e.response.status_code == 200:\n logger.debug(\n f\"SSE endpoint {proxy_pass_url} returned 200 OK before timeout - considering healthy\"\n )\n return True, HealthStatus.HEALTHY\n # For SSE, timeout after initial connection usually means server is responding\n return True, HealthStatus.HEALTHY\n except Exception as e:\n logger.warning(\n f\"SSE endpoint {proxy_pass_url} failed with exception: {type(e).__name__} - {e}\"\n )\n return False, f\"unhealthy: {type(e).__name__}\"\n else:\n logger.info(\n \"[TRACE] Detected MCP endpoint in URL, using standard HTTP handling\"\n )\n response = await client.get(\n proxy_pass_url, headers=headers, follow_redirects=True\n )\n\n # Check for auth failures first\n if response.status_code in [401, 403]:\n logger.info(\n f\"[TRACE] Auth failure detected ({response.status_code}) for {proxy_pass_url}, trying ping without auth\"\n )\n if await self._try_ping_without_auth(client, proxy_pass_url):\n return True, HealthStatus.HEALTHY\n else:\n return False, \"unhealthy: auth failed and ping without auth failed\"\n\n if self._is_mcp_endpoint_healthy(response):\n return True, HealthStatus.HEALTHY\n else:\n return False, f\"unhealthy: status {response.status_code}\"\n except Exception as e:\n logger.warning(\n f\"Health check failed for {proxy_pass_url}: {type(e).__name__} - {e}\"\n )\n return False, f\"unhealthy: {type(e).__name__}\"\n\n # Skip health checks for stdio transport (as requested)\n if supported_transports == [\"stdio\"]:\n logger.info(f\"[TRACE] Skipping health check for stdio transport: {proxy_pass_url}\")\n return True, HealthStatus.UNKNOWN\n\n # Try endpoints based on supported transports, prioritizing streamable-http\n logger.info(f\"[TRACE] No transport endpoint in URL: {proxy_pass_url}\")\n logger.info(f\"[TRACE] Supported transports: {supported_transports}\")\n\n # Try streamable-http first (default preference)\n if \"streamable-http\" in supported_transports:\n logger.info(\"[TRACE] Trying streamable-http transport\")\n # Build base headers without session ID\n headers = self._build_headers_for_server(server_info, include_session_id=False)\n\n # Resolve endpoint URL using centralized utility\n # Priority: explicit mcp_endpoint > URL detection > append /mcp\n endpoint = get_endpoint_url_from_server_info(\n server_info, transport_type=\"streamable-http\"\n )\n logger.info(f\"[TRACE] Resolved streamable-http endpoint: {endpoint}\")\n\n try:\n # Step 1: Initialize session to get session ID\n logger.info(f\"[TRACE] Initializing MCP session for endpoint: {endpoint}\")\n session_id = await self._initialize_mcp_session(client, endpoint, headers)\n\n # If initialize failed, check if it was due to auth (401/403)\n # Try ping without auth before giving up\n if not session_id:\n logger.warning(\n f\"Failed to initialize MCP session for {endpoint}, trying ping without auth\"\n )\n if await self._try_ping_without_auth(client, endpoint):\n return True, HealthStatus.HEALTHY\n else:\n return (\n False,\n \"unhealthy: session initialization failed and ping without auth failed\",\n )\n\n # Step 2: Add session ID to headers for ping\n headers[\"Mcp-Session-Id\"] = session_id\n ping_payload = '{ \"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"ping\" }'\n\n logger.info(f\"[TRACE] Sending ping to endpoint: {endpoint}\")\n logger.info(f\"[TRACE] Headers being sent: {self._mask_sensitive_headers(headers)}\")\n response = await client.post(\n endpoint, headers=headers, content=ping_payload, follow_redirects=True\n )\n logger.info(f\"[TRACE] Response status: {response.status_code}\")\n\n # Check for auth failures first\n if response.status_code in [401, 403]:\n logger.info(\n f\"[TRACE] Auth failure detected ({response.status_code}) for {endpoint}, trying ping without auth\"\n )\n if await self._try_ping_without_auth(client, endpoint):\n # ============================================================================\n # TEMPORARY WORKAROUND - TODO: REVERT AFTER CREDENTIALS MANAGER IS IMPLEMENTED\n # ============================================================================\n # Issue: https://github.com/agentic-community/mcp-gateway-registry/issues/167\n #\n # Temporarily marking servers with auth failures as \"healthy\" instead of\n # \"healthy-auth-expired\" to avoid confusing users when servers are registered\n # with auth requirements but no credentials manager is in place yet.\n #\n # This allows servers like customer-support-assistant (Bedrock AgentCore) to\n # show as healthy when they respond to ping, even though live tool fetching\n # requires authentication.\n #\n # BEFORE CREDENTIALS MANAGER: Return healthy (current behavior)\n # AFTER CREDENTIALS MANAGER: Return healthy-auth-expired (proper behavior)\n #\n # When the credentials manager container is implemented (see design doc at\n # .scratchpad/credentials-manager-design.md), this should be changed back to:\n # return True, HealthStatus.HEALTHY_AUTH_EXPIRED\n # ============================================================================\n return (\n True,\n HealthStatus.HEALTHY,\n ) # TODO: Change back to HEALTHY_AUTH_EXPIRED\n else:\n return False, \"unhealthy: auth failed and ping without auth failed\"\n\n # Check normal health status\n if self._is_mcp_endpoint_healthy_streamable(response):\n logger.info(f\"Health check succeeded at {endpoint}\")\n return True, HealthStatus.HEALTHY\n else:\n logger.warning(\n f\"Health check failed for {endpoint}: Status {response.status_code}, Response: {response.text}\"\n )\n return False, f\"unhealthy: status {response.status_code}\"\n\n except Exception as e:\n logger.warning(f\"Health check failed for {endpoint}: {type(e).__name__} - {e}\")\n return False, f\"unhealthy: {type(e).__name__}\"\n\n # Fallback to SSE\n if \"sse\" in supported_transports:\n logger.info(\"[TRACE] Trying SSE transport\")\n try:\n # Resolve SSE endpoint URL using centralized utility\n # Priority: explicit sse_endpoint > URL detection > append /sse\n sse_endpoint = get_endpoint_url_from_server_info(server_info, transport_type=\"sse\")\n logger.info(f\"[TRACE] Resolved SSE endpoint: {sse_endpoint}\")\n # Build headers including server-specific headers\n headers = self._build_headers_for_server(server_info)\n # Use shorter timeout for SSE since it starts streaming immediately\n timeout = httpx.Timeout(connect=5.0, read=2.0, write=5.0, pool=5.0)\n response = await client.get(\n sse_endpoint, headers=headers, follow_redirects=True, timeout=timeout\n )\n if self._is_mcp_endpoint_healthy(response):\n return True, HealthStatus.HEALTHY\n except (TimeoutError, httpx.TimeoutException) as e:\n # For SSE endpoints, timeout while reading streaming response is normal after getting 200 OK\n logger.info(\n f\"SSE endpoint {sse_endpoint} timed out while streaming (expected): {e}\"\n )\n # If we can extract status code from response, check if it was 200\n if hasattr(e, \"response\") and e.response and e.response.status_code == 200:\n logger.info(\n f\"SSE endpoint {sse_endpoint} returned 200 OK before timeout - considering healthy\"\n )\n return True, HealthStatus.HEALTHY\n # For SSE, timeout after initial connection usually means server is responding\n return True, \"healthy\"\n except Exception as e:\n logger.error(\n f\"SSE endpoint {sse_endpoint} failed with exception: {type(e).__name__} - {e}\"\n )\n pass\n\n # If no specific transports, try default streamable-http then sse\n if not supported_transports or supported_transports == []:\n logger.info(\"[TRACE] No specific transports defined, trying defaults\")\n headers = self._build_headers_for_server(server_info)\n\n # Resolve default streamable-http endpoint using centralized utility\n endpoint = get_endpoint_url_from_server_info(\n server_info, transport_type=\"streamable-http\"\n )\n logger.info(f\"[TRACE] Resolved default streamable-http endpoint: {endpoint}\")\n ping_payload = '{ \"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"ping\" }'\n\n try:\n logger.info(f\"[TRACE] Trying default endpoint: {endpoint}\")\n logger.info(f\"[TRACE] Headers being sent: {self._mask_sensitive_headers(headers)}\")\n response = await client.post(\n endpoint, headers=headers, content=ping_payload, follow_redirects=True\n )\n logger.info(f\"[TRACE] Response status: {response.status_code}\")\n if self._is_mcp_endpoint_healthy_streamable(response):\n logger.info(f\"Health check succeeded at {endpoint}\")\n return True, HealthStatus.HEALTHY\n else:\n logger.warning(\n f\"Health check failed for {endpoint}: Status {response.status_code}, Response: {response.text}\"\n )\n return False, f\"unhealthy: status {response.status_code}\"\n except Exception as e:\n logger.warning(f\"Health check failed for {endpoint}: {type(e).__name__} - {e}\")\n\n try:\n # Resolve default SSE endpoint using centralized utility\n sse_endpoint = get_endpoint_url_from_server_info(server_info, transport_type=\"sse\")\n logger.info(f\"[TRACE] Resolved default SSE endpoint: {sse_endpoint}\")\n # Build headers including server-specific headers\n headers = self._build_headers_for_server(server_info)\n # Use shorter timeout for SSE since it starts streaming immediately\n timeout = httpx.Timeout(connect=5.0, read=2.0, write=5.0, pool=5.0)\n response = await client.get(\n sse_endpoint, headers=headers, follow_redirects=True, timeout=timeout\n )\n if self._is_mcp_endpoint_healthy(response):\n return True, HealthStatus.HEALTHY\n except (TimeoutError, httpx.TimeoutException) as e:\n # For SSE endpoints, timeout while reading streaming response is normal after getting 200 OK\n logger.info(\n f\"SSE endpoint {sse_endpoint} timed out while streaming (expected): {e}\"\n )\n # If we can extract status code from response, check if it was 200\n if hasattr(e, \"response\") and e.response and e.response.status_code == 200:\n logger.info(\n f\"SSE endpoint {sse_endpoint} returned 200 OK before timeout - considering healthy\"\n )\n return True, HealthStatus.HEALTHY\n # For SSE, timeout after initial connection usually means server is responding\n return True, \"healthy\"\n except Exception as e:\n logger.error(\n f\"SSE endpoint {sse_endpoint} failed with exception: {type(e).__name__} - {e}\"\n )\n pass\n\n return False, \"unhealthy: all transport checks failed\"\n\n def _mask_sensitive_headers(self, headers: dict[str, str]) -> dict[str, str]:\n \"\"\"\n Mask sensitive authentication headers for logging.\n\n Args:\n headers: Dictionary of HTTP headers\n\n Returns:\n Dictionary with sensitive headers masked\n \"\"\"\n masked = headers.copy()\n sensitive_headers = [\"Authorization\", \"X-API-Key\", \"X-Api-Key\", \"Api-Key\"]\n\n for key in masked:\n # Check for common auth headers (case-insensitive)\n if key in sensitive_headers or key.lower() in [h.lower() for h in sensitive_headers]:\n masked[key] = \"***REDACTED***\"\n\n return masked\n\n def _is_mcp_endpoint_healthy_streamable(self, response) -> bool:\n \"\"\"\n Determine if a streamable-http MCP endpoint is healthy based on HTTP response.\n\n For streamable-http MCP endpoints, we consider them healthy if:\n 1. HTTP 200 OK - Normal successful response\n 2. HTTP 400 Bad Request with JSON-RPC error code -32600\n\n Args:\n response: httpx.Response object from the health check request\n\n Returns:\n bool: True if the endpoint is considered healthy, False otherwise\n \"\"\"\n # HTTP 200 is always healthy\n if response.status_code == 200:\n return True\n\n # HTTP 400 is healthy only if it has JSON-RPC error code -32600\n if response.status_code == 400:\n try:\n # Parse the JSON response\n response_data = response.json()\n\n # Check for error dictionary with code -32600 (standard MCP error)\n if isinstance(response_data.get(\"error\"), dict):\n error = response_data[\"error\"]\n if isinstance(error.get(\"code\"), int) and error.get(\"code\") == -32600:\n return True\n\n # Check for streamable-http no auth specific query parameter error\n if isinstance(response_data.get(\"error\"), str):\n error_msg = response_data[\"error\"]\n if \"Missing required query parameter: strata_id or instance_id\" in error_msg:\n return True\n\n except (ValueError, KeyError, TypeError):\n # If we can't parse JSON or the structure is wrong, treat as unhealthy\n pass\n\n # All other status codes are considered unhealthy\n return False\n\n def _is_mcp_endpoint_healthy(self, response) -> bool:\n \"\"\"\n Determine if an MCP endpoint is healthy based on HTTP response.\n\n For MCP endpoints, we consider them healthy if:\n 1. HTTP 200 OK - Normal successful response\n 2. HTTP 400 Bad Request with specific JSON-RPC error indicating missing session ID\n\n The 400 status with \"Missing session ID\" error is considered healthy because:\n - It proves the MCP endpoint is reachable and functioning\n - The server is properly validating requests according to MCP protocol\n - It's rejecting our basic GET request because we're not providing a session ID\n - This is expected behavior for a working MCP server when accessed without proper session\n\n Args:\n response: httpx.Response object from the health check request\n\n Returns:\n bool: True if the endpoint is considered healthy, False otherwise\n \"\"\"\n # HTTP 200 is always healthy\n if response.status_code == 200:\n return True\n\n # HTTP 400 is healthy only if it's the expected MCP session error\n if response.status_code == 400:\n try:\n # Parse the JSON response\n response_data = response.json()\n\n # Check for the specific JSON-RPC error indicating missing session ID\n # This is the expected response from a healthy MCP endpoint when accessed without session\n if (\n response_data.get(\"jsonrpc\") == \"2.0\"\n and response_data.get(\"id\") == \"server-error\"\n and isinstance(response_data.get(\"error\"), dict)\n ):\n error = response_data[\"error\"]\n if error.get(\"code\") == -32600 and \"Missing session ID\" in error.get(\n \"message\", \"\"\n ):\n return True\n\n except (ValueError, KeyError, TypeError):\n # If we can't parse JSON or the structure is wrong, treat as unhealthy\n pass\n\n # All other status codes (404, 500, etc.) are considered unhealthy\n return False\n\n async def _update_tools_background(self, service_path: str, proxy_pass_url: str):\n \"\"\"Update tool list in the background without blocking health checks.\"\"\"\n try:\n logger.info(f\"Starting background tool update for {service_path}\")\n from ..core.mcp_client import mcp_client_service\n from ..services.server_service import server_service\n\n # Wait a moment to ensure health check session is fully closed\n # This prevents connection conflicts with servers like currenttime and realserverfaketools\n # that don't allow multiple concurrent sessions on the same endpoint\n await asyncio.sleep(0.5)\n\n # Get server info to pass transport configuration and credentials\n server_info = await server_service.get_server_info(\n service_path, include_credentials=True\n )\n logger.info(f\"Fetching tools from {proxy_pass_url} for {service_path}\")\n\n # Use the new connection result function to get both tools and server info\n connection_result = await mcp_client_service.get_mcp_connection_result(\n proxy_pass_url, server_info\n )\n\n tool_list = connection_result.get(\"tools\") if connection_result else None\n mcp_server_info = connection_result.get(\"server_info\") if connection_result else None\n\n logger.info(\n f\"Tool fetch result for {service_path}: \"\n f\"{len(tool_list) if tool_list else 'None'} tools\"\n )\n\n if tool_list is not None:\n new_tool_count = len(tool_list)\n current_server_info = await server_service.get_server_info(service_path)\n if current_server_info:\n current_tool_count = current_server_info.get(\"num_tools\", 0)\n\n # Update if count changed OR if we have no tool details yet\n current_tool_list = current_server_info.get(\"tool_list\", [])\n\n # Check if MCP server version changed\n current_mcp_version = current_server_info.get(\"mcp_server_version\")\n new_mcp_version = mcp_server_info.get(\"version\") if mcp_server_info else None\n\n # Log warning if version changed\n if (\n current_mcp_version\n and new_mcp_version\n and current_mcp_version != new_mcp_version\n ):\n logger.warning(\n f\"MCP server version change detected for {service_path}: \"\n f\"{current_mcp_version} -> {new_mcp_version}\"\n )\n\n needs_update = (\n current_tool_count != new_tool_count\n or not current_tool_list\n or current_mcp_version != new_mcp_version\n )\n\n if needs_update:\n updated_server_info = current_server_info.copy()\n updated_server_info[\"tool_list\"] = tool_list\n updated_server_info[\"num_tools\"] = new_tool_count\n\n # Store MCP server info if available\n if mcp_server_info:\n if mcp_server_info.get(\"version\"):\n new_ver = mcp_server_info[\"version\"]\n # Track previous version and change timestamp\n if current_mcp_version and current_mcp_version != new_ver:\n updated_server_info[\"mcp_server_version_previous\"] = (\n current_mcp_version\n )\n updated_server_info[\"mcp_server_version_updated_at\"] = (\n datetime.now(UTC).isoformat()\n )\n updated_server_info[\"mcp_server_version\"] = new_ver\n logger.info(\n f\"Storing MCP server version for {service_path}: {new_ver}\"\n )\n if mcp_server_info.get(\"name\"):\n updated_server_info[\"mcp_server_name\"] = mcp_server_info[\"name\"]\n\n await server_service.update_server(service_path, updated_server_info)\n\n # Update scopes.yml with newly discovered tools\n try:\n from ..services.scope_service import update_server_scopes\n\n tool_names = [tool[\"name\"] for tool in tool_list if \"name\" in tool]\n await update_server_scopes(\n service_path,\n current_server_info.get(\"server_name\", \"Unknown\"),\n tool_names,\n )\n logger.info(\n f\"Updated scopes for {service_path} with {len(tool_names)} discovered tools\"\n )\n except Exception as e:\n logger.error(\n f\"Failed to update scopes for {service_path} after tool discovery: {e}\"\n )\n\n # Broadcast only this specific service update\n await self.broadcast_health_update(service_path)\n\n except Exception as e:\n logger.warning(f\"Failed to fetch tools for {service_path}: {e}\")\n\n async def get_all_health_status(self) -> dict:\n \"\"\"Get health status for all services.\"\"\"\n from ..services.server_service import server_service\n\n all_servers = await server_service.get_all_servers()\n\n data = {}\n for path, server_info in all_servers.items():\n data[path] = self._get_service_health_data_fast(path, server_info)\n\n return data\n\n async def perform_immediate_health_check(\n self, service_path: str\n ) -> tuple[str, datetime | None]:\n \"\"\"Perform an immediate health check for a single service.\"\"\"\n import httpx\n\n from ..services.server_service import server_service\n\n server_info = await server_service.get_server_info(service_path)\n if not server_info:\n return \"error: server not registered\", None\n\n proxy_pass_url = server_info.get(\"proxy_pass_url\")\n\n # Record check time\n last_checked_time = datetime.now(UTC)\n self.server_last_check_time[service_path] = last_checked_time\n\n if not proxy_pass_url:\n current_status = \"error: missing proxy URL\"\n self.server_health_status[service_path] = current_status\n logger.info(f\"Health check skipped for {service_path}: Missing URL.\")\n return current_status, last_checked_time\n\n # Set status to 'checking' before performing the check\n logger.info(\n f\"Setting status to '{HealthStatus.CHECKING}' for {service_path} ({proxy_pass_url})...\"\n )\n previous_status = self.server_health_status.get(service_path, HealthStatus.UNKNOWN)\n self.server_health_status[service_path] = HealthStatus.CHECKING\n\n try:\n async with httpx.AsyncClient(\n timeout=httpx.Timeout(settings.health_check_timeout_seconds)\n ) as client:\n # Use transport-aware endpoint checking\n is_healthy, status_detail = await self._check_server_endpoint_transport_aware(\n client, proxy_pass_url, server_info\n )\n\n if is_healthy:\n current_status = status_detail # Could be \"healthy\" or \"healthy-auth-expired\"\n logger.info(\n f\"Health check successful for {service_path} ({proxy_pass_url}): {status_detail}\"\n )\n\n # Schedule tool list fetch in background only for fully healthy status\n logger.info(\n f\"DEBUG: Health check status for {service_path}: status_detail='{status_detail}' (type: {type(status_detail)}) vs HealthStatus.HEALTHY='{HealthStatus.HEALTHY}' (type: {type(HealthStatus.HEALTHY)})\"\n )\n if status_detail == HealthStatus.HEALTHY:\n logger.info(\n f\"DEBUG: Status detail matches HealthStatus.HEALTHY, triggering background tool update for {service_path}\"\n )\n asyncio.create_task(\n self._update_tools_background(service_path, proxy_pass_url)\n )\n elif status_detail == HealthStatus.HEALTHY_AUTH_EXPIRED:\n logger.warning(\n f\"Auth token expired for {service_path} but server is reachable\"\n )\n else:\n logger.info(\n f\"DEBUG: Status detail '{status_detail}' does not match HealthStatus.HEALTHY, NOT triggering background tool update\"\n )\n\n else:\n current_status = status_detail # Detailed error from transport check\n logger.info(\n f\"Health check failed for {service_path} ({proxy_pass_url}): {status_detail}\"\n )\n\n except httpx.TimeoutException:\n current_status = \"unhealthy: timeout\"\n logger.info(f\"Health check timeout for {service_path}\")\n except httpx.ConnectError:\n current_status = \"error: connection failed\"\n logger.info(f\"Health check connection failed for {service_path}\")\n except Exception as e:\n current_status = f\"error: {type(e).__name__}\"\n logger.error(f\"ERROR: Unexpected error during health check for {service_path}: {e}\")\n\n # Update the status\n self.server_health_status[service_path] = current_status\n logger.info(f\"Final health status for {service_path}: {current_status}\")\n\n # Regenerate nginx configuration if status changed\n if previous_status != current_status:\n try:\n from ..core.nginx_service import nginx_service\n\n # Build enabled_servers dict with proper async/await\n enabled_servers = {}\n for path in await server_service.get_enabled_services():\n server_info = await server_service.get_server_info(path)\n if server_info:\n enabled_servers[path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n logger.info(\n f\"Nginx configuration regenerated due to status change for {service_path}: {previous_status} -> {current_status}\"\n )\n except Exception as e:\n logger.error(\n f\"Failed to regenerate nginx configuration after immediate health check: {e}\"\n )\n\n return current_status, last_checked_time\n\n def _get_service_health_data(self, service_path: str, server_info: dict = None) -> dict:\n \"\"\"Get health data for a specific service - legacy method, use _get_service_health_data_fast for better performance.\"\"\"\n return self._get_service_health_data_fast(service_path, server_info or {})\n\n def _get_service_health_data_fast(self, service_path: str, server_info: dict) -> dict:\n \"\"\"Get health data for a specific service - optimized version.\"\"\"\n\n # Quick enabled check from server_info\n is_enabled = server_info.get(\"is_enabled\", False)\n\n if not is_enabled:\n status = \"disabled\"\n self.server_health_status[service_path] = \"disabled\"\n else:\n # Use cached status, only update if transitioning from disabled\n cached_status = self.server_health_status.get(service_path, \"unknown\")\n if cached_status == \"disabled\":\n status = HealthStatus.CHECKING\n self.server_health_status[service_path] = HealthStatus.CHECKING\n else:\n status = cached_status\n\n # Use pre-fetched server_info instead of calling get_server_info again\n last_checked_dt = self.server_last_check_time.get(service_path)\n last_checked_iso = last_checked_dt.isoformat() if last_checked_dt else None\n num_tools = server_info.get(\"num_tools\", 0) if server_info else 0\n\n return {\"status\": status, \"last_checked_iso\": last_checked_iso, \"num_tools\": num_tools}\n\n\n# Global health monitoring service instance\nhealth_service = HealthMonitoringService()\n" }, { "path": "registry/main.py", "content": "#!/usr/bin/env python3\n\"\"\"\nMCP Gateway Registry - Modern FastAPI Application\n\nA clean, domain-driven FastAPI app for managing MCP (Model Context Protocol) servers.\nThis main.py file serves as the application coordinator, importing and registering\ndomain routers while handling core app configuration.\n\"\"\"\n\nimport logging\nimport os\nfrom contextlib import asynccontextmanager\n\n# Import datetime for uptime tracking\nfrom datetime import UTC, datetime\nfrom pathlib import Path\nfrom typing import Any\nfrom uuid import uuid4\n\nfrom fastapi import Depends, FastAPI, HTTPException\nfrom fastapi.middleware.cors import CORSMiddleware\nfrom fastapi.openapi.utils import get_openapi\nfrom fastapi.responses import FileResponse, HTMLResponse\nfrom fastapi.staticfiles import StaticFiles\n\nfrom registry.api.agent_routes import router as agent_router\nfrom registry.api.ans_routes import router as ans_router\nfrom registry.api.auth0_m2m_routes import router as auth0_m2m_router\nfrom registry.api.config_routes import router as config_router\nfrom registry.api.export_routes import router as export_router\nfrom registry.api.federation_export_routes import router as federation_export_router\nfrom registry.api.federation_routes import router as federation_router\nfrom registry.api.internal_routes import router as internal_router\nfrom registry.api.log_routes import router as log_router\nfrom registry.api.m2m_management_routes import router as m2m_management_router\nfrom registry.api.management_routes import router as management_router\nfrom registry.api.okta_m2m_routes import router as okta_m2m_router\nfrom registry.api.peer_management_routes import router as peer_management_router\nfrom registry.api.registry_management_routes import router as registry_management_router\nfrom registry.api.registry_routes import router as registry_router\nfrom registry.api.search_routes import router as search_router\nfrom registry.api.server_routes import router as servers_router\nfrom registry.api.skill_routes import router as skill_router\nfrom registry.api.system_routes import router as system_router\nfrom registry.api.system_routes import set_server_start_time\nfrom registry.api.virtual_server_routes import router as virtual_server_router\nfrom registry.api.wellknown_routes import router as wellknown_router\n\n# Import audit logging\nfrom registry.audit import AuditLogger, add_audit_middleware\nfrom registry.audit.routes import router as audit_router\n\n# Import auth dependencies\nfrom registry.auth.dependencies import (\n get_ui_permissions_for_user,\n nginx_proxied_auth,\n)\n\n# Import domain routers\nfrom registry.auth.routes import router as auth_router\n\n# Import core configuration\nfrom registry.core.config import (\n RegistryMode,\n _print_config_warning_banner,\n _validate_mode_combination,\n log_tab_visibility_warnings,\n settings,\n)\nfrom registry.core.metrics import DEPLOYMENT_MODE_INFO\nfrom registry.core.nginx_service import nginx_service\nfrom registry.core.telemetry import (\n initialize_telemetry,\n send_startup_ping,\n start_heartbeat_scheduler,\n stop_heartbeat_scheduler,\n)\nfrom registry.health.routes import router as health_router\nfrom registry.health.service import health_service\n\n# Import registry mode middleware\nfrom registry.middleware.mode_filter import RegistryModeMiddleware\nfrom registry.repositories.factory import get_search_repository\nfrom registry.services.agent_service import agent_service\nfrom registry.services.peer_federation_service import get_peer_federation_service\nfrom registry.services.peer_sync_scheduler import get_peer_sync_scheduler\n\n# Import services for initialization\nfrom registry.services.server_service import server_service\n\n# Server start time tracking moved to registry/api/system_routes.py\n# Setup logging using shared module (RotatingFileHandler + optional MongoDB)\nfrom registry.utils.logging_setup import setup_logging as _setup_logging\n\n# Import version\nfrom registry.version import __version__\n\nlog_file_path = _setup_logging(service_name=\"registry\")\nlogger = logging.getLogger(__name__)\nlogger.info(f\"Logging configured. Writing to file: {log_file_path}\")\n\n\ndef _log_startup_configuration() -> None:\n \"\"\"Log startup configuration with clear formatting.\"\"\"\n logger.info(\"=\" * 60)\n logger.info(\"Registry starting with:\")\n logger.info(f\" - DEPLOYMENT_MODE: {settings.deployment_mode.value}\")\n logger.info(f\" - REGISTRY_MODE: {settings.registry_mode.value}\")\n logger.info(f\" - Nginx updates: {'ENABLED' if settings.nginx_updates_enabled else 'DISABLED'}\")\n\n # Log what's disabled based on registry mode\n if settings.registry_mode == RegistryMode.SKILLS_ONLY:\n logger.info(\" - Running in skills-only mode:\")\n logger.info(\" - MCP servers API: DISABLED\")\n logger.info(\" - A2A agents API: DISABLED\")\n logger.info(\" - Federation API: DISABLED\")\n logger.info(\" - Skills API: ENABLED\")\n elif settings.registry_mode == RegistryMode.MCP_SERVERS_ONLY:\n logger.info(\" - Running in mcp-servers-only mode:\")\n logger.info(\" - MCP servers API: ENABLED\")\n logger.info(\" - A2A agents API: DISABLED\")\n logger.info(\" - Skills API: DISABLED\")\n logger.info(\" - Federation API: DISABLED\")\n elif settings.registry_mode == RegistryMode.AGENTS_ONLY:\n logger.info(\" - Running in agents-only mode:\")\n logger.info(\" - A2A agents API: ENABLED\")\n logger.info(\" - MCP servers API: DISABLED\")\n logger.info(\" - Skills API: DISABLED\")\n logger.info(\" - Federation API: DISABLED\")\n\n logger.info(\"=\" * 60)\n\n\ndef _initialize_deployment_metrics() -> None:\n \"\"\"Initialize deployment mode Prometheus metrics.\"\"\"\n DEPLOYMENT_MODE_INFO.labels(\n deployment_mode=settings.deployment_mode.value, registry_mode=settings.registry_mode.value\n ).set(1)\n\n\n# Stats and deployment detection functions moved to registry/api/system_routes.py\n\n\nasync def _sync_agentcore_on_startup(\n federation_config: Any,\n server_service: Any,\n) -> None:\n \"\"\"Sync records from AWS Agent Registry on startup.\n\n Fetches all records from configured AgentCore registries,\n registers them locally, and reconciles stale records.\n\n Args:\n federation_config: FederationConfig with agentcore settings\n server_service: ServerService for server registration\n \"\"\"\n from registry.repositories.factory import (\n get_agent_repository,\n get_server_repository,\n get_skill_repository,\n )\n from registry.schemas.agent_models import AgentCard\n from registry.schemas.skill_models import SkillCard\n from registry.services.agent_service import agent_service\n from registry.services.federation.agentcore_client import (\n AgentCoreFederationClient,\n )\n from registry.services.federation_reconciliation import (\n reconcile_agentcore_records,\n )\n from registry.services.skill_service import get_skill_service\n\n logger.info(\"Syncing from AWS Agent Registry...\")\n\n agentcore_client = AgentCoreFederationClient(\n aws_region=federation_config.aws_registry.aws_region\n )\n records = agentcore_client.fetch_all_records(\n registry_configs=federation_config.aws_registry.registries,\n sync_timeout_seconds=federation_config.aws_registry.sync_timeout_seconds,\n max_concurrent_fetches=federation_config.aws_registry.max_concurrent_fetches,\n )\n\n synced_paths: dict[str, set[str]] = {\n \"servers\": set(),\n \"agents\": set(),\n \"skills\": set(),\n }\n\n # Register servers (MCP records)\n server_count = 0\n for server_data in records[\"servers\"]:\n try:\n server_path = server_data.get(\"path\")\n if not server_path:\n continue\n\n if \"id\" not in server_data or not server_data[\"id\"]:\n server_data[\"id\"] = str(uuid4())\n\n success = await server_service.register_server(server_data)\n if not success:\n if \"id\" not in server_data or not server_data[\"id\"]:\n server_data[\"id\"] = str(uuid4())\n success = await server_service.update_server(server_path, server_data)\n\n if success:\n await server_service.toggle_service(server_path, True)\n server_count += 1\n synced_paths[\"servers\"].add(server_path)\n except Exception as e:\n logger.error(\n f\"Failed to sync AgentCore server {server_data.get('server_name', 'unknown')}: {e}\"\n )\n\n # Register agents (A2A + CUSTOM records)\n agent_count = 0\n for agent_data in records[\"agents\"]:\n try:\n agent_path = agent_data.get(\"path\")\n if not agent_path:\n continue\n\n try:\n agent_card = AgentCard(**agent_data)\n await agent_service.register_agent(agent_card)\n agent_count += 1\n synced_paths[\"agents\"].add(agent_path)\n except ValueError:\n # Path already exists -- update instead\n await agent_service.update_agent(agent_path, agent_data)\n agent_count += 1\n synced_paths[\"agents\"].add(agent_path)\n except Exception as e:\n logger.error(f\"Failed to sync AgentCore agent {agent_data.get('name', 'unknown')}: {e}\")\n\n # Register skills (AGENT_SKILLS records)\n skill_count = 0\n skill_service = get_skill_service()\n skill_repo = get_skill_repository()\n for skill_data in records[\"skills\"]:\n try:\n skill_path = skill_data.get(\"path\")\n if not skill_path:\n continue\n\n try:\n skill_card = SkillCard(**skill_data)\n await skill_repo.create(skill_card)\n skill_count += 1\n synced_paths[\"skills\"].add(skill_path)\n except Exception as create_err:\n # Skill already exists -- update instead\n logger.debug(f\"Skill create failed for {skill_path}, trying update: {create_err}\")\n update_fields = {\n k: v for k, v in skill_data.items() if k not in (\"path\", \"id\", \"created_at\")\n }\n await skill_repo.update(skill_path, update_fields)\n skill_count += 1\n synced_paths[\"skills\"].add(skill_path)\n except Exception as e:\n logger.error(f\"Failed to sync AgentCore skill {skill_data.get('name', 'unknown')}: {e}\")\n\n logger.info(\n f\"Synced from AWS Agent Registry: \"\n f\"{server_count} servers, {agent_count} agents, {skill_count} skills\"\n )\n\n # Run reconciliation to remove stale records\n logger.info(\"Running AgentCore reconciliation after startup sync...\")\n try:\n server_repo = get_server_repository()\n agent_repo = get_agent_repository()\n\n reconciliation_result = await reconcile_agentcore_records(\n config=federation_config,\n server_service=server_service,\n server_repo=server_repo,\n agent_repo=agent_repo,\n skill_repo=skill_repo,\n synced_paths=synced_paths,\n )\n\n logger.info(\n f\"AgentCore reconciliation complete: \"\n f\"removed {reconciliation_result.get('total_removed', 0)} stale records\"\n )\n except Exception as e:\n logger.error(\n f\"AgentCore reconciliation failed (continuing with startup): {e}\",\n exc_info=True,\n )\n\n\nasync def _apply_aws_registry_env_vars() -> None:\n \"\"\"Apply AWS_REGISTRY_FEDERATION_ENABLED env var to the federation config.\n\n When the env var is set (e.g. via ECS task definition or .env),\n it overrides the aws_registry.enabled flag in the MongoDB federation\n config document. Creates the config document if it does not exist.\n\n Other aws_registry settings (region, sync_on_startup, registries)\n are managed exclusively via the /api/federation/config API.\n \"\"\"\n from registry.repositories.factory import get_federation_config_repository\n from registry.schemas.federation_schema import FederationConfig\n\n env_enabled = os.environ.get(\"AWS_REGISTRY_FEDERATION_ENABLED\", \"\").lower()\n\n if not env_enabled:\n logger.debug(\"AWS_REGISTRY_FEDERATION_ENABLED not set, skipping env var override\")\n return\n\n enabled = env_enabled in (\"true\", \"1\", \"yes\")\n logger.info(f\"AWS_REGISTRY_FEDERATION_ENABLED={enabled} (from env var)\")\n\n federation_repo = get_federation_config_repository()\n config = await federation_repo.get_config(\"default\")\n\n if config is None:\n config = FederationConfig()\n\n config.aws_registry.enabled = enabled\n\n await federation_repo.save_config(config, \"default\")\n logger.info(f\"Federation config updated: aws_registry.enabled={enabled}\")\n\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n \"\"\"Application startup and shutdown lifecycle management.\"\"\"\n # Record server start time for uptime tracking\n server_start_time = datetime.now(UTC)\n set_server_start_time(server_start_time)\n logger.info(f\"Server started at: {server_start_time.isoformat()}\")\n\n logger.info(\"🚀 Starting MCP Gateway Registry...\")\n\n # Validate and potentially correct mode combination\n original_deployment = settings.deployment_mode\n original_registry = settings.registry_mode\n\n corrected_deployment, corrected_registry, was_corrected = _validate_mode_combination(\n original_deployment, original_registry\n )\n\n if was_corrected:\n _print_config_warning_banner(\n original_deployment, original_registry, corrected_deployment, corrected_registry\n )\n # Update settings (use object.__setattr__ for frozen pydantic settings)\n object.__setattr__(settings, \"deployment_mode\", corrected_deployment)\n object.__setattr__(settings, \"registry_mode\", corrected_registry)\n\n # Log startup configuration\n _log_startup_configuration()\n\n # Log warnings for ineffective SHOW_*_TAB overrides\n log_tab_visibility_warnings(settings)\n\n # Initialize Prometheus metrics\n _initialize_deployment_metrics()\n\n # Validate required configuration settings\n logger.info(\"🔍 Validating configuration...\")\n errors = []\n\n if not settings.registry_url:\n errors.append(\"REGISTRY_URL is required\")\n\n if not settings.registry_name:\n errors.append(\"REGISTRY_NAME is required\")\n\n if not settings.registry_organization_name:\n errors.append(\"REGISTRY_ORGANIZATION_NAME is required\")\n\n if errors:\n logger.error(\n \"Configuration validation failed\",\n extra={\"errors\": errors},\n )\n raise RuntimeError(f\"Configuration errors: {', '.join(errors)}\")\n\n logger.info(\n \"Configuration validated successfully\",\n extra={\n \"registry_name\": settings.registry_name,\n \"registry_url\": settings.registry_url,\n \"organization\": settings.registry_organization_name,\n },\n )\n\n # Initialize audit logger reference (middleware added at module level)\n audit_logger = getattr(app.state, \"audit_logger\", None)\n if audit_logger:\n logger.info(f\"✅ Audit logging enabled. Writing to: {settings.audit_log_path}\")\n\n try:\n # Load scopes configuration from repository\n logger.info(\"🔐 Loading scopes configuration from repository...\")\n from registry.auth.dependencies import reload_scopes_from_repository\n\n await reload_scopes_from_repository()\n\n # Initialize services in order\n logger.info(\"📚 Loading server definitions and state...\")\n await server_service.load_servers_and_state()\n\n # Get repository based on STORAGE_BACKEND configuration\n search_repo = get_search_repository()\n backend_name = \"DocumentDB\" if settings.storage_backend == \"documentdb\" else \"FAISS\"\n\n logger.info(f\"🔍 Initializing {backend_name} search service...\")\n await search_repo.initialize()\n\n logger.info(f\"📊 Updating {backend_name} index with all registered services...\")\n all_servers = await server_service.get_all_servers()\n for service_path, server_info in all_servers.items():\n is_enabled = await server_service.is_service_enabled(service_path)\n try:\n await search_repo.index_server(service_path, server_info, is_enabled)\n logger.debug(f\"Updated {backend_name} index for service: {service_path}\")\n except Exception as e:\n logger.error(\n f\"Failed to update {backend_name} index for service {service_path}: {e}\",\n exc_info=True,\n )\n\n logger.info(f\"✅ {backend_name} index updated with {len(all_servers)} services\")\n\n logger.info(\"📋 Loading agent cards and state...\")\n await agent_service.load_agents_and_state()\n\n logger.info(f\"📊 Updating {backend_name} index with all registered agents...\")\n all_agents = await agent_service.list_agents()\n for agent_card in all_agents:\n is_enabled = await agent_service.is_agent_enabled(agent_card.path)\n try:\n await search_repo.index_agent(agent_card.path, agent_card, is_enabled)\n logger.debug(f\"Updated {backend_name} index for agent: {agent_card.path}\")\n except Exception as e:\n logger.error(\n f\"Failed to update {backend_name} index for agent {agent_card.path}: {e}\",\n exc_info=True,\n )\n\n logger.info(f\"✅ {backend_name} index updated with {len(all_agents)} agents\")\n\n logger.info(f\"📊 Updating {backend_name} index with all registered skills...\")\n from registry.repositories.factory import get_skill_repository\n\n skill_repo = get_skill_repository()\n all_skills = await skill_repo.list_all(skip=0, limit=10000)\n for skill_card in all_skills:\n try:\n await search_repo.index_skill(skill_card.path, skill_card, skill_card.is_enabled)\n logger.debug(f\"Updated {backend_name} index for skill: {skill_card.path}\")\n except Exception as e:\n logger.error(\n f\"Failed to update {backend_name} index for skill {skill_card.path}: {e}\",\n exc_info=True,\n )\n\n logger.info(f\"✅ {backend_name} index updated with {len(all_skills)} skills\")\n\n logger.info(\"🏥 Initializing health monitoring service...\")\n await health_service.initialize()\n\n logger.info(\"🔗 Checking federation configuration...\")\n from registry.repositories.factory import get_federation_config_repository\n\n # Apply env var overrides (e.g. from ECS/terraform) before loading config\n try:\n await _apply_aws_registry_env_vars()\n except Exception as e:\n logger.error(\n f\"Failed to apply AWS Registry env vars (continuing with startup): {e}\",\n exc_info=True,\n )\n\n try:\n # Load federation config\n federation_repo = get_federation_config_repository()\n federation_config = await federation_repo.get_config(\"default\")\n\n if federation_config and federation_config.is_any_federation_enabled():\n logger.info(\n f\"Federation enabled for: {', '.join(federation_config.get_enabled_federations())}\"\n )\n\n # Sync on startup if configured\n sync_on_startup = (\n (\n federation_config.anthropic.enabled\n and federation_config.anthropic.sync_on_startup\n )\n or (federation_config.asor.enabled and federation_config.asor.sync_on_startup)\n or (\n federation_config.aws_registry.enabled\n and federation_config.aws_registry.sync_on_startup\n )\n )\n\n if sync_on_startup:\n logger.info(\"🔄 Syncing servers from federated registries on startup...\")\n try:\n from registry.services.federation.anthropic_client import (\n AnthropicFederationClient,\n )\n\n # Sync Anthropic servers if enabled and sync_on_startup is true\n if (\n federation_config.anthropic.enabled\n and federation_config.anthropic.sync_on_startup\n ):\n logger.info(\"Syncing from Anthropic MCP Registry...\")\n anthropic_client = AnthropicFederationClient(\n endpoint=federation_config.anthropic.endpoint\n )\n servers = anthropic_client.fetch_all_servers(\n federation_config.anthropic.servers\n )\n\n # Register servers\n synced_count = 0\n for server_data in servers:\n try:\n server_path = server_data.get(\"path\")\n if not server_path:\n continue\n\n # Ensure UUID id field exists for federation sync\n if \"id\" not in server_data or not server_data[\"id\"]:\n server_data[\"id\"] = str(uuid4())\n\n # Register or update server\n success = await server_service.register_server(server_data)\n if not success:\n # Ensure UUID exists before updating (for servers registered before UUID feature)\n if \"id\" not in server_data or not server_data[\"id\"]:\n server_data[\"id\"] = str(uuid4())\n success = await server_service.update_server(\n server_path, server_data\n )\n\n if success:\n # Enable the server\n await server_service.toggle_service(server_path, True)\n synced_count += 1\n logger.info(\n f\"Synced: {server_data.get('server_name', server_path)}\"\n )\n except Exception as e:\n logger.error(\n f\"Failed to sync server {server_data.get('server_name', 'unknown')}: {e}\"\n )\n\n logger.info(f\"✅ Synced {synced_count} servers from Anthropic\")\n\n # Run reconciliation after sync to remove stale servers\n logger.info(\"🔄 Running reconciliation after startup sync...\")\n try:\n from registry.repositories.factory import (\n get_server_repository,\n )\n from registry.services.federation_reconciliation import (\n reconcile_anthropic_servers,\n )\n\n server_repo = get_server_repository()\n reconciliation_result = await reconcile_anthropic_servers(\n config=federation_config,\n server_service=server_service,\n server_repo=server_repo,\n nginx_service=None,\n skip_nginx_regen=True,\n )\n\n logger.info(\n f\"✅ Reconciliation complete: \"\n f\"removed {reconciliation_result['removed_count']} stale servers, \"\n f\"expected {reconciliation_result['expected_count']}, \"\n f\"found {reconciliation_result['actual_count']} in DB\"\n )\n except Exception as e:\n logger.error(\n f\"⚠️ Reconciliation failed (continuing with startup): {e}\",\n exc_info=True,\n )\n\n # ASOR sync would go here if needed\n\n # AgentCore sync (AWS Agent Registry)\n if (\n federation_config.aws_registry.enabled\n and federation_config.aws_registry.sync_on_startup\n ):\n try:\n await _sync_agentcore_on_startup(\n federation_config=federation_config,\n server_service=server_service,\n )\n except Exception as e:\n logger.error(\n f\"AgentCore federation sync failed (continuing with startup): {e}\",\n exc_info=True,\n )\n\n except Exception as e:\n logger.error(\n f\"⚠️ Federation sync failed (continuing with startup): {e}\",\n exc_info=True,\n )\n else:\n logger.info(\"Federation is disabled or not configured\")\n except Exception as e:\n logger.error(f\"Failed to load federation config: {e}\")\n logger.info(\"Continuing without federation\")\n\n logger.info(\"Initializing peer federation service...\")\n peer_federation_service = get_peer_federation_service()\n await peer_federation_service.load_peers_and_state()\n logger.info(f\"Loaded {len(peer_federation_service.registered_peers)} peer registries\")\n\n # Start peer sync scheduler for scheduled federation sync\n logger.info(\"Starting peer sync scheduler...\")\n peer_sync_scheduler = get_peer_sync_scheduler()\n await peer_sync_scheduler.start()\n logger.info(\"Peer sync scheduler started\")\n\n # Start ANS sync scheduler\n if settings.ans_integration_enabled:\n from registry.services.ans_sync_scheduler import get_ans_sync_scheduler\n\n ans_scheduler = get_ans_sync_scheduler()\n await ans_scheduler.start()\n logger.info(\"ANS sync scheduler started\")\n\n # Ensure unique index on idp_m2m_clients.client_id for the direct\n # M2M registration API (issue #851). Only when feature is enabled.\n if settings.m2m_direct_registration_enabled:\n try:\n from registry.repositories.documentdb.client import get_documentdb_client\n from registry.services.m2m_management_service import (\n M2MManagementService,\n )\n\n m2m_db = await get_documentdb_client()\n await M2MManagementService(m2m_db).ensure_indexes()\n except Exception as e:\n logger.warning(\n f\"Failed to ensure idp_m2m_clients index (continuing with startup): {e}\",\n )\n\n # Initialize built-in demo servers (airegistry-tools)\n # Skipped when DISABLE_AI_REGISTRY_TOOLS_SERVER=true (e.g. GitOps/production deployments)\n if not settings.disable_ai_registry_tools_server:\n logger.info(\"Initializing demo servers...\")\n from registry.services.demo_servers_init import initialize_demo_servers\n\n await initialize_demo_servers()\n else:\n logger.info(\n \"Demo server auto-registration disabled (DISABLE_AI_REGISTRY_TOOLS_SERVER=true)\"\n )\n\n # Verify registration gate connectivity (non-blocking)\n from registry.services.registration_gate_service import verify_gate_connectivity\n\n try:\n await verify_gate_connectivity()\n except Exception as e:\n logger.warning(\n f\"Registration gate connectivity check failed (continuing with startup): {e}\"\n )\n\n # Always generate nginx configuration at startup to ensure placeholders are replaced\n # In registry-only mode, generate base config without MCP server location blocks\n if settings.nginx_updates_enabled:\n logger.info(\"Generating initial Nginx configuration with MCP server locations...\")\n enabled_service_paths = await server_service.get_enabled_services()\n enabled_servers = {}\n for path in enabled_service_paths:\n server_info = await server_service.get_server_info(path)\n if server_info:\n enabled_servers[path] = server_info\n await nginx_service.generate_config_async(enabled_servers)\n else:\n logger.info(\"Generating base Nginx configuration (registry-only mode)...\")\n # Generate base config with empty location blocks but substitute all placeholders\n await nginx_service.generate_config_async({}, force_base_config=True)\n\n logger.info(\"✅ All services initialized successfully!\")\n\n # Initialize and send anonymous startup telemetry (opt-out: MCP_TELEMETRY_DISABLED=1)\n await initialize_telemetry()\n await send_startup_ping()\n await start_heartbeat_scheduler()\n\n except Exception as e:\n logger.error(f\"❌ Failed to initialize services: {e}\", exc_info=True)\n raise\n\n # Application is ready\n yield\n\n # Shutdown tasks\n logger.info(\"🔄 Shutting down MCP Gateway Registry...\")\n try:\n # Stop ANS sync scheduler\n if settings.ans_integration_enabled:\n from registry.services.ans_sync_scheduler import get_ans_sync_scheduler\n\n ans_scheduler = get_ans_sync_scheduler()\n await ans_scheduler.stop()\n\n # Stop telemetry scheduler\n await stop_heartbeat_scheduler()\n\n # Stop peer sync scheduler\n peer_sync_scheduler = get_peer_sync_scheduler()\n await peer_sync_scheduler.stop()\n\n # Shutdown audit logger if enabled\n if audit_logger is not None:\n logger.info(\"📝 Closing audit logger...\")\n await audit_logger.close()\n\n # Shutdown services gracefully\n await health_service.shutdown()\n logger.info(\"✅ Shutdown completed successfully!\")\n except Exception as e:\n logger.error(f\"❌ Error during shutdown: {e}\", exc_info=True)\n\n\n# Create FastAPI application\napp = FastAPI(\n title=\"MCP Gateway Registry\",\n description=\"A registry and management system for Model Context Protocol (MCP) servers\",\n version=__version__,\n lifespan=lifespan,\n root_path=os.environ.get(\"ROOT_PATH\", \"\"), # Support path-based routing with ALB\n swagger_ui_parameters={\n \"persistAuthorization\": True,\n },\n openapi_tags=[\n {\n \"name\": \"Authentication\",\n \"description\": \"OAuth2 and session-based authentication endpoints\",\n },\n {\n \"name\": \"Server Management\",\n \"description\": \"MCP server registration and management. Requires JWT Bearer token authentication.\",\n },\n {\n \"name\": \"Agent Management\",\n \"description\": \"A2A agent registration and management. Requires JWT Bearer token authentication.\",\n },\n {\n \"name\": \"Management API\",\n \"description\": \"IAM and user management operations. Requires JWT Bearer token with admin permissions.\",\n },\n {\n \"name\": \"Semantic Search\",\n \"description\": \"Vector-based semantic search for agents. Requires JWT Bearer token authentication.\",\n },\n {\"name\": \"Health Monitoring\", \"description\": \"Service health check endpoints\"},\n {\n \"name\": \"Anthropic Registry API\",\n \"description\": \"Anthropic-compatible registry API (v0.1) for MCP server discovery\",\n },\n {\n \"name\": \"federation\",\n \"description\": \"Federation configuration and peer-to-peer registry synchronization APIs\",\n },\n {\n \"name\": \"peer-management\",\n \"description\": \"Peer registry management API for configuring and synchronizing with peer registries. Requires JWT Bearer token authentication.\",\n },\n {\n \"name\": \"Audit Logs\",\n \"description\": \"Audit log viewing and export endpoints. Requires admin permissions.\",\n },\n {\n \"name\": \"Application Logs\",\n \"description\": \"Centralized application log retrieval API. Requires admin permissions.\",\n },\n {\n \"name\": \"skills\",\n \"description\": \"Agent Skills registration and management. Requires JWT Bearer token authentication.\",\n },\n {\n \"name\": \"virtual-servers\",\n \"description\": \"Virtual MCP Server management. Aggregate tools from multiple backends into unified endpoints.\",\n },\n ],\n)\n\n# Add CORS middleware for React development and Docker deployment\napp.add_middleware(\n CORSMiddleware,\n allow_origin_regex=r\"https?://(localhost(:[0-9]+)?|.*\\.compute.*\\.amazonaws\\.com(:[0-9]+)?)\",\n allow_credentials=True,\n allow_methods=[\"GET\", \"POST\", \"PUT\", \"DELETE\", \"OPTIONS\"],\n allow_headers=[\"*\"],\n)\n\n# Add registry mode middleware to filter endpoints based on REGISTRY_MODE\n# This must be after CORS (to allow preflight) and before audit (to log blocked requests)\nif settings.registry_mode != RegistryMode.FULL:\n logger.info(f\"Adding registry mode middleware - mode: {settings.registry_mode.value}\")\n app.add_middleware(RegistryModeMiddleware)\n\n# Add audit middleware if enabled (must be added before app starts)\nif settings.audit_log_enabled:\n logger.info(\"📝 Initializing audit logging...\")\n\n # Get audit repository if MongoDB is enabled\n _audit_repository = None\n _mongodb_enabled = settings.audit_log_mongodb_enabled and settings.storage_backend in (\n \"documentdb\",\n \"mongodb-ce\",\n )\n if _mongodb_enabled:\n from registry.repositories.factory import get_audit_repository\n\n _audit_repository = get_audit_repository()\n if _audit_repository:\n logger.info(\"📊 MongoDB audit storage enabled\")\n else:\n logger.warning(\"⚠️ MongoDB audit storage requested but repository unavailable\")\n _mongodb_enabled = False\n\n _audit_logger = AuditLogger(\n log_dir=str(settings.audit_log_path),\n rotation_hours=settings.audit_log_rotation_hours,\n rotation_max_mb=settings.audit_log_rotation_max_mb,\n local_retention_hours=settings.audit_log_local_retention_hours,\n stream_name=\"registry-api-access\",\n mongodb_enabled=_mongodb_enabled,\n audit_repository=_audit_repository,\n )\n # Store audit logger in app state for lifespan access\n app.state.audit_logger = _audit_logger\n\n # Add audit middleware to the app\n add_audit_middleware(\n app,\n audit_logger=_audit_logger,\n log_health_checks=settings.audit_log_health_checks,\n log_static_assets=settings.audit_log_static_assets,\n )\n\n# Register API routers with /api prefix\napp.include_router(system_router, tags=[\"System\"]) # /api/version, /api/stats\napp.include_router(auth_router, prefix=\"/api/auth\", tags=[\"Authentication\"])\napp.include_router(servers_router, prefix=\"/api\", tags=[\"Server Management\"])\napp.include_router(ans_router, prefix=\"/api\", tags=[\"ANS Integration\"])\napp.include_router(agent_router, prefix=\"/api\", tags=[\"Agent Management\"])\napp.include_router(management_router, prefix=\"/api\")\napp.include_router(search_router, prefix=\"/api/search\", tags=[\"Semantic Search\"])\napp.include_router(federation_router, prefix=\"/api\", tags=[\"federation\"])\napp.include_router(skill_router, prefix=\"/api\", tags=[\"skills\"])\napp.include_router(config_router, prefix=\"/api/config\", tags=[\"config\"])\napp.include_router(virtual_server_router, prefix=\"/api\", tags=[\"virtual-servers\"])\napp.include_router(internal_router, prefix=\"/api\")\napp.include_router(health_router, prefix=\"/api/health\", tags=[\"Health Monitoring\"])\napp.include_router(federation_export_router)\napp.include_router(peer_management_router)\napp.include_router(audit_router, prefix=\"/api\", tags=[\"Audit Logs\"])\napp.include_router(log_router, prefix=\"/api\", tags=[\"Application Logs\"])\napp.include_router(export_router, tags=[\"Data Export\"])\napp.include_router(registry_management_router, prefix=\"/api\")\n\n# Register IdP M2M management routers (Okta and Auth0)\napp.include_router(okta_m2m_router, prefix=\"/api\", tags=[\"Okta M2M\"])\napp.include_router(auth0_m2m_router, prefix=\"/api\", tags=[\"Auth0 M2M\"])\n\n# Direct M2M client registration API (issue #851)\n# Does not require IdP Admin API token. Gated by feature flag.\nif settings.m2m_direct_registration_enabled:\n app.include_router(m2m_management_router, prefix=\"/api\", tags=[\"M2M Management\"])\n\n# Register Anthropic MCP Registry API (public API for MCP servers only)\napp.include_router(registry_router, prefix=\"/api/registry\", tags=[\"Registry Card\"])\n\n# Register well-known discovery router\napp.include_router(wellknown_router, prefix=\"/.well-known\", tags=[\"Discovery\"])\n\n\n# Customize OpenAPI schema to add security schemes\ndef custom_openapi():\n if app.openapi_schema:\n return app.openapi_schema\n\n openapi_schema = get_openapi(\n title=app.title,\n version=app.version,\n description=app.description,\n routes=app.routes,\n )\n\n # Add security schemes\n openapi_schema[\"components\"][\"securitySchemes\"] = {\n \"Bearer\": {\n \"type\": \"http\",\n \"scheme\": \"bearer\",\n \"bearerFormat\": \"JWT\",\n \"description\": \"JWT Bearer token obtained from Keycloak OAuth2 authentication. \"\n \"Include in Authorization header as: `Authorization: Bearer `\",\n }\n }\n\n # Apply Bearer security to all endpoints except auth, health, and public discovery endpoints\n for path, path_item in openapi_schema[\"paths\"].items():\n # Skip authentication, health check, and public discovery endpoints\n if path.startswith(\"/api/auth/\") or path == \"/health\" or path.startswith(\"/.well-known/\"):\n continue\n\n # Apply Bearer security to all methods in this path\n for method in path_item:\n if method in [\"get\", \"post\", \"put\", \"delete\", \"patch\"]:\n if \"security\" not in path_item[method]:\n path_item[method][\"security\"] = [{\"Bearer\": []}]\n\n app.openapi_schema = openapi_schema\n return app.openapi_schema\n\n\napp.openapi = custom_openapi\n\n\n# Add user info endpoint for React auth context\n@app.get(\"/api/auth/me\")\nasync def get_current_user(user_context: dict[str, Any] = Depends(nginx_proxied_auth)):\n \"\"\"Get current user information for React auth context\"\"\"\n # Get user's scopes\n user_scopes = user_context.get(\"scopes\", [])\n\n # Get UI permissions for the user based on their scopes\n ui_permissions = await get_ui_permissions_for_user(user_scopes)\n\n # Return user info with scopes and UI permissions for token generation\n return {\n \"username\": user_context[\"username\"],\n \"auth_method\": user_context.get(\"auth_method\", \"basic\"),\n \"provider\": user_context.get(\"provider\"),\n \"scopes\": user_scopes,\n \"groups\": user_context.get(\"groups\", []),\n \"can_modify_servers\": user_context.get(\"can_modify_servers\", False),\n \"is_admin\": user_context.get(\"is_admin\", False),\n \"ui_permissions\": ui_permissions,\n \"accessible_servers\": user_context.get(\"accessible_servers\", []),\n \"accessible_services\": user_context.get(\"accessible_services\", []),\n \"accessible_agents\": user_context.get(\"accessible_agents\", []),\n }\n\n\n# Basic health check endpoint\n@app.get(\"/health\")\nasync def health_check():\n \"\"\"Simple health check for load balancers and monitoring.\"\"\"\n return {\n \"status\": \"healthy\",\n \"service\": \"mcp-gateway-registry\",\n \"deployment_mode\": settings.deployment_mode.value,\n \"registry_mode\": settings.registry_mode.value,\n \"nginx_updates_enabled\": settings.nginx_updates_enabled,\n }\n\n\n# Version endpoint for UI\n# System endpoints (version, stats) moved to registry/api/system_routes.py\n\n\n# Serve React static files\nFRONTEND_BUILD_PATH = Path(__file__).parent.parent / \"frontend\" / \"build\"\n\n# Cache the modified index.html content for path-based routing\n# Read once at startup instead of on every request\n_CACHED_INDEX_HTML: str | None = None\n_ROOT_PATH: str = os.environ.get(\"ROOT_PATH\", \"\")\n\n\ndef _build_cached_index_html() -> str | None:\n \"\"\"Read index.html and inject tag if ROOT_PATH is set.\n\n Returns:\n Modified HTML string if ROOT_PATH is set, None otherwise.\n \"\"\"\n if not _ROOT_PATH:\n return None\n\n index_path = FRONTEND_BUILD_PATH / \"index.html\"\n if not index_path.exists():\n return None\n\n with open(index_path) as f:\n html_content = f.read()\n\n # Inject tag if not already present\n if \"'\n html_content = html_content.replace(\"\", f\"\\n {base_tag}\")\n\n return html_content\n\n\nif FRONTEND_BUILD_PATH.exists():\n # Build the cached HTML at import time\n _CACHED_INDEX_HTML = _build_cached_index_html()\n # Mount static files - path depends on ROOT_PATH\n # When ROOT_PATH is set, FastAPI automatically handles the prefix for routes,\n # but we need to explicitly mount static files at the root level\n # The tag in HTML will make browsers request /registry/static/*\n # which FastAPI will handle correctly with root_path\n app.mount(\"/static\", StaticFiles(directory=FRONTEND_BUILD_PATH / \"static\"), name=\"static\")\n\n # Serve React app for all other routes (SPA)\n @app.get(\"/{full_path:path}\")\n async def serve_react_app(full_path: str):\n \"\"\"Serve React app for all non-API routes\"\"\"\n # Import here to avoid circular dependency\n from registry.constants import REGISTRY_CONSTANTS\n\n # Don't serve React for API routes, Anthropic registry API, health checks, well-known discovery endpoints, and static files\n anthropic_api_prefix = f\"{REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION}/\"\n if (\n full_path.startswith(\"api/\")\n or full_path.startswith(anthropic_api_prefix)\n or full_path.startswith(\"health\")\n or full_path.startswith(\".well-known/\")\n or full_path.startswith(\"static/\")\n ): # Let static files mount handle these\n raise HTTPException(status_code=404)\n\n if _CACHED_INDEX_HTML is not None:\n return HTMLResponse(content=_CACHED_INDEX_HTML)\n\n return FileResponse(FRONTEND_BUILD_PATH / \"index.html\")\nelse:\n logger.warning(\n \"React build directory not found. Serve React app separately during development.\"\n )\n\n # Serve legacy templates and static files during development\n from fastapi.templating import Jinja2Templates\n\n app.mount(\"/static\", StaticFiles(directory=settings.static_dir), name=\"static\")\n templates = Jinja2Templates(directory=settings.templates_dir)\n\n\nif __name__ == \"__main__\":\n import uvicorn\n\n uvicorn.run(\n \"registry.main:app\",\n host=os.getenv(\"REGISTRY_HOST\", \"127.0.0.1\"), # nosec B104\n port=7860,\n reload=True,\n log_level=\"info\",\n proxy_headers=True,\n forwarded_allow_ips=\"*\",\n )\n" }, { "path": "registry/metrics/__init__.py", "content": "\"\"\"\nRegistry Metrics Integration Package\n\nProvides metrics collection for registry operations, MCP client calls,\nand request header analysis for dynamic nginx configuration.\n\"\"\"\n\nfrom .client import (\n EnhancedMCPClientDep,\n EnhancedMCPClientService,\n MetricsClient,\n MetricsCollector,\n MetricsCollectorDep,\n create_metrics_client,\n get_enhanced_mcp_client,\n get_metrics_collector,\n)\nfrom .middleware import RegistryMetricsMiddleware, add_registry_metrics_middleware\nfrom .utils import extract_server_name_from_url, hash_user_id\n\n__all__ = [\n \"MetricsClient\",\n \"create_metrics_client\",\n \"MetricsCollector\",\n \"EnhancedMCPClientService\",\n \"get_metrics_collector\",\n \"get_enhanced_mcp_client\",\n \"MetricsCollectorDep\",\n \"EnhancedMCPClientDep\",\n \"RegistryMetricsMiddleware\",\n \"add_registry_metrics_middleware\",\n \"extract_server_name_from_url\",\n \"hash_user_id\",\n]\n" }, { "path": "registry/metrics/client.py", "content": "\"\"\"\nMetrics client and enhanced MCP client for registry service.\n\nProvides both the basic metrics client and an enhanced MCP client service\nthat uses dependency injection for clean metrics collection.\n\"\"\"\n\nimport logging\nimport os\nimport time\nfrom contextlib import asynccontextmanager\nfrom datetime import datetime\nfrom typing import Any\n\n# Import HTTP client for metrics\nimport httpx\nfrom fastapi import Depends\n\nfrom .utils import extract_server_name_from_url\n\nlogger = logging.getLogger(__name__)\n\n\nclass MetricsClient:\n \"\"\"HTTP-based metrics client for registry service.\"\"\"\n\n def __init__(\n self,\n service_name: str = \"registry\",\n service_version: str = \"1.0.0\",\n metrics_url: str = None,\n api_key: str = None,\n timeout: float = 5.0,\n ):\n self.service_name = service_name\n self.service_version = service_version\n self.metrics_url = metrics_url or os.getenv(\"METRICS_SERVICE_URL\", \"http://localhost:8890\")\n self.api_key = api_key or os.getenv(\"METRICS_API_KEY\", \"\")\n self.client = httpx.AsyncClient(timeout=timeout)\n\n async def _emit_metric(\n self,\n metric_type: str,\n value: float = 1.0,\n duration_ms: float | None = None,\n dimensions: dict[str, Any] | None = None,\n metadata: dict[str, Any] | None = None,\n ) -> bool:\n \"\"\"Emit a metric to the metrics service.\"\"\"\n try:\n if not self.api_key:\n return False\n\n payload = {\n \"service\": self.service_name,\n \"version\": self.service_version,\n \"metrics\": [\n {\n \"type\": metric_type,\n \"timestamp\": datetime.utcnow().isoformat(),\n \"value\": value,\n \"duration_ms\": duration_ms,\n \"dimensions\": dimensions or {},\n \"metadata\": metadata or {},\n }\n ],\n }\n\n response = await self.client.post(\n f\"{self.metrics_url}/metrics\", json=payload, headers={\"X-API-Key\": self.api_key}\n )\n\n return response.status_code == 200\n except Exception as e:\n logger.debug(f\"Failed to emit metric {metric_type}: {e}\")\n return False\n\n async def emit_registry_metric(\n self,\n operation: str,\n resource_type: str,\n success: bool,\n duration_ms: float,\n resource_id: str | None = None,\n user_id: str | None = None,\n error_code: str | None = None,\n ) -> bool:\n \"\"\"Emit registry operation metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"registry_operation\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\n \"operation\": operation,\n \"resource_type\": resource_type,\n \"success\": success,\n \"resource_id\": resource_id or \"\",\n \"user_id\": user_id or \"\",\n },\n metadata={\"error_code\": error_code},\n )\n\n async def emit_discovery_metric(\n self,\n query: str,\n results_count: int,\n duration_ms: float,\n top_k_services: int | None = None,\n top_n_tools: int | None = None,\n embedding_time_ms: float | None = None,\n faiss_search_time_ms: float | None = None,\n ) -> bool:\n \"\"\"Emit tool discovery metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"tool_discovery\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\n \"query\": query[:100],\n \"results_count\": results_count,\n \"top_k_services\": top_k_services,\n \"top_n_tools\": top_n_tools,\n },\n metadata={\n \"embedding_time_ms\": embedding_time_ms,\n \"faiss_search_time_ms\": faiss_search_time_ms,\n },\n )\n\n async def emit_tool_execution_metric(\n self,\n tool_name: str,\n server_path: str,\n server_name: str,\n success: bool,\n duration_ms: float,\n input_size_bytes: int | None = None,\n output_size_bytes: int | None = None,\n error_code: str | None = None,\n ) -> bool:\n \"\"\"Emit tool execution metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"tool_execution\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\n \"tool_name\": tool_name,\n \"server_path\": server_path,\n \"server_name\": server_name,\n \"success\": success,\n },\n metadata={\n \"error_code\": error_code,\n \"input_size_bytes\": input_size_bytes,\n \"output_size_bytes\": output_size_bytes,\n },\n )\n\n async def emit_health_metric(\n self, endpoint: str, status_code: int, duration_ms: float, healthy: bool = True\n ) -> bool:\n \"\"\"Emit health check metric.\"\"\"\n return await self._emit_metric(\n metric_type=\"health_check\",\n value=1.0,\n duration_ms=duration_ms,\n dimensions={\"endpoint\": endpoint, \"status_code\": status_code, \"healthy\": healthy},\n )\n\n async def emit_custom_metric(\n self,\n metric_name: str,\n value: float,\n duration_ms: float | None = None,\n dimensions: dict[str, Any] | None = None,\n metadata: dict[str, Any] | None = None,\n ) -> bool:\n \"\"\"Emit custom metric with arbitrary data.\"\"\"\n custom_dimensions = {\"metric_name\": metric_name}\n if dimensions:\n custom_dimensions.update(dimensions)\n\n return await self._emit_metric(\n metric_type=\"custom\",\n value=value,\n duration_ms=duration_ms,\n dimensions=custom_dimensions,\n metadata=metadata,\n )\n\n\ndef create_metrics_client(service_name: str = \"registry\", **kwargs) -> MetricsClient:\n \"\"\"Create a registry metrics client with default configuration.\"\"\"\n return MetricsClient(service_name=service_name, **kwargs)\n\n\nclass MetricsCollector:\n \"\"\"\n Metrics collection service for MCP operations.\n\n Uses dependency injection to provide clean, testable metrics collection\n for MCP client calls and other registry operations.\n \"\"\"\n\n def __init__(self, service_name: str = \"registry\"):\n self.metrics_client = create_metrics_client(service_name=service_name)\n self._enabled = True\n\n def is_enabled(self) -> bool:\n \"\"\"Check if metrics collection is enabled.\"\"\"\n return self._enabled\n\n def disable(self):\n \"\"\"Disable metrics collection (useful for testing).\"\"\"\n self._enabled = False\n\n def enable(self):\n \"\"\"Enable metrics collection.\"\"\"\n self._enabled = True\n\n @asynccontextmanager\n async def track_tool_discovery(self, server_url: str):\n \"\"\"\n Context manager to track tool discovery operations.\n\n Usage:\n async with metrics.track_tool_discovery(server_url) as tracker:\n tools = await get_tools_from_server(server_url)\n tracker.set_result(tools)\n \"\"\"\n if not self._enabled:\n yield _NoOpTracker()\n return\n\n start_time = time.perf_counter()\n server_name = extract_server_name_from_url(server_url)\n tracker = _ToolDiscoveryTracker(self.metrics_client, server_name, server_url, start_time)\n\n try:\n yield tracker\n except Exception as e:\n tracker.set_error(e)\n raise\n finally:\n await tracker.finish()\n\n @asynccontextmanager\n async def track_health_check(self, server_url: str):\n \"\"\"Context manager to track health check operations.\"\"\"\n if not self._enabled:\n yield _NoOpTracker()\n return\n\n start_time = time.perf_counter()\n server_name = extract_server_name_from_url(server_url)\n tracker = _HealthCheckTracker(self.metrics_client, server_name, start_time)\n\n try:\n yield tracker\n except Exception as e:\n tracker.set_error(e)\n raise\n finally:\n await tracker.finish()\n\n\nclass _ToolDiscoveryTracker:\n \"\"\"Tracker for tool discovery operations.\"\"\"\n\n def __init__(self, metrics_client, server_name: str, server_url: str, start_time: float):\n self.metrics_client = metrics_client\n self.server_name = server_name\n self.server_url = server_url\n self.start_time = start_time\n self.success = False\n self.tools_count = 0\n self.error_code = None\n\n def set_result(self, tools: list[dict] | None):\n \"\"\"Set the result of the tool discovery operation.\"\"\"\n if tools is not None:\n self.success = True\n self.tools_count = len(tools)\n\n def set_error(self, error: Exception):\n \"\"\"Set error information.\"\"\"\n self.success = False\n self.error_code = type(error).__name__\n\n async def finish(self):\n \"\"\"Emit metrics for the completed operation.\"\"\"\n duration_ms = (time.perf_counter() - self.start_time) * 1000\n\n try:\n # Emit discovery metric\n await self.metrics_client.emit_discovery_metric(\n query=f\"tools_from_{self.server_name}\",\n results_count=self.tools_count if self.success else 0,\n duration_ms=duration_ms,\n )\n\n # Emit tool execution metric for MCP protocol interaction\n await self.metrics_client.emit_tool_execution_metric(\n tool_name=\"tools/list\",\n server_path=self.server_url,\n server_name=self.server_name,\n success=self.success,\n duration_ms=duration_ms,\n output_size_bytes=self.tools_count * 100 if self.success else 0,\n error_code=self.error_code,\n )\n except Exception as e:\n logger.debug(f\"Failed to emit tool discovery metrics: {e}\")\n\n\nclass _HealthCheckTracker:\n \"\"\"Tracker for health check operations.\"\"\"\n\n def __init__(self, metrics_client, server_name: str, start_time: float):\n self.metrics_client = metrics_client\n self.server_name = server_name\n self.start_time = start_time\n self.success = False\n self.error_code = None\n\n def set_success(self):\n \"\"\"Mark the health check as successful.\"\"\"\n self.success = True\n\n def set_error(self, error: Exception):\n \"\"\"Set error information.\"\"\"\n self.success = False\n self.error_code = type(error).__name__\n\n async def finish(self):\n \"\"\"Emit metrics for the completed health check.\"\"\"\n duration_ms = (time.perf_counter() - self.start_time) * 1000\n\n try:\n await self.metrics_client.emit_health_metric(\n endpoint=f\"/health/{self.server_name}\",\n status_code=200 if self.success else 500,\n duration_ms=duration_ms,\n healthy=self.success,\n )\n except Exception as e:\n logger.debug(f\"Failed to emit health check metric: {e}\")\n\n\nclass _NoOpTracker:\n \"\"\"No-op tracker for when metrics are disabled.\"\"\"\n\n def set_result(self, *args, **kwargs):\n pass\n\n def set_error(self, *args, **kwargs):\n pass\n\n def set_success(self, *args, **kwargs):\n pass\n\n async def finish(self):\n pass\n\n\nclass EnhancedMCPClientService:\n \"\"\"\n Enhanced MCP client service with metrics collection.\n\n Uses dependency injection to cleanly add metrics to MCP operations\n without modifying the original client.\n \"\"\"\n\n def __init__(self, metrics_collector: MetricsCollector):\n self.metrics_collector = metrics_collector\n # Import here to avoid circular imports\n from ..core.mcp_client import mcp_client_service\n\n self.original_client = mcp_client_service\n\n async def get_tools_from_server_with_server_info(\n self, base_url: str, server_info: dict = None\n ) -> list[dict] | None:\n \"\"\"Get tools from MCP server with metrics collection.\"\"\"\n async with self.metrics_collector.track_tool_discovery(base_url) as tracker:\n # Call the original client method\n result = await self.original_client.get_tools_from_server_with_server_info(\n base_url, server_info\n )\n\n # Set the result for metrics tracking\n tracker.set_result(result)\n\n return result\n\n\n# Global instances\n_metrics_collector = None\n_enhanced_mcp_client = None\n\n\ndef get_metrics_collector() -> MetricsCollector:\n \"\"\"Dependency to get the metrics collector instance.\"\"\"\n global _metrics_collector\n if _metrics_collector is None:\n _metrics_collector = MetricsCollector()\n return _metrics_collector\n\n\ndef get_enhanced_mcp_client(\n metrics_collector: MetricsCollector = Depends(get_metrics_collector),\n) -> EnhancedMCPClientService:\n \"\"\"Dependency to get the enhanced MCP client service.\"\"\"\n return EnhancedMCPClientService(metrics_collector)\n\n\n# Convenient dependency aliases\nMetricsCollectorDep = Depends(get_metrics_collector)\nEnhancedMCPClientDep = Depends(get_enhanced_mcp_client)\n" }, { "path": "registry/metrics/middleware.py", "content": "\"\"\"\nFastAPI middleware for registry metrics collection.\n\nTracks registry operations, request headers, and API usage patterns.\n\"\"\"\n\nimport asyncio\nimport logging\nimport time\nfrom collections.abc import Callable\nfrom typing import Any\n\nfrom fastapi import Request, Response\nfrom starlette.middleware.base import BaseHTTPMiddleware\n\nfrom .client import create_metrics_client\nfrom .utils import extract_headers_for_analysis, hash_user_id\n\nlogger = logging.getLogger(__name__)\n\n\nclass RegistryMetricsMiddleware(BaseHTTPMiddleware):\n \"\"\"\n Middleware to collect registry operation and request metrics.\n\n Tracks:\n - Registry operations (server CRUD, search, health)\n - Request headers for nginx config analysis\n - API usage patterns\n \"\"\"\n\n def __init__(self, app, service_name: str = \"registry\"):\n super().__init__(app)\n self.metrics_client = create_metrics_client(service_name=service_name)\n\n def extract_operation_info(self, request: Request) -> dict[str, Any]:\n \"\"\"Extract operation type and resource information from the request.\"\"\"\n path = request.url.path\n method = request.method\n\n # Skip non-API endpoints\n if not path.startswith(\"/api/\"):\n return None\n\n # Determine operation and resource type\n operation = \"unknown\"\n resource_type = \"unknown\"\n resource_id = \"\"\n\n # Map HTTP methods to operations\n method_mapping = {\n \"GET\": \"read\",\n \"POST\": \"create\",\n \"PUT\": \"update\",\n \"PATCH\": \"update\",\n \"DELETE\": \"delete\",\n }\n\n operation = method_mapping.get(method, \"unknown\")\n\n # Parse path to determine resource type and ID\n path_parts = [p for p in path.split(\"/\") if p] # Remove empty parts\n\n if len(path_parts) >= 2 and path_parts[0] == \"api\":\n if path_parts[1] == \"servers\":\n resource_type = \"server\"\n if len(path_parts) >= 3:\n resource_id = path_parts[2]\n # Special case for GET /api/servers - this is a list operation\n if method == \"GET\" and len(path_parts) == 2:\n operation = \"list\"\n elif path_parts[1] == \"search\":\n resource_type = \"search\"\n operation = \"search\"\n elif path_parts[1] == \"health\":\n resource_type = \"health\"\n operation = \"check\"\n elif path_parts[1] == \"auth\":\n resource_type = \"auth\"\n if len(path_parts) >= 3:\n if path_parts[2] == \"login\":\n operation = \"login\"\n elif path_parts[2] == \"logout\":\n operation = \"logout\"\n elif path_parts[2] == \"me\":\n operation = \"profile\"\n\n return {\n \"operation\": operation,\n \"resource_type\": resource_type,\n \"resource_id\": resource_id,\n \"path\": path,\n }\n\n def extract_user_info(self, request: Request) -> str:\n \"\"\"Extract user information from request headers or auth context.\"\"\"\n # Try to get user from various headers\n user_id = request.headers.get(\"X-User\", \"\")\n if not user_id:\n user_id = request.headers.get(\"X-Username\", \"\")\n\n return hash_user_id(user_id)\n\n def should_track_request(self, request: Request) -> bool:\n \"\"\"Determine if the request should be tracked for metrics.\"\"\"\n path = request.url.path\n\n # Skip static files and non-API endpoints\n if (\n path.startswith(\"/static/\")\n or path.startswith(\"/favicon.ico\")\n or path == \"/\"\n or path == \"/docs\"\n or path == \"/openapi.json\"\n ):\n return False\n\n return True\n\n async def dispatch(self, request: Request, call_next: Callable) -> Response:\n \"\"\"Process request and collect metrics.\"\"\"\n # Skip tracking for certain endpoints\n if not self.should_track_request(request):\n return await call_next(request)\n\n # Start timing\n start_time = time.perf_counter()\n\n # Extract operation information\n operation_info = self.extract_operation_info(request)\n if not operation_info:\n return await call_next(request)\n\n # Extract user and header information\n user_hash = self.extract_user_info(request)\n headers_info = extract_headers_for_analysis(dict(request.headers))\n\n # Process the request\n response = None\n success = False\n error_code = None\n\n try:\n response = await call_next(request)\n\n # Work around Starlette BaseHTTPMiddleware bug with 204 responses\n if response.status_code == 204:\n response = Response(status_code=204, headers=dict(response.headers))\n\n # Determine success based on response status\n success = 200 <= response.status_code < 400\n\n if not success:\n error_code = str(response.status_code)\n\n except Exception as e:\n # Handle exceptions during request processing\n success = False\n error_code = type(e).__name__\n logger.error(f\"Error in registry request: {e}\")\n # Re-raise the exception to maintain normal error handling\n raise\n\n finally:\n # Calculate duration\n duration_ms = (time.perf_counter() - start_time) * 1000\n\n # Emit registry operation metric asynchronously\n asyncio.create_task(\n self._emit_registry_metric(\n operation=operation_info[\"operation\"],\n resource_type=operation_info[\"resource_type\"],\n success=success,\n duration_ms=duration_ms,\n resource_id=operation_info[\"resource_id\"],\n user_id=user_hash,\n error_code=error_code,\n )\n )\n\n # Emit headers analysis metric for nginx config insights\n if success and operation_info[\"resource_type\"] != \"health\":\n asyncio.create_task(\n self._emit_headers_metric(\n path=operation_info[\"path\"],\n method=request.method,\n headers_info=headers_info,\n status_code=response.status_code if response else 500,\n )\n )\n\n # If this is a search operation, emit discovery metric too\n if operation_info[\"resource_type\"] == \"search\" and success:\n asyncio.create_task(\n self._emit_discovery_metric_from_request(\n request=request, duration_ms=duration_ms\n )\n )\n\n return response\n\n async def _emit_registry_metric(\n self,\n operation: str,\n resource_type: str,\n success: bool,\n duration_ms: float,\n resource_id: str = \"\",\n user_id: str = \"\",\n error_code: str = None,\n ):\n \"\"\"Emit registry operation metric asynchronously.\"\"\"\n try:\n await self.metrics_client.emit_registry_metric(\n operation=operation,\n resource_type=resource_type,\n success=success,\n duration_ms=duration_ms,\n resource_id=resource_id,\n user_id=user_id,\n error_code=error_code,\n )\n except Exception as e:\n logger.debug(f\"Failed to emit registry metric: {e}\")\n\n async def _emit_headers_metric(\n self, path: str, method: str, headers_info: dict[str, Any], status_code: int\n ):\n \"\"\"Emit custom metric with request header information for nginx config analysis.\"\"\"\n try:\n await self.metrics_client.emit_custom_metric(\n metric_name=\"request_headers_analysis\",\n value=1.0,\n dimensions={\n \"path\": path,\n \"method\": method,\n \"status_code\": status_code,\n \"has_auth\": headers_info.get(\"authorization_present\", False),\n \"user_agent_type\": headers_info.get(\"user_agent_type\", \"unknown\"),\n \"content_type\": headers_info.get(\"content_type\", \"unknown\")[:50],\n \"has_origin\": headers_info.get(\"origin\", \"unknown\") != \"unknown\",\n },\n metadata={\n \"headers_sample\": str(headers_info)[:500] # Truncated sample\n },\n )\n except Exception as e:\n logger.debug(f\"Failed to emit headers metric: {e}\")\n\n async def _emit_discovery_metric_from_request(self, request: Request, duration_ms: float):\n \"\"\"Emit discovery metric for search operations.\"\"\"\n try:\n # Extract query from request parameters\n query_params = request.query_params\n query = query_params.get(\"q\", query_params.get(\"query\", \"unknown\"))\n\n # For now, we can't easily get the results count from the response\n # without parsing the response body, so we'll set a placeholder\n results_count = -1 # Indicates count not available\n\n await self.metrics_client.emit_discovery_metric(\n query=query, results_count=results_count, duration_ms=duration_ms\n )\n except Exception as e:\n logger.debug(f\"Failed to emit discovery metric: {e}\")\n\n\ndef add_registry_metrics_middleware(app, service_name: str = \"registry\"):\n \"\"\"\n Convenience function to add registry metrics middleware to a FastAPI app.\n\n Args:\n app: FastAPI application instance\n service_name: Name of the service for metrics identification\n \"\"\"\n app.add_middleware(RegistryMetricsMiddleware, service_name=service_name)\n logger.info(f\"Registry metrics middleware added for service: {service_name}\")\n" }, { "path": "registry/metrics/utils.py", "content": "\"\"\"\nUtility functions for metrics collection in the registry.\n\"\"\"\n\nimport hashlib\nimport logging\nfrom typing import Any\nfrom urllib.parse import urlparse\n\nlogger = logging.getLogger(__name__)\n\n\ndef extract_server_name_from_url(url: str) -> str:\n \"\"\"Extract server name from MCP server URL.\"\"\"\n if not url:\n return \"unknown\"\n\n try:\n # URL format is typically http://host:port/server_name/\n parsed = urlparse(url)\n path_parts = [p for p in parsed.path.split(\"/\") if p]\n return path_parts[0] if path_parts else \"unknown\"\n except Exception:\n return \"unknown\"\n\n\ndef hash_user_id(user_id: str) -> str:\n \"\"\"Hash user ID for privacy in metrics.\"\"\"\n if not user_id:\n return \"\"\n return hashlib.sha256(user_id.encode()).hexdigest()[:12]\n\n\ndef categorize_user_agent(user_agent: str) -> str:\n \"\"\"Categorize user agent for metrics analysis.\"\"\"\n if not user_agent:\n return \"unknown\"\n\n user_agent_lower = user_agent.lower()\n\n if \"curl\" in user_agent_lower:\n return \"curl\"\n elif \"postman\" in user_agent_lower:\n return \"postman\"\n elif \"chrome\" in user_agent_lower:\n return \"chrome\"\n elif \"firefox\" in user_agent_lower:\n return \"firefox\"\n elif \"safari\" in user_agent_lower:\n return \"safari\"\n elif \"python\" in user_agent_lower or \"requests\" in user_agent_lower:\n return \"python_client\"\n elif \"bot\" in user_agent_lower or \"crawler\" in user_agent_lower:\n return \"bot\"\n else:\n return \"other\"\n\n\ndef extract_headers_for_analysis(headers: dict[str, str]) -> dict[str, Any]:\n \"\"\"Extract and categorize headers for nginx config analysis.\"\"\"\n return {\n \"user_agent_type\": categorize_user_agent(headers.get(\"user-agent\", \"\")),\n \"accept\": headers.get(\"accept\", \"unknown\"),\n \"content_type\": headers.get(\"content-type\", \"unknown\"),\n \"authorization_present\": bool(headers.get(\"authorization\")),\n \"x_forwarded_for_present\": bool(headers.get(\"x-forwarded-for\")),\n \"origin\": headers.get(\"origin\", \"unknown\"),\n \"referer_present\": bool(headers.get(\"referer\")),\n \"connection\": headers.get(\"connection\", \"unknown\"),\n \"upgrade\": headers.get(\"upgrade\", \"unknown\"),\n }\n" }, { "path": "registry/middleware/__init__.py", "content": "\"\"\"Middleware package for MCP Gateway Registry.\"\"\"\n\nfrom .mode_filter import RegistryModeMiddleware\n\n__all__ = [\"RegistryModeMiddleware\"]\n" }, { "path": "registry/middleware/mode_filter.py", "content": "\"\"\"\nMiddleware to filter API endpoints based on registry mode.\n\nThis middleware enforces registry mode restrictions by returning 403 Forbidden\nfor endpoints that are disabled in the current mode (e.g., skills-only mode\nblocks /api/servers and /api/agents endpoints).\n\"\"\"\n\nimport logging\nfrom collections.abc import Callable\n\nfrom fastapi import Request, Response\nfrom fastapi.responses import JSONResponse\nfrom starlette.middleware.base import BaseHTTPMiddleware\n\nfrom ..core.config import RegistryMode, settings\nfrom ..core.metrics import MODE_BLOCKED_REQUESTS\n\nlogger = logging.getLogger(__name__)\n\n\n# Endpoints that are always allowed regardless of mode\n# These are administrative/infrastructure endpoints, not feature-specific\nALWAYS_ALLOWED_PREFIXES = (\n \"/health\",\n \"/api/version\",\n \"/api/stats\",\n \"/api/config\",\n \"/api/auth/\",\n \"/api/tokens/\",\n \"/api/audit/\",\n \"/api/management/\",\n \"/oauth2/\",\n \"/docs\",\n \"/openapi.json\",\n \"/redoc\",\n \"/static/\",\n \"/assets/\",\n \"/_next/\",\n \"/validate\",\n \"/favicon\",\n)\n\n# API endpoints allowed in skills-only mode\nSKILLS_MODE_ALLOWED_PREFIXES = (\n \"/api/skills\",\n \"/api/search/semantic\",\n)\n\n# API endpoints allowed in mcp-servers-only mode\nMCP_SERVERS_MODE_ALLOWED_PREFIXES = (\n \"/api/servers\",\n \"/api/search/semantic\",\n \"/.well-known/mcp-servers\",\n)\n\n# API endpoints allowed in agents-only mode\nAGENTS_MODE_ALLOWED_PREFIXES = (\n \"/api/agents\",\n \"/api/search/semantic\",\n)\n\n\ndef _is_path_allowed(path: str, mode: RegistryMode) -> bool:\n \"\"\"Check if path is allowed for the given registry mode.\n\n Args:\n path: Request URL path\n mode: Current registry mode\n\n Returns:\n True if path is allowed, False otherwise\n \"\"\"\n # Always allowed paths (auth, health, docs, static, etc.)\n for prefix in ALWAYS_ALLOWED_PREFIXES:\n if path.startswith(prefix):\n return True\n\n # Full mode allows everything\n if mode == RegistryMode.FULL:\n return True\n\n # Skills-only mode\n if mode == RegistryMode.SKILLS_ONLY:\n # Allow skills-related endpoints\n for prefix in SKILLS_MODE_ALLOWED_PREFIXES:\n if path.startswith(prefix):\n return True\n # Allow well-known but it will return empty list\n if path.startswith(\"/.well-known/\"):\n return True\n # Block all other /api/* endpoints\n if path.startswith(\"/api/\"):\n return False\n # Allow non-API paths (frontend, etc.)\n return True\n\n # MCP-servers-only mode\n if mode == RegistryMode.MCP_SERVERS_ONLY:\n for prefix in MCP_SERVERS_MODE_ALLOWED_PREFIXES:\n if path.startswith(prefix):\n return True\n if path.startswith(\"/api/\"):\n return False\n return True\n\n # Agents-only mode\n if mode == RegistryMode.AGENTS_ONLY:\n for prefix in AGENTS_MODE_ALLOWED_PREFIXES:\n if path.startswith(prefix):\n return True\n if path.startswith(\"/api/\"):\n return False\n return True\n\n # Unknown mode - allow by default\n return True\n\n\ndef _get_path_category(path: str) -> str:\n \"\"\"Extract path category for metrics labeling.\n\n Args:\n path: Request URL path\n\n Returns:\n Category string for metrics (e.g., 'servers', 'agents', 'federation')\n \"\"\"\n if path.startswith(\"/api/servers\"):\n return \"servers\"\n if path.startswith(\"/api/agents\"):\n return \"agents\"\n if path.startswith(\"/api/skills\"):\n return \"skills\"\n if path.startswith(\"/api/federation\") or path.startswith(\"/api/peers\"):\n return \"federation\"\n if path.startswith(\"/api/\"):\n parts = path.split(\"/\")\n if len(parts) > 2:\n return parts[2]\n return \"other\"\n\n\nclass RegistryModeMiddleware(BaseHTTPMiddleware):\n \"\"\"Middleware to filter requests based on registry mode.\"\"\"\n\n async def dispatch(self, request: Request, call_next: Callable) -> Response:\n \"\"\"Process request and block if endpoint is disabled for current mode.\n\n Args:\n request: Incoming HTTP request\n call_next: Next handler in middleware chain\n\n Returns:\n Response from next handler or 403 if blocked\n \"\"\"\n path = request.url.path\n mode = settings.registry_mode\n\n # Check if path is allowed for current mode\n if not _is_path_allowed(path, mode):\n # Log blocked request\n client_host = request.client.host if request.client else \"unknown\"\n logger.warning(\n f\"Blocked request to '{path}' - endpoint disabled in {mode.value} mode. \"\n f\"Client: {client_host}\"\n )\n\n # Increment metrics counter\n category = _get_path_category(path)\n MODE_BLOCKED_REQUESTS.labels(path_category=category, mode=mode.value).inc()\n\n return JSONResponse(\n status_code=403,\n content={\n \"detail\": f\"This endpoint is disabled in {mode.value} mode\",\n \"error\": \"endpoint_disabled\",\n \"registry_mode\": mode.value,\n \"path\": path,\n },\n )\n\n return await call_next(request)\n" }, { "path": "registry/models/idp_m2m_client.py", "content": "\"\"\"IdP M2M Client model for MongoDB storage.\n\nThis module defines the schema for storing M2M client applications\nand their group mappings in MongoDB. This allows the registry to track\nservice accounts from any IdP (Keycloak, Okta, Entra) and their permissions\nwithout hardcoding them in authorization server expressions.\n\nThis collection serves as the authorization database for M2M clients.\n\"\"\"\n\nfrom datetime import datetime\n\nfrom pydantic import BaseModel, Field\n\n\nclass IdPM2MClient(BaseModel):\n \"\"\"IdP M2M client application with group mappings.\n\n Stores information about M2M service accounts from any identity provider\n including their client IDs, groups, and metadata. This data is used for\n authorization decisions when JWT tokens have empty groups claim.\n \"\"\"\n\n client_id: str = Field(..., description=\"IdP application client ID\")\n name: str = Field(..., description=\"Application name\")\n description: str | None = Field(None, description=\"Application description\")\n groups: list[str] = Field(default_factory=list, description=\"Groups this client belongs to\")\n enabled: bool = Field(default=True, description=\"Whether client is active\")\n provider: str = Field(..., description=\"Identity provider (okta, keycloak, entra)\")\n created_at: datetime = Field(\n default_factory=datetime.utcnow, description=\"When record was created\"\n )\n updated_at: datetime = Field(\n default_factory=datetime.utcnow, description=\"When record was last updated\"\n )\n idp_app_id: str | None = Field(None, description=\"IdP internal app ID\")\n\n class Config:\n \"\"\"Pydantic model configuration.\"\"\"\n\n json_schema_extra = {\n \"example\": {\n \"client_id\": \"0oa1100req1AzfKaY698\",\n \"name\": \"ai-agent\",\n \"description\": \"AI agent with admin access\",\n \"groups\": [\"registry-admins\"],\n \"enabled\": True,\n \"provider\": \"okta\",\n \"idp_app_id\": \"0oa1100req1AzfKaY698\",\n }\n }\n\n\nclass IdPM2MClientUpdate(BaseModel):\n \"\"\"Payload for updating an IdP M2M client's group mappings.\"\"\"\n\n groups: list[str] = Field(..., description=\"New list of groups for this client\", min_length=1)\n description: str | None = Field(None, description=\"Updated description\")\n" }, { "path": "registry/repositories/__init__.py", "content": "" }, { "path": "registry/repositories/app_log_repository.py", "content": "\"\"\"Read-only repository for querying application logs stored in MongoDB.\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom .documentdb.client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass AppLogRepository:\n \"\"\"Queries the ``application_logs`` collection written by MongoDBLogHandler.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"application_logs\")\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def query(\n self,\n service: str | None = None,\n level_no: int | None = None,\n hostname: str | None = None,\n start: datetime | None = None,\n end: datetime | None = None,\n search: str | None = None,\n skip: int = 0,\n limit: int = 100,\n ) -> tuple[list[dict[str, Any]], int]:\n \"\"\"Query application log entries with filtering and pagination.\n\n Args:\n service: Filter by service name (registry, auth-server).\n level_no: Minimum log level number (10=DEBUG, 20=INFO, etc.).\n hostname: Filter by pod/hostname.\n start: Only include entries at or after this timestamp.\n end: Only include entries at or before this timestamp.\n search: Substring search within the message field (pre-escaped).\n skip: Number of entries to skip (offset).\n limit: Maximum number of entries to return.\n\n Returns:\n Tuple of (list of log documents, total matching count).\n \"\"\"\n collection = await self._get_collection()\n\n query_filter: dict[str, Any] = {}\n\n if service:\n query_filter[\"service\"] = service\n if level_no is not None:\n query_filter[\"level_no\"] = {\"$gte\": level_no}\n if hostname:\n query_filter[\"hostname\"] = hostname\n\n time_filter: dict[str, Any] = {}\n if start:\n time_filter[\"$gte\"] = start\n if end:\n time_filter[\"$lte\"] = end\n if time_filter:\n query_filter[\"timestamp\"] = time_filter\n\n if search:\n query_filter[\"message\"] = {\"$regex\": search, \"$options\": \"i\"}\n\n try:\n if not query_filter:\n total = await collection.estimated_document_count()\n else:\n total = await collection.count_documents(query_filter)\n\n cursor = collection.find(query_filter).sort(\"timestamp\", -1).skip(skip).limit(limit)\n\n results: list[dict[str, Any]] = []\n async for doc in cursor:\n doc.pop(\"_id\", None)\n results.append(doc)\n\n return results, total\n except Exception as e:\n logger.error(f\"Error querying application logs: {e}\", exc_info=True)\n return [], 0\n\n async def get_distinct_services(self) -> list[str]:\n \"\"\"Get list of distinct service names in the log collection.\"\"\"\n collection = await self._get_collection()\n try:\n return await collection.distinct(\"service\")\n except Exception as e:\n logger.error(f\"Error fetching distinct services: {e}\", exc_info=True)\n return []\n\n async def get_distinct_hostnames(self) -> list[str]:\n \"\"\"Get list of distinct hostnames in the log collection.\"\"\"\n collection = await self._get_collection()\n try:\n return await collection.distinct(\"hostname\")\n except Exception as e:\n logger.error(f\"Error fetching distinct hostnames: {e}\", exc_info=True)\n return []\n" }, { "path": "registry/repositories/audit_repository.py", "content": "\"\"\"\nAudit repository for storing and querying audit events.\n\nThis module provides the abstract base class and DocumentDB implementation\nfor audit event storage, supporting the audit logging system's MongoDB\nwarm storage requirements.\n\"\"\"\n\nimport logging\nfrom abc import ABC, abstractmethod\nfrom datetime import UTC, datetime\nfrom typing import Any, Union\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\nfrom pymongo.errors import DuplicateKeyError\n\nfrom ..audit.models import MCPServerAccessRecord, RegistryApiAccessRecord\nfrom .documentdb.client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n# Type alias for audit records\nAuditRecord = Union[RegistryApiAccessRecord, MCPServerAccessRecord]\n\n\nclass AuditRepositoryBase(ABC):\n \"\"\"\n Abstract base class for audit event data access.\n\n Implementations:\n - DocumentDBAuditRepository: MongoDB/DocumentDB storage with TTL\n \"\"\"\n\n @abstractmethod\n async def find(\n self,\n query: dict[str, Any],\n limit: int = 50,\n offset: int = 0,\n sort_field: str = \"timestamp\",\n sort_order: int = -1,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Find audit events matching the query.\n\n Args:\n query: MongoDB query filter\n limit: Maximum number of results to return\n offset: Number of results to skip for pagination\n sort_field: Field to sort by (default: timestamp)\n sort_order: Sort order (-1 for descending, 1 for ascending)\n\n Returns:\n List of audit event documents\n \"\"\"\n pass\n\n @abstractmethod\n async def find_one(\n self,\n query: dict[str, Any],\n ) -> dict[str, Any] | None:\n \"\"\"\n Find a single audit event matching the query.\n\n Args:\n query: MongoDB query filter\n\n Returns:\n Audit event document if found, None otherwise\n \"\"\"\n pass\n\n @abstractmethod\n async def count(\n self,\n query: dict[str, Any],\n ) -> int:\n \"\"\"\n Count audit events matching the query.\n\n Args:\n query: MongoDB query filter\n\n Returns:\n Number of matching documents\n \"\"\"\n pass\n\n @abstractmethod\n async def distinct(\n self,\n field: str,\n query: dict[str, Any] | None = None,\n ) -> list[str]:\n \"\"\"\n Get distinct values for a field in audit events.\n\n Args:\n field: The document field path (e.g., 'identity.username')\n query: Optional filter query to scope the distinct values\n\n Returns:\n Sorted list of distinct string values\n \"\"\"\n pass\n\n @abstractmethod\n async def aggregate(\n self,\n pipeline: list[dict[str, Any]],\n ) -> list[dict[str, Any]]:\n \"\"\"\n Run a MongoDB aggregation pipeline on audit events.\n\n Args:\n pipeline: MongoDB aggregation pipeline stages\n\n Returns:\n List of aggregation result documents\n \"\"\"\n pass\n\n @abstractmethod\n async def insert(\n self,\n record: AuditRecord,\n ) -> bool:\n \"\"\"\n Insert an audit event record.\n\n Args:\n record: The audit record to insert (RegistryApiAccessRecord or MCPServerAccessRecord)\n\n Returns:\n True if inserted successfully, False otherwise\n \"\"\"\n pass\n\n\nclass DocumentDBAuditRepository(AuditRepositoryBase):\n \"\"\"\n DocumentDB/MongoDB implementation of audit repository.\n\n Stores audit events in a MongoDB collection with TTL index\n for automatic expiration of old events.\n \"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"audit_events\")\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def find(\n self,\n query: dict[str, Any],\n limit: int = 50,\n offset: int = 0,\n sort_field: str = \"timestamp\",\n sort_order: int = -1,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Find audit events matching the query.\n\n Args:\n query: MongoDB query filter\n limit: Maximum number of results to return\n offset: Number of results to skip for pagination\n sort_field: Field to sort by (default: timestamp)\n sort_order: Sort order (-1 for descending, 1 for ascending)\n\n Returns:\n List of audit event documents\n \"\"\"\n logger.debug(\n f\"DocumentDB READ: Finding audit events with query={query}, \"\n f\"limit={limit}, offset={offset}\"\n )\n collection = await self._get_collection()\n\n try:\n cursor = collection.find(query)\n cursor = cursor.sort(sort_field, sort_order)\n cursor = cursor.skip(offset).limit(limit)\n\n events = []\n async for doc in cursor:\n # Convert _id to string if it's an ObjectId\n if \"_id\" in doc:\n doc[\"_id\"] = str(doc[\"_id\"])\n # Motor returns naive datetimes; re-attach UTC for correct serialization\n if isinstance(doc.get(\"timestamp\"), datetime) and doc[\"timestamp\"].tzinfo is None:\n doc[\"timestamp\"] = doc[\"timestamp\"].replace(tzinfo=UTC)\n events.append(doc)\n\n logger.debug(f\"DocumentDB READ: Found {len(events)} audit events\")\n return events\n except Exception as e:\n logger.error(f\"Error finding audit events: {e}\", exc_info=True)\n return []\n\n async def find_one(\n self,\n query: dict[str, Any],\n ) -> dict[str, Any] | None:\n \"\"\"\n Find a single audit event matching the query.\n\n Args:\n query: MongoDB query filter\n\n Returns:\n Audit event document if found, None otherwise\n \"\"\"\n logger.debug(f\"DocumentDB READ: Finding single audit event with query={query}\")\n collection = await self._get_collection()\n\n try:\n doc = await collection.find_one(query)\n if doc:\n # Convert _id to string if it's an ObjectId\n if \"_id\" in doc:\n doc[\"_id\"] = str(doc[\"_id\"])\n # Motor returns naive datetimes; re-attach UTC for correct serialization\n if isinstance(doc.get(\"timestamp\"), datetime) and doc[\"timestamp\"].tzinfo is None:\n doc[\"timestamp\"] = doc[\"timestamp\"].replace(tzinfo=UTC)\n logger.debug(\n f\"DocumentDB READ: Found audit event with request_id={doc.get('request_id')}\"\n )\n else:\n logger.debug(\"DocumentDB READ: Audit event not found\")\n return doc\n except Exception as e:\n logger.error(f\"Error finding audit event: {e}\", exc_info=True)\n return None\n\n async def count(\n self,\n query: dict[str, Any],\n ) -> int:\n \"\"\"\n Count audit events matching the query.\n\n Args:\n query: MongoDB query filter\n\n Returns:\n Number of matching documents\n \"\"\"\n logger.debug(f\"DocumentDB READ: Counting audit events with query={query}\")\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents(query)\n logger.debug(f\"DocumentDB READ: Counted {count} audit events\")\n return count\n except Exception as e:\n logger.error(f\"Error counting audit events: {e}\", exc_info=True)\n return 0\n\n async def distinct(\n self,\n field: str,\n query: dict[str, Any] | None = None,\n ) -> list[str]:\n \"\"\"Get distinct values for a field in audit events.\"\"\"\n logger.debug(f\"DocumentDB READ: Getting distinct values for field={field}\")\n collection = await self._get_collection()\n try:\n values = await collection.distinct(field, query or {})\n result = sorted([str(v) for v in values if v])\n logger.debug(f\"DocumentDB READ: Found {len(result)} distinct values for {field}\")\n return result\n except Exception as e:\n logger.error(f\"Error getting distinct values for {field}: {e}\", exc_info=True)\n return []\n\n async def aggregate(\n self,\n pipeline: list[dict[str, Any]],\n ) -> list[dict[str, Any]]:\n \"\"\"Run a MongoDB aggregation pipeline on audit events.\"\"\"\n logger.debug(f\"DocumentDB READ: Running aggregation pipeline with {len(pipeline)} stages\")\n collection = await self._get_collection()\n try:\n results = []\n async for doc in collection.aggregate(pipeline):\n results.append(doc)\n logger.debug(f\"DocumentDB READ: Aggregation returned {len(results)} results\")\n return results\n except Exception as e:\n logger.error(f\"Error running aggregation pipeline: {e}\", exc_info=True)\n return []\n\n async def insert(\n self,\n record: AuditRecord,\n ) -> bool:\n \"\"\"\n Insert an audit event record.\n\n Args:\n record: The audit record to insert (RegistryApiAccessRecord or MCPServerAccessRecord)\n\n Returns:\n True if inserted successfully or if the record already exists (duplicate request_id),\n False if an unexpected error occurs\n \"\"\"\n logger.debug(f\"DocumentDB WRITE: Inserting audit event with request_id={record.request_id}\")\n collection = await self._get_collection()\n\n try:\n # Convert Pydantic model to dict\n doc = record.model_dump(mode=\"json\")\n\n # Ensure timestamp is stored as datetime for TTL index\n if isinstance(doc.get(\"timestamp\"), str):\n doc[\"timestamp\"] = datetime.fromisoformat(doc[\"timestamp\"].replace(\"Z\", \"+00:00\"))\n\n await collection.insert_one(doc)\n logger.info(f\"DocumentDB WRITE: Inserted audit event request_id={record.request_id}\")\n return True\n except DuplicateKeyError:\n logger.debug(\n f\"DocumentDB WRITE: Skipped duplicate audit event for request_id={record.request_id}. \"\n f\"This occurs when the same request_id is processed twice (auth validation + endpoint execution). \"\n f\"Returning True to not break the request.\"\n )\n return True\n except Exception as e:\n logger.error(f\"Error inserting audit event: {e}\", exc_info=True)\n return False\n" }, { "path": "registry/repositories/documentdb/__init__.py", "content": "\"\"\"DocumentDB repository implementations using Motor (async MongoDB driver).\"\"\"\n\nfrom .agent_repository import DocumentDBAgentRepository\nfrom .client import (\n close_documentdb_client,\n get_collection_name,\n get_documentdb_client,\n)\nfrom .federation_config_repository import DocumentDBFederationConfigRepository\nfrom .scope_repository import DocumentDBScopeRepository\nfrom .search_repository import DocumentDBSearchRepository\nfrom .security_scan_repository import DocumentDBSecurityScanRepository\nfrom .server_repository import DocumentDBServerRepository\n\n__all__ = [\n \"DocumentDBAgentRepository\",\n \"DocumentDBFederationConfigRepository\",\n \"DocumentDBScopeRepository\",\n \"DocumentDBSearchRepository\",\n \"DocumentDBSecurityScanRepository\",\n \"DocumentDBServerRepository\",\n \"close_documentdb_client\",\n \"get_collection_name\",\n \"get_documentdb_client\",\n]\n" }, { "path": "registry/repositories/documentdb/agent_repository.py", "content": "\"\"\"DocumentDB-based repository for A2A agent storage.\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\nfrom pymongo.errors import DuplicateKeyError\n\nfrom ...schemas.agent_models import AgentCard\nfrom ..interfaces import AgentRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBAgentRepository(AgentRepositoryBase):\n \"\"\"DocumentDB implementation of agent repository.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"mcp_agents\")\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def load_all(self) -> None:\n \"\"\"Load all agents from DocumentDB.\"\"\"\n logger.info(f\"Loading agents from DocumentDB collection: {self._collection_name}\")\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({})\n logger.info(f\"Loaded {count} agents from DocumentDB\")\n except Exception as e:\n logger.error(f\"Error loading agents from DocumentDB: {e}\", exc_info=True)\n\n async def get(\n self,\n path: str,\n ) -> AgentCard | None:\n \"\"\"Get agent by path.\"\"\"\n collection = await self._get_collection()\n\n try:\n agent_doc = await collection.find_one({\"_id\": path})\n if not agent_doc:\n return None\n\n agent_doc[\"path\"] = agent_doc.pop(\"_id\")\n return AgentCard(**agent_doc)\n except Exception as e:\n logger.error(f\"Error getting agent '{path}' from DocumentDB: {e}\", exc_info=True)\n return None\n\n async def list_all(self) -> list[AgentCard]:\n \"\"\"List all agents.\"\"\"\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({})\n agents = []\n async for doc in cursor:\n path = doc.pop(\"_id\")\n doc[\"path\"] = path\n try:\n agent_card = AgentCard(**doc)\n agents.append(agent_card)\n except Exception as e:\n logger.error(f\"Failed to parse agent {path}: {e}\")\n return agents\n except Exception as e:\n logger.error(f\"Error listing agents from DocumentDB: {e}\", exc_info=True)\n return []\n\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> list[AgentCard]:\n \"\"\"List agents with DB-level skip/limit pagination.\"\"\"\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({}).sort(\"_id\", 1).skip(skip).limit(limit)\n agents = []\n async for doc in cursor:\n path = doc.pop(\"_id\")\n doc[\"path\"] = path\n try:\n agents.append(AgentCard(**doc))\n except Exception as e:\n logger.warning(f\"Skipping invalid agent document {path}: {e}\")\n return agents\n except Exception as e:\n logger.error(f\"Error listing paginated agents from DocumentDB: {e}\", exc_info=True)\n return []\n\n async def create(\n self,\n agent: AgentCard,\n ) -> AgentCard:\n \"\"\"Create a new agent.\"\"\"\n path = agent.path\n collection = await self._get_collection()\n\n if not agent.registered_at:\n agent.registered_at = datetime.utcnow()\n if not agent.updated_at:\n agent.updated_at = datetime.utcnow()\n\n agent_dict = agent.model_dump(mode=\"json\")\n agent_dict[\"is_enabled\"] = False\n\n try:\n doc = {**agent_dict}\n doc[\"_id\"] = path\n doc.pop(\"path\", None)\n\n await collection.insert_one(doc)\n logger.info(f\"Created agent '{agent.name}' at '{path}'\")\n return agent\n except DuplicateKeyError:\n logger.error(f\"Agent path '{path}' already exists\")\n raise ValueError(f\"Agent path '{path}' already exists\")\n except Exception as e:\n logger.error(f\"Failed to create agent in DocumentDB: {e}\", exc_info=True)\n raise ValueError(f\"Failed to create agent: {e}\")\n\n async def update(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> AgentCard:\n \"\"\"Update an existing agent.\"\"\"\n existing_agent = await self.get(path)\n if not existing_agent:\n logger.error(f\"Cannot update agent at '{path}': not found\")\n raise ValueError(f\"Agent not found at path: {path}\")\n\n collection = await self._get_collection()\n\n agent_dict = existing_agent.model_dump()\n agent_dict.update(updates)\n agent_dict[\"updated_at\"] = datetime.utcnow()\n\n try:\n updated_agent = AgentCard(**agent_dict)\n except Exception as e:\n logger.error(f\"Failed to validate updated agent: {e}\")\n raise ValueError(f\"Invalid agent update: {e}\")\n\n update_dict = updated_agent.model_dump(mode=\"json\")\n update_dict.pop(\"path\", None)\n\n try:\n result = await collection.update_one({\"_id\": path}, {\"$set\": update_dict})\n\n if result.matched_count == 0:\n raise ValueError(f\"Agent at '{path}' not found in DocumentDB\")\n\n logger.info(f\"Updated agent '{updated_agent.name}' ({path})\")\n return updated_agent\n except Exception as e:\n logger.error(f\"Failed to update agent in DocumentDB: {e}\", exc_info=True)\n raise ValueError(f\"Failed to update agent: {e}\")\n\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete an agent.\"\"\"\n collection = await self._get_collection()\n\n try:\n agent_doc = await collection.find_one({\"_id\": path})\n if not agent_doc:\n logger.error(f\"Agent at '{path}' not found in DocumentDB\")\n return False\n\n agent_name = agent_doc.get(\"name\", \"Unknown\")\n\n result = await collection.delete_one({\"_id\": path})\n\n if result.deleted_count == 0:\n logger.error(f\"Failed to delete agent at '{path}'\")\n return False\n\n logger.info(f\"Deleted agent '{agent_name}' from '{path}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to delete agent from DocumentDB: {e}\", exc_info=True)\n return False\n\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get enabled/disabled state for a single agent.\"\"\"\n agent = await self.get(path)\n if agent:\n return getattr(agent, \"is_enabled\", False)\n return False\n\n async def get_all_states(self) -> dict[str, bool]:\n \"\"\"Get enabled/disabled state for all agents in a single query.\"\"\"\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({}, {\"_id\": 1, \"is_enabled\": 1})\n states: dict[str, bool] = {}\n async for doc in cursor:\n agent_path = doc.get(\"_id\")\n if agent_path:\n states[agent_path] = doc.get(\"is_enabled\", False)\n return states\n except Exception as e:\n logger.error(f\"Error getting all agent states from DocumentDB: {e}\", exc_info=True)\n return {}\n\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set agent enabled/disabled state.\"\"\"\n collection = await self._get_collection()\n\n try:\n agent_doc = await collection.find_one({\"_id\": path})\n if not agent_doc:\n logger.error(f\"Agent at '{path}' not found in DocumentDB\")\n return False\n\n agent_name = agent_doc.get(\"name\", path)\n\n result = await collection.update_one(\n {\"_id\": path},\n {\"$set\": {\"is_enabled\": enabled, \"updated_at\": datetime.utcnow().isoformat()}},\n )\n\n if result.matched_count == 0:\n logger.error(f\"Agent at '{path}' not found\")\n return False\n\n logger.info(f\"Toggled '{agent_name}' ({path}) to {enabled}\")\n return True\n except Exception as e:\n logger.error(f\"Failed to update agent state in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def save_state(\n self,\n state: dict[str, list[str]],\n ) -> None:\n \"\"\"Save agent state (compatibility method for file repository interface).\"\"\"\n logger.debug(\n f\"Updated agent state cache: {len(state['enabled'])} enabled, \"\n f\"{len(state['disabled'])} disabled\"\n )\n\n async def count(self) -> int:\n \"\"\"Get total count of agents.\n\n Returns:\n Total number of agents in the repository.\n \"\"\"\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({})\n logger.debug(f\"DocumentDB COUNT: Found {count} agents\")\n return count\n except Exception as e:\n logger.error(f\"Error counting agents in DocumentDB: {e}\", exc_info=True)\n return 0\n\n async def update_field(\n self,\n path: str,\n field: str,\n value: Any,\n ) -> bool:\n \"\"\"Update a single field on a document.\"\"\"\n collection = await self._get_collection()\n\n if value is None:\n result = await collection.update_one(\n {\"_id\": path},\n {\"$unset\": {field: \"\"}},\n )\n else:\n result = await collection.update_one(\n {\"_id\": path},\n {\"$set\": {field: value}},\n )\n\n return result.modified_count > 0\n\n async def find_with_filter(\n self,\n filter_dict: dict[str, Any],\n ) -> dict[str, dict]:\n \"\"\"Find documents matching a MongoDB-style filter.\"\"\"\n collection = await self._get_collection()\n cursor = collection.find(filter_dict)\n results = {}\n async for doc in cursor:\n doc_id = doc.pop(\"_id\", None)\n if doc_id:\n results[doc_id] = doc\n return results\n" }, { "path": "registry/repositories/documentdb/backend_session_repository.py", "content": "\"\"\"\nDocumentDB (MongoDB) implementation for backend session repository.\n\nStores per-client backend MCP session mappings in MongoDB with a TTL index\non last_used_at for automatic cleanup of idle sessions. Uses compound keys\n(:) as _id for fast lookups.\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\nfrom pymongo import ASCENDING\n\nfrom ..interfaces import BackendSessionRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\n# Session TTL: 1 hour of inactivity\nSESSION_TTL_SECONDS: int = 3600\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _make_backend_session_id(\n client_session_id: str,\n backend_key: str,\n) -> str:\n \"\"\"Build compound _id for a backend session document.\"\"\"\n return f\"{client_session_id}:{backend_key}\"\n\n\ndef _make_client_session_id(\n client_session_id: str,\n) -> str:\n \"\"\"Build _id for a client session document.\"\"\"\n return f\"client:{client_session_id}\"\n\n\nclass DocumentDBBackendSessionRepository(BackendSessionRepositoryBase):\n \"\"\"MongoDB implementation for backend session storage.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"backend_sessions\")\n self._indexes_created = False\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection, creating indexes on first access.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n await self.ensure_indexes()\n return self._collection\n\n async def ensure_indexes(self) -> None:\n \"\"\"Create required indexes if not present.\n\n Creates:\n - TTL index on last_used_at (expires after SESSION_TTL_SECONDS)\n - Index on client_session_id for listing all backend sessions per client\n \"\"\"\n if self._indexes_created:\n return\n\n if self._collection is None:\n return\n\n try:\n # TTL index: auto-delete documents after SESSION_TTL_SECONDS of inactivity\n await self._collection.create_index(\n [(\"last_used_at\", ASCENDING)],\n expireAfterSeconds=SESSION_TTL_SECONDS,\n name=\"ttl_last_used_at\",\n )\n\n # Index for querying all backend sessions for a given client session\n await self._collection.create_index(\n [(\"client_session_id\", ASCENDING)],\n name=\"idx_client_session_id\",\n )\n\n self._indexes_created = True\n logger.info(\n f\"Created indexes for {self._collection_name} collection \"\n f\"(TTL={SESSION_TTL_SECONDS}s)\"\n )\n except Exception as e:\n logger.warning(f\"Could not create indexes for {self._collection_name}: {e}\")\n\n async def get_backend_session(\n self,\n client_session_id: str,\n backend_key: str,\n ) -> str | None:\n \"\"\"Get backend session ID and atomically bump last_used_at.\n\n Uses find_one_and_update so the TTL is refreshed on every access,\n keeping active sessions alive.\n\n Args:\n client_session_id: Client-facing session ID\n backend_key: Backend location key\n\n Returns:\n Backend session ID if found, None otherwise\n \"\"\"\n collection = await self._get_collection()\n doc_id = _make_backend_session_id(client_session_id, backend_key)\n\n result = await collection.find_one_and_update(\n {\"_id\": doc_id},\n {\"$set\": {\"last_used_at\": datetime.now(UTC)}},\n )\n\n if result:\n return result.get(\"backend_session_id\")\n return None\n\n async def store_backend_session(\n self,\n client_session_id: str,\n backend_key: str,\n backend_session_id: str,\n user_id: str,\n virtual_server_path: str,\n ) -> None:\n \"\"\"Store or update a backend session (upsert).\n\n Args:\n client_session_id: Client-facing session ID\n backend_key: Backend location key\n backend_session_id: Session ID from the backend MCP server\n user_id: User identity for audit\n virtual_server_path: Virtual server path\n \"\"\"\n collection = await self._get_collection()\n doc_id = _make_backend_session_id(client_session_id, backend_key)\n now = datetime.now(UTC)\n\n doc = {\n \"_id\": doc_id,\n \"client_session_id\": client_session_id,\n \"backend_key\": backend_key,\n \"backend_session_id\": backend_session_id,\n \"user_id\": user_id,\n \"virtual_server_path\": virtual_server_path,\n \"created_at\": now,\n \"last_used_at\": now,\n }\n\n await collection.replace_one(\n {\"_id\": doc_id},\n doc,\n upsert=True,\n )\n logger.debug(f\"Stored backend session: {doc_id} -> {backend_session_id}\")\n\n async def delete_backend_session(\n self,\n client_session_id: str,\n backend_key: str,\n ) -> None:\n \"\"\"Delete a stale backend session.\n\n Args:\n client_session_id: Client-facing session ID\n backend_key: Backend location key\n \"\"\"\n collection = await self._get_collection()\n doc_id = _make_backend_session_id(client_session_id, backend_key)\n\n result = await collection.delete_one({\"_id\": doc_id})\n if result.deleted_count > 0:\n logger.debug(f\"Deleted backend session: {doc_id}\")\n\n async def create_client_session(\n self,\n client_session_id: str,\n user_id: str,\n virtual_server_path: str,\n ) -> None:\n \"\"\"Create a client session document for validation.\n\n Uses the same collection with a 'client:' prefix on _id to\n distinguish from backend session documents.\n\n Args:\n client_session_id: Generated client session ID\n user_id: User identity from auth context\n virtual_server_path: Virtual server path\n \"\"\"\n collection = await self._get_collection()\n doc_id = _make_client_session_id(client_session_id)\n now = datetime.now(UTC)\n\n doc = {\n \"_id\": doc_id,\n \"client_session_id\": client_session_id,\n \"user_id\": user_id,\n \"virtual_server_path\": virtual_server_path,\n \"created_at\": now,\n \"last_used_at\": now,\n }\n\n await collection.insert_one(doc)\n logger.info(\n f\"Created client session: {client_session_id} \"\n f\"for user={user_id} path={virtual_server_path}\"\n )\n\n async def validate_client_session(\n self,\n client_session_id: str,\n ) -> bool:\n \"\"\"Check if a client session exists and bump last_used_at.\n\n Args:\n client_session_id: Client-facing session ID\n\n Returns:\n True if session exists, False otherwise\n \"\"\"\n collection = await self._get_collection()\n doc_id = _make_client_session_id(client_session_id)\n\n result = await collection.find_one_and_update(\n {\"_id\": doc_id},\n {\"$set\": {\"last_used_at\": datetime.now(UTC)}},\n )\n\n return result is not None\n" }, { "path": "registry/repositories/documentdb/client.py", "content": "\"\"\"DocumentDB client singleton with IAM authentication support.\"\"\"\n\nimport logging\n\nfrom motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase\n\nfrom ...core.config import settings\nfrom ...utils.mongodb_connection import build_client_options, build_connection_string, build_tls_kwargs\n\nlogger = logging.getLogger(__name__)\n\n_client: AsyncIOMotorClient | None = None\n_database: AsyncIOMotorDatabase | None = None\n\n\nasync def get_documentdb_client() -> AsyncIOMotorDatabase:\n \"\"\"Get DocumentDB database client singleton.\"\"\"\n global _client, _database\n\n if _database is not None:\n return _database\n\n connection_string = build_connection_string()\n logger.info(\n f\"Connecting to {settings.storage_backend} \"\n f\"(host: {settings.documentdb_host})\"\n )\n\n _client = AsyncIOMotorClient(\n connection_string,\n **build_client_options(),\n **build_tls_kwargs(),\n )\n _database = _client[settings.documentdb_database]\n\n server_info = await _client.server_info()\n logger.info(f\"Connected to DocumentDB/MongoDB {server_info.get('version', 'unknown')}\")\n\n return _database\n\n\nasync def close_documentdb_client() -> None:\n \"\"\"Close DocumentDB client.\"\"\"\n global _client, _database\n if _client is not None:\n _client.close()\n _client = None\n _database = None\n\n\ndef get_collection_name(\n base_name: str,\n) -> str:\n \"\"\"Get full collection name with namespace.\"\"\"\n return f\"{base_name}_{settings.documentdb_namespace}\"\n" }, { "path": "registry/repositories/documentdb/federation_config_repository.py", "content": "\"\"\"DocumentDB repository for federation configuration storage.\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom ...schemas.federation_schema import FederationConfig\nfrom ..interfaces import FederationConfigRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBFederationConfigRepository(FederationConfigRepositoryBase):\n \"\"\"DocumentDB implementation of federation configuration repository.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"mcp_federation_config\")\n logger.info(\n f\"Initialized DocumentDB FederationConfigRepository with collection: \"\n f\"{self._collection_name}\"\n )\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def get_config(self, config_id: str = \"default\") -> FederationConfig | None:\n \"\"\"Get federation configuration by ID.\"\"\"\n try:\n collection = await self._get_collection()\n\n config_doc = await collection.find_one({\"_id\": config_id})\n\n if not config_doc:\n logger.info(f\"Federation config not found: {config_id}\")\n return None\n\n config_doc.pop(\"_id\", None)\n config_doc.pop(\"created_at\", None)\n config_doc.pop(\"updated_at\", None)\n\n config = FederationConfig(**config_doc)\n logger.info(f\"Retrieved federation config: {config_id}\")\n return config\n\n except Exception as e:\n logger.error(f\"Failed to get federation config {config_id}: {e}\", exc_info=True)\n return None\n\n async def save_config(\n self, config: FederationConfig, config_id: str = \"default\"\n ) -> FederationConfig:\n \"\"\"Save or update federation configuration.\"\"\"\n try:\n collection = await self._get_collection()\n\n existing = await collection.find_one({\"_id\": config_id})\n\n doc = config.model_dump()\n\n now = datetime.now(UTC).isoformat()\n if existing:\n doc[\"created_at\"] = existing.get(\"created_at\", now)\n doc[\"updated_at\"] = now\n else:\n doc[\"created_at\"] = now\n doc[\"updated_at\"] = now\n\n doc[\"_id\"] = config_id\n\n await collection.replace_one({\"_id\": config_id}, doc, upsert=True)\n\n logger.info(f\"Saved federation config: {config_id}\")\n return config\n\n except Exception as e:\n logger.error(f\"Failed to save federation config {config_id}: {e}\", exc_info=True)\n raise\n\n async def delete_config(self, config_id: str = \"default\") -> bool:\n \"\"\"Delete federation configuration.\"\"\"\n try:\n collection = await self._get_collection()\n\n result = await collection.delete_one({\"_id\": config_id})\n\n if result.deleted_count == 0:\n logger.warning(f\"Federation config not found for deletion: {config_id}\")\n return False\n\n logger.info(f\"Deleted federation config: {config_id}\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to delete federation config {config_id}: {e}\", exc_info=True)\n return False\n\n async def list_configs(self) -> list[dict[str, Any]]:\n \"\"\"List all federation configurations.\"\"\"\n try:\n collection = await self._get_collection()\n\n cursor = collection.find({}, {\"_id\": 1, \"created_at\": 1, \"updated_at\": 1})\n\n configs = []\n async for doc in cursor:\n configs.append(\n {\n \"id\": doc.get(\"_id\"),\n \"created_at\": doc.get(\"created_at\"),\n \"updated_at\": doc.get(\"updated_at\"),\n }\n )\n\n logger.info(f\"Listed {len(configs)} federation configs\")\n return configs\n\n except Exception as e:\n logger.error(f\"Failed to list federation configs: {e}\", exc_info=True)\n return []\n" }, { "path": "registry/repositories/documentdb/peer_federation_repository.py", "content": "\"\"\"DocumentDB repository for peer federation configuration storage.\n\nWorks with both MongoDB Community Edition (storage_backend=mongodb-ce)\nand AWS DocumentDB (storage_backend=documentdb). The client.py handles\nauthentication differences automatically.\n\nCollections:\n- mcp_peers_{namespace}: Peer registry configurations (_id = peer_id)\n- mcp_peer_sync_state_{namespace}: Sync status (_id = peer_id)\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom ...schemas.peer_federation_schema import (\n PeerRegistryConfig,\n PeerSyncStatus,\n)\nfrom ...utils.federation_encryption import (\n decrypt_token_in_peer_dict,\n encrypt_token_in_peer_dict,\n)\nfrom ..interfaces import PeerFederationRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBPeerFederationRepository(PeerFederationRepositoryBase):\n \"\"\"DocumentDB implementation of peer federation repository.\n\n Uses two collections:\n - Peers collection: stores PeerRegistryConfig documents\n - Sync state collection: stores PeerSyncStatus documents\n\n Both use peer_id as the _id field for efficient lookups.\n \"\"\"\n\n def __init__(self):\n self._peers_collection: AsyncIOMotorCollection | None = None\n self._sync_state_collection: AsyncIOMotorCollection | None = None\n self._peers_collection_name = get_collection_name(\"mcp_peers\")\n self._sync_state_collection_name = get_collection_name(\"mcp_peer_sync_state\")\n logger.info(\n f\"Initialized DocumentDB PeerFederationRepository with collections: \"\n f\"{self._peers_collection_name}, {self._sync_state_collection_name}\"\n )\n\n async def _get_peers_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB peers collection.\"\"\"\n if self._peers_collection is None:\n db = await get_documentdb_client()\n self._peers_collection = db[self._peers_collection_name]\n return self._peers_collection\n\n async def _get_sync_state_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB sync state collection.\"\"\"\n if self._sync_state_collection is None:\n db = await get_documentdb_client()\n self._sync_state_collection = db[self._sync_state_collection_name]\n return self._sync_state_collection\n\n async def get_peer(\n self,\n peer_id: str,\n ) -> PeerRegistryConfig | None:\n \"\"\"Get peer configuration by ID.\"\"\"\n try:\n collection = await self._get_peers_collection()\n\n doc = await collection.find_one({\"_id\": peer_id})\n\n if not doc:\n logger.debug(f\"Peer not found: {peer_id}\")\n return None\n\n # Remove MongoDB _id before creating Pydantic model\n doc.pop(\"_id\", None)\n\n # Decrypt federation token if present\n decrypt_token_in_peer_dict(doc)\n\n peer_config = PeerRegistryConfig(**doc)\n logger.debug(f\"Retrieved peer config: {peer_id}\")\n return peer_config\n\n except Exception as e:\n logger.error(f\"Failed to get peer {peer_id}: {e}\", exc_info=True)\n return None\n\n async def list_peers(\n self,\n enabled: bool | None = None,\n ) -> list[PeerRegistryConfig]:\n \"\"\"List all peer configurations with optional filtering.\"\"\"\n try:\n collection = await self._get_peers_collection()\n\n # Build query based on enabled filter\n query: dict[str, Any] = {}\n if enabled is not None:\n query[\"enabled\"] = enabled\n\n cursor = collection.find(query)\n\n peers = []\n async for doc in cursor:\n doc.pop(\"_id\", None)\n # Decrypt federation token if present\n decrypt_token_in_peer_dict(doc)\n try:\n peer_config = PeerRegistryConfig(**doc)\n peers.append(peer_config)\n except Exception as e:\n logger.error(\n f\"Failed to parse peer config {doc.get('peer_id', 'unknown')}: {e}\"\n )\n\n logger.info(f\"Listed {len(peers)} peers (enabled={enabled})\")\n return peers\n\n except Exception as e:\n logger.error(f\"Failed to list peers: {e}\", exc_info=True)\n return []\n\n async def create_peer(\n self,\n config: PeerRegistryConfig,\n ) -> PeerRegistryConfig:\n \"\"\"Create a new peer configuration.\"\"\"\n try:\n collection = await self._get_peers_collection()\n peer_id = config.peer_id\n\n # Check if peer already exists\n existing = await collection.find_one({\"_id\": peer_id})\n if existing:\n raise ValueError(f\"Peer ID '{peer_id}' already exists\")\n\n # Set timestamps\n now = datetime.now(UTC)\n config.created_at = now\n config.updated_at = now\n\n # Convert to document with _id\n doc = config.model_dump(mode=\"json\")\n doc[\"_id\"] = peer_id\n\n # Encrypt federation token before storage\n encrypt_token_in_peer_dict(doc)\n\n await collection.insert_one(doc)\n\n # Also create initial sync status\n initial_status = PeerSyncStatus(peer_id=peer_id)\n await self.update_sync_status(peer_id, initial_status)\n\n logger.info(f\"Created peer: {peer_id} ({config.name})\")\n return config\n\n except ValueError:\n raise\n except Exception as e:\n logger.error(f\"Failed to create peer {config.peer_id}: {e}\", exc_info=True)\n raise ValueError(f\"Failed to create peer: {e}\")\n\n async def update_peer(\n self,\n peer_id: str,\n updates: dict[str, Any],\n ) -> PeerRegistryConfig:\n \"\"\"Update an existing peer configuration.\"\"\"\n try:\n collection = await self._get_peers_collection()\n\n # Get existing peer\n existing_doc = await collection.find_one({\"_id\": peer_id})\n if not existing_doc:\n raise ValueError(f\"Peer not found: {peer_id}\")\n\n # Remove _id before merging\n existing_doc.pop(\"_id\", None)\n\n # Decrypt federation token before constructing Pydantic model.\n # Without this, federation_token_encrypted (unknown to Pydantic)\n # is silently dropped during model_dump(), permanently losing the\n # token on any peer update. Fixes issue #561.\n decrypt_token_in_peer_dict(existing_doc)\n\n # Merge updates with existing data\n existing_doc.update(updates)\n\n # Ensure peer_id is consistent\n existing_doc[\"peer_id\"] = peer_id\n\n # Update timestamp\n existing_doc[\"updated_at\"] = datetime.now(UTC).isoformat()\n\n # Validate updated peer\n try:\n updated_peer = PeerRegistryConfig(**existing_doc)\n except Exception as e:\n raise ValueError(f\"Invalid peer update: {e}\")\n\n # Save to database\n doc = updated_peer.model_dump(mode=\"json\")\n doc[\"_id\"] = peer_id\n\n # Encrypt federation token before storage\n encrypt_token_in_peer_dict(doc)\n\n await collection.replace_one({\"_id\": peer_id}, doc, upsert=False)\n\n logger.info(f\"Updated peer: {peer_id}\")\n return updated_peer\n\n except ValueError:\n raise\n except Exception as e:\n logger.error(f\"Failed to update peer {peer_id}: {e}\", exc_info=True)\n raise ValueError(f\"Failed to update peer: {e}\")\n\n async def delete_peer(\n self,\n peer_id: str,\n ) -> bool:\n \"\"\"Delete a peer configuration and its sync status.\"\"\"\n try:\n peers_collection = await self._get_peers_collection()\n sync_collection = await self._get_sync_state_collection()\n\n # Check if peer exists\n existing = await peers_collection.find_one({\"_id\": peer_id})\n if not existing:\n raise ValueError(f\"Peer not found: {peer_id}\")\n\n # Delete peer config\n result = await peers_collection.delete_one({\"_id\": peer_id})\n\n if result.deleted_count == 0:\n logger.warning(f\"Peer not found for deletion: {peer_id}\")\n return False\n\n # Also delete sync status (cascade delete)\n await sync_collection.delete_one({\"_id\": peer_id})\n\n logger.info(f\"Deleted peer and sync status: {peer_id}\")\n return True\n\n except ValueError:\n raise\n except Exception as e:\n logger.error(f\"Failed to delete peer {peer_id}: {e}\", exc_info=True)\n raise ValueError(f\"Failed to delete peer: {e}\")\n\n async def get_sync_status(\n self,\n peer_id: str,\n ) -> PeerSyncStatus | None:\n \"\"\"Get sync status for a peer.\"\"\"\n try:\n collection = await self._get_sync_state_collection()\n\n doc = await collection.find_one({\"_id\": peer_id})\n\n if not doc:\n logger.debug(f\"Sync status not found for peer: {peer_id}\")\n return None\n\n # Remove MongoDB _id and metadata before creating Pydantic model\n doc.pop(\"_id\", None)\n doc.pop(\"updated_at\", None)\n\n sync_status = PeerSyncStatus(**doc)\n logger.debug(f\"Retrieved sync status for peer: {peer_id}\")\n return sync_status\n\n except Exception as e:\n logger.error(f\"Failed to get sync status for {peer_id}: {e}\", exc_info=True)\n return None\n\n async def update_sync_status(\n self,\n peer_id: str,\n status: PeerSyncStatus,\n ) -> PeerSyncStatus:\n \"\"\"Update sync status for a peer (upsert).\"\"\"\n try:\n collection = await self._get_sync_state_collection()\n\n # Convert to document with _id\n doc = status.model_dump(mode=\"json\")\n doc[\"_id\"] = peer_id\n doc[\"updated_at\"] = datetime.now(UTC).isoformat()\n\n await collection.replace_one({\"_id\": peer_id}, doc, upsert=True)\n\n logger.debug(f\"Updated sync status for peer: {peer_id}\")\n return status\n\n except Exception as e:\n logger.error(f\"Failed to update sync status for {peer_id}: {e}\", exc_info=True)\n raise ValueError(f\"Failed to update sync status: {e}\")\n\n async def list_sync_statuses(self) -> list[PeerSyncStatus]:\n \"\"\"List all peer sync statuses.\"\"\"\n try:\n collection = await self._get_sync_state_collection()\n\n cursor = collection.find({})\n\n statuses = []\n async for doc in cursor:\n doc.pop(\"_id\", None)\n doc.pop(\"updated_at\", None) # Remove metadata field\n try:\n sync_status = PeerSyncStatus(**doc)\n statuses.append(sync_status)\n except Exception as e:\n logger.error(\n f\"Failed to parse sync status {doc.get('peer_id', 'unknown')}: {e}\"\n )\n\n logger.info(f\"Listed {len(statuses)} sync statuses\")\n return statuses\n\n except Exception as e:\n logger.error(f\"Failed to list sync statuses: {e}\", exc_info=True)\n return []\n\n async def load_all(self) -> None:\n \"\"\"Load/reload all peers and sync states from storage.\n\n For DocumentDB, this is a no-op since data is loaded on-demand.\n However, we verify connectivity and log collection stats.\n \"\"\"\n try:\n peers_collection = await self._get_peers_collection()\n sync_collection = await self._get_sync_state_collection()\n\n # Count documents to verify connectivity\n peer_count = await peers_collection.count_documents({})\n sync_count = await sync_collection.count_documents({})\n\n logger.info(\n f\"Loaded peer federation data: {peer_count} peers, {sync_count} sync statuses\"\n )\n\n except Exception as e:\n logger.error(f\"Failed to load peer federation data: {e}\", exc_info=True)\n raise\n" }, { "path": "registry/repositories/documentdb/registry_card_repository.py", "content": "\"\"\"DocumentDB repository for registry card storage.\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom ...schemas.registry_card import RegistryCard\nfrom ..interfaces import RegistryCardRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBRegistryCardRepository(RegistryCardRepositoryBase):\n \"\"\"DocumentDB implementation of Registry Card repository.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"registry_cards\")\n logger.info(\n f\"Initialized DocumentDB RegistryCardRepository with collection: \"\n f\"{self._collection_name}\"\n )\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection (lazy initialization).\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def get(self) -> RegistryCard | None:\n \"\"\"Retrieve the Registry Card.\"\"\"\n try:\n collection = await self._get_collection()\n\n doc = await collection.find_one({\"_id\": \"default\"})\n\n if not doc:\n logger.debug(\"No registry card found in database\")\n return None\n\n doc.pop(\"_id\", None)\n\n card = RegistryCard(**doc)\n logger.info(\"Retrieved registry card from DocumentDB\")\n return card\n\n except Exception as e:\n logger.error(f\"Error getting registry card: {e}\", exc_info=True)\n return None\n\n async def save(\n self,\n card: RegistryCard,\n ) -> RegistryCard:\n \"\"\"Save or update the Registry Card using upsert.\"\"\"\n try:\n collection = await self._get_collection()\n\n card_id = \"default\"\n existing = await collection.find_one({\"_id\": card_id})\n\n doc = card.model_dump(mode=\"json\")\n\n now = datetime.now(UTC).isoformat()\n if existing:\n doc[\"created_at\"] = existing.get(\"created_at\", now)\n doc[\"updated_at\"] = now\n else:\n doc[\"created_at\"] = now\n doc[\"updated_at\"] = now\n\n doc[\"_id\"] = card_id\n\n await collection.replace_one({\"_id\": card_id}, doc, upsert=True)\n\n logger.info(\"Saved registry card to DocumentDB\")\n return card\n\n except Exception as e:\n logger.error(f\"Error saving registry card: {e}\", exc_info=True)\n raise\n\n async def exists(self) -> bool:\n \"\"\"Check if Registry Card exists.\"\"\"\n try:\n collection = await self._get_collection()\n\n result = await collection.find_one({\"_id\": \"default\"})\n\n exists = result is not None\n logger.debug(f\"Registry card exists check: {exists}\")\n return exists\n\n except Exception as e:\n logger.error(f\"Error checking registry card existence: {e}\", exc_info=True)\n return False\n" }, { "path": "registry/repositories/documentdb/scope_repository.py", "content": "\"\"\"DocumentDB-based repository for authorization scopes storage.\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom ..interfaces import ScopeRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBScopeRepository(ScopeRepositoryBase):\n \"\"\"DocumentDB implementation of scope repository using embedded documents.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"mcp_scopes\")\n self._scopes_cache: dict[str, Any] = {}\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def load_all(self) -> None:\n \"\"\"Load all scopes from DocumentDB.\"\"\"\n logger.info(f\"Loading scopes from DocumentDB collection: {self._collection_name}\")\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({})\n self._scopes_cache = {\n \"UI-Scopes\": {},\n \"group_mappings\": {},\n }\n\n async for doc in cursor:\n scope_name = doc.get(\"_id\")\n\n # UI permissions: scope_name -> ui_permissions\n if doc.get(\"ui_permissions\"):\n self._scopes_cache[\"UI-Scopes\"][scope_name] = doc.get(\"ui_permissions\", {})\n\n # Group mappings: keycloak_group -> [scope_names]\n # Build reverse mapping from scope's group_mappings list\n for keycloak_group in doc.get(\"group_mappings\", []):\n if keycloak_group not in self._scopes_cache[\"group_mappings\"]:\n self._scopes_cache[\"group_mappings\"][keycloak_group] = []\n if scope_name not in self._scopes_cache[\"group_mappings\"][keycloak_group]:\n self._scopes_cache[\"group_mappings\"][keycloak_group].append(scope_name)\n\n # Scope definitions: scope_name -> [access_rules]\n if doc.get(\"server_access\"):\n self._scopes_cache[scope_name] = doc.get(\"server_access\", [])\n\n logger.info(\"Loaded scopes from DocumentDB\")\n except Exception as e:\n logger.error(f\"Error loading scopes from DocumentDB: {e}\", exc_info=True)\n self._scopes_cache = {\"UI-Scopes\": {}, \"group_mappings\": {}}\n\n async def get_ui_scopes(\n self,\n group_name: str,\n ) -> dict[str, Any]:\n \"\"\"Get UI scopes for a Keycloak group - queries DocumentDB directly.\"\"\"\n logger.debug(f\"DocumentDB READ: Getting UI scopes for group '{group_name}' from DB\")\n collection = await self._get_collection()\n\n try:\n group_doc = await collection.find_one({\"_id\": group_name})\n if not group_doc:\n logger.debug(f\"DocumentDB READ: Group '{group_name}' not found\")\n return {}\n\n scopes = group_doc.get(\"ui_permissions\", {})\n logger.debug(f\"DocumentDB READ: Found {len(scopes)} UI scopes for group '{group_name}'\")\n return scopes\n except Exception as e:\n logger.error(f\"Error getting UI scopes for group '{group_name}': {e}\", exc_info=True)\n return {}\n\n async def get_group_mappings(\n self,\n keycloak_group: str,\n ) -> list[str]:\n \"\"\"Get scope names mapped to a group (Keycloak group name or Entra ID group Object ID).\n\n The scopes collection stores documents with:\n - _id: scope name (e.g., 'registry-admins')\n - group_mappings: list of group identifiers that have this scope\n\n This method finds all scopes where the given group appears in group_mappings.\n \"\"\"\n logger.debug(f\"DocumentDB READ: Getting group mappings for '{keycloak_group}' from DB\")\n collection = await self._get_collection()\n\n try:\n # Find all scope documents where group_mappings array contains this group\n cursor = collection.find({\"group_mappings\": keycloak_group})\n scope_names = [doc[\"_id\"] async for doc in cursor]\n\n logger.debug(\n f\"DocumentDB READ: Found {len(scope_names)} scopes for group \"\n f\"'{keycloak_group}': {scope_names}\"\n )\n return scope_names\n except Exception as e:\n logger.error(f\"Error getting group mappings for '{keycloak_group}': {e}\", exc_info=True)\n return []\n\n async def get_server_scopes(\n self,\n scope_name: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Get server access rules for a scope - queries DocumentDB directly.\"\"\"\n logger.debug(\n f\"DocumentDB READ: Getting server access rules for scope '{scope_name}' from DB\"\n )\n collection = await self._get_collection()\n\n try:\n # Find the group document that contains this scope\n group_doc = await collection.find_one({\"_id\": scope_name})\n if not group_doc:\n logger.debug(f\"DocumentDB READ: Scope '{scope_name}' not found\")\n return []\n\n # Extract server access rules from the server_access array\n server_access = group_doc.get(\"server_access\", [])\n\n # Flatten the access rules from all scope entries\n # Handle two formats:\n # 1. New format: {\"scope_name\": \"...\", \"access_rules\": [...]}\n # 2. Old/direct format: {\"server\": \"...\", \"methods\": [...], \"tools\": [...]}\n all_rules = []\n for scope_entry in server_access:\n # Check if this entry has \"access_rules\" (new format)\n if \"access_rules\" in scope_entry:\n access_rules = scope_entry.get(\"access_rules\", [])\n all_rules.extend(access_rules)\n # Check if this entry is a direct server access rule (old format)\n elif \"server\" in scope_entry:\n all_rules.append(scope_entry)\n # Skip entries that are not server access rules (e.g., agent permissions)\n\n logger.debug(\n f\"DocumentDB READ: Found {len(all_rules)} access rules for scope '{scope_name}'\"\n )\n return all_rules\n except Exception as e:\n logger.error(f\"Error getting server scopes for '{scope_name}': {e}\", exc_info=True)\n return []\n\n async def add_server_scope(\n self,\n server_path: str,\n scope_name: str,\n methods: list[str],\n tools: list[str] | None = None,\n ) -> bool:\n \"\"\"Add scope for a server.\"\"\"\n try:\n collection = await self._get_collection()\n server_name = server_path.lstrip(\"/\")\n\n server_entry = {\"server\": server_name, \"methods\": methods, \"tools\": tools}\n\n result = await collection.update_one(\n {\"_id\": scope_name},\n {\n \"$push\": {\n \"server_access\": {\n \"$each\": [{\"scope_name\": scope_name, \"access_rules\": [server_entry]}]\n }\n },\n \"$set\": {\"updated_at\": datetime.utcnow()},\n },\n )\n\n if result.matched_count == 0:\n logger.error(f\"Scope '{scope_name}' not found\")\n return False\n\n self._scopes_cache.setdefault(scope_name, []).append(server_entry)\n\n logger.info(f\"Added server '{server_name}' to scope '{scope_name}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to add server scope in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def remove_server_scope(\n self,\n server_path: str,\n scope_name: str,\n ) -> bool:\n \"\"\"Remove scope for a server.\"\"\"\n try:\n collection = await self._get_collection()\n server_name = server_path.lstrip(\"/\")\n\n result = await collection.update_one(\n {\"_id\": scope_name},\n {\n \"$pull\": {\n \"server_access\": {\n \"scope_name\": scope_name,\n \"access_rules.server\": server_name,\n }\n },\n \"$set\": {\"updated_at\": datetime.utcnow()},\n },\n )\n\n if result.matched_count == 0:\n logger.error(f\"Scope '{scope_name}' not found\")\n return False\n\n if scope_name in self._scopes_cache:\n self._scopes_cache[scope_name] = [\n s for s in self._scopes_cache[scope_name] if s.get(\"server\") != server_name\n ]\n\n logger.info(f\"Removed server '{server_name}' from scope '{scope_name}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to remove server scope in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def create_group(\n self,\n group_name: str,\n description: str = \"\",\n ) -> bool:\n \"\"\"Create a new group in scopes.\"\"\"\n try:\n collection = await self._get_collection()\n\n doc = {\n \"_id\": group_name,\n \"scope_type\": \"group\",\n \"description\": description,\n \"server_access\": [],\n \"group_mappings\": [],\n \"ui_permissions\": {},\n \"created_at\": datetime.utcnow(),\n \"updated_at\": datetime.utcnow(),\n }\n\n await collection.insert_one(doc)\n\n self._scopes_cache.setdefault(\"UI-Scopes\", {})[group_name] = {}\n self._scopes_cache.setdefault(\"group_mappings\", {})[group_name] = []\n\n logger.info(f\"Created group '{group_name}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to create group in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def delete_group(\n self,\n group_name: str,\n remove_from_mappings: bool = True,\n ) -> bool:\n \"\"\"Delete a group from scopes.\"\"\"\n try:\n collection = await self._get_collection()\n\n result = await collection.delete_one({\"_id\": group_name})\n\n if result.deleted_count == 0:\n logger.error(f\"Group '{group_name}' not found\")\n return False\n\n self._scopes_cache.get(\"UI-Scopes\", {}).pop(group_name, None)\n self._scopes_cache.get(\"group_mappings\", {}).pop(group_name, None)\n\n logger.info(f\"Deleted group '{group_name}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to delete group in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def get_group(\n self,\n group_name: str,\n ) -> dict[str, Any]:\n \"\"\"Get full details of a specific group.\"\"\"\n collection = await self._get_collection()\n\n try:\n group_doc = await collection.find_one({\"_id\": group_name})\n if not group_doc:\n return None\n\n group_doc[\"scope_name\"] = group_doc.pop(\"_id\")\n return group_doc\n except Exception as e:\n logger.error(f\"Error getting group '{group_name}' from DocumentDB: {e}\", exc_info=True)\n return None\n\n async def list_groups(self) -> dict[str, Any]:\n \"\"\"List all groups with server counts.\"\"\"\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({})\n groups = {}\n async for doc in cursor:\n group_name = doc.get(\"_id\")\n server_count = len(doc.get(\"server_access\", []))\n groups[group_name] = {\n \"server_count\": server_count,\n \"ui_scopes\": doc.get(\"ui_permissions\", {}),\n \"mappings\": doc.get(\"group_mappings\", []),\n }\n return groups\n except Exception as e:\n logger.error(f\"Error listing groups from DocumentDB: {e}\", exc_info=True)\n return {}\n\n async def group_exists(\n self,\n group_name: str,\n ) -> bool:\n \"\"\"Check if a group exists.\"\"\"\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({\"_id\": group_name})\n return count > 0\n except Exception as e:\n logger.error(f\"Error checking group existence in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def add_server_to_ui_scopes(\n self,\n group_name: str,\n server_name: str,\n ) -> bool:\n \"\"\"Add server to group's UI scopes list_service.\"\"\"\n try:\n collection = await self._get_collection()\n\n result = await collection.update_one(\n {\"_id\": group_name},\n {\n \"$addToSet\": {\"ui_permissions.list_service\": server_name},\n \"$set\": {\"updated_at\": datetime.utcnow()},\n },\n )\n\n if result.matched_count == 0:\n logger.error(f\"Group '{group_name}' not found\")\n return False\n\n logger.info(f\"Added server '{server_name}' to UI scopes for group '{group_name}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to add server to UI scopes in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def remove_server_from_ui_scopes(\n self,\n group_name: str,\n server_name: str,\n ) -> bool:\n \"\"\"Remove server from group's UI scopes list_service.\"\"\"\n try:\n collection = await self._get_collection()\n\n result = await collection.update_one(\n {\"_id\": group_name},\n {\n \"$pull\": {\"ui_permissions.list_service\": server_name},\n \"$set\": {\"updated_at\": datetime.utcnow()},\n },\n )\n\n if result.matched_count == 0:\n logger.error(f\"Group '{group_name}' not found\")\n return False\n\n logger.info(f\"Removed server '{server_name}' from UI scopes for group '{group_name}'\")\n return True\n except Exception as e:\n logger.error(\n f\"Failed to remove server from UI scopes in DocumentDB: {e}\", exc_info=True\n )\n return False\n\n async def add_group_mapping(\n self,\n group_name: str,\n scope_name: str,\n ) -> bool:\n \"\"\"Add a scope to group mappings.\"\"\"\n try:\n collection = await self._get_collection()\n\n result = await collection.update_one(\n {\"_id\": group_name},\n {\n \"$addToSet\": {\"group_mappings\": scope_name},\n \"$set\": {\"updated_at\": datetime.utcnow()},\n },\n )\n\n if result.matched_count == 0:\n logger.error(f\"Group '{group_name}' not found\")\n return False\n\n logger.info(f\"Added mapping '{scope_name}' to group '{group_name}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to add group mapping in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def remove_group_mapping(\n self,\n group_name: str,\n scope_name: str,\n ) -> bool:\n \"\"\"Remove a scope from group mappings.\"\"\"\n try:\n collection = await self._get_collection()\n\n result = await collection.update_one(\n {\"_id\": group_name},\n {\n \"$pull\": {\"group_mappings\": scope_name},\n \"$set\": {\"updated_at\": datetime.utcnow()},\n },\n )\n\n if result.matched_count == 0:\n logger.error(f\"Group '{group_name}' not found\")\n return False\n\n logger.info(f\"Removed mapping '{scope_name}' from group '{group_name}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to remove group mapping in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def get_all_group_mappings(self) -> dict[str, list[str]]:\n \"\"\"Get all group mappings.\"\"\"\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({})\n mappings = {}\n async for doc in cursor:\n group_name = doc.get(\"_id\")\n mappings[group_name] = doc.get(\"group_mappings\", [])\n return mappings\n except Exception as e:\n logger.error(f\"Error getting all group mappings from DocumentDB: {e}\", exc_info=True)\n return {}\n\n async def add_server_to_multiple_scopes(\n self,\n server_path: str,\n scope_names: list[str],\n methods: list[str],\n tools: list[str],\n ) -> bool:\n \"\"\"Add server to multiple scopes at once.\"\"\"\n try:\n for scope_name in scope_names:\n success = await self.add_server_scope(server_path, scope_name, methods, tools)\n if not success:\n return False\n return True\n except Exception as e:\n logger.error(f\"Failed to add server to multiple scopes: {e}\", exc_info=True)\n return False\n\n async def remove_server_from_all_scopes(\n self,\n server_path: str,\n ) -> bool:\n \"\"\"Remove server from all scopes.\"\"\"\n try:\n collection = await self._get_collection()\n server_name = server_path.lstrip(\"/\")\n\n result = await collection.update_many(\n {},\n {\n \"$pull\": {\"server_access\": {\"access_rules.server\": server_name}},\n \"$set\": {\"updated_at\": datetime.utcnow()},\n },\n )\n\n for scope_name in list(self._scopes_cache.keys()):\n if scope_name not in [\"UI-Scopes\", \"group_mappings\"]:\n self._scopes_cache[scope_name] = [\n s for s in self._scopes_cache[scope_name] if s.get(\"server\") != server_name\n ]\n\n logger.info(f\"Removed server '{server_name}' from all scopes\")\n return True\n except Exception as e:\n logger.error(\n f\"Failed to remove server from all scopes in DocumentDB: {e}\", exc_info=True\n )\n return False\n\n async def import_group(\n self,\n group_name: str,\n description: str = \"\",\n server_access: list = None,\n group_mappings: list = None,\n ui_permissions: dict = None,\n agent_access: list = None,\n ) -> bool:\n \"\"\"\n Import a complete group definition.\n\n Args:\n group_name: Name of the group\n description: Description of the group\n server_access: List of server access definitions\n group_mappings: List of group names this group maps to\n ui_permissions: Dictionary of UI permissions\n agent_access: List of agent paths this group can access\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n collection = await self._get_collection()\n\n # Set defaults\n if server_access is None:\n server_access = []\n if group_mappings is None:\n group_mappings = [group_name]\n if ui_permissions is None:\n ui_permissions = {\"list_service\": []}\n if agent_access is None:\n agent_access = []\n\n # Create the complete group document\n group_doc = {\n \"_id\": group_name,\n \"scope_type\": \"group\",\n \"description\": description,\n \"server_access\": server_access,\n \"group_mappings\": group_mappings,\n \"ui_permissions\": ui_permissions,\n \"agent_access\": agent_access,\n \"created_at\": datetime.utcnow(),\n \"updated_at\": datetime.utcnow(),\n }\n\n # Use replace_one with upsert=True to create or replace the entire document\n result = await collection.replace_one({\"_id\": group_name}, group_doc, upsert=True)\n\n # Update in-memory cache\n self._scopes_cache.setdefault(\"UI-Scopes\", {})[group_name] = ui_permissions\n self._scopes_cache.setdefault(\"group_mappings\", {})[group_name] = group_mappings\n\n # Update server access in cache\n for scope_entry in server_access:\n scope_name = scope_entry.get(\"scope_name\")\n if scope_name:\n if scope_name not in self._scopes_cache:\n self._scopes_cache[scope_name] = []\n self._scopes_cache[scope_name].extend(scope_entry.get(\"access_rules\", []))\n\n if result.upserted_id:\n logger.info(f\"Created new group '{group_name}' via import\")\n else:\n logger.info(f\"Updated existing group '{group_name}' via import\")\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to import group {group_name}: {e}\", exc_info=True)\n return False\n" }, { "path": "registry/repositories/documentdb/search_repository.py", "content": "\"\"\"DocumentDB-based repository for hybrid search (text + vector).\"\"\"\n\nimport logging\nimport math\nimport re\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom ...core.config import embedding_config, settings\nfrom ...schemas.agent_models import AgentCard\nfrom ...utils.metadata import flatten_metadata_to_text\nfrom ..interfaces import SearchRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\n# Stopwords to filter out when tokenizing queries for keyword matching\n_STOPWORDS: set[str] = {\n \"a\",\n \"an\",\n \"the\",\n \"is\",\n \"are\",\n \"was\",\n \"were\",\n \"be\",\n \"been\",\n \"being\",\n \"have\",\n \"has\",\n \"had\",\n \"do\",\n \"does\",\n \"did\",\n \"will\",\n \"would\",\n \"could\",\n \"should\",\n \"may\",\n \"might\",\n \"can\",\n \"to\",\n \"of\",\n \"in\",\n \"on\",\n \"at\",\n \"by\",\n \"for\",\n \"with\",\n \"about\",\n \"as\",\n \"into\",\n \"through\",\n \"from\",\n \"what\",\n \"when\",\n \"where\",\n \"who\",\n \"which\",\n \"how\",\n \"why\",\n \"get\",\n \"set\",\n \"put\",\n}\n\n\ndef _tokenize_query(query: str) -> list[str]:\n \"\"\"Tokenize a query string into meaningful keywords.\n\n Splits on non-word characters, filters stopwords and short tokens.\n\n Args:\n query: The search query string\n\n Returns:\n List of lowercase tokens suitable for keyword matching\n \"\"\"\n tokens = [\n token.lower()\n for token in re.split(r\"\\W+\", query)\n if token and len(token) > 2 and token.lower() not in _STOPWORDS\n ]\n return tokens\n\n\ndef _tokens_match_text(\n tokens: list[str],\n text: str,\n) -> bool:\n \"\"\"Check if any token matches within the given text.\n\n Args:\n tokens: List of query tokens\n text: Text to search within\n\n Returns:\n True if any token is found in the text\n \"\"\"\n if not tokens or not text:\n return False\n text_lower = text.lower()\n return any(token in text_lower for token in tokens)\n\n\n# Maximum possible text_boost sum for lexical scoring normalization\n# path(5.0) + name(3.0) + description(2.0) + tag(1.5) + metadata(1.0) + tool(1.0) = 13.5\nMAX_LEXICAL_BOOST: float = 13.5\n\n# Maximum fraction of max_results any single entity type can claim\n# when other entity types have results competing for slots.\n# 0.6 means no type gets more than 60% of total unless no competition.\nSOFT_CAP_RATIO: float = 0.6\n\n\ndef _tool_extraction_limit(\n max_results: int,\n) -> int:\n \"\"\"Calculate the maximum number of tools to extract from server matching_tools.\n\n Uses the soft cap ratio but never goes below 3 for backward compatibility.\n\n Args:\n max_results: The max_results parameter from the search request.\n\n Returns:\n Maximum number of tools to extract.\n \"\"\"\n return max(3, math.ceil(max_results * SOFT_CAP_RATIO))\n\n\ndef _distribute_results(\n scored_results: list[tuple[dict, float]],\n max_results: int,\n) -> list[tuple[dict, float]]:\n \"\"\"Select top results with competitive soft caps per entity type.\n\n Picks the top max_results items by relevance_score. A soft cap prevents\n any single entity type from taking more than 60% of slots -- but the cap\n is only enforced when other entity types have results waiting below in\n the ranking. If no other types remain, the cap is lifted.\n\n Uses a two-pass approach:\n 1. First pass: pick items respecting soft caps\n 2. Backfill pass: if we haven't reached max_results, fill remaining\n slots from skipped items (highest score first)\n\n Args:\n scored_results: List of (doc, relevance_score) tuples, sorted by\n relevance_score descending.\n max_results: Maximum number of results to return.\n\n Returns:\n Filtered list of (doc, relevance_score) tuples, length <= max_results.\n \"\"\"\n if not scored_results or max_results <= 0:\n return []\n\n soft_cap = max(1, math.ceil(max_results * SOFT_CAP_RATIO))\n type_counts: dict[str, int] = {}\n selected: list[tuple[dict, float]] = []\n skipped: list[tuple[dict, float]] = []\n\n # Pre-compute which entity types exist at each position onward.\n # remaining_types[i] = set of entity types present in scored_results[i:]\n total = len(scored_results)\n remaining_types: list[set[str]] = [set() for _ in range(total + 1)]\n for i in range(total - 1, -1, -1):\n entity_type = scored_results[i][0].get(\"entity_type\", \"\")\n remaining_types[i] = remaining_types[i + 1] | {entity_type}\n\n # Pass 1: pick items respecting soft caps\n for i, (doc, score) in enumerate(scored_results):\n if len(selected) >= max_results:\n break\n\n entity_type = doc.get(\"entity_type\", \"\")\n current_count = type_counts.get(entity_type, 0)\n\n if current_count >= soft_cap:\n # Check if other types still have results after this position\n types_after = remaining_types[i + 1] - {entity_type}\n if types_after:\n skipped.append((doc, score))\n continue # Other types waiting -- enforce cap\n # No competition -- allow this type to fill remaining slots\n\n selected.append((doc, score))\n type_counts[entity_type] = current_count + 1\n\n # Pass 2: backfill from skipped items if we haven't reached max_results\n # Skipped items are already in descending score order\n for doc, score in skipped:\n if len(selected) >= max_results:\n break\n selected.append((doc, score))\n\n logger.debug(\n \"Search distribution: max_results=%d, soft_cap=%d, selected=%d, per_type=%s\",\n max_results,\n soft_cap,\n len(selected),\n dict(type_counts),\n )\n\n return selected\n\n\n\n\n\n\ndef _build_status_filter(\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n) -> dict:\n \"\"\"Build MongoDB $match filter to exclude statuses and disabled entities.\n\n By default, draft, deprecated, and disabled assets are excluded from search.\n Existing documents without a status field are treated as active.\n Existing documents without is_enabled field are treated as enabled.\n\n Applied consistently across servers, agents, and skills.\n\n Args:\n include_draft: If True, include draft assets in results\n include_deprecated: If True, include deprecated assets in results\n include_disabled: If True, include disabled assets in results\n\n Returns:\n MongoDB filter dict (empty dict if no filtering needed)\n \"\"\"\n conditions: list[dict] = []\n\n # Status filtering\n excluded_statuses = []\n if not include_draft:\n excluded_statuses.append(\"draft\")\n if not include_deprecated:\n excluded_statuses.append(\"deprecated\")\n\n if excluded_statuses:\n # Exclude listed statuses; documents missing the field are treated as active\n conditions.append(\n {\n \"$or\": [\n {\"status\": {\"$nin\": excluded_statuses}},\n {\"status\": {\"$exists\": False}},\n ]\n }\n )\n\n # Enabled filtering\n if not include_disabled:\n # Exclude disabled entities; documents missing is_enabled are treated as enabled\n conditions.append(\n {\n \"$or\": [\n {\"is_enabled\": True},\n {\"is_enabled\": {\"$exists\": False}},\n ]\n }\n )\n\n if not conditions:\n return {}\n\n if len(conditions) == 1:\n return conditions[0]\n\n return {\"$and\": conditions}\n\n\ndef _build_keyword_match_filter(\n token_regex: str,\n entity_types: list[str] | None = None,\n) -> dict:\n \"\"\"Build the $match filter for keyword matching across document fields.\n\n Args:\n token_regex: Regex pattern combining query tokens with OR\n entity_types: Optional list of entity types to filter\n\n Returns:\n MongoDB $match filter dict\n \"\"\"\n match_filter = {\n \"$or\": [\n {\"name\": {\"$regex\": token_regex, \"$options\": \"i\"}},\n {\"path\": {\"$regex\": token_regex, \"$options\": \"i\"}},\n {\"description\": {\"$regex\": token_regex, \"$options\": \"i\"}},\n {\"tags\": {\"$regex\": token_regex, \"$options\": \"i\"}},\n {\"tools.name\": {\"$regex\": token_regex, \"$options\": \"i\"}},\n {\"tools.description\": {\"$regex\": token_regex, \"$options\": \"i\"}},\n {\"metadata_text\": {\"$regex\": token_regex, \"$options\": \"i\"}},\n ]\n }\n if entity_types:\n match_filter[\"entity_type\"] = {\"$in\": entity_types}\n return match_filter\n\n\ndef _build_text_boost_stage(\n token_regex: str,\n) -> dict:\n \"\"\"Build the $addFields stage for text boost calculation.\n\n Computes text_boost by matching query tokens against document fields:\n path (+5.0), name (+3.0), description (+2.0), tags (+1.5), metadata (+1.0), tools (+1.0).\n\n Args:\n token_regex: Regex pattern combining query tokens with OR\n\n Returns:\n MongoDB $addFields pipeline stage dict\n \"\"\"\n return {\n \"$addFields\": {\n \"text_boost\": {\n \"$add\": [\n # Path match: +5.0\n {\n \"$cond\": [\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$path\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n 5.0,\n 0.0,\n ]\n },\n # Name match: +3.0\n {\n \"$cond\": [\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$name\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n 3.0,\n 0.0,\n ]\n },\n # Description match: +2.0\n {\n \"$cond\": [\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$description\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n 2.0,\n 0.0,\n ]\n },\n # Tags match: +1.5 if any tag matches\n {\n \"$cond\": [\n {\n \"$gt\": [\n {\n \"$size\": {\n \"$filter\": {\n \"input\": {\"$ifNull\": [\"$tags\", []]},\n \"as\": \"tag\",\n \"cond\": {\n \"$regexMatch\": {\n \"input\": \"$$tag\",\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n }\n }\n },\n 0,\n ]\n },\n 1.5,\n 0.0,\n ]\n },\n # Metadata match: +1.0\n {\n \"$cond\": [\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$metadata_text\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n 1.0,\n 0.0,\n ]\n },\n # Tools match: +1.0 per matching tool\n {\n \"$size\": {\n \"$filter\": {\n \"input\": {\"$ifNull\": [\"$tools\", []]},\n \"as\": \"tool\",\n \"cond\": {\n \"$or\": [\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$$tool.name\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$$tool.description\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n ]\n },\n }\n }\n },\n ]\n },\n # Track matching tools for display\n \"matching_tools\": {\n \"$map\": {\n \"input\": {\n \"$filter\": {\n \"input\": {\"$ifNull\": [\"$tools\", []]},\n \"as\": \"tool\",\n \"cond\": {\n \"$or\": [\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$$tool.name\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n {\n \"$regexMatch\": {\n \"input\": {\"$ifNull\": [\"$$tool.description\", \"\"]},\n \"regex\": token_regex,\n \"options\": \"i\",\n }\n },\n ]\n },\n }\n },\n \"as\": \"tool\",\n \"in\": {\n \"tool_name\": \"$$tool.name\",\n \"description\": {\"$ifNull\": [\"$$tool.description\", \"\"]},\n \"relevance_score\": 1.0,\n \"match_context\": {\n \"$cond\": [\n {\"$ne\": [\"$$tool.description\", None]},\n \"$$tool.description\",\n {\"$concat\": [\"Tool: \", \"$$tool.name\"]},\n ]\n },\n },\n }\n },\n }\n }\n\n\nclass DocumentDBSearchRepository(SearchRepositoryBase):\n \"\"\"DocumentDB implementation with hybrid search (text + vector).\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\n f\"mcp_embeddings_{settings.embeddings_model_dimensions}\"\n )\n self._embedding_model = None\n self._embedding_unavailable: bool = False\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def _get_embedding_model(self):\n \"\"\"Lazy load embedding model.\"\"\"\n if self._embedding_model is None:\n from ...embeddings import create_embeddings_client\n\n self._embedding_model = create_embeddings_client(\n provider=settings.embeddings_provider,\n model_name=settings.embeddings_model_name,\n model_dir=settings.embeddings_model_dir,\n api_key=settings.embeddings_api_key,\n api_base=settings.embeddings_api_base,\n aws_region=settings.embeddings_aws_region,\n embedding_dimension=settings.embeddings_model_dimensions,\n )\n return self._embedding_model\n\n async def initialize(self) -> None:\n \"\"\"Initialize the search service and create vector index.\"\"\"\n logger.info(f\"Initializing DocumentDB hybrid search on collection: {self._collection_name}\")\n collection = await self._get_collection()\n\n try:\n indexes = await collection.list_indexes().to_list(length=100)\n index_names = [idx[\"name\"] for idx in indexes]\n\n if \"embedding_vector_idx\" not in index_names:\n try:\n logger.info(\"Creating HNSW vector index for embeddings...\")\n await collection.create_index(\n [(\"embedding\", \"vector\")],\n name=\"embedding_vector_idx\",\n vectorOptions={\n \"type\": \"hnsw\",\n \"similarity\": \"cosine\",\n \"dimensions\": settings.embeddings_model_dimensions,\n \"m\": 16,\n \"efConstruction\": 128,\n },\n )\n logger.info(\"Created HNSW vector index\")\n except Exception as vector_error:\n # Check if this is a MongoDB CE error (vectorOptions not supported)\n if \"vectorOptions\" in str(\n vector_error\n ) or \"not valid for an index specification\" in str(vector_error):\n logger.warning(\n \"Vector indexes not supported (MongoDB CE detected). \"\n \"Creating regular index on embedding field.\"\n )\n # Create a regular index on the embedding field for faster retrieval\n await collection.create_index(\n [(\"embedding\", 1)], name=\"embedding_vector_idx\"\n )\n logger.info(\"Created regular embedding index\")\n else:\n # Re-raise if it's a different error\n raise vector_error\n else:\n logger.info(\"Vector index already exists\")\n\n if \"path_idx\" not in index_names:\n await collection.create_index([(\"path\", 1)], name=\"path_idx\", unique=True)\n logger.info(\"Created path index\")\n\n except Exception as e:\n logger.error(f\"Failed to initialize search indexes: {e}\", exc_info=True)\n\n async def index_server(\n self,\n path: str,\n server_info: dict[str, Any],\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index a server for search.\"\"\"\n collection = await self._get_collection()\n\n text_parts = [\n server_info.get(\"server_name\", \"\"),\n server_info.get(\"description\", \"\"),\n ]\n\n tags = server_info.get(\"tags\", [])\n if tags:\n text_parts.append(\"Tags: \" + \", \".join(tags))\n\n for tool in server_info.get(\"tool_list\", []):\n text_parts.append(tool.get(\"name\", \"\"))\n text_parts.append(tool.get(\"description\", \"\"))\n\n # Include custom metadata key-value pairs in embedding text\n metadata = server_info.get(\"metadata\", {})\n if isinstance(metadata, dict) and metadata:\n for key, value in metadata.items():\n text_parts.append(f\"{key}: {value}\")\n\n text_for_embedding = \" \".join(filter(None, text_parts))\n\n # Flatten metadata into a searchable text field for keyword matching\n metadata_text = flatten_metadata_to_text(metadata)\n\n try:\n model = await self._get_embedding_model()\n embedding = model.encode([text_for_embedding])[0].tolist()\n except Exception as e:\n logger.warning(\n \"Embedding model unavailable, indexing '%s' without embeddings: %s\",\n server_info.get(\"server_name\", path),\n e,\n )\n embedding = []\n\n doc = {\n \"_id\": path,\n \"entity_type\": \"mcp_server\",\n \"path\": path,\n \"name\": server_info.get(\"server_name\", \"\"),\n \"description\": server_info.get(\"description\", \"\"),\n \"tags\": server_info.get(\"tags\", []),\n \"metadata_text\": metadata_text,\n \"is_enabled\": is_enabled,\n \"status\": server_info.get(\"status\", \"active\"),\n \"text_for_embedding\": text_for_embedding,\n \"embedding\": embedding,\n \"embedding_metadata\": embedding_config.get_embedding_metadata(),\n \"tools\": [\n {\n \"name\": t.get(\"name\"),\n \"description\": t.get(\"description\"),\n # Support both \"inputSchema\" (MCP standard) and \"schema\" (legacy)\n \"inputSchema\": t.get(\"inputSchema\") or t.get(\"schema\", {}),\n }\n for t in server_info.get(\"tool_list\", [])\n ],\n \"metadata\": server_info,\n \"indexed_at\": server_info.get(\"updated_at\", server_info.get(\"registered_at\")),\n }\n\n try:\n await collection.replace_one({\"_id\": path}, doc, upsert=True)\n logger.info(f\"Indexed server '{server_info.get('server_name')}' for search\")\n except Exception as e:\n logger.error(f\"Failed to index server in search: {e}\", exc_info=True)\n\n async def index_agent(\n self,\n path: str,\n agent_card: AgentCard,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index an agent for search.\"\"\"\n collection = await self._get_collection()\n\n text_parts = [\n agent_card.name,\n agent_card.description or \"\",\n ]\n\n tags = agent_card.tags or []\n if tags:\n text_parts.append(\"Tags: \" + \", \".join(tags))\n\n # Include capability keys (feature flags like \"streaming\")\n if agent_card.capabilities:\n text_parts.append(\"Capabilities: \" + \", \".join(agent_card.capabilities))\n\n # Include skill names and descriptions for better semantic search\n if agent_card.skills:\n for skill in agent_card.skills:\n text_parts.append(skill.name)\n if skill.description:\n text_parts.append(skill.description)\n\n text_for_embedding = \" \".join(filter(None, text_parts))\n\n try:\n model = await self._get_embedding_model()\n embedding = model.encode([text_for_embedding])[0].tolist()\n except Exception as e:\n logger.warning(\n \"Embedding model unavailable, indexing agent '%s' without embeddings: %s\",\n agent_card.name,\n e,\n )\n embedding = []\n\n # Flatten agent metadata for keyword search\n agent_metadata = getattr(agent_card, \"metadata\", None) or {}\n agent_metadata_text = flatten_metadata_to_text(agent_metadata)\n\n doc = {\n \"_id\": path,\n \"entity_type\": \"a2a_agent\",\n \"path\": path,\n \"name\": agent_card.name,\n \"description\": agent_card.description or \"\",\n \"tags\": agent_card.tags or [],\n \"metadata_text\": agent_metadata_text,\n \"is_enabled\": is_enabled,\n \"status\": getattr(agent_card, \"status\", \"active\"),\n \"text_for_embedding\": text_for_embedding,\n \"embedding\": embedding,\n \"embedding_metadata\": embedding_config.get_embedding_metadata(),\n \"capabilities\": agent_card.capabilities or [],\n \"metadata\": agent_card.model_dump(mode=\"json\"),\n \"indexed_at\": agent_card.updated_at or agent_card.registered_at,\n }\n\n try:\n await collection.replace_one({\"_id\": path}, doc, upsert=True)\n logger.info(f\"Indexed agent '{agent_card.name}' for search\")\n except Exception as e:\n logger.error(f\"Failed to index agent in search: {e}\", exc_info=True)\n\n async def index_skill(\n self,\n path: str,\n skill: Any,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index a skill for semantic search.\n\n Args:\n path: Skill path (e.g., /skills/pdf-processing)\n skill: SkillCard object\n is_enabled: Whether skill is enabled\n \"\"\"\n collection = await self._get_collection()\n\n # Compose text for embedding\n text_parts = [\n skill.name,\n skill.description,\n ]\n\n if skill.tags:\n text_parts.append(f\"Tags: {', '.join(skill.tags)}\")\n\n if skill.compatibility:\n text_parts.append(f\"Compatibility: {skill.compatibility}\")\n\n if skill.target_agents:\n text_parts.append(f\"For: {', '.join(skill.target_agents)}\")\n\n if skill.metadata and skill.metadata.author:\n text_parts.append(f\"Author: {skill.metadata.author}\")\n\n if skill.metadata and skill.metadata.extra:\n extra_text = flatten_metadata_to_text(skill.metadata.extra)\n if extra_text:\n text_parts.append(extra_text)\n\n text_for_embedding = \" \".join(filter(None, text_parts))\n\n # Generate embedding\n try:\n model = await self._get_embedding_model()\n embedding = model.encode([text_for_embedding])[0].tolist()\n except Exception as e:\n logger.warning(\n \"Embedding model unavailable, indexing skill '%s' without embeddings: %s\",\n skill.name,\n e,\n )\n embedding = []\n\n # Handle visibility enum\n visibility_value = skill.visibility\n if hasattr(visibility_value, \"value\"):\n visibility_value = visibility_value.value\n\n # Flatten skill metadata for keyword search\n skill_metadata_parts = []\n if skill.metadata and skill.metadata.author:\n skill_metadata_parts.append(f\"author {skill.metadata.author}\")\n if skill.metadata and skill.metadata.version:\n skill_metadata_parts.append(f\"version {skill.metadata.version}\")\n if skill.metadata and skill.metadata.extra:\n extra_text = flatten_metadata_to_text(skill.metadata.extra)\n if extra_text:\n skill_metadata_parts.append(extra_text)\n if skill.registry_name:\n skill_metadata_parts.append(f\"registry {skill.registry_name}\")\n skill_metadata_text = \" \".join(skill_metadata_parts)\n\n # Build search document\n search_doc = {\n \"_id\": path,\n \"entity_type\": \"skill\",\n \"path\": path,\n \"name\": skill.name,\n \"description\": skill.description,\n \"tags\": skill.tags or [],\n \"metadata_text\": skill_metadata_text,\n \"is_enabled\": is_enabled,\n \"visibility\": visibility_value,\n \"allowed_groups\": skill.allowed_groups or [],\n \"owner\": skill.owner,\n \"health_status\": skill.health_status,\n \"last_checked_time\": skill.last_checked_time.isoformat()\n if skill.last_checked_time\n else None,\n \"status\": getattr(skill, \"status\", \"active\"),\n \"text_for_embedding\": text_for_embedding,\n \"embedding\": embedding,\n \"embedding_metadata\": embedding_config.get_embedding_metadata(),\n \"metadata\": {\n \"skill_md_url\": str(skill.skill_md_url),\n \"skill_md_raw_url\": str(skill.skill_md_raw_url) if skill.skill_md_raw_url else None,\n \"author\": skill.metadata.author if skill.metadata else None,\n \"version\": skill.metadata.version if skill.metadata else None,\n \"compatibility\": skill.compatibility,\n \"target_agents\": skill.target_agents or [],\n \"registry_name\": skill.registry_name,\n },\n \"indexed_at\": skill.updated_at or skill.created_at,\n }\n\n # Upsert to search collection\n try:\n await collection.replace_one({\"_id\": path}, search_doc, upsert=True)\n logger.info(f\"Indexed skill for search: {path}\")\n except Exception as e:\n logger.error(f\"Failed to index skill in search: {e}\", exc_info=True)\n\n async def index_virtual_server(\n self,\n path: str,\n virtual_server: Any,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index a virtual server for semantic search.\n\n Args:\n path: Virtual server path (e.g., /virtual/dev-essentials)\n virtual_server: VirtualServerConfig object\n is_enabled: Whether virtual server is enabled\n \"\"\"\n # Lazy import to avoid circular dependency\n from ...services.server_service import server_service\n\n collection = await self._get_collection()\n\n # Get backend server paths for metadata\n backend_paths = list(\n {mapping.backend_server_path for mapping in virtual_server.tool_mappings}\n )\n\n # Fetch tool descriptions from backend servers\n # Build a map: backend_path -> {tool_name -> description}\n backend_tool_descriptions: dict[str, dict[str, str]] = {}\n for backend_path in backend_paths:\n try:\n server_info = await server_service.get_server_info(backend_path)\n if server_info:\n tool_list = server_info.get(\"tool_list\", [])\n backend_tool_descriptions[backend_path] = {\n tool.get(\"name\", \"\"): tool.get(\"description\", \"\") for tool in tool_list\n }\n except Exception as e:\n logger.warning(f\"Failed to fetch tools from backend {backend_path}: {e}\")\n backend_tool_descriptions[backend_path] = {}\n\n # Compose text for embedding\n text_parts = [\n virtual_server.server_name,\n virtual_server.description or \"\",\n ]\n\n # Add tags\n if virtual_server.tags:\n text_parts.append(f\"Tags: {', '.join(virtual_server.tags)}\")\n\n # Build tools array and collect text for embedding\n tools = []\n tool_names = []\n for mapping in virtual_server.tool_mappings:\n display_name = mapping.alias or mapping.tool_name\n tool_names.append(display_name)\n\n # Use description_override if set, otherwise get from backend\n if mapping.description_override:\n description = mapping.description_override\n else:\n backend_tools = backend_tool_descriptions.get(mapping.backend_server_path, {})\n description = backend_tools.get(mapping.tool_name, \"\")\n\n # Add description to embedding text\n if description:\n text_parts.append(description)\n\n tools.append(\n {\n \"name\": display_name,\n \"description\": description,\n \"backend_server\": mapping.backend_server_path,\n }\n )\n\n if tool_names:\n text_parts.append(f\"Tools: {', '.join(tool_names)}\")\n\n text_for_embedding = \" \".join(filter(None, text_parts))\n\n # Generate embedding\n try:\n model = await self._get_embedding_model()\n embedding = model.encode([text_for_embedding])[0].tolist()\n except Exception as e:\n logger.warning(\n \"Embedding model unavailable, indexing virtual server '%s' without embeddings: %s\",\n virtual_server.server_name,\n e,\n )\n embedding = []\n\n # Flatten virtual server metadata for keyword search\n vs_metadata_parts = []\n if virtual_server.created_by:\n vs_metadata_parts.append(f\"created_by {virtual_server.created_by}\")\n vs_metadata_text = \" \".join(vs_metadata_parts)\n\n # Build search document\n search_doc = {\n \"_id\": path,\n \"entity_type\": \"virtual_server\",\n \"path\": path,\n \"name\": virtual_server.server_name,\n \"description\": virtual_server.description or \"\",\n \"tags\": virtual_server.tags or [],\n \"metadata_text\": vs_metadata_text,\n \"is_enabled\": is_enabled,\n \"text_for_embedding\": text_for_embedding,\n \"embedding\": embedding,\n \"embedding_metadata\": embedding_config.get_embedding_metadata(),\n \"tools\": tools,\n \"metadata\": {\n \"server_name\": virtual_server.server_name,\n \"num_tools\": len(virtual_server.tool_mappings),\n \"backend_count\": len(backend_paths),\n \"backend_paths\": backend_paths,\n \"required_scopes\": virtual_server.required_scopes,\n \"supported_transports\": virtual_server.supported_transports,\n \"created_by\": virtual_server.created_by,\n },\n \"indexed_at\": virtual_server.updated_at or virtual_server.created_at,\n }\n\n # Upsert to search collection\n try:\n await collection.replace_one({\"_id\": path}, search_doc, upsert=True)\n logger.info(f\"Indexed virtual server for search: {path}\")\n except Exception as e:\n logger.error(f\"Failed to index virtual server in search: {e}\", exc_info=True)\n\n def _calculate_cosine_similarity(self, vec1: list[float], vec2: list[float]) -> float:\n \"\"\"Calculate cosine similarity between two vectors.\n\n Returns a value between 0 and 1, where 1 is identical.\n \"\"\"\n import math\n\n if not vec1 or not vec2 or len(vec1) != len(vec2):\n return 0.0\n\n dot_product = sum(a * b for a, b in zip(vec1, vec2, strict=True))\n magnitude1 = math.sqrt(sum(a * a for a in vec1))\n magnitude2 = math.sqrt(sum(b * b for b in vec2))\n\n if magnitude1 == 0 or magnitude2 == 0:\n return 0.0\n\n return dot_product / (magnitude1 * magnitude2)\n\n async def search_by_tags(\n self,\n tags: list[str],\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Search entities by exact tag match using a direct DB query.\"\"\"\n collection = await self._get_collection()\n\n # Build a case-insensitive match for ALL tags\n tag_conditions: list[dict[str, Any]] = [\n {\"tags\": {\"$regex\": f\"^{re.escape(tag)}$\", \"$options\": \"i\"}} for tag in tags\n ]\n\n # Add lifecycle status and enabled filter\n status_filter = _build_status_filter(\n include_draft=include_draft,\n include_deprecated=include_deprecated,\n include_disabled=include_disabled,\n )\n if status_filter:\n tag_conditions.append(status_filter)\n\n query_filter: dict[str, Any] = {\"$and\": tag_conditions}\n if entity_types:\n query_filter[\"entity_type\"] = {\"$in\": entity_types}\n\n cursor = collection.find(query_filter).limit(max_results * 5)\n results = await cursor.to_list(length=max_results * 5)\n\n logger.info(\n \"Tag-only search for %s returned %d documents\",\n tags,\n len(results),\n )\n\n # Format into grouped results using the lexical formatter\n # Assign relevance 1.0 since these are exact tag matches\n for doc in results:\n doc[\"text_boost\"] = MAX_LEXICAL_BOOST\n doc[\"matching_tools\"] = []\n return self._format_lexical_results(results, max_results)\n\n async def get_all_tags(self) -> list[str]:\n \"\"\"Return a sorted list of all unique tags across all indexed entities.\"\"\"\n collection = await self._get_collection()\n try:\n pipeline = [\n {\"$match\": {\"tags\": {\"$exists\": True, \"$ne\": []}}},\n {\"$unwind\": \"$tags\"},\n {\"$group\": {\"_id\": {\"$toLower\": \"$tags\"}, \"original\": {\"$first\": \"$tags\"}}},\n {\"$sort\": {\"_id\": 1}},\n ]\n cursor = collection.aggregate(pipeline)\n results = await cursor.to_list(length=500)\n return [doc[\"original\"] for doc in results]\n except Exception as e:\n logger.error(\"Failed to retrieve tags: %s\", e, exc_info=True)\n return []\n\n async def remove_entity(\n self,\n path: str,\n ) -> None:\n \"\"\"Remove entity from search index.\"\"\"\n collection = await self._get_collection()\n\n try:\n result = await collection.delete_one({\"_id\": path})\n if result.deleted_count > 0:\n logger.info(f\"Removed entity '{path}' from search index\")\n else:\n logger.warning(f\"Entity '{path}' not found in search index\")\n except Exception as e:\n logger.error(f\"Failed to remove entity from search index: {e}\", exc_info=True)\n\n async def _client_side_search(\n self,\n query: str,\n query_embedding: list[float],\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Fallback search using client-side cosine similarity for MongoDB CE.\n\n This method is used when MongoDB doesn't support native vector search.\n It fetches all embeddings from the database and computes similarity locally.\n \"\"\"\n collection = await self._get_collection()\n\n try:\n # Build query filter\n query_filter = {}\n if entity_types:\n query_filter[\"entity_type\"] = {\"$in\": entity_types}\n\n # Apply lifecycle status and enabled filter\n status_filter = _build_status_filter(\n include_draft=include_draft,\n include_deprecated=include_deprecated,\n include_disabled=include_disabled,\n )\n if status_filter:\n query_filter.update(status_filter)\n\n # Fetch all embeddings from MongoDB\n cursor = collection.find(\n query_filter,\n {\n \"_id\": 1,\n \"path\": 1,\n \"entity_type\": 1,\n \"name\": 1,\n \"description\": 1,\n \"tags\": 1,\n \"tools\": 1,\n \"metadata\": 1,\n \"metadata_text\": 1,\n \"is_enabled\": 1,\n \"status\": 1,\n \"visibility\": 1,\n \"owner\": 1,\n \"allowed_groups\": 1,\n \"health_status\": 1,\n \"last_checked_time\": 1,\n \"embedding\": 1,\n },\n )\n\n all_docs = await cursor.to_list(length=None)\n logger.info(f\"Client-side search: Retrieved {len(all_docs)} documents with embeddings\")\n\n # Tokenize query for keyword matching\n query_tokens = _tokenize_query(query)\n logger.debug(f\"Client-side search tokens: {query_tokens}\")\n\n # Calculate cosine similarity for each document\n scored_docs = []\n for doc in all_docs:\n embedding = doc.get(\"embedding\", [])\n if not embedding:\n vector_score = 0.0\n else:\n vector_score = self._calculate_cosine_similarity(query_embedding, embedding)\n\n # Add text-based boost using tokenized matching\n text_boost = 0.0\n name = doc.get(\"name\", \"\")\n description = doc.get(\"description\", \"\")\n tags = doc.get(\"tags\", [])\n tools = doc.get(\"tools\", [])\n matching_tools = []\n\n # Token-based matching for text boost\n # Check path match first (highest priority - user explicitly named the server)\n path = doc.get(\"path\", \"\")\n server_name_matched = False\n if path and _tokens_match_text(query_tokens, path):\n text_boost += 5.0\n server_name_matched = True\n if name and _tokens_match_text(query_tokens, name):\n text_boost += 3.0\n server_name_matched = True\n if description and _tokens_match_text(query_tokens, description):\n text_boost += 2.0\n # Check if any token matches any tag\n if tags and any(_tokens_match_text(query_tokens, tag) for tag in tags):\n text_boost += 1.5\n\n # Check metadata_text match\n metadata_text = doc.get(\"metadata_text\", \"\")\n if metadata_text and _tokens_match_text(query_tokens, metadata_text):\n text_boost += 1.0\n\n # Check if any token matches any tool name or description\n for tool in tools:\n tool_name = tool.get(\"name\", \"\")\n tool_desc = tool.get(\"description\") or \"\"\n tool_matched = _tokens_match_text(\n query_tokens, tool_name\n ) or _tokens_match_text(query_tokens, tool_desc)\n\n if tool_matched:\n text_boost += 1.0\n matching_tools.append(\n {\n \"tool_name\": tool_name,\n \"description\": tool_desc,\n \"relevance_score\": 1.0,\n \"match_context\": tool_desc or f\"Tool: {tool_name}\",\n }\n )\n elif server_name_matched:\n # If server name/path matched, include all tools with base score\n matching_tools.append(\n {\n \"tool_name\": tool_name,\n \"description\": tool_desc,\n \"relevance_score\": 0.8,\n \"match_context\": tool_desc or f\"Tool: {tool_name}\",\n }\n )\n\n # Store matching tools for later use\n doc[\"_matching_tools\"] = matching_tools\n\n # Hybrid score: vector score + normalized text boost\n # Normalize vector_score to [0, 1] range (cosine can be [-1, 1])\n normalized_vector_score = (vector_score + 1.0) / 2.0\n # Text boost multiplier: 0.1 (same as DocumentDB search path)\n # Path match (5.0) adds +0.50, Name match (3.0) adds +0.30\n text_boost_contribution = text_boost * 0.1\n relevance_score = normalized_vector_score + text_boost_contribution\n relevance_score = max(0.0, min(1.0, relevance_score))\n\n logger.info(\n \"Score for '%s' (type=%s): vector=%.4f, \"\n \"normalized_vector=%.4f, text_boost=%.1f, \"\n \"boost_contrib=%.4f, final=%.4f\",\n doc.get(\"name\"),\n doc.get(\"entity_type\"),\n vector_score,\n normalized_vector_score,\n text_boost,\n text_boost_contribution,\n relevance_score,\n )\n\n scored_docs.append(\n {\n \"doc\": doc,\n \"relevance_score\": relevance_score,\n \"vector_score\": vector_score,\n \"text_boost\": text_boost,\n }\n )\n\n # Sort by relevance score (descending)\n scored_docs.sort(key=lambda x: x[\"relevance_score\"], reverse=True)\n\n # Convert to (doc, score) tuples and distribute with soft caps\n scored_tuples = [(item[\"doc\"], item[\"relevance_score\"]) for item in scored_docs]\n selected = _distribute_results(scored_tuples, max_results)\n\n # Format results to match the API contract\n grouped_results = {\n \"servers\": [],\n \"tools\": [],\n \"agents\": [],\n \"skills\": [],\n \"virtual_servers\": [],\n }\n\n tool_count = 0\n tool_limit = _tool_extraction_limit(max_results)\n\n for doc, relevance_score in selected:\n entity_type = doc.get(\"entity_type\")\n\n if entity_type == \"mcp_server\":\n matching_tools = doc.get(\"_matching_tools\", [])\n server_metadata = doc.get(\"metadata\", {})\n\n result_entry = {\n \"entity_type\": \"mcp_server\",\n \"path\": doc.get(\"path\"),\n \"server_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"num_tools\": server_metadata.get(\"num_tools\", 0),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"matching_tools\": matching_tools,\n \"proxy_pass_url\": server_metadata.get(\"proxy_pass_url\"),\n \"mcp_endpoint\": server_metadata.get(\"mcp_endpoint\"),\n \"sse_endpoint\": server_metadata.get(\"sse_endpoint\"),\n \"supported_transports\": server_metadata.get(\"supported_transports\", []),\n }\n grouped_results[\"servers\"].append(result_entry)\n\n # Also add matching tools to the top-level tools array\n original_tools = doc.get(\"tools\", [])\n tool_schema_map = {\n t.get(\"name\", \"\"): t.get(\"inputSchema\", {}) for t in original_tools\n }\n\n server_path = doc.get(\"path\", \"\")\n server_name = doc.get(\"name\", \"\")\n for tool in matching_tools:\n if tool_count >= tool_limit:\n break\n tool_name = tool.get(\"tool_name\", \"\")\n grouped_results[\"tools\"].append(\n {\n \"entity_type\": \"tool\",\n \"server_path\": server_path,\n \"server_name\": server_name,\n \"tool_name\": tool_name,\n \"description\": tool.get(\"description\", \"\"),\n \"inputSchema\": tool_schema_map.get(tool_name, {}),\n \"relevance_score\": tool.get(\"relevance_score\", relevance_score),\n \"match_context\": tool.get(\"match_context\", \"\"),\n }\n )\n tool_count += 1\n\n elif entity_type == \"a2a_agent\":\n metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"a2a_agent\",\n \"path\": doc.get(\"path\"),\n \"agent_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"skills\": metadata.get(\"skills\", []),\n \"visibility\": metadata.get(\"visibility\", \"public\"),\n \"trust_level\": metadata.get(\"trust_level\"),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"agent_card\": metadata.get(\"agent_card\", {}),\n }\n grouped_results[\"agents\"].append(result_entry)\n\n elif entity_type == \"mcp_tool\":\n result_entry = {\n \"entity_type\": \"mcp_tool\",\n \"path\": doc.get(\"path\"),\n \"tool_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"inputSchema\": doc.get(\"inputSchema\", {}),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n }\n grouped_results[\"tools\"].append(result_entry)\n\n elif entity_type == \"skill\":\n metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"skill\",\n \"path\": doc.get(\"path\"),\n \"skill_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"skill_md_url\": metadata.get(\"skill_md_url\"),\n \"version\": metadata.get(\"version\"),\n \"author\": metadata.get(\"author\"),\n \"visibility\": doc.get(\"visibility\", \"public\"),\n \"owner\": doc.get(\"owner\"),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"status\": doc.get(\"status\", \"active\"),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n }\n grouped_results[\"skills\"].append(result_entry)\n\n elif entity_type == \"virtual_server\":\n metadata = doc.get(\"metadata\", {})\n matching_tools = doc.get(\"_matching_tools\", [])\n result_entry = {\n \"entity_type\": \"virtual_server\",\n \"path\": doc.get(\"path\"),\n \"server_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"num_tools\": metadata.get(\"num_tools\", 0),\n \"backend_count\": metadata.get(\"backend_count\", 0),\n \"backend_paths\": metadata.get(\"backend_paths\", []),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"matching_tools\": matching_tools,\n }\n grouped_results[\"virtual_servers\"].append(result_entry)\n\n logger.info(\n \"Client-side search returned \"\n \"%d servers, %d tools, %d agents, %d skills, \"\n \"%d virtual_servers from %d total documents (max_results=%d)\",\n len(grouped_results[\"servers\"]),\n len(grouped_results[\"tools\"]),\n len(grouped_results[\"agents\"]),\n len(grouped_results[\"skills\"]),\n len(grouped_results[\"virtual_servers\"]),\n len(all_docs),\n max_results,\n )\n\n return grouped_results\n\n except Exception as e:\n logger.error(f\"Failed to perform client-side search: {e}\", exc_info=True)\n return {\n \"servers\": [],\n \"tools\": [],\n \"agents\": [],\n \"skills\": [],\n \"virtual_servers\": [],\n }\n\n async def _lexical_only_search(\n self,\n query: str,\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Fallback search using keyword matching only (no embeddings).\n\n Used when the embedding model fails to load. Scores results purely\n by keyword matches against name, path, description, tags, and tools.\n\n Args:\n query: The search query string\n entity_types: Optional list of entity types to filter\n max_results: Maximum number of results to return\n include_draft: If True, include draft assets in results\n include_deprecated: If True, include deprecated assets in results\n include_disabled: If True, include disabled assets in results\n\n Returns:\n Grouped search results dict with servers, tools, agents lists\n \"\"\"\n collection = await self._get_collection()\n query_tokens = _tokenize_query(query)\n\n if not query_tokens:\n logger.info(\"Lexical search: no valid tokens from query '%s'\", query)\n return {\"servers\": [], \"tools\": [], \"agents\": [], \"skills\": []}\n\n escaped_tokens = [re.escape(token) for token in query_tokens]\n token_regex = \"|\".join(escaped_tokens)\n\n keyword_match_filter = _build_keyword_match_filter(\n token_regex=token_regex,\n entity_types=entity_types,\n )\n\n text_boost_stage = _build_text_boost_stage(token_regex)\n\n pipeline = [\n {\"$match\": keyword_match_filter},\n ]\n\n # Apply lifecycle status and enabled filter\n status_filter = _build_status_filter(\n include_draft=include_draft,\n include_deprecated=include_deprecated,\n include_disabled=include_disabled,\n )\n if status_filter:\n pipeline.append({\"$match\": status_filter})\n\n pipeline.extend(\n [\n text_boost_stage,\n {\"$sort\": {\"text_boost\": -1}},\n {\"$limit\": max(max_results * 3, 50)},\n ]\n )\n\n cursor = collection.aggregate(pipeline)\n results = await cursor.to_list(length=max(max_results * 3, 50))\n\n grouped_results = self._format_lexical_results(results, max_results)\n\n logger.info(\n \"Lexical-only search for '%s' returned %d servers, %d tools, %d agents\",\n query,\n len(grouped_results[\"servers\"]),\n len(grouped_results[\"tools\"]),\n len(grouped_results[\"agents\"]),\n )\n\n return grouped_results\n\n def _format_lexical_results(\n self,\n results: list[dict],\n max_results: int = 10,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Format lexical search results into grouped response.\n\n Uses fixed-denominator normalization for relevance scoring.\n Applies global ranking with competitive soft caps via _distribute_results().\n\n Args:\n results: Raw MongoDB documents with text_boost field\n max_results: Maximum number of results to return\n\n Returns:\n Grouped search results dict with servers, tools, agents lists\n \"\"\"\n # Score results and sort by relevance before distributing\n scored_tuples: list[tuple[dict, float]] = []\n for doc in results:\n text_boost = doc.get(\"text_boost\", 0.0)\n relevance_score = min(1.0, text_boost / MAX_LEXICAL_BOOST)\n scored_tuples.append((doc, relevance_score))\n\n scored_tuples.sort(key=lambda x: x[1], reverse=True)\n selected = _distribute_results(scored_tuples, max_results)\n\n # Group selected results by entity type\n grouped_results = {\n \"servers\": [],\n \"tools\": [],\n \"agents\": [],\n \"skills\": [],\n \"virtual_servers\": [],\n }\n tool_count = 0\n tool_limit = _tool_extraction_limit(max_results)\n\n for doc, relevance_score in selected:\n entity_type = doc.get(\"entity_type\")\n\n if entity_type == \"mcp_server\":\n matching_tools = doc.get(\"matching_tools\", [])\n server_metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"mcp_server\",\n \"path\": doc.get(\"path\"),\n \"server_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"num_tools\": server_metadata.get(\"num_tools\", 0),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"matching_tools\": matching_tools,\n \"proxy_pass_url\": server_metadata.get(\"proxy_pass_url\"),\n \"mcp_endpoint\": server_metadata.get(\"mcp_endpoint\"),\n \"sse_endpoint\": server_metadata.get(\"sse_endpoint\"),\n \"supported_transports\": server_metadata.get(\"supported_transports\", []),\n }\n grouped_results[\"servers\"].append(result_entry)\n\n # Add matching tools to top-level tools array\n original_tools = doc.get(\"tools\", [])\n tool_schema_map = {\n t.get(\"name\", \"\"): t.get(\"inputSchema\", {}) for t in original_tools\n }\n server_path = doc.get(\"path\", \"\")\n server_name = doc.get(\"name\", \"\")\n for tool in matching_tools:\n if tool_count >= tool_limit:\n break\n tool_name = tool.get(\"tool_name\", \"\")\n grouped_results[\"tools\"].append(\n {\n \"entity_type\": \"tool\",\n \"server_path\": server_path,\n \"server_name\": server_name,\n \"tool_name\": tool_name,\n \"description\": tool.get(\"description\", \"\"),\n \"inputSchema\": tool_schema_map.get(tool_name, {}),\n \"relevance_score\": tool.get(\"relevance_score\", relevance_score),\n \"match_context\": tool.get(\"match_context\", \"\"),\n }\n )\n tool_count += 1\n\n elif entity_type == \"a2a_agent\":\n metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"a2a_agent\",\n \"path\": doc.get(\"path\"),\n \"agent_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"skills\": metadata.get(\"skills\", []),\n \"visibility\": metadata.get(\"visibility\", \"public\"),\n \"trust_level\": metadata.get(\"trust_level\"),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"agent_card\": metadata.get(\"agent_card\", {}),\n }\n grouped_results[\"agents\"].append(result_entry)\n\n elif entity_type == \"mcp_tool\":\n result_entry = {\n \"entity_type\": \"mcp_tool\",\n \"path\": doc.get(\"path\"),\n \"tool_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"inputSchema\": doc.get(\"inputSchema\", {}),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n }\n grouped_results[\"tools\"].append(result_entry)\n\n elif entity_type == \"skill\":\n metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"skill\",\n \"path\": doc.get(\"path\"),\n \"skill_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"skill_md_url\": metadata.get(\"skill_md_url\"),\n \"version\": metadata.get(\"version\"),\n \"author\": metadata.get(\"author\"),\n \"visibility\": doc.get(\"visibility\", \"public\"),\n \"owner\": doc.get(\"owner\"),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"status\": doc.get(\"status\", \"active\"),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n }\n grouped_results[\"skills\"].append(result_entry)\n\n elif entity_type == \"virtual_server\":\n metadata = doc.get(\"metadata\", {})\n matching_tools = doc.get(\"matching_tools\", [])\n result_entry = {\n \"entity_type\": \"virtual_server\",\n \"path\": doc.get(\"path\"),\n \"server_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"num_tools\": metadata.get(\"num_tools\", 0),\n \"backend_count\": metadata.get(\"backend_count\", 0),\n \"backend_paths\": metadata.get(\"backend_paths\", []),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"matching_tools\": matching_tools,\n }\n grouped_results[\"virtual_servers\"].append(result_entry)\n\n return grouped_results\n\n async def search(\n self,\n query: str,\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Perform hybrid search (text + vector).\n\n Note: DocumentDB vector search returns results sorted by similarity\n but does NOT support $meta operators for score retrieval.\n We apply text-based boosting as a secondary ranking factor.\n \"\"\"\n collection = await self._get_collection()\n\n try:\n # Try to get embedding; fall back to lexical-only search if unavailable\n query_embedding = None\n if not self._embedding_unavailable:\n try:\n model = await self._get_embedding_model()\n query_embedding = model.encode([query])[0].tolist()\n except Exception as embed_error:\n logger.warning(\n \"Embedding model unavailable, falling back to lexical-only search: %s\",\n embed_error,\n )\n self._embedding_unavailable = True\n\n if query_embedding is None:\n return await self._lexical_only_search(\n query,\n entity_types,\n max_results,\n include_draft=include_draft,\n include_deprecated=include_deprecated,\n include_disabled=include_disabled,\n )\n\n # DocumentDB vector search returns results sorted by similarity\n # We get more results than needed to allow for text-based re-ranking\n ef_search = settings.vector_search_ef_search\n k_value = max(max_results * 3, 50) # At least 50 to avoid missing docs\n pipeline = [\n {\n \"$search\": {\n \"vectorSearch\": {\n \"vector\": query_embedding,\n \"path\": \"embedding\",\n \"similarity\": \"cosine\",\n \"k\": k_value,\n \"efSearch\": ef_search,\n }\n }\n }\n ]\n logger.info(\n \"Vector search pipeline: k=%d, efSearch=%d\",\n k_value,\n ef_search,\n )\n\n # Apply entity type filter if specified\n if entity_types:\n pipeline.append({\"$match\": {\"entity_type\": {\"$in\": entity_types}}})\n\n # Apply lifecycle status and enabled filter\n status_filter = _build_status_filter(\n include_draft=include_draft,\n include_deprecated=include_deprecated,\n include_disabled=include_disabled,\n )\n if status_filter:\n pipeline.append({\"$match\": status_filter})\n\n # Tokenize query and create regex pattern for matching any token\n query_tokens = _tokenize_query(query)\n # Create regex that matches any token (e.g., \"current|time|timezone\")\n # Escape special regex characters in tokens for safety\n escaped_tokens = [re.escape(token) for token in query_tokens]\n token_regex = \"|\".join(escaped_tokens) if escaped_tokens else query\n logger.info(\n \"Hybrid search tokens for '%s': %s (regex: %s)\",\n query,\n query_tokens,\n token_regex,\n )\n\n # NOTE: DocumentDB does not support $unionWith, so we run a separate\n # keyword query and merge results in Python code after the main pipeline.\n # Reuse shared helper for consistent matching across all fields\n keyword_match_filter = _build_keyword_match_filter(\n token_regex=token_regex,\n entity_types=entity_types,\n )\n\n # Add text-based scoring for re-ranking using shared helper\n # Scores: path (+5.0), name (+3.0), description (+2.0),\n # tags (+1.5), tools (+1.0 per match)\n text_boost_stage = _build_text_boost_stage(token_regex)\n pipeline.append(text_boost_stage)\n\n # Sort by text boost (descending), keeping vector search order as secondary\n pipeline.append({\"$sort\": {\"text_boost\": -1}})\n\n # Fetch more candidates than max_results to allow for global ranking.\n # The _distribute_results() function will pick the top max_results.\n candidate_limit = max(max_results * 3, 50)\n pipeline.append({\"$limit\": candidate_limit})\n\n cursor = collection.aggregate(pipeline)\n results = await cursor.to_list(length=candidate_limit)\n\n # Log vector search results for diagnosis\n logger.info(\n \"Vector search for '%s' returned %d documents (k=%d, efSearch=%d)\",\n query,\n len(results),\n k_value,\n ef_search,\n )\n for i, doc in enumerate(results):\n logger.info(\n \" Vector result [%d]: name='%s', type=%s, text_boost=%.1f, path='%s'\",\n i,\n doc.get(\"name\"),\n doc.get(\"entity_type\"),\n doc.get(\"text_boost\", 0.0),\n doc.get(\"path\"),\n )\n\n # DocumentDB doesn't support $unionWith, so we run a separate keyword\n # query to find documents that match by name/path/description/tags/tools\n # but may not appear in vector search results\n keyword_cursor = collection.find(keyword_match_filter).limit(5)\n keyword_results = await keyword_cursor.to_list(length=5)\n\n logger.info(\n \"Keyword search for '%s' found %d candidates\",\n query,\n len(keyword_results),\n )\n for i, kw_doc in enumerate(keyword_results):\n already_in = kw_doc.get(\"_id\") in {doc.get(\"_id\") for doc in results}\n logger.info(\n \" Keyword candidate [%d]: name='%s', type=%s, path='%s', already_in_vector=%s\",\n i,\n kw_doc.get(\"name\"),\n kw_doc.get(\"entity_type\"),\n kw_doc.get(\"path\"),\n already_in,\n )\n\n # Merge keyword results with vector results, avoiding duplicates\n # Calculate text_boost and matching_tools for keyword results since they\n # didn't go through the aggregation pipeline\n result_ids = {doc.get(\"_id\") for doc in results}\n keyword_added_count = 0\n for kw_doc in keyword_results:\n if kw_doc.get(\"_id\") not in result_ids:\n # Calculate text_boost for keyword-matched docs\n # Use same weights as pipeline: path(+5), name(+3),\n # description(+2), tags(+1.5), tools(+1 each)\n kw_text_boost = 0.0\n doc_name = (kw_doc.get(\"name\") or \"\").lower()\n doc_path = (kw_doc.get(\"path\") or \"\").lower()\n doc_desc = (kw_doc.get(\"description\") or \"\").lower()\n doc_tags = [(t or \"\").lower() for t in kw_doc.get(\"tags\", [])]\n\n for token in query_tokens:\n token_lower = token.lower()\n if token_lower in doc_path:\n kw_text_boost += 5.0 # Path match\n if token_lower in doc_name:\n kw_text_boost += 3.0 # Name match\n if token_lower in doc_desc:\n kw_text_boost += 2.0 # Description match\n if any(token_lower in tag for tag in doc_tags):\n kw_text_boost += 1.5 # Tags match\n\n # Calculate matching_tools for keyword-matched docs\n tools = kw_doc.get(\"tools\", [])\n matching_tools = []\n for tool in tools:\n tool_name = (tool.get(\"name\") or \"\").lower()\n tool_desc = (tool.get(\"description\") or \"\").lower()\n # Check if any token matches tool name or description\n tool_matches = any(\n token.lower() in tool_name or token.lower() in tool_desc\n for token in query_tokens\n )\n if tool_matches:\n kw_text_boost += 1.0 # Tool match\n matching_tools.append(\n {\n \"tool_name\": tool.get(\"name\", \"\"),\n \"description\": tool.get(\"description\", \"\"),\n \"relevance_score\": 1.0,\n \"match_context\": tool.get(\"description\")\n or f\"Tool: {tool.get('name', '')}\",\n }\n )\n\n kw_doc[\"text_boost\"] = kw_text_boost\n kw_doc[\"matching_tools\"] = matching_tools\n\n results.append(kw_doc)\n result_ids.add(kw_doc.get(\"_id\"))\n keyword_added_count += 1\n logger.info(\n \"Keyword merge added '%s' (type=%s, text_boost=%.1f)\",\n kw_doc.get(\"name\"),\n kw_doc.get(\"entity_type\"),\n kw_text_boost,\n )\n\n logger.info(\n \"After keyword merge: %d total results (%d added from keyword search)\",\n len(results),\n keyword_added_count,\n )\n\n # Calculate hybrid scores for ALL results before grouping\n # This ensures we log every document's score for diagnosis\n scored_results = []\n for doc in results:\n entity_type = doc.get(\"entity_type\")\n doc_embedding = doc.get(\"embedding\", [])\n vector_score = self._calculate_cosine_similarity(query_embedding, doc_embedding)\n text_boost = doc.get(\"text_boost\", 0.0)\n\n # Normalize vector_score from [-1, 1] to [0, 1]\n normalized_vector_score = (vector_score + 1.0) / 2.0\n\n # Text boost multiplier: 0.1 gives significant weight to keyword matches\n # Name match (3.0) adds +0.30, Description (2.0) adds +0.20\n text_boost_contribution = text_boost * 0.1\n relevance_score = normalized_vector_score + text_boost_contribution\n relevance_score = max(0.0, min(1.0, relevance_score))\n\n logger.info(\n \"Score for '%s' (type=%s): vector=%.4f, \"\n \"normalized_vector=%.4f, text_boost=%.1f, \"\n \"boost_contrib=%.4f, final=%.4f\",\n doc.get(\"name\"),\n entity_type,\n vector_score,\n normalized_vector_score,\n text_boost,\n text_boost_contribution,\n relevance_score,\n )\n\n scored_results.append((doc, relevance_score))\n\n # Sort by hybrid score descending\n scored_results.sort(key=lambda x: x[1], reverse=True)\n\n # Distribute results using global ranking with soft caps\n selected_results = _distribute_results(scored_results, max_results)\n\n # Group selected results by entity type for the response\n grouped_results = {\n \"servers\": [],\n \"tools\": [],\n \"agents\": [],\n \"skills\": [],\n \"virtual_servers\": [],\n }\n tool_count = 0\n tool_limit = _tool_extraction_limit(max_results)\n\n for doc, relevance_score in selected_results:\n entity_type = doc.get(\"entity_type\")\n\n if entity_type == \"mcp_server\":\n matching_tools = doc.get(\"matching_tools\", [])\n server_metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"mcp_server\",\n \"path\": doc.get(\"path\"),\n \"server_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"num_tools\": server_metadata.get(\"num_tools\", 0),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"matching_tools\": matching_tools,\n \"sync_metadata\": server_metadata.get(\"sync_metadata\"),\n \"proxy_pass_url\": server_metadata.get(\"proxy_pass_url\"),\n \"mcp_endpoint\": server_metadata.get(\"mcp_endpoint\"),\n \"sse_endpoint\": server_metadata.get(\"sse_endpoint\"),\n \"supported_transports\": server_metadata.get(\"supported_transports\", []),\n }\n grouped_results[\"servers\"].append(result_entry)\n\n # Also add matching tools to the top-level tools array\n original_tools = doc.get(\"tools\", [])\n tool_schema_map = {\n t.get(\"name\", \"\"): t.get(\"inputSchema\", {}) for t in original_tools\n }\n\n server_path = doc.get(\"path\", \"\")\n server_name = doc.get(\"name\", \"\")\n for tool in matching_tools:\n if tool_count >= tool_limit:\n break\n tool_name = tool.get(\"tool_name\", \"\")\n grouped_results[\"tools\"].append(\n {\n \"entity_type\": \"tool\",\n \"server_path\": server_path,\n \"server_name\": server_name,\n \"tool_name\": tool_name,\n \"description\": tool.get(\"description\", \"\"),\n \"inputSchema\": tool_schema_map.get(tool_name, {}),\n \"relevance_score\": tool.get(\"relevance_score\", relevance_score),\n \"match_context\": tool.get(\"match_context\", \"\"),\n }\n )\n tool_count += 1\n\n elif entity_type == \"a2a_agent\":\n metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"a2a_agent\",\n \"path\": doc.get(\"path\"),\n \"agent_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"skills\": metadata.get(\"skills\", []),\n \"visibility\": metadata.get(\"visibility\", \"public\"),\n \"trust_level\": metadata.get(\"trust_level\"),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"agent_card\": metadata.get(\"agent_card\", {}),\n \"sync_metadata\": metadata.get(\"sync_metadata\"),\n }\n grouped_results[\"agents\"].append(result_entry)\n\n elif entity_type == \"mcp_tool\":\n result_entry = {\n \"entity_type\": \"mcp_tool\",\n \"path\": doc.get(\"path\"),\n \"tool_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"inputSchema\": doc.get(\"inputSchema\", {}),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n }\n grouped_results[\"tools\"].append(result_entry)\n\n elif entity_type == \"skill\":\n metadata = doc.get(\"metadata\", {})\n result_entry = {\n \"entity_type\": \"skill\",\n \"path\": doc.get(\"path\"),\n \"skill_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"skill_md_url\": metadata.get(\"skill_md_url\"),\n \"version\": metadata.get(\"version\"),\n \"author\": metadata.get(\"author\"),\n \"visibility\": doc.get(\"visibility\", \"public\"),\n \"owner\": doc.get(\"owner\"),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"status\": doc.get(\"status\", \"active\"),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n }\n grouped_results[\"skills\"].append(result_entry)\n\n elif entity_type == \"virtual_server\":\n metadata = doc.get(\"metadata\", {})\n matching_tools = doc.get(\"matching_tools\", [])\n result_entry = {\n \"entity_type\": \"virtual_server\",\n \"path\": doc.get(\"path\"),\n \"server_name\": doc.get(\"name\"),\n \"description\": doc.get(\"description\"),\n \"tags\": doc.get(\"tags\", []),\n \"num_tools\": metadata.get(\"num_tools\", 0),\n \"backend_count\": metadata.get(\"backend_count\", 0),\n \"backend_paths\": metadata.get(\"backend_paths\", []),\n \"is_enabled\": doc.get(\"is_enabled\", False),\n \"relevance_score\": relevance_score,\n \"match_context\": doc.get(\"description\"),\n \"matching_tools\": matching_tools,\n }\n grouped_results[\"virtual_servers\"].append(result_entry)\n\n # Sort each group by relevance_score (descending) to ensure highest matches\n # appear first. This is needed because the DB sorts by text_boost only,\n # but relevance_score combines both vector similarity and text boost.\n grouped_results[\"servers\"].sort(key=lambda x: x.get(\"relevance_score\", 0), reverse=True)\n grouped_results[\"tools\"].sort(key=lambda x: x.get(\"relevance_score\", 0), reverse=True)\n grouped_results[\"agents\"].sort(key=lambda x: x.get(\"relevance_score\", 0), reverse=True)\n grouped_results[\"skills\"].sort(key=lambda x: x.get(\"relevance_score\", 0), reverse=True)\n grouped_results[\"virtual_servers\"].sort(\n key=lambda x: x.get(\"relevance_score\", 0), reverse=True\n )\n\n logger.info(\n \"Hybrid search for '%s' returned \"\n \"%d servers, %d tools, %d agents, %d skills, \"\n \"%d virtual_servers (max_results=%d)\",\n query,\n len(grouped_results[\"servers\"]),\n len(grouped_results[\"tools\"]),\n len(grouped_results[\"agents\"]),\n len(grouped_results[\"skills\"]),\n len(grouped_results[\"virtual_servers\"]),\n max_results,\n )\n\n return grouped_results\n\n except Exception as e:\n # Check if this is MongoDB CE without vector search support\n from pymongo.errors import OperationFailure\n\n if isinstance(e, OperationFailure) and (e.code == 31082 or \"vectorSearch\" in str(e)):\n # MongoDB CE doesn't support $vectorSearch - fall back to client-side search\n logger.warning(\n \"Vector search not supported (MongoDB CE detected). \"\n \"Falling back to client-side cosine similarity search.\"\n )\n return await self._client_side_search(\n query,\n query_embedding,\n entity_types,\n max_results,\n include_draft=include_draft,\n include_deprecated=include_deprecated,\n include_disabled=include_disabled,\n )\n elif \"vectorSearch\" in str(e) or \"$search\" in str(e):\n # General vector search not supported - fall back to client-side search\n logger.warning(\n \"Vector search not supported by this MongoDB instance. \"\n \"Falling back to client-side cosine similarity search.\"\n )\n return await self._client_side_search(\n query,\n query_embedding,\n entity_types,\n max_results,\n include_draft=include_draft,\n include_deprecated=include_deprecated,\n include_disabled=include_disabled,\n )\n\n logger.error(f\"Failed to perform hybrid search: {e}\", exc_info=True)\n return {\"servers\": [], \"tools\": [], \"agents\": [], \"skills\": []}\n" }, { "path": "registry/repositories/documentdb/security_scan_repository.py", "content": "\"\"\"DocumentDB-based repository for security scan results storage.\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom ..interfaces import SecurityScanRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBSecurityScanRepository(SecurityScanRepositoryBase):\n \"\"\"DocumentDB implementation of security scan repository.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"mcp_security_scans\")\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def load_all(self) -> None:\n \"\"\"Load all security scan results from DocumentDB.\"\"\"\n logger.info(f\"Loading security scans from DocumentDB collection: {self._collection_name}\")\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({})\n logger.info(f\"Loaded {count} security scan results from DocumentDB\")\n except Exception as e:\n logger.error(f\"Error loading security scans from DocumentDB: {e}\", exc_info=True)\n\n async def get(\n self,\n server_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest security scan result for a server.\"\"\"\n return await self.get_latest(server_path)\n\n async def list_all(self) -> list[dict[str, Any]]:\n \"\"\"List all security scan results.\"\"\"\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({}).sort(\"scan_timestamp\", -1)\n scans = []\n async for doc in cursor:\n doc.pop(\"_id\", None)\n scans.append(doc)\n return scans\n except Exception as e:\n logger.error(f\"Error listing security scans from DocumentDB: {e}\", exc_info=True)\n return []\n\n async def create(\n self,\n scan_result: dict[str, Any],\n ) -> bool:\n \"\"\"Create/update a security scan result.\"\"\"\n try:\n path = scan_result.get(\"server_path\") or scan_result.get(\"agent_path\")\n if not path:\n logger.error(\"Scan result must contain either 'server_path' or 'agent_path' field\")\n return False\n\n collection = await self._get_collection()\n\n if \"agent_path\" in scan_result and \"server_path\" not in scan_result:\n scan_result[\"server_path\"] = scan_result[\"agent_path\"]\n\n if \"scan_timestamp\" not in scan_result:\n scan_result[\"scan_timestamp\"] = datetime.utcnow().isoformat()\n\n if \"vulnerabilities\" in scan_result and isinstance(\n scan_result[\"vulnerabilities\"], list\n ):\n vuln_counts = {\"critical\": 0, \"high\": 0, \"medium\": 0, \"low\": 0}\n for vuln in scan_result[\"vulnerabilities\"]:\n severity = vuln.get(\"severity\", \"\").lower()\n if severity in vuln_counts:\n vuln_counts[severity] += 1\n\n scan_result[\"total_vulnerabilities\"] = len(scan_result[\"vulnerabilities\"])\n scan_result[\"critical_count\"] = vuln_counts[\"critical\"]\n scan_result[\"high_count\"] = vuln_counts[\"high\"]\n scan_result[\"medium_count\"] = vuln_counts[\"medium\"]\n scan_result[\"low_count\"] = vuln_counts[\"low\"]\n\n await collection.insert_one(scan_result)\n\n logger.info(f\"Indexed security scan for {path} in DocumentDB\")\n return True\n except Exception as e:\n logger.error(f\"Failed to index security scan in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def get_latest(\n self,\n server_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest scan result for a server.\n\n Normalizes paths to match both with and without trailing slashes.\n \"\"\"\n try:\n collection = await self._get_collection()\n\n # Normalize path - try both with and without trailing slash\n path_without_slash = server_path.rstrip(\"/\")\n path_with_slash = path_without_slash + \"/\"\n\n scan_doc = await collection.find_one(\n {\n \"$or\": [\n {\"server_path\": path_without_slash},\n {\"server_path\": path_with_slash},\n ]\n },\n sort=[(\"scan_timestamp\", -1)],\n )\n\n if scan_doc:\n scan_doc.pop(\"_id\", None)\n return scan_doc\n\n return None\n except Exception as e:\n logger.error(f\"Failed to get latest scan from DocumentDB: {e}\", exc_info=True)\n return None\n\n async def query_by_status(\n self,\n status: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Query scan results by status.\"\"\"\n try:\n collection = await self._get_collection()\n\n cursor = collection.find({\"scan_status\": status}).sort(\"scan_timestamp\", -1)\n\n scans = []\n async for doc in cursor:\n doc.pop(\"_id\", None)\n scans.append(doc)\n\n return scans\n except Exception as e:\n logger.error(f\"Failed to query scans by status from DocumentDB: {e}\", exc_info=True)\n return []\n" }, { "path": "registry/repositories/documentdb/server_repository.py", "content": "\"\"\"DocumentDB-based repository for MCP server storage.\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\nfrom pymongo.errors import DuplicateKeyError\n\nfrom ..interfaces import ServerRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBServerRepository(ServerRepositoryBase):\n \"\"\"DocumentDB implementation of server repository.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"mcp_servers\")\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def load_all(self) -> None:\n \"\"\"Load all servers from DocumentDB.\"\"\"\n logger.info(f\"Loading servers from DocumentDB collection: {self._collection_name}\")\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({})\n logger.info(f\"Loaded {count} servers from DocumentDB\")\n except Exception as e:\n logger.error(f\"Error loading servers from DocumentDB: {e}\", exc_info=True)\n\n async def get(\n self,\n path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get server by path.\n\n Normalizes paths to match both with and without trailing slashes.\n \"\"\"\n logger.debug(\n f\"DocumentDB READ: Getting server with path='{path}' from collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n try:\n server_info = await collection.find_one({\"_id\": path})\n\n # If not found, try alternate path (with/without trailing slash)\n if not server_info:\n if path.endswith(\"/\"):\n alternate_path = path.rstrip(\"/\")\n else:\n alternate_path = path + \"/\"\n\n logger.debug(f\"DocumentDB READ: Trying alternate path '{alternate_path}'\")\n server_info = await collection.find_one({\"_id\": alternate_path})\n\n if server_info:\n server_info[\"path\"] = server_info.pop(\"_id\")\n logger.debug(\n f\"DocumentDB READ: Found server '{server_info.get('server_name', 'unknown')}' at '{path}'\"\n )\n else:\n logger.debug(f\"DocumentDB READ: Server not found at '{path}'\")\n return server_info\n except Exception as e:\n logger.error(f\"Error getting server '{path}' from DocumentDB: {e}\", exc_info=True)\n return None\n\n async def list_all(self) -> dict[str, dict[str, Any]]:\n \"\"\"List all servers.\"\"\"\n logger.debug(\n f\"DocumentDB READ: Listing all servers from collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({})\n servers = {}\n async for doc in cursor:\n path = doc.pop(\"_id\")\n doc[\"path\"] = path\n servers[path] = doc\n logger.info(\n f\"DocumentDB READ: Retrieved {len(servers)} servers from collection '{self._collection_name}'\"\n )\n return servers\n except Exception as e:\n logger.error(f\"Error listing servers from DocumentDB: {e}\", exc_info=True)\n return {}\n\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"List servers with DB-level skip/limit pagination.\n\n Args:\n skip: Number of documents to skip.\n limit: Maximum number of documents to return.\n\n Returns:\n Dictionary mapping server path to server info for the requested page.\n \"\"\"\n logger.debug(\n f\"DocumentDB READ: Listing paginated servers (skip={skip}, limit={limit}) \"\n f\"from collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({}).sort(\"_id\", 1).skip(skip).limit(limit)\n servers = {}\n async for doc in cursor:\n path = doc.pop(\"_id\")\n doc[\"path\"] = path\n servers[path] = doc\n logger.info(\n f\"DocumentDB READ: Retrieved {len(servers)} servers (skip={skip}, limit={limit}) \"\n f\"from collection '{self._collection_name}'\"\n )\n return servers\n except Exception as e:\n logger.error(f\"Error listing paginated servers from DocumentDB: {e}\", exc_info=True)\n return {}\n\n async def list_by_source(\n self,\n source: str,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"List all servers from a specific federation source.\n\n Args:\n source: Federation source identifier (e.g., \"anthropic\")\n\n Returns:\n Dictionary mapping server path to server info\n \"\"\"\n logger.debug(\n f\"DocumentDB READ: Listing servers with source='{source}' from collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({\"source\": source})\n servers = {}\n async for doc in cursor:\n path = doc.pop(\"_id\")\n doc[\"path\"] = path\n servers[path] = doc\n logger.info(\n f\"DocumentDB READ: Retrieved {len(servers)} servers with source='{source}' from collection '{self._collection_name}'\"\n )\n return servers\n except Exception as e:\n logger.error(\n f\"Error listing servers by source '{source}' from DocumentDB: {e}\", exc_info=True\n )\n return {}\n\n async def create(\n self,\n server_info: dict[str, Any],\n ) -> bool:\n \"\"\"Create a new server.\"\"\"\n path = server_info[\"path\"]\n logger.debug(\n f\"DocumentDB WRITE: Creating server '{server_info.get('server_name', 'unknown')}' at '{path}' in collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n server_info[\"registered_at\"] = datetime.utcnow().isoformat()\n server_info[\"updated_at\"] = datetime.utcnow().isoformat()\n server_info.setdefault(\"is_enabled\", False)\n\n try:\n doc = {**server_info}\n doc[\"_id\"] = path\n doc.pop(\"path\", None)\n\n await collection.insert_one(doc)\n logger.info(\n f\"DocumentDB WRITE: Created server '{server_info['server_name']}' at '{path}'\"\n )\n return True\n except DuplicateKeyError:\n logger.error(f\"Server path '{path}' already exists in DocumentDB\")\n return False\n except Exception as e:\n logger.error(f\"Failed to create server in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def update(\n self,\n path: str,\n server_info: dict[str, Any],\n ) -> bool:\n \"\"\"Update an existing server.\"\"\"\n logger.debug(\n f\"DocumentDB WRITE: Updating server at '{path}' in collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n server_info[\"updated_at\"] = datetime.utcnow().isoformat()\n\n try:\n doc = {**server_info}\n doc.pop(\"path\", None)\n\n result = await collection.update_one({\"_id\": path}, {\"$set\": doc})\n\n if result.matched_count == 0:\n logger.error(f\"Server at '{path}' not found in DocumentDB\")\n return False\n\n logger.info(\n f\"DocumentDB WRITE: Updated server '{server_info.get('server_name', 'unknown')}' at '{path}'\"\n )\n return True\n except Exception as e:\n logger.error(f\"Failed to update server in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a server.\"\"\"\n logger.debug(\n f\"DocumentDB DELETE: Deleting server at '{path}' from collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n try:\n server_doc = await collection.find_one({\"_id\": path})\n if not server_doc:\n logger.error(f\"Server at '{path}' not found in DocumentDB\")\n return False\n\n server_name = server_doc.get(\"server_name\", \"Unknown\")\n\n result = await collection.delete_one({\"_id\": path})\n\n if result.deleted_count == 0:\n logger.error(f\"Failed to delete server at '{path}'\")\n return False\n\n logger.info(f\"DocumentDB DELETE: Deleted server '{server_name}' from '{path}'\")\n return True\n except Exception as e:\n logger.error(f\"Failed to delete server from DocumentDB: {e}\", exc_info=True)\n return False\n\n async def delete_with_versions(\n self,\n path: str,\n ) -> int:\n \"\"\"Delete a server and all its version documents.\n\n Deletes the active document at `path` and any inactive version\n documents with IDs matching `{path}:{version}`.\n\n Args:\n path: Server base path (e.g., \"/context7\")\n\n Returns:\n Number of documents deleted (0 if none found)\n \"\"\"\n logger.debug(\n f\"DocumentDB DELETE: Deleting server at '{path}' and all version documents \"\n f\"from collection '{self._collection_name}'\"\n )\n collection = await self._get_collection()\n\n try:\n # Match the active document (exact path) and version documents (path:version)\n filter_query = {\n \"$or\": [\n {\"_id\": path},\n {\"_id\": {\"$regex\": f\"^{path}:\"}},\n ]\n }\n\n result = await collection.delete_many(filter_query)\n deleted_count = result.deleted_count\n\n if deleted_count == 0:\n logger.error(f\"No documents found for server at '{path}'\")\n else:\n logger.info(\n f\"DocumentDB DELETE: Deleted {deleted_count} document(s) \"\n f\"for server at '{path}' (active + version documents)\"\n )\n\n return deleted_count\n except Exception as e:\n logger.error(\n f\"Failed to delete server and versions from DocumentDB: {e}\",\n exc_info=True,\n )\n return 0\n\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get server enabled/disabled state.\"\"\"\n server_info = await self.get(path)\n if server_info:\n return server_info.get(\"is_enabled\", False)\n return False\n\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set server enabled/disabled state.\"\"\"\n collection = await self._get_collection()\n\n try:\n server_doc = await collection.find_one({\"_id\": path})\n if not server_doc:\n logger.error(f\"Server at '{path}' not found in DocumentDB\")\n return False\n\n server_name = server_doc.get(\"server_name\", path)\n\n result = await collection.update_one(\n {\"_id\": path},\n {\"$set\": {\"is_enabled\": enabled, \"updated_at\": datetime.utcnow().isoformat()}},\n )\n\n if result.matched_count == 0:\n logger.error(f\"Server at '{path}' not found\")\n return False\n\n logger.info(f\"Toggled '{server_name}' ({path}) to {enabled}\")\n return True\n except Exception as e:\n logger.error(f\"Failed to update server state in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def count(self) -> int:\n \"\"\"Get total count of servers.\n\n Returns:\n Total number of servers in the repository.\n \"\"\"\n logger.debug(f\"DocumentDB COUNT: Counting servers in collection '{self._collection_name}'\")\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({})\n logger.debug(f\"DocumentDB COUNT: Found {count} servers\")\n return count\n except Exception as e:\n logger.error(f\"Error counting servers in DocumentDB: {e}\", exc_info=True)\n return 0\n\n async def update_field(\n self,\n path: str,\n field: str,\n value: Any,\n ) -> bool:\n \"\"\"Update a single field on a document.\"\"\"\n collection = await self._get_collection()\n\n if value is None:\n result = await collection.update_one(\n {\"_id\": path},\n {\"$unset\": {field: \"\"}},\n )\n else:\n result = await collection.update_one(\n {\"_id\": path},\n {\"$set\": {field: value}},\n )\n\n return result.modified_count > 0\n\n async def find_with_filter(\n self,\n filter_dict: dict[str, Any],\n ) -> dict[str, dict]:\n \"\"\"Find documents matching a MongoDB-style filter.\"\"\"\n collection = await self._get_collection()\n cursor = collection.find(filter_dict)\n results = {}\n async for doc in cursor:\n doc_id = doc.pop(\"_id\", None)\n if doc_id:\n results[doc_id] = doc\n return results\n" }, { "path": "registry/repositories/documentdb/skill_repository.py", "content": "\"\"\"\nDocumentDB (MongoDB) implementation for skill repository.\n\nImplements all recommendations:\n- Index creation on initialization\n- Batch operations for federation sync\n- Database-level filtering\n- Duplicate key handling\n\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import (\n Any,\n)\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\nfrom pymongo.errors import DuplicateKeyError\n\nfrom ...exceptions import (\n SkillAlreadyExistsError,\n SkillServiceError,\n)\nfrom ...schemas.skill_models import SkillCard\nfrom ..interfaces import SkillRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _skill_to_document(\n skill: SkillCard,\n) -> dict[str, Any]:\n \"\"\"Convert SkillCard to MongoDB document.\"\"\"\n doc = skill.model_dump(mode=\"json\")\n doc[\"_id\"] = skill.path\n return doc\n\n\ndef _normalize_metadata(\n metadata: Any,\n) -> dict[str, Any] | None:\n \"\"\"Normalize metadata to SkillMetadata-compatible dict.\n\n Handles legacy flat dicts (e.g., {category: 'x'}) by wrapping\n them into the SkillMetadata structure with an 'extra' field.\n \"\"\"\n if not metadata or not isinstance(metadata, dict):\n return None\n\n # Already in SkillMetadata format (has 'extra' key)\n if \"extra\" in metadata:\n return metadata\n\n # Legacy flat dict — wrap into SkillMetadata structure\n return {\n \"author\": metadata.pop(\"author\", None),\n \"version\": metadata.pop(\"version\", None),\n \"extra\": metadata,\n }\n\n\ndef _document_to_skill(\n doc: dict[str, Any],\n) -> SkillCard:\n \"\"\"Convert MongoDB document to SkillCard.\"\"\"\n doc_copy = dict(doc)\n doc_copy.pop(\"_id\", None)\n doc_copy[\"metadata\"] = _normalize_metadata(doc_copy.get(\"metadata\"))\n return SkillCard(**doc_copy)\n\n\nclass DocumentDBSkillRepository(SkillRepositoryBase):\n \"\"\"MongoDB implementation for skill storage.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"agent_skills\")\n self._indexes_created = False\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def ensure_indexes(self) -> None:\n \"\"\"Create required indexes if not present.\"\"\"\n if self._indexes_created:\n return\n\n collection = await self._get_collection()\n\n try:\n # Name index (unique)\n await collection.create_index(\"name\", unique=True)\n\n # Tags index for filtering\n await collection.create_index(\"tags\")\n\n # Visibility index for access control\n await collection.create_index(\"visibility\")\n\n # Registry name for federation queries\n await collection.create_index(\"registry_name\")\n\n # Owner for private visibility\n await collection.create_index(\"owner\")\n\n # Compound index for common query patterns\n await collection.create_index(\n [(\"visibility\", 1), (\"is_enabled\", 1), (\"registry_name\", 1)]\n )\n\n self._indexes_created = True\n logger.info(f\"Created indexes for {self._collection_name} collection\")\n except Exception as e:\n logger.warning(f\"Could not create indexes: {e}\")\n\n async def get(\n self,\n path: str,\n ) -> SkillCard | None:\n \"\"\"Get a skill by path.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n doc = await collection.find_one({\"_id\": path})\n if doc:\n return _document_to_skill(doc)\n return None\n\n async def list_all(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> list[SkillCard]:\n \"\"\"List all skills with pagination.\n\n Args:\n skip: Number of records to skip (offset)\n limit: Maximum number of records to return\n\n Returns:\n List of SkillCard objects\n \"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n skills = []\n cursor = collection.find({}).skip(skip).limit(limit)\n async for doc in cursor:\n try:\n skills.append(_document_to_skill(doc))\n except Exception as e:\n logger.error(f\"Failed to parse skill document: {e}\")\n return skills\n\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> list[SkillCard]:\n \"\"\"List skills with DB-level pagination and deterministic ordering.\n\n Args:\n skip: Number of documents to skip.\n limit: Maximum number of documents to return.\n\n Returns:\n List of SkillCard objects for the requested page.\n \"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n skills = []\n cursor = collection.find({}).sort(\"_id\", 1).skip(skip).limit(limit)\n async for doc in cursor:\n try:\n skills.append(_document_to_skill(doc))\n except Exception as e:\n logger.error(f\"Failed to parse skill document: {e}\")\n return skills\n\n async def list_filtered(\n self,\n include_disabled: bool = False,\n tag: str | None = None,\n visibility: str | None = None,\n registry_name: str | None = None,\n ) -> list[SkillCard]:\n \"\"\"List skills with database-level filtering.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n\n query: dict[str, Any] = {}\n\n if not include_disabled:\n query[\"is_enabled\"] = True\n\n if tag:\n query[\"tags\"] = tag\n\n if visibility:\n query[\"visibility\"] = visibility\n\n if registry_name:\n query[\"registry_name\"] = registry_name\n\n skills = []\n cursor = collection.find(query)\n async for doc in cursor:\n try:\n skills.append(_document_to_skill(doc))\n except Exception as e:\n logger.error(f\"Failed to parse skill document: {e}\")\n return skills\n\n async def create(\n self,\n skill: SkillCard,\n ) -> SkillCard:\n \"\"\"Create a new skill.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n doc = _skill_to_document(skill)\n\n try:\n await collection.insert_one(doc)\n logger.info(f\"Created skill: {skill.path}\")\n return skill\n except DuplicateKeyError:\n logger.error(f\"Skill already exists: {skill.path}\")\n raise SkillAlreadyExistsError(skill.name)\n except Exception as e:\n logger.error(f\"Failed to create skill {skill.path}: {e}\")\n raise SkillServiceError(f\"Failed to create skill: {e}\") from e\n\n async def update(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> SkillCard | None:\n \"\"\"Update a skill.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n updates[\"updated_at\"] = datetime.utcnow().isoformat()\n\n try:\n result = await collection.find_one_and_update(\n {\"_id\": path}, {\"$set\": updates}, return_document=True\n )\n\n if result:\n logger.info(f\"Updated skill: {path}\")\n return _document_to_skill(result)\n return None\n except Exception as e:\n logger.error(f\"Failed to update skill {path}: {e}\")\n raise SkillServiceError(f\"Failed to update skill: {e}\") from e\n\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a skill.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n result = await collection.delete_one({\"_id\": path})\n if result.deleted_count > 0:\n logger.info(f\"Deleted skill: {path}\")\n return True\n return False\n\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get skill enabled state.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n doc = await collection.find_one({\"_id\": path}, {\"is_enabled\": 1})\n return doc.get(\"is_enabled\", False) if doc else False\n\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set skill enabled state.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n result = await collection.update_one(\n {\"_id\": path},\n {\"$set\": {\"is_enabled\": enabled, \"updated_at\": datetime.utcnow().isoformat()}},\n )\n if result.modified_count > 0:\n logger.info(f\"Set skill {path} enabled={enabled}\")\n return True\n return False\n\n async def create_many(\n self,\n skills: list[SkillCard],\n ) -> list[SkillCard]:\n \"\"\"Create multiple skills in single operation.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n\n if not skills:\n return []\n\n docs = [_skill_to_document(s) for s in skills]\n\n try:\n await collection.insert_many(docs, ordered=False)\n logger.info(f\"Created {len(skills)} skills in batch\")\n return skills\n except Exception as e:\n logger.error(f\"Failed to create skills in batch: {e}\")\n raise SkillServiceError(f\"Batch create failed: {e}\") from e\n\n async def update_many(\n self,\n updates: dict[str, dict[str, Any]],\n ) -> int:\n \"\"\"Update multiple skills by path, return count.\"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n\n if not updates:\n return 0\n\n count = 0\n for path, update_data in updates.items():\n update_data[\"updated_at\"] = datetime.utcnow().isoformat()\n result = await collection.update_one({\"_id\": path}, {\"$set\": update_data}, upsert=True)\n if result.modified_count > 0 or result.upserted_id:\n count += 1\n\n logger.info(f\"Updated {count} skills in batch\")\n return count\n\n async def count(self) -> int:\n \"\"\"Get total count of skills.\n\n Returns:\n Total number of skills in the repository.\n \"\"\"\n await self.ensure_indexes()\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({})\n logger.debug(f\"DocumentDB COUNT: Found {count} skills\")\n return count\n except Exception as e:\n logger.error(f\"Error counting skills in DocumentDB: {e}\", exc_info=True)\n return 0\n" }, { "path": "registry/repositories/documentdb/skill_security_scan_repository.py", "content": "\"\"\"DocumentDB-based repository for skill security scan results storage.\"\"\"\n\nimport logging\nfrom datetime import datetime\nfrom typing import Any\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\n\nfrom ..interfaces import SkillSecurityScanRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\nlogger = logging.getLogger(__name__)\n\n\nclass DocumentDBSkillSecurityScanRepository(SkillSecurityScanRepositoryBase):\n \"\"\"DocumentDB implementation of skill security scan repository.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"mcp_skill_security_scans\")\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n return self._collection\n\n async def load_all(self) -> None:\n \"\"\"Load all skill security scan results from DocumentDB.\"\"\"\n logger.info(\n f\"Loading skill security scans from DocumentDB collection: {self._collection_name}\"\n )\n collection = await self._get_collection()\n\n try:\n count = await collection.count_documents({})\n logger.info(f\"Loaded {count} skill security scan results from DocumentDB\")\n except Exception as e:\n logger.error(f\"Error loading skill security scans from DocumentDB: {e}\", exc_info=True)\n\n async def get(\n self,\n skill_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest security scan result for a skill.\"\"\"\n return await self.get_latest(skill_path)\n\n async def list_all(self) -> list[dict[str, Any]]:\n \"\"\"List all skill security scan results.\"\"\"\n collection = await self._get_collection()\n\n try:\n cursor = collection.find({}).sort(\"scan_timestamp\", -1)\n scans = []\n async for doc in cursor:\n doc.pop(\"_id\", None)\n scans.append(doc)\n return scans\n except Exception as e:\n logger.error(f\"Error listing skill security scans from DocumentDB: {e}\", exc_info=True)\n return []\n\n async def create(\n self,\n scan_result: dict[str, Any],\n ) -> bool:\n \"\"\"Create/update a skill security scan result.\"\"\"\n try:\n skill_path = scan_result.get(\"skill_path\")\n if not skill_path:\n logger.error(\"Scan result must contain 'skill_path' field\")\n return False\n\n collection = await self._get_collection()\n\n if \"scan_timestamp\" not in scan_result:\n scan_result[\"scan_timestamp\"] = datetime.utcnow().isoformat()\n\n await collection.insert_one(scan_result)\n\n logger.info(f\"Indexed skill security scan for {skill_path} in DocumentDB\")\n return True\n except Exception as e:\n logger.error(f\"Failed to index skill security scan in DocumentDB: {e}\", exc_info=True)\n return False\n\n async def get_latest(\n self,\n skill_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest scan result for a skill.\"\"\"\n try:\n collection = await self._get_collection()\n\n scan_doc = await collection.find_one(\n {\"skill_path\": skill_path}, sort=[(\"scan_timestamp\", -1)]\n )\n\n if scan_doc:\n scan_doc.pop(\"_id\", None)\n return scan_doc\n\n return None\n except Exception as e:\n logger.error(f\"Failed to get latest skill scan from DocumentDB: {e}\", exc_info=True)\n return None\n\n async def query_by_status(\n self,\n status: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Query scan results by status.\"\"\"\n try:\n collection = await self._get_collection()\n\n cursor = collection.find({\"scan_status\": status}).sort(\"scan_timestamp\", -1)\n\n scans = []\n async for doc in cursor:\n doc.pop(\"_id\", None)\n scans.append(doc)\n\n return scans\n except Exception as e:\n logger.error(\n f\"Failed to query skill scans by status from DocumentDB: {e}\", exc_info=True\n )\n return []\n" }, { "path": "registry/repositories/documentdb/virtual_server_repository.py", "content": "\"\"\"\nDocumentDB (MongoDB) implementation for virtual server repository.\n\nStores virtual MCP server configurations in MongoDB with the path\nas the document _id, following the same patterns as skill and server\nrepositories.\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import (\n Any,\n)\n\nfrom motor.motor_asyncio import AsyncIOMotorCollection\nfrom pymongo.errors import DuplicateKeyError\n\nfrom ...exceptions import (\n VirtualServerAlreadyExistsError,\n VirtualServerServiceError,\n)\nfrom ...schemas.virtual_server_models import VirtualServerConfig\nfrom ..interfaces import VirtualServerRepositoryBase\nfrom .client import get_collection_name, get_documentdb_client\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _config_to_document(\n config: VirtualServerConfig,\n) -> dict[str, Any]:\n \"\"\"Convert VirtualServerConfig to MongoDB document.\"\"\"\n doc = config.model_dump(mode=\"json\")\n doc[\"_id\"] = config.path\n return doc\n\n\ndef _document_to_config(\n doc: dict[str, Any],\n) -> VirtualServerConfig:\n \"\"\"Convert MongoDB document to VirtualServerConfig.\"\"\"\n doc_copy = dict(doc)\n doc_copy.pop(\"_id\", None)\n return VirtualServerConfig(**doc_copy)\n\n\nclass DocumentDBVirtualServerRepository(VirtualServerRepositoryBase):\n \"\"\"MongoDB implementation for virtual server storage.\"\"\"\n\n def __init__(self):\n self._collection: AsyncIOMotorCollection | None = None\n self._collection_name = get_collection_name(\"virtual_servers\")\n self._indexes_created = False\n\n async def _get_collection(self) -> AsyncIOMotorCollection:\n \"\"\"Get DocumentDB collection, creating indexes on first access.\"\"\"\n if self._collection is None:\n db = await get_documentdb_client()\n self._collection = db[self._collection_name]\n await self.ensure_indexes()\n return self._collection\n\n async def ensure_indexes(self) -> None:\n \"\"\"Create required indexes if not present.\n\n Called automatically on first collection access via _get_collection().\n \"\"\"\n if self._indexes_created:\n return\n\n if self._collection is None:\n return\n\n try:\n # Enabled state index for list_enabled queries\n await self._collection.create_index(\"is_enabled\")\n\n # Tags index for filtering\n await self._collection.create_index(\"tags\")\n\n # Server name index for search\n await self._collection.create_index(\"server_name\")\n\n # Compound index for common query patterns\n await self._collection.create_index(\n [\n (\"is_enabled\", 1),\n (\"server_name\", 1),\n ]\n )\n\n self._indexes_created = True\n logger.info(f\"Created indexes for {self._collection_name} collection\")\n except Exception as e:\n logger.warning(f\"Could not create indexes for {self._collection_name}: {e}\")\n\n async def get(\n self,\n path: str,\n ) -> VirtualServerConfig | None:\n \"\"\"Get a virtual server by path.\"\"\"\n collection = await self._get_collection()\n doc = await collection.find_one({\"_id\": path})\n if doc:\n return _document_to_config(doc)\n return None\n\n async def list_all(self) -> list[VirtualServerConfig]:\n \"\"\"List all virtual servers.\"\"\"\n collection = await self._get_collection()\n configs = []\n cursor = collection.find({})\n async for doc in cursor:\n try:\n configs.append(_document_to_config(doc))\n except Exception as e:\n logger.error(f\"Failed to parse virtual server document: {e}\")\n return configs\n\n async def list_enabled(self) -> list[VirtualServerConfig]:\n \"\"\"List only enabled virtual servers.\"\"\"\n collection = await self._get_collection()\n configs = []\n cursor = collection.find({\"is_enabled\": True})\n async for doc in cursor:\n try:\n configs.append(_document_to_config(doc))\n except Exception as e:\n logger.error(f\"Failed to parse virtual server document: {e}\")\n return configs\n\n async def create(\n self,\n config: VirtualServerConfig,\n ) -> VirtualServerConfig:\n \"\"\"Create a new virtual server.\"\"\"\n collection = await self._get_collection()\n doc = _config_to_document(config)\n\n try:\n await collection.insert_one(doc)\n logger.info(f\"Created virtual server: {config.path}\")\n return config\n except DuplicateKeyError:\n logger.error(f\"Virtual server already exists: {config.path}\")\n raise VirtualServerAlreadyExistsError(config.path)\n except Exception as e:\n logger.error(f\"Failed to create virtual server {config.path}: {e}\")\n raise VirtualServerServiceError(f\"Failed to create virtual server: {e}\") from e\n\n async def update(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> VirtualServerConfig | None:\n \"\"\"Update a virtual server.\"\"\"\n collection = await self._get_collection()\n updates[\"updated_at\"] = datetime.now(UTC).isoformat()\n\n try:\n result = await collection.find_one_and_update(\n {\"_id\": path},\n {\"$set\": updates},\n return_document=True,\n )\n\n if result:\n logger.info(f\"Updated virtual server: {path}\")\n return _document_to_config(result)\n return None\n except Exception as e:\n logger.error(f\"Failed to update virtual server {path}: {e}\")\n raise VirtualServerServiceError(f\"Failed to update virtual server: {e}\") from e\n\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a virtual server.\"\"\"\n collection = await self._get_collection()\n result = await collection.delete_one({\"_id\": path})\n if result.deleted_count > 0:\n logger.info(f\"Deleted virtual server: {path}\")\n return True\n return False\n\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get virtual server enabled state.\"\"\"\n collection = await self._get_collection()\n doc = await collection.find_one(\n {\"_id\": path},\n {\"is_enabled\": 1},\n )\n return doc.get(\"is_enabled\", False) if doc else False\n\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set virtual server enabled state.\"\"\"\n collection = await self._get_collection()\n result = await collection.update_one(\n {\"_id\": path},\n {\n \"$set\": {\n \"is_enabled\": enabled,\n \"updated_at\": datetime.now(UTC).isoformat(),\n }\n },\n )\n if result.modified_count > 0:\n logger.info(f\"Set virtual server {path} enabled={enabled}\")\n return True\n return False\n\n async def update_rating(\n self,\n path: str,\n num_stars: float,\n rating_details: list[dict[str, Any]],\n ) -> bool:\n \"\"\"Update virtual server rating.\n\n Args:\n path: Virtual server path\n num_stars: Calculated average star rating\n rating_details: List of rating entries with user and rating\n\n Returns:\n True if update succeeded, False if server not found\n \"\"\"\n collection = await self._get_collection()\n result = await collection.update_one(\n {\"_id\": path},\n {\n \"$set\": {\n \"num_stars\": num_stars,\n \"rating_details\": rating_details,\n \"updated_at\": datetime.now(UTC).isoformat(),\n }\n },\n )\n if result.modified_count > 0 or result.matched_count > 0:\n logger.info(f\"Updated rating for virtual server {path}: {num_stars:.2f} stars\")\n return True\n return False\n\n async def get_rating(\n self,\n path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get virtual server rating info.\n\n Args:\n path: Virtual server path\n\n Returns:\n Dict with num_stars and rating_details, or None if not found\n \"\"\"\n collection = await self._get_collection()\n doc = await collection.find_one(\n {\"_id\": path},\n {\"num_stars\": 1, \"rating_details\": 1},\n )\n if doc:\n return {\n \"num_stars\": doc.get(\"num_stars\", 0.0),\n \"rating_details\": doc.get(\"rating_details\", []),\n }\n return None\n" }, { "path": "registry/repositories/factory.py", "content": "\"\"\"\nRepository factory - creates concrete implementations based on configuration.\n\"\"\"\n\nimport logging\n\nfrom ..core.config import settings\nfrom .app_log_repository import AppLogRepository\nfrom .audit_repository import AuditRepositoryBase\nfrom .interfaces import (\n AgentRepositoryBase,\n BackendSessionRepositoryBase,\n FederationConfigRepositoryBase,\n PeerFederationRepositoryBase,\n RegistryCardRepositoryBase,\n ScopeRepositoryBase,\n SearchRepositoryBase,\n SecurityScanRepositoryBase,\n ServerRepositoryBase,\n SkillRepositoryBase,\n SkillSecurityScanRepositoryBase,\n VirtualServerRepositoryBase,\n)\n\nlogger = logging.getLogger(__name__)\n\n# Singleton instances\n_server_repo: ServerRepositoryBase | None = None\n_agent_repo: AgentRepositoryBase | None = None\n_scope_repo: ScopeRepositoryBase | None = None\n_security_scan_repo: SecurityScanRepositoryBase | None = None\n_search_repo: SearchRepositoryBase | None = None\n_federation_config_repo: FederationConfigRepositoryBase | None = None\n_peer_federation_repo: PeerFederationRepositoryBase | None = None\n_audit_repo: AuditRepositoryBase | None = None\n_skill_repo: SkillRepositoryBase | None = None\n_virtual_server_repo: VirtualServerRepositoryBase | None = None\n_backend_session_repo: BackendSessionRepositoryBase | None = None\n_skill_security_scan_repo: SkillSecurityScanRepositoryBase | None = None\n_registry_card_repo: RegistryCardRepositoryBase | None = None\n_app_log_repo: AppLogRepository | None = None\n\n\ndef get_server_repository() -> ServerRepositoryBase:\n \"\"\"Get server repository singleton.\"\"\"\n global _server_repo\n\n if _server_repo is not None:\n return _server_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating server repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.server_repository import DocumentDBServerRepository\n\n _server_repo = DocumentDBServerRepository()\n else:\n from .file.server_repository import FileServerRepository\n\n _server_repo = FileServerRepository()\n\n return _server_repo\n\n\ndef get_agent_repository() -> AgentRepositoryBase:\n \"\"\"Get agent repository singleton.\"\"\"\n global _agent_repo\n\n if _agent_repo is not None:\n return _agent_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating agent repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.agent_repository import DocumentDBAgentRepository\n\n _agent_repo = DocumentDBAgentRepository()\n else:\n from .file.agent_repository import FileAgentRepository\n\n _agent_repo = FileAgentRepository()\n\n return _agent_repo\n\n\ndef get_scope_repository() -> ScopeRepositoryBase:\n \"\"\"Get scope repository singleton.\"\"\"\n global _scope_repo\n\n if _scope_repo is not None:\n return _scope_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating scope repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.scope_repository import DocumentDBScopeRepository\n\n _scope_repo = DocumentDBScopeRepository()\n else:\n from .file.scope_repository import FileScopeRepository\n\n _scope_repo = FileScopeRepository()\n\n return _scope_repo\n\n\ndef get_security_scan_repository() -> SecurityScanRepositoryBase:\n \"\"\"Get security scan repository singleton.\"\"\"\n global _security_scan_repo\n\n if _security_scan_repo is not None:\n return _security_scan_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating security scan repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.security_scan_repository import DocumentDBSecurityScanRepository\n\n _security_scan_repo = DocumentDBSecurityScanRepository()\n else:\n from .file.security_scan_repository import FileSecurityScanRepository\n\n _security_scan_repo = FileSecurityScanRepository()\n\n return _security_scan_repo\n\n\ndef get_search_repository() -> SearchRepositoryBase:\n \"\"\"Get search repository singleton.\"\"\"\n global _search_repo\n\n if _search_repo is not None:\n return _search_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating search repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.search_repository import DocumentDBSearchRepository\n\n _search_repo = DocumentDBSearchRepository()\n else:\n from .file.search_repository import FaissSearchRepository\n\n _search_repo = FaissSearchRepository()\n\n return _search_repo\n\n\ndef get_federation_config_repository() -> FederationConfigRepositoryBase:\n \"\"\"Get federation config repository singleton.\"\"\"\n global _federation_config_repo\n\n if _federation_config_repo is not None:\n return _federation_config_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating federation config repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.federation_config_repository import DocumentDBFederationConfigRepository\n\n _federation_config_repo = DocumentDBFederationConfigRepository()\n else:\n from .file.federation_config_repository import FileFederationConfigRepository\n\n _federation_config_repo = FileFederationConfigRepository()\n\n return _federation_config_repo\n\n\ndef get_peer_federation_repository() -> PeerFederationRepositoryBase:\n \"\"\"Get peer federation repository singleton.\"\"\"\n global _peer_federation_repo\n\n if _peer_federation_repo is not None:\n return _peer_federation_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating peer federation repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.peer_federation_repository import DocumentDBPeerFederationRepository\n\n _peer_federation_repo = DocumentDBPeerFederationRepository()\n else:\n from .file.peer_federation_repository import FilePeerFederationRepository\n\n _peer_federation_repo = FilePeerFederationRepository()\n\n return _peer_federation_repo\n\n\ndef get_audit_repository() -> AuditRepositoryBase:\n \"\"\"Get audit repository singleton.\n\n Note: Audit repository only supports DocumentDB/MongoDB backends.\n Returns None if storage backend is 'file'.\n \"\"\"\n global _audit_repo\n\n if _audit_repo is not None:\n return _audit_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating audit repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .audit_repository import DocumentDBAuditRepository\n\n _audit_repo = DocumentDBAuditRepository()\n else:\n # Audit repository requires MongoDB - return None for file backend\n logger.warning(\"Audit repository requires MongoDB backend. File backend not supported.\")\n return None\n\n return _audit_repo\n\n\ndef get_skill_repository() -> SkillRepositoryBase:\n \"\"\"Get skill repository singleton.\"\"\"\n global _skill_repo\n\n if _skill_repo is not None:\n return _skill_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating skill repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.skill_repository import DocumentDBSkillRepository\n\n _skill_repo = DocumentDBSkillRepository()\n else:\n # File-based skill repository not implemented yet\n # Fall back to DocumentDB repository for now\n from .documentdb.skill_repository import DocumentDBSkillRepository\n\n _skill_repo = DocumentDBSkillRepository()\n\n return _skill_repo\n\n\ndef get_skill_security_scan_repository() -> SkillSecurityScanRepositoryBase:\n \"\"\"Get skill security scan repository singleton.\"\"\"\n global _skill_security_scan_repo\n\n if _skill_security_scan_repo is not None:\n return _skill_security_scan_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating skill security scan repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.skill_security_scan_repository import DocumentDBSkillSecurityScanRepository\n\n _skill_security_scan_repo = DocumentDBSkillSecurityScanRepository()\n else:\n from .file.skill_security_scan_repository import FileSkillSecurityScanRepository\n\n _skill_security_scan_repo = FileSkillSecurityScanRepository()\n\n return _skill_security_scan_repo\n\n\ndef get_virtual_server_repository() -> VirtualServerRepositoryBase:\n \"\"\"Get virtual server repository singleton.\"\"\"\n global _virtual_server_repo\n\n if _virtual_server_repo is not None:\n return _virtual_server_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating virtual server repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.virtual_server_repository import DocumentDBVirtualServerRepository\n\n _virtual_server_repo = DocumentDBVirtualServerRepository()\n else:\n # File-based virtual server repository not implemented\n # Fall back to DocumentDB repository\n from .documentdb.virtual_server_repository import DocumentDBVirtualServerRepository\n\n _virtual_server_repo = DocumentDBVirtualServerRepository()\n\n return _virtual_server_repo\n\n\ndef get_backend_session_repository() -> BackendSessionRepositoryBase | None:\n \"\"\"Get backend session repository singleton.\n\n Note: Backend session repository only supports DocumentDB/MongoDB backends.\n Returns None if storage backend is 'file'.\n \"\"\"\n global _backend_session_repo\n\n if _backend_session_repo is not None:\n return _backend_session_repo\n\n backend = settings.storage_backend\n logger.info(f\"Creating backend session repository with backend: {backend}\")\n\n if backend in (\"documentdb\", \"mongodb-ce\"):\n from .documentdb.backend_session_repository import DocumentDBBackendSessionRepository\n\n _backend_session_repo = DocumentDBBackendSessionRepository()\n else:\n logger.warning(\n \"Backend session repository requires MongoDB backend. File backend not supported.\"\n )\n return None\n\n return _backend_session_repo\n\n\ndef get_registry_card_repository() -> RegistryCardRepositoryBase:\n \"\"\"\n Get Registry Card repository instance (singleton).\n\n Uses DocumentDB storage for all deployments.\n \"\"\"\n global _registry_card_repo\n\n if _registry_card_repo is None:\n from .documentdb.registry_card_repository import DocumentDBRegistryCardRepository\n\n _registry_card_repo = DocumentDBRegistryCardRepository()\n logger.info(\"Initialized Registry Card repository (DocumentDB)\")\n\n return _registry_card_repo\n\n\ndef get_app_log_repository() -> AppLogRepository | None:\n \"\"\"Get application log repository singleton.\n\n Note: Only available with DocumentDB/MongoDB backends.\n Returns None for file backend.\n \"\"\"\n global _app_log_repo\n\n if _app_log_repo is not None:\n return _app_log_repo\n\n backend = settings.storage_backend\n if backend in (\"documentdb\", \"mongodb-ce\"):\n _app_log_repo = AppLogRepository()\n logger.info(\"Initialized application log repository (DocumentDB/MongoDB)\")\n else:\n logger.warning(\"Application log repository requires MongoDB backend.\")\n return None\n\n return _app_log_repo\n\n\ndef reset_repositories() -> None:\n \"\"\"Reset all repository singletons. USE ONLY IN TESTS.\"\"\"\n global \\\n _server_repo, \\\n _agent_repo, \\\n _scope_repo, \\\n _security_scan_repo, \\\n _search_repo, \\\n _federation_config_repo, \\\n _peer_federation_repo, \\\n _audit_repo, \\\n _skill_repo, \\\n _virtual_server_repo, \\\n _backend_session_repo, \\\n _skill_security_scan_repo, \\\n _registry_card_repo, \\\n _app_log_repo\n _server_repo = None\n _agent_repo = None\n _scope_repo = None\n _security_scan_repo = None\n _search_repo = None\n _federation_config_repo = None\n _peer_federation_repo = None\n _audit_repo = None\n _skill_repo = None\n _virtual_server_repo = None\n _backend_session_repo = None\n _skill_security_scan_repo = None\n _registry_card_repo = None\n _app_log_repo = None\n" }, { "path": "registry/repositories/file/__init__.py", "content": "" }, { "path": "registry/repositories/file/agent_repository.py", "content": "\"\"\"File-based agent repository implementation.\"\"\"\n\nimport json\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nfrom ...core.config import settings\nfrom ...schemas.agent_models import AgentCard\nfrom ..interfaces import AgentRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\ndef _path_to_filename(path: str) -> str:\n \"\"\"Convert agent path to safe filename.\"\"\"\n normalized = path.lstrip(\"/\").replace(\"/\", \"_\")\n if not normalized.endswith(\"_agent.json\"):\n if normalized.endswith(\".json\"):\n normalized = normalized.replace(\".json\", \"_agent.json\")\n else:\n normalized += \"_agent.json\"\n return normalized\n\n\nclass FileAgentRepository(AgentRepositoryBase):\n \"\"\"File-based agent repository using JSON files.\"\"\"\n\n def __init__(self):\n self.agents_dir = settings.agents_dir\n self.state_file = settings.agent_state_file_path\n self.agents_dir.mkdir(parents=True, exist_ok=True)\n\n async def get_all(self) -> dict[str, AgentCard]:\n \"\"\"Load all agents from disk.\"\"\"\n agents = {}\n agent_files = [\n f for f in self.agents_dir.glob(\"**/*_agent.json\") if f.name != self.state_file.name\n ]\n\n for file in agent_files:\n try:\n with open(file) as f:\n data = json.load(f)\n if isinstance(data, dict) and \"path\" in data and \"name\" in data:\n agent = AgentCard(**data)\n agents[agent.path] = agent\n except Exception as e:\n logger.error(f\"Failed to load agent from {file}: {e}\")\n\n return agents\n\n async def get(self, path: str) -> AgentCard | None:\n \"\"\"Get agent by path.\"\"\"\n agents = await self.get_all()\n return agents.get(path)\n\n async def save(self, agent: AgentCard) -> AgentCard:\n \"\"\"Save agent to disk.\"\"\"\n if not agent.registered_at:\n agent.registered_at = datetime.now(UTC)\n agent.updated_at = datetime.now(UTC)\n\n filename = _path_to_filename(agent.path)\n file_path = self.agents_dir / filename\n\n with open(file_path, \"w\") as f:\n json.dump(agent.model_dump(mode=\"json\"), f, indent=2)\n\n return agent\n\n async def delete(self, path: str) -> bool:\n \"\"\"Delete agent from disk.\"\"\"\n filename = _path_to_filename(path)\n file_path = self.agents_dir / filename\n\n if file_path.exists():\n file_path.unlink()\n return True\n return False\n\n async def _load_state_file(self) -> dict[str, list[str]]:\n \"\"\"Load raw state dict from disk.\"\"\"\n if self.state_file.exists():\n try:\n with open(self.state_file) as f:\n state = json.load(f)\n if isinstance(state, dict):\n return {\n \"enabled\": state.get(\"enabled\", []),\n \"disabled\": state.get(\"disabled\", []),\n }\n except Exception as e:\n logger.error(f\"Failed to load state: {e}\")\n\n return {\"enabled\": [], \"disabled\": []}\n\n async def get_state(self, path: str) -> bool:\n \"\"\"Get enabled/disabled state for a single agent.\"\"\"\n state = await self._load_state_file()\n return path in state[\"enabled\"]\n\n async def get_all_states(self) -> dict[str, bool]:\n \"\"\"Get enabled/disabled state for all agents in a single read.\"\"\"\n state = await self._load_state_file()\n states: dict[str, bool] = {}\n for path in state.get(\"enabled\", []):\n states[path] = True\n for path in state.get(\"disabled\", []):\n states[path] = False\n return states\n\n async def save_state(self, state: dict[str, list[str]]) -> None:\n \"\"\"Save agent state to disk.\"\"\"\n with open(self.state_file, \"w\") as f:\n json.dump(state, f, indent=2)\n\n async def is_enabled(self, path: str) -> bool:\n \"\"\"Check if agent is enabled.\"\"\"\n state = await self._load_state_file()\n return path in state[\"enabled\"]\n\n async def set_enabled(self, path: str, enabled: bool) -> None:\n \"\"\"Set agent enabled state.\"\"\"\n state = await self._load_state_file()\n\n if enabled:\n if path in state[\"disabled\"]:\n state[\"disabled\"].remove(path)\n if path not in state[\"enabled\"]:\n state[\"enabled\"].append(path)\n else:\n if path in state[\"enabled\"]:\n state[\"enabled\"].remove(path)\n if path not in state[\"disabled\"]:\n state[\"disabled\"].append(path)\n\n await self.save_state(state)\n\n async def create(self, agent: AgentCard) -> AgentCard:\n \"\"\"Create a new agent (alias for save).\"\"\"\n return await self.save(agent)\n\n async def update(self, path: str, agent: AgentCard) -> AgentCard | None:\n \"\"\"Update an existing agent.\"\"\"\n existing = await self.get(path)\n if not existing:\n return None\n return await self.save(agent)\n\n async def list_all(self) -> list[AgentCard]:\n \"\"\"List all agents.\"\"\"\n agents = await self.get_all()\n return list(agents.values())\n\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> list[AgentCard]:\n \"\"\"List agents with in-memory pagination (file backend).\"\"\"\n all_agents = await self.list_all()\n return all_agents[skip : skip + limit]\n\n async def load_all(self) -> dict[str, AgentCard]:\n \"\"\"Load all agents (alias for get_all).\"\"\"\n return await self.get_all()\n\n async def set_state(self, path: str, enabled: bool) -> None:\n \"\"\"Set agent state (alias for set_enabled).\"\"\"\n await self.set_enabled(path, enabled)\n\n async def count(self) -> int:\n \"\"\"Get total count of agents.\n\n Returns:\n Total number of agents in the repository.\n \"\"\"\n agents = await self.get_all()\n return len(agents)\n\n async def update_field(\n self,\n path: str,\n field: str,\n value: Any,\n ) -> bool:\n \"\"\"Update a single field on a document (file-based).\"\"\"\n agent = await self.get(path)\n if not agent:\n return False\n\n data = agent.model_dump(mode=\"json\")\n\n if value is None:\n parts = field.split(\".\")\n obj = data\n for part in parts[:-1]:\n obj = obj.get(part, {})\n obj.pop(parts[-1], None)\n else:\n parts = field.split(\".\")\n obj = data\n for part in parts[:-1]:\n if part not in obj:\n obj[part] = {}\n obj = obj[part]\n obj[parts[-1]] = value\n\n updated_agent = AgentCard(**data)\n await self.save(updated_agent)\n return True\n\n async def find_with_filter(\n self,\n filter_dict: dict[str, Any],\n ) -> dict[str, dict]:\n \"\"\"Find documents matching a filter (file-based, basic support).\"\"\"\n all_agents = await self.get_all()\n results = {}\n for agent_path, agent in all_agents.items():\n data = agent.model_dump(mode=\"json\")\n match = True\n for field_name, condition in filter_dict.items():\n if isinstance(condition, dict) and \"$exists\" in condition:\n has_field = data.get(field_name) is not None\n if condition.get(\"$ne\") is not None:\n has_field = has_field and data.get(field_name) != condition[\"$ne\"]\n if condition[\"$exists\"] != has_field:\n match = False\n break\n if match:\n results[agent_path] = data\n return results\n" }, { "path": "registry/repositories/file/federation_config_repository.py", "content": "\"\"\"File-based repository for federation configuration storage.\"\"\"\n\nimport json\nimport logging\nfrom datetime import UTC, datetime\nfrom pathlib import Path\nfrom typing import Any\n\nfrom ...schemas.federation_schema import FederationConfig\nfrom ..interfaces import FederationConfigRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass FileFederationConfigRepository(FederationConfigRepositoryBase):\n \"\"\"File-based implementation of federation configuration repository.\"\"\"\n\n def __init__(self, config_dir: Path | None = None):\n \"\"\"\n Initialize file-based federation config repository.\n\n Args:\n config_dir: Directory for config files (default: from settings)\n \"\"\"\n if config_dir is None:\n config_dir = Path(\"/app/config/federation\")\n\n self._config_dir = config_dir\n self._config_dir.mkdir(parents=True, exist_ok=True)\n\n logger.info(\n f\"Initialized File FederationConfigRepository with directory: {self._config_dir}\"\n )\n\n def _get_config_path(self, config_id: str) -> Path:\n \"\"\"Get file path for a config ID.\"\"\"\n return self._config_dir / f\"{config_id}.json\"\n\n async def get_config(self, config_id: str = \"default\") -> FederationConfig | None:\n \"\"\"\n Get federation configuration by ID.\n\n Args:\n config_id: Configuration ID\n\n Returns:\n FederationConfig if found, None otherwise\n \"\"\"\n try:\n config_path = self._get_config_path(config_id)\n\n if not config_path.exists():\n logger.info(f\"Federation config file not found: {config_path}\")\n return None\n\n with open(config_path) as f:\n data = json.load(f)\n\n # Remove internal fields before creating Pydantic model\n data.pop(\"config_id\", None)\n data.pop(\"created_at\", None)\n data.pop(\"updated_at\", None)\n\n config = FederationConfig(**data)\n logger.info(f\"Retrieved federation config from file: {config_id}\")\n return config\n\n except Exception as e:\n logger.error(f\"Failed to read federation config {config_id}: {e}\", exc_info=True)\n return None\n\n async def save_config(\n self, config: FederationConfig, config_id: str = \"default\"\n ) -> FederationConfig:\n \"\"\"\n Save or update federation configuration.\n\n Args:\n config: Federation configuration to save\n config_id: Configuration ID\n\n Returns:\n Saved configuration\n \"\"\"\n try:\n config_path = self._get_config_path(config_id)\n\n # Check if config exists\n existing = None\n if config_path.exists():\n with open(config_path) as f:\n existing = json.load(f)\n\n # Prepare document\n doc = config.model_dump()\n doc[\"config_id\"] = config_id\n\n now = datetime.now(UTC).isoformat()\n if existing:\n # Preserve created_at for updates\n doc[\"created_at\"] = existing.get(\"created_at\", now)\n doc[\"updated_at\"] = now\n else:\n # New config\n doc[\"created_at\"] = now\n doc[\"updated_at\"] = now\n\n # Write to file\n with open(config_path, \"w\") as f:\n json.dump(doc, f, indent=2)\n\n logger.info(f\"Saved federation config to file: {config_id} -> {config_path}\")\n return config\n\n except Exception as e:\n logger.error(f\"Failed to save federation config {config_id}: {e}\", exc_info=True)\n raise\n\n async def delete_config(self, config_id: str = \"default\") -> bool:\n \"\"\"\n Delete federation configuration.\n\n Args:\n config_id: Configuration ID\n\n Returns:\n True if deleted, False if not found\n \"\"\"\n try:\n config_path = self._get_config_path(config_id)\n\n if not config_path.exists():\n logger.warning(f\"Federation config file not found for deletion: {config_path}\")\n return False\n\n config_path.unlink()\n logger.info(f\"Deleted federation config file: {config_id}\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to delete federation config {config_id}: {e}\", exc_info=True)\n return False\n\n async def list_configs(self) -> list[dict[str, Any]]:\n \"\"\"\n List all federation configurations.\n\n Returns:\n List of config summaries\n \"\"\"\n try:\n if not self._config_dir.exists():\n return []\n\n configs = []\n for config_file in self._config_dir.glob(\"*.json\"):\n try:\n with open(config_file) as f:\n data = json.load(f)\n\n configs.append(\n {\n \"id\": data.get(\"config_id\", config_file.stem),\n \"created_at\": data.get(\"created_at\"),\n \"updated_at\": data.get(\"updated_at\"),\n }\n )\n except Exception as e:\n logger.error(f\"Failed to read config file {config_file}: {e}\")\n continue\n\n logger.info(f\"Listed {len(configs)} federation configs from files\")\n return configs\n\n except Exception as e:\n logger.error(f\"Failed to list federation configs: {e}\", exc_info=True)\n return []\n" }, { "path": "registry/repositories/file/peer_federation_repository.py", "content": "\"\"\"File-based repository for peer federation configuration storage.\n\nDEPRECATED: This implementation is kept for backward compatibility only.\nNew deployments should use storage_backend=documentdb or storage_backend=mongodb-ce.\n\nStorage structure:\n- {peers_dir}/{peer_id}.json: Peer registry configurations\n- {peers_dir}/../peer_sync_state.json: Sync status for all peers\n\"\"\"\n\nimport json\nimport logging\nimport warnings\nfrom datetime import UTC, datetime\nfrom pathlib import Path\nfrom typing import Any\n\nfrom ...core.config import settings\nfrom ...schemas.peer_federation_schema import (\n PeerRegistryConfig,\n PeerSyncStatus,\n)\nfrom ...utils.federation_encryption import (\n decrypt_token_in_peer_dict,\n encrypt_token_in_peer_dict,\n)\nfrom ..interfaces import PeerFederationRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\ndef _validate_peer_id(\n peer_id: str,\n) -> None:\n \"\"\"\n Validate peer_id to prevent path traversal and invalid characters.\n\n Args:\n peer_id: Peer identifier to validate\n\n Raises:\n ValueError: If peer_id contains invalid characters or path traversal\n \"\"\"\n if not peer_id:\n raise ValueError(\"peer_id cannot be empty\")\n\n # Check for path traversal attempts\n if \"..\" in peer_id or \"/\" in peer_id or \"\\\\\" in peer_id:\n raise ValueError(f\"Invalid peer_id: path traversal detected in '{peer_id}'\")\n\n # Check for invalid filename characters\n invalid_chars = [\"<\", \">\", \":\", '\"', \"|\", \"?\", \"*\", \"\\0\"]\n for char in invalid_chars:\n if char in peer_id:\n raise ValueError(f\"Invalid peer_id: contains invalid character '{char}'\")\n\n # Check for reserved names\n if peer_id.lower() in [\"con\", \"prn\", \"aux\", \"nul\"]:\n raise ValueError(f\"Invalid peer_id: '{peer_id}' is a reserved name\")\n\n\ndef _get_safe_file_path(\n peer_id: str,\n peers_dir: Path,\n) -> Path:\n \"\"\"\n Get safe file path for a peer config, with path traversal protection.\n\n Args:\n peer_id: Peer identifier\n peers_dir: Directory for peer storage\n\n Returns:\n Safe file path within peers_dir\n\n Raises:\n ValueError: If path traversal is detected\n \"\"\"\n _validate_peer_id(peer_id)\n\n filename = f\"{peer_id}.json\"\n file_path = peers_dir / filename\n\n # Resolve to absolute path and verify it's within peers_dir\n resolved_path = file_path.resolve()\n resolved_peers_dir = peers_dir.resolve()\n\n if not resolved_path.is_relative_to(resolved_peers_dir):\n raise ValueError(f\"Invalid peer_id: path traversal detected for '{peer_id}'\")\n\n return file_path\n\n\nclass FilePeerFederationRepository(PeerFederationRepositoryBase):\n \"\"\"File-based implementation of peer federation repository.\n\n DEPRECATED: Use DocumentDBPeerFederationRepository for new deployments.\n \"\"\"\n\n def __init__(\n self,\n peers_dir: Path | None = None,\n sync_state_file: Path | None = None,\n ):\n \"\"\"\n Initialize file-based peer federation repository.\n\n Args:\n peers_dir: Directory for peer config files (default: from settings)\n sync_state_file: Path to sync state file (default: from settings)\n \"\"\"\n warnings.warn(\n \"FilePeerFederationRepository is deprecated. \"\n \"Use storage_backend=documentdb or storage_backend=mongodb-ce instead.\",\n DeprecationWarning,\n stacklevel=2,\n )\n\n self._peers_dir = peers_dir or settings.peers_dir\n self._sync_state_file = sync_state_file or settings.peer_sync_state_file_path\n\n # Ensure directories exist\n self._peers_dir.mkdir(parents=True, exist_ok=True)\n self._sync_state_file.parent.mkdir(parents=True, exist_ok=True)\n\n # In-memory caches\n self._peers_cache: dict[str, PeerRegistryConfig] = {}\n self._sync_status_cache: dict[str, PeerSyncStatus] = {}\n\n logger.info(\n f\"Initialized File PeerFederationRepository with \"\n f\"peers_dir={self._peers_dir}, sync_state_file={self._sync_state_file} \"\n \"(DEPRECATED)\"\n )\n\n def _load_peer_from_file(\n self,\n file_path: Path,\n ) -> PeerRegistryConfig | None:\n \"\"\"Load peer config from JSON file.\"\"\"\n try:\n with open(file_path) as f:\n peer_data = json.load(f)\n\n if not isinstance(peer_data, dict):\n logger.warning(f\"Invalid peer data format in {file_path}\")\n return None\n\n if \"peer_id\" not in peer_data:\n logger.warning(f\"Missing peer_id in {file_path}\")\n return None\n\n # Decrypt federation token if present\n decrypt_token_in_peer_dict(peer_data)\n\n peer_config = PeerRegistryConfig(**peer_data)\n return peer_config\n\n except FileNotFoundError:\n logger.error(f\"Peer file not found: {file_path}\")\n return None\n except json.JSONDecodeError as e:\n logger.error(f\"Could not parse JSON from {file_path}: {e}\")\n return None\n except Exception as e:\n logger.error(f\"Unexpected error loading {file_path}: {e}\", exc_info=True)\n return None\n\n def _save_peer_to_file(\n self,\n peer_config: PeerRegistryConfig,\n ) -> bool:\n \"\"\"Save peer config to JSON file.\"\"\"\n try:\n file_path = _get_safe_file_path(peer_config.peer_id, self._peers_dir)\n\n peer_dict = peer_config.model_dump(mode=\"json\")\n\n # Encrypt federation token before storage\n encrypt_token_in_peer_dict(peer_dict)\n\n with open(file_path, \"w\") as f:\n json.dump(peer_dict, f, indent=2)\n\n logger.debug(f\"Saved peer config to {file_path}\")\n return True\n\n except ValueError as e:\n logger.error(f\"Invalid peer_id: {e}\")\n return False\n except Exception as e:\n logger.error(f\"Failed to save peer '{peer_config.peer_id}' to disk: {e}\", exc_info=True)\n return False\n\n def _load_sync_state_file(self) -> dict[str, PeerSyncStatus]:\n \"\"\"Load sync state from file.\"\"\"\n try:\n if not self._sync_state_file.exists():\n logger.info(f\"No sync state file found at {self._sync_state_file}\")\n return {}\n\n with open(self._sync_state_file) as f:\n state_data = json.load(f)\n\n if not isinstance(state_data, dict):\n logger.warning(f\"Invalid state format in {self._sync_state_file}\")\n return {}\n\n sync_status_map = {}\n for peer_id, status_dict in state_data.items():\n try:\n sync_status = PeerSyncStatus(**status_dict)\n sync_status_map[peer_id] = sync_status\n except Exception as e:\n logger.error(f\"Failed to load sync status for peer '{peer_id}': {e}\")\n\n return sync_status_map\n\n except json.JSONDecodeError as e:\n logger.error(f\"Could not parse JSON from {self._sync_state_file}: {e}\")\n return {}\n except Exception as e:\n logger.error(\n f\"Failed to read sync state file {self._sync_state_file}: {e}\", exc_info=True\n )\n return {}\n\n def _save_sync_state_file(self) -> None:\n \"\"\"Persist sync state to file.\"\"\"\n try:\n state_data = {\n peer_id: status.model_dump(mode=\"json\")\n for peer_id, status in self._sync_status_cache.items()\n }\n\n with open(self._sync_state_file, \"w\") as f:\n json.dump(state_data, f, indent=2)\n\n logger.debug(f\"Persisted sync state to {self._sync_state_file}\")\n\n except Exception as e:\n logger.error(\n f\"Failed to persist sync state to {self._sync_state_file}: {e}\", exc_info=True\n )\n\n async def get_peer(\n self,\n peer_id: str,\n ) -> PeerRegistryConfig | None:\n \"\"\"Get peer configuration by ID.\"\"\"\n return self._peers_cache.get(peer_id)\n\n async def list_peers(\n self,\n enabled: bool | None = None,\n ) -> list[PeerRegistryConfig]:\n \"\"\"List all peer configurations with optional filtering.\"\"\"\n peers = list(self._peers_cache.values())\n\n if enabled is None:\n return peers\n\n return [peer for peer in peers if peer.enabled == enabled]\n\n async def create_peer(\n self,\n config: PeerRegistryConfig,\n ) -> PeerRegistryConfig:\n \"\"\"Create a new peer configuration.\"\"\"\n peer_id = config.peer_id\n\n # Validate peer_id\n _validate_peer_id(peer_id)\n\n # Check if peer already exists\n if peer_id in self._peers_cache:\n raise ValueError(f\"Peer ID '{peer_id}' already exists\")\n\n # Set timestamps\n now = datetime.now(UTC)\n config.created_at = now\n config.updated_at = now\n\n # Save to file\n if not self._save_peer_to_file(config):\n raise ValueError(f\"Failed to save peer '{config.name}' to disk\")\n\n # Update cache\n self._peers_cache[peer_id] = config\n\n # Initialize sync status\n self._sync_status_cache[peer_id] = PeerSyncStatus(peer_id=peer_id)\n self._save_sync_state_file()\n\n logger.info(f\"Created peer: {peer_id} ({config.name})\")\n return config\n\n async def update_peer(\n self,\n peer_id: str,\n updates: dict[str, Any],\n ) -> PeerRegistryConfig:\n \"\"\"Update an existing peer configuration.\"\"\"\n if peer_id not in self._peers_cache:\n raise ValueError(f\"Peer not found: {peer_id}\")\n\n existing_peer = self._peers_cache[peer_id]\n\n # Merge updates with existing data\n peer_dict = existing_peer.model_dump()\n peer_dict.update(updates)\n\n # Ensure peer_id is consistent\n peer_dict[\"peer_id\"] = peer_id\n\n # Update timestamp\n peer_dict[\"updated_at\"] = datetime.now(UTC)\n\n # Validate updated peer\n try:\n updated_peer = PeerRegistryConfig(**peer_dict)\n except Exception as e:\n raise ValueError(f\"Invalid peer update: {e}\")\n\n # Save to file\n if not self._save_peer_to_file(updated_peer):\n raise ValueError(\"Failed to save updated peer to disk\")\n\n # Update cache\n self._peers_cache[peer_id] = updated_peer\n\n logger.info(f\"Updated peer: {peer_id}\")\n return updated_peer\n\n async def delete_peer(\n self,\n peer_id: str,\n ) -> bool:\n \"\"\"Delete a peer configuration and its sync status.\"\"\"\n if peer_id not in self._peers_cache:\n raise ValueError(f\"Peer not found: {peer_id}\")\n\n try:\n file_path = _get_safe_file_path(peer_id, self._peers_dir)\n\n if file_path.exists():\n file_path.unlink()\n logger.debug(f\"Removed peer file: {file_path}\")\n\n # Remove from caches\n peer_name = self._peers_cache[peer_id].name\n del self._peers_cache[peer_id]\n\n if peer_id in self._sync_status_cache:\n del self._sync_status_cache[peer_id]\n\n # Persist updated sync state\n self._save_sync_state_file()\n\n logger.info(f\"Deleted peer: {peer_id} ({peer_name})\")\n return True\n\n except ValueError:\n raise\n except Exception as e:\n logger.error(f\"Failed to delete peer '{peer_id}': {e}\", exc_info=True)\n raise ValueError(f\"Failed to delete peer: {e}\")\n\n async def get_sync_status(\n self,\n peer_id: str,\n ) -> PeerSyncStatus | None:\n \"\"\"Get sync status for a peer.\"\"\"\n return self._sync_status_cache.get(peer_id)\n\n async def update_sync_status(\n self,\n peer_id: str,\n status: PeerSyncStatus,\n ) -> PeerSyncStatus:\n \"\"\"Update sync status for a peer.\"\"\"\n self._sync_status_cache[peer_id] = status\n self._save_sync_state_file()\n\n logger.debug(f\"Updated sync status for peer: {peer_id}\")\n return status\n\n async def list_sync_statuses(self) -> list[PeerSyncStatus]:\n \"\"\"List all peer sync statuses.\"\"\"\n return list(self._sync_status_cache.values())\n\n async def load_all(self) -> None:\n \"\"\"Load/reload all peers and sync states from storage.\"\"\"\n logger.info(f\"Loading peers from {self._peers_dir}...\")\n\n # Clear caches\n self._peers_cache = {}\n self._sync_status_cache = {}\n\n # Load peer configs from files\n peer_files = list(self._peers_dir.glob(\"*.json\"))\n\n # Exclude sync state file if it's in the same directory\n peer_files = [f for f in peer_files if f.name != self._sync_state_file.name]\n\n logger.info(f\"Found {len(peer_files)} peer config files\")\n\n for peer_file in peer_files:\n peer_config = self._load_peer_from_file(peer_file)\n if peer_config:\n self._peers_cache[peer_config.peer_id] = peer_config\n\n logger.info(f\"Loaded {len(self._peers_cache)} peer configs\")\n\n # Load sync state\n self._sync_status_cache = self._load_sync_state_file()\n\n # Initialize sync status for any peers without one\n for peer_id in self._peers_cache.keys():\n if peer_id not in self._sync_status_cache:\n self._sync_status_cache[peer_id] = PeerSyncStatus(peer_id=peer_id)\n\n logger.info(\n f\"Peer federation loaded: {len(self._peers_cache)} peers, \"\n f\"{len(self._sync_status_cache)} sync statuses\"\n )\n" }, { "path": "registry/repositories/file/scope_repository.py", "content": "\"\"\"\nFile-based repository for authorization scopes storage.\n\nExtracts all scopes.yml file I/O logic while maintaining identical behavior.\n\"\"\"\n\nimport logging\nimport shutil\nfrom pathlib import Path\nfrom typing import Any\n\nimport yaml\n\nfrom ..interfaces import ScopeRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass FileScopeRepository(ScopeRepositoryBase):\n \"\"\"File-based implementation of scope repository.\"\"\"\n\n def __init__(self):\n self._scopes_data: dict[str, Any] = {}\n self._scopes_file = Path(\"/app/auth_server/scopes.yml\")\n self._alt_scopes_file = Path(\"/app/auth_server/auth_config/scopes.yml\")\n\n async def load_all(self) -> None:\n \"\"\"Load all scopes from scopes.yml file.\"\"\"\n # Check primary location first, then alternative (EFS mount)\n if self._scopes_file.exists():\n scopes_file = self._scopes_file\n elif self._alt_scopes_file.exists():\n scopes_file = self._alt_scopes_file\n logger.info(f\"Using alternative scopes file at {scopes_file}\")\n else:\n logger.error(f\"Scopes file not found at {self._scopes_file} or {self._alt_scopes_file}\")\n self._scopes_data = {}\n return\n\n logger.info(f\"Loading scopes from {scopes_file}...\")\n\n try:\n with open(scopes_file) as f:\n self._scopes_data = yaml.safe_load(f)\n\n if not isinstance(self._scopes_data, dict):\n logger.warning(\"Invalid scopes file format, resetting\")\n self._scopes_data = {}\n else:\n logger.info(f\"Successfully loaded scopes from {scopes_file}\")\n\n except Exception as e:\n logger.error(f\"Failed to read scopes file: {e}\", exc_info=True)\n self._scopes_data = {}\n\n async def _save_scopes(self) -> bool:\n \"\"\"Save scopes data to file.\"\"\"\n try:\n backup_file = self._scopes_file.with_suffix(\".backup\")\n\n shutil.copy2(self._scopes_file, backup_file)\n\n class NoAnchorDumper(yaml.SafeDumper):\n def ignore_aliases(self, data):\n return True\n\n with open(self._scopes_file, \"w\") as f:\n yaml.dump(\n self._scopes_data,\n f,\n default_flow_style=False,\n sort_keys=False,\n Dumper=NoAnchorDumper,\n )\n\n logger.info(f\"Successfully updated scopes file at {self._scopes_file}\")\n\n if backup_file.exists():\n backup_file.unlink()\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to write scopes file: {e}\", exc_info=True)\n if backup_file.exists():\n shutil.copy2(backup_file, self._scopes_file)\n logger.info(\"Restored scopes file from backup\")\n return False\n\n async def get_ui_scopes(\n self,\n group_name: str,\n ) -> dict[str, Any]:\n \"\"\"Get UI scopes for a Keycloak group.\"\"\"\n ui_scopes = self._scopes_data.get(\"UI-Scopes\", {})\n return ui_scopes.get(group_name, {})\n\n async def get_group_mappings(\n self,\n keycloak_group: str,\n ) -> list[str]:\n \"\"\"Get scope names mapped to a Keycloak group.\"\"\"\n group_mappings = self._scopes_data.get(\"group_mappings\", {})\n return group_mappings.get(keycloak_group, [])\n\n async def get_server_scopes(\n self,\n scope_name: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Get server access rules for a scope.\"\"\"\n return self._scopes_data.get(scope_name, [])\n\n async def add_server_scope(\n self,\n server_path: str,\n scope_name: str,\n methods: list[str],\n tools: list[str] | None = None,\n ) -> bool:\n \"\"\"Add scope for a server.\"\"\"\n try:\n server_name = server_path.lstrip(\"/\")\n\n server_entry = {\"server\": server_name, \"methods\": methods, \"tools\": tools}\n\n if scope_name not in self._scopes_data:\n logger.warning(f\"Scope section {scope_name} not found in scopes.yml\")\n return False\n\n if not isinstance(self._scopes_data[scope_name], list):\n logger.warning(f\"Scope section {scope_name} is not a list\")\n return False\n\n existing = [s for s in self._scopes_data[scope_name] if s.get(\"server\") == server_name]\n\n if existing:\n idx = self._scopes_data[scope_name].index(existing[0])\n self._scopes_data[scope_name][idx] = server_entry\n logger.info(f\"Updated existing server {server_path} in scope {scope_name}\")\n else:\n self._scopes_data[scope_name].append(server_entry)\n logger.info(f\"Added server {server_path} to scope {scope_name}\")\n\n return await self._save_scopes()\n\n except Exception as e:\n logger.error(f\"Failed to add server scope: {e}\", exc_info=True)\n return False\n\n async def remove_server_scope(\n self,\n server_path: str,\n scope_name: str,\n ) -> bool:\n \"\"\"Remove scope for a server.\"\"\"\n try:\n server_name = server_path.lstrip(\"/\")\n\n if scope_name not in self._scopes_data:\n logger.warning(f\"Scope section {scope_name} not found\")\n return False\n\n if not isinstance(self._scopes_data[scope_name], list):\n logger.warning(f\"Scope section {scope_name} is not a list\")\n return False\n\n original_length = len(self._scopes_data[scope_name])\n self._scopes_data[scope_name] = [\n s for s in self._scopes_data[scope_name] if s.get(\"server\") != server_name\n ]\n\n if len(self._scopes_data[scope_name]) < original_length:\n logger.info(f\"Removed server {server_path} from scope {scope_name}\")\n return await self._save_scopes()\n else:\n logger.warning(f\"Server {server_path} not found in scope {scope_name}\")\n return False\n\n except Exception as e:\n logger.error(f\"Failed to remove server scope: {e}\", exc_info=True)\n return False\n\n async def create_group(\n self,\n group_name: str,\n description: str = \"\",\n ) -> bool:\n \"\"\"Create a new group in scopes.\"\"\"\n try:\n if group_name in self._scopes_data:\n logger.warning(f\"Group {group_name} already exists in scopes.yml\")\n return False\n\n self._scopes_data[group_name] = []\n logger.info(f\"Created new group entry: {group_name}\")\n\n if \"group_mappings\" not in self._scopes_data:\n self._scopes_data[\"group_mappings\"] = {}\n\n if group_name not in self._scopes_data[\"group_mappings\"]:\n self._scopes_data[\"group_mappings\"][group_name] = [group_name]\n logger.info(f\"Added {group_name} to group_mappings (self-mapping)\")\n\n if \"UI-Scopes\" not in self._scopes_data:\n self._scopes_data[\"UI-Scopes\"] = {}\n\n if group_name not in self._scopes_data[\"UI-Scopes\"]:\n self._scopes_data[\"UI-Scopes\"][group_name] = {\"list_service\": []}\n logger.info(f\"Added {group_name} to UI-Scopes with empty list_service\")\n\n return await self._save_scopes()\n\n except Exception as e:\n logger.error(f\"Failed to create group {group_name}: {e}\", exc_info=True)\n return False\n\n async def delete_group(\n self,\n group_name: str,\n remove_from_mappings: bool = True,\n ) -> bool:\n \"\"\"Delete a group from scopes.\"\"\"\n try:\n if group_name not in self._scopes_data:\n logger.warning(f\"Group {group_name} not found in scopes.yml\")\n return False\n\n if (\n isinstance(self._scopes_data[group_name], list)\n and len(self._scopes_data[group_name]) > 0\n ):\n server_count = len(self._scopes_data[group_name])\n logger.warning(f\"Group {group_name} has {server_count} servers assigned\")\n\n del self._scopes_data[group_name]\n logger.info(f\"Removed group {group_name} from scopes.yml\")\n\n if remove_from_mappings and \"group_mappings\" in self._scopes_data:\n modified_mappings = False\n for mapped_group, mapped_scopes in self._scopes_data[\"group_mappings\"].items():\n if group_name in mapped_scopes:\n self._scopes_data[\"group_mappings\"][mapped_group].remove(group_name)\n logger.info(f\"Removed {group_name} from group_mappings[{mapped_group}]\")\n modified_mappings = True\n\n if modified_mappings:\n logger.info(\"Updated group_mappings after group deletion\")\n\n return await self._save_scopes()\n\n except Exception as e:\n logger.error(f\"Failed to delete group {group_name}: {e}\", exc_info=True)\n return False\n\n async def import_group(\n self,\n group_name: str,\n description: str = \"\",\n server_access: list = None,\n group_mappings: list = None,\n ui_permissions: dict = None,\n agent_access: list = None,\n ) -> bool:\n \"\"\"\n Import a complete group definition.\n\n Args:\n group_name: Name of the group\n description: Description of the group\n server_access: List of server access definitions\n group_mappings: List of group names this group maps to\n ui_permissions: Dictionary of UI permissions\n agent_access: List of agent paths this group can access\n \"\"\"\n try:\n # Set defaults\n if server_access is None:\n server_access = []\n if group_mappings is None:\n group_mappings = [group_name]\n if ui_permissions is None:\n ui_permissions = {\"list_service\": []}\n\n # Update server_access\n self._scopes_data[group_name] = server_access\n\n # Update group_mappings\n if \"group_mappings\" not in self._scopes_data:\n self._scopes_data[\"group_mappings\"] = {}\n self._scopes_data[\"group_mappings\"][group_name] = group_mappings\n\n # Update UI-Scopes\n if \"UI-Scopes\" not in self._scopes_data:\n self._scopes_data[\"UI-Scopes\"] = {}\n self._scopes_data[\"UI-Scopes\"][group_name] = ui_permissions\n\n logger.info(f\"Imported complete group definition for {group_name}\")\n return await self._save_scopes()\n\n except Exception as e:\n logger.error(f\"Failed to import group {group_name}: {e}\", exc_info=True)\n return False\n\n async def get_group(self, group_name: str) -> dict[str, Any]:\n \"\"\"Get full details of a specific group.\"\"\"\n try:\n if group_name not in self._scopes_data:\n logger.warning(f\"Group {group_name} not found in scopes.yml\")\n return None\n\n # Get server_access from main scopes data\n server_access = self._scopes_data.get(group_name, [])\n\n # Get group_mappings\n group_mappings = self._scopes_data.get(\"group_mappings\", {}).get(\n group_name, [group_name]\n )\n\n # Get ui_permissions\n ui_permissions = self._scopes_data.get(\"UI-Scopes\", {}).get(group_name, {})\n\n result = {\n \"scope_name\": group_name,\n \"scope_type\": \"server_scope\",\n \"description\": \"\", # File-based doesn't have separate description field\n \"server_access\": server_access,\n \"group_mappings\": group_mappings,\n \"ui_permissions\": ui_permissions,\n \"created_at\": \"\",\n \"updated_at\": \"\",\n }\n\n logger.info(f\"Retrieved full group details for {group_name} from scopes.yml\")\n return result\n\n except Exception as e:\n logger.error(f\"Failed to get group {group_name}: {e}\", exc_info=True)\n return None\n\n async def list_groups(\n self,\n ) -> dict[str, Any]:\n \"\"\"List all groups with server counts.\"\"\"\n try:\n groups = {}\n\n for key, value in self._scopes_data.items():\n if key in [\"UI-Scopes\", \"group_mappings\"]:\n continue\n\n if isinstance(value, list):\n server_count = len(value)\n server_names = [\n s.get(\"server\", \"unknown\") for s in value if isinstance(s, dict)\n ]\n\n groups[key] = {\n \"name\": key,\n \"server_count\": server_count,\n \"servers\": server_names,\n \"in_mappings\": [],\n }\n\n if \"group_mappings\" in self._scopes_data:\n for mapped_group, mapped_scopes in self._scopes_data[\"group_mappings\"].items():\n for scope in mapped_scopes:\n if scope in groups:\n groups[scope][\"in_mappings\"].append(mapped_group)\n\n logger.info(f\"Found {len(groups)} groups in scopes.yml\")\n\n return {\"total_count\": len(groups), \"groups\": groups}\n\n except Exception as e:\n logger.error(f\"Failed to list groups: {e}\", exc_info=True)\n return {\"total_count\": 0, \"groups\": {}, \"error\": str(e)}\n\n async def group_exists(\n self,\n group_name: str,\n ) -> bool:\n \"\"\"Check if a group exists.\"\"\"\n try:\n return group_name in self._scopes_data\n except Exception as e:\n logger.error(f\"Error checking if group exists: {e}\", exc_info=True)\n return False\n\n async def add_server_to_ui_scopes(\n self,\n group_name: str,\n server_name: str,\n ) -> bool:\n \"\"\"Add server to group's UI scopes list_service.\"\"\"\n try:\n if \"UI-Scopes\" not in self._scopes_data:\n self._scopes_data[\"UI-Scopes\"] = {}\n\n if group_name not in self._scopes_data[\"UI-Scopes\"]:\n self._scopes_data[\"UI-Scopes\"][group_name] = {\"list_service\": []}\n\n if \"list_service\" not in self._scopes_data[\"UI-Scopes\"][group_name]:\n self._scopes_data[\"UI-Scopes\"][group_name][\"list_service\"] = []\n\n if server_name not in self._scopes_data[\"UI-Scopes\"][group_name][\"list_service\"]:\n self._scopes_data[\"UI-Scopes\"][group_name][\"list_service\"].append(server_name)\n logger.info(f\"Added {server_name} to UI-Scopes[{group_name}].list_service\")\n return await self._save_scopes()\n else:\n logger.info(f\"Server {server_name} already in UI-Scopes[{group_name}].list_service\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to add server to UI scopes: {e}\", exc_info=True)\n return False\n\n async def remove_server_from_ui_scopes(\n self,\n group_name: str,\n server_name: str,\n ) -> bool:\n \"\"\"Remove server from group's UI scopes list_service.\"\"\"\n try:\n if \"UI-Scopes\" not in self._scopes_data:\n logger.warning(\"UI-Scopes section not found\")\n return False\n\n if group_name not in self._scopes_data[\"UI-Scopes\"]:\n logger.warning(f\"Group {group_name} not found in UI-Scopes\")\n return False\n\n if \"list_service\" not in self._scopes_data[\"UI-Scopes\"][group_name]:\n logger.warning(f\"list_service not found in UI-Scopes[{group_name}]\")\n return False\n\n if server_name in self._scopes_data[\"UI-Scopes\"][group_name][\"list_service\"]:\n self._scopes_data[\"UI-Scopes\"][group_name][\"list_service\"].remove(server_name)\n logger.info(f\"Removed {server_name} from UI-Scopes[{group_name}].list_service\")\n return await self._save_scopes()\n else:\n logger.warning(\n f\"Server {server_name} not found in UI-Scopes[{group_name}].list_service\"\n )\n return False\n\n except Exception as e:\n logger.error(f\"Failed to remove server from UI scopes: {e}\", exc_info=True)\n return False\n\n async def add_group_mapping(\n self,\n group_name: str,\n scope_name: str,\n ) -> bool:\n \"\"\"Add a scope to group mappings.\"\"\"\n try:\n if \"group_mappings\" not in self._scopes_data:\n self._scopes_data[\"group_mappings\"] = {}\n\n if group_name not in self._scopes_data[\"group_mappings\"]:\n self._scopes_data[\"group_mappings\"][group_name] = []\n\n if scope_name not in self._scopes_data[\"group_mappings\"][group_name]:\n self._scopes_data[\"group_mappings\"][group_name].append(scope_name)\n logger.info(f\"Added scope {scope_name} to group_mappings[{group_name}]\")\n return await self._save_scopes()\n else:\n logger.info(f\"Scope {scope_name} already in group_mappings[{group_name}]\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to add group mapping: {e}\", exc_info=True)\n return False\n\n async def remove_group_mapping(\n self,\n group_name: str,\n scope_name: str,\n ) -> bool:\n \"\"\"Remove a scope from group mappings.\"\"\"\n try:\n if \"group_mappings\" not in self._scopes_data:\n logger.warning(\"group_mappings section not found\")\n return False\n\n if group_name not in self._scopes_data[\"group_mappings\"]:\n logger.warning(f\"Group {group_name} not found in group_mappings\")\n return False\n\n if scope_name in self._scopes_data[\"group_mappings\"][group_name]:\n self._scopes_data[\"group_mappings\"][group_name].remove(scope_name)\n logger.info(f\"Removed scope {scope_name} from group_mappings[{group_name}]\")\n return await self._save_scopes()\n else:\n logger.warning(f\"Scope {scope_name} not found in group_mappings[{group_name}]\")\n return False\n\n except Exception as e:\n logger.error(f\"Failed to remove group mapping: {e}\", exc_info=True)\n return False\n\n async def get_all_group_mappings(\n self,\n ) -> dict[str, list[str]]:\n \"\"\"Get all group mappings.\"\"\"\n try:\n return self._scopes_data.get(\"group_mappings\", {})\n except Exception as e:\n logger.error(f\"Failed to get group mappings: {e}\", exc_info=True)\n return {}\n\n async def add_server_to_multiple_scopes(\n self,\n server_path: str,\n scope_names: list[str],\n methods: list[str],\n tools: list[str],\n ) -> bool:\n \"\"\"Add server to multiple scopes at once.\"\"\"\n try:\n success = True\n for scope_name in scope_names:\n result = await self.add_server_scope(server_path, scope_name, methods, tools)\n if not result:\n logger.warning(f\"Failed to add server {server_path} to scope {scope_name}\")\n success = False\n\n return success\n\n except Exception as e:\n logger.error(f\"Failed to add server to multiple scopes: {e}\", exc_info=True)\n return False\n\n async def remove_server_from_all_scopes(\n self,\n server_path: str,\n ) -> bool:\n \"\"\"Remove server from all scopes.\"\"\"\n try:\n server_name = server_path.lstrip(\"/\")\n\n sections = [\n \"mcp-servers-unrestricted/read\",\n \"mcp-servers-unrestricted/execute\",\n \"mcp-servers-restricted/read\",\n \"mcp-servers-restricted/execute\",\n ]\n\n modified = False\n for section in sections:\n if section in self._scopes_data:\n original_length = len(self._scopes_data[section])\n self._scopes_data[section] = [\n s for s in self._scopes_data[section] if s.get(\"server\") != server_name\n ]\n\n if len(self._scopes_data[section]) < original_length:\n logger.info(f\"Removed server {server_path} from section {section}\")\n modified = True\n\n if modified:\n return await self._save_scopes()\n else:\n logger.warning(f\"Server {server_path} not found in any scope sections\")\n return False\n\n except Exception as e:\n logger.error(f\"Failed to remove server from all scopes: {e}\", exc_info=True)\n return False\n" }, { "path": "registry/repositories/file/search_repository.py", "content": "\"\"\"File-based search repository using FAISS.\"\"\"\n\nimport logging\nfrom typing import Any\n\nfrom ..interfaces import SearchRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass FaissSearchRepository(SearchRepositoryBase):\n \"\"\"FAISS-based search repository.\"\"\"\n\n def __init__(self):\n # Import FaissService lazily to avoid circular imports\n from ...search.service import faiss_service\n\n self.faiss_service = faiss_service\n\n async def index_entity(\n self, entity_path: str, entity_data: dict[str, Any], entity_type: str, is_enabled: bool\n ) -> None:\n \"\"\"Add or update entity in FAISS index.\"\"\"\n await self.faiss_service.add_or_update_entity(\n entity_path=entity_path,\n entity_info=entity_data,\n entity_type=entity_type,\n is_enabled=is_enabled,\n )\n\n async def remove_entity(self, entity_path: str) -> None:\n \"\"\"Remove entity from FAISS index.\"\"\"\n await self.faiss_service.remove_entity(entity_path)\n\n async def search_by_tags(\n self,\n tags: list[str],\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Search entities by exact tag match from FAISS metadata store.\"\"\"\n required = {t.lower() for t in tags}\n results: dict[str, list[dict[str, Any]]] = {\n \"servers\": [],\n \"tools\": [],\n \"agents\": [],\n \"skills\": [],\n \"virtual_servers\": [],\n }\n for path, metadata in self.faiss_service.metadata_store.items():\n entity_tags = {t.lower() for t in metadata.get(\"tags\", [])}\n if not required.issubset(entity_tags):\n continue\n entity_type = metadata.get(\"entity_type\", \"\")\n if entity_types and entity_type not in entity_types:\n continue\n entry = {\n \"path\": path,\n \"server_name\": metadata.get(\"server_name\", metadata.get(\"name\", \"\")),\n \"description\": metadata.get(\"description\", \"\"),\n \"tags\": metadata.get(\"tags\", []),\n \"is_enabled\": metadata.get(\"is_enabled\", False),\n \"relevance_score\": 1.0,\n \"match_context\": metadata.get(\"description\", \"\"),\n \"matching_tools\": [],\n }\n if entity_type == \"mcp_server\":\n entry[\"num_tools\"] = metadata.get(\"num_tools\", 0)\n results[\"servers\"].append(entry)\n elif entity_type == \"a2a_agent\":\n results[\"agents\"].append(entry)\n elif entity_type == \"skill\":\n entry[\"skill_name\"] = metadata.get(\"name\", \"\")\n results[\"skills\"].append(entry)\n elif entity_type == \"virtual_server\":\n results[\"virtual_servers\"].append(entry)\n # Limit each group\n for key in results:\n results[key] = results[key][:max_results]\n return results\n\n async def get_all_tags(self) -> list[str]:\n \"\"\"Return a sorted list of all unique tags from the FAISS metadata store.\"\"\"\n tags_set: set[str] = set()\n for metadata in self.faiss_service.metadata_store.values():\n for tag in metadata.get(\"tags\", []):\n if tag:\n tags_set.add(tag)\n return sorted(tags_set, key=str.lower)\n\n async def search(\n self,\n query: str,\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Search entities using FAISS.\n\n Args:\n query: Search query text\n entity_types: Optional list of entity types to filter by (e.g., [\"mcp_server\", \"tool\", \"a2a_agent\"])\n max_results: Maximum number of results per entity type\n\n Returns:\n Dictionary with entity types as keys and lists of results as values\n \"\"\"\n return await self.faiss_service.search_mixed(\n query=query, entity_types=entity_types, max_results=max_results\n )\n\n async def rebuild_index(self) -> None:\n \"\"\"Rebuild FAISS index from scratch.\"\"\"\n await self.faiss_service.rebuild_index()\n\n async def initialize(self) -> None:\n \"\"\"Initialize the search repository.\"\"\"\n # Explicitly initialize the shared FAISS service used by this repository.\n await self.faiss_service.initialize()\n\n async def index_server(\n self, server_path: str, server_data: dict[str, Any], is_enabled: bool\n ) -> None:\n \"\"\"Index a server.\"\"\"\n await self.index_entity(server_path, server_data, \"mcp_server\", is_enabled)\n\n async def index_agent(\n self, agent_path: str, agent_data: dict[str, Any], is_enabled: bool\n ) -> None:\n \"\"\"Index an agent.\"\"\"\n await self.index_entity(agent_path, agent_data, \"a2a_agent\", is_enabled)\n" }, { "path": "registry/repositories/file/security_scan_repository.py", "content": "\"\"\"\nFile-based repository for security scan results storage.\n\nReads security scan results from ~/mcp-gateway/security_scans/*.json files.\n\"\"\"\n\nimport json\nimport logging\nfrom pathlib import Path\nfrom typing import Any\n\nfrom ..interfaces import SecurityScanRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass FileSecurityScanRepository(SecurityScanRepositoryBase):\n \"\"\"File-based implementation of security scan repository.\"\"\"\n\n def __init__(self):\n self._scans: dict[str, dict[str, Any]] = {}\n self._scans_dir = Path.home() / \"mcp-gateway\" / \"security_scans\"\n\n async def load_all(self) -> None:\n \"\"\"Load all security scan results from disk.\"\"\"\n logger.info(f\"Loading security scans from {self._scans_dir}...\")\n\n if not self._scans_dir.exists():\n logger.info(f\"Security scans directory does not exist: {self._scans_dir}\")\n self._scans = {}\n return\n\n try:\n self._scans = {}\n scan_files = list(self._scans_dir.glob(\"*.json\"))\n logger.info(f\"Found {len(scan_files)} scan files\")\n\n for scan_file in scan_files:\n try:\n with open(scan_file) as f:\n scan_data = json.load(f)\n\n if isinstance(scan_data, dict) and \"server_path\" in scan_data:\n server_path = scan_data[\"server_path\"]\n self._scans[server_path] = scan_data\n else:\n logger.warning(f\"Invalid scan file format: {scan_file}\")\n\n except Exception as e:\n logger.error(f\"Error loading scan file {scan_file}: {e}\", exc_info=True)\n\n logger.info(f\"Loaded {len(self._scans)} security scan results\")\n\n except Exception as e:\n logger.error(f\"Failed to load security scans: {e}\", exc_info=True)\n self._scans = {}\n\n async def get(\n self,\n server_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest security scan result for a server.\"\"\"\n return self._scans.get(server_path)\n\n async def list_all(self) -> list[dict[str, Any]]:\n \"\"\"List all security scan results.\"\"\"\n return list(self._scans.values())\n\n async def create(\n self,\n scan_result: dict[str, Any],\n ) -> bool:\n \"\"\"Create/update a security scan result.\"\"\"\n try:\n if \"server_path\" not in scan_result:\n logger.error(\"Scan result must contain 'server_path' field\")\n return False\n\n server_path = scan_result[\"server_path\"]\n self._scans[server_path] = scan_result\n\n self._scans_dir.mkdir(parents=True, exist_ok=True)\n\n sanitized_path = server_path.lstrip(\"/\").replace(\"/\", \"_\")\n scan_file = self._scans_dir / f\"{sanitized_path}_scan.json\"\n\n with open(scan_file, \"w\") as f:\n json.dump(scan_result, f, indent=2)\n\n logger.info(f\"Saved security scan for {server_path} to {scan_file}\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to save security scan: {e}\", exc_info=True)\n return False\n\n async def get_latest(\n self,\n server_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest scan result for a server.\"\"\"\n return await self.get(server_path)\n\n async def query_by_status(\n self,\n status: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Query scan results by status.\"\"\"\n return [scan for scan in self._scans.values() if scan.get(\"scan_status\") == status]\n" }, { "path": "registry/repositories/file/server_repository.py", "content": "\"\"\"\nFile-based repository for MCP server storage.\n\nExtracts all file I/O logic from ServerService while maintaining identical behavior.\n\"\"\"\n\nimport json\nimport logging\nfrom typing import Any\n\nfrom ...core.config import settings\nfrom ..interfaces import ServerRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass FileServerRepository(ServerRepositoryBase):\n \"\"\"File-based implementation of server repository.\"\"\"\n\n def __init__(self):\n self._servers: dict[str, dict[str, Any]] = {}\n self._state: dict[str, bool] = {}\n\n async def load_all(self) -> None:\n \"\"\"Load server definitions and state from disk.\"\"\"\n logger.info(f\"Loading server definitions from {settings.servers_dir}...\")\n\n settings.servers_dir.mkdir(parents=True, exist_ok=True)\n\n temp_servers = {}\n server_files = list(settings.servers_dir.glob(\"**/*.json\"))\n logger.info(f\"Found {len(server_files)} JSON files\")\n\n for server_file in server_files:\n if server_file.name == settings.state_file_path.name:\n continue\n\n try:\n with open(server_file) as f:\n server_info = json.load(f)\n\n if (\n isinstance(server_info, dict)\n and \"path\" in server_info\n and \"server_name\" in server_info\n ):\n server_path = server_info[\"path\"]\n if server_path in temp_servers:\n logger.warning(f\"Duplicate server path in {server_file}: {server_path}\")\n\n server_info.setdefault(\"description\", \"\")\n server_info.setdefault(\"tags\", [])\n server_info.setdefault(\"num_tools\", 0)\n server_info.setdefault(\"license\", \"N/A\")\n server_info.setdefault(\"proxy_pass_url\", None)\n server_info.setdefault(\"tool_list\", [])\n\n temp_servers[server_path] = server_info\n else:\n logger.warning(f\"Invalid server entry in {server_file}\")\n except Exception as e:\n logger.error(f\"Error loading {server_file}: {e}\", exc_info=True)\n\n self._servers = temp_servers\n logger.info(f\"Loaded {len(self._servers)} server definitions\")\n\n await self._load_state()\n\n async def _load_state(self) -> None:\n \"\"\"Load persisted service state from disk.\"\"\"\n logger.info(f\"Loading state from {settings.state_file_path}...\")\n loaded_state = {}\n\n try:\n if settings.state_file_path.exists():\n with open(settings.state_file_path) as f:\n loaded_state = json.load(f)\n if not isinstance(loaded_state, dict):\n logger.warning(\"Invalid state format, resetting\")\n loaded_state = {}\n else:\n logger.info(\"Successfully loaded persisted state\")\n else:\n logger.info(\"No state file found, initializing\")\n except Exception as e:\n logger.error(f\"Failed to read state file: {e}\", exc_info=True)\n loaded_state = {}\n\n self._state = {}\n for path in self._servers.keys():\n value = loaded_state.get(path)\n if value is None:\n if path.endswith(\"/\"):\n value = loaded_state.get(path.rstrip(\"/\"), False)\n else:\n value = loaded_state.get(path + \"/\", False)\n self._state[path] = value\n\n logger.info(f\"Initial service state loaded: {self._state}\")\n\n async def _save_state(self) -> None:\n \"\"\"Persist service state to disk.\"\"\"\n try:\n with open(settings.state_file_path, \"w\") as f:\n json.dump(self._state, f, indent=2)\n logger.info(f\"Persisted state to {settings.state_file_path}\")\n except Exception as e:\n logger.error(f\"Failed to persist state: {e}\")\n\n def _path_to_filename(\n self,\n path: str,\n ) -> str:\n \"\"\"Convert path to safe filename.\"\"\"\n normalized = path.lstrip(\"/\").replace(\"/\", \"_\")\n if not normalized.endswith(\".json\"):\n normalized += \".json\"\n return normalized\n\n async def _save_to_file(\n self,\n server_info: dict[str, Any],\n ) -> bool:\n \"\"\"Save server data to individual file.\"\"\"\n try:\n settings.servers_dir.mkdir(parents=True, exist_ok=True)\n\n path = server_info[\"path\"]\n filename = self._path_to_filename(path)\n file_path = settings.servers_dir / filename\n\n with open(file_path, \"w\") as f:\n json.dump(server_info, f, indent=2)\n\n logger.info(f\"Saved server '{server_info['server_name']}' to {file_path}\")\n return True\n except Exception as e:\n logger.error(f\"Failed to save server: {e}\", exc_info=True)\n return False\n\n async def get(\n self,\n path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get server by path.\"\"\"\n server_info = self._servers.get(path)\n if server_info:\n return server_info\n\n if path.endswith(\"/\"):\n alternate_path = path.rstrip(\"/\")\n else:\n alternate_path = path + \"/\"\n\n return self._servers.get(alternate_path)\n\n async def list_all(self) -> dict[str, dict[str, Any]]:\n \"\"\"List all servers.\"\"\"\n return self._servers.copy()\n\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"List servers with in-memory pagination (file backend).\n\n Args:\n skip: Number of servers to skip.\n limit: Maximum number of servers to return.\n\n Returns:\n Dictionary mapping server path to server info for the requested page.\n \"\"\"\n items = list(self._servers.items())\n page_items = items[skip : skip + limit]\n return dict(page_items)\n\n async def list_by_source(\n self,\n source: str,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"List all servers from a specific federation source.\n\n Args:\n source: Federation source identifier (e.g., \"anthropic\")\n\n Returns:\n Dictionary mapping server path to server info\n \"\"\"\n return {path: info for path, info in self._servers.items() if info.get(\"source\") == source}\n\n async def create(\n self,\n server_info: dict[str, Any],\n ) -> bool:\n \"\"\"Create a new server.\"\"\"\n path = server_info[\"path\"]\n\n if path in self._servers:\n logger.error(f\"Server path '{path}' already exists\")\n return False\n\n if not await self._save_to_file(server_info):\n return False\n\n self._servers[path] = server_info\n self._state[path] = False\n\n await self._save_state()\n\n logger.info(f\"New server registered: '{server_info['server_name']}' at '{path}'\")\n return True\n\n async def update(\n self,\n path: str,\n server_info: dict[str, Any],\n ) -> bool:\n \"\"\"Update an existing server.\"\"\"\n if path not in self._servers:\n logger.error(f\"Cannot update server at '{path}': not found\")\n return False\n\n server_info[\"path\"] = path\n\n if not await self._save_to_file(server_info):\n return False\n\n self._servers[path] = server_info\n\n logger.info(f\"Server '{server_info['server_name']}' ({path}) updated\")\n return True\n\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a server.\"\"\"\n if path not in self._servers:\n logger.error(f\"Cannot delete server at '{path}': not found\")\n return False\n\n try:\n filename = self._path_to_filename(path)\n file_path = settings.servers_dir / filename\n\n if file_path.exists():\n file_path.unlink()\n logger.info(f\"Removed server file: {file_path}\")\n else:\n logger.warning(f\"Server file not found: {file_path}\")\n\n server_name = self._servers[path].get(\"server_name\", \"Unknown\")\n del self._servers[path]\n\n if path in self._state:\n del self._state[path]\n\n await self._save_state()\n\n logger.info(f\"Successfully removed server '{server_name}' from '{path}'\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to remove server at '{path}': {e}\", exc_info=True)\n return False\n\n async def delete_with_versions(\n self,\n path: str,\n ) -> int:\n \"\"\"Delete a server and all its version documents.\n\n Deletes the active document at `path` and any version documents\n with keys matching `{path}:{version}`.\n\n Args:\n path: Server base path (e.g., \"/context7\")\n\n Returns:\n Number of documents deleted (0 if none found)\n \"\"\"\n deleted_count = 0\n\n # Find all keys that match: exact path or path:version pattern\n version_prefix = f\"{path}:\"\n keys_to_delete = []\n for key in list(self._servers.keys()):\n if key == path or key.startswith(version_prefix):\n keys_to_delete.append(key)\n\n for key in keys_to_delete:\n # Remove the server file from disk\n filename = self._path_to_filename(key)\n file_path = settings.servers_dir / filename\n if file_path.exists():\n file_path.unlink()\n logger.info(\"Removed server file: %s\", file_path)\n\n # Remove from in-memory dicts\n del self._servers[key]\n if key in self._state:\n del self._state[key]\n deleted_count += 1\n\n if deleted_count > 0:\n await self._save_state()\n logger.info(\n \"delete_with_versions: removed %d document(s) for path '%s'\",\n deleted_count,\n path,\n )\n\n return deleted_count\n\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get server enabled/disabled state.\"\"\"\n result = self._state.get(path)\n\n if result is None:\n if path.endswith(\"/\"):\n result = self._state.get(path.rstrip(\"/\"), False)\n else:\n result = self._state.get(path + \"/\", False)\n\n if result is None:\n result = False\n\n return result\n\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set server enabled/disabled state.\"\"\"\n if path not in self._servers:\n logger.error(f\"Cannot toggle service at '{path}': not found\")\n return False\n\n self._state[path] = enabled\n await self._save_state()\n\n server_name = self._servers[path][\"server_name\"]\n logger.info(f\"Toggled '{server_name}' ({path}) to {enabled}\")\n\n return True\n\n async def count(self) -> int:\n \"\"\"Get total count of servers.\n\n Returns:\n Total number of servers in the repository.\n \"\"\"\n return len(self._servers)\n\n async def update_field(\n self,\n path: str,\n field: str,\n value: Any,\n ) -> bool:\n \"\"\"Update a single field on a document (file-based).\"\"\"\n data = await self.get(path)\n if not data:\n return False\n\n if value is None:\n parts = field.split(\".\")\n obj = data\n for part in parts[:-1]:\n obj = obj.get(part, {})\n obj.pop(parts[-1], None)\n else:\n parts = field.split(\".\")\n obj = data\n for part in parts[:-1]:\n if part not in obj:\n obj[part] = {}\n obj = obj[part]\n obj[parts[-1]] = value\n\n await self._save_to_file(data)\n self._servers[path] = data\n return True\n\n async def find_with_filter(\n self,\n filter_dict: dict[str, Any],\n ) -> dict[str, dict]:\n \"\"\"Find documents matching a filter (file-based, basic support).\"\"\"\n all_data = await self.list_all()\n results = {}\n for path, data in all_data.items():\n match = True\n for field_name, condition in filter_dict.items():\n if isinstance(condition, dict) and \"$exists\" in condition:\n has_field = data.get(field_name) is not None\n if condition.get(\"$ne\") is not None:\n has_field = has_field and data.get(field_name) != condition[\"$ne\"]\n if condition[\"$exists\"] != has_field:\n match = False\n break\n if match:\n results[path] = data\n return results\n" }, { "path": "registry/repositories/file/skill_security_scan_repository.py", "content": "\"\"\"\nFile-based repository for skill security scan results storage.\n\nReads skill security scan results from ~/mcp-gateway/skill_security_scans/*.json files.\n\"\"\"\n\nimport json\nimport logging\nfrom pathlib import Path\nfrom typing import Any\n\nfrom ..interfaces import SkillSecurityScanRepositoryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass FileSkillSecurityScanRepository(SkillSecurityScanRepositoryBase):\n \"\"\"File-based implementation of skill security scan repository.\"\"\"\n\n def __init__(self):\n self._scans: dict[str, dict[str, Any]] = {}\n self._scans_dir = Path.home() / \"mcp-gateway\" / \"skill_security_scans\"\n\n async def load_all(self) -> None:\n \"\"\"Load all skill security scan results from disk.\"\"\"\n logger.info(f\"Loading skill security scans from {self._scans_dir}...\")\n\n if not self._scans_dir.exists():\n logger.info(f\"Skill security scans directory does not exist: {self._scans_dir}\")\n self._scans = {}\n return\n\n try:\n self._scans = {}\n scan_files = list(self._scans_dir.glob(\"*.json\"))\n logger.info(f\"Found {len(scan_files)} skill scan files\")\n\n for scan_file in scan_files:\n try:\n with open(scan_file) as f:\n scan_data = json.load(f)\n\n if isinstance(scan_data, dict) and \"skill_path\" in scan_data:\n skill_path = scan_data[\"skill_path\"]\n self._scans[skill_path] = scan_data\n else:\n logger.warning(f\"Invalid skill scan file format: {scan_file}\")\n\n except Exception as e:\n logger.error(f\"Error loading skill scan file {scan_file}: {e}\", exc_info=True)\n\n logger.info(f\"Loaded {len(self._scans)} skill security scan results\")\n\n except Exception as e:\n logger.error(f\"Failed to load skill security scans: {e}\", exc_info=True)\n self._scans = {}\n\n async def get(\n self,\n skill_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest security scan result for a skill.\"\"\"\n return self._scans.get(skill_path)\n\n async def list_all(self) -> list[dict[str, Any]]:\n \"\"\"List all skill security scan results.\"\"\"\n return list(self._scans.values())\n\n async def create(\n self,\n scan_result: dict[str, Any],\n ) -> bool:\n \"\"\"Create/update a skill security scan result.\"\"\"\n try:\n if \"skill_path\" not in scan_result:\n logger.error(\"Scan result must contain 'skill_path' field\")\n return False\n\n skill_path = scan_result[\"skill_path\"]\n self._scans[skill_path] = scan_result\n\n self._scans_dir.mkdir(parents=True, exist_ok=True)\n\n sanitized_path = skill_path.lstrip(\"/\").replace(\"/\", \"_\")\n scan_file = self._scans_dir / f\"{sanitized_path}_scan.json\"\n\n with open(scan_file, \"w\") as f:\n json.dump(scan_result, f, indent=2)\n\n logger.info(f\"Saved skill security scan for {skill_path} to {scan_file}\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to save skill security scan: {e}\", exc_info=True)\n return False\n\n async def get_latest(\n self,\n skill_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get latest scan result for a skill.\"\"\"\n return await self.get(skill_path)\n\n async def query_by_status(\n self,\n status: str,\n ) -> list[dict[str, Any]]:\n \"\"\"Query scan results by status.\"\"\"\n return [scan for scan in self._scans.values() if scan.get(\"scan_status\") == status]\n" }, { "path": "registry/repositories/interfaces.py", "content": "\"\"\"\nRepository base classes for data access abstraction.\n\nThese abstract base classes define the contract that ALL repository implementations must follow.\n\"\"\"\n\nfrom abc import ABC, abstractmethod\nfrom typing import Any\n\nfrom ..schemas.agent_models import AgentCard\nfrom ..schemas.federation_schema import FederationConfig\nfrom ..schemas.registry_card import RegistryCard\n\n# Import skill models with try/except to avoid circular import issues\ntry:\n from ..schemas.skill_models import SkillCard\nexcept ImportError:\n SkillCard = None\n\ntry:\n from ..schemas.virtual_server_models import VirtualServerConfig\nexcept ImportError:\n VirtualServerConfig = None\n\n\nclass ServerRepositoryBase(ABC):\n \"\"\"Abstract base class for MCP server data access.\"\"\"\n\n @abstractmethod\n async def get(\n self,\n path: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get server by path.\"\"\"\n pass\n\n @abstractmethod\n async def list_all(self) -> dict[str, dict[str, Any]]:\n \"\"\"List all servers.\"\"\"\n pass\n\n @abstractmethod\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"List servers with DB-level pagination.\n\n Args:\n skip: Number of documents to skip.\n limit: Maximum number of documents to return.\n\n Returns:\n Dictionary mapping server path to server info for the requested page.\n \"\"\"\n pass\n\n @abstractmethod\n async def list_by_source(\n self,\n source: str,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"List all servers from a specific federation source.\n\n Args:\n source: Federation source identifier (e.g., \"anthropic\")\n\n Returns:\n Dictionary mapping server path to server info\n \"\"\"\n pass\n\n @abstractmethod\n async def create(\n self,\n server_info: dict[str, Any],\n ) -> bool:\n \"\"\"Create a new server.\"\"\"\n pass\n\n @abstractmethod\n async def update(\n self,\n path: str,\n server_info: dict[str, Any],\n ) -> bool:\n \"\"\"Update an existing server.\"\"\"\n pass\n\n @abstractmethod\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a server.\"\"\"\n pass\n\n @abstractmethod\n async def delete_with_versions(\n self,\n path: str,\n ) -> int:\n \"\"\"Delete a server and all its version documents.\n\n Deletes the active document at `path` and any version documents\n with IDs matching `{path}:{version}`.\n\n Args:\n path: Server base path (e.g., \"/context7\")\n\n Returns:\n Number of documents deleted (0 if none found)\n \"\"\"\n pass\n\n @abstractmethod\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get server enabled/disabled state.\"\"\"\n pass\n\n @abstractmethod\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set server enabled/disabled state.\"\"\"\n pass\n\n @abstractmethod\n async def load_all(self) -> None:\n \"\"\"Load/reload all servers from storage.\"\"\"\n pass\n\n @abstractmethod\n async def count(self) -> int:\n \"\"\"Get total count of servers.\n\n Returns:\n Total number of servers in the repository.\n \"\"\"\n pass\n\n @abstractmethod\n async def update_field(\n self,\n path: str,\n field: str,\n value: Any,\n ) -> bool:\n \"\"\"Update a single field on a document.\n\n Args:\n path: Document path/ID\n field: Field name (supports dot notation for nested fields)\n value: New value (None to unset the field)\n\n Returns:\n True if document was found and updated\n \"\"\"\n ...\n\n @abstractmethod\n async def find_with_filter(\n self,\n filter_dict: dict[str, Any],\n ) -> dict[str, dict]:\n \"\"\"Find documents matching a MongoDB-style filter.\n\n Args:\n filter_dict: MongoDB-style filter\n\n Returns:\n Dict mapping path -> document data for matching documents\n \"\"\"\n ...\n\n\nclass AgentRepositoryBase(ABC):\n \"\"\"Abstract base class for A2A agent data access.\"\"\"\n\n @abstractmethod\n async def get(\n self,\n path: str,\n ) -> AgentCard | None:\n \"\"\"Get agent by path.\"\"\"\n pass\n\n @abstractmethod\n async def list_all(self) -> list[AgentCard]:\n \"\"\"List all agents.\"\"\"\n pass\n\n @abstractmethod\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> list[AgentCard]:\n \"\"\"List agents with DB-level pagination.\n\n Args:\n skip: Number of documents to skip.\n limit: Maximum number of documents to return.\n\n Returns:\n List of AgentCard objects for the requested page.\n \"\"\"\n pass\n\n @abstractmethod\n async def create(\n self,\n agent: AgentCard,\n ) -> AgentCard:\n \"\"\"Create a new agent.\"\"\"\n pass\n\n @abstractmethod\n async def update(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> AgentCard:\n \"\"\"Update an existing agent.\"\"\"\n pass\n\n @abstractmethod\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete an agent.\"\"\"\n pass\n\n @abstractmethod\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get agent enabled/disabled state.\"\"\"\n pass\n\n @abstractmethod\n async def get_all_states(self) -> dict[str, bool]:\n \"\"\"Get enabled/disabled state for all agents in a single query.\n\n Returns:\n Dict mapping agent path to enabled (True) or disabled (False).\n \"\"\"\n pass\n\n @abstractmethod\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set agent enabled/disabled state.\"\"\"\n pass\n\n @abstractmethod\n async def load_all(self) -> None:\n \"\"\"Load/reload all agents from storage.\"\"\"\n pass\n\n @abstractmethod\n async def count(self) -> int:\n \"\"\"Get total count of agents.\n\n Returns:\n Total number of agents in the repository.\n \"\"\"\n pass\n\n @abstractmethod\n async def update_field(\n self,\n path: str,\n field: str,\n value: Any,\n ) -> bool:\n \"\"\"Update a single field on a document.\n\n Args:\n path: Document path/ID\n field: Field name (supports dot notation for nested fields)\n value: New value (None to unset the field)\n\n Returns:\n True if document was found and updated\n \"\"\"\n ...\n\n @abstractmethod\n async def find_with_filter(\n self,\n filter_dict: dict[str, Any],\n ) -> dict[str, dict]:\n \"\"\"Find documents matching a MongoDB-style filter.\n\n Args:\n filter_dict: MongoDB-style filter\n\n Returns:\n Dict mapping path -> document data for matching documents\n \"\"\"\n ...\n\n\nclass ScopeRepositoryBase(ABC):\n \"\"\"\n Abstract base class for authorization scopes data access.\n\n Implementations:\n - FileScopeRepository: reads auth_server/scopes.yml\n - DocumentDBScopeRepository: reads mcp-scopes collection\n \"\"\"\n\n @abstractmethod\n async def get_ui_scopes(\n self,\n group_name: str,\n ) -> dict[str, Any]:\n \"\"\"\n Get UI scopes for a Keycloak group.\n\n Args:\n group_name: Keycloak group name (e.g., \"mcp-registry-admin\")\n\n Returns:\n Dict with \"agent_actions\", \"service_actions\", \"allowed_agents\",\n \"allowed_servers\" keys. Returns empty dict if group not found.\n \"\"\"\n pass\n\n @abstractmethod\n async def get_group_mappings(\n self,\n keycloak_group: str,\n ) -> list[str]:\n \"\"\"\n Get scope names mapped to a Keycloak group.\n\n Args:\n keycloak_group: Keycloak group name\n\n Returns:\n List of scope names. Returns empty list if group not found.\n \"\"\"\n pass\n\n @abstractmethod\n async def get_server_scopes(\n self,\n scope_name: str,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Get server access rules for a scope.\n\n Args:\n scope_name: Scope name (e.g., \"mcp-servers-unrestricted/read\")\n\n Returns:\n List of dicts with \"server\", \"methods\", \"tools\" keys.\n Returns empty list if scope not found.\n \"\"\"\n pass\n\n @abstractmethod\n async def load_all(self) -> None:\n \"\"\"\n Load/reload all scopes from storage.\n Called once at application startup.\n \"\"\"\n pass\n\n @abstractmethod\n async def add_server_scope(\n self,\n server_path: str,\n scope_name: str,\n methods: list[str],\n tools: list[str] | None = None,\n ) -> bool:\n \"\"\"\n Add scope for a server.\n\n Args:\n server_path: Server path (e.g., \"/currenttime\")\n scope_name: Scope name\n methods: Allowed methods\n tools: Allowed tools (None = all tools)\n\n Returns:\n True if added successfully\n \"\"\"\n pass\n\n @abstractmethod\n async def remove_server_scope(\n self,\n server_path: str,\n scope_name: str,\n ) -> bool:\n \"\"\"\n Remove scope for a server.\n\n Args:\n server_path: Server path\n scope_name: Scope name to remove\n\n Returns:\n True if removed successfully\n \"\"\"\n pass\n\n @abstractmethod\n async def create_group(\n self,\n group_name: str,\n description: str = \"\",\n ) -> bool:\n \"\"\"\n Create a new group in scopes.\n\n Args:\n group_name: Name of the group to create\n description: Optional description for the group\n\n Returns:\n True if created successfully\n\n Note:\n This creates entries in both UI-Scopes and group_mappings sections.\n \"\"\"\n pass\n\n @abstractmethod\n async def delete_group(\n self,\n group_name: str,\n remove_from_mappings: bool = True,\n ) -> bool:\n \"\"\"\n Delete a group from scopes.\n\n Args:\n group_name: Name of the group to delete\n remove_from_mappings: If True, also remove from group_mappings\n\n Returns:\n True if deleted successfully\n\n Note:\n This removes the group's scope section and optionally its mappings.\n \"\"\"\n pass\n\n @abstractmethod\n async def get_group(self, group_name: str) -> dict[str, Any]:\n \"\"\"\n Get full details of a specific group.\n\n Args:\n group_name: Name of the group\n\n Returns:\n Dictionary with complete group information including:\n - scope_name: Name of the scope/group\n - scope_type: Type of scope (e.g., \"server_scope\")\n - description: Description of the group\n - server_access: List of server access definitions\n - group_mappings: List of group mappings\n - ui_permissions: UI permissions configuration\n - created_at: Creation timestamp\n - updated_at: Last update timestamp\n\n Returns None if group not found.\n \"\"\"\n pass\n\n async def list_groups(self) -> dict[str, Any]:\n \"\"\"\n List all groups with server counts.\n\n Returns:\n Dictionary mapping group names to their metadata including:\n - server_count: Number of servers in the group\n - ui_scopes: UI permission configuration\n - mappings: List of scope names mapped to this group\n\n Example:\n {\n \"mcp-registry-admin\": {\n \"server_count\": 5,\n \"ui_scopes\": {\"list_agents\": [\"all\"]},\n \"mappings\": [\"mcp-registry-admin\", \"mcp-servers-unrestricted/read\"]\n }\n }\n \"\"\"\n return {}\n\n @abstractmethod\n async def group_exists(\n self,\n group_name: str,\n ) -> bool:\n \"\"\"\n Check if a group exists.\n\n Args:\n group_name: Name of the group to check\n\n Returns:\n True if group exists, False otherwise\n \"\"\"\n pass\n\n @abstractmethod\n async def add_server_to_ui_scopes(\n self,\n group_name: str,\n server_name: str,\n ) -> bool:\n \"\"\"\n Add server to group's UI scopes list_service.\n\n Args:\n group_name: Name of the group\n server_name: Name of the server to add\n\n Returns:\n True if added successfully\n\n Note:\n This updates the UI-Scopes section to allow the server\n to appear in the UI for users in this group.\n \"\"\"\n pass\n\n @abstractmethod\n async def remove_server_from_ui_scopes(\n self,\n group_name: str,\n server_name: str,\n ) -> bool:\n \"\"\"\n Remove server from group's UI scopes list_service.\n\n Args:\n group_name: Name of the group\n server_name: Name of the server to remove\n\n Returns:\n True if removed successfully\n\n Note:\n This updates the UI-Scopes section to hide the server\n from the UI for users in this group.\n \"\"\"\n pass\n\n @abstractmethod\n async def add_group_mapping(\n self,\n group_name: str,\n scope_name: str,\n ) -> bool:\n \"\"\"\n Add a scope to group mappings.\n\n Args:\n group_name: Name of the group\n scope_name: Name of the scope to map to the group\n\n Returns:\n True if added successfully\n\n Note:\n This updates the group_mappings section to associate\n a scope with a Keycloak group.\n \"\"\"\n pass\n\n @abstractmethod\n async def remove_group_mapping(\n self,\n group_name: str,\n scope_name: str,\n ) -> bool:\n \"\"\"\n Remove a scope from group mappings.\n\n Args:\n group_name: Name of the group\n scope_name: Name of the scope to remove from the group\n\n Returns:\n True if removed successfully\n\n Note:\n This updates the group_mappings section to disassociate\n a scope from a Keycloak group.\n \"\"\"\n pass\n\n @abstractmethod\n async def get_all_group_mappings(self) -> dict[str, list[str]]:\n \"\"\"\n Get all group mappings.\n\n Returns:\n Dictionary mapping group names to lists of scope names.\n\n Example:\n {\n \"mcp-registry-admin\": [\n \"mcp-registry-admin\",\n \"mcp-servers-unrestricted/read\"\n ],\n \"mcp-registry-user\": [\n \"mcp-servers-unrestricted/read\"\n ]\n }\n \"\"\"\n pass\n\n @abstractmethod\n async def add_server_to_multiple_scopes(\n self,\n server_path: str,\n scope_names: list[str],\n methods: list[str],\n tools: list[str],\n ) -> bool:\n \"\"\"\n Add server to multiple scopes at once.\n\n Args:\n server_path: Server path (e.g., \"/currenttime\")\n scope_names: List of scope names to add the server to\n methods: Allowed methods for all scopes\n tools: Allowed tools for all scopes\n\n Returns:\n True if added successfully to all scopes\n\n Note:\n This is a bulk operation that atomically adds a server\n to multiple scope groups with the same permissions.\n \"\"\"\n pass\n\n @abstractmethod\n async def remove_server_from_all_scopes(\n self,\n server_path: str,\n ) -> bool:\n \"\"\"\n Remove server from all scopes.\n\n Args:\n server_path: Server path to remove\n\n Returns:\n True if removed successfully from all scopes\n\n Note:\n This is used during server deletion to clean up all\n scope references to the server.\n \"\"\"\n pass\n\n\nclass SecurityScanRepositoryBase(ABC):\n \"\"\"\n Abstract base class for security scan results data access.\n\n Implementations:\n - FileSecurityScanRepository: reads ~/mcp-gateway/security_scans/*.json\n - DocumentDBSecurityScanRepository: reads mcp-security-scans collection\n \"\"\"\n\n @abstractmethod\n async def get(\n self,\n server_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"\n Get latest security scan result for a server.\n\n Args:\n server_path: Server path (e.g., \"/currenttime\")\n\n Returns:\n Security scan result dict if found, None otherwise.\n \"\"\"\n pass\n\n @abstractmethod\n async def list_all(self) -> list[dict[str, Any]]:\n \"\"\"\n List all security scan results.\n\n Returns:\n List of all security scan result dicts.\n \"\"\"\n pass\n\n @abstractmethod\n async def create(\n self,\n scan_result: dict[str, Any],\n ) -> bool:\n \"\"\"\n Create/update a security scan result.\n\n Args:\n scan_result: Security scan result dict. Must contain \"server_path\".\n\n Returns:\n True if created successfully.\n \"\"\"\n pass\n\n @abstractmethod\n async def get_latest(\n self,\n server_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"\n Get latest scan result for a server.\n\n Args:\n server_path: Server path\n\n Returns:\n Latest scan result if found, None otherwise.\n \"\"\"\n pass\n\n @abstractmethod\n async def query_by_status(\n self,\n status: str,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Query scan results by status.\n\n Args:\n status: Scan status (e.g., \"passed\", \"failed\", \"error\")\n\n Returns:\n List of scan results with the given status.\n \"\"\"\n pass\n\n @abstractmethod\n async def load_all(self) -> None:\n \"\"\"\n Load/reload all security scan results from storage.\n Called once at application startup.\n \"\"\"\n pass\n\n\nclass SkillSecurityScanRepositoryBase(ABC):\n \"\"\"\n Abstract base class for skill security scan results data access.\n\n Implementations:\n - FileSkillSecurityScanRepository: reads ~/mcp-gateway/skill_security_scans/*.json\n - DocumentDBSkillSecurityScanRepository: reads mcp-skill-security-scans collection\n \"\"\"\n\n @abstractmethod\n async def get(\n self,\n skill_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"\n Get latest security scan result for a skill.\n\n Args:\n skill_path: Skill path (e.g., \"/skills/pdf-processing\")\n\n Returns:\n Security scan result dict if found, None otherwise.\n \"\"\"\n pass\n\n @abstractmethod\n async def list_all(self) -> list[dict[str, Any]]:\n \"\"\"\n List all skill security scan results.\n\n Returns:\n List of all skill security scan result dicts.\n \"\"\"\n pass\n\n @abstractmethod\n async def create(\n self,\n scan_result: dict[str, Any],\n ) -> bool:\n \"\"\"\n Create/update a skill security scan result.\n\n Args:\n scan_result: Skill security scan result dict. Must contain \"skill_path\".\n\n Returns:\n True if created successfully.\n \"\"\"\n pass\n\n @abstractmethod\n async def get_latest(\n self,\n skill_path: str,\n ) -> dict[str, Any] | None:\n \"\"\"\n Get latest scan result for a skill.\n\n Args:\n skill_path: Skill path\n\n Returns:\n Latest scan result if found, None otherwise.\n \"\"\"\n pass\n\n @abstractmethod\n async def query_by_status(\n self,\n status: str,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Query scan results by status.\n\n Args:\n status: Scan status (e.g., \"completed\", \"failed\", \"pending\")\n\n Returns:\n List of scan results with the given status.\n \"\"\"\n pass\n\n @abstractmethod\n async def load_all(self) -> None:\n \"\"\"\n Load/reload all skill security scan results from storage.\n Called once at application startup.\n \"\"\"\n pass\n\n\nclass SearchRepositoryBase(ABC):\n \"\"\"Abstract base class for semantic/hybrid search using FAISS or DocumentDB.\"\"\"\n\n @abstractmethod\n async def initialize(self) -> None:\n \"\"\"Initialize the search service.\"\"\"\n pass\n\n @abstractmethod\n async def index_server(\n self,\n path: str,\n server_info: dict[str, Any],\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index a server for search.\"\"\"\n pass\n\n @abstractmethod\n async def index_agent(\n self,\n path: str,\n agent_card: AgentCard,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index an agent for search.\"\"\"\n pass\n\n @abstractmethod\n async def remove_entity(\n self,\n path: str,\n ) -> None:\n \"\"\"Remove entity from search index.\"\"\"\n pass\n\n @abstractmethod\n async def search(\n self,\n query: str,\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Perform search.\"\"\"\n pass\n\n async def index_skill(\n self,\n path: str,\n skill: Any,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index a skill for search.\n\n Default implementation is a no-op. Override in implementations\n that support skill indexing.\n\n Args:\n path: Skill path (e.g., /skills/pdf-processing)\n skill: SkillCard object\n is_enabled: Whether skill is enabled\n \"\"\"\n return None\n\n async def index_virtual_server(\n self,\n path: str,\n virtual_server: Any,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Index a virtual server for search.\n\n Default implementation is a no-op. Override in implementations\n that support virtual server indexing.\n\n Args:\n path: Virtual server path (e.g., /virtual/dev-essentials)\n virtual_server: VirtualServerConfig object\n is_enabled: Whether virtual server is enabled\n \"\"\"\n return None\n\n async def search_by_tags(\n self,\n tags: list[str],\n entity_types: list[str] | None = None,\n max_results: int = 10,\n include_draft: bool = False,\n include_deprecated: bool = False,\n include_disabled: bool = False,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Search entities by exact tag match (case-insensitive).\n\n Returns entities that have ALL specified tags. Default implementation\n falls back to search() with the tag names as query text.\n\n Args:\n tags: Required tags (all must match)\n entity_types: Optional entity type filter\n max_results: Max results per entity type\n\n Returns:\n Grouped search results dict\n \"\"\"\n return await self.search(\n query=\" \".join(tags),\n entity_types=entity_types,\n max_results=max_results,\n )\n\n async def get_all_tags(self) -> list[str]:\n \"\"\"Return a sorted list of all unique tags across all indexed entities.\n\n Default implementation returns an empty list. Override in implementations\n that support tag retrieval.\n\n Returns:\n Sorted list of unique tag strings\n \"\"\"\n return []\n\n\nclass PeerFederationRepositoryBase(ABC):\n \"\"\"Abstract base class for peer federation storage.\"\"\"\n\n @abstractmethod\n async def load_all(self) -> None:\n \"\"\"Load/reload all peers and sync states from storage.\"\"\"\n pass\n\n @abstractmethod\n async def get_peer(\n self,\n peer_id: str,\n ) -> Any | None:\n \"\"\"Get peer configuration by ID.\"\"\"\n pass\n\n @abstractmethod\n async def list_peers(\n self,\n enabled: bool | None = None,\n ) -> list[Any]:\n \"\"\"List all peer configurations with optional filtering.\"\"\"\n pass\n\n @abstractmethod\n async def create_peer(\n self,\n config: Any,\n ) -> Any:\n \"\"\"Create a new peer configuration.\"\"\"\n pass\n\n @abstractmethod\n async def update_peer(\n self,\n peer_id: str,\n updates: dict[str, Any],\n ) -> Any:\n \"\"\"Update an existing peer configuration.\"\"\"\n pass\n\n @abstractmethod\n async def delete_peer(\n self,\n peer_id: str,\n ) -> bool:\n \"\"\"Delete a peer configuration and its sync status.\"\"\"\n pass\n\n @abstractmethod\n async def get_sync_status(\n self,\n peer_id: str,\n ) -> Any | None:\n \"\"\"Get sync status for a peer.\"\"\"\n pass\n\n @abstractmethod\n async def update_sync_status(\n self,\n peer_id: str,\n status: Any,\n ) -> Any:\n \"\"\"Update sync status for a peer.\"\"\"\n pass\n\n @abstractmethod\n async def list_sync_statuses(self) -> list[Any]:\n \"\"\"List all peer sync statuses.\"\"\"\n pass\n\n\nclass FederationConfigRepositoryBase(ABC):\n \"\"\"Abstract base class for federation configuration storage.\"\"\"\n\n @abstractmethod\n async def get_config(self, config_id: str = \"default\") -> FederationConfig | None:\n \"\"\"\n Get federation configuration by ID.\n\n Args:\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n FederationConfig if found, None otherwise\n \"\"\"\n pass\n\n @abstractmethod\n async def save_config(\n self, config: FederationConfig, config_id: str = \"default\"\n ) -> FederationConfig:\n \"\"\"\n Save or update federation configuration.\n\n Args:\n config: Federation configuration to save\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n Saved configuration with timestamps\n \"\"\"\n pass\n\n @abstractmethod\n async def delete_config(self, config_id: str = \"default\") -> bool:\n \"\"\"\n Delete federation configuration.\n\n Args:\n config_id: Configuration ID (default: \"default\")\n\n Returns:\n True if deleted, False if not found\n \"\"\"\n pass\n\n @abstractmethod\n async def list_configs(self) -> list[dict[str, Any]]:\n \"\"\"\n List all federation configurations.\n\n Returns:\n List of config summaries with id, created_at, updated_at\n \"\"\"\n pass\n\n\nclass SkillRepositoryBase(ABC):\n \"\"\"Abstract base class for skill repository implementations.\"\"\"\n\n @abstractmethod\n async def ensure_indexes(self) -> None:\n \"\"\"Create required indexes if not present.\"\"\"\n pass\n\n @abstractmethod\n async def get(\n self,\n path: str,\n ) -> SkillCard | None:\n \"\"\"Get a skill by path.\"\"\"\n pass\n\n @abstractmethod\n async def list_all(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> list[SkillCard]:\n \"\"\"List all skills with pagination.\n\n Args:\n skip: Number of records to skip (offset)\n limit: Maximum number of records to return\n\n Returns:\n List of SkillCard objects\n \"\"\"\n pass\n\n @abstractmethod\n async def list_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> list[SkillCard]:\n \"\"\"List skills with DB-level pagination and deterministic ordering.\n\n Args:\n skip: Number of documents to skip.\n limit: Maximum number of documents to return.\n\n Returns:\n List of SkillCard objects for the requested page.\n \"\"\"\n pass\n\n @abstractmethod\n async def list_filtered(\n self,\n include_disabled: bool = False,\n tag: str | None = None,\n visibility: str | None = None,\n registry_name: str | None = None,\n ) -> list[SkillCard]:\n \"\"\"List skills with database-level filtering.\"\"\"\n pass\n\n @abstractmethod\n async def create(\n self,\n skill: SkillCard,\n ) -> SkillCard:\n \"\"\"Create a new skill.\"\"\"\n pass\n\n @abstractmethod\n async def update(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> SkillCard | None:\n \"\"\"Update a skill.\"\"\"\n pass\n\n @abstractmethod\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a skill.\"\"\"\n pass\n\n @abstractmethod\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get skill enabled state.\"\"\"\n pass\n\n @abstractmethod\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set skill enabled state.\"\"\"\n pass\n\n # Batch operations for federation sync\n @abstractmethod\n async def create_many(\n self,\n skills: list[SkillCard],\n ) -> list[SkillCard]:\n \"\"\"Create multiple skills in single operation.\"\"\"\n pass\n\n @abstractmethod\n async def update_many(\n self,\n updates: dict[str, dict[str, Any]],\n ) -> int:\n \"\"\"Update multiple skills by path, return count.\"\"\"\n pass\n\n @abstractmethod\n async def count(self) -> int:\n \"\"\"Get total count of skills.\n\n Returns:\n Total number of skills in the repository.\n \"\"\"\n pass\n\n\nclass BackendSessionRepositoryBase(ABC):\n \"\"\"Abstract base class for backend MCP session storage.\n\n Manages per-client backend sessions for virtual MCP servers.\n Each session maps a (client_session_id, backend_key) pair to the\n backend MCP server's session ID, enabling session isolation and\n persistence across L1 cache misses.\n \"\"\"\n\n @abstractmethod\n async def ensure_indexes(self) -> None:\n \"\"\"Create required indexes (TTL on last_used_at, etc.).\"\"\"\n pass\n\n @abstractmethod\n async def get_backend_session(\n self,\n client_session_id: str,\n backend_key: str,\n ) -> str | None:\n \"\"\"Get backend session ID and bump last_used_at atomically.\n\n Args:\n client_session_id: Client-facing session ID\n backend_key: Backend location key\n\n Returns:\n Backend session ID if found, None otherwise\n \"\"\"\n pass\n\n @abstractmethod\n async def store_backend_session(\n self,\n client_session_id: str,\n backend_key: str,\n backend_session_id: str,\n user_id: str,\n virtual_server_path: str,\n ) -> None:\n \"\"\"Store or update a backend session (upsert).\n\n Args:\n client_session_id: Client-facing session ID\n backend_key: Backend location key\n backend_session_id: Session ID from the backend MCP server\n user_id: User identity for audit\n virtual_server_path: Virtual server path\n \"\"\"\n pass\n\n @abstractmethod\n async def delete_backend_session(\n self,\n client_session_id: str,\n backend_key: str,\n ) -> None:\n \"\"\"Delete a stale backend session.\n\n Args:\n client_session_id: Client-facing session ID\n backend_key: Backend location key\n \"\"\"\n pass\n\n @abstractmethod\n async def create_client_session(\n self,\n client_session_id: str,\n user_id: str,\n virtual_server_path: str,\n ) -> None:\n \"\"\"Create a client session document for validation.\n\n Args:\n client_session_id: Generated client session ID\n user_id: User identity from auth context\n virtual_server_path: Virtual server path\n \"\"\"\n pass\n\n @abstractmethod\n async def validate_client_session(\n self,\n client_session_id: str,\n ) -> bool:\n \"\"\"Check if a client session exists and bump last_used_at.\n\n Args:\n client_session_id: Client-facing session ID\n\n Returns:\n True if session exists, False otherwise\n \"\"\"\n pass\n\n\nclass VirtualServerRepositoryBase(ABC):\n \"\"\"Abstract base class for virtual MCP server data access.\"\"\"\n\n @abstractmethod\n async def ensure_indexes(self) -> None:\n \"\"\"Create required indexes if not present.\"\"\"\n pass\n\n @abstractmethod\n async def get(\n self,\n path: str,\n ) -> VirtualServerConfig | None:\n \"\"\"Get a virtual server by path.\n\n Args:\n path: Virtual server path (e.g., '/virtual/dev-essentials')\n\n Returns:\n VirtualServerConfig if found, None otherwise\n \"\"\"\n pass\n\n @abstractmethod\n async def list_all(self) -> list[VirtualServerConfig]:\n \"\"\"List all virtual servers.\n\n Returns:\n List of all VirtualServerConfig objects\n \"\"\"\n pass\n\n @abstractmethod\n async def list_enabled(self) -> list[VirtualServerConfig]:\n \"\"\"List all enabled virtual servers.\n\n Returns:\n List of enabled VirtualServerConfig objects\n \"\"\"\n pass\n\n @abstractmethod\n async def create(\n self,\n config: VirtualServerConfig,\n ) -> VirtualServerConfig:\n \"\"\"Create a new virtual server.\n\n Args:\n config: Virtual server configuration\n\n Returns:\n Created VirtualServerConfig\n\n Raises:\n VirtualServerAlreadyExistsError: If path already exists\n \"\"\"\n pass\n\n @abstractmethod\n async def update(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> VirtualServerConfig | None:\n \"\"\"Update a virtual server.\n\n Args:\n path: Virtual server path\n updates: Fields to update\n\n Returns:\n Updated VirtualServerConfig if found, None otherwise\n \"\"\"\n pass\n\n @abstractmethod\n async def delete(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a virtual server.\n\n Args:\n path: Virtual server path\n\n Returns:\n True if deleted, False if not found\n \"\"\"\n pass\n\n @abstractmethod\n async def get_state(\n self,\n path: str,\n ) -> bool:\n \"\"\"Get virtual server enabled/disabled state.\n\n Args:\n path: Virtual server path\n\n Returns:\n True if enabled, False if disabled or not found\n \"\"\"\n pass\n\n @abstractmethod\n async def set_state(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Set virtual server enabled/disabled state.\n\n Args:\n path: Virtual server path\n enabled: New enabled state\n\n Returns:\n True if updated, False if not found\n \"\"\"\n pass\n\n\nclass RegistryCardRepositoryBase(ABC):\n \"\"\"Interface for Registry Card persistence.\"\"\"\n\n @abstractmethod\n async def get(self) -> RegistryCard | None:\n \"\"\"Retrieve the Registry Card.\"\"\"\n pass\n\n @abstractmethod\n async def save(\n self,\n card: RegistryCard,\n ) -> RegistryCard:\n \"\"\"Save or update the Registry Card.\"\"\"\n pass\n\n @abstractmethod\n async def exists(self) -> bool:\n \"\"\"Check if Registry Card exists.\"\"\"\n pass\n" }, { "path": "registry/repositories/stats_repository.py", "content": "\"\"\"\nStats repository for tracking usage counters (semantic search, etc.).\n\nStores counters at three granularities:\n- hourly: resets every hour\n- daily: resets every 24 hours\n- forever: never resets\n\nMongoDB storage uses the mcp_stats_{namespace} collection.\nFile-based storage uses {data_dir}/.stats.json.\n\"\"\"\n\nimport fcntl\nimport json\nimport logging\nfrom datetime import UTC, datetime, timedelta\nfrom pathlib import Path\n\nfrom ..core.config import settings\n\nlogger = logging.getLogger(__name__)\n\n\nasync def increment_search_counter() -> None:\n \"\"\"Increment semantic search counter across all three time windows.\n\n Fail-silent: never impacts search operation.\n \"\"\"\n try:\n if settings.storage_backend in (\"mongodb-ce\", \"documentdb\"):\n await _increment_mongodb()\n else:\n _increment_file()\n except Exception as e:\n logger.debug(f\"[stats] Failed to increment search counter: {e}\")\n\n\nasync def get_search_count() -> int:\n \"\"\"Get lifetime (forever) semantic search count.\n\n Returns:\n Cumulative search count, or 0 on failure.\n \"\"\"\n try:\n if settings.storage_backend in (\"mongodb-ce\", \"documentdb\"):\n return await _get_count_mongodb()\n else:\n return _get_count_file()\n except Exception as e:\n logger.debug(f\"[stats] Failed to get search count: {e}\")\n return 0\n\n\nasync def get_search_counts() -> dict[str, int]:\n \"\"\"Get search counts for all three time windows.\n\n Returns:\n Dict with keys: total, last_24h, last_1h (all default to 0 on failure).\n \"\"\"\n try:\n if settings.storage_backend in (\"mongodb-ce\", \"documentdb\"):\n return await _get_counts_mongodb()\n else:\n return _get_counts_file()\n except Exception as e:\n logger.debug(f\"[stats] Failed to get search counts: {e}\")\n return {\"total\": 0, \"last_24h\": 0, \"last_1h\": 0}\n\n\nasync def _increment_mongodb() -> None:\n \"\"\"Atomic increment in MongoDB with inline staleness reset.\"\"\"\n from .documentdb.client import get_collection_name, get_documentdb_client\n\n db = await get_documentdb_client()\n collection_name = get_collection_name(\"mcp_stats\")\n collection = db[collection_name]\n\n now = datetime.now(UTC)\n\n # Ensure document exists\n await collection.update_one(\n {\"_id\": \"counters\"},\n {\n \"$setOnInsert\": {\n \"hourly\": {\"semantic_search_ctr\": 0},\n \"daily\": {\"semantic_search_ctr\": 0},\n \"forever\": {\"semantic_search_ctr\": 0},\n \"hourly_reset_at\": now,\n \"daily_reset_at\": now,\n }\n },\n upsert=True,\n )\n\n # Check staleness and reset if needed\n doc = await collection.find_one({\"_id\": \"counters\"})\n if doc:\n updates = {}\n hourly_reset = doc.get(\"hourly_reset_at\")\n daily_reset = doc.get(\"daily_reset_at\")\n\n # MongoDB returns naive datetimes; make them UTC-aware for comparison\n if hourly_reset and hourly_reset.tzinfo is None:\n hourly_reset = hourly_reset.replace(tzinfo=UTC)\n if daily_reset and daily_reset.tzinfo is None:\n daily_reset = daily_reset.replace(tzinfo=UTC)\n\n if hourly_reset and (now - hourly_reset) > timedelta(hours=1):\n updates[\"hourly.semantic_search_ctr\"] = 0\n updates[\"hourly_reset_at\"] = now\n\n if daily_reset and (now - daily_reset) > timedelta(hours=24):\n updates[\"daily.semantic_search_ctr\"] = 0\n updates[\"daily_reset_at\"] = now\n\n if updates:\n await collection.update_one({\"_id\": \"counters\"}, {\"$set\": updates})\n\n # Atomic increment on all three windows\n await collection.update_one(\n {\"_id\": \"counters\"},\n {\n \"$inc\": {\n \"hourly.semantic_search_ctr\": 1,\n \"daily.semantic_search_ctr\": 1,\n \"forever.semantic_search_ctr\": 1,\n }\n },\n )\n\n\nasync def _get_count_mongodb() -> int:\n \"\"\"Read forever.semantic_search_ctr from MongoDB.\"\"\"\n from .documentdb.client import get_collection_name, get_documentdb_client\n\n db = await get_documentdb_client()\n collection_name = get_collection_name(\"mcp_stats\")\n collection = db[collection_name]\n\n doc = await collection.find_one({\"_id\": \"counters\"})\n if doc:\n return doc.get(\"forever\", {}).get(\"semantic_search_ctr\", 0)\n return 0\n\n\nasync def _get_counts_mongodb() -> dict[str, int]:\n \"\"\"Read all three time-window counters from MongoDB.\"\"\"\n from .documentdb.client import get_collection_name, get_documentdb_client\n\n db = await get_documentdb_client()\n collection_name = get_collection_name(\"mcp_stats\")\n collection = db[collection_name]\n\n doc = await collection.find_one({\"_id\": \"counters\"})\n if doc:\n return {\n \"total\": doc.get(\"forever\", {}).get(\"semantic_search_ctr\", 0),\n \"last_24h\": doc.get(\"daily\", {}).get(\"semantic_search_ctr\", 0),\n \"last_1h\": doc.get(\"hourly\", {}).get(\"semantic_search_ctr\", 0),\n }\n return {\"total\": 0, \"last_24h\": 0, \"last_1h\": 0}\n\n\ndef _get_stats_file() -> Path:\n \"\"\"Get path to file-based stats storage.\"\"\"\n return settings.data_dir / \".stats.json\"\n\n\ndef _read_file_stats() -> dict:\n \"\"\"Read stats from file.\"\"\"\n stats_file = _get_stats_file()\n if stats_file.exists():\n return json.loads(stats_file.read_text())\n return {\n \"hourly\": {\"semantic_search_ctr\": 0},\n \"daily\": {\"semantic_search_ctr\": 0},\n \"forever\": {\"semantic_search_ctr\": 0},\n \"hourly_reset_at\": datetime.now(UTC).isoformat(),\n \"daily_reset_at\": datetime.now(UTC).isoformat(),\n }\n\n\ndef _write_file_stats(stats: dict) -> None:\n \"\"\"Write stats to file.\"\"\"\n stats_file = _get_stats_file()\n settings.data_dir.mkdir(parents=True, exist_ok=True)\n stats_file.write_text(json.dumps(stats, default=str))\n\n\ndef _increment_file() -> None:\n \"\"\"Increment counter in file-based storage with staleness reset.\n\n Uses file locking (fcntl.flock) to prevent lost updates from\n concurrent processes.\n \"\"\"\n stats_file = _get_stats_file()\n settings.data_dir.mkdir(parents=True, exist_ok=True)\n\n # Open file for read+write, create if missing\n with open(stats_file, \"a+\") as f:\n fcntl.flock(f, fcntl.LOCK_EX)\n try:\n f.seek(0)\n content = f.read()\n stats = json.loads(content) if content.strip() else _read_file_stats()\n\n now = datetime.now(UTC)\n\n # Check hourly staleness\n hourly_reset = stats.get(\"hourly_reset_at\", \"\")\n if hourly_reset:\n try:\n reset_time = datetime.fromisoformat(hourly_reset.replace(\"Z\", \"+00:00\"))\n if (now - reset_time) > timedelta(hours=1):\n stats[\"hourly\"] = {\"semantic_search_ctr\": 0}\n stats[\"hourly_reset_at\"] = now.isoformat()\n except (ValueError, TypeError):\n stats[\"hourly_reset_at\"] = now.isoformat()\n\n # Check daily staleness\n daily_reset = stats.get(\"daily_reset_at\", \"\")\n if daily_reset:\n try:\n reset_time = datetime.fromisoformat(daily_reset.replace(\"Z\", \"+00:00\"))\n if (now - reset_time) > timedelta(hours=24):\n stats[\"daily\"] = {\"semantic_search_ctr\": 0}\n stats[\"daily_reset_at\"] = now.isoformat()\n except (ValueError, TypeError):\n stats[\"daily_reset_at\"] = now.isoformat()\n\n # Increment all three\n for window in (\"hourly\", \"daily\", \"forever\"):\n if window not in stats:\n stats[window] = {\"semantic_search_ctr\": 0}\n stats[window][\"semantic_search_ctr\"] = (\n stats[window].get(\"semantic_search_ctr\", 0) + 1\n )\n\n # Write back while holding lock\n f.seek(0)\n f.truncate()\n f.write(json.dumps(stats, default=str))\n finally:\n fcntl.flock(f, fcntl.LOCK_UN)\n\n\ndef _get_count_file() -> int:\n \"\"\"Read forever.semantic_search_ctr from file.\"\"\"\n stats = _read_file_stats()\n return stats.get(\"forever\", {}).get(\"semantic_search_ctr\", 0)\n\n\ndef _get_counts_file() -> dict[str, int]:\n \"\"\"Read all three time-window counters from file.\"\"\"\n stats = _read_file_stats()\n return {\n \"total\": stats.get(\"forever\", {}).get(\"semantic_search_ctr\", 0),\n \"last_24h\": stats.get(\"daily\", {}).get(\"semantic_search_ctr\", 0),\n \"last_1h\": stats.get(\"hourly\", {}).get(\"semantic_search_ctr\", 0),\n }\n" }, { "path": "registry/schemas/__init__.py", "content": "\"\"\"Models for the registry service.\"\"\"\n\nfrom .agent_models import (\n AgentCard,\n AgentInfo,\n AgentRegistrationRequest,\n SecurityScheme,\n Skill,\n)\nfrom .anthropic_schema import (\n ErrorResponse,\n Package,\n PaginationMetadata,\n Repository,\n ServerDetail,\n ServerList,\n ServerResponse,\n SseTransport,\n StdioTransport,\n StreamableHttpTransport,\n)\nfrom .registry_card import (\n LifecycleStatus,\n RegistryAuthConfig,\n RegistryCapabilities,\n RegistryCard,\n RegistryContact,\n)\n\n__all__ = [\n \"Repository\",\n \"StdioTransport\",\n \"StreamableHttpTransport\",\n \"SseTransport\",\n \"Package\",\n \"ServerDetail\",\n \"ServerResponse\",\n \"ServerList\",\n \"PaginationMetadata\",\n \"ErrorResponse\",\n \"SecurityScheme\",\n \"Skill\",\n \"AgentCard\",\n \"AgentInfo\",\n \"AgentRegistrationRequest\",\n \"LifecycleStatus\",\n \"RegistryCapabilities\",\n \"RegistryAuthConfig\",\n \"RegistryContact\",\n \"RegistryCard\",\n]\n" }, { "path": "registry/schemas/agent_models.py", "content": "\"\"\"\nPydantic models for A2A (Agent-to-Agent) protocol support.\n\nThis module defines Agent Cards and related models following the A2A specification\nfor agent discovery and registration in the MCP Gateway Registry.\n\nBased on: docs/design/a2a-protocol-integration.md\n\"\"\"\n\nimport logging\nimport re\nfrom datetime import datetime\nfrom typing import Any\nfrom uuid import UUID, uuid4\n\nfrom pydantic import (\n BaseModel,\n ConfigDict,\n Field,\n field_validator,\n model_validator,\n)\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\nGROUP_NAME_PATTERN = re.compile(r\"^[a-zA-Z0-9_\\-\\.]+$\")\n\n\ndef _validate_path_format(\n path: str,\n) -> str:\n \"\"\"\n Validate agent path format.\n\n Args:\n path: Agent path to validate\n\n Returns:\n Validated path string\n\n Raises:\n ValueError: If path format is invalid\n \"\"\"\n if not path.startswith(\"/\"):\n raise ValueError(\"Path must start with '/'\")\n\n if \"//\" in path:\n raise ValueError(\"Path cannot contain consecutive slashes\")\n\n if path.endswith(\"/\") and len(path) > 1:\n raise ValueError(\"Path cannot end with '/' unless it is the root path\")\n\n return path\n\n\ndef _validate_protocol_version(\n version: str,\n) -> str:\n \"\"\"\n Validate A2A protocol version format.\n\n Args:\n version: Protocol version string\n\n Returns:\n Validated version string\n\n Raises:\n ValueError: If version format is invalid\n \"\"\"\n if not version:\n raise ValueError(\"Protocol version cannot be empty\")\n\n parts = version.split(\".\")\n if len(parts) < 2:\n raise ValueError(\"Protocol version must be in format 'X.Y' or 'X.Y.Z'\")\n\n for part in parts:\n if not part.isdigit():\n raise ValueError(\"Protocol version parts must be numeric\")\n\n return version\n\n\ndef _validate_skill_ids_unique(\n skills: list[\"Skill\"],\n) -> list[\"Skill\"]:\n \"\"\"\n Validate that skill IDs are unique within the agent.\n\n Args:\n skills: List of skill objects\n\n Returns:\n Validated skills list\n\n Raises:\n ValueError: If duplicate skill IDs are found\n \"\"\"\n if not skills:\n return skills\n\n skill_ids = [skill.id for skill in skills]\n duplicates = [sid for sid in skill_ids if skill_ids.count(sid) > 1]\n\n if duplicates:\n unique_duplicates = list(set(duplicates))\n raise ValueError(f\"Duplicate skill IDs found: {', '.join(unique_duplicates)}\")\n\n return skills\n\n\ndef _validate_url_format(\n url: str,\n) -> str:\n \"\"\"\n Validate URL format and protocol.\n\n Allows both HTTP and HTTPS for flexibility in local/development environments,\n though HTTPS is required for production per A2A specification.\n\n Args:\n url: URL string to validate\n\n Returns:\n Validated URL string\n\n Raises:\n ValueError: If URL format is invalid or protocol is not HTTP/HTTPS\n \"\"\"\n if not url:\n raise ValueError(\"URL cannot be empty\")\n\n if not (url.startswith(\"http://\") or url.startswith(\"https://\")):\n raise ValueError(\"URL must use HTTP or HTTPS protocol\")\n\n try:\n from urllib.parse import urlparse\n\n parsed = urlparse(url)\n if not parsed.netloc:\n raise ValueError(\"URL must include a valid hostname\")\n except Exception as e:\n raise ValueError(f\"Invalid URL format: {e}\")\n\n return url\n\n\ndef _validate_security_references(\n security: list[dict[str, list[str]]] | None,\n security_schemes: dict[str, \"SecurityScheme | dict[str, Any]\"],\n) -> list[dict[str, list[str]]] | None:\n \"\"\"\n Validate that security references exist in security_schemes.\n\n Args:\n security: Security requirements array\n security_schemes: Available security schemes\n\n Returns:\n Validated security array\n\n Raises:\n ValueError: If referenced security scheme does not exist\n \"\"\"\n if not security:\n return security\n\n for requirement in security:\n for scheme_name in requirement.keys():\n if scheme_name not in security_schemes:\n raise ValueError(f\"Security requirement references undefined scheme: {scheme_name}\")\n\n return security\n\n\nclass SecurityScheme(BaseModel):\n \"\"\"\n Security scheme for agent authentication.\n\n Supports various authentication methods including OAuth2, bearer tokens,\n API keys, and OpenID Connect.\n\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n type: str = Field(\n ...,\n description=\"Security type: apiKey, http, oauth2, openIdConnect\",\n )\n scheme: str | None = Field(\n None,\n description=\"HTTP auth scheme: basic, bearer, digest\",\n )\n in_: str | None = Field(\n None,\n alias=\"in\",\n description=\"API key location: header, query, cookie\",\n )\n name: str | None = Field(\n None,\n description=\"Name of header/query/cookie for API key\",\n )\n bearer_format: str | None = Field(\n None,\n alias=\"bearerFormat\",\n description=\"Bearer token format hint (e.g., JWT)\",\n )\n flows: dict[str, Any] | None = Field(\n None,\n description=\"OAuth2 flows configuration\",\n )\n openid_connect_url: str | None = Field(\n None,\n alias=\"openIdConnectUrl\",\n description=\"OpenID Connect discovery URL\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True # Allow both snake_case and camelCase on input\n )\n\n @field_validator(\"type\")\n @classmethod\n def _validate_security_type(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate security type is one of the supported types.\"\"\"\n valid_types = [\"apiKey\", \"http\", \"oauth2\", \"openIdConnect\"]\n if v not in valid_types:\n raise ValueError(f\"Security type must be one of: {', '.join(valid_types)}\")\n return v\n\n @field_validator(\"in_\")\n @classmethod\n def _validate_api_key_location(\n cls,\n v: str | None,\n ) -> str | None:\n \"\"\"Validate API key location.\"\"\"\n if v is not None:\n valid_locations = [\"header\", \"query\", \"cookie\"]\n if v not in valid_locations:\n raise ValueError(f\"API key location must be one of: {', '.join(valid_locations)}\")\n return v\n\n\nclass AgentProvider(BaseModel):\n \"\"\"\n A2A Agent Provider information.\n\n Represents the service provider of an agent with organization name and website URL.\n Per A2A specification, if provider is present, both organization and url are required.\n \"\"\"\n\n organization: str = Field(\n ...,\n description=\"Provider organization name\",\n )\n url: str = Field(\n ...,\n description=\"Provider website or documentation URL\",\n )\n\n model_config = ConfigDict(populate_by_name=True)\n\n\nclass Skill(BaseModel):\n \"\"\"\n Agent skill definition per A2A protocol specification.\n\n A skill represents a discrete capability that an agent can perform.\n Skills describe high-level capabilities without operation-specific schemas.\n\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n id: str = Field(\n ...,\n description=\"Unique skill identifier\",\n )\n name: str = Field(\n ...,\n description=\"Human-readable skill name\",\n )\n description: str = Field(\n ...,\n description=\"Detailed skill description\",\n )\n tags: list[str] = Field(\n ...,\n description=\"Skill categorization tags - keywords describing capability\",\n )\n examples: list[str] | None = Field(\n None,\n description=\"Usage scenarios and examples\",\n )\n input_modes: list[str] | None = Field(\n None,\n alias=\"inputModes\",\n description=\"Skill-specific input MIME types\",\n )\n output_modes: list[str] | None = Field(\n None,\n alias=\"outputModes\",\n description=\"Skill-specific output MIME types\",\n )\n security: list[dict[str, list[str]]] | None = Field(\n None,\n description=\"Skill-level security requirements\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True # Allow both snake_case and camelCase on input\n )\n\n @field_validator(\"id\")\n @classmethod\n def _validate_skill_id(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate skill ID format.\"\"\"\n if not v:\n raise ValueError(\"Skill ID cannot be empty\")\n if \" \" in v:\n raise ValueError(\"Skill ID cannot contain spaces\")\n return v\n\n @field_validator(\"name\")\n @classmethod\n def _validate_skill_name(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate skill name.\"\"\"\n if not v or not v.strip():\n raise ValueError(\"Skill name cannot be empty\")\n return v.strip()\n\n\nclass AgentCard(BaseModel):\n \"\"\"\n A2A Agent Card - machine-readable agent profile.\n\n This model represents a complete agent card following the A2A protocol\n specification (v0.3.0), with extensions for MCP Gateway Registry integration.\n\n The agent card includes:\n - Required A2A fields (protocolVersion, name, description, url, version, capabilities, etc.)\n - Optional A2A fields (provider, skills, security, etc.)\n - MCP Gateway Registry extensions (path, tags, visibility, trust_level)\n\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n # Unique identifier\n id: UUID = Field(\n default_factory=uuid4,\n description=\"Unique identifier (UUID) for this agent\",\n )\n\n # Required A2A fields\n protocol_version: str = Field(\n \"1.0\",\n alias=\"protocolVersion\",\n description=\"A2A protocol version (e.g., '1.0')\",\n )\n name: str = Field(\n ...,\n description=\"Agent name\",\n )\n description: str = Field(\n ...,\n description=\"Agent description\",\n )\n url: str = Field(\n ...,\n description=\"Agent endpoint URL (HTTP or HTTPS)\",\n )\n version: str = Field(\n ...,\n description=\"Agent version\",\n )\n capabilities: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Feature declarations (e.g., {'streaming': true})\",\n )\n default_input_modes: list[str] = Field(\n default_factory=lambda: [\"text/plain\"],\n alias=\"defaultInputModes\",\n description=\"Supported input MIME types\",\n )\n default_output_modes: list[str] = Field(\n default_factory=lambda: [\"text/plain\"],\n alias=\"defaultOutputModes\",\n description=\"Supported output MIME types\",\n )\n skills: list[Skill] = Field(\n default_factory=list,\n description=\"Agent capabilities (skills)\",\n )\n\n # Optional A2A fields\n preferred_transport: str | None = Field(\n \"JSONRPC\",\n alias=\"preferredTransport\",\n description=\"Preferred transport protocol: JSONRPC, GRPC, HTTP+JSON\",\n )\n provider: AgentProvider | None = Field(\n None,\n description=\"Agent provider information per A2A spec\",\n )\n icon_url: str | None = Field(\n None,\n alias=\"iconUrl\",\n description=\"Agent icon URL\",\n )\n documentation_url: str | None = Field(\n None,\n alias=\"documentationUrl\",\n description=\"Documentation URL\",\n )\n security_schemes: dict[str, SecurityScheme | dict[str, Any]] = Field(\n default_factory=dict,\n alias=\"securitySchemes\",\n description=\"Supported authentication methods\",\n )\n security: list[dict[str, list[str]]] | None = Field(\n None,\n description=\"Security requirements array\",\n )\n supports_authenticated_extended_card: bool | None = Field(\n None,\n alias=\"supportsAuthenticatedExtendedCard\",\n description=\"Supports extended card with auth\",\n )\n metadata: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Additional metadata\",\n )\n\n # MCP Gateway Registry extensions (optional - not part of A2A spec)\n path: str | None = Field(\n None,\n description=\"Registry path (e.g., /agents/my-agent). Optional - auto-generated if not provided.\",\n )\n tags: list[str] = Field(\n default_factory=list,\n description=\"Categorization tags\",\n )\n is_enabled: bool = Field(\n False,\n alias=\"isEnabled\",\n description=\"Whether agent is enabled in registry\",\n )\n num_stars: float = Field(\n 0.0,\n ge=0.0,\n le=5.0,\n alias=\"numStars\",\n description=\"Average community rating (0.0-5.0)\",\n )\n rating_details: list[dict[str, Any]] = Field(\n default_factory=list,\n alias=\"ratingDetails\",\n description=\"Individual user ratings with username and rating value\",\n )\n license: str = Field(\n \"N/A\",\n description=\"License information\",\n )\n\n # Registry metadata\n registered_at: datetime | None = Field(\n None,\n alias=\"registeredAt\",\n description=\"Registration timestamp\",\n )\n updated_at: datetime | None = Field(\n None,\n alias=\"updatedAt\",\n description=\"Last update timestamp\",\n )\n registered_by: str | None = Field(\n None,\n alias=\"registeredBy\",\n description=\"Username who registered agent\",\n )\n\n # Access control\n visibility: str = Field(\n \"public\",\n description=\"public, group-restricted, or internal\",\n )\n allowed_groups: list[str] = Field(\n default_factory=list,\n alias=\"allowedGroups\",\n description=\"Groups with access when visibility is group-restricted\",\n )\n\n # Federation sync metadata\n sync_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"syncMetadata\",\n description=\"Metadata for items synced from peer registries\",\n )\n\n # Validation and trust\n signature: str | None = Field(\n None,\n description=\"JWS signature for card integrity\",\n )\n trust_level: str = Field(\n \"community\",\n alias=\"trustLevel\",\n description=\"unverified, community, verified, trusted\",\n )\n\n # ANS Integration\n ans_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"ansMetadata\",\n description=\"ANS (Agent Name Service) verification metadata\",\n )\n\n # Health check status (persisted to MongoDB)\n health_status: str = Field(\n default=\"unknown\",\n alias=\"healthStatus\",\n description=\"Last known health status: healthy, unhealthy, unknown\",\n )\n last_health_check: datetime | None = Field(\n default=None,\n alias=\"lastHealthCheck\",\n description=\"Timestamp of last health check\",\n )\n\n # Lifecycle and federation metadata\n status: str = Field(\n default=\"active\",\n description=\"Lifecycle status (default: active for existing assets)\",\n )\n source_created_at: datetime | None = Field(\n default=None,\n description=\"Original creation timestamp from source system\",\n alias=\"sourceCreatedAt\",\n )\n source_updated_at: datetime | None = Field(\n default=None,\n description=\"Last update timestamp from source system\",\n alias=\"sourceUpdatedAt\",\n )\n external_tags: list[str] = Field(\n default_factory=list,\n description=\"Tags from external/source system\",\n alias=\"externalTags\",\n )\n supported_protocol: str | None = Field(\n default=None,\n alias=\"supportedProtocol\",\n description=\"Agent protocol: 'a2a' for A2A protocol agents, 'other' for non-A2A agents\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True # Allow both snake_case and camelCase on input\n )\n\n @field_validator(\"protocol_version\")\n @classmethod\n def _validate_protocol_version_field(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate protocol version format.\"\"\"\n return _validate_protocol_version(v)\n\n @field_validator(\"url\")\n @classmethod\n def _validate_url_field(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate URL format and protocol.\"\"\"\n return _validate_url_format(v)\n\n @field_validator(\"path\")\n @classmethod\n def _validate_path_field(\n cls,\n v: str | None,\n ) -> str | None:\n \"\"\"Validate path format if provided.\"\"\"\n if v is None:\n return None\n return _validate_path_format(v)\n\n @field_validator(\"visibility\")\n @classmethod\n def _validate_visibility_field(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate and normalize visibility value.\n\n Accepts \"internal\" as alias for \"private\" and \"group\" as alias\n for \"group-restricted\" for backward compatibility.\n \"\"\"\n from registry.utils.visibility import validate_visibility\n\n return validate_visibility(v)\n\n @field_validator(\"trust_level\")\n @classmethod\n def _validate_trust_level_field(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate trust level value.\"\"\"\n valid_levels = [\"unverified\", \"community\", \"verified\", \"trusted\"]\n if v not in valid_levels:\n raise ValueError(f\"Trust level must be one of: {', '.join(valid_levels)}\")\n return v\n\n @field_validator(\"tags\", mode=\"before\")\n @classmethod\n def _convert_tags_field(\n cls,\n v: Any,\n ) -> list[str]:\n \"\"\"Convert tags from string or list format to list of strings.\n\n Supports both:\n - String format: \"tag1,tag2,tag3\"\n - List format: [\"tag1\", \"tag2\", \"tag3\"]\n \"\"\"\n if isinstance(v, str):\n return [tag.strip() for tag in v.split(\",\") if tag.strip()]\n if isinstance(v, list):\n return [str(tag).strip() for tag in v if str(tag).strip()]\n return []\n\n @field_validator(\"skills\")\n @classmethod\n def _validate_skills_field(\n cls,\n v: list[Skill],\n ) -> list[Skill]:\n \"\"\"Validate skills have unique IDs.\"\"\"\n return _validate_skill_ids_unique(v)\n\n @model_validator(mode=\"after\")\n def _validate_security_requirements(\n self,\n ) -> \"AgentCard\":\n \"\"\"Validate security requirements reference existing schemes.\"\"\"\n if self.security is not None:\n _validate_security_references(self.security, self.security_schemes)\n return self\n\n @model_validator(mode=\"after\")\n def _validate_group_restricted_access(\n self,\n ) -> \"AgentCard\":\n \"\"\"Validate group-restricted visibility has allowed groups.\"\"\"\n if self.visibility == \"group-restricted\" and not self.allowed_groups:\n raise ValueError(\"Group-restricted visibility requires at least one allowed group\")\n return self\n\n\nclass AgentInfo(BaseModel):\n \"\"\"\n Simplified agent information for listing and search.\n\n This lightweight model is used for agent discovery results and listings,\n containing only the essential information needed for agent selection.\n\n Note: Uses snake_case internally but serializes to camelCase for A2A compliance.\n \"\"\"\n\n name: str = Field(\n ...,\n description=\"Agent name\",\n )\n description: str = Field(\n default=\"\",\n description=\"Agent description\",\n )\n path: str = Field(\n ...,\n description=\"Registry path\",\n )\n url: str = Field(\n ...,\n description=\"Agent endpoint URL\",\n )\n tags: list[str] = Field(\n default_factory=list,\n description=\"Categorization tags\",\n )\n skills: list[str] = Field(\n default_factory=list,\n description=\"Skill names only\",\n )\n num_skills: int = Field(\n 0,\n ge=0,\n alias=\"numSkills\",\n description=\"Number of skills\",\n )\n num_stars: float = Field(\n 0.0,\n ge=0.0,\n le=5.0,\n alias=\"numStars\",\n description=\"Average community rating (0.0-5.0)\",\n )\n is_enabled: bool = Field(\n False,\n alias=\"isEnabled\",\n description=\"Whether agent is enabled\",\n )\n provider: str | None = Field(\n None,\n description=\"Agent provider/author\",\n )\n streaming: bool = Field(\n False,\n description=\"Supports streaming responses\",\n )\n trust_level: str = Field(\n \"community\",\n alias=\"trustLevel\",\n description=\"unverified, community, verified, trusted\",\n )\n visibility: str = Field(\n \"public\",\n description=\"public, group-restricted, or internal\",\n )\n allowed_groups: list[str] = Field(\n default_factory=list,\n alias=\"allowedGroups\",\n description=\"Groups with access when visibility is group-restricted\",\n )\n supported_protocol: str | None = Field(\n default=None,\n alias=\"supportedProtocol\",\n description=\"Agent protocol: 'a2a' or 'other'\",\n )\n sync_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"syncMetadata\",\n description=\"Federation sync metadata for items from peer registries\",\n )\n ans_metadata: dict[str, Any] | None = Field(\n default=None,\n alias=\"ansMetadata\",\n description=\"ANS verification metadata\",\n )\n registered_by: str | None = Field(\n None,\n alias=\"registeredBy\",\n description=\"Username who registered the agent\",\n )\n status: str = Field(\n \"active\",\n description=\"Lifecycle status: active, deprecated, draft, beta\",\n )\n provider_organization: str | None = Field(\n None,\n alias=\"providerOrganization\",\n description=\"Provider organization name\",\n )\n provider_url: str | None = Field(\n None,\n alias=\"providerUrl\",\n description=\"Provider URL\",\n )\n source_created_at: str | None = Field(\n None,\n alias=\"sourceCreatedAt\",\n description=\"Original creation timestamp from source system (ISO format)\",\n )\n source_updated_at: str | None = Field(\n None,\n alias=\"sourceUpdatedAt\",\n description=\"Last update timestamp from source system (ISO format)\",\n )\n registered_at: str | None = Field(\n None,\n alias=\"registeredAt\",\n description=\"Registration timestamp in this registry (ISO format)\",\n )\n updated_at: str | None = Field(\n None,\n alias=\"updatedAt\",\n description=\"Last update timestamp in this registry (ISO format)\",\n )\n health_status: str = Field(\n default=\"unknown\",\n alias=\"healthStatus\",\n description=\"Last known health status: healthy, unhealthy, unknown\",\n )\n last_health_check: str | None = Field(\n default=None,\n alias=\"lastHealthCheck\",\n description=\"Timestamp of last health check (ISO format)\",\n )\n metadata: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Additional metadata key-value pairs\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True # Allow both snake_case and camelCase on input\n )\n\n\nclass AgentRegistrationRequest(BaseModel):\n \"\"\"\n API request model for agent registration.\n\n This model is used for the agent registration API endpoint and converts\n form-style inputs (e.g., comma-separated tags) into the proper types.\n Accepts both snake_case (Python) and camelCase (A2A spec JSON) field names.\n \"\"\"\n\n name: str = Field(\n ...,\n min_length=1,\n description=\"Agent name\",\n )\n description: str = Field(\n default=\"\",\n description=\"Agent description\",\n )\n url: str = Field(\n ...,\n min_length=1,\n description=\"Agent endpoint URL\",\n )\n path: str | None = Field(\n None,\n description=\"Registry path (optional - auto-generated if not provided)\",\n )\n protocol_version: str = Field(\n default=\"1.0\",\n alias=\"protocolVersion\",\n description=\"A2A protocol version\",\n )\n version: str | None = Field(\n None,\n description=\"Agent version\",\n )\n provider: dict[str, str] | None = Field(\n None,\n description=\"Agent provider information {organization, url}\",\n )\n security_schemes: dict[str, dict[str, Any]] | None = Field(\n None,\n alias=\"securitySchemes\",\n description=\"Security schemes configuration\",\n )\n skills: list[dict[str, Any]] | None = Field(\n None,\n description=\"Agent skills\",\n )\n streaming: bool = Field(\n False,\n description=\"Supports streaming responses\",\n )\n tags: str | list[str] = Field(\n default=\"\",\n description=\"Comma-separated tags or list of tags\",\n )\n license: str = Field(\n default=\"N/A\",\n description=\"License information\",\n )\n visibility: str = Field(\n default=\"public\",\n description=\"Visibility: public, private, or group-restricted (default: public). 'internal' accepted as alias for 'private'.\",\n )\n allowed_groups: list[str] = Field(\n default_factory=list,\n alias=\"allowedGroups\",\n max_length=50,\n description=\"Groups with access when visibility is group-restricted (list or comma-separated string)\",\n )\n trust_level: str = Field(\n default=\"community\",\n alias=\"trustLevel\",\n description=\"Trust level: unverified, community, verified, trusted (default: community)\",\n )\n\n status: str = Field(\n default=\"draft\",\n description=\"Lifecycle status (default: draft). Allowed: active, deprecated, draft, beta\",\n )\n source_created_at: str | None = Field(\n None,\n description=\"Original creation timestamp from source system (ISO format)\",\n )\n source_updated_at: str | None = Field(\n None,\n description=\"Last update timestamp from source system (ISO format)\",\n )\n external_tags: str | list[str] | None = Field(\n None,\n description=\"Comma-separated tags or list of tags from external/source system\",\n )\n default_input_modes: list[str] | None = Field(\n None,\n alias=\"defaultInputModes\",\n description=\"Supported input MIME types (e.g., ['text', 'text/plain'])\",\n )\n default_output_modes: list[str] | None = Field(\n None,\n alias=\"defaultOutputModes\",\n description=\"Supported output MIME types (e.g., ['text', 'text/plain'])\",\n )\n ans_agent_id: str | None = Field(\n default=None,\n description=\"Optional ANS Agent ID to link during registration\",\n )\n supported_protocol: str = Field(\n ...,\n alias=\"supportedProtocol\",\n description=\"Agent protocol: 'a2a' for A2A protocol agents, 'other' for non-A2A agents\",\n )\n metadata: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Additional metadata key-value pairs\",\n )\n capabilities: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Agent capabilities (e.g., streaming, push_notifications)\",\n )\n\n model_config = ConfigDict(populate_by_name=True)\n\n @field_validator(\"tags\", mode=\"before\")\n @classmethod\n def _normalize_tags(\n cls,\n v: str | list[str] | None,\n ) -> str:\n \"\"\"Normalize tags to comma-separated string.\"\"\"\n if v is None:\n return \"\"\n if isinstance(v, list):\n return \",\".join(v)\n return v\n\n @field_validator(\"external_tags\", mode=\"before\")\n @classmethod\n def _normalize_external_tags(\n cls,\n v: str | list[str] | None,\n ) -> str | None:\n \"\"\"Normalize external_tags to comma-separated string.\"\"\"\n if v is None:\n return None\n if isinstance(v, list):\n return \",\".join(v)\n return v\n\n @field_validator(\"path\")\n @classmethod\n def _validate_path_request(\n cls,\n v: str | None,\n ) -> str | None:\n \"\"\"Validate path format if provided.\"\"\"\n if v is None:\n return None\n return _validate_path_format(v)\n\n @field_validator(\"protocol_version\")\n @classmethod\n def _validate_protocol_version_request(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate protocol version format.\"\"\"\n return _validate_protocol_version(v)\n\n @field_validator(\"supported_protocol\")\n @classmethod\n def _validate_supported_protocol(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate and normalize supported_protocol to lowercase.\"\"\"\n v = v.lower()\n valid_values = [\"a2a\", \"other\"]\n if v not in valid_values:\n raise ValueError(f\"supported_protocol must be one of: {', '.join(valid_values)}\")\n return v\n\n @field_validator(\"visibility\")\n @classmethod\n def _validate_visibility_request(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate and normalize visibility value.\n\n Accepts \"internal\" as alias for \"private\" and \"group\" as alias\n for \"group-restricted\" for backward compatibility.\n \"\"\"\n from registry.utils.visibility import validate_visibility\n\n return validate_visibility(v)\n\n @field_validator(\"trust_level\")\n @classmethod\n def _validate_trust_level_request(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate trust_level value.\"\"\"\n valid_values = [\"unverified\", \"community\", \"verified\", \"trusted\"]\n if v not in valid_values:\n raise ValueError(f\"trust_level must be one of: {', '.join(valid_values)}\")\n return v\n\n @field_validator(\"allowed_groups\", mode=\"before\")\n @classmethod\n def _normalize_allowed_groups(\n cls,\n v: str | list[str] | None,\n ) -> list[str]:\n \"\"\"Normalize allowed_groups from comma-separated string or list.\"\"\"\n if v is None:\n return []\n if isinstance(v, str):\n return [g.strip() for g in v.split(\",\") if g.strip()]\n if isinstance(v, list):\n return [str(g).strip() for g in v if str(g).strip()]\n return []\n\n @field_validator(\"allowed_groups\", mode=\"after\")\n @classmethod\n def _validate_group_name_format(\n cls,\n v: list[str],\n ) -> list[str]:\n \"\"\"Validate group name format (alphanumeric, hyphens, underscores, dots).\"\"\"\n for name in v:\n if not GROUP_NAME_PATTERN.match(name):\n raise ValueError(\n f\"Invalid group name '{name}'. \"\n \"Group names may only contain letters, digits, hyphens, underscores, and dots.\"\n )\n return v\n\n @model_validator(mode=\"after\")\n def _validate_group_restricted_groups(\n self,\n ) -> \"AgentRegistrationRequest\":\n \"\"\"Validate group-restricted visibility has allowed groups.\"\"\"\n if self.visibility == \"group-restricted\" and not self.allowed_groups:\n raise ValueError(\n \"group-restricted visibility requires at least one allowed_group\"\n )\n return self\n" }, { "path": "registry/schemas/agent_security.py", "content": "\"\"\"\nAgent security schema models for A2A scanner integration.\n\nThis module defines Pydantic models for agent security scan results, configurations,\nand related data structures used throughout the A2A security scanning workflow.\n\"\"\"\n\nfrom pydantic import BaseModel, Field\n\n\nclass AgentSecurityScanFinding(BaseModel):\n \"\"\"Individual security finding from A2A scanner.\"\"\"\n\n skill_name: str | None = Field(\n None, description=\"Name of the skill that was scanned (if applicable)\"\n )\n agent_component: str = Field(\n \"agent_card\", description=\"Component scanned: agent_card, skill, endpoint\"\n )\n severity: str = Field(..., description=\"Severity level: CRITICAL, HIGH, MEDIUM, LOW, SAFE\")\n threat_names: list[str] = Field(\n default_factory=list, description=\"List of detected threat names\"\n )\n threat_summary: str = Field(default=\"\", description=\"Summary of threats found\")\n is_safe: bool = Field(..., description=\"Whether the component is considered safe\")\n\n\nclass AgentSecurityScanAnalyzerResult(BaseModel):\n \"\"\"Results from a specific A2A security analyzer.\"\"\"\n\n analyzer_name: str = Field(\n ..., description=\"Name of the analyzer (yara, spec, heuristic, llm, endpoint)\"\n )\n findings: list[AgentSecurityScanFinding] = Field(\n default_factory=list, description=\"List of findings from this analyzer\"\n )\n\n\nclass AgentSecurityScanResult(BaseModel):\n \"\"\"Complete security scan result for an A2A agent.\"\"\"\n\n agent_path: str = Field(..., description=\"Path of the scanned agent\")\n agent_url: str | None = Field(None, description=\"URL of the scanned agent endpoint\")\n scan_timestamp: str = Field(..., description=\"ISO timestamp of the scan\")\n is_safe: bool = Field(..., description=\"Overall safety assessment\")\n critical_issues: int = Field(default=0, description=\"Count of critical severity issues\")\n high_severity: int = Field(default=0, description=\"Count of high severity issues\")\n medium_severity: int = Field(default=0, description=\"Count of medium severity issues\")\n low_severity: int = Field(default=0, description=\"Count of low severity issues\")\n analyzers_used: list[str] = Field(\n default_factory=list, description=\"List of analyzers used in scan\"\n )\n raw_output: dict = Field(default_factory=dict, description=\"Full scanner output\")\n output_file: str | None = Field(None, description=\"Path to detailed JSON output file\")\n scan_failed: bool = Field(default=False, description=\"Whether the scan failed to complete\")\n error_message: str | None = Field(None, description=\"Error message if scan failed\")\n\n\nclass AgentSecurityScanConfig(BaseModel):\n \"\"\"Configuration for A2A agent security scanning.\"\"\"\n\n enabled: bool = Field(default=True, description=\"Enable/disable agent security scanning\")\n scan_on_registration: bool = Field(default=True, description=\"Scan agents during registration\")\n block_unsafe_agents: bool = Field(\n default=True, description=\"Disable agents that fail security scan\"\n )\n analyzers: str = Field(\n default=\"yara,spec\", description=\"Comma-separated list of analyzers to use\"\n )\n scan_timeout_seconds: int = Field(\n default=300, description=\"Timeout for security scans in seconds\"\n )\n llm_api_key: str | None = Field(None, description=\"API key for LLM-based analysis\")\n add_security_pending_tag: bool = Field(\n default=True, description=\"Add 'security-pending' tag to unsafe agents\"\n )\n\n\nclass AgentSecurityStatus(BaseModel):\n \"\"\"Security status summary for an agent.\"\"\"\n\n agent_path: str = Field(..., description=\"Agent path (e.g., /code-reviewer)\")\n agent_name: str = Field(..., description=\"Display name of the agent\")\n is_safe: bool = Field(..., description=\"Whether the agent passed security scan\")\n last_scan_timestamp: str | None = Field(None, description=\"ISO timestamp of last scan\")\n critical_issues: int = Field(default=0, description=\"Count of critical issues\")\n high_severity: int = Field(default=0, description=\"Count of high severity issues\")\n scan_status: str = Field(default=\"pending\", description=\"Status: pending, completed, failed\")\n is_disabled_for_security: bool = Field(\n default=False, description=\"Whether agent is disabled due to security issues\"\n )\n" }, { "path": "registry/schemas/ans_models.py", "content": "\"\"\"ANS (Agent Name Service) Pydantic models for the registry.\"\"\"\n\nimport logging\nfrom datetime import datetime\n\nfrom pydantic import (\n BaseModel,\n Field,\n)\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO, # Set the log level to INFO\n # Define log message format\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass ANSCertificateInfo(BaseModel):\n \"\"\"Certificate information from ANS.\"\"\"\n\n serial_number: str | None = Field(\n default=None,\n description=\"Certificate serial number\",\n )\n not_before: str | None = Field(\n default=None,\n description=\"Certificate validity start (ISO 8601)\",\n )\n not_after: str | None = Field(\n default=None,\n description=\"Certificate validity end (ISO 8601)\",\n )\n subject_dn: str | None = Field(\n default=None,\n description=\"Certificate subject distinguished name\",\n )\n issuer_dn: str | None = Field(\n default=None,\n description=\"Certificate issuer distinguished name\",\n )\n\n\nclass ANSFunctionInfo(BaseModel):\n \"\"\"Function (skill) information from an ANS endpoint.\"\"\"\n\n id: str = Field(description=\"Function identifier\")\n name: str = Field(description=\"Function display name\")\n tags: list[str] | None = Field(default=None, description=\"Function tags\")\n\n\nclass ANSEndpointInfo(BaseModel):\n \"\"\"Endpoint information from ANS.\"\"\"\n\n type: str = Field(\n description=\"Endpoint type (e.g., http)\",\n )\n url: str = Field(\n description=\"Endpoint URL\",\n )\n protocol: str | None = Field(\n default=None,\n description=\"Protocol (A2A, MCP, HTTP-API)\",\n )\n transports: list[str] = Field(\n default_factory=list,\n description=\"Transport types (e.g., STREAMABLE-HTTP, JSON-RPC)\",\n )\n functions: list[ANSFunctionInfo] = Field(\n default_factory=list,\n description=\"Functions available on this endpoint\",\n )\n\n\nclass ANSMetadata(BaseModel):\n \"\"\"ANS verification metadata stored on agents and servers.\"\"\"\n\n ans_agent_id: str = Field(\n description=\"ANS Agent ID (e.g., ans://v1.0.0.myagent.example.com)\",\n )\n linked_at: datetime = Field(\n description=\"When the ANS ID was linked\",\n )\n last_verified: datetime = Field(\n description=\"When ANS status was last verified\",\n )\n status: str = Field(\n default=\"pending\",\n description=\"Verification status: verified, expired, revoked, not_found, pending\",\n )\n domain: str | None = Field(\n default=None,\n description=\"Verified domain from ANS\",\n )\n organization: str | None = Field(\n default=None,\n description=\"Organization name from ANS\",\n )\n ans_name: str | None = Field(\n default=None,\n description=\"Full ANS name (e.g., ans://v1.0.0.myagent.example.com)\",\n )\n ans_display_name: str | None = Field(\n default=None,\n description=\"Display name as registered in ANS\",\n )\n ans_description: str | None = Field(\n default=None,\n description=\"Description as registered in ANS\",\n )\n ans_version: str | None = Field(\n default=None,\n description=\"Agent version registered in ANS\",\n )\n registered_with_ans_at: str | None = Field(\n default=None,\n description=\"When the agent was registered with ANS (ISO 8601)\",\n )\n certificate: ANSCertificateInfo | None = Field(\n default=None,\n description=\"Certificate details from ANS\",\n )\n endpoints: list[ANSEndpointInfo] = Field(\n default_factory=list,\n description=\"Endpoints registered in ANS\",\n )\n links: list[dict[str, str]] = Field(\n default_factory=list,\n description=\"HATEOAS links from ANS API (self, server-certificates, identity-certificates)\",\n )\n raw_ans_response: dict | None = Field(\n default=None,\n description=\"Full raw JSON response from the ANS API\",\n )\n\n\nclass LinkANSRequest(BaseModel):\n \"\"\"Request to link an ANS Agent ID.\"\"\"\n\n ans_agent_id: str = Field(\n description=\"ANS Agent ID to link\",\n min_length=5,\n pattern=r\"^ans://v[\\d.]+\\.[a-zA-Z0-9]([a-zA-Z0-9.-]*[a-zA-Z0-9])?$\",\n )\n\n\nclass LinkANSResponse(BaseModel):\n \"\"\"Response after linking an ANS Agent ID.\"\"\"\n\n success: bool = Field(\n description=\"Whether linking succeeded\",\n )\n message: str = Field(\n description=\"Status message\",\n )\n ans_metadata: ANSMetadata | None = Field(\n default=None,\n description=\"ANS metadata if successful\",\n )\n\n\nclass ANSSyncStats(BaseModel):\n \"\"\"Statistics from an ANS sync operation.\"\"\"\n\n total: int = Field(\n default=0,\n description=\"Total assets with ANS links checked\",\n )\n updated: int = Field(\n default=0,\n description=\"Assets whose status was updated\",\n )\n errors: int = Field(\n default=0,\n description=\"Assets that failed verification\",\n )\n duration_seconds: float = Field(\n default=0.0,\n description=\"Total sync duration in seconds\",\n )\n\n\nclass ANSIntegrationMetrics(BaseModel):\n \"\"\"ANS integration metrics for admin dashboard.\"\"\"\n\n total_linked: int = Field(\n default=0,\n description=\"Total assets with ANS links\",\n )\n by_status: dict[str, int] = Field(\n default_factory=dict,\n description=\"Count of assets by ANS status\",\n )\n by_asset_type: dict[str, int] = Field(\n default_factory=dict,\n description=\"Count of linked assets by type (agent, server)\",\n )\n last_sync_at: datetime | None = Field(\n default=None,\n description=\"When the last sync completed\",\n )\n last_sync_stats: ANSSyncStats | None = Field(\n default=None,\n description=\"Stats from the last sync\",\n )\n" }, { "path": "registry/schemas/anthropic_schema.py", "content": "\"\"\"\nPydantic models for Anthropic MCP Registry API schema.\n\nBased on: https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/api/openapi.yaml\n\"\"\"\n\nimport logging\nfrom typing import Any\n\nfrom pydantic import BaseModel, Field\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass Repository(BaseModel):\n \"\"\"Repository metadata for MCP server source code.\"\"\"\n\n url: str = Field(..., description=\"Repository URL for browsing source code\")\n source: str = Field(..., description=\"Repository hosting service identifier (e.g., 'github')\")\n id: str | None = Field(None, description=\"Repository ID from hosting service\")\n subfolder: str | None = Field(None, description=\"Path within monorepo\")\n\n\nclass StdioTransport(BaseModel):\n \"\"\"Standard I/O transport configuration.\"\"\"\n\n type: str = Field(default=\"stdio\")\n command: str | None = Field(None, description=\"Command to execute\")\n args: list[str] | None = Field(None, description=\"Command arguments\")\n env: dict[str, str] | None = Field(None, description=\"Environment variables\")\n\n\nclass StreamableHttpTransport(BaseModel):\n \"\"\"HTTP-based transport configuration.\"\"\"\n\n type: str = Field(default=\"streamable-http\")\n url: str = Field(..., description=\"HTTP endpoint URL\")\n headers: dict[str, str] | None = Field(None, description=\"HTTP headers\")\n\n\nclass SseTransport(BaseModel):\n \"\"\"Server-Sent Events transport configuration.\"\"\"\n\n type: str = Field(default=\"sse\")\n url: str = Field(..., description=\"SSE endpoint URL\")\n\n\nclass Package(BaseModel):\n \"\"\"Package information for MCP server distribution.\"\"\"\n\n registryType: str = Field(..., description=\"Registry type (npm, pypi, oci, etc.)\")\n identifier: str = Field(..., description=\"Package identifier or URL\")\n version: str = Field(..., description=\"Specific package version\")\n registryBaseUrl: str | None = Field(None, description=\"Base URL of package registry\")\n transport: dict[str, Any] = Field(..., description=\"Transport configuration\")\n runtimeHint: str | None = Field(None, description=\"Runtime hint (npx, uvx, docker, etc.)\")\n\n\nclass ServerDetail(BaseModel):\n \"\"\"Detailed MCP server information.\"\"\"\n\n model_config = {\"populate_by_name\": True}\n\n name: str = Field(..., description=\"Server name in reverse-DNS format\")\n description: str = Field(..., description=\"Server description\")\n version: str = Field(..., description=\"Server version\")\n title: str | None = Field(None, description=\"Human-readable server name\")\n repository: Repository | None = Field(None, description=\"Repository information\")\n websiteUrl: str | None = Field(None, description=\"Server website URL\")\n packages: list[Package] | None = Field(None, description=\"Package distributions\")\n meta: dict[str, Any] | None = Field(\n None, alias=\"_meta\", serialization_alias=\"_meta\", description=\"Extensible metadata\"\n )\n\n\nclass ServerResponse(BaseModel):\n \"\"\"Response for single server query.\"\"\"\n\n model_config = {\"populate_by_name\": True}\n\n server: ServerDetail = Field(..., description=\"Server details\")\n meta: dict[str, Any] | None = Field(\n None, alias=\"_meta\", serialization_alias=\"_meta\", description=\"Registry-managed metadata\"\n )\n\n\nclass PaginationMetadata(BaseModel):\n \"\"\"Pagination information for server lists.\"\"\"\n\n nextCursor: str | None = Field(None, description=\"Cursor for next page\")\n count: int | None = Field(None, description=\"Number of items in current page\")\n\n\nclass ServerList(BaseModel):\n \"\"\"Response for server list queries.\"\"\"\n\n servers: list[ServerResponse] = Field(..., description=\"List of servers\")\n metadata: PaginationMetadata | None = Field(None, description=\"Pagination info\")\n\n\nclass ErrorResponse(BaseModel):\n \"\"\"Standard error response.\"\"\"\n\n error: str = Field(..., description=\"Error message\")\n" }, { "path": "registry/schemas/backend_session_models.py", "content": "\"\"\"\nBackend session data models for virtual MCP server session management.\n\nDefines schemas for storing and managing per-client backend MCP sessions\nin MongoDB. Sessions map a client session ID + backend location to the\nbackend's MCP session ID, enabling session isolation and persistence.\n\"\"\"\n\nfrom datetime import UTC, datetime\n\nfrom pydantic import BaseModel, Field\n\n\ndef _utc_now() -> datetime:\n \"\"\"Return current UTC datetime (timezone-aware).\"\"\"\n return datetime.now(UTC)\n\n\nclass BackendSessionDocument(BaseModel):\n \"\"\"MongoDB document for a backend MCP session.\n\n Stored with _id = ':' for fast lookups.\n TTL index on last_used_at auto-expires idle sessions.\n \"\"\"\n\n client_session_id: str = Field(\n ...,\n description=\"Client-facing session ID (e.g., 'vs-abc123')\",\n )\n backend_key: str = Field(\n ...,\n description=\"Backend location key (e.g., '/_vs_backend_weather_')\",\n )\n backend_session_id: str = Field(\n ...,\n description=\"Session ID returned by the backend MCP server\",\n )\n user_id: str = Field(\n ...,\n description=\"User identity from auth context (for audit)\",\n )\n virtual_server_path: str = Field(\n ...,\n description=\"Virtual server path (e.g., '/virtual/my-server')\",\n )\n created_at: datetime = Field(\n default_factory=_utc_now,\n description=\"When the backend session was first created\",\n )\n last_used_at: datetime = Field(\n default_factory=_utc_now,\n description=\"Last time this session was accessed (drives TTL expiry)\",\n )\n\n\nclass ClientSessionDocument(BaseModel):\n \"\"\"MongoDB document for a client session.\n\n Stored with _id = 'client:' for validation lookups.\n TTL index on last_used_at auto-expires idle sessions.\n \"\"\"\n\n client_session_id: str = Field(\n ...,\n description=\"Client-facing session ID (e.g., 'vs-abc123')\",\n )\n user_id: str = Field(\n ...,\n description=\"User identity from auth context\",\n )\n virtual_server_path: str = Field(\n ...,\n description=\"Virtual server path this session was created for\",\n )\n created_at: datetime = Field(\n default_factory=_utc_now,\n description=\"When the client session was created\",\n )\n last_used_at: datetime = Field(\n default_factory=_utc_now,\n description=\"Last time this session was accessed (drives TTL expiry)\",\n )\n\n\nclass StoreSessionRequest(BaseModel):\n \"\"\"Request body for storing a backend session via internal API.\"\"\"\n\n backend_session_id: str = Field(\n ...,\n description=\"Session ID from the backend MCP server\",\n )\n client_session_id: str = Field(\n ...,\n description=\"Client-facing session ID\",\n )\n user_id: str = Field(\n default=\"anonymous\",\n description=\"User identity from auth context\",\n )\n virtual_server_path: str = Field(\n default=\"\",\n description=\"Virtual server path\",\n )\n\n\nclass CreateClientSessionRequest(BaseModel):\n \"\"\"Request body for creating a client session via internal API.\"\"\"\n\n user_id: str = Field(\n default=\"anonymous\",\n description=\"User identity from auth context\",\n )\n virtual_server_path: str = Field(\n default=\"\",\n description=\"Virtual server path this session is for\",\n )\n\n\nclass CreateClientSessionResponse(BaseModel):\n \"\"\"Response body after creating a client session.\"\"\"\n\n client_session_id: str = Field(\n ...,\n description=\"Generated client session ID\",\n )\n\n\nclass GetBackendSessionResponse(BaseModel):\n \"\"\"Response body for backend session lookup.\"\"\"\n\n backend_session_id: str = Field(\n ...,\n description=\"Backend MCP session ID\",\n )\n" }, { "path": "registry/schemas/federation_schema.py", "content": "\"\"\"Simplified federation configuration schemas.\"\"\"\n\nfrom typing import Any\n\nfrom pydantic import BaseModel, Field, model_validator\n\n\nclass AnthropicServerConfig(BaseModel):\n \"\"\"Anthropic server configuration.\"\"\"\n\n name: str\n\n\nclass AnthropicFederationConfig(BaseModel):\n \"\"\"Anthropic federation configuration.\"\"\"\n\n enabled: bool = False\n endpoint: str = \"https://registry.modelcontextprotocol.io\"\n sync_on_startup: bool = False\n servers: list[AnthropicServerConfig] = Field(default_factory=list)\n\n\nclass AsorAgentConfig(BaseModel):\n \"\"\"ASOR agent configuration.\"\"\"\n\n id: str\n\n\nclass AsorFederationConfig(BaseModel):\n \"\"\"ASOR federation configuration.\"\"\"\n\n enabled: bool = False\n endpoint: str = \"\"\n auth_env_var: str | None = None\n sync_on_startup: bool = False\n agents: list[AsorAgentConfig] = Field(default_factory=list)\n\n\nclass AwsRegistryConfig(BaseModel):\n \"\"\"Configuration for a single AWS Agent Registry to sync from.\n\n For cross-account or cross-region access, provide aws_account_id,\n assume_role_arn, and/or aws_region per registry. The gateway assumes\n the IAM role via STS to read from the remote registry.\n \"\"\"\n\n registry_id: str\n aws_account_id: str | None = None\n aws_region: str | None = None\n assume_role_arn: str | None = None\n descriptor_types: list[str] = Field(\n default_factory=lambda: [\"MCP\", \"A2A\", \"CUSTOM\", \"AGENT_SKILLS\"]\n )\n sync_status_filter: str = \"APPROVED\"\n\n\nclass AwsRegistryFederationConfig(BaseModel):\n \"\"\"AWS Agent Registry federation configuration.\"\"\"\n\n enabled: bool = False\n aws_region: str = \"us-east-1\"\n sync_on_startup: bool = False\n sync_interval_minutes: int = 60\n sync_timeout_seconds: int = 300\n max_concurrent_fetches: int = 5\n registries: list[AwsRegistryConfig] = Field(default_factory=list)\n\n\nclass FederationConfig(BaseModel):\n \"\"\"Root federation configuration.\"\"\"\n\n anthropic: AnthropicFederationConfig = Field(default_factory=AnthropicFederationConfig)\n asor: AsorFederationConfig = Field(default_factory=AsorFederationConfig)\n aws_registry: AwsRegistryFederationConfig = Field(default_factory=AwsRegistryFederationConfig)\n\n @model_validator(mode=\"before\")\n @classmethod\n def _migrate_agentcore_key(cls, data: Any) -> Any:\n \"\"\"Accept old 'agentcore' key as alias for 'aws_registry'.\n\n MongoDB documents created before the rename use 'agentcore'.\n This validator transparently maps the old key so existing\n documents deserialize without a migration script.\n \"\"\"\n if isinstance(data, dict) and \"agentcore\" in data and \"aws_registry\" not in data:\n data[\"aws_registry\"] = data.pop(\"agentcore\")\n return data\n\n def is_any_federation_enabled(self) -> bool:\n \"\"\"Check if any federation is enabled.\"\"\"\n return self.anthropic.enabled or self.asor.enabled or self.aws_registry.enabled\n\n def get_enabled_federations(self) -> list[str]:\n \"\"\"Get list of enabled federation names.\"\"\"\n enabled = []\n if self.anthropic.enabled:\n enabled.append(\"anthropic\")\n if self.asor.enabled:\n enabled.append(\"asor\")\n if self.aws_registry.enabled:\n enabled.append(\"aws_registry\")\n return enabled\n\n\n# Backward-compatible aliases for the renamed classes\nAgentCoreRegistryConfig = AwsRegistryConfig\nAgentCoreFederationConfig = AwsRegistryFederationConfig\n\n\n# Add missing FederatedServer class for compatibility\nclass FederatedServer(BaseModel):\n \"\"\"Federated server configuration.\"\"\"\n\n name: str\n endpoint: str\n enabled: bool = True\n" }, { "path": "registry/schemas/idp_m2m_client.py", "content": "\"\"\"IdP M2M Client model for MongoDB storage.\n\nThis module defines the schema for storing M2M client applications\nand their group mappings in MongoDB. This allows the registry to track\nservice accounts from any IdP (Keycloak, Okta, Entra) and their permissions\nwithout hardcoding them in authorization server expressions.\n\nThis collection serves as the authorization database for M2M clients.\n\"\"\"\n\nimport re\nfrom datetime import datetime\n\nfrom pydantic import BaseModel, Field, field_validator\n\nMANUAL_PROVIDER: str = \"manual\"\n\n_CLIENT_ID_PATTERN: re.Pattern = re.compile(r\"^[A-Za-z0-9_\\-.:]{1,256}$\")\n\n\ndef _validate_client_id(value: str) -> str:\n \"\"\"Validate that client_id matches the allowed character set.\"\"\"\n if not _CLIENT_ID_PATTERN.match(value):\n raise ValueError(\n \"client_id must match ^[A-Za-z0-9_\\\\-.:]{1,256}$ \"\n \"(alphanumerics, dash, underscore, dot, colon only)\"\n )\n return value\n\n\nclass IdPM2MClient(BaseModel):\n \"\"\"IdP M2M client application with group mappings.\n\n Stores information about M2M service accounts from any identity provider\n including their client IDs, groups, and metadata. This data is used for\n authorization decisions when JWT tokens have empty groups claim.\n \"\"\"\n\n client_id: str = Field(..., description=\"IdP application client ID\")\n name: str = Field(..., description=\"Application name\")\n description: str | None = Field(None, description=\"Application description\")\n groups: list[str] = Field(default_factory=list, description=\"Groups this client belongs to\")\n enabled: bool = Field(default=True, description=\"Whether client is active\")\n provider: str = Field(..., description=\"Identity provider (okta, keycloak, entra, manual)\")\n created_at: datetime = Field(\n default_factory=datetime.utcnow, description=\"When record was created\"\n )\n updated_at: datetime = Field(\n default_factory=datetime.utcnow, description=\"When record was last updated\"\n )\n idp_app_id: str | None = Field(None, description=\"IdP internal app ID\")\n created_by: str | None = Field(\n default=None,\n description=(\n \"Username of operator who registered this M2M client. \"\n \"Populated only for records with provider=manual.\"\n ),\n )\n\n class Config:\n \"\"\"Pydantic model configuration.\"\"\"\n\n json_schema_extra = {\n \"example\": {\n \"client_id\": \"0oa1100req1AzfKaY698\",\n \"name\": \"ai-agent\",\n \"description\": \"AI agent with admin access\",\n \"groups\": [\"registry-admins\"],\n \"enabled\": True,\n \"provider\": \"okta\",\n \"idp_app_id\": \"0oa1100req1AzfKaY698\",\n }\n }\n\n\nclass IdPM2MClientUpdate(BaseModel):\n \"\"\"Payload for updating an IdP M2M client's group mappings (legacy).\"\"\"\n\n groups: list[str] = Field(..., description=\"New list of groups for this client\", min_length=1)\n description: str | None = Field(None, description=\"Updated description\")\n\n\nclass IdPM2MClientCreate(BaseModel):\n \"\"\"Request body for POST /api/iam/m2m-clients.\n\n Creates a new M2M client record with provider=manual. Does not require\n any IdP Admin API token.\n \"\"\"\n\n client_id: str = Field(\n ...,\n description=\"IdP application client ID\",\n min_length=1,\n max_length=256,\n )\n client_name: str = Field(\n ...,\n description=\"Human-readable name for the client\",\n min_length=1,\n max_length=256,\n )\n groups: list[str] = Field(\n default_factory=list,\n description=\"Groups this client belongs to (may be empty)\",\n )\n description: str | None = Field(\n default=None,\n description=\"Optional human-readable description\",\n max_length=1024,\n )\n\n @field_validator(\"client_id\")\n @classmethod\n def _validate_client_id_format(cls, v: str) -> str:\n return _validate_client_id(v)\n\n\nclass IdPM2MClientPatch(BaseModel):\n \"\"\"Request body for PATCH /api/iam/m2m-clients/{client_id}.\n\n Patch semantics use Pydantic v2's `model_dump(exclude_unset=True)` in the\n service, so fields not present in the request body are NOT written. Fields\n explicitly present (including None or empty list) ARE written.\n \"\"\"\n\n client_name: str | None = Field(\n default=None,\n min_length=1,\n max_length=256,\n )\n groups: list[str] | None = Field(\n default=None,\n description=\"New groups list. Empty list clears groups.\",\n )\n description: str | None = Field(\n default=None,\n max_length=1024,\n )\n enabled: bool | None = Field(default=None)\n\n\nclass M2MClientListResponse(BaseModel):\n \"\"\"Paginated response envelope for GET /api/iam/m2m-clients.\"\"\"\n\n total: int = Field(..., description=\"Total number of matching records\")\n limit: int = Field(..., description=\"Limit applied to this page\")\n skip: int = Field(..., description=\"Offset applied to this page\")\n items: list[IdPM2MClient] = Field(\n default_factory=list,\n description=\"Records on this page\",\n )\n" }, { "path": "registry/schemas/management.py", "content": "from __future__ import annotations\n\nfrom pydantic import BaseModel, EmailStr, Field\n\n\nclass M2MAccountRequest(BaseModel):\n \"\"\"Payload for creating a Keycloak service account client.\"\"\"\n\n name: str = Field(..., min_length=1)\n groups: list[str] = Field(..., min_length=1)\n description: str | None = None\n\n\nclass HumanUserRequest(BaseModel):\n \"\"\"Payload for creating a Keycloak human user.\"\"\"\n\n username: str = Field(..., min_length=1)\n email: EmailStr\n first_name: str = Field(..., min_length=1, alias=\"firstname\")\n last_name: str = Field(..., min_length=1, alias=\"lastname\")\n groups: list[str] = Field(..., min_length=1)\n password: str | None = Field(\n None, description=\"Initial password (optional, generated elsewhere)\"\n )\n\n model_config = {\"populate_by_name\": True}\n\n\nclass UserDeleteResponse(BaseModel):\n \"\"\"Standard response returned when a Keycloak user is deleted.\"\"\"\n\n username: str\n deleted: bool = True\n\n\nclass UserSummary(BaseModel):\n \"\"\"Subset of user information exposed through the API.\"\"\"\n\n id: str\n username: str\n email: str | None = None\n firstName: str | None = None\n lastName: str | None = None\n enabled: bool = True\n groups: list[str] = Field(default_factory=list)\n\n\nclass UserListResponse(BaseModel):\n \"\"\"Wrapper for list users endpoint.\"\"\"\n\n users: list[UserSummary] = Field(default_factory=list)\n total: int\n\n\nclass GroupCreateRequest(BaseModel):\n \"\"\"Payload for creating a group.\n\n Note: The backend currently only processes name and description.\n The scope_config field is accepted but not yet wired to\n scope_service.import_group(). Future work should pass\n server_access, group_mappings, and ui_permissions through\n to the scope service when creating a group.\n \"\"\"\n\n name: str = Field(..., min_length=1)\n description: str | None = None\n scope_config: dict | None = Field(\n None,\n description=\"Scope configuration (accepted but not yet applied server-side)\",\n )\n\n\nclass GroupSummary(BaseModel):\n \"\"\"Group information.\"\"\"\n\n id: str\n name: str\n path: str\n attributes: dict | None = None\n\n\nclass GroupListResponse(BaseModel):\n \"\"\"Response for listing groups.\"\"\"\n\n groups: list[GroupSummary] = Field(default_factory=list)\n total: int\n\n\nclass GroupDeleteResponse(BaseModel):\n \"\"\"Response when a Keycloak group is deleted.\"\"\"\n\n name: str\n deleted: bool = True\n\n\nclass UpdateUserGroupsRequest(BaseModel):\n \"\"\"Payload for updating a user's group memberships.\"\"\"\n\n groups: list[str] = Field(..., description=\"List of group names to assign\")\n\n\nclass UpdateUserGroupsResponse(BaseModel):\n \"\"\"Response after updating user's group memberships.\"\"\"\n\n username: str\n groups: list[str] = Field(default_factory=list)\n added: list[str] = Field(default_factory=list)\n removed: list[str] = Field(default_factory=list)\n\n\nclass GroupUpdateRequest(BaseModel):\n \"\"\"Request to update a group.\"\"\"\n\n description: str | None = None\n scope_config: dict | None = Field(\n None,\n description=\"Scope configuration (server_access, ui_permissions, etc.)\",\n )\n\n\nclass GroupDetailResponse(BaseModel):\n \"\"\"Detailed group information.\"\"\"\n\n id: str\n name: str\n path: str | None = None\n description: str | None = None\n server_access: list | None = None\n group_mappings: list | None = None\n ui_permissions: dict | None = None\n agent_access: list | None = None\n" }, { "path": "registry/schemas/okta_m2m_client.py", "content": "\"\"\"Okta M2M Client models for API routes.\n\nThis module defines the request/response schemas for Okta M2M client\nmanagement endpoints.\n\"\"\"\n\nfrom datetime import datetime\n\nfrom pydantic import BaseModel, Field\n\n\nclass OktaM2MClient(BaseModel):\n \"\"\"Okta M2M client application with group mappings.\"\"\"\n\n client_id: str = Field(..., description=\"Okta application client ID\")\n name: str = Field(..., description=\"Application name/label\")\n description: str | None = Field(None, description=\"Application description\")\n groups: list[str] = Field(default_factory=list, description=\"Groups this client belongs to\")\n enabled: bool = Field(default=True, description=\"Whether client is active\")\n okta_app_id: str | None = Field(None, description=\"Okta internal app ID\")\n last_synced: datetime | None = Field(None, description=\"Last sync timestamp\")\n created_at: datetime = Field(\n default_factory=datetime.utcnow, description=\"When record was created\"\n )\n updated_at: datetime = Field(\n default_factory=datetime.utcnow, description=\"When record was last updated\"\n )\n\n class Config:\n \"\"\"Pydantic model configuration.\"\"\"\n\n json_schema_extra = {\n \"example\": {\n \"client_id\": \"0oa1100req1AzfKaY698\",\n \"name\": \"ai-agent\",\n \"description\": \"AI agent with admin access\",\n \"groups\": [\"registry-admins\"],\n \"enabled\": True,\n \"okta_app_id\": \"0oa1100req1AzfKaY698\",\n }\n }\n\n\nclass OktaM2MClientUpdate(BaseModel):\n \"\"\"Payload for updating an Okta M2M client's group mappings.\"\"\"\n\n groups: list[str] = Field(..., description=\"New list of groups for this client\", min_length=1)\n\n\nclass OktaSyncRequest(BaseModel):\n \"\"\"Request payload for Okta M2M sync.\"\"\"\n\n force_full_sync: bool = False\n\n\nclass OktaSyncResponse(BaseModel):\n \"\"\"Response from Okta M2M sync operation.\"\"\"\n\n synced_count: int\n added_count: int\n updated_count: int\n removed_count: int\n errors: list[str]\n" }, { "path": "registry/schemas/peer_federation_schema.py", "content": "\"\"\"\nPydantic models for peer-to-peer federation in MCP Gateway Registry.\n\nThis module defines configuration and metadata models for federated registry\nsynchronization, enabling mesh topology where any registry can sync from any other.\n\nBased on: docs/federation.md and implementation plan\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Any, Literal\n\nfrom pydantic import (\n BaseModel,\n ConfigDict,\n Field,\n field_validator,\n model_validator,\n)\n\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nMIN_SYNC_INTERVAL_MINUTES: int = 5\nMAX_SYNC_INTERVAL_MINUTES: int = 1440 # 24 hours\nDEFAULT_SYNC_INTERVAL_MINUTES: int = 60\nMAX_SYNC_HISTORY_ENTRIES: int = 100\n\n\ndef _validate_endpoint_url(\n url: str,\n) -> str:\n \"\"\"\n Validate peer registry endpoint URL format.\n\n Args:\n url: Endpoint URL to validate\n\n Returns:\n Validated URL string\n\n Raises:\n ValueError: If URL format is invalid\n \"\"\"\n if not url:\n raise ValueError(\"Endpoint URL cannot be empty\")\n\n if not (url.startswith(\"http://\") or url.startswith(\"https://\")):\n raise ValueError(\"Endpoint URL must use HTTP or HTTPS protocol\")\n\n # Remove trailing slash for consistency\n url = url.rstrip(\"/\")\n\n try:\n from urllib.parse import urlparse\n\n parsed = urlparse(url)\n if not parsed.netloc:\n raise ValueError(\"Endpoint URL must include a valid hostname\")\n except Exception as e:\n raise ValueError(f\"Invalid endpoint URL format: {e}\")\n\n return url\n\n\ndef _validate_peer_id(\n peer_id: str,\n) -> str:\n \"\"\"\n Validate peer ID format for use as filename.\n\n Args:\n peer_id: Peer identifier to validate\n\n Returns:\n Validated peer ID\n\n Raises:\n ValueError: If peer ID format is invalid\n \"\"\"\n if not peer_id:\n raise ValueError(\"Peer ID cannot be empty\")\n\n if not peer_id.strip():\n raise ValueError(\"Peer ID cannot be whitespace only\")\n\n # Check for invalid filename characters\n invalid_chars = [\"/\", \"\\\\\", \":\", \"*\", \"?\", '\"', \"<\", \">\", \"|\", \"\\0\"]\n for char in invalid_chars:\n if char in peer_id:\n raise ValueError(f\"Peer ID cannot contain '{char}' character\")\n\n # Limit length for filesystem compatibility\n if len(peer_id) > 255:\n raise ValueError(\"Peer ID cannot exceed 255 characters\")\n\n return peer_id.strip()\n\n\nclass SyncMetadata(BaseModel):\n \"\"\"\n Metadata for items synced from peer registries.\n\n Tracks the origin of synced items and local customizations,\n enabling proper merge behavior during subsequent syncs.\n \"\"\"\n\n upstream_peer_id: str = Field(\n ...,\n description=\"ID of the peer registry this item was synced from\",\n )\n upstream_path: str = Field(\n ...,\n description=\"Original path of the item in the upstream registry\",\n )\n sync_generation: int = Field(\n default=1,\n ge=1,\n description=\"Generation number for incremental sync tracking\",\n )\n last_synced_at: datetime = Field(\n ...,\n description=\"Timestamp of the last successful sync\",\n )\n is_orphaned: bool = Field(\n default=False,\n description=\"Whether this item no longer exists in upstream\",\n )\n orphaned_at: datetime | None = Field(\n default=None,\n description=\"Timestamp when item was marked as orphaned\",\n )\n local_overrides: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Fields that have been locally customized\",\n )\n is_read_only: bool = Field(\n default=True,\n description=\"Whether core fields are read-only (synced items are read-only)\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True,\n json_schema_extra={\n \"example\": {\n \"upstream_peer_id\": \"central-registry\",\n \"upstream_path\": \"/finance-tools\",\n \"sync_generation\": 42,\n \"last_synced_at\": \"2024-01-15T10:30:00Z\",\n \"is_orphaned\": False,\n \"local_overrides\": {\"tags\": [\"local-tag\"]},\n \"is_read_only\": True,\n }\n },\n )\n\n @model_validator(mode=\"after\")\n def _validate_orphan_timestamp(\n self,\n ) -> \"SyncMetadata\":\n \"\"\"Validate orphaned_at is set when is_orphaned is True.\"\"\"\n if self.is_orphaned and self.orphaned_at is None:\n # Auto-set orphaned_at if not provided\n object.__setattr__(self, \"orphaned_at\", datetime.now(UTC))\n return self\n\n\nclass PeerRegistryConfig(BaseModel):\n \"\"\"\n Configuration for a peer registry connection.\n\n Defines how to connect to and sync from a peer registry,\n including endpoint, sync mode, and filtering options.\n \"\"\"\n\n peer_id: str = Field(\n ...,\n min_length=1,\n max_length=255,\n description=\"Unique identifier for this peer registry\",\n )\n name: str = Field(\n ...,\n min_length=1,\n max_length=255,\n description=\"Human-readable display name for the peer\",\n )\n endpoint: str = Field(\n ...,\n description=\"Base URL of the peer registry API\",\n )\n enabled: bool = Field(\n default=True,\n description=\"Whether sync from this peer is enabled\",\n )\n\n # Sync configuration\n sync_mode: Literal[\"all\", \"whitelist\", \"tag_filter\"] = Field(\n default=\"all\",\n description=\"Sync mode: all items, whitelist only, or tag-based filtering\",\n )\n whitelist_servers: list[str] = Field(\n default_factory=list,\n description=\"Server paths to sync when sync_mode is 'whitelist'\",\n )\n whitelist_agents: list[str] = Field(\n default_factory=list,\n description=\"Agent paths to sync when sync_mode is 'whitelist'\",\n )\n tag_filters: list[str] = Field(\n default_factory=list,\n description=\"Tags to filter by when sync_mode is 'tag_filter'\",\n )\n\n # Scheduling\n sync_interval_minutes: int = Field(\n default=DEFAULT_SYNC_INTERVAL_MINUTES,\n ge=MIN_SYNC_INTERVAL_MINUTES,\n le=MAX_SYNC_INTERVAL_MINUTES,\n description=f\"Sync interval in minutes ({MIN_SYNC_INTERVAL_MINUTES}-{MAX_SYNC_INTERVAL_MINUTES})\",\n )\n\n # Federation static token (for peer-to-peer sync without OAuth2)\n # This is the FEDERATION_STATIC_TOKEN value from the remote peer registry.\n # When set, the client uses this directly as Bearer token instead of OAuth2.\n federation_token: str | None = Field(\n default=None,\n description=\"Federation static token from the remote peer registry. \"\n \"Used as Bearer token for sync requests when the peer has \"\n \"FEDERATION_STATIC_TOKEN_AUTH_ENABLED=true.\",\n )\n\n # Identity binding (for peer identification via OAuth2 tokens)\n expected_client_id: str | None = Field(\n default=None,\n description=\"Azure AD/Keycloak client_id (azp claim) that identifies this peer\",\n )\n expected_issuer: str | None = Field(\n default=None,\n description=\"Expected token issuer URL (for cross-tenant validation)\",\n )\n\n # Metadata (set by service, not user input)\n created_at: datetime | None = Field(\n default=None,\n description=\"When this peer config was created\",\n )\n updated_at: datetime | None = Field(\n default=None,\n description=\"When this peer config was last updated\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True,\n json_schema_extra={\n \"example\": {\n \"peer_id\": \"central-registry\",\n \"name\": \"Central MCP Registry\",\n \"endpoint\": \"https://central.registry.company.com\",\n \"enabled\": True,\n \"sync_mode\": \"all\",\n \"sync_interval_minutes\": 30,\n \"federation_token\": None,\n \"expected_client_id\": \"uuid-central-1111-2222-3333\",\n \"expected_issuer\": \"https://login.microsoftonline.com/tenant-id/v2.0\",\n }\n },\n )\n\n @field_validator(\"peer_id\")\n @classmethod\n def _validate_peer_id_field(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate peer ID format.\"\"\"\n return _validate_peer_id(v)\n\n @field_validator(\"endpoint\")\n @classmethod\n def _validate_endpoint_field(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate endpoint URL format.\"\"\"\n return _validate_endpoint_url(v)\n\n @model_validator(mode=\"after\")\n def _validate_sync_mode_config(\n self,\n ) -> \"PeerRegistryConfig\":\n \"\"\"Validate sync mode has required configuration.\"\"\"\n if self.sync_mode == \"whitelist\":\n if not self.whitelist_servers and not self.whitelist_agents:\n logger.warning(\n f\"Peer '{self.peer_id}' has sync_mode='whitelist' but no \"\n \"whitelist_servers or whitelist_agents configured. \"\n \"No items will be synced.\"\n )\n elif self.sync_mode == \"tag_filter\":\n if not self.tag_filters:\n logger.warning(\n f\"Peer '{self.peer_id}' has sync_mode='tag_filter' but no \"\n \"tag_filters configured. No items will be synced.\"\n )\n return self\n\n\nclass SyncHistoryEntry(BaseModel):\n \"\"\"\n Record of a single sync operation.\n\n Captures the outcome of a sync attempt including success/failure,\n items synced, and any errors encountered.\n \"\"\"\n\n sync_id: str = Field(\n ...,\n description=\"Unique identifier for this sync operation\",\n )\n started_at: datetime = Field(\n ...,\n description=\"When the sync operation started\",\n )\n completed_at: datetime | None = Field(\n default=None,\n description=\"When the sync operation completed\",\n )\n success: bool = Field(\n default=False,\n description=\"Whether the sync completed successfully\",\n )\n servers_synced: int = Field(\n default=0,\n ge=0,\n description=\"Number of servers synced\",\n )\n agents_synced: int = Field(\n default=0,\n ge=0,\n description=\"Number of agents synced\",\n )\n servers_orphaned: int = Field(\n default=0,\n ge=0,\n description=\"Number of servers marked as orphaned\",\n )\n agents_orphaned: int = Field(\n default=0,\n ge=0,\n description=\"Number of agents marked as orphaned\",\n )\n error_message: str | None = Field(\n default=None,\n description=\"Error message if sync failed\",\n )\n sync_generation: int = Field(\n default=0,\n ge=0,\n description=\"Generation number used for this sync\",\n )\n full_sync: bool = Field(\n default=False,\n description=\"Whether this was a full sync (vs incremental)\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True,\n json_schema_extra={\n \"example\": {\n \"sync_id\": \"sync-2024-01-15-103000\",\n \"started_at\": \"2024-01-15T10:30:00Z\",\n \"completed_at\": \"2024-01-15T10:30:15Z\",\n \"success\": True,\n \"servers_synced\": 42,\n \"agents_synced\": 15,\n \"servers_orphaned\": 0,\n \"agents_orphaned\": 1,\n \"sync_generation\": 100,\n \"full_sync\": False,\n }\n },\n )\n\n\nclass PeerSyncStatus(BaseModel):\n \"\"\"\n Current sync status for a peer registry.\n\n Tracks the state of synchronization including last sync time,\n health status, and recent sync history.\n \"\"\"\n\n peer_id: str = Field(\n ...,\n description=\"ID of the peer registry\",\n )\n is_healthy: bool = Field(\n default=False,\n description=\"Whether the peer is currently reachable\",\n )\n last_health_check: datetime | None = Field(\n default=None,\n description=\"When health was last checked\",\n )\n last_successful_sync: datetime | None = Field(\n default=None,\n description=\"When last successful sync completed\",\n )\n last_sync_attempt: datetime | None = Field(\n default=None,\n description=\"When last sync was attempted\",\n )\n current_generation: int = Field(\n default=0,\n ge=0,\n description=\"Current sync generation number\",\n )\n total_servers_synced: int = Field(\n default=0,\n ge=0,\n description=\"Total number of servers from this peer\",\n )\n total_agents_synced: int = Field(\n default=0,\n ge=0,\n description=\"Total number of agents from this peer\",\n )\n sync_in_progress: bool = Field(\n default=False,\n description=\"Whether a sync is currently running\",\n )\n consecutive_failures: int = Field(\n default=0,\n ge=0,\n description=\"Number of consecutive sync failures\",\n )\n sync_history: list[SyncHistoryEntry] = Field(\n default_factory=list,\n description=f\"Recent sync history (max {MAX_SYNC_HISTORY_ENTRIES} entries)\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True,\n json_schema_extra={\n \"example\": {\n \"peer_id\": \"central-registry\",\n \"is_healthy\": True,\n \"last_health_check\": \"2024-01-15T10:35:00Z\",\n \"last_successful_sync\": \"2024-01-15T10:30:15Z\",\n \"current_generation\": 100,\n \"total_servers_synced\": 42,\n \"total_agents_synced\": 15,\n \"sync_in_progress\": False,\n \"consecutive_failures\": 0,\n }\n },\n )\n\n def add_history_entry(\n self,\n entry: SyncHistoryEntry,\n ) -> None:\n \"\"\"\n Add a sync history entry, maintaining max entries limit.\n\n Args:\n entry: The sync history entry to add\n \"\"\"\n self.sync_history.insert(0, entry)\n if len(self.sync_history) > MAX_SYNC_HISTORY_ENTRIES:\n self.sync_history = self.sync_history[:MAX_SYNC_HISTORY_ENTRIES]\n\n\nclass SyncResult(BaseModel):\n \"\"\"\n Result of a sync operation.\n\n Returned by sync methods to indicate success/failure and\n provide details about what was synced.\n \"\"\"\n\n success: bool = Field(\n ...,\n description=\"Whether the sync completed successfully\",\n )\n peer_id: str = Field(\n ...,\n description=\"ID of the peer that was synced\",\n )\n servers_synced: int = Field(\n default=0,\n ge=0,\n description=\"Number of servers synced\",\n )\n agents_synced: int = Field(\n default=0,\n ge=0,\n description=\"Number of agents synced\",\n )\n servers_orphaned: int = Field(\n default=0,\n ge=0,\n description=\"Number of servers marked as orphaned\",\n )\n agents_orphaned: int = Field(\n default=0,\n ge=0,\n description=\"Number of agents marked as orphaned\",\n )\n error_message: str | None = Field(\n default=None,\n description=\"Error message if sync failed\",\n )\n duration_seconds: float = Field(\n default=0.0,\n ge=0.0,\n description=\"Duration of the sync operation in seconds\",\n )\n new_generation: int = Field(\n default=0,\n ge=0,\n description=\"New generation number after sync\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True,\n )\n\n\nclass FederationExportResponse(BaseModel):\n \"\"\"\n Response model for federation export API endpoints.\n\n Contains items to be synced by peer registries along with\n metadata for incremental sync support.\n \"\"\"\n\n items: list[dict[str, Any]] = Field(\n default_factory=list,\n description=\"List of items (servers or agents) to sync\",\n )\n sync_generation: int = Field(\n ...,\n description=\"Current generation number for incremental sync\",\n )\n total_count: int = Field(\n ...,\n ge=0,\n description=\"Total number of items available\",\n )\n has_more: bool = Field(\n default=False,\n description=\"Whether more items are available (pagination)\",\n )\n registry_id: str = Field(\n ...,\n description=\"ID of the source registry\",\n )\n\n model_config = ConfigDict(\n populate_by_name=True,\n json_schema_extra={\n \"example\": {\n \"items\": [{\"path\": \"/finance-tools\", \"name\": \"Finance Tools\"}],\n \"sync_generation\": 100,\n \"total_count\": 42,\n \"has_more\": False,\n \"registry_id\": \"central-registry\",\n }\n },\n )\n" }, { "path": "registry/schemas/registration_gate_models.py", "content": "\"\"\"Pydantic models for the registration gate (admission control webhook).\"\"\"\n\nfrom enum import Enum\n\nfrom pydantic import (\n BaseModel,\n Field,\n)\n\n\nclass RegistrationGateAuthType(str, Enum):\n \"\"\"Authentication type for calling the gate endpoint.\"\"\"\n\n NONE = \"none\"\n API_KEY = \"api_key\"\n BEARER = \"bearer\"\n\n\nclass RegistrationGateRequest(BaseModel):\n \"\"\"Payload sent to the registration gate endpoint.\n\n The registration_payload is sanitized before sending:\n all credential fields (auth_credential, auth_credential_encrypted,\n tokens, secrets, API keys) are stripped to prevent leaking\n sensitive data to the external gate endpoint.\n \"\"\"\n\n asset_type: str = Field(\n ...,\n description=\"Type of asset: 'agent', 'server', or 'skill'\",\n )\n operation: str = Field(\n ...,\n description=\"Operation type: 'register' or 'update'\",\n )\n source_api: str = Field(\n ...,\n description=\"Source API path that triggered the request\",\n )\n registration_payload: dict = Field(\n ...,\n description=\"Sanitized registration request payload (credential fields removed)\",\n )\n request_headers: dict[str, str] = Field(\n default_factory=dict,\n description=\"HTTP request headers (sensitive headers excluded)\",\n )\n\n\nclass RegistrationGateResponse(BaseModel):\n \"\"\"Expected response from the registration gate endpoint.\"\"\"\n\n status: str = Field(\n ...,\n description=\"Gate decision: 'allowed' or 'denied'\",\n )\n error: str | None = Field(\n default=None,\n description=\"Reason for denial (only present when status='denied')\",\n )\n\n\nclass RegistrationGateResult(BaseModel):\n \"\"\"Internal result from the gate service check.\"\"\"\n\n allowed: bool = Field(\n ...,\n description=\"Whether the registration is allowed to proceed\",\n )\n error_message: str | None = Field(\n default=None,\n description=\"Error message to return to the caller if denied\",\n )\n gate_status_code: int | None = Field(\n default=None,\n description=\"HTTP status code returned by the gate endpoint\",\n )\n attempts: int = Field(\n default=0,\n description=\"Number of HTTP attempts made to the gate endpoint\",\n )\n" }, { "path": "registry/schemas/registry_card.py", "content": "\"\"\"\nRegistry Card model for describing this registry instance.\n\nThis module defines the RegistryCard model used for federation discovery\nand registry metadata, along with supporting models for capabilities,\nauthentication, and contact information.\n\"\"\"\n\nimport json\nimport logging\nfrom datetime import datetime\nfrom enum import Enum\nfrom typing import Any\nfrom uuid import UUID, uuid4\n\nfrom pydantic import BaseModel, Field, HttpUrl, field_validator\n\n# Configure logging with basicConfig\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass LifecycleStatus(str, Enum):\n \"\"\"Lifecycle status values for registry assets.\"\"\"\n\n ACTIVE = \"active\"\n DEPRECATED = \"deprecated\"\n DRAFT = \"draft\"\n BETA = \"beta\"\n\n\ndef _validate_lifecycle_status(\n status_value: str,\n) -> str:\n \"\"\"Validate that status is one of the known lifecycle values.\n\n Returns the normalized (lowercase) status value.\n\n Raises:\n ValueError: If status is not a valid LifecycleStatus value.\n \"\"\"\n normalized = status_value.lower().strip()\n allowed = {s.value for s in LifecycleStatus}\n if normalized not in allowed:\n raise ValueError(\n f\"Invalid status '{status_value}'. Allowed values: {', '.join(sorted(allowed))}\"\n )\n return normalized\n\n\nclass RegistryCapabilities(BaseModel):\n \"\"\"Capabilities supported by this registry.\"\"\"\n\n servers: bool = Field(default=True, description=\"Supports MCP servers\")\n agents: bool = Field(default=True, description=\"Supports A2A agents\")\n skills: bool = Field(default=True, description=\"Supports AI agent skills\")\n prompts: bool = Field(default=False, description=\"Supports prompt templates\")\n security_scans: bool = Field(default=True, description=\"Runs security scans\")\n incremental_sync: bool = Field(default=False, description=\"Supports incremental sync\")\n webhooks: bool = Field(default=False, description=\"Supports webhook notifications\")\n\n\nclass RegistryAuthConfig(BaseModel):\n \"\"\"Authentication configuration for federation.\"\"\"\n\n schemes: list[str] = Field(\n default_factory=lambda: [\"oauth2\", \"bearer\"],\n description=\"Supported auth schemes\",\n )\n oauth2_issuer: str | None = Field(default=None, description=\"OAuth2/OIDC issuer URL\")\n oauth2_token_endpoint: str | None = Field(default=None, description=\"OAuth2 token endpoint\")\n scopes_supported: list[str] = Field(\n default_factory=lambda: [\"federation/read\"],\n description=\"OAuth2 scopes\",\n )\n\n\nclass RegistryContact(BaseModel):\n \"\"\"Contact information for registry operators.\"\"\"\n\n email: str | None = Field(default=None, description=\"Contact email\")\n url: str | None = Field(default=None, description=\"Documentation or support URL\")\n\n\nclass RegistryCard(BaseModel):\n \"\"\"\n Registry Card describing this registry instance.\n\n Used for federation discovery and registry metadata.\n \"\"\"\n\n schema_version: str = Field(\n default=\"1.0.0\",\n description=\"Schema version for forward/backward compatibility\",\n )\n id: UUID = Field(\n default_factory=uuid4,\n description=\"Unique identifier (UUID) for this registry instance\",\n )\n name: str = Field(..., description=\"Human-readable registry name\")\n description: str | None = Field(\n default=None,\n max_length=1000,\n description=\"Registry description (max 1000 chars)\",\n )\n\n # Base URL and organization (for frontend display)\n registry_url: str | None = Field(default=None, description=\"Base URL of this registry instance\")\n organization_name: str | None = Field(\n default=None, description=\"Organization name that operates this registry\"\n )\n\n federation_api_version: str = Field(default=\"1.0\", description=\"Federation API version\")\n federation_endpoint: HttpUrl = Field(\n ..., description=\"Federation API base URL (HTTPS required)\"\n )\n\n capabilities: RegistryCapabilities = Field(\n default_factory=RegistryCapabilities, description=\"Registry capabilities\"\n )\n authentication: RegistryAuthConfig = Field(\n default_factory=RegistryAuthConfig, description=\"Auth configuration\"\n )\n\n visibility_policy: str = Field(\n default=\"public_only\",\n description=\"Visibility policy: public_only, authenticated, private\",\n )\n contact: RegistryContact | None = Field(default=None, description=\"Contact information\")\n metadata: dict[str, Any] = Field(\n default_factory=dict,\n description=\"Additional metadata (max 10KB serialized)\",\n )\n\n # Internal tracking\n created_at: datetime | None = Field(default=None, description=\"Created timestamp\")\n updated_at: datetime | None = Field(default=None, description=\"Last updated timestamp\")\n\n @field_validator(\"visibility_policy\")\n @classmethod\n def _validate_visibility_policy(cls, v: str) -> str:\n \"\"\"Validate visibility policy.\"\"\"\n allowed = [\"public_only\", \"authenticated\", \"private\"]\n if v not in allowed:\n raise ValueError(f\"visibility_policy must be one of {allowed}\")\n return v\n\n @field_validator(\"federation_endpoint\")\n @classmethod\n def _validate_https_endpoint(cls, v: HttpUrl) -> HttpUrl:\n \"\"\"Ensure federation endpoint uses HTTPS in production.\"\"\"\n # Allow HTTP for localhost/development, require HTTPS for production\n url_str = str(v)\n if url_str.startswith(\"http://\") and not any(\n host in url_str for host in [\"localhost\", \"127.0.0.1\", \"host.docker.internal\"]\n ):\n logger.warning(\n f\"federation_endpoint uses HTTP in production: {url_str}. \"\n \"HTTPS is strongly recommended for security.\"\n )\n return v\n\n @field_validator(\"metadata\")\n @classmethod\n def _validate_metadata_size(cls, v: dict[str, Any]) -> dict[str, Any]:\n \"\"\"Validate metadata size limit (10KB).\"\"\"\n serialized = json.dumps(v)\n if len(serialized) > 10240: # 10KB\n raise ValueError(\"metadata exceeds 10KB size limit\")\n return v\n" }, { "path": "registry/schemas/security.py", "content": "\"\"\"\nSecurity schema models for MCP server scanning.\n\nThis module defines Pydantic models for security scan results, configurations,\nand related data structures used throughout the security scanning workflow.\n\"\"\"\n\nfrom pydantic import BaseModel, Field\n\n\nclass SecurityScanFinding(BaseModel):\n \"\"\"Individual security finding from a scanner.\"\"\"\n\n tool_name: str = Field(..., description=\"Name of the tool that was scanned\")\n severity: str = Field(..., description=\"Severity level: CRITICAL, HIGH, MEDIUM, LOW, SAFE\")\n threat_names: list[str] = Field(\n default_factory=list, description=\"List of detected threat names\"\n )\n threat_summary: str = Field(default=\"\", description=\"Summary of threats found\")\n is_safe: bool = Field(..., description=\"Whether the tool is considered safe\")\n\n\nclass SecurityScanAnalyzerResult(BaseModel):\n \"\"\"Results from a specific security analyzer.\"\"\"\n\n analyzer_name: str = Field(..., description=\"Name of the analyzer (yara, llm, etc.)\")\n findings: list[SecurityScanFinding] = Field(\n default_factory=list, description=\"List of findings from this analyzer\"\n )\n\n\nclass SecurityScanResult(BaseModel):\n \"\"\"Complete security scan result for an MCP server.\"\"\"\n\n server_url: str = Field(..., description=\"URL of the scanned MCP server\")\n server_path: str = Field(..., description=\"Registry path of the MCP server (e.g., /context7)\")\n scan_timestamp: str = Field(..., description=\"ISO timestamp of the scan\")\n is_safe: bool = Field(..., description=\"Overall safety assessment\")\n critical_issues: int = Field(default=0, description=\"Count of critical severity issues\")\n high_severity: int = Field(default=0, description=\"Count of high severity issues\")\n medium_severity: int = Field(default=0, description=\"Count of medium severity issues\")\n low_severity: int = Field(default=0, description=\"Count of low severity issues\")\n analyzers_used: list[str] = Field(\n default_factory=list, description=\"List of analyzers used in scan\"\n )\n raw_output: dict = Field(default_factory=dict, description=\"Full scanner output\")\n output_file: str | None = Field(None, description=\"Path to detailed JSON output file\")\n scan_failed: bool = Field(default=False, description=\"Whether the scan failed to complete\")\n error_message: str | None = Field(None, description=\"Error message if scan failed\")\n\n\nclass SecurityScanConfig(BaseModel):\n \"\"\"Configuration for security scanning.\"\"\"\n\n enabled: bool = Field(default=True, description=\"Enable/disable security scanning\")\n scan_on_registration: bool = Field(default=True, description=\"Scan servers during registration\")\n block_unsafe_servers: bool = Field(\n default=True, description=\"Disable servers that fail security scan\"\n )\n analyzers: str = Field(default=\"yara\", description=\"Comma-separated list of analyzers to use\")\n scan_timeout_seconds: int = Field(\n default=300, description=\"Timeout for security scans in seconds\"\n )\n llm_api_key: str | None = Field(None, description=\"API key for LLM-based analysis\")\n add_security_pending_tag: bool = Field(\n default=True, description=\"Add 'security-pending' tag to unsafe servers\"\n )\n\n\nclass ServerSecurityStatus(BaseModel):\n \"\"\"Security status summary for a server.\"\"\"\n\n server_path: str = Field(..., description=\"Server path (e.g., /mcpgw)\")\n server_name: str = Field(..., description=\"Display name of the server\")\n is_safe: bool = Field(..., description=\"Whether the server passed security scan\")\n last_scan_timestamp: str | None = Field(None, description=\"ISO timestamp of last scan\")\n critical_issues: int = Field(default=0, description=\"Count of critical issues\")\n high_severity: int = Field(default=0, description=\"Count of high severity issues\")\n scan_status: str = Field(default=\"pending\", description=\"Status: pending, completed, failed\")\n is_disabled_for_security: bool = Field(\n default=False, description=\"Whether server is disabled due to security issues\"\n )\n" }, { "path": "registry/schemas/skill_models.py", "content": "\"\"\"\nAgent Skills data models following agentskills.io specification.\n\nAll recommendations incorporated:\n- VisibilityEnum for type-safe visibility\n- Explicit path field in SkillCard\n- HttpUrl validation for URLs\n- ToolReference for allowed_tools linking\n- CompatibilityRequirement for machine-readable requirements\n- Progressive disclosure tier models\n- Owner field for access control\n- Content versioning fields\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom enum import Enum\nfrom typing import (\n Any,\n Literal,\n)\nfrom uuid import UUID, uuid4\n\nfrom pydantic import (\n BaseModel,\n ConfigDict,\n Field,\n HttpUrl,\n field_validator,\n)\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _utc_now() -> datetime:\n \"\"\"Return current UTC datetime (timezone-aware).\"\"\"\n return datetime.now(UTC)\n\n\nclass VisibilityEnum(str, Enum):\n \"\"\"Visibility options for skills.\"\"\"\n\n PUBLIC = \"public\"\n PRIVATE = \"private\"\n GROUP = \"group\"\n\n\nclass SkillMetadata(BaseModel):\n \"\"\"Optional metadata for skills.\"\"\"\n\n author: str | None = None\n version: str | None = None\n extra: dict[str, Any] = Field(default_factory=dict)\n\n\nclass CompatibilityRequirement(BaseModel):\n \"\"\"Machine-readable compatibility constraint.\"\"\"\n\n type: Literal[\"product\", \"tool\", \"api\", \"environment\"] = Field(\n ..., description=\"Type of requirement\"\n )\n target: str = Field(..., description=\"Target identifier (e.g., 'claude-code', 'python>=3.10')\")\n min_version: str | None = None\n max_version: str | None = None\n required: bool = Field(default=True, description=\"False = optional enhancement\")\n\n\nclass ToolReference(BaseModel):\n \"\"\"Reference to a tool with optional filtering.\"\"\"\n\n tool_name: str = Field(..., description=\"Tool name (e.g., 'Read', 'Bash')\")\n server_path: str | None = Field(\n None, description=\"MCP server path (e.g., '/servers/claude-tools')\"\n )\n version: str | None = None\n capabilities: list[str] = Field(\n default_factory=list, description=\"Capability filters (e.g., ['git:*'])\"\n )\n\n\nclass SkillResource(BaseModel):\n \"\"\"Reference to a skill resource file.\"\"\"\n\n path: str = Field(..., description=\"Relative path from skill root\")\n type: Literal[\"script\", \"reference\", \"asset\", \"agent\"] = Field(...)\n size_bytes: int = Field(default=0)\n description: str | None = None\n language: str | None = Field(None, description=\"Programming language for scripts\")\n\n\nclass SkillResourceManifest(BaseModel):\n \"\"\"Manifest of available resources for a skill.\"\"\"\n\n scripts: list[SkillResource] = Field(default_factory=list)\n references: list[SkillResource] = Field(default_factory=list)\n assets: list[SkillResource] = Field(default_factory=list)\n agents: list[SkillResource] = Field(default_factory=list)\n\n\nclass FileHash(BaseModel):\n \"\"\"SHA-256 hash for a single file in the skill directory.\"\"\"\n\n path: str = Field(..., description=\"Relative path (e.g. 'SKILL.md' or 'references/arch.md')\")\n sha256: str = Field(..., description=\"Full SHA-256 hex digest of the file content\")\n size_bytes: int = Field(default=0, description=\"File size at hash time\")\n\n\nclass ContentIntegrity(BaseModel):\n \"\"\"Content integrity record computed at registration or refresh.\n\n Stores per-file SHA-256 hashes and a composite hash derived from all\n individual hashes, enabling drift detection without re-fetching content.\n \"\"\"\n\n composite_hash: str = Field(\n ..., description=\"SHA-256 of the sorted, concatenated per-file hashes\"\n )\n file_hashes: list[FileHash] = Field(default_factory=list)\n computed_at: datetime = Field(default_factory=_utc_now)\n drift_detected: bool = Field(\n default=False, description=\"True when a drift check found content differs from this baseline\"\n )\n last_drift_check: datetime | None = Field(\n None, description=\"When drift was last checked\"\n )\n drifted_files: list[str] = Field(\n default_factory=list, description=\"Paths of files that changed since baseline\"\n )\n\n\nclass SkillCard(BaseModel):\n \"\"\"Full skill profile following Agent Skills specification.\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n # Unique identifier\n id: UUID = Field(\n default_factory=uuid4,\n description=\"Unique identifier (UUID) for this skill\",\n )\n\n # Explicit path - immutable after creation\n path: str = Field(..., description=\"Unique skill path (e.g., /skills/pdf-processing)\")\n name: str = Field(\n ...,\n min_length=1,\n max_length=64,\n description=\"Skill name: lowercase alphanumeric and hyphens only\",\n )\n description: str = Field(\n ..., min_length=1, max_length=1024, description=\"What the skill does and when to use it\"\n )\n\n # URLs with validation\n skill_md_url: HttpUrl = Field(\n ..., description=\"URL to the SKILL.md file as provided by the user\"\n )\n skill_md_raw_url: HttpUrl | None = Field(\n None,\n description=\"Raw URL for fetching SKILL.md content (auto-translated from skill_md_url)\",\n )\n skill_md_content: str | None = Field(\n None,\n description=\"Inline SKILL.md content for federated skills (stored in DB instead of URL fetch)\",\n )\n repository_url: HttpUrl | None = Field(\n None, description=\"URL to the git repository containing the skill\"\n )\n\n # Skill metadata\n license: str | None = Field(\n None, description=\"License name or reference to bundled license file\"\n )\n compatibility: str | None = Field(\n None, max_length=500, description=\"Human-readable environment requirements\"\n )\n requirements: list[CompatibilityRequirement] = Field(\n default_factory=list, description=\"Machine-readable compatibility requirements\"\n )\n target_agents: list[str] = Field(\n default_factory=list,\n description=\"Target coding assistants (e.g., ['claude-code', 'cursor'])\",\n )\n metadata: SkillMetadata | None = Field(\n None, description=\"Additional metadata (author, version, etc.)\"\n )\n\n # Tool references\n allowed_tools: list[ToolReference] = Field(\n default_factory=list, description=\"Tools the skill may use with capabilities\"\n )\n\n # Categorization\n tags: list[str] = Field(default_factory=list, description=\"Tags for categorization and search\")\n\n # Access control\n visibility: VisibilityEnum = Field(\n default=VisibilityEnum.PUBLIC, description=\"Visibility scope\"\n )\n allowed_groups: list[str] = Field(\n default_factory=list, description=\"Groups allowed to view (when visibility=group)\"\n )\n owner: str | None = Field(None, description=\"Owner email/username for private visibility\")\n\n # Source authentication (for private Git repos)\n # Literal keeps the wire-format strings compatible with existing clients\n # while rejecting unsupported schemes at validation time. Adding a new\n # scheme requires updating both this list and SkillRegistrationRequest.\n auth_scheme: Literal[\"none\", \"global_credentials\", \"bearer\", \"api_key\"] = Field(\n default=\"none\",\n description=\"Auth scheme for fetching SKILL.md: none, global_credentials, bearer, api_key\",\n )\n auth_credential_encrypted: str | None = Field(\n None,\n description=\"Encrypted credential for SKILL.md fetching\",\n )\n auth_header_name: str | None = Field(\n None,\n description=\"Custom header name for credential (default: Authorization for bearer, PRIVATE-TOKEN for api_key)\",\n )\n credential_updated_at: datetime | None = Field(\n None, description=\"When the credential was last updated\"\n )\n\n # Resource manifest (companion files: references, scripts, agents, assets)\n resource_manifest: SkillResourceManifest | None = Field(\n None, description=\"Manifest of companion resource files discovered in the skill directory\"\n )\n\n # State\n is_enabled: bool = Field(default=True, description=\"Whether the skill is enabled\")\n registry_name: str = Field(default=\"local\", description=\"Registry this skill belongs to\")\n health_status: Literal[\"healthy\", \"unhealthy\", \"unknown\"] = Field(\n default=\"unknown\", description=\"Health status from last SKILL.md accessibility check\"\n )\n last_checked_time: datetime | None = Field(None, description=\"When health was last checked\")\n\n # Rating\n num_stars: float = Field(default=0.0, ge=0.0, le=5.0, description=\"Average rating (1-5 stars)\")\n rating_details: list[dict[str, Any]] = Field(\n default_factory=list,\n description=\"List of individual user ratings with user and rating fields\",\n )\n\n # Content versioning\n content_version: str | None = Field(None, description=\"Hash of SKILL.md for cache validation\")\n content_updated_at: datetime | None = Field(\n None, description=\"When SKILL.md content was last updated\"\n )\n\n # Content integrity (full hash of SKILL.md + all resources)\n content_integrity: ContentIntegrity | None = Field(\n None, description=\"Per-file hashes and composite hash for drift detection\"\n )\n\n # Timestamps\n created_at: datetime = Field(default_factory=_utc_now)\n updated_at: datetime = Field(default_factory=_utc_now)\n\n # Registry Card fields for federation\n status: str = Field(\n default=\"active\",\n description=\"Lifecycle status (default: active for existing assets)\",\n )\n source_created_at: datetime | None = Field(\n None, description=\"Creation timestamp from federated source\"\n )\n source_updated_at: datetime | None = Field(\n None, description=\"Last update timestamp from federated source\"\n )\n external_tags: list[str] = Field(\n default_factory=list, description=\"Tags from external/federated registries\"\n )\n\n @field_validator(\"name\")\n @classmethod\n def validate_name(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate name follows Agent Skills spec.\"\"\"\n import re\n\n if not re.match(r\"^[a-z0-9]+(-[a-z0-9]+)*$\", v):\n raise ValueError(\n \"Name must be lowercase alphanumeric with single hyphens, \"\n \"not starting or ending with hyphen\"\n )\n return v\n\n @field_validator(\"path\")\n @classmethod\n def validate_path(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate path format.\"\"\"\n if not v.startswith(\"/skills/\"):\n raise ValueError(\"Path must start with /skills/\")\n return v\n\n\nclass SkillInfo(BaseModel):\n \"\"\"Lightweight skill summary for listings.\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n id: UUID = Field(..., description=\"Unique identifier (UUID) for this skill\")\n path: str = Field(..., description=\"Unique skill path\")\n name: str\n description: str\n skill_md_url: str\n skill_md_raw_url: str | None = Field(None, description=\"Raw URL for fetching SKILL.md content\")\n repository_url: HttpUrl | None = Field(\n None, description=\"URL to the git repository containing the skill\"\n )\n tags: list[str] = Field(default_factory=list)\n author: str | None = None\n version: str | None = None\n metadata: SkillMetadata | None = None\n compatibility: str | None = None\n target_agents: list[str] = Field(default_factory=list)\n is_enabled: bool = True\n visibility: VisibilityEnum = VisibilityEnum.PUBLIC\n allowed_groups: list[str] = Field(default_factory=list)\n registry_name: str = \"local\"\n owner: str | None = Field(\n None, description=\"Owner email/username for private visibility access control\"\n )\n auth_scheme: Literal[\"none\", \"global_credentials\", \"bearer\", \"api_key\"] = Field(\n default=\"none\",\n description=\"Auth scheme for fetching SKILL.md: none, global_credentials, bearer, api_key\",\n )\n auth_header_name: str | None = Field(\n None,\n description=\"Custom header name for credential (default: Authorization for bearer, PRIVATE-TOKEN for api_key)\",\n )\n num_stars: float = Field(default=0.0, ge=0.0, le=5.0, description=\"Average rating (1-5 stars)\")\n health_status: Literal[\"healthy\", \"unhealthy\", \"unknown\"] = Field(\n default=\"unknown\", description=\"Health status from last SKILL.md accessibility check\"\n )\n last_checked_time: datetime | None = Field(None, description=\"When health was last checked\")\n\n # Registry Card fields for federation\n status: str = Field(\n default=\"active\",\n description=\"Lifecycle status (default: active for existing assets)\",\n )\n source_created_at: datetime | None = Field(\n None, description=\"Creation timestamp from federated source\"\n )\n source_updated_at: datetime | None = Field(\n None, description=\"Last update timestamp from federated source\"\n )\n external_tags: list[str] = Field(\n default_factory=list, description=\"Tags from external/federated registries\"\n )\n\n\nclass SkillRegistrationRequest(BaseModel):\n \"\"\"Request model for skill registration.\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n name: str = Field(..., min_length=1, max_length=64)\n description: str = Field(..., min_length=1, max_length=1024)\n skill_md_url: HttpUrl = Field(..., description=\"URL to SKILL.md file\")\n repository_url: HttpUrl | None = None\n version: str | None = Field(None, max_length=32, description=\"Skill version (e.g., 1.0.0)\")\n license: str | None = None\n compatibility: str | None = Field(None, max_length=500)\n requirements: list[CompatibilityRequirement] = Field(default_factory=list)\n target_agents: list[str] = Field(default_factory=list)\n metadata: dict[str, Any] | None = None\n allowed_tools: list[ToolReference] = Field(default_factory=list)\n tags: list[str] = Field(default_factory=list)\n visibility: VisibilityEnum = Field(default=VisibilityEnum.PUBLIC)\n allowed_groups: list[str] = Field(default_factory=list)\n status: str = Field(\n default=\"draft\",\n description=\"Lifecycle status (default: draft). Allowed: active, deprecated, draft, beta\",\n )\n auth_scheme: Literal[\"none\", \"global_credentials\", \"bearer\", \"api_key\"] = Field(\n default=\"none\",\n description=\"Auth scheme for fetching SKILL.md from private repos: none, global_credentials, bearer, api_key\",\n )\n auth_credential: str | None = Field(\n None,\n description=\"Credential (token/key) for fetching SKILL.md; encrypted before storage, never persisted in plaintext\",\n )\n auth_header_name: str | None = Field(\n None,\n description=\"Custom header name (default: Authorization for bearer, PRIVATE-TOKEN for api_key)\",\n )\n\n @field_validator(\"name\")\n @classmethod\n def validate_name(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate name follows Agent Skills spec.\"\"\"\n import re\n\n if not re.match(r\"^[a-z0-9]+(-[a-z0-9]+)*$\", v):\n raise ValueError(\n \"Name must be lowercase alphanumeric with single hyphens, \"\n \"not starting or ending with hyphen\"\n )\n return v\n\n\nclass SkillSearchResult(BaseModel):\n \"\"\"Skill search result with relevance score.\"\"\"\n\n skill: SkillInfo\n score: float = Field(description=\"Relevance score 0-1\")\n match_context: str | None = Field(None, description=\"Snippet showing where query matched\")\n required_mcp_servers: list[str] = Field(\n default_factory=list, description=\"MCP servers providing required tools\"\n )\n missing_tools: list[str] = Field(\n default_factory=list, description=\"Tools not available in registry\"\n )\n\n\nclass ToggleStateRequest(BaseModel):\n \"\"\"Request model for toggling skill state.\"\"\"\n\n enabled: bool = Field(..., description=\"New enabled state\")\n\n\n# Progressive Disclosure Models\n\n\nclass SkillTier1_Metadata(BaseModel):\n \"\"\"Tier 1: Always available, ~100 tokens.\"\"\"\n\n path: str\n name: str\n description: str\n skill_md_url: str\n skill_md_raw_url: str | None = Field(None, description=\"Raw URL for fetching SKILL.md content\")\n tags: list[str] = Field(default_factory=list)\n compatibility: str | None = None\n target_agents: list[str] = Field(default_factory=list)\n status: str = Field(\n default=\"active\",\n description=\"Lifecycle status (default: active for existing assets)\",\n )\n\n\nclass SkillTier2_Instructions(BaseModel):\n \"\"\"Tier 2: Loaded when activated, <5000 tokens.\"\"\"\n\n skill_md_body: str = Field(..., description=\"Full SKILL.md content\")\n metadata: SkillMetadata | None = None\n allowed_tools: list[ToolReference] = Field(default_factory=list)\n requirements: list[CompatibilityRequirement] = Field(default_factory=list)\n\n\nclass SkillTier3_Resources(BaseModel):\n \"\"\"Tier 3: Loaded on-demand.\"\"\"\n\n available_resources: list[SkillResource] = Field(default_factory=list)\n\n\nclass ToolValidationResult(BaseModel):\n \"\"\"Result of tool availability validation.\"\"\"\n\n all_available: bool\n missing_tools: list[str] = Field(default_factory=list)\n available_tools: list[str] = Field(default_factory=list)\n mcp_servers_required: list[str] = Field(default_factory=list)\n\n\nclass DiscoveryResponse(BaseModel):\n \"\"\"Response for coding assistant discovery endpoint.\"\"\"\n\n skills: list[SkillTier1_Metadata]\n total_count: int\n page: int = 0\n page_size: int = 100\n" }, { "path": "registry/schemas/skill_security.py", "content": "\"\"\"\nSkill security schema models for skill-scanner integration.\n\nThis module defines Pydantic models for skill security scan results, configurations,\nand related data structures used throughout the skill security scanning workflow.\n\"\"\"\n\nfrom pydantic import BaseModel, Field\n\n\nclass SkillSecurityScanFinding(BaseModel):\n \"\"\"Individual security finding from skill scanner.\"\"\"\n\n file_path: str | None = Field(None, description=\"File where finding was detected\")\n line_number: int | None = Field(None, description=\"Line number of finding\")\n severity: str = Field(..., description=\"Severity level: CRITICAL, HIGH, MEDIUM, LOW\")\n threat_names: list[str] = Field(\n default_factory=list, description=\"List of detected threat names\"\n )\n threat_summary: str = Field(default=\"\", description=\"Summary of threat found\")\n analyzer: str = Field(\n ...,\n description=\"Analyzer that detected the finding: static, behavioral, llm, meta, virustotal, ai-defense\",\n )\n is_safe: bool = Field(..., description=\"Whether the component is considered safe\")\n\n\nclass SkillSecurityScanResult(BaseModel):\n \"\"\"Complete security scan result for a skill.\"\"\"\n\n skill_path: str = Field(..., description=\"Path of the scanned skill\")\n skill_md_url: str | None = Field(None, description=\"URL to SKILL.md\")\n scan_timestamp: str = Field(..., description=\"ISO timestamp of the scan\")\n is_safe: bool = Field(..., description=\"Overall safety assessment\")\n critical_issues: int = Field(default=0, description=\"Count of critical severity issues\")\n high_severity: int = Field(default=0, description=\"Count of high severity issues\")\n medium_severity: int = Field(default=0, description=\"Count of medium severity issues\")\n low_severity: int = Field(default=0, description=\"Count of low severity issues\")\n analyzers_used: list[str] = Field(\n default_factory=list, description=\"List of analyzers used in scan\"\n )\n raw_output: dict = Field(default_factory=dict, description=\"Full scanner output\")\n output_file: str | None = Field(None, description=\"Path to detailed JSON output file\")\n scan_failed: bool = Field(default=False, description=\"Whether the scan failed to complete\")\n error_message: str | None = Field(None, description=\"Error message if scan failed\")\n\n\nclass SkillSecurityScanConfig(BaseModel):\n \"\"\"Configuration for skill security scanning.\"\"\"\n\n enabled: bool = Field(default=True, description=\"Enable/disable skill security scanning\")\n scan_on_registration: bool = Field(default=True, description=\"Scan skills during registration\")\n block_unsafe_skills: bool = Field(\n default=True, description=\"Disable skills that fail security scan\"\n )\n analyzers: str = Field(default=\"static\", description=\"Comma-separated list of analyzers to use\")\n scan_timeout_seconds: int = Field(\n default=120, description=\"Timeout for security scans in seconds\"\n )\n llm_api_key: str | None = Field(None, description=\"API key for LLM-based analysis\")\n virustotal_api_key: str | None = Field(None, description=\"API key for VirusTotal integration\")\n ai_defense_api_key: str | None = Field(None, description=\"API key for Cisco AI Defense\")\n add_security_pending_tag: bool = Field(\n default=True, description=\"Add 'security-pending' tag to unsafe skills\"\n )\n\n\nclass SkillSecurityStatus(BaseModel):\n \"\"\"Security status summary for a skill.\"\"\"\n\n skill_path: str = Field(..., description=\"Skill path (e.g., /pdf-processing)\")\n skill_name: str = Field(..., description=\"Display name of the skill\")\n is_safe: bool = Field(..., description=\"Whether the skill passed security scan\")\n last_scan_timestamp: str | None = Field(None, description=\"ISO timestamp of last scan\")\n critical_issues: int = Field(default=0, description=\"Count of critical issues\")\n high_severity: int = Field(default=0, description=\"Count of high severity issues\")\n scan_status: str = Field(default=\"pending\", description=\"Status: pending, completed, failed\")\n is_disabled_for_security: bool = Field(\n default=False, description=\"Whether skill is disabled due to security issues\"\n )\n" }, { "path": "registry/schemas/virtual_server_models.py", "content": "\"\"\"\nVirtual MCP Server data models.\n\nDefines the schema for virtual servers that aggregate tools from multiple\nbackend MCP servers into a single unified endpoint with fine-grained\naccess control, tool aliasing, and version pinning.\n\"\"\"\n\nimport logging\nimport re\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nfrom pydantic import (\n BaseModel,\n ConfigDict,\n Field,\n field_validator,\n)\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\ndef _utc_now() -> datetime:\n \"\"\"Return current UTC datetime (timezone-aware).\"\"\"\n return datetime.now(UTC)\n\n\nclass ToolMapping(BaseModel):\n \"\"\"Maps a tool from a backend server into a virtual server.\n\n Each mapping selects a specific tool from a backend MCP server,\n optionally renaming it (alias) and pinning it to a specific version.\n \"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n tool_name: str = Field(\n ...,\n min_length=1,\n description=\"Original tool name on the backend server\",\n )\n alias: str | None = Field(\n None,\n description=\"Renamed tool name in virtual server (for conflict resolution)\",\n )\n backend_server_path: str = Field(\n ...,\n min_length=1,\n description=\"Backend server path (e.g., '/github')\",\n )\n backend_version: str | None = Field(\n None,\n description=\"Pinned version (None = active version, e.g., 'v1.5.0' = pinned)\",\n )\n description_override: str | None = Field(\n None,\n max_length=1024,\n description=\"Override the tool's description in this virtual server\",\n )\n\n @field_validator(\"backend_server_path\")\n @classmethod\n def validate_backend_path(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate backend server path starts with /.\"\"\"\n if not v.startswith(\"/\"):\n raise ValueError(\"Backend server path must start with '/'\")\n return v\n\n\nclass ToolScopeOverride(BaseModel):\n \"\"\"Per-tool scope override for fine-grained access control.\n\n Allows requiring additional scopes to see or call specific tools\n beyond the virtual server's base required_scopes.\n \"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n tool_alias: str = Field(\n ...,\n min_length=1,\n description=\"Tool alias or original tool_name\",\n )\n required_scopes: list[str] = Field(\n ...,\n min_length=1,\n description=\"Scopes needed to see/call this tool\",\n )\n\n\nclass VirtualServerConfig(BaseModel):\n \"\"\"Full virtual MCP server configuration.\n\n A virtual server aggregates tools from multiple backend MCP servers\n into a single endpoint. It supports tool aliasing, version pinning,\n and scope-based access control.\n \"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n # Identity\n path: str = Field(\n ...,\n description=\"Unique path and MongoDB _id (e.g., '/virtual/dev-essentials')\",\n )\n server_name: str = Field(\n ...,\n min_length=1,\n max_length=128,\n description=\"Human-readable name for the virtual server\",\n )\n description: str = Field(\n default=\"\",\n max_length=2048,\n description=\"Description of the virtual server's purpose\",\n )\n\n # Tool configuration\n tool_mappings: list[ToolMapping] = Field(\n default_factory=list,\n max_length=500,\n description=\"List of tools mapped from backend servers (max 500)\",\n )\n\n # Access control\n required_scopes: list[str] = Field(\n default_factory=list,\n description=\"Scopes required to access any tool on this virtual server\",\n )\n tool_scope_overrides: list[ToolScopeOverride] = Field(\n default_factory=list,\n description=\"Per-tool scope overrides for fine-grained access\",\n )\n\n # State\n is_enabled: bool = Field(\n default=False,\n description=\"Whether the virtual server is enabled and routable\",\n )\n\n # Categorization\n tags: list[str] = Field(\n default_factory=list,\n max_length=50,\n description=\"Tags for categorization and filtering (max 50)\",\n )\n supported_transports: list[str] = Field(\n default_factory=lambda: [\"streamable-http\"],\n description=\"Supported MCP transport types\",\n )\n\n # Rating\n num_stars: float = Field(\n default=0.0,\n ge=0.0,\n le=5.0,\n description=\"Average star rating (0-5)\",\n )\n rating_details: list[dict[str, Any]] = Field(\n default_factory=list,\n description=\"List of individual ratings with user and rating\",\n )\n\n # Audit\n created_by: str | None = Field(\n None,\n description=\"Username of the creator\",\n )\n created_at: datetime = Field(\n default_factory=_utc_now,\n description=\"Creation timestamp\",\n )\n updated_at: datetime = Field(\n default_factory=_utc_now,\n description=\"Last update timestamp\",\n )\n\n @field_validator(\"path\")\n @classmethod\n def validate_path(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate path starts with /virtual/ to avoid collision with real servers.\"\"\"\n if not v.startswith(\"/virtual/\"):\n raise ValueError(\"Virtual server path must start with '/virtual/'\")\n # Validate path segment after /virtual/\n segment = v[len(\"/virtual/\") :]\n if not segment:\n raise ValueError(\"Virtual server path must have a name after '/virtual/'\")\n if not re.match(r\"^[a-z0-9]+(-[a-z0-9]+)*$\", segment):\n raise ValueError(\n \"Virtual server path segment must be lowercase alphanumeric \"\n \"with single hyphens, not starting or ending with hyphen\"\n )\n return v\n\n @field_validator(\"tags\")\n @classmethod\n def validate_tags(\n cls,\n v: list[str],\n ) -> list[str]:\n \"\"\"Validate each tag is within max length.\"\"\"\n for tag in v:\n if len(tag) > 64:\n raise ValueError(f\"Tag '{tag[:20]}...' exceeds max length of 64 characters\")\n return v\n\n @field_validator(\"server_name\")\n @classmethod\n def validate_server_name(\n cls,\n v: str,\n ) -> str:\n \"\"\"Validate server name is not empty after stripping.\"\"\"\n stripped = v.strip()\n if not stripped:\n raise ValueError(\"Server name cannot be empty or whitespace-only\")\n return stripped\n\n\nclass VirtualServerInfo(BaseModel):\n \"\"\"Lightweight virtual server summary for listings.\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n path: str = Field(..., description=\"Virtual server path\")\n server_name: str = Field(..., description=\"Human-readable name\")\n description: str = Field(default=\"\", description=\"Server description\")\n tool_count: int = Field(default=0, description=\"Number of mapped tools\")\n backend_count: int = Field(default=0, description=\"Number of unique backend servers\")\n backend_paths: list[str] = Field(\n default_factory=list,\n description=\"List of unique backend server paths\",\n )\n is_enabled: bool = Field(default=False, description=\"Whether the server is enabled\")\n tags: list[str] = Field(default_factory=list, description=\"Tags\")\n num_stars: float = Field(default=0.0, description=\"Average star rating\")\n rating_details: list[dict[str, Any]] = Field(\n default_factory=list,\n description=\"List of individual ratings\",\n )\n created_by: str | None = None\n created_at: datetime | None = None\n updated_at: datetime | None = None\n\n\nclass CreateVirtualServerRequest(BaseModel):\n \"\"\"Request model for creating a virtual server.\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n server_name: str = Field(\n ...,\n min_length=1,\n max_length=128,\n description=\"Human-readable name\",\n )\n path: str | None = Field(\n None,\n description=\"Custom path (auto-generated from name if not provided)\",\n )\n description: str = Field(\n default=\"\",\n max_length=2048,\n description=\"Description of the virtual server\",\n )\n tool_mappings: list[ToolMapping] = Field(\n default_factory=list,\n max_length=500,\n description=\"Tools to map from backend servers (max 500)\",\n )\n required_scopes: list[str] = Field(\n default_factory=list,\n description=\"Scopes required for access\",\n )\n tool_scope_overrides: list[ToolScopeOverride] = Field(\n default_factory=list,\n description=\"Per-tool scope overrides\",\n )\n tags: list[str] = Field(\n default_factory=list,\n max_length=50,\n description=\"Tags for categorization (max 50)\",\n )\n supported_transports: list[str] = Field(\n default_factory=lambda: [\"streamable-http\"],\n description=\"Supported transport types\",\n )\n\n\nclass UpdateVirtualServerRequest(BaseModel):\n \"\"\"Request model for updating a virtual server.\"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n server_name: str | None = Field(\n None,\n min_length=1,\n max_length=128,\n description=\"Updated name\",\n )\n description: str | None = Field(\n None,\n max_length=2048,\n description=\"Updated description\",\n )\n tool_mappings: list[ToolMapping] | None = Field(\n None,\n description=\"Updated tool mappings\",\n )\n required_scopes: list[str] | None = Field(\n None,\n description=\"Updated required scopes\",\n )\n tool_scope_overrides: list[ToolScopeOverride] | None = Field(\n None,\n description=\"Updated per-tool scope overrides\",\n )\n tags: list[str] | None = Field(\n None,\n description=\"Updated tags\",\n )\n supported_transports: list[str] | None = Field(\n None,\n description=\"Updated transport types\",\n )\n\n\nclass ToggleVirtualServerRequest(BaseModel):\n \"\"\"Request model for toggling virtual server enabled state.\"\"\"\n\n enabled: bool = Field(..., description=\"New enabled state\")\n\n\nclass ToolCatalogEntry(BaseModel):\n \"\"\"A tool available in the registry, from the global tool catalog.\n\n Aggregates tool information across all enabled backend servers.\n \"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n tool_name: str = Field(..., description=\"Tool name\")\n server_path: str = Field(..., description=\"Backend server path\")\n server_name: str = Field(default=\"\", description=\"Backend server display name\")\n description: str = Field(default=\"\", description=\"Tool description\")\n input_schema: dict[str, Any] = Field(\n default_factory=dict,\n description=\"JSON Schema for tool input parameters\",\n )\n available_versions: list[str] = Field(\n default_factory=list,\n description=\"Available versions of the backend server\",\n )\n\n\nclass ResolvedTool(BaseModel):\n \"\"\"A tool resolved from a virtual server's tool mappings.\n\n Contains the final tool name (alias or original), its source backend,\n and the full tool metadata for serving in tools/list responses.\n \"\"\"\n\n model_config = ConfigDict(populate_by_name=True)\n\n name: str = Field(..., description=\"Tool name (alias if set, otherwise original)\")\n original_name: str = Field(..., description=\"Original tool name on backend\")\n backend_server_path: str = Field(..., description=\"Backend server path\")\n backend_version: str | None = Field(None, description=\"Pinned version if set\")\n description: str = Field(default=\"\", description=\"Tool description\")\n input_schema: dict[str, Any] = Field(\n default_factory=dict,\n description=\"JSON Schema for tool input\",\n )\n required_scopes: list[str] = Field(\n default_factory=list,\n description=\"Scopes required for this specific tool\",\n )\n" }, { "path": "registry/scripts/inspect-documentdb.py", "content": "#!/usr/bin/env python3\n\"\"\"\nInspect DocumentDB collections and indexes.\n\nUsage:\n python inspect-documentdb.py\n\"\"\"\n\nimport asyncio\nimport json\nimport os\nimport sys\n\nfrom motor.motor_asyncio import AsyncIOMotorClient\n\n\nasync def inspect_documentdb():\n \"\"\"Inspect DocumentDB collections and indexes.\"\"\"\n # Get connection details from environment\n host = os.getenv(\"DOCUMENTDB_HOST\")\n port = int(os.getenv(\"DOCUMENTDB_PORT\", \"27017\"))\n username = os.getenv(\"DOCUMENTDB_USERNAME\")\n password = os.getenv(\"DOCUMENTDB_PASSWORD\")\n database = os.getenv(\"DOCUMENTDB_DATABASE\", \"mcp_registry\")\n use_tls = os.getenv(\"DOCUMENTDB_USE_TLS\", \"true\").lower() == \"true\"\n ca_file = os.getenv(\"DOCUMENTDB_TLS_CA_FILE\", \"/app/certs/global-bundle.pem\")\n\n print(\"=\" * 80)\n print(\"DocumentDB Inspection\")\n print(\"=\" * 80)\n print(f\"Host: {host}:{port}\")\n print(f\"Database: {database}\")\n print(f\"TLS: {use_tls}\")\n if use_tls:\n print(f\"CA File: {ca_file}\")\n print(\"=\" * 80)\n print()\n\n # Build connection string with appropriate auth mechanism\n # Choose auth mechanism based on storage backend from environment\n storage_backend = os.getenv(\"STORAGE_BACKEND\", \"documentdb\")\n if storage_backend == \"mongodb-ce\":\n auth_mechanism = \"SCRAM-SHA-256\"\n else:\n auth_mechanism = \"SCRAM-SHA-1\"\n\n if username and password:\n connection_string = (\n f\"mongodb://{username}:{password}@{host}:{port}/{database}?\"\n f\"authMechanism={auth_mechanism}&authSource=admin\"\n )\n else:\n connection_string = f\"mongodb://{host}:{port}/{database}\"\n\n # TLS options\n tls_options = {}\n if use_tls:\n tls_options[\"tls\"] = True\n if ca_file:\n tls_options[\"tlsCAFile\"] = ca_file\n\n # Connect to DocumentDB\n print(\"Connecting to DocumentDB...\")\n # IMPORTANT: DocumentDB does not support retryable writes\n client = AsyncIOMotorClient(connection_string, retryWrites=False, **tls_options)\n db = client[database]\n\n try:\n # Test connection\n server_info = await client.server_info()\n print(f\"Connected to MongoDB/DocumentDB version: {server_info.get('version')}\")\n print()\n\n # List all collections\n collections = await db.list_collection_names()\n print(f\"Collections ({len(collections)}):\")\n print(\"-\" * 80)\n for coll_name in sorted(collections):\n print(f\" - {coll_name}\")\n print()\n\n # Inspect each collection\n for coll_name in sorted(collections):\n print(\"=\" * 80)\n print(f\"Collection: {coll_name}\")\n print(\"=\" * 80)\n\n collection = db[coll_name]\n\n # Count documents\n count = await collection.count_documents({})\n print(f\"Document count: {count}\")\n print()\n\n # List indexes\n indexes = await collection.list_indexes().to_list(None)\n print(f\"Indexes ({len(indexes)}):\")\n print(\"-\" * 80)\n\n for idx in indexes:\n idx_name = idx.get(\"name\")\n print(f\"\\nIndex: {idx_name}\")\n\n # Check if it's a vector index\n if \"vectorOptions\" in idx:\n vector_opts = idx[\"vectorOptions\"]\n print(\" Type: Vector Index (HNSW)\")\n print(f\" Dimensions: {vector_opts.get('dimensions')}\")\n print(f\" Similarity: {vector_opts.get('similarity')}\")\n print(f\" Vector Type: {vector_opts.get('type')}\")\n else:\n print(\" Type: Standard Index\")\n if \"key\" in idx:\n print(f\" Keys: {idx['key']}\")\n\n if \"unique\" in idx and idx[\"unique\"]:\n print(\" Unique: True\")\n\n if \"sparse\" in idx and idx[\"sparse\"]:\n print(\" Sparse: True\")\n\n print()\n\n # Show sample document (if any exist)\n if count > 0:\n print(\"Sample document:\")\n print(\"-\" * 80)\n sample = await collection.find_one({})\n if sample:\n # Remove _id for cleaner display\n sample.pop(\"_id\", None)\n print(json.dumps(sample, indent=2, default=str))\n print()\n\n print(\"=\" * 80)\n print(\"Inspection complete!\")\n print(\"=\" * 80)\n\n finally:\n client.close()\n\n\nif __name__ == \"__main__\":\n try:\n asyncio.run(inspect_documentdb())\n except Exception as e:\n print(f\"ERROR: {e}\", file=sys.stderr)\n import traceback\n\n traceback.print_exc()\n sys.exit(1)\n" }, { "path": "registry/search/__init__.py", "content": "" }, { "path": "registry/search/service.py", "content": "import asyncio\nimport json\nimport logging\nimport re\nfrom datetime import datetime\nfrom typing import Any\n\nimport faiss\nimport numpy as np\nfrom pydantic import HttpUrl\n\nfrom ..core.config import settings\nfrom ..embeddings import (\n EmbeddingsClient,\n create_embeddings_client,\n)\nfrom ..schemas.agent_models import AgentCard\n\nlogger = logging.getLogger(__name__)\n\n\nclass _PydanticAwareJSONEncoder(json.JSONEncoder):\n \"\"\"Custom JSON encoder that handles Pydantic and standard types.\"\"\"\n\n def default(\n self,\n o: Any,\n ) -> Any:\n \"\"\"Convert non-serializable types to JSON-compatible formats.\"\"\"\n if isinstance(o, HttpUrl):\n return str(o)\n if isinstance(o, datetime):\n return o.isoformat()\n return super().default(o)\n\n\nclass FaissService:\n \"\"\"Service for managing FAISS vector database operations.\"\"\"\n\n def __init__(self):\n self.embedding_model: EmbeddingsClient | None = None\n self.faiss_index: faiss.IndexIDMap | None = None\n self.metadata_store: dict[str, dict[str, Any]] = {}\n self.next_id_counter: int = 0\n\n async def initialize(self):\n \"\"\"Initialize the FAISS service - load model and index.\"\"\"\n await self._load_embedding_model()\n await self._load_faiss_data()\n\n async def _load_embedding_model(self):\n \"\"\"Load the embeddings model using the configured provider.\"\"\"\n logger.info(f\"Loading embedding model with provider: {settings.embeddings_provider}\")\n\n # Ensure servers directory exists\n settings.servers_dir.mkdir(parents=True, exist_ok=True)\n\n try:\n # Prepare cache directory for sentence-transformers\n model_cache_path = settings.container_registry_dir / \".cache\"\n model_cache_path.mkdir(parents=True, exist_ok=True)\n\n # Create embeddings client using factory\n self.embedding_model = create_embeddings_client(\n provider=settings.embeddings_provider,\n model_name=settings.embeddings_model_name,\n model_dir=settings.embeddings_model_dir\n if settings.embeddings_provider == \"sentence-transformers\"\n else None,\n cache_dir=model_cache_path\n if settings.embeddings_provider == \"sentence-transformers\"\n else None,\n api_key=settings.embeddings_api_key\n if settings.embeddings_provider == \"litellm\"\n else None,\n api_base=settings.embeddings_api_base\n if settings.embeddings_provider == \"litellm\"\n else None,\n aws_region=settings.embeddings_aws_region\n if settings.embeddings_provider == \"litellm\"\n else None,\n embedding_dimension=settings.embeddings_model_dimensions,\n )\n\n # Get and log the embedding dimension\n embedding_dim = self.embedding_model.get_embedding_dimension()\n logger.info(\n f\"Embedding model loaded successfully. Provider: {settings.embeddings_provider}, \"\n f\"Model: {settings.embeddings_model_name}, Dimension: {embedding_dim}\"\n )\n\n # Warn if dimension doesn't match configuration\n if embedding_dim != settings.embeddings_model_dimensions:\n logger.warning(\n f\"Embedding dimension mismatch: configured={settings.embeddings_model_dimensions}, \"\n f\"actual={embedding_dim}. Using actual dimension.\"\n )\n settings.embeddings_model_dimensions = embedding_dim\n\n except Exception as e:\n logger.error(f\"Failed to load embedding model: {e}\", exc_info=True)\n self.embedding_model = None\n\n async def _load_faiss_data(self):\n \"\"\"Load existing FAISS index and metadata or create new ones.\"\"\"\n if settings.faiss_index_path.exists() and settings.faiss_metadata_path.exists():\n try:\n logger.info(f\"Loading FAISS index from {settings.faiss_index_path}\")\n self.faiss_index = faiss.read_index(str(settings.faiss_index_path))\n\n logger.info(f\"Loading FAISS metadata from {settings.faiss_metadata_path}\")\n with open(settings.faiss_metadata_path) as f:\n loaded_metadata = json.load(f)\n self.metadata_store = loaded_metadata.get(\"metadata\", {})\n self.next_id_counter = loaded_metadata.get(\"next_id\", 0)\n\n logger.info(\n f\"FAISS data loaded. Index size: {self.faiss_index.ntotal if self.faiss_index else 0}. Next ID: {self.next_id_counter}\"\n )\n\n # Check dimension compatibility\n if self.faiss_index and self.faiss_index.d != settings.embeddings_model_dimensions:\n logger.warning(\n f\"Loaded FAISS index dimension ({self.faiss_index.d}) differs from expected ({settings.embeddings_model_dimensions}). Re-initializing.\"\n )\n self._initialize_new_index()\n\n except Exception as e:\n logger.error(f\"Error loading FAISS data: {e}. Re-initializing.\", exc_info=True)\n self._initialize_new_index()\n else:\n logger.info(\"FAISS index or metadata not found. Initializing new.\")\n self._initialize_new_index()\n\n def _initialize_new_index(self):\n \"\"\"Initialize a new FAISS index with Inner Product (IP) for cosine similarity.\n\n Uses IndexFlatIP instead of IndexFlatL2 to enable cosine similarity search.\n When embeddings are normalized to unit length, inner product equals cosine similarity.\n \"\"\"\n self.faiss_index = faiss.IndexIDMap(faiss.IndexFlatIP(settings.embeddings_model_dimensions))\n self.metadata_store = {}\n self.next_id_counter = 0\n logger.info(\n f\"Initialized FAISS IndexFlatIP with {settings.embeddings_model_dimensions} dimensions for cosine similarity\"\n )\n\n async def save_data(self):\n \"\"\"Save FAISS index and metadata to disk.\"\"\"\n if self.faiss_index is None:\n logger.error(\"FAISS index is not initialized. Cannot save.\")\n return\n\n try:\n # Ensure directory exists\n settings.servers_dir.mkdir(parents=True, exist_ok=True)\n\n logger.info(\n f\"Saving FAISS index to {settings.faiss_index_path} (Size: {self.faiss_index.ntotal})\"\n )\n faiss.write_index(self.faiss_index, str(settings.faiss_index_path))\n\n logger.info(f\"Saving FAISS metadata to {settings.faiss_metadata_path}\")\n with open(settings.faiss_metadata_path, \"w\") as f:\n json.dump(\n {\"metadata\": self.metadata_store, \"next_id\": self.next_id_counter},\n f,\n indent=2,\n cls=_PydanticAwareJSONEncoder,\n )\n\n logger.info(\"FAISS data saved successfully.\")\n except Exception as e:\n logger.error(f\"Error saving FAISS data: {e}\", exc_info=True)\n\n def _get_text_for_embedding(self, server_info: dict[str, Any]) -> str:\n \"\"\"Prepare text string from server info (including tools and metadata) for embedding.\"\"\"\n name = server_info.get(\"server_name\", \"\")\n description = server_info.get(\"description\", \"\")\n tags = server_info.get(\"tags\", [])\n tag_string = \", \".join(tags)\n tool_list = server_info.get(\"tool_list\") or []\n tool_snippets = []\n for tool in tool_list:\n tool_name = tool.get(\"name\", \"\")\n parsed_description = tool.get(\"parsed_description\", {}) or {}\n tool_desc = parsed_description.get(\"main\") or tool.get(\"description\", \"\")\n tool_args = parsed_description.get(\"args\", \"\")\n snippet = f\"Tool: {tool_name}. Description: {tool_desc}. Args: {tool_args}\"\n tool_snippets.append(snippet.strip())\n\n tools_section = \"\\n\".join(tool_snippets)\n\n metadata = server_info.get(\"metadata\", {})\n metadata_snippets = []\n if metadata:\n for key, value in metadata.items():\n if isinstance(value, (dict, list)):\n value_str = str(value)\n else:\n value_str = str(value)\n metadata_snippets.append(f\"{key}: {value_str}\")\n\n metadata_section = \"\\n\".join(metadata_snippets) if metadata_snippets else \"\"\n\n text_parts = [\n f\"Name: {name}\",\n f\"Description: {description}\",\n f\"Tags: {tag_string}\",\n f\"Tools:\\n{tools_section}\",\n ]\n\n if metadata_section:\n text_parts.append(f\"Metadata:\\n{metadata_section}\")\n\n return \"\\n\".join(text_parts).strip()\n\n def _get_text_for_agent(self, agent_card: AgentCard) -> str:\n \"\"\"Prepare text string from agent card (including metadata) for embedding.\"\"\"\n name = agent_card.name\n description = agent_card.description\n\n skills_text = \"\"\n if agent_card.skills:\n skill_names = [skill.name for skill in agent_card.skills]\n skill_descriptions = [\n f\"{skill.name}: {skill.description}\" for skill in agent_card.skills\n ]\n skills_text = \"Skills: \" + \", \".join(skill_names)\n skills_text += \"\\nSkill Details: \" + \" | \".join(skill_descriptions)\n\n tags = agent_card.tags\n tag_string = \", \".join(tags) if tags else \"\"\n\n text_parts = [\n f\"Name: {name}\",\n f\"Description: {description}\",\n ]\n\n if skills_text:\n text_parts.append(skills_text)\n\n if tag_string:\n text_parts.append(f\"Tags: {tag_string}\")\n\n if agent_card.metadata:\n metadata_snippets = []\n for key, value in agent_card.metadata.items():\n if isinstance(value, (dict, list)):\n value_str = str(value)\n else:\n value_str = str(value)\n metadata_snippets.append(f\"{key}: {value_str}\")\n\n if metadata_snippets:\n metadata_section = \"\\n\".join(metadata_snippets)\n text_parts.append(f\"Metadata:\\n{metadata_section}\")\n\n return \"\\n\".join(text_parts)\n\n async def add_or_update_service(\n self, service_path: str, server_info: dict[str, Any], is_enabled: bool = False\n ):\n \"\"\"Add or update a service in the FAISS index.\"\"\"\n if self.embedding_model is None or self.faiss_index is None:\n logger.error(\n \"Embedding model or FAISS index not initialized. Cannot add/update service in FAISS.\"\n )\n return\n\n logger.info(f\"Attempting to add/update service '{service_path}' in FAISS.\")\n text_to_embed = self._get_text_for_embedding(server_info)\n\n current_faiss_id = -1\n needs_new_embedding = True\n\n existing_entry = self.metadata_store.get(service_path)\n\n if existing_entry:\n current_faiss_id = existing_entry[\"id\"]\n if existing_entry.get(\"text_for_embedding\") == text_to_embed:\n needs_new_embedding = False\n logger.info(\n f\"Text for embedding for '{service_path}' has not changed. Will update metadata store only if server_info differs.\"\n )\n else:\n logger.info(\n f\"Text for embedding for '{service_path}' has changed. Re-embedding required.\"\n )\n else:\n # New service\n current_faiss_id = self.next_id_counter\n self.next_id_counter += 1\n logger.info(\n f\"New service '{service_path}'. Assigning new FAISS ID: {current_faiss_id}.\"\n )\n needs_new_embedding = True\n\n if needs_new_embedding:\n try:\n # Run model encoding in a separate thread\n embedding = await asyncio.to_thread(self.embedding_model.encode, [text_to_embed])\n embedding_np = np.array([embedding[0]], dtype=np.float32)\n\n # Normalize embedding for cosine similarity (IndexFlatIP)\n normalized_embedding = self._normalize_embedding(embedding_np[0])\n embedding_np = np.array([normalized_embedding], dtype=np.float32)\n logger.debug(\n f\"Normalized embedding for '{service_path}' (norm check: {np.linalg.norm(normalized_embedding):.4f})\"\n )\n\n ids_to_remove = np.array([current_faiss_id])\n if existing_entry:\n try:\n num_removed = self.faiss_index.remove_ids(ids_to_remove)\n if num_removed > 0:\n logger.info(\n f\"Removed {num_removed} old vector(s) for FAISS ID {current_faiss_id} ({service_path}).\"\n )\n else:\n logger.info(\n f\"No old vector found for FAISS ID {current_faiss_id} ({service_path}) during update, or ID not in index.\"\n )\n except Exception as e_remove:\n logger.warning(\n f\"Issue removing FAISS ID {current_faiss_id} for {service_path}: {e_remove}. Proceeding to add.\"\n )\n\n self.faiss_index.add_with_ids(embedding_np, np.array([current_faiss_id]))\n logger.info(\n f\"Added/Updated vector for '{service_path}' with FAISS ID {current_faiss_id}.\"\n )\n except Exception as e:\n logger.error(\n f\"Error encoding or adding embedding for '{service_path}': {e}\", exc_info=True\n )\n return\n\n # Update metadata store\n enriched_server_info = server_info.copy()\n enriched_server_info[\"is_enabled\"] = is_enabled\n\n if (\n existing_entry is None\n or needs_new_embedding\n or existing_entry.get(\"full_server_info\") != enriched_server_info\n ):\n self.metadata_store[service_path] = {\n \"id\": current_faiss_id,\n \"text_for_embedding\": text_to_embed,\n \"full_server_info\": enriched_server_info,\n \"entity_type\": server_info.get(\"entity_type\", \"mcp_server\"),\n }\n logger.debug(f\"Updated faiss_metadata_store for '{service_path}'.\")\n await self.save_data()\n else:\n logger.debug(\n f\"No changes to FAISS vector or enriched full_server_info for '{service_path}'. Skipping save.\"\n )\n\n async def remove_service(self, service_path: str):\n \"\"\"Remove a service from the FAISS index and metadata store.\"\"\"\n try:\n # Check if service exists in metadata\n if service_path not in self.metadata_store:\n logger.warning(f\"Service '{service_path}' not found in FAISS metadata store\")\n return\n\n # Get the FAISS ID for this service\n service_id = self.metadata_store[service_path].get(\"id\")\n if service_id is not None and self.faiss_index:\n # Remove from FAISS index\n # Note: FAISS doesn't support direct removal, but we can remove from metadata\n # The vector will remain in the index but won't be accessible via metadata\n logger.info(\n f\"Removing service '{service_path}' with FAISS ID {service_id} from index\"\n )\n\n # Remove from metadata store\n del self.metadata_store[service_path]\n logger.info(f\"Removed service '{service_path}' from FAISS metadata store\")\n\n # Save the updated metadata\n await self.save_data()\n\n except Exception as e:\n logger.error(\n f\"Failed to remove service '{service_path}' from FAISS: {e}\",\n exc_info=True,\n )\n\n async def add_or_update_agent(\n self,\n agent_path: str,\n agent_card: AgentCard,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"Add or update an agent in the FAISS index.\"\"\"\n if self.embedding_model is None or self.faiss_index is None:\n logger.error(\n \"Embedding model or FAISS index not initialized. Cannot add/update agent in FAISS.\"\n )\n return\n\n logger.info(f\"Attempting to add/update agent '{agent_path}' in FAISS.\")\n text_to_embed = self._get_text_for_agent(agent_card)\n\n current_faiss_id = -1\n needs_new_embedding = True\n\n existing_entry = self.metadata_store.get(agent_path)\n\n if existing_entry:\n current_faiss_id = existing_entry[\"id\"]\n if existing_entry.get(\"text_for_embedding\") == text_to_embed:\n needs_new_embedding = False\n logger.info(\n f\"Text for embedding for '{agent_path}' has not changed. Will update metadata store only if agent_card differs.\"\n )\n else:\n logger.info(\n f\"Text for embedding for '{agent_path}' has changed. Re-embedding required.\"\n )\n else:\n # New agent\n current_faiss_id = self.next_id_counter\n self.next_id_counter += 1\n logger.info(f\"New agent '{agent_path}'. Assigning new FAISS ID: {current_faiss_id}.\")\n needs_new_embedding = True\n\n if needs_new_embedding:\n try:\n # Run model encoding in a separate thread\n embedding = await asyncio.to_thread(\n self.embedding_model.encode,\n [text_to_embed],\n )\n embedding_np = np.array([embedding[0]], dtype=np.float32)\n\n # Normalize embedding for cosine similarity (IndexFlatIP)\n normalized_embedding = self._normalize_embedding(embedding_np[0])\n embedding_np = np.array([normalized_embedding], dtype=np.float32)\n logger.debug(\n f\"Normalized embedding for '{agent_path}' (norm check: {np.linalg.norm(normalized_embedding):.4f})\"\n )\n\n ids_to_remove = np.array([current_faiss_id])\n if existing_entry:\n try:\n num_removed = self.faiss_index.remove_ids(ids_to_remove)\n if num_removed > 0:\n logger.info(\n f\"Removed {num_removed} old vector(s) for FAISS ID {current_faiss_id} ({agent_path}).\"\n )\n else:\n logger.info(\n f\"No old vector found for FAISS ID {current_faiss_id} ({agent_path}) during update, or ID not in index.\"\n )\n except Exception as e_remove:\n logger.warning(\n f\"Issue removing FAISS ID {current_faiss_id} for {agent_path}: {e_remove}. Proceeding to add.\"\n )\n\n self.faiss_index.add_with_ids(\n embedding_np,\n np.array([current_faiss_id]),\n )\n logger.info(\n f\"Added/Updated vector for '{agent_path}' with FAISS ID {current_faiss_id}.\"\n )\n except Exception as e:\n logger.error(\n f\"Error encoding or adding embedding for '{agent_path}': {e}\",\n exc_info=True,\n )\n return\n\n # Update metadata store\n agent_card_dict = agent_card.model_dump()\n\n if (\n existing_entry is None\n or needs_new_embedding\n or existing_entry.get(\"full_agent_card\") != agent_card_dict\n ):\n self.metadata_store[agent_path] = {\n \"id\": current_faiss_id,\n \"entity_type\": \"a2a_agent\",\n \"text_for_embedding\": text_to_embed,\n \"full_agent_card\": agent_card_dict,\n }\n logger.debug(f\"Updated faiss_metadata_store for agent '{agent_path}'.\")\n await self.save_data()\n else:\n logger.debug(\n f\"No changes to FAISS vector or agent card for '{agent_path}'. Skipping save.\"\n )\n\n async def remove_agent(self, agent_path: str) -> None:\n \"\"\"Remove an agent from the FAISS index and metadata store.\"\"\"\n try:\n # Check if agent exists in metadata\n if agent_path not in self.metadata_store:\n logger.warning(f\"Agent '{agent_path}' not found in FAISS metadata store\")\n return\n\n # Get the FAISS ID for this agent\n agent_id = self.metadata_store[agent_path].get(\"id\")\n if agent_id is not None and self.faiss_index:\n logger.info(f\"Removing agent '{agent_path}' with FAISS ID {agent_id} from index\")\n\n # Remove from metadata store\n del self.metadata_store[agent_path]\n logger.info(f\"Removed agent '{agent_path}' from FAISS metadata store\")\n\n # Save the updated metadata\n await self.save_data()\n\n except Exception as e:\n logger.error(\n f\"Failed to remove agent '{agent_path}' from FAISS: {e}\",\n exc_info=True,\n )\n\n async def search_agents(\n self,\n query: str,\n max_results: int = 10,\n ) -> list[dict[str, Any]]:\n \"\"\"Search for agents in the FAISS index.\"\"\"\n results = await self.search_mixed(\n query=query,\n entity_types=[\"a2a_agent\"],\n max_results=max_results,\n )\n return results.get(\"agents\", [])\n\n async def add_or_update_entity(\n self,\n entity_path: str,\n entity_info: dict[str, Any],\n entity_type: str,\n is_enabled: bool = False,\n ) -> None:\n \"\"\"\n Wrapper method for adding or updating an entity.\n\n Routes agents to appropriate methods based on entity_type.\n \"\"\"\n if entity_type == \"a2a_agent\":\n agent_card = AgentCard(**entity_info)\n await self.add_or_update_agent(entity_path, agent_card, is_enabled)\n elif entity_type == \"mcp_server\":\n await self.add_or_update_service(entity_path, entity_info, is_enabled)\n\n async def remove_entity(\n self,\n entity_path: str,\n ) -> None:\n \"\"\"\n Wrapper method for removing an entity.\n\n Attempts to remove as agent first, then server.\n \"\"\"\n try:\n await self.remove_agent(entity_path)\n except Exception:\n try:\n await self.remove_service(entity_path)\n except Exception as e:\n logger.warning(f\"Could not remove entity {entity_path}: {e}\")\n\n async def search_entities(\n self,\n query: str,\n entity_types: list[str] | None = None,\n enabled_only: bool = False,\n max_results: int = 10,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Wrapper method for searching entities.\n\n Searches both agents and servers, returns list of matching entities.\n \"\"\"\n if entity_types is None:\n entity_types = [\"a2a_agent\", \"mcp_server\", \"tool\"]\n\n results = await self.search_mixed(\n query=query,\n entity_types=entity_types,\n max_results=max_results,\n )\n\n combined: list[dict[str, Any]] = []\n requested = set(entity_types)\n\n if \"agents\" in results and \"a2a_agent\" in requested:\n for agent in results[\"agents\"]:\n if enabled_only and not agent.get(\"is_enabled\", False):\n continue\n combined.append(agent)\n\n if \"servers\" in results and \"mcp_server\" in requested:\n for server in results[\"servers\"]:\n if enabled_only and not server.get(\"is_enabled\", False):\n continue\n combined.append(server)\n\n if \"tools\" in results and \"tool\" in requested:\n combined.extend(results[\"tools\"])\n\n return combined[:max_results]\n\n def _distance_to_relevance(self, distance: float) -> float:\n \"\"\"Convert FAISS Inner Product distance to cosine similarity score (0-1).\n\n FAISS IndexFlatIP behavior depends on index configuration:\n - Standard IndexFlatIP: Returns (1 - inner_product) as distance\n Example: inner_product=0.95 → distance=0.05 → similarity=0.95\n - With negated scores: Returns -inner_product as distance\n Example: inner_product=0.95 → distance=-0.95 → similarity=0.95\n\n For normalized vectors: inner_product = cosine_similarity\n\n This function handles both cases:\n - Positive distances (0 to 1): similarity = 1 - distance\n - Negative distances (-1 to 0): similarity = -distance\n\n Expected behavior:\n - distance=0.05 → similarity=0.95 (95% match)\n - distance=-0.95 → similarity=0.95 (95% match)\n - distance=0.50 → similarity=0.50 (50% match)\n - distance=-0.50 → similarity=0.50 (50% match)\n\n Args:\n distance: Distance from FAISS IndexFlatIP\n\n Returns:\n Cosine similarity score in range 0-1\n \"\"\"\n try:\n dist = float(distance)\n\n # Handle both positive and negative distance conventions\n if dist < 0:\n # Negative distance: negate to get similarity\n similarity = -dist\n else:\n # Positive distance: convert from (1-IP) to similarity\n similarity = 1.0 - dist\n\n # Clamp to 0-1 range (handle edge cases)\n clamped_similarity = max(0.0, min(1.0, similarity))\n\n # Log conversion for debugging\n logger.info(\n f\"IP-to-similarity conversion: \"\n f\"faiss_distance={distance:.4f}, similarity={similarity:.4f}, \"\n f\"clamped={clamped_similarity:.4f}, percentage={clamped_similarity * 100:.1f}%\"\n )\n\n return clamped_similarity\n except Exception as e:\n logger.error(\n f\"Error in _distance_to_relevance: faiss_distance={distance}, exception={str(e)}\",\n exc_info=True,\n )\n return 0.0\n\n def _normalize_embedding(\n self,\n embedding: np.ndarray,\n ) -> np.ndarray:\n \"\"\"Normalize embedding vector to unit length for cosine similarity.\n\n Converts any embedding vector to unit length (L2 norm = 1).\n This allows FAISS IndexFlatIP to compute cosine similarity via inner product.\n\n Args:\n embedding: Input embedding vector (numpy array)\n\n Returns:\n Normalized embedding with L2 norm = 1\n \"\"\"\n norm = np.linalg.norm(embedding)\n if norm == 0:\n logger.warning(\"Zero-norm embedding detected, returning as-is\")\n return embedding\n return embedding / norm\n\n def _calculate_keyword_boost(\n self,\n query: str,\n server_info: dict[str, Any],\n ) -> float:\n \"\"\"Calculate keyword match boost for hybrid search.\n\n Boosts semantic similarity score when query keywords appear in:\n - Server name (highest boost)\n - Tool names (high boost)\n - Tags (medium boost)\n - Description (low boost)\n\n Args:\n query: Search query\n server_info: Server information dict\n\n Returns:\n Boost multiplier (1.0 = no boost, up to 2.0 = maximum boost)\n \"\"\"\n # Filter out stopwords to prevent false matches\n stopwords = {\n \"a\",\n \"an\",\n \"the\",\n \"is\",\n \"are\",\n \"was\",\n \"were\",\n \"be\",\n \"been\",\n \"being\",\n \"have\",\n \"has\",\n \"had\",\n \"do\",\n \"does\",\n \"did\",\n \"will\",\n \"would\",\n \"could\",\n \"should\",\n \"may\",\n \"might\",\n \"can\",\n \"to\",\n \"of\",\n \"in\",\n \"on\",\n \"at\",\n \"by\",\n \"for\",\n \"with\",\n \"about\",\n \"as\",\n \"into\",\n \"through\",\n \"from\",\n \"what\",\n \"when\",\n \"where\",\n \"who\",\n \"which\",\n \"how\",\n \"why\",\n \"get\",\n \"set\",\n \"put\",\n }\n\n query_lower = query.lower()\n query_tokens = set(\n token\n for token in re.split(r\"\\W+\", query_lower)\n if token and len(token) > 2 and token not in stopwords\n )\n\n if not query_tokens:\n return 1.0\n\n boost = 1.0\n boost_reasons = []\n\n # Server name exact match: +0.5 boost\n server_name = server_info.get(\"server_name\", \"\").lower()\n if any(token in server_name for token in query_tokens):\n boost += 0.5\n boost_reasons.append(f\"name({server_name}):+0.5\")\n\n # Tool name matches: +0.3 boost per matching tool (max +0.6)\n tools = server_info.get(\"tool_list\") or []\n tool_matches = 0\n matching_tool_names = []\n for tool in tools:\n tool_name = tool.get(\"name\", \"\").lower()\n if any(token in tool_name for token in query_tokens):\n tool_matches += 1\n matching_tool_names.append(tool_name)\n\n tool_boost = min(0.6, tool_matches * 0.3)\n if tool_boost > 0:\n boost += tool_boost\n boost_reasons.append(f\"tools({','.join(matching_tool_names[:2])}):+{tool_boost:.1f}\")\n\n # Tag matches: +0.2 boost per matching tag (max +0.4)\n tags = server_info.get(\"tags\", [])\n tag_matches = sum(1 for tag in tags if any(token in tag.lower() for token in query_tokens))\n tag_boost = min(0.4, tag_matches * 0.2)\n if tag_boost > 0:\n boost += tag_boost\n boost_reasons.append(f\"tags:{tag_matches}:+{tag_boost:.1f}\")\n\n # Description keyword density: +0.1 to +0.2 based on match ratio\n description = server_info.get(\"description\", \"\").lower()\n if description:\n desc_matches = sum(1 for token in query_tokens if token in description)\n match_ratio = desc_matches / len(query_tokens)\n desc_boost = match_ratio * 0.2\n if desc_boost > 0.01: # Only log if significant\n boost += desc_boost\n boost_reasons.append(f\"desc:{desc_matches}/{len(query_tokens)}:+{desc_boost:.2f}\")\n\n # Log boost reasoning if there's any boost\n if boost_reasons:\n logger.info(f\" Keyword boost breakdown: {' | '.join(boost_reasons)}\")\n\n # Cap total boost at 2.0 (100% increase)\n return min(2.0, boost)\n\n def _extract_matching_tools(\n self,\n query: str,\n server_info: dict[str, Any],\n ) -> list[dict[str, Any]]:\n \"\"\"Extract tool matches using keyword overlap and server name matching.\n\n When the query contains the server name (e.g., \"context7\"), all tools\n from that server are returned with a base relevance score. This handles\n queries like \"use context7 to look up MongoDB docs\" where the user\n explicitly mentions the server but not specific tool names.\n\n Args:\n query: The search query\n server_info: Server information including tool_list\n\n Returns:\n List of matching tools with relevance scores\n \"\"\"\n tools = server_info.get(\"tool_list\") or []\n if not tools:\n return []\n\n # Filter out stopwords and short tokens to improve matching quality\n stopwords = {\n \"a\",\n \"an\",\n \"the\",\n \"is\",\n \"are\",\n \"was\",\n \"were\",\n \"be\",\n \"been\",\n \"being\",\n \"have\",\n \"has\",\n \"had\",\n \"do\",\n \"does\",\n \"did\",\n \"will\",\n \"would\",\n \"could\",\n \"should\",\n \"may\",\n \"might\",\n \"can\",\n \"to\",\n \"of\",\n \"in\",\n \"on\",\n \"at\",\n \"by\",\n \"for\",\n \"with\",\n \"about\",\n \"as\",\n \"into\",\n \"through\",\n \"from\",\n \"what\",\n \"when\",\n \"where\",\n \"who\",\n \"which\",\n \"how\",\n \"why\",\n \"get\",\n \"set\",\n \"put\",\n }\n\n tokens = [\n token\n for token in re.split(r\"\\W+\", query.lower())\n if token and len(token) > 2 and token not in stopwords\n ]\n if not tokens:\n return []\n\n # Check if query contains server name - if so, include all tools\n server_name = server_info.get(\"server_name\", \"\").lower()\n server_name_tokens = [t for t in re.split(r\"\\W+\", server_name) if t and len(t) > 2]\n server_name_match = any(\n token in server_name or any(snt in token or token in snt for snt in server_name_tokens)\n for token in tokens\n )\n\n matches: list[tuple[float, dict[str, Any]]] = []\n for tool in tools:\n tool_name = tool.get(\"name\", \"\")\n parsed_description = tool.get(\"parsed_description\", {}) or {}\n tool_desc = (\n parsed_description.get(\"main\")\n or tool.get(\"description\")\n or parsed_description.get(\"summary\")\n or \"\"\n )\n tool_args = parsed_description.get(\"args\") or \"\"\n\n # Ensure all values are strings to avoid NoneType errors\n tool_name = tool_name or \"\"\n tool_desc = tool_desc or \"\"\n tool_args = tool_args or \"\"\n\n searchable_text = f\"{tool_name} {tool_desc} {tool_args}\".lower()\n if not searchable_text.strip():\n continue\n\n # Calculate matches with higher weight for tool name matches\n tool_name_lower = tool_name.lower()\n name_matches = sum(1 for token in tokens if token in tool_name_lower)\n desc_matches = sum(\n 1 for token in tokens if token in tool_desc.lower() or token in tool_args.lower()\n )\n\n # Weight tool name matches more heavily (2x)\n weighted_matches = (name_matches * 2.0) + desc_matches\n max_possible_score = len(tokens) * 2.0 # If all tokens match in name\n\n # If server name matches query, include tool with base score\n if weighted_matches == 0 and server_name_match:\n # Server name matched - include this tool with base relevance\n base_score = 0.5 # Base score for server-name-matched tools\n matches.append(\n (\n base_score,\n {\n \"tool_name\": tool_name,\n \"description\": tool_desc,\n \"match_context\": (tool_desc or tool_args or \"\")[:180],\n \"schema\": tool.get(\"schema\", {}),\n \"raw_score\": base_score,\n },\n )\n )\n continue\n\n if weighted_matches == 0:\n continue\n\n # Normalize to 0-1 range, with name matches getting higher scores\n coverage = min(1.0, weighted_matches / max_possible_score)\n matches.append(\n (\n coverage,\n {\n \"tool_name\": tool_name,\n \"description\": tool_desc,\n \"match_context\": (tool_desc or tool_args or \"\")[:180],\n \"schema\": tool.get(\"schema\", {}),\n \"raw_score\": coverage,\n },\n )\n )\n\n matches.sort(key=lambda item: item[0], reverse=True)\n return [match for _, match in matches]\n\n async def search_mixed(\n self,\n query: str,\n entity_types: list[str] | None = None,\n max_results: int = 20,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"\n Run a semantic search across MCP servers, their tools, and A2A agents.\n\n Args:\n query: Natural language query text\n entity_types: Optional list of entity filters (\"mcp_server\", \"tool\", \"a2a_agent\")\n max_results: Maximum results to return per entity collection\n\n Returns:\n Dict with \"servers\", \"tools\", and \"agents\" result lists\n \"\"\"\n if not query or not query.strip():\n raise ValueError(\"Query text is required for semantic search\")\n\n if self.embedding_model is None or self.faiss_index is None:\n raise RuntimeError(\"FAISS search service is not initialized\")\n\n max_results = max(1, min(max_results, 50))\n requested_entity_types = set(entity_types or [\"mcp_server\", \"tool\", \"a2a_agent\"])\n allowed_entity_types = {\"mcp_server\", \"tool\", \"a2a_agent\"}\n entity_filter = requested_entity_types & allowed_entity_types\n if not entity_filter:\n entity_filter = allowed_entity_types\n\n total_vectors = self.faiss_index.ntotal if self.faiss_index else 0\n if total_vectors == 0:\n return {\"servers\": [], \"tools\": [], \"agents\": []}\n\n top_k = min(max_results, total_vectors)\n query_embedding = await asyncio.to_thread(self.embedding_model.encode, [query.strip()])\n query_np = np.array([query_embedding[0]], dtype=np.float32)\n\n # Normalize query embedding for cosine similarity (IndexFlatIP)\n normalized_query = self._normalize_embedding(query_np[0])\n query_np = np.array([normalized_query], dtype=np.float32)\n logger.debug(\n f\"Normalized query embedding (norm check: {np.linalg.norm(normalized_query):.4f})\"\n )\n\n distances, indices = self.faiss_index.search(query_np, top_k)\n distance_row = distances[0]\n id_row = indices[0]\n\n id_to_path = {entry.get(\"id\"): path for path, entry in self.metadata_store.items()}\n\n server_results: list[dict[str, Any]] = []\n tool_results: list[dict[str, Any]] = []\n agent_results: list[dict[str, Any]] = []\n\n for distance, faiss_id in zip(distance_row, id_row, strict=False):\n if faiss_id == -1:\n continue\n\n path = id_to_path.get(int(faiss_id))\n if not path:\n continue\n\n metadata_entry = self.metadata_store.get(path, {})\n entity_type = metadata_entry.get(\"entity_type\", \"mcp_server\")\n base_relevance = self._distance_to_relevance(distance)\n\n if entity_type == \"mcp_server\":\n server_info = metadata_entry.get(\"full_server_info\", {})\n if not server_info:\n continue\n\n # Apply keyword boost for hybrid search\n keyword_boost = self._calculate_keyword_boost(query, server_info)\n relevance = min(1.0, base_relevance * keyword_boost)\n\n match_context = (\n server_info.get(\"description\")\n or \", \".join(server_info.get(\"tags\", []))\n or server_info.get(\"path\")\n )\n\n matching_tools: list[dict[str, Any]] = []\n if \"tool\" in entity_filter:\n matching_tools = self._extract_matching_tools(query, server_info)[:5]\n\n # Comprehensive trace for search debugging\n logger.info(\n f\"[SEARCH] Server: {server_info.get('server_name')} | \"\n f\"Distance: {distance:.4f} | \"\n f\"Base Similarity: {base_relevance:.2%} | \"\n f\"Keyword Boost: {keyword_boost:.2f}x | \"\n f\"Final Score: {relevance:.2%} | \"\n f\"Matching Tools: {len(matching_tools)}\"\n )\n if matching_tools:\n for tool in matching_tools[:3]: # Show top 3 matching tools\n logger.info(\n f\" └─ Tool: {tool.get('tool_name')} | \"\n f\"Coverage: {tool.get('raw_score', 0):.2%}\"\n )\n\n if \"mcp_server\" in entity_filter:\n server_results.append(\n {\n \"entity_type\": \"mcp_server\",\n \"path\": path,\n \"server_name\": server_info.get(\"server_name\", path.strip(\"/\")),\n \"description\": server_info.get(\"description\", \"\"),\n \"tags\": server_info.get(\"tags\", []),\n \"num_tools\": server_info.get(\"num_tools\", 0),\n \"is_enabled\": server_info.get(\"is_enabled\", False),\n \"relevance_score\": relevance,\n \"match_context\": match_context,\n \"matching_tools\": [\n {\n \"tool_name\": tool.get(\"tool_name\", \"\"),\n \"description\": tool.get(\"description\", \"\"),\n \"relevance_score\": min(\n 1.0, (relevance + tool.get(\"raw_score\", 0)) / 2\n ),\n \"match_context\": tool.get(\"match_context\", \"\"),\n }\n for tool in matching_tools\n ],\n }\n )\n\n if \"tool\" in entity_filter and matching_tools:\n for tool in matching_tools:\n tool_results.append(\n {\n \"entity_type\": \"tool\",\n \"server_path\": path,\n \"server_name\": server_info.get(\"server_name\", path.strip(\"/\")),\n \"tool_name\": tool.get(\"tool_name\", \"\"),\n \"description\": tool.get(\"description\", \"\"),\n \"match_context\": tool.get(\"match_context\", \"\"),\n \"relevance_score\": min(\n 1.0, (relevance + tool.get(\"raw_score\", 0)) / 2\n ),\n }\n )\n\n elif entity_type == \"a2a_agent\":\n if \"a2a_agent\" not in entity_filter:\n continue\n\n agent_card = metadata_entry.get(\"full_agent_card\", {})\n if not agent_card:\n continue\n\n # Apply keyword boost for agents (using base_relevance from line 831)\n # For agents, check name, description, skills, and tags\n agent_info_for_boost = {\n \"server_name\": agent_card.get(\"name\", \"\"),\n \"description\": agent_card.get(\"description\", \"\"),\n \"tags\": agent_card.get(\"tags\", []),\n \"tool_list\": [\n {\"name\": skill.get(\"name\", \"\")}\n for skill in agent_card.get(\"skills\", [])\n if isinstance(skill, dict)\n ],\n }\n keyword_boost = self._calculate_keyword_boost(query, agent_info_for_boost)\n agent_relevance = min(1.0, base_relevance * keyword_boost)\n\n skills = [\n skill.get(\"name\")\n for skill in agent_card.get(\"skills\", [])\n if isinstance(skill, dict)\n ]\n match_context = (\n agent_card.get(\"description\")\n or \", \".join(skills)\n or \", \".join(agent_card.get(\"tags\", []))\n )\n\n # Comprehensive trace for agent search debugging\n logger.info(\n f\"[SEARCH] Agent: {agent_card.get('name')} | \"\n f\"Distance: {distance:.4f} | \"\n f\"Base Similarity: {base_relevance:.2%} | \"\n f\"Keyword Boost: {keyword_boost:.2f}x | \"\n f\"Final Score: {agent_relevance:.2%} | \"\n f\"Skills: {len(skills)}\"\n )\n\n agent_results.append(\n {\n \"entity_type\": \"a2a_agent\",\n \"path\": path,\n \"agent_name\": agent_card.get(\"name\", path.strip(\"/\")),\n \"description\": agent_card.get(\"description\", \"\"),\n \"tags\": agent_card.get(\"tags\", []),\n \"skills\": skills,\n \"visibility\": agent_card.get(\"visibility\", \"public\"),\n \"trust_level\": agent_card.get(\"trust_level\"),\n \"is_enabled\": agent_card.get(\"is_enabled\", False),\n \"relevance_score\": agent_relevance,\n \"match_context\": match_context,\n \"agent_card\": agent_card,\n }\n )\n\n server_results.sort(key=lambda item: item[\"relevance_score\"], reverse=True)\n tool_results.sort(key=lambda item: item[\"relevance_score\"], reverse=True)\n agent_results.sort(key=lambda item: item[\"relevance_score\"], reverse=True)\n\n return {\n \"servers\": server_results[:max_results],\n \"tools\": tool_results[:max_results],\n \"agents\": agent_results[:max_results],\n }\n\n\n# Global service instance\nfaiss_service = FaissService()\n" }, { "path": "registry/servers/atlassian.json", "content": "{\n \"server_name\": \"Atlassian\",\n \"description\": \"Atlassian\",\n \"path\": \"/atlassian\",\n \"proxy_pass_url\": \"http://atlassian-server:8005/mcp/\",\n \"auth_provider\": \"atlassian\",\n \"auth_scheme\": \"bearer\",\n \"tags\": [\n \"Atlassian\", \"Jira\", \"Confluence\"\n ],\n \"num_tools\": 42,\n \"license\": \"MIT\",\n \"tool_list\": [\n {\n \"name\": \"jira_get_user_profile\",\n \"parsed_description\": {\n \"main\": \"Retrieve profile information for a specific Jira user.\",\n \"args\": \"ctx: The FastMCP context.\\nuser_identifier: User identifier (email, username, key, or account ID).\",\n \"returns\": \"JSON string representing the Jira user profile object, or an error object if not found.\",\n \"raises\": \"ValueError: If the Jira client is not configured or available.\"\n },\n \"schema\": {\n \"properties\": {\n \"user_identifier\": {\n \"description\": \"Identifier for the user (e.g., email address 'user@example.com', username 'johndoe', account ID 'accountid:...', or key for Server/DC).\",\n \"title\": \"User Identifier\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"user_identifier\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_issue\",\n \"parsed_description\": {\n \"main\": \"Get details of a specific Jira issue including its Epic links and relationship information.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\\nfields: Comma-separated list of fields to return (e.g., 'summary,status,customfield_10010'), a single field as a string (e.g., 'duedate'), '*all' for all fields, or omitted for essentials.\\nexpand: Optional fields to expand.\\ncomment_limit: Maximum number of comments.\\nproperties: Issue properties to return.\\nupdate_history: Whether to update issue view history.\",\n \"returns\": \"JSON string representing the Jira issue object.\",\n \"raises\": \"ValueError: If the Jira client is not configured or available.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"fields\": {\n \"default\": \"reporter,labels,description,created,priority,assignee,updated,status,issuetype,summary\",\n \"description\": \"(Optional) Comma-separated list of fields to return (e.g., 'summary,status,customfield_10010'). You may also provide a single field as a string (e.g., 'duedate'). Use '*all' for all fields (including custom fields), or omit for essential fields only.\",\n \"title\": \"Fields\",\n \"type\": \"string\"\n },\n \"expand\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Fields to expand. Examples: 'renderedFields' (for rendered content), 'transitions' (for available status transitions), 'changelog' (for history)\",\n \"title\": \"Expand\"\n },\n \"comment_limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of comments to include (0 or null for no comments)\",\n \"maximum\": 100,\n \"minimum\": 0,\n \"title\": \"Comment Limit\",\n \"type\": \"integer\"\n },\n \"properties\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"description\": \"(Optional) A comma-separated list of issue properties to return\",\n \"default\": null,\n \"title\": \"Properties\"\n },\n \"update_history\": {\n \"default\": true,\n \"description\": \"Whether to update the issue view history for the requesting user\",\n \"title\": \"Update History\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"issue_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_search\",\n \"parsed_description\": {\n \"main\": \"Search Jira issues using JQL (Jira Query Language).\",\n \"args\": \"ctx: The FastMCP context.\\njql: JQL query string.\\nfields: Comma-separated fields to return.\\nlimit: Maximum number of results.\\nstart_at: Starting index for pagination.\\nprojects_filter: Comma-separated list of project keys to filter by.\\nexpand: Optional fields to expand.\",\n \"returns\": \"JSON string representing the search results including pagination info.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"jql\": {\n \"description\": \"JQL query string (Jira Query Language). Examples:\\n- Find Epics: \\\"issuetype = Epic AND project = PROJ\\\"\\n- Find issues in Epic: \\\"parent = PROJ-123\\\"\\n- Find by status: \\\"status = 'In Progress' AND project = PROJ\\\"\\n- Find by assignee: \\\"assignee = currentUser()\\\"\\n- Find recently updated: \\\"updated >= -7d AND project = PROJ\\\"\\n- Find by label: \\\"labels = frontend AND project = PROJ\\\"\\n- Find by priority: \\\"priority = High AND project = PROJ\\\"\",\n \"title\": \"Jql\",\n \"type\": \"string\"\n },\n \"fields\": {\n \"default\": \"reporter,labels,description,created,priority,assignee,updated,status,issuetype,summary\",\n \"description\": \"(Optional) Comma-separated fields to return in the results. Use '*all' for all fields, or specify individual fields like 'summary,status,assignee,priority'\",\n \"title\": \"Fields\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n },\n \"start_at\": {\n \"default\": 0,\n \"description\": \"Starting index for pagination (0-based)\",\n \"minimum\": 0,\n \"title\": \"Start At\",\n \"type\": \"integer\"\n },\n \"projects_filter\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Comma-separated list of project keys to filter results by. Overrides the environment variable JIRA_PROJECTS_FILTER if provided.\",\n \"title\": \"Projects Filter\"\n },\n \"expand\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) fields to expand. Examples: 'renderedFields', 'transitions', 'changelog'\",\n \"title\": \"Expand\"\n }\n },\n \"required\": [\n \"jql\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_search_fields\",\n \"parsed_description\": {\n \"main\": \"Search Jira fields by keyword with fuzzy match.\",\n \"args\": \"ctx: The FastMCP context.\\nkeyword: Keyword for fuzzy search.\\nlimit: Maximum number of results.\\nrefresh: Whether to force refresh the field list.\",\n \"returns\": \"JSON string representing a list of matching field definitions.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"keyword\": {\n \"default\": \"\",\n \"description\": \"Keyword for fuzzy search. If left empty, lists the first 'limit' available fields in their default order.\",\n \"title\": \"Keyword\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results\",\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n },\n \"refresh\": {\n \"default\": false,\n \"description\": \"Whether to force refresh the field list\",\n \"title\": \"Refresh\",\n \"type\": \"boolean\"\n }\n },\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_project_issues\",\n \"parsed_description\": {\n \"main\": \"Get all issues for a specific Jira project.\",\n \"args\": \"ctx: The FastMCP context.\\nproject_key: The project key.\\nlimit: Maximum number of results.\\nstart_at: Starting index for pagination.\",\n \"returns\": \"JSON string representing the search results including pagination info.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"project_key\": {\n \"description\": \"The project key\",\n \"title\": \"Project Key\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n },\n \"start_at\": {\n \"default\": 0,\n \"description\": \"Starting index for pagination (0-based)\",\n \"minimum\": 0,\n \"title\": \"Start At\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"project_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_transitions\",\n \"parsed_description\": {\n \"main\": \"Get available status transitions for a Jira issue.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\",\n \"returns\": \"JSON string representing a list of available transitions.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"issue_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_worklog\",\n \"parsed_description\": {\n \"main\": \"Get worklog entries for a Jira issue.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\",\n \"returns\": \"JSON string representing the worklog entries.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"issue_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_download_attachments\",\n \"parsed_description\": {\n \"main\": \"Download attachments from a Jira issue.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\\ntarget_dir: Directory to save attachments.\",\n \"returns\": \"JSON string indicating the result of the download operation.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"target_dir\": {\n \"description\": \"Directory where attachments should be saved\",\n \"title\": \"Target Dir\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"issue_key\",\n \"target_dir\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_agile_boards\",\n \"parsed_description\": {\n \"main\": \"Get jira agile boards by name, project key, or type.\",\n \"args\": \"ctx: The FastMCP context.\\nboard_name: Name of the board (fuzzy search).\\nproject_key: Project key.\\nboard_type: Board type ('scrum' or 'kanban').\\nstart_at: Starting index.\\nlimit: Maximum results.\",\n \"returns\": \"JSON string representing a list of board objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"board_name\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) The name of board, support fuzzy search\",\n \"title\": \"Board Name\"\n },\n \"project_key\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Jira project key (e.g., 'PROJ-123')\",\n \"title\": \"Project Key\"\n },\n \"board_type\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) The type of jira board (e.g., 'scrum', 'kanban')\",\n \"title\": \"Board Type\"\n },\n \"start_at\": {\n \"default\": 0,\n \"description\": \"Starting index for pagination (0-based)\",\n \"minimum\": 0,\n \"title\": \"Start At\",\n \"type\": \"integer\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n }\n },\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_board_issues\",\n \"parsed_description\": {\n \"main\": \"Get all issues linked to a specific board filtered by JQL.\",\n \"args\": \"ctx: The FastMCP context.\\nboard_id: The ID of the board.\\njql: JQL query string to filter issues.\\nfields: Comma-separated fields to return.\\nstart_at: Starting index for pagination.\\nlimit: Maximum number of results.\\nexpand: Optional fields to expand.\",\n \"returns\": \"JSON string representing the search results including pagination info.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"board_id\": {\n \"description\": \"The id of the board (e.g., '1001')\",\n \"title\": \"Board Id\",\n \"type\": \"string\"\n },\n \"jql\": {\n \"description\": \"JQL query string (Jira Query Language). Examples:\\n- Find Epics: \\\"issuetype = Epic AND project = PROJ\\\"\\n- Find issues in Epic: \\\"parent = PROJ-123\\\"\\n- Find by status: \\\"status = 'In Progress' AND project = PROJ\\\"\\n- Find by assignee: \\\"assignee = currentUser()\\\"\\n- Find recently updated: \\\"updated >= -7d AND project = PROJ\\\"\\n- Find by label: \\\"labels = frontend AND project = PROJ\\\"\\n- Find by priority: \\\"priority = High AND project = PROJ\\\"\",\n \"title\": \"Jql\",\n \"type\": \"string\"\n },\n \"fields\": {\n \"default\": \"reporter,labels,description,created,priority,assignee,updated,status,issuetype,summary\",\n \"description\": \"Comma-separated fields to return in the results. Use '*all' for all fields, or specify individual fields like 'summary,status,assignee,priority'\",\n \"title\": \"Fields\",\n \"type\": \"string\"\n },\n \"start_at\": {\n \"default\": 0,\n \"description\": \"Starting index for pagination (0-based)\",\n \"minimum\": 0,\n \"title\": \"Start At\",\n \"type\": \"integer\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n },\n \"expand\": {\n \"default\": \"version\",\n \"description\": \"Optional fields to expand in the response (e.g., 'changelog').\",\n \"title\": \"Expand\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"board_id\",\n \"jql\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_sprints_from_board\",\n \"parsed_description\": {\n \"main\": \"Get jira sprints from board by state.\",\n \"args\": \"ctx: The FastMCP context.\\nboard_id: The ID of the board.\\nstate: Sprint state ('active', 'future', 'closed'). If None, returns all sprints.\\nstart_at: Starting index.\\nlimit: Maximum results.\",\n \"returns\": \"JSON string representing a list of sprint objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"board_id\": {\n \"description\": \"The id of board (e.g., '1000')\",\n \"title\": \"Board Id\",\n \"type\": \"string\"\n },\n \"state\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Sprint state (e.g., 'active', 'future', 'closed')\",\n \"title\": \"State\"\n },\n \"start_at\": {\n \"default\": 0,\n \"description\": \"Starting index for pagination (0-based)\",\n \"minimum\": 0,\n \"title\": \"Start At\",\n \"type\": \"integer\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"board_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_sprint_issues\",\n \"parsed_description\": {\n \"main\": \"Get jira issues from sprint.\",\n \"args\": \"ctx: The FastMCP context.\\nsprint_id: The ID of the sprint.\\nfields: Comma-separated fields to return.\\nstart_at: Starting index.\\nlimit: Maximum results.\",\n \"returns\": \"JSON string representing the search results including pagination info.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"sprint_id\": {\n \"description\": \"The id of sprint (e.g., '10001')\",\n \"title\": \"Sprint Id\",\n \"type\": \"string\"\n },\n \"fields\": {\n \"default\": \"reporter,labels,description,created,priority,assignee,updated,status,issuetype,summary\",\n \"description\": \"Comma-separated fields to return in the results. Use '*all' for all fields, or specify individual fields like 'summary,status,assignee,priority'\",\n \"title\": \"Fields\",\n \"type\": \"string\"\n },\n \"start_at\": {\n \"default\": 0,\n \"description\": \"Starting index for pagination (0-based)\",\n \"minimum\": 0,\n \"title\": \"Start At\",\n \"type\": \"integer\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"sprint_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_link_types\",\n \"parsed_description\": {\n \"main\": \"Get all available issue link types.\",\n \"args\": \"ctx: The FastMCP context.\",\n \"returns\": \"JSON string representing a list of issue link type objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {},\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_create_issue\",\n \"parsed_description\": {\n \"main\": \"Create a new Jira issue with optional Epic link or parent for subtasks.\",\n \"args\": \"ctx: The FastMCP context.\\nproject_key: The JIRA project key.\\nsummary: Summary/title of the issue.\\nissue_type: Issue type (e.g., 'Task', 'Bug', 'Story', 'Epic', 'Subtask').\\nassignee: Assignee's user identifier (string): Email, display name, or account ID (e.g., 'user@example.com', 'John Doe', 'accountid:...').\\ndescription: Issue description.\\ncomponents: Comma-separated list of component names.\\nadditional_fields: Dictionary of additional fields.\",\n \"returns\": \"JSON string representing the created issue object.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client is unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"project_key\": {\n \"description\": \"The JIRA project key (e.g. 'PROJ', 'DEV', 'SUPPORT'). This is the prefix of issue keys in your project. Never assume what it might be, always ask the user.\",\n \"title\": \"Project Key\",\n \"type\": \"string\"\n },\n \"summary\": {\n \"description\": \"Summary/title of the issue\",\n \"title\": \"Summary\",\n \"type\": \"string\"\n },\n \"issue_type\": {\n \"description\": \"Issue type (e.g. 'Task', 'Bug', 'Story', 'Epic', 'Subtask'). The available types depend on your project configuration. For subtasks, use 'Subtask' (not 'Sub-task') and include parent in additional_fields.\",\n \"title\": \"Issue Type\",\n \"type\": \"string\"\n },\n \"assignee\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Assignee's user identifier (string): Email, display name, or account ID (e.g., 'user@example.com', 'John Doe', 'accountid:...')\",\n \"title\": \"Assignee\"\n },\n \"description\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Issue description\",\n \"title\": \"Description\"\n },\n \"components\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Comma-separated list of component names to assign (e.g., 'Frontend,API')\",\n \"title\": \"Components\"\n },\n \"additional_fields\": {\n \"anyOf\": [\n {\n \"additionalProperties\": true,\n \"type\": \"object\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Dictionary of additional fields to set. Examples:\\n- Set priority: {'priority': {'name': 'High'}}\\n- Add labels: {'labels': ['frontend', 'urgent']}\\n- Link to parent (for any issue type): {'parent': 'PROJ-123'}\\n- Set Fix Version/s: {'fixVersions': [{'id': '10020'}]}\\n- Custom fields: {'customfield_10010': 'value'}\",\n \"title\": \"Additional Fields\"\n }\n },\n \"required\": [\n \"project_key\",\n \"summary\",\n \"issue_type\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_batch_create_issues\",\n \"parsed_description\": {\n \"main\": \"Create multiple Jira issues in a batch.\",\n \"args\": \"ctx: The FastMCP context.\\nissues: JSON array string of issue objects.\\nvalidate_only: If true, only validates without creating.\",\n \"returns\": \"JSON string indicating success and listing created issues (or validation result).\",\n \"raises\": \"ValueError: If in read-only mode, Jira client unavailable, or invalid JSON.\"\n },\n \"schema\": {\n \"properties\": {\n \"issues\": {\n \"description\": \"JSON array of issue objects. Each object should contain:\\n- project_key (required): The project key (e.g., 'PROJ')\\n- summary (required): Issue summary/title\\n- issue_type (required): Type of issue (e.g., 'Task', 'Bug')\\n- description (optional): Issue description\\n- assignee (optional): Assignee username or email\\n- components (optional): Array of component names\\nExample: [\\n {\\\"project_key\\\": \\\"PROJ\\\", \\\"summary\\\": \\\"Issue 1\\\", \\\"issue_type\\\": \\\"Task\\\"},\\n {\\\"project_key\\\": \\\"PROJ\\\", \\\"summary\\\": \\\"Issue 2\\\", \\\"issue_type\\\": \\\"Bug\\\", \\\"components\\\": [\\\"Frontend\\\"]}\\n]\",\n \"title\": \"Issues\",\n \"type\": \"string\"\n },\n \"validate_only\": {\n \"default\": false,\n \"description\": \"If true, only validates the issues without creating them\",\n \"title\": \"Validate Only\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"issues\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_batch_get_changelogs\",\n \"parsed_description\": {\n \"main\": \"Get changelogs for multiple Jira issues (Cloud only).\",\n \"args\": \"ctx: The FastMCP context.\\nissue_ids_or_keys: List of issue IDs or keys.\\nfields: List of fields to filter changelogs by. None for all fields.\\nlimit: Maximum changelogs per issue (-1 for all).\",\n \"returns\": \"JSON string representing a list of issues with their changelogs.\",\n \"raises\": \"NotImplementedError: If run on Jira Server/Data Center.\\nValueError: If Jira client is unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_ids_or_keys\": {\n \"description\": \"List of Jira issue IDs or keys, e.g. ['PROJ-123', 'PROJ-124']\",\n \"items\": {\n \"type\": \"string\"\n },\n \"title\": \"Issue Ids Or Keys\",\n \"type\": \"array\"\n },\n \"fields\": {\n \"anyOf\": [\n {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Filter the changelogs by fields, e.g. ['status', 'assignee']. Default to None for all fields.\",\n \"title\": \"Fields\"\n },\n \"limit\": {\n \"default\": -1,\n \"description\": \"Maximum number of changelogs to return in result for each issue. Default to -1 for all changelogs. Notice that it only limits the results in the response, the function will still fetch all the data.\",\n \"title\": \"Limit\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"issue_ids_or_keys\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_update_issue\",\n \"parsed_description\": {\n \"main\": \"Update an existing Jira issue including changing status, adding Epic links, updating fields, etc.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\\nfields: Dictionary of fields to update.\\nadditional_fields: Optional dictionary of additional fields.\\nattachments: Optional JSON array string or comma-separated list of file paths.\",\n \"returns\": \"JSON string representing the updated issue object and attachment results.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client unavailable, or invalid input.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"fields\": {\n \"additionalProperties\": true,\n \"description\": \"Dictionary of fields to update. For 'assignee', provide a string identifier (email, name, or accountId). Example: `{'assignee': 'user@example.com', 'summary': 'New Summary'}`\",\n \"title\": \"Fields\",\n \"type\": \"object\"\n },\n \"additional_fields\": {\n \"anyOf\": [\n {\n \"additionalProperties\": true,\n \"type\": \"object\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Dictionary of additional fields to update. Use this for custom fields or more complex updates.\",\n \"title\": \"Additional Fields\"\n },\n \"attachments\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) JSON string array or comma-separated list of file paths to attach to the issue. Example: '/path/to/file1.txt,/path/to/file2.txt' or ['/path/to/file1.txt','/path/to/file2.txt']\",\n \"title\": \"Attachments\"\n }\n },\n \"required\": [\n \"issue_key\",\n \"fields\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_delete_issue\",\n \"parsed_description\": {\n \"main\": \"Delete an existing Jira issue.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\",\n \"returns\": \"JSON string indicating success.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g. PROJ-123)\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"issue_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_add_comment\",\n \"parsed_description\": {\n \"main\": \"Add a comment to a Jira issue.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\\ncomment: Comment text in Markdown.\",\n \"returns\": \"JSON string representing the added comment object.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"comment\": {\n \"description\": \"Comment text in Markdown format\",\n \"title\": \"Comment\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"issue_key\",\n \"comment\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_add_worklog\",\n \"parsed_description\": {\n \"main\": \"Add a worklog entry to a Jira issue.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\\ntime_spent: Time spent in Jira format.\\ncomment: Optional comment in Markdown.\\nstarted: Optional start time in ISO format.\\noriginal_estimate: Optional new original estimate.\\nremaining_estimate: Optional new remaining estimate.\",\n \"returns\": \"JSON string representing the added worklog object.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"time_spent\": {\n \"description\": \"Time spent in Jira format. Examples: '1h 30m' (1 hour and 30 minutes), '1d' (1 day), '30m' (30 minutes), '4h' (4 hours)\",\n \"title\": \"Time Spent\",\n \"type\": \"string\"\n },\n \"comment\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Comment for the worklog in Markdown format\",\n \"title\": \"Comment\"\n },\n \"started\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Start time in ISO format. If not provided, the current time will be used. Example: '2023-08-01T12:00:00.000+0000'\",\n \"title\": \"Started\"\n },\n \"original_estimate\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) New value for the original estimate\",\n \"title\": \"Original Estimate\"\n },\n \"remaining_estimate\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) New value for the remaining estimate\",\n \"title\": \"Remaining Estimate\"\n }\n },\n \"required\": [\n \"issue_key\",\n \"time_spent\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_link_to_epic\",\n \"parsed_description\": {\n \"main\": \"Link an existing issue to an epic.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: The key of the issue to link.\\nepic_key: The key of the epic to link to.\",\n \"returns\": \"JSON string representing the updated issue object.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"The key of the issue to link (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"epic_key\": {\n \"description\": \"The key of the epic to link to (e.g., 'PROJ-456')\",\n \"title\": \"Epic Key\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"issue_key\",\n \"epic_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_create_issue_link\",\n \"parsed_description\": {\n \"main\": \"Create a link between two Jira issues.\",\n \"args\": \"ctx: The FastMCP context.\\nlink_type: The type of link (e.g., 'Blocks').\\ninward_issue_key: The key of the source issue.\\noutward_issue_key: The key of the target issue.\\ncomment: Optional comment text.\\ncomment_visibility: Optional dictionary for comment visibility.\",\n \"returns\": \"JSON string indicating success or failure.\",\n \"raises\": \"ValueError: If required fields are missing, invalid input, in read-only mode, or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"link_type\": {\n \"description\": \"The type of link to create (e.g., 'Duplicate', 'Blocks', 'Relates to')\",\n \"title\": \"Link Type\",\n \"type\": \"string\"\n },\n \"inward_issue_key\": {\n \"description\": \"The key of the inward issue (e.g., 'PROJ-123')\",\n \"title\": \"Inward Issue Key\",\n \"type\": \"string\"\n },\n \"outward_issue_key\": {\n \"description\": \"The key of the outward issue (e.g., 'PROJ-456')\",\n \"title\": \"Outward Issue Key\",\n \"type\": \"string\"\n },\n \"comment\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Comment to add to the link\",\n \"title\": \"Comment\"\n },\n \"comment_visibility\": {\n \"anyOf\": [\n {\n \"additionalProperties\": {\n \"type\": \"string\"\n },\n \"type\": \"object\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Visibility settings for the comment (e.g., {'type': 'group', 'value': 'jira-users'})\",\n \"title\": \"Comment Visibility\"\n }\n },\n \"required\": [\n \"link_type\",\n \"inward_issue_key\",\n \"outward_issue_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_create_remote_issue_link\",\n \"parsed_description\": {\n \"main\": \"Create a remote issue link (web link or Confluence link) for a Jira issue.\\n\\nThis tool allows you to add web links and Confluence links to Jira issues.\\nThe links will appear in the issue's \\\"Links\\\" section and can be clicked to navigate to external resources.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: The key of the issue to add the link to.\\nurl: The URL to link to (can be any web page or Confluence page).\\ntitle: The title/name that will be displayed for the link.\\nsummary: Optional description of what the link is for.\\nrelationship: Optional relationship description.\\nicon_url: Optional URL to a 16x16 icon for the link.\",\n \"returns\": \"JSON string indicating success or failure.\",\n \"raises\": \"ValueError: If required fields are missing, invalid input, in read-only mode, or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"The key of the issue to add the link to (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"url\": {\n \"description\": \"The URL to link to (e.g., 'https://example.com/page' or Confluence page URL)\",\n \"title\": \"Url\",\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"The title/name of the link (e.g., 'Documentation Page', 'Confluence Page')\",\n \"title\": \"Title\",\n \"type\": \"string\"\n },\n \"summary\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Description of the link\",\n \"title\": \"Summary\"\n },\n \"relationship\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Relationship description (e.g., 'causes', 'relates to', 'documentation')\",\n \"title\": \"Relationship\"\n },\n \"icon_url\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) URL to a 16x16 icon for the link\",\n \"title\": \"Icon Url\"\n }\n },\n \"required\": [\n \"issue_key\",\n \"url\",\n \"title\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_remove_issue_link\",\n \"parsed_description\": {\n \"main\": \"Remove a link between two Jira issues.\",\n \"args\": \"ctx: The FastMCP context.\\nlink_id: The ID of the link to remove.\",\n \"returns\": \"JSON string indicating success.\",\n \"raises\": \"ValueError: If link_id is missing, in read-only mode, or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"link_id\": {\n \"description\": \"The ID of the link to remove\",\n \"title\": \"Link Id\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"link_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_transition_issue\",\n \"parsed_description\": {\n \"main\": \"Transition a Jira issue to a new status.\",\n \"args\": \"ctx: The FastMCP context.\\nissue_key: Jira issue key.\\ntransition_id: ID of the transition.\\nfields: Optional dictionary of fields to update during transition.\\ncomment: Optional comment for the transition.\",\n \"returns\": \"JSON string representing the updated issue object.\",\n \"raises\": \"ValueError: If required fields missing, invalid input, in read-only mode, or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"issue_key\": {\n \"description\": \"Jira issue key (e.g., 'PROJ-123')\",\n \"title\": \"Issue Key\",\n \"type\": \"string\"\n },\n \"transition_id\": {\n \"description\": \"ID of the transition to perform. Use the jira_get_transitions tool first to get the available transition IDs for the issue. Example values: '11', '21', '31'\",\n \"title\": \"Transition Id\",\n \"type\": \"string\"\n },\n \"fields\": {\n \"anyOf\": [\n {\n \"additionalProperties\": true,\n \"type\": \"object\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Dictionary of fields to update during the transition. Some transitions require specific fields to be set (e.g., resolution). Example: {'resolution': {'name': 'Fixed'}}\",\n \"title\": \"Fields\"\n },\n \"comment\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Comment to add during the transition. This will be visible in the issue history.\",\n \"title\": \"Comment\"\n }\n },\n \"required\": [\n \"issue_key\",\n \"transition_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_create_sprint\",\n \"parsed_description\": {\n \"main\": \"Create Jira sprint for a board.\",\n \"args\": \"ctx: The FastMCP context.\\nboard_id: Board ID.\\nsprint_name: Sprint name.\\nstart_date: Start date (ISO format).\\nend_date: End date (ISO format).\\ngoal: Optional sprint goal.\",\n \"returns\": \"JSON string representing the created sprint object.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"board_id\": {\n \"description\": \"The id of board (e.g., '1000')\",\n \"title\": \"Board Id\",\n \"type\": \"string\"\n },\n \"sprint_name\": {\n \"description\": \"Name of the sprint (e.g., 'Sprint 1')\",\n \"title\": \"Sprint Name\",\n \"type\": \"string\"\n },\n \"start_date\": {\n \"description\": \"Start time for sprint (ISO 8601 format)\",\n \"title\": \"Start Date\",\n \"type\": \"string\"\n },\n \"end_date\": {\n \"description\": \"End time for sprint (ISO 8601 format)\",\n \"title\": \"End Date\",\n \"type\": \"string\"\n },\n \"goal\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Goal of the sprint\",\n \"title\": \"Goal\"\n }\n },\n \"required\": [\n \"board_id\",\n \"sprint_name\",\n \"start_date\",\n \"end_date\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_update_sprint\",\n \"parsed_description\": {\n \"main\": \"Update jira sprint.\",\n \"args\": \"ctx: The FastMCP context.\\nsprint_id: The ID of the sprint.\\nsprint_name: Optional new name.\\nstate: Optional new state (future|active|closed).\\nstart_date: Optional new start date.\\nend_date: Optional new end date.\\ngoal: Optional new goal.\",\n \"returns\": \"JSON string representing the updated sprint object or an error message.\",\n \"raises\": \"ValueError: If in read-only mode or Jira client unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"sprint_id\": {\n \"description\": \"The id of sprint (e.g., '10001')\",\n \"title\": \"Sprint Id\",\n \"type\": \"string\"\n },\n \"sprint_name\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) New name for the sprint\",\n \"title\": \"Sprint Name\"\n },\n \"state\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) New state for the sprint (future|active|closed)\",\n \"title\": \"State\"\n },\n \"start_date\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) New start date for the sprint\",\n \"title\": \"Start Date\"\n },\n \"end_date\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) New end date for the sprint\",\n \"title\": \"End Date\"\n },\n \"goal\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) New goal for the sprint\",\n \"title\": \"Goal\"\n }\n },\n \"required\": [\n \"sprint_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_project_versions\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"project_key\": {\n \"description\": \"Jira project key (e.g., 'PROJ')\",\n \"title\": \"Project Key\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"project_key\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_get_all_projects\",\n \"parsed_description\": {\n \"main\": \"Get all Jira projects accessible to the current user.\",\n \"args\": \"ctx: The FastMCP context.\\ninclude_archived: Whether to include archived projects.\",\n \"returns\": \"JSON string representing a list of project objects accessible to the user.\\nProject keys are always returned in uppercase.\\nIf JIRA_PROJECTS_FILTER is configured, only returns projects matching those keys.\",\n \"raises\": \"ValueError: If the Jira client is not configured or available.\"\n },\n \"schema\": {\n \"properties\": {\n \"include_archived\": {\n \"default\": false,\n \"description\": \"Whether to include archived projects in the results\",\n \"title\": \"Include Archived\",\n \"type\": \"boolean\"\n }\n },\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_create_version\",\n \"parsed_description\": {\n \"main\": \"Create a new fix version in a Jira project.\",\n \"args\": \"ctx: The FastMCP context.\\nproject_key: The project key.\\nname: Name of the version.\\nstart_date: Start date (optional).\\nrelease_date: Release date (optional).\\ndescription: Description (optional).\",\n \"returns\": \"JSON string of the created version object.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"project_key\": {\n \"description\": \"Jira project key (e.g., 'PROJ')\",\n \"title\": \"Project Key\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"Name of the version\",\n \"title\": \"Name\",\n \"type\": \"string\"\n },\n \"start_date\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Start date (YYYY-MM-DD)\",\n \"title\": \"Start Date\"\n },\n \"release_date\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Release date (YYYY-MM-DD)\",\n \"title\": \"Release Date\"\n },\n \"description\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Description of the version\",\n \"title\": \"Description\"\n }\n },\n \"required\": [\n \"project_key\",\n \"name\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"jira_batch_create_versions\",\n \"parsed_description\": {\n \"main\": \"Batch create multiple versions in a Jira project.\",\n \"args\": \"ctx: The FastMCP context.\\nproject_key: The project key.\\nversions: JSON array string of version objects.\",\n \"returns\": \"JSON array of results, each with success flag, version or error.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"project_key\": {\n \"description\": \"Jira project key (e.g., 'PROJ')\",\n \"title\": \"Project Key\",\n \"type\": \"string\"\n },\n \"versions\": {\n \"description\": \"JSON array of version objects. Each object should contain:\\n- name (required): Name of the version\\n- startDate (optional): Start date (YYYY-MM-DD)\\n- releaseDate (optional): Release date (YYYY-MM-DD)\\n- description (optional): Description of the version\\nExample: [\\n {\\\"name\\\": \\\"v1.0\\\", \\\"startDate\\\": \\\"2025-01-01\\\", \\\"releaseDate\\\": \\\"2025-02-01\\\", \\\"description\\\": \\\"First release\\\"},\\n {\\\"name\\\": \\\"v2.0\\\"}\\n]\",\n \"title\": \"Versions\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"project_key\",\n \"versions\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_search\",\n \"parsed_description\": {\n \"main\": \"Search Confluence content using simple terms or CQL.\",\n \"args\": \"ctx: The FastMCP context.\\nquery: Search query - can be simple text or a CQL query string.\\nlimit: Maximum number of results (1-50).\\nspaces_filter: Comma-separated list of space keys to filter by.\",\n \"returns\": \"JSON string representing a list of simplified Confluence page objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"query\": {\n \"description\": \"Search query - can be either a simple text (e.g. 'project documentation') or a CQL query string. Simple queries use 'siteSearch' by default, to mimic the WebUI search, with an automatic fallback to 'text' search if not supported. Examples of CQL:\\n- Basic search: 'type=page AND space=DEV'\\n- Personal space search: 'space=\\\"~username\\\"' (note: personal space keys starting with ~ must be quoted)\\n- Search by title: 'title~\\\"Meeting Notes\\\"'\\n- Use siteSearch: 'siteSearch ~ \\\"important concept\\\"'\\n- Use text search: 'text ~ \\\"important concept\\\"'\\n- Recent content: 'created >= \\\"2023-01-01\\\"'\\n- Content with specific label: 'label=documentation'\\n- Recently modified content: 'lastModified > startOfMonth(\\\"-1M\\\")'\\n- Content modified this year: 'creator = currentUser() AND lastModified > startOfYear()'\\n- Content you contributed to recently: 'contributor = currentUser() AND lastModified > startOfWeek()'\\n- Content watched by user: 'watcher = \\\"user@domain.com\\\" AND type = page'\\n- Exact phrase in content: 'text ~ \\\"\\\\\\\"Urgent Review Required\\\\\\\"\\\" AND label = \\\"pending-approval\\\"'\\n- Title wildcards: 'title ~ \\\"Minutes*\\\" AND (space = \\\"HR\\\" OR space = \\\"Marketing\\\")'\\nNote: Special identifiers need proper quoting in CQL: personal space keys (e.g., \\\"~username\\\"), reserved words, numeric IDs, and identifiers with special characters.\",\n \"title\": \"Query\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n },\n \"spaces_filter\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) Comma-separated list of space keys to filter results by. Overrides the environment variable CONFLUENCE_SPACES_FILTER if provided. Use empty string to disable filtering.\",\n \"title\": \"Spaces Filter\"\n }\n },\n \"required\": [\n \"query\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_get_page\",\n \"parsed_description\": {\n \"main\": \"Get content of a specific Confluence page by its ID, or by its title and space key.\",\n \"args\": \"ctx: The FastMCP context.\\npage_id: Confluence page ID. If provided, 'title' and 'space_key' are ignored.\\ntitle: The exact title of the page. Must be used with 'space_key'.\\nspace_key: The key of the space. Must be used with 'title'.\\ninclude_metadata: Whether to include page metadata.\\nconvert_to_markdown: Convert content to markdown (true) or keep raw HTML (false).\",\n \"returns\": \"JSON string representing the page content and/or metadata, or an error if not found or parameters are invalid.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"page_id\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Confluence page ID (numeric ID, can be found in the page URL). For example, in the URL 'https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title', the page ID is '123456789'. Provide this OR both 'title' and 'space_key'. If page_id is provided, title and space_key will be ignored.\",\n \"title\": \"Page Id\"\n },\n \"title\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"The exact title of the Confluence page. Use this with 'space_key' if 'page_id' is not known.\",\n \"title\": \"Title\"\n },\n \"space_key\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"The key of the Confluence space where the page resides (e.g., 'DEV', 'TEAM'). Required if using 'title'.\",\n \"title\": \"Space Key\"\n },\n \"include_metadata\": {\n \"default\": true,\n \"description\": \"Whether to include page metadata such as creation date, last update, version, and labels.\",\n \"title\": \"Include Metadata\",\n \"type\": \"boolean\"\n },\n \"convert_to_markdown\": {\n \"default\": true,\n \"description\": \"Whether to convert page to markdown (true) or keep it in raw HTML format (false). Raw HTML can reveal macros (like dates) not visible in markdown, but CAUTION: using HTML significantly increases token usage in AI responses.\",\n \"title\": \"Convert To Markdown\",\n \"type\": \"boolean\"\n }\n },\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_get_page_children\",\n \"parsed_description\": {\n \"main\": \"Get child pages of a specific Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\nparent_id: The ID of the parent page.\\nexpand: Fields to expand.\\nlimit: Maximum number of child pages.\\ninclude_content: Whether to include page content.\\nconvert_to_markdown: Convert content to markdown if include_content is true.\\nstart: Starting index for pagination.\",\n \"returns\": \"JSON string representing a list of child page objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"parent_id\": {\n \"description\": \"The ID of the parent page whose children you want to retrieve\",\n \"title\": \"Parent Id\",\n \"type\": \"string\"\n },\n \"expand\": {\n \"default\": \"version\",\n \"description\": \"Fields to expand in the response (e.g., 'version', 'body.storage')\",\n \"title\": \"Expand\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"default\": 25,\n \"description\": \"Maximum number of child pages to return (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n },\n \"include_content\": {\n \"default\": false,\n \"description\": \"Whether to include the page content in the response\",\n \"title\": \"Include Content\",\n \"type\": \"boolean\"\n },\n \"convert_to_markdown\": {\n \"default\": true,\n \"description\": \"Whether to convert page content to markdown (true) or keep it in raw HTML format (false). Only relevant if include_content is true.\",\n \"title\": \"Convert To Markdown\",\n \"type\": \"boolean\"\n },\n \"start\": {\n \"default\": 0,\n \"description\": \"Starting index for pagination (0-based)\",\n \"minimum\": 0,\n \"title\": \"Start\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"parent_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_get_comments\",\n \"parsed_description\": {\n \"main\": \"Get comments for a specific Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\npage_id: Confluence page ID.\",\n \"returns\": \"JSON string representing a list of comment objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"page_id\": {\n \"description\": \"Confluence page ID (numeric ID, can be parsed from URL, e.g. from 'https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title' -> '123456789')\",\n \"title\": \"Page Id\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"page_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_get_labels\",\n \"parsed_description\": {\n \"main\": \"Get labels for a specific Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\npage_id: Confluence page ID.\",\n \"returns\": \"JSON string representing a list of label objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"page_id\": {\n \"description\": \"Confluence page ID (numeric ID, can be parsed from URL, e.g. from 'https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title' -> '123456789')\",\n \"title\": \"Page Id\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"page_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_add_label\",\n \"parsed_description\": {\n \"main\": \"Add label to an existing Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\npage_id: The ID of the page to update.\\nname: The name of the label.\",\n \"returns\": \"JSON string representing the updated list of label objects for the page.\",\n \"raises\": \"ValueError: If in read-only mode or Confluence client is unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"page_id\": {\n \"description\": \"The ID of the page to update\",\n \"title\": \"Page Id\",\n \"type\": \"string\"\n },\n \"name\": {\n \"description\": \"The name of the label\",\n \"title\": \"Name\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"page_id\",\n \"name\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_create_page\",\n \"parsed_description\": {\n \"main\": \"Create a new Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\nspace_key: The key of the space.\\ntitle: The title of the page.\\ncontent: The content of the page (format depends on content_format).\\nparent_id: Optional parent page ID.\\ncontent_format: The format of the content ('markdown', 'wiki', or 'storage').\\nenable_heading_anchors: Whether to enable heading anchors (markdown only).\",\n \"returns\": \"JSON string representing the created page object.\",\n \"raises\": \"ValueError: If in read-only mode, Confluence client is unavailable, or invalid content_format.\"\n },\n \"schema\": {\n \"properties\": {\n \"space_key\": {\n \"description\": \"The key of the space to create the page in (usually a short uppercase code like 'DEV', 'TEAM', or 'DOC')\",\n \"title\": \"Space Key\",\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"The title of the page\",\n \"title\": \"Title\",\n \"type\": \"string\"\n },\n \"content\": {\n \"description\": \"The content of the page. Format depends on content_format parameter. Can be Markdown (default), wiki markup, or storage format\",\n \"title\": \"Content\",\n \"type\": \"string\"\n },\n \"parent_id\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"(Optional) parent page ID. If provided, this page will be created as a child of the specified page\",\n \"title\": \"Parent Id\"\n },\n \"content_format\": {\n \"default\": \"markdown\",\n \"description\": \"(Optional) The format of the content parameter. Options: 'markdown' (default), 'wiki', or 'storage'. Wiki format uses Confluence wiki markup syntax\",\n \"title\": \"Content Format\",\n \"type\": \"string\"\n },\n \"enable_heading_anchors\": {\n \"default\": false,\n \"description\": \"(Optional) Whether to enable automatic heading anchor generation. Only applies when content_format is 'markdown'\",\n \"title\": \"Enable Heading Anchors\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"space_key\",\n \"title\",\n \"content\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_update_page\",\n \"parsed_description\": {\n \"main\": \"Update an existing Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\npage_id: The ID of the page to update.\\ntitle: The new title of the page.\\ncontent: The new content of the page (format depends on content_format).\\nis_minor_edit: Whether this is a minor edit.\\nversion_comment: Optional comment for this version.\\nparent_id: Optional new parent page ID.\\ncontent_format: The format of the content ('markdown', 'wiki', or 'storage').\\nenable_heading_anchors: Whether to enable heading anchors (markdown only).\",\n \"returns\": \"JSON string representing the updated page object.\",\n \"raises\": \"ValueError: If Confluence client is not configured, available, or invalid content_format.\"\n },\n \"schema\": {\n \"properties\": {\n \"page_id\": {\n \"description\": \"The ID of the page to update\",\n \"title\": \"Page Id\",\n \"type\": \"string\"\n },\n \"title\": {\n \"description\": \"The new title of the page\",\n \"title\": \"Title\",\n \"type\": \"string\"\n },\n \"content\": {\n \"description\": \"The new content of the page. Format depends on content_format parameter\",\n \"title\": \"Content\",\n \"type\": \"string\"\n },\n \"is_minor_edit\": {\n \"default\": false,\n \"description\": \"Whether this is a minor edit\",\n \"title\": \"Is Minor Edit\",\n \"type\": \"boolean\"\n },\n \"version_comment\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Optional comment for this version\",\n \"title\": \"Version Comment\"\n },\n \"parent_id\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Optional the new parent page ID\",\n \"title\": \"Parent Id\"\n },\n \"content_format\": {\n \"default\": \"markdown\",\n \"description\": \"(Optional) The format of the content parameter. Options: 'markdown' (default), 'wiki', or 'storage'. Wiki format uses Confluence wiki markup syntax\",\n \"title\": \"Content Format\",\n \"type\": \"string\"\n },\n \"enable_heading_anchors\": {\n \"default\": false,\n \"description\": \"(Optional) Whether to enable automatic heading anchor generation. Only applies when content_format is 'markdown'\",\n \"title\": \"Enable Heading Anchors\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"page_id\",\n \"title\",\n \"content\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_delete_page\",\n \"parsed_description\": {\n \"main\": \"Delete an existing Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\npage_id: The ID of the page to delete.\",\n \"returns\": \"JSON string indicating success or failure.\",\n \"raises\": \"ValueError: If Confluence client is not configured or available.\"\n },\n \"schema\": {\n \"properties\": {\n \"page_id\": {\n \"description\": \"The ID of the page to delete\",\n \"title\": \"Page Id\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"page_id\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_add_comment\",\n \"parsed_description\": {\n \"main\": \"Add a comment to a Confluence page.\",\n \"args\": \"ctx: The FastMCP context.\\npage_id: The ID of the page to add a comment to.\\ncontent: The comment content in Markdown format.\",\n \"returns\": \"JSON string representing the created comment.\",\n \"raises\": \"ValueError: If in read-only mode or Confluence client is unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"page_id\": {\n \"description\": \"The ID of the page to add a comment to\",\n \"title\": \"Page Id\",\n \"type\": \"string\"\n },\n \"content\": {\n \"description\": \"The comment content in Markdown format\",\n \"title\": \"Content\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"page_id\",\n \"content\"\n ],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"confluence_search_user\",\n \"parsed_description\": {\n \"main\": \"Search Confluence users using CQL.\",\n \"args\": \"ctx: The FastMCP context.\\nquery: Search query - a CQL query string for user search.\\nlimit: Maximum number of results (1-50).\",\n \"returns\": \"JSON string representing a list of simplified Confluence user search result objects.\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"query\": {\n \"description\": \"Search query - a CQL query string for user search. Examples of CQL:\\n- Basic user lookup by full name: 'user.fullname ~ \\\"First Last\\\"'\\nNote: Special identifiers need proper quoting in CQL: personal space keys (e.g., \\\"~username\\\"), reserved words, numeric IDs, and identifiers with special characters.\",\n \"title\": \"Query\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"default\": 10,\n \"description\": \"Maximum number of results (1-50)\",\n \"maximum\": 50,\n \"minimum\": 1,\n \"title\": \"Limit\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"query\"\n ],\n \"type\": \"object\"\n }\n }\n ]\n }" }, { "path": "registry/servers/currenttime.json", "content": "{\n \"server_name\": \"Current Time API\",\n \"description\": \"A simple API that returns the current server time in various formats.\",\n \"path\": \"/currenttime/\",\n \"proxy_pass_url\": \"http://currenttime-server:8000/\",\n \"auth_scheme\": \"none\",\n \"tags\": [\"time\", \"utility\", \"api\"],\n \"num_tools\": 1,\n \"license\": \"MIT-0\",\n \"metadata\": {\n \"team\": \"platform-services\",\n \"owner\": \"alice@example.com\",\n \"cost_center\": \"CC-1001\",\n \"compliance\": [\"SOC2\"],\n \"deployment_region\": \"us-east-1\",\n \"jira_project\": \"PLAT-123\",\n \"environment\": \"production\"\n },\n \"tool_list\": [\n {\n \"name\": \"current_time_by_timezone\",\n \"parsed_description\": {\n \"main\": \"Get the current time for a specified timezone using the timeapi.io API.\",\n \"args\": \"params: TZ_Name object containing the timezone name\",\n \"returns\": \"str: JSON response from the API with current time information\",\n \"raises\": \"Exception: If the API request fails after maximum retries\"\n },\n \"schema\": {\n \"$defs\": {\n \"TZ_Name\": {\n \"description\": \"Parameters for specifying the name of the timezone for which to find out the current time.\",\n \"properties\": {\n \"tz_name\": {\n \"default\": \"America/New_York\",\n \"description\": \"Name of the timezone for which to find out the current time\",\n \"title\": \"Tz Name\",\n \"type\": \"string\"\n }\n },\n \"title\": \"TZ_Name\",\n \"type\": \"object\"\n }\n },\n \"properties\": {\n \"params\": {\n \"$ref\": \"#/$defs/TZ_Name\"\n }\n },\n \"required\": [\n \"params\"\n ],\n \"title\": \"current_time_by_timezoneArguments\",\n \"type\": \"object\"\n }\n }\n ]\n}" }, { "path": "registry/servers/fininfo.json", "content": "{\n \"server_name\": \"Financial Info Proxy\",\n \"description\": \"Secure gateway proxy for internal financial information systems.\",\n \"path\": \"/fininfo\",\n \"proxy_pass_url\": \"http://fininfo-server:8001/sse\",\n \"supported_transports\": [\"sse\"],\n \"auth_scheme\": \"api_key\",\n \"tags\": [],\n \"num_tools\": 2,\n \"license\": \"N/A\",\n \"tool_list\": [\n {\n \"name\": \"get_stock_aggregates\",\n \"parsed_description\": {\n \"main\": \"Retrieve stock aggregate data from Polygon.io API.\",\n \"args\": \"stock_ticker: Case-sensitive ticker symbol (e.g., 'AAPL'), multiplier: Size of the timespan multiplier, timespan: Size of the time window, from_date: Start date in YYYY-MM-DD format or millisecond timestamp, to_date: End date in YYYY-MM-DD format or millisecond timestamp, adjusted: Whether results are adjusted for splits, sort: Sort results by timestamp ('asc' or 'desc'), limit: Maximum number of base aggregates (max 50000)\",\n \"returns\": \"Dict[str, Any]: Response data from Polygon API\",\n \"raises\": \"requests.RequestException: If API call fails after retries\"\n },\n \"schema\": {\n \"properties\": {\n \"stock_ticker\": {\n \"description\": \"Case-sensitive ticker symbol (e.g., 'AAPL')\",\n \"title\": \"Stock Ticker\",\n \"type\": \"string\"\n },\n \"multiplier\": {\n \"description\": \"Size of the timespan multiplier\",\n \"title\": \"Multiplier\",\n \"type\": \"integer\"\n },\n \"timespan\": {\n \"description\": \"Size of the time window\",\n \"title\": \"Timespan\",\n \"type\": \"string\"\n },\n \"from_date\": {\n \"description\": \"Start date in YYYY-MM-DD format or millisecond timestamp\",\n \"title\": \"From Date\",\n \"type\": \"string\"\n },\n \"to_date\": {\n \"description\": \"End date in YYYY-MM-DD format or millisecond timestamp\",\n \"title\": \"To Date\",\n \"type\": \"string\"\n },\n \"adjusted\": {\n \"default\": true,\n \"description\": \"Whether results are adjusted for splits\",\n \"title\": \"Adjusted\",\n \"type\": \"boolean\"\n },\n \"sort\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Sort results by timestamp ('asc' or 'desc')\",\n \"title\": \"Sort\"\n },\n \"limit\": {\n \"default\": 5000,\n \"description\": \"Maximum number of base aggregates (max 50000)\",\n \"title\": \"Limit\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"stock_ticker\",\n \"multiplier\",\n \"timespan\",\n \"from_date\",\n \"to_date\"\n ],\n \"title\": \"get_stock_aggregatesArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"print_stock_data\",\n \"parsed_description\": {\n \"main\": \"Format all fields from the Polygon.io stock aggregate response as a string.\",\n \"args\": \"stock_ticker: Case-sensitive ticker symbol (e.g., 'AAPL'), multiplier: Size of the timespan multiplier, timespan: Size of the time window, from_date: Start date in YYYY-MM-DD format or millisecond timestamp, to_date: End date in YYYY-MM-DD format or millisecond timestamp, adjusted: Whether results are adjusted for splits, sort: Sort results by timestamp ('asc' or 'desc'), limit: Maximum number of base aggregates (max 50000)\",\n \"returns\": \"str: Formatted string containing all stock data\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"stock_ticker\": {\n \"description\": \"Case-sensitive ticker symbol (e.g., 'AAPL')\",\n \"title\": \"Stock Ticker\",\n \"type\": \"string\"\n },\n \"multiplier\": {\n \"description\": \"Size of the timespan multiplier\",\n \"title\": \"Multiplier\",\n \"type\": \"integer\"\n },\n \"timespan\": {\n \"description\": \"Size of the time window\",\n \"title\": \"Timespan\",\n \"type\": \"string\"\n },\n \"from_date\": {\n \"description\": \"Start date in YYYY-MM-DD format or millisecond timestamp\",\n \"title\": \"From Date\",\n \"type\": \"string\"\n },\n \"to_date\": {\n \"description\": \"End date in YYYY-MM-DD format or millisecond timestamp\",\n \"title\": \"To Date\",\n \"type\": \"string\"\n },\n \"adjusted\": {\n \"default\": true,\n \"description\": \"Whether results are adjusted for splits\",\n \"title\": \"Adjusted\",\n \"type\": \"boolean\"\n },\n \"sort\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Sort results by timestamp ('asc' or 'desc')\",\n \"title\": \"Sort\"\n },\n \"limit\": {\n \"default\": 5000,\n \"description\": \"Maximum number of base aggregates (max 50000)\",\n \"title\": \"Limit\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"stock_ticker\",\n \"multiplier\",\n \"timespan\",\n \"from_date\",\n \"to_date\"\n ],\n \"title\": \"print_stock_dataArguments\",\n \"type\": \"object\"\n }\n }\n ],\n \"resource_list\": [\n {\n \"name\": \"get_config\",\n \"uri\": \"config://app\",\n \"parsed_description\": {\n \"main\": \"Static configuration data\",\n \"returns\": \"str: App configuration data\"\n }\n }\n ]\n}" }, { "path": "registry/servers/mcpgw.json", "content": "{\n \"server_name\": \"MCP Gateway Tools\",\n \"description\": \"Provides tools to interact with the MCP Gateway Registry API.\",\n \"path\": \"/mcpgw/\",\n \"proxy_pass_url\": \"http://mcpgw-server:8003/\",\n \"supported_transports\": [\"streamable-http\"],\n \"auth_scheme\": \"none\",\n \"tags\": [\"registry\", \"management\"],\n \"num_tools\": 11,\n \"license\": \"N/A\",\n \"tool_list\": [\n {\n \"name\": \"debug_auth_context\",\n \"parsed_description\": {\n \"main\": \"Debug tool to explore what authentication context is available.\",\n \"args\": \"None\",\n \"returns\": \"Dict[str, Any]: Detailed debug information about available auth context\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {},\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"get_http_headers\",\n \"parsed_description\": {\n \"main\": \"FastMCP 2.0 tool to access HTTP headers directly using the new dependency system.\",\n \"args\": \"None\",\n \"returns\": \"Dict[str, Any]: HTTP request information including headers\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {},\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"toggle_service\",\n \"parsed_description\": {\n \"main\": \"Toggles the enabled/disabled state of a registered MCP server in the gateway.\",\n \"args\": \"service_path: The unique path identifier for the service\",\n \"returns\": \"Dict[str, Any]: Response from the registry API indicating success or failure.\",\n \"raises\": \"Exception: If the API call fails.\"\n },\n \"schema\": {\n \"properties\": {\n \"service_path\": {\n \"description\": \"The unique path identifier for the service (e.g., '/fininfo'). Must start with '/'.\",\n \"title\": \"Service Path\",\n \"type\": \"string\"\n }\n },\n \"required\": [\"service_path\"],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"register_service\",\n \"parsed_description\": {\n \"main\": \"Registers a new MCP server with the gateway.\",\n \"args\": \"server_name, path, proxy_pass_url, and optional: description, tags, num_tools, license\",\n \"returns\": \"Dict[str, Any]: Response from the registry API, likely including the registered server details.\",\n \"raises\": \"Exception: If the API call fails.\"\n },\n \"schema\": {\n \"properties\": {\n \"server_name\": {\n \"description\": \"Display name for the server.\",\n \"title\": \"Server Name\",\n \"type\": \"string\"\n },\n \"path\": {\n \"description\": \"Unique URL path prefix for the server (e.g., '/my-service'). Must start with '/'.\",\n \"title\": \"Path\",\n \"type\": \"string\"\n },\n \"proxy_pass_url\": {\n \"description\": \"The internal URL where the actual MCP server is running (e.g., 'http://localhost:8001').\",\n \"title\": \"Proxy Pass Url\",\n \"type\": \"string\"\n },\n \"description\": {\n \"anyOf\": [\n {\"type\": \"string\"},\n {\"type\": \"null\"}\n ],\n \"default\": \"\",\n \"description\": \"Description of the server.\",\n \"title\": \"Description\"\n },\n \"tags\": {\n \"anyOf\": [\n {\n \"items\": {\"type\": \"string\"},\n \"type\": \"array\"\n },\n {\"type\": \"null\"}\n ],\n \"default\": null,\n \"description\": \"Optional list of tags for categorization.\",\n \"title\": \"Tags\"\n },\n \"num_tools\": {\n \"anyOf\": [\n {\"type\": \"integer\"},\n {\"type\": \"null\"}\n ],\n \"default\": 0,\n \"description\": \"Number of tools provided by the server.\",\n \"title\": \"Num Tools\"\n },\n \"license\": {\n \"anyOf\": [\n {\"type\": \"string\"},\n {\"type\": \"null\"}\n ],\n \"default\": \"N/A\",\n \"description\": \"License information for the server.\",\n \"title\": \"License\"\n }\n },\n \"required\": [\"server_name\", \"path\", \"proxy_pass_url\"],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"list_services\",\n \"parsed_description\": {\n \"main\": \"Lists all registered MCP services in the gateway.\",\n \"args\": \"None\",\n \"returns\": \"A dictionary containing services list and total_count\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {},\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"remove_service\",\n \"parsed_description\": {\n \"main\": \"Removes a registered MCP server from the gateway.\",\n \"args\": \"service_path: The unique path identifier for the service to remove\",\n \"returns\": \"Dict[str, Any]: Response from the registry API indicating success or failure of the removal.\",\n \"raises\": \"Exception: If the API call fails or the server is not found.\"\n },\n \"schema\": {\n \"properties\": {\n \"service_path\": {\n \"description\": \"The unique path identifier for the service to remove (e.g., '/fininfo'). Must start with '/'.\",\n \"title\": \"Service Path\",\n \"type\": \"string\"\n }\n },\n \"required\": [\"service_path\"],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"refresh_service\",\n \"parsed_description\": {\n \"main\": \"Triggers a refresh of the tool list for a specific registered MCP server. The registry will re-connect to the target server to get its latest tools.\",\n \"args\": \"service_path: The unique path identifier for the service\",\n \"returns\": \"Dict[str, Any]: Response from the registry API indicating the result of the refresh attempt.\",\n \"raises\": \"Exception: If the API call fails.\"\n },\n \"schema\": {\n \"properties\": {\n \"service_path\": {\n \"description\": \"The unique path identifier for the service (e.g., '/fininfo'). Must start with '/'.\",\n \"title\": \"Service Path\",\n \"type\": \"string\"\n }\n },\n \"required\": [\"service_path\"],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"healthcheck\",\n \"parsed_description\": {\n \"main\": \"Retrieves health status information from all registered MCP servers via the registry's WebSocket endpoint.\",\n \"args\": \"None\",\n \"returns\": \"Dict[str, Any]: Health status information for all registered servers\",\n \"raises\": \"Exception: If the WebSocket connection fails or the data cannot be retrieved.\"\n },\n \"schema\": {\n \"properties\": {},\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"intelligent_tool_finder\",\n \"parsed_description\": {\n \"main\": \"Finds the most relevant MCP tool(s) across all registered and enabled services based on a natural language query and/or tag filtering. IMPORTANT FOR AI AGENTS: Only use the 'tags' parameter if the user explicitly provides specific tags. DO NOT infer or guess tags from the query - incorrect tags will exclude valid results. When tags are provided with a query, results must match BOTH. If unsure about tags, use natural_language_query alone for best results.\",\n \"args\": \"natural_language_query: Optional - Your query in natural language (recommended for AI agents unless user specifies tags). tags: Optional - List of tags to filter by using AND logic (CAUTION: Only use if explicitly provided by user). top_k_services: Number of top services from FAISS search (default: 3, ignored for tags-only). top_n_tools: Number of best tools to return (default: 1).\",\n \"returns\": \"List[Dict[str, Any]]: A list of dictionaries, each describing a recommended tool, its parent service, and similarity score (if semantic search used).\",\n \"raises\": \"Exception: If neither query nor tags is provided, or if FAISS index/model is unavailable.\"\n },\n \"schema\": {\n \"properties\": {\n \"natural_language_query\": {\n \"anyOf\": [\n {\"type\": \"string\"},\n {\"type\": \"null\"}\n ],\n \"default\": null,\n \"description\": \"Your query in natural language describing the task you want to perform. Optional if tags are provided.\",\n \"title\": \"Natural Language Query\"\n },\n \"tags\": {\n \"anyOf\": [\n {\n \"items\": {\"type\": \"string\"},\n \"type\": \"array\"\n },\n {\"type\": \"null\"}\n ],\n \"default\": null,\n \"description\": \"List of tags to filter tools by using AND logic. IMPORTANT: AI agents should ONLY use this if the user explicitly provides specific tags. DO NOT infer tags - incorrect tags will exclude valid results.\",\n \"title\": \"Tags\"\n },\n \"top_k_services\": {\n \"default\": 3,\n \"description\": \"Number of top services to consider from initial FAISS search (ignored if only tags provided).\",\n \"title\": \"Top K Services\",\n \"type\": \"integer\"\n },\n \"top_n_tools\": {\n \"default\": 1,\n \"description\": \"Number of best matching tools to return.\",\n \"title\": \"Top N Tools\",\n \"type\": \"integer\"\n }\n },\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"add_server_to_scopes_groups\",\n \"parsed_description\": {\n \"main\": \"Add a server and all its known tools/methods to specific scopes groups.\",\n \"args\": \"server_name: Name of the server (without leading slash), group_names: List of group names to add the server to\",\n \"returns\": \"Dict with success status and details about the operation\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"server_name\": {\n \"description\": \"Name of the server to add to groups (e.g., 'example-server'). Should not include leading slash.\",\n \"title\": \"Server Name\",\n \"type\": \"string\"\n },\n \"group_names\": {\n \"description\": \"List of scopes group names to add the server to (e.g., ['mcp-servers-restricted/read', 'mcp-servers-restricted/execute']).\",\n \"items\": {\"type\": \"string\"},\n \"title\": \"Group Names\",\n \"type\": \"array\"\n }\n },\n \"required\": [\"server_name\", \"group_names\"],\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"remove_server_from_scopes_groups\",\n \"parsed_description\": {\n \"main\": \"Remove a server from specific scopes groups.\",\n \"args\": \"server_name: Name of the server (without leading slash), group_names: List of group names to remove the server from\",\n \"returns\": \"Dict with success status and details about the operation\",\n \"raises\": null\n },\n \"schema\": {\n \"properties\": {\n \"server_name\": {\n \"description\": \"Name of the server to remove from groups (e.g., 'example-server'). Should not include leading slash.\",\n \"title\": \"Server Name\",\n \"type\": \"string\"\n },\n \"group_names\": {\n \"description\": \"List of scopes group names to remove the server from (e.g., ['mcp-servers-restricted/read', 'mcp-servers-restricted/execute']).\",\n \"items\": {\"type\": \"string\"},\n \"title\": \"Group Names\",\n \"type\": \"array\"\n }\n },\n \"required\": [\"server_name\", \"group_names\"],\n \"type\": \"object\"\n }\n }\n ]\n}" }, { "path": "registry/servers/realserverfaketools.json", "content": "{\n \"server_name\": \"Real Server Fake Tools\",\n \"description\": \"A collection of fake tools with interesting names that take different parameter types\",\n \"path\": \"/realserverfaketools/\",\n \"proxy_pass_url\": \"http://realserverfaketools-server:8002/\", \n \"supported_transports\": [\"streamable-http\"],\n \"auth_scheme\": \"none\",\n \"tags\": [\"demo\", \"fake\", \"tools\", \"testing\"],\n \"num_tools\": 6,\n \"license\": \"MIT\",\n \"tool_list\": [\n {\n \"name\": \"quantum_flux_analyzer\",\n \"parsed_description\": {\n \"main\": \"Analyzes quantum flux patterns with configurable energy levels and stabilization.\",\n \"args\": \"energy_level: Energy level for quantum analysis (1-10), stabilization_factor: Stabilization factor for quantum flux, enable_temporal_shift: Whether to enable temporal shifting in the analysis\",\n \"returns\": \"str: JSON response with mock quantum flux analysis results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"energy_level\": {\n \"default\": 5,\n \"description\": \"Energy level for quantum analysis (1-10)\",\n \"maximum\": 10,\n \"minimum\": 1,\n \"title\": \"Energy Level\",\n \"type\": \"integer\"\n },\n \"stabilization_factor\": {\n \"default\": 0.75,\n \"description\": \"Stabilization factor for quantum flux\",\n \"title\": \"Stabilization Factor\",\n \"type\": \"number\"\n },\n \"enable_temporal_shift\": {\n \"default\": false,\n \"description\": \"Whether to enable temporal shifting in the analysis\",\n \"title\": \"Enable Temporal Shift\",\n \"type\": \"boolean\"\n }\n },\n \"title\": \"quantum_flux_analyzerArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"neural_pattern_synthesizer\",\n \"parsed_description\": {\n \"main\": \"Synthesizes neural patterns into coherent structures.\",\n \"args\": \"input_patterns: List of neural patterns to synthesize, coherence_threshold: Threshold for pattern coherence (0.0-1.0), dimensions: Number of dimensions for synthesis (1-10)\",\n \"returns\": \"Dict[str, Any]: Dictionary with mock neural pattern synthesis results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"input_patterns\": {\n \"description\": \"List of neural patterns to synthesize\",\n \"items\": {\n \"type\": \"string\"\n },\n \"title\": \"Input Patterns\",\n \"type\": \"array\"\n },\n \"coherence_threshold\": {\n \"default\": 0.7,\n \"description\": \"Threshold for pattern coherence (0.0-1.0)\",\n \"maximum\": 1.0,\n \"minimum\": 0.0,\n \"title\": \"Coherence Threshold\",\n \"type\": \"number\"\n },\n \"dimensions\": {\n \"default\": 3,\n \"description\": \"Number of dimensions for synthesis (1-10)\",\n \"maximum\": 10,\n \"minimum\": 1,\n \"title\": \"Dimensions\",\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"input_patterns\"\n ],\n \"title\": \"neural_pattern_synthesizerArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"hyper_dimensional_mapper\",\n \"parsed_description\": {\n \"main\": \"Maps geographical coordinates to hyper-dimensional space.\",\n \"args\": \"coordinates: Geographical coordinates to map, dimension_count: Number of hyper-dimensions to map to (4-11), reality_anchoring: Reality anchoring factor (0.1-1.0)\",\n \"returns\": \"str: JSON response with mock hyper-dimensional mapping results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"$defs\": {\n \"GeoCoordinates\": {\n \"properties\": {\n \"latitude\": {\n \"description\": \"Latitude coordinate\",\n \"title\": \"Latitude\",\n \"type\": \"number\"\n },\n \"longitude\": {\n \"description\": \"Longitude coordinate\",\n \"title\": \"Longitude\",\n \"type\": \"number\"\n },\n \"altitude\": {\n \"description\": \"Altitude in meters (optional)\",\n \"title\": \"Altitude\",\n \"type\": [\"number\", \"null\"]\n }\n },\n \"required\": [\n \"latitude\",\n \"longitude\"\n ],\n \"title\": \"GeoCoordinates\",\n \"type\": \"object\"\n }\n },\n \"properties\": {\n \"coordinates\": {\n \"$ref\": \"#/$defs/GeoCoordinates\",\n \"description\": \"Geographical coordinates to map to hyper-dimensions\"\n },\n \"dimension_count\": {\n \"default\": 5,\n \"description\": \"Number of hyper-dimensions to map to (4-11)\",\n \"maximum\": 11,\n \"minimum\": 4,\n \"title\": \"Dimension Count\",\n \"type\": \"integer\"\n },\n \"reality_anchoring\": {\n \"default\": 0.8,\n \"description\": \"Reality anchoring factor (0.1-1.0)\",\n \"maximum\": 1.0,\n \"minimum\": 0.1,\n \"title\": \"Reality Anchoring\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"coordinates\"\n ],\n \"title\": \"hyper_dimensional_mapperArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"temporal_anomaly_detector\",\n \"parsed_description\": {\n \"main\": \"Detects temporal anomalies within a specified timeframe.\",\n \"args\": \"timeframe: Dictionary with 'start' and 'end' times for anomaly detection, sensitivity: Sensitivity level for detection (1-10), anomaly_types: Types of anomalies to detect\",\n \"returns\": \"Dict[str, Any]: Dictionary with mock temporal anomaly detection results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"timeframe\": {\n \"description\": \"Start and end times for anomaly detection\",\n \"properties\": {\n \"start\": {\n \"type\": \"string\"\n },\n \"end\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\"start\", \"end\"],\n \"title\": \"Timeframe\",\n \"type\": \"object\"\n },\n \"sensitivity\": {\n \"default\": 7,\n \"description\": \"Sensitivity level for detection (1-10)\",\n \"maximum\": 10,\n \"minimum\": 1,\n \"title\": \"Sensitivity\",\n \"type\": \"integer\"\n },\n \"anomaly_types\": {\n \"default\": [\"temporal_shift\", \"causal_loop\", \"timeline_divergence\"],\n \"description\": \"Types of anomalies to detect\",\n \"items\": {\n \"type\": \"string\"\n },\n \"title\": \"Anomaly Types\",\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"timeframe\"\n ],\n \"title\": \"temporal_anomaly_detectorArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"user_profile_analyzer\",\n \"parsed_description\": {\n \"main\": \"Analyzes a user profile with configurable analysis options.\",\n \"args\": \"profile: User profile to analyze, analysis_options: Options for the analysis\",\n \"returns\": \"str: JSON response with mock user profile analysis results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"$defs\": {\n \"UserProfile\": {\n \"properties\": {\n \"username\": {\n \"description\": \"User's username\",\n \"title\": \"Username\",\n \"type\": \"string\"\n },\n \"email\": {\n \"description\": \"User's email address\",\n \"title\": \"Email\",\n \"type\": \"string\"\n },\n \"age\": {\n \"description\": \"User's age (optional)\",\n \"title\": \"Age\",\n \"type\": [\"integer\", \"null\"]\n },\n \"interests\": {\n \"default\": [],\n \"description\": \"List of user interests\",\n \"items\": {\n \"type\": \"string\"\n },\n \"title\": \"Interests\",\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"username\",\n \"email\"\n ],\n \"title\": \"UserProfile\",\n \"type\": \"object\"\n },\n \"AnalysisOptions\": {\n \"properties\": {\n \"depth\": {\n \"default\": 3,\n \"description\": \"Depth of analysis (1-10)\",\n \"title\": \"Depth\",\n \"type\": \"integer\"\n },\n \"include_metadata\": {\n \"default\": true,\n \"description\": \"Whether to include metadata\",\n \"title\": \"Include Metadata\",\n \"type\": \"boolean\"\n },\n \"filters\": {\n \"default\": {},\n \"description\": \"Filters to apply\",\n \"title\": \"Filters\",\n \"type\": \"object\"\n }\n },\n \"title\": \"AnalysisOptions\",\n \"type\": \"object\"\n }\n },\n \"properties\": {\n \"profile\": {\n \"$ref\": \"#/$defs/UserProfile\",\n \"description\": \"User profile to analyze\"\n },\n \"analysis_options\": {\n \"$ref\": \"#/$defs/AnalysisOptions\",\n \"default\": {},\n \"description\": \"Options for the analysis\"\n }\n },\n \"required\": [\n \"profile\"\n ],\n \"title\": \"user_profile_analyzerArguments\",\n \"type\": \"object\"\n }\n },\n {\n \"name\": \"synthetic_data_generator\",\n \"parsed_description\": {\n \"main\": \"Generates synthetic data based on a provided schema.\",\n \"args\": \"schema: Schema defining the structure of synthetic data, record_count: Number of synthetic records to generate (1-1000), seed: Random seed for reproducibility (optional)\",\n \"returns\": \"Dict[str, Any]: Dictionary with mock synthetic data generation results\",\n \"raises\": \"\"\n },\n \"schema\": {\n \"properties\": {\n \"schema\": {\n \"description\": \"Schema defining the structure of synthetic data\",\n \"title\": \"Schema\",\n \"type\": \"object\"\n },\n \"record_count\": {\n \"default\": 10,\n \"description\": \"Number of synthetic records to generate (1-1000)\",\n \"maximum\": 1000,\n \"minimum\": 1,\n \"title\": \"Record Count\",\n \"type\": \"integer\"\n },\n \"seed\": {\n \"description\": \"Random seed for reproducibility (optional)\",\n \"title\": \"Seed\",\n \"type\": [\"integer\", \"null\"]\n }\n },\n \"required\": [\n \"schema\"\n ],\n \"title\": \"synthetic_data_generatorArguments\",\n \"type\": \"object\"\n }\n }\n ]\n}" }, { "path": "registry/servers/server_state.json", "content": "{\n \"/sre-gateway/\": false,\n \"/atlassian\": false,\n \"/realserverfaketools/\": false,\n \"/mcpgw/\": false,\n \"/fininfo\": false,\n \"/currenttime/\": false\n}" }, { "path": "registry/servers/sre-gateway.json", "content": "{\n \"server_name\": \"SRE Gateway (Bedrock AgentCore Gateway)\",\n \"description\": \"Tools for an SRE Agent.\",\n \"path\": \"/sre-gateway/\",\n \"proxy_pass_url\": \"https://sre-gateway-i7ge1zayhw.gateway.bedrock-agentcore.us-east-1.amazonaws.com/\",\n \"auth_provider\": \"bedrock-agentcore\",\n \"auth_scheme\": \"bearer\",\n \"supported_transports\": [\n \"streamable-http\"\n ],\n \"tags\": [\n \"sre\",\n \"gateway\",\n \"agentcore\"\n ],\n \"headers\": [\n {\n \"Authorization\": \"Bearer $SRE_GATEWAY_AUTH_TOKEN\"\n }\n ],\n \"num_tools\": 21,\n \"license\": \"MIT-0\",\n \"tool_list\": [\n {\n \"name\": \"x_amz_bedrock_agentcore_search\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"query\"\n ]\n }\n },\n {\n \"name\": \"k8s-api___get_cluster_events\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"severity\": {\n \"description\": \"Filter by event severity\",\n \"type\": \"string\",\n \"enum\": [\n \"Warning\",\n \"Error\",\n \"Normal\"\n ]\n },\n \"since\": {\n \"format\": \"date-time\",\n \"description\": \"Filter events since this timestamp\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"k8s-api___get_deployment_status\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"deployment_name\": {\n \"description\": \"Specific deployment name\",\n \"type\": \"string\"\n },\n \"namespace\": {\n \"description\": \"Kubernetes namespace\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"k8s-api___get_node_status\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"node_name\": {\n \"description\": \"Specific node name\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"k8s-api___get_pod_status\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"namespace\": {\n \"description\": \"Kubernetes namespace to filter pods\",\n \"type\": \"string\"\n },\n \"pod_name\": {\n \"description\": \"Specific pod name to retrieve\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"k8s-api___get_resource_usage\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"namespace\": {\n \"description\": \"Filter by namespace\",\n \"type\": \"string\"\n },\n \"resource_type\": {\n \"description\": \"Type of resource to monitor\",\n \"type\": \"string\",\n \"enum\": [\n \"cpu\",\n \"memory\",\n \"pods\"\n ]\n }\n }\n }\n },\n {\n \"name\": \"logs-api___analyze_log_patterns\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"time_window\": {\n \"description\": \"Time window for pattern analysis\",\n \"type\": \"string\",\n \"enum\": [\n \"1h\",\n \"6h\",\n \"24h\",\n \"7d\"\n ]\n },\n \"min_occurrences\": {\n \"description\": \"Minimum occurrences to be considered a pattern\",\n \"type\": \"integer\"\n }\n }\n }\n },\n {\n \"name\": \"logs-api___count_log_events\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"event_type\": {\n \"description\": \"Type of event to count\",\n \"type\": \"string\"\n },\n \"time_window\": {\n \"description\": \"Time window for counting\",\n \"type\": \"string\",\n \"enum\": [\n \"1h\",\n \"6h\",\n \"24h\",\n \"7d\"\n ]\n },\n \"group_by\": {\n \"description\": \"Group results by this field\",\n \"type\": \"string\",\n \"enum\": [\n \"service\",\n \"level\",\n \"hour\"\n ]\n }\n },\n \"required\": [\n \"event_type\"\n ]\n }\n },\n {\n \"name\": \"logs-api___get_error_logs\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"service\": {\n \"description\": \"Filter by service name\",\n \"type\": \"string\"\n },\n \"since\": {\n \"format\": \"date-time\",\n \"description\": \"Get errors since this timestamp\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"logs-api___get_recent_logs\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"service\": {\n \"description\": \"Filter by service name\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"description\": \"Number of recent logs to return\",\n \"type\": \"integer\"\n }\n }\n }\n },\n {\n \"name\": \"logs-api___search_logs\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"start_time\": {\n \"format\": \"date-time\",\n \"description\": \"Start time for log search\",\n \"type\": \"string\"\n },\n \"pattern\": {\n \"description\": \"Search pattern or keyword\",\n \"type\": \"string\"\n },\n \"end_time\": {\n \"format\": \"date-time\",\n \"description\": \"End time for log search\",\n \"type\": \"string\"\n },\n \"log_level\": {\n \"description\": \"Filter by log level\",\n \"type\": \"string\",\n \"enum\": [\n \"ERROR\",\n \"WARN\",\n \"INFO\",\n \"DEBUG\"\n ]\n }\n },\n \"required\": [\n \"pattern\"\n ]\n }\n },\n {\n \"name\": \"metrics-api___analyze_trends\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"anomaly_threshold\": {\n \"description\": \"Percentile threshold for anomaly detection\",\n \"type\": \"number\"\n },\n \"metric_name\": {\n \"description\": \"Name of the metric to analyze\",\n \"type\": \"string\"\n },\n \"time_window\": {\n \"description\": \"Time window for trend analysis\",\n \"type\": \"string\",\n \"enum\": [\n \"1h\",\n \"6h\",\n \"24h\",\n \"7d\"\n ]\n },\n \"service\": {\n \"description\": \"Filter by service name\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"metric_name\"\n ]\n }\n },\n {\n \"name\": \"metrics-api___get_availability_metrics\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"time_window\": {\n \"description\": \"Time window for availability calculation\",\n \"type\": \"string\",\n \"enum\": [\n \"1h\",\n \"6h\",\n \"24h\",\n \"7d\",\n \"30d\"\n ]\n },\n \"service\": {\n \"description\": \"Service name\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"metrics-api___get_error_rates\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"time_window\": {\n \"description\": \"Time window for error rates\",\n \"type\": \"string\",\n \"enum\": [\n \"1h\",\n \"6h\",\n \"24h\",\n \"7d\"\n ]\n },\n \"service\": {\n \"description\": \"Filter by service name\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"metrics-api___get_performance_metrics\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"start_time\": {\n \"format\": \"date-time\",\n \"description\": \"Start time for metrics\",\n \"type\": \"string\"\n },\n \"service\": {\n \"description\": \"Filter by service name\",\n \"type\": \"string\"\n },\n \"metric_type\": {\n \"description\": \"Type of performance metric\",\n \"type\": \"string\",\n \"enum\": [\n \"response_time\",\n \"throughput\",\n \"cpu_usage\",\n \"memory_usage\"\n ]\n },\n \"end_time\": {\n \"format\": \"date-time\",\n \"description\": \"End time for metrics\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"metrics-api___get_resource_metrics\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"time_window\": {\n \"description\": \"Time window for metrics\",\n \"type\": \"string\",\n \"enum\": [\n \"1h\",\n \"6h\",\n \"24h\",\n \"7d\"\n ]\n },\n \"service\": {\n \"description\": \"Filter by service name\",\n \"type\": \"string\"\n },\n \"resource_type\": {\n \"description\": \"Type of resource metric\",\n \"type\": \"string\",\n \"enum\": [\n \"cpu\",\n \"memory\",\n \"disk\",\n \"network\"\n ]\n }\n }\n }\n },\n {\n \"name\": \"runbooks-api___get_common_resolutions\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"issue\": {\n \"description\": \"Issue or error type\",\n \"type\": \"string\"\n },\n \"service\": {\n \"description\": \"Affected service\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"issue\"\n ]\n }\n },\n {\n \"name\": \"runbooks-api___get_escalation_procedures\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"severity\": {\n \"description\": \"Incident severity\",\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\",\n \"critical\"\n ]\n },\n \"incident_type\": {\n \"description\": \"Type of incident\",\n \"type\": \"string\"\n }\n }\n }\n },\n {\n \"name\": \"runbooks-api___get_incident_playbook\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"playbook_id\": {\n \"description\": \"Unique identifier of the playbook\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"playbook_id\"\n ]\n }\n },\n {\n \"name\": \"runbooks-api___get_troubleshooting_guide\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"issue_type\": {\n \"description\": \"Specific issue type\",\n \"type\": \"string\"\n },\n \"category\": {\n \"description\": \"Troubleshooting category\",\n \"type\": \"string\",\n \"enum\": [\n \"kubernetes\",\n \"performance\",\n \"networking\",\n \"database\"\n ]\n }\n }\n }\n },\n {\n \"name\": \"runbooks-api___search_runbooks\",\n \"parsed_description\": {\n \"main\": \"No description available.\",\n \"args\": null,\n \"returns\": null,\n \"raises\": null\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"severity\": {\n \"description\": \"Incident severity level\",\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\",\n \"critical\"\n ]\n },\n \"incident_type\": {\n \"description\": \"Type of incident\",\n \"type\": \"string\",\n \"enum\": [\n \"performance\",\n \"availability\",\n \"security\",\n \"deployment\"\n ]\n },\n \"keyword\": {\n \"description\": \"Search keyword in runbook content\",\n \"type\": \"string\"\n }\n }\n }\n }\n ]\n}" }, { "path": "registry/services/__init__.py", "content": "" }, { "path": "registry/services/agent_scanner.py", "content": "\"\"\"\nAgent Scanner Service\n\nThis service provides security scanning functionality for A2A agents during registration.\nIt wraps the CLI A2A scanner and makes it available to API endpoints with proper\nconfiguration and error handling.\n\"\"\"\n\nimport asyncio\nimport json\nimport logging\nimport os\nimport re\nimport subprocess # nosec B404\nimport tempfile\nfrom datetime import UTC, datetime\nfrom pathlib import Path\n\nfrom ..core.config import settings\nfrom ..repositories.factory import get_security_scan_repository\nfrom ..schemas.agent_security import AgentSecurityScanConfig, AgentSecurityScanResult\n\nlogger = logging.getLogger(__name__)\n\n# Constants\nPROJECT_ROOT = Path(__file__).parent.parent.parent\nOUTPUT_DIR = PROJECT_ROOT / \"agent_security_scans\"\n\n\nclass AgentScannerService:\n \"\"\"Service for scanning A2A agents for security vulnerabilities.\"\"\"\n\n def __init__(self):\n \"\"\"Initialize the agent scanner service.\"\"\"\n self._ensure_output_directory()\n self._scan_repo = get_security_scan_repository()\n\n def _ensure_output_directory(self) -> Path:\n \"\"\"Ensure output directory exists.\"\"\"\n OUTPUT_DIR.mkdir(parents=True, exist_ok=True)\n return OUTPUT_DIR\n\n def get_scan_config(self) -> AgentSecurityScanConfig:\n \"\"\"Get agent security scan configuration from settings.\"\"\"\n return AgentSecurityScanConfig(\n enabled=settings.agent_security_scan_enabled,\n scan_on_registration=settings.agent_security_scan_on_registration,\n block_unsafe_agents=settings.agent_security_block_unsafe_agents,\n analyzers=settings.agent_security_analyzers,\n scan_timeout_seconds=settings.agent_security_scan_timeout,\n llm_api_key=settings.a2a_scanner_llm_api_key or os.getenv(\"A2A_SCANNER_LLM_API_KEY\"),\n add_security_pending_tag=settings.agent_security_add_pending_tag,\n )\n\n async def scan_agent(\n self,\n agent_card: dict,\n agent_path: str,\n analyzers: str | None = None,\n api_key: str | None = None,\n timeout: int | None = None,\n ) -> AgentSecurityScanResult:\n \"\"\"\n Scan an A2A agent for security vulnerabilities.\n\n Args:\n agent_card: Agent card dictionary to scan\n agent_path: Path identifier for the agent (e.g., /code-reviewer)\n analyzers: Comma-separated list of analyzers to use (overrides config)\n api_key: Azure OpenAI API key for LLM-based analysis (overrides config)\n timeout: Scan timeout in seconds (overrides config)\n\n Returns:\n AgentSecurityScanResult containing scan results\n\n Raises:\n Exception: If scan completely fails\n \"\"\"\n config = self.get_scan_config()\n\n # Use config values if not provided\n if analyzers is None:\n analyzers = config.analyzers\n if api_key is None:\n api_key = config.llm_api_key\n if timeout is None:\n timeout = config.scan_timeout_seconds\n\n logger.info(f\"Starting agent security scan for {agent_path} with analyzers: {analyzers}\")\n\n try:\n # Run the scan in a thread pool to avoid blocking\n raw_output = await asyncio.to_thread(\n self._run_a2a_scanner,\n agent_card=agent_card,\n agent_path=agent_path,\n analyzers=analyzers,\n api_key=api_key,\n timeout=timeout,\n )\n\n # Analyze results\n is_safe, critical, high, medium, low = self._analyze_scan_results(raw_output)\n\n # Get agent URL if available\n agent_url = agent_card.get(\"url\")\n\n # Create result object\n result = AgentSecurityScanResult(\n agent_path=agent_path,\n agent_url=str(agent_url) if agent_url else None,\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=is_safe,\n critical_issues=critical,\n high_severity=high,\n medium_severity=medium,\n low_severity=low,\n analyzers_used=analyzers.split(\",\"),\n raw_output=raw_output,\n output_file=\"\", # Repository handles storage\n scan_failed=False,\n )\n\n # Save scan result via repository\n await self._scan_repo.create(result.model_dump())\n\n logger.info(\n f\"Agent security scan completed for {agent_path}. \"\n f\"Safe: {is_safe}, Critical: {critical}, High: {high}, Medium: {medium}, Low: {low}\"\n )\n\n return result\n\n except Exception as e:\n logger.error(f\"Agent security scan failed for {agent_path}: {e}\")\n\n # Create error output\n raw_output = {\n \"error\": str(e),\n \"analysis_results\": {},\n \"scan_failed\": True,\n }\n\n # Return error result\n result = AgentSecurityScanResult(\n agent_path=agent_path,\n agent_url=agent_card.get(\"url\"),\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=False, # Treat scanner failures as unsafe\n critical_issues=0,\n high_severity=0,\n medium_severity=0,\n low_severity=0,\n analyzers_used=analyzers.split(\",\") if analyzers else [],\n raw_output=raw_output,\n output_file=\"\", # Repository handles storage\n scan_failed=True,\n error_message=str(e),\n )\n\n # Save error result via repository\n await self._scan_repo.create(result.model_dump())\n\n return result\n\n def _run_a2a_scanner(\n self,\n agent_card: dict,\n agent_path: str,\n analyzers: str,\n api_key: str | None = None,\n timeout: int | None = None,\n ) -> dict:\n \"\"\"\n Run a2a-scanner command and return raw output.\n\n This is a synchronous method that runs in a thread pool.\n \"\"\"\n logger.info(f\"Running A2A security scan on: {agent_path}\")\n logger.info(f\"Using analyzers: {analyzers}\")\n\n # Create temporary file for agent card\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False) as tmp_file:\n json.dump(agent_card, tmp_file, indent=2, default=str)\n tmp_file_path = tmp_file.name\n\n try:\n # Build command\n cmd = [\n \"a2a-scanner\",\n \"scan-card\",\n tmp_file_path,\n \"--analyzers\",\n analyzers,\n \"--format\",\n \"json\",\n ]\n\n # Set environment variable for API key if provided\n env = os.environ.copy()\n if api_key:\n env[\"AZURE_OPENAI_API_KEY\"] = api_key\n\n # Run scanner with timeout\n try:\n result = subprocess.run( # nosec B603 - args are hardcoded flags and validated config values\n cmd,\n capture_output=True,\n text=True,\n check=True,\n env=env,\n timeout=timeout,\n )\n\n # Log raw output for debugging\n logger.debug(f\"Raw A2A scanner stdout:\\n{result.stdout[:500]}\")\n\n # Parse JSON output - scanner outputs JSON\n stdout = result.stdout.strip()\n\n # Remove ANSI color codes\n ansi_escape = re.compile(r\"\\x1B(?:[@-Z\\\\-_]|\\[[0-?]*[ -/]*[@-~])\")\n stdout = ansi_escape.sub(\"\", stdout)\n\n # Try to parse as JSON directly\n try:\n scan_results = json.loads(stdout)\n except json.JSONDecodeError:\n # If direct parse fails, try to find JSON in output\n json_start = -1\n for i in range(len(stdout) - 1):\n if stdout[i] == \"{\" and (i == 0 or stdout[i - 1] in \"\\n\\r\"):\n json_start = i\n break\n\n if json_start == -1:\n # Try array format\n for i in range(len(stdout) - 1):\n if stdout[i] == \"[\" and (i == 0 or stdout[i - 1] in \"\\n\\r\"):\n json_start = i\n break\n\n if json_start == -1:\n raise ValueError(\"No JSON found in A2A scanner output\")\n\n json_str = stdout[json_start:]\n scan_results = json.loads(json_str)\n\n # Wrap in expected format with analysis_results\n raw_output = {\n \"analysis_results\": {},\n \"scan_results\": scan_results,\n }\n\n # Extract findings and organize by analyzer\n if isinstance(scan_results, dict):\n findings = scan_results.get(\"findings\", [])\n # Findings is always a list from a2a-scanner\n for finding in findings:\n analyzer_name = finding.get(\"analyzer\", \"unknown\")\n if analyzer_name not in raw_output[\"analysis_results\"]:\n raw_output[\"analysis_results\"][analyzer_name] = {\"findings\": []}\n raw_output[\"analysis_results\"][analyzer_name][\"findings\"].append(finding)\n\n logger.debug(\n f\"A2A scanner output:\\n{json.dumps(raw_output, indent=2, default=str)}\"\n )\n return raw_output\n\n except subprocess.TimeoutExpired as e:\n logger.error(f\"A2A scanner command timed out after {timeout} seconds\")\n raise RuntimeError(f\"Agent security scan timed out after {timeout} seconds\") from e\n except subprocess.CalledProcessError as e:\n logger.error(f\"A2A scanner command failed with exit code {e.returncode}\")\n logger.error(f\"stderr: {e.stderr}\")\n raise RuntimeError(f\"Agent security scanner failed: {e.stderr}\") from e\n\n finally:\n # Clean up temporary file\n try:\n os.unlink(tmp_file_path)\n except Exception as e:\n logger.warning(f\"Failed to delete temporary agent card file: {e}\")\n\n def _analyze_scan_results(self, raw_output: dict) -> tuple[bool, int, int, int, int]:\n \"\"\"\n Analyze scan results and extract severity counts.\n\n Returns:\n Tuple of (is_safe, critical_count, high_count, medium_count, low_count)\n \"\"\"\n critical_count = 0\n high_count = 0\n medium_count = 0\n low_count = 0\n\n # Navigate the raw output structure to find findings\n analysis_results = raw_output.get(\"analysis_results\", {})\n\n for _analyzer_name, analyzer_data in analysis_results.items():\n if isinstance(analyzer_data, dict):\n findings = analyzer_data.get(\"findings\", [])\n for finding in findings:\n severity = finding.get(\"severity\", \"\").lower()\n if severity == \"critical\":\n critical_count += 1\n elif severity == \"high\":\n high_count += 1\n elif severity == \"medium\":\n medium_count += 1\n elif severity == \"low\":\n low_count += 1\n\n # Determine if safe: no critical or high severity issues\n is_safe = critical_count == 0 and high_count == 0\n\n logger.info(\"Agent security analysis results:\")\n logger.info(f\" Critical Issues: {critical_count}\")\n logger.info(f\" High Severity: {high_count}\")\n logger.info(f\" Medium Severity: {medium_count}\")\n logger.info(f\" Low Severity: {low_count}\")\n logger.info(f\" Overall Assessment: {'SAFE' if is_safe else 'UNSAFE'}\")\n\n return is_safe, critical_count, high_count, medium_count, low_count\n\n async def get_scan_result(self, agent_path: str) -> dict | None:\n \"\"\"\n Get the latest scan result for an agent.\n\n Args:\n agent_path: Agent path (e.g., /code-reviewer)\n\n Returns:\n Dictionary containing scan results, or None if no scan found\n \"\"\"\n try:\n # Get latest scan from repository\n scan_result = await self._scan_repo.get_latest(agent_path)\n\n if scan_result:\n logger.info(f\"Loaded agent scan results for {agent_path} from repository\")\n # Convert to dict if needed\n if hasattr(scan_result, \"model_dump\"):\n return scan_result.model_dump()\n return scan_result\n\n logger.warning(f\"No scan results found for agent: {agent_path}\")\n return None\n\n except Exception as e:\n logger.exception(f\"Unexpected error loading agent scan results for {agent_path}\")\n return None\n\n\n# Global singleton instance\nagent_scanner_service = AgentScannerService()\n" }, { "path": "registry/services/agent_service.py", "content": "\"\"\"\nService for managing A2A agent registration and state.\n\nThis module provides CRUD operations for agent cards following the A2A protocol,\nusing repository pattern for storage abstraction.\n\nBased on: registry/services/server_service.py\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nfrom ..repositories.factory import get_agent_repository, get_search_repository\nfrom ..repositories.interfaces import AgentRepositoryBase, SearchRepositoryBase\nfrom ..schemas.agent_models import AgentCard\n\nlogger = logging.getLogger(__name__)\n\n\nclass AgentService:\n \"\"\"Service for managing A2A agent registration and state.\"\"\"\n\n def __init__(self):\n \"\"\"Initialize agent service with repository.\"\"\"\n self._repo: AgentRepositoryBase = get_agent_repository()\n self._search_repo: SearchRepositoryBase = get_search_repository()\n\n async def load_agents_and_state(self) -> None:\n \"\"\"Load agent cards from the repository.\"\"\"\n logger.info(\"Loading agent cards from repository...\")\n await self._repo.load_all()\n count = await self._repo.count()\n logger.info(f\"Repository reports {count} agents loaded\")\n\n async def register_agent(\n self,\n agent_card: AgentCard,\n ) -> AgentCard:\n \"\"\"\n Register a new agent.\n\n Args:\n agent_card: Agent card to register\n\n Returns:\n Registered agent card\n\n Raises:\n ValueError: If agent path already exists\n \"\"\"\n path = agent_card.path\n\n if await self._repo.get(path) is not None:\n logger.error(f\"Agent registration failed: path '{path}' already exists\")\n raise ValueError(f\"Agent path '{path}' already exists\")\n\n agent_card = await self._repo.create(agent_card)\n await self._repo.set_state(path, False)\n\n try:\n is_enabled = await self.is_agent_enabled(path)\n await self._search_repo.index_agent(path, agent_card, is_enabled)\n except Exception as e:\n logger.error(f\"Failed to index agent {path}: {e}\")\n\n logger.info(\n f\"New agent registered: '{agent_card.name}' at path '{path}' (disabled by default)\"\n )\n\n return agent_card\n\n async def get_agent(\n self,\n path: str,\n ) -> AgentCard:\n \"\"\"\n Get agent card by path.\n\n Args:\n path: Agent path\n\n Returns:\n Agent card\n\n Raises:\n ValueError: If agent not found\n \"\"\"\n agent = await self._repo.get(path)\n\n if not agent:\n if path.endswith(\"/\"):\n alternate_path = path.rstrip(\"/\")\n else:\n alternate_path = path + \"/\"\n agent = await self._repo.get(alternate_path)\n\n if not agent:\n raise ValueError(f\"Agent not found at path: {path}\")\n\n return agent\n\n async def list_agents(self) -> list[AgentCard]:\n \"\"\"\n List all registered agents.\n\n Returns:\n List of all agent cards\n \"\"\"\n return await self._repo.list_all()\n\n async def update_rating(\n self,\n path: str,\n username: str,\n rating: int,\n ) -> float:\n \"\"\"\n Log a user rating for an agent. If the user has already rated, update their rating.\n\n Args:\n path: Agent path\n username: The user who submitted rating\n rating: integer between 1-5\n\n Return:\n Updated average rating\n\n Raises:\n ValueError: If agent not found or invalid rating\n \"\"\"\n from . import rating_service\n\n existing_agent = await self._repo.get(path)\n if not existing_agent:\n logger.error(f\"Cannot update agent at path '{path}': not found\")\n raise ValueError(f\"Agent not found at path: {path}\")\n\n rating_service.validate_rating(rating)\n\n agent_dict = existing_agent.model_dump()\n\n if \"rating_details\" not in agent_dict or agent_dict[\"rating_details\"] is None:\n agent_dict[\"rating_details\"] = []\n\n updated_details, is_new_rating = rating_service.update_rating_details(\n agent_dict[\"rating_details\"], username, rating\n )\n agent_dict[\"rating_details\"] = updated_details\n\n agent_dict[\"num_stars\"] = rating_service.calculate_average_rating(\n agent_dict[\"rating_details\"]\n )\n\n await self._repo.update(path, agent_dict)\n\n logger.info(\n f\"Updated rating for agent {path}: user {username} rated {rating}, \"\n f\"new average: {agent_dict['num_stars']:.2f}\"\n )\n\n return agent_dict[\"num_stars\"]\n\n async def update_agent(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> AgentCard:\n \"\"\"\n Update an existing agent.\n\n Args:\n path: Agent path\n updates: Dictionary of fields to update\n\n Returns:\n Updated agent card\n\n Raises:\n ValueError: If agent not found\n \"\"\"\n existing_agent = await self._repo.get(path)\n if existing_agent is None:\n logger.error(f\"Cannot update agent at path '{path}': not found\")\n raise ValueError(f\"Agent not found at path: {path}\")\n\n agent_dict = existing_agent.model_dump()\n agent_dict.update(updates)\n agent_dict[\"path\"] = path\n agent_dict[\"updated_at\"] = datetime.now(UTC)\n\n try:\n AgentCard(**agent_dict)\n except Exception as e:\n logger.error(f\"Failed to validate updated agent: {e}\")\n raise ValueError(f\"Invalid agent update: {e}\")\n\n updated_agent = await self._repo.update(path, agent_dict)\n\n try:\n is_enabled = await self.is_agent_enabled(path)\n await self._search_repo.index_agent(path, updated_agent, is_enabled)\n except Exception as e:\n logger.error(f\"Failed to re-index agent {path}: {e}\")\n\n logger.info(f\"Agent '{updated_agent.name}' ({path}) updated\")\n return updated_agent\n\n async def delete_agent(\n self,\n path: str,\n ) -> bool:\n \"\"\"\n Delete an agent from registry.\n\n Args:\n path: Agent path\n\n Returns:\n True if deleted successfully\n\n Raises:\n ValueError: If agent not found\n \"\"\"\n existing_agent = await self._repo.get(path)\n if existing_agent is None:\n logger.error(f\"Cannot delete agent at path '{path}': not found\")\n raise ValueError(f\"Agent not found at path: {path}\")\n\n try:\n agent_name = existing_agent.name\n\n await self._repo.delete(path)\n\n try:\n await self._search_repo.remove_entity(path)\n except Exception as e:\n logger.error(f\"Failed to remove agent {path} from search: {e}\")\n\n logger.info(f\"Successfully deleted agent '{agent_name}' from path '{path}'\")\n return True\n\n except Exception as e:\n logger.error(f\"Failed to delete agent at path '{path}': {e}\", exc_info=True)\n raise ValueError(f\"Failed to delete agent: {e}\")\n\n async def enable_agent(\n self,\n path: str,\n ) -> None:\n \"\"\"\n Enable an agent.\n\n Args:\n path: Agent path\n\n Raises:\n ValueError: If agent not found\n \"\"\"\n agent = await self._repo.get(path)\n if agent is None:\n raise ValueError(f\"Agent not found at path: {path}\")\n\n if await self._repo.get_state(path):\n logger.info(f\"Agent '{path}' is already enabled\")\n return\n\n await self._repo.set_state(path, True)\n logger.info(f\"Enabled agent '{agent.name}' ({path})\")\n\n async def disable_agent(\n self,\n path: str,\n ) -> None:\n \"\"\"\n Disable an agent.\n\n Args:\n path: Agent path\n\n Raises:\n ValueError: If agent not found\n \"\"\"\n agent = await self._repo.get(path)\n if agent is None:\n raise ValueError(f\"Agent not found at path: {path}\")\n\n if not await self._repo.get_state(path):\n logger.info(f\"Agent '{path}' is already disabled\")\n return\n\n await self._repo.set_state(path, False)\n logger.info(f\"Disabled agent '{agent.name}' ({path})\")\n\n async def is_agent_enabled(\n self,\n path: str,\n ) -> bool:\n \"\"\"\n Check if agent is enabled.\n\n Args:\n path: Agent path\n\n Returns:\n True if enabled, False otherwise\n \"\"\"\n if await self._repo.get_state(path):\n return True\n\n if path.endswith(\"/\"):\n alternate_path = path.rstrip(\"/\")\n else:\n alternate_path = path + \"/\"\n\n return await self._repo.get_state(alternate_path)\n\n async def get_enabled_agents(self) -> list[str]:\n \"\"\"\n Get list of enabled agent paths.\n\n Returns:\n List of enabled agent paths\n \"\"\"\n all_states = await self._repo.get_all_states()\n return [path for path, enabled in all_states.items() if enabled]\n\n async def get_disabled_agents(self) -> list[str]:\n \"\"\"\n Get list of disabled agent paths.\n\n Returns:\n List of disabled agent paths\n \"\"\"\n all_states = await self._repo.get_all_states()\n return [path for path, enabled in all_states.items() if not enabled]\n\n async def get_all_agent_states(self) -> dict[str, bool]:\n \"\"\"\n Get enabled/disabled state for all agents in a single query.\n\n Returns:\n Dict mapping agent path to enabled (True) or disabled (False).\n \"\"\"\n return await self._repo.get_all_states()\n\n async def index_agent(\n self,\n agent_card: AgentCard,\n ) -> None:\n \"\"\"\n Add agent to search index.\n\n Args:\n agent_card: Agent card to index\n \"\"\"\n try:\n agent_data = agent_card.model_dump(mode=\"json\")\n is_enabled = await self.is_agent_enabled(agent_card.path)\n await self._search_repo.index_entity(\n entity_path=agent_card.path,\n entity_data=agent_data,\n entity_type=\"a2a_agent\",\n is_enabled=is_enabled,\n )\n logger.info(f\"Indexed agent '{agent_card.name}' in search\")\n except Exception as e:\n logger.error(f\"Failed to index agent: {e}\", exc_info=True)\n\n async def get_agent_info(\n self,\n path: str,\n ) -> AgentCard | None:\n \"\"\"\n Get agent by path - queries repository directly (returns None if not found).\n\n Args:\n path: Agent path\n\n Returns:\n Agent card or None if not found\n \"\"\"\n return await self._repo.get(path)\n\n async def get_all_agents(self) -> list[AgentCard]:\n \"\"\"\n Get all registered agents - queries repository directly.\n\n Returns:\n List of all agent cards\n \"\"\"\n return await self._repo.list_all()\n\n async def get_agents_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> tuple[list[AgentCard], int]:\n \"\"\"\n Get a page of agents with total count.\n\n Used for unrestricted users (admins) where DB-level pagination\n is correct because no agents are filtered out by access control.\n\n Note: list_paginated and count are separate DB calls, so total_count\n may be slightly inconsistent if agents are added/removed between calls.\n This is standard for offset-based pagination.\n\n Args:\n skip: Number of agents to skip.\n limit: Maximum number of agents to return.\n\n Returns:\n Tuple of (page of agents, total count of all agents).\n \"\"\"\n agents = await self._repo.list_paginated(skip=skip, limit=limit)\n total = await self._repo.count()\n return agents, total\n\n async def remove_agent(\n self,\n path: str,\n ) -> bool:\n \"\"\"\n Remove an agent from registry.\n\n Args:\n path: Agent path\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n await self.delete_agent(path)\n return True\n except ValueError:\n return False\n\n async def toggle_agent(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"\n Toggle agent enabled/disabled state.\n\n Args:\n path: Agent path\n enabled: New enabled state\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n if enabled:\n await self.enable_agent(path)\n else:\n await self.disable_agent(path)\n return True\n except ValueError:\n return False\n\n\n# Global service instance\nagent_service = AgentService()\n" }, { "path": "registry/services/agent_transform_service.py", "content": "\"\"\"\nService for transforming internal A2A agent data to Anthropic API schema.\n\nThis bridges our internal agent data model with the external Anthropic API format,\nfollowing the same pattern as the server transform service.\n\"\"\"\n\nimport logging\nfrom typing import Any\n\nfrom ..constants import REGISTRY_CONSTANTS\nfrom ..schemas.anthropic_schema import (\n Package,\n PaginationMetadata,\n ServerDetail,\n ServerList,\n ServerResponse,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _create_agent_transport_config(\n agent_info: dict[str, Any],\n) -> dict[str, Any]:\n \"\"\"\n Create transport configuration from internal agent info.\n\n For A2A agents, the transport URL is the agent's endpoint URL.\n\n Args:\n agent_info: Internal agent data structure\n\n Returns:\n Transport configuration dict\n \"\"\"\n agent_url = agent_info.get(\"url\", \"\")\n\n return {\"type\": \"streamable-http\", \"url\": agent_url}\n\n\ndef _determine_agent_version(agent_info: dict[str, Any]) -> str:\n \"\"\"\n Determine agent version from metadata.\n\n Uses protocol_version from agent card if available, defaults to \"1.0.0\".\n\n Args:\n agent_info: Internal agent data\n\n Returns:\n Version string\n \"\"\"\n # Check if we have protocol version from agent card\n if \"protocol_version\" in agent_info:\n return agent_info[\"protocol_version\"]\n\n # Check metadata\n if \"_meta\" in agent_info and \"version\" in agent_info[\"_meta\"]:\n return agent_info[\"_meta\"][\"version\"]\n\n # Default version for all agents\n return \"1.0.0\"\n\n\ndef _create_agent_name(agent_info: dict[str, Any]) -> str:\n \"\"\"\n Create reverse-DNS style agent name.\n\n Transforms our path-based naming (/code-reviewer) to reverse-DNS format\n (io.mcpgateway/code-reviewer).\n\n Args:\n agent_info: Internal agent data\n\n Returns:\n Reverse-DNS formatted agent name\n \"\"\"\n path = agent_info.get(\"path\", \"\")\n\n # Remove leading and trailing slashes from path\n clean_path = path.strip(\"/\")\n\n # Use our domain as prefix\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n return f\"{namespace}/{clean_path}\"\n\n\ndef transform_to_agent_detail(\n agent_info: dict[str, Any],\n) -> ServerDetail:\n \"\"\"\n Transform internal agent info to Anthropic ServerDetail format.\n\n A2A agents are exposed as ServerDetail objects in the Anthropic schema\n to maintain compatibility with the existing API structure.\n\n Maps from our internal agent schema to Anthropic schema.\n\n Args:\n agent_info: Internal agent data structure\n\n Returns:\n ServerDetail object\n \"\"\"\n # Create reverse-DNS name\n name = _create_agent_name(agent_info)\n\n # Get version\n version = _determine_agent_version(agent_info)\n\n # Create transport config\n transport = _create_agent_transport_config(agent_info)\n\n # Create package entry\n # Use \"mcpb\" as registry type for our A2A agents\n package = Package(\n registryType=\"mcpb\",\n identifier=name,\n version=version,\n transport=transport,\n runtimeHint=\"docker\",\n )\n\n # Build metadata with agent-specific info\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n meta = {\n f\"{namespace}/internal\": {\n \"path\": agent_info.get(\"path\"),\n \"type\": \"a2a-agent\",\n \"is_enabled\": agent_info.get(\"is_enabled\", True),\n \"visibility\": agent_info.get(\"visibility\", \"public\"),\n \"trust_level\": agent_info.get(\"trust_level\", \"community\"),\n \"skills\": agent_info.get(\"skills\", []),\n \"tags\": agent_info.get(\"tags\", []),\n \"protocol_version\": agent_info.get(\"protocol_version\", \"1.0\"),\n }\n }\n\n # Create ServerDetail with agent info\n return ServerDetail(\n name=name,\n description=agent_info.get(\"description\", \"\"),\n version=version,\n title=agent_info.get(\"name\"),\n repository=None, # Agents typically don't have GitHub repos\n packages=[package],\n meta=meta,\n )\n\n\ndef transform_to_agent_response(\n agent_info: dict[str, Any],\n include_registry_meta: bool = True,\n) -> ServerResponse:\n \"\"\"\n Transform internal agent info to Anthropic ServerResponse format.\n\n Args:\n agent_info: Internal agent data\n include_registry_meta: Whether to include registry metadata\n\n Returns:\n ServerResponse object\n \"\"\"\n agent_detail = transform_to_agent_detail(agent_info)\n\n registry_meta = None\n if include_registry_meta:\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n registry_meta = {\n f\"{namespace}/registry\": {\n \"last_checked\": agent_info.get(\"last_checked_iso\"),\n \"health_status\": agent_info.get(\"health_status\", \"unknown\"),\n }\n }\n\n return ServerResponse(server=agent_detail, meta=registry_meta)\n\n\ndef transform_to_agent_list(\n agents_data: list[dict[str, Any]],\n cursor: str | None = None,\n limit: int | None = None,\n) -> ServerList:\n \"\"\"\n Transform list of internal agents to Anthropic ServerList format.\n\n Implements cursor-based pagination following the same pattern as servers.\n\n Args:\n agents_data: List of internal agent data structures\n cursor: Current pagination cursor (agent name to start after)\n limit: Maximum number of results to return\n\n Returns:\n ServerList object with pagination metadata\n \"\"\"\n # Default limit\n if limit is None or limit <= 0:\n limit = 100\n\n # Enforce maximum limit\n limit = min(limit, 1000)\n\n # Sort agents by name for consistent pagination\n sorted_agents = sorted(agents_data, key=lambda a: _create_agent_name(a))\n\n # Apply cursor-based pagination\n start_index = 0\n if cursor:\n # Find the index of the agent matching the cursor\n for idx, agent in enumerate(sorted_agents):\n if _create_agent_name(agent) == cursor:\n start_index = idx + 1\n break\n\n # Slice the results\n end_index = start_index + limit\n page_agents = sorted_agents[start_index:end_index]\n\n # Transform to ServerResponse objects\n agent_responses = [\n transform_to_agent_response(agent, include_registry_meta=True) for agent in page_agents\n ]\n\n # Determine next cursor\n next_cursor = None\n if end_index < len(sorted_agents):\n # More results available\n next_cursor = _create_agent_name(sorted_agents[end_index - 1])\n\n # Build pagination metadata\n metadata = PaginationMetadata(nextCursor=next_cursor, count=len(agent_responses))\n\n return ServerList(servers=agent_responses, metadata=metadata)\n" }, { "path": "registry/services/ans_client.py", "content": "# registry/services/ans_client.py\n\nimport asyncio\nimport logging\nfrom datetime import (\n UTC,\n datetime,\n timedelta,\n)\n\nimport httpx\n\nfrom registry.core.config import settings\nfrom registry.schemas.ans_models import (\n ANSCertificateInfo,\n ANSEndpointInfo,\n ANSFunctionInfo,\n ANSMetadata,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nANS_STATUS_VERIFIED: str = \"verified\"\nANS_STATUS_EXPIRED: str = \"expired\"\nANS_STATUS_REVOKED: str = \"revoked\"\nANS_STATUS_NOT_FOUND: str = \"not_found\"\nANS_STATUS_PENDING: str = \"pending\"\nANS_STATUS_ERROR: str = \"error\"\n\nMAX_RETRIES: int = 3\nRETRY_BASE_DELAY_SECONDS: float = 1.0\nCIRCUIT_BREAKER_THRESHOLD: int = 5\nCIRCUIT_BREAKER_RESET_SECONDS: int = 3600\n\n# Circuit breaker state (module-level)\n_consecutive_failures: int = 0\n_circuit_open_until: datetime | None = None\n\n\ndef _build_auth_header() -> dict[str, str]:\n \"\"\"Build the ANS API authentication header.\"\"\"\n return {\n \"Authorization\": f\"sso-key {settings.ans_api_key}:{settings.ans_api_secret}\",\n \"Accept\": \"application/json\",\n }\n\n\ndef _check_circuit_breaker() -> bool:\n \"\"\"Check if circuit breaker is open (ANS API assumed down).\n\n Returns:\n True if requests should proceed, False if circuit is open\n \"\"\"\n global _circuit_open_until\n if _circuit_open_until is None:\n return True\n if datetime.now(UTC) > _circuit_open_until:\n _circuit_open_until = None\n logger.info(\"ANS circuit breaker reset -- resuming API calls\")\n return True\n return False\n\n\ndef _record_failure() -> None:\n \"\"\"Record an ANS API failure for circuit breaker.\"\"\"\n global _consecutive_failures, _circuit_open_until\n _consecutive_failures += 1\n if _consecutive_failures >= CIRCUIT_BREAKER_THRESHOLD:\n _circuit_open_until = datetime.now(UTC) + timedelta(seconds=CIRCUIT_BREAKER_RESET_SECONDS)\n logger.warning(\n f\"ANS circuit breaker OPEN after {_consecutive_failures} failures. \"\n f\"Pausing API calls for {CIRCUIT_BREAKER_RESET_SECONDS} seconds.\"\n )\n\n\ndef _record_success() -> None:\n \"\"\"Record an ANS API success -- reset circuit breaker.\"\"\"\n global _consecutive_failures, _circuit_open_until\n _consecutive_failures = 0\n _circuit_open_until = None\n\n\ndef _determine_status(\n ans_data: dict,\n) -> str:\n \"\"\"Determine verification status from ANS response data.\n\n Args:\n ans_data: Raw ANS API response\n\n Returns:\n Status string: verified, expired, revoked\n \"\"\"\n if ans_data.get(\"revoked\", False):\n return ANS_STATUS_REVOKED\n\n agent_status = ans_data.get(\"agentStatus\", \"\")\n if agent_status == \"REVOKED\":\n return ANS_STATUS_REVOKED\n\n cert = ans_data.get(\"certificate\", {})\n not_after = cert.get(\"not_after\") or cert.get(\"notAfter\")\n if not_after:\n try:\n expiry = datetime.fromisoformat(not_after.replace(\"Z\", \"+00:00\"))\n if expiry < datetime.now(expiry.tzinfo):\n return ANS_STATUS_EXPIRED\n except (ValueError, TypeError):\n logger.warning(f\"Could not parse certificate expiry: {not_after}\")\n\n return ANS_STATUS_VERIFIED\n\n\ndef _extract_metadata(\n ans_agent_id: str,\n ans_data: dict,\n) -> ANSMetadata:\n \"\"\"Extract ANS metadata from API response.\n\n Args:\n ans_agent_id: The ANS Agent ID that was queried\n ans_data: Raw ANS API response\n\n Returns:\n Structured ANS metadata\n \"\"\"\n now = datetime.now(UTC)\n status = _determine_status(ans_data)\n\n cert_data = ans_data.get(\"certificate\", {})\n certificate = ANSCertificateInfo(\n serial_number=cert_data.get(\"serial_number\") or cert_data.get(\"serialNumber\"),\n not_before=cert_data.get(\"not_before\") or cert_data.get(\"notBefore\"),\n not_after=cert_data.get(\"not_after\") or cert_data.get(\"notAfter\"),\n subject_dn=cert_data.get(\"subject_dn\") or cert_data.get(\"subjectDn\"),\n issuer_dn=cert_data.get(\"issuer_dn\") or cert_data.get(\"issuerDn\"),\n )\n\n endpoints = []\n for ep in ans_data.get(\"endpoints\", []):\n functions = []\n for fn in ep.get(\"functions\", []):\n if fn and fn.get(\"id\"):\n functions.append(\n ANSFunctionInfo(\n id=fn.get(\"id\", \"\"),\n name=fn.get(\"name\", \"\"),\n tags=fn.get(\"tags\"),\n )\n )\n endpoints.append(\n ANSEndpointInfo(\n type=ep.get(\"type\", \"http\"),\n url=ep.get(\"agentUrl\") or ep.get(\"url\", \"\"),\n protocol=ep.get(\"protocol\"),\n transports=ep.get(\"transports\", []),\n functions=functions,\n )\n )\n\n links = ans_data.get(\"links\", [])\n\n return ANSMetadata(\n ans_agent_id=ans_agent_id,\n linked_at=now,\n last_verified=now,\n status=status,\n domain=ans_data.get(\"agentHost\") or ans_data.get(\"domain\"),\n organization=ans_data.get(\"organization\"),\n ans_name=ans_data.get(\"ansName\") or ans_data.get(\"name\"),\n ans_display_name=ans_data.get(\"agentDisplayName\"),\n ans_description=ans_data.get(\"agentDescription\"),\n ans_version=ans_data.get(\"version\"),\n registered_with_ans_at=ans_data.get(\"registrationTimestamp\"),\n certificate=certificate,\n endpoints=endpoints,\n links=links,\n raw_ans_response=ans_data,\n )\n\n\nasync def _resolve_ans_id(\n ans_agent_id: str,\n) -> str | None:\n \"\"\"Resolve an ANS agent identifier to a UUID.\n\n If the input is already a UUID, return it as-is.\n If the input is an ans:// URI, search the ANS API to find the UUID.\n\n Args:\n ans_agent_id: ANS Agent ID (UUID or ans:// URI)\n\n Returns:\n UUID string if found, None if ans:// URI could not be resolved\n \"\"\"\n if not ans_agent_id.startswith(\"ans://\"):\n return ans_agent_id\n\n headers = _build_auth_header()\n search_url = f\"{settings.ans_api_endpoint}/v1/agents\"\n\n try:\n async with httpx.AsyncClient(timeout=settings.ans_api_timeout_seconds) as client:\n response = await client.get(\n search_url,\n headers=headers,\n params={\"limit\": 100, \"offset\": 0},\n )\n response.raise_for_status()\n data = response.json()\n\n for agent in data.get(\"agents\", []):\n if agent.get(\"ansName\") == ans_agent_id:\n agent_uuid = agent.get(\"agentId\")\n logger.info(f\"Resolved ANS name '{ans_agent_id}' to UUID '{agent_uuid}'\")\n return agent_uuid\n\n # Search remaining pages if needed\n total_count = data.get(\"totalCount\", 0)\n offset = 100\n while offset < total_count:\n response = await client.get(\n search_url,\n headers=headers,\n params={\"limit\": 100, \"offset\": offset},\n )\n response.raise_for_status()\n page_data = response.json()\n\n for agent in page_data.get(\"agents\", []):\n if agent.get(\"ansName\") == ans_agent_id:\n agent_uuid = agent.get(\"agentId\")\n logger.info(f\"Resolved ANS name '{ans_agent_id}' to UUID '{agent_uuid}'\")\n return agent_uuid\n\n offset += 100\n\n except Exception as e:\n logger.error(f\"Failed to resolve ANS name '{ans_agent_id}': {e}\")\n\n logger.warning(f\"Could not resolve ANS name to UUID: {ans_agent_id}\")\n return None\n\n\nasync def verify_ans_agent(\n ans_agent_id: str,\n) -> ANSMetadata | None:\n \"\"\"Verify an ANS Agent ID by calling the GoDaddy ANS API.\n\n Includes retry with exponential backoff and circuit breaker.\n\n Args:\n ans_agent_id: ANS Agent ID (e.g., ans://v1.0.0.myagent.example.com)\n\n Returns:\n ANSMetadata if found, None if not found\n\n Raises:\n httpx.HTTPStatusError: For non-404 HTTP errors after retries\n httpx.TimeoutException: If ANS API times out after retries\n RuntimeError: If circuit breaker is open\n \"\"\"\n if not _check_circuit_breaker():\n raise RuntimeError(\"ANS API circuit breaker is open -- API assumed unavailable\")\n\n # If ans_agent_id is an ans:// URI, resolve it to a UUID first\n resolved_id = await _resolve_ans_id(ans_agent_id)\n if resolved_id is None:\n logger.info(f\"ANS name not found in registry: {ans_agent_id}\")\n return None\n\n headers = _build_auth_header()\n url = f\"{settings.ans_api_endpoint}/v1/agents/{resolved_id}\"\n\n logger.info(f\"Verifying ANS Agent ID: {resolved_id} (input: {ans_agent_id})\")\n\n last_exception = None\n for attempt in range(MAX_RETRIES):\n try:\n async with httpx.AsyncClient(timeout=settings.ans_api_timeout_seconds) as client:\n response = await client.get(url, headers=headers)\n\n if response.status_code == 404:\n logger.info(f\"ANS Agent ID not found: {ans_agent_id}\")\n _record_success()\n return None\n\n response.raise_for_status()\n ans_data = response.json()\n\n logger.info(f\"ANS verification successful for: {ans_agent_id}\")\n _record_success()\n return _extract_metadata(ans_agent_id, ans_data)\n\n except (httpx.TimeoutException, httpx.HTTPStatusError) as e:\n last_exception = e\n if attempt < MAX_RETRIES - 1:\n delay = RETRY_BASE_DELAY_SECONDS * (2**attempt)\n logger.warning(\n f\"ANS API attempt {attempt + 1}/{MAX_RETRIES} failed for \"\n f\"{ans_agent_id}: {e}. Retrying in {delay}s...\"\n )\n await asyncio.sleep(delay)\n else:\n logger.error(f\"ANS API failed after {MAX_RETRIES} attempts for {ans_agent_id}: {e}\")\n\n _record_failure()\n raise last_exception\n" }, { "path": "registry/services/ans_service.py", "content": "# registry/services/ans_service.py\n\nimport logging\nimport time\nfrom datetime import (\n UTC,\n datetime,\n)\nfrom typing import Any\n\nimport httpx\n\nfrom registry.repositories.factory import (\n get_agent_repository,\n get_server_repository,\n)\nfrom registry.schemas.ans_models import (\n ANSIntegrationMetrics,\n ANSSyncStats,\n)\nfrom registry.services.ans_client import (\n ANS_STATUS_NOT_FOUND,\n verify_ans_agent,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n# In-memory sync history (last 20 entries)\n_sync_history: list[dict] = []\nMAX_SYNC_HISTORY: int = 20\n\n\ndef _store_sync_history(\n stats: ANSSyncStats,\n) -> None:\n \"\"\"Store sync result in history for admin visibility.\"\"\"\n global _sync_history\n _sync_history.append(\n {\n \"completed_at\": datetime.now(UTC).isoformat(),\n **stats.model_dump(),\n }\n )\n if len(_sync_history) > MAX_SYNC_HISTORY:\n _sync_history = _sync_history[-MAX_SYNC_HISTORY:]\n\n\nasync def _sync_asset_type(\n repo: Any,\n asset_type: str,\n stats: ANSSyncStats,\n) -> None:\n \"\"\"Sync ANS status for one asset type (agent or server).\n\n Args:\n repo: Repository instance (agent or server)\n asset_type: \"agent\" or \"server\" for logging\n stats: Mutable stats object to update\n \"\"\"\n if hasattr(repo, \"find_with_filter\"):\n linked_assets = await repo.find_with_filter(\n {\"ans_metadata\": {\"$exists\": True, \"$ne\": None}}\n )\n else:\n all_assets = await repo.list_all()\n linked_assets = {}\n for asset in all_assets:\n asset_dict = asset.model_dump() if hasattr(asset, \"model_dump\") else asset\n asset_path = asset_dict.get(\"path\", \"\")\n if asset_dict.get(\"ans_metadata\"):\n linked_assets[asset_path] = asset_dict\n\n for path, asset_data in linked_assets.items():\n ans_meta = asset_data.get(\"ans_metadata\", {})\n stats.total += 1\n ans_agent_id = ans_meta.get(\"ans_agent_id\", \"\")\n\n try:\n result = await verify_ans_agent(ans_agent_id)\n now = datetime.now(UTC)\n if result is None:\n await repo.update_field(path, \"ans_metadata.status\", ANS_STATUS_NOT_FOUND)\n await repo.update_field(path, \"ans_metadata.last_verified\", now.isoformat())\n else:\n metadata_dict = result.model_dump(mode=\"json\")\n metadata_dict[\"linked_at\"] = ans_meta.get(\"linked_at\")\n await repo.update_field(path, \"ans_metadata\", metadata_dict)\n stats.updated += 1\n\n except Exception as e:\n stats.errors += 1\n logger.error(f\"ANS sync error for {asset_type} {path}: {e}\")\n\n\nasync def link_ans_to_agent(\n agent_path: str,\n ans_agent_id: str,\n username: str | None = None,\n) -> dict:\n \"\"\"Link an ANS Agent ID to an AI Registry agent.\n\n Args:\n agent_path: Agent path in the registry\n ans_agent_id: ANS Agent ID to link\n username: Authenticated user's username (for ownership check)\n\n Returns:\n Dict with success, message, and ans_metadata\n \"\"\"\n repo = get_agent_repository()\n\n agent = await repo.get(agent_path)\n if not agent:\n return {\"success\": False, \"message\": f\"Agent not found: {agent_path}\"}\n\n registered_by = getattr(agent, \"registered_by\", None)\n if username and registered_by and username != registered_by:\n return {\"success\": False, \"message\": \"Not authorized: you are not the owner of this agent\"}\n\n try:\n ans_metadata = await verify_ans_agent(ans_agent_id)\n except httpx.TimeoutException:\n return {\"success\": False, \"message\": \"ANS API timed out\"}\n except httpx.HTTPStatusError as e:\n return {\"success\": False, \"message\": f\"ANS API error: {e.response.status_code}\"}\n except RuntimeError as e:\n return {\"success\": False, \"message\": str(e)}\n\n if ans_metadata is None:\n return {\"success\": False, \"message\": f\"ANS Agent ID not found: {ans_agent_id}\"}\n\n metadata_dict = ans_metadata.model_dump(mode=\"json\")\n await repo.update_field(agent_path, \"ans_metadata\", metadata_dict)\n\n logger.info(\n f\"ANS ID linked to agent {agent_path}: {ans_agent_id} (status: {ans_metadata.status})\"\n )\n return {\n \"success\": True,\n \"message\": f\"ANS Agent ID linked and verified (status: {ans_metadata.status})\",\n \"ans_metadata\": metadata_dict,\n }\n\n\nasync def link_ans_to_server(\n server_path: str,\n ans_agent_id: str,\n username: str | None = None,\n) -> dict:\n \"\"\"Link an ANS Agent ID to an MCP server.\n\n Args:\n server_path: Server path in the registry\n ans_agent_id: ANS Agent ID to link\n username: Authenticated user's username (for ownership check)\n\n Returns:\n Dict with success, message, and ans_metadata\n \"\"\"\n repo = get_server_repository()\n\n server = await repo.get(server_path)\n if not server:\n return {\"success\": False, \"message\": f\"Server not found: {server_path}\"}\n\n registered_by = getattr(server, \"registered_by\", None)\n if username and registered_by and username != registered_by:\n return {\"success\": False, \"message\": \"Not authorized: you are not the owner of this server\"}\n\n try:\n ans_metadata = await verify_ans_agent(ans_agent_id)\n except httpx.TimeoutException:\n return {\"success\": False, \"message\": \"ANS API timed out\"}\n except httpx.HTTPStatusError as e:\n return {\"success\": False, \"message\": f\"ANS API error: {e.response.status_code}\"}\n except RuntimeError as e:\n return {\"success\": False, \"message\": str(e)}\n\n if ans_metadata is None:\n return {\"success\": False, \"message\": f\"ANS Agent ID not found: {ans_agent_id}\"}\n\n metadata_dict = ans_metadata.model_dump(mode=\"json\")\n await repo.update_field(server_path, \"ans_metadata\", metadata_dict)\n\n logger.info(\n f\"ANS ID linked to server {server_path}: {ans_agent_id} (status: {ans_metadata.status})\"\n )\n return {\n \"success\": True,\n \"message\": f\"ANS Agent ID linked and verified (status: {ans_metadata.status})\",\n \"ans_metadata\": metadata_dict,\n }\n\n\nasync def unlink_ans_from_agent(\n agent_path: str,\n username: str | None = None,\n) -> dict:\n \"\"\"Remove ANS link from an agent.\n\n Args:\n agent_path: Agent path in the registry\n username: Authenticated user's username (for ownership check)\n\n Returns:\n Dict with success and message\n \"\"\"\n repo = get_agent_repository()\n agent = await repo.get(agent_path)\n if not agent:\n return {\"success\": False, \"message\": f\"Agent not found: {agent_path}\"}\n\n registered_by = getattr(agent, \"registered_by\", None)\n if username and registered_by and username != registered_by:\n return {\"success\": False, \"message\": \"Not authorized: you are not the owner of this agent\"}\n\n await repo.update_field(agent_path, \"ans_metadata\", None)\n logger.info(f\"ANS link removed from agent: {agent_path}\")\n return {\"success\": True, \"message\": \"ANS link removed\"}\n\n\nasync def unlink_ans_from_server(\n server_path: str,\n username: str | None = None,\n) -> dict:\n \"\"\"Remove ANS link from a server.\n\n Args:\n server_path: Server path in the registry\n username: Authenticated user's username (for ownership check)\n\n Returns:\n Dict with success and message\n \"\"\"\n repo = get_server_repository()\n server = await repo.get(server_path)\n if not server:\n return {\"success\": False, \"message\": f\"Server not found: {server_path}\"}\n\n registered_by = getattr(server, \"registered_by\", None)\n if username and registered_by and username != registered_by:\n return {\"success\": False, \"message\": \"Not authorized: you are not the owner of this server\"}\n\n await repo.update_field(server_path, \"ans_metadata\", None)\n logger.info(f\"ANS link removed from server: {server_path}\")\n return {\"success\": True, \"message\": \"ANS link removed\"}\n\n\nasync def sync_all_ans_status() -> ANSSyncStats:\n \"\"\"Sync ANS verification status for all linked assets.\n\n Returns:\n Sync statistics\n \"\"\"\n start_time = time.time()\n stats = ANSSyncStats()\n\n agent_repo = get_agent_repository()\n server_repo = get_server_repository()\n\n await _sync_asset_type(agent_repo, \"agent\", stats)\n await _sync_asset_type(server_repo, \"server\", stats)\n\n elapsed = time.time() - start_time\n stats.duration_seconds = round(elapsed, 2)\n\n minutes = int(elapsed // 60)\n seconds = elapsed % 60\n if minutes > 0:\n logger.info(\n f\"ANS sync completed in {minutes} minutes and {seconds:.1f} seconds: {stats.model_dump()}\"\n )\n else:\n logger.info(f\"ANS sync completed in {seconds:.1f} seconds: {stats.model_dump()}\")\n\n _store_sync_history(stats)\n\n return stats\n\n\ndef get_sync_history() -> list[dict]:\n \"\"\"Get recent sync history entries.\"\"\"\n return list(_sync_history)\n\n\nasync def get_ans_metrics() -> ANSIntegrationMetrics:\n \"\"\"Get ANS integration metrics for admin dashboard.\n\n Returns:\n ANS integration metrics\n \"\"\"\n agent_repo = get_agent_repository()\n server_repo = get_server_repository()\n\n metrics = ANSIntegrationMetrics()\n\n agents = await agent_repo.list_all()\n for agent in agents:\n agent_dict = agent.model_dump() if hasattr(agent, \"model_dump\") else agent\n ans_meta = agent_dict.get(\"ans_metadata\")\n if ans_meta:\n metrics.total_linked += 1\n status = ans_meta.get(\"status\", \"pending\")\n metrics.by_status[status] = metrics.by_status.get(status, 0) + 1\n metrics.by_asset_type[\"agent\"] = metrics.by_asset_type.get(\"agent\", 0) + 1\n\n servers = await server_repo.list_all()\n for server in servers:\n server_dict = server.model_dump() if hasattr(server, \"model_dump\") else server\n ans_meta = server_dict.get(\"ans_metadata\")\n if ans_meta:\n metrics.total_linked += 1\n status = ans_meta.get(\"status\", \"pending\")\n metrics.by_status[status] = metrics.by_status.get(status, 0) + 1\n metrics.by_asset_type[\"server\"] = metrics.by_asset_type.get(\"server\", 0) + 1\n\n return metrics\n" }, { "path": "registry/services/ans_sync_scheduler.py", "content": "# registry/services/ans_sync_scheduler.py\n\nimport asyncio\nimport logging\n\nfrom registry.core.config import settings\nfrom registry.services.ans_service import sync_all_ans_status\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\nSCHEDULER_CHECK_INTERVAL_SECONDS: int = 300\n\n\nclass ANSSyncScheduler:\n \"\"\"Background scheduler for ANS verification status sync.\"\"\"\n\n def __init__(self):\n self._task: asyncio.Task | None = None\n self._running: bool = False\n\n async def start(self) -> None:\n \"\"\"Start the ANS sync scheduler.\"\"\"\n if not settings.ans_integration_enabled:\n logger.info(\"ANS integration disabled, skipping scheduler start\")\n return\n\n self._running = True\n self._task = asyncio.create_task(self._scheduler_loop())\n logger.info(\n f\"ANS sync scheduler started (interval: {settings.ans_sync_interval_hours} hours)\"\n )\n\n async def stop(self) -> None:\n \"\"\"Stop the ANS sync scheduler.\"\"\"\n self._running = False\n if self._task:\n self._task.cancel()\n try:\n await self._task\n except asyncio.CancelledError:\n pass\n logger.info(\"ANS sync scheduler stopped\")\n\n async def _scheduler_loop(self) -> None:\n \"\"\"Main scheduler loop.\"\"\"\n interval_seconds = settings.ans_sync_interval_hours * 3600\n\n while self._running:\n try:\n await asyncio.sleep(interval_seconds)\n if not self._running:\n break\n logger.info(\"ANS sync scheduler: starting sync cycle\")\n stats = await sync_all_ans_status()\n logger.info(f\"ANS sync scheduler: cycle complete - {stats.model_dump()}\")\n except asyncio.CancelledError:\n break\n except Exception as e:\n logger.error(f\"ANS sync scheduler error: {e}\")\n\n\n_scheduler: ANSSyncScheduler | None = None\n\n\ndef get_ans_sync_scheduler() -> ANSSyncScheduler:\n \"\"\"Get the global ANS sync scheduler singleton.\"\"\"\n global _scheduler\n if _scheduler is None:\n _scheduler = ANSSyncScheduler()\n return _scheduler\n" }, { "path": "registry/services/auth0_m2m_sync.py", "content": "\"\"\"Auth0 M2M Client Sync Service.\n\nThis service syncs M2M applications from Auth0 to MongoDB, allowing the registry\nto track service accounts and their group mappings without hardcoding them in\nauthorization server expressions.\n\"\"\"\n\nimport logging\nimport os\nfrom datetime import datetime\n\nimport requests\nfrom motor.motor_asyncio import AsyncIOMotorDatabase\n\nfrom registry.schemas.idp_m2m_client import IdPM2MClient\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\n# Auth0 client ID to groups mapping\n# TODO: Make this configurable via database or config file\nDEFAULT_CLIENT_GROUPS = {\n # Add Auth0 M2M client IDs and their default groups here\n # Example: \"KhZMijfKUcl2TEJqZzrzVJb8rmwk6Qcd\": [\"registry-admins\"],\n}\n\n\nclass Auth0M2MSync:\n \"\"\"Service for syncing Auth0 M2M applications to MongoDB.\"\"\"\n\n def __init__(\n self,\n db: AsyncIOMotorDatabase,\n auth0_domain: str,\n m2m_client_id: str,\n m2m_client_secret: str,\n ):\n \"\"\"Initialize Auth0 M2M sync service.\n\n Args:\n db: MongoDB database instance\n auth0_domain: Auth0 tenant domain (e.g., dev-abc123.us.auth0.com)\n m2m_client_id: Auth0 M2M client ID for Management API\n m2m_client_secret: Auth0 M2M client secret for Management API\n \"\"\"\n self.db = db\n self.auth0_domain = auth0_domain.replace(\"https://\", \"\").rstrip(\"/\")\n self.m2m_client_id = m2m_client_id\n self.m2m_client_secret = m2m_client_secret\n self.collection = db[\"auth0_m2m_clients\"]\n self.idp_collection = db[\"idp_m2m_clients\"]\n\n logger.info(f\"Initialized Auth0 M2M sync for domain: {self.auth0_domain}\")\n\n async def _get_management_api_token(self) -> str:\n \"\"\"Get Auth0 Management API access token.\n\n Returns:\n Access token string\n\n Raises:\n ValueError: If token request fails\n \"\"\"\n token_url = f\"https://{self.auth0_domain}/oauth/token\"\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": self.m2m_client_id,\n \"client_secret\": self.m2m_client_secret,\n \"audience\": f\"https://{self.auth0_domain}/api/v2/\",\n }\n\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n }\n\n try:\n logger.debug(f\"Requesting Management API token from {token_url}\")\n response = requests.post(token_url, data=data, headers=headers, timeout=30)\n response.raise_for_status()\n\n token_data = response.json()\n return token_data[\"access_token\"]\n\n except requests.RequestException as e:\n logger.error(f\"Failed to get Management API token: {e}\")\n raise ValueError(f\"Management API token request failed: {e}\")\n\n async def _get_auth0_clients(self, access_token: str) -> list[dict]:\n \"\"\"Fetch all clients from Auth0 Management API.\n\n Args:\n access_token: Auth0 Management API access token\n\n Returns:\n List of Auth0 client dictionaries\n\n Raises:\n ValueError: If Auth0 API request fails\n \"\"\"\n url = f\"https://{self.auth0_domain}/api/v2/clients\"\n headers = {\n \"Authorization\": f\"Bearer {access_token}\",\n \"Content-Type\": \"application/json\",\n }\n\n try:\n logger.info(f\"Fetching clients from Auth0: {url}\")\n response = requests.get(url, headers=headers, timeout=30)\n response.raise_for_status()\n\n clients = response.json()\n logger.info(f\"Retrieved {len(clients)} clients from Auth0\")\n return clients\n\n except requests.RequestException as e:\n logger.error(f\"Failed to fetch Auth0 clients: {e}\")\n raise ValueError(f\"Auth0 API request failed: {e}\")\n\n def _filter_m2m_clients(self, clients: list[dict]) -> list[dict]:\n \"\"\"Filter to only M2M (non-interactive) clients.\n\n Args:\n clients: List of all Auth0 clients\n\n Returns:\n Filtered list of M2M clients\n \"\"\"\n m2m_clients = []\n\n for client in clients:\n # M2M clients have app_type \"non_interactive\" or \"machine_to_machine\"\n app_type = client.get(\"app_type\", \"\")\n name = client.get(\"name\", \"\")\n client_id = client.get(\"client_id\", \"\")\n\n if app_type in [\"non_interactive\", \"machine_to_machine\"]:\n logger.debug(f\"Found M2M client: {name} (ID: {client_id})\")\n m2m_clients.append(client)\n\n logger.info(f\"Filtered to {len(m2m_clients)} M2M clients\")\n return m2m_clients\n\n def _determine_groups(self, client_id: str) -> list[str]:\n \"\"\"Determine groups for a client ID.\n\n This checks the hardcoded mapping (DEFAULT_CLIENT_GROUPS) to determine\n which groups a client should have. In the future, this could query a\n configuration table or use other logic.\n\n Args:\n client_id: Auth0 client ID\n\n Returns:\n List of group names for this client\n \"\"\"\n groups = DEFAULT_CLIENT_GROUPS.get(client_id, [])\n logger.debug(f\"Client {client_id} assigned groups: {groups}\")\n return groups\n\n async def sync_from_auth0(self, force_full_sync: bool = False) -> dict:\n \"\"\"Sync M2M clients from Auth0 to MongoDB.\n\n Args:\n force_full_sync: If True, update all clients. Otherwise incremental.\n\n Returns:\n Dictionary with sync statistics\n \"\"\"\n logger.info(f\"Starting Auth0 M2M sync (force_full_sync={force_full_sync})\")\n\n added_count = 0\n updated_count = 0\n error_count = 0\n errors = []\n\n try:\n # Get Management API token\n access_token = await self._get_management_api_token()\n\n # Fetch all clients from Auth0\n all_clients = await self._get_auth0_clients(access_token)\n\n # Filter to M2M clients\n m2m_clients = self._filter_m2m_clients(all_clients)\n\n # Process each M2M client\n for client in m2m_clients:\n try:\n client_id = client.get(\"client_id\")\n\n if not client_id:\n logger.warning(f\"Client {client.get('name')} has no client_id, skipping\")\n continue\n\n # Check if client already exists in database\n existing = await self.collection.find_one({\"client_id\": client_id})\n\n # Determine groups for this client\n groups = self._determine_groups(client_id)\n\n # Auth0-specific collection document\n client_doc = {\n \"client_id\": client_id,\n \"name\": client.get(\"name\", client_id),\n \"description\": client.get(\"description\"),\n \"groups\": groups,\n \"enabled\": not client.get(\"is_first_party\", False),\n \"auth0_client_id\": client.get(\"client_id\"),\n \"app_type\": client.get(\"app_type\"),\n \"last_synced\": datetime.utcnow(),\n }\n\n if existing:\n # Update existing record\n client_doc[\"updated_at\"] = datetime.utcnow()\n await self.collection.update_one(\n {\"client_id\": client_id}, {\"$set\": client_doc}\n )\n updated_count += 1\n logger.info(f\"Updated client: {client_id}\")\n else:\n # Insert new record\n client_doc[\"created_at\"] = datetime.utcnow()\n client_doc[\"updated_at\"] = datetime.utcnow()\n await self.collection.insert_one(client_doc)\n added_count += 1\n logger.info(f\"Added new client: {client_id}\")\n\n # Also sync to generic idp_m2m_clients collection for groups enrichment\n idp_doc = {\n \"client_id\": client_id,\n \"name\": client.get(\"name\", client_id),\n \"description\": client.get(\"description\"),\n \"groups\": groups,\n \"enabled\": not client.get(\"is_first_party\", False),\n \"provider\": \"auth0\",\n \"idp_app_id\": client.get(\"client_id\"),\n \"updated_at\": datetime.utcnow(),\n }\n\n existing_idp = await self.idp_collection.find_one({\"client_id\": client_id})\n if existing_idp:\n await self.idp_collection.update_one(\n {\"client_id\": client_id}, {\"$set\": idp_doc}\n )\n else:\n idp_doc[\"created_at\"] = datetime.utcnow()\n await self.idp_collection.insert_one(idp_doc)\n\n except Exception as e:\n error_msg = f\"Failed to process client {client.get('name')}: {e}\"\n logger.error(error_msg)\n errors.append(error_msg)\n error_count += 1\n\n logger.info(\n f\"Sync completed: {added_count} added, {updated_count} updated, \"\n f\"{error_count} errors\"\n )\n\n return {\n \"synced_count\": added_count + updated_count,\n \"added_count\": added_count,\n \"updated_count\": updated_count,\n \"removed_count\": 0,\n \"errors\": errors,\n }\n\n except Exception as e:\n logger.exception(f\"Auth0 sync failed: {e}\")\n return {\n \"synced_count\": 0,\n \"added_count\": 0,\n \"updated_count\": 0,\n \"removed_count\": 0,\n \"errors\": [str(e)],\n }\n\n async def get_all_clients(self) -> list[IdPM2MClient]:\n \"\"\"Get all M2M clients from MongoDB.\n\n Returns:\n List of IdPM2MClient objects\n \"\"\"\n cursor = self.collection.find({})\n docs = await cursor.to_list(length=None)\n\n clients = []\n for doc in docs:\n try:\n # Remove MongoDB _id field\n doc.pop(\"_id\", None)\n # Convert to generic IdPM2MClient format\n client = IdPM2MClient(\n client_id=doc[\"client_id\"],\n name=doc.get(\"name\", doc[\"client_id\"]),\n description=doc.get(\"description\"),\n groups=doc.get(\"groups\", []),\n enabled=doc.get(\"enabled\", True),\n provider=\"auth0\",\n created_at=doc.get(\"created_at\", datetime.utcnow()),\n updated_at=doc.get(\"updated_at\", datetime.utcnow()),\n idp_app_id=doc.get(\"auth0_client_id\"),\n )\n clients.append(client)\n except Exception as e:\n logger.warning(f\"Failed to parse client document: {e}\")\n\n return clients\n\n async def get_client_groups(self, client_id: str) -> list[str]:\n \"\"\"Get groups for a specific client ID.\n\n Args:\n client_id: Auth0 client ID\n\n Returns:\n List of group names, empty if client not found\n \"\"\"\n doc = await self.collection.find_one({\"client_id\": client_id})\n if doc:\n return doc.get(\"groups\", [])\n return []\n\n async def update_client_groups(\n self,\n client_id: str,\n groups: list[str],\n ) -> bool:\n \"\"\"Update groups for a specific client.\n\n Args:\n client_id: Auth0 client ID\n groups: New list of groups\n\n Returns:\n True if updated, False if client not found\n \"\"\"\n # Update in Auth0-specific collection\n result = await self.collection.update_one(\n {\"client_id\": client_id},\n {\n \"$set\": {\n \"groups\": groups,\n \"updated_at\": datetime.utcnow(),\n }\n },\n )\n\n # Also update in generic idp_m2m_clients collection\n await self.idp_collection.update_one(\n {\"client_id\": client_id},\n {\n \"$set\": {\n \"groups\": groups,\n \"updated_at\": datetime.utcnow(),\n }\n },\n )\n\n if result.modified_count > 0:\n logger.info(f\"Updated groups for client {client_id}: {groups}\")\n return True\n\n logger.warning(f\"Client {client_id} not found for update\")\n return False\n\n\ndef get_auth0_m2m_sync(db: AsyncIOMotorDatabase) -> Auth0M2MSync | None:\n \"\"\"Factory function to create Auth0M2MSync instance.\n\n Args:\n db: MongoDB database instance\n\n Returns:\n Auth0M2MSync instance if Auth0 is configured, None otherwise\n \"\"\"\n auth0_domain = os.getenv(\"AUTH0_DOMAIN\")\n m2m_client_id = os.getenv(\"AUTH0_M2M_CLIENT_ID\")\n m2m_client_secret = os.getenv(\"AUTH0_M2M_CLIENT_SECRET\")\n\n if not auth0_domain or not m2m_client_id or not m2m_client_secret:\n logger.warning(\n \"Auth0 M2M sync not configured (missing AUTH0_DOMAIN, \"\n \"AUTH0_M2M_CLIENT_ID, or AUTH0_M2M_CLIENT_SECRET)\"\n )\n return None\n\n return Auth0M2MSync(\n db=db,\n auth0_domain=auth0_domain,\n m2m_client_id=m2m_client_id,\n m2m_client_secret=m2m_client_secret,\n )\n" }, { "path": "registry/services/demo_servers_init.py", "content": "\"\"\"Initialize built-in demo servers on registry startup.\n\nThis module automatically registers essential demo servers directly into the\ndatabase during registry startup, eliminating the need for external registration\nscripts and authentication tokens.\n\"\"\"\n\nimport asyncio\nimport json\nimport logging\nfrom datetime import datetime\nfrom pathlib import Path\nfrom typing import Any\nfrom uuid import uuid4\n\nlogger = logging.getLogger(__name__)\n\n\ndef _load_server_config(config_path: str) -> dict[str, Any]:\n \"\"\"Load server configuration from JSON file.\n\n Args:\n config_path: Relative path to config file from project root (/app in container)\n\n Returns:\n Server configuration dictionary\n\n Raises:\n FileNotFoundError: If config file doesn't exist\n json.JSONDecodeError: If config file is invalid JSON\n \"\"\"\n # Get project root (3 levels up from this file: registry/services -> registry -> app)\n project_root = Path(__file__).parent.parent.parent\n full_path = project_root / config_path\n\n logger.debug(f\"Loading server config from: {full_path}\")\n\n if not full_path.exists():\n raise FileNotFoundError(f\"Server config not found: {full_path}\")\n\n with open(full_path) as f:\n return json.load(f)\n\n\nasync def initialize_airegistry_server() -> bool:\n \"\"\"Initialize AI Registry Tools server on startup.\n\n This function registers the airegistry-tools server (mcpgw) directly into\n the database, making it immediately available after deployment without\n requiring external registration scripts.\n\n The server provides essential registry management tools including:\n - Semantic search across all registered servers\n - Server discovery and listing\n - Intelligent tool finder\n\n Returns:\n True if initialization succeeded, False otherwise\n \"\"\"\n try:\n logger.info(\"Initializing AI Registry Tools server...\")\n\n # Load configuration from file\n config = _load_server_config(\"cli/examples/airegistry.json\")\n\n # Get server repository (works with any backend: DocumentDB, MongoDB, or file)\n from registry.repositories.factory import get_server_repository\n\n server_repo = get_server_repository()\n\n # Check if server already exists\n path = config[\"path\"]\n existing = await server_repo.get(path)\n\n if existing:\n logger.info(f\"AI Registry Tools server already exists at {path}, updating...\")\n\n # Update with new configuration\n config[\"updated_at\"] = datetime.utcnow().isoformat()\n config[\"is_enabled\"] = True # Ensure it's enabled\n\n success = await server_repo.update(path, config)\n if success:\n logger.info(f\"✅ AI Registry Tools server updated at {path}\")\n else:\n logger.error(f\"Failed to update AI Registry Tools server at {path}\")\n return False\n else:\n logger.info(f\"Creating AI Registry Tools server at {path}...\")\n\n # Set metadata for new server\n config[\"registered_at\"] = datetime.utcnow().isoformat()\n config[\"updated_at\"] = datetime.utcnow().isoformat()\n config[\"is_enabled\"] = True # Enable by default\n config[\"source\"] = \"builtin\" # Mark as built-in server\n\n # Ensure UUID id field exists\n if \"id\" not in config or not config[\"id\"]:\n config[\"id\"] = str(uuid4())\n\n success = await server_repo.create(config)\n if success:\n logger.info(f\"✅ AI Registry Tools server created at {path}\")\n else:\n logger.error(f\"Failed to create AI Registry Tools server at {path}\")\n return False\n\n # Trigger immediate health check and security scan for the registered server\n logger.info(f\"Triggering health check and security scan for {path}...\")\n from registry.health.service import health_service\n from registry.services.security_scanner import security_scanner_service\n\n # Trigger health check asynchronously\n asyncio.create_task(health_service.perform_immediate_health_check(path))\n\n # Trigger security scan asynchronously\n proxy_pass_url = config.get(\"proxy_pass_url\")\n if proxy_pass_url:\n asyncio.create_task(\n security_scanner_service.scan_server(server_url=proxy_pass_url, server_path=path)\n )\n logger.info(f\"Security scan scheduled for {path}\")\n else:\n logger.warning(f\"No proxy_pass_url found for {path}, skipping security scan\")\n\n return True\n\n except FileNotFoundError as e:\n logger.error(f\"Server config file not found: {e}\")\n return False\n except json.JSONDecodeError as e:\n logger.error(f\"Invalid JSON in server config: {e}\")\n return False\n except Exception as e:\n logger.error(f\"Failed to initialize AI Registry Tools server: {e}\", exc_info=True)\n return False\n\n\nasync def initialize_demo_servers() -> None:\n \"\"\"Initialize all built-in demo servers on registry startup.\n\n This is called during FastAPI lifespan initialization to ensure demo\n servers are available immediately after deployment.\n\n Currently initializes:\n - AI Registry Tools (mcpgw server) at /airegistry-tools/\n \"\"\"\n logger.info(\"🔧 Initializing built-in demo servers...\")\n\n # Initialize AI Registry Tools\n success = await initialize_airegistry_server()\n\n if success:\n logger.info(\"✅ Built-in demo servers initialized successfully\")\n else:\n logger.warning(\"⚠️ Failed to initialize some demo servers (registry will continue)\")\n" }, { "path": "registry/services/federation/__init__.py", "content": "\"\"\"\nFederation services for integrating with external registries.\n\nSupports federation with:\n- Anthropic MCP Registry\n- Workday ASOR (Agent Service Operating Registry)\n- AWS Agent Registry\n\"\"\"\n\nfrom .agentcore_client import AgentCoreFederationClient\nfrom .anthropic_client import AnthropicFederationClient\nfrom .asor_client import AsorFederationClient\nfrom .base_client import BaseFederationClient\n\n__all__ = [\n \"AgentCoreFederationClient\",\n \"AnthropicFederationClient\",\n \"AsorFederationClient\",\n \"BaseFederationClient\",\n]\n" }, { "path": "registry/services/federation/agentcore_client.py", "content": "\"\"\"\nAWS Agent Registry federation client.\n\nFetches registry records from AWS Agent Registry via boto3 control plane API\n(bedrock-agentcore-control) and transforms them to the gateway's internal format.\n\nDescriptor type mapping:\n MCP -> MCP Servers (server model)\n A2A -> Agents (agent card model)\n CUSTOM -> Agents (agent card model, self-referencing URL)\n AGENT_SKILLS -> Skills (skill card model, inline content stored in DB)\n\"\"\"\n\nimport json\nimport logging\nimport time\nfrom concurrent.futures import (\n ThreadPoolExecutor,\n as_completed,\n)\nfrom concurrent.futures import (\n TimeoutError as FuturesTimeoutError,\n)\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nimport boto3\nfrom botocore.config import Config as BotoConfig\nfrom botocore.exceptions import (\n BotoCoreError,\n ClientError,\n)\n\nfrom ...schemas.federation_schema import AgentCoreRegistryConfig\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nAGENTCORE_SOURCE: str = \"agentcore\"\nAGENTCORE_ATTRIBUTION: str = \"AWS Agent Registry\"\nDEFAULT_AWS_REGION: str = \"us-east-1\"\nDEFAULT_SYNC_STATUS: str = \"APPROVED\"\nDEFAULT_SYNC_TIMEOUT_SECONDS: int = 300\nDEFAULT_MAX_CONCURRENT_FETCHES: int = 5\nMAX_RESULTS_PER_PAGE: int = 100\n\n\ndef _safe_parse_json(\n content: str,\n context: str = \"\",\n) -> dict[str, Any]:\n \"\"\"Parse JSON string safely, returning empty dict on failure.\n\n Args:\n content: JSON string to parse\n context: Description for error logging\n\n Returns:\n Parsed dict or empty dict on failure\n \"\"\"\n try:\n return json.loads(content)\n except (json.JSONDecodeError, TypeError) as e:\n logger.warning(f\"Failed to parse JSON for {context}: {e}\")\n return {}\n\n\ndef _sanitize_path_segment(\n name: str,\n) -> str:\n \"\"\"Sanitize a name for use in a URL path segment.\n\n Replaces slashes and spaces with hyphens, lowercases.\n\n Args:\n name: Raw name string\n\n Returns:\n Sanitized path-safe string\n \"\"\"\n return name.replace(\"/\", \"-\").replace(\" \", \"-\").replace(\"_\", \"-\").lower().strip(\"-\")\n\n\ndef _extract_transport_info(\n server_content: dict[str, Any],\n) -> tuple[str, str | None]:\n \"\"\"Extract transport type and proxy URL from MCP server definition.\n\n Args:\n server_content: Parsed MCP server inlineContent\n\n Returns:\n Tuple of (transport_type, proxy_url)\n \"\"\"\n transport_type = \"streamable-http\"\n proxy_url = None\n\n remotes = server_content.get(\"remotes\", [])\n if remotes:\n remote = remotes[0]\n transport_type = remote.get(\"type\", \"streamable-http\")\n proxy_url = remote.get(\"url\")\n else:\n packages = server_content.get(\"packages\", [])\n if packages:\n transport = packages[0].get(\"transport\", {})\n transport_type = transport.get(\"type\", \"streamable-http\")\n if transport_type in (\"streamable-http\", \"http\"):\n proxy_url = transport.get(\"url\")\n\n return transport_type, proxy_url\n\n\nclass AgentCoreFederationClient:\n \"\"\"Client for fetching records from AWS Agent Registry.\n\n Uses boto3 bedrock-agentcore-control client (control plane) to:\n - List registries in the AWS account\n - List and fetch registry records\n - Transform records to gateway internal format by descriptor type\n \"\"\"\n\n def __init__(\n self,\n aws_region: str = DEFAULT_AWS_REGION,\n timeout_seconds: int = 30,\n retry_attempts: int = 3,\n ) -> None:\n \"\"\"Initialize AWS Agent Registry federation client.\n\n Args:\n aws_region: AWS region for API calls\n timeout_seconds: boto3 read timeout\n retry_attempts: Number of retry attempts for API calls\n \"\"\"\n self.aws_region = aws_region\n self.timeout_seconds = timeout_seconds\n self.retry_attempts = retry_attempts\n\n boto_config = BotoConfig(\n region_name=aws_region,\n read_timeout=timeout_seconds,\n retries={\"max_attempts\": retry_attempts, \"mode\": \"adaptive\"},\n )\n self._client = boto3.client(\n \"bedrock-agentcore-control\",\n config=boto_config,\n )\n\n # Health indicator state\n self._last_sync_success: bool = False\n self._last_sync_time: str | None = None\n self._last_sync_record_count: int = 0\n self._last_sync_error: str | None = None\n\n # Cache for per-registry clients (keyed by cache key)\n self._registry_clients: dict[str, Any] = {}\n\n logger.info(\n f\"AgentCoreFederationClient initialized \"\n f\"(region={aws_region}, timeout={timeout_seconds}s, retries={retry_attempts})\"\n )\n\n def _get_client_for_registry(\n self,\n reg_config: AgentCoreRegistryConfig,\n ) -> Any:\n \"\"\"Get a boto3 client for the given registry config.\n\n Returns the default client when the registry uses the same region\n and no cross-account role. Creates a region-specific or cross-account\n client via STS AssumeRole when needed.\n\n Args:\n reg_config: Registry configuration (may include aws_region, assume_role_arn)\n\n Returns:\n boto3 bedrock-agentcore-control client\n \"\"\"\n registry_region = reg_config.aws_region or self.aws_region\n has_custom_region = registry_region != self.aws_region\n has_role = bool(reg_config.assume_role_arn)\n\n # Same region, no role assumption -> use default client\n if not has_custom_region and not has_role:\n return self._client\n\n # Build cache key from region + role\n cache_key = f\"{registry_region}:{reg_config.assume_role_arn or 'default'}\"\n if cache_key in self._registry_clients:\n return self._registry_clients[cache_key]\n\n return self._create_registry_client(\n reg_config=reg_config,\n registry_region=registry_region,\n cache_key=cache_key,\n )\n\n def _create_registry_client(\n self,\n reg_config: AgentCoreRegistryConfig,\n registry_region: str,\n cache_key: str,\n ) -> Any:\n \"\"\"Create a boto3 client for cross-account or cross-region access.\n\n Args:\n reg_config: Registry configuration\n registry_region: Resolved AWS region for this registry\n cache_key: Cache key for storing the created client\n\n Returns:\n boto3 bedrock-agentcore-control client\n \"\"\"\n boto_config = BotoConfig(\n region_name=registry_region,\n read_timeout=self.timeout_seconds,\n retries={\"max_attempts\": self.retry_attempts, \"mode\": \"adaptive\"},\n )\n\n if reg_config.assume_role_arn:\n logger.info(\n f\"Assuming role {reg_config.assume_role_arn} for registry \"\n f\"{reg_config.registry_id} (region={registry_region})\"\n )\n client = self._create_cross_account_client(\n role_arn=reg_config.assume_role_arn,\n registry_id=reg_config.registry_id,\n registry_region=registry_region,\n boto_config=boto_config,\n )\n else:\n # Different region, same account\n logger.info(\n f\"Creating region-specific client for registry \"\n f\"{reg_config.registry_id} (region={registry_region})\"\n )\n client = boto3.client(\n \"bedrock-agentcore-control\",\n config=boto_config,\n )\n\n self._registry_clients[cache_key] = client\n return client\n\n def _create_cross_account_client(\n self,\n role_arn: str,\n registry_id: str,\n registry_region: str,\n boto_config: BotoConfig,\n ) -> Any:\n \"\"\"Create a boto3 client using STS AssumeRole for cross-account access.\n\n Args:\n role_arn: IAM role ARN to assume\n registry_id: Registry ID (for session name)\n registry_region: AWS region for the target registry\n boto_config: Boto3 client config\n\n Returns:\n boto3 bedrock-agentcore-control client with assumed role credentials\n \"\"\"\n try:\n sts_client = boto3.client(\"sts\", region_name=registry_region)\n assumed = sts_client.assume_role(\n RoleArn=role_arn,\n RoleSessionName=f\"agentcore-federation-{registry_id[:20]}\",\n DurationSeconds=3600,\n )\n\n credentials = assumed[\"Credentials\"]\n cross_account_client = boto3.client(\n \"bedrock-agentcore-control\",\n config=boto_config,\n aws_access_key_id=credentials[\"AccessKeyId\"],\n aws_secret_access_key=credentials[\"SecretAccessKey\"],\n aws_session_token=credentials[\"SessionToken\"],\n )\n\n logger.info(f\"Cross-account client created for role {role_arn}\")\n return cross_account_client\n\n except (ClientError, BotoCoreError) as e:\n logger.error(f\"Failed to assume role {role_arn}: {e}\")\n raise\n\n def get_health_status(self) -> dict[str, Any]:\n \"\"\"Return health indicator for AWS Agent Registry federation.\n\n Returns:\n Dict with last sync status, time, record count, and error (if any)\n \"\"\"\n return {\n \"source\": AGENTCORE_SOURCE,\n \"healthy\": self._last_sync_success,\n \"last_sync_time\": self._last_sync_time,\n \"last_sync_record_count\": self._last_sync_record_count,\n \"last_sync_error\": self._last_sync_error,\n \"aws_region\": self.aws_region,\n }\n\n def list_registries(self) -> list[dict[str, Any]]:\n \"\"\"List all AgentCore registries in the AWS account.\n\n Returns:\n List of registry summary dicts\n \"\"\"\n registries: list[dict[str, Any]] = []\n next_token = None\n\n try:\n while True:\n params: dict[str, Any] = {\n \"maxResults\": MAX_RESULTS_PER_PAGE,\n \"status\": \"READY\",\n }\n if next_token:\n params[\"nextToken\"] = next_token\n\n response = self._client.list_registries(**params)\n registries.extend(response.get(\"registries\", []))\n\n next_token = response.get(\"nextToken\")\n if not next_token:\n break\n\n logger.info(f\"Found {len(registries)} AgentCore registries\")\n return registries\n\n except (ClientError, BotoCoreError) as e:\n logger.error(f\"Failed to list AgentCore registries: {e}\")\n return []\n\n def list_registry_records(\n self,\n registry_id: str,\n descriptor_type: str | None = None,\n status: str = DEFAULT_SYNC_STATUS,\n ) -> list[dict[str, Any]]:\n \"\"\"List all registry records from an AgentCore registry.\n\n Handles pagination automatically.\n\n Args:\n registry_id: Registry ID or ARN\n descriptor_type: Filter by descriptor type (MCP, A2A, CUSTOM, AGENT_SKILLS)\n status: Filter by record status (default: APPROVED)\n\n Returns:\n List of registry record summary dicts\n \"\"\"\n records: list[dict[str, Any]] = []\n next_token = None\n\n try:\n while True:\n params: dict[str, Any] = {\n \"registryId\": registry_id,\n \"maxResults\": MAX_RESULTS_PER_PAGE,\n }\n if descriptor_type:\n params[\"descriptorType\"] = descriptor_type\n if status:\n params[\"status\"] = status\n if next_token:\n params[\"nextToken\"] = next_token\n\n response = self._client.list_registry_records(**params)\n records.extend(response.get(\"registryRecords\", []))\n\n next_token = response.get(\"nextToken\")\n if not next_token:\n break\n\n logger.info(\n f\"Found {len(records)} records in registry {registry_id} \"\n f\"(descriptor_type={descriptor_type}, status={status})\"\n )\n return records\n\n except ClientError as e:\n error_code = e.response.get(\"Error\", {}).get(\"Code\", \"\")\n logger.error(f\"Failed to list records from registry {registry_id}: {error_code} - {e}\")\n return []\n except BotoCoreError as e:\n logger.error(f\"Failed to list records from registry {registry_id}: {e}\")\n return []\n\n def get_registry_record(\n self,\n registry_id: str,\n record_id: str,\n ) -> dict[str, Any] | None:\n \"\"\"Get full details of a single registry record.\n\n Args:\n registry_id: Registry ID or ARN\n record_id: Record ID or ARN\n\n Returns:\n Full registry record dict or None if fetch fails\n \"\"\"\n try:\n response = self._client.get_registry_record(\n registryId=registry_id,\n recordId=record_id,\n )\n\n # Remove ResponseMetadata added by boto3\n response.pop(\"ResponseMetadata\", None)\n return response\n\n except ClientError as e:\n error_code = e.response.get(\"Error\", {}).get(\"Code\", \"\")\n if error_code == \"ResourceNotFoundException\":\n logger.warning(f\"Record {record_id} not found in registry {registry_id}\")\n else:\n logger.error(\n f\"Failed to get record {record_id} from {registry_id}: {error_code} - {e}\"\n )\n return None\n except BotoCoreError as e:\n logger.error(f\"Failed to get record {record_id} from {registry_id}: {e}\")\n return None\n\n def fetch_all_records(\n self,\n registry_configs: list[AgentCoreRegistryConfig],\n sync_timeout_seconds: int = DEFAULT_SYNC_TIMEOUT_SECONDS,\n max_concurrent_fetches: int = DEFAULT_MAX_CONCURRENT_FETCHES,\n ) -> dict[str, list[dict[str, Any]]]:\n \"\"\"Fetch and transform all records from configured AWS Agent Registry registries.\n\n Uses ThreadPoolExecutor for parallel get_registry_record calls\n and enforces an overall sync timeout.\n\n Args:\n registry_configs: List of registry configurations\n sync_timeout_seconds: Max time for entire sync (default 300s / 5 min)\n max_concurrent_fetches: Thread pool size for parallel fetches (default 5)\n\n Returns:\n Dict with keys \"servers\", \"agents\", \"skills\" containing\n transformed record dicts ready for registration\n \"\"\"\n start_time = time.monotonic()\n\n result: dict[str, list[dict[str, Any]]] = {\n \"servers\": [],\n \"agents\": [],\n \"skills\": [],\n }\n\n try:\n for reg_config in registry_configs:\n # Check overall timeout before starting next registry\n elapsed = time.monotonic() - start_time\n if elapsed >= sync_timeout_seconds:\n logger.warning(\n f\"Sync timeout reached ({sync_timeout_seconds}s) \"\n f\"after processing some registries. Stopping gracefully.\"\n )\n break\n\n self._fetch_from_registry(\n reg_config=reg_config,\n result=result,\n start_time=start_time,\n sync_timeout_seconds=sync_timeout_seconds,\n max_concurrent_fetches=max_concurrent_fetches,\n )\n\n except Exception as e:\n logger.error(f\"Unexpected error during AgentCore sync: {e}\")\n self._last_sync_error = str(e)\n\n # Log timing\n elapsed_total = time.monotonic() - start_time\n minutes = int(elapsed_total // 60)\n seconds = elapsed_total % 60\n if minutes > 0:\n logger.info(f\"AgentCore sync completed in {minutes} minutes and {seconds:.1f} seconds\")\n else:\n logger.info(f\"AgentCore sync completed in {seconds:.1f} seconds\")\n\n # Update health indicator\n total_count = len(result[\"servers\"]) + len(result[\"agents\"]) + len(result[\"skills\"])\n self._last_sync_success = True\n self._last_sync_time = datetime.now(UTC).isoformat()\n self._last_sync_record_count = total_count\n self._last_sync_error = None\n\n return result\n\n def _fetch_from_registry(\n self,\n reg_config: AgentCoreRegistryConfig,\n result: dict[str, list[dict[str, Any]]],\n start_time: float,\n sync_timeout_seconds: int,\n max_concurrent_fetches: int,\n ) -> None:\n \"\"\"Fetch and transform records from a single registry.\n\n Args:\n reg_config: Registry configuration\n result: Result dict to append transformed records to\n start_time: Monotonic start time for timeout calculation\n sync_timeout_seconds: Overall sync timeout\n max_concurrent_fetches: Thread pool size\n \"\"\"\n registry_id = reg_config.registry_id\n status_filter = reg_config.sync_status_filter\n account_info = (\n f\" (account={reg_config.aws_account_id})\" if reg_config.aws_account_id else \"\"\n )\n logger.info(f\"Fetching records from AWS Agent Registry: {registry_id}{account_info}\")\n\n # Swap to cross-account client if needed\n original_client = self._client\n try:\n self._client = self._get_client_for_registry(reg_config)\n except (ClientError, BotoCoreError) as e:\n logger.error(f\"Skipping registry {registry_id}: failed to get client: {e}\")\n return\n\n try:\n record_summaries = self.list_registry_records(\n registry_id=registry_id,\n status=status_filter,\n )\n\n # Filter to configured descriptor types\n filtered_summaries = [\n s\n for s in record_summaries\n if s.get(\"descriptorType\", \"\") in reg_config.descriptor_types\n ]\n\n skipped = len(record_summaries) - len(filtered_summaries)\n if skipped > 0:\n logger.debug(f\"Skipped {skipped} records with non-configured descriptor types\")\n\n # Fetch full details in parallel\n timeout_remaining = sync_timeout_seconds - (time.monotonic() - start_time)\n fetched_records = self._fetch_records_parallel(\n registry_id=registry_id,\n summaries=filtered_summaries,\n max_workers=max_concurrent_fetches,\n timeout_remaining=timeout_remaining,\n )\n finally:\n # Restore original client\n self._client = original_client\n\n # Transform and route to correct bucket\n for full_record in fetched_records:\n transformed = self._transform_record(full_record, registry_id)\n if not transformed:\n continue\n\n descriptor_type = full_record.get(\"descriptorType\", \"\")\n if descriptor_type == \"MCP\":\n result[\"servers\"].append(transformed)\n elif descriptor_type in (\"A2A\", \"CUSTOM\"):\n result[\"agents\"].append(transformed)\n elif descriptor_type == \"AGENT_SKILLS\":\n result[\"skills\"].append(transformed)\n\n logger.info(\n f\"Registry {registry_id}: \"\n f\"{len(result['servers'])} servers, \"\n f\"{len(result['agents'])} agents, \"\n f\"{len(result['skills'])} skills\"\n )\n\n def _fetch_records_parallel(\n self,\n registry_id: str,\n summaries: list[dict[str, Any]],\n max_workers: int = DEFAULT_MAX_CONCURRENT_FETCHES,\n timeout_remaining: float = DEFAULT_SYNC_TIMEOUT_SECONDS,\n ) -> list[dict[str, Any]]:\n \"\"\"Fetch full record details in parallel using ThreadPoolExecutor.\n\n boto3 clients are thread-safe for read operations.\n\n Args:\n registry_id: Registry ID to fetch from\n summaries: List of record summaries to fetch details for\n max_workers: Maximum concurrent threads (default 5)\n timeout_remaining: Seconds remaining before sync timeout\n\n Returns:\n List of full record dicts (failed fetches are excluded)\n \"\"\"\n if not summaries:\n return []\n\n if timeout_remaining <= 0:\n logger.warning(\"No time remaining for parallel fetch, skipping\")\n return []\n\n records: list[dict[str, Any]] = []\n failed_count = 0\n\n with ThreadPoolExecutor(max_workers=max_workers) as executor:\n future_to_record_id = {\n executor.submit(\n self.get_registry_record,\n registry_id,\n summary.get(\"recordId\", \"\"),\n ): summary.get(\"recordId\", \"\")\n for summary in summaries\n }\n\n try:\n for future in as_completed(future_to_record_id, timeout=timeout_remaining):\n record_id = future_to_record_id[future]\n try:\n full_record = future.result()\n if full_record:\n records.append(full_record)\n else:\n failed_count += 1\n logger.warning(f\"Skipping record {record_id}: fetch returned None\")\n except Exception as e:\n failed_count += 1\n logger.error(f\"Error fetching record {record_id}: {e}\")\n except FuturesTimeoutError:\n failed_count += len(future_to_record_id) - len(records)\n logger.warning(\n f\"Parallel fetch timed out for registry {registry_id}, \"\n f\"got {len(records)} of {len(summaries)} records\"\n )\n\n logger.info(\n f\"Parallel fetch from {registry_id}: \"\n f\"{len(records)} succeeded, {failed_count} failed \"\n f\"(of {len(summaries)} total, {max_workers} workers)\"\n )\n\n return records\n\n def _transform_record(\n self,\n record: dict[str, Any],\n registry_id: str,\n ) -> dict[str, Any] | None:\n \"\"\"Transform a record to internal format based on descriptor type.\n\n Args:\n record: Full record from get_registry_record\n registry_id: Source registry ID\n\n Returns:\n Transformed dict ready for registration, or None on failure\n \"\"\"\n descriptor_type = record.get(\"descriptorType\", \"\")\n descriptors = record.get(\"descriptors\", {})\n\n if descriptor_type == \"MCP\":\n return self._transform_mcp_record(record, descriptors, registry_id)\n elif descriptor_type == \"A2A\":\n return self._transform_a2a_record(record, descriptors, registry_id)\n elif descriptor_type == \"CUSTOM\":\n return self._transform_custom_record(record, descriptors, registry_id)\n elif descriptor_type == \"AGENT_SKILLS\":\n return self._transform_skills_record(record, descriptors, registry_id)\n else:\n logger.warning(f\"Unknown descriptor type: {descriptor_type}\")\n return None\n\n def _transform_mcp_record(\n self,\n record: dict[str, Any],\n descriptors: dict[str, Any],\n registry_id: str,\n ) -> dict[str, Any]:\n \"\"\"Transform MCP descriptor record to server registration data.\n\n Args:\n record: Full AgentCore record\n descriptors: Descriptors section of the record\n registry_id: Source registry ID\n\n Returns:\n Server data dict for ServerService.register_server()\n \"\"\"\n record_name = record.get(\"name\", \"\")\n record_id = record.get(\"recordId\", \"\")\n description = record.get(\"description\", \"\")\n version = record.get(\"recordVersion\", \"1.0.0\")\n\n # Parse MCP server definition\n mcp_desc = descriptors.get(\"mcp\", {})\n server_content = _safe_parse_json(\n mcp_desc.get(\"server\", {}).get(\"inlineContent\", \"{}\"),\n context=f\"MCP server for {record_name}\",\n )\n tools_content = _safe_parse_json(\n mcp_desc.get(\"tools\", {}).get(\"inlineContent\", \"{}\"),\n context=f\"MCP tools for {record_name}\",\n )\n\n # Extract transport info\n transport_type, proxy_url = _extract_transport_info(server_content)\n\n # Check synchronizationConfiguration for URL as fallback\n sync_config = record.get(\"synchronizationConfiguration\", {})\n from_url = sync_config.get(\"fromUrl\", {})\n sync_url = from_url.get(\"url\")\n if sync_url and not proxy_url:\n proxy_url = sync_url\n\n # Count tools\n tools_list = tools_content.get(\"tools\", [])\n num_tools = len(tools_list) if isinstance(tools_list, list) else 0\n\n # Use description from server content if record description is empty\n if not description:\n description = server_content.get(\"description\", \"\")\n\n path_segment = _sanitize_path_segment(record_name)\n\n tags = [\n \"agentcore\",\n \"bedrock\",\n \"federated\",\n \"mcp\",\n f\"registry-{registry_id[:12]}\",\n ]\n\n # Extract AWS timestamps (datetime objects from boto3)\n created_at = record.get(\"createdAt\")\n updated_at = record.get(\"lastUpdatedAt\")\n\n return {\n \"source\": AGENTCORE_SOURCE,\n \"server_name\": record_name,\n \"description\": description,\n \"version\": version,\n \"title\": server_content.get(\"title\", record_name),\n \"proxy_pass_url\": proxy_url,\n \"transport_type\": transport_type,\n \"requires_auth\": False,\n \"auth_headers\": [],\n \"tags\": tags,\n \"metadata\": {\n \"agentcore_registry_id\": registry_id,\n \"agentcore_record_id\": record_id,\n \"descriptor_type\": \"MCP\",\n \"created_at\": created_at.isoformat() if created_at else None,\n \"updated_at\": updated_at.isoformat() if updated_at else None,\n },\n \"cached_at\": datetime.now(UTC).isoformat(),\n \"is_read_only\": True,\n \"attribution_label\": AGENTCORE_ATTRIBUTION,\n \"path\": f\"/agentcore-{path_segment}\",\n \"is_enabled\": True,\n \"health_status\": \"unknown\",\n \"num_tools\": num_tools,\n }\n\n def _transform_a2a_record(\n self,\n record: dict[str, Any],\n descriptors: dict[str, Any],\n registry_id: str,\n ) -> dict[str, Any]:\n \"\"\"Transform A2A descriptor record to agent card registration data.\n\n Args:\n record: Full AgentCore record\n descriptors: Descriptors section\n registry_id: Source registry ID\n\n Returns:\n Agent data dict for AgentService.register_agent()\n \"\"\"\n record_name = record.get(\"name\", \"\")\n record_id = record.get(\"recordId\", \"\")\n description = record.get(\"description\", \"\")\n version = record.get(\"recordVersion\", \"1.0.0\")\n\n # Parse A2A agent card\n a2a_desc = descriptors.get(\"a2a\", {})\n agent_card_content = _safe_parse_json(\n a2a_desc.get(\"agentCard\", {}).get(\"inlineContent\", \"{}\"),\n context=f\"A2A agent card for {record_name}\",\n )\n\n path_segment = _sanitize_path_segment(record_name)\n\n # Extract A2A protocol fields\n agent_url = agent_card_content.get(\"url\", \"\")\n agent_name = agent_card_content.get(\"name\", record_name)\n agent_description = agent_card_content.get(\"description\", description)\n agent_version = agent_card_content.get(\"version\", version)\n\n tags = [\n \"agentcore\",\n \"bedrock\",\n \"federated\",\n \"a2a\",\n f\"registry-{registry_id[:12]}\",\n ]\n\n # Extract AWS timestamps (datetime objects from boto3)\n created_at = record.get(\"createdAt\")\n updated_at = record.get(\"lastUpdatedAt\")\n\n return {\n \"source\": AGENTCORE_SOURCE,\n \"name\": agent_name,\n \"description\": agent_description,\n \"url\": agent_url,\n \"path\": f\"/agents/agentcore-{path_segment}\",\n \"version\": agent_version,\n \"protocol_version\": agent_card_content.get(\"protocolVersion\", \"1.0\"),\n \"capabilities\": agent_card_content.get(\"capabilities\", {}),\n \"skills\": agent_card_content.get(\"skills\", []),\n \"provider\": agent_card_content.get(\"provider\"),\n \"security_schemes\": agent_card_content.get(\"securitySchemes\", {}),\n \"default_input_modes\": agent_card_content.get(\"defaultInputModes\", [\"text/plain\"]),\n \"default_output_modes\": agent_card_content.get(\"defaultOutputModes\", [\"text/plain\"]),\n \"tags\": tags,\n \"is_enabled\": True,\n \"is_read_only\": True,\n \"attribution_label\": AGENTCORE_ATTRIBUTION,\n \"supported_protocol\": \"a2a\",\n \"metadata\": {\n \"agentcore_registry_id\": registry_id,\n \"agentcore_record_id\": record_id,\n \"descriptor_type\": \"A2A\",\n \"created_at\": created_at.isoformat() if created_at else None,\n \"updated_at\": updated_at.isoformat() if updated_at else None,\n },\n \"cached_at\": datetime.now(UTC).isoformat(),\n }\n\n def _transform_custom_record(\n self,\n record: dict[str, Any],\n descriptors: dict[str, Any],\n registry_id: str,\n ) -> dict[str, Any]:\n \"\"\"Transform CUSTOM descriptor record to agent card registration data.\n\n Custom descriptors are treated as agents. Uses a self-referencing URL\n pointing to our own agent detail endpoint.\n\n Args:\n record: Full AgentCore record\n descriptors: Descriptors section\n registry_id: Source registry ID\n\n Returns:\n Agent data dict for AgentService.register_agent()\n \"\"\"\n record_name = record.get(\"name\", \"\")\n record_id = record.get(\"recordId\", \"\")\n description = record.get(\"description\", \"\")\n version = record.get(\"recordVersion\", \"1.0.0\")\n\n # Parse custom content\n custom_desc = descriptors.get(\"custom\", {})\n custom_content = _safe_parse_json(\n custom_desc.get(\"inlineContent\", \"{}\"),\n context=f\"CUSTOM descriptor for {record_name}\",\n )\n\n path_segment = _sanitize_path_segment(record_name)\n agent_path = f\"/agents/agentcore-custom-{path_segment}\"\n\n # Use our own agent detail endpoint as the URL\n from registry.core.config import settings\n\n agent_url = f\"{settings.registry_url}/api{agent_path}\"\n original_url = (\n custom_content.get(\"url\")\n or custom_content.get(\"endpoint\")\n or custom_content.get(\"baseUrl\")\n )\n\n tags = [\n \"agentcore\",\n \"bedrock\",\n \"federated\",\n \"custom\",\n f\"registry-{registry_id[:12]}\",\n ]\n\n # Map custom provider to AgentProvider format (needs organization + url)\n raw_provider = custom_content.get(\"provider\")\n provider_data = None\n if isinstance(raw_provider, dict):\n org = raw_provider.get(\"organization\") or raw_provider.get(\"name\", \"\")\n provider_url = raw_provider.get(\"url\", \"\")\n if org and provider_url:\n provider_data = {\"organization\": org, \"url\": provider_url}\n\n # Extract AWS timestamps (datetime objects from boto3)\n created_at = record.get(\"createdAt\")\n updated_at = record.get(\"lastUpdatedAt\")\n\n # Extract record ARN and status for CUSTOM card display\n record_arn = record.get(\"recordArn\", \"\")\n record_status = record.get(\"status\", \"\")\n\n return {\n \"source\": AGENTCORE_SOURCE,\n \"name\": record_name,\n \"description\": description or \"Custom protocol record\",\n \"url\": agent_url,\n \"path\": agent_path,\n \"version\": version,\n \"protocol_version\": \"1.0\",\n \"capabilities\": custom_content.get(\"capabilities\", {}),\n \"skills\": [],\n \"provider\": provider_data,\n \"security_schemes\": {},\n \"default_input_modes\": [\"text/plain\"],\n \"default_output_modes\": [\"text/plain\"],\n \"tags\": tags,\n \"is_enabled\": True,\n \"is_read_only\": True,\n \"attribution_label\": AGENTCORE_ATTRIBUTION,\n \"supported_protocol\": \"other\",\n \"metadata\": {\n \"agentcore_registry_id\": registry_id,\n \"agentcore_record_id\": record_id,\n \"descriptor_type\": \"CUSTOM\",\n \"custom_content\": custom_content,\n \"original_url\": original_url,\n \"record_arn\": record_arn,\n \"record_status\": record_status,\n \"created_at\": created_at.isoformat() if created_at else None,\n \"updated_at\": updated_at.isoformat() if updated_at else None,\n },\n \"cached_at\": datetime.now(UTC).isoformat(),\n }\n\n def _transform_skills_record(\n self,\n record: dict[str, Any],\n descriptors: dict[str, Any],\n registry_id: str,\n ) -> dict[str, Any]:\n \"\"\"Transform AGENT_SKILLS descriptor record to skill registration data.\n\n Uses a self-referencing URL for skill_md_url and stores inline\n markdown content in skill_md_content for DB storage.\n\n Args:\n record: Full AgentCore record\n descriptors: Descriptors section\n registry_id: Source registry ID\n\n Returns:\n Skill data dict for SkillService registration\n \"\"\"\n record_name = record.get(\"name\", \"\")\n record_id = record.get(\"recordId\", \"\")\n description = record.get(\"description\", \"\")\n version = record.get(\"recordVersion\", \"1.0.0\")\n\n # Sanitize name for SkillCard: lowercase alphanumeric and hyphens only\n sanitized_name = record_name.replace(\"_\", \"-\").replace(\" \", \"-\").lower().strip(\"-\")\n\n # Parse skill descriptors\n skills_desc = descriptors.get(\"agentSkills\", {})\n skill_md_content = skills_desc.get(\"skillMd\", {}).get(\"inlineContent\", \"\")\n skill_def_content = _safe_parse_json(\n skills_desc.get(\"skillDefinition\", {}).get(\"inlineContent\", \"{}\"),\n context=f\"AGENT_SKILLS definition for {record_name}\",\n )\n\n path_segment = _sanitize_path_segment(record_name)\n skill_path = f\"/skills/agentcore-{path_segment}\"\n\n # Build self-referencing URL for skill_md_url\n from registry.core.config import settings\n\n skill_md_url = f\"{settings.registry_url}/api/skills/agentcore-{path_segment}/content\"\n\n # Extract fields from skill definition\n if not description:\n description = skill_def_content.get(\"description\", \"\")\n\n target_agents = skill_def_content.get(\"targetAgents\", [])\n allowed_tools = skill_def_content.get(\"allowedTools\", [])\n\n tags = [\n \"agentcore\",\n \"bedrock\",\n \"federated\",\n \"skill\",\n f\"registry-{registry_id[:12]}\",\n ]\n\n # Extract AWS timestamps (datetime objects from boto3)\n created_at = record.get(\"createdAt\")\n updated_at = record.get(\"lastUpdatedAt\")\n\n return {\n \"source\": AGENTCORE_SOURCE,\n \"name\": sanitized_name,\n \"description\": description,\n \"skill_md_url\": skill_md_url,\n \"skill_md_content\": skill_md_content,\n \"path\": skill_path,\n \"version\": version,\n \"tags\": tags,\n \"target_agents\": target_agents,\n \"allowed_tools\": allowed_tools,\n \"is_enabled\": True,\n \"is_read_only\": True,\n \"attribution_label\": AGENTCORE_ATTRIBUTION,\n \"registry_name\": AGENTCORE_SOURCE,\n \"metadata\": {\n \"agentcore_registry_id\": registry_id,\n \"agentcore_record_id\": record_id,\n \"descriptor_type\": \"AGENT_SKILLS\",\n \"skill_definition\": skill_def_content,\n \"created_at\": created_at.isoformat() if created_at else None,\n \"updated_at\": updated_at.isoformat() if updated_at else None,\n },\n \"cached_at\": datetime.now(UTC).isoformat(),\n }\n\n # BaseFederationClient interface methods (for compatibility)\n\n def fetch_server(\n self,\n server_name: str,\n **kwargs: Any,\n ) -> dict[str, Any] | None:\n \"\"\"Fetch a single server record by name.\n\n Not the primary usage pattern -- prefer fetch_all_records().\n\n Args:\n server_name: Record name to search for\n\n Returns:\n Server data dict or None\n \"\"\"\n registry_id = kwargs.get(\"registry_id\", \"\")\n if not registry_id:\n logger.error(\"registry_id required for AgentCore fetch_server\")\n return None\n\n records = self.list_registry_records(\n registry_id=registry_id,\n descriptor_type=\"MCP\",\n )\n\n for rec in records:\n if rec.get(\"name\") == server_name:\n full_record = self.get_registry_record(registry_id, rec[\"recordId\"])\n if full_record:\n return self._transform_record(full_record, registry_id)\n\n return None\n\n def fetch_all_servers(\n self,\n server_names: list[str],\n **kwargs: Any,\n ) -> list[dict[str, Any]]:\n \"\"\"Fetch multiple servers by name.\n\n Args:\n server_names: List of record names to fetch\n\n Returns:\n List of server data dicts\n \"\"\"\n registry_id = kwargs.get(\"registry_id\", \"\")\n if not registry_id:\n logger.error(\"registry_id required for AgentCore fetch_all_servers\")\n return []\n\n records = self.list_registry_records(\n registry_id=registry_id,\n descriptor_type=\"MCP\",\n )\n\n servers: list[dict[str, Any]] = []\n name_set = set(server_names)\n for rec in records:\n if rec.get(\"name\") in name_set:\n full_record = self.get_registry_record(registry_id, rec[\"recordId\"])\n if full_record:\n transformed = self._transform_record(full_record, registry_id)\n if transformed:\n servers.append(transformed)\n\n return servers\n" }, { "path": "registry/services/federation/anthropic_client.py", "content": "\"\"\"\nAnthropic MCP Registry federation client.\n\nFetches server configurations from Anthropic's MCP Registry API\nand transforms them to the gateway's internal format.\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom typing import Any\nfrom urllib.parse import quote\n\nfrom ...schemas.federation_schema import AnthropicServerConfig\nfrom .base_client import BaseFederationClient\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass AnthropicFederationClient(BaseFederationClient):\n \"\"\"Client for fetching servers from Anthropic MCP Registry.\"\"\"\n\n def __init__(\n self,\n endpoint: str,\n api_version: str = \"v0.1\",\n timeout_seconds: int = 30,\n retry_attempts: int = 3,\n ):\n \"\"\"\n Initialize Anthropic federation client.\n\n Args:\n endpoint: Base URL for Anthropic MCP Registry API\n api_version: API version to use (default: v0.1)\n timeout_seconds: HTTP request timeout\n retry_attempts: Number of retry attempts\n \"\"\"\n super().__init__(endpoint, timeout_seconds, retry_attempts)\n self.api_version = api_version\n\n def fetch_server(\n self, server_name: str, server_config: AnthropicServerConfig | None = None\n ) -> dict[str, Any] | None:\n \"\"\"\n Fetch a single server from Anthropic Registry.\n\n Args:\n server_name: Server name in Anthropic format (e.g., ai.smithery/github)\n server_config: Optional server configuration with auth details\n\n Returns:\n Server data dictionary or None if fetch fails\n \"\"\"\n # URL-encode server name (replace / with %2F)\n encoded_name = quote(server_name, safe=\"\")\n url = f\"{self.endpoint}/{self.api_version}/servers/{encoded_name}/versions/latest\"\n\n # Build headers\n headers = {\"Content-Type\": \"application/json\"}\n\n # No authentication for public Anthropic registry\n\n # Make request\n logger.info(f\"Fetching server {server_name} from Anthropic Registry\")\n response = self._make_request(url, headers=headers)\n\n if not response:\n logger.error(f\"Failed to fetch server {server_name}\")\n return None\n\n # Transform response to internal format\n return self._transform_server_response(response, server_name, server_config)\n\n def fetch_all_servers(\n self, server_configs: list[AnthropicServerConfig]\n ) -> list[dict[str, Any]]:\n \"\"\"\n Fetch multiple servers from Anthropic Registry.\n\n Args:\n server_configs: List of server configurations\n\n Returns:\n List of server data dictionaries\n \"\"\"\n servers = []\n\n for config in server_configs:\n server_data = self.fetch_server(config.name, config)\n if server_data:\n servers.append(server_data)\n else:\n logger.warning(f\"Failed to fetch server: {config.name}\")\n\n logger.info(f\"Successfully fetched {len(servers)}/{len(server_configs)} servers\")\n return servers\n\n def _transform_server_response(\n self,\n response: dict[str, Any],\n server_name: str,\n server_config: AnthropicServerConfig | None,\n ) -> dict[str, Any]:\n \"\"\"\n Transform Anthropic API response to internal gateway format.\n\n Args:\n response: Raw response from Anthropic API\n server_name: Server name\n server_config: Optional server configuration\n\n Returns:\n Transformed server data\n \"\"\"\n # Extract server details from response\n server = response.get(\"server\", {})\n\n # Get basic info\n description = server.get(\"description\", \"\")\n version = server.get(\"version\", \"1.0.0\")\n title = server.get(\"title\", server_name)\n\n # Extract transport info - handle both old (packages) and new (remotes) schema\n transport_type = \"streamable-http\"\n proxy_url = None\n\n # Try new schema format (remotes)\n remotes = server.get(\"remotes\", [])\n if remotes:\n remote = remotes[0]\n transport_type = remote.get(\"type\", \"streamable-http\")\n proxy_url = remote.get(\"url\")\n else:\n # Fallback to old schema format (packages)\n packages = server.get(\"packages\", [])\n if packages:\n package = packages[0]\n transport = package.get(\"transport\", {})\n transport_type = transport.get(\"type\", \"streamable-http\")\n # Only set URL for HTTP-based transports\n if transport_type in [\"streamable-http\", \"http\"]:\n proxy_url = transport.get(\"url\")\n # stdio and other transports don't have URLs\n\n # Extract tags from metadata if available\n tags = []\n metadata = server.get(\"_meta\", {})\n for key, value in metadata.items():\n if isinstance(value, dict):\n internal_tags = value.get(\"tags\", [])\n if internal_tags:\n tags.extend(internal_tags)\n\n # Add default tags from server name\n name_parts = server_name.split(\"/\")\n if len(name_parts) > 1:\n tags.extend([name_parts[0], name_parts[1]])\n tags.append(\"anthropic-registry\")\n tags.append(\"federated\")\n\n # Build transformed server object\n transformed = {\n \"source\": \"anthropic\",\n \"server_name\": server_name,\n \"description\": description,\n \"version\": version,\n \"title\": title,\n \"proxy_pass_url\": proxy_url,\n \"transport_type\": transport_type,\n \"requires_auth\": False,\n \"auth_headers\": [],\n \"tags\": list(set(tags)), # Remove duplicates\n \"metadata\": {\"original_response\": response, \"config_metadata\": {}},\n \"cached_at\": datetime.now(UTC).isoformat(),\n \"is_read_only\": True,\n \"attribution_label\": \"Anthropic MCP Registry\",\n # Additional fields for compatibility\n \"path\": f\"/{server_name.replace('/', '-')}\",\n \"is_enabled\": True,\n \"health_status\": \"unknown\", # Will be updated by health checks\n \"num_tools\": 0, # Will be updated if we can query the server\n }\n\n return transformed\n" }, { "path": "registry/services/federation/asor_client.py", "content": "\"\"\"\nWorkday ASOR (Agent Service Operating Registry) federation client.\n\nFetches agent configurations from Workday ASOR API and transforms them\nto the gateway's internal format.\n\"\"\"\n\nimport logging\nimport os\nfrom datetime import UTC, datetime\nfrom typing import Any\n\nfrom registry.core.config import settings\n\nfrom ...schemas.federation_schema import AsorAgentConfig\nfrom .base_client import BaseFederationClient\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass AsorFederationClient(BaseFederationClient):\n \"\"\"Client for fetching agents from Workday ASOR.\"\"\"\n\n def __init__(\n self,\n endpoint: str,\n auth_type: str = \"oauth2\",\n auth_env_var: str | None = None,\n tenant_url: str | None = None,\n timeout_seconds: int = 30,\n retry_attempts: int = 3,\n ):\n \"\"\"\n Initialize ASOR federation client.\n\n Args:\n endpoint: Base URL for ASOR API\n auth_type: Authentication type (oauth2, api-key)\n auth_env_var: Environment variable containing auth credentials\n tenant_url: Workday tenant URL (for authentication)\n timeout_seconds: HTTP request timeout\n retry_attempts: Number of retry attempts\n \"\"\"\n super().__init__(endpoint, timeout_seconds, retry_attempts)\n self.auth_type = auth_type\n self.auth_env_var = auth_env_var\n self.tenant_url = tenant_url\n self._access_token: str | None = None\n self._token_expiry: datetime | None = None\n\n def _get_access_token(self) -> str | None:\n \"\"\"\n Get or refresh OAuth2 access token from Workday.\n\n Returns:\n Access token or None if authentication fails\n \"\"\"\n # Always check for pre-obtained access token first (for 3LO scenarios)\n access_token_env = os.getenv(\"ASOR_ACCESS_TOKEN\")\n if access_token_env:\n logger.info(\"Using pre-obtained ASOR access token from environment\")\n logger.debug(f\"Token starts with: {access_token_env[:10]}...\")\n self._access_token = access_token_env\n # Set a reasonable expiry (1 hour from now)\n self._token_expiry = datetime.now(UTC).replace(microsecond=0) + timedelta(hours=1)\n return self._access_token\n\n # Check if we have a valid cached token (only for client credentials)\n if self._access_token and self._token_expiry:\n if datetime.now(UTC) < self._token_expiry:\n logger.debug(\"Using cached access token\")\n return self._access_token\n\n # Get credentials from environment\n if self.auth_env_var:\n credentials = os.getenv(self.auth_env_var)\n if credentials:\n # Parse credentials (format: client_id:client_secret or client_id:client_secret:refresh_token)\n try:\n parts = credentials.split(\":\")\n if len(parts) >= 2:\n client_id, client_secret = parts[0], parts[1]\n # Ignore any additional parts (like refresh token)\n else:\n raise ValueError(\"Invalid credentials format\")\n # Decode base64 client_id if needed\n try:\n import base64\n\n decoded_client_id = base64.b64decode(client_id).decode(\"utf-8\")\n client_id = decoded_client_id\n logger.info(f\"Decoded base64 client_id: {client_id}\")\n except Exception:\n # If decoding fails, use original client_id\n logger.info(f\"Using original client_id: {client_id}\")\n except ValueError:\n logger.error(\"ASOR credentials must be in format 'client_id:client_secret'\")\n return None\n else:\n logger.error(f\"Environment variable {self.auth_env_var} not found\")\n return None\n else:\n logger.error(\"No auth_env_var configured for ASOR\")\n return None\n\n # Request token from Workday - use tenant-specific URL from config\n token_url = settings.workday_token_url\n\n # Check if using placeholder URL (exact match to avoid false positive security warning)\n # This is not a security check - we're validating our own config default, not user input\n PLACEHOLDER_URL = \"https://your-tenant.workday.com/ccx/oauth2/your_instance/token\"\n if token_url == PLACEHOLDER_URL:\n logger.warning(\n \"WORKDAY_TOKEN_URL is using placeholder value. \"\n \"ASOR federation is disabled. \"\n \"Set WORKDAY_TOKEN_URL environment variable to your actual Workday tenant URL to enable ASOR federation. \"\n \"Example: https://services.wd101.myworkday.com/ccx/oauth2/instance_name/token\"\n )\n return None\n\n logger.info(f\"Requesting access token from Workday: {token_url}\")\n\n # Use Basic Auth like agentcore integration\n import base64\n\n credentials = f\"{client_id}:{client_secret}\"\n credentials_b64 = base64.b64encode(credentials.encode()).decode()\n\n headers = {\n \"Authorization\": f\"Basic {credentials_b64}\",\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n data = {\"grant_type\": \"client_credentials\"}\n\n try:\n response = self.client.post(token_url, data=data, headers=headers)\n response.raise_for_status()\n token_data = response.json()\n\n self._access_token = token_data.get(\"access_token\")\n expires_in = token_data.get(\"expires_in\", 3600)\n\n # Set expiry slightly before actual expiry (5 min buffer)\n self._token_expiry = datetime.now(UTC).replace(microsecond=0) + timedelta(\n seconds=expires_in - 300\n )\n\n logger.info(f\"Successfully obtained access token (expires in {expires_in}s)\")\n return self._access_token\n\n except Exception as e:\n logger.error(f\"Failed to obtain access token via client credentials: {e}\")\n logger.info(\"ASOR typically requires 3-legged OAuth. To use ASOR federation:\")\n logger.info(\"1. Run the test_asor_complete.py script to get an access token\")\n logger.info(\"2. Set the ASOR_ACCESS_TOKEN environment variable with the token\")\n logger.info(\"3. Restart the registry to use the pre-obtained token\")\n return None\n\n def fetch_agent(\n self, agent_id: str, agent_config: AsorAgentConfig | None = None\n ) -> dict[str, Any] | None:\n \"\"\"\n Fetch a single agent from ASOR.\n\n Args:\n agent_id: Agent ID in ASOR\n agent_config: Optional agent configuration\n\n Returns:\n Agent data dictionary or None if fetch fails\n \"\"\"\n # Use direct ASOR API endpoint\n url = f\"{self.endpoint}/agentDefinition/{agent_id}\"\n\n # Get access token\n access_token = self._get_access_token()\n if not access_token:\n logger.error(\"Failed to authenticate with Workday\")\n return None\n\n logger.debug(\"Using access token for API call\")\n\n # Build headers - match working test script format\n headers = {\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json\",\n \"Authorization\": f\"Bearer {access_token}\",\n }\n\n # Make request\n logger.info(f\"Fetching agent {agent_id} from ASOR\")\n response = self._make_request(url, headers=headers)\n\n if not response:\n logger.error(f\"Failed to fetch agent {agent_id}\")\n return None\n\n # Transform response to internal format\n return self._transform_agent_response(response, agent_id, agent_config)\n\n def list_all_agents(self) -> list[dict[str, Any]]:\n \"\"\"\n List all agent definitions from ASOR.\n\n Returns:\n List of all agent definitions\n \"\"\"\n # ASOR API: GET /asor/v1/agentDefinition (singular, per OpenAPI spec)\n url = f\"{self.endpoint}/agentDefinition\"\n\n # Get access token\n access_token = self._get_access_token()\n if not access_token:\n logger.error(\"Failed to authenticate with Workday\")\n return []\n\n logger.debug(f\"ASOR DEBUG - URL: {url}\")\n logger.debug(f\"ASOR DEBUG - Endpoint: {self.endpoint}\")\n\n # Build headers - match working test script format\n headers = {\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json\",\n \"Authorization\": f\"Bearer {access_token}\",\n }\n\n logger.debug(\"ASOR DEBUG - Headers prepared (Authorization redacted)\")\n\n # Make request\n logger.info(\"Listing all agents from ASOR\")\n response = self._make_request(url, method=\"GET\", headers=headers)\n\n if not response:\n logger.error(\"Failed to list agents\")\n return []\n\n # Response should be a list of agent definitions or wrapped in data field\n if isinstance(response, dict) and \"data\" in response:\n agents = response[\"data\"]\n total = response.get(\"total\", len(agents))\n logger.info(f\"Found {total} agents in ASOR (from data field)\")\n elif isinstance(response, list):\n agents = response\n logger.info(f\"Found {len(agents)} agents in ASOR (direct list)\")\n else:\n agents = []\n logger.warning(f\"Unexpected ASOR response format: {type(response)}\")\n\n return agents\n\n def fetch_all_agents(self, agent_configs: list[AsorAgentConfig]) -> list[dict[str, Any]]:\n \"\"\"\n Fetch multiple agents from ASOR.\n\n Args:\n agent_configs: List of agent configurations\n\n Returns:\n List of agent data dictionaries\n \"\"\"\n agents = []\n\n # If no configs provided, list all agents\n if not agent_configs:\n logger.info(\"No agent configs provided, listing all agents from ASOR\")\n return self.list_all_agents()\n\n for config in agent_configs:\n agent_data = self.fetch_agent(config.id, config)\n if agent_data:\n agents.append(agent_data)\n else:\n logger.warning(f\"Failed to fetch agent: {config.id}\")\n\n logger.info(f\"Successfully fetched {len(agents)}/{len(agent_configs)} agents\")\n return agents\n\n def fetch_server(self, server_name: str, **kwargs) -> dict[str, Any] | None:\n \"\"\"\n Fetch a single server (agent) from ASOR.\n\n Args:\n server_name: Agent ID\n **kwargs: Additional parameters\n\n Returns:\n Server data dictionary\n \"\"\"\n return self.fetch_agent(server_name, kwargs.get(\"agent_config\"))\n\n def fetch_all_servers(self, server_names: list[str], **kwargs) -> list[dict[str, Any]]:\n \"\"\"\n Fetch multiple servers (agents) from ASOR.\n\n Args:\n server_names: List of agent IDs\n **kwargs: Additional parameters\n\n Returns:\n List of server data dictionaries\n \"\"\"\n # Convert server names to agent configs\n agent_configs = [AsorAgentConfig(id=name) for name in server_names]\n return self.fetch_all_agents(agent_configs)\n\n def _transform_agent_response(\n self, response: dict[str, Any], agent_id: str, agent_config: AsorAgentConfig | None\n ) -> dict[str, Any]:\n \"\"\"\n Transform ASOR API response to internal gateway format.\n\n Args:\n response: Raw response from ASOR API\n agent_id: Agent ID\n agent_config: Optional agent configuration\n\n Returns:\n Transformed agent data\n \"\"\"\n # Extract agent details from response\n # Note: Adjust field names based on actual ASOR API response structure\n name = response.get(\"name\", agent_id)\n description = response.get(\"description\", \"\")\n version = response.get(\"version\", \"1.0.0\")\n\n # Extract endpoint/URL\n endpoint = response.get(\"endpoint\") or response.get(\"url\")\n\n # Extract capabilities\n capabilities = response.get(\"capabilities\", [])\n tools = response.get(\"tools\", [])\n\n # Generate tags\n tags = [\"asor\", \"workday\", \"federated\"]\n # Build transformed agent object\n transformed = {\n \"source\": \"asor\",\n \"server_name\": f\"asor/{agent_id}\",\n \"description\": description,\n \"version\": version,\n \"title\": name,\n \"proxy_pass_url\": endpoint,\n \"transport_type\": \"streamable-http\", # Assume HTTP transport\n \"requires_auth\": True, # ASOR agents likely require auth\n \"auth_headers\": [], # Auth handled by gateway\n \"tags\": tags,\n \"metadata\": {\n \"original_response\": response,\n \"agent_id\": agent_id,\n \"capabilities\": capabilities,\n \"tools\": tools,\n \"config_metadata\": {},\n },\n \"cached_at\": datetime.now(UTC).isoformat(),\n \"is_read_only\": True,\n \"attribution_label\": \"ASOR\",\n # Additional fields for compatibility\n \"path\": f\"/asor-{agent_id}\",\n \"is_enabled\": True,\n \"health_status\": \"unknown\",\n \"num_tools\": len(tools) if tools else 0,\n }\n\n return transformed\n\n\n# Import timedelta for token expiry calculation\nfrom datetime import timedelta\n" }, { "path": "registry/services/federation/base_client.py", "content": "\"\"\"\nBase federation client interface.\n\nProvides common functionality for all federation clients.\n\"\"\"\n\nimport logging\nfrom abc import ABC, abstractmethod\nfrom typing import Any\n\nimport httpx\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass BaseFederationClient(ABC):\n \"\"\"Base class for federation clients.\"\"\"\n\n def __init__(self, endpoint: str, timeout_seconds: int = 30, retry_attempts: int = 3):\n \"\"\"\n Initialize federation client.\n\n Args:\n endpoint: Base URL for the federation API\n timeout_seconds: HTTP request timeout\n retry_attempts: Number of retry attempts for failed requests\n \"\"\"\n self.endpoint = endpoint.rstrip(\"/\")\n self.timeout_seconds = timeout_seconds\n self.retry_attempts = retry_attempts\n self.client = httpx.Client(timeout=timeout_seconds)\n\n def __del__(self):\n \"\"\"Clean up HTTP client.\"\"\"\n if hasattr(self, \"client\"):\n self.client.close()\n\n @abstractmethod\n def fetch_server(self, server_name: str, **kwargs) -> dict[str, Any] | None:\n \"\"\"\n Fetch a single server from the federated registry.\n\n Args:\n server_name: Name of the server to fetch\n **kwargs: Additional parameters specific to the federation source\n\n Returns:\n Server data dictionary or None if fetch fails\n \"\"\"\n pass\n\n @abstractmethod\n def fetch_all_servers(self, server_names: list[str], **kwargs) -> list[dict[str, Any]]:\n \"\"\"\n Fetch multiple servers from the federated registry.\n\n Args:\n server_names: List of server names to fetch\n **kwargs: Additional parameters specific to the federation source\n\n Returns:\n List of server data dictionaries\n \"\"\"\n pass\n\n def _make_request(\n self,\n url: str,\n method: str = \"GET\",\n headers: dict[str, str] | None = None,\n params: dict[str, Any] | None = None,\n data: dict[str, Any] | None = None,\n ) -> dict[str, Any] | None:\n \"\"\"\n Make HTTP request with retry logic.\n\n Args:\n url: Full URL to request\n method: HTTP method (GET, POST, etc.)\n headers: HTTP headers\n params: Query parameters\n data: Request body data\n\n Returns:\n Response JSON or None if request fails\n \"\"\"\n for attempt in range(self.retry_attempts):\n try:\n logger.debug(\n f\"Making {method} request to {url} (attempt {attempt + 1}/{self.retry_attempts})\"\n )\n\n response = self.client.request(\n method=method, url=url, headers=headers, params=params, json=data\n )\n\n response.raise_for_status()\n return response.json()\n\n except httpx.HTTPStatusError as e:\n logger.error(f\"HTTP error {e.response.status_code} for {url}: {e}\")\n if e.response.status_code in [404, 401, 403]:\n # Don't retry for these errors\n return None\n if attempt == self.retry_attempts - 1:\n return None\n\n except httpx.RequestError as e:\n logger.error(f\"Request error for {url}: {e}\")\n if attempt == self.retry_attempts - 1:\n return None\n\n except Exception as e:\n logger.error(f\"Unexpected error for {url}: {e}\")\n if attempt == self.retry_attempts - 1:\n return None\n\n return None\n" }, { "path": "registry/services/federation/federation_auth.py", "content": "\"\"\"\nFederation authentication manager.\n\nSingleton class for managing OAuth2 client credentials authentication\nfor peer registry federation. Handles token caching and automatic refresh.\n\"\"\"\n\nimport logging\nimport os\nfrom datetime import UTC, datetime, timedelta\nfrom threading import Lock\nfrom typing import Optional\n\nimport httpx\n\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nTOKEN_REFRESH_BUFFER_SECONDS: int = 60\nDEFAULT_TOKEN_TIMEOUT_SECONDS: int = 30\n\n\nclass FederationAuthManager:\n \"\"\"\n Singleton authentication manager for federation clients.\n\n Handles OAuth2 client credentials flow with token caching and\n expiry-aware refresh. Thread-safe for concurrent access.\n \"\"\"\n\n _instance: Optional[\"FederationAuthManager\"] = None\n _lock: Lock = Lock()\n\n def __new__(cls) -> \"FederationAuthManager\":\n \"\"\"Create singleton instance.\"\"\"\n if cls._instance is None:\n with cls._lock:\n if cls._instance is None:\n cls._instance = super().__new__(cls)\n cls._instance._initialized = False\n return cls._instance\n\n def __init__(self):\n \"\"\"Initialize authentication manager.\"\"\"\n if self._initialized:\n return\n\n self._initialized = True\n self._access_token: str | None = None\n self._token_expiry: datetime | None = None\n self._token_lock = Lock()\n\n # Get configuration from environment\n self._token_endpoint = os.getenv(\"FEDERATION_TOKEN_ENDPOINT\")\n self._client_id = os.getenv(\"FEDERATION_CLIENT_ID\")\n self._client_secret = os.getenv(\"FEDERATION_CLIENT_SECRET\")\n\n # Validate configuration at startup\n self._validate_config()\n\n # HTTP client for token requests\n self._http_client = httpx.Client(timeout=DEFAULT_TOKEN_TIMEOUT_SECONDS)\n\n logger.info(\"FederationAuthManager initialized\")\n\n def _validate_config(self) -> None:\n \"\"\"\n Validate required environment variables are present.\n\n Logs clear warnings if configuration is missing but doesn't\n raise exceptions (to allow registry to start without federation).\n \"\"\"\n missing = []\n\n if not self._token_endpoint:\n missing.append(\"FEDERATION_TOKEN_ENDPOINT\")\n if not self._client_id:\n missing.append(\"FEDERATION_CLIENT_ID\")\n if not self._client_secret:\n missing.append(\"FEDERATION_CLIENT_SECRET\")\n\n if missing:\n logger.warning(\n f\"Federation authentication not configured. Missing environment variables: {', '.join(missing)}\"\n )\n logger.warning(\n \"Peer registry federation will not be available until these variables are set.\"\n )\n logger.info(\"To enable federation, set the following environment variables:\")\n for var in missing:\n logger.info(f\" - {var}\")\n else:\n logger.info(\n f\"Federation authentication configured. Token endpoint: {self._token_endpoint}\"\n )\n\n def is_configured(self) -> bool:\n \"\"\"\n Check if federation authentication is properly configured.\n\n Returns:\n True if all OAuth2 variables are set\n \"\"\"\n return all(\n [\n self._token_endpoint,\n self._client_id,\n self._client_secret,\n ]\n )\n\n def get_token(self) -> str | None:\n \"\"\"\n Get valid access token for federation API calls.\n\n Returns cached OAuth2 token if still valid (with 60s buffer),\n or requests a new token via client credentials flow.\n\n Returns:\n Access token or None if authentication fails\n\n Raises:\n ValueError: If federation authentication is not configured\n \"\"\"\n if not self.is_configured():\n raise ValueError(\n \"Federation authentication not configured. \"\n \"Set FEDERATION_TOKEN_ENDPOINT, FEDERATION_CLIENT_ID, \"\n \"and FEDERATION_CLIENT_SECRET environment variables.\"\n )\n\n with self._token_lock:\n # Check if cached token is still valid\n if self._is_token_valid():\n logger.debug(\"Using cached access token\")\n return self._access_token\n\n # Request new token\n logger.info(\"Requesting new access token for federation\")\n return self._refresh_token()\n\n def _is_token_valid(self) -> bool:\n \"\"\"\n Check if cached token is still valid.\n\n Returns:\n True if token exists and hasn't expired (with buffer)\n \"\"\"\n if not self._access_token or not self._token_expiry:\n return False\n\n # Check if token expires within buffer period\n now = datetime.now(UTC)\n buffer_time = self._token_expiry - timedelta(seconds=TOKEN_REFRESH_BUFFER_SECONDS)\n\n return now < buffer_time\n\n def _refresh_token(self) -> str | None:\n \"\"\"\n Request new access token via OAuth2 client credentials flow.\n\n Returns:\n Access token or None if request fails\n \"\"\"\n try:\n # Build token request\n headers = {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n \"Accept\": \"application/json\",\n }\n\n data = {\n \"grant_type\": \"client_credentials\",\n \"client_id\": self._client_id,\n \"client_secret\": self._client_secret,\n }\n\n logger.debug(f\"Requesting token from {self._token_endpoint}\")\n\n # Make token request\n response = self._http_client.post(\n self._token_endpoint,\n data=data,\n headers=headers,\n )\n\n response.raise_for_status()\n token_data = response.json()\n\n # Extract token and expiry\n self._access_token = token_data.get(\"access_token\")\n expires_in = token_data.get(\"expires_in\", 3600)\n\n if not self._access_token:\n logger.error(\"Token response missing access_token field\")\n return None\n\n # Set expiry time\n self._token_expiry = datetime.now(UTC) + timedelta(seconds=expires_in)\n\n logger.info(f\"Successfully obtained access token (expires in {expires_in}s)\")\n return self._access_token\n\n except httpx.HTTPStatusError as e:\n logger.error(f\"HTTP error obtaining access token: {e.response.status_code} - {e}\")\n if e.response.status_code in [401, 403]:\n logger.error(\n \"Authentication failed. Check FEDERATION_CLIENT_ID and \"\n \"FEDERATION_CLIENT_SECRET are correct.\"\n )\n return None\n\n except httpx.RequestError as e:\n logger.error(f\"Network error obtaining access token: {e}\")\n logger.error(f\"Token endpoint: {self._token_endpoint}\")\n return None\n\n except Exception as e:\n logger.error(f\"Unexpected error obtaining access token: {e}\")\n return None\n\n def clear_token(self) -> None:\n \"\"\"\n Clear cached token.\n\n Useful for forcing a token refresh or clearing expired tokens.\n \"\"\"\n with self._token_lock:\n self._access_token = None\n self._token_expiry = None\n logger.info(\"Cleared cached access token\")\n\n def __del__(self):\n \"\"\"Clean up HTTP client on deletion.\"\"\"\n if hasattr(self, \"_http_client\"):\n self._http_client.close()\n" }, { "path": "registry/services/federation/peer_registry_client.py", "content": "\"\"\"\nPeer registry federation client.\n\nFetches servers and agents from peer registries using the standard\nfederation API endpoints with JWT authentication.\n\"\"\"\n\nimport logging\nfrom typing import Any\n\nfrom ...schemas.peer_federation_schema import PeerRegistryConfig\nfrom .base_client import BaseFederationClient\nfrom .federation_auth import FederationAuthManager\n\nlogger = logging.getLogger(__name__)\n\n\nclass PeerRegistryClient(BaseFederationClient):\n \"\"\"Client for fetching servers and agents from peer registries.\"\"\"\n\n def __init__(\n self, peer_config: PeerRegistryConfig, timeout_seconds: int = 30, retry_attempts: int = 3\n ):\n \"\"\"\n Initialize peer registry client.\n\n Args:\n peer_config: Configuration for the peer registry\n timeout_seconds: HTTP request timeout\n retry_attempts: Number of retry attempts for failed requests\n \"\"\"\n super().__init__(peer_config.endpoint, timeout_seconds, retry_attempts)\n self.peer_config = peer_config\n\n # Per-peer federation static token takes priority over global OAuth2\n self._federation_token = peer_config.federation_token\n self._auth_manager = FederationAuthManager()\n\n # Validate auth is configured (either per-peer token or global OAuth2)\n if self._federation_token:\n logger.info(f\"Using per-peer federation static token for peer '{peer_config.peer_id}'\")\n elif not self._auth_manager.is_configured():\n logger.warning(\n f\"Federation authentication not configured for peer '{peer_config.peer_id}'. \"\n \"Set federation_token in peer config, or set FEDERATION_TOKEN_ENDPOINT, \"\n \"FEDERATION_CLIENT_ID, and FEDERATION_CLIENT_SECRET environment variables.\"\n )\n\n logger.info(\n f\"Initialized PeerRegistryClient for peer '{peer_config.peer_id}' \"\n f\"at {peer_config.endpoint}\"\n )\n\n def _get_auth_token(self) -> str | None:\n \"\"\"Get authentication token for this peer.\n\n Uses per-peer federation static token if configured,\n otherwise falls back to global OAuth2 FederationAuthManager.\n\n Returns:\n Bearer token string, or None if auth fails.\n\n Raises:\n ValueError: If no authentication method is configured.\n \"\"\"\n # Per-peer federation static token takes priority\n if self._federation_token:\n return self._federation_token\n\n # Fall back to global OAuth2 auth manager\n return self._auth_manager.get_token()\n\n def fetch_servers(self, since_generation: int | None = None) -> list[dict[str, Any]] | None:\n \"\"\"\n Fetch servers from peer registry.\n\n Args:\n since_generation: Optional generation number for incremental sync.\n If provided, only returns servers updated since that generation.\n\n Returns:\n List of server dictionaries or None if fetch fails\n \"\"\"\n # Build URL\n url = f\"{self.endpoint}/api/federation/servers\"\n\n # Get authentication token\n try:\n token = self._get_auth_token()\n except ValueError as e:\n logger.error(f\"Cannot fetch servers: {e}\")\n return None\n\n if not token:\n logger.error(\n f\"Failed to obtain authentication token for peer '{self.peer_config.peer_id}'\"\n )\n return None\n\n # Build headers\n headers = {\n \"Authorization\": f\"Bearer {token}\",\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json\",\n }\n\n # Build query parameters\n params = {}\n if since_generation is not None:\n params[\"since_generation\"] = since_generation\n\n # Make request\n logger.info(\n f\"Fetching servers from peer '{self.peer_config.peer_id}' \"\n f\"(since_generation={since_generation})\"\n )\n\n response = self._make_request(url, headers=headers, params=params)\n\n if not response:\n logger.error(f\"Failed to fetch servers from peer '{self.peer_config.peer_id}'\")\n return None\n\n # Extract items from response\n # Expected format: {\"items\": [...], \"sync_generation\": N, ...}\n if isinstance(response, dict):\n items = response.get(\"items\", [])\n sync_generation = response.get(\"sync_generation\", 0)\n total_count = response.get(\"total_count\", len(items))\n\n logger.info(\n f\"Successfully fetched {len(items)} servers from peer \"\n f\"'{self.peer_config.peer_id}' (generation={sync_generation}, \"\n f\"total={total_count})\"\n )\n return items\n\n elif isinstance(response, list):\n # Handle direct list response\n logger.info(\n f\"Successfully fetched {len(response)} servers from peer \"\n f\"'{self.peer_config.peer_id}' (direct list response)\"\n )\n return response\n\n else:\n logger.error(\n f\"Unexpected response format from peer '{self.peer_config.peer_id}': \"\n f\"{type(response)}\"\n )\n return None\n\n def fetch_security_scans(self) -> list[dict[str, Any]] | None:\n \"\"\"\n Fetch security scan results from peer registry.\n\n Security scans are filtered by the peer based on server visibility,\n so only scans for servers visible to this client are returned.\n\n Returns:\n List of security scan dictionaries or None if fetch fails\n \"\"\"\n # Build URL\n url = f\"{self.endpoint}/api/federation/security-scans\"\n\n # Get authentication token\n try:\n token = self._get_auth_token()\n except ValueError as e:\n logger.error(f\"Cannot fetch security scans: {e}\")\n return None\n\n if not token:\n logger.error(\n f\"Failed to obtain authentication token for peer '{self.peer_config.peer_id}'\"\n )\n return None\n\n # Build headers\n headers = {\n \"Authorization\": f\"Bearer {token}\",\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json\",\n }\n\n # Make request\n logger.info(f\"Fetching security scans from peer '{self.peer_config.peer_id}'\")\n\n response = self._make_request(url, headers=headers)\n\n if not response:\n logger.error(f\"Failed to fetch security scans from peer '{self.peer_config.peer_id}'\")\n return None\n\n # Extract items from response\n # Expected format: {\"items\": [...], \"sync_generation\": N, ...}\n if isinstance(response, dict):\n items = response.get(\"items\", [])\n total_count = response.get(\"total_count\", len(items))\n\n logger.info(\n f\"Successfully fetched {len(items)} security scans from peer \"\n f\"'{self.peer_config.peer_id}' (total={total_count})\"\n )\n return items\n\n elif isinstance(response, list):\n # Handle direct list response\n logger.info(\n f\"Successfully fetched {len(response)} security scans from peer \"\n f\"'{self.peer_config.peer_id}' (direct list response)\"\n )\n return response\n\n else:\n logger.error(\n f\"Unexpected response format from peer '{self.peer_config.peer_id}': \"\n f\"{type(response)}\"\n )\n return None\n\n def fetch_agents(self, since_generation: int | None = None) -> list[dict[str, Any]] | None:\n \"\"\"\n Fetch agents from peer registry.\n\n Args:\n since_generation: Optional generation number for incremental sync.\n If provided, only returns agents updated since that generation.\n\n Returns:\n List of agent dictionaries or None if fetch fails\n \"\"\"\n # Build URL\n url = f\"{self.endpoint}/api/federation/agents\"\n\n # Get authentication token\n try:\n token = self._get_auth_token()\n except ValueError as e:\n logger.error(f\"Cannot fetch agents: {e}\")\n return None\n\n if not token:\n logger.error(\n f\"Failed to obtain authentication token for peer '{self.peer_config.peer_id}'\"\n )\n return None\n\n # Build headers\n headers = {\n \"Authorization\": f\"Bearer {token}\",\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json\",\n }\n\n # Build query parameters\n params = {}\n if since_generation is not None:\n params[\"since_generation\"] = since_generation\n\n # Make request\n logger.info(\n f\"Fetching agents from peer '{self.peer_config.peer_id}' \"\n f\"(since_generation={since_generation})\"\n )\n\n response = self._make_request(url, headers=headers, params=params)\n\n if not response:\n logger.error(f\"Failed to fetch agents from peer '{self.peer_config.peer_id}'\")\n return None\n\n # Extract items from response\n # Expected format: {\"items\": [...], \"sync_generation\": N, ...}\n if isinstance(response, dict):\n items = response.get(\"items\", [])\n sync_generation = response.get(\"sync_generation\", 0)\n total_count = response.get(\"total_count\", len(items))\n\n logger.info(\n f\"Successfully fetched {len(items)} agents from peer \"\n f\"'{self.peer_config.peer_id}' (generation={sync_generation}, \"\n f\"total={total_count})\"\n )\n return items\n\n elif isinstance(response, list):\n # Handle direct list response\n logger.info(\n f\"Successfully fetched {len(response)} agents from peer \"\n f\"'{self.peer_config.peer_id}' (direct list response)\"\n )\n return response\n\n else:\n logger.error(\n f\"Unexpected response format from peer '{self.peer_config.peer_id}': \"\n f\"{type(response)}\"\n )\n return None\n\n def check_peer_health(self) -> bool:\n \"\"\"\n Check if peer registry is healthy and reachable.\n\n Makes a lightweight health check request to the peer's health endpoint.\n\n Returns:\n True if peer is healthy, False otherwise\n \"\"\"\n # Try health endpoint first\n health_url = f\"{self.endpoint}/health\"\n\n logger.debug(f\"Checking health of peer '{self.peer_config.peer_id}'\")\n\n try:\n # Don't need auth for health check\n response = self.client.get(health_url)\n\n # Accept 2xx status codes\n if 200 <= response.status_code < 300:\n logger.debug(\n f\"Peer '{self.peer_config.peer_id}' is healthy (status={response.status_code})\"\n )\n return True\n\n logger.warning(\n f\"Peer '{self.peer_config.peer_id}' health check returned \"\n f\"status {response.status_code}\"\n )\n return False\n\n except Exception as e:\n logger.error(f\"Health check failed for peer '{self.peer_config.peer_id}': {e}\")\n return False\n\n def fetch_server(self, server_name: str, **kwargs) -> dict[str, Any] | None:\n \"\"\"\n Fetch a single server from peer registry.\n\n This is required by BaseFederationClient but not used for peer registries\n which typically fetch in bulk via fetch_servers().\n\n Args:\n server_name: Name/path of the server to fetch\n **kwargs: Additional parameters\n\n Returns:\n Server data dictionary or None if fetch fails\n \"\"\"\n # For peer registries, we typically fetch all servers\n # and filter client-side. But we can implement single fetch\n # if the peer API supports it.\n servers = self.fetch_servers()\n if not servers:\n return None\n\n # Find server by name/path\n for server in servers:\n if server.get(\"path\") == server_name or server.get(\"server_name\") == server_name:\n return server\n\n logger.warning(f\"Server '{server_name}' not found in peer '{self.peer_config.peer_id}'\")\n return None\n\n def fetch_all_servers(self, server_names: list[str], **kwargs) -> list[dict[str, Any]]:\n \"\"\"\n Fetch multiple servers from peer registry.\n\n This is required by BaseFederationClient but for peer registries\n we typically fetch all servers and filter client-side.\n\n Args:\n server_names: List of server names/paths to fetch\n **kwargs: Additional parameters\n\n Returns:\n List of server data dictionaries\n \"\"\"\n # Fetch all servers\n all_servers = self.fetch_servers()\n if not all_servers:\n return []\n\n # Filter to requested servers if specific names provided\n if server_names:\n filtered = []\n for server in all_servers:\n server_id = server.get(\"path\") or server.get(\"server_name\")\n if server_id in server_names:\n filtered.append(server)\n return filtered\n\n return all_servers\n" }, { "path": "registry/services/federation_audit_service.py", "content": "\"\"\"\nFederation audit service for tracking peer connections.\n\nThis module provides services for logging and querying federation\nconnection history, enabling visibility into peer sync operations.\n\"\"\"\n\nimport logging\nfrom datetime import UTC, datetime\nfrom threading import Lock\nfrom typing import Optional\n\nfrom pydantic import BaseModel, Field\n\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nMAX_CONNECTION_LOG_ENTRIES: int = 1000\nDEFAULT_LOG_RETENTION_DAYS: int = 30\n\n\nclass FederationConnectionLog(BaseModel):\n \"\"\"Record of a federation connection from a peer.\"\"\"\n\n timestamp: datetime = Field(\n default_factory=lambda: datetime.now(UTC),\n description=\"When the connection occurred\",\n )\n peer_id: str = Field(\n ...,\n description=\"ID of the connecting peer\",\n )\n peer_name: str = Field(\n default=\"\",\n description=\"Display name of the connecting peer\",\n )\n client_id: str = Field(\n ...,\n description=\"OAuth2 client_id from the token\",\n )\n endpoint: str = Field(\n ...,\n description=\"API endpoint accessed\",\n )\n items_requested: int = Field(\n default=0,\n ge=0,\n description=\"Number of items requested/returned\",\n )\n success: bool = Field(\n default=True,\n description=\"Whether the request succeeded\",\n )\n error_message: str | None = Field(\n default=None,\n description=\"Error message if request failed\",\n )\n request_id: str | None = Field(\n default=None,\n description=\"Unique request identifier for correlation\",\n )\n\n\nclass PeerSyncSummary(BaseModel):\n \"\"\"Summary of resources shared with a peer.\"\"\"\n\n peer_id: str = Field(\n ...,\n description=\"ID of the peer\",\n )\n peer_name: str = Field(\n default=\"\",\n description=\"Display name of the peer\",\n )\n total_connections: int = Field(\n default=0,\n ge=0,\n description=\"Total number of connections from this peer\",\n )\n last_connection: datetime | None = Field(\n default=None,\n description=\"Timestamp of last connection\",\n )\n servers_shared: int = Field(\n default=0,\n ge=0,\n description=\"Number of servers shared with this peer\",\n )\n agents_shared: int = Field(\n default=0,\n ge=0,\n description=\"Number of agents shared with this peer\",\n )\n successful_requests: int = Field(\n default=0,\n ge=0,\n description=\"Number of successful requests\",\n )\n failed_requests: int = Field(\n default=0,\n ge=0,\n description=\"Number of failed requests\",\n )\n\n\nclass FederationAuditService:\n \"\"\"Service for tracking peer federation connections.\n\n Provides in-memory logging of federation connections for visibility\n and debugging purposes. In production, this could be backed by a\n persistent store.\n \"\"\"\n\n _instance: Optional[\"FederationAuditService\"] = None\n _lock: Lock = Lock()\n\n def __new__(cls) -> \"FederationAuditService\":\n \"\"\"Singleton pattern with thread-safe double-checked locking.\"\"\"\n if cls._instance is None:\n with cls._lock:\n if cls._instance is None:\n cls._instance = super().__new__(cls)\n cls._instance._initialized = False\n return cls._instance\n\n def __init__(self):\n \"\"\"Initialize the audit service.\"\"\"\n if self._initialized:\n return\n\n self._connection_logs: list[FederationConnectionLog] = []\n self._peer_summaries: dict[str, PeerSyncSummary] = {}\n self._operation_lock = Lock()\n\n self._initialized = True\n logger.info(\"FederationAuditService initialized\")\n\n async def log_connection(\n self,\n peer_id: str,\n client_id: str,\n endpoint: str,\n items_requested: int = 0,\n success: bool = True,\n error_message: str | None = None,\n peer_name: str = \"\",\n request_id: str | None = None,\n ) -> None:\n \"\"\"\n Log a federation sync connection.\n\n Args:\n peer_id: ID of the connecting peer\n client_id: OAuth2 client_id from token\n endpoint: API endpoint accessed\n items_requested: Number of items returned\n success: Whether request succeeded\n error_message: Error message if failed\n peer_name: Display name of peer\n request_id: Unique request ID for correlation\n \"\"\"\n with self._operation_lock:\n # Create log entry\n log_entry = FederationConnectionLog(\n peer_id=peer_id,\n peer_name=peer_name,\n client_id=client_id,\n endpoint=endpoint,\n items_requested=items_requested,\n success=success,\n error_message=error_message,\n request_id=request_id,\n )\n\n # Add to logs, maintaining max size\n self._connection_logs.insert(0, log_entry)\n if len(self._connection_logs) > MAX_CONNECTION_LOG_ENTRIES:\n self._connection_logs = self._connection_logs[:MAX_CONNECTION_LOG_ENTRIES]\n\n # Update peer summary\n if peer_id not in self._peer_summaries:\n self._peer_summaries[peer_id] = PeerSyncSummary(\n peer_id=peer_id,\n peer_name=peer_name,\n )\n\n summary = self._peer_summaries[peer_id]\n summary.total_connections += 1\n summary.last_connection = log_entry.timestamp\n\n if peer_name and not summary.peer_name:\n summary.peer_name = peer_name\n\n if success:\n summary.successful_requests += 1\n # Update shared counts based on endpoint\n if \"/servers\" in endpoint:\n summary.servers_shared = max(summary.servers_shared, items_requested)\n elif \"/agents\" in endpoint:\n summary.agents_shared = max(summary.agents_shared, items_requested)\n else:\n summary.failed_requests += 1\n\n logger.debug(\n f\"Logged federation connection: peer={peer_id}, \"\n f\"endpoint={endpoint}, items={items_requested}, success={success}\"\n )\n\n async def get_peer_connections(\n self,\n peer_id: str,\n since: datetime | None = None,\n limit: int = 100,\n ) -> list[FederationConnectionLog]:\n \"\"\"\n Get connection history for a peer.\n\n Args:\n peer_id: ID of the peer\n since: Only return connections after this timestamp\n limit: Maximum entries to return\n\n Returns:\n List of connection logs for the peer\n \"\"\"\n with self._operation_lock:\n # Filter by peer_id\n peer_logs = [log for log in self._connection_logs if log.peer_id == peer_id]\n\n # Filter by timestamp if specified\n if since:\n peer_logs = [log for log in peer_logs if log.timestamp > since]\n\n # Apply limit\n return peer_logs[:limit]\n\n async def get_all_connections(\n self,\n since: datetime | None = None,\n limit: int = 100,\n ) -> list[FederationConnectionLog]:\n \"\"\"\n Get all connection history.\n\n Args:\n since: Only return connections after this timestamp\n limit: Maximum entries to return\n\n Returns:\n List of all connection logs\n \"\"\"\n with self._operation_lock:\n logs = self._connection_logs.copy()\n\n # Filter by timestamp if specified\n if since:\n logs = [log for log in logs if log.timestamp > since]\n\n # Apply limit\n return logs[:limit]\n\n async def get_shared_resources_summary(self) -> dict[str, PeerSyncSummary]:\n \"\"\"\n Get summary of what's shared with each peer.\n\n Returns:\n Dictionary mapping peer_id to PeerSyncSummary\n \"\"\"\n with self._operation_lock:\n return self._peer_summaries.copy()\n\n async def get_peer_summary(\n self,\n peer_id: str,\n ) -> PeerSyncSummary | None:\n \"\"\"\n Get summary for a specific peer.\n\n Args:\n peer_id: ID of the peer\n\n Returns:\n PeerSyncSummary if peer has connected, None otherwise\n \"\"\"\n with self._operation_lock:\n return self._peer_summaries.get(peer_id)\n\n def clear_logs(self) -> None:\n \"\"\"Clear all connection logs (for testing).\"\"\"\n with self._operation_lock:\n self._connection_logs.clear()\n self._peer_summaries.clear()\n logger.info(\"Cleared all federation audit logs\")\n\n\n# Global service instance\n_federation_audit_service: FederationAuditService | None = None\n\n\ndef get_federation_audit_service() -> FederationAuditService:\n \"\"\"\n Get the global federation audit service instance.\n\n Returns:\n Singleton FederationAuditService instance\n \"\"\"\n global _federation_audit_service\n if _federation_audit_service is None:\n _federation_audit_service = FederationAuditService()\n return _federation_audit_service\n" }, { "path": "registry/services/federation_reconciliation.py", "content": "\"\"\"\nFederation server reconciliation service.\n\nDetects and removes servers from mcp_servers_default that are no longer\npresent in the federation configuration. Called after config saves,\nmanual syncs, and startup syncs.\n\nSupports reconciliation for:\n- Anthropic MCP Registry (servers)\n- AWS Agent Registry (servers, agents, skills)\n\nIMPORTANT: This module should only be called from authenticated contexts\n(route handlers with user_context or startup code). It does not perform\nits own authorization checks.\n\nIf reconciliation fails after a config save, stale servers will be\ncleaned up on next startup (reconciliation always runs at startup).\n\"\"\"\n\nimport logging\nimport time\nfrom typing import (\n Any,\n)\n\nfrom ..schemas.federation_schema import FederationConfig\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n# OTel metric names\nRECONCILIATION_REMOVED_METRIC: str = \"mcp_federation_reconciliation_removed_total\"\nRECONCILIATION_DURATION_METRIC: str = \"mcp_federation_reconciliation_duration_seconds\"\n\n\ndef _config_server_names_to_paths(\n config: FederationConfig,\n) -> set[str]:\n \"\"\"Convert federation config server names to expected DB paths.\n\n Anthropic server names like 'io.github.jgador/websharp'\n are stored with paths like '/io.github.jgador-websharp'.\n\n Args:\n config: The current federation configuration\n\n Returns:\n Set of expected server paths\n \"\"\"\n expected_paths = set()\n for server in config.anthropic.servers:\n path = f\"/{server.name.replace('/', '-')}\"\n expected_paths.add(path)\n return expected_paths\n\n\ndef _record_reconciliation_metrics(\n removed_count: int,\n elapsed_seconds: float,\n) -> None:\n \"\"\"Record OTel metrics for reconciliation.\n\n Args:\n removed_count: Number of servers removed\n elapsed_seconds: Time taken for reconciliation\n \"\"\"\n try:\n from ..otel.instruments import get_instruments\n\n instruments = get_instruments()\n if instruments:\n # Record removed count (counter)\n counter = instruments.get(RECONCILIATION_REMOVED_METRIC)\n if counter:\n counter.add(removed_count, {\"source\": \"anthropic\"})\n\n # Record duration (histogram)\n histogram = instruments.get(RECONCILIATION_DURATION_METRIC)\n if histogram:\n histogram.record(elapsed_seconds, {\"source\": \"anthropic\"})\n except Exception as e:\n logger.debug(f\"Failed to record reconciliation metrics: {e}\")\n\n\nasync def reconcile_anthropic_servers(\n config: FederationConfig,\n server_service: Any,\n server_repo: Any,\n nginx_service: Any | None = None,\n dry_run: bool = False,\n skip_nginx_regen: bool = False,\n audit_username: str | None = None,\n) -> dict[str, Any]:\n \"\"\"Reconcile Anthropic federated servers against the current config.\n\n Removes servers from mcp_servers_default that have source=\"anthropic\"\n but are no longer listed in the federation config.\n\n Args:\n config: Current federation configuration\n server_service: ServerService instance for remove_server()\n server_repo: Server repository for list_by_source()\n nginx_service: Optional NginxService for config regeneration\n dry_run: If True, compute delta but do not delete anything\n skip_nginx_regen: If True, skip nginx config regeneration\n (useful during startup when nginx is regenerated separately)\n audit_username: Username to include in audit log entry\n (None for startup/system-triggered reconciliation)\n\n Returns:\n Dictionary with reconciliation results:\n - removed: List of removed server names\n - removed_count: Number of servers removed\n - expected_count: Number of servers in config\n - actual_count: Number of servers found in DB\n - dry_run: Whether this was a dry run\n - errors: List of errors (if any)\n \"\"\"\n start_time = time.time()\n\n # Step 1: Get expected paths from config\n expected_paths = _config_server_names_to_paths(config)\n\n # If anthropic is disabled entirely, all anthropic servers are stale\n if not config.anthropic.enabled:\n expected_paths = set()\n\n logger.info(\n f\"Reconciliation: {len(expected_paths)} servers expected from Anthropic federation config\"\n )\n\n # Step 2: Get actual Anthropic servers in DB\n actual_servers = await server_repo.list_by_source(\"anthropic\")\n actual_paths = set(actual_servers.keys())\n\n logger.info(\n f\"Reconciliation: {len(actual_paths)} servers found \"\n f\"in mcp_servers_default with source='anthropic'\"\n )\n\n # Step 3: Compute stale servers (in DB but not in config)\n stale_paths = actual_paths - expected_paths\n\n if not stale_paths:\n logger.debug(\"Reconciliation: no stale servers found\")\n return {\n \"removed\": [],\n \"removed_count\": 0,\n \"expected_count\": len(expected_paths),\n \"actual_count\": len(actual_paths),\n \"dry_run\": dry_run,\n }\n\n stale_names = [actual_servers[p].get(\"server_name\", p) for p in sorted(stale_paths)]\n logger.info(f\"Reconciliation: {len(stale_paths)} stale servers to remove: {stale_names}\")\n\n # Dry run: return what would be removed without deleting\n if dry_run:\n logger.info(\"Reconciliation: dry_run=True, skipping actual removal\")\n return {\n \"removed\": stale_names,\n \"removed_count\": len(stale_names),\n \"expected_count\": len(expected_paths),\n \"actual_count\": len(actual_paths),\n \"dry_run\": True,\n }\n\n # Step 4: Remove stale servers\n removed = []\n errors = []\n for path in sorted(stale_paths):\n try:\n server_name = actual_servers[path].get(\"server_name\", path)\n success = await server_service.remove_server(path)\n if success:\n removed.append(server_name)\n logger.info(f\"Reconciliation: removed stale server '{server_name}' ({path})\")\n else:\n errors.append(f\"Failed to remove {server_name} ({path})\")\n logger.warning(f\"Reconciliation: failed to remove server '{server_name}' ({path})\")\n except Exception as e:\n errors.append(f\"Error removing {path}: {e}\")\n logger.error(f\"Reconciliation: error removing server {path}: {e}\")\n\n # Step 5: Regenerate nginx config if any servers were removed\n if removed and nginx_service and not skip_nginx_regen:\n try:\n all_servers = await server_repo.list_all()\n enabled_servers = {\n p: info for p, info in all_servers.items() if info.get(\"is_enabled\", False)\n }\n await nginx_service.generate_config_async(enabled_servers)\n logger.info(\"Reconciliation: nginx config regenerated\")\n except Exception as e:\n logger.error(f\"Reconciliation: failed to regenerate nginx config: {e}\")\n\n elapsed = time.time() - start_time\n\n # Step 6: Record OTel metrics\n _record_reconciliation_metrics(len(removed), elapsed)\n\n # Step 7: Audit trail summary\n triggered_by = audit_username or \"system\"\n logger.info(\n f\"Reconciliation complete: removed {len(removed)} stale servers \"\n f\"in {elapsed:.1f} seconds \"\n f\"(triggered_by={triggered_by}, \"\n f\"expected={len(expected_paths)}, \"\n f\"actual_in_db={len(actual_paths)}, \"\n f\"stale={len(stale_paths)}, \"\n f\"errors={len(errors)})\"\n )\n\n return {\n \"removed\": removed,\n \"removed_count\": len(removed),\n \"expected_count\": len(expected_paths),\n \"actual_count\": len(actual_paths),\n \"dry_run\": False,\n \"errors\": errors,\n }\n\n\ndef _build_expected_agentcore_paths(\n config: FederationConfig,\n synced_paths: dict[str, set[str]],\n) -> dict[str, set[str]]:\n \"\"\"Build sets of expected paths from synced data.\n\n If agentcore federation is disabled, returns empty sets (all records are stale).\n\n Args:\n config: Current federation configuration\n synced_paths: Dict with \"servers\", \"agents\", \"skills\" keys\n containing paths that were just synced\n\n Returns:\n Dict with \"servers\", \"agents\", \"skills\" keys containing expected path sets\n \"\"\"\n if not config.aws_registry.enabled:\n return {\"servers\": set(), \"agents\": set(), \"skills\": set()}\n\n return {\n \"servers\": synced_paths.get(\"servers\", set()),\n \"agents\": synced_paths.get(\"agents\", set()),\n \"skills\": synced_paths.get(\"skills\", set()),\n }\n\n\nasync def _reconcile_agentcore_servers(\n expected_paths: set[str],\n server_service: Any,\n server_repo: Any,\n) -> dict[str, Any]:\n \"\"\"Reconcile AgentCore federated servers.\n\n Args:\n expected_paths: Paths that should exist after sync\n server_service: ServerService instance\n server_repo: Server repository\n\n Returns:\n Dict with removed list and error list\n \"\"\"\n removed: list[str] = []\n errors: list[str] = []\n\n actual_servers = await server_repo.list_by_source(\"agentcore\")\n actual_paths = set(actual_servers.keys())\n stale_paths = actual_paths - expected_paths\n\n for path in sorted(stale_paths):\n try:\n server_name = actual_servers[path].get(\"server_name\", path)\n success = await server_service.remove_server(path)\n if success:\n removed.append(server_name)\n logger.info(f\"AgentCore reconciliation: removed stale server '{server_name}'\")\n else:\n errors.append(f\"Failed to remove server {server_name} ({path})\")\n except Exception as e:\n errors.append(f\"Error removing server {path}: {e}\")\n logger.error(f\"AgentCore reconciliation: error removing server {path}: {e}\")\n\n return {\"removed\": removed, \"errors\": errors}\n\n\nasync def _reconcile_agentcore_agents(\n expected_paths: set[str],\n agent_repo: Any,\n) -> dict[str, Any]:\n \"\"\"Reconcile AgentCore federated agents.\n\n Finds agents with 'agentcore' tag and path starting with /agents/agentcore-,\n then removes those not in expected_paths.\n\n Args:\n expected_paths: Paths that should exist after sync\n agent_repo: Agent repository\n\n Returns:\n Dict with removed list and error list\n \"\"\"\n removed: list[str] = []\n errors: list[str] = []\n\n all_agents = await agent_repo.list_all()\n agentcore_agents = [\n a\n for a in all_agents\n if \"agentcore\" in (a.tags or []) and str(a.path).startswith(\"/agents/agentcore-\")\n ]\n\n for agent in agentcore_agents:\n if agent.path not in expected_paths:\n try:\n success = await agent_repo.delete(agent.path)\n if success:\n removed.append(agent.name)\n logger.info(f\"AgentCore reconciliation: removed stale agent '{agent.name}'\")\n else:\n errors.append(f\"Failed to remove agent {agent.name} ({agent.path})\")\n except Exception as e:\n errors.append(f\"Error removing agent {agent.path}: {e}\")\n logger.error(f\"AgentCore reconciliation: error removing agent {agent.path}: {e}\")\n\n return {\"removed\": removed, \"errors\": errors}\n\n\nasync def _reconcile_agentcore_skills(\n expected_paths: set[str],\n skill_repo: Any,\n) -> dict[str, Any]:\n \"\"\"Reconcile AgentCore federated skills.\n\n Finds skills with 'agentcore' tag and path starting with /skills/agentcore-,\n then removes those not in expected_paths.\n\n Args:\n expected_paths: Paths that should exist after sync\n skill_repo: Skill repository\n\n Returns:\n Dict with removed list and error list\n \"\"\"\n removed: list[str] = []\n errors: list[str] = []\n\n all_skills = await skill_repo.list_all()\n agentcore_skills = [\n s\n for s in all_skills\n if \"agentcore\" in (s.tags or []) and str(s.path).startswith(\"/skills/agentcore-\")\n ]\n\n for skill in agentcore_skills:\n if skill.path not in expected_paths:\n try:\n success = await skill_repo.delete(skill.path)\n if success:\n removed.append(skill.name)\n logger.info(f\"AgentCore reconciliation: removed stale skill '{skill.name}'\")\n else:\n errors.append(f\"Failed to remove skill {skill.name} ({skill.path})\")\n except Exception as e:\n errors.append(f\"Error removing skill {skill.path}: {e}\")\n logger.error(f\"AgentCore reconciliation: error removing skill {skill.path}: {e}\")\n\n return {\"removed\": removed, \"errors\": errors}\n\n\nasync def reconcile_agentcore_records(\n config: FederationConfig,\n server_service: Any,\n server_repo: Any,\n agent_repo: Any,\n skill_repo: Any,\n synced_paths: dict[str, set[str]] | None = None,\n dry_run: bool = False,\n audit_username: str | None = None,\n) -> dict[str, Any]:\n \"\"\"Reconcile AgentCore federated records against the current config.\n\n Removes servers, agents, and skills that have source/tag \"agentcore\"\n but were not part of the latest sync.\n\n Args:\n config: Current federation configuration\n server_service: ServerService instance for remove_server()\n server_repo: Server repository for list_by_source()\n agent_repo: Agent repository for list_all() and delete()\n skill_repo: Skill repository for list_all() and delete()\n synced_paths: Dict with \"servers\", \"agents\", \"skills\" keys containing\n paths that were just synced. If None, uses empty sets (removes all).\n dry_run: If True, compute delta but do not delete anything\n audit_username: Username for audit trail\n\n Returns:\n Dictionary with reconciliation results per item type\n \"\"\"\n start_time = time.time()\n\n if synced_paths is None:\n synced_paths = {\"servers\": set(), \"agents\": set(), \"skills\": set()}\n\n expected = _build_expected_agentcore_paths(config, synced_paths)\n\n logger.info(\n f\"AgentCore reconciliation: expecting \"\n f\"{len(expected['servers'])} servers, \"\n f\"{len(expected['agents'])} agents, \"\n f\"{len(expected['skills'])} skills\"\n )\n\n if dry_run:\n logger.info(\"AgentCore reconciliation: dry_run=True, skipping actual removal\")\n return {\n \"dry_run\": True,\n \"servers\": {\"removed\": [], \"errors\": []},\n \"agents\": {\"removed\": [], \"errors\": []},\n \"skills\": {\"removed\": [], \"errors\": []},\n }\n\n # Reconcile each type\n server_result = await _reconcile_agentcore_servers(\n expected[\"servers\"], server_service, server_repo\n )\n agent_result = await _reconcile_agentcore_agents(expected[\"agents\"], agent_repo)\n skill_result = await _reconcile_agentcore_skills(expected[\"skills\"], skill_repo)\n\n elapsed = time.time() - start_time\n total_removed = (\n len(server_result[\"removed\"]) + len(agent_result[\"removed\"]) + len(skill_result[\"removed\"])\n )\n\n # Record metrics\n try:\n from ..otel.instruments import get_instruments\n\n instruments = get_instruments()\n if instruments:\n counter = instruments.get(RECONCILIATION_REMOVED_METRIC)\n if counter:\n counter.add(\n len(server_result[\"removed\"]), {\"source\": \"agentcore\", \"item_type\": \"server\"}\n )\n counter.add(\n len(agent_result[\"removed\"]), {\"source\": \"agentcore\", \"item_type\": \"agent\"}\n )\n counter.add(\n len(skill_result[\"removed\"]), {\"source\": \"agentcore\", \"item_type\": \"skill\"}\n )\n\n histogram = instruments.get(RECONCILIATION_DURATION_METRIC)\n if histogram:\n histogram.record(elapsed, {\"source\": \"agentcore\"})\n except Exception as e:\n logger.debug(f\"Failed to record AgentCore reconciliation metrics: {e}\")\n\n triggered_by = audit_username or \"system\"\n logger.info(\n f\"AgentCore reconciliation complete: removed {total_removed} stale records \"\n f\"in {elapsed:.1f} seconds (triggered_by={triggered_by})\"\n )\n\n return {\n \"dry_run\": False,\n \"servers\": server_result,\n \"agents\": agent_result,\n \"skills\": skill_result,\n \"total_removed\": total_removed,\n \"elapsed_seconds\": round(elapsed, 2),\n }\n" }, { "path": "registry/services/github_auth.py", "content": "\"\"\"GitHub authentication provider for private repository access.\n\nProvides auth headers for httpx requests to GitHub, supporting:\n- Personal Access Token (PAT) -- static, user-scoped\n- GitHub App installation token -- ephemeral, org-scoped\n\nAuth headers are only sent to explicitly allowed hosts.\n\"\"\"\n\nimport asyncio\nimport logging\nimport time\nfrom datetime import datetime\nfrom urllib.parse import urlparse\n\nimport httpx\nimport jwt\n\nfrom ..core.config import settings\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n# Default GitHub hosts that receive auth headers\n_DEFAULT_GITHUB_HOSTS: frozenset[str] = frozenset(\n {\n \"github.com\",\n \"raw.githubusercontent.com\",\n }\n)\n\n\nclass GitHubAuthProvider:\n \"\"\"Provides auth headers for GitHub API requests.\n\n Supports two credential tiers with automatic fallback:\n 1. GitHub App (installation token, ephemeral, org-scoped)\n 2. Personal Access Token (static, user-scoped)\n\n Auth headers are only sent to explicitly allowed hosts.\n \"\"\"\n\n def __init__(self) -> None:\n self._allowed_hosts = self._build_allowed_hosts()\n self._cached_token: str | None = None\n self._token_expires_at: float = 0.0\n self._failure_retry_after: float = 0.0\n self._token_lock = asyncio.Lock()\n self._log_active_tier()\n\n def _build_allowed_hosts(self) -> frozenset[str]:\n \"\"\"Build allowed hosts from defaults + github_extra_hosts config.\"\"\"\n extra_raw = settings.github_extra_hosts\n extra = frozenset(h.strip().lower() for h in extra_raw.split(\",\") if h.strip())\n return _DEFAULT_GITHUB_HOSTS | extra\n\n def _is_allowed_host(self, url: str) -> bool:\n \"\"\"Check if URL hostname is in the allowed GitHub hosts set.\"\"\"\n parsed = urlparse(url)\n hostname = (parsed.hostname or \"\").lower()\n allowed = hostname in self._allowed_hosts\n if not allowed:\n logger.debug(\"GitHub auth: host '%s' not in allowed hosts, skipping auth\", hostname)\n return allowed\n\n def _log_active_tier(self) -> None:\n \"\"\"Log which auth tier is active at initialization.\"\"\"\n if self._has_app_credentials():\n logger.info(\"GitHub auth: GitHub App credentials configured\")\n elif settings.github_pat:\n logger.info(\"GitHub auth: Personal Access Token configured\")\n else:\n logger.info(\"GitHub auth: No credentials configured (unauthenticated access)\")\n\n def _has_app_credentials(self) -> bool:\n \"\"\"Check if all GitHub App credentials are present.\"\"\"\n return bool(\n settings.github_app_id\n and settings.github_app_installation_id\n and settings.github_app_private_key\n )\n\n async def get_auth_headers(self, url: str) -> dict[str, str]:\n \"\"\"Return auth headers if url matches an allowed GitHub host.\n\n Returns empty dict if:\n - URL host is not in the allowed hosts set\n - No credentials are configured\n - Token exchange fails (logged, falls back gracefully)\n \"\"\"\n if not self._is_allowed_host(url):\n return {}\n\n # Tier 2: GitHub App\n if self._has_app_credentials():\n token = await self._get_github_app_token()\n if token:\n return {\"Authorization\": f\"Bearer {token}\"}\n logger.warning(\"GitHub App token exchange failed, falling back to PAT\")\n\n # Tier 1: PAT\n if settings.github_pat:\n return {\"Authorization\": f\"Bearer {settings.github_pat}\"}\n\n # Tier 0: Unauthenticated\n return {}\n\n def _create_jwt(self) -> str:\n \"\"\"Create signed JWT for GitHub App authentication.\n\n Uses RS256 algorithm per GitHub's requirements.\n Claims: iat (now - 60s for clock skew), exp (now + 600s), iss (app_id).\n \"\"\"\n now = int(time.time())\n payload = {\n \"iat\": now - 60,\n \"exp\": now + 600,\n \"iss\": settings.github_app_id,\n }\n # Handle PEM key from env vars where newlines may be literal \\n strings\n private_key = settings.github_app_private_key.replace(\"\\\\n\", \"\\n\")\n return jwt.encode(payload, private_key, algorithm=\"RS256\")\n\n async def _get_github_app_token(self) -> str | None:\n \"\"\"Get or refresh cached GitHub App installation token.\"\"\"\n now = time.time()\n\n # Fast path: valid cache (no lock needed)\n if self._cached_token and now < self._token_expires_at - 300:\n return self._cached_token\n\n # Negative cache: avoid hammering GitHub API on sustained misconfiguration\n if not self._cached_token and now < self._failure_retry_after:\n return None\n\n async with self._token_lock:\n # Double-check after acquiring lock\n if self._cached_token and time.time() < self._token_expires_at - 300:\n return self._cached_token\n\n try:\n app_jwt = self._create_jwt()\n installation_id = settings.github_app_installation_id\n base_url = settings.github_api_base_url.rstrip(\"/\")\n url = f\"{base_url}/app/installations/{installation_id}/access_tokens\"\n\n async with httpx.AsyncClient() as client:\n response = await client.post(\n url,\n headers={\n \"Authorization\": f\"Bearer {app_jwt}\",\n \"Accept\": \"application/vnd.github+json\",\n },\n timeout=10,\n )\n\n if response.status_code != 201:\n logger.error(\n \"GitHub App token exchange failed: HTTP %d - %s\",\n response.status_code,\n response.text[:200],\n )\n self._failure_retry_after = time.time() + 60\n return None\n\n data = response.json()\n token = data.get(\"token\")\n if not token:\n logger.error(\"GitHub App token response missing 'token' field\")\n self._failure_retry_after = time.time() + 60\n return None\n\n self._cached_token = token\n\n # Parse expiry from response, fall back to 1 hour\n expires_at = data.get(\"expires_at\")\n if expires_at:\n try:\n expiry_dt = datetime.fromisoformat(expires_at.replace(\"Z\", \"+00:00\"))\n self._token_expires_at = expiry_dt.timestamp()\n except ValueError:\n self._token_expires_at = time.time() + 3600\n else:\n self._token_expires_at = time.time() + 3600\n\n logger.debug(\"GitHub App installation token refreshed successfully\")\n return self._cached_token\n\n except (httpx.RequestError, KeyError, ValueError) as e:\n logger.error(\"GitHub App token exchange error: %s\", e)\n self._failure_retry_after = time.time() + 60\n return None\n\n\n# Module-level singleton -- shared across all consumers\ngithub_auth_provider = GitHubAuthProvider()\n" }, { "path": "registry/services/m2m_management_service.py", "content": "\"\"\"Direct CRUD service for manually-registered M2M clients.\n\nThis service writes to the shared ``idp_m2m_clients`` collection without\ncalling any IdP Admin API. Records written by this service are tagged with\n``provider == \"manual\"`` so they are distinguishable from IdP-synced records,\nand only ``manual`` records can be modified or deleted via this API.\n\nTracked by issue #851.\n\"\"\"\n\nimport logging\nfrom datetime import datetime\n\nfrom motor.motor_asyncio import AsyncIOMotorDatabase\nfrom pymongo.errors import DuplicateKeyError\n\nfrom registry.schemas.idp_m2m_client import (\n MANUAL_PROVIDER,\n IdPM2MClient,\n IdPM2MClientCreate,\n IdPM2MClientPatch,\n)\n\nlogger = logging.getLogger(__name__)\n\n\nCOLLECTION_NAME: str = \"idp_m2m_clients\"\n\n\nclass M2MClientConflict(Exception):\n \"\"\"Raised when a client_id already exists in the collection.\"\"\"\n\n\nclass M2MClientNotFound(Exception):\n \"\"\"Raised when the requested client_id does not exist.\"\"\"\n\n\nclass M2MClientImmutable(Exception):\n \"\"\"Raised when attempting to mutate a record owned by IdP sync.\"\"\"\n\n\nclass M2MManagementService:\n \"\"\"CRUD service for manually-registered M2M clients.\"\"\"\n\n def __init__(\n self,\n db: AsyncIOMotorDatabase,\n ) -> None:\n self._collection = db[COLLECTION_NAME]\n\n async def ensure_indexes(self) -> None:\n \"\"\"Create required indexes (idempotent).\n\n Creates a unique index on ``client_id`` to prevent duplicate registrations\n under concurrent POSTs.\n \"\"\"\n await self._collection.create_index(\"client_id\", unique=True)\n logger.info(\n \"Ensured unique index on %s.client_id\",\n COLLECTION_NAME,\n )\n\n async def create(\n self,\n payload: IdPM2MClientCreate,\n created_by: str | None,\n ) -> IdPM2MClient:\n \"\"\"Insert a new manual M2M client record.\n\n Args:\n payload: Validated create request body.\n created_by: Username of the operator performing the action\n (captured from the authenticated user context).\n\n Returns:\n The persisted :class:`IdPM2MClient`.\n\n Raises:\n M2MClientConflict: If ``client_id`` already exists (unique index\n violation).\n \"\"\"\n now = datetime.utcnow()\n doc: dict = {\n \"client_id\": payload.client_id,\n \"name\": payload.client_name,\n \"description\": payload.description,\n \"groups\": list(payload.groups),\n \"enabled\": True,\n \"provider\": MANUAL_PROVIDER,\n \"idp_app_id\": None,\n \"created_by\": created_by,\n \"created_at\": now,\n \"updated_at\": now,\n }\n try:\n await self._collection.insert_one(doc)\n except DuplicateKeyError as e:\n raise M2MClientConflict(payload.client_id) from e\n\n logger.info(\n \"Registered manual M2M client client_id=%s name=%s groups=%s created_by=%s\",\n payload.client_id,\n payload.client_name,\n payload.groups,\n created_by,\n )\n return IdPM2MClient(**doc)\n\n async def list_paged(\n self,\n provider: str | None = None,\n limit: int = 500,\n skip: int = 0,\n ) -> tuple[list[IdPM2MClient], int]:\n \"\"\"Return a paginated slice of the collection.\n\n Args:\n provider: Optional filter on the ``provider`` field.\n limit: Maximum number of records to return on this page.\n skip: Number of records to skip (offset).\n\n Returns:\n Tuple of (items_on_page, total_matching_count).\n \"\"\"\n query: dict = {}\n if provider is not None:\n query[\"provider\"] = provider\n total = await self._collection.count_documents(query)\n cursor = self._collection.find(query).skip(skip).limit(limit)\n docs = await cursor.to_list(length=limit)\n return [IdPM2MClient(**d) for d in docs], total\n\n async def get(\n self,\n client_id: str,\n ) -> IdPM2MClient:\n \"\"\"Fetch a single client by ``client_id``.\n\n Raises:\n M2MClientNotFound: If the record does not exist.\n \"\"\"\n doc = await self._collection.find_one({\"client_id\": client_id})\n if doc is None:\n raise M2MClientNotFound(client_id)\n return IdPM2MClient(**doc)\n\n async def patch(\n self,\n client_id: str,\n payload: IdPM2MClientPatch,\n ) -> IdPM2MClient:\n \"\"\"Update a manual M2M client record.\n\n Only records with ``provider == \"manual\"`` can be modified.\n\n Raises:\n M2MClientNotFound: If the record does not exist.\n M2MClientImmutable: If the record was written by IdP sync.\n \"\"\"\n existing = await self._collection.find_one({\"client_id\": client_id})\n if existing is None:\n raise M2MClientNotFound(client_id)\n if existing.get(\"provider\") != MANUAL_PROVIDER:\n raise M2MClientImmutable(client_id)\n\n # Pydantic v2: only fields explicitly set in the request body appear\n # in the dump. Callers clearing groups pass [] and it lands here too.\n provided = payload.model_dump(exclude_unset=True)\n\n field_map: dict[str, str] = {\n \"client_name\": \"name\",\n \"groups\": \"groups\",\n \"description\": \"description\",\n \"enabled\": \"enabled\",\n }\n updates: dict = {\"updated_at\": datetime.utcnow()}\n for request_field, storage_field in field_map.items():\n if request_field in provided:\n updates[storage_field] = provided[request_field]\n\n if len(updates) == 1:\n # No meaningful changes requested; return existing doc unchanged.\n return IdPM2MClient(**existing)\n\n await self._collection.update_one(\n {\"client_id\": client_id},\n {\"$set\": updates},\n )\n\n logger.info(\n \"Updated manual M2M client client_id=%s fields=%s\",\n client_id,\n sorted(updates.keys()),\n )\n return await self.get(client_id)\n\n async def delete(\n self,\n client_id: str,\n ) -> None:\n \"\"\"Delete a manual M2M client record.\n\n Only records with ``provider == \"manual\"`` can be deleted.\n\n Raises:\n M2MClientNotFound: If the record does not exist.\n M2MClientImmutable: If the record was written by IdP sync.\n \"\"\"\n existing = await self._collection.find_one({\"client_id\": client_id})\n if existing is None:\n raise M2MClientNotFound(client_id)\n if existing.get(\"provider\") != MANUAL_PROVIDER:\n raise M2MClientImmutable(client_id)\n\n await self._collection.delete_one({\"client_id\": client_id})\n logger.info(\"Deleted manual M2M client client_id=%s\", client_id)\n" }, { "path": "registry/services/okta_m2m_sync.py", "content": "\"\"\"Okta M2M Client Sync Service.\n\nThis service syncs M2M applications from Okta to MongoDB, allowing the registry\nto track service accounts and their group mappings without hardcoding them in\nauthorization server expressions.\n\"\"\"\n\nimport logging\nimport os\nfrom datetime import datetime\n\nimport requests\nfrom motor.motor_asyncio import AsyncIOMotorDatabase\n\nfrom registry.schemas.okta_m2m_client import OktaM2MClient\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\n# Okta client ID to groups mapping\n# TODO: Make this configurable via database or config file\nDEFAULT_CLIENT_GROUPS = {\n \"0oa1100req1AzfKaY698\": [\"registry-admins\"], # ai-agent\n \"0oa110977fajZVrlY698\": [\"public-mcp-users\"], # ai-agent-public-servers-only\n}\n\n\nclass OktaM2MSync:\n \"\"\"Service for syncing Okta M2M applications to MongoDB.\"\"\"\n\n def __init__(\n self,\n db: AsyncIOMotorDatabase,\n okta_domain: str,\n okta_api_token: str,\n ):\n \"\"\"Initialize Okta M2M sync service.\n\n Args:\n db: MongoDB database instance\n okta_domain: Okta org domain (e.g., integrator-9917255.okta.com)\n okta_api_token: Okta API token for Admin API access\n \"\"\"\n self.db = db\n self.okta_domain = okta_domain.replace(\"https://\", \"\").rstrip(\"/\")\n self.okta_api_token = okta_api_token\n self.collection = db[\"okta_m2m_clients\"]\n self.idp_collection = db[\"idp_m2m_clients\"]\n\n logger.info(f\"Initialized Okta M2M sync for domain: {self.okta_domain}\")\n\n async def _get_okta_applications(self) -> list[dict]:\n \"\"\"Fetch all applications from Okta Admin API.\n\n Returns:\n List of Okta application dictionaries\n\n Raises:\n ValueError: If Okta API request fails\n \"\"\"\n url = f\"https://{self.okta_domain}/api/v1/apps\"\n headers = {\n \"Accept\": \"application/json\",\n \"Content-Type\": \"application/json\",\n \"Authorization\": f\"SSWS {self.okta_api_token}\",\n }\n\n try:\n logger.info(f\"Fetching applications from Okta: {url}\")\n response = requests.get(url, headers=headers, timeout=30)\n response.raise_for_status()\n\n apps = response.json()\n logger.info(f\"Retrieved {len(apps)} applications from Okta\")\n return apps\n\n except requests.RequestException as e:\n logger.error(f\"Failed to fetch Okta applications: {e}\")\n raise ValueError(f\"Okta API request failed: {e}\")\n\n def _filter_m2m_applications(self, apps: list[dict]) -> list[dict]:\n \"\"\"Filter to only M2M service applications.\n\n Args:\n apps: List of all Okta applications\n\n Returns:\n Filtered list of M2M applications\n \"\"\"\n m2m_apps = []\n\n for app in apps:\n # M2M apps have signOnMode as \"OPENID_CONNECT\" and specific settings\n sign_on_mode = app.get(\"signOnMode\")\n app_name = app.get(\"name\", \"\")\n label = app.get(\"label\", \"\")\n\n # Filter for service apps (API Services type in Okta)\n # or apps that have client_credentials grant type\n settings = app.get(\"settings\", {})\n oauth_client = settings.get(\"oauthClient\", {})\n grant_types = oauth_client.get(\"grant_types\", [])\n\n if \"client_credentials\" in grant_types:\n logger.debug(f\"Found M2M app: {label} (ID: {app.get('id')})\")\n m2m_apps.append(app)\n\n logger.info(f\"Filtered to {len(m2m_apps)} M2M applications\")\n return m2m_apps\n\n def _determine_groups(self, client_id: str) -> list[str]:\n \"\"\"Determine groups for a client ID.\n\n This checks the hardcoded mapping (DEFAULT_CLIENT_GROUPS) to determine\n which groups a client should have. In the future, this could query a\n configuration table or use other logic.\n\n Args:\n client_id: Okta client ID\n\n Returns:\n List of group names for this client\n \"\"\"\n groups = DEFAULT_CLIENT_GROUPS.get(client_id, [])\n masked_id = f\"{client_id[:8]}...\" if client_id else \"\"\n logger.debug(f\"Client {masked_id} assigned groups: {groups}\")\n return groups\n\n async def sync_from_okta(self, force_full_sync: bool = False) -> dict:\n \"\"\"Sync M2M clients from Okta to MongoDB.\n\n Args:\n force_full_sync: If True, update all clients. Otherwise incremental.\n\n Returns:\n Dictionary with sync statistics\n \"\"\"\n logger.info(f\"Starting Okta M2M sync (force_full_sync={force_full_sync})\")\n\n added_count = 0\n updated_count = 0\n error_count = 0\n errors = []\n\n try:\n # Fetch all applications from Okta\n all_apps = await self._get_okta_applications()\n\n # Filter to M2M applications\n m2m_apps = self._filter_m2m_applications(all_apps)\n\n # Process each M2M app\n for app in m2m_apps:\n try:\n client_id = app.get(\"credentials\", {}).get(\"oauthClient\", {}).get(\"client_id\")\n\n if not client_id:\n logger.warning(f\"App {app.get('label')} has no client_id, skipping\")\n continue\n\n # Check if client already exists in database\n existing = await self.collection.find_one({\"client_id\": client_id})\n\n # Determine groups for this client\n groups = self._determine_groups(client_id)\n\n client_doc = {\n \"client_id\": client_id,\n \"name\": app.get(\"label\", client_id),\n \"description\": app.get(\"_embedded\", {})\n .get(\"user\", {})\n .get(\"profile\", {})\n .get(\"description\"),\n \"groups\": groups,\n \"enabled\": app.get(\"status\") == \"ACTIVE\",\n \"okta_app_id\": app.get(\"id\"),\n \"last_synced\": datetime.utcnow(),\n }\n\n masked_cid = f\"{client_id[:8]}...\" if client_id else \"\"\n\n if existing:\n # Update existing record\n client_doc[\"updated_at\"] = datetime.utcnow()\n await self.collection.update_one(\n {\"client_id\": client_id}, {\"$set\": client_doc}\n )\n updated_count += 1\n logger.info(f\"Updated client: {masked_cid}\")\n else:\n # Insert new record\n client_doc[\"created_at\"] = datetime.utcnow()\n client_doc[\"updated_at\"] = datetime.utcnow()\n await self.collection.insert_one(client_doc)\n added_count += 1\n logger.info(f\"Added new client: {masked_cid}\")\n\n # Also sync to generic idp_m2m_clients collection for groups enrichment\n idp_doc = {\n \"client_id\": client_id,\n \"name\": app.get(\"label\", client_id),\n \"description\": client_doc.get(\"description\"),\n \"groups\": groups,\n \"enabled\": client_doc[\"enabled\"],\n \"provider\": \"okta\",\n \"idp_app_id\": app.get(\"id\"),\n \"updated_at\": datetime.utcnow(),\n }\n\n existing_idp = await self.idp_collection.find_one({\"client_id\": client_id})\n if existing_idp:\n await self.idp_collection.update_one(\n {\"client_id\": client_id}, {\"$set\": idp_doc}\n )\n else:\n idp_doc[\"created_at\"] = datetime.utcnow()\n await self.idp_collection.insert_one(idp_doc)\n\n except Exception as e:\n error_msg = f\"Failed to process app {app.get('label')}: {e}\"\n logger.error(error_msg)\n errors.append(error_msg)\n error_count += 1\n\n logger.info(\n f\"Sync completed: {added_count} added, {updated_count} updated, \"\n f\"{error_count} errors\"\n )\n\n return {\n \"synced_count\": added_count + updated_count,\n \"added_count\": added_count,\n \"updated_count\": updated_count,\n \"removed_count\": 0,\n \"errors\": errors,\n }\n\n except Exception as e:\n logger.exception(f\"Okta sync failed: {e}\")\n return {\n \"synced_count\": 0,\n \"added_count\": 0,\n \"updated_count\": 0,\n \"removed_count\": 0,\n \"errors\": [str(e)],\n }\n\n async def get_all_clients(self) -> list[OktaM2MClient]:\n \"\"\"Get all M2M clients from MongoDB.\n\n Returns:\n List of OktaM2MClient objects\n \"\"\"\n cursor = self.collection.find({})\n docs = await cursor.to_list(length=None)\n\n clients = []\n for doc in docs:\n try:\n # Remove MongoDB _id field\n doc.pop(\"_id\", None)\n client = OktaM2MClient(**doc)\n clients.append(client)\n except Exception as e:\n logger.warning(f\"Failed to parse client document: {e}\")\n\n return clients\n\n async def get_client_groups(self, client_id: str) -> list[str]:\n \"\"\"Get groups for a specific client ID.\n\n Args:\n client_id: Okta client ID\n\n Returns:\n List of group names, empty if client not found\n \"\"\"\n doc = await self.collection.find_one({\"client_id\": client_id})\n if doc:\n return doc.get(\"groups\", [])\n return []\n\n async def update_client_groups(\n self,\n client_id: str,\n groups: list[str],\n ) -> bool:\n \"\"\"Update groups for a specific client.\n\n Args:\n client_id: Okta client ID\n groups: New list of groups\n\n Returns:\n True if updated, False if client not found\n \"\"\"\n result = await self.collection.update_one(\n {\"client_id\": client_id},\n {\n \"$set\": {\n \"groups\": groups,\n \"updated_at\": datetime.utcnow(),\n }\n },\n )\n\n # Also update in generic idp_m2m_clients collection\n await self.idp_collection.update_one(\n {\"client_id\": client_id},\n {\n \"$set\": {\n \"groups\": groups,\n \"updated_at\": datetime.utcnow(),\n }\n },\n )\n\n if result.modified_count > 0:\n logger.info(f\"Updated groups for client {client_id}: {groups}\")\n return True\n\n logger.warning(f\"Client {client_id} not found for update\")\n return False\n\n\ndef get_okta_m2m_sync(db: AsyncIOMotorDatabase) -> OktaM2MSync | None:\n \"\"\"Factory function to create OktaM2MSync instance.\n\n Args:\n db: MongoDB database instance\n\n Returns:\n OktaM2MSync instance if Okta is configured, None otherwise\n \"\"\"\n okta_domain = os.getenv(\"OKTA_DOMAIN\")\n okta_api_token = os.getenv(\"OKTA_API_TOKEN\")\n\n if not okta_domain or not okta_api_token:\n logger.warning(\"Okta not configured (missing OKTA_DOMAIN or OKTA_API_TOKEN)\")\n return None\n\n return OktaM2MSync(\n db=db,\n okta_domain=okta_domain,\n okta_api_token=okta_api_token,\n )\n" }, { "path": "registry/services/peer_federation_service.py", "content": "\"\"\"\nService for managing peer registry federation configurations.\n\nThis module provides CRUD operations for peer registry connections,\nusing the repository pattern for storage abstraction. Supports both\nMongoDB/DocumentDB and file-based storage backends.\n\nBased on: registry/services/server_service.py and registry/services/agent_service.py\n\"\"\"\n\nimport asyncio\nimport logging\nimport time\nimport uuid\nfrom datetime import UTC, datetime\nfrom threading import Lock as ThreadingLock\nfrom typing import Any, Literal, Optional\n\nfrom ..core.metrics import PEER_SYNC_DURATION_SECONDS, PEER_SYNC_FAILURES\nfrom ..repositories.factory import (\n get_peer_federation_repository,\n get_search_repository,\n get_security_scan_repository,\n)\nfrom ..repositories.interfaces import PeerFederationRepositoryBase\nfrom ..schemas.agent_models import AgentCard\nfrom ..schemas.peer_federation_schema import (\n PeerRegistryConfig,\n PeerSyncStatus,\n SyncHistoryEntry,\n SyncResult,\n)\nfrom .agent_service import agent_service\nfrom .federation.peer_registry_client import PeerRegistryClient\nfrom .server_service import server_service\n\nlogger = logging.getLogger(__name__)\n\n\nclass PeerFederationService:\n \"\"\"Service for managing peer registry federation configurations.\n\n Uses repository pattern for data access, supporting multiple storage backends.\n \"\"\"\n\n _instance: Optional[\"PeerFederationService\"] = None\n _lock: ThreadingLock = ThreadingLock()\n\n def __new__(cls) -> \"PeerFederationService\":\n \"\"\"Singleton pattern with thread-safe double-checked locking.\"\"\"\n if cls._instance is None:\n with cls._lock:\n if cls._instance is None:\n cls._instance = super().__new__(cls)\n cls._instance._initialized = False\n return cls._instance\n\n def __init__(self):\n \"\"\"Initialize peer federation service with repository.\"\"\"\n # Singleton: only initialize once\n if self._initialized:\n return\n\n self._repo: PeerFederationRepositoryBase | None = None\n self._operation_lock = asyncio.Lock() # Async-safe lock for operations\n\n # In-memory caches for quick access (populated from repository)\n self.registered_peers: dict[str, PeerRegistryConfig] = {}\n self.peer_sync_status: dict[str, PeerSyncStatus] = {}\n\n self._initialized = True\n\n def _get_repo(self) -> PeerFederationRepositoryBase:\n \"\"\"Get or create repository instance.\"\"\"\n if self._repo is None:\n self._repo = get_peer_federation_repository()\n return self._repo\n\n async def load_peers_and_state(self) -> None:\n \"\"\"Load peer configs and sync state from repository.\"\"\"\n logger.info(\"Loading peer federation data from repository...\")\n\n repo = self._get_repo()\n await repo.load_all()\n\n # Load peers into cache\n peers = await repo.list_peers()\n self.registered_peers = {peer.peer_id: peer for peer in peers}\n\n # Load sync statuses into cache\n statuses = await repo.list_sync_statuses()\n self.peer_sync_status = {status.peer_id: status for status in statuses}\n\n # Initialize sync status for any peers without one\n for peer_id in self.registered_peers.keys():\n if peer_id not in self.peer_sync_status:\n status = PeerSyncStatus(peer_id=peer_id)\n self.peer_sync_status[peer_id] = status\n await repo.update_sync_status(peer_id, status)\n\n logger.info(\n f\"Loaded {len(self.registered_peers)} peers, {len(self.peer_sync_status)} sync statuses\"\n )\n\n # Synchronous wrapper for backward compatibility\n def load_peers_and_state_sync(self) -> None:\n \"\"\"Synchronous wrapper for load_peers_and_state.\n\n DEPRECATED: Use async version load_peers_and_state() instead.\n \"\"\"\n import asyncio\n\n loop = asyncio.get_event_loop()\n if loop.is_running():\n # Create a new task in the running loop\n asyncio.create_task(self.load_peers_and_state())\n else:\n loop.run_until_complete(self.load_peers_and_state())\n\n async def add_peer(\n self,\n config: PeerRegistryConfig,\n ) -> PeerRegistryConfig:\n \"\"\"\n Add a new peer registry configuration.\n\n Args:\n config: Peer registry config to add\n\n Returns:\n Added peer config\n\n Raises:\n ValueError: If peer_id already exists or is invalid\n \"\"\"\n async with self._operation_lock:\n repo = self._get_repo()\n\n # Create peer via repository (handles validation and timestamps)\n created_peer = await repo.create_peer(config)\n\n # Update cache\n self.registered_peers[created_peer.peer_id] = created_peer\n\n # Get/create sync status\n sync_status = await repo.get_sync_status(created_peer.peer_id)\n if sync_status:\n self.peer_sync_status[created_peer.peer_id] = sync_status\n\n logger.info(\n f\"New peer registered: '{created_peer.name}' with peer_id \"\n f\"'{created_peer.peer_id}' (enabled={created_peer.enabled})\"\n )\n\n return created_peer\n\n async def get_peer(\n self,\n peer_id: str,\n ) -> PeerRegistryConfig:\n \"\"\"\n Get peer config by peer_id.\n\n Args:\n peer_id: Peer identifier\n\n Returns:\n Peer config\n\n Raises:\n ValueError: If peer not found\n \"\"\"\n # Check cache first\n if peer_id in self.registered_peers:\n return self.registered_peers[peer_id]\n\n # Try repository\n repo = self._get_repo()\n peer_config = await repo.get_peer(peer_id)\n\n if not peer_config:\n raise ValueError(f\"Peer not found: {peer_id}\")\n\n # Update cache\n self.registered_peers[peer_id] = peer_config\n return peer_config\n\n async def update_peer(\n self,\n peer_id: str,\n updates: dict[str, Any],\n ) -> PeerRegistryConfig:\n \"\"\"\n Update an existing peer config.\n\n Args:\n peer_id: Peer identifier\n updates: Dictionary of fields to update\n\n Returns:\n Updated peer config\n\n Raises:\n ValueError: If peer not found or invalid\n \"\"\"\n async with self._operation_lock:\n repo = self._get_repo()\n\n # Check if token is being updated for audit logging\n is_token_update = \"federation_token\" in updates\n had_token_before = False\n\n if is_token_update:\n # Get existing peer to check if it had a token\n try:\n existing_peer = await repo.get_peer(peer_id)\n had_token_before = existing_peer and existing_peer.federation_token is not None\n except Exception:\n pass # Continue with update even if we can't check existing state\n\n # Update via repository (handles validation)\n updated_peer = await repo.update_peer(peer_id, updates)\n\n # Update cache\n self.registered_peers[peer_id] = updated_peer\n\n # Audit logging for token updates\n if is_token_update:\n logger.info(\n f\"AUDIT: Federation token updated for peer '{peer_id}' \"\n f\"(name='{updated_peer.name}'). \"\n f\"Previous token existed: {had_token_before}, \"\n f\"New token provided: {updated_peer.federation_token is not None}\"\n )\n\n logger.info(f\"Peer '{updated_peer.name}' ({peer_id}) updated\")\n return updated_peer\n\n async def remove_peer(\n self,\n peer_id: str,\n ) -> bool:\n \"\"\"\n Remove a peer from registry.\n\n Also cleans up all servers and agents synced from this peer\n (paths starting with /{peer_id}/).\n\n Args:\n peer_id: Peer identifier\n\n Returns:\n True if deleted successfully\n\n Raises:\n ValueError: If peer not found\n \"\"\"\n async with self._operation_lock:\n # Get peer name for logging before deletion\n peer_name = self.registered_peers.get(\n peer_id,\n PeerRegistryConfig(peer_id=peer_id, name=\"unknown\", endpoint=\"http://unknown\"),\n ).name\n\n # Clean up synced servers from this peer\n servers_deleted = await self._cleanup_synced_servers(peer_id)\n logger.info(f\"Deleted {servers_deleted} synced servers from peer '{peer_id}'\")\n\n # Clean up synced agents from this peer\n agents_deleted = await self._cleanup_synced_agents(peer_id)\n logger.info(f\"Deleted {agents_deleted} synced agents from peer '{peer_id}'\")\n\n repo = self._get_repo()\n\n # Delete via repository (handles cascade delete of sync status)\n result = await repo.delete_peer(peer_id)\n\n if result:\n # Remove from caches\n if peer_id in self.registered_peers:\n del self.registered_peers[peer_id]\n if peer_id in self.peer_sync_status:\n del self.peer_sync_status[peer_id]\n\n logger.info(\n f\"Successfully removed peer '{peer_name}' with peer_id '{peer_id}' \"\n f\"(cleaned up {servers_deleted} servers, {agents_deleted} agents)\"\n )\n\n return result\n\n async def _cleanup_synced_servers(\n self,\n peer_id: str,\n ) -> int:\n \"\"\"\n Delete all servers synced from a specific peer.\n\n Args:\n peer_id: Peer identifier\n\n Returns:\n Number of servers deleted\n \"\"\"\n deleted_count = 0\n path_prefix = f\"/{peer_id}/\"\n\n try:\n # Get all servers from the repository\n all_servers = await server_service.get_all_servers()\n\n # Find servers with paths starting with the peer prefix\n for path in list(all_servers.keys()):\n if path.startswith(path_prefix):\n try:\n success = await server_service.remove_server(path)\n if success:\n deleted_count += 1\n logger.debug(f\"Deleted synced server: {path}\")\n else:\n logger.warning(f\"Failed to delete synced server: {path}\")\n except Exception as e:\n logger.error(f\"Error deleting synced server {path}: {e}\")\n\n except Exception as e:\n logger.error(f\"Error cleaning up synced servers for peer '{peer_id}': {e}\")\n\n return deleted_count\n\n async def _cleanup_synced_agents(\n self,\n peer_id: str,\n ) -> int:\n \"\"\"\n Delete all agents synced from a specific peer.\n\n Args:\n peer_id: Peer identifier\n\n Returns:\n Number of agents deleted\n \"\"\"\n deleted_count = 0\n path_prefix = f\"/{peer_id}/\"\n\n try:\n # Get all agents from the repository\n all_agents = await agent_service.get_all_agents()\n\n # Find agents with paths starting with the peer prefix\n for agent in all_agents:\n if agent.path.startswith(path_prefix):\n try:\n success = await agent_service.delete_agent(agent.path)\n if success:\n deleted_count += 1\n logger.debug(f\"Deleted synced agent: {agent.path}\")\n else:\n logger.warning(f\"Failed to delete synced agent: {agent.path}\")\n except Exception as e:\n logger.error(f\"Error deleting synced agent {agent.path}: {e}\")\n\n except Exception as e:\n logger.error(f\"Error cleaning up synced agents for peer '{peer_id}': {e}\")\n\n return deleted_count\n\n async def list_peers(\n self,\n enabled: bool | None = None,\n ) -> list[PeerRegistryConfig]:\n \"\"\"\n List all configured peers with optional filtering.\n\n Args:\n enabled: If True, return only enabled peers.\n If False, return only disabled peers.\n If None, return all peers.\n\n Returns:\n List of peer configs\n \"\"\"\n peers = list(self.registered_peers.values())\n\n if enabled is None:\n return peers\n\n return [peer for peer in peers if peer.enabled == enabled]\n\n async def get_peer_by_client_id(\n self,\n client_id: str,\n ) -> PeerRegistryConfig | None:\n \"\"\"\n Find peer config by Azure AD/Keycloak client_id (from azp claim).\n\n This enables peer identification during federation requests by matching\n the client_id from the OAuth2 token to a registered peer's expected_client_id.\n\n Args:\n client_id: The client_id from the token's azp claim\n\n Returns:\n PeerRegistryConfig if found, None otherwise\n \"\"\"\n if not client_id:\n return None\n\n peers = await self.list_peers()\n for peer in peers:\n if peer.expected_client_id == client_id:\n logger.debug(f\"Found peer '{peer.peer_id}' for client_id '{client_id}'\")\n return peer\n\n logger.debug(f\"No peer found for client_id '{client_id}'\")\n return None\n\n async def get_sync_status(\n self,\n peer_id: str,\n ) -> PeerSyncStatus | None:\n \"\"\"\n Get sync status for a peer.\n\n Args:\n peer_id: Peer identifier\n\n Returns:\n PeerSyncStatus or None if not found\n \"\"\"\n # Check cache first\n if peer_id in self.peer_sync_status:\n return self.peer_sync_status[peer_id]\n\n # Try repository\n repo = self._get_repo()\n status = await repo.get_sync_status(peer_id)\n\n if status:\n self.peer_sync_status[peer_id] = status\n\n return status\n\n async def update_sync_status(\n self,\n peer_id: str,\n sync_status: PeerSyncStatus,\n ) -> None:\n \"\"\"\n Update sync status for a peer.\n\n Args:\n peer_id: Peer identifier\n sync_status: Updated sync status\n \"\"\"\n repo = self._get_repo()\n await repo.update_sync_status(peer_id, sync_status)\n\n # Update cache\n self.peer_sync_status[peer_id] = sync_status\n\n logger.debug(f\"Updated sync status for peer '{peer_id}'\")\n\n async def sync_peer(\n self,\n peer_id: str,\n ) -> SyncResult:\n \"\"\"\n Sync servers and agents from a single peer.\n\n Args:\n peer_id: Peer identifier\n\n Returns:\n SyncResult with sync statistics\n\n Raises:\n ValueError: If peer not found or disabled\n \"\"\"\n # Start timing\n start_time = time.time()\n\n # Generate sync ID\n sync_id = f\"sync-{datetime.now(UTC).strftime('%Y%m%d-%H%M%S')}-{uuid.uuid4().hex[:8]}\"\n\n # Get peer config\n peer_config = await self.get_peer(peer_id)\n\n # Check if peer is enabled\n if not peer_config.enabled:\n error_msg = f\"Peer '{peer_id}' is disabled. Enable it before syncing.\"\n logger.error(error_msg)\n raise ValueError(error_msg)\n\n # Get current sync status for incremental sync\n sync_status = await self.get_sync_status(peer_id)\n if not sync_status:\n # Initialize if not exists\n sync_status = PeerSyncStatus(peer_id=peer_id)\n\n since_generation = sync_status.current_generation\n\n logger.info(\n f\"Starting sync from peer '{peer_id}' ({peer_config.name}) \"\n f\"with generation {since_generation}\"\n )\n\n # Mark sync as in progress\n sync_status.sync_in_progress = True\n sync_status.last_sync_attempt = datetime.now(UTC)\n await self.update_sync_status(peer_id, sync_status)\n\n try:\n # Create PeerRegistryClient for this peer\n client = PeerRegistryClient(\n peer_config=peer_config, timeout_seconds=30, retry_attempts=3\n )\n\n # Fetch servers using client\n servers = client.fetch_servers(since_generation=since_generation)\n\n # Fetch agents using client\n agents = client.fetch_agents(since_generation=since_generation)\n\n # Fetch security scans using client\n security_scans = client.fetch_security_scans()\n\n # Check for fetch failures (None indicates error, not empty result)\n # Fixes issue #561: None was silently converted to [] making auth\n # failures appear as successful syncs with 0 items.\n fetch_errors = []\n if servers is None:\n fetch_errors.append(\"servers\")\n servers = []\n if agents is None:\n fetch_errors.append(\"agents\")\n agents = []\n if security_scans is None:\n fetch_errors.append(\"security_scans\")\n security_scans = []\n\n # If any fetch failed, raise error to mark sync as failed\n if fetch_errors:\n error_types = \", \".join(fetch_errors)\n raise ValueError(\n f\"Failed to fetch {error_types} from peer '{peer_config.peer_id}'. \"\n f\"This typically indicates authentication or network errors. \"\n f\"Check peer configuration and logs for details.\"\n )\n\n logger.info(\n f\"Fetched {len(servers)} servers, {len(agents)} agents, and \"\n f\"{len(security_scans)} security scans from peer '{peer_id}'\"\n )\n\n # Apply filters based on peer config\n servers = self._filter_servers_by_config(servers, peer_config)\n agents = self._filter_agents_by_config(agents, peer_config)\n\n logger.info(\n f\"After filtering: {len(servers)} servers and {len(agents)} agents \"\n f\"from peer '{peer_id}'\"\n )\n\n # Store fetched items\n servers_stored = await self._store_synced_servers(peer_id, servers)\n agents_stored = await self._store_synced_agents(peer_id, agents)\n scans_stored = await self._store_synced_security_scans(peer_id, security_scans)\n\n # Extract paths from fetched items for orphan detection\n fetched_server_paths = [s.get(\"path\", \"\") for s in servers]\n fetched_agent_paths = [a.get(\"path\", \"\") for a in agents]\n\n # Detect orphaned items\n orphaned_servers, orphaned_agents = await self.detect_orphaned_items(\n peer_id, fetched_server_paths, fetched_agent_paths\n )\n\n # Handle orphaned items (mark by default)\n if orphaned_servers or orphaned_agents:\n await self.handle_orphaned_items(\n peer_id, orphaned_servers, orphaned_agents, action=\"mark\"\n )\n\n # Calculate duration\n duration_seconds = time.time() - start_time\n\n # Update sync status with success\n sync_status.sync_in_progress = False\n sync_status.last_successful_sync = datetime.now(UTC)\n\n # Only increment generation if items were actually synced\n if servers_stored > 0 or agents_stored > 0 or since_generation == 0:\n sync_status.current_generation += 1\n\n sync_status.total_servers_synced = servers_stored\n sync_status.total_agents_synced = agents_stored\n sync_status.consecutive_failures = 0\n sync_status.is_healthy = True\n sync_status.last_health_check = datetime.now(UTC)\n\n # Create history entry\n history_entry = SyncHistoryEntry(\n sync_id=sync_id,\n started_at=sync_status.last_sync_attempt,\n completed_at=datetime.now(UTC),\n success=True,\n servers_synced=servers_stored,\n agents_synced=agents_stored,\n servers_orphaned=len(orphaned_servers),\n agents_orphaned=len(orphaned_agents),\n sync_generation=sync_status.current_generation,\n full_sync=(since_generation == 0),\n )\n sync_status.add_history_entry(history_entry)\n\n # Persist updated status\n await self.update_sync_status(peer_id, sync_status)\n\n logger.info(\n f\"Successfully synced peer '{peer_id}': \"\n f\"{servers_stored} servers, {agents_stored} agents, {scans_stored} security scans, \"\n f\"{len(orphaned_servers)} orphaned servers, {len(orphaned_agents)} orphaned agents \"\n f\"in {duration_seconds:.2f} seconds\"\n )\n\n # Record success metrics\n PEER_SYNC_DURATION_SECONDS.labels(peer_id=peer_id, success=\"true\").set(duration_seconds)\n\n return SyncResult(\n success=True,\n peer_id=peer_id,\n servers_synced=servers_stored,\n agents_synced=agents_stored,\n servers_orphaned=len(orphaned_servers),\n agents_orphaned=len(orphaned_agents),\n duration_seconds=duration_seconds,\n new_generation=sync_status.current_generation,\n )\n\n except Exception as e:\n # Calculate duration even on failure\n duration_seconds = time.time() - start_time\n\n # Update sync status with failure\n sync_status.sync_in_progress = False\n sync_status.consecutive_failures += 1\n sync_status.is_healthy = False\n sync_status.last_health_check = datetime.now(UTC)\n\n error_msg = str(e)\n\n # Create history entry for failure\n history_entry = SyncHistoryEntry(\n sync_id=sync_id,\n started_at=sync_status.last_sync_attempt,\n completed_at=datetime.now(UTC),\n success=False,\n servers_synced=0,\n agents_synced=0,\n servers_orphaned=0,\n agents_orphaned=0,\n error_message=error_msg,\n sync_generation=sync_status.current_generation,\n full_sync=(since_generation == 0),\n )\n sync_status.add_history_entry(history_entry)\n\n # Persist updated status\n await self.update_sync_status(peer_id, sync_status)\n\n # Record failure metrics\n # Determine failure type from error message\n failure_type = \"unknown\"\n if \"authentication\" in error_msg.lower() or \"token\" in error_msg.lower():\n failure_type = \"auth_error\"\n elif \"network\" in error_msg.lower() or \"timeout\" in error_msg.lower():\n failure_type = \"network_error\"\n elif \"failed to fetch\" in error_msg.lower():\n failure_type = \"fetch_error\"\n\n PEER_SYNC_FAILURES.labels(peer_id=peer_id, failure_type=failure_type).inc()\n PEER_SYNC_DURATION_SECONDS.labels(peer_id=peer_id, success=\"false\").set(\n duration_seconds\n )\n\n logger.error(f\"Failed to sync peer '{peer_id}': {error_msg}\", exc_info=True)\n\n return SyncResult(\n success=False,\n peer_id=peer_id,\n servers_synced=0,\n agents_synced=0,\n servers_orphaned=0,\n agents_orphaned=0,\n error_message=error_msg,\n duration_seconds=duration_seconds,\n new_generation=sync_status.current_generation,\n )\n\n async def sync_all_peers(\n self,\n enabled_only: bool = True,\n ) -> dict[str, SyncResult]:\n \"\"\"\n Sync all (or enabled) peers.\n\n Args:\n enabled_only: If True, only sync enabled peers\n\n Returns:\n Dictionary mapping peer_id to SyncResult\n \"\"\"\n peers = await self.list_peers(enabled=enabled_only if enabled_only else None)\n\n logger.info(\n f\"Starting sync for {len(peers)} peers ({'enabled only' if enabled_only else 'all'})\"\n )\n\n results = {}\n\n for peer in peers:\n peer_id = peer.peer_id\n\n try:\n logger.info(f\"Syncing peer '{peer_id}' ({peer.name})...\")\n result = await self.sync_peer(peer_id)\n results[peer_id] = result\n\n if result.success:\n logger.info(\n f\"Successfully synced '{peer_id}': \"\n f\"{result.servers_synced} servers, {result.agents_synced} agents\"\n )\n else:\n logger.error(f\"Failed to sync '{peer_id}': {result.error_message}\")\n\n except Exception as e:\n logger.error(f\"Unexpected error syncing peer '{peer_id}': {e}\", exc_info=True)\n results[peer_id] = SyncResult(\n success=False,\n peer_id=peer_id,\n servers_synced=0,\n agents_synced=0,\n servers_orphaned=0,\n agents_orphaned=0,\n error_message=str(e),\n duration_seconds=0.0,\n new_generation=0,\n )\n\n # Summary logging\n successful = sum(1 for r in results.values() if r.success)\n failed = len(results) - successful\n total_servers = sum(r.servers_synced for r in results.values())\n total_agents = sum(r.agents_synced for r in results.values())\n\n logger.info(\n f\"Sync completed: {successful} succeeded, {failed} failed. \"\n f\"Total: {total_servers} servers, {total_agents} agents\"\n )\n\n return results\n\n def _filter_servers_by_config(\n self,\n servers: list[dict[str, Any]],\n peer_config: PeerRegistryConfig,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Filter servers based on peer sync configuration.\n\n Args:\n servers: List of server data from peer\n peer_config: Peer configuration with sync settings\n\n Returns:\n Filtered list of servers\n \"\"\"\n if peer_config.sync_mode == \"all\":\n return servers\n\n if peer_config.sync_mode == \"whitelist\":\n if not peer_config.whitelist_servers:\n logger.debug(\n f\"Peer '{peer_config.peer_id}' has empty whitelist_servers, \"\n \"returning empty list\"\n )\n return []\n\n filtered = []\n for server in servers:\n server_path = server.get(\"path\", \"\")\n if server_path in peer_config.whitelist_servers:\n filtered.append(server)\n logger.debug(\n f\"Server '{server_path}' matches whitelist for peer '{peer_config.peer_id}'\"\n )\n\n logger.info(\n f\"Filtered {len(servers)} servers to {len(filtered)} using whitelist \"\n f\"for peer '{peer_config.peer_id}'\"\n )\n return filtered\n\n if peer_config.sync_mode == \"tag_filter\":\n if not peer_config.tag_filters:\n logger.debug(\n f\"Peer '{peer_config.peer_id}' has empty tag_filters, returning empty list\"\n )\n return []\n\n filtered = []\n for server in servers:\n if self._matches_tag_filter(server, peer_config.tag_filters):\n filtered.append(server)\n logger.debug(\n f\"Server '{server.get('path', '')}' matches tag filter \"\n f\"for peer '{peer_config.peer_id}'\"\n )\n\n logger.info(\n f\"Filtered {len(servers)} servers to {len(filtered)} using tag filter \"\n f\"for peer '{peer_config.peer_id}'\"\n )\n return filtered\n\n logger.warning(\n f\"Unknown sync_mode '{peer_config.sync_mode}' for peer \"\n f\"'{peer_config.peer_id}', returning all servers\"\n )\n return servers\n\n def _filter_agents_by_config(\n self,\n agents: list[dict[str, Any]],\n peer_config: PeerRegistryConfig,\n ) -> list[dict[str, Any]]:\n \"\"\"\n Filter agents based on peer sync configuration.\n\n Args:\n agents: List of agent data from peer\n peer_config: Peer configuration with sync settings\n\n Returns:\n Filtered list of agents\n \"\"\"\n if peer_config.sync_mode == \"all\":\n return agents\n\n if peer_config.sync_mode == \"whitelist\":\n if not peer_config.whitelist_agents:\n logger.debug(\n f\"Peer '{peer_config.peer_id}' has empty whitelist_agents, returning empty list\"\n )\n return []\n\n filtered = []\n for agent in agents:\n agent_path = agent.get(\"path\", \"\")\n if agent_path in peer_config.whitelist_agents:\n filtered.append(agent)\n logger.debug(\n f\"Agent '{agent_path}' matches whitelist for peer '{peer_config.peer_id}'\"\n )\n\n logger.info(\n f\"Filtered {len(agents)} agents to {len(filtered)} using whitelist \"\n f\"for peer '{peer_config.peer_id}'\"\n )\n return filtered\n\n if peer_config.sync_mode == \"tag_filter\":\n if not peer_config.tag_filters:\n logger.debug(\n f\"Peer '{peer_config.peer_id}' has empty tag_filters, returning empty list\"\n )\n return []\n\n filtered = []\n for agent in agents:\n if self._matches_tag_filter(agent, peer_config.tag_filters):\n filtered.append(agent)\n logger.debug(\n f\"Agent '{agent.get('path', '')}' matches tag filter \"\n f\"for peer '{peer_config.peer_id}'\"\n )\n\n logger.info(\n f\"Filtered {len(agents)} agents to {len(filtered)} using tag filter \"\n f\"for peer '{peer_config.peer_id}'\"\n )\n return filtered\n\n logger.warning(\n f\"Unknown sync_mode '{peer_config.sync_mode}' for peer \"\n f\"'{peer_config.peer_id}', returning all agents\"\n )\n return agents\n\n def _matches_tag_filter(\n self,\n item: dict[str, Any],\n tag_filters: list[str],\n ) -> bool:\n \"\"\"\n Check if an item matches any of the tag filters.\n\n Args:\n item: Server or agent data dict\n tag_filters: List of tag strings to match\n\n Returns:\n True if item has any matching tag\n \"\"\"\n # Extract tags from item - could be in \"tags\" or \"categories\" field\n item_tags = item.get(\"tags\", [])\n if not isinstance(item_tags, list):\n item_tags = []\n\n # Also check categories field\n item_categories = item.get(\"categories\", [])\n if not isinstance(item_categories, list):\n item_categories = []\n\n # Combine both lists\n all_item_tags = item_tags + item_categories\n\n # Check if any filter matches any tag\n for filter_tag in tag_filters:\n if filter_tag in all_item_tags:\n return True\n\n return False\n\n async def detect_orphaned_items(\n self,\n peer_id: str,\n current_server_paths: list[str],\n current_agent_paths: list[str],\n ) -> tuple[list[str], list[str]]:\n \"\"\"\n Detect items that exist locally but no longer exist in peer.\n\n Args:\n peer_id: Peer identifier\n current_server_paths: Paths of servers currently in peer\n current_agent_paths: Paths of agents currently in peer\n\n Returns:\n Tuple of (orphaned_server_paths, orphaned_agent_paths)\n \"\"\"\n orphaned_servers = []\n orphaned_agents = []\n\n # Normalize current paths for comparison (ensure leading slash)\n normalized_server_paths = {\n p if p.startswith(\"/\") else f\"/{p}\" for p in current_server_paths if p\n }\n normalized_agent_paths = {\n p if p.startswith(\"/\") else f\"/{p}\" for p in current_agent_paths if p\n }\n\n # Find all local servers with sync_metadata.source_peer_id == peer_id\n all_servers = await server_service.get_all_servers()\n for server in all_servers.values():\n server_dict = server if isinstance(server, dict) else server\n sync_metadata = server_dict.get(\"sync_metadata\") or {}\n path = server_dict.get(\"path\", \"\")\n\n if sync_metadata.get(\"source_peer_id\") == peer_id:\n # Extract and normalize original path for comparison\n original_path = sync_metadata.get(\"original_path\", \"\")\n normalized_original = (\n original_path if original_path.startswith(\"/\") else f\"/{original_path}\"\n )\n\n # Check if normalized original path is in current peer paths\n if normalized_original not in normalized_server_paths:\n orphaned_servers.append(path)\n logger.debug(f\"Detected orphaned server: {path} (original: {original_path})\")\n\n # Find all local agents with sync_metadata.source_peer_id == peer_id\n all_agents = await agent_service.get_all_agents()\n for agent in all_agents:\n agent_dict = agent.model_dump() if hasattr(agent, \"model_dump\") else agent\n sync_metadata = agent_dict.get(\"sync_metadata\") or {}\n path = agent_dict.get(\"path\", \"\")\n\n if sync_metadata.get(\"source_peer_id\") == peer_id:\n # Extract and normalize original path for comparison\n original_path = sync_metadata.get(\"original_path\", \"\")\n normalized_original = (\n original_path if original_path.startswith(\"/\") else f\"/{original_path}\"\n )\n\n # Check if normalized original path is in current peer paths\n if normalized_original not in normalized_agent_paths:\n orphaned_agents.append(path)\n logger.debug(f\"Detected orphaned agent: {path} (original: {original_path})\")\n\n logger.info(\n f\"Detected {len(orphaned_servers)} orphaned servers and \"\n f\"{len(orphaned_agents)} orphaned agents from peer '{peer_id}'\"\n )\n\n return orphaned_servers, orphaned_agents\n\n async def mark_item_as_orphaned(\n self,\n item_path: str,\n item_type: Literal[\"server\", \"agent\"],\n ) -> bool:\n \"\"\"\n Mark a synced item as orphaned.\n\n Args:\n item_path: Path of the item (prefixed)\n item_type: \"server\" or \"agent\"\n\n Returns:\n True if marked successfully\n \"\"\"\n try:\n if item_type == \"server\":\n existing_server = await server_service.get_server_info(item_path)\n if not existing_server:\n logger.warning(f\"Server not found for orphan marking: {item_path}\")\n return False\n\n # get_server_info returns a dict\n server_dict = existing_server\n\n # Update sync_metadata\n sync_metadata = server_dict.get(\"sync_metadata\") or {}\n sync_metadata[\"is_orphaned\"] = True\n sync_metadata[\"orphaned_at\"] = datetime.now(UTC).isoformat()\n\n server_dict[\"sync_metadata\"] = sync_metadata\n\n # Update server\n success = await server_service.update_server(item_path, server_dict)\n if success:\n logger.info(f\"Marked server as orphaned: {item_path}\")\n return success\n\n elif item_type == \"agent\":\n existing_agent = await agent_service.get_agent_info(item_path)\n if not existing_agent:\n logger.warning(f\"Agent not found for orphan marking: {item_path}\")\n return False\n\n # get_agent_info returns an AgentCard Pydantic model, convert to dict\n agent_dict = existing_agent.model_dump()\n\n # Update sync_metadata\n sync_metadata = agent_dict.get(\"sync_metadata\") or {}\n sync_metadata[\"is_orphaned\"] = True\n sync_metadata[\"orphaned_at\"] = datetime.now(UTC).isoformat()\n\n agent_dict[\"sync_metadata\"] = sync_metadata\n\n # Update agent\n updated_agent = await agent_service.update_agent(item_path, agent_dict)\n if updated_agent:\n logger.info(f\"Marked agent as orphaned: {item_path}\")\n return True\n return False\n\n else:\n logger.error(f\"Invalid item_type: {item_type}\")\n return False\n\n except Exception as e:\n logger.error(\n f\"Failed to mark item as orphaned: {item_path} ({item_type}): {e}\",\n exc_info=True,\n )\n return False\n\n async def handle_orphaned_items(\n self,\n peer_id: str,\n orphaned_servers: list[str],\n orphaned_agents: list[str],\n action: Literal[\"mark\", \"delete\"] = \"mark\",\n ) -> int:\n \"\"\"\n Handle orphaned items by marking or deleting them.\n\n Args:\n peer_id: Source peer ID\n orphaned_servers: List of orphaned server paths\n orphaned_agents: List of orphaned agent paths\n action: \"mark\" to mark as orphaned, \"delete\" to remove\n\n Returns:\n Number of items handled\n \"\"\"\n handled_count = 0\n\n logger.info(\n f\"Handling {len(orphaned_servers)} orphaned servers and \"\n f\"{len(orphaned_agents)} orphaned agents from peer '{peer_id}' \"\n f\"(action: {action})\"\n )\n\n # Handle orphaned servers\n for server_path in orphaned_servers:\n try:\n if action == \"mark\":\n if await self.mark_item_as_orphaned(server_path, \"server\"):\n handled_count += 1\n elif action == \"delete\":\n success = await server_service.remove_server(server_path)\n if success:\n logger.info(f\"Deleted orphaned server: {server_path}\")\n handled_count += 1\n else:\n logger.error(f\"Failed to delete orphaned server: {server_path}\")\n except Exception as e:\n logger.error(\n f\"Failed to handle orphaned server {server_path}: {e}\",\n exc_info=True,\n )\n\n # Handle orphaned agents\n for agent_path in orphaned_agents:\n try:\n if action == \"mark\":\n if await self.mark_item_as_orphaned(agent_path, \"agent\"):\n handled_count += 1\n elif action == \"delete\":\n success = await agent_service.remove_agent(agent_path)\n if success:\n logger.info(f\"Deleted orphaned agent: {agent_path}\")\n handled_count += 1\n else:\n logger.error(f\"Failed to delete orphaned agent: {agent_path}\")\n except Exception as e:\n logger.error(f\"Failed to handle orphaned agent {agent_path}: {e}\", exc_info=True)\n\n logger.info(\n f\"Successfully handled {handled_count}/{len(orphaned_servers) + len(orphaned_agents)} \"\n f\"orphaned items from peer '{peer_id}'\"\n )\n\n return handled_count\n\n async def set_local_override(\n self,\n item_path: str,\n item_type: Literal[\"server\", \"agent\"],\n override: bool = True,\n ) -> bool:\n \"\"\"\n Set or clear local override flag for a synced item.\n\n When override=True, sync will skip this item to preserve local changes.\n\n Args:\n item_path: Path of the item\n item_type: \"server\" or \"agent\"\n override: True to set override, False to clear\n\n Returns:\n True if set successfully\n \"\"\"\n try:\n if item_type == \"server\":\n existing_server = await server_service.get_server_info(item_path)\n if not existing_server:\n logger.warning(f\"Server not found for local override: {item_path}\")\n return False\n\n # get_server_info returns a dict\n server_dict = existing_server\n\n # Update sync_metadata\n sync_metadata = server_dict.get(\"sync_metadata\") or {}\n sync_metadata[\"local_overrides\"] = override\n\n server_dict[\"sync_metadata\"] = sync_metadata\n\n # Update server\n success = await server_service.update_server(item_path, server_dict)\n if success:\n logger.info(f\"Set local override to {override} for server: {item_path}\")\n return success\n\n elif item_type == \"agent\":\n existing_agent = await agent_service.get_agent_info(item_path)\n if not existing_agent:\n logger.warning(f\"Agent not found for local override: {item_path}\")\n return False\n\n # get_agent_info returns an AgentCard Pydantic model, convert to dict\n agent_dict = existing_agent.model_dump()\n\n # Update sync_metadata\n sync_metadata = agent_dict.get(\"sync_metadata\") or {}\n sync_metadata[\"local_overrides\"] = override\n\n agent_dict[\"sync_metadata\"] = sync_metadata\n\n # Update agent\n updated_agent = await agent_service.update_agent(item_path, agent_dict)\n if updated_agent:\n logger.info(f\"Set local override to {override} for agent: {item_path}\")\n return True\n return False\n\n else:\n logger.error(f\"Invalid item_type: {item_type}\")\n return False\n\n except Exception as e:\n logger.error(\n f\"Failed to set local override for item: {item_path} ({item_type}): {e}\",\n exc_info=True,\n )\n return False\n\n def is_locally_overridden(\n self,\n item: dict[str, Any],\n ) -> bool:\n \"\"\"\n Check if an item has local override flag set.\n\n Args:\n item: Server or agent data dict\n\n Returns:\n True if item has local override\n \"\"\"\n sync_metadata = item.get(\"sync_metadata\") or {}\n return sync_metadata.get(\"local_overrides\", False)\n\n async def _index_server_for_search(\n self,\n path: str,\n server_data: dict[str, Any],\n ) -> None:\n \"\"\"\n Explicitly index a server for search (embeddings).\n\n This is called after successfully storing a synced server to ensure\n it's indexed for semantic search. The server_service methods should\n do this automatically, but this is a fallback to ensure it happens.\n\n Args:\n path: Server path (e.g., /peer-registry-lob-1/my-server)\n server_data: Server data dict\n \"\"\"\n try:\n search_repo = get_search_repository()\n is_enabled = server_data.get(\"is_enabled\", True)\n await search_repo.index_server(path, server_data, is_enabled)\n logger.debug(f\"Indexed synced server for search: {path}\")\n except Exception as e:\n logger.error(f\"Failed to index synced server {path} for search: {e}\")\n\n async def _index_agent_for_search(\n self,\n path: str,\n agent_card: AgentCard,\n ) -> None:\n \"\"\"\n Explicitly index an agent for search (embeddings).\n\n This is called after successfully storing a synced agent to ensure\n it's indexed for semantic search. The agent_service methods should\n do this automatically, but this is a fallback to ensure it happens.\n\n Args:\n path: Agent path (e.g., /peer-registry-lob-1/my-agent)\n agent_card: AgentCard instance\n \"\"\"\n try:\n search_repo = get_search_repository()\n is_enabled = await agent_service.is_agent_enabled(path)\n await search_repo.index_agent(path, agent_card, is_enabled)\n logger.debug(f\"Indexed synced agent for search: {path}\")\n except Exception as e:\n logger.error(f\"Failed to index synced agent {path} for search: {e}\")\n\n async def _store_synced_servers(\n self,\n peer_id: str,\n servers: list[dict[str, Any]],\n ) -> int:\n \"\"\"\n Store servers fetched from a peer.\n\n Args:\n peer_id: Source peer identifier\n servers: List of server data dictionaries\n\n Returns:\n Number of servers stored/updated\n \"\"\"\n stored_count = 0\n\n for server in servers:\n try:\n # Extract original path\n original_path = server.get(\"path\", \"\")\n\n if not original_path:\n logger.warning(f\"Server missing 'path' field, skipping: {server}\")\n continue\n\n # Normalize path - ensure it starts with /\n normalized_path = (\n original_path if original_path.startswith(\"/\") else f\"/{original_path}\"\n )\n\n # Prefix path with peer_id to avoid collisions\n # e.g., \"/my-server\" becomes \"/peer-central/my-server\"\n prefixed_path = f\"/{peer_id}{normalized_path}\"\n\n # Add sync_metadata to track origin\n sync_metadata = {\n \"source_peer_id\": peer_id,\n \"synced_at\": datetime.now(UTC).isoformat(),\n \"is_federated\": True,\n \"original_path\": original_path,\n }\n\n # Create a copy to avoid modifying original\n server_data = server.copy()\n server_data[\"path\"] = prefixed_path\n server_data[\"sync_metadata\"] = sync_metadata\n\n # Ensure UUID id field exists - use from peer if present, generate if not\n if \"id\" not in server_data or not server_data[\"id\"]:\n server_data[\"id\"] = str(uuid.uuid4())\n\n # Check if server already exists and store\n try:\n existing_server = await server_service.get_server_info(prefixed_path)\n if existing_server:\n # Check if locally overridden - if so, skip update\n # get_server_info returns a dict\n if self.is_locally_overridden(existing_server):\n logger.debug(\n f\"Skipping update for locally overridden server: {prefixed_path}\"\n )\n continue\n\n # Update existing server - returns bool\n success = await server_service.update_server(prefixed_path, server_data)\n if success:\n logger.debug(f\"Updated synced server: {prefixed_path}\")\n stored_count += 1\n # Explicitly index for search (embeddings)\n await self._index_server_for_search(prefixed_path, server_data)\n else:\n logger.error(f\"Failed to update server: {prefixed_path}\")\n else:\n # Register new server - returns dict with 'success' key\n result = await server_service.register_server(server_data)\n if result.get(\"success\"):\n logger.debug(f\"Registered synced server: {prefixed_path}\")\n stored_count += 1\n # Explicitly index for search (embeddings)\n await self._index_server_for_search(prefixed_path, server_data)\n else:\n logger.error(f\"Failed to register server: {prefixed_path}\")\n\n except Exception as e:\n logger.error(f\"Failed to store server '{prefixed_path}': {e}\", exc_info=True)\n\n except Exception as e:\n logger.error(\n f\"Failed to process server from peer '{peer_id}': {e}\",\n exc_info=True,\n )\n\n logger.info(f\"Stored {stored_count}/{len(servers)} servers from peer '{peer_id}'\")\n return stored_count\n\n async def _store_synced_agents(\n self,\n peer_id: str,\n agents: list[dict[str, Any]],\n ) -> int:\n \"\"\"\n Store agents fetched from a peer.\n\n Args:\n peer_id: Source peer identifier\n agents: List of agent data dictionaries\n\n Returns:\n Number of agents stored/updated\n \"\"\"\n stored_count = 0\n\n for agent in agents:\n try:\n # Extract original path\n original_path = agent.get(\"path\", \"\")\n\n if not original_path:\n logger.warning(f\"Agent missing 'path' field, skipping: {agent}\")\n continue\n\n # Normalize path - ensure it starts with /\n normalized_path = (\n original_path if original_path.startswith(\"/\") else f\"/{original_path}\"\n )\n\n # Prefix path with peer_id to avoid collisions\n # e.g., \"/code-reviewer\" becomes \"/peer-central/code-reviewer\"\n prefixed_path = f\"/{peer_id}{normalized_path}\"\n\n # Add sync_metadata to track origin\n sync_metadata = {\n \"source_peer_id\": peer_id,\n \"synced_at\": datetime.now(UTC).isoformat(),\n \"is_federated\": True,\n \"original_path\": original_path,\n }\n\n # Create a copy to avoid modifying original\n agent_data = agent.copy()\n agent_data[\"path\"] = prefixed_path\n agent_data[\"sync_metadata\"] = sync_metadata\n\n # Ensure UUID id field exists - use from peer if present, generate if not\n if \"id\" not in agent_data or not agent_data[\"id\"]:\n agent_data[\"id\"] = str(uuid.uuid4())\n\n # Check if agent already exists and store\n try:\n existing_agent = await agent_service.get_agent_info(prefixed_path)\n\n if existing_agent:\n # Check if locally overridden - if so, skip update\n # get_agent_info returns an AgentCard, convert to dict for is_locally_overridden\n if self.is_locally_overridden(existing_agent.model_dump()):\n logger.debug(\n f\"Skipping update for locally overridden agent: {prefixed_path}\"\n )\n continue\n\n # Update existing agent - returns AgentCard on success\n updated_agent = await agent_service.update_agent(prefixed_path, agent_data)\n if updated_agent:\n logger.debug(f\"Updated synced agent: {prefixed_path}\")\n stored_count += 1\n # Explicitly index for search (embeddings)\n await self._index_agent_for_search(prefixed_path, updated_agent)\n else:\n logger.error(f\"Failed to update agent: {prefixed_path}\")\n else:\n # Register new agent - create AgentCard instance\n agent_card = AgentCard(**agent_data)\n registered_agent = await agent_service.register_agent(agent_card)\n if registered_agent:\n logger.debug(f\"Registered synced agent: {prefixed_path}\")\n stored_count += 1\n # Explicitly index for search (embeddings)\n await self._index_agent_for_search(prefixed_path, registered_agent)\n else:\n logger.error(f\"Failed to register agent: {prefixed_path}\")\n\n except ValueError as e:\n # Validation errors\n logger.error(f\"Validation error storing agent '{prefixed_path}': {e}\")\n except Exception as e:\n logger.error(f\"Failed to store agent '{prefixed_path}': {e}\", exc_info=True)\n\n except Exception as e:\n logger.error(f\"Failed to process agent from peer '{peer_id}': {e}\", exc_info=True)\n\n logger.info(f\"Stored {stored_count}/{len(agents)} agents from peer '{peer_id}'\")\n return stored_count\n\n async def _store_synced_security_scans(\n self,\n peer_id: str,\n security_scans: list[dict[str, Any]],\n ) -> int:\n \"\"\"\n Store security scan results fetched from a peer.\n\n Args:\n peer_id: Source peer identifier\n security_scans: List of security scan dictionaries\n\n Returns:\n Number of scans stored/updated\n \"\"\"\n stored_count = 0\n\n if not security_scans:\n logger.debug(f\"No security scans to store from peer '{peer_id}'\")\n return 0\n\n # Get security scan repository\n scan_repo = get_security_scan_repository()\n\n for scan in security_scans:\n try:\n # Extract original server path\n original_server_path = scan.get(\"server_path\", \"\")\n\n if not original_server_path:\n logger.warning(\"Security scan missing 'server_path' field, skipping\")\n continue\n\n # Normalize path - ensure it starts with /\n normalized_path = (\n original_server_path\n if original_server_path.startswith(\"/\")\n else f\"/{original_server_path}\"\n )\n\n # Prefix path with peer_id to match synced server paths\n # e.g., \"/my-server\" becomes \"/peer-central/my-server\"\n prefixed_path = f\"/{peer_id}{normalized_path}\"\n\n # Create a copy to avoid modifying original\n scan_data = scan.copy()\n scan_data[\"server_path\"] = prefixed_path\n\n # Add sync_metadata to track origin\n scan_data[\"sync_metadata\"] = {\n \"source_peer_id\": peer_id,\n \"synced_at\": datetime.now(UTC).isoformat(),\n \"is_federated\": True,\n \"original_server_path\": original_server_path,\n }\n\n # Store the scan via repository\n try:\n success = await scan_repo.create(scan_data)\n if success:\n logger.debug(f\"Stored synced security scan for: {prefixed_path}\")\n stored_count += 1\n else:\n logger.error(f\"Failed to store security scan for: {prefixed_path}\")\n\n except Exception as e:\n logger.error(\n f\"Failed to store security scan for '{prefixed_path}': {e}\",\n exc_info=True,\n )\n\n except Exception as e:\n logger.error(\n f\"Failed to process security scan from peer '{peer_id}': {e}\",\n exc_info=True,\n )\n\n logger.info(\n f\"Stored {stored_count}/{len(security_scans)} security scans from peer '{peer_id}'\"\n )\n return stored_count\n\n\n# Global service instance\n_peer_federation_service: PeerFederationService | None = None\n\n\ndef get_peer_federation_service() -> PeerFederationService:\n \"\"\"\n Get the global peer federation service instance.\n\n Returns:\n Singleton PeerFederationService instance\n \"\"\"\n global _peer_federation_service\n if _peer_federation_service is None:\n _peer_federation_service = PeerFederationService()\n return _peer_federation_service\n" }, { "path": "registry/services/peer_sync_scheduler.py", "content": "\"\"\"\nBackground scheduler for periodic peer federation sync.\n\nUses asyncio to periodically check enabled peers and trigger sync\nwhen their configured interval has elapsed.\n\"\"\"\n\nimport asyncio\nimport logging\nfrom datetime import UTC, datetime\n\nfrom registry.repositories.factory import get_peer_federation_repository\nfrom registry.services.peer_federation_service import PeerFederationService\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Check interval in seconds (how often to check if any peer needs sync)\nSCHEDULER_CHECK_INTERVAL_SECONDS: int = 60\n\n\nclass PeerSyncScheduler:\n \"\"\"\n Background scheduler for peer federation sync.\n\n Periodically checks all enabled peers and triggers sync when\n the configured interval has elapsed since last successful sync.\n \"\"\"\n\n def __init__(self):\n self._task: asyncio.Task | None = None\n self._running: bool = False\n\n async def start(self) -> None:\n \"\"\"Start the background scheduler.\"\"\"\n if self._running:\n logger.warning(\"Peer sync scheduler already running\")\n return\n\n self._running = True\n self._task = asyncio.create_task(self._scheduler_loop())\n logger.info(\"Peer sync scheduler started\")\n\n async def stop(self) -> None:\n \"\"\"Stop the background scheduler.\"\"\"\n self._running = False\n if self._task:\n self._task.cancel()\n try:\n await self._task\n except asyncio.CancelledError:\n pass\n self._task = None\n logger.info(\"Peer sync scheduler stopped\")\n\n async def _scheduler_loop(self) -> None:\n \"\"\"Main scheduler loop that checks peers and triggers sync.\"\"\"\n logger.info(\n f\"Peer sync scheduler loop started, checking every {SCHEDULER_CHECK_INTERVAL_SECONDS}s\"\n )\n\n while self._running:\n try:\n await self._check_and_sync_peers()\n except Exception as e:\n logger.error(f\"Error in peer sync scheduler: {e}\", exc_info=True)\n\n # Wait before next check\n await asyncio.sleep(SCHEDULER_CHECK_INTERVAL_SECONDS)\n\n async def _check_and_sync_peers(self) -> None:\n \"\"\"Check all peers and sync those that need it.\"\"\"\n try:\n peer_repo = get_peer_federation_repository()\n peers = await peer_repo.list_peers()\n\n if not peers:\n return\n\n federation_service = PeerFederationService()\n now = datetime.now(UTC)\n\n for peer in peers:\n # Skip disabled peers\n if not peer.enabled:\n continue\n\n # Skip peers with no scheduled sync (interval = 0)\n if peer.sync_interval_minutes <= 0:\n continue\n\n # Check if sync is needed\n should_sync = await self._should_sync_peer(\n peer.peer_id, peer.sync_interval_minutes, now\n )\n\n if should_sync:\n logger.info(\n f\"Scheduled sync triggered for peer '{peer.peer_id}' \"\n f\"(interval: {peer.sync_interval_minutes}m)\"\n )\n try:\n result = await federation_service.sync_peer(peer.peer_id)\n if result.success:\n logger.info(\n f\"Scheduled sync completed for peer '{peer.peer_id}': \"\n f\"{result.servers_synced} servers, {result.agents_synced} agents\"\n )\n else:\n logger.warning(\n f\"Scheduled sync failed for peer '{peer.peer_id}': \"\n f\"{result.error_message}\"\n )\n except Exception as e:\n logger.error(f\"Error during scheduled sync for peer '{peer.peer_id}': {e}\")\n\n except Exception as e:\n logger.error(f\"Error checking peers for scheduled sync: {e}\", exc_info=True)\n\n async def _should_sync_peer(self, peer_id: str, interval_minutes: int, now: datetime) -> bool:\n \"\"\"\n Determine if a peer should be synced based on last sync time.\n\n Args:\n peer_id: The peer identifier\n interval_minutes: Configured sync interval in minutes\n now: Current UTC time\n\n Returns:\n True if sync should be triggered\n \"\"\"\n try:\n peer_repo = get_peer_federation_repository()\n status = await peer_repo.get_sync_status(peer_id)\n\n if not status:\n # No status record means never synced - should sync\n return True\n\n if status.sync_in_progress:\n # Sync already in progress - skip\n return False\n\n last_sync = status.last_successful_sync\n if not last_sync:\n # Never successfully synced - should sync\n return True\n\n # Ensure last_sync is timezone-aware\n if last_sync.tzinfo is None:\n last_sync = last_sync.replace(tzinfo=UTC)\n\n # Calculate time since last sync\n elapsed_minutes = (now - last_sync).total_seconds() / 60\n\n return elapsed_minutes >= interval_minutes\n\n except Exception as e:\n logger.error(f\"Error checking sync status for peer '{peer_id}': {e}\")\n return False\n\n\n# Global scheduler instance\n_scheduler: PeerSyncScheduler | None = None\n\n\ndef get_peer_sync_scheduler() -> PeerSyncScheduler:\n \"\"\"Get or create the global scheduler instance.\"\"\"\n global _scheduler\n if _scheduler is None:\n _scheduler = PeerSyncScheduler()\n return _scheduler\n" }, { "path": "registry/services/rating_service.py", "content": "\"\"\"\nShared rating service utilities for servers and agents.\n\nThis module provides common rating functionality to avoid code duplication\nbetween server_service.py and agent_service.py.\n\"\"\"\n\nimport logging\nfrom typing import Any\n\nlogger = logging.getLogger(__name__)\n\n\n# Rating configuration constants\nMAX_RATINGS_PER_RESOURCE = 100\nMIN_RATING_VALUE = 1\nMAX_RATING_VALUE = 5\n\n\ndef validate_rating(rating: int) -> None:\n \"\"\"\n Validate rating value with detailed logging.\n\n Args:\n rating: The rating value to validate\n\n Raises:\n ValueError: If rating is not an integer or not in valid range\n \"\"\"\n if not isinstance(rating, int):\n logger.error(f\"Invalid rating type: {rating} (type={type(rating)})\")\n raise ValueError(\"Rating must be an integer\")\n\n if rating < MIN_RATING_VALUE or rating > MAX_RATING_VALUE:\n logger.error(\n f\"Invalid rating value: {rating}. Must be between {MIN_RATING_VALUE} and {MAX_RATING_VALUE}.\"\n )\n raise ValueError(\n f\"Rating must be between {MIN_RATING_VALUE} and {MAX_RATING_VALUE} (inclusive)\"\n )\n\n\ndef update_rating_details(\n rating_details: list[dict[str, Any]],\n username: str,\n rating: int,\n) -> tuple[list[dict[str, Any]], bool]:\n \"\"\"\n Update rating details list with new or updated user rating.\n\n This function handles:\n - Updating existing user ratings\n - Adding new user ratings\n - Maintaining a rotating buffer of max ratings\n\n Args:\n rating_details: Current list of rating detail dicts\n username: Username submitting the rating\n rating: Rating value (already validated)\n\n Returns:\n Tuple of (updated_rating_details, is_new_rating)\n - updated_rating_details: Modified list\n - is_new_rating: True if this was a new rating, False if update\n \"\"\"\n if rating_details is None:\n rating_details = []\n\n # Check if user has already rated\n user_found = False\n for entry in rating_details:\n if entry.get(\"user\") == username:\n entry[\"rating\"] = rating\n user_found = True\n logger.info(f\"Updated existing rating for user {username} to {rating}\")\n break\n\n # If no existing rating from this user, append a new one\n if not user_found:\n rating_details.append(\n {\n \"user\": username,\n \"rating\": rating,\n }\n )\n logger.info(f\"Added new rating for user {username}: {rating}\")\n\n # Maintain a rotating buffer of MAX_RATINGS_PER_RESOURCE entries\n if len(rating_details) > MAX_RATINGS_PER_RESOURCE:\n # Remove the oldest entry to maintain the limit\n rating_details.pop(0)\n logger.info(\n f\"Removed oldest rating to maintain {MAX_RATINGS_PER_RESOURCE} entries limit\"\n )\n\n return rating_details, not user_found\n\n\ndef calculate_average_rating(rating_details: list[dict[str, Any]]) -> float:\n \"\"\"\n Calculate average rating from rating details.\n\n Args:\n rating_details: List of rating detail dicts with 'rating' key\n\n Returns:\n Average rating as float\n\n Raises:\n ValueError: If rating_details is empty\n \"\"\"\n if not rating_details:\n raise ValueError(\"Cannot calculate average from empty rating details\")\n\n all_ratings = [entry[\"rating\"] for entry in rating_details]\n average = float(sum(all_ratings) / len(all_ratings))\n\n logger.debug(f\"Calculated average rating: {average:.2f} from {len(all_ratings)} ratings\")\n\n return average\n" }, { "path": "registry/services/registration_gate_service.py", "content": "\"\"\"Registration gate service for admission control.\n\nCalls a configurable external endpoint to approve or deny\nregistration and update requests before they are persisted.\n\nSecurity: Credential fields are always stripped from payloads.\nSensitive headers (authorization, cookie, csrf) are excluded.\n\"\"\"\n\nimport asyncio\nimport logging\nimport time\n\nimport httpx\n\nfrom registry.core.config import settings\nfrom registry.schemas.registration_gate_models import (\n RegistrationGateAuthType,\n RegistrationGateRequest,\n RegistrationGateResponse,\n RegistrationGateResult,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\nALLOWED_STATUS_CODE: int = 200\nDENIED_STATUS_CODE: int = 403\nINITIAL_BACKOFF_SECONDS: float = 0.5\nGATE_ERROR_MAX_LENGTH: int = 500\n\nSENSITIVE_FIELD_SUBSTRINGS: list[str] = [\n \"credential\",\n \"secret\",\n \"token\",\n \"password\",\n \"api_key\",\n]\n\nSENSITIVE_FIELD_NAMES: set[str] = {\n \"auth_credential\",\n \"auth_credential_encrypted\",\n \"auth_header_name\",\n}\n\nSENSITIVE_HEADERS: set[str] = {\n \"cookie\",\n \"authorization\",\n \"x-csrf-token\",\n}\n\n\ndef _sanitize_payload(\n payload: dict,\n) -> dict:\n \"\"\"Remove credential and sensitive fields from a registration payload.\n\n Args:\n payload: Raw registration payload dict.\n\n Returns:\n A new dict with sensitive fields removed.\n \"\"\"\n sanitized = {}\n for key, value in payload.items():\n if key in SENSITIVE_FIELD_NAMES:\n continue\n key_lower = key.lower()\n if any(sub in key_lower for sub in SENSITIVE_FIELD_SUBSTRINGS):\n continue\n sanitized[key] = value\n return sanitized\n\n\ndef _build_auth_headers() -> dict[str, str]:\n \"\"\"Build authentication headers based on gate auth configuration.\n\n Returns:\n Dictionary of auth headers to include in the gate request.\n \"\"\"\n auth_type = settings.registration_gate_auth_type.lower()\n credential = settings.registration_gate_auth_credential\n\n if auth_type == RegistrationGateAuthType.BEARER and credential:\n return {\"Authorization\": f\"Bearer {credential}\"}\n\n if auth_type == RegistrationGateAuthType.API_KEY and credential:\n header_name = settings.registration_gate_auth_header_name\n return {header_name: credential}\n\n return {}\n\n\ndef _extract_request_headers(\n raw_headers: list[tuple[bytes, bytes]],\n) -> dict[str, str]:\n \"\"\"Extract request headers as a string dict, filtering sensitive headers.\n\n Args:\n raw_headers: Raw ASGI header tuples from the request scope.\n\n Returns:\n Dictionary of header name to header value strings.\n \"\"\"\n result = {}\n for name_bytes, value_bytes in raw_headers:\n name = name_bytes.decode(\"latin-1\").lower()\n if name not in SENSITIVE_HEADERS:\n result[name] = value_bytes.decode(\"latin-1\")\n return result\n\n\ndef _is_gate_configured() -> bool:\n \"\"\"Check if the registration gate is enabled and properly configured.\n\n Returns:\n True if the gate should be invoked, False otherwise.\n \"\"\"\n if not settings.registration_gate_enabled:\n return False\n\n if not settings.registration_gate_url:\n logger.warning(\n \"Registration gate is enabled but no URL is configured. \"\n \"Treating as disabled.\"\n )\n return False\n\n return True\n\n\ndef _truncate_error(\n message: str,\n) -> str:\n \"\"\"Truncate gate error message to safe length.\n\n Args:\n message: Raw error message from gate.\n\n Returns:\n Truncated message (max GATE_ERROR_MAX_LENGTH chars).\n \"\"\"\n if len(message) > GATE_ERROR_MAX_LENGTH:\n return message[:GATE_ERROR_MAX_LENGTH] + \"...\"\n return message\n\n\nasync def _call_gate_endpoint(\n gate_request: RegistrationGateRequest,\n) -> RegistrationGateResult:\n \"\"\"Call the gate endpoint with retry logic.\n\n Args:\n gate_request: The payload to send to the gate endpoint.\n\n Returns:\n RegistrationGateResult with the gate decision.\n \"\"\"\n url = settings.registration_gate_url\n timeout = settings.registration_gate_timeout_seconds\n max_retries = settings.registration_gate_max_retries\n\n headers = {\"Content-Type\": \"application/json\"}\n headers.update(_build_auth_headers())\n\n payload_json = gate_request.model_dump_json()\n total_attempts = 1 + max_retries\n last_error = \"\"\n\n for attempt in range(1, total_attempts + 1):\n start_time = time.time()\n try:\n async with httpx.AsyncClient(timeout=timeout) as client:\n response = await client.post(\n url,\n content=payload_json,\n headers=headers,\n )\n\n elapsed = time.time() - start_time\n logger.info(\n f\"Registration gate response: status={response.status_code}, \"\n f\"attempt={attempt}/{total_attempts}, elapsed={elapsed:.2f}s\"\n )\n\n if response.status_code == ALLOWED_STATUS_CODE:\n return RegistrationGateResult(\n allowed=True,\n error_message=None,\n gate_status_code=response.status_code,\n attempts=attempt,\n )\n\n if response.status_code == DENIED_STATUS_CODE:\n error_message = \"Registration denied by policy\"\n try:\n gate_response = RegistrationGateResponse(\n **response.json()\n )\n if gate_response.error:\n error_message = _truncate_error(gate_response.error)\n except Exception:\n raw_text = response.text[:GATE_ERROR_MAX_LENGTH]\n error_message = raw_text or error_message\n\n return RegistrationGateResult(\n allowed=False,\n error_message=error_message,\n gate_status_code=response.status_code,\n attempts=attempt,\n )\n\n last_error = (\n f\"Unexpected status code {response.status_code} \"\n f\"from gate endpoint\"\n )\n logger.warning(\n f\"Registration gate returned unexpected status \"\n f\"{response.status_code} on attempt {attempt}/{total_attempts}\"\n )\n\n except httpx.TimeoutException:\n elapsed = time.time() - start_time\n last_error = f\"Gate endpoint timed out after {elapsed:.2f}s\"\n logger.warning(\n f\"Registration gate timeout on attempt \"\n f\"{attempt}/{total_attempts}: {last_error}\"\n )\n\n except httpx.RequestError as e:\n last_error = f\"Connection error: {e}\"\n logger.warning(\n f\"Registration gate connection error on attempt \"\n f\"{attempt}/{total_attempts}: {last_error}\"\n )\n\n if attempt < total_attempts:\n backoff = INITIAL_BACKOFF_SECONDS * (2 ** (attempt - 1))\n logger.info(\n f\"Retrying gate call in {backoff:.1f}s \"\n f\"(attempt {attempt + 1}/{total_attempts})\"\n )\n await asyncio.sleep(backoff)\n\n logger.error(\n f\"Registration gate exhausted all {total_attempts} attempts. \"\n f\"Last error: {last_error}. Blocking registration (fail-closed).\"\n )\n return RegistrationGateResult(\n allowed=False,\n error_message=(\n \"Registration gate is unavailable. \"\n \"Registration blocked (fail-closed policy).\"\n ),\n gate_status_code=None,\n attempts=total_attempts,\n )\n\n\nasync def check_registration_gate(\n asset_type: str,\n operation: str,\n source_api: str,\n registration_payload: dict,\n raw_headers: list[tuple[bytes, bytes]],\n) -> RegistrationGateResult:\n \"\"\"Check the registration gate for a registration or update request.\n\n This is the main public function called by registration and update\n endpoints. Returns immediately with allowed=True if the gate is\n not configured.\n\n Args:\n asset_type: Type of asset (\"agent\", \"server\", or \"skill\").\n operation: \"register\" or \"update\".\n source_api: API path that triggered the request.\n registration_payload: Full request as a dict.\n raw_headers: Raw ASGI headers from the HTTP request scope.\n\n Returns:\n RegistrationGateResult indicating whether to proceed or block.\n \"\"\"\n if not _is_gate_configured():\n return RegistrationGateResult(\n allowed=True,\n error_message=None,\n gate_status_code=None,\n attempts=0,\n )\n\n sanitized_payload = _sanitize_payload(registration_payload)\n request_headers = _extract_request_headers(raw_headers)\n\n gate_request = RegistrationGateRequest(\n asset_type=asset_type,\n operation=operation,\n source_api=source_api,\n registration_payload=sanitized_payload,\n request_headers=request_headers,\n )\n\n logger.info(\n f\"Calling registration gate for {operation} of {asset_type} \"\n f\"from {source_api}\"\n )\n\n return await _call_gate_endpoint(gate_request)\n\n\nasync def verify_gate_connectivity() -> None:\n \"\"\"Verify connectivity to the gate endpoint at startup.\n\n Called during application startup when gate is enabled.\n Logs warnings if the gate is unreachable or uses HTTP.\n Does NOT block startup.\n \"\"\"\n if not _is_gate_configured():\n return\n\n url = settings.registration_gate_url\n auth_type = settings.registration_gate_auth_type\n\n logger.info(\n f\"Registration gate enabled: url={url}, auth_type={auth_type}\"\n )\n\n if url.startswith(\"http://\"):\n logger.warning(\n \"Registration gate URL uses HTTP. \"\n \"HTTPS is strongly recommended for production.\"\n )\n\n try:\n async with httpx.AsyncClient(timeout=5) as client:\n response = await client.head(url)\n logger.info(\n f\"Registration gate connectivity check: \"\n f\"status={response.status_code} (reachable)\"\n )\n except Exception as e:\n logger.warning(\n f\"Registration gate connectivity check failed: {e}. \"\n f\"The gate endpoint may be unreachable. \"\n f\"Registrations will be blocked until the gate is available.\"\n )\n" }, { "path": "registry/services/scope_service.py", "content": "\"\"\"\nScope service - Business logic layer for scope management.\n\nThis service wraps the scope repository and implements high-level business\nlogic for managing server scopes, groups, and authorization rules.\n\"\"\"\n\nimport logging\nfrom typing import (\n Any,\n)\n\nimport httpx\n\nfrom ..auth.internal import generate_internal_token\nfrom ..core.config import settings\nfrom ..repositories.factory import get_scope_repository\nfrom .server_service import server_service\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n# Constants\nSTANDARD_METHODS: list[str] = [\n \"initialize\",\n \"notifications/initialized\",\n \"ping\",\n \"tools/list\",\n \"tools/call\",\n \"resources/list\",\n \"resources/templates/list\",\n]\n\n\nasync def _trigger_auth_server_reload() -> bool:\n \"\"\"\n Trigger the auth server to reload its scopes configuration.\n\n Uses a self-signed JWT (signed with the shared SECRET_KEY) for\n internal service-to-service authentication.\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n token = generate_internal_token(\n subject=\"registry-service\",\n purpose=\"reload-scopes\",\n )\n\n async with httpx.AsyncClient() as client:\n response = await client.post(\n f\"{settings.auth_server_url}/internal/reload-scopes\",\n headers={\"Authorization\": f\"Bearer {token}\"},\n timeout=10.0,\n )\n\n if response.status_code == 200:\n logger.info(\"Successfully triggered auth server scope reload\")\n return True\n else:\n logger.error(\n f\"Failed to reload auth server scopes: {response.status_code} - {response.text}\"\n )\n return False\n\n except Exception as e:\n logger.error(f\"Failed to trigger auth server reload: {e}\")\n # Non-fatal - scopes will be picked up on next restart\n return False\n\n\nasync def update_server_scopes(\n server_path: str,\n server_name: str,\n tools: list[str],\n) -> bool:\n \"\"\"\n Update scopes for a server (add or update) and reload auth server.\n\n This adds the server to unrestricted read and execute scopes.\n\n Args:\n server_path: The server's path (e.g., '/example-server')\n server_name: The server's display name\n tools: List of tool names the server provides\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Add to unrestricted scopes (both read and execute)\n await scope_repo.add_server_scope(\n server_path=server_path,\n scope_name=\"mcp-servers-unrestricted/read\",\n methods=STANDARD_METHODS,\n tools=tools,\n )\n\n await scope_repo.add_server_scope(\n server_path=server_path,\n scope_name=\"mcp-servers-unrestricted/execute\",\n methods=STANDARD_METHODS,\n tools=tools,\n )\n\n logger.info(f\"Successfully updated scopes for server {server_path} with {len(tools)} tools\")\n\n # Reload auth server\n await _trigger_auth_server_reload()\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to update server scopes for {server_path}: {e}\")\n return False\n\n\nasync def remove_server_scopes(\n server_path: str,\n) -> bool:\n \"\"\"\n Remove a server from all scopes and reload auth server.\n\n Args:\n server_path: The server's path (e.g., '/example-server')\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Remove from all scopes\n await scope_repo.remove_server_from_all_scopes(server_path=server_path)\n\n logger.info(f\"Successfully removed server {server_path} from all scopes\")\n\n # Reload auth server\n await _trigger_auth_server_reload()\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to remove server scopes for {server_path}: {e}\")\n return False\n\n\nasync def add_server_to_groups(\n server_path: str,\n group_names: list[str],\n) -> bool:\n \"\"\"\n Add a server and all its known tools/methods to specific groups.\n\n Gets the server's tools from the registry and adds them to the\n specified groups using the standard methods.\n\n Args:\n server_path: The server's path (e.g., '/example-server')\n group_names: List of group names to add the server to\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Get server info to find its tools\n server_info = await server_service.get_server_info(server_path)\n if not server_info:\n logger.error(f\"Server {server_path} not found in registry\")\n return False\n\n # Get the tools from the last health check\n tool_list = server_info.get(\"tool_list\", [])\n tool_names = [\n tool[\"name\"] for tool in tool_list if isinstance(tool, dict) and \"name\" in tool\n ]\n\n logger.info(f\"Found {len(tool_names)} tools for server {server_path}: {tool_names}\")\n\n # Add server to each group\n for group_name in group_names:\n # Check if group exists\n if not await scope_repo.group_exists(group_name):\n logger.warning(f\"Group {group_name} not found in scopes\")\n continue\n\n # Add server to this group\n await scope_repo.add_server_scope(\n server_path=server_path,\n scope_name=group_name,\n methods=STANDARD_METHODS,\n tools=tool_names,\n )\n\n # Add to UI-Scopes for web interface visibility\n server_name = server_info.get(\"server_name\", server_path.lstrip(\"/\").rstrip(\"/\"))\n await scope_repo.add_server_to_ui_scopes(\n group_name=group_name,\n server_name=server_name,\n )\n\n logger.info(f\"Added server {server_path} to group {group_name}\")\n\n # Reload auth server\n await _trigger_auth_server_reload()\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to add server {server_path} to groups {group_names}: {e}\")\n return False\n\n\nasync def remove_server_from_groups(\n server_path: str,\n group_names: list[str],\n) -> bool:\n \"\"\"\n Remove a server from specific groups.\n\n Args:\n server_path: The server's path (e.g., '/example-server')\n group_names: List of group names to remove the server from\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Get server info for UI-Scopes updates\n server_info = await server_service.get_server_info(server_path)\n if server_info:\n server_name = server_info.get(\"server_name\", server_path.lstrip(\"/\").rstrip(\"/\"))\n else:\n # If server not found, derive name from path\n server_name = server_path.lstrip(\"/\").rstrip(\"/\")\n\n # Remove server from each group\n for group_name in group_names:\n # Check if group exists\n if not await scope_repo.group_exists(group_name):\n logger.warning(f\"Group {group_name} not found in scopes\")\n continue\n\n # Remove server from this group\n await scope_repo.remove_server_scope(\n server_path=server_path,\n scope_name=group_name,\n )\n\n # Remove from UI-Scopes\n await scope_repo.remove_server_from_ui_scopes(\n group_name=group_name,\n server_name=server_name,\n )\n\n logger.info(f\"Removed server {server_path} from group {group_name}\")\n\n # Reload auth server\n await _trigger_auth_server_reload()\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to remove server {server_path} from groups {group_names}: {e}\")\n return False\n\n\nasync def create_group(\n group_name: str,\n description: str = \"\",\n) -> bool:\n \"\"\"\n Create a new group in scopes and add it to group_mappings.\n\n Args:\n group_name: Name of the group (e.g., 'mcp-servers-custom/read')\n description: Optional description\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Check if group already exists\n if await scope_repo.group_exists(group_name):\n logger.warning(f\"Group {group_name} already exists in scopes\")\n return False\n\n # Create the group\n await scope_repo.create_group(\n group_name=group_name,\n description=description,\n )\n\n logger.info(\n f\"Successfully created group {group_name} in scopes, group_mappings, and UI-Scopes\"\n )\n\n # Reload auth server\n await _trigger_auth_server_reload()\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to create group {group_name} in scopes: {e}\")\n return False\n\n\nasync def delete_group(\n group_name: str,\n remove_from_mappings: bool = True,\n) -> bool:\n \"\"\"\n Delete a group from scopes and optionally from group_mappings.\n\n Args:\n group_name: Name of the group to delete\n remove_from_mappings: Whether to remove from group_mappings section\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Check if group exists\n if not await scope_repo.group_exists(group_name):\n logger.warning(f\"Group {group_name} not found in scopes\")\n return False\n\n # Delete the group\n await scope_repo.delete_group(\n group_name=group_name,\n remove_from_mappings=remove_from_mappings,\n )\n\n logger.info(f\"Successfully deleted group {group_name} from scopes\")\n\n # Reload auth server\n await _trigger_auth_server_reload()\n\n return True\n\n except Exception as e:\n logger.error(f\"Failed to delete group {group_name} from scopes: {e}\")\n return False\n\n\nasync def import_group(\n scope_name: str,\n scope_type: str = \"server_scope\",\n description: str = \"\",\n server_access: list = None,\n group_mappings: list = None,\n ui_permissions: dict = None,\n agent_access: list = None,\n) -> bool:\n \"\"\"\n Import a complete group definition with all document types.\n\n This creates/updates all group-related data structures based on the provided\n definition. The group_name is derived from scope_name.\n\n Args:\n scope_name: Name of the scope/group\n scope_type: Type of scope (default: server_scope)\n description: Description of the group\n server_access: Optional list of server access definitions\n group_mappings: Optional list of group names this group maps to\n ui_permissions: Optional dictionary of UI permissions\n agent_access: Optional list of agent paths this group can access\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Use scope_name as the group_name\n group_name = scope_name\n\n # Call repository import_group method\n success = await scope_repo.import_group(\n group_name=group_name,\n description=description,\n server_access=server_access,\n group_mappings=group_mappings,\n ui_permissions=ui_permissions,\n agent_access=agent_access,\n )\n\n if success:\n logger.info(f\"Successfully imported group definition for {group_name}\")\n else:\n logger.error(f\"Failed to import group definition for {group_name}\")\n\n return success\n\n except Exception as e:\n logger.error(f\"Failed to import group {scope_name}: {e}\")\n return False\n\n\nasync def get_group(group_name: str) -> dict[str, Any]:\n \"\"\"\n Get full details of a specific group from scopes storage.\n\n Args:\n group_name: Name of the group\n\n Returns:\n Dict with complete group information including server_access, group_mappings, and ui_permissions\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Get group details\n group_data = await scope_repo.get_group(group_name)\n\n if not group_data:\n logger.warning(f\"Group {group_name} not found in scopes\")\n return None\n\n logger.info(f\"Retrieved group {group_name} from scopes\")\n return group_data\n\n except Exception as e:\n logger.error(f\"Failed to get group {group_name} from scopes: {e}\")\n return None\n\n\nasync def list_groups() -> dict[str, Any]:\n \"\"\"\n List all groups defined in scopes.\n\n Returns:\n Dict with group information including server counts and mappings\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Get all groups\n groups_data = await scope_repo.list_groups()\n\n logger.info(f\"Found {groups_data.get('total_count', 0)} groups in scopes\")\n\n return groups_data\n\n except Exception as e:\n logger.error(f\"Failed to list groups from scopes: {e}\")\n return {\n \"total_count\": 0,\n \"groups\": {},\n \"error\": str(e),\n }\n\n\nasync def group_exists(\n group_name: str,\n) -> bool:\n \"\"\"\n Check if a group exists in scopes.\n\n Args:\n group_name: Name of the group to check\n\n Returns:\n True if group exists, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n return await scope_repo.group_exists(group_name)\n except Exception as e:\n logger.error(f\"Error checking if group exists in scopes: {e}\")\n return False\n\n\nasync def trigger_auth_server_reload() -> bool:\n \"\"\"\n Trigger the auth server to reload its scopes configuration.\n\n Public wrapper around the private function.\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n return await _trigger_auth_server_reload()\n\n\nasync def add_group_mapping_to_scope(\n scope_name: str,\n group_id: str,\n) -> bool:\n \"\"\"\n Add a group mapping (IdP group ID) to an existing scope's group_mappings.\n\n This is used when creating a group in an IdP (like Entra ID) that returns\n group IDs (GUIDs) in tokens. We need to map both the group name and ID\n so that token validation works correctly.\n\n Args:\n scope_name: Name of the scope to update\n group_id: IdP group ID to add to group_mappings\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n scope_repo = get_scope_repository()\n\n # Use the existing add_group_mapping method which adds\n # an entry to the scope's group_mappings array\n success = await scope_repo.add_group_mapping(scope_name, group_id)\n\n if success:\n logger.info(f\"Added group ID {group_id} to scope {scope_name} group_mappings\")\n else:\n logger.error(f\"Failed to add group ID {group_id} to scope {scope_name} group_mappings\")\n return success\n\n except Exception as e:\n logger.error(f\"Error adding group mapping to scope {scope_name}: {e}\")\n return False\n" }, { "path": "registry/services/security_scanner.py", "content": "\"\"\"\nSecurity Scanner Service\n\nThis service provides security scanning functionality for MCP servers during registration.\nIt wraps the CLI security scanner and makes it available to API endpoints with proper\nconfiguration and error handling.\n\"\"\"\n\nimport asyncio\nimport json\nimport logging\nimport os\nimport re\nimport subprocess # nosec B404\nfrom datetime import UTC, datetime\nfrom pathlib import Path\n\nfrom ..core.config import settings\nfrom ..core.endpoint_utils import get_endpoint_url\nfrom ..repositories.factory import get_security_scan_repository\nfrom ..schemas.security import SecurityScanConfig, SecurityScanResult\n\nlogger = logging.getLogger(__name__)\n\n# Constants\nPROJECT_ROOT = Path(__file__).parent.parent.parent\nOUTPUT_DIR = PROJECT_ROOT / \"security_scans\"\n\n\ndef _extract_bearer_token_from_headers(headers: str) -> str | None:\n \"\"\"\n Extract bearer token from headers JSON string.\n\n Args:\n headers: JSON string containing headers\n\n Returns:\n Bearer token if found, None otherwise\n\n Raises:\n ValueError: If headers JSON is invalid\n \"\"\"\n logger.info(\"Adding custom headers for scanning\")\n try:\n headers_dict = json.loads(headers)\n # Check for X-Authorization header with Bearer token\n auth_header = headers_dict.get(\"X-Authorization\", \"\")\n if auth_header.startswith(\"Bearer \"):\n bearer_token = auth_header.replace(\"Bearer \", \"\")\n logger.info(\"Using bearer token authentication\")\n return bearer_token\n else:\n logger.warning(\"Headers provided but no Bearer token found in X-Authorization header\")\n return None\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to parse headers JSON: {e}\")\n raise ValueError(f\"Invalid headers JSON: {headers}\") from e\n\n\ndef _parse_scanner_json_output(stdout: str) -> list:\n \"\"\"\n Parse JSON output from scanner stdout.\n\n Args:\n stdout: Raw stdout from scanner command\n\n Returns:\n Parsed JSON array of tool results\n\n Raises:\n ValueError: If no valid JSON array found in output\n json.JSONDecodeError: If JSON parsing fails\n \"\"\"\n # Remove ANSI color codes\n ansi_escape = re.compile(r\"\\x1B(?:[@-Z\\\\-_]|\\[[0-?]*[ -/]*[@-~])\")\n clean_stdout = ansi_escape.sub(\"\", stdout)\n\n # Find the start of JSON array\n json_start = -1\n\n # Try to find JSON array start\n for i in range(len(clean_stdout) - 1):\n if clean_stdout[i] == \"[\" and (i == 0 or clean_stdout[i - 1] in \"\\n\\r\"):\n json_start = i\n break\n\n # Fallback: find any '[' followed by whitespace and '{'\n if json_start == -1:\n pattern = r\"\\[\\s*\\{\"\n match = re.search(pattern, clean_stdout)\n if match:\n json_start = match.start()\n\n if json_start == -1:\n raise ValueError(\"No JSON array found in scanner output\")\n\n # Extract and parse JSON\n json_str = clean_stdout[json_start:]\n tool_results = json.loads(json_str)\n return tool_results\n\n\ndef _organize_findings_by_analyzer(tool_results: list) -> dict:\n \"\"\"\n Organize findings from tool results by analyzer.\n\n Args:\n tool_results: List of tool results from scanner\n\n Returns:\n Dictionary organized by analyzer name with findings\n \"\"\"\n organized_results = {}\n\n for tool_result in tool_results:\n findings_dict = tool_result.get(\"findings\", {})\n for analyzer_name, analyzer_findings in findings_dict.items():\n if analyzer_name not in organized_results:\n organized_results[analyzer_name] = {\"findings\": []}\n\n # Convert analyzer findings to expected format\n if isinstance(analyzer_findings, dict):\n finding = {\n \"tool_name\": tool_result.get(\"tool_name\"),\n \"severity\": analyzer_findings.get(\"severity\", \"unknown\"),\n \"threat_names\": analyzer_findings.get(\"threat_names\", []),\n \"threat_summary\": analyzer_findings.get(\"threat_summary\", \"\"),\n \"is_safe\": tool_result.get(\"is_safe\", True),\n }\n organized_results[analyzer_name][\"findings\"].append(finding)\n\n return organized_results\n\n\nclass SecurityScannerService:\n \"\"\"Service for scanning MCP servers for security vulnerabilities.\"\"\"\n\n def __init__(self) -> None:\n \"\"\"Initialize the security scanner service.\"\"\"\n self._ensure_output_directory()\n self._scan_repo = get_security_scan_repository()\n\n def _ensure_output_directory(self) -> Path:\n \"\"\"Ensure output directory exists.\"\"\"\n OUTPUT_DIR.mkdir(parents=True, exist_ok=True)\n return OUTPUT_DIR\n\n def get_scan_config(self) -> SecurityScanConfig:\n \"\"\"Get security scan configuration from settings.\"\"\"\n return SecurityScanConfig(\n enabled=settings.security_scan_enabled,\n scan_on_registration=settings.security_scan_on_registration,\n block_unsafe_servers=settings.security_block_unsafe_servers,\n analyzers=settings.security_analyzers,\n scan_timeout_seconds=settings.security_scan_timeout,\n llm_api_key=settings.mcp_scanner_llm_api_key or os.getenv(\"MCP_SCANNER_LLM_API_KEY\"),\n add_security_pending_tag=settings.security_add_pending_tag,\n )\n\n async def scan_server(\n self,\n server_url: str,\n server_path: str | None = None,\n analyzers: str | None = None,\n api_key: str | None = None,\n headers: str | None = None,\n timeout: int | None = None,\n mcp_endpoint: str | None = None,\n ) -> SecurityScanResult:\n \"\"\"\n Scan an MCP server for security vulnerabilities.\n\n Args:\n server_url: URL of the MCP server to scan (proxy_pass_url)\n server_path: Optional path identifier for the server\n analyzers: Comma-separated list of analyzers to use (overrides config)\n api_key: OpenAI API key for LLM-based analysis (overrides config)\n headers: JSON string of headers to include in requests\n timeout: Scan timeout in seconds (overrides config)\n mcp_endpoint: Optional explicit MCP endpoint URL. If set, used directly\n instead of appending /mcp to server_url.\n\n Returns:\n SecurityScanResult containing scan results\n\n Raises:\n subprocess.TimeoutExpired: If scan times out\n subprocess.CalledProcessError: If scanner command fails\n ValueError: If invalid input provided\n RuntimeError: If scan fails for other reasons\n \"\"\"\n config = self.get_scan_config()\n\n # Use config values if not provided\n if analyzers is None:\n analyzers = config.analyzers\n if api_key is None:\n api_key = config.llm_api_key\n if timeout is None:\n timeout = config.scan_timeout_seconds\n\n # Resolve endpoint URL using centralized utility\n # Priority: explicit mcp_endpoint > URL detection > append /mcp\n server_url = get_endpoint_url(\n proxy_pass_url=server_url,\n transport_type=\"streamable-http\",\n mcp_endpoint=mcp_endpoint,\n )\n\n logger.info(f\"Starting security scan for {server_url} with analyzers: {analyzers}\")\n\n try:\n # Run the scan in a thread pool to avoid blocking\n raw_output = await asyncio.to_thread(\n self._run_mcp_scanner,\n server_url=server_url,\n analyzers=analyzers,\n api_key=api_key,\n headers=headers,\n timeout=timeout,\n )\n\n # Analyze results\n is_safe, critical, high, medium, low = self._analyze_scan_results(raw_output)\n\n # Create result object\n result = SecurityScanResult(\n server_url=server_url,\n server_path=server_path\n or server_url, # Use server_path if provided, fallback to URL\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=is_safe,\n critical_issues=critical,\n high_severity=high,\n medium_severity=medium,\n low_severity=low,\n analyzers_used=analyzers.split(\",\"),\n raw_output=raw_output,\n output_file=\"\", # Repository handles storage\n scan_failed=False,\n )\n\n # Save scan result via repository\n await self._scan_repo.create(result.model_dump())\n\n logger.info(\n f\"Security scan completed for {server_url}. \"\n f\"Safe: {is_safe}, Critical: {critical}, High: {high}, Medium: {medium}, Low: {low}\"\n )\n\n return result\n\n except (\n subprocess.TimeoutExpired,\n subprocess.CalledProcessError,\n ValueError,\n RuntimeError,\n ) as e:\n logger.error(f\"Security scan failed for {server_url}: {e}\")\n\n # Create error output\n raw_output = {\n \"error\": str(e),\n \"analysis_results\": {},\n \"tool_results\": [],\n \"scan_failed\": True,\n }\n\n # Return error result\n result = SecurityScanResult(\n server_url=server_url,\n server_path=server_path\n or server_url, # Use server_path if provided, fallback to URL\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=False, # Treat scanner failures as unsafe\n critical_issues=0,\n high_severity=0,\n medium_severity=0,\n low_severity=0,\n analyzers_used=analyzers.split(\",\") if analyzers else [],\n raw_output=raw_output,\n output_file=\"\", # Repository handles storage\n scan_failed=True,\n error_message=str(e),\n )\n\n # Save error result via repository\n await self._scan_repo.create(result.model_dump())\n\n return result\n except Exception as e:\n logger.exception(f\"Unexpected error during security scan for {server_url}\")\n\n # Create error output\n raw_output = {\n \"error\": str(e),\n \"analysis_results\": {},\n \"tool_results\": [],\n \"scan_failed\": True,\n }\n\n # Return error result\n result = SecurityScanResult(\n server_url=server_url,\n server_path=server_path\n or server_url, # Use server_path if provided, fallback to URL\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=False, # Treat scanner failures as unsafe\n critical_issues=0,\n high_severity=0,\n medium_severity=0,\n low_severity=0,\n analyzers_used=analyzers.split(\",\") if analyzers else [],\n raw_output=raw_output,\n output_file=\"\", # Repository handles storage\n scan_failed=True,\n error_message=str(e),\n )\n\n # Save error result via repository\n await self._scan_repo.create(result.model_dump())\n\n return result\n\n def _run_mcp_scanner(\n self,\n server_url: str,\n analyzers: str,\n api_key: str | None = None,\n headers: str | None = None,\n timeout: int | None = None,\n ) -> dict:\n \"\"\"\n Run mcp-scanner command and return raw output.\n\n This is a synchronous method that runs in a thread pool.\n\n Args:\n server_url: URL of the MCP server to scan\n analyzers: Comma-separated list of analyzers to use\n api_key: OpenAI API key for LLM-based analysis\n headers: JSON string of headers to include in requests\n timeout: Scan timeout in seconds\n\n Returns:\n Dictionary containing analysis results and tool results\n\n Raises:\n subprocess.TimeoutExpired: If scan times out\n subprocess.CalledProcessError: If scanner command fails\n ValueError: If headers are invalid or output cannot be parsed\n RuntimeError: If scan fails for other reasons\n \"\"\"\n logger.info(f\"Running security scan on: {server_url}\")\n logger.info(f\"Using analyzers: {analyzers}\")\n\n # Build command\n cmd = [\n \"mcp-scanner\",\n \"--analyzers\",\n analyzers,\n \"--raw\", # Use raw format instead of summary\n \"remote\", # Subcommand to scan remote MCP server\n \"--server-url\",\n server_url,\n ]\n\n # Add headers if provided - parse JSON and extract bearer token\n if headers:\n bearer_token = _extract_bearer_token_from_headers(headers)\n if bearer_token:\n cmd.extend([\"--bearer-token\", bearer_token])\n\n # Set environment variable for API key if provided\n env = os.environ.copy()\n if api_key:\n env[\"MCP_SCANNER_LLM_API_KEY\"] = api_key\n\n # Run scanner with timeout\n try:\n result = subprocess.run( # nosec B603 - args are hardcoded flags passed to mcp-scanner tool\n cmd,\n capture_output=True,\n text=True,\n check=True,\n env=env,\n timeout=timeout,\n )\n\n # Log raw output for debugging\n logger.debug(f\"Raw scanner stdout:\\n{result.stdout[:500]}\")\n\n # Parse JSON output - scanner outputs JSON array after log messages\n stdout = result.stdout.strip()\n tool_results = _parse_scanner_json_output(stdout)\n\n # Wrap in expected format with analysis_results\n raw_output = {\"analysis_results\": {}, \"tool_results\": tool_results}\n\n # Extract findings from tool results and organize by analyzer\n raw_output[\"analysis_results\"] = _organize_findings_by_analyzer(tool_results)\n\n logger.debug(f\"Scanner output:\\n{json.dumps(raw_output, indent=2, default=str)}\")\n return raw_output\n\n except subprocess.TimeoutExpired as e:\n logger.error(f\"Scanner command timed out after {timeout} seconds\")\n raise RuntimeError(f\"Security scan timed out after {timeout} seconds\") from e\n except subprocess.CalledProcessError as e:\n logger.error(f\"Scanner command failed with exit code {e.returncode}\")\n logger.error(f\"stderr: {e.stderr}\")\n raise RuntimeError(f\"Security scanner failed: {e.stderr}\") from e\n except json.JSONDecodeError as e:\n logger.error(f\"Failed to parse scanner output as JSON: {e}\")\n logger.error(f\"Raw stdout: {result.stdout[:1000]}\")\n raise RuntimeError(\"Failed to parse security scanner output\") from e\n\n def _analyze_scan_results(self, raw_output: dict) -> tuple[bool, int, int, int, int]:\n \"\"\"\n Analyze scan results and extract severity counts.\n\n Args:\n raw_output: Dictionary containing scanner results\n\n Returns:\n Tuple of (is_safe, critical_count, high_count, medium_count, low_count)\n \"\"\"\n critical_count = 0\n high_count = 0\n medium_count = 0\n low_count = 0\n\n # Navigate the raw output structure to find findings\n analysis_results = raw_output.get(\"analysis_results\", {})\n\n for _analyzer_name, analyzer_data in analysis_results.items():\n if isinstance(analyzer_data, dict):\n findings = analyzer_data.get(\"findings\", [])\n for finding in findings:\n severity = finding.get(\"severity\", \"\").lower()\n if severity == \"critical\":\n critical_count += 1\n elif severity == \"high\":\n high_count += 1\n elif severity == \"medium\":\n medium_count += 1\n elif severity == \"low\":\n low_count += 1\n\n # Determine if safe: no critical or high severity issues\n is_safe = critical_count == 0 and high_count == 0\n\n logger.info(\"Security analysis results:\")\n logger.info(f\" Critical Issues: {critical_count}\")\n logger.info(f\" High Severity: {high_count}\")\n logger.info(f\" Medium Severity: {medium_count}\")\n logger.info(f\" Low Severity: {low_count}\")\n logger.info(f\" Overall Assessment: {'SAFE' if is_safe else 'UNSAFE'}\")\n\n return is_safe, critical_count, high_count, medium_count, low_count\n\n async def get_scan_result(self, server_path: str) -> dict | None:\n \"\"\"\n Get the latest scan result for a server.\n\n Args:\n server_path: Server path (e.g., /cloudflare-docs)\n\n Returns:\n Dictionary containing scan results, or None if no scan found\n \"\"\"\n try:\n # Get latest scan from repository\n scan_result = await self._scan_repo.get_latest(server_path)\n\n if scan_result:\n logger.info(f\"Loaded security scan results for {server_path} from repository\")\n # Convert to dict if needed\n if hasattr(scan_result, \"model_dump\"):\n return scan_result.model_dump()\n return scan_result\n\n logger.warning(f\"No security scan results found for server {server_path}\")\n return None\n\n except Exception as e:\n logger.exception(f\"Unexpected error loading security scan results for {server_path}\")\n return None\n\n\n# Global singleton instance\nsecurity_scanner_service = SecurityScannerService()\n" }, { "path": "registry/services/server_service.py", "content": "import asyncio\nimport logging\nfrom typing import Any\n\nfrom ..repositories.factory import get_server_repository\nfrom ..repositories.interfaces import ServerRepositoryBase\nfrom ..utils.credential_encryption import (\n _migrate_auth_type_to_auth_scheme,\n strip_credentials_from_dict,\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass ServerService:\n \"\"\"Service for managing server registration and state.\"\"\"\n\n def __init__(self):\n self._repo: ServerRepositoryBase = get_server_repository()\n from ..repositories.factory import get_search_repository\n\n self._search_repo = get_search_repository()\n\n def _prepare_server_dict(\n self,\n server_dict: dict[str, Any],\n include_credentials: bool = False,\n ) -> dict[str, Any]:\n \"\"\"Apply read-time migration and optionally strip credentials.\n\n Args:\n server_dict: Raw server dict from storage.\n include_credentials: If True, keep encrypted credentials in the dict.\n\n Returns:\n Prepared server dict with auth_scheme migrated and credentials\n optionally stripped.\n \"\"\"\n _migrate_auth_type_to_auth_scheme(server_dict)\n if not include_credentials:\n strip_credentials_from_dict(server_dict)\n return server_dict\n\n async def load_servers_and_state(self):\n \"\"\"Load server definitions and persisted state from repository.\"\"\"\n # Delegate to repository - no longer maintains service-level cache\n await self._repo.load_all()\n\n async def register_server(\n self,\n server_info: dict[str, Any],\n is_version_registration: bool = False,\n ) -> dict[str, Any]:\n \"\"\"\n Register a new server or a new version of an existing server.\n\n If a server with the same path exists:\n - If new server has a different version, register as inactive version\n - If same version or no version specified, return 409 conflict\n\n Args:\n server_info: Server configuration dict\n is_version_registration: Internal flag, True when called recursively for version\n\n Returns:\n Dict with 'success', 'message', and optionally 'is_new_version' keys\n \"\"\"\n path = server_info.get(\"path\")\n new_version = server_info.get(\"version\")\n\n # Check if server with this path already exists\n existing_server = await self._repo.get(path)\n\n if existing_server:\n existing_version = existing_server.get(\"version\", \"v1.0.0\")\n\n # If new version is specified and different, register as new version\n if new_version and new_version != existing_version:\n logger.info(\n f\"Server {path} exists with version {existing_version}, \"\n f\"registering {new_version} as new version\"\n )\n\n # Use add_server_version to create the inactive version document\n try:\n await self.add_server_version(\n path=path,\n version=new_version,\n proxy_pass_url=server_info.get(\"proxy_pass_url\"),\n status=server_info.get(\"status\", \"stable\"),\n is_default=False,\n )\n return {\n \"success\": True,\n \"message\": f\"Registered version {new_version} for existing server {path}\",\n \"is_new_version\": True,\n \"existing_version\": existing_version,\n }\n except ValueError as e:\n return {\n \"success\": False,\n \"message\": str(e),\n \"is_new_version\": False,\n }\n\n # Same version or no version - conflict\n return {\n \"success\": False,\n \"message\": f\"Server already exists at path {path} with version {existing_version}\",\n \"is_new_version\": False,\n }\n\n # New server - create it\n # Initialize version metadata for new servers\n if not server_info.get(\"version\"):\n server_info[\"version\"] = \"v1.0.0\"\n server_info[\"is_active\"] = True\n\n result = await self._repo.create(server_info)\n\n if result:\n # Index in search backend\n try:\n is_enabled = await self._repo.get_state(path)\n await self._search_repo.index_server(path, server_info, is_enabled)\n except Exception as e:\n logger.error(f\"Failed to index server {path}: {e}\")\n # Don't fail the primary operation\n\n return {\n \"success\": True,\n \"message\": f\"Server registered at {path}\",\n \"is_new_version\": False,\n }\n\n return {\n \"success\": False,\n \"message\": f\"Failed to register server at {path}\",\n \"is_new_version\": False,\n }\n\n async def update_server(self, path: str, server_info: dict[str, Any]) -> bool:\n \"\"\"Update an existing server.\"\"\"\n result = await self._repo.update(path, server_info)\n\n if result:\n # Update search index\n try:\n is_enabled = await self._repo.get_state(path)\n await self._search_repo.index_server(path, server_info, is_enabled)\n except Exception as e:\n logger.error(f\"Failed to update search index after server update: {e}\")\n\n # Regenerate nginx config if enabled\n if await self._repo.get_state(path):\n try:\n from ..core.nginx_service import nginx_service\n\n enabled_servers = {\n service_path: await self.get_server_info(service_path)\n for service_path in await self.get_enabled_services()\n }\n await nginx_service.generate_config_async(enabled_servers)\n nginx_service.reload_nginx()\n logger.info(f\"Regenerated nginx config due to server update: {path}\")\n except Exception as e:\n logger.error(\n f\"Failed to regenerate nginx configuration after server update: {e}\"\n )\n\n return result\n\n async def toggle_service(self, path: str, enabled: bool) -> bool:\n \"\"\"Toggle service enabled/disabled state.\"\"\"\n result = await self._repo.set_state(path, enabled)\n\n if result:\n # Trigger nginx config regeneration\n try:\n from ..core.nginx_service import nginx_service\n\n enabled_servers = {\n service_path: await self.get_server_info(service_path)\n for service_path in await self.get_enabled_services()\n }\n await nginx_service.generate_config_async(enabled_servers)\n nginx_service.reload_nginx()\n except Exception as e:\n logger.error(f\"Failed to update nginx configuration after toggle: {e}\")\n\n return result\n\n async def get_server_info(\n self,\n path: str,\n include_credentials: bool = False,\n ) -> dict[str, Any] | None:\n \"\"\"Get server information by path - queries repository directly.\n\n Args:\n path: Server path (e.g., \"/my-server\").\n include_credentials: If True, include encrypted credentials in result.\n Set to True only for internal callers like health checks.\n\n Returns:\n Server info dict, or None if not found.\n \"\"\"\n result = await self._repo.get(path)\n if result:\n self._prepare_server_dict(result, include_credentials)\n return result\n\n async def get_all_servers(\n self,\n include_inactive: bool = False,\n include_credentials: bool = False,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"\n Get all registered servers.\n\n Args:\n include_inactive: If True, include inactive server versions (default False)\n include_credentials: If True, include encrypted credentials in result\n\n Returns:\n Dict of all servers\n \"\"\"\n # Query repository directly instead of using cache\n all_servers = await self._repo.list_all()\n\n # Apply read-time migration and credential stripping\n for server_info in all_servers.values():\n self._prepare_server_dict(server_info, include_credentials)\n\n # Filter out inactive servers (non-default versions) unless requested\n if not include_inactive:\n all_servers = {\n path: server_info\n for path, server_info in all_servers.items()\n if server_info.get(\"is_active\", True) # Default to True for backward compatibility\n }\n\n return all_servers\n\n async def get_servers_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> tuple[dict[str, dict[str, Any]], int]:\n \"\"\"Get a page of servers with total count.\n\n Used for unrestricted users (admins) where DB-level pagination\n is correct because no servers are filtered out by access control.\n\n Note: list_paginated and count are separate DB calls, so total_count\n may be slightly inconsistent if servers are added/removed between calls.\n This is standard for offset-based pagination.\n\n Args:\n skip: Number of servers to skip.\n limit: Maximum number of servers to return.\n\n Returns:\n Tuple of (servers dict for the requested page, total count of all servers).\n \"\"\"\n servers = await self._repo.list_paginated(skip=skip, limit=limit)\n total = await self._repo.count()\n\n # Apply read-time migration and credential stripping\n for server_info in servers.values():\n self._prepare_server_dict(server_info, include_credentials=False)\n\n # Filter out inactive servers (non-default versions)\n servers = {\n path: server_info\n for path, server_info in servers.items()\n if server_info.get(\"is_active\", True)\n }\n\n return servers, total\n\n async def get_filtered_servers(\n self,\n accessible_servers: list[str],\n include_inactive: bool = False,\n ) -> dict[str, dict[str, Any]]:\n \"\"\"\n Get servers filtered by user's accessible servers list.\n\n Args:\n accessible_servers: List of server names the user can access\n include_inactive: If True, include inactive server versions (default False)\n\n Returns:\n Dict of servers the user is authorized to see\n \"\"\"\n if not accessible_servers:\n logger.debug(\"User has no accessible servers, returning empty dict\")\n return {}\n\n # Wildcard access — return all servers (non-admin with server: '*')\n if \"*\" in accessible_servers:\n logger.debug(\"Wildcard access detected in accessible_servers, returning all servers\")\n return await self.get_all_servers(include_inactive=include_inactive)\n\n # Query repository directly instead of using cache\n all_servers = await self._repo.list_all()\n\n # Apply read-time migration and credential stripping\n for server_info in all_servers.values():\n self._prepare_server_dict(server_info, include_credentials=False)\n\n # Filter out inactive servers (non-default versions) unless requested\n if not include_inactive:\n all_servers = {\n path: server_info\n for path, server_info in all_servers.items()\n if server_info.get(\"is_active\", True) # Default to True for backward compatibility\n }\n\n logger.info(\n f\"DEBUG: get_filtered_servers called with accessible_servers: {accessible_servers}\"\n )\n logger.info(f\"DEBUG: Available registered servers paths: {list(all_servers.keys())}\")\n\n filtered_servers = {}\n for path, server_info in all_servers.items():\n server_name = server_info.get(\"server_name\", \"\")\n # Extract technical name from path (remove leading and trailing slashes)\n technical_name = path.strip(\"/\")\n logger.info(\n f\"DEBUG: Checking server path='{path}', server_name='{server_name}', technical_name='{technical_name}' against accessible_servers\"\n )\n\n # Check if user has access to this server using technical name\n if technical_name in accessible_servers:\n filtered_servers[path] = server_info\n logger.info(f\"DEBUG: ✓ User has access to server: {technical_name} ({server_name})\")\n else:\n logger.info(\n f\"DEBUG: ✗ User does not have access to server: {technical_name} ({server_name})\"\n )\n\n logger.info(\n f\"Filtered {len(filtered_servers)} servers from {len(all_servers)} total servers\"\n )\n return filtered_servers\n\n async def get_all_servers_with_permissions(\n self, accessible_servers: list[str] | None = None\n ) -> dict[str, dict[str, Any]]:\n \"\"\"\n Get servers with optional filtering based on user permissions.\n\n Args:\n accessible_servers: Optional list of server names the user can access.\n If None, returns all servers (admin access).\n\n Returns:\n Dict of servers the user is authorized to see\n \"\"\"\n if accessible_servers is None:\n # Admin access - return all servers\n logger.debug(\"Admin access - returning all servers\")\n return await self.get_all_servers()\n elif \"*\" in accessible_servers:\n # Wildcard access — return all servers (non-admin with server: '*')\n logger.debug(\"Wildcard access detected in accessible_servers, returning all servers\")\n return await self.get_all_servers()\n else:\n # Filtered access - return only accessible servers\n logger.debug(\n f\"Filtered access - returning servers accessible to user: {accessible_servers}\"\n )\n all_servers = await self.get_all_servers()\n\n # Filter based on accessible_servers\n filtered_servers = {}\n logger.info(f\"[FILTER DEBUG] Starting to filter {len(all_servers)} servers\")\n logger.info(f\"[FILTER DEBUG] accessible_servers = {accessible_servers}\")\n\n for path, server_info in all_servers.items():\n server_name = server_info.get(\"server_name\", \"\")\n technical_name = path.strip(\"/\")\n\n logger.info(\n f\"[FILTER DEBUG] Checking server: path='{path}', technical_name='{technical_name}', server_name='{server_name}'\"\n )\n\n # Check if user has access to this server using multiple formats\n # Support: \"currenttime\", \"/currenttime\", \"/currenttime/\"\n has_access = False\n for accessible_server in accessible_servers:\n # Normalize both sides by stripping slashes for comparison\n normalized_accessible = accessible_server.strip(\"/\")\n logger.info(\n f\"[FILTER DEBUG] Comparing: '{technical_name}' == '{normalized_accessible}' ? {technical_name == normalized_accessible}\"\n )\n if technical_name == normalized_accessible:\n has_access = True\n break\n\n logger.info(f\"[FILTER DEBUG] has_access = {has_access}\")\n if has_access:\n filtered_servers[path] = server_info\n\n logger.info(f\"[FILTER DEBUG] Final filtered_servers: {len(filtered_servers)} servers\")\n logger.info(f\"[FILTER DEBUG] Filtered server paths: {list(filtered_servers.keys())}\")\n return filtered_servers\n\n async def user_can_access_server_path(self, path: str, accessible_servers: list[str]) -> bool:\n \"\"\"\n Check if user can access a specific server by path.\n\n Args:\n path: Server path to check\n accessible_servers: List of server names the user can access\n\n Returns:\n True if user can access the server, False otherwise\n \"\"\"\n server_info = await self.get_server_info(path)\n if not server_info:\n return False\n\n # Wildcard access — grant access to any existing server (non-admin with server: '*')\n if \"*\" in accessible_servers:\n return True\n\n # Extract technical name from path (remove leading and trailing slashes)\n technical_name = path.strip(\"/\")\n\n # Check with normalized paths - support \"currenttime\", \"/currenttime\", \"/currenttime/\"\n for accessible_server in accessible_servers:\n normalized_accessible = accessible_server.strip(\"/\")\n if technical_name == normalized_accessible:\n return True\n\n return False\n\n async def is_service_enabled(self, path: str) -> bool:\n \"\"\"Check if a service is enabled.\"\"\"\n return await self._repo.get_state(path)\n\n async def get_enabled_services(self) -> list[str]:\n \"\"\"Get list of enabled service paths - queries repository directly.\n\n Only returns active versions for health checks. Inactive versions\n (those with is_active=False) are skipped since health checks should\n only run on the currently active version of each server.\n \"\"\"\n all_servers = await self._repo.list_all()\n enabled_paths = []\n\n # Extract state from list_all() response instead of N+1 queries\n for path, server_info in all_servers.items():\n if not server_info.get(\"is_enabled\", False):\n continue\n\n # Skip inactive versions - only health check active versions\n # Servers without version_group are single-version (implicitly active)\n # Servers with version_group but is_active=False are inactive versions\n if server_info.get(\"version_group\") and not server_info.get(\"is_active\", True):\n continue\n\n enabled_paths.append(path)\n\n return enabled_paths\n\n async def reload_state_from_disk(self):\n \"\"\"Reload service state from repository.\"\"\"\n logger.info(\"Reloading service state from repository...\")\n\n previous_enabled_services = set(await self.get_enabled_services())\n\n # Reload from repository\n await self._repo.load_all()\n\n current_enabled_services = set(await self.get_enabled_services())\n\n if previous_enabled_services != current_enabled_services:\n logger.info(\n f\"Service state changes detected: {len(previous_enabled_services)} -> {len(current_enabled_services)} enabled services\"\n )\n\n try:\n from ..core.nginx_service import nginx_service\n\n enabled_servers = {\n service_path: await self.get_server_info(service_path)\n for service_path in await self.get_enabled_services()\n }\n await nginx_service.generate_config_async(enabled_servers)\n nginx_service.reload_nginx()\n logger.info(\"Regenerated nginx config due to state reload\")\n except Exception as e:\n logger.error(f\"Failed to regenerate nginx configuration after state reload: {e}\")\n else:\n logger.info(\"No service state changes detected after reload\")\n\n async def update_rating(\n self,\n path: str,\n username: str,\n rating: int,\n ) -> float:\n \"\"\"\n Log a user rating for a server. If the user has already rated, update their rating.\n\n Args:\n path: server path\n username: The user who submitted rating\n rating: integer between 1-5\n\n Return:\n Updated average rating\n\n Raises:\n ValueError: If server not found or invalid rating\n \"\"\"\n from . import rating_service\n\n # Query repository directly instead of using cache\n server_info = await self._repo.get(path)\n if not server_info:\n logger.error(f\"Cannot update server at path '{path}': not found\")\n raise ValueError(f\"Server not found at path: {path}\")\n\n # Validate rating using shared service\n rating_service.validate_rating(rating)\n\n # Ensure rating_details is a list\n if \"rating_details\" not in server_info or server_info[\"rating_details\"] is None:\n server_info[\"rating_details\"] = []\n\n # Update rating details using shared service\n updated_details, is_new_rating = rating_service.update_rating_details(\n server_info[\"rating_details\"], username, rating\n )\n server_info[\"rating_details\"] = updated_details\n\n # Calculate average rating using shared service\n server_info[\"num_stars\"] = rating_service.calculate_average_rating(\n server_info[\"rating_details\"]\n )\n\n # Save to repository\n await self._repo.update(path, server_info)\n\n logger.info(\n f\"Updated rating for server {path}: user {username} rated {rating}, \"\n f\"new average: {server_info['num_stars']:.2f}\"\n )\n return server_info[\"num_stars\"]\n\n async def remove_server(self, path: str) -> bool:\n \"\"\"Remove a server and all its version documents from the registry.\n\n Deletes the active document and any inactive version documents\n with IDs matching `{path}:{version}` (e.g., /context7:v2.0.0).\n\n Args:\n path: Server base path (e.g., \"/context7\")\n\n Returns:\n True if at least one document was deleted\n \"\"\"\n deleted_count = await self._repo.delete_with_versions(path)\n\n if deleted_count > 0:\n # Remove from search backend\n try:\n await self._search_repo.remove_entity(path)\n except Exception as e:\n logger.error(f\"Failed to remove server {path} from search: {e}\")\n\n return deleted_count > 0\n\n async def add_server_version(\n self,\n path: str,\n version: str,\n proxy_pass_url: str,\n status: str = \"stable\",\n is_default: bool = False,\n ) -> bool:\n \"\"\"\n Add a new version to an existing server.\n\n Uses the separate-documents design where each version is a separate document:\n - Active version uses `_id: \"{path}\"`\n - Inactive versions use `_id: \"{path}:{version}\"`\n\n Args:\n path: Server path (e.g., \"/context7\")\n version: Version identifier (e.g., \"v2.0.0\")\n proxy_pass_url: Backend URL for this version\n status: Version status (stable, deprecated, beta)\n is_default: Set this as the default version\n\n Returns:\n True if version added successfully\n\n Raises:\n ValueError: If server not found or version already exists\n \"\"\"\n # Get active server document\n active_server = await self._repo.get(path)\n if not active_server:\n raise ValueError(f\"Server not found: {path}\")\n\n # Derive version_group from path (e.g., \"/context7\" -> \"context7\")\n version_group = path.strip(\"/\").replace(\"/\", \"-\")\n\n # Initialize version metadata on active server if first multi-version setup\n if not active_server.get(\"version_group\"):\n active_server[\"version\"] = active_server.get(\"version\", \"v1.0.0\")\n active_server[\"is_active\"] = True\n active_server[\"version_group\"] = version_group\n active_server[\"other_version_ids\"] = []\n await self._repo.update(path, active_server)\n\n # Check if version already exists\n new_version_id = f\"{path}:{version}\"\n existing_inactive = await self._repo.get(new_version_id)\n if existing_inactive:\n raise ValueError(f\"Version {version} already exists for server {path}\")\n\n # Check if version matches active version\n if active_server.get(\"version\") == version:\n raise ValueError(f\"Version {version} already exists as active version\")\n\n # Create new version document (inactive by default)\n new_version_doc = {\n \"path\": new_version_id,\n \"server_name\": active_server.get(\"server_name\"),\n \"version\": version,\n \"proxy_pass_url\": proxy_pass_url,\n \"status\": status,\n \"is_active\": False,\n \"version_group\": version_group,\n \"active_version_id\": path,\n \"description\": active_server.get(\"description\", \"\"),\n \"tags\": active_server.get(\"tags\", []),\n \"supported_transports\": active_server.get(\"supported_transports\", []),\n \"is_enabled\": active_server.get(\"is_enabled\", False),\n }\n\n # Create the new version document\n result = await self._repo.create(new_version_doc)\n\n if result:\n # Update active server's other_version_ids\n other_versions = active_server.get(\"other_version_ids\", [])\n other_versions.append(new_version_id)\n active_server[\"other_version_ids\"] = other_versions\n await self._repo.update(path, active_server)\n\n # If is_default, swap this to be the active version\n if is_default:\n await self.set_default_version(path, version)\n\n # Regenerate nginx config\n await self._regenerate_nginx_config()\n logger.info(f\"Added version {version} to server {path}\")\n\n return result\n\n async def remove_server_version(self, path: str, version: str) -> bool:\n \"\"\"\n Remove a version from a server.\n\n Uses separate-documents design: deletes the inactive version document.\n\n Args:\n path: Server path\n version: Version to remove\n\n Returns:\n True if version removed successfully\n\n Raises:\n ValueError: If server not found, version not found, or trying to remove active\n \"\"\"\n # Get active server document\n active_server = await self._repo.get(path)\n if not active_server:\n raise ValueError(f\"Server not found: {path}\")\n\n # Cannot remove active version\n if active_server.get(\"version\") == version:\n raise ValueError(\n f\"Cannot remove active version {version}. Set a new active version first.\"\n )\n\n # Check if this is a single-version server\n if not active_server.get(\"version_group\"):\n raise ValueError(f\"Server {path} has no versions to remove\")\n\n # Find and remove the inactive version document\n version_id = f\"{path}:{version}\"\n inactive_version = await self._repo.get(version_id)\n if not inactive_version:\n raise ValueError(f\"Version {version} not found for server {path}\")\n\n # Delete the inactive version document\n result = await self._repo.delete(version_id)\n\n if result:\n # Update active server's other_version_ids\n other_versions = active_server.get(\"other_version_ids\", [])\n if version_id in other_versions:\n other_versions.remove(version_id)\n active_server[\"other_version_ids\"] = other_versions\n await self._repo.update(path, active_server)\n\n await self._regenerate_nginx_config()\n logger.info(f\"Removed version {version} from server {path}\")\n\n return result\n\n async def set_default_version(self, path: str, version: str) -> bool:\n \"\"\"\n Set the default (active) version for a server.\n\n Uses separate-documents design: swaps documents by:\n 1. Current active becomes inactive with _id: \"{path}:{current_version}\"\n 2. Target inactive becomes active with _id: \"{path}\"\n\n Args:\n path: Server path\n version: Version to set as active\n\n Returns:\n True if swap successful\n\n Raises:\n ValueError: If server or version not found\n \"\"\"\n # Get current active document - try with and without trailing slash\n current_active = await self._repo.get(path)\n if not current_active and not path.endswith(\"/\"):\n path_with_slash = path + \"/\"\n current_active = await self._repo.get(path_with_slash)\n if current_active:\n path = path_with_slash\n logger.debug(f\"Normalized path to {path} (added trailing slash)\")\n if not current_active:\n raise ValueError(f\"Server not found: {path}\")\n\n current_version = current_active.get(\"version\", \"v1.0.0\")\n\n # If already active, nothing to do\n if current_version == version:\n logger.info(f\"Version {version} is already the active version\")\n return True\n\n # Check if this is a single-version server\n if not current_active.get(\"version_group\"):\n raise ValueError(f\"Server {path} has no other versions configured\")\n\n # Find target inactive version\n target_version_id = f\"{path}:{version}\"\n target_inactive = await self._repo.get(target_version_id)\n if not target_inactive:\n # List available versions\n other_version_ids = current_active.get(\"other_version_ids\", [])\n available = [vid.split(\":\")[-1] for vid in other_version_ids]\n raise ValueError(f\"Version {version} not found. Available: {available}\")\n\n # Prepare new active doc (target becomes active with original path)\n new_active = {**target_inactive}\n new_active[\"path\"] = path\n new_active[\"is_active\"] = True\n new_active.pop(\"active_version_id\", None)\n # Update other_version_ids: remove target, add current\n other_versions = list(current_active.get(\"other_version_ids\", []))\n if target_version_id in other_versions:\n other_versions.remove(target_version_id)\n new_inactive_id = f\"{path}:{current_version}\"\n other_versions.append(new_inactive_id)\n new_active[\"other_version_ids\"] = other_versions\n\n # Prepare new inactive doc (current becomes inactive with compound id)\n new_inactive = {**current_active}\n new_inactive[\"path\"] = new_inactive_id\n new_inactive[\"is_active\"] = False\n new_inactive[\"active_version_id\"] = path\n new_inactive.pop(\"other_version_ids\", None)\n\n # Execute swap: delete old docs, insert new docs\n await self._repo.delete(path)\n await self._repo.delete(target_version_id)\n await self._repo.create(new_active)\n await self._repo.create(new_inactive)\n\n # Update search index: re-index with new active version\n try:\n is_enabled = new_active.get(\"is_enabled\", False)\n await self._search_repo.index_server(path, new_active, is_enabled)\n logger.info(f\"Updated search index for {path} with version {version}\")\n except Exception as e:\n logger.error(f\"Failed to update search index after version swap: {e}\")\n\n await self._regenerate_nginx_config()\n logger.info(f\"Swapped active version from {current_version} to {version} for {path}\")\n\n # Trigger an immediate health check for the newly active version\n try:\n from ..health.service import health_service\n\n asyncio.create_task(health_service.perform_immediate_health_check(path))\n logger.info(\n f\"Triggered background health check for {path} after version swap to {version}\"\n )\n except Exception as e:\n logger.error(f\"Failed to trigger health check after version swap for {path}: {e}\")\n\n return True\n\n async def get_server_versions(self, path: str) -> dict[str, Any]:\n \"\"\"\n Get all versions for a server.\n\n Uses separate-documents design: queries by version_group.\n\n Args:\n path: Server path\n\n Returns:\n Dictionary with version information\n\n Raises:\n ValueError: If server not found\n \"\"\"\n # Get active server\n active_server = await self._repo.get(path)\n if not active_server:\n raise ValueError(f\"Server not found: {path}\")\n\n # Single-version server (no version_group)\n if not active_server.get(\"version_group\"):\n return {\n \"path\": path,\n \"default_version\": active_server.get(\"version\", \"v1.0.0\"),\n \"versions\": [\n {\n \"version\": active_server.get(\"version\", \"v1.0.0\"),\n \"proxy_pass_url\": active_server.get(\"proxy_pass_url\"),\n \"status\": \"stable\",\n \"is_default\": True,\n }\n ],\n }\n\n # Build versions list from active + inactive documents\n versions = []\n\n # Add active version\n versions.append(\n {\n \"version\": active_server.get(\"version\"),\n \"proxy_pass_url\": active_server.get(\"proxy_pass_url\"),\n \"status\": active_server.get(\"status\", \"stable\"),\n \"is_default\": True,\n \"description\": active_server.get(\"description\"),\n }\n )\n\n # Add inactive versions\n other_version_ids = active_server.get(\"other_version_ids\", [])\n for version_id in other_version_ids:\n inactive_doc = await self._repo.get(version_id)\n if inactive_doc:\n versions.append(\n {\n \"version\": inactive_doc.get(\"version\"),\n \"proxy_pass_url\": inactive_doc.get(\"proxy_pass_url\"),\n \"status\": inactive_doc.get(\"status\", \"stable\"),\n \"is_default\": False,\n \"description\": inactive_doc.get(\"description\"),\n }\n )\n\n return {\"path\": path, \"default_version\": active_server.get(\"version\"), \"versions\": versions}\n\n async def _regenerate_nginx_config(self) -> None:\n \"\"\"Regenerate nginx configuration for all enabled servers.\"\"\"\n try:\n from ..core.nginx_service import nginx_service\n\n enabled_servers = {}\n for service_path in await self.get_enabled_services():\n server_info = await self.get_server_info(service_path)\n if server_info:\n enabled_servers[service_path] = server_info\n\n await nginx_service.generate_config_async(enabled_servers)\n nginx_service.reload_nginx()\n logger.info(\"Regenerated nginx config after version change\")\n\n except Exception as e:\n logger.error(f\"Failed to regenerate nginx configuration: {e}\")\n raise\n\n\n# Global service instance\nserver_service = ServerService()\n" }, { "path": "registry/services/skill_scanner.py", "content": "\"\"\"\nSkill Scanner Service\n\nWraps the Cisco AI Defense skill-scanner CLI tool for security scanning\nof AI agent skills during registration.\n\"\"\"\n\nimport asyncio\nimport json\nimport logging\nimport os\nimport re\nimport subprocess # nosec B404\nimport tempfile\nfrom datetime import UTC, datetime\nfrom pathlib import Path\n\nfrom ..core.config import settings\nfrom ..repositories.factory import get_skill_security_scan_repository\nfrom ..schemas.skill_security import SkillSecurityScanConfig, SkillSecurityScanResult\n\nlogger = logging.getLogger(__name__)\n\nOUTPUT_DIR = Path(__file__).parent.parent.parent / \"skill_security_scans\"\n\n\nclass SkillScannerService:\n \"\"\"Service for scanning skills for security vulnerabilities.\"\"\"\n\n def __init__(self) -> None:\n \"\"\"Initialize the skill scanner service.\"\"\"\n self._ensure_output_directory()\n self._scan_repo = None\n\n @property\n def scan_repo(self):\n \"\"\"Lazy-load the scan repository.\"\"\"\n if self._scan_repo is None:\n self._scan_repo = get_skill_security_scan_repository()\n return self._scan_repo\n\n def _ensure_output_directory(self) -> Path:\n \"\"\"Ensure output directory exists.\"\"\"\n OUTPUT_DIR.mkdir(parents=True, exist_ok=True)\n return OUTPUT_DIR\n\n def get_scan_config(self) -> SkillSecurityScanConfig:\n \"\"\"Get skill security scan configuration from settings.\"\"\"\n return SkillSecurityScanConfig(\n enabled=settings.skill_security_scan_enabled,\n scan_on_registration=settings.skill_security_scan_on_registration,\n block_unsafe_skills=settings.skill_security_block_unsafe_skills,\n analyzers=settings.skill_security_analyzers,\n scan_timeout_seconds=settings.skill_security_scan_timeout,\n llm_api_key=settings.skill_scanner_llm_api_key\n or os.getenv(\"SKILL_SCANNER_LLM_API_KEY\"),\n virustotal_api_key=settings.skill_scanner_virustotal_api_key\n or os.getenv(\"VIRUSTOTAL_API_KEY\"),\n ai_defense_api_key=settings.skill_scanner_ai_defense_api_key\n or os.getenv(\"AI_DEFENSE_API_KEY\"),\n add_security_pending_tag=settings.skill_security_add_pending_tag,\n )\n\n async def scan_skill(\n self,\n skill_path: str,\n skill_md_url: str | None = None,\n skill_content_path: str | None = None,\n analyzers: str | None = None,\n timeout: int | None = None,\n headers: dict[str, str] | None = None,\n ) -> SkillSecurityScanResult:\n \"\"\"\n Scan a skill for security vulnerabilities.\n\n Args:\n skill_path: Registry path of the skill (e.g., /skills/pdf-processing)\n skill_md_url: URL to SKILL.md file (for remote scanning)\n skill_content_path: Local path to skill content (for local scanning)\n analyzers: Comma-separated list of analyzers\n timeout: Scan timeout in seconds\n headers: Optional HTTP headers for authenticated SKILL.md downloads\n\n Returns:\n SkillSecurityScanResult containing scan results\n \"\"\"\n config = self.get_scan_config()\n\n if analyzers is None:\n analyzers = config.analyzers\n if timeout is None:\n timeout = config.scan_timeout_seconds\n\n logger.info(f\"Starting skill security scan for {skill_path} with analyzers: {analyzers}\")\n\n try:\n raw_output = await asyncio.to_thread(\n self._run_skill_scanner,\n skill_path=skill_path,\n skill_md_url=skill_md_url,\n skill_content_path=skill_content_path,\n analyzers=analyzers,\n timeout=timeout,\n headers=headers,\n )\n\n is_safe, critical, high, medium, low = self._analyze_scan_results(raw_output)\n\n result = SkillSecurityScanResult(\n skill_path=skill_path,\n skill_md_url=skill_md_url,\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=is_safe,\n critical_issues=critical,\n high_severity=high,\n medium_severity=medium,\n low_severity=low,\n analyzers_used=analyzers.split(\",\"),\n raw_output=raw_output,\n scan_failed=False,\n )\n\n await self.scan_repo.create(result.model_dump())\n\n logger.info(\n f\"Skill security scan completed for {skill_path}. \"\n f\"Safe: {is_safe}, Critical: {critical}, High: {high}\"\n )\n\n return result\n\n except Exception as e:\n logger.error(f\"Skill security scan failed for {skill_path}: {e}\")\n\n result = SkillSecurityScanResult(\n skill_path=skill_path,\n skill_md_url=skill_md_url,\n scan_timestamp=datetime.now(UTC).isoformat().replace(\"+00:00\", \"Z\"),\n is_safe=False,\n analyzers_used=analyzers.split(\",\") if analyzers else [],\n raw_output={\"error\": str(e), \"scan_failed\": True},\n scan_failed=True,\n error_message=str(e),\n )\n\n await self.scan_repo.create(result.model_dump())\n return result\n\n def _run_skill_scanner(\n self,\n skill_path: str,\n skill_md_url: str | None = None,\n skill_content_path: str | None = None,\n analyzers: str = \"static\",\n timeout: int = 120,\n headers: dict[str, str] | None = None,\n ) -> dict:\n \"\"\"\n Run skill-scanner command and return raw output.\n\n This is a synchronous method that runs in a thread pool.\n\n Args:\n skill_path: Registry path of the skill\n skill_md_url: URL to SKILL.md file\n skill_content_path: Local path to skill content\n analyzers: Comma-separated list of analyzers\n timeout: Scan timeout in seconds\n headers: Optional HTTP headers for authenticated downloads\n\n Returns:\n Dict containing parsed scan results\n\n Raises:\n RuntimeError: If scan times out or CLI returns non-zero exit code\n ValueError: If neither skill_content_path nor skill_md_url is provided\n \"\"\"\n logger.info(f\"Running skill security scan on: {skill_path}\")\n\n # Determine scan target\n if skill_content_path:\n target = skill_content_path\n elif skill_md_url:\n target = self._download_skill_content(skill_md_url, headers=headers)\n else:\n raise ValueError(\"Either skill_content_path or skill_md_url must be provided\")\n\n try:\n cmd = [\n \"skill-scanner\",\n \"scan\",\n target,\n \"--format\",\n \"json\",\n ]\n\n # Add optional analyzer flags based on config\n config = self.get_scan_config()\n analyzer_list = [a.strip() for a in analyzers.split(\",\")]\n if \"behavioral\" in analyzer_list:\n cmd.append(\"--use-behavioral\")\n if \"llm\" in analyzer_list:\n cmd.append(\"--use-llm\")\n if \"virustotal\" in analyzer_list:\n cmd.append(\"--use-virustotal\")\n if \"ai-defense\" in analyzer_list:\n cmd.append(\"--use-aidefense\")\n\n # Set environment variables for API keys\n env = os.environ.copy()\n if config.llm_api_key:\n env[\"LLM_API_KEY\"] = config.llm_api_key\n if config.virustotal_api_key:\n env[\"VIRUSTOTAL_API_KEY\"] = config.virustotal_api_key\n if config.ai_defense_api_key:\n env[\"AI_DEFENSE_API_KEY\"] = config.ai_defense_api_key\n\n result = subprocess.run( # nosec B603 - args are hardcoded flags and validated config values\n cmd,\n capture_output=True,\n text=True,\n check=True,\n env=env,\n timeout=timeout,\n )\n\n return self._parse_scanner_output(result.stdout)\n\n except subprocess.TimeoutExpired as e:\n raise RuntimeError(f\"Skill scan timed out after {timeout} seconds\") from e\n except subprocess.CalledProcessError as e:\n raise RuntimeError(f\"Skill scanner failed: {e.stderr}\") from e\n\n def _download_skill_content(\n self, skill_md_url: str, headers: dict[str, str] | None = None\n ) -> str:\n \"\"\"\n Download skill content for scanning.\n\n Mirrors the MCP server scanner pattern: accepts optional headers\n for authenticated endpoints (e.g., private Git repos).\n\n Args:\n skill_md_url: URL to SKILL.md file\n headers: Optional HTTP headers for authentication\n\n Returns:\n Path to temporary directory containing downloaded skill content\n\n Raises:\n httpx.HTTPError: If download fails\n \"\"\"\n import httpx\n\n temp_dir = tempfile.mkdtemp(prefix=\"skill_scan_\")\n skill_md_path = Path(temp_dir) / \"SKILL.md\"\n\n response = httpx.get(\n skill_md_url, headers=headers or {}, follow_redirects=True, timeout=30.0\n )\n response.raise_for_status()\n skill_md_path.write_text(response.text)\n\n return temp_dir\n\n def _parse_scanner_output(self, stdout: str) -> dict:\n \"\"\"\n Parse JSON output from skill-scanner CLI.\n\n Strips ANSI escape codes, parses JSON, and organizes findings by analyzer.\n\n Args:\n stdout: Raw stdout from skill-scanner CLI\n\n Returns:\n Dict with analysis_results organized by analyzer and raw scan_results\n \"\"\"\n # Remove ANSI codes\n ansi_escape = re.compile(r\"\\x1B(?:[@-Z\\\\-_]|\\[[0-?]*[ -/]*[@-~])\")\n clean_stdout = ansi_escape.sub(\"\", stdout.strip())\n\n # Parse JSON\n scan_results = json.loads(clean_stdout)\n\n # Organize into standard format\n raw_output = {\n \"analysis_results\": {},\n \"scan_results\": scan_results,\n }\n\n # Extract findings by analyzer\n findings = scan_results.get(\"findings\", [])\n for finding in findings:\n analyzer = finding.get(\"analyzer\", \"unknown\")\n if analyzer not in raw_output[\"analysis_results\"]:\n raw_output[\"analysis_results\"][analyzer] = {\"findings\": []}\n raw_output[\"analysis_results\"][analyzer][\"findings\"].append(finding)\n\n return raw_output\n\n def _analyze_scan_results(self, raw_output: dict) -> tuple[bool, int, int, int, int]:\n \"\"\"\n Analyze scan results and extract severity counts.\n\n Args:\n raw_output: Parsed scanner output dict\n\n Returns:\n Tuple of (is_safe, critical_count, high_count, medium_count, low_count)\n \"\"\"\n critical = high = medium = low = 0\n\n analysis_results = raw_output.get(\"analysis_results\", {})\n for analyzer_data in analysis_results.values():\n if isinstance(analyzer_data, dict):\n for finding in analyzer_data.get(\"findings\", []):\n severity = finding.get(\"severity\", \"\").lower()\n if severity == \"critical\":\n critical += 1\n elif severity == \"high\":\n high += 1\n elif severity == \"medium\":\n medium += 1\n elif severity == \"low\":\n low += 1\n\n is_safe = critical == 0 and high == 0\n\n logger.info(\n f\"Skill security analysis: Critical={critical}, High={high}, Medium={medium}, Low={low}\"\n )\n return is_safe, critical, high, medium, low\n\n async def get_scan_result(self, skill_path: str) -> dict | None:\n \"\"\"\n Get the latest scan result for a skill.\n\n Args:\n skill_path: Skill path (e.g., /skills/pdf-processing)\n\n Returns:\n Dictionary containing scan results, or None if no scan found\n \"\"\"\n try:\n scan_result = await self.scan_repo.get_latest(skill_path)\n if scan_result:\n if hasattr(scan_result, \"model_dump\"):\n return scan_result.model_dump()\n return scan_result\n return None\n except Exception:\n logger.exception(f\"Error loading skill scan results for {skill_path}\")\n return None\n\n\n# Global singleton instance\nskill_scanner_service = SkillScannerService()\n" }, { "path": "registry/services/skill_service.py", "content": "\"\"\"\nService layer for skill management.\n\nSimplified design:\n- No in-memory state duplication\n- Database as source of truth\n- SKILL.md URL validation on registration\n\"\"\"\n\nimport hashlib\nimport ipaddress\nimport logging\nimport socket\nfrom datetime import UTC, datetime\nfrom typing import (\n Any,\n)\nfrom urllib.parse import urlparse\n\nimport httpx\n\nfrom ..exceptions import (\n SkillUrlValidationError,\n)\nfrom ..repositories.factory import (\n get_search_repository,\n get_skill_repository,\n)\nfrom ..repositories.interfaces import (\n SearchRepositoryBase,\n SkillRepositoryBase,\n)\nfrom ..schemas.skill_models import (\n ContentIntegrity,\n FileHash,\n SkillCard,\n SkillInfo,\n SkillMetadata,\n SkillRegistrationRequest,\n VisibilityEnum,\n)\nfrom ..utils.path_utils import normalize_skill_path\nfrom ..utils.url_utils import (\n extract_repository_url,\n translate_skill_url,\n)\nfrom .github_auth import github_auth_provider as _github_auth\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Constants\nURL_VALIDATION_TIMEOUT: int = 10\n\n# Trusted domains that skip IP validation (SSRF protection allowlist)\nTRUSTED_DOMAINS: frozenset = frozenset(\n {\n \"github.com\",\n \"gitlab.com\",\n \"raw.githubusercontent.com\",\n \"bitbucket.org\",\n }\n)\n\n\ndef _is_private_ip(\n ip_str: str,\n) -> bool:\n \"\"\"Check if an IP address is private, loopback, or link-local.\n\n Args:\n ip_str: IP address string to check\n\n Returns:\n True if the IP is private/loopback/link-local, False otherwise\n \"\"\"\n try:\n ip = ipaddress.ip_address(ip_str)\n\n # Check for private, loopback, link-local, or reserved addresses\n if ip.is_private:\n return True\n if ip.is_loopback:\n return True\n if ip.is_link_local:\n return True\n if ip.is_reserved:\n return True\n\n # Check for cloud metadata endpoint (169.254.169.254)\n if ip_str == \"169.254.169.254\":\n return True\n\n return False\n except ValueError:\n # Invalid IP address format\n return True\n\n\ndef _is_safe_url(\n url: str,\n) -> bool:\n \"\"\"Check if a URL is safe to fetch (SSRF protection).\n\n This function validates that a URL:\n 1. Uses http or https scheme\n 2. Does not resolve to a private/loopback/link-local IP address\n 3. Does not target cloud metadata endpoints\n\n Trusted domains (github.com, gitlab.com, etc.) skip the IP check.\n\n Args:\n url: URL to validate\n\n Returns:\n True if the URL is safe to fetch, False otherwise\n \"\"\"\n try:\n parsed = urlparse(url)\n\n # Check scheme - only allow http and https\n if parsed.scheme not in (\"http\", \"https\"):\n logger.warning(f\"SSRF protection: Blocked URL with scheme '{parsed.scheme}'\")\n return False\n\n hostname = parsed.hostname\n if not hostname:\n logger.warning(\"SSRF protection: URL has no hostname\")\n return False\n\n # Check if hostname is in trusted domains allowlist\n hostname_lower = hostname.lower()\n if hostname_lower in TRUSTED_DOMAINS:\n logger.debug(f\"SSRF protection: Trusted domain '{hostname_lower}'\")\n return True\n\n # Resolve hostname to IP addresses\n try:\n addr_info = socket.getaddrinfo(\n hostname,\n parsed.port or (443 if parsed.scheme == \"https\" else 80),\n proto=socket.IPPROTO_TCP,\n )\n except socket.gaierror as e:\n logger.warning(f\"SSRF protection: Failed to resolve hostname '{hostname}': {e}\")\n return False\n\n # Check all resolved IP addresses\n for family, socktype, proto, canonname, sockaddr in addr_info:\n ip_address = sockaddr[0]\n if _is_private_ip(ip_address):\n logger.warning(\n f\"SSRF protection: Blocked URL resolving to private IP \"\n f\"'{ip_address}' for hostname '{hostname}'\"\n )\n return False\n\n return True\n\n except Exception as e:\n logger.warning(f\"SSRF protection: Error validating URL: {e}\")\n return False\n\n\ndef _build_fetch_headers(\n url: str,\n auth_scheme: str = \"none\",\n auth_credential: str | None = None,\n auth_header_name: str | None = None,\n) -> tuple[str, dict[str, str]]:\n \"\"\"Build fetch URL and auth headers for a SKILL.md request.\n\n Returns (fetch_url, headers) tuple. The URL is returned unchanged;\n platform-specific modules may override to translate web URLs to\n authenticated API endpoints.\n \"\"\"\n headers: dict[str, str] = {}\n fetch_url = url\n\n if auth_scheme in (\"none\", \"global_credentials\") or not auth_credential:\n return fetch_url, headers\n\n if auth_scheme == \"bearer\":\n header_name = auth_header_name or \"Authorization\"\n headers[header_name] = f\"Bearer {auth_credential}\"\n elif auth_scheme == \"api_key\":\n header_name = auth_header_name or \"PRIVATE-TOKEN\"\n headers[header_name] = auth_credential\n\n return fetch_url, headers\n\n\n_RESOURCE_TYPE_MAP: dict[str, str] = {\n \"references\": \"reference\",\n \"scripts\": \"script\",\n \"agents\": \"agent\",\n \"assets\": \"asset\",\n}\n\n_LANG_BY_EXT: dict[str, str] = {\n \".py\": \"python\",\n \".sh\": \"shell\",\n \".bash\": \"shell\",\n \".js\": \"javascript\",\n \".ts\": \"typescript\",\n \".yaml\": \"yaml\",\n \".yml\": \"yaml\",\n \".md\": \"markdown\",\n \".json\": \"json\",\n}\n\n\ndef _resolve_tree_api(\n skill_md_url: str,\n) -> tuple[str, str, str, str] | None:\n \"\"\"Resolve a tree/directory listing API endpoint for a skill URL.\n\n Returns (tree_api_url, encoded_project, ref, skill_dir) or None\n when no hosting-platform provider handles the URL. Override or\n extend this function to add support for specific Git platforms.\n\n .. note::\n **This is intentionally a stub.** The default implementation\n always returns ``None``, which means :func:`_discover_skill_resources`\n will not find any companion files until a deployment provides a\n platform-specific implementation (e.g. GitHub Trees API, GitLab\n Repository Tree, Bitbucket source listing).\n\n Multi-file resource support is fully wired through the rest of the\n stack (manifest storage, ``/content?resource=...`` serving, drift\n detection); only the discovery step is gated on this hook.\n Replace this function — or monkey-patch it from a deployment\n module — with a provider that returns the tuple described above\n to enable resource discovery for your hosting platform.\n \"\"\"\n return None\n\n\nasync def _discover_skill_resources(\n skill_md_url: str,\n auth_scheme: str = \"none\",\n auth_credential: str | None = None,\n auth_header_name: str | None = None,\n) -> \"SkillResourceManifest | None\":\n \"\"\"Discover companion resource files in the skill directory.\n\n Calls the hosting platform's tree/directory listing API to find files\n alongside SKILL.md and classifies them into the resource manifest.\n Returns None when the platform is not recognised or on any failure.\n \"\"\"\n from ..schemas.skill_models import SkillResource, SkillResourceManifest\n\n tree_info = _resolve_tree_api(skill_md_url)\n if not tree_info:\n logger.debug(\"Cannot derive tree API URL from %s — skipping resource discovery\", skill_md_url)\n return None\n\n tree_url, _encoded_project, _ref, skill_dir = tree_info\n skill_dir_prefix = skill_dir + \"/\" if skill_dir else \"\"\n _, headers = _build_fetch_headers(tree_url, auth_scheme, auth_credential, auth_header_name)\n\n try:\n async with httpx.AsyncClient(timeout=15.0) as client:\n resp = await client.get(tree_url, headers=headers)\n if resp.status_code >= 400:\n logger.warning(\"Resource discovery failed: HTTP %s for %s\", resp.status_code, tree_url)\n return None\n items = resp.json()\n except Exception as e:\n logger.warning(\"Resource discovery error for %s: %s\", tree_url, e)\n return None\n\n if not isinstance(items, list):\n return None\n\n manifest = SkillResourceManifest()\n for item in items:\n if item.get(\"type\") != \"blob\":\n continue\n path = item.get(\"path\", \"\")\n name = item.get(\"name\", \"\")\n if name.upper() == \"SKILL.MD\" or name.upper() == \"README.MD\" or name.upper() == \"LICENSE.TXT\":\n continue\n\n parts = path.split(\"/\")\n if len(parts) < 2:\n continue\n subdir = parts[-2] # immediate parent directory\n resource_type = _RESOURCE_TYPE_MAP.get(subdir)\n if not resource_type:\n continue\n\n ext = \".\" + name.rsplit(\".\", 1)[-1].lower() if \".\" in name else \"\"\n relative_path = path[len(skill_dir_prefix):] if path.startswith(skill_dir_prefix) else path\n\n resource = SkillResource(\n path=relative_path,\n type=resource_type,\n size_bytes=item.get(\"size\", 0),\n language=_LANG_BY_EXT.get(ext),\n )\n\n bucket = getattr(manifest, f\"{resource_type}s\" if resource_type != \"reference\" else \"references\", None)\n if bucket is not None:\n bucket.append(resource)\n\n total = len(manifest.references) + len(manifest.scripts) + len(manifest.agents) + len(manifest.assets)\n if total == 0:\n return None\n\n logger.info(\n \"Discovered %d resources: %d references, %d scripts, %d agents, %d assets\",\n total, len(manifest.references), len(manifest.scripts),\n len(manifest.agents), len(manifest.assets),\n )\n return manifest\n\n\nasync def _validate_skill_md_url(\n url: str,\n auth_scheme: str = \"none\",\n auth_credential: str | None = None,\n auth_header_name: str | None = None,\n) -> dict[str, Any]:\n \"\"\"Validate SKILL.md URL is accessible and get content hash.\n\n Args:\n url: URL to SKILL.md file\n auth_scheme: Authentication scheme (none, bearer, api_key)\n auth_credential: Plaintext credential for URL validation\n auth_header_name: Custom header name for the credential\n\n Returns:\n Dict with validation result and content hash\n\n Raises:\n SkillUrlValidationError: If URL is not accessible or fails SSRF check\n \"\"\"\n if not _is_safe_url(url):\n raise SkillUrlValidationError(\n url, \"URL failed SSRF validation - private/internal addresses are not allowed\"\n )\n\n fetch_url, fetch_headers = _build_fetch_headers(\n url, auth_scheme, auth_credential, auth_header_name\n )\n\n try:\n async with httpx.AsyncClient() as client:\n github_headers = await _github_auth.get_auth_headers(str(url))\n merged_headers = {**fetch_headers, **github_headers}\n response = await client.get(\n fetch_url, headers=merged_headers, follow_redirects=True,\n timeout=URL_VALIDATION_TIMEOUT,\n )\n\n final_url = str(response.url)\n if final_url != fetch_url and not _is_safe_url(final_url):\n logger.warning(\n f\"SSRF protection: Blocked redirect from {url} to unsafe URL {final_url}\"\n )\n raise SkillUrlValidationError(url, f\"Redirect to unsafe URL blocked: {final_url}\")\n\n if response.status_code >= 400:\n raise SkillUrlValidationError(url, f\"HTTP {response.status_code}\")\n\n content_hash = hashlib.sha256(response.content).hexdigest()[:16]\n\n return {\n \"valid\": True,\n \"content_version\": content_hash,\n \"content_updated_at\": datetime.now(UTC),\n }\n\n except httpx.RequestError as e:\n raise SkillUrlValidationError(url, str(e)) from e\n\n\nasync def _parse_skill_md_content(\n url: str,\n auth_scheme: str = \"none\",\n auth_credential: str | None = None,\n auth_header_name: str | None = None,\n) -> dict[str, Any]:\n \"\"\"Parse SKILL.md content and extract metadata.\n\n Parses the SKILL.md markdown file to extract:\n - name: From H1 heading or YAML frontmatter\n - description: From first paragraph or YAML frontmatter\n - version: From YAML frontmatter if present\n - tags: From YAML frontmatter if present\n\n Also translates GitHub URLs to raw content URLs.\n\n Args:\n url: URL to SKILL.md file (user-provided)\n\n Returns:\n Dict with parsed metadata including:\n - skill_md_url: Original user-provided URL\n - skill_md_raw_url: Translated raw URL for content fetching\n\n Raises:\n SkillUrlValidationError: If URL is not accessible\n \"\"\"\n import re\n\n # Translate URL to get both user-provided and raw URL\n user_url, raw_url = translate_skill_url(url)\n\n # Extract the repository URL from the user-provided URL\n repository_url = extract_repository_url(url)\n\n # Normalize to string for further validation\n raw_url_str = str(raw_url)\n\n # Basic scheme/hostname validation before SSRF/IP checks\n parsed_raw = urlparse(raw_url_str)\n if parsed_raw.scheme not in {\"http\", \"https\"} or not parsed_raw.hostname:\n raise SkillUrlValidationError(url, \"URL must use http/https scheme and include a hostname\")\n\n # SSRF protection - check the raw URL we'll actually fetch\n if not _is_safe_url(raw_url_str):\n raise SkillUrlValidationError(\n url, \"URL failed SSRF validation - private/internal addresses are not allowed\"\n )\n\n try:\n async with httpx.AsyncClient() as client:\n fetch_url, fetch_headers = _build_fetch_headers(\n raw_url_str, auth_scheme, auth_credential, auth_header_name,\n )\n if auth_scheme == \"none\":\n headers = fetch_headers\n elif auth_scheme == \"global_credentials\":\n headers = await _github_auth.get_auth_headers(fetch_url)\n else:\n github_headers = await _github_auth.get_auth_headers(fetch_url)\n headers = {**github_headers, **fetch_headers}\n response = await client.get(\n fetch_url, headers=headers, follow_redirects=True, timeout=URL_VALIDATION_TIMEOUT\n )\n\n # SSRF protection: validate final URL after redirects\n final_url = str(response.url)\n if final_url != str(raw_url) and not _is_safe_url(final_url):\n logger.warning(\n f\"SSRF protection: Blocked redirect from {raw_url} to unsafe URL {final_url}\"\n )\n raise SkillUrlValidationError(url, f\"Redirect to unsafe URL blocked: {final_url}\")\n\n if response.status_code >= 400:\n raise SkillUrlValidationError(url, f\"HTTP {response.status_code}\")\n\n content = response.text\n result: dict[str, Any] = {\n \"name\": None,\n \"description\": None,\n \"version\": None,\n \"tags\": [],\n \"content_version\": hashlib.sha256(response.content).hexdigest()[:16],\n \"skill_md_url\": user_url,\n \"skill_md_raw_url\": raw_url,\n \"repository_url\": repository_url,\n }\n\n # Try to parse YAML frontmatter from multiple formats:\n # 1. Standard: --- at start of file\n # 2. Code block with ---: ```yaml\\n---\\n...\\n---\\n```\n # 3. Code block without ---: ```yaml\\n...\\n```\n frontmatter = None\n frontmatter_end_pos = 0\n\n # Format 1: Standard frontmatter at start of file\n frontmatter_match = re.match(r\"^---\\s*\\n(.*?)\\n---\\s*\\n\", content, re.DOTALL)\n if frontmatter_match:\n frontmatter = frontmatter_match.group(1)\n frontmatter_end_pos = frontmatter_match.end()\n else:\n # Format 2: YAML code block with --- markers inside\n # Matches: ```yaml\\n---\\nkey: value\\n---\\n```\n codeblock_with_markers = re.search(\n r\"```ya?ml\\s*\\n---\\s*\\n(.*?)\\n---\\s*\\n```\",\n content,\n re.DOTALL | re.IGNORECASE,\n )\n if codeblock_with_markers:\n frontmatter = codeblock_with_markers.group(1)\n frontmatter_end_pos = codeblock_with_markers.end()\n else:\n # Format 3: YAML code block without --- markers\n # Matches: ```yaml\\nkey: value\\n```\n codeblock_no_markers = re.search(\n r\"```ya?ml\\s*\\n(.*?)\\n```\",\n content,\n re.DOTALL | re.IGNORECASE,\n )\n if codeblock_no_markers:\n frontmatter = codeblock_no_markers.group(1)\n frontmatter_end_pos = codeblock_no_markers.end()\n\n if frontmatter:\n # Parse simple YAML key: value pairs\n for line in frontmatter.split(\"\\n\"):\n if \":\" in line:\n key, value = line.split(\":\", 1)\n key = key.strip().lower()\n value = value.strip().strip('\"').strip(\"'\")\n if key == \"name\":\n result[\"name\"] = value\n elif key == \"description\":\n result[\"description\"] = value\n elif key == \"version\":\n result[\"version\"] = value\n elif key == \"tags\":\n # Handle comma-separated or YAML list\n if value.startswith(\"[\"):\n value = value.strip(\"[]\")\n result[\"tags\"] = [\n t.strip().strip('\"').strip(\"'\")\n for t in value.split(\",\")\n if t.strip()\n ]\n\n # Remove frontmatter from content for further parsing\n content = content[frontmatter_end_pos:]\n\n # Extract name from first H1 heading if not in frontmatter\n if not result[\"name\"]:\n h1_match = re.search(r\"^#\\s+(.+)$\", content, re.MULTILINE)\n if h1_match:\n result[\"name\"] = h1_match.group(1).strip()\n\n # Extract description from first paragraph if not in frontmatter\n if not result[\"description\"]:\n # Skip headings and find first non-empty paragraph\n lines = content.split(\"\\n\")\n paragraph_lines = []\n in_paragraph = False\n\n for line in lines:\n stripped = line.strip()\n # Skip headings and empty lines at start\n if stripped.startswith(\"#\"):\n if in_paragraph:\n break\n continue\n if not stripped:\n if in_paragraph:\n break\n continue\n # Skip code blocks\n if stripped.startswith(\"```\"):\n if in_paragraph:\n break\n continue\n\n in_paragraph = True\n paragraph_lines.append(stripped)\n\n if paragraph_lines:\n result[\"description\"] = \" \".join(paragraph_lines)[:500]\n\n # Convert name to slug format if found\n if result[\"name\"]:\n # Convert \"My Skill Name\" to \"my-skill-name\"\n name_slug = result[\"name\"].lower()\n name_slug = re.sub(r\"[^a-z0-9]+\", \"-\", name_slug)\n name_slug = re.sub(r\"-+\", \"-\", name_slug)\n name_slug = name_slug.strip(\"-\")\n result[\"name_slug\"] = name_slug\n\n logger.info(\n f\"Parsed SKILL.md from {user_url} (raw: {raw_url}): \"\n f\"name={result.get('name')}, has_description={bool(result.get('description'))}\"\n )\n return result\n\n except httpx.RequestError as e:\n raise SkillUrlValidationError(url, str(e)) from e\n\n\nasync def _check_skill_health(\n url: str,\n auth_scheme: str = \"none\",\n auth_credential_encrypted: str | None = None,\n auth_header_name: str | None = None,\n) -> dict[str, Any]:\n \"\"\"Check skill health by performing HEAD request to SKILL.md URL.\n\n Args:\n url: URL to SKILL.md file\n auth_scheme: Auth scheme for private repos\n auth_credential_encrypted: Encrypted credential\n auth_header_name: Custom header name\n\n Returns:\n Dict with health status\n \"\"\"\n import time\n\n start_time = time.perf_counter()\n\n # SSRF protection\n if not _is_safe_url(url):\n return {\n \"healthy\": False,\n \"status_code\": None,\n \"error\": \"URL failed SSRF validation\",\n \"response_time_ms\": 0,\n }\n\n # Build auth headers for private repos\n credential = None\n if auth_scheme not in (\"none\", \"global_credentials\") and auth_credential_encrypted:\n from ..utils.credential_encryption import decrypt_credential\n\n credential = decrypt_credential(auth_credential_encrypted)\n\n fetch_url, fetch_headers = _build_fetch_headers(\n url, auth_scheme, credential, auth_header_name\n )\n\n try:\n async with httpx.AsyncClient() as client:\n github_headers = await _github_auth.get_auth_headers(str(url))\n merged_headers = {**github_headers, **fetch_headers}\n response = await client.head(\n fetch_url, headers=merged_headers,\n follow_redirects=True, timeout=URL_VALIDATION_TIMEOUT,\n )\n\n # SSRF protection: validate final URL after redirects\n final_url = str(response.url)\n if final_url != str(url) and not _is_safe_url(final_url):\n logger.warning(\n f\"SSRF protection: Blocked redirect from {url} to unsafe URL {final_url}\"\n )\n response_time_ms = (time.perf_counter() - start_time) * 1000\n return {\n \"healthy\": False,\n \"status_code\": None,\n \"error\": f\"Redirect to unsafe URL blocked: {final_url}\",\n \"response_time_ms\": round(response_time_ms, 2),\n }\n\n response_time_ms = (time.perf_counter() - start_time) * 1000\n\n return {\n \"healthy\": response.status_code < 400,\n \"status_code\": response.status_code,\n \"error\": None if response.status_code < 400 else f\"HTTP {response.status_code}\",\n \"response_time_ms\": round(response_time_ms, 2),\n }\n\n except httpx.RequestError as e:\n # Log detailed exception on the server, but return a generic message to the client\n logger.error(\"Error while checking skill health for URL %s: %s\", url, e)\n response_time_ms = (time.perf_counter() - start_time) * 1000\n return {\n \"healthy\": False,\n \"status_code\": None,\n \"error\": \"Unexpected error during health check\",\n \"response_time_ms\": round(response_time_ms, 2),\n }\n\n\nasync def _compute_content_integrity(\n skill_md_url: str,\n resource_manifest: \"SkillResourceManifest | None\",\n auth_scheme: str = \"none\",\n auth_credential: str | None = None,\n auth_header_name: str | None = None,\n) -> ContentIntegrity | None:\n \"\"\"Compute SHA-256 hashes for SKILL.md and all companion resources.\n\n Returns a ContentIntegrity record with per-file hashes and a composite\n hash, or None if the SKILL.md cannot be fetched.\n \"\"\"\n file_hashes: list[FileHash] = []\n\n async def _hash_url(\n client: httpx.AsyncClient,\n url: str,\n rel_path: str,\n ) -> FileHash | None:\n fetch_url, fetch_headers = _build_fetch_headers(\n url, auth_scheme, auth_credential, auth_header_name,\n )\n try:\n resp = await client.get(\n fetch_url, headers=fetch_headers,\n follow_redirects=True, timeout=URL_VALIDATION_TIMEOUT,\n )\n if resp.status_code >= 400:\n logger.warning(\"Integrity fetch failed for %s: HTTP %s\", rel_path, resp.status_code)\n return None\n digest = hashlib.sha256(resp.content).hexdigest()\n return FileHash(path=rel_path, sha256=digest, size_bytes=len(resp.content))\n except httpx.RequestError as e:\n logger.warning(\"Integrity fetch error for %s: %s\", rel_path, e)\n return None\n\n async with httpx.AsyncClient() as client:\n skill_md_hash = await _hash_url(client, skill_md_url, \"SKILL.md\")\n if not skill_md_hash:\n return None\n file_hashes.append(skill_md_hash)\n\n if resource_manifest:\n from ..utils.url_utils import derive_resource_url\n\n all_resources = (\n resource_manifest.references\n + resource_manifest.scripts\n + resource_manifest.agents\n + resource_manifest.assets\n )\n for res in all_resources:\n res_url = derive_resource_url(skill_md_url, res.path)\n fh = await _hash_url(client, res_url, res.path)\n if fh:\n file_hashes.append(fh)\n\n sorted_entries = sorted(file_hashes, key=lambda h: h.path)\n composite_input = \"\".join(f\"{h.path}:{h.sha256}\" for h in sorted_entries)\n composite_hash = hashlib.sha256(composite_input.encode()).hexdigest()\n\n return ContentIntegrity(\n composite_hash=composite_hash,\n file_hashes=file_hashes,\n computed_at=datetime.now(UTC),\n )\n\n\ndef _decrypt_skill_auth(\n skill: SkillCard,\n) -> tuple[str, str | None, str | None]:\n \"\"\"Extract and decrypt authentication details from a skill.\n\n Returns (auth_scheme, plaintext_credential_or_none, auth_header_name).\n \"\"\"\n auth_scheme = getattr(skill, \"auth_scheme\", \"none\")\n encrypted_cred = getattr(skill, \"auth_credential_encrypted\", None)\n credential = None\n if auth_scheme not in (\"none\", \"global_credentials\") and encrypted_cred:\n from ..utils.credential_encryption import decrypt_credential\n\n credential = decrypt_credential(encrypted_cred)\n return auth_scheme, credential, getattr(skill, \"auth_header_name\", None)\n\n\nasync def _fetch_authenticated_content(\n url: str,\n skill: SkillCard,\n *,\n max_size: int | None = None,\n timeout: float = 30.0,\n) -> \"httpx.Response\":\n \"\"\"Fetch content from a URL using the skill's encrypted credentials.\n\n Handles SSRF validation, credential decryption, header building,\n and redirect safety checks.\n\n Raises:\n SkillContentSSRFError: URL or redirect target fails SSRF check.\n SkillContentFetchError: Upstream returned an HTTP error or was unreachable.\n SkillContentTooLargeError: Response body exceeds max_size.\n \"\"\"\n from ..exceptions import (\n SkillContentFetchError,\n SkillContentSSRFError,\n SkillContentTooLargeError,\n )\n\n if not _is_safe_url(url):\n raise SkillContentSSRFError(url)\n\n auth_scheme, credential, auth_header_name = _decrypt_skill_auth(skill)\n fetch_url, fetch_headers = _build_fetch_headers(\n url, auth_scheme, credential, auth_header_name,\n )\n\n if auth_scheme == \"none\":\n merged_headers = fetch_headers\n elif auth_scheme == \"global_credentials\":\n merged_headers = await _github_auth.get_auth_headers(fetch_url)\n else:\n github_headers = await _github_auth.get_auth_headers(fetch_url)\n merged_headers = {**github_headers, **fetch_headers}\n\n try:\n async with httpx.AsyncClient() as client:\n response = await client.get(\n fetch_url,\n headers=merged_headers,\n follow_redirects=True,\n timeout=timeout,\n )\n\n final_url = str(response.url)\n if final_url != fetch_url and not _is_safe_url(final_url):\n raise SkillContentSSRFError(final_url)\n\n if response.status_code >= 400:\n raise SkillContentFetchError(\n url, f\"HTTP {response.status_code}\",\n )\n\n if max_size and len(response.content) > max_size:\n raise SkillContentTooLargeError(max_size)\n\n return response\n except httpx.RequestError as e:\n logger.error(\"Failed to fetch from %s: %s\", url, e)\n raise SkillContentFetchError(url, str(e))\n\n\nasync def _check_drift_inline(\n service: \"SkillService\",\n skill_path: str,\n skill: SkillCard,\n file_path: str,\n content_bytes: bytes,\n) -> None:\n \"\"\"Compare fetched content against the stored integrity baseline.\n\n Runs as a fire-and-forget background task so it never blocks the\n content response. Updates the DB only when a change is detected\n (or when a previously-drifted file returns to its baseline).\n \"\"\"\n integrity = skill.content_integrity\n if not integrity or not integrity.file_hashes:\n return\n\n baseline = {fh.path: fh.sha256 for fh in integrity.file_hashes}\n expected = baseline.get(file_path)\n if expected is None:\n return\n\n actual = hashlib.sha256(content_bytes).hexdigest()\n file_drifted = actual != expected\n\n previously_drifted = file_path in (integrity.drifted_files or [])\n now = datetime.now(UTC).isoformat()\n\n try:\n if file_drifted == previously_drifted:\n await service.update_skill(\n skill_path,\n {\"content_integrity.last_drift_check\": now},\n )\n return\n\n current_drifted = list(integrity.drifted_files or [])\n if file_drifted and file_path not in current_drifted:\n current_drifted.append(file_path)\n elif not file_drifted and file_path in current_drifted:\n current_drifted.remove(file_path)\n\n current_tags = list(skill.tags or [])\n drift_tag = \"content-drifted\"\n if current_drifted and drift_tag not in current_tags:\n current_tags.append(drift_tag)\n elif not current_drifted and drift_tag in current_tags:\n current_tags.remove(drift_tag)\n\n combined_updates: dict[str, Any] = {\n \"content_integrity.drift_detected\": bool(current_drifted),\n \"content_integrity.last_drift_check\": now,\n \"content_integrity.drifted_files\": current_drifted,\n \"tags\": current_tags,\n }\n await service.update_skill(skill_path, combined_updates)\n\n if current_drifted:\n await service.toggle_skill(skill_path, enabled=False)\n logger.warning(\n \"Drift detected for %s in skill %s, skill disabled\",\n file_path, skill_path,\n )\n else:\n await service.toggle_skill(skill_path, enabled=True)\n logger.info(\"Drift cleared for skill %s, skill re-enabled\", skill_path)\n except Exception:\n logger.debug(\"Failed to persist drift state for %s\", skill_path, exc_info=True)\n\n\ndef _build_skill_card(\n request: SkillRegistrationRequest,\n path: str,\n owner: str | None,\n content_version: str | None,\n content_updated_at: datetime | None,\n skill_md_raw_url: str | None = None,\n resource_manifest: \"SkillResourceManifest | None\" = None,\n content_integrity: ContentIntegrity | None = None,\n) -> SkillCard:\n \"\"\"Build SkillCard from registration request.\n\n Args:\n request: Registration request\n path: Skill path\n owner: Owner username/email\n content_version: Content hash\n content_updated_at: Content update timestamp\n skill_md_raw_url: Raw URL for fetching SKILL.md content\n resource_manifest: Discovered companion resource files\n\n Returns:\n SkillCard instance\n \"\"\"\n # Convert metadata dict to SkillMetadata if provided\n # Use explicit version field if provided, otherwise fall back to metadata.version\n version = request.version\n if not version and request.metadata:\n version = request.metadata.get(\"version\")\n\n metadata = None\n if request.metadata or version:\n metadata = SkillMetadata(\n author=request.metadata.get(\"author\") if request.metadata else None,\n version=version,\n extra={k: v for k, v in request.metadata.items() if k not in (\"author\", \"version\")}\n if request.metadata\n else {},\n )\n\n # Encrypt credential if provided\n auth_credential_encrypted = None\n credential_updated_at = None\n if (\n getattr(request, \"auth_credential\", None)\n and getattr(request, \"auth_scheme\", \"none\") not in (\"none\", \"global_credentials\")\n ):\n from ..utils.credential_encryption import encrypt_credential\n\n auth_credential_encrypted = encrypt_credential(request.auth_credential)\n credential_updated_at = datetime.now(UTC)\n\n return SkillCard(\n path=path,\n name=request.name,\n description=request.description,\n skill_md_url=request.skill_md_url,\n skill_md_raw_url=skill_md_raw_url,\n repository_url=request.repository_url,\n license=request.license,\n compatibility=request.compatibility,\n requirements=request.requirements,\n target_agents=request.target_agents,\n metadata=metadata,\n allowed_tools=request.allowed_tools,\n tags=request.tags,\n visibility=request.visibility,\n allowed_groups=request.allowed_groups,\n owner=owner,\n is_enabled=True,\n status=request.status,\n auth_scheme=getattr(request, \"auth_scheme\", \"none\"),\n auth_credential_encrypted=auth_credential_encrypted,\n auth_header_name=getattr(request, \"auth_header_name\", None),\n credential_updated_at=credential_updated_at,\n resource_manifest=resource_manifest,\n content_version=content_version,\n content_updated_at=content_updated_at,\n content_integrity=content_integrity,\n created_at=datetime.now(UTC),\n updated_at=datetime.now(UTC),\n )\n\n\nclass SkillService:\n \"\"\"Service for skill CRUD operations.\n\n Simplified design with no in-memory state duplication.\n Database is the source of truth.\n \"\"\"\n\n def __init__(self):\n self._repo: SkillRepositoryBase | None = None\n self._search_repo: SearchRepositoryBase | None = None\n\n def _get_repo(self) -> SkillRepositoryBase:\n \"\"\"Lazy initialization of repository.\"\"\"\n if self._repo is None:\n self._repo = get_skill_repository()\n return self._repo\n\n def _get_search_repo(self) -> SearchRepositoryBase:\n \"\"\"Lazy initialization of search repository.\"\"\"\n if self._search_repo is None:\n self._search_repo = get_search_repository()\n return self._search_repo\n\n async def register_skill(\n self,\n request: SkillRegistrationRequest,\n owner: str | None = None,\n validate_url: bool = True,\n ) -> SkillCard:\n \"\"\"Register a new skill.\n\n Args:\n request: Skill registration request\n owner: Owner username/email for access control\n validate_url: Whether to validate SKILL.md URL\n\n Returns:\n Created SkillCard\n\n Raises:\n SkillUrlValidationError: If URL validation fails\n SkillAlreadyExistsError: If skill name exists\n \"\"\"\n # Generate path\n path = normalize_skill_path(request.name)\n\n # Translate URL to get the raw URL for content fetching\n _, raw_url = translate_skill_url(str(request.skill_md_url))\n\n # Validate URL and get content hash (validate the raw URL)\n content_version = None\n content_updated_at = None\n\n if validate_url:\n validation = await _validate_skill_md_url(\n raw_url,\n auth_scheme=getattr(request, \"auth_scheme\", \"none\"),\n auth_credential=getattr(request, \"auth_credential\", None),\n auth_header_name=getattr(request, \"auth_header_name\", None),\n )\n content_version = validation[\"content_version\"]\n content_updated_at = validation[\"content_updated_at\"]\n\n # Discover companion resource files (non-fatal)\n resource_manifest = None\n try:\n resource_manifest = await _discover_skill_resources(\n raw_url,\n auth_scheme=getattr(request, \"auth_scheme\", \"none\"),\n auth_credential=getattr(request, \"auth_credential\", None),\n auth_header_name=getattr(request, \"auth_header_name\", None),\n )\n except Exception as e:\n logger.warning(\"Resource discovery failed for %s: %s\", request.name, e)\n\n # Compute content integrity (SKILL.md + all resources)\n content_integrity = None\n try:\n content_integrity = await _compute_content_integrity(\n raw_url,\n resource_manifest,\n auth_scheme=getattr(request, \"auth_scheme\", \"none\"),\n auth_credential=getattr(request, \"auth_credential\", None),\n auth_header_name=getattr(request, \"auth_header_name\", None),\n )\n except Exception as e:\n logger.warning(\"Content integrity computation failed for %s: %s\", request.name, e)\n\n # Build SkillCard\n skill = _build_skill_card(\n request=request,\n path=path,\n owner=owner,\n content_version=content_version,\n content_updated_at=content_updated_at,\n skill_md_raw_url=raw_url,\n resource_manifest=resource_manifest,\n content_integrity=content_integrity,\n )\n\n # Save to repository\n repo = self._get_repo()\n created_skill = await repo.create(skill)\n\n # Index for search\n try:\n search_repo = self._get_search_repo()\n await search_repo.index_skill(\n path=path,\n skill=created_skill,\n is_enabled=True,\n )\n except Exception as e:\n logger.warning(f\"Failed to index skill for search: {e}\")\n\n logger.info(f\"Registered skill: {path}\")\n return created_skill\n\n async def get_skill(\n self,\n path: str,\n ) -> SkillCard | None:\n \"\"\"Get a skill by path.\"\"\"\n normalized = normalize_skill_path(path)\n repo = self._get_repo()\n return await repo.get(normalized)\n\n async def list_skills(\n self,\n include_disabled: bool = False,\n tag: str | None = None,\n visibility: str | None = None,\n registry_name: str | None = None,\n ) -> list[SkillInfo]:\n \"\"\"List skills with optional filtering.\n\n Uses database-level filtering for performance.\n\n Args:\n include_disabled: Whether to include disabled skills\n tag: Filter by tag\n visibility: Filter by visibility\n registry_name: Filter by registry\n\n Returns:\n List of SkillInfo summaries\n \"\"\"\n repo = self._get_repo()\n skills = await repo.list_filtered(\n include_disabled=include_disabled,\n tag=tag,\n visibility=visibility,\n registry_name=registry_name,\n )\n\n return [\n SkillInfo(\n id=s.id,\n path=s.path,\n name=s.name,\n description=s.description,\n skill_md_url=str(s.skill_md_url),\n skill_md_raw_url=str(s.skill_md_raw_url) if s.skill_md_raw_url else None,\n repository_url=s.repository_url,\n tags=s.tags,\n author=s.metadata.author if s.metadata else None,\n version=s.metadata.version if s.metadata else None,\n metadata=s.metadata,\n compatibility=s.compatibility,\n target_agents=s.target_agents,\n is_enabled=s.is_enabled,\n visibility=s.visibility,\n allowed_groups=s.allowed_groups,\n registry_name=s.registry_name,\n owner=s.owner,\n auth_scheme=s.auth_scheme,\n auth_header_name=s.auth_header_name,\n num_stars=s.num_stars,\n health_status=s.health_status,\n last_checked_time=s.last_checked_time,\n status=s.status,\n )\n for s in skills\n ]\n\n async def list_skills_for_user(\n self,\n user_context: dict[str, Any] | None,\n include_disabled: bool = False,\n tag: str | None = None,\n ) -> list[SkillInfo]:\n \"\"\"List skills filtered by user's visibility access.\n\n Args:\n user_context: User context with groups and username\n include_disabled: Whether to include disabled skills\n tag: Filter by tag\n\n Returns:\n List of SkillInfo visible to user\n \"\"\"\n all_skills = await self.list_skills(\n include_disabled=include_disabled,\n tag=tag,\n )\n\n if not user_context:\n # Anonymous - only public\n return [s for s in all_skills if s.visibility == VisibilityEnum.PUBLIC]\n\n if user_context.get(\"is_admin\"):\n return all_skills\n\n user_groups = set(user_context.get(\"groups\", []))\n username = user_context.get(\"username\", \"\")\n\n filtered = []\n for skill in all_skills:\n if skill.visibility == VisibilityEnum.PUBLIC:\n filtered.append(skill)\n elif skill.visibility == VisibilityEnum.PRIVATE:\n # Check owner directly from SkillInfo (no N+1 query)\n if skill.owner == username:\n filtered.append(skill)\n elif skill.visibility == VisibilityEnum.GROUP:\n if user_groups & set(skill.allowed_groups):\n filtered.append(skill)\n\n return filtered\n\n async def get_skills_paginated(\n self,\n skip: int = 0,\n limit: int = 100,\n ) -> tuple[list[SkillCard], int]:\n \"\"\"Get a page of skills with total count.\n\n Used for unrestricted users (admins) where DB-level pagination\n is correct because no skills are filtered out by access control.\n\n Note: list_paginated and count are separate DB calls, so total_count\n may be slightly inconsistent if skills are added/removed between calls.\n This is standard for offset-based pagination.\n\n Args:\n skip: Number of skills to skip.\n limit: Maximum number of skills to return.\n\n Returns:\n Tuple of (page of skills, total count of all skills).\n \"\"\"\n repo = self._get_repo()\n skills = await repo.list_paginated(skip=skip, limit=limit)\n total = await repo.count()\n return skills, total\n\n async def update_skill(\n self,\n path: str,\n updates: dict[str, Any],\n ) -> SkillCard | None:\n \"\"\"Update a skill.\"\"\"\n normalized = normalize_skill_path(path)\n repo = self._get_repo()\n updated = await repo.update(normalized, updates)\n\n if updated:\n # Update search index\n try:\n search_repo = self._get_search_repo()\n await search_repo.index_skill(\n path=normalized,\n skill=updated,\n is_enabled=updated.is_enabled,\n )\n except Exception as e:\n logger.warning(f\"Failed to update skill in search index: {e}\")\n logger.info(f\"Updated skill: {normalized}\")\n\n return updated\n\n async def delete_skill(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a skill.\"\"\"\n normalized = normalize_skill_path(path)\n repo = self._get_repo()\n success = await repo.delete(normalized)\n\n if success:\n # Remove from search index\n try:\n search_repo = self._get_search_repo()\n await search_repo.remove_entity(normalized)\n except Exception as e:\n logger.warning(f\"Failed to remove skill from search index: {e}\")\n logger.info(f\"Deleted skill: {normalized}\")\n\n return success\n\n async def toggle_skill(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Toggle skill enabled state.\"\"\"\n normalized = normalize_skill_path(path)\n repo = self._get_repo()\n success = await repo.set_state(normalized, enabled)\n\n if success:\n # Update search index\n skill = await repo.get(normalized)\n if skill:\n try:\n search_repo = self._get_search_repo()\n await search_repo.index_skill(\n path=normalized,\n skill=skill,\n is_enabled=enabled,\n )\n except Exception as e:\n logger.warning(f\"Failed to update skill in search index: {e}\")\n logger.info(f\"Toggled skill {normalized} to enabled={enabled}\")\n\n return success\n\n async def parse_skill_md(\n self,\n url: str,\n auth_scheme: str = \"none\",\n auth_credential: str | None = None,\n auth_header_name: str | None = None,\n ) -> dict[str, Any]:\n \"\"\"Parse SKILL.md content and extract metadata.\n\n Args:\n url: URL to SKILL.md file\n auth_scheme: Auth scheme (none, global_credentials, bearer, api_key)\n auth_credential: Plaintext credential for bearer/api_key\n auth_header_name: Custom header name for api_key scheme\n\n Returns:\n Dict with parsed metadata (name, description, version, tags)\n \"\"\"\n return await _parse_skill_md_content(\n url,\n auth_scheme=auth_scheme,\n auth_credential=auth_credential,\n auth_header_name=auth_header_name,\n )\n\n async def check_skill_health(\n self,\n path: str,\n ) -> dict[str, Any]:\n \"\"\"Check skill health by performing HEAD request to SKILL.md URL.\n\n Args:\n path: Skill path\n\n Returns:\n Dict with health status\n \"\"\"\n from datetime import UTC, datetime\n\n normalized = normalize_skill_path(path)\n repo = self._get_repo()\n skill = await repo.get(normalized)\n\n if not skill:\n return {\n \"healthy\": False,\n \"status_code\": None,\n \"error\": \"Skill not found\",\n \"response_time_ms\": 0,\n }\n\n # Use raw URL for health check (more reliable, returns actual content)\n url = skill.skill_md_raw_url or skill.skill_md_url\n result = await _check_skill_health(\n str(url),\n auth_scheme=getattr(skill, \"auth_scheme\", \"none\"),\n auth_credential_encrypted=getattr(skill, \"auth_credential_encrypted\", None),\n auth_header_name=getattr(skill, \"auth_header_name\", None),\n )\n\n # Persist health status to database\n health_status = \"healthy\" if result.get(\"healthy\") else \"unhealthy\"\n checked_time = datetime.now(UTC)\n\n await repo.update(\n normalized,\n {\n \"health_status\": health_status,\n \"last_checked_time\": checked_time.isoformat(),\n },\n )\n\n logger.info(f\"Updated health status for skill {normalized}: {health_status}\")\n\n return result\n\n async def update_rating(\n self,\n path: str,\n username: str,\n rating: int,\n ) -> float:\n \"\"\"Update rating for a skill.\n\n Args:\n path: Skill path\n username: The user who submitted rating\n rating: integer between 1-5\n\n Returns:\n Updated average rating\n\n Raises:\n ValueError: If skill not found or invalid rating\n \"\"\"\n from . import rating_service\n\n normalized = normalize_skill_path(path)\n repo = self._get_repo()\n\n # Get existing skill\n existing_skill = await repo.get(normalized)\n if not existing_skill:\n logger.error(f\"Cannot update skill at path '{normalized}': not found\")\n raise ValueError(f\"Skill not found at path: {normalized}\")\n\n # Validate rating using shared service\n rating_service.validate_rating(rating)\n\n # Convert to dict for modification - use mode=\"json\" to serialize HttpUrl to strings\n skill_dict = existing_skill.model_dump(mode=\"json\")\n\n # Ensure rating_details is a list\n if \"rating_details\" not in skill_dict or skill_dict[\"rating_details\"] is None:\n skill_dict[\"rating_details\"] = []\n\n # Update rating details using shared service\n updated_details, is_new_rating = rating_service.update_rating_details(\n skill_dict[\"rating_details\"], username, rating\n )\n skill_dict[\"rating_details\"] = updated_details\n\n # Calculate average rating using shared service\n skill_dict[\"num_stars\"] = rating_service.calculate_average_rating(\n skill_dict[\"rating_details\"]\n )\n\n # Save to repository\n await repo.update(normalized, skill_dict)\n\n logger.info(\n f\"Updated rating for skill {normalized}: user {username} rated {rating}, \"\n f\"new average: {skill_dict['num_stars']:.2f}\"\n )\n\n return skill_dict[\"num_stars\"]\n\n async def get_rating(\n self,\n path: str,\n ) -> dict[str, Any]:\n \"\"\"Get rating information for a skill.\n\n Args:\n path: Skill path\n\n Returns:\n Dict with num_stars and rating_details\n\n Raises:\n ValueError: If skill not found\n \"\"\"\n normalized = normalize_skill_path(path)\n repo = self._get_repo()\n\n skill = await repo.get(normalized)\n if not skill:\n raise ValueError(f\"Skill not found at path: {normalized}\")\n\n return {\n \"num_stars\": skill.num_stars,\n \"rating_details\": skill.rating_details,\n }\n\n\n# Singleton instance\n_skill_service: SkillService | None = None\n\n\ndef get_skill_service() -> SkillService:\n \"\"\"Get or create skill service singleton.\"\"\"\n global _skill_service\n if _skill_service is None:\n _skill_service = SkillService()\n return _skill_service\n" }, { "path": "registry/services/tool_catalog_service.py", "content": "\"\"\"\nService layer for the global tool catalog.\n\nAggregates tools from all enabled, active MCP servers to provide\na browsable catalog for building virtual server configurations.\n\"\"\"\n\nimport logging\nfrom typing import (\n Any,\n Optional,\n)\n\nfrom ..repositories.factory import get_server_repository\nfrom ..repositories.interfaces import ServerRepositoryBase\nfrom ..schemas.virtual_server_models import ToolCatalogEntry\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Singleton instance\n_tool_catalog_service: Optional[\"ToolCatalogService\"] = None\n\n\nclass ToolCatalogService:\n \"\"\"Service for aggregating tools across all registered backend servers.\"\"\"\n\n def __init__(self):\n self._server_repo: ServerRepositoryBase = get_server_repository()\n\n async def get_tool_catalog(\n self,\n server_path_filter: str | None = None,\n user_scopes: list[str] | None = None,\n ) -> list[ToolCatalogEntry]:\n \"\"\"Get all tools available across enabled servers.\n\n Reads tool_list from each server's MongoDB document and returns\n structured catalog entries, filtered by the user's scopes.\n\n Args:\n server_path_filter: Optional filter to only return tools from\n a specific server path\n user_scopes: User's scopes for access filtering. If None,\n no scope filtering is applied (backwards-compatible).\n\n Returns:\n List of ToolCatalogEntry objects the user has access to\n \"\"\"\n catalog: list[ToolCatalogEntry] = []\n\n # Get all servers\n all_servers = await self._server_repo.list_all()\n\n # Pre-compute user scope set for efficient lookup\n user_scope_set: set[str] | None = None\n if user_scopes is not None:\n user_scope_set = set(user_scopes)\n\n for path, server_info in all_servers.items():\n # Skip version documents (contain \":\" in path)\n if \":\" in path:\n continue\n\n # Apply server path filter if specified (normalize slashes for comparison)\n if server_path_filter:\n normalized_filter = server_path_filter.strip(\"/\")\n normalized_path = path.strip(\"/\")\n if normalized_path != normalized_filter:\n continue\n\n # Check if server is enabled\n is_enabled = await self._server_repo.get_state(path)\n if not is_enabled:\n continue\n\n # Filter by user's accessible servers if scopes are provided\n if user_scope_set is not None:\n server_required_scopes = server_info.get(\"required_scopes\", [])\n if server_required_scopes and not all(\n s in user_scope_set for s in server_required_scopes\n ):\n logger.debug(f\"Filtering out server {path}: user lacks required scopes\")\n continue\n\n server_name = server_info.get(\"server_name\", path)\n tool_list = server_info.get(\"tool_list\", [])\n\n # Get available versions from other_version_ids\n available_versions = self._get_available_versions(server_info)\n\n for tool in tool_list:\n tool_name = tool.get(\"name\", \"\")\n if not tool_name:\n continue\n\n catalog.append(\n ToolCatalogEntry(\n tool_name=tool_name,\n server_path=path,\n server_name=server_name,\n description=tool.get(\"description\", \"\"),\n input_schema=tool.get(\"inputSchema\", {}),\n available_versions=available_versions,\n )\n )\n\n logger.debug(\n f\"Tool catalog: {len(catalog)} tools from \"\n f\"{len(set(e.server_path for e in catalog))} servers\"\n )\n return catalog\n\n def _get_available_versions(\n self,\n server_info: dict[str, Any],\n ) -> list[str]:\n \"\"\"Extract available versions for a server.\n\n Args:\n server_info: Server document from repository\n\n Returns:\n List of version strings\n \"\"\"\n versions = []\n\n # Current/active version\n current_version = server_info.get(\"version\")\n if current_version:\n versions.append(current_version)\n\n # Other versions from linked version documents\n other_version_ids = server_info.get(\"other_version_ids\", [])\n for version_id in other_version_ids:\n # Version IDs are like \"/context7:v1.5.0\"\n if \":\" in version_id:\n version_str = version_id.split(\":\")[-1]\n if version_str and version_str not in versions:\n versions.append(version_str)\n\n return versions\n\n\ndef get_tool_catalog_service() -> ToolCatalogService:\n \"\"\"Get tool catalog service singleton.\"\"\"\n global _tool_catalog_service\n\n if _tool_catalog_service is not None:\n return _tool_catalog_service\n\n _tool_catalog_service = ToolCatalogService()\n return _tool_catalog_service\n" }, { "path": "registry/services/tool_validation_service.py", "content": "\"\"\"\nService for validating tool availability for skills.\n\nLinks allowed_tools to MCP servers in the registry.\n\"\"\"\n\nimport logging\nimport time\n\nfrom ..repositories.factory import get_server_repository\nfrom ..repositories.interfaces import ServerRepositoryBase\nfrom ..schemas.skill_models import (\n SkillCard,\n ToolReference,\n ToolValidationResult,\n)\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\nclass ToolValidationService:\n \"\"\"Validate tool availability for skill execution.\"\"\"\n\n def __init__(self):\n self._server_repo: ServerRepositoryBase | None = None\n\n def _get_server_repo(self) -> ServerRepositoryBase:\n \"\"\"Lazy initialization of server repository.\"\"\"\n if self._server_repo is None:\n self._server_repo = get_server_repository()\n return self._server_repo\n\n async def validate_tools_available(\n self,\n skill: SkillCard,\n enabled_only: bool = True,\n ) -> ToolValidationResult:\n \"\"\"Check if required tools are available.\n\n Args:\n skill: SkillCard with allowed_tools\n enabled_only: Only check enabled servers\n\n Returns:\n ToolValidationResult with availability status\n \"\"\"\n start_time = time.perf_counter()\n skill_path = skill.path if skill.path else \"unknown\"\n required_tool_count = len(skill.allowed_tools) if skill.allowed_tools else 0\n\n logger.info(\n f\"Starting tool validation for skill '{skill_path}' \"\n f\"with {required_tool_count} required tools\"\n )\n\n if not skill.allowed_tools:\n elapsed_ms = (time.perf_counter() - start_time) * 1000\n logger.info(\n f\"Tool validation completed for skill '{skill_path}': \"\n f\"all_available=True, found=0, missing=0, duration={elapsed_ms:.2f}ms\"\n )\n return ToolValidationResult(\n all_available=True, missing_tools=[], available_tools=[], mcp_servers_required=[]\n )\n\n # Get all servers\n server_repo = self._get_server_repo()\n servers_dict = await server_repo.list_all()\n\n logger.debug(f\"Retrieved {len(servers_dict)} servers from repository\")\n\n # Build index of available tools\n available_tools: set[str] = set()\n server_tool_map: dict = {}\n\n for server_path, server_info in servers_dict.items():\n # Check if server is enabled\n if enabled_only:\n is_enabled = await server_repo.get_state(server_path)\n if not is_enabled:\n logger.debug(f\"Skipping disabled server: {server_path}\")\n continue\n\n tool_list = server_info.get(\"tool_list\", [])\n tool_names_in_server = []\n\n for tool in tool_list:\n tool_name = tool.get(\"name\", \"\")\n if tool_name:\n available_tools.add(tool_name)\n tool_names_in_server.append(tool_name)\n if tool_name not in server_tool_map:\n server_tool_map[tool_name] = []\n server_tool_map[tool_name].append(server_path)\n\n logger.debug(\n f\"Server '{server_path}' provides {len(tool_names_in_server)} tools: \"\n f\"{tool_names_in_server}\"\n )\n\n # Check each required tool\n missing: list[str] = []\n found: list[str] = []\n required_servers: set[str] = set()\n\n for tool_ref in skill.allowed_tools:\n tool_name = tool_ref.tool_name\n\n if tool_name in available_tools:\n found.append(tool_name)\n required_servers.update(server_tool_map.get(tool_name, []))\n logger.debug(f\"Tool '{tool_name}' is available\")\n else:\n missing.append(tool_name)\n logger.debug(f\"Tool '{tool_name}' is NOT available\")\n\n # Log warnings for missing tools\n if missing:\n logger.warning(f\"Skill '{skill_path}' has {len(missing)} missing tools: {missing}\")\n\n elapsed_ms = (time.perf_counter() - start_time) * 1000\n all_available = len(missing) == 0\n\n logger.info(\n f\"Tool validation completed for skill '{skill_path}': \"\n f\"all_available={all_available}, found={len(found)}, \"\n f\"missing={len(missing)}, duration={elapsed_ms:.2f}ms\"\n )\n\n return ToolValidationResult(\n all_available=all_available,\n missing_tools=missing,\n available_tools=found,\n mcp_servers_required=list(required_servers),\n )\n\n async def get_tools_with_servers(\n self,\n tool_refs: list[ToolReference],\n ) -> list[dict]:\n \"\"\"Get tool references with their providing servers.\n\n Args:\n tool_refs: List of ToolReference objects\n\n Returns:\n List of dicts with tool info and server paths\n \"\"\"\n start_time = time.perf_counter()\n tool_count = len(tool_refs)\n\n logger.info(f\"Looking up servers for {tool_count} tool references\")\n\n server_repo = self._get_server_repo()\n servers_dict = await server_repo.list_all()\n\n logger.debug(f\"Retrieved {len(servers_dict)} servers from repository\")\n\n result = []\n for tool_ref in tool_refs:\n tool_info = {\n \"tool_name\": tool_ref.tool_name,\n \"capabilities\": tool_ref.capabilities,\n \"servers\": [],\n }\n\n for server_path, server_info in servers_dict.items():\n is_enabled = await server_repo.get_state(server_path)\n tool_list = server_info.get(\"tool_list\", [])\n\n for tool in tool_list:\n if tool.get(\"name\") == tool_ref.tool_name:\n tool_info[\"servers\"].append(\n {\n \"path\": server_path,\n \"name\": server_info.get(\"server_name\", \"\"),\n \"is_enabled\": is_enabled,\n }\n )\n logger.debug(\n f\"Tool '{tool_ref.tool_name}' found on server \"\n f\"'{server_path}' (enabled={is_enabled})\"\n )\n break\n\n if not tool_info[\"servers\"]:\n logger.warning(f\"Tool '{tool_ref.tool_name}' not found on any server\")\n\n result.append(tool_info)\n\n elapsed_ms = (time.perf_counter() - start_time) * 1000\n tools_with_servers = sum(1 for t in result if t[\"servers\"])\n\n logger.info(\n f\"Server lookup completed: {tools_with_servers}/{tool_count} tools \"\n f\"have servers, duration={elapsed_ms:.2f}ms\"\n )\n\n return result\n\n\n# Singleton\n_tool_validation_service: ToolValidationService | None = None\n\n\ndef get_tool_validation_service() -> ToolValidationService:\n \"\"\"Get or create tool validation service singleton.\"\"\"\n global _tool_validation_service\n if _tool_validation_service is None:\n _tool_validation_service = ToolValidationService()\n return _tool_validation_service\n" }, { "path": "registry/services/transform_service.py", "content": "\"\"\"\nService for transforming internal server data to Anthropic API schema.\n\nThis bridges our internal data model with the external Anthropic API format.\n\"\"\"\n\nimport logging\nfrom typing import Any\n\nfrom ..constants import REGISTRY_CONSTANTS\nfrom ..schemas.anthropic_schema import (\n Package,\n PaginationMetadata,\n Repository,\n ServerDetail,\n ServerList,\n ServerResponse,\n)\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _create_transport_config(server_info: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Create transport configuration from internal server info.\n\n Args:\n server_info: Internal server data structure\n\n Returns:\n Transport configuration dict\n \"\"\"\n proxy_pass_url = server_info.get(\"proxy_pass_url\", \"\")\n\n return {\"type\": \"streamable-http\", \"url\": proxy_pass_url}\n\n\ndef _extract_repository_from_description(description: str) -> Repository | None:\n \"\"\"\n Extract repository info from description or tags if available.\n\n For now, returns None. Future: parse GitHub URLs from description.\n\n Args:\n description: Server description text\n\n Returns:\n Repository object or None\n \"\"\"\n # TODO: Implement GitHub URL extraction from description\n # For now, return None - this is optional per spec\n return None\n\n\ndef _determine_version(server_info: dict[str, Any]) -> str:\n \"\"\"\n Determine server version.\n\n Since we don't currently track versions, we use \"1.0.0\" as default.\n\n Args:\n server_info: Internal server data\n\n Returns:\n Version string\n \"\"\"\n # Check if we have version metadata\n if \"_meta\" in server_info and \"version\" in server_info[\"_meta\"]:\n return server_info[\"_meta\"][\"version\"]\n\n # Default version for all servers\n return \"1.0.0\"\n\n\ndef _create_server_name(server_info: dict[str, Any]) -> str:\n \"\"\"\n Create reverse-DNS style server name.\n\n Transforms our path-based naming (/example-server) to reverse-DNS format\n (io.mcpgateway/example-server).\n\n Args:\n server_info: Internal server data\n\n Returns:\n Reverse-DNS formatted server name\n \"\"\"\n path = server_info.get(\"path\", \"\")\n\n # Remove leading and trailing slashes from path\n clean_path = path.strip(\"/\")\n\n # Use our domain as prefix\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n return f\"{namespace}/{clean_path}\"\n\n\ndef transform_to_server_detail(server_info: dict[str, Any]) -> ServerDetail:\n \"\"\"\n Transform internal server info to Anthropic ServerDetail format.\n\n Maps from our internal schema to Anthropic schema.\n\n Args:\n server_info: Internal server data structure\n\n Returns:\n ServerDetail object\n \"\"\"\n # Create reverse-DNS name\n name = _create_server_name(server_info)\n\n # Get version\n version = _determine_version(server_info)\n\n # Create transport config\n transport = _create_transport_config(server_info)\n\n # Create package entry\n # Note: We use \"mcpb\" as registry type for our custom servers\n package = Package(\n registryType=\"mcpb\",\n identifier=name,\n version=version,\n transport=transport,\n runtimeHint=\"docker\",\n )\n\n # Try to extract repository info\n repository = _extract_repository_from_description(server_info.get(\"description\", \"\"))\n\n # Build metadata\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n meta = {\n f\"{namespace}/internal\": {\n \"path\": server_info.get(\"path\"),\n \"is_enabled\": server_info.get(\"is_enabled\", False),\n \"health_status\": server_info.get(\"health_status\", \"unknown\"),\n \"num_tools\": server_info.get(\"num_tools\", 0),\n \"tags\": server_info.get(\"tags\", []),\n \"license\": server_info.get(\"license\", \"N/A\"),\n }\n }\n\n # Create ServerDetail\n return ServerDetail(\n name=name,\n description=server_info.get(\"description\", \"\"),\n version=version,\n title=server_info.get(\"server_name\"),\n repository=repository,\n packages=[package],\n meta=meta,\n )\n\n\ndef transform_to_server_response(\n server_info: dict[str, Any],\n include_registry_meta: bool = True,\n) -> ServerResponse:\n \"\"\"\n Transform internal server info to Anthropic ServerResponse format.\n\n Args:\n server_info: Internal server data\n include_registry_meta: Whether to include registry metadata\n\n Returns:\n ServerResponse object\n \"\"\"\n server_detail = transform_to_server_detail(server_info)\n\n registry_meta = None\n if include_registry_meta:\n namespace = REGISTRY_CONSTANTS.ANTHROPIC_SERVER_NAMESPACE\n registry_meta = {\n f\"{namespace}/registry\": {\n \"last_checked\": server_info.get(\"last_checked_iso\"),\n \"health_status\": server_info.get(\"health_status\", \"unknown\"),\n }\n }\n\n return ServerResponse(server=server_detail, meta=registry_meta)\n\n\ndef transform_to_server_list(\n servers_data: list[dict[str, Any]],\n cursor: str | None = None,\n limit: int | None = None,\n) -> ServerList:\n \"\"\"\n Transform list of internal servers to Anthropic ServerList format.\n\n Implements cursor-based pagination.\n\n Args:\n servers_data: List of internal server data structures\n cursor: Current pagination cursor (server name to start after)\n limit: Maximum number of results to return\n\n Returns:\n ServerList object with pagination metadata\n \"\"\"\n # Default limit\n if limit is None or limit <= 0:\n limit = 100\n\n # Enforce maximum limit\n limit = min(limit, 1000)\n\n # Sort servers by name for consistent pagination\n sorted_servers = sorted(servers_data, key=lambda s: _create_server_name(s))\n\n # Apply cursor-based pagination\n start_index = 0\n if cursor:\n # Find the index of the server matching the cursor\n for idx, server in enumerate(sorted_servers):\n if _create_server_name(server) == cursor:\n start_index = idx + 1\n break\n\n # Slice the results\n end_index = start_index + limit\n page_servers = sorted_servers[start_index:end_index]\n\n # Transform to ServerResponse objects\n server_responses = [\n transform_to_server_response(server, include_registry_meta=True) for server in page_servers\n ]\n\n # Determine next cursor\n next_cursor = None\n if end_index < len(sorted_servers):\n # More results available\n next_cursor = _create_server_name(sorted_servers[end_index - 1])\n\n # Build pagination metadata\n metadata = PaginationMetadata(nextCursor=next_cursor, count=len(server_responses))\n\n return ServerList(servers=server_responses, metadata=metadata)\n" }, { "path": "registry/services/virtual_server_service.py", "content": "\"\"\"\nService layer for virtual MCP server management.\n\nHandles validation, CRUD operations, tool resolution, and nginx config\nregeneration for virtual servers that aggregate tools from multiple backends.\n\"\"\"\n\nimport asyncio\nimport logging\nimport re\nfrom datetime import UTC, datetime\nfrom typing import (\n Optional,\n)\n\nfrom ..exceptions import (\n VirtualServerNotFoundError,\n VirtualServerValidationError,\n)\nfrom ..repositories.factory import (\n get_search_repository,\n get_server_repository,\n get_virtual_server_repository,\n)\nfrom ..repositories.interfaces import (\n ServerRepositoryBase,\n VirtualServerRepositoryBase,\n)\nfrom ..schemas.virtual_server_models import (\n CreateVirtualServerRequest,\n ResolvedTool,\n ToolMapping,\n UpdateVirtualServerRequest,\n VirtualServerConfig,\n VirtualServerInfo,\n)\nfrom ..services.rating_service import (\n calculate_average_rating,\n update_rating_details,\n validate_rating,\n)\n\n# Configure logging\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\nlogger = logging.getLogger(__name__)\n\n\n# Singleton instance\n_virtual_server_service: Optional[\"VirtualServerService\"] = None\n\n# Lock to serialize nginx config regeneration across concurrent mutations\n_nginx_reload_lock = asyncio.Lock()\n\n\ndef _generate_path_from_name(\n name: str,\n) -> str:\n \"\"\"Generate a virtual server path from a name.\n\n Converts to lowercase, replaces spaces/special chars with hyphens,\n and prepends /virtual/.\n\n Args:\n name: Human-readable server name\n\n Returns:\n Path like /virtual/dev-essentials\n \"\"\"\n slug = re.sub(r\"[^a-z0-9]+\", \"-\", name.lower()).strip(\"-\")\n slug = re.sub(r\"-+\", \"-\", slug)\n if not slug:\n slug = \"virtual-server\"\n return f\"/virtual/{slug}\"\n\n\ndef _get_unique_backends(\n tool_mappings: list[ToolMapping],\n) -> list[str]:\n \"\"\"Extract unique backend server paths from tool mappings.\"\"\"\n return list({tm.backend_server_path for tm in tool_mappings})\n\n\ndef _get_effective_tool_name(\n mapping: ToolMapping,\n) -> str:\n \"\"\"Get the effective tool name (alias if set, otherwise original).\"\"\"\n return mapping.alias if mapping.alias else mapping.tool_name\n\n\nclass VirtualServerService:\n \"\"\"Service for managing virtual MCP server configurations.\"\"\"\n\n def __init__(self):\n self._repo: VirtualServerRepositoryBase = get_virtual_server_repository()\n self._server_repo: ServerRepositoryBase = get_server_repository()\n\n async def list_virtual_servers(self) -> list[VirtualServerInfo]:\n \"\"\"List all virtual servers with summary information.\n\n Returns:\n List of VirtualServerInfo summaries\n \"\"\"\n configs = await self._repo.list_all()\n return [self._config_to_info(c) for c in configs]\n\n async def get_virtual_server(\n self,\n path: str,\n ) -> VirtualServerConfig | None:\n \"\"\"Get a virtual server by path.\n\n Args:\n path: Virtual server path\n\n Returns:\n VirtualServerConfig if found, None otherwise\n \"\"\"\n return await self._repo.get(path)\n\n async def create_virtual_server(\n self,\n request: CreateVirtualServerRequest,\n created_by: str | None = None,\n ) -> VirtualServerConfig:\n \"\"\"Create a new virtual server.\n\n Validates all backend references and tool mappings before creation.\n\n Args:\n request: Creation request with server config\n created_by: Username of creator\n\n Returns:\n Created VirtualServerConfig\n\n Raises:\n VirtualServerValidationError: If validation fails\n VirtualServerAlreadyExistsError: If path already exists\n \"\"\"\n # Generate path from name if not provided\n path = request.path\n if not path:\n path = _generate_path_from_name(request.server_name)\n\n # Ensure path starts with /virtual/\n if not path.startswith(\"/virtual/\"):\n path = f\"/virtual/{path.strip('/')}\"\n\n # Validate tool mappings\n if request.tool_mappings:\n await self._validate_tool_mappings(request.tool_mappings)\n\n # Validate unique tool names/aliases\n self._validate_unique_tool_names(request.tool_mappings)\n\n now = datetime.now(UTC)\n config = VirtualServerConfig(\n path=path,\n server_name=request.server_name,\n description=request.description,\n tool_mappings=request.tool_mappings,\n required_scopes=request.required_scopes,\n tool_scope_overrides=request.tool_scope_overrides,\n tags=request.tags,\n supported_transports=request.supported_transports,\n is_enabled=False,\n created_by=created_by,\n created_at=now,\n updated_at=now,\n )\n\n result = await self._repo.create(config)\n logger.info(\n f\"Created virtual server '{config.server_name}' at {config.path} \"\n f\"with {len(config.tool_mappings)} tools\"\n )\n\n await self._trigger_nginx_reload()\n await self._index_for_search(result)\n return result\n\n async def update_virtual_server(\n self,\n path: str,\n request: UpdateVirtualServerRequest,\n ) -> VirtualServerConfig | None:\n \"\"\"Update an existing virtual server.\n\n Args:\n path: Virtual server path\n request: Update request with changed fields\n\n Returns:\n Updated VirtualServerConfig if found\n\n Raises:\n VirtualServerNotFoundError: If not found\n VirtualServerValidationError: If validation fails\n \"\"\"\n existing = await self._repo.get(path)\n if not existing:\n raise VirtualServerNotFoundError(path)\n\n updates = request.model_dump(exclude_unset=True)\n\n # Validate tool mappings if being updated\n if \"tool_mappings\" in updates and updates[\"tool_mappings\"]:\n tool_mappings = [ToolMapping(**tm) for tm in updates[\"tool_mappings\"]]\n await self._validate_tool_mappings(tool_mappings)\n self._validate_unique_tool_names(tool_mappings)\n\n result = await self._repo.update(path, updates)\n\n if result:\n await self._trigger_nginx_reload()\n await self._index_for_search(result)\n logger.info(f\"Updated virtual server: {path}\")\n\n return result\n\n async def delete_virtual_server(\n self,\n path: str,\n ) -> bool:\n \"\"\"Delete a virtual server.\n\n Args:\n path: Virtual server path\n\n Returns:\n True if deleted\n\n Raises:\n VirtualServerNotFoundError: If not found\n \"\"\"\n existing = await self._repo.get(path)\n if not existing:\n raise VirtualServerNotFoundError(path)\n\n success = await self._repo.delete(path)\n\n if success:\n await self._trigger_nginx_reload()\n await self._remove_from_search(path)\n logger.info(f\"Deleted virtual server: {path}\")\n return success\n\n async def toggle_virtual_server(\n self,\n path: str,\n enabled: bool,\n ) -> bool:\n \"\"\"Toggle virtual server enabled/disabled state.\n\n Args:\n path: Virtual server path\n enabled: New enabled state\n\n Returns:\n True if toggled successfully\n\n Raises:\n VirtualServerNotFoundError: If not found\n VirtualServerValidationError: If enabling with no tool mappings\n \"\"\"\n existing = await self._repo.get(path)\n if not existing:\n raise VirtualServerNotFoundError(path)\n\n # Validate before enabling\n if enabled and not existing.tool_mappings:\n raise VirtualServerValidationError(\"Cannot enable virtual server with no tool mappings\")\n\n if enabled:\n # Re-validate tool mappings before enabling\n await self._validate_tool_mappings(existing.tool_mappings)\n\n success = await self._repo.set_state(path, enabled)\n\n if success:\n await self._trigger_nginx_reload()\n # Re-index with new enabled state\n updated = await self._repo.get(path)\n if updated:\n await self._index_for_search(updated)\n logger.info(f\"Virtual server {path} {'enabled' if enabled else 'disabled'}\")\n\n return success\n\n async def resolve_tools(\n self,\n path: str,\n ) -> list[ResolvedTool]:\n \"\"\"Resolve all tools for a virtual server.\n\n Fetches tool metadata from backend servers and applies\n aliases, version pins, and scope overrides.\n\n Args:\n path: Virtual server path\n\n Returns:\n List of resolved tools with full metadata\n \"\"\"\n config = await self._repo.get(path)\n if not config:\n raise VirtualServerNotFoundError(path)\n\n return await self._resolve_tool_list(config)\n\n async def rate_virtual_server(\n self,\n path: str,\n username: str,\n rating: int,\n ) -> dict:\n \"\"\"Rate a virtual server.\n\n Args:\n path: Virtual server path\n username: Username submitting the rating\n rating: Rating value (1-5)\n\n Returns:\n Dict with average_rating and is_new_rating\n\n Raises:\n VirtualServerNotFoundError: If virtual server not found\n ValueError: If rating is invalid\n \"\"\"\n validate_rating(rating)\n\n config = await self._repo.get(path)\n if not config:\n raise VirtualServerNotFoundError(path)\n\n rating_details = config.rating_details or []\n updated_details, is_new = update_rating_details(\n rating_details,\n username,\n rating,\n )\n average = calculate_average_rating(updated_details)\n\n success = await self._repo.update_rating(path, average, updated_details)\n if not success:\n raise VirtualServerNotFoundError(path)\n\n logger.info(\n f\"User '{username}' rated virtual server '{path}': {rating} stars \"\n f\"(new avg: {average:.2f}, new={is_new})\"\n )\n\n return {\n \"average_rating\": average,\n \"is_new_rating\": is_new,\n \"total_ratings\": len(updated_details),\n }\n\n async def get_virtual_server_rating(\n self,\n path: str,\n ) -> dict:\n \"\"\"Get rating information for a virtual server.\n\n Args:\n path: Virtual server path\n\n Returns:\n Dict with num_stars and rating_details\n\n Raises:\n VirtualServerNotFoundError: If virtual server not found\n \"\"\"\n rating_info = await self._repo.get_rating(path)\n if rating_info is None:\n raise VirtualServerNotFoundError(path)\n\n return rating_info\n\n async def _validate_tool_mappings(\n self,\n tool_mappings: list[ToolMapping],\n ) -> None:\n \"\"\"Validate that all tool mappings reference existing backends and tools.\n\n Args:\n tool_mappings: List of tool mappings to validate\n\n Raises:\n VirtualServerValidationError: If any validation fails\n \"\"\"\n errors = []\n\n for mapping in tool_mappings:\n # Check backend server exists\n server_path = mapping.backend_server_path\n server_info = await self._server_repo.get(server_path)\n\n if not server_info:\n errors.append(f\"Backend server '{server_path}' does not exist\")\n continue\n\n # Check tool exists in backend\n tool_list = server_info.get(\"tool_list\", [])\n tool_names = [t.get(\"name\", \"\") for t in tool_list]\n\n if mapping.tool_name not in tool_names:\n errors.append(\n f\"Tool '{mapping.tool_name}' not found in backend \"\n f\"server '{server_path}'. Available tools: \"\n f\"{', '.join(tool_names[:10])}\"\n )\n\n # Check version exists if pinned\n if mapping.backend_version:\n version_id = f\"{server_path}:{mapping.backend_version}\"\n version_info = await self._server_repo.get(version_id)\n if not version_info:\n errors.append(\n f\"Version '{mapping.backend_version}' not found \"\n f\"for backend server '{server_path}'\"\n )\n\n if errors:\n raise VirtualServerValidationError(\n \"Tool mapping validation failed:\\n\" + \"\\n\".join(f\"- {e}\" for e in errors)\n )\n\n def _validate_unique_tool_names(\n self,\n tool_mappings: list[ToolMapping],\n ) -> None:\n \"\"\"Validate that effective tool names are unique within a virtual server.\n\n Args:\n tool_mappings: List of tool mappings\n\n Raises:\n VirtualServerValidationError: If duplicate names found\n \"\"\"\n seen_names: dict[str, str] = {}\n duplicates = []\n\n for mapping in tool_mappings:\n effective_name = _get_effective_tool_name(mapping)\n if effective_name in seen_names:\n duplicates.append(\n f\"'{effective_name}' (from {mapping.backend_server_path} \"\n f\"and {seen_names[effective_name]})\"\n )\n else:\n seen_names[effective_name] = mapping.backend_server_path\n\n if duplicates:\n raise VirtualServerValidationError(\n \"Duplicate tool names in virtual server: \"\n + \", \".join(duplicates)\n + \". Use aliases to resolve conflicts.\"\n )\n\n async def _resolve_tool_list(\n self,\n config: VirtualServerConfig,\n ) -> list[ResolvedTool]:\n \"\"\"Resolve tool mappings to full tool metadata.\n\n Args:\n config: Virtual server configuration\n\n Returns:\n List of ResolvedTool with full metadata from backends\n \"\"\"\n resolved = []\n\n # Build scope override lookup\n scope_overrides: dict[str, list[str]] = {}\n for override in config.tool_scope_overrides:\n scope_overrides[override.tool_alias] = override.required_scopes\n\n for mapping in config.tool_mappings:\n effective_name = _get_effective_tool_name(mapping)\n\n # Get tool metadata from backend\n server_path = mapping.backend_server_path\n\n # If version is pinned, look up version-specific server doc\n if mapping.backend_version:\n version_id = f\"{server_path}:{mapping.backend_version}\"\n server_info = await self._server_repo.get(version_id)\n else:\n server_info = await self._server_repo.get(server_path)\n\n if not server_info:\n logger.warning(\n f\"Backend server '{server_path}' not found, skipping tool '{mapping.tool_name}'\"\n )\n continue\n\n # Find tool in backend's tool list\n tool_list = server_info.get(\"tool_list\", [])\n tool_meta = None\n for tool in tool_list:\n if tool.get(\"name\") == mapping.tool_name:\n tool_meta = tool\n break\n\n if not tool_meta:\n logger.warning(\n f\"Tool '{mapping.tool_name}' not found in backend '{server_path}', skipping\"\n )\n continue\n\n # Build resolved tool\n description = mapping.description_override or tool_meta.get(\"description\", \"\")\n input_schema = tool_meta.get(\"inputSchema\", {})\n tool_scopes = scope_overrides.get(effective_name, [])\n\n resolved.append(\n ResolvedTool(\n name=effective_name,\n original_name=mapping.tool_name,\n backend_server_path=server_path,\n backend_version=mapping.backend_version,\n description=description,\n input_schema=input_schema,\n required_scopes=tool_scopes,\n )\n )\n\n return resolved\n\n def _config_to_info(\n self,\n config: VirtualServerConfig,\n ) -> VirtualServerInfo:\n \"\"\"Convert a VirtualServerConfig to a lightweight VirtualServerInfo.\n\n Args:\n config: Full virtual server configuration\n\n Returns:\n VirtualServerInfo summary\n \"\"\"\n backend_paths = _get_unique_backends(config.tool_mappings)\n return VirtualServerInfo(\n path=config.path,\n server_name=config.server_name,\n description=config.description,\n tool_count=len(config.tool_mappings),\n backend_count=len(backend_paths),\n backend_paths=backend_paths,\n is_enabled=config.is_enabled,\n tags=config.tags,\n num_stars=config.num_stars,\n rating_details=config.rating_details,\n created_by=config.created_by,\n created_at=config.created_at,\n updated_at=config.updated_at,\n )\n\n async def _index_for_search(\n self,\n config: VirtualServerConfig,\n ) -> None:\n \"\"\"Index or update a virtual server in the search index.\n\n Args:\n config: Virtual server configuration to index\n \"\"\"\n try:\n search_repo = get_search_repository()\n await search_repo.index_virtual_server(\n path=config.path,\n virtual_server=config,\n is_enabled=config.is_enabled,\n )\n except Exception as e:\n logger.warning(f\"Failed to index virtual server '{config.path}' for search: {e}\")\n\n async def _remove_from_search(\n self,\n path: str,\n ) -> None:\n \"\"\"Remove a virtual server from the search index.\n\n Args:\n path: Virtual server path to remove\n \"\"\"\n try:\n search_repo = get_search_repository()\n await search_repo.remove_entity(path)\n except Exception as e:\n logger.warning(f\"Failed to remove virtual server '{path}' from search: {e}\")\n\n async def _trigger_nginx_reload(self) -> bool:\n \"\"\"Trigger nginx configuration regeneration.\n\n Serializes concurrent nginx reloads using an asyncio.Lock to\n prevent race conditions when multiple mutations happen at once.\n\n This regenerates the full nginx config including virtual server\n location blocks and mapping files, then reloads nginx.\n\n Returns:\n True if nginx was successfully reloaded, False otherwise.\n The CRUD operation itself has already succeeded at this point,\n so callers should treat False as a non-fatal warning.\n \"\"\"\n async with _nginx_reload_lock:\n try:\n from ..core.nginx_service import nginx_service\n from ..services.server_service import server_service\n\n # Get currently enabled servers for the full config generation\n enabled_paths = await server_service.get_enabled_services()\n enabled_servers = {}\n for path in enabled_paths:\n server_info = await server_service.get_server_info(path)\n if server_info:\n enabled_servers[path] = server_info\n\n await nginx_service.generate_config_async(enabled_servers)\n logger.info(\"Nginx configuration regenerated for virtual server change\")\n return True\n except Exception as e:\n logger.error(\n f\"Failed to regenerate nginx config after virtual server change: {e}\",\n exc_info=True,\n )\n return False\n\n\ndef get_virtual_server_service() -> VirtualServerService:\n \"\"\"Get virtual server service singleton.\"\"\"\n global _virtual_server_service\n\n if _virtual_server_service is not None:\n return _virtual_server_service\n\n _virtual_server_service = VirtualServerService()\n return _virtual_server_service\n" }, { "path": "registry/services/webhook_service.py", "content": "\"\"\"Registration webhook notification service.\n\nFires an async POST to a configurable URL when a server, agent, or skill\nis registered (added) or deleted (removed). The call is fire-and-forget:\nfailures are logged at WARNING but never propagated to the caller.\n\"\"\"\n\nimport logging\nfrom datetime import (\n UTC,\n datetime,\n)\n\nimport httpx\n\nfrom registry.core.config import settings\n\nlogging.basicConfig(\n level=logging.INFO,\n format=\"%(asctime)s,p%(process)s,{%(filename)s:%(lineno)d},%(levelname)s,%(message)s\",\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _build_auth_headers() -> dict[str, str]:\n \"\"\"Build authentication headers for the webhook request.\n\n If auth header is 'Authorization', auto-prepends 'Bearer ' to the token.\n For any other header name, the token is sent as-is.\n\n Returns:\n Dict with a single auth header entry, or empty dict if no token.\n \"\"\"\n if not settings.registration_webhook_auth_token:\n return {}\n\n header_name = settings.registration_webhook_auth_header\n token = settings.registration_webhook_auth_token\n\n if header_name.lower() == \"authorization\":\n token = f\"Bearer {token}\"\n\n return {header_name: token}\n\n\nasync def send_registration_webhook(\n event_type: str,\n registration_type: str,\n card_data: dict,\n performed_by: str | None = None,\n) -> None:\n \"\"\"Send a webhook notification for a successful registration or deletion.\n\n This is fire-and-forget: failures are logged but never raised.\n\n Args:\n event_type: One of \"registration\" (add) or \"deletion\" (remove).\n registration_type: One of \"server\", \"agent\", or \"skill\".\n card_data: The full card JSON as a dictionary.\n performed_by: Username of the operator who performed the action.\n \"\"\"\n webhook_url = settings.registration_webhook_url\n if not webhook_url:\n return\n\n if not webhook_url.startswith((\"http://\", \"https://\")):\n logger.error(f\"Invalid webhook URL scheme: {webhook_url}\")\n return\n\n if webhook_url.startswith(\"http://\"):\n logger.warning(\n \"Registration webhook URL uses HTTP (not HTTPS). \"\n \"Credential data may be transmitted insecurely.\"\n )\n\n payload = {\n \"event_type\": event_type,\n \"registration_type\": registration_type,\n \"timestamp\": datetime.now(UTC).isoformat(),\n \"performed_by\": performed_by,\n \"card\": card_data,\n }\n\n headers = _build_auth_headers()\n headers[\"Content-Type\"] = \"application/json\"\n timeout = settings.registration_webhook_timeout_seconds\n\n try:\n async with httpx.AsyncClient(timeout=timeout) as client:\n response = await client.post(\n webhook_url,\n json=payload,\n headers=headers,\n )\n logger.info(\n f\"Registration webhook sent: event={event_type}, \"\n f\"type={registration_type}, \"\n f\"status={response.status_code}, url={webhook_url}\"\n )\n except httpx.TimeoutException:\n logger.warning(\n f\"Registration webhook timed out after {timeout}s: \"\n f\"event={event_type}, type={registration_type}, url={webhook_url}\"\n )\n except Exception as e:\n logger.warning(\n f\"Registration webhook failed: event={event_type}, \"\n f\"type={registration_type}, url={webhook_url}, error={e}\"\n )\n" }, { "path": "registry/static/asset-manifest.json", "content": "{\n \"files\": {\n \"main.css\": \"/static/css/main.509e9b60.css\",\n \"main.js\": \"/static/js/main.d2eb0b7d.js\",\n \"static/media/logo.png\": \"/static/media/logo.9208f8b33399c1bbac8a.png\",\n \"index.html\": \"/index.html\",\n \"main.509e9b60.css.map\": \"/static/css/main.509e9b60.css.map\",\n \"main.d2eb0b7d.js.map\": \"/static/js/main.d2eb0b7d.js.map\"\n },\n \"entrypoints\": [\n \"static/css/main.509e9b60.css\",\n \"static/js/main.d2eb0b7d.js\"\n ]\n}" }, { "path": "registry/static/index.html", "content": "AI Gateway & Registry
" }, { "path": "registry/static/static/css/main.509e9b60.css", "content": "@import url(https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap);*,:after,:before{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:#3b82f680;--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }::backdrop{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:#3b82f680;--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }/*\n! tailwindcss v3.4.17 | MIT License | https://tailwindcss.com\n*/*,:after,:before{border:0 solid #e8eaed;box-sizing:border-box}:after,:before{--tw-content:\"\"}:host,html{-webkit-text-size-adjust:100%;font-feature-settings:normal;-webkit-tap-highlight-color:transparent;font-family:Inter,system-ui,sans-serif;font-variation-settings:normal;line-height:1.5;tab-size:4}body{line-height:inherit}hr{border-top-width:1px;color:inherit;height:0}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,pre,samp{font-feature-settings:normal;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-size:1em;font-variation-settings:normal}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:initial}sub{bottom:-.25em}sup{top:-.5em}table{border-collapse:collapse;border-color:inherit;text-indent:0}button,input,optgroup,select,textarea{font-feature-settings:inherit;color:inherit;font-family:inherit;font-size:100%;font-variation-settings:inherit;font-weight:inherit;letter-spacing:inherit;line-height:inherit;margin:0;padding:0}button,select{text-transform:none}button,input:where([type=button]),input:where([type=reset]),input:where([type=submit]){-webkit-appearance:button;background-color:initial;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:initial}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}blockquote,dd,dl,figure,h1,h2,h3,h4,h5,h6,hr,p,pre{margin:0}fieldset{margin:0}fieldset,legend{padding:0}menu,ol,ul{list-style:none;margin:0;padding:0}dialog{padding:0}textarea{resize:vertical}input::placeholder,textarea::placeholder{color:#bdc1c6}[role=button],button{cursor:pointer}:disabled{cursor:default}audio,canvas,embed,iframe,img,object,svg,video{display:block;vertical-align:middle}img,video{height:auto;max-width:100%}[hidden]:where(:not([hidden=until-found])){display:none}[multiple],[type=date],[type=datetime-local],[type=email],[type=month],[type=number],[type=password],[type=search],[type=tel],[type=text],[type=time],[type=url],[type=week],input:where(:not([type])),select,textarea{--tw-shadow:0 0 #0000;-webkit-appearance:none;appearance:none;background-color:#fff;border-color:#9aa0a6;border-radius:0;border-width:1px;font-size:1rem;line-height:1.5rem;padding:.5rem .75rem}[multiple]:focus,[type=date]:focus,[type=datetime-local]:focus,[type=email]:focus,[type=month]:focus,[type=number]:focus,[type=password]:focus,[type=search]:focus,[type=tel]:focus,[type=text]:focus,[type=time]:focus,[type=url]:focus,[type=week]:focus,input:where(:not([type])):focus,select:focus,textarea:focus{--tw-ring-inset:var(--tw-empty,/*!*/ /*!*/);--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:#2563eb;--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);border-color:#2563eb;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow);outline:2px solid #0000;outline-offset:2px}input::placeholder,textarea::placeholder{color:#9aa0a6;opacity:1}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-date-and-time-value{min-height:1.5em;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit,::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-meridiem-field,::-webkit-datetime-edit-millisecond-field,::-webkit-datetime-edit-minute-field,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-second-field,::-webkit-datetime-edit-year-field{padding-bottom:0;padding-top:0}select{background-image:url(\"data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3E%3Cpath stroke='%239aa0a6' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' d='m6 8 4 4 4-4'/%3E%3C/svg%3E\");background-position:right .5rem center;background-repeat:no-repeat;background-size:1.5em 1.5em;padding-right:2.5rem;-webkit-print-color-adjust:exact;print-color-adjust:exact}[multiple],[size]:where(select:not([size=\"1\"])){background-image:none;background-position:0 0;background-repeat:repeat;background-size:initial;padding-right:.75rem;-webkit-print-color-adjust:inherit;print-color-adjust:inherit}[type=checkbox],[type=radio]{--tw-shadow:0 0 #0000;-webkit-appearance:none;appearance:none;background-color:#fff;background-origin:border-box;border-color:#9aa0a6;border-width:1px;color:#2563eb;display:inline-block;flex-shrink:0;height:1rem;padding:0;-webkit-print-color-adjust:exact;print-color-adjust:exact;-webkit-user-select:none;user-select:none;vertical-align:middle;width:1rem}[type=checkbox]{border-radius:0}[type=radio]{border-radius:100%}[type=checkbox]:focus,[type=radio]:focus{--tw-ring-inset:var(--tw-empty,/*!*/ /*!*/);--tw-ring-offset-width:2px;--tw-ring-offset-color:#fff;--tw-ring-color:#2563eb;--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow);outline:2px solid #0000;outline-offset:2px}[type=checkbox]:checked,[type=radio]:checked{background-color:currentColor;background-position:50%;background-repeat:no-repeat;background-size:100% 100%;border-color:#0000}[type=checkbox]:checked{background-image:url(\"data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23fff' viewBox='0 0 16 16'%3E%3Cpath d='M12.207 4.793a1 1 0 0 1 0 1.414l-5 5a1 1 0 0 1-1.414 0l-2-2a1 1 0 0 1 1.414-1.414L6.5 9.086l4.293-4.293a1 1 0 0 1 1.414 0'/%3E%3C/svg%3E\")}@media (forced-colors:active){[type=checkbox]:checked{-webkit-appearance:auto;appearance:auto}}[type=radio]:checked{background-image:url(\"data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23fff' viewBox='0 0 16 16'%3E%3Ccircle cx='8' cy='8' r='3'/%3E%3C/svg%3E\")}@media (forced-colors:active){[type=radio]:checked{-webkit-appearance:auto;appearance:auto}}[type=checkbox]:checked:focus,[type=checkbox]:checked:hover,[type=checkbox]:indeterminate,[type=radio]:checked:focus,[type=radio]:checked:hover{background-color:currentColor;border-color:#0000}[type=checkbox]:indeterminate{background-image:url(\"data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 16 16'%3E%3Cpath stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M4 8h8'/%3E%3C/svg%3E\");background-position:50%;background-repeat:no-repeat;background-size:100% 100%}@media (forced-colors:active){[type=checkbox]:indeterminate{-webkit-appearance:auto;appearance:auto}}[type=checkbox]:indeterminate:focus,[type=checkbox]:indeterminate:hover{background-color:currentColor;border-color:#0000}[type=file]{background:#0000 none repeat 0 0/auto auto padding-box border-box scroll;background:initial;border-color:inherit;border-radius:0;border-width:0;font-size:inherit;line-height:inherit;padding:0}[type=file]:focus{outline:1px solid ButtonText;outline:1px auto -webkit-focus-ring-color}html{font-family:Inter,system-ui,sans-serif}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;margin:0}.container{width:100%}@media (min-width:640px){.container{max-width:640px}}@media (min-width:768px){.container{max-width:768px}}@media (min-width:1024px){.container{max-width:1024px}}@media (min-width:1280px){.container{max-width:1280px}}@media (min-width:1536px){.container{max-width:1536px}}.prose{color:var(--tw-prose-body);max-width:65ch}.prose :where(p):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.25em;margin-top:1.25em}.prose :where([class~=lead]):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-lead);font-size:1.25em;line-height:1.6;margin-bottom:1.2em;margin-top:1.2em}.prose :where(a):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-links);font-weight:500;text-decoration:underline}.prose :where(strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-bold);font-weight:600}.prose :where(a strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(blockquote strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(thead th strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(ol):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1.625em;list-style-type:decimal;margin-bottom:1.25em;margin-top:1.25em;padding-inline-start:1.625em}.prose :where(ol[type=A]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:upper-alpha}.prose :where(ol[type=a]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:lower-alpha}.prose :where(ol[type=A s]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:upper-alpha}.prose :where(ol[type=a s]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:lower-alpha}.prose :where(ol[type=I]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:upper-roman}.prose :where(ol[type=i]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:lower-roman}.prose :where(ol[type=I s]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:upper-roman}.prose :where(ol[type=i s]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:lower-roman}.prose :where(ol[type=\"1\"]):not(:where([class~=not-prose],[class~=not-prose] *)){list-style-type:decimal}.prose :where(ul):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1.625em;list-style-type:disc;margin-bottom:1.25em;margin-top:1.25em;padding-inline-start:1.625em}.prose :where(ol>li):not(:where([class~=not-prose],[class~=not-prose] *))::marker{color:var(--tw-prose-counters);font-weight:400}.prose :where(ul>li):not(:where([class~=not-prose],[class~=not-prose] *))::marker{color:var(--tw-prose-bullets)}.prose :where(dt):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-headings);font-weight:600;margin-top:1.25em}.prose :where(hr):not(:where([class~=not-prose],[class~=not-prose] *)){border-color:var(--tw-prose-hr);border-top-width:1px;margin-bottom:3em;margin-top:3em}.prose :where(blockquote):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1em;border-inline-start-color:var(--tw-prose-quote-borders);border-inline-start-width:.25rem;color:var(--tw-prose-quotes);font-style:italic;font-weight:500;margin-bottom:1.6em;margin-top:1.6em;padding-inline-start:1em;quotes:\"\\201C\"\"\\201D\"\"\\2018\"\"\\2019\"}.prose :where(blockquote p:first-of-type):not(:where([class~=not-prose],[class~=not-prose] *)):before{content:open-quote}.prose :where(blockquote p:last-of-type):not(:where([class~=not-prose],[class~=not-prose] *)):after{content:close-quote}.prose :where(h1):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-headings);font-size:2.25em;font-weight:800;line-height:1.1111111;margin-bottom:.8888889em;margin-top:0}.prose :where(h1 strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit;font-weight:900}.prose :where(h2):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-headings);font-size:1.5em;font-weight:700;line-height:1.3333333;margin-bottom:1em;margin-top:2em}.prose :where(h2 strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit;font-weight:800}.prose :where(h3):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-headings);font-size:1.25em;font-weight:600;line-height:1.6;margin-bottom:.6em;margin-top:1.6em}.prose :where(h3 strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit;font-weight:700}.prose :where(h4):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-headings);font-weight:600;line-height:1.5;margin-bottom:.5em;margin-top:1.5em}.prose :where(h4 strong):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit;font-weight:700}.prose :where(img):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:2em;margin-top:2em}.prose :where(picture):not(:where([class~=not-prose],[class~=not-prose] *)){display:block;margin-bottom:2em;margin-top:2em}.prose :where(video):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:2em;margin-top:2em}.prose :where(kbd):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:.375em;-webkit-padding-start:.375em;border-radius:.3125rem;box-shadow:0 0 0 1px var(--tw-prose-kbd-shadows),0 3px 0 var(--tw-prose-kbd-shadows);color:var(--tw-prose-kbd);font-family:inherit;font-size:.875em;font-weight:500;padding-inline-end:.375em;padding-bottom:.1875em;padding-top:.1875em;padding-inline-start:.375em}.prose :where(code):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-code);font-size:.875em;font-weight:600}.prose :where(code):not(:where([class~=not-prose],[class~=not-prose] *)):before{content:\"`\"}.prose :where(code):not(:where([class~=not-prose],[class~=not-prose] *)):after{content:\"`\"}.prose :where(a code):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(h1 code):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(h2 code):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit;font-size:.875em}.prose :where(h3 code):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit;font-size:.9em}.prose :where(h4 code):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(blockquote code):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(thead th code):not(:where([class~=not-prose],[class~=not-prose] *)){color:inherit}.prose :where(pre):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:1.1428571em;-webkit-padding-start:1.1428571em;background-color:var(--tw-prose-pre-bg);border-radius:.375rem;color:var(--tw-prose-pre-code);font-size:.875em;font-weight:400;line-height:1.7142857;margin-bottom:1.7142857em;margin-top:1.7142857em;overflow-x:auto;padding-inline-end:1.1428571em;padding-bottom:.8571429em;padding-top:.8571429em;padding-inline-start:1.1428571em}.prose :where(pre code):not(:where([class~=not-prose],[class~=not-prose] *)){background-color:initial;border-radius:0;border-width:0;color:inherit;font-family:inherit;font-size:inherit;font-weight:inherit;line-height:inherit;padding:0}.prose :where(pre code):not(:where([class~=not-prose],[class~=not-prose] *)):before{content:none}.prose :where(pre code):not(:where([class~=not-prose],[class~=not-prose] *)):after{content:none}.prose :where(table):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:.875em;line-height:1.7142857;margin-bottom:2em;margin-top:2em;table-layout:auto;width:100%}.prose :where(thead):not(:where([class~=not-prose],[class~=not-prose] *)){border-bottom-color:var(--tw-prose-th-borders);border-bottom-width:1px}.prose :where(thead th):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:.5714286em;-webkit-padding-start:.5714286em;color:var(--tw-prose-headings);font-weight:600;padding-inline-end:.5714286em;padding-bottom:.5714286em;padding-inline-start:.5714286em;vertical-align:bottom}.prose :where(tbody tr):not(:where([class~=not-prose],[class~=not-prose] *)){border-bottom-color:var(--tw-prose-td-borders);border-bottom-width:1px}.prose :where(tbody tr:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){border-bottom-width:0}.prose :where(tbody td):not(:where([class~=not-prose],[class~=not-prose] *)){vertical-align:initial}.prose :where(tfoot):not(:where([class~=not-prose],[class~=not-prose] *)){border-top-color:var(--tw-prose-th-borders);border-top-width:1px}.prose :where(tfoot td):not(:where([class~=not-prose],[class~=not-prose] *)){vertical-align:top}.prose :where(th,td):not(:where([class~=not-prose],[class~=not-prose] *)){text-align:start}.prose :where(figure>*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:0;margin-top:0}.prose :where(figcaption):not(:where([class~=not-prose],[class~=not-prose] *)){color:var(--tw-prose-captions);font-size:.875em;line-height:1.4285714;margin-top:.8571429em}.prose{--tw-prose-body:#374151;--tw-prose-headings:#111827;--tw-prose-lead:#4b5563;--tw-prose-links:#111827;--tw-prose-bold:#111827;--tw-prose-counters:#6b7280;--tw-prose-bullets:#d1d5db;--tw-prose-hr:#e5e7eb;--tw-prose-quotes:#111827;--tw-prose-quote-borders:#e5e7eb;--tw-prose-captions:#6b7280;--tw-prose-kbd:#111827;--tw-prose-kbd-shadows:#1118271a;--tw-prose-code:#111827;--tw-prose-pre-code:#e5e7eb;--tw-prose-pre-bg:#1f2937;--tw-prose-th-borders:#d1d5db;--tw-prose-td-borders:#e5e7eb;--tw-prose-invert-body:#d1d5db;--tw-prose-invert-headings:#fff;--tw-prose-invert-lead:#9ca3af;--tw-prose-invert-links:#fff;--tw-prose-invert-bold:#fff;--tw-prose-invert-counters:#9ca3af;--tw-prose-invert-bullets:#4b5563;--tw-prose-invert-hr:#374151;--tw-prose-invert-quotes:#f3f4f6;--tw-prose-invert-quote-borders:#374151;--tw-prose-invert-captions:#9ca3af;--tw-prose-invert-kbd:#fff;--tw-prose-invert-kbd-shadows:#ffffff1a;--tw-prose-invert-code:#fff;--tw-prose-invert-pre-code:#d1d5db;--tw-prose-invert-pre-bg:#00000080;--tw-prose-invert-th-borders:#4b5563;--tw-prose-invert-td-borders:#374151;font-size:1rem;line-height:1.75}.prose :where(picture>img):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:0;margin-top:0}.prose :where(li):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:.5em;margin-top:.5em}.prose :where(ol>li):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:.375em;padding-inline-start:.375em}.prose :where(ul>li):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:.375em;padding-inline-start:.375em}.prose :where(.prose>ul>li p):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:.75em;margin-top:.75em}.prose :where(.prose>ul>li>p:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:1.25em}.prose :where(.prose>ul>li>p:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.25em}.prose :where(.prose>ol>li>p:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:1.25em}.prose :where(.prose>ol>li>p:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.25em}.prose :where(ul ul,ul ol,ol ul,ol ol):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:.75em;margin-top:.75em}.prose :where(dl):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.25em;margin-top:1.25em}.prose :where(dd):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1.625em;margin-top:.5em;padding-inline-start:1.625em}.prose :where(hr+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose :where(h2+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose :where(h3+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose :where(h4+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose :where(thead th:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:0;padding-inline-start:0}.prose :where(thead th:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:0;padding-inline-end:0}.prose :where(tbody td,tfoot td):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:.5714286em;-webkit-padding-start:.5714286em;padding-inline-end:.5714286em;padding-bottom:.5714286em;padding-top:.5714286em;padding-inline-start:.5714286em}.prose :where(tbody td:first-child,tfoot td:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:0;padding-inline-start:0}.prose :where(tbody td:last-child,tfoot td:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:0;padding-inline-end:0}.prose :where(figure):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:2em;margin-top:2em}.prose :where(.prose>:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose :where(.prose>:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:0}.prose-sm{font-size:.875rem;line-height:1.7142857}.prose-sm :where(p):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.1428571em;margin-top:1.1428571em}.prose-sm :where([class~=lead]):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:1.2857143em;line-height:1.5555556;margin-bottom:.8888889em;margin-top:.8888889em}.prose-sm :where(blockquote):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1.1111111em;margin-bottom:1.3333333em;margin-top:1.3333333em;padding-inline-start:1.1111111em}.prose-sm :where(h1):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:2.1428571em;line-height:1.2;margin-bottom:.8em;margin-top:0}.prose-sm :where(h2):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:1.4285714em;line-height:1.4;margin-bottom:.8em;margin-top:1.6em}.prose-sm :where(h3):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:1.2857143em;line-height:1.5555556;margin-bottom:.4444444em;margin-top:1.5555556em}.prose-sm :where(h4):not(:where([class~=not-prose],[class~=not-prose] *)){line-height:1.4285714;margin-bottom:.5714286em;margin-top:1.4285714em}.prose-sm :where(img):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.7142857em;margin-top:1.7142857em}.prose-sm :where(picture):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.7142857em;margin-top:1.7142857em}.prose-sm :where(picture>img):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:0;margin-top:0}.prose-sm :where(video):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.7142857em;margin-top:1.7142857em}.prose-sm :where(kbd):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:.3571429em;-webkit-padding-start:.3571429em;border-radius:.3125rem;font-size:.8571429em;padding-inline-end:.3571429em;padding-bottom:.1428571em;padding-top:.1428571em;padding-inline-start:.3571429em}.prose-sm :where(code):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:.8571429em}.prose-sm :where(h2 code):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:.9em}.prose-sm :where(h3 code):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:.8888889em}.prose-sm :where(pre):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:1em;-webkit-padding-start:1em;border-radius:.25rem;font-size:.8571429em;line-height:1.6666667;margin-bottom:1.6666667em;margin-top:1.6666667em;padding-inline-end:1em;padding-bottom:.6666667em;padding-top:.6666667em;padding-inline-start:1em}.prose-sm :where(ol):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1.5714286em;margin-bottom:1.1428571em;margin-top:1.1428571em;padding-inline-start:1.5714286em}.prose-sm :where(ul):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1.5714286em;margin-bottom:1.1428571em;margin-top:1.1428571em;padding-inline-start:1.5714286em}.prose-sm :where(li):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:.2857143em;margin-top:.2857143em}.prose-sm :where(ol>li):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:.4285714em;padding-inline-start:.4285714em}.prose-sm :where(ul>li):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:.4285714em;padding-inline-start:.4285714em}.prose-sm :where(.prose-sm>ul>li p):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:.5714286em;margin-top:.5714286em}.prose-sm :where(.prose-sm>ul>li>p:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:1.1428571em}.prose-sm :where(.prose-sm>ul>li>p:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.1428571em}.prose-sm :where(.prose-sm>ol>li>p:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:1.1428571em}.prose-sm :where(.prose-sm>ol>li>p:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.1428571em}.prose-sm :where(ul ul,ul ol,ol ul,ol ol):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:.5714286em;margin-top:.5714286em}.prose-sm :where(dl):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.1428571em;margin-top:1.1428571em}.prose-sm :where(dt):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:1.1428571em}.prose-sm :where(dd):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:1.5714286em;margin-top:.2857143em;padding-inline-start:1.5714286em}.prose-sm :where(hr):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:2.8571429em;margin-top:2.8571429em}.prose-sm :where(hr+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose-sm :where(h2+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose-sm :where(h3+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose-sm :where(h4+*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose-sm :where(table):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:.8571429em;line-height:1.5}.prose-sm :where(thead th):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:1em;-webkit-padding-start:1em;padding-inline-end:1em;padding-bottom:.6666667em;padding-inline-start:1em}.prose-sm :where(thead th:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:0;padding-inline-start:0}.prose-sm :where(thead th:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:0;padding-inline-end:0}.prose-sm :where(tbody td,tfoot td):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:1em;-webkit-padding-start:1em;padding-inline-end:1em;padding-bottom:.6666667em;padding-top:.6666667em;padding-inline-start:1em}.prose-sm :where(tbody td:first-child,tfoot td:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-start:0;padding-inline-start:0}.prose-sm :where(tbody td:last-child,tfoot td:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){-webkit-padding-end:0;padding-inline-end:0}.prose-sm :where(figure):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:1.7142857em;margin-top:1.7142857em}.prose-sm :where(figure>*):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:0;margin-top:0}.prose-sm :where(figcaption):not(:where([class~=not-prose],[class~=not-prose] *)){font-size:.8571429em;line-height:1.3333333;margin-top:.6666667em}.prose-sm :where(.prose-sm>:first-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-top:0}.prose-sm :where(.prose-sm>:last-child):not(:where([class~=not-prose],[class~=not-prose] *)){margin-bottom:0}.btn-primary{--tw-bg-opacity:1;--tw-text-opacity:1;background-color:#7a00cc;background-color:rgb(122 0 204/var(--tw-bg-opacity,1));border-radius:.5rem;color:#fff;color:rgb(255 255 255/var(--tw-text-opacity,1));font-weight:500;padding:.5rem 1rem;transition-duration:.2s;transition-property:color,background-color,border-color,fill,stroke,-webkit-text-decoration-color;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,-webkit-text-decoration-color;transition-timing-function:cubic-bezier(.4,0,.2,1)}.btn-primary:hover{--tw-bg-opacity:1;background-color:#6b46c1;background-color:rgb(107 70 193/var(--tw-bg-opacity,1))}.btn-secondary{--tw-bg-opacity:1;--tw-text-opacity:1;background-color:#f1f3f4;background-color:rgb(241 243 244/var(--tw-bg-opacity,1));border-radius:.5rem;color:#202124;color:rgb(32 33 36/var(--tw-text-opacity,1));font-weight:500;padding:.5rem 1rem;transition-duration:.2s;transition-property:color,background-color,border-color,fill,stroke,-webkit-text-decoration-color;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,-webkit-text-decoration-color;transition-timing-function:cubic-bezier(.4,0,.2,1)}.btn-secondary:hover{--tw-bg-opacity:1;background-color:#e8eaed;background-color:rgb(232 234 237/var(--tw-bg-opacity,1))}.\\!card{--tw-border-opacity:1;--tw-bg-opacity:1;--tw-shadow:0 1px 2px 0 #0000000d;--tw-shadow-colored:0 1px 2px 0 var(--tw-shadow-color);background-color:#fff;background-color:rgb(255 255 255/var(--tw-bg-opacity,1));border-color:#e8eaed;border-color:rgb(232 234 237/var(--tw-border-opacity,1));border-radius:.75rem;border-width:1px;box-shadow:0 0 #0000,0 0 #0000,var(--tw-shadow);box-shadow:var(--tw-ring-offset-shadow,0 0 #0000),var(--tw-ring-shadow,0 0 #0000),var(--tw-shadow)}.\\!card:is(.dark *){--tw-border-opacity:1;--tw-bg-opacity:1;background-color:#3c4043;background-color:rgb(60 64 67/var(--tw-bg-opacity,1));border-color:#5f6368;border-color:rgb(95 99 104/var(--tw-border-opacity,1))}.card{--tw-border-opacity:1;--tw-bg-opacity:1;--tw-shadow:0 1px 2px 0 #0000000d;--tw-shadow-colored:0 1px 2px 0 var(--tw-shadow-color);background-color:#fff;background-color:rgb(255 255 255/var(--tw-bg-opacity,1));border-color:#e8eaed;border-color:rgb(232 234 237/var(--tw-border-opacity,1));border-radius:.75rem;border-width:1px;box-shadow:0 0 #0000,0 0 #0000,var(--tw-shadow);box-shadow:var(--tw-ring-offset-shadow,0 0 #0000),var(--tw-ring-shadow,0 0 #0000),var(--tw-shadow)}.card:is(.dark *){--tw-border-opacity:1;--tw-bg-opacity:1;background-color:#3c4043;background-color:rgb(60 64 67/var(--tw-bg-opacity,1));border-color:#5f6368;border-color:rgb(95 99 104/var(--tw-border-opacity,1))}.input{--tw-border-opacity:1;border-color:#dadce0;border-color:rgb(218 220 224/var(--tw-border-opacity,1));border-radius:.5rem;border-width:1px;display:block;padding:.5rem .75rem;width:100%}.input::placeholder{--tw-placeholder-opacity:1;color:#bdc1c6;color:rgb(189 193 198/var(--tw-placeholder-opacity,1))}.input:focus{--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color);--tw-ring-opacity:1;--tw-ring-color:rgb(149 115 255/var(--tw-ring-opacity,1));border-color:#0000;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),0 0 #0000;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow,0 0 #0000);outline:2px solid #0000;outline-offset:2px}@keyframes slide-in-top{0%{opacity:0;transform:translateY(-100%)}to{opacity:1;transform:translateY(0)}}.animate-slide-in-top{animation:slide-in-top .3s ease-out}.discover-scroll{scrollbar-color:#0000 #0000;scrollbar-width:thin}.discover-scroll:hover{scrollbar-color:#64648c4d #0000}.discover-scroll::-webkit-scrollbar{width:6px}.discover-scroll::-webkit-scrollbar-track{background:#0000}.discover-scroll::-webkit-scrollbar-thumb{background:#0000;border-radius:3px}.discover-scroll:hover::-webkit-scrollbar-thumb{background:#64648c4d}.discover-scroll::-webkit-scrollbar-thumb:hover{background:#64648c80}.sr-only{clip:rect(0,0,0,0);border-width:0;height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;white-space:nowrap;width:1px}.pointer-events-none{pointer-events:none}.visible{visibility:visible}.invisible{visibility:hidden}.collapse{visibility:collapse}.static{position:static}.fixed{position:fixed}.absolute{position:absolute}.relative{position:relative}.sticky{position:-webkit-sticky;position:sticky}.inset-0{inset:0}.inset-y-0{bottom:0;top:0}.bottom-0{bottom:0}.bottom-4{bottom:1rem}.left-0{left:0}.left-0\\.5{left:.125rem}.left-3{left:.75rem}.left-full{left:100%}.right-0{right:0}.right-2{right:.5rem}.right-3{right:.75rem}.right-4{right:1rem}.top-0{top:0}.top-0\\.5{top:.125rem}.top-1\\/2{top:50%}.top-16{top:4rem}.top-2{top:.5rem}.top-3{top:.75rem}.top-4{top:1rem}.top-8{top:2rem}.top-full{top:100%}.z-10{z-index:10}.z-40{z-index:40}.z-50{z-index:50}.z-\\[9999\\]{z-index:9999}.col-span-2{grid-column:span 2/span 2}.-m-2\\.5{margin:-.625rem}.-mx-2{margin-left:-.5rem;margin-right:-.5rem}.-my-1{margin-bottom:-.25rem;margin-top:-.25rem}.mx-2{margin-left:.5rem;margin-right:.5rem}.mx-4{margin-left:1rem;margin-right:1rem}.mx-auto{margin-left:auto;margin-right:auto}.my-1{margin-bottom:.25rem;margin-top:.25rem}.my-4{margin-bottom:1rem;margin-top:1rem}.-mt-2{margin-top:-.5rem}.mb-1{margin-bottom:.25rem}.mb-1\\.5{margin-bottom:.375rem}.mb-2{margin-bottom:.5rem}.mb-3{margin-bottom:.75rem}.mb-4{margin-bottom:1rem}.mb-5{margin-bottom:1.25rem}.mb-6{margin-bottom:1.5rem}.mb-8{margin-bottom:2rem}.ml-1{margin-left:.25rem}.ml-1\\.5{margin-left:.375rem}.ml-12{margin-left:3rem}.ml-2{margin-left:.5rem}.ml-3{margin-left:.75rem}.ml-4{margin-left:1rem}.ml-5{margin-left:1.25rem}.ml-8{margin-left:2rem}.ml-auto{margin-left:auto}.mr-1{margin-right:.25rem}.mr-1\\.5{margin-right:.375rem}.mr-16{margin-right:4rem}.mr-2{margin-right:.5rem}.mr-3{margin-right:.75rem}.mr-4{margin-right:1rem}.mt-0\\.5{margin-top:.125rem}.mt-1{margin-top:.25rem}.mt-1\\.5{margin-top:.375rem}.mt-2{margin-top:.5rem}.mt-3{margin-top:.75rem}.mt-4{margin-top:1rem}.mt-5{margin-top:1.25rem}.mt-6{margin-top:1.5rem}.mt-8{margin-top:2rem}.mt-auto{margin-top:auto}.line-clamp-1{-webkit-line-clamp:1}.line-clamp-1,.line-clamp-2{-webkit-box-orient:vertical;display:-webkit-box;overflow:hidden}.line-clamp-2{-webkit-line-clamp:2}.line-clamp-3{-webkit-box-orient:vertical;-webkit-line-clamp:3;display:-webkit-box;overflow:hidden}.block{display:block}.inline-block{display:inline-block}.inline{display:inline}.flex{display:flex}.inline-flex{display:inline-flex}.table{display:table}.grid{display:grid}.contents{display:contents}.hidden{display:none}.h-0\\.5{height:.125rem}.h-1\\.5{height:.375rem}.h-10{height:2.5rem}.h-12{height:3rem}.h-14{height:3.5rem}.h-16{height:4rem}.h-2{height:.5rem}.h-2\\.5{height:.625rem}.h-24{height:6rem}.h-3{height:.75rem}.h-3\\.5{height:.875rem}.h-4{height:1rem}.h-5{height:1.25rem}.h-6{height:1.5rem}.h-64{height:16rem}.h-7{height:1.75rem}.h-8{height:2rem}.h-9{height:2.25rem}.h-full{height:100%}.h-screen{height:100vh}.max-h-32{max-height:8rem}.max-h-40{max-height:10rem}.max-h-48{max-height:12rem}.max-h-60{max-height:15rem}.max-h-64{max-height:16rem}.max-h-80{max-height:20rem}.max-h-96{max-height:24rem}.max-h-\\[160px\\]{max-height:160px}.max-h-\\[30vh\\]{max-height:30vh}.max-h-\\[60vh\\]{max-height:60vh}.max-h-\\[80vh\\]{max-height:80vh}.max-h-\\[85vh\\]{max-height:85vh}.max-h-\\[90vh\\]{max-height:90vh}.min-h-0{min-height:0}.min-h-full{min-height:100%}.min-h-screen{min-height:100vh}.w-1\\.5{width:.375rem}.w-1\\/4{width:25%}.w-10{width:2.5rem}.w-11{width:2.75rem}.w-12{width:3rem}.w-16{width:4rem}.w-2{width:.5rem}.w-2\\.5{width:.625rem}.w-24{width:6rem}.w-28{width:7rem}.w-3{width:.75rem}.w-3\\.5{width:.875rem}.w-32{width:8rem}.w-4{width:1rem}.w-40{width:10rem}.w-48{width:12rem}.w-5{width:1.25rem}.w-56{width:14rem}.w-6{width:1.5rem}.w-64{width:16rem}.w-8{width:2rem}.w-80{width:20rem}.w-9{width:2.25rem}.w-full{width:100%}.w-px{width:1px}.min-w-0{min-width:0}.min-w-\\[120px\\]{min-width:120px}.min-w-\\[130px\\]{min-width:130px}.min-w-full{min-width:100%}.max-w-2xl{max-width:42rem}.max-w-3xl{max-width:48rem}.max-w-4xl{max-width:56rem}.max-w-5xl{max-width:64rem}.max-w-7xl{max-width:80rem}.max-w-\\[100px\\]{max-width:100px}.max-w-\\[200px\\]{max-width:200px}.max-w-lg{max-width:32rem}.max-w-md{max-width:28rem}.max-w-none{max-width:none}.max-w-sm{max-width:24rem}.max-w-xl{max-width:36rem}.max-w-xs{max-width:20rem}.flex-1{flex:1 1}.flex-shrink-0{flex-shrink:0}.grow{flex-grow:1}.origin-top-right{transform-origin:top right}.-translate-x-full{--tw-translate-x:-100%}.-translate-x-full,.-translate-y-1\\/2{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.-translate-y-1\\/2{--tw-translate-y:-50%}.translate-x-0{--tw-translate-x:0px}.translate-x-0,.translate-x-1{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.translate-x-1{--tw-translate-x:0.25rem}.translate-x-4{--tw-translate-x:1rem}.translate-x-4,.translate-x-6{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.translate-x-6{--tw-translate-x:1.5rem}.rotate-180{--tw-rotate:180deg}.rotate-180,.scale-100{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.scale-100{--tw-scale-x:1;--tw-scale-y:1}.scale-95{--tw-scale-x:.95;--tw-scale-y:.95}.scale-95,.transform{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}@keyframes pulse{50%{opacity:.5}}.animate-pulse{animation:pulse 2s cubic-bezier(.4,0,.6,1) infinite}@keyframes spin{to{transform:rotate(1turn)}}.animate-spin{animation:spin 1s linear infinite}.cursor-default{cursor:default}.cursor-not-allowed{cursor:not-allowed}.cursor-pointer{cursor:pointer}.select-none{-webkit-user-select:none;user-select:none}.scroll-mt-4{scroll-margin-top:1rem}.list-inside{list-style-position:inside}.list-decimal{list-style-type:decimal}.grid-cols-1{grid-template-columns:repeat(1,minmax(0,1fr))}.grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))}.grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))}.flex-col{flex-direction:column}.flex-wrap{flex-wrap:wrap}.items-start{align-items:flex-start}.items-end{align-items:flex-end}.items-center{align-items:center}.justify-end{justify-content:flex-end}.justify-center{justify-content:center}.justify-between{justify-content:space-between}.gap-0\\.5{gap:.125rem}.gap-1{gap:.25rem}.gap-1\\.5{gap:.375rem}.gap-2{gap:.5rem}.gap-3{gap:.75rem}.gap-4{gap:1rem}.gap-6{gap:1.5rem}.gap-x-4{column-gap:1rem}.gap-y-2{row-gap:.5rem}.gap-y-5{row-gap:1.25rem}.space-x-1>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0;margin-left:calc(.25rem*(1 - var(--tw-space-x-reverse)));margin-right:calc(.25rem*var(--tw-space-x-reverse))}.space-x-2>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0;margin-left:calc(.5rem*(1 - var(--tw-space-x-reverse)));margin-right:calc(.5rem*var(--tw-space-x-reverse))}.space-x-3>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0;margin-left:calc(.75rem*(1 - var(--tw-space-x-reverse)));margin-right:calc(.75rem*var(--tw-space-x-reverse))}.space-x-4>:not([hidden])~:not([hidden]){--tw-space-x-reverse:0;margin-left:calc(1rem*(1 - var(--tw-space-x-reverse)));margin-right:calc(1rem*var(--tw-space-x-reverse))}.space-y-1>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(.25rem*var(--tw-space-y-reverse));margin-top:calc(.25rem*(1 - var(--tw-space-y-reverse)))}.space-y-1\\.5>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(.375rem*var(--tw-space-y-reverse));margin-top:calc(.375rem*(1 - var(--tw-space-y-reverse)))}.space-y-10>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(2.5rem*var(--tw-space-y-reverse));margin-top:calc(2.5rem*(1 - var(--tw-space-y-reverse)))}.space-y-2>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(.5rem*var(--tw-space-y-reverse));margin-top:calc(.5rem*(1 - var(--tw-space-y-reverse)))}.space-y-2\\.5>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(.625rem*var(--tw-space-y-reverse));margin-top:calc(.625rem*(1 - var(--tw-space-y-reverse)))}.space-y-3>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(.75rem*var(--tw-space-y-reverse));margin-top:calc(.75rem*(1 - var(--tw-space-y-reverse)))}.space-y-4>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(1rem*var(--tw-space-y-reverse));margin-top:calc(1rem*(1 - var(--tw-space-y-reverse)))}.space-y-6>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(1.5rem*var(--tw-space-y-reverse));margin-top:calc(1.5rem*(1 - var(--tw-space-y-reverse)))}.space-y-8>:not([hidden])~:not([hidden]){--tw-space-y-reverse:0;margin-bottom:calc(2rem*var(--tw-space-y-reverse));margin-top:calc(2rem*(1 - var(--tw-space-y-reverse)))}.divide-y>:not([hidden])~:not([hidden]){--tw-divide-y-reverse:0;border-bottom-width:calc(1px*var(--tw-divide-y-reverse));border-top-width:calc(1px*(1 - var(--tw-divide-y-reverse)))}.divide-gray-100>:not([hidden])~:not([hidden]){--tw-divide-opacity:1;border-color:#f1f3f4;border-color:rgb(241 243 244/var(--tw-divide-opacity,1))}.divide-gray-200>:not([hidden])~:not([hidden]){--tw-divide-opacity:1;border-color:#e8eaed;border-color:rgb(232 234 237/var(--tw-divide-opacity,1))}.overflow-auto{overflow:auto}.overflow-hidden{overflow:hidden}.overflow-visible{overflow:visible}.overflow-x-auto{overflow-x:auto}.overflow-y-auto{overflow-y:auto}.truncate{overflow:hidden;white-space:nowrap}.text-ellipsis,.truncate{text-overflow:ellipsis}.whitespace-nowrap{white-space:nowrap}.whitespace-pre-wrap{white-space:pre-wrap}.break-words{overflow-wrap:break-word}.break-all{word-break:break-all}.rounded{border-radius:.25rem}.rounded-2xl{border-radius:1rem}.rounded-full{border-radius:9999px}.rounded-lg{border-radius:.5rem}.rounded-md{border-radius:.375rem}.rounded-xl{border-radius:.75rem}.rounded-b-2xl{border-bottom-left-radius:1rem;border-bottom-right-radius:1rem}.border{border-width:1px}.border-2{border-width:2px}.border-b{border-bottom-width:1px}.border-b-2{border-bottom-width:2px}.border-l{border-left-width:1px}.border-r{border-right-width:1px}.border-t{border-top-width:1px}.border-dashed{border-style:dashed}.border-amber-100{--tw-border-opacity:1;border-color:#fef3c7;border-color:rgb(254 243 199/var(--tw-border-opacity,1))}.border-amber-200{--tw-border-opacity:1;border-color:#fde68a;border-color:rgb(253 230 138/var(--tw-border-opacity,1))}.border-amber-500{--tw-border-opacity:1;border-color:#f59e0b;border-color:rgb(245 158 11/var(--tw-border-opacity,1))}.border-amber-600{--tw-border-opacity:1;border-color:#d97706;border-color:rgb(217 119 6/var(--tw-border-opacity,1))}.border-blue-200{--tw-border-opacity:1;border-color:#bfdbfe;border-color:rgb(191 219 254/var(--tw-border-opacity,1))}.border-blue-500{--tw-border-opacity:1;border-color:#3b82f6;border-color:rgb(59 130 246/var(--tw-border-opacity,1))}.border-blue-600{--tw-border-opacity:1;border-color:#2563eb;border-color:rgb(37 99 235/var(--tw-border-opacity,1))}.border-cyan-100{--tw-border-opacity:1;border-color:#cffafe;border-color:rgb(207 250 254/var(--tw-border-opacity,1))}.border-cyan-200{--tw-border-opacity:1;border-color:#a5f3fc;border-color:rgb(165 243 252/var(--tw-border-opacity,1))}.border-cyan-500{--tw-border-opacity:1;border-color:#06b6d4;border-color:rgb(6 182 212/var(--tw-border-opacity,1))}.border-cyan-600{--tw-border-opacity:1;border-color:#0891b2;border-color:rgb(8 145 178/var(--tw-border-opacity,1))}.border-emerald-200{--tw-border-opacity:1;border-color:#a7f3d0;border-color:rgb(167 243 208/var(--tw-border-opacity,1))}.border-gray-100{--tw-border-opacity:1;border-color:#f1f3f4;border-color:rgb(241 243 244/var(--tw-border-opacity,1))}.border-gray-200{--tw-border-opacity:1;border-color:#e8eaed;border-color:rgb(232 234 237/var(--tw-border-opacity,1))}.border-gray-200\\/60{border-color:#e8eaed99}.border-gray-300{--tw-border-opacity:1;border-color:#dadce0;border-color:rgb(218 220 224/var(--tw-border-opacity,1))}.border-gray-600{--tw-border-opacity:1;border-color:#80868b;border-color:rgb(128 134 139/var(--tw-border-opacity,1))}.border-gray-700\\/50{border-color:#5f636880}.border-green-200{--tw-border-opacity:1;border-color:#bbf7d0;border-color:rgb(187 247 208/var(--tw-border-opacity,1))}.border-green-300{--tw-border-opacity:1;border-color:#86efac;border-color:rgb(134 239 172/var(--tw-border-opacity,1))}.border-green-500{--tw-border-opacity:1;border-color:#22c55e;border-color:rgb(34 197 94/var(--tw-border-opacity,1))}.border-indigo-200{--tw-border-opacity:1;border-color:#c7d2fe;border-color:rgb(199 210 254/var(--tw-border-opacity,1))}.border-indigo-500{--tw-border-opacity:1;border-color:#6366f1;border-color:rgb(99 102 241/var(--tw-border-opacity,1))}.border-orange-200{--tw-border-opacity:1;border-color:#fed7aa;border-color:rgb(254 215 170/var(--tw-border-opacity,1))}.border-primary-200{--tw-border-opacity:1;border-color:#e2dcff;border-color:rgb(226 220 255/var(--tw-border-opacity,1))}.border-primary-600{--tw-border-opacity:1;border-color:#7a00cc;border-color:rgb(122 0 204/var(--tw-border-opacity,1))}.border-purple-200{--tw-border-opacity:1;border-color:#e9d5ff;border-color:rgb(233 213 255/var(--tw-border-opacity,1))}.border-purple-500{--tw-border-opacity:1;border-color:#a855f7;border-color:rgb(168 85 247/var(--tw-border-opacity,1))}.border-purple-600{--tw-border-opacity:1;border-color:#9333ea;border-color:rgb(147 51 234/var(--tw-border-opacity,1))}.border-purple-700{--tw-border-opacity:1;border-color:#7e22ce;border-color:rgb(126 34 206/var(--tw-border-opacity,1))}.border-red-200{--tw-border-opacity:1;border-color:#fecaca;border-color:rgb(254 202 202/var(--tw-border-opacity,1))}.border-red-300{--tw-border-opacity:1;border-color:#fca5a5;border-color:rgb(252 165 165/var(--tw-border-opacity,1))}.border-red-500{--tw-border-opacity:1;border-color:#ef4444;border-color:rgb(239 68 68/var(--tw-border-opacity,1))}.border-teal-100{--tw-border-opacity:1;border-color:#ccfbf1;border-color:rgb(204 251 241/var(--tw-border-opacity,1))}.border-teal-200{--tw-border-opacity:1;border-color:#99f6e4;border-color:rgb(153 246 228/var(--tw-border-opacity,1))}.border-teal-500{--tw-border-opacity:1;border-color:#14b8a6;border-color:rgb(20 184 166/var(--tw-border-opacity,1))}.border-teal-600{--tw-border-opacity:1;border-color:#0d9488;border-color:rgb(13 148 136/var(--tw-border-opacity,1))}.border-transparent{border-color:#0000}.border-violet-200{--tw-border-opacity:1;border-color:#ddd6fe;border-color:rgb(221 214 254/var(--tw-border-opacity,1))}.border-white{--tw-border-opacity:1;border-color:#fff;border-color:rgb(255 255 255/var(--tw-border-opacity,1))}.border-yellow-200{--tw-border-opacity:1;border-color:#fef08a;border-color:rgb(254 240 138/var(--tw-border-opacity,1))}.border-t-transparent{border-top-color:#0000}.bg-amber-100{--tw-bg-opacity:1;background-color:#fef3c7;background-color:rgb(254 243 199/var(--tw-bg-opacity,1))}.bg-amber-200{--tw-bg-opacity:1;background-color:#fde68a;background-color:rgb(253 230 138/var(--tw-bg-opacity,1))}.bg-amber-400{--tw-bg-opacity:1;background-color:#fbbf24;background-color:rgb(251 191 36/var(--tw-bg-opacity,1))}.bg-amber-50{--tw-bg-opacity:1;background-color:#fffbeb;background-color:rgb(255 251 235/var(--tw-bg-opacity,1))}.bg-amber-50\\/50{background-color:#fffbeb80}.bg-amber-500\\/15{background-color:#f59e0b26}.bg-amber-600{--tw-bg-opacity:1;background-color:#d97706;background-color:rgb(217 119 6/var(--tw-bg-opacity,1))}.bg-black{--tw-bg-opacity:1;background-color:#000;background-color:rgb(0 0 0/var(--tw-bg-opacity,1))}.bg-black\\/50{background-color:#00000080}.bg-blue-100{--tw-bg-opacity:1;background-color:#dbeafe;background-color:rgb(219 234 254/var(--tw-bg-opacity,1))}.bg-blue-50{--tw-bg-opacity:1;background-color:#eff6ff;background-color:rgb(239 246 255/var(--tw-bg-opacity,1))}.bg-blue-50\\/50{background-color:#eff6ff80}.bg-blue-500{--tw-bg-opacity:1;background-color:#3b82f6;background-color:rgb(59 130 246/var(--tw-bg-opacity,1))}.bg-blue-600{--tw-bg-opacity:1;background-color:#2563eb;background-color:rgb(37 99 235/var(--tw-bg-opacity,1))}.bg-cyan-100{--tw-bg-opacity:1;background-color:#cffafe;background-color:rgb(207 250 254/var(--tw-bg-opacity,1))}.bg-cyan-200{--tw-bg-opacity:1;background-color:#a5f3fc;background-color:rgb(165 243 252/var(--tw-bg-opacity,1))}.bg-cyan-50{--tw-bg-opacity:1;background-color:#ecfeff;background-color:rgb(236 254 255/var(--tw-bg-opacity,1))}.bg-cyan-50\\/50{background-color:#ecfeff80}.bg-cyan-500\\/15{background-color:#06b6d426}.bg-cyan-600{--tw-bg-opacity:1;background-color:#0891b2;background-color:rgb(8 145 178/var(--tw-bg-opacity,1))}.bg-emerald-100{--tw-bg-opacity:1;background-color:#d1fae5;background-color:rgb(209 250 229/var(--tw-bg-opacity,1))}.bg-emerald-400{--tw-bg-opacity:1;background-color:#34d399;background-color:rgb(52 211 153/var(--tw-bg-opacity,1))}.bg-gray-100{--tw-bg-opacity:1;background-color:#f1f3f4;background-color:rgb(241 243 244/var(--tw-bg-opacity,1))}.bg-gray-100\\/50{background-color:#f1f3f480}.bg-gray-200{--tw-bg-opacity:1;background-color:#e8eaed;background-color:rgb(232 234 237/var(--tw-bg-opacity,1))}.bg-gray-300{--tw-bg-opacity:1;background-color:#dadce0;background-color:rgb(218 220 224/var(--tw-bg-opacity,1))}.bg-gray-400{--tw-bg-opacity:1;background-color:#bdc1c6;background-color:rgb(189 193 198/var(--tw-bg-opacity,1))}.bg-gray-50{--tw-bg-opacity:1;background-color:#f8f9fa;background-color:rgb(248 249 250/var(--tw-bg-opacity,1))}.bg-gray-50\\/50{background-color:#f8f9fa80}.bg-gray-50\\/80{background-color:#f8f9facc}.bg-gray-700\\/60{background-color:#5f636899}.bg-gray-800\\/40{background-color:#3c404366}.bg-gray-800\\/90{background-color:#3c4043e6}.bg-gray-900{--tw-bg-opacity:1;background-color:#202124;background-color:rgb(32 33 36/var(--tw-bg-opacity,1))}.bg-gray-900\\/80{background-color:#202124cc}.bg-gray-950{--tw-bg-opacity:1;background-color:#030712;background-color:rgb(3 7 18/var(--tw-bg-opacity,1))}.bg-green-100{--tw-bg-opacity:1;background-color:#dcfce7;background-color:rgb(220 252 231/var(--tw-bg-opacity,1))}.bg-green-400{--tw-bg-opacity:1;background-color:#4ade80;background-color:rgb(74 222 128/var(--tw-bg-opacity,1))}.bg-green-50{--tw-bg-opacity:1;background-color:#f0fdf4;background-color:rgb(240 253 244/var(--tw-bg-opacity,1))}.bg-green-50\\/50{background-color:#f0fdf480}.bg-green-500{--tw-bg-opacity:1;background-color:#22c55e;background-color:rgb(34 197 94/var(--tw-bg-opacity,1))}.bg-green-600{--tw-bg-opacity:1;background-color:#16a34a;background-color:rgb(22 163 74/var(--tw-bg-opacity,1))}.bg-green-700{--tw-bg-opacity:1;background-color:#15803d;background-color:rgb(21 128 61/var(--tw-bg-opacity,1))}.bg-indigo-100{--tw-bg-opacity:1;background-color:#e0e7ff;background-color:rgb(224 231 255/var(--tw-bg-opacity,1))}.bg-indigo-50{--tw-bg-opacity:1;background-color:#eef2ff;background-color:rgb(238 242 255/var(--tw-bg-opacity,1))}.bg-indigo-500{--tw-bg-opacity:1;background-color:#6366f1;background-color:rgb(99 102 241/var(--tw-bg-opacity,1))}.bg-indigo-500\\/15{background-color:#6366f126}.bg-orange-100{--tw-bg-opacity:1;background-color:#ffedd5;background-color:rgb(255 237 213/var(--tw-bg-opacity,1))}.bg-orange-400{--tw-bg-opacity:1;background-color:#fb923c;background-color:rgb(251 146 60/var(--tw-bg-opacity,1))}.bg-orange-50{--tw-bg-opacity:1;background-color:#fff7ed;background-color:rgb(255 247 237/var(--tw-bg-opacity,1))}.bg-primary-100{--tw-bg-opacity:1;background-color:#f0edff;background-color:rgb(240 237 255/var(--tw-bg-opacity,1))}.bg-purple-100{--tw-bg-opacity:1;background-color:#f3e8ff;background-color:rgb(243 232 255/var(--tw-bg-opacity,1))}.bg-purple-50{--tw-bg-opacity:1;background-color:#faf5ff;background-color:rgb(250 245 255/var(--tw-bg-opacity,1))}.bg-purple-500{--tw-bg-opacity:1;background-color:#a855f7;background-color:rgb(168 85 247/var(--tw-bg-opacity,1))}.bg-purple-500\\/15{background-color:#a855f726}.bg-purple-600{--tw-bg-opacity:1;background-color:#9333ea;background-color:rgb(147 51 234/var(--tw-bg-opacity,1))}.bg-red-100{--tw-bg-opacity:1;background-color:#fee2e2;background-color:rgb(254 226 226/var(--tw-bg-opacity,1))}.bg-red-400{--tw-bg-opacity:1;background-color:#f87171;background-color:rgb(248 113 113/var(--tw-bg-opacity,1))}.bg-red-50{--tw-bg-opacity:1;background-color:#fef2f2;background-color:rgb(254 242 242/var(--tw-bg-opacity,1))}.bg-red-500{--tw-bg-opacity:1;background-color:#ef4444;background-color:rgb(239 68 68/var(--tw-bg-opacity,1))}.bg-red-600{--tw-bg-opacity:1;background-color:#dc2626;background-color:rgb(220 38 38/var(--tw-bg-opacity,1))}.bg-teal-100{--tw-bg-opacity:1;background-color:#ccfbf1;background-color:rgb(204 251 241/var(--tw-bg-opacity,1))}.bg-teal-50{--tw-bg-opacity:1;background-color:#f0fdfa;background-color:rgb(240 253 250/var(--tw-bg-opacity,1))}.bg-teal-50\\/50{background-color:#f0fdfa80}.bg-teal-500{--tw-bg-opacity:1;background-color:#14b8a6;background-color:rgb(20 184 166/var(--tw-bg-opacity,1))}.bg-teal-500\\/15{background-color:#14b8a626}.bg-teal-600{--tw-bg-opacity:1;background-color:#0d9488;background-color:rgb(13 148 136/var(--tw-bg-opacity,1))}.bg-violet-100{--tw-bg-opacity:1;background-color:#ede9fe;background-color:rgb(237 233 254/var(--tw-bg-opacity,1))}.bg-white{--tw-bg-opacity:1;background-color:#fff;background-color:rgb(255 255 255/var(--tw-bg-opacity,1))}.bg-white\\/50{background-color:#ffffff80}.bg-yellow-100{--tw-bg-opacity:1;background-color:#fef9c3;background-color:rgb(254 249 195/var(--tw-bg-opacity,1))}.bg-yellow-200{--tw-bg-opacity:1;background-color:#fef08a;background-color:rgb(254 240 138/var(--tw-bg-opacity,1))}.bg-yellow-50{--tw-bg-opacity:1;background-color:#fefce8;background-color:rgb(254 252 232/var(--tw-bg-opacity,1))}.bg-yellow-500{--tw-bg-opacity:1;background-color:#eab308;background-color:rgb(234 179 8/var(--tw-bg-opacity,1))}.bg-opacity-25{--tw-bg-opacity:0.25}.bg-opacity-50{--tw-bg-opacity:0.5}.bg-gradient-to-br{background-image:linear-gradient(to bottom right,var(--tw-gradient-stops))}.bg-gradient-to-r{background-image:linear-gradient(to right,var(--tw-gradient-stops))}.bg-gradient-to-t{background-image:linear-gradient(to top,var(--tw-gradient-stops))}.from-amber-100{--tw-gradient-from:#fef3c7 var(--tw-gradient-from-position);--tw-gradient-to:#fef3c700 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-amber-50{--tw-gradient-from:#fffbeb var(--tw-gradient-from-position);--tw-gradient-to:#fffbeb00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-blue-100{--tw-gradient-from:#dbeafe var(--tw-gradient-from-position);--tw-gradient-to:#dbeafe00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-cyan-100{--tw-gradient-from:#cffafe var(--tw-gradient-from-position);--tw-gradient-to:#cffafe00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-cyan-50{--tw-gradient-from:#ecfeff var(--tw-gradient-from-position);--tw-gradient-to:#ecfeff00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-emerald-100{--tw-gradient-from:#d1fae5 var(--tw-gradient-from-position);--tw-gradient-to:#d1fae500 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-gray-100{--tw-gradient-from:#f1f3f4 var(--tw-gradient-from-position);--tw-gradient-to:#f1f3f400 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-gray-900\\/80{--tw-gradient-from:#202124cc var(--tw-gradient-from-position);--tw-gradient-to:#20212400 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-green-50{--tw-gradient-from:#f0fdf4 var(--tw-gradient-from-position);--tw-gradient-to:#f0fdf400 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-indigo-50{--tw-gradient-from:#eef2ff var(--tw-gradient-from-position);--tw-gradient-to:#eef2ff00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-orange-100{--tw-gradient-from:#ffedd5 var(--tw-gradient-from-position);--tw-gradient-to:#ffedd500 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-purple-100{--tw-gradient-from:#f3e8ff var(--tw-gradient-from-position);--tw-gradient-to:#f3e8ff00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-purple-50{--tw-gradient-from:#faf5ff var(--tw-gradient-from-position);--tw-gradient-to:#faf5ff00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-red-100{--tw-gradient-from:#fee2e2 var(--tw-gradient-from-position);--tw-gradient-to:#fee2e200 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-teal-50{--tw-gradient-from:#f0fdfa var(--tw-gradient-from-position);--tw-gradient-to:#f0fdfa00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-violet-100{--tw-gradient-from:#ede9fe var(--tw-gradient-from-position);--tw-gradient-to:#ede9fe00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-violet-50{--tw-gradient-from:#f5f3ff var(--tw-gradient-from-position);--tw-gradient-to:#f5f3ff00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.from-yellow-100{--tw-gradient-from:#fef9c3 var(--tw-gradient-from-position);--tw-gradient-to:#fef9c300 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.to-amber-100{--tw-gradient-to:#fef3c7 var(--tw-gradient-to-position)}.to-blue-100{--tw-gradient-to:#dbeafe var(--tw-gradient-to-position)}.to-blue-50{--tw-gradient-to:#eff6ff var(--tw-gradient-to-position)}.to-cyan-50{--tw-gradient-to:#ecfeff var(--tw-gradient-to-position)}.to-emerald-50{--tw-gradient-to:#ecfdf5 var(--tw-gradient-to-position)}.to-green-100{--tw-gradient-to:#dcfce7 var(--tw-gradient-to-position)}.to-indigo-100{--tw-gradient-to:#e0e7ff var(--tw-gradient-to-position)}.to-indigo-50{--tw-gradient-to:#eef2ff var(--tw-gradient-to-position)}.to-orange-100{--tw-gradient-to:#ffedd5 var(--tw-gradient-to-position)}.to-orange-50{--tw-gradient-to:#fff7ed var(--tw-gradient-to-position)}.to-purple-100{--tw-gradient-to:#f3e8ff var(--tw-gradient-to-position)}.to-purple-50{--tw-gradient-to:#faf5ff var(--tw-gradient-to-position)}.to-red-100{--tw-gradient-to:#fee2e2 var(--tw-gradient-to-position)}.to-rose-100{--tw-gradient-to:#ffe4e6 var(--tw-gradient-to-position)}.to-slate-100{--tw-gradient-to:#f1f5f9 var(--tw-gradient-to-position)}.to-teal-100{--tw-gradient-to:#ccfbf1 var(--tw-gradient-to-position)}.to-transparent{--tw-gradient-to:#0000 var(--tw-gradient-to-position)}.fill-blue-500{fill:#3b82f6}.fill-blue-500\\/15{fill:#3b82f626}.fill-gray-300{fill:#dadce0}.fill-gray-400{fill:#bdc1c6}.fill-gray-800{fill:#3c4043}.fill-white{fill:#fff}.stroke-blue-400\\/50{stroke:#60a5fa80}.stroke-blue-500{stroke:#3b82f6}.stroke-gray-300{stroke:#dadce0}.p-0\\.5{padding:.125rem}.p-1{padding:.25rem}.p-1\\.5{padding:.375rem}.p-2{padding:.5rem}.p-2\\.5{padding:.625rem}.p-3{padding:.75rem}.p-4{padding:1rem}.p-5{padding:1.25rem}.p-6{padding:1.5rem}.p-8{padding:2rem}.px-0\\.5{padding-left:.125rem;padding-right:.125rem}.px-1{padding-left:.25rem;padding-right:.25rem}.px-1\\.5{padding-left:.375rem;padding-right:.375rem}.px-2{padding-left:.5rem;padding-right:.5rem}.px-2\\.5{padding-left:.625rem;padding-right:.625rem}.px-3{padding-left:.75rem;padding-right:.75rem}.px-4{padding-left:1rem;padding-right:1rem}.px-5{padding-left:1.25rem;padding-right:1.25rem}.px-6{padding-left:1.5rem;padding-right:1.5rem}.py-0\\.5{padding-bottom:.125rem;padding-top:.125rem}.py-1{padding-bottom:.25rem;padding-top:.25rem}.py-1\\.5{padding-bottom:.375rem;padding-top:.375rem}.py-12{padding-bottom:3rem;padding-top:3rem}.py-16{padding-bottom:4rem;padding-top:4rem}.py-2{padding-bottom:.5rem;padding-top:.5rem}.py-2\\.5{padding-bottom:.625rem;padding-top:.625rem}.py-20{padding-bottom:5rem;padding-top:5rem}.py-3{padding-bottom:.75rem;padding-top:.75rem}.py-4{padding-bottom:1rem;padding-top:1rem}.py-6{padding-bottom:1.5rem;padding-top:1.5rem}.py-8{padding-bottom:2rem;padding-top:2rem}.pb-1{padding-bottom:.25rem}.pb-12{padding-bottom:3rem}.pb-2{padding-bottom:.5rem}.pb-3{padding-bottom:.75rem}.pb-4{padding-bottom:1rem}.pb-6{padding-bottom:1.5rem}.pl-10{padding-left:2.5rem}.pl-2{padding-left:.5rem}.pl-3{padding-left:.75rem}.pl-6{padding-left:1.5rem}.pl-8{padding-left:2rem}.pl-9{padding-left:2.25rem}.pr-10{padding-right:2.5rem}.pr-2{padding-right:.5rem}.pr-3{padding-right:.75rem}.pr-4{padding-right:1rem}.pr-8{padding-right:2rem}.pr-9{padding-right:2.25rem}.pt-0{padding-top:0}.pt-16{padding-top:4rem}.pt-2{padding-top:.5rem}.pt-3{padding-top:.75rem}.pt-4{padding-top:1rem}.pt-5{padding-top:1.25rem}.pt-6{padding-top:1.5rem}.text-left{text-align:left}.text-center{text-align:center}.text-right{text-align:right}.align-middle{vertical-align:middle}.font-mono{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace}.text-2xl{font-size:1.5rem;line-height:2rem}.text-3xl{font-size:1.875rem;line-height:2.25rem}.text-\\[10px\\]{font-size:10px}.text-\\[11px\\]{font-size:11px}.text-base{font-size:1rem;line-height:1.5rem}.text-lg{font-size:1.125rem;line-height:1.75rem}.text-sm{font-size:.875rem;line-height:1.25rem}.text-xl{font-size:1.25rem;line-height:1.75rem}.text-xs{font-size:.75rem;line-height:1rem}.font-bold{font-weight:700}.font-medium{font-weight:500}.font-normal{font-weight:400}.font-semibold{font-weight:600}.uppercase{text-transform:uppercase}.lowercase{text-transform:lowercase}.capitalize{text-transform:capitalize}.normal-case{text-transform:none}.italic{font-style:italic}.tabular-nums{--tw-numeric-spacing:tabular-nums;font-feature-settings:var(--tw-ordinal) var(--tw-slashed-zero) var(--tw-numeric-figure) var(--tw-numeric-spacing) var(--tw-numeric-fraction);font-variant-numeric:var(--tw-ordinal) var(--tw-slashed-zero) var(--tw-numeric-figure) var(--tw-numeric-spacing) var(--tw-numeric-fraction)}.leading-6{line-height:1.5rem}.leading-none{line-height:1}.leading-relaxed{line-height:1.625}.tracking-normal{letter-spacing:0}.tracking-wide{letter-spacing:.025em}.tracking-wider{letter-spacing:.05em}.text-amber-300{--tw-text-opacity:1;color:#fcd34d;color:rgb(252 211 77/var(--tw-text-opacity,1))}.text-amber-600{--tw-text-opacity:1;color:#d97706;color:rgb(217 119 6/var(--tw-text-opacity,1))}.text-amber-700{--tw-text-opacity:1;color:#b45309;color:rgb(180 83 9/var(--tw-text-opacity,1))}.text-amber-800{--tw-text-opacity:1;color:#92400e;color:rgb(146 64 14/var(--tw-text-opacity,1))}.text-amber-900{--tw-text-opacity:1;color:#78350f;color:rgb(120 53 15/var(--tw-text-opacity,1))}.text-blue-400{--tw-text-opacity:1;color:#60a5fa;color:rgb(96 165 250/var(--tw-text-opacity,1))}.text-blue-500{--tw-text-opacity:1;color:#3b82f6;color:rgb(59 130 246/var(--tw-text-opacity,1))}.text-blue-600{--tw-text-opacity:1;color:#2563eb;color:rgb(37 99 235/var(--tw-text-opacity,1))}.text-blue-700{--tw-text-opacity:1;color:#1d4ed8;color:rgb(29 78 216/var(--tw-text-opacity,1))}.text-blue-800{--tw-text-opacity:1;color:#1e40af;color:rgb(30 64 175/var(--tw-text-opacity,1))}.text-blue-900{--tw-text-opacity:1;color:#1e3a8a;color:rgb(30 58 138/var(--tw-text-opacity,1))}.text-current{color:currentColor}.text-cyan-300{--tw-text-opacity:1;color:#67e8f9;color:rgb(103 232 249/var(--tw-text-opacity,1))}.text-cyan-600{--tw-text-opacity:1;color:#0891b2;color:rgb(8 145 178/var(--tw-text-opacity,1))}.text-cyan-700{--tw-text-opacity:1;color:#0e7490;color:rgb(14 116 144/var(--tw-text-opacity,1))}.text-cyan-800{--tw-text-opacity:1;color:#155e75;color:rgb(21 94 117/var(--tw-text-opacity,1))}.text-emerald-600{--tw-text-opacity:1;color:#059669;color:rgb(5 150 105/var(--tw-text-opacity,1))}.text-emerald-700{--tw-text-opacity:1;color:#047857;color:rgb(4 120 87/var(--tw-text-opacity,1))}.text-gray-100{--tw-text-opacity:1;color:#f1f3f4;color:rgb(241 243 244/var(--tw-text-opacity,1))}.text-gray-300{--tw-text-opacity:1;color:#dadce0;color:rgb(218 220 224/var(--tw-text-opacity,1))}.text-gray-400{--tw-text-opacity:1;color:#bdc1c6;color:rgb(189 193 198/var(--tw-text-opacity,1))}.text-gray-500{--tw-text-opacity:1;color:#9aa0a6;color:rgb(154 160 166/var(--tw-text-opacity,1))}.text-gray-500\\/70{color:#9aa0a6b3}.text-gray-600{--tw-text-opacity:1;color:#80868b;color:rgb(128 134 139/var(--tw-text-opacity,1))}.text-gray-700{--tw-text-opacity:1;color:#5f6368;color:rgb(95 99 104/var(--tw-text-opacity,1))}.text-gray-800{--tw-text-opacity:1;color:#3c4043;color:rgb(60 64 67/var(--tw-text-opacity,1))}.text-gray-900{--tw-text-opacity:1;color:#202124;color:rgb(32 33 36/var(--tw-text-opacity,1))}.text-green-100{--tw-text-opacity:1;color:#dcfce7;color:rgb(220 252 231/var(--tw-text-opacity,1))}.text-green-400{--tw-text-opacity:1;color:#4ade80;color:rgb(74 222 128/var(--tw-text-opacity,1))}.text-green-500{--tw-text-opacity:1;color:#22c55e;color:rgb(34 197 94/var(--tw-text-opacity,1))}.text-green-600{--tw-text-opacity:1;color:#16a34a;color:rgb(22 163 74/var(--tw-text-opacity,1))}.text-green-700{--tw-text-opacity:1;color:#15803d;color:rgb(21 128 61/var(--tw-text-opacity,1))}.text-green-800{--tw-text-opacity:1;color:#166534;color:rgb(22 101 52/var(--tw-text-opacity,1))}.text-green-900{--tw-text-opacity:1;color:#14532d;color:rgb(20 83 45/var(--tw-text-opacity,1))}.text-indigo-300{--tw-text-opacity:1;color:#a5b4fc;color:rgb(165 180 252/var(--tw-text-opacity,1))}.text-indigo-600{--tw-text-opacity:1;color:#4f46e5;color:rgb(79 70 229/var(--tw-text-opacity,1))}.text-indigo-700{--tw-text-opacity:1;color:#4338ca;color:rgb(67 56 202/var(--tw-text-opacity,1))}.text-orange-500{--tw-text-opacity:1;color:#f97316;color:rgb(249 115 22/var(--tw-text-opacity,1))}.text-orange-600{--tw-text-opacity:1;color:#ea580c;color:rgb(234 88 12/var(--tw-text-opacity,1))}.text-orange-700{--tw-text-opacity:1;color:#c2410c;color:rgb(194 65 12/var(--tw-text-opacity,1))}.text-orange-800{--tw-text-opacity:1;color:#9a3412;color:rgb(154 52 18/var(--tw-text-opacity,1))}.text-primary-600{--tw-text-opacity:1;color:#7a00cc;color:rgb(122 0 204/var(--tw-text-opacity,1))}.text-primary-700{--tw-text-opacity:1;color:#6b46c1;color:rgb(107 70 193/var(--tw-text-opacity,1))}.text-purple-300{--tw-text-opacity:1;color:#d8b4fe;color:rgb(216 180 254/var(--tw-text-opacity,1))}.text-purple-600{--tw-text-opacity:1;color:#9333ea;color:rgb(147 51 234/var(--tw-text-opacity,1))}.text-purple-700{--tw-text-opacity:1;color:#7e22ce;color:rgb(126 34 206/var(--tw-text-opacity,1))}.text-purple-800{--tw-text-opacity:1;color:#6b21a8;color:rgb(107 33 168/var(--tw-text-opacity,1))}.text-purple-900{--tw-text-opacity:1;color:#581c87;color:rgb(88 28 135/var(--tw-text-opacity,1))}.text-red-400{--tw-text-opacity:1;color:#f87171;color:rgb(248 113 113/var(--tw-text-opacity,1))}.text-red-500{--tw-text-opacity:1;color:#ef4444;color:rgb(239 68 68/var(--tw-text-opacity,1))}.text-red-600{--tw-text-opacity:1;color:#dc2626;color:rgb(220 38 38/var(--tw-text-opacity,1))}.text-red-700{--tw-text-opacity:1;color:#b91c1c;color:rgb(185 28 28/var(--tw-text-opacity,1))}.text-red-800{--tw-text-opacity:1;color:#991b1b;color:rgb(153 27 27/var(--tw-text-opacity,1))}.text-red-900{--tw-text-opacity:1;color:#7f1d1d;color:rgb(127 29 29/var(--tw-text-opacity,1))}.text-teal-300{--tw-text-opacity:1;color:#5eead4;color:rgb(94 234 212/var(--tw-text-opacity,1))}.text-teal-500{--tw-text-opacity:1;color:#14b8a6;color:rgb(20 184 166/var(--tw-text-opacity,1))}.text-teal-600{--tw-text-opacity:1;color:#0d9488;color:rgb(13 148 136/var(--tw-text-opacity,1))}.text-teal-700{--tw-text-opacity:1;color:#0f766e;color:rgb(15 118 110/var(--tw-text-opacity,1))}.text-violet-600{--tw-text-opacity:1;color:#7c3aed;color:rgb(124 58 237/var(--tw-text-opacity,1))}.text-violet-700{--tw-text-opacity:1;color:#6d28d9;color:rgb(109 40 217/var(--tw-text-opacity,1))}.text-white{--tw-text-opacity:1;color:#fff;color:rgb(255 255 255/var(--tw-text-opacity,1))}.text-yellow-400{--tw-text-opacity:1;color:#facc15;color:rgb(250 204 21/var(--tw-text-opacity,1))}.text-yellow-600{--tw-text-opacity:1;color:#ca8a04;color:rgb(202 138 4/var(--tw-text-opacity,1))}.text-yellow-700{--tw-text-opacity:1;color:#a16207;color:rgb(161 98 7/var(--tw-text-opacity,1))}.text-yellow-800{--tw-text-opacity:1;color:#854d0e;color:rgb(133 77 14/var(--tw-text-opacity,1))}.placeholder-gray-400::placeholder{--tw-placeholder-opacity:1;color:#bdc1c6;color:rgb(189 193 198/var(--tw-placeholder-opacity,1))}.opacity-0{opacity:0}.opacity-100{opacity:1}.opacity-25{opacity:.25}.opacity-40{opacity:.4}.opacity-50{opacity:.5}.opacity-60{opacity:.6}.opacity-70{opacity:.7}.opacity-75{opacity:.75}.shadow-2xl{--tw-shadow:0 25px 50px -12px #00000040;--tw-shadow-colored:0 25px 50px -12px var(--tw-shadow-color)}.shadow-2xl,.shadow-lg{box-shadow:0 0 #0000,0 0 #0000,var(--tw-shadow);box-shadow:var(--tw-ring-offset-shadow,0 0 #0000),var(--tw-ring-shadow,0 0 #0000),var(--tw-shadow)}.shadow-lg{--tw-shadow:0 10px 15px -3px #0000001a,0 4px 6px -4px #0000001a;--tw-shadow-colored:0 10px 15px -3px var(--tw-shadow-color),0 4px 6px -4px var(--tw-shadow-color)}.shadow-sm{--tw-shadow:0 1px 2px 0 #0000000d;--tw-shadow-colored:0 1px 2px 0 var(--tw-shadow-color)}.shadow-sm,.shadow-xl{box-shadow:0 0 #0000,0 0 #0000,var(--tw-shadow);box-shadow:var(--tw-ring-offset-shadow,0 0 #0000),var(--tw-ring-shadow,0 0 #0000),var(--tw-shadow)}.shadow-xl{--tw-shadow:0 20px 25px -5px #0000001a,0 8px 10px -6px #0000001a;--tw-shadow-colored:0 20px 25px -5px var(--tw-shadow-color),0 8px 10px -6px var(--tw-shadow-color)}.shadow-amber-400\\/30{--tw-shadow-color:#fbbf244d;--tw-shadow:var(--tw-shadow-colored)}.shadow-emerald-400\\/30{--tw-shadow-color:#34d3994d;--tw-shadow:var(--tw-shadow-colored)}.shadow-green-400\\/30{--tw-shadow-color:#4ade804d;--tw-shadow:var(--tw-shadow-colored)}.shadow-orange-400\\/30{--tw-shadow-color:#fb923c4d;--tw-shadow:var(--tw-shadow-colored)}.shadow-red-400\\/30{--tw-shadow-color:#f871714d;--tw-shadow:var(--tw-shadow-colored)}.ring-1{--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),0 0 #0000;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow,0 0 #0000)}.ring-black{--tw-ring-opacity:1;--tw-ring-color:rgb(0 0 0/var(--tw-ring-opacity,1))}.ring-opacity-5{--tw-ring-opacity:0.05}.blur{--tw-blur:blur(8px)}.blur,.filter{filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)}.backdrop-blur-sm{--tw-backdrop-blur:blur(4px);-webkit-backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia);backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia)}.transition{transition-duration:.15s;transition-property:color,background-color,border-color,fill,stroke,opacity,box-shadow,transform,filter,-webkit-text-decoration-color,-webkit-backdrop-filter;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,opacity,box-shadow,transform,filter,backdrop-filter;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,opacity,box-shadow,transform,filter,backdrop-filter,-webkit-text-decoration-color,-webkit-backdrop-filter;transition-timing-function:cubic-bezier(.4,0,.2,1)}.transition-all{transition-duration:.15s;transition-property:all;transition-timing-function:cubic-bezier(.4,0,.2,1)}.transition-colors{transition-duration:.15s;transition-property:color,background-color,border-color,fill,stroke,-webkit-text-decoration-color;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke;transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,-webkit-text-decoration-color;transition-timing-function:cubic-bezier(.4,0,.2,1)}.transition-opacity{transition-duration:.15s;transition-property:opacity;transition-timing-function:cubic-bezier(.4,0,.2,1)}.transition-shadow{transition-duration:.15s;transition-property:box-shadow;transition-timing-function:cubic-bezier(.4,0,.2,1)}.transition-transform{transition-duration:.15s;transition-property:transform;transition-timing-function:cubic-bezier(.4,0,.2,1)}.duration-100{transition-duration:.1s}.duration-150{transition-duration:.15s}.duration-200{transition-duration:.2s}.duration-300{transition-duration:.3s}.duration-75{transition-duration:75ms}.ease-in{transition-timing-function:cubic-bezier(.4,0,1,1)}.ease-in-out{transition-timing-function:cubic-bezier(.4,0,.2,1)}.ease-linear{transition-timing-function:linear}.ease-out{transition-timing-function:cubic-bezier(0,0,.2,1)}.dark\\:prose-invert:is(.dark *){--tw-prose-body:var(--tw-prose-invert-body);--tw-prose-headings:var(--tw-prose-invert-headings);--tw-prose-lead:var(--tw-prose-invert-lead);--tw-prose-links:var(--tw-prose-invert-links);--tw-prose-bold:var(--tw-prose-invert-bold);--tw-prose-counters:var(--tw-prose-invert-counters);--tw-prose-bullets:var(--tw-prose-invert-bullets);--tw-prose-hr:var(--tw-prose-invert-hr);--tw-prose-quotes:var(--tw-prose-invert-quotes);--tw-prose-quote-borders:var(--tw-prose-invert-quote-borders);--tw-prose-captions:var(--tw-prose-invert-captions);--tw-prose-kbd:var(--tw-prose-invert-kbd);--tw-prose-kbd-shadows:var(--tw-prose-invert-kbd-shadows);--tw-prose-code:var(--tw-prose-invert-code);--tw-prose-pre-code:var(--tw-prose-invert-pre-code);--tw-prose-pre-bg:var(--tw-prose-invert-pre-bg);--tw-prose-th-borders:var(--tw-prose-invert-th-borders);--tw-prose-td-borders:var(--tw-prose-invert-td-borders)}.first\\:rounded-t-lg:first-child{border-top-left-radius:.5rem;border-top-right-radius:.5rem}.last\\:rounded-b-lg:last-child{border-bottom-left-radius:.5rem;border-bottom-right-radius:.5rem}.last\\:border-b-0:last-child{border-bottom-width:0}.hover\\:scale-105:hover{--tw-scale-x:1.05;--tw-scale-y:1.05}.hover\\:scale-105:hover,.hover\\:scale-110:hover{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.hover\\:scale-110:hover{--tw-scale-x:1.1;--tw-scale-y:1.1}.hover\\:border-amber-300:hover{--tw-border-opacity:1;border-color:#fcd34d;border-color:rgb(252 211 77/var(--tw-border-opacity,1))}.hover\\:border-cyan-300:hover{--tw-border-opacity:1;border-color:#67e8f9;border-color:rgb(103 232 249/var(--tw-border-opacity,1))}.hover\\:border-gray-200:hover{--tw-border-opacity:1;border-color:#e8eaed;border-color:rgb(232 234 237/var(--tw-border-opacity,1))}.hover\\:border-gray-300:hover{--tw-border-opacity:1;border-color:#dadce0;border-color:rgb(218 220 224/var(--tw-border-opacity,1))}.hover\\:border-gray-600\\/50:hover{border-color:#80868b80}.hover\\:border-purple-300:hover{--tw-border-opacity:1;border-color:#d8b4fe;border-color:rgb(216 180 254/var(--tw-border-opacity,1))}.hover\\:border-purple-400:hover{--tw-border-opacity:1;border-color:#c084fc;border-color:rgb(192 132 252/var(--tw-border-opacity,1))}.hover\\:border-teal-300:hover{--tw-border-opacity:1;border-color:#5eead4;border-color:rgb(94 234 212/var(--tw-border-opacity,1))}.hover\\:bg-amber-50:hover{--tw-bg-opacity:1;background-color:#fffbeb;background-color:rgb(255 251 235/var(--tw-bg-opacity,1))}.hover\\:bg-amber-700:hover{--tw-bg-opacity:1;background-color:#b45309;background-color:rgb(180 83 9/var(--tw-bg-opacity,1))}.hover\\:bg-blue-50:hover{--tw-bg-opacity:1;background-color:#eff6ff;background-color:rgb(239 246 255/var(--tw-bg-opacity,1))}.hover\\:bg-blue-700:hover{--tw-bg-opacity:1;background-color:#1d4ed8;background-color:rgb(29 78 216/var(--tw-bg-opacity,1))}.hover\\:bg-cyan-100:hover{--tw-bg-opacity:1;background-color:#cffafe;background-color:rgb(207 250 254/var(--tw-bg-opacity,1))}.hover\\:bg-cyan-200:hover{--tw-bg-opacity:1;background-color:#a5f3fc;background-color:rgb(165 243 252/var(--tw-bg-opacity,1))}.hover\\:bg-cyan-50:hover{--tw-bg-opacity:1;background-color:#ecfeff;background-color:rgb(236 254 255/var(--tw-bg-opacity,1))}.hover\\:bg-cyan-700:hover{--tw-bg-opacity:1;background-color:#0e7490;background-color:rgb(14 116 144/var(--tw-bg-opacity,1))}.hover\\:bg-gray-100:hover{--tw-bg-opacity:1;background-color:#f1f3f4;background-color:rgb(241 243 244/var(--tw-bg-opacity,1))}.hover\\:bg-gray-200:hover{--tw-bg-opacity:1;background-color:#e8eaed;background-color:rgb(232 234 237/var(--tw-bg-opacity,1))}.hover\\:bg-gray-300:hover{--tw-bg-opacity:1;background-color:#dadce0;background-color:rgb(218 220 224/var(--tw-bg-opacity,1))}.hover\\:bg-gray-50:hover{--tw-bg-opacity:1;background-color:#f8f9fa;background-color:rgb(248 249 250/var(--tw-bg-opacity,1))}.hover\\:bg-gray-800\\/70:hover{background-color:#3c4043b3}.hover\\:bg-green-200:hover{--tw-bg-opacity:1;background-color:#bbf7d0;background-color:rgb(187 247 208/var(--tw-bg-opacity,1))}.hover\\:bg-green-50:hover{--tw-bg-opacity:1;background-color:#f0fdf4;background-color:rgb(240 253 244/var(--tw-bg-opacity,1))}.hover\\:bg-green-700:hover{--tw-bg-opacity:1;background-color:#15803d;background-color:rgb(21 128 61/var(--tw-bg-opacity,1))}.hover\\:bg-indigo-100:hover{--tw-bg-opacity:1;background-color:#e0e7ff;background-color:rgb(224 231 255/var(--tw-bg-opacity,1))}.hover\\:bg-indigo-50:hover{--tw-bg-opacity:1;background-color:#eef2ff;background-color:rgb(238 242 255/var(--tw-bg-opacity,1))}.hover\\:bg-purple-200:hover{--tw-bg-opacity:1;background-color:#e9d5ff;background-color:rgb(233 213 255/var(--tw-bg-opacity,1))}.hover\\:bg-purple-50:hover{--tw-bg-opacity:1;background-color:#faf5ff;background-color:rgb(250 245 255/var(--tw-bg-opacity,1))}.hover\\:bg-purple-700:hover{--tw-bg-opacity:1;background-color:#7e22ce;background-color:rgb(126 34 206/var(--tw-bg-opacity,1))}.hover\\:bg-red-100:hover{--tw-bg-opacity:1;background-color:#fee2e2;background-color:rgb(254 226 226/var(--tw-bg-opacity,1))}.hover\\:bg-red-50:hover{--tw-bg-opacity:1;background-color:#fef2f2;background-color:rgb(254 242 242/var(--tw-bg-opacity,1))}.hover\\:bg-red-700:hover{--tw-bg-opacity:1;background-color:#b91c1c;background-color:rgb(185 28 28/var(--tw-bg-opacity,1))}.hover\\:bg-teal-100:hover{--tw-bg-opacity:1;background-color:#ccfbf1;background-color:rgb(204 251 241/var(--tw-bg-opacity,1))}.hover\\:bg-teal-50:hover{--tw-bg-opacity:1;background-color:#f0fdfa;background-color:rgb(240 253 250/var(--tw-bg-opacity,1))}.hover\\:bg-teal-700:hover{--tw-bg-opacity:1;background-color:#0f766e;background-color:rgb(15 118 110/var(--tw-bg-opacity,1))}.hover\\:bg-violet-100:hover{--tw-bg-opacity:1;background-color:#ede9fe;background-color:rgb(237 233 254/var(--tw-bg-opacity,1))}.hover\\:bg-violet-200:hover{--tw-bg-opacity:1;background-color:#ddd6fe;background-color:rgb(221 214 254/var(--tw-bg-opacity,1))}.hover\\:bg-yellow-200:hover{--tw-bg-opacity:1;background-color:#fef08a;background-color:rgb(254 240 138/var(--tw-bg-opacity,1))}.hover\\:bg-yellow-50:hover{--tw-bg-opacity:1;background-color:#fefce8;background-color:rgb(254 252 232/var(--tw-bg-opacity,1))}.hover\\:from-cyan-100:hover{--tw-gradient-from:#cffafe var(--tw-gradient-from-position);--tw-gradient-to:#cffafe00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.hover\\:from-green-100:hover{--tw-gradient-from:#dcfce7 var(--tw-gradient-from-position);--tw-gradient-to:#dcfce700 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.hover\\:from-violet-100:hover{--tw-gradient-from:#ede9fe var(--tw-gradient-from-position);--tw-gradient-to:#ede9fe00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.hover\\:to-blue-100:hover{--tw-gradient-to:#dbeafe var(--tw-gradient-to-position)}.hover\\:to-emerald-100:hover{--tw-gradient-to:#d1fae5 var(--tw-gradient-to-position)}.hover\\:to-purple-100:hover{--tw-gradient-to:#f3e8ff var(--tw-gradient-to-position)}.hover\\:text-amber-600:hover{--tw-text-opacity:1;color:#d97706;color:rgb(217 119 6/var(--tw-text-opacity,1))}.hover\\:text-amber-700:hover{--tw-text-opacity:1;color:#b45309;color:rgb(180 83 9/var(--tw-text-opacity,1))}.hover\\:text-blue-600:hover{--tw-text-opacity:1;color:#2563eb;color:rgb(37 99 235/var(--tw-text-opacity,1))}.hover\\:text-blue-700:hover{--tw-text-opacity:1;color:#1d4ed8;color:rgb(29 78 216/var(--tw-text-opacity,1))}.hover\\:text-cyan-600:hover{--tw-text-opacity:1;color:#0891b2;color:rgb(8 145 178/var(--tw-text-opacity,1))}.hover\\:text-cyan-800:hover{--tw-text-opacity:1;color:#155e75;color:rgb(21 94 117/var(--tw-text-opacity,1))}.hover\\:text-gray-500:hover{--tw-text-opacity:1;color:#9aa0a6;color:rgb(154 160 166/var(--tw-text-opacity,1))}.hover\\:text-gray-600:hover{--tw-text-opacity:1;color:#80868b;color:rgb(128 134 139/var(--tw-text-opacity,1))}.hover\\:text-gray-700:hover{--tw-text-opacity:1;color:#5f6368;color:rgb(95 99 104/var(--tw-text-opacity,1))}.hover\\:text-gray-800:hover{--tw-text-opacity:1;color:#3c4043;color:rgb(60 64 67/var(--tw-text-opacity,1))}.hover\\:text-gray-900:hover{--tw-text-opacity:1;color:#202124;color:rgb(32 33 36/var(--tw-text-opacity,1))}.hover\\:text-green-600:hover{--tw-text-opacity:1;color:#16a34a;color:rgb(22 163 74/var(--tw-text-opacity,1))}.hover\\:text-indigo-600:hover{--tw-text-opacity:1;color:#4f46e5;color:rgb(79 70 229/var(--tw-text-opacity,1))}.hover\\:text-indigo-700:hover{--tw-text-opacity:1;color:#4338ca;color:rgb(67 56 202/var(--tw-text-opacity,1))}.hover\\:text-purple-500:hover{--tw-text-opacity:1;color:#a855f7;color:rgb(168 85 247/var(--tw-text-opacity,1))}.hover\\:text-purple-600:hover{--tw-text-opacity:1;color:#9333ea;color:rgb(147 51 234/var(--tw-text-opacity,1))}.hover\\:text-purple-700:hover{--tw-text-opacity:1;color:#7e22ce;color:rgb(126 34 206/var(--tw-text-opacity,1))}.hover\\:text-purple-900:hover{--tw-text-opacity:1;color:#581c87;color:rgb(88 28 135/var(--tw-text-opacity,1))}.hover\\:text-red-500:hover{--tw-text-opacity:1;color:#ef4444;color:rgb(239 68 68/var(--tw-text-opacity,1))}.hover\\:text-red-600:hover{--tw-text-opacity:1;color:#dc2626;color:rgb(220 38 38/var(--tw-text-opacity,1))}.hover\\:text-teal-700:hover{--tw-text-opacity:1;color:#0f766e;color:rgb(15 118 110/var(--tw-text-opacity,1))}.hover\\:text-violet-800:hover{--tw-text-opacity:1;color:#5b21b6;color:rgb(91 33 182/var(--tw-text-opacity,1))}.hover\\:underline:hover{-webkit-text-decoration-line:underline;text-decoration-line:underline}.hover\\:opacity-100:hover{opacity:1}.hover\\:opacity-80:hover{opacity:.8}.hover\\:shadow-md:hover{--tw-shadow:0 4px 6px -1px #0000001a,0 2px 4px -2px #0000001a;--tw-shadow-colored:0 4px 6px -1px var(--tw-shadow-color),0 2px 4px -2px var(--tw-shadow-color)}.hover\\:shadow-md:hover,.hover\\:shadow-xl:hover{box-shadow:0 0 #0000,0 0 #0000,var(--tw-shadow);box-shadow:var(--tw-ring-offset-shadow,0 0 #0000),var(--tw-ring-shadow,0 0 #0000),var(--tw-shadow)}.hover\\:shadow-xl:hover{--tw-shadow:0 20px 25px -5px #0000001a,0 8px 10px -6px #0000001a;--tw-shadow-colored:0 20px 25px -5px var(--tw-shadow-color),0 8px 10px -6px var(--tw-shadow-color)}.focus\\:border-amber-500:focus{--tw-border-opacity:1;border-color:#f59e0b;border-color:rgb(245 158 11/var(--tw-border-opacity,1))}.focus\\:border-blue-500:focus{--tw-border-opacity:1;border-color:#3b82f6;border-color:rgb(59 130 246/var(--tw-border-opacity,1))}.focus\\:border-cyan-500:focus{--tw-border-opacity:1;border-color:#06b6d4;border-color:rgb(6 182 212/var(--tw-border-opacity,1))}.focus\\:border-indigo-500:focus{--tw-border-opacity:1;border-color:#6366f1;border-color:rgb(99 102 241/var(--tw-border-opacity,1))}.focus\\:border-purple-500:focus{--tw-border-opacity:1;border-color:#a855f7;border-color:rgb(168 85 247/var(--tw-border-opacity,1))}.focus\\:border-red-500:focus{--tw-border-opacity:1;border-color:#ef4444;border-color:rgb(239 68 68/var(--tw-border-opacity,1))}.focus\\:border-transparent:focus{border-color:#0000}.focus\\:outline-none:focus{outline:2px solid #0000;outline-offset:2px}.focus\\:ring-1:focus{--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color)}.focus\\:ring-1:focus,.focus\\:ring-2:focus{box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),0 0 #0000;box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow,0 0 #0000)}.focus\\:ring-2:focus{--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color)}.focus\\:ring-amber-500:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(245 158 11/var(--tw-ring-opacity,1))}.focus\\:ring-blue-500:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(59 130 246/var(--tw-ring-opacity,1))}.focus\\:ring-cyan-500:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(6 182 212/var(--tw-ring-opacity,1))}.focus\\:ring-primary-500:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(149 115 255/var(--tw-ring-opacity,1))}.focus\\:ring-purple-500:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(168 85 247/var(--tw-ring-opacity,1))}.focus\\:ring-red-500:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(239 68 68/var(--tw-ring-opacity,1))}.focus\\:ring-teal-500:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(20 184 166/var(--tw-ring-opacity,1))}.focus\\:ring-yellow-400:focus{--tw-ring-opacity:1;--tw-ring-color:rgb(250 204 21/var(--tw-ring-opacity,1))}.focus\\:ring-offset-2:focus{--tw-ring-offset-width:2px}.disabled\\:cursor-not-allowed:disabled{cursor:not-allowed}.disabled\\:bg-gray-300:disabled{--tw-bg-opacity:1;background-color:#dadce0;background-color:rgb(218 220 224/var(--tw-bg-opacity,1))}.disabled\\:opacity-50:disabled{opacity:.5}.group:hover .group-hover\\:visible{visibility:visible}.group:hover .group-hover\\:opacity-100{opacity:1}.prose-headings\\:text-amber-800 :is(:where(h1,h2,h3,h4,h5,h6,th):not(:where([class~=not-prose],[class~=not-prose] *))){--tw-text-opacity:1;color:#92400e;color:rgb(146 64 14/var(--tw-text-opacity,1))}.prose-a\\:text-amber-600 :is(:where(a):not(:where([class~=not-prose],[class~=not-prose] *))){--tw-text-opacity:1;color:#d97706;color:rgb(217 119 6/var(--tw-text-opacity,1))}.prose-code\\:rounded :is(:where(code):not(:where([class~=not-prose],[class~=not-prose] *))){border-radius:.25rem}.prose-code\\:bg-gray-100 :is(:where(code):not(:where([class~=not-prose],[class~=not-prose] *))){--tw-bg-opacity:1;background-color:#f1f3f4;background-color:rgb(241 243 244/var(--tw-bg-opacity,1))}.prose-code\\:px-1 :is(:where(code):not(:where([class~=not-prose],[class~=not-prose] *))){padding-left:.25rem;padding-right:.25rem}.prose-code\\:py-0\\.5 :is(:where(code):not(:where([class~=not-prose],[class~=not-prose] *))){padding-bottom:.125rem;padding-top:.125rem}.prose-pre\\:bg-gray-100 :is(:where(pre):not(:where([class~=not-prose],[class~=not-prose] *))){--tw-bg-opacity:1;background-color:#f1f3f4;background-color:rgb(241 243 244/var(--tw-bg-opacity,1))}.dark\\:divide-gray-700:is(.dark *)>:not([hidden])~:not([hidden]){--tw-divide-opacity:1;border-color:#5f6368;border-color:rgb(95 99 104/var(--tw-divide-opacity,1))}.dark\\:divide-gray-700\\/50:is(.dark *)>:not([hidden])~:not([hidden]){border-color:#5f636880}.dark\\:divide-gray-800:is(.dark *)>:not([hidden])~:not([hidden]){--tw-divide-opacity:1;border-color:#3c4043;border-color:rgb(60 64 67/var(--tw-divide-opacity,1))}.dark\\:border-amber-600:is(.dark *){--tw-border-opacity:1;border-color:#d97706;border-color:rgb(217 119 6/var(--tw-border-opacity,1))}.dark\\:border-amber-700:is(.dark *){--tw-border-opacity:1;border-color:#b45309;border-color:rgb(180 83 9/var(--tw-border-opacity,1))}.dark\\:border-amber-800:is(.dark *){--tw-border-opacity:1;border-color:#92400e;border-color:rgb(146 64 14/var(--tw-border-opacity,1))}.dark\\:border-blue-400:is(.dark *){--tw-border-opacity:1;border-color:#60a5fa;border-color:rgb(96 165 250/var(--tw-border-opacity,1))}.dark\\:border-blue-600:is(.dark *){--tw-border-opacity:1;border-color:#2563eb;border-color:rgb(37 99 235/var(--tw-border-opacity,1))}.dark\\:border-blue-700:is(.dark *){--tw-border-opacity:1;border-color:#1d4ed8;border-color:rgb(29 78 216/var(--tw-border-opacity,1))}.dark\\:border-blue-800:is(.dark *){--tw-border-opacity:1;border-color:#1e40af;border-color:rgb(30 64 175/var(--tw-border-opacity,1))}.dark\\:border-cyan-600:is(.dark *){--tw-border-opacity:1;border-color:#0891b2;border-color:rgb(8 145 178/var(--tw-border-opacity,1))}.dark\\:border-cyan-700:is(.dark *){--tw-border-opacity:1;border-color:#0e7490;border-color:rgb(14 116 144/var(--tw-border-opacity,1))}.dark\\:border-cyan-800:is(.dark *){--tw-border-opacity:1;border-color:#155e75;border-color:rgb(21 94 117/var(--tw-border-opacity,1))}.dark\\:border-cyan-900\\/40:is(.dark *){border-color:#164e6366}.dark\\:border-emerald-600:is(.dark *){--tw-border-opacity:1;border-color:#059669;border-color:rgb(5 150 105/var(--tw-border-opacity,1))}.dark\\:border-gray-600:is(.dark *){--tw-border-opacity:1;border-color:#80868b;border-color:rgb(128 134 139/var(--tw-border-opacity,1))}.dark\\:border-gray-700:is(.dark *){--tw-border-opacity:1;border-color:#5f6368;border-color:rgb(95 99 104/var(--tw-border-opacity,1))}.dark\\:border-gray-700\\/50:is(.dark *){border-color:#5f636880}.dark\\:border-gray-700\\/60:is(.dark *){border-color:#5f636899}.dark\\:border-gray-800:is(.dark *){--tw-border-opacity:1;border-color:#3c4043;border-color:rgb(60 64 67/var(--tw-border-opacity,1))}.dark\\:border-green-700:is(.dark *){--tw-border-opacity:1;border-color:#15803d;border-color:rgb(21 128 61/var(--tw-border-opacity,1))}.dark\\:border-green-800:is(.dark *){--tw-border-opacity:1;border-color:#166534;border-color:rgb(22 101 52/var(--tw-border-opacity,1))}.dark\\:border-indigo-600:is(.dark *){--tw-border-opacity:1;border-color:#4f46e5;border-color:rgb(79 70 229/var(--tw-border-opacity,1))}.dark\\:border-indigo-700:is(.dark *){--tw-border-opacity:1;border-color:#4338ca;border-color:rgb(67 56 202/var(--tw-border-opacity,1))}.dark\\:border-orange-600:is(.dark *){--tw-border-opacity:1;border-color:#ea580c;border-color:rgb(234 88 12/var(--tw-border-opacity,1))}.dark\\:border-orange-700:is(.dark *){--tw-border-opacity:1;border-color:#c2410c;border-color:rgb(194 65 12/var(--tw-border-opacity,1))}.dark\\:border-orange-800:is(.dark *){--tw-border-opacity:1;border-color:#9a3412;border-color:rgb(154 52 18/var(--tw-border-opacity,1))}.dark\\:border-primary-800:is(.dark *){--tw-border-opacity:1;border-color:#553c9a;border-color:rgb(85 60 154/var(--tw-border-opacity,1))}.dark\\:border-purple-300:is(.dark *){--tw-border-opacity:1;border-color:#d8b4fe;border-color:rgb(216 180 254/var(--tw-border-opacity,1))}.dark\\:border-purple-400:is(.dark *){--tw-border-opacity:1;border-color:#c084fc;border-color:rgb(192 132 252/var(--tw-border-opacity,1))}.dark\\:border-purple-600:is(.dark *){--tw-border-opacity:1;border-color:#9333ea;border-color:rgb(147 51 234/var(--tw-border-opacity,1))}.dark\\:border-purple-700:is(.dark *){--tw-border-opacity:1;border-color:#7e22ce;border-color:rgb(126 34 206/var(--tw-border-opacity,1))}.dark\\:border-purple-800:is(.dark *){--tw-border-opacity:1;border-color:#6b21a8;border-color:rgb(107 33 168/var(--tw-border-opacity,1))}.dark\\:border-red-400:is(.dark *){--tw-border-opacity:1;border-color:#f87171;border-color:rgb(248 113 113/var(--tw-border-opacity,1))}.dark\\:border-red-500\\/40:is(.dark *){border-color:#ef444466}.dark\\:border-red-600:is(.dark *){--tw-border-opacity:1;border-color:#dc2626;border-color:rgb(220 38 38/var(--tw-border-opacity,1))}.dark\\:border-red-700:is(.dark *){--tw-border-opacity:1;border-color:#b91c1c;border-color:rgb(185 28 28/var(--tw-border-opacity,1))}.dark\\:border-red-800:is(.dark *){--tw-border-opacity:1;border-color:#991b1b;border-color:rgb(153 27 27/var(--tw-border-opacity,1))}.dark\\:border-teal-600:is(.dark *){--tw-border-opacity:1;border-color:#0d9488;border-color:rgb(13 148 136/var(--tw-border-opacity,1))}.dark\\:border-teal-700:is(.dark *){--tw-border-opacity:1;border-color:#0f766e;border-color:rgb(15 118 110/var(--tw-border-opacity,1))}.dark\\:border-teal-800:is(.dark *){--tw-border-opacity:1;border-color:#115e59;border-color:rgb(17 94 89/var(--tw-border-opacity,1))}.dark\\:border-violet-600:is(.dark *){--tw-border-opacity:1;border-color:#7c3aed;border-color:rgb(124 58 237/var(--tw-border-opacity,1))}.dark\\:border-violet-700:is(.dark *){--tw-border-opacity:1;border-color:#6d28d9;border-color:rgb(109 40 217/var(--tw-border-opacity,1))}.dark\\:border-yellow-600:is(.dark *){--tw-border-opacity:1;border-color:#ca8a04;border-color:rgb(202 138 4/var(--tw-border-opacity,1))}.dark\\:border-yellow-800:is(.dark *){--tw-border-opacity:1;border-color:#854d0e;border-color:rgb(133 77 14/var(--tw-border-opacity,1))}.dark\\:bg-amber-600:is(.dark *){--tw-bg-opacity:1;background-color:#d97706;background-color:rgb(217 119 6/var(--tw-bg-opacity,1))}.dark\\:bg-amber-900\\/20:is(.dark *){background-color:#78350f33}.dark\\:bg-amber-900\\/30:is(.dark *){background-color:#78350f4d}.dark\\:bg-amber-900\\/40:is(.dark *){background-color:#78350f66}.dark\\:bg-black\\/20:is(.dark *){background-color:#0003}.dark\\:bg-blue-800:is(.dark *){--tw-bg-opacity:1;background-color:#1e40af;background-color:rgb(30 64 175/var(--tw-bg-opacity,1))}.dark\\:bg-blue-900:is(.dark *){--tw-bg-opacity:1;background-color:#1e3a8a;background-color:rgb(30 58 138/var(--tw-bg-opacity,1))}.dark\\:bg-blue-900\\/10:is(.dark *){background-color:#1e3a8a1a}.dark\\:bg-blue-900\\/20:is(.dark *){background-color:#1e3a8a33}.dark\\:bg-blue-900\\/30:is(.dark *){background-color:#1e3a8a4d}.dark\\:bg-blue-900\\/40:is(.dark *){background-color:#1e3a8a66}.dark\\:bg-cyan-600:is(.dark *){--tw-bg-opacity:1;background-color:#0891b2;background-color:rgb(8 145 178/var(--tw-bg-opacity,1))}.dark\\:bg-cyan-900\\/20:is(.dark *){background-color:#164e6333}.dark\\:bg-cyan-900\\/30:is(.dark *){background-color:#164e634d}.dark\\:bg-cyan-900\\/40:is(.dark *){background-color:#164e6366}.dark\\:bg-emerald-900\\/30:is(.dark *){background-color:#064e3b4d}.dark\\:bg-gray-600:is(.dark *){--tw-bg-opacity:1;background-color:#80868b;background-color:rgb(128 134 139/var(--tw-bg-opacity,1))}.dark\\:bg-gray-700:is(.dark *){--tw-bg-opacity:1;background-color:#5f6368;background-color:rgb(95 99 104/var(--tw-bg-opacity,1))}.dark\\:bg-gray-700\\/50:is(.dark *){background-color:#5f636880}.dark\\:bg-gray-800:is(.dark *){--tw-bg-opacity:1;background-color:#3c4043;background-color:rgb(60 64 67/var(--tw-bg-opacity,1))}.dark\\:bg-gray-800\\/50:is(.dark *){background-color:#3c404380}.dark\\:bg-gray-800\\/80:is(.dark *){background-color:#3c4043cc}.dark\\:bg-gray-900:is(.dark *){--tw-bg-opacity:1;background-color:#202124;background-color:rgb(32 33 36/var(--tw-bg-opacity,1))}.dark\\:bg-gray-900\\/20:is(.dark *){background-color:#20212433}.dark\\:bg-gray-900\\/30:is(.dark *){background-color:#2021244d}.dark\\:bg-gray-900\\/50:is(.dark *){background-color:#20212480}.dark\\:bg-green-900\\/20:is(.dark *){background-color:#14532d33}.dark\\:bg-green-900\\/30:is(.dark *){background-color:#14532d4d}.dark\\:bg-green-900\\/50:is(.dark *){background-color:#14532d80}.dark\\:bg-indigo-900\\/30:is(.dark *){background-color:#312e814d}.dark\\:bg-indigo-900\\/40:is(.dark *){background-color:#312e8166}.dark\\:bg-orange-900\\/30:is(.dark *){background-color:#7c2d124d}.dark\\:bg-primary-900:is(.dark *){--tw-bg-opacity:1;background-color:#483177;background-color:rgb(72 49 119/var(--tw-bg-opacity,1))}.dark\\:bg-purple-800:is(.dark *){--tw-bg-opacity:1;background-color:#6b21a8;background-color:rgb(107 33 168/var(--tw-bg-opacity,1))}.dark\\:bg-purple-900:is(.dark *){--tw-bg-opacity:1;background-color:#581c87;background-color:rgb(88 28 135/var(--tw-bg-opacity,1))}.dark\\:bg-purple-900\\/10:is(.dark *){background-color:#581c871a}.dark\\:bg-purple-900\\/20:is(.dark *){background-color:#581c8733}.dark\\:bg-purple-900\\/30:is(.dark *){background-color:#581c874d}.dark\\:bg-purple-900\\/40:is(.dark *){background-color:#581c8766}.dark\\:bg-red-900\\/20:is(.dark *){background-color:#7f1d1d33}.dark\\:bg-red-900\\/30:is(.dark *){background-color:#7f1d1d4d}.dark\\:bg-red-900\\/40:is(.dark *){background-color:#7f1d1d66}.dark\\:bg-red-900\\/50:is(.dark *){background-color:#7f1d1d80}.dark\\:bg-teal-900\\/10:is(.dark *){background-color:#134e4a1a}.dark\\:bg-teal-900\\/20:is(.dark *){background-color:#134e4a33}.dark\\:bg-teal-900\\/30:is(.dark *){background-color:#134e4a4d}.dark\\:bg-teal-900\\/40:is(.dark *){background-color:#134e4a66}.dark\\:bg-violet-900\\/30:is(.dark *){background-color:#4c1d954d}.dark\\:bg-violet-900\\/40:is(.dark *){background-color:#4c1d9566}.dark\\:bg-yellow-700:is(.dark *){--tw-bg-opacity:1;background-color:#a16207;background-color:rgb(161 98 7/var(--tw-bg-opacity,1))}.dark\\:bg-yellow-900:is(.dark *){--tw-bg-opacity:1;background-color:#713f12;background-color:rgb(113 63 18/var(--tw-bg-opacity,1))}.dark\\:bg-yellow-900\\/20:is(.dark *){background-color:#713f1233}.dark\\:bg-yellow-900\\/30:is(.dark *){background-color:#713f124d}.dark\\:bg-yellow-900\\/40:is(.dark *){background-color:#713f1266}.dark\\:from-amber-900\\/20:is(.dark *){--tw-gradient-from:#78350f33 var(--tw-gradient-from-position);--tw-gradient-to:#78350f00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-amber-900\\/30:is(.dark *){--tw-gradient-from:#78350f4d var(--tw-gradient-from-position);--tw-gradient-to:#78350f00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-blue-900\\/30:is(.dark *){--tw-gradient-from:#1e3a8a4d var(--tw-gradient-from-position);--tw-gradient-to:#1e3a8a00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-cyan-900\\/20:is(.dark *){--tw-gradient-from:#164e6333 var(--tw-gradient-from-position);--tw-gradient-to:#164e6300 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-cyan-900\\/30:is(.dark *){--tw-gradient-from:#164e634d var(--tw-gradient-from-position);--tw-gradient-to:#164e6300 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-emerald-900\\/30:is(.dark *){--tw-gradient-from:#064e3b4d var(--tw-gradient-from-position);--tw-gradient-to:#064e3b00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-gray-900\\/30:is(.dark *){--tw-gradient-from:#2021244d var(--tw-gradient-from-position);--tw-gradient-to:#20212400 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-green-900\\/20:is(.dark *){--tw-gradient-from:#14532d33 var(--tw-gradient-from-position);--tw-gradient-to:#14532d00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-indigo-900\\/20:is(.dark *){--tw-gradient-from:#312e8133 var(--tw-gradient-from-position);--tw-gradient-to:#312e8100 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-orange-900\\/30:is(.dark *){--tw-gradient-from:#7c2d124d var(--tw-gradient-from-position);--tw-gradient-to:#7c2d1200 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-purple-900\\/20:is(.dark *){--tw-gradient-from:#581c8733 var(--tw-gradient-from-position);--tw-gradient-to:#581c8700 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-purple-900\\/30:is(.dark *){--tw-gradient-from:#581c874d var(--tw-gradient-from-position);--tw-gradient-to:#581c8700 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-red-900\\/30:is(.dark *){--tw-gradient-from:#7f1d1d4d var(--tw-gradient-from-position);--tw-gradient-to:#7f1d1d00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-teal-900\\/20:is(.dark *){--tw-gradient-from:#134e4a33 var(--tw-gradient-from-position);--tw-gradient-to:#134e4a00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-violet-900\\/20:is(.dark *){--tw-gradient-from:#4c1d9533 var(--tw-gradient-from-position);--tw-gradient-to:#4c1d9500 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-violet-900\\/30:is(.dark *){--tw-gradient-from:#4c1d954d var(--tw-gradient-from-position);--tw-gradient-to:#4c1d9500 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:from-yellow-900\\/30:is(.dark *){--tw-gradient-from:#713f124d var(--tw-gradient-from-position);--tw-gradient-to:#713f1200 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:to-amber-900\\/30:is(.dark *){--tw-gradient-to:#78350f4d var(--tw-gradient-to-position)}.dark\\:to-blue-900\\/20:is(.dark *){--tw-gradient-to:#1e3a8a33 var(--tw-gradient-to-position)}.dark\\:to-blue-900\\/30:is(.dark *){--tw-gradient-to:#1e3a8a4d var(--tw-gradient-to-position)}.dark\\:to-cyan-900\\/20:is(.dark *){--tw-gradient-to:#164e6333 var(--tw-gradient-to-position)}.dark\\:to-emerald-900\\/20:is(.dark *){--tw-gradient-to:#064e3b33 var(--tw-gradient-to-position)}.dark\\:to-green-900\\/30:is(.dark *){--tw-gradient-to:#14532d4d var(--tw-gradient-to-position)}.dark\\:to-indigo-900\\/20:is(.dark *){--tw-gradient-to:#312e8133 var(--tw-gradient-to-position)}.dark\\:to-indigo-900\\/30:is(.dark *){--tw-gradient-to:#312e814d var(--tw-gradient-to-position)}.dark\\:to-orange-900\\/20:is(.dark *){--tw-gradient-to:#7c2d1233 var(--tw-gradient-to-position)}.dark\\:to-orange-900\\/30:is(.dark *){--tw-gradient-to:#7c2d124d var(--tw-gradient-to-position)}.dark\\:to-purple-900\\/20:is(.dark *){--tw-gradient-to:#581c8733 var(--tw-gradient-to-position)}.dark\\:to-purple-900\\/30:is(.dark *){--tw-gradient-to:#581c874d var(--tw-gradient-to-position)}.dark\\:to-red-900\\/30:is(.dark *){--tw-gradient-to:#7f1d1d4d var(--tw-gradient-to-position)}.dark\\:to-rose-900\\/30:is(.dark *){--tw-gradient-to:#8813374d var(--tw-gradient-to-position)}.dark\\:to-slate-900\\/30:is(.dark *){--tw-gradient-to:#0f172a4d var(--tw-gradient-to-position)}.dark\\:to-teal-900\\/30:is(.dark *){--tw-gradient-to:#134e4a4d var(--tw-gradient-to-position)}.dark\\:fill-blue-400:is(.dark *){fill:#60a5fa}.dark\\:fill-blue-400\\/15:is(.dark *){fill:#60a5fa26}.dark\\:fill-gray-200:is(.dark *){fill:#e8eaed}.dark\\:fill-gray-500:is(.dark *){fill:#9aa0a6}.dark\\:fill-gray-600:is(.dark *){fill:#80868b}.dark\\:fill-gray-800:is(.dark *){fill:#3c4043}.dark\\:stroke-blue-400:is(.dark *){stroke:#60a5fa}.dark\\:stroke-gray-600:is(.dark *){stroke:#80868b}.dark\\:text-amber-100:is(.dark *){--tw-text-opacity:1;color:#fef3c7;color:rgb(254 243 199/var(--tw-text-opacity,1))}.dark\\:text-amber-200:is(.dark *){--tw-text-opacity:1;color:#fde68a;color:rgb(253 230 138/var(--tw-text-opacity,1))}.dark\\:text-amber-300:is(.dark *){--tw-text-opacity:1;color:#fcd34d;color:rgb(252 211 77/var(--tw-text-opacity,1))}.dark\\:text-amber-400:is(.dark *){--tw-text-opacity:1;color:#fbbf24;color:rgb(251 191 36/var(--tw-text-opacity,1))}.dark\\:text-blue-100:is(.dark *){--tw-text-opacity:1;color:#dbeafe;color:rgb(219 234 254/var(--tw-text-opacity,1))}.dark\\:text-blue-200:is(.dark *){--tw-text-opacity:1;color:#bfdbfe;color:rgb(191 219 254/var(--tw-text-opacity,1))}.dark\\:text-blue-300:is(.dark *){--tw-text-opacity:1;color:#93c5fd;color:rgb(147 197 253/var(--tw-text-opacity,1))}.dark\\:text-blue-400:is(.dark *){--tw-text-opacity:1;color:#60a5fa;color:rgb(96 165 250/var(--tw-text-opacity,1))}.dark\\:text-cyan-200:is(.dark *){--tw-text-opacity:1;color:#a5f3fc;color:rgb(165 243 252/var(--tw-text-opacity,1))}.dark\\:text-cyan-300:is(.dark *){--tw-text-opacity:1;color:#67e8f9;color:rgb(103 232 249/var(--tw-text-opacity,1))}.dark\\:text-cyan-400:is(.dark *){--tw-text-opacity:1;color:#22d3ee;color:rgb(34 211 238/var(--tw-text-opacity,1))}.dark\\:text-emerald-300:is(.dark *){--tw-text-opacity:1;color:#6ee7b7;color:rgb(110 231 183/var(--tw-text-opacity,1))}.dark\\:text-emerald-400:is(.dark *){--tw-text-opacity:1;color:#34d399;color:rgb(52 211 153/var(--tw-text-opacity,1))}.dark\\:text-gray-100:is(.dark *){--tw-text-opacity:1;color:#f1f3f4;color:rgb(241 243 244/var(--tw-text-opacity,1))}.dark\\:text-gray-200:is(.dark *){--tw-text-opacity:1;color:#e8eaed;color:rgb(232 234 237/var(--tw-text-opacity,1))}.dark\\:text-gray-300:is(.dark *){--tw-text-opacity:1;color:#dadce0;color:rgb(218 220 224/var(--tw-text-opacity,1))}.dark\\:text-gray-400:is(.dark *){--tw-text-opacity:1;color:#bdc1c6;color:rgb(189 193 198/var(--tw-text-opacity,1))}.dark\\:text-gray-500:is(.dark *){--tw-text-opacity:1;color:#9aa0a6;color:rgb(154 160 166/var(--tw-text-opacity,1))}.dark\\:text-gray-600:is(.dark *){--tw-text-opacity:1;color:#80868b;color:rgb(128 134 139/var(--tw-text-opacity,1))}.dark\\:text-green-100:is(.dark *){--tw-text-opacity:1;color:#dcfce7;color:rgb(220 252 231/var(--tw-text-opacity,1))}.dark\\:text-green-200:is(.dark *){--tw-text-opacity:1;color:#bbf7d0;color:rgb(187 247 208/var(--tw-text-opacity,1))}.dark\\:text-green-300:is(.dark *){--tw-text-opacity:1;color:#86efac;color:rgb(134 239 172/var(--tw-text-opacity,1))}.dark\\:text-green-400:is(.dark *){--tw-text-opacity:1;color:#4ade80;color:rgb(74 222 128/var(--tw-text-opacity,1))}.dark\\:text-indigo-200:is(.dark *){--tw-text-opacity:1;color:#c7d2fe;color:rgb(199 210 254/var(--tw-text-opacity,1))}.dark\\:text-indigo-300:is(.dark *){--tw-text-opacity:1;color:#a5b4fc;color:rgb(165 180 252/var(--tw-text-opacity,1))}.dark\\:text-indigo-400:is(.dark *){--tw-text-opacity:1;color:#818cf8;color:rgb(129 140 248/var(--tw-text-opacity,1))}.dark\\:text-orange-300:is(.dark *){--tw-text-opacity:1;color:#fdba74;color:rgb(253 186 116/var(--tw-text-opacity,1))}.dark\\:text-orange-400:is(.dark *){--tw-text-opacity:1;color:#fb923c;color:rgb(251 146 60/var(--tw-text-opacity,1))}.dark\\:text-primary-300:is(.dark *){--tw-text-opacity:1;color:#cdc0ff;color:rgb(205 192 255/var(--tw-text-opacity,1))}.dark\\:text-primary-400:is(.dark *){--tw-text-opacity:1;color:#b199ff;color:rgb(177 153 255/var(--tw-text-opacity,1))}.dark\\:text-purple-100:is(.dark *){--tw-text-opacity:1;color:#f3e8ff;color:rgb(243 232 255/var(--tw-text-opacity,1))}.dark\\:text-purple-200:is(.dark *){--tw-text-opacity:1;color:#e9d5ff;color:rgb(233 213 255/var(--tw-text-opacity,1))}.dark\\:text-purple-300:is(.dark *){--tw-text-opacity:1;color:#d8b4fe;color:rgb(216 180 254/var(--tw-text-opacity,1))}.dark\\:text-purple-400:is(.dark *){--tw-text-opacity:1;color:#c084fc;color:rgb(192 132 252/var(--tw-text-opacity,1))}.dark\\:text-red-100:is(.dark *){--tw-text-opacity:1;color:#fee2e2;color:rgb(254 226 226/var(--tw-text-opacity,1))}.dark\\:text-red-200:is(.dark *){--tw-text-opacity:1;color:#fecaca;color:rgb(254 202 202/var(--tw-text-opacity,1))}.dark\\:text-red-300:is(.dark *){--tw-text-opacity:1;color:#fca5a5;color:rgb(252 165 165/var(--tw-text-opacity,1))}.dark\\:text-red-400:is(.dark *){--tw-text-opacity:1;color:#f87171;color:rgb(248 113 113/var(--tw-text-opacity,1))}.dark\\:text-teal-200:is(.dark *){--tw-text-opacity:1;color:#99f6e4;color:rgb(153 246 228/var(--tw-text-opacity,1))}.dark\\:text-teal-300:is(.dark *){--tw-text-opacity:1;color:#5eead4;color:rgb(94 234 212/var(--tw-text-opacity,1))}.dark\\:text-teal-400:is(.dark *){--tw-text-opacity:1;color:#2dd4bf;color:rgb(45 212 191/var(--tw-text-opacity,1))}.dark\\:text-violet-200:is(.dark *){--tw-text-opacity:1;color:#ddd6fe;color:rgb(221 214 254/var(--tw-text-opacity,1))}.dark\\:text-violet-300:is(.dark *){--tw-text-opacity:1;color:#c4b5fd;color:rgb(196 181 253/var(--tw-text-opacity,1))}.dark\\:text-violet-400:is(.dark *){--tw-text-opacity:1;color:#a78bfa;color:rgb(167 139 250/var(--tw-text-opacity,1))}.dark\\:text-white:is(.dark *){--tw-text-opacity:1;color:#fff;color:rgb(255 255 255/var(--tw-text-opacity,1))}.dark\\:text-yellow-200:is(.dark *){--tw-text-opacity:1;color:#fef08a;color:rgb(254 240 138/var(--tw-text-opacity,1))}.dark\\:text-yellow-300:is(.dark *){--tw-text-opacity:1;color:#fde047;color:rgb(253 224 71/var(--tw-text-opacity,1))}.dark\\:text-yellow-400:is(.dark *){--tw-text-opacity:1;color:#facc15;color:rgb(250 204 21/var(--tw-text-opacity,1))}.dark\\:placeholder-gray-500:is(.dark *)::placeholder{--tw-placeholder-opacity:1;color:#9aa0a6;color:rgb(154 160 166/var(--tw-placeholder-opacity,1))}.dark\\:brightness-0:is(.dark *){--tw-brightness:brightness(0);filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)}.dark\\:invert:is(.dark *){--tw-invert:invert(100%);filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)}.dark\\:hover\\:border-amber-600:hover:is(.dark *){--tw-border-opacity:1;border-color:#d97706;border-color:rgb(217 119 6/var(--tw-border-opacity,1))}.dark\\:hover\\:border-cyan-600:hover:is(.dark *){--tw-border-opacity:1;border-color:#0891b2;border-color:rgb(8 145 178/var(--tw-border-opacity,1))}.dark\\:hover\\:border-gray-600:hover:is(.dark *){--tw-border-opacity:1;border-color:#80868b;border-color:rgb(128 134 139/var(--tw-border-opacity,1))}.dark\\:hover\\:border-purple-500:hover:is(.dark *){--tw-border-opacity:1;border-color:#a855f7;border-color:rgb(168 85 247/var(--tw-border-opacity,1))}.dark\\:hover\\:border-purple-600:hover:is(.dark *){--tw-border-opacity:1;border-color:#9333ea;border-color:rgb(147 51 234/var(--tw-border-opacity,1))}.dark\\:hover\\:border-teal-600:hover:is(.dark *){--tw-border-opacity:1;border-color:#0d9488;border-color:rgb(13 148 136/var(--tw-border-opacity,1))}.dark\\:hover\\:bg-amber-700\\/30:hover:is(.dark *){background-color:#b453094d}.dark\\:hover\\:bg-amber-700\\/50:hover:is(.dark *){background-color:#b4530980}.dark\\:hover\\:bg-amber-900\\/20:hover:is(.dark *){background-color:#78350f33}.dark\\:hover\\:bg-blue-700\\/50:hover:is(.dark *){background-color:#1d4ed880}.dark\\:hover\\:bg-blue-900\\/20:hover:is(.dark *){background-color:#1e3a8a33}.dark\\:hover\\:bg-blue-900\\/30:hover:is(.dark *){background-color:#1e3a8a4d}.dark\\:hover\\:bg-cyan-700\\/30:hover:is(.dark *){background-color:#0e74904d}.dark\\:hover\\:bg-cyan-900\\/20:hover:is(.dark *){background-color:#164e6333}.dark\\:hover\\:bg-cyan-900\\/30:hover:is(.dark *){background-color:#164e634d}.dark\\:hover\\:bg-cyan-900\\/50:hover:is(.dark *){background-color:#164e6380}.dark\\:hover\\:bg-gray-600:hover:is(.dark *){--tw-bg-opacity:1;background-color:#80868b;background-color:rgb(128 134 139/var(--tw-bg-opacity,1))}.dark\\:hover\\:bg-gray-700:hover:is(.dark *){--tw-bg-opacity:1;background-color:#5f6368;background-color:rgb(95 99 104/var(--tw-bg-opacity,1))}.dark\\:hover\\:bg-gray-700\\/50:hover:is(.dark *){background-color:#5f636880}.dark\\:hover\\:bg-gray-800:hover:is(.dark *){--tw-bg-opacity:1;background-color:#3c4043;background-color:rgb(60 64 67/var(--tw-bg-opacity,1))}.dark\\:hover\\:bg-gray-800\\/50:hover:is(.dark *){background-color:#3c404380}.dark\\:hover\\:bg-green-700\\/30:hover:is(.dark *){background-color:#15803d4d}.dark\\:hover\\:bg-green-700\\/50:hover:is(.dark *){background-color:#15803d80}.dark\\:hover\\:bg-green-900\\/50:hover:is(.dark *){background-color:#14532d80}.dark\\:hover\\:bg-indigo-700\\/30:hover:is(.dark *){background-color:#4338ca4d}.dark\\:hover\\:bg-indigo-900\\/30:hover:is(.dark *){background-color:#312e814d}.dark\\:hover\\:bg-indigo-900\\/50:hover:is(.dark *){background-color:#312e8180}.dark\\:hover\\:bg-purple-700\\/30:hover:is(.dark *){background-color:#7e22ce4d}.dark\\:hover\\:bg-purple-800:hover:is(.dark *){--tw-bg-opacity:1;background-color:#6b21a8;background-color:rgb(107 33 168/var(--tw-bg-opacity,1))}.dark\\:hover\\:bg-purple-900\\/30:hover:is(.dark *){background-color:#581c874d}.dark\\:hover\\:bg-red-700\\/50:hover:is(.dark *){background-color:#b91c1c80}.dark\\:hover\\:bg-red-900\\/30:hover:is(.dark *){background-color:#7f1d1d4d}.dark\\:hover\\:bg-red-900\\/40:hover:is(.dark *){background-color:#7f1d1d66}.dark\\:hover\\:bg-teal-900\\/20:hover:is(.dark *){background-color:#134e4a33}.dark\\:hover\\:bg-teal-900\\/40:hover:is(.dark *){background-color:#134e4a66}.dark\\:hover\\:bg-violet-900\\/30:hover:is(.dark *){background-color:#4c1d954d}.dark\\:hover\\:bg-violet-900\\/50:hover:is(.dark *){background-color:#4c1d9580}.dark\\:hover\\:bg-yellow-800:hover:is(.dark *){--tw-bg-opacity:1;background-color:#854d0e;background-color:rgb(133 77 14/var(--tw-bg-opacity,1))}.dark\\:hover\\:bg-yellow-900\\/20:hover:is(.dark *){background-color:#713f1233}.dark\\:hover\\:from-cyan-900\\/30:hover:is(.dark *){--tw-gradient-from:#164e634d var(--tw-gradient-from-position);--tw-gradient-to:#164e6300 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:hover\\:from-green-900\\/30:hover:is(.dark *){--tw-gradient-from:#14532d4d var(--tw-gradient-from-position);--tw-gradient-to:#14532d00 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:hover\\:from-violet-900\\/30:hover:is(.dark *){--tw-gradient-from:#4c1d954d var(--tw-gradient-from-position);--tw-gradient-to:#4c1d9500 var(--tw-gradient-to-position);--tw-gradient-stops:var(--tw-gradient-from),var(--tw-gradient-to)}.dark\\:hover\\:to-blue-900\\/30:hover:is(.dark *){--tw-gradient-to:#1e3a8a4d var(--tw-gradient-to-position)}.dark\\:hover\\:to-emerald-900\\/30:hover:is(.dark *){--tw-gradient-to:#064e3b4d var(--tw-gradient-to-position)}.dark\\:hover\\:to-purple-900\\/30:hover:is(.dark *){--tw-gradient-to:#581c874d var(--tw-gradient-to-position)}.dark\\:hover\\:text-amber-300:hover:is(.dark *){--tw-text-opacity:1;color:#fcd34d;color:rgb(252 211 77/var(--tw-text-opacity,1))}.dark\\:hover\\:text-amber-400:hover:is(.dark *){--tw-text-opacity:1;color:#fbbf24;color:rgb(251 191 36/var(--tw-text-opacity,1))}.dark\\:hover\\:text-blue-300:hover:is(.dark *){--tw-text-opacity:1;color:#93c5fd;color:rgb(147 197 253/var(--tw-text-opacity,1))}.dark\\:hover\\:text-blue-400:hover:is(.dark *){--tw-text-opacity:1;color:#60a5fa;color:rgb(96 165 250/var(--tw-text-opacity,1))}.dark\\:hover\\:text-cyan-200:hover:is(.dark *){--tw-text-opacity:1;color:#a5f3fc;color:rgb(165 243 252/var(--tw-text-opacity,1))}.dark\\:hover\\:text-cyan-300:hover:is(.dark *){--tw-text-opacity:1;color:#67e8f9;color:rgb(103 232 249/var(--tw-text-opacity,1))}.dark\\:hover\\:text-cyan-400:hover:is(.dark *){--tw-text-opacity:1;color:#22d3ee;color:rgb(34 211 238/var(--tw-text-opacity,1))}.dark\\:hover\\:text-gray-100:hover:is(.dark *){--tw-text-opacity:1;color:#f1f3f4;color:rgb(241 243 244/var(--tw-text-opacity,1))}.dark\\:hover\\:text-gray-200:hover:is(.dark *){--tw-text-opacity:1;color:#e8eaed;color:rgb(232 234 237/var(--tw-text-opacity,1))}.dark\\:hover\\:text-gray-300:hover:is(.dark *){--tw-text-opacity:1;color:#dadce0;color:rgb(218 220 224/var(--tw-text-opacity,1))}.dark\\:hover\\:text-green-300:hover:is(.dark *){--tw-text-opacity:1;color:#86efac;color:rgb(134 239 172/var(--tw-text-opacity,1))}.dark\\:hover\\:text-indigo-300:hover:is(.dark *){--tw-text-opacity:1;color:#a5b4fc;color:rgb(165 180 252/var(--tw-text-opacity,1))}.dark\\:hover\\:text-indigo-400:hover:is(.dark *){--tw-text-opacity:1;color:#818cf8;color:rgb(129 140 248/var(--tw-text-opacity,1))}.dark\\:hover\\:text-purple-100:hover:is(.dark *){--tw-text-opacity:1;color:#f3e8ff;color:rgb(243 232 255/var(--tw-text-opacity,1))}.dark\\:hover\\:text-purple-300:hover:is(.dark *){--tw-text-opacity:1;color:#d8b4fe;color:rgb(216 180 254/var(--tw-text-opacity,1))}.dark\\:hover\\:text-purple-400:hover:is(.dark *){--tw-text-opacity:1;color:#c084fc;color:rgb(192 132 252/var(--tw-text-opacity,1))}.dark\\:hover\\:text-red-400:hover:is(.dark *){--tw-text-opacity:1;color:#f87171;color:rgb(248 113 113/var(--tw-text-opacity,1))}.dark\\:hover\\:text-teal-300:hover:is(.dark *){--tw-text-opacity:1;color:#5eead4;color:rgb(94 234 212/var(--tw-text-opacity,1))}.dark\\:hover\\:text-violet-200:hover:is(.dark *){--tw-text-opacity:1;color:#ddd6fe;color:rgb(221 214 254/var(--tw-text-opacity,1))}.dark\\:hover\\:text-white:hover:is(.dark *){--tw-text-opacity:1;color:#fff;color:rgb(255 255 255/var(--tw-text-opacity,1))}.dark\\:focus\\:border-indigo-400:focus:is(.dark *){--tw-border-opacity:1;border-color:#818cf8;border-color:rgb(129 140 248/var(--tw-border-opacity,1))}.dark\\:disabled\\:bg-gray-600:disabled:is(.dark *){--tw-bg-opacity:1;background-color:#80868b;background-color:rgb(128 134 139/var(--tw-bg-opacity,1))}.dark\\:prose-headings\\:text-amber-200 :is(:where(h1,h2,h3,h4,h5,h6,th):not(:where([class~=not-prose],[class~=not-prose] *))):is(.dark *){--tw-text-opacity:1;color:#fde68a;color:rgb(253 230 138/var(--tw-text-opacity,1))}.dark\\:prose-a\\:text-amber-400 :is(:where(a):not(:where([class~=not-prose],[class~=not-prose] *))):is(.dark *){--tw-text-opacity:1;color:#fbbf24;color:rgb(251 191 36/var(--tw-text-opacity,1))}.dark\\:prose-code\\:bg-gray-900 :is(:where(code):not(:where([class~=not-prose],[class~=not-prose] *))):is(.dark *){--tw-bg-opacity:1;background-color:#202124;background-color:rgb(32 33 36/var(--tw-bg-opacity,1))}.dark\\:prose-pre\\:bg-gray-900 :is(:where(pre):not(:where([class~=not-prose],[class~=not-prose] *))):is(.dark *){--tw-bg-opacity:1;background-color:#202124;background-color:rgb(32 33 36/var(--tw-bg-opacity,1))}@media (min-width:640px){.sm\\:mx-auto{margin-left:auto;margin-right:auto}.sm\\:inline{display:inline}.sm\\:flex{display:flex}.sm\\:w-full{width:100%}.sm\\:max-w-md{max-width:28rem}.sm\\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.sm\\:flex-row{flex-direction:row}.sm\\:items-start{align-items:flex-start}.sm\\:items-center{align-items:center}.sm\\:justify-between{justify-content:space-between}.sm\\:px-6{padding-left:1.5rem;padding-right:1.5rem}}@media (min-width:768px){.md\\:col-span-2{grid-column:span 2/span 2}.md\\:ml-0{margin-left:0}.md\\:ml-64{margin-left:16rem}.md\\:block{display:block}.md\\:flex{display:flex}.md\\:inline-flex{display:inline-flex}.md\\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.md\\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))}.md\\:grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))}.md\\:p-6{padding:1.5rem}.md\\:py-8{padding-bottom:2rem;padding-top:2rem}}@media (min-width:1024px){.lg\\:col-span-1{grid-column:span 1/span 1}.lg\\:col-span-2{grid-column:span 2/span 2}.lg\\:col-span-3{grid-column:span 3/span 3}.lg\\:ml-72{margin-left:18rem}.lg\\:w-72{width:18rem}.lg\\:max-w-\\[300px\\]{max-width:300px}.lg\\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.lg\\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))}.lg\\:grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))}.lg\\:px-8{padding-left:2rem;padding-right:2rem}}@media (min-width:1280px){.xl\\:ml-80{margin-left:20rem}.xl\\:w-80{width:20rem}}\n/*# sourceMappingURL=main.509e9b60.css.map*/" }, { "path": "registry/static/static/js/main.d2eb0b7d.js", "content": "/*! For license information please see main.d2eb0b7d.js.LICENSE.txt */\n(()=>{\"use strict\";var e={240(e){var t=Object.prototype.hasOwnProperty,r=Object.prototype.toString,a=Object.defineProperty,n=Object.getOwnPropertyDescriptor,s=function(e){return\"function\"===typeof Array.isArray?Array.isArray(e):\"[object Array]\"===r.call(e)},l=function(e){if(!e||\"[object Object]\"!==r.call(e))return!1;var a,n=t.call(e,\"constructor\"),s=e.constructor&&e.constructor.prototype&&t.call(e.constructor.prototype,\"isPrototypeOf\");if(e.constructor&&!n&&!s)return!1;for(a in e);return\"undefined\"===typeof a||t.call(e,a)},i=function(e,t){a&&\"__proto__\"===t.name?a(e,t.name,{enumerable:!0,configurable:!0,value:t.newValue,writable:!0}):e[t.name]=t.newValue},o=function(e,r){if(\"__proto__\"===r){if(!t.call(e,r))return;if(n)return n(e,r).value}return e[r]};e.exports=function e(){var t,r,a,n,u,c,d=arguments[0],m=1,g=arguments.length,p=!1;for(\"boolean\"===typeof d&&(p=d,d=arguments[1]||{},m=2),(null==d||\"object\"!==typeof d&&\"function\"!==typeof d)&&(d={});m